@elaraai/e3-ui 1.0.0

package/dist/src/data.js

@@ -0,0 +1,195 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Reactive dataset binding for e3 UI tasks.
+ *
+ * @packageDocumentation
+ */
+import { East, NullType, BooleanType, FunctionType, StructType, VariantType, OptionType, none, some, variant, } from '@elaraai/east';
+import { TreePathType, DatasetStatusType } from '@elaraai/e3-types';
+// ============================================================================
+// Mode + binding descriptor types — shared with the Diff component.
+// ============================================================================
+/**
+ * The two operating modes for {@link Data.bind}.
+ *
+ * @property staged - Edits are buffered locally (in-memory + IndexedDB) and
+ *   only flushed on `commit()`. Use for editor flows where the user reviews
+ *   pending changes before publishing.
+ * @property direct - Every `write()` immediately mutates the destination
+ *   (the source dataset, or the patch dataset when `patch` is set). Use for
+ *   live shared cursors and other no-staging surfaces.
+ */
+export const DataBindModeType = VariantType({
+    staged: NullType,
+    direct: NullType,
+});
+/**
+ * Descriptor for a single binding the {@link Diff.Root} component displays.
+ *
+ * Every {@link Data.bind} call exposes this descriptor as its `binding`
+ * field, so callers can wire a Diff card via `Diff.Root({ bindings:
+ * [view.binding, ...] })` without re-spelling the source / patch paths.
+ *
+ * @property source - The dataset path of the source value the binding
+ *   reads from.
+ * @property patch - When the binding writes through a separate patch
+ *   dataset, this is its path. `none` means the binding writes directly to
+ *   the source on commit (or to the staging buffer in staged mode).
+ * @property mode - The binding's operating mode — see {@link DataBindModeType}.
+ */
+export const DiffBindingType = StructType({
+    source: TreePathType,
+    patch: OptionType(TreePathType),
+    mode: DataBindModeType,
+});
+// ============================================================================
+// Bind handle — return type of `Data.bind`.
+// ============================================================================
+/**
+ * The struct returned by every {@link Data.bind} call. Every field is
+ * present regardless of `mode` / `patch` — the per-mode semantics are
+ * captured in the property docs of {@link Data.bind}.
+ *
+ * @property read - Reactive accessor for the binding's view of the source.
+ * @property write - Update the binding (buffer in staged mode, dataset in
+ *   direct mode). Always returns null.
+ * @property writeAndStart - Like `write`, but kicks the workspace dataflow
+ *   so downstream tasks recompute. Only meaningful when `mode = "direct"`
+ *   and `patch` is absent — in other modes it falls back to `write`.
+ * @property source - Read the raw source value with no overlay applied.
+ * @property pending - True when there is an in-flight change waiting to be
+ *   committed. Always false in `mode = "direct"` without a `patch` dataset.
+ * @property commit - Resolve the in-flight change. The destination depends
+ *   on `mode` / `patch` — see {@link Data.bind} for the full matrix.
+ * @property discard - Drop the in-flight change.
+ * @property has - True iff the source dataset has a value.
+ * @property status - Per-dataset freshness signal — see
+ *   {@link DatasetStatusType}.
+ * @property binding - Descriptor for this binding — pass directly to
+ *   {@link Diff.Root}'s `bindings` array.
+ */
+export const DataBindHandleType = (t) => StructType({
+    read: FunctionType([], t),
+    write: FunctionType([t], NullType),
+    writeAndStart: FunctionType([t], NullType),
+    source: FunctionType([], t),
+    pending: FunctionType([], BooleanType),
+    commit: FunctionType([], NullType),
+    discard: FunctionType([], NullType),
+    has: FunctionType([], BooleanType),
+    status: FunctionType([], DatasetStatusType),
+    binding: DiffBindingType,
+});
+// ============================================================================
+// Platform function — single unified definition.
+// ============================================================================
+/**
+ * The underlying `Data.bind` platform-function definition. End-users
+ * should call {@link Data.bind} (the typed factory in this module);
+ * runtime implementations register against this raw definition via
+ * `bindPlatformFn.implement(...)`.
+ */
+export const bindPlatformFn = East.genericPlatform("data_bind", ["T"], [TreePathType, OptionType(TreePathType), DataBindModeType], StructType({
+    read: FunctionType([], "T"),
+    write: FunctionType(["T"], NullType),
+    writeAndStart: FunctionType(["T"], NullType),
+    source: FunctionType([], "T"),
+    pending: FunctionType([], BooleanType),
+    commit: FunctionType([], NullType),
+    discard: FunctionType([], NullType),
+    has: FunctionType([], BooleanType),
+    status: FunctionType([], DatasetStatusType),
+    binding: DiffBindingType,
+}), { optional: true });
+/**
+ * The Data namespace — reactive dataset binding for e3 UI tasks.
+ *
+ * @remarks
+ * `Data.bind` exposes a single binding handle that adapts to four
+ * combinations of `mode` (staged | direct) and `patch` (absent | present).
+ * The full per-mode semantics matrix is documented on {@link Data.bind}.
+ *
+ * Use inside `Reactive.Root` for reactive re-rendering when the underlying
+ * datasets change.
+ */
+export const Data = {
+    /**
+     * Bind a dataset path to a reactive view of its current value, with
+     * optional local staging or a separate server-backed patch dataset.
+     *
+     * @typeParam T - The East type of the source dataset value.
+     * @param types - Single-element type-args tuple `[T]`.
+     * @param source - The source dataset path.
+     * @param options - {@link DataBindOptions}. When omitted, defaults to
+     *   `{ mode: "staged" }` (no separate patch dataset, edits buffered
+     *   locally until commit).
+     * @returns A handle struct described by {@link DataBindHandleType} —
+     *   `read` / `write` / `writeAndStart` / `source` / `pending` /
+     *   `commit` / `discard` / `has` / `status` / `binding`.
+     *
+     * @remarks
+     * Per-mode semantics matrix (rows are `mode × patch`, columns are
+     * methods):
+     *
+     * | mode    | patch   | `read()`                            | `write(v)`                              | `commit()`                                          | `discard()`                  | `pending()`         |
+     * |---------|---------|-------------------------------------|-----------------------------------------|-----------------------------------------------------|------------------------------|---------------------|
+     * | direct  | absent  | source                              | dataset write                           | no-op                                               | no-op                        | always false        |
+     * | direct  | present | apply(source, patch dataset)        | write diff(source, v) → patch dataset   | apply patch → source; clear patch dataset           | clear patch dataset          | patch non-trivial   |
+     * | staged  | absent  | buffered ?? source                  | update buffer (pin snapshot first time) | apply buffer → source; drop buffer                  | drop buffer                  | buffer non-empty    |
+     * | staged  | present | buffered ?? apply(source, patch)    | update buffer                           | write diff(source, buffer) → patch dataset; drop buffer | drop buffer (patch intact) | buffer non-empty  |
+     *
+     * `writeAndStart(v)` kicks the workspace dataflow after the write — only
+     * meaningful for `mode = "direct"` without a `patch` dataset; in other
+     * modes it falls back to `write(v)` (the workspace dataflow is triggered
+     * on `commit` instead).
+     *
+     * The `binding` field surfaces this binding's descriptor as a
+     * {@link DiffBindingType} value — pass it directly to
+     * {@link Diff.Root}'s `bindings` array to surface the in-flight change
+     * in a Diff card.
+     *
+     * Use inside `Reactive.Root` so `read` / `pending` / `status` re-fire
+     * on every dataset or staging-buffer change.
+     *
+     * @example
+     * ```ts
+     * import { East, FloatType, NullType } from "@elaraai/east";
+     * import { Reactive, Slider, UIComponentType } from "@elaraai/east-ui";
+     * import { Data, Diff } from "@elaraai/e3-ui";
+     * import * as e3 from "@elaraai/e3";
+     *
+     * const thresholdInput = e3.input("threshold", FloatType, 38.0);
+     *
+     * // Mirrors `dataBindStaged` in test/data.examples.ts.
+     * const dataBindStaged = East.function([], UIComponentType, _$ => {
+     *     return Reactive.Root(East.function([], UIComponentType, $ => {
+     *         const view = $.let(Data.bind([FloatType], thresholdInput.path));
+     *         const value = $.let(view.read(), FloatType);
+     *         return Slider.Root(value, {
+     *             min: 30.0, max: 60.0, step: 1.0,
+     *             onChangeEnd: East.function([FloatType], NullType, ($, v) => {
+     *                  $(view.write(v));
+     *             }),
+     *         });
+     *     }));
+     * });
+     * ```
+     */
+    bind(types, source, options) {
+        // Source / patch paths must be statically known so manifest
+        // derivation (`deriveManifest`) can preload them. We wrap each
+        // explicitly via `East.value(...)` to force a single literal
+        // `Value` IR node — the only IR shape `derive.ts` needs to
+        // handle.
+        const sourceValue = East.value(source, TreePathType);
+        const modeValue = East.value(variant(options?.mode ?? "staged", null), DataBindModeType);
+        const patchValue = options?.patch === undefined
+            ? East.value(none, OptionType(TreePathType))
+            : East.value(some(options.patch), OptionType(TreePathType));
+        return bindPlatformFn(types, sourceValue, patchValue, modeValue);
+    },
+};
+//# sourceMappingURL=data.js.map

