@elaraai/e3-ui 1.0.11 → 1.0.13

package/dist/src/experiment/index.d.ts.map

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

package/dist/src/experiment/index.js

@@ -0,0 +1,147 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `Experiment` component — an interactive causal-experiment surface.
+ *
+ * @remarks
+ * `Experiment` lets a domain expert ask *"did X change Y, and can I trust it?"*
+ * against a dataset and read a derived, honest answer — without meeting a
+ * statistician's vocabulary. It is a registered extension component
+ * (architecturally like {@link Ontology}): the author writes one tag,
+ * `Experiment.Root({ … })`; the React renderer lives in
+ * `@elaraai/e3-ui-components`.
+ *
+ * **Generic over the input row, like `Table`.** The author binds the input
+ * dataset (`data: BoundValue<ArrayType<Row>>`); the renderer introspects its row
+ * struct to drive the treatment / outcome / confounder pickers.
+ *
+ * **The user edits the config → Apply runs ONE function.** Editing a picker
+ * stages a new {@link ExperimentConfigType}; **Apply** calls the single bound
+ * `experiment` function (`(rows, config) → ExperimentResult`) and the answer
+ * arrives reactively. The result carries the naive vs adjusted effect, balance,
+ * overlap, robustness, and an honesty **verdict** — `adjusted` is `none` when the
+ * engine refuses. **Commit** appends to the journal.
+ *
+ * **Visual-first and derived.** Nothing on the result side is hand-authored —
+ * every word is a column name the user picked, a number the engine returned, or
+ * a status derived by rule from the verdict tag.
+ *
+ * @packageDocumentation
+ */
+import { NullType, BooleanType, ArrayType, StructType, VariantType, OptionType, East, none, some, variant, } from '@elaraai/east';
+import { EastUI } from '@elaraai/east-ui';
+import { DiffBindingType } from '../data.js';
+import { FuncBindingType } from '../func.js';
+import { ExperimentConfigType, ExperimentResultType, DoseResponseType, JournalType, ColumnMetaType, PopulationType, DesignConfigType, ExperimentDesignType, } from './types.js';
+// Re-export the contract types so consumers can reach them from the component
+// module too (the canonical home is `./types`).
+export { CiType, WeightingSchemeType, EstimatorType, TargetUnitsType, BootstrapConfigType, RefuteSpecType, ExperimentConfigType, BalanceRowType, OverlapDiagnosticType, RefutationType, DoseResponseType, ExperimentVerdictType, ExperimentResultType, JournalRowType, JournalType, ColumnMetaType, PopulationType, } from './types.js';
+// ============================================================================
+// Component payload — descriptors only (binding handles + options).
+// ============================================================================
+/** Initial result tab variant — `answer` (default), `trust`, `dose`, or `validate`. */
+export const ExperimentTabType = VariantType({ answer: NullType, trust: NullType, dose: NullType, validate: NullType });
+/**
+ * The `Experiment` component payload — binding descriptors + options. Renderers
+ * decode this and resolve each binding to a live, reactive value / call handle.
+ *
+ * @property data - {@link DiffBindingType} for the input dataset — the renderer
+ *   introspects its row struct for the pickers and passes it to the function.
+ * @property config - {@link DiffBindingType} for the staged {@link ExperimentConfigType}.
+ * @property experiment - {@link FuncBindingType} for the single `experiment` function.
+ * @property population - Optional {@link DiffBindingType} for the staged Step-4
+ *   population filter ({@link PopulationType}); narrows rows UI-side before the call.
+ * @property journal - Optional {@link DiffBindingType} for the committed-experiment journal.
+ * @property columnMeta - Optional per-column display metadata.
+ * @property readonly - Render without the Apply / Commit / edit affordances.
+ * @property defaultTab - Initial result tab ({@link ExperimentTabType}).
+ */
+export const ExperimentPayloadType = StructType({
+    data: DiffBindingType,
+    config: DiffBindingType,
+    experiment: FuncBindingType,
+    population: OptionType(DiffBindingType),
+    journal: OptionType(DiffBindingType),
+    /** Optional `design` function → the validation-trial recipe ("Validate" tab). */
+    design: OptionType(FuncBindingType),
+    columnMeta: OptionType(ColumnMetaType),
+    readonly: OptionType(BooleanType),
+    defaultTab: OptionType(ExperimentTabType),
+});
+/**
+ * Internal {@link EastUI.component} carrier. The React renderer registers
+ * against this in `@elaraai/e3-ui-components`.
+ */
+export const ExperimentComponent = EastUI.component('Experiment', ExperimentPayloadType, { optional: true });
+/**
+ * Build an Experiment surface bound to an input dataset + the single experiment
+ * function.
+ *
+ * @typeParam Row - The input dataset's row struct, inferred from `data`.
+ * @param options - {@link ExperimentOptions}. `data`, `config` and `experiment`
+ *   are required; the rest are optional.
+ * @returns An East expression of {@link UIComponentType}.
+ */
+function createExperiment(options) {
+    const defaultTab = options.defaultTab === undefined
+        ? none
+        : some(East.value(variant(options.defaultTab, null), ExperimentTabType));
+    const columnMeta = options.columns === undefined
+        ? none
+        : some(East.value(new Map(Object.entries(options.columns).map(([k, c]) => [k, {
+                label: c?.label !== undefined ? some(c.label) : none,
+                unit: c?.unit !== undefined ? some(c.unit) : none,
+                higherIsBetter: c?.higherIsBetter !== undefined ? some(c.higherIsBetter) : none,
+            }])), ColumnMetaType));
+    return ExperimentComponent.Root({
+        data: options.data.binding,
+        config: options.config.binding,
+        experiment: options.experiment.binding,
+        population: options.population !== undefined ? some(options.population.binding) : none,
+        journal: options.journal !== undefined ? some(options.journal.binding) : none,
+        design: options.design !== undefined ? some(options.design.binding) : none,
+        columnMeta,
+        readonly: options.readonly ?? none,
+        defaultTab,
+    });
+}
+/**
+ * The Experiment component namespace. Surfaces an interactive causal-experiment
+ * over a bound input dataset + a single `experiment` function, generic over the
+ * row struct (the `Table` pattern).
+ *
+ * @remarks
+ * Use `Experiment.Root({ data, config, experiment, journal })` inside a
+ * `Reactive` block. `Types` exposes the render-contract value types (`Config`,
+ * `Result`, `Verdict`, `Overlap`, `Balance`, `Refutation`, `Journal`, …).
+ */
+export const Experiment = {
+    Root: createExperiment,
+    /** The internal {@link EastUI.component} carrier renderers register against. */
+    Component: ExperimentComponent,
+    Types: {
+        /** Rendered payload struct (bindings + options). */
+        Payload: ExperimentPayloadType,
+        /** The experiment-config value type (what the pickers stage). */
+        Config: ExperimentConfigType,
+        /** The result value type (numbers + verdict). */
+        Result: ExperimentResultType,
+        /** The ALE dose-response curve value type (the "How much?" tab). */
+        DoseResponse: DoseResponseType,
+        /** The committed-experiment journal value type. */
+        Journal: JournalType,
+        /** The validation-trial recipe value type (the "Validate" tab). */
+        Design: ExperimentDesignType,
+        /** The optional design-knobs value type. */
+        DesignConfig: DesignConfigType,
+        /** The UI-side Step-4 population filter value type (Array of Slice predicates). */
+        Population: PopulationType,
+        /** Optional per-column display metadata. */
+        ColumnMeta: ColumnMetaType,
+        /** Initial result tab variant. */
+        Tab: ExperimentTabType,
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/src/experiment/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/experiment/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACH,QAAQ,EACR,WAAW,EACX,SAAS,EACT,UAAU,EACV,WAAW,EACX,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,OAAO,GAGV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,MAAM,EAAwB,MAAM,kBAAkB,CAAC;AAEhE,OAAO,EAAE,eAAe,EAAmB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAkB,MAAM,YAAY,CAAC;AAC7D,OAAO,EACH,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACvB,MAAM,YAAY,CAAC;AAEpB,8EAA8E;AAC9E,gDAAgD;AAChD,OAAO,EACH,MAAM,EACN,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,cAAc,EACd,cAAc,GACjB,MAAM,YAAY,CAAC;AAsBpB,+EAA+E;AAC/E,oEAAoE;AACpE,+EAA+E;AAE/E,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;AAIxH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC;IAC5C,IAAI,EAAE,eAAe;IACrB,MAAM,EAAE,eAAe;IACvB,UAAU,EAAE,eAAe;IAC3B,UAAU,EAAE,UAAU,CAAC,eAAe,CAAC;IACvC,OAAO,EAAE,UAAU,CAAC,eAAe,CAAC;IACpC,iFAAiF;IACjF,MAAM,EAAE,UAAU,CAAC,eAAe,CAAC;IACnC,UAAU,EAAE,UAAU,CAAC,cAAc,CAAC;IACtC,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC;IACjC,UAAU,EAAE,UAAU,CAAC,iBAAiB,CAAC;CAC5C,CAAC,CAAC;AAOH;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,qBAAqB,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AA2D7G;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAyB,OAA+B;IAC7E,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,KAAK,SAAS;QAC/C,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC7E,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,KAAK,SAAS;QAC5C,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CACb,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE;gBACxD,KAAK,EAAE,CAAC,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;gBACpD,IAAI,EAAE,CAAC,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;gBACjD,cAAc,EAAE,CAAC,EAAE,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI;aAClF,CAAU,CAAC,CAAC,EACb,cAAc,CACjB,CAAC,CAAC;IACP,OAAO,mBAAmB,CAAC,IAAI,CAAC;QAC5B,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO;QACtC,UAAU,EAAE,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI;QACtF,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI;QAC7E,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI;QAC1E,UAAU;QACV,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;QAClC,UAAU;KACb,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACtB,IAAI,EAAE,gBAAgB;IACtB,gFAAgF;IAChF,SAAS,EAAE,mBAAmB;IAC9B,KAAK,EAAE;QACH,oDAAoD;QACpD,OAAO,EAAE,qBAAqB;QAC9B,iEAAiE;QACjE,MAAM,EAAE,oBAAoB;QAC5B,iDAAiD;QACjD,MAAM,EAAE,oBAAoB;QAC5B,oEAAoE;QACpE,YAAY,EAAE,gBAAgB;QAC9B,mDAAmD;QACnD,OAAO,EAAE,WAAW;QACpB,mEAAmE;QACnE,MAAM,EAAE,oBAAoB;QAC5B,4CAA4C;QAC5C,YAAY,EAAE,gBAAgB;QAC9B,mFAAmF;QACnF,UAAU,EAAE,cAAc;QAC1B,4CAA4C;QAC5C,UAAU,EAAE,cAAc;QAC1B,kCAAkC;QAClC,GAAG,EAAE,iBAAiB;KACzB;CACK,CAAC"}