@elaraai/east-ui 1.0.67 → 1.0.69

package/dist/src/contracts/slice-affordances.d.ts

@@ -20,6 +20,8 @@ import { NullType, VariantType, type ExprType } from "@elaraai/east";
  * | `presets` | left | curated toggle-only preset pills (`Slice.Cohort` in `toggle` mode) |
  * | `search` | right (fixed) | closed `.search` pill that opens the dropdown |
  * | `range` | right | single date-window pill |
+ * | `resolution` | right | bucket-unit segment (`WEEK · DAY`) writing the slice's shared `resolution` |
+ * | `summary` | right (trailing) | the `N of M · narrowings` line (`Slice.Summary` as chrome) |
  *
  * A cross-cutting *contract*, not a style token — it lives in `src/contracts/`
  * alongside `StateValueType`.
@@ -31,15 +33,20 @@ import { NullType, VariantType, type ExprType } from "@elaraai/east";
  * @property cohort - Toggleable saved-segment pills with authoring (left zone)
  * @property presets - Curated toggle-only preset pills — no authoring (#163; left zone)
  * @property brush - Drag-a-window gesture writing the slice's range. Hosts
- *   render it natively: a Chart brushes the plot's continuous x, a Gantt the
- *   timeline, a standalone `Slice.Rail` the mini brush strip. Hosts with no
- *   continuous axis reject it at the factory.
+ *   render it natively: a Chart brushes the plot's continuous x, a Plan its
+ *   horizon strip, a standalone `Slice.Rail` the mini brush strip. Hosts with
+ *   no continuous axis reject it at the factory.
  * @property legend - The colour-matched series legend (primary click
  *   cross-filters; the eye toggles series visibility), rendered natively by
  *   the host: a Chart mounts it beneath the plot, a standalone `Slice.Rail`
  *   beneath the cluster. Explicit only (#187) — nothing mounts a legend the
  *   author didn't list; compose `<Slice.Legend>` directly to place it
  *   anywhere else.
+ * @property resolution - The shared bucket-unit segment (`WEEK · DAY`) beside
+ *   the range pill — writes `state.resolution` so every bound time-bucketed
+ *   surface re-buckets together. Hosts with no bucketed time axis omit it.
+ * @property summary - The trailing `N of M · narrowings` line —
+ *   `Slice.Summary` mounted as chrome at the rail's right edge.
  */
 export declare const SliceAffordanceType: VariantType<{
     readonly filter: NullType;
@@ -50,11 +57,13 @@ export declare const SliceAffordanceType: VariantType<{
     readonly brush: NullType;
     readonly presets: NullType;
     readonly legend: NullType;
+    readonly resolution: NullType;
+    readonly summary: NullType;
 }>;
 /** Type representing slice affordance variant values. */
 export type SliceAffordanceType = typeof SliceAffordanceType;
 /** String literal type for slice affordances. */
-export type SliceAffordanceLiteral = "filter" | "search" | "breakdown" | "range" | "cohort" | "brush" | "presets" | "legend";
+export type SliceAffordanceLiteral = "filter" | "search" | "breakdown" | "range" | "cohort" | "brush" | "presets" | "legend" | "resolution" | "summary";
 /**
  * Creates a slice affordance variant expression.
  *

package/dist/src/contracts/slice-affordances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slice-affordances.d.ts","sourceRoot":"","sources":["../../../src/contracts/slice-affordances.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,QAAQ,EAAW,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAMpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;EAS9B,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC;AAE7D,iDAAiD;AACjD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7H;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,sBAAsB,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAEjG"}
+{"version":3,"file":"slice-affordances.d.ts","sourceRoot":"","sources":["../../../src/contracts/slice-affordances.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,QAAQ,EAAW,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAMpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAY9B,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC;AAE7D,iDAAiD;AACjD,MAAM,MAAM,sBAAsB,GAC5B,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GACvF,YAAY,GAAG,SAAS,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,sBAAsB,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAEjG"}

package/dist/src/contracts/slice-affordances.js

@@ -23,6 +23,8 @@ import { East, NullType, variant, VariantType } from "@elaraai/east";
  * | `presets` | left | curated toggle-only preset pills (`Slice.Cohort` in `toggle` mode) |
  * | `search` | right (fixed) | closed `.search` pill that opens the dropdown |
  * | `range` | right | single date-window pill |
+ * | `resolution` | right | bucket-unit segment (`WEEK · DAY`) writing the slice's shared `resolution` |
+ * | `summary` | right (trailing) | the `N of M · narrowings` line (`Slice.Summary` as chrome) |
  *
  * A cross-cutting *contract*, not a style token — it lives in `src/contracts/`
  * alongside `StateValueType`.
@@ -34,15 +36,20 @@ import { East, NullType, variant, VariantType } from "@elaraai/east";
  * @property cohort - Toggleable saved-segment pills with authoring (left zone)
  * @property presets - Curated toggle-only preset pills — no authoring (#163; left zone)
  * @property brush - Drag-a-window gesture writing the slice's range. Hosts
- *   render it natively: a Chart brushes the plot's continuous x, a Gantt the
- *   timeline, a standalone `Slice.Rail` the mini brush strip. Hosts with no
- *   continuous axis reject it at the factory.
+ *   render it natively: a Chart brushes the plot's continuous x, a Plan its
+ *   horizon strip, a standalone `Slice.Rail` the mini brush strip. Hosts with
+ *   no continuous axis reject it at the factory.
  * @property legend - The colour-matched series legend (primary click
  *   cross-filters; the eye toggles series visibility), rendered natively by
  *   the host: a Chart mounts it beneath the plot, a standalone `Slice.Rail`
  *   beneath the cluster. Explicit only (#187) — nothing mounts a legend the
  *   author didn't list; compose `<Slice.Legend>` directly to place it
  *   anywhere else.
+ * @property resolution - The shared bucket-unit segment (`WEEK · DAY`) beside
+ *   the range pill — writes `state.resolution` so every bound time-bucketed
+ *   surface re-buckets together. Hosts with no bucketed time axis omit it.
+ * @property summary - The trailing `N of M · narrowings` line —
+ *   `Slice.Summary` mounted as chrome at the rail's right edge.
  */
 export const SliceAffordanceType = VariantType({
     filter: NullType,
@@ -53,6 +60,9 @@ export const SliceAffordanceType = VariantType({
     brush: NullType,
     presets: NullType,
     legend: NullType,
+    // Appended last: wire-order compatibility.
+    resolution: NullType,
+    summary: NullType,
 });
 /**
  * Creates a slice affordance variant expression.

package/dist/src/contracts/slice-affordances.js.map

@@ -1 +1 @@
-{"version":3,"file":"slice-affordances.js","sourceRoot":"","sources":["../../../src/contracts/slice-affordances.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAEpF,+EAA+E;AAC/E,uDAAuD;AACvD,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC;IAC3C,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,QAAQ;IACnB,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,QAAQ;CACnB,CAAC,CAAC;AAQH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC;IAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"slice-affordances.js","sourceRoot":"","sources":["../../../src/contracts/slice-affordances.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAEpF,+EAA+E;AAC/E,uDAAuD;AACvD,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC;IAC3C,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,QAAQ;IACnB,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,QAAQ;IAChB,2CAA2C;IAC3C,UAAU,EAAE,QAAQ;IACpB,OAAO,EAAE,QAAQ;CACpB,CAAC,CAAC;AAUH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC;IAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC;AACtE,CAAC"}

package/dist/src/contracts/source.d.ts

@@ -0,0 +1,432 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The ROW-SOURCE contract (#567) — how a collection component takes its rows.
+ *
+ * A component's `rows` / `data` prop accepts an inline collection or a WINDOWED
+ * source, and this module is the one place that vocabulary is spelled. Both are
+ * parameterised on the COLLECTION the component speaks — an `Array<Row>` for a
+ * positional surface, a `Dict<String, Row>` for a keyed one (#568). east-ui
+ * declares the shape; whoever can actually fetch windows produces a value of
+ * it. `Data.bindPaged` in `@elaraai/e3-ui` is the production implementation
+ * (dataset windows over an e3 workspace) and {@link Paged.of} is the in-memory
+ * one; neither is named here, and **nothing in this file imports e3**.
+ *
+ * # Why a variant, not a narrow struct
+ *
+ * East struct subtyping is EXACT — same arity, same field names, same order
+ * (`types.ts`'s `isSubtypeImpl`: `if (e1.length !== e2.length) return false`).
+ * Variants get width subtyping. So a narrow "source" struct could never be
+ * *satisfied* by a wider handle, and there is no `extends` to lean on. The
+ * component prop therefore takes a {@link RowSourceType} VARIANT, and the
+ * factory wraps whatever it was handed into the right arm at build time
+ * ({@link resolveRowSource}) — the same shape `Plan`'s rows channel already
+ * uses. What lands in the IR is a tagged union the renderer matches
+ * exhaustively, never a shape it has to sniff.
+ *
+ * @packageDocumentation
+ */
+import { type EastType, type ExprType, type SubtypeExprOrValue, ArrayType, BooleanType, DictType, FunctionType, IntegerType, OptionType, StringType, StructType, VariantType } from "@elaraai/east";
+/**
+ * Where a key query landed in a source's canonical row order.
+ *
+ * @remarks
+ * The RANGE, not just a row: a prefix query matches a contiguous run, and the
+ * search chrome needs `count` for its "k of n" indicator and its prev/next
+ * stepping. `found: false` still carries a `row` — the query's insertion point
+ * — so a miss can still position the viewport.
+ *
+ * @property found - Whether any row matched.
+ * @property row - First matched row (a miss carries the insertion row).
+ * @property count - Number of matched rows (1/0 for an exact key).
+ */
+export declare const SeekRangeType: StructType<{
+    readonly found: BooleanType;
+    readonly row: IntegerType;
+    readonly count: IntegerType;
+}>;
+/** Type alias for {@link SeekRangeType}. */
+export type SeekRangeType = typeof SeekRangeType;
+/**
+ * A key query, in the one form every key-ordered source understands.
+ *
+ * @remarks
+ * Three shapes, because a key is not always one string: an exact whole-key
+ * literal, a String prefix, or — for STRUCT keys — exact leading fields with an
+ * optional prefix continuing into the next String field. Every shape addresses
+ * ONE CONTIGUOUS RANGE in the canonical key order, which is what makes a hit a
+ * `row` + `count` rather than a set of scattered matches.
+ *
+ * Literals are canonical `.east` text of already-validated values, so the query
+ * is plain serializable data at any key type — no type-specific wire format,
+ * and the search chrome parses the user's text against the key type it was
+ * handed ({@link SeekType.keyType}) before it ever gets here.
+ *
+ * Deliberately the same three shapes as e3's `DatasetFindQuery`, so a bound
+ * source forwards a query rather than translating one.
+ *
+ * @property key - A whole-key `.east` literal — an exact lookup, any key type.
+ * @property prefix - A String prefix (String keys, or a Struct key's first
+ *   field when it is a String).
+ * @property fields - Struct keys: `.east` literals of exact leading fields in
+ *   declaration order (`values`), optionally continuing into the next String
+ *   field (`prefix`).
+ */
+export declare const SeekQueryType: VariantType<{
+    readonly key: StringType;
+    readonly prefix: StringType;
+    readonly fields: StructType<{
+        readonly values: ArrayType<StringType>;
+        readonly prefix: OptionType<StringType>;
+    }>;
+}>;
+/** Type alias for {@link SeekQueryType}. */
+export type SeekQueryType = typeof SeekQueryType;
+/**
+ * The KEY TYPE is deliberately NOT part of this contract.
+ *
+ * A first design carried it here (`seek: Option<{ keyType: EastTypeType, find }>`)
+ * so a component could compose a typed query with no authoring-time knowledge
+ * of the dataset's schema. Two things ruled it out:
+ *
+ * - `EastTypeType` is a `RecursiveType`, and the generic-platform type
+ *   substituter walks output types structurally — `applyTypeArgs`
+ *   (`east/src/expr/block.ts`) recurses forever through the marker and blows
+ *   the stack the moment `Data.bindPaged` instantiates its handle. A recursive
+ *   type cannot ride a generic platform's output.
+ * - It has no consumer. The hosts that mount key search — `<DatasetPreview>`,
+ *   `<PagedDatasetPreview>` — hold the dataset's `EastTypeValue` already and
+ *   pass it as a prop; a keyed component's own keys are Strings, whose search
+ *   input is a plain prefix.
+ *
+ * So the QUERY is data ({@link SeekQueryType}, `.east` literals as text) and the
+ * key type stays with whoever knows the schema. Revisit only with a real
+ * component-level consumer, and then as printed type text, not a recursive
+ * value.
+ */
+/**
+ * A WINDOWED view of a row collection — the contract a component consumes when
+ * the source is too large to hold whole.
+ *
+ * @remarks
+ * Deliberately read-only: a window is not a value you can diff or stage.
+ *
+ * Parameterised on the COLLECTION, not on the row: a window of an `Array<R>`
+ * dataset is an `Array<R>`, a window of a `Dict<K, V>` dataset is a
+ * `Dict<K, V>`, and the Plan's canvas windows are `Dict<String, PlanRow>`
+ * (#568). That is what `Data.bindPaged` already produces — it returns
+ * `Option<T>` at the dataset's own type — so the contract matches the producer
+ * instead of narrowing it to arrays.
+ *
+ * `page` and `total` follow the in-flight-is-`none` convention: a window still
+ * being fetched reads `none` and the call re-fires when it lands, so the reads
+ * belong inside a tracked evaluation. An EMPTY window (`some([])`) means the
+ * source is exhausted at that offset — a reader that walks offsets terminates
+ * on an empty window, never on `none`.
+ *
+ * @typeParam C - The collection type one window carries.
+ * @param c - The collection type value.
+ * @returns The concrete `StructType` of a paged source over `c`.
+ *
+ * @property id - Comparable identity (a dataset path, a fixture name). East
+ *   compares every function as EQUAL, so a struct of nothing but closures is
+ *   indistinguishable from any other — without this field a memoized component
+ *   never re-renders when the source is swapped, and a window cache cannot key
+ *   itself. Two sources with the same `id` must serve the same rows.
+ * @property page - `(offset, limit)` → that window's elements as a value of the
+ *   collection type; `none` while in flight, an EMPTY collection at exhaustion.
+ * @property total - The source's total element count, once known; `none` until then.
+ * @property seek - The source's key-search capability ({@link SeekType}) —
+ *   `none` when the source is not key-ordered (an Array-backed source cannot
+ *   seek; there is nothing to binary-search).
+ */
+export declare const PagedSourceType: <C extends EastType>(c: C) => StructType<{
+    readonly id: StringType;
+    readonly page: FunctionType<[IntegerType, IntegerType], OptionType<C>>;
+    readonly total: FunctionType<[], OptionType<IntegerType>>;
+    readonly seek: OptionType<FunctionType<[VariantType<{
+        readonly key: StringType;
+        readonly prefix: StringType;
+        readonly fields: StructType<{
+            readonly values: ArrayType<StringType>;
+            readonly prefix: OptionType<StringType>;
+        }>;
+    }>], OptionType<StructType<{
+        readonly found: BooleanType;
+        readonly row: IntegerType;
+        readonly count: IntegerType;
+    }>>>>;
+}>;
+/**
+ * The TypeScript type of a {@link PagedSourceType} over collection type `C` —
+ * what a component's prop takes when it wants a windowed source specifically.
+ *
+ * @remarks
+ * `C` rides STRUCTURALLY, in the `page` signature, so a source bound to one
+ * collection type is a compile error against a component expecting another. The
+ * identity lives in the East type rather than a phantom brand, so it survives
+ * `$.let` / `$.const` and ordinary expression plumbing.
+ *
+ * @typeParam C - The collection type one window carries.
+ */
+export type PagedSource<C extends EastType> = ExprType<ReturnType<typeof PagedSourceType<C>>>;
+/**
+ * How a component's rows arrive: inline, or from a windowed source.
+ *
+ * @remarks
+ * Both arms speak the same COLLECTION type — inline is the whole of it, paged
+ * is a window of it — so a component that keys its rows (the Plan's
+ * `Dict<String, PlanRow>`) and one that positions them (`Array<Row>`) share one
+ * vocabulary without either shape leaking into the arm names (#568).
+ *
+ * @typeParam C - The collection type.
+ * @param c - The collection type value.
+ * @returns The concrete `VariantType` of a row source over `c`.
+ *
+ * @property inline - The whole collection, already in hand.
+ * @property paged - A {@link PagedSourceType} fetched a window at a time.
+ */
+export declare const RowSourceType: <C extends EastType>(c: C) => VariantType<{
+    readonly inline: C;
+    readonly paged: StructType<{
+        readonly id: StringType;
+        readonly page: FunctionType<[IntegerType, IntegerType], OptionType<C>>;
+        readonly total: FunctionType<[], OptionType<IntegerType>>;
+        readonly seek: OptionType<FunctionType<[VariantType<{
+            readonly key: StringType;
+            readonly prefix: StringType;
+            readonly fields: StructType<{
+                readonly values: ArrayType<StringType>;
+                readonly prefix: OptionType<StringType>;
+            }>;
+        }>], OptionType<StructType<{
+            readonly found: BooleanType;
+            readonly row: IntegerType;
+            readonly count: IntegerType;
+        }>>>>;
+    }>;
+}>;
+/**
+ * The TypeScript type of a {@link RowSourceType} over collection type `C`.
+ *
+ * @typeParam C - The collection type.
+ */
+export type RowSource<C extends EastType> = ExprType<ReturnType<typeof RowSourceType<C>>>;
+/**
+ * The loose TS face a paged source presents at a `rows` / `data` prop —
+ * structural only (`page` / `total`, which a concrete source expression
+ * exposes and an array expression does not). {@link resolveRowSource}'s
+ * `Expr.type` dispatch is the real check.
+ */
+export interface PagedSourceLike {
+    /** The source's page method (typed precisely on the concrete value). */
+    readonly page: unknown;
+    /** The source's total method. */
+    readonly total: unknown;
+}
+/**
+ * What a component's rows prop accepts: an inline collection expression, a
+ * paged source, or a whole-value bind handle (anything with a `read`).
+ *
+ * @typeParam C - The collection type.
+ */
+export type RowSourceInput<C extends EastType> = SubtypeExprOrValue<C> | PagedSourceLike;
+/**
+ * A resolved rows prop — the arm, the COLLECTION type the source speaks, the
+ * element type recovered from it (an `Array`'s value, a `Set`'s key, a
+ * `Dict`'s value), and its KEY type when it has one.
+ *
+ * `keyType` is what a keyed component checks: the Plan requires
+ * `Dict<String, R>` because its canvas rows inherit the source's keys, so an
+ * unkeyed source is refused rather than silently re-keyed (#568).
+ */
+export type ResolvedRowSource = {
+    kind: "inline";
+    rows: ExprType<EastType>;
+    collectionType: EastType;
+    elementType: EastType;
+    keyType: EastType | undefined;
+} | {
+    kind: "paged";
+    source: ExprType<StructType>;
+    collectionType: EastType;
+    elementType: EastType;
+    keyType: EastType | undefined;
+};
+/**
+ * Classify a component's rows prop at BUILD time — the one dispatch every
+ * collection shares, so no component re-sniffs shapes of its own.
+ *
+ * Accepted shapes, in order:
+ * - a collection expression / value (`Array<R>`, `Dict<K, V>`, `Set<R>`) ⇒ `inline`;
+ * - a struct carrying `page` + `total` ⇒ `paged` (a {@link PagedSourceType},
+ *   or anything structurally matching it — `Data.bindPaged`'s handle);
+ * - a struct carrying `read` ⇒ a whole-value bind handle, which resolves by
+ *   CALLING `read()` and recursing. The call becomes part of the surrounding
+ *   East expression, so it is evaluated inside the component's reactive render
+ *   and re-fires like any other tracked read — `rows={handle}` and
+ *   `rows={handle.read()}` build the same IR.
+ *
+ * @param data - The rows prop as the author passed it
+ * @param label - Component name for the error message (`"Plan"`, `"Table"`)
+ * @returns The resolved arm — see {@link ResolvedRowSource}
+ * @throws Error when the expression is none of the accepted shapes
+ */
+export declare function resolveRowSource(data: unknown, label: string): ResolvedRowSource;
+/**
+ * Wrap a resolved rows prop into the {@link RowSourceType} arm a component
+ * stores, mapping each window through the same `make` the inline arm applies
+ * to the whole collection.
+ *
+ * @remarks
+ * `make` is the component's own row-construction pipeline (Table's
+ * `rows_mapped`, Plan's `applySeries`). Applying it inside `page` is the single
+ * point where the DOMAIN collection is erased to the component's row
+ * COLLECTION, so everything downstream — the renderer, the window cache — sees
+ * one row space.
+ *
+ * It is handed the source's COLLECTION, not a flattened element array: a keyed
+ * component's rows inherit the source's keys, and flattening at the boundary
+ * would throw away exactly what makes a window's rows addressable (#568). A
+ * positional component (Table) receives its `Array<Row>`; a keyed one (Plan) a
+ * `Dict<String, R>`.
+ *
+ * @typeParam Out - The component's own row COLLECTION type.
+ * @param resolved - The output of {@link resolveRowSource}
+ * @param outType - The component's row collection type
+ * @param make - The source collection → the component's row collection
+ * @param idSuffix - Appended to the paged source's `id` — see below
+ * @returns The `RowSourceType(outType)` value to store in the IR
+ *
+ * @remarks
+ * `idSuffix` exists because `make` is part of what the derived source SERVES.
+ * {@link PagedSourceType} requires that two sources sharing an `id` serve the
+ * same rows, and a component whose `make` changes — a Plan whose series list was
+ * narrowed by a pick — now serves different rows from the same underlying
+ * handle. Since a window cache keys on `id` alone and resident windows are never
+ * re-read, an unsigned id leaves the previous rows on screen forever. A
+ * component that can vary its `make` must pass a signature of what varied.
+ */
+export declare function buildRowSource<Out extends EastType>(resolved: ResolvedRowSource, outType: Out, make: (collection: ExprType<EastType>) => SubtypeExprOrValue<Out>, idSuffix?: SubtypeExprOrValue<StringType>): RowSource<Out>;
+/** Options for the ARRAY form of {@link Paged.of}. */
+export interface PagedOfOptions<R extends EastType> {
+    /**
+     * Key accessor. Supplying it declares the rows are SORTED by that key and
+     * enables `seek` (prefix-matched, the canonical key order the search
+     * chrome expects). Omitted ⇒ `seek` is `none`, exactly as an
+     * Array-backed dataset behaves.
+     *
+     * A keyed collection needs none of this — pass a `Dict` and its own keys
+     * are the row order and the search space.
+     */
+    key?: (row: ExprType<R>) => SubtypeExprOrValue<StringType>;
+}
+/**
+ * Build an in-memory {@link PagedSourceType} over a collection already in hand
+ * — the paged sibling of passing the array directly.
+ *
+ * @remarks
+ * Every window resolves immediately (`page` never returns `none`), so this is
+ * the source to reach for in examples, fixtures and tests: it exercises the
+ * whole paged path — windowing, exhaustion on `some([])`, totals, seek — with
+ * no server, no platform function and no bind. `@elaraai/e3-ui`'s
+ * `Data.bindPaged` is the same contract backed by real dataset windows.
+ *
+ * Windows follow the collection: an `Array` source serves array windows in
+ * stream order, a `Dict` source serves DICT windows in canonical key order —
+ * the same shape and the same order a keyed dataset's windows arrive in, which
+ * is what a keyed component (the Plan) requires of its source (#568).
+ *
+ * @typeParam R - The row type (array form) / the value type (dict form).
+ * @param id - Comparable identity for this source (see {@link PagedSourceType}).
+ * @param collection - The whole collection — an `Array<R>` or a `Dict<String, R>`.
+ * @param options - {@link PagedOfOptions} — array form only; supply `key` to enable `seek`.
+ * @returns A `PagedSourceType` at the collection it was given.
+ *
+ * @example
+ * ```tsx
+ * // A keyed source: the canvas rows inherit these keys, so `seek` addresses
+ * // real rows and a window's key range is a canvas key range.
+ * const units = $.const(new Map([["UNIT-001", { … }]]), DictType(StringType, UnitRow));
+ * const source = $.const(Paged.of("units", units));
+ * // A paged canvas declares its window — fitting the axis to a partial
+ * // prefix would re-fit it on every landed window (#567 D8).
+ * const axis = $.const(Plan.axis({ window: { min: W27, max: W39 }, resolution: "week" }));
+ * return <Plan axis={axis} data={source} series={series} style={{ height: "fill" }} />;
+ * ```
+ */
+declare function createPagedOf<R extends EastType>(id: SubtypeExprOrValue<StringType>, rows: SubtypeExprOrValue<ArrayType<R>>, options?: PagedOfOptions<R>): PagedSource<ArrayType<R>>;
+declare function createPagedOf<V extends EastType>(id: SubtypeExprOrValue<StringType>, entries: SubtypeExprOrValue<DictType<StringType, V>>): PagedSource<DictType<StringType, V>>;
+/**
+ * The `Paged` namespace — building a {@link PagedSourceType} without a server.
+ *
+ * @remarks
+ * The contract itself is what components consume; this namespace is the
+ * in-memory producer. Production sources come from the platform that owns the
+ * data (`Data.bindPaged` in `@elaraai/e3-ui`).
+ */
+export declare const Paged: {
+    /** Build an in-memory paged source over a collection already in hand. */
+    readonly of: typeof createPagedOf;
+    /** East types — the contract, for `$.const` / `$.let` annotations. */
+    readonly Types: {
+        /** A windowed row source over a collection type. */
+        readonly Source: <C extends EastType>(c: C) => StructType<{
+            readonly id: StringType;
+            readonly page: FunctionType<[IntegerType, IntegerType], OptionType<C>>;
+            readonly total: FunctionType<[], OptionType<IntegerType>>;
+            readonly seek: OptionType<FunctionType<[VariantType<{
+                readonly key: StringType;
+                readonly prefix: StringType;
+                readonly fields: StructType<{
+                    readonly values: ArrayType<StringType>;
+                    readonly prefix: OptionType<StringType>;
+                }>;
+            }>], OptionType<StructType<{
+                readonly found: BooleanType;
+                readonly row: IntegerType;
+                readonly count: IntegerType;
+            }>>>>;
+        }>;
+        /** Where a key query landed in a source's row order. */
+        readonly SeekRange: StructType<{
+            readonly found: BooleanType;
+            readonly row: IntegerType;
+            readonly count: IntegerType;
+        }>;
+        /** A key query — exact literal, String prefix, or leading struct fields. */
+        readonly SeekQuery: VariantType<{
+            readonly key: StringType;
+            readonly prefix: StringType;
+            readonly fields: StructType<{
+                readonly values: ArrayType<StringType>;
+                readonly prefix: OptionType<StringType>;
+            }>;
+        }>;
+        /** How a component's rows arrive (inline / paged), at a collection type. */
+        readonly RowSource: <C extends EastType>(c: C) => VariantType<{
+            readonly inline: C;
+            readonly paged: StructType<{
+                readonly id: StringType;
+                readonly page: FunctionType<[IntegerType, IntegerType], OptionType<C>>;
+                readonly total: FunctionType<[], OptionType<IntegerType>>;
+                readonly seek: OptionType<FunctionType<[VariantType<{
+                    readonly key: StringType;
+                    readonly prefix: StringType;
+                    readonly fields: StructType<{
+                        readonly values: ArrayType<StringType>;
+                        readonly prefix: OptionType<StringType>;
+                    }>;
+                }>], OptionType<StructType<{
+                    readonly found: BooleanType;
+                    readonly row: IntegerType;
+                    readonly count: IntegerType;
+                }>>>>;
+            }>;
+        }>;
+    };
+};
+export {};
+//# sourceMappingURL=source.d.ts.map

package/dist/src/contracts/source.d.ts.map

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