package/dist/src/data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.js","sourceRoot":"","sources":["../../src/data.ts"],"names":[],"mappings":"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"}

package/dist/src/derive.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Derive a `DataManifest` by walking an East function's IR.
+ *
+ * Finds every `Data.bind(...)` platform call (the walker recurses into
+ * nested `FunctionIR` bodies) and reads its source + (optional) patch
+ * path arguments.
+ *
+ * Both arguments are required to be statically known JS-side
+ * `TreePath`s — the public `Data.bind` factory enforces this through
+ * its TS signature. Each path arrives as East-compiled structured IR:
+ *
+ *   - source: `NewArray` of `Variant("field", Value(string))` (the
+ *     TreePath array literal)
+ *   - patch:  `Variant("some"|"none", inner)` where `inner` for
+ *     `some` is the same `NewArray` shape as a source path
+ *
+ * Anything else is a programmer error and throws.
+ *
+ * @packageDocumentation
+ */
+import type { IR } from '@elaraai/east';
+import type { DataManifest } from './manifest.js';
+/** Walk `fn`'s IR and derive its bound-path manifest. */
+export declare function deriveManifest(fn: {
+    toIR(): {
+        ir: IR;
+    };
+}): DataManifest;
+//# sourceMappingURL=derive.d.ts.map

