E3 UI Components

React Query hooks and preview components for the e3 API

E3 UI Components provides React Query hooks for all e3-api-client functions and reusable preview components for tasks, inputs, and logs.

Features

• React Query Hooks - useQuery and useMutation wrappers for all e3 API client functions
• Task Preview - Component for viewing task execution output and logs
• Input Preview - Component for viewing dataset input values
• Virtualized Log Viewer - Performant log display with search and auto-scroll
• Type-Safe - Full TypeScript support with proper return type inference

Installation

npm install @elaraai/e3-ui-components @elaraai/e3-api-client @tanstack/react-query

Hooks

React Query hooks are provided for every e3 API domain:

Quick Start

import { useWorkspaceList, useTaskList } from '@elaraai/e3-ui-components';

function WorkspaceView({ apiUrl, repo }: { apiUrl: string; repo: string }) {
    const { data: workspaces, isLoading } = useWorkspaceList(apiUrl, repo);

    if (isLoading) return <div>Loading...</div>;

    return (
        <ul>
            {workspaces?.map(ws => <li key={ws.name}>{ws.name}</li>)}
        </ul>
    );
}

Query Overrides

All query hooks accept an optional QueryOverrides parameter for controlling query behavior:

const { data } = useTaskList(apiUrl, repo, workspace, requestOptions, {
    refetchInterval: 5000,
    staleTime: 10000,
    enabled: isReady,
});

Polling

A screen left open costs the server as little as it can:

• A poll makes one request attempt. useWorkspaceStatus, useDataflowExecution, useTaskLogs, useDatasetStatus and the dataset cache's status poll send their requests with e3-api-client's pollRequestOptions, so a transient failure is left to the next poll rather than retried three times in between.
• The dataset cache asks conditionally. <ReactiveDatasetProvider>'s cache polls a workspace's status at pollIntervalMs (1000 ms) while what it shows changes, backing off to pollBackoffMs (5000 ms) once nothing has; each poll sends the last answer's ETag back (workspaceStatusSince), and a server that still holds that status answers nothing. Every half minute it asks in full, so a runner that died shows as stale, and after a fetch that failed, a new watch or a refresh, so nothing a conditional answer would leave as it is stays so. While the page is hidden — its tab in the background — it polls nothing, and polls every workspace at once when the page is shown again. A UITaskPreview shortens the interval with pollInterval and the backoff with pollBackoff.
• A dataset's status is polled every 30 s (DATASET_STATUS_POLL_MS): useDatasetStatus's pollInterval, and the previews' pollInterval (DatasetPreview, InputPreview) and statusPollInterval (TaskPreview, DataTaskPreview; UITaskPreview's outputPollInterval) shorten it.
• A task's log is polled while it grows: every second while it changes, backing off to 5 s while it does not, and every half minute once the task's execution has ended and the log is read, for another execution of the task, which starts the polls again. A log the view left — the other stream, another task — is kept as far as it was read, so a view that comes back to it reads on from there. TaskPreview's logPollInterval and logPollBackoff set the intervals.
• A task's details are read once. useTaskDetails and useTaskGet share one query key, so a preview and the host that opened it read the task once; a host that holds the details hands them over as TaskPreview's details, and the preview makes no request.

Recovering a failed read

A view on a screen no one touches, such as a kiosk's, has no one to reload it. useQueryRecovery tries a failed query again by itself while the view is mounted, as every stage of UITaskPreview does. It waits a random point in the second half of a backoff from 1 s to 30 s (recoveryDelay), and shows the latest failure through each try, never loading again.

import { StatusDisplay, useQueryRecovery, useTaskGet } from '@elaraai/e3-ui-components';

const details = useTaskGet(apiUrl, repo, workspace, task);
const failure = useQueryRecovery(details); // null once it reads
if (failure !== null) return <StatusDisplay variant="error" title="Error" message={failure.message} />;

Rendering a UI outside UITaskPreview

A host that renders UI functions itself decodes each with the platforms UITaskPreview lists. Every one is exported by name: east-ui-components' own, Decision.bind's (DecisionBindPlatform), and the bindings scoped to the UI's manifest. Preload the manifest's paths with usePreloadReactiveDatasets before the UI's first read.

import { decodeBeast2For } from '@elaraai/east';
import { UIComponentType } from '@elaraai/east-ui';
import {
    StateImpl, SliceImpl, SliceApplyImpl, OverlayImpl, ClipboardImpl, DownloadImpl, ShareImpl,
} from '@elaraai/east-ui-components';
import { RecordSliceImpl } from '@elaraai/east-ui-components/platform';
import {
    DecisionBindPlatform, createScopedBindPlatform, createScopedPagedPlatform,
    createScopedFuncPlatform, createScopedRecordPlatform,
} from '@elaraai/e3-ui-components';

