ETL CoreStream React

Build fully reactive ETL interfaces in React using composable hooks, compound components, render props, context orchestration, and headless UI patterns.

@etl-corestream/react transforms the CoreStream orchestration engine into a complete React-first developer experience.

It provides:

Reactive ETL hooks
Compound context architecture
Fully customizable UI components
Headless render-prop APIs
Context-driven orchestration
Slot/asChild composition support
Pagination-aware data views
Editable ETL tables
Recovery workflows
Mapping interfaces
Import/export triggers
Metrics & progress subscriptions

The adapter is designed to work seamlessly with the reactive architecture exposed by @etl-corestream/core.

⚠️ Disclaimer — under active development

@etl-corestream/react is currently under heavy development and is not stable yet.

Until version 1.0.0, APIs, component contracts, behaviors, and internal architecture may change without notice.

Expect breaking changes while the ecosystem evolves.

📚 Table of Contents

Features
Philosophy
Installation
Quick Start
Architecture Overview
Compound Component Architecture
Context System
Render Props
asChild / Slot Support
Hooks
Components
DataView System
Editable Tables
Mapping System
Recovery Workflows
Reactive State Integration
Headless UI Philosophy
Advanced Composition
Example Workflow
Why This Architecture?
Design Goals
Official Packages
License

✨ Features

React-first ETL architecture
Headless & composable APIs
Compound component system
Render prop support
Slot/asChild composition
Context-driven orchestration
Reactive ETL state
Pagination-aware data views
Editable datasets
Built-in mapping UI helpers
Recovery flow helpers
Reactive metrics & progress
Framework-style component API
Tailwind-friendly
Fully customizable rendering
Hooks + components interoperability
RxJS + Signals integration
Zero imposed styling
Massive dataset visualization support

🧠 Philosophy

@etl-corestream/react is not a styled UI kit.

It is a headless orchestration layer for React applications built on top of ETL CoreStream.

The adapter focuses on:

Composition over rigid components
Context over prop drilling
Headless APIs over opinionated UI
Reactive state over imperative synchronization
Reusable orchestration primitives
Massive-scale workflows

You can:

Use the included components directly
Build your own UI entirely from hooks
Mix both approaches freely
Replace rendering at any level

🚀 Installation

Install the React adapter:

npm install @etl-corestream/react

⚡ Quick Start

import { Etl } from "@etl-corestream/react";

export const App = () => {
  return (
    <Etl.Root>
      <Etl.Layout.Root layouts={layouts}>
        <Etl.Layout.Selector />
        <Etl.Layout.Trigger>
          Select Layout
        </Etl.Layout.Trigger>
      </Etl.Layout.Root>

      <Etl.Importer.Root>
        <Etl.Importer.Input />
        <Etl.Importer.Trigger>
          Select File
        </Etl.Importer.Trigger>
      </Etl.Importer.Root>

      <Etl.Progress>
        {({ totalProgress }) => (
          <progress value={totalProgress} max={100} />
        )}
      </Etl.Progress>

      <Etl.DataView.Root>
        <Etl.DataView.Table.Root>
          <Etl.DataView.Table.THead />
          <Etl.DataView.Table.TBody />
        </Etl.DataView.Table.Root>
      </Etl.DataView.Root>
    </Etl.Root>
  );
};

🏗️ Architecture Overview

The React adapter wraps the ETL CoreStream orchestrator with layered React contexts and composable hooks.

ETL CoreStream Orchestrator
            ↓
Reactive Hooks
            ↓
Context Providers
            ↓
Compound Components
            ↓
Custom UI Rendering

The system allows:

Shared orchestration state
Nested contextual behavior
Localized state composition
Headless rendering control
Massive UI flexibility

🧩 Compound Component Architecture

The adapter uses a compound component architecture inspired by systems like:

Radix UI
Headless UI
React Aria

Example:

<Etl.DataView.Root>
  <Etl.DataView.Table.Root>
    <Etl.DataView.Table.THead />
    <Etl.DataView.Table.TBody />
  </Etl.DataView.Table.Root>

  <Etl.DataView.Pagination.Root>
    <Etl.DataView.Pagination.PagePreviousButton />
    <Etl.DataView.Pagination.PageNextButton />
  </Etl.DataView.Pagination.Root>
</Etl.DataView.Root>

Contexts automatically coordinate:

Pagination
Current rows
Filtering
Editing
Metrics
Viewer state

🌐 Context System

The adapter exposes multiple contextual layers.

Global ETL Context

<Etl.Root> creates and exposes the orchestrator instance to all descendants.

<Etl.Root>
  <MyETLInterface />
</Etl.Root>

Internally:

<EtlContext.Provider value={orchestrator}>

This provides:

State
Metrics
Logs
Progress
Steps
Recovery state
Viewer state
Reactive signals

Compound Local Contexts

Certain systems create localized contextual state.

Example:

<Etl.DataView.Root>

Provides:

Pagination coordination
Filtering state
Current rows
Editing state
Data navigation helpers

This enables deeply nested composition without prop drilling.

🎨 Render Props

Most components support render props for full rendering control.

Example:

<Etl.Progress>
  {({ totalProgress }) => (
    <progress value={totalProgress} max={100} />
  )}
</Etl.Progress>

Example:

<Etl.DataView.Table.Cell>
  {({ isError }) => (
    <div>
      {isError && <span>Error</span>}
    </div>
  )}
</Etl.DataView.Table.Cell>

Render props expose internal contextual values while preserving orchestration behavior.

Render props — examples

Below are short examples (and references to the Storybook viewer) showing common render-prop patterns used across the library.

See the concrete implementation in the Storybook viewer:

For a full Storybook example, see: src/components/etl/storybook on GitHub

                <Etl.DataView.Edit.Root className="fixed top-0 left-0 w-full h-full bg-white/50 backdrop-blur-sm z-50 flex items-center justify-center">
                    {
                        ({ currentEditRow }) => {
                            if (!currentEditRow)
                                return null;

                            return <>
                                <div className="flex flex-col gap-2 p-4 bg-white rounded-md border border-gray-300">
                                    <span className="text-lg font-semibold">Edit Cell</span>
                                    <div className="flex gap-5 ">
                                        <div className="flex flex-col gap-1">
                                            <span className="text-gray-400 text-xs">Previous Value:</span>
                                            <Etl.DataView.Edit.PreviusInput className="border border-gray-300 w-min text-nowrap bg-gray-100 text-gray-800 p-2 px-4 rounded-md hover:bg-gray-200 transition-colors duration-300 cursor-pointer" >
                                                {
                                                    ({ previusValue }) =>
                                                        previusValue
                                                }
                                            </Etl.DataView.Edit.PreviusInput>
                                        </div>

And a cell-level render-prop used for per-cell rendering/validation UI:

                                                    Object.keys(row.value).map((key) =>
                                                        <Etl.DataView.Table.Cell key={key} row={row} column={key} className="border-r border-gray-300 data-[is-error]:bg-red-200">
                                                            {
                                                                ({ isError }) =>
                                                                    <div className="flex items-center">
                                                                        <div className="flex flex-col items-center gap-0 w-full px-1">
                                                                            {isError ?
                                                                                <span className="bottom-0 order-2 text-xs font-semibold text-red-500">
                                                                                    {ErrorDicc[isError] || isError}
                                                                                </span> : null

Minimal usage examples:

// Progress (simple)
<Etl.Progress>
  {({ totalProgress }) => <progress value={totalProgress} max={100} />}
</Etl.Progress>

// Edit overlay (previous / new value)
<Etl.DataView.Edit.Root>
  {({ currentEditRow }) =>
    currentEditRow ? (
      <div>
        <Etl.DataView.Edit.PreviusInput>
          {({ previusValue }) => previusValue}
        </Etl.DataView.Edit.PreviusInput>
        <Etl.DataView.Edit.NewInput />
      </div>
    ) : null
  }
</Etl.DataView.Edit.Root>

// Table body + cell render-props
<Etl.DataView.Table.TBody>
  {({ currentRows, setCurrentEditRow }) =>
    currentRows.value?.map(row => (
      <Etl.DataView.Table.Row key={row.__rowId} rowObject={row}>
        {({ row }) => (
          <>
            <Etl.DataView.Table.Cell row={row} column="index">
              {() => <span>{row.__rowId}</span>}
            </Etl.DataView.Table.Cell>
            <Etl.DataView.Table.Cell row={row} column="name">
              {({ isError }) => <span className={isError ? 'text-red-500' : ''}>{row.value.name}</span>}
            </Etl.DataView.Table.Cell>
          </>
        )}
      </Etl.DataView.Table.Row>
    ))
  }
</Etl.DataView.Table.TBody>

These patterns let you access contextual state (current rows, edit state, validation flags, header helpers, etc.) while keeping the UI fully custom and headless.

🔌 asChild / Slot Support

All major interactive components support asChild.

This enables integration with:

Radix UI Slot
Custom buttons
Design systems
Tailwind components
External UI libraries

Example:

<Etl.ResetButton asChild>
  <button className="custom-button">
    Reset
  </button>
</Etl.ResetButton>

The ETL behavior is preserved while rendering your own component.

🪝 Hooks

The adapter exposes hooks for building completely custom interfaces.

Core Hooks

`useEtlOrchestrator()`

Creates and exposes the orchestrator instance.

const orchestrator = useEtlOrchestrator();

`useEtlContext()`

Access the global ETL context.

const { metrics, progress } = useEtlContext();

`useDataView()`

Provides:

Current rows
Pagination
Filtering
Editing helpers
Metrics
View navigation

`useImporter()`

Importer helpers and state.

`useExporter()`

Export helpers and exporter triggers.

`useMapper()`

Header mapping orchestration.

`useRecoveryView()`

Recovery workflow helpers.

`useLayoutView()`

Layout selection orchestration.

`useAbortButton()`

Abort current workflow actions.

`useResetButton()`

Reset ETL sessions.

Reactive Hooks

useEtlState()
useMetrics()
useProgress()
useLogs()
useStepFlags()

🧱 Components

Main Namespace

<Etl.Root />
<Etl.Importer />
<Etl.StateView />
<Etl.Layout />
<Etl.LogView />
<Etl.DataView />
<Etl.ResetButton />
<Etl.Exporter />
<Etl.Mapper />
<Etl.Progress />
<Etl.Recover />
<Etl.AbortButton />

📊 DataView System

The DataView system centralizes:

Table rendering
Pagination
Editing
Filtering
Row removal
Reactive dataset visualization

Table Components

<Etl.DataView.Table.Root />
<Etl.DataView.Table.THead />
<Etl.DataView.Table.TBody />
<Etl.DataView.Table.Row />
<Etl.DataView.Table.Cell />
<Etl.DataView.Table.HeaderCell />

Pagination Components

<Etl.DataView.Pagination.Root />
<Etl.DataView.Pagination.PageNextButton />
<Etl.DataView.Pagination.PagePreviousButton />
<Etl.DataView.Pagination.PageFirstButton />
<Etl.DataView.Pagination.PageLastButton />

✏️ Editable Tables

The adapter includes contextual editing workflows.

<Etl.DataView.Edit.Root>
  <Etl.DataView.Edit.PreviusInput />
  <Etl.DataView.Edit.NewInput />

  <Etl.DataView.Edit.TriggerCancel />
  <Etl.DataView.Edit.TriggerSubmit />
</Etl.DataView.Edit.Root>

Rows can be edited while ETL processing continues in the background.

🧭 Mapping System

The mapping system helps users map incoming headers dynamically.

Example:

<Etl.Mapper.Root>
  <Etl.Mapper.HeadersView />

  <Etl.Mapper.TriggerConfirm>
    Confirm
  </Etl.Mapper.TriggerConfirm>

  <Etl.Mapper.TriggerCancel>
    Cancel
  </Etl.Mapper.TriggerCancel>
</Etl.Mapper.Root>

Useful for:

CSV imports
Alias mapping
Flexible schemas
User-driven remapping

💾 Recovery Workflows

The adapter exposes recovery flows directly to React interfaces.

Example:

const { recoveryPoint } = useRecoveryView();

Recovery UI can be fully customized while maintaining orchestration behavior.

⚛️ Reactive State Integration

The adapter integrates with the reactive CoreStream architecture.

Supported internally:

RxJS
Preact Signals

React components automatically react to:

Progress updates
Metrics changes
Validation updates
Dataset changes
Recovery state
Viewer state

🎯 Headless UI Philosophy

The adapter intentionally avoids imposing:

Styling systems
CSS frameworks
Component themes
Layout opinions

You fully control:

Rendering
Styling
Accessibility
Animations
Design systems

Tailwind, CSS Modules, Styled Components, Emotion, or custom systems all work naturally.

🧪 Example Workflow

A complete workflow may include:

Select Layout
    ↓
Select File
    ↓
Map Headers
    ↓
Process Stream
    ↓
Validate Rows
    ↓
Edit Invalid Data
    ↓
Filter Results
    ↓
Export Dataset

All while remaining:

Reactive
Recoverable
Non-blocking
Editable

🚀 Why This Architecture?

Massive ETL interfaces are difficult to build traditionally.

Most solutions suffer from:

Prop drilling
Tight coupling
Non-reactive orchestration
Inflexible rendering
UI blocking
Poor scalability

@etl-corestream/react solves this with:

Layered contexts
Reactive orchestration
Compound composition
Render-prop extensibility
Hook-driven APIs

🧭 Design Goals

The adapter was designed around a few core principles:

Composition over monolithic widgets
Headless APIs over rigid UI
Reactive orchestration over imperative sync
Context coordination over prop drilling
Massive dataset support
Incremental rendering
Flexible integration

📦 Official Packages

Core Engine

@etl-corestream/core

GitHub:

ETLCoreStream-Core

React Adapter

@etl-corestream/react

GitHub:

ETLCoreStream-React

🤝 Open Source

The project is fully open source.

Contributions are welcome:

Issues
Discussions
Documentation
Adapters
Custom modules
Examples
Performance improvements

📄 License

MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.storybook		.storybook
src		src
.gitignore		.gitignore
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.app.json		tsconfig.app.json
tsconfig.emit-types.json		tsconfig.emit-types.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts
vitest.shims.d.ts		vitest.shims.d.ts

Folders and files

Latest commit

History

Repository files navigation

ETL CoreStream React

⚠️ Disclaimer — under active development

📚 Table of Contents

✨ Features

🧠 Philosophy

🚀 Installation

⚡ Quick Start

🏗️ Architecture Overview

🧩 Compound Component Architecture

🌐 Context System

Global ETL Context

Compound Local Contexts

🎨 Render Props

Render props — examples

🔌 asChild / Slot Support

🪝 Hooks

Core Hooks

useEtlOrchestrator()

useEtlContext()

useDataView()

useImporter()

useExporter()

useMapper()

useRecoveryView()

useLayoutView()

useAbortButton()

useResetButton()

Reactive Hooks

🧱 Components

Main Namespace

📊 DataView System

Table Components

Pagination Components

✏️ Editable Tables

🧭 Mapping System

💾 Recovery Workflows

⚛️ Reactive State Integration

🎯 Headless UI Philosophy

🧪 Example Workflow

🚀 Why This Architecture?

🧭 Design Goals

📦 Official Packages

Core Engine

React Adapter

🤝 Open Source

📄 License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages

`useEtlOrchestrator()`

`useEtlContext()`

`useDataView()`

`useImporter()`

`useExporter()`

`useMapper()`

`useRecoveryView()`

`useLayoutView()`

`useAbortButton()`

`useResetButton()`