package/dist/src/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/derive.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,EAAE,EAA8C,MAAM,eAAe,CAAC;AAGpF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAKlD,yDAAyD;AACzD,wBAAgB,cAAc,CAC1B,EAAE,EAAE;IAAE,IAAI,IAAI;QAAE,EAAE,EAAE,EAAE,CAAA;KAAE,CAAA;CAAE,GAC3B,YAAY,CA4Bd"}

package/dist/src/derive.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { variant, walkIR, literalValueOf } from '@elaraai/east';
+/** Platform-fn name we extract paths from. */
+const DATA_BIND = "data_bind";
+/** Walk `fn`'s IR and derive its bound-path manifest. */
+export function deriveManifest(fn) {
+    const paths = [];
+    walkIR(fn.toIR().ir, (node) => {
+        if (node.type !== 'Platform')
+            return;
+        const platform = node;
+        if (platform.value.name !== DATA_BIND)
+            return;
+        // arg[0] — source: always a NewArray of Variant("field", Value(string)).
+        paths.push(readTreePath(platform.value.arguments[0]));
+        // arg[1] — patch: Option<TreePath>, encoded as a Variant IR with
+        // case "some" (carrying a NewArray inner) or "none".
+        const patchArg = platform.value.arguments[1];
+        if (patchArg.type !== 'Variant') {
+            throw new Error(`Data.bind: patch must be a literal Option<TreePath>; got dynamic IR (${patchArg.type}).`);
+        }
+        const patchVariant = patchArg.value;
+        if (patchVariant.case === 'some') {
+            paths.push(readTreePath(patchVariant.value));
+        }
+        else if (patchVariant.case !== 'none') {
+            throw new Error(`Data.bind: patch variant tag must be "some" or "none"; got "${patchVariant.case}".`);
+        }
+    });
+    return { paths: dedupePaths(paths) };
+}
+/**
+ * Read a literal `TreePath` from a `NewArray` IR node. Each element is
+ * a `Variant("field", Value(string))` produced by East.value-wrapping a
+ * `TreePath` JS literal. Used for both the source path arg and the
+ * inner of a `some(path)` patch variant.
+ */
+function readTreePath(ir) {
+    if (ir.type !== 'NewArray') {
+        throw new Error(`Data.bind: path must be a literal TreePath; got dynamic IR (${ir.type}). ` +
+            `Pass a JS TreePath (e.g. someInput.path), not a computed expression.`);
+    }
+    return ir.value.values.map((segIR) => {
+        const v = segIR;
+        const fieldName = literalValueOf(v.value.value);
+        return variant('field', fieldName);
+    });
+}
+function dedupePaths(paths) {
+    const seen = new Set();
+    const result = [];
+    for (const p of paths) {
+        const k = p.map(s => `${s.type}:${s.value}`).join('/');
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        result.push(p);
+    }
+    return result;
+}
+//# sourceMappingURL=derive.js.map