const platforms = [
    ...StateImpl, ...SliceImpl, ...RecordSliceImpl, ...SliceApplyImpl, ...OverlayImpl,
    ...ClipboardImpl, ...DownloadImpl, ...ShareImpl, ...DecisionBindPlatform,
    ...createScopedBindPlatform(manifest),
    ...createScopedPagedPlatform(manifest.pages),
    ...createScopedFuncPlatform(manifest.functions),
    ...createScopedRecordPlatform(manifest.records),
];
const ui = decodeBeast2For(UIComponentType, { platform: platforms })(bytes);

Components

TaskPreview

Previews a task by its role: a ui() task renders its UI; a data task shows its output (Output) and its logs (Logs) under a band holding the Output/Logs switch. Above the output are its key search, size and Download, and above its tree Collapse all and Expand all; above the log, its stdout/stderr tabs, its search and Copy.

import { TaskPreview } from '@elaraai/e3-ui-components';

<TaskPreview apiUrl={url} repo="default" workspace={ws} task={taskName} />

A host whose frame holds its controls in its header draws them itself and hides the bands:

import {
    TaskPreview, downloadDataset, formatSize, usePreviewControls, useDatasetStatus, useTaskDetails, type LogMatches,
} from '@elaraai/e3-ui-components';

const [view, setView] = useState<'output' | 'logs'>('output');
const [search, setSearch] = useState('');
const [stream, setStream] = useState<'stdout' | 'stderr'>('stdout');
const [logSearch, setLogSearch] = useState('');
const [matches, setMatches] = useState<LogMatches>({ current: 0, count: 0 });
const controls = usePreviewControls();
const details = useTaskDetails(url, 'default', ws, taskName);
const output = details.data?.output.path.map((step) => step.value).join('.') ?? null;
const status = useDatasetStatus(url, 'default', ws, output);

// In the header, at the header's size: the tab; on Output, the search, the size,
// Download, and Collapse all and Expand all; on Logs, the stream, the search,
// `${matches.current + 1}/${matches.count}`, the chevrons and Copy.
// In the body:
<TaskPreview apiUrl={url} repo="default" workspace={ws} task={taskName} bare
    toolbar={false} view={view} onViewChange={setView} search={search}
    logStream={stream} onLogStreamChange={setStream} logSearch={logSearch}
    onLogMatchesChange={setMatches} controls={controls} />
// Download: downloadDataset(url, 'default', ws, output); the size: formatSize(status.data.sizeBytes)
// Collapse all: controls.collapseAll(); Expand all: controls.expandAll()
// The chevrons: controls.previousMatch(), controls.nextMatch(); Copy: controls.copyLog()

search is read as the preview's own search box reads its text: a key's prefix, a struct key's leading fields (press, 2), a from..to range, or a whole key in .east syntax.

usePreviewControls() makes the handle. collapseAll() and expandAll() act on the output's tree; nextMatch() and previousMatch() step through the log's matches, from the last round to the first and back; and copyLog() copies the log shown, resolving true once it is on the clipboard and false when the clipboard refuses it. Each does nothing while its view is not shown — the Output tab shows no log, and a value too large to show has no tree. A handle serves one preview at a time, and holds no query, so a header outside <E3Provider> can make it.

DatasetPreview

Shows a dataset's value: a tree, inline while it is small, a page at a time for a read-only collection, and a Download for a value too large to show. editable writes a mutable input's edits back. toolbar, search, onSearchChange and controls are TaskPreview's, for the value alone.

import { DatasetPreview } from '@elaraai/e3-ui-components';

<DatasetPreview apiUrl={url} repo="default" workspace={ws} path="inputs.threshold" editable />

InputPreview

Shows an input's value, editable, under a band naming the input.

import { InputPreview } from '@elaraai/e3-ui-components';

<InputPreview apiUrl={url} repo="default" workspace={ws} path=".inputs.threshold" />

bare draws no band naming the input, for a host whose frame names it, and toolbar, search, onSearchChange, controls and pollInterval reach the value's DatasetPreview.

VirtualizedLogViewer

A log, its lines virtualized, under a band holding the stdout/stderr tabs, a search that marks its matches and steps through them, and Copy. It follows the log's end while it is there, and says when new lines arrive while it is not.

import { useTabs } from '@chakra-ui/react';
import { VirtualizedLogViewer } from '@elaraai/e3-ui-components';

const tabs = useTabs({ defaultValue: 'stdout' });

<VirtualizedLogViewer content={tabs.value === 'stderr' ? stderr : stdout} tabs={tabs} />

StatusDisplay

Status feedback component with error, warning, info, and loading variants.

import { StatusDisplay } from '@elaraai/e3-ui-components';

<StatusDisplay variant="error" title="Failed" message={error.message} />

Development

npm run build     # Build library
npm run lint      # Check code quality

Claude Code plugin

The East ecosystem also ships a Claude Code plugin — East language skills, example search, and preemptive diagnostics for East code — installed separately from the elaraai marketplace:

# Inside Claude Code
/plugin marketplace add elaraai/east-workspace
/plugin install east@elaraai

# From a terminal
claude plugin marketplace add elaraai/east-workspace
claude plugin install east@elaraai

License

Dual-licensed:

• Open Source: AGPL-3.0 - Free for open source use
• Commercial: Available for proprietary use - contact [email protected]

Ecosystem

• East: Statically typed, expression-based language with serializable IR. Run portable logic across TypeScript, Python, C, and other runtimes.

  • @elaraai/east: Core language SDK with type system, expressions, and reference JS compiler

• East Node: Node.js platform functions for I/O, databases, and system operations.

  • @elaraai/east-node-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • @elaraai/east-node-io: SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
  • @elaraai/east-node-cli: CLI for running East IR programs in Node.js

• East C: C11 native runtime for executing East IR. Tarballed for linux-x64 and linux-arm64, attached to each GitHub Release.

  • east-c: Core runtime — type system, IR interpreter, 200+ builtins, serialization (Beast2, JSON, CSV, East text)
  • east-c-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • east-c-cli: CLI for running East IR programs natively

• East Python: Python runtime, standard platform, I/O, and data-science platform functions. Published to PyPI.

  • east-py: Core Python runtime — type system, IR compiler, 212+ builtins, Cython-accelerated hot paths
  • east-py-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • east-py-io: SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
  • east-py-cli: CLI for running East IR programs in Python
  • east-py-datascience (PyPI) + @elaraai/east-py-datascience (npm): Optimization (MADS, Optuna, ALNS, GoogleOR), ML (XGBoost, LightGBM, NGBoost, PyTorch, Lightning, GP), Bayesian inference (PyMC), explainability (SHAP), conformal prediction (MAPIE)

• East UI: Typed UI component definitions and React renderer, plus VS Code preview.

  • @elaraai/east-ui: 50+ typed UI components for layouts, forms, charts, tables, dialogs
  • @elaraai/east-ui-components: React renderer with Chakra UI v3 styling
  • @elaraai/e3-ui: e3 + UI bridge — Data bindings, e3.ui() task, manifest
  • @elaraai/e3-ui-components: React Query hooks and preview components for the e3 API
  • @elaraai/e3-ui-cli: Browse an e3 repository in the terminal (e3-ui [repo]), and render east-ui / e3-ui components to PNG (e3-ui shot)

• e3 — East Execution Engine: Durable execution engine for running East pipelines at scale. Git-like content-addressable storage, automatic memoization, reactive dataflow, real-time monitoring.

  • @elaraai/e3: SDK for authoring e3 packages with typed tasks and pipelines
  • @elaraai/e3-core: Object store, dataflow orchestrator, execution state
  • @elaraai/e3-types: Shared type definitions for e3 packages
  • @elaraai/e3-cli: e3 repo, e3 package, e3 workspace, e3 dataflow run, e3 watch, e3 task logs commands
  • @elaraai/e3-api-client: HTTP client for remote e3 repositories
  • @elaraai/e3-api-server: REST API server for e3 repositories
  • @elaraai/e3-api-tests: Shared API compliance test suites

Links

• Website: https://elaraai.com/
• e3 API Client: https://www.npmjs.com/package/@elaraai/e3-api-client
• East UI: https://www.npmjs.com/package/@elaraai/east-ui
• Issues: https://github.com/elaraai/east-workspace/issues
• Email: [email protected]

About Elara

East is developed by Elara AI Pty Ltd, an AI-powered platform that creates economic digital twins of businesses that optimize performance. Elara combines business objectives, decisions and data to help organizations make data-driven decisions across operations, purchasing, sales and customer engagement, and project and investment planning. East powers the computational layer of Elara solutions, enabling the expression of complex business logic and data in a simple, type-safe and portable language.

Developed by Elara AI Pty Ltd.

Developed by Elara AI Pty Ltd - Powering the computational layer of AI-driven business optimization.