package/dist/src/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../src/derive.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwBH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIhE,8CAA8C;AAC9C,MAAM,SAAS,GAAG,WAAW,CAAC;AAE9B,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAC1B,EAA0B;IAE1B,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO;QACrC,MAAM,QAAQ,GAAG,IAAkB,CAAC;QACpC,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO;QAE9C,yEAAyE;QACzE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAO,CAAC,CAAC,CAAC;QAE5D,iEAAiE;QACjE,qDAAqD;QACrD,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAO,CAAC;QACnD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACX,wEAAwE,QAAQ,CAAC,IAAI,IAAI,CAC5F,CAAC;QACN,CAAC;QACD,MAAM,YAAY,GAAI,QAAsB,CAAC,KAAK,CAAC;QACnD,IAAI,YAAY,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,KAAW,CAAC,CAAC,CAAC;QACvD,CAAC;aAAM,IAAI,YAAY,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACX,+DAA+D,YAAY,CAAC,IAAI,IAAI,CACvF,CAAC;QACN,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,EAAM;IACxB,IAAI,EAAE,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACX,+DAA+D,EAAE,CAAC,IAAI,KAAK;YAC3E,sEAAsE,CACzE,CAAC;IACN,CAAC;IACD,OAAQ,EAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAS,EAAE,EAAE;QACrD,MAAM,CAAC,GAAG,KAAkB,CAAC;QAC7B,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,KAAgB,CAAW,CAAC;QACrE,OAAO,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACP,CAAC;AAED,SAAS,WAAW,CAAC,KAAiB;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACpB,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC1B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACZ,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/src/diff.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Diff component — transactional review of pending changes for any
+ * combination of {@link Data.bind} bindings.
+ *
+ * @remarks
+ * The Diff card surfaces the in-flight change for each binding the caller
+ * lists in `bindings`. Per-leaf Discard, per-group Discard-all, and a
+ * footer Apply button drive the binding's commit flow. Conflicts surface
+ * inline as orange chooser rows (staged-mode 3-way drift) and as orange
+ * "stale" warning badges (drift between a patch dataset's expectations
+ * and the current source).
+ *
+ * Declared via the `EastUI.component` extension API — the React renderer
+ * lives in `@elaraai/e3-ui-components` and is wired via
+ * `implementUIComponent(DiffComponent, EastChakraDiff)` at module load
+ * time.
+ *
+ * @packageDocumentation
+ */
+import { StringType, BooleanType, NullType, IntegerType, StructType, OptionType, ArrayType, FunctionType, type ExprType, type SubtypeExprOrValue } from "@elaraai/east";
+import { DensityType, type DensityLiteral, type UIComponentType } from "@elaraai/east-ui";
+import { DiffBindingType } from "./data.js";
+/**
+ * Visual style escape hatches for the Diff component. Every visible surface
+ * is tokenable; defaults come from the host's Chakra theme (Elara AI brand).
+ *
+ * @property addedBackground - Soft-tint background for added / inserted leaves.
+ * @property addedColor - Foreground for added leaves.
+ * @property addedBorderColor - Border for added chips.
+ * @property removedBackground - Soft-tint background for removed / deleted leaves.
+ * @property removedColor - Foreground for removed leaves.
+ * @property removedBorderColor - Border for removed chips.
+ * @property changedBackground - Soft-tint background for updated leaves.
+ * @property changedColor - Foreground for updated leaves.
+ * @property changedBorderColor - Border for updated chips.
+ * @property unchangedColor - Foreground for unchanged rows when shown.
+ * @property acceptedBackground - Lane background for accepted-row indicator.
+ * @property acceptedBorderColor - Left-edge accent stripe for accepted rows.
+ * @property rejectedBackground - Lane background for rejected rows.
+ * @property rejectedBorderColor - Border for rejected rows.
+ * @property headerBackground - Card header background.
+ * @property summaryBackground - Stats bar background.
+ * @property background - Card body background.
+ * @property borderColor - Card outer border.
+ * @property indentGuideColor - Vertical guide line for nested rows.
+ * @property lineNumberColor - Gutter line numbers in unified mode.
+ */
+export declare const DiffStyleType: StructType<{
+    readonly addedBackground: OptionType<StringType>;
+    readonly addedColor: OptionType<StringType>;
+    readonly addedBorderColor: OptionType<StringType>;
+    readonly removedBackground: OptionType<StringType>;
+    readonly removedColor: OptionType<StringType>;
+    readonly removedBorderColor: OptionType<StringType>;
+    readonly changedBackground: OptionType<StringType>;
+    readonly changedColor: OptionType<StringType>;
+    readonly changedBorderColor: OptionType<StringType>;
+    readonly unchangedColor: OptionType<StringType>;
+    readonly acceptedBackground: OptionType<StringType>;
+    readonly acceptedBorderColor: OptionType<StringType>;
+    readonly rejectedBackground: OptionType<StringType>;
+    readonly rejectedBorderColor: OptionType<StringType>;
+    readonly headerBackground: OptionType<StringType>;
+    readonly summaryBackground: OptionType<StringType>;
+    readonly background: OptionType<StringType>;
+    readonly borderColor: OptionType<StringType>;
+    readonly indentGuideColor: OptionType<StringType>;
+    readonly lineNumberColor: OptionType<StringType>;
+}>;
+/** Type alias for {@link DiffStyleType}. */
+export type DiffStyleType = typeof DiffStyleType;
+export { DiffBindingType } from "./data.js";
+/**
+ * Schema for the `Diff` extension component. Internal IR shape — the
+ * developer-facing factory `Diff.Root` accepts {@link DataBindHandleType}
+ * descriptors and forwards them as `bindings`.
+ *
+ * @property bindings - The set of bindings to surface in the card. Each
+ *   entry is a {@link DiffBindingType} value (typically obtained via the
+ *   `binding` field of a {@link Data.bind} handle).
+ * @property readonly - Render the Diff without per-leaf or per-group Discard
+ *   buttons. The footer Apply / Discard-all still render. Default `false`
+ *   (interactive review).
+ * @property hideUnchanged - Elide unchanged rows. None ⇒ false.
+ * @property maxDepth - Cap nesting depth before "Show more" collapses. None ⇒ no cap.
+ * @property density - Information-density preset (`comfortable` | `compact`
+ *   | `condensed`). Defaults to `comfortable`.
+ * @property onCommitted - Fired after a successful commit (post-merge).
+ * @property onDiscarded - Fired after a successful discard.
+ * @property style - Visual style escape hatches.
+ */
+export declare const DiffPayloadType: StructType<{
+    readonly bindings: ArrayType<StructType<{
+        readonly source: ArrayType<import("@elaraai/east").VariantType<{
+            readonly field: StringType;
+        }>>;
+        readonly patch: OptionType<ArrayType<import("@elaraai/east").VariantType<{
+            readonly field: StringType;
+        }>>>;
+        readonly mode: import("@elaraai/east").VariantType<{
+            readonly staged: NullType;
+            readonly direct: NullType;
+        }>;
+    }>>;
+    readonly readonly: OptionType<BooleanType>;
+    readonly hideUnchanged: OptionType<BooleanType>;
+    readonly maxDepth: OptionType<IntegerType>;
+    readonly density: OptionType<import("@elaraai/east").VariantType<{
+        readonly comfortable: NullType;
+        readonly compact: NullType;
+        readonly condensed: NullType;
+    }>>;
+    readonly onCommitted: OptionType<FunctionType<[], NullType>>;
+    readonly onDiscarded: OptionType<FunctionType<[], NullType>>;
+    readonly style: OptionType<StructType<{
+        readonly addedBackground: OptionType<StringType>;
+        readonly addedColor: OptionType<StringType>;
+        readonly addedBorderColor: OptionType<StringType>;
+        readonly removedBackground: OptionType<StringType>;
+        readonly removedColor: OptionType<StringType>;
+        readonly removedBorderColor: OptionType<StringType>;
+        readonly changedBackground: OptionType<StringType>;
+        readonly changedColor: OptionType<StringType>;
+        readonly changedBorderColor: OptionType<StringType>;
+        readonly unchangedColor: OptionType<StringType>;
+        readonly acceptedBackground: OptionType<StringType>;
+        readonly acceptedBorderColor: OptionType<StringType>;
+        readonly rejectedBackground: OptionType<StringType>;
+        readonly rejectedBorderColor: OptionType<StringType>;
+        readonly headerBackground: OptionType<StringType>;
+        readonly summaryBackground: OptionType<StringType>;
+        readonly background: OptionType<StringType>;
+        readonly borderColor: OptionType<StringType>;
+        readonly indentGuideColor: OptionType<StringType>;
+        readonly lineNumberColor: OptionType<StringType>;
+    }>>;
+}>;
+/** Type alias for {@link DiffPayloadType}. */
+export type DiffPayloadType = typeof DiffPayloadType;
+/**
+ * Internal `EastUI.component` carrier. Renderers register against this in
+ * `@elaraai/e3-ui-components`. Most callers should use {@link Diff.Root}
+ * (which wraps this with the handle-friendly API) rather than touching
+ * `DiffComponent` directly.
+ */
+export declare const DiffComponent: import("@elaraai/east-ui").UIComponentDef<StructType<{
+    readonly bindings: ArrayType<StructType<{
+        readonly source: ArrayType<import("@elaraai/east").VariantType<{
+            readonly field: StringType;
+        }>>;
+        readonly patch: OptionType<ArrayType<import("@elaraai/east").VariantType<{
+            readonly field: StringType;
+        }>>>;
+        readonly mode: import("@elaraai/east").VariantType<{
+            readonly staged: NullType;
+            readonly direct: NullType;
+        }>;
+    }>>;
+    readonly readonly: OptionType<BooleanType>;
+    readonly hideUnchanged: OptionType<BooleanType>;
+    readonly maxDepth: OptionType<IntegerType>;
+    readonly density: OptionType<import("@elaraai/east").VariantType<{
+        readonly comfortable: NullType;
+        readonly compact: NullType;
+        readonly condensed: NullType;
+    }>>;
+    readonly onCommitted: OptionType<FunctionType<[], NullType>>;
+    readonly onDiscarded: OptionType<FunctionType<[], NullType>>;
+    readonly style: OptionType<StructType<{
+        readonly addedBackground: OptionType<StringType>;
+        readonly addedColor: OptionType<StringType>;
+        readonly addedBorderColor: OptionType<StringType>;
+        readonly removedBackground: OptionType<StringType>;
+        readonly removedColor: OptionType<StringType>;
+        readonly removedBorderColor: OptionType<StringType>;
+        readonly changedBackground: OptionType<StringType>;
+        readonly changedColor: OptionType<StringType>;
+        readonly changedBorderColor: OptionType<StringType>;
+        readonly unchangedColor: OptionType<StringType>;
+        readonly acceptedBackground: OptionType<StringType>;
+        readonly acceptedBorderColor: OptionType<StringType>;
+        readonly rejectedBackground: OptionType<StringType>;
+        readonly rejectedBorderColor: OptionType<StringType>;
+        readonly headerBackground: OptionType<StringType>;
+        readonly summaryBackground: OptionType<StringType>;
+        readonly background: OptionType<StringType>;
+        readonly borderColor: OptionType<StringType>;
+        readonly indentGuideColor: OptionType<StringType>;
+        readonly lineNumberColor: OptionType<StringType>;
+    }>>;
+}>>;
+/**
+ * Options for {@link Diff.Root}.
+ *
+ * @property bindings - The set of bindings to surface. Pass `view.binding`
+ *   from each {@link Data.bind} handle, or hand-build descriptors of shape
+ *   {@link DiffBindingType}.
+ * @property readonly - Render without per-leaf / per-group Discard buttons.
+ *   The footer Apply / Discard-all still render. Defaults to false.
+ * @property hideUnchanged - Elide unchanged rows. Defaults to false.
+ * @property maxDepth - Cap nesting depth. Defaults to no cap.
+ * @property density - Information-density preset (`comfortable` | `compact`
+ *   | `condensed`). Defaults to `comfortable`.
+ * @property onCommitted - Fired after the user commits.
+ * @property onDiscarded - Fired after the user discards.
+ * @property style - Visual style escape hatches.
+ */
+export interface DiffOptions {
+    /** Bindings to surface. Typically `[view.binding, ...]`. */
+    bindings: SubtypeExprOrValue<ArrayType<DiffBindingType>>;
+    /** Render without per-leaf / per-group Discard buttons. Defaults to false (interactive). */
+    readonly?: SubtypeExprOrValue<OptionType<BooleanType>>;
+    /** Elide unchanged rows. Defaults to false. */
+    hideUnchanged?: SubtypeExprOrValue<OptionType<BooleanType>>;
+    /** Cap nesting depth before "Show more" collapses. Defaults to no cap. */
+    maxDepth?: SubtypeExprOrValue<OptionType<IntegerType>>;
+    /** Information-density preset. */
+    density?: SubtypeExprOrValue<OptionType<DensityType>> | DensityLiteral;
+    /** Fired after a successful commit (post-merge). */
+    onCommitted?: SubtypeExprOrValue<OptionType<FunctionType<[], NullType>>>;
+    /** Fired after a successful discard. */
+    onDiscarded?: SubtypeExprOrValue<OptionType<FunctionType<[], NullType>>>;
+    /** Visual style escape hatches — see {@link DiffStyleType}. */
+    style?: SubtypeExprOrValue<OptionType<DiffStyleType>>;
+}
+/**
+ * The Diff component namespace. Surfaces transactional pending edits for
+ * review and commit, with merge-aware conflict resolution and stale-patch
+ * drift detection.
+ *
+ * @remarks
+ * Use `Diff.Root({ bindings: [view.binding, ...] })` to render the panel.
+ * The `Component` property is the internal {@link EastUI.component}
+ * carrier that renderers register against — most callers shouldn't need
+ * it.
+ */
+export declare const Diff: {
+    /**
+     * Build a Diff component. Surfaces every binding's in-flight change in
+     * a single review card, with per-leaf accept / reject and a footer
+     * Apply that runs the right commit per binding.
+     *
+     * @param options - {@link DiffOptions}. Only `bindings` is required;
+     *   the rest default to absent / interactive.
+     * @returns An East expression of {@link UIComponentType} representing
+     *   the Diff panel.
+     *
+     * @remarks
+     * The renderer reads each binding's IR descriptor (`source`, optional
+     * `patch`, `mode`), looks up the runtime types in the binding
+     * registry, and derives the in-flight change to display. Apply's
+     * commit code path depends on the binding's mode and patch presence —
+     * staged + no patch applies the buffer to source; staged + patch
+     * publishes the buffer as a fresh patch to the patch dataset; direct
+     * + patch applies the existing patch dataset to the source. Discard
+     * always drops the in-flight change in place.
+     *
+     * @example
+     * ```ts
+     * import { East, FloatType } from "@elaraai/east";
+     * import { Reactive, UIComponentType } from "@elaraai/east-ui";
+     * import { Data, Diff } from "@elaraai/e3-ui";
+     * import * as e3 from "@elaraai/e3";
+     *
+     * const maxWeeklyHoursInput = e3.input("max_weekly_hours", FloatType, 38.0);
+     *
+     * // Mirrors `diffDefaults` in test/diff.examples.ts (wired via Assert.examples).
+     * const diffDefaults = East.function([], UIComponentType, _$ => {
+     *     return Reactive.Root(East.function([], UIComponentType, $ => {
+     *         const view = $.let(Data.bind([FloatType], maxWeeklyHoursInput.path));
+     *         return Diff.Root({ bindings: [view.binding] });
+     *     }));
+     * });
+     * ```
+     */
+    readonly Root: (options: DiffOptions) => ExprType<UIComponentType>;
+    /**
+     * The internal {@link EastUI.component} carrier. Renderers register
+     * against this in `@elaraai/e3-ui-components` via
+     * `implementUIComponent(Diff.Component, EastChakraDiff)`. Most callers
+     * should use {@link Diff.Root} (the handle-friendly factory) and never
+     * touch this directly.
+     */
+    readonly Component: import("@elaraai/east-ui").UIComponentDef<StructType<{
+        readonly bindings: ArrayType<StructType<{
+            readonly source: ArrayType<import("@elaraai/east").VariantType<{
+                readonly field: StringType;
+            }>>;
+            readonly patch: OptionType<ArrayType<import("@elaraai/east").VariantType<{
+                readonly field: StringType;
+            }>>>;
+            readonly mode: import("@elaraai/east").VariantType<{
+                readonly staged: NullType;
+                readonly direct: NullType;
+            }>;
+        }>>;
+        readonly readonly: OptionType<BooleanType>;
+        readonly hideUnchanged: OptionType<BooleanType>;
+        readonly maxDepth: OptionType<IntegerType>;
+        readonly density: OptionType<import("@elaraai/east").VariantType<{
+            readonly comfortable: NullType;
+            readonly compact: NullType;
+            readonly condensed: NullType;
+        }>>;
+        readonly onCommitted: OptionType<FunctionType<[], NullType>>;
+        readonly onDiscarded: OptionType<FunctionType<[], NullType>>;
+        readonly style: OptionType<StructType<{
+            readonly addedBackground: OptionType<StringType>;
+            readonly addedColor: OptionType<StringType>;
+            readonly addedBorderColor: OptionType<StringType>;
+            readonly removedBackground: OptionType<StringType>;
+            readonly removedColor: OptionType<StringType>;
+            readonly removedBorderColor: OptionType<StringType>;
+            readonly changedBackground: OptionType<StringType>;
+            readonly changedColor: OptionType<StringType>;
+            readonly changedBorderColor: OptionType<StringType>;
+            readonly unchangedColor: OptionType<StringType>;
+            readonly acceptedBackground: OptionType<StringType>;
+            readonly acceptedBorderColor: OptionType<StringType>;
+            readonly rejectedBackground: OptionType<StringType>;
+            readonly rejectedBorderColor: OptionType<StringType>;
+            readonly headerBackground: OptionType<StringType>;
+            readonly summaryBackground: OptionType<StringType>;
+            readonly background: OptionType<StringType>;
+            readonly borderColor: OptionType<StringType>;
+            readonly indentGuideColor: OptionType<StringType>;
+            readonly lineNumberColor: OptionType<StringType>;
+        }>>;
+    }>>;
+};
+//# sourceMappingURL=diff.d.ts.map

package/dist/src/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/diff.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEH,UAAU,EACV,WAAW,EACX,QAAQ,EACR,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,YAAY,EAIZ,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAU,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAElG,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAM5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;EAqBxB,CAAC;AACH,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AAOjD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAM5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1B,CAAC;AACH,8CAA8C;AAC9C,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAAgE,CAAC;AAM3F;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IACxB,4DAA4D;IAC5D,QAAQ,EAAE,kBAAkB,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC;IACzD,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IACvD,+CAA+C;IAC/C,aAAa,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IACvD,kCAAkC;IAClC,OAAO,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,GAAG,cAAc,CAAC;IACvE,oDAAoD;IACpD,WAAW,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACzE,wCAAwC;IACxC,WAAW,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACzE,+DAA+D;IAC/D,KAAK,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI;IACb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;6BACW,WAAW,KAAG,QAAQ,CAAC,eAAe,CAAC;IAiBrD;;;;;;OAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAEG,CAAC"}