@elaraai/e3-ui 1.0.86 → 1.0.87

package/dist/src/plan/builders.d.ts

@@ -0,0 +1,790 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Plan value builders — shorthand resolvers, the instant sugar
+ * ({@link resolveInstant} / `Plan.at`), the axis declarations (`Plan.axis`,
+ * `.time` / `.number` / `.ordinal`), element value builders (`Plan.run` /
+ * `decision` / `port` / `event` / `marker` / `chip` / `mark`) and cell
+ * builders (`heatCells` / `weightCells` / `segmentCells` / `tableCells`).
+ * Every element is pure data — rich click/hover surfaces resolve through
+ * the ROOT's `popover` / `hover` functions over `PlanElementRefType`
+ * (`Plan Data Interface.md` §3.3), never per-element embeds.
+ *
+ * @packageDocumentation
+ */
+import { type ExprType, type SubtypeExprOrValue, ArrayType, BooleanType, DateTimeType, FloatType, IntegerType, OptionType, StringType, StructType } from "@elaraai/east";
+import { EventStateType, IconType, StatusValueType, type EventStateLiteral, type IconName, type StatusValueLiteral } from "@elaraai/east-ui";
+import { ColorSchemeType, MatrixFillType, TickFormatType, type ColorSchemeLiteral, type MatrixFillLiteral, type SolidIconPrefix } from "@elaraai/east-ui/internal";
+import { type PlanAxisOptions, type PlanNumberAxisOptions, type PlanOrdinalAxisOptions, PlanInstantType, type PlanInstantLikeType, type PlanInstantInput, type PlanAxisKindLiteral, type PlanKindOf, type PlanInstantExpr, type PlanRunExpr, type PlanDecisionMarkExpr, type PlanPortExpr, type PlanBucketEventExpr, type PlanCellMarkerExpr, type PlanChipExpr, type PlanEventMarkExpr, type PlanHeatCellsExpr, type PlanTableCellsExpr, type PlanTableSeriesExpr, type PlanAxisExpr, type PlanCellsInput, type PlanTableCellsInput, PlanStretchType, type PlanStretchLiteral, PlanContentAlignType, type PlanContentAlignLiteral, PlanAnimationType, type PlanAnimationLiteral, PlanEventMarkKindType, PlanHeatCellType, PlanWeightCellType, PlanSegmentType, PlanSegmentCellType, PlanTableToneType, type PlanTableToneLiteral, PlanLinkType, PlanRunRefType, PlanLaneType, PlanRowIdType, PlanFoldType, type PlanFoldLiteral, PlanQuantityType, PlanHeatScaleType, PlanUiStateType } from "./types.js";
+/**
+ * Resolves the shared event-lifecycle string shorthands into an
+ * {@link EventStateType} value: `"estimated"`, `"added"`, `"recommended"`,
+ * `"removed"` (the three `proposed` flavours), `"confirmed"`,
+ * `"in-progress"`, `"actual"`, `"rejected"`.
+ *
+ * @param state - An `EventStateType` value/expression or a string shorthand
+ * @returns The resolved `EventStateType` value
+ */
+export declare function resolvePlanEventState(state: SubtypeExprOrValue<EventStateType> | EventStateLiteral): SubtypeExprOrValue<EventStateType>;
+/** A fold input — a {@link PlanFoldLiteral} or a `PlanFoldType` value / expression (#824). */
+export type PlanFoldInput = PlanFoldLiteral | SubtypeExprOrValue<PlanFoldType>;
+/**
+ * Resolve a fold input, falling back to the default of what it folds.
+ *
+ * @param fold - The declared fold, if any
+ * @param fallback - The default for the values being folded (`mean` for levels, `sum` for amounts)
+ * @returns The fold
+ */
+export declare function resolveFold(fold: PlanFoldInput | undefined, fallback: PlanFoldLiteral): ExprType<PlanFoldType>;
+/**
+ * An icon input — a bare Font Awesome solid name (`"rocket"`), a
+ * `{ prefix: "fas", name }` pair, or an `IconType` expression (the Banner
+ * envelope precedent). East UI draws Font Awesome's solid set only (#1263).
+ * The mounting context pins size and colour; hosts choose the glyph, never
+ * the geometry.
+ */
+export type PlanIconInput = IconName | {
+    prefix: SolidIconPrefix;
+    name: string;
+} | SubtypeExprOrValue<IconType>;
+/**
+ * Resolve a {@link PlanIconInput} into an `IconType` value.
+ *
+ * @param icon - The icon
+ * @param where - What takes it, as a refusal names it (`Plan.run icon`, …)
+ * @returns The icon as an `IconType` value or expression
+ * @throws {Error} When an icon given by value is not of Font Awesome's solid set (#1263)
+ */
+export declare function resolveIcon(icon: PlanIconInput, where?: string): SubtypeExprOrValue<IconType>;
+/**
+ * Resolves an instant input into a {@link PlanInstantType} value — the one
+ * place the arm is inferred (#631).
+ *
+ * @remarks
+ * The input is any {@link PlanInstantLikeType} value or expression. JS values
+ * wrap by their type (`Date` ⇒ `time`, `number` / `bigint` ⇒ `number`,
+ * `string` ⇒ `ordinal`); East expressions wrap by their STATIC type
+ * (`DateTimeType` ⇒ `time`, `FloatType` ⇒ `number`, `IntegerType` ⇒ `number`
+ * via `toFloat`, `StringType` ⇒ `ordinal`); a {@link PlanInstantType} value
+ * or expression passes through (subtype-checked by `East.value`). Nothing
+ * here knows the canvas axis — the arm is the INPUT's; the renderer holds it
+ * against the root's declaration.
+ *
+ * @param v - The instant (a value or expression of a {@link PlanInstantLikeType})
+ * @param where - The field being resolved, for the error message
+ * @returns The instant as a `PlanInstantType` expression
+ * @throws {Error} If `v` is an expression of a non-instant type
+ */
+export declare function resolveInstant(v: PlanInstantInput, where: string): ExprType<PlanInstantType>;
+/**
+ * The `Plan.at` builders — one instant per axis kind, explicitly. The
+ * element builders already wrap by type; these are for element RECORDS
+ * written as data (`{ at: Plan.at.time(week(27n)), … }` in a
+ * `Plan.Types.HeatCell` array) and for reading as a declaration. Each
+ * result is BRANDED with its arm ({@link PlanInstantExpr}), so a cell
+ * list built from them carries the kind to the root's compile-time check.
+ */
+export declare const at: {
+    /**
+     * A `time` instant.
+     *
+     * @param v - The UTC instant (a `Date` or `DateTimeType` expression)
+     * @returns A `PlanInstantType` expression with the `time` arm, branded `"time"`
+     */
+    readonly time: (v: SubtypeExprOrValue<DateTimeType>) => PlanInstantExpr<"time">;
+    /**
+     * A `number` instant.
+     *
+     * @param v - The position (a number or `FloatType` expression)
+     * @returns A `PlanInstantType` expression with the `number` arm, branded `"number"`
+     */
+    readonly number: (v: SubtypeExprOrValue<FloatType> | number) => PlanInstantExpr<"number">;
+    /**
+     * An `ordinal` instant.
+     *
+     * @param v - The declared value (a string or `StringType` expression)
+     * @returns A `PlanInstantType` expression with the `ordinal` arm, branded `"ordinal"`
+     */
+    readonly ordinal: (v: SubtypeExprOrValue<StringType>) => PlanInstantExpr<"ordinal">;
+};
+/**
+ * The axis values built WITHOUT a window (#822) — a canvas given one must bind
+ * a slice, whose range supplies the window, or the root refuses it at build
+ * time. An axis held in a variable (`$.const(Plan.axis(…))`) is not the value
+ * recorded here, so its canvas is held to the rule at render instead.
+ */
+export declare const WINDOWLESS_AXES: WeakSet<object>;
+/**
+ * The kind of an axis value `Plan.axis` built.
+ *
+ * @param axis - A Plan's `axis`
+ * @returns `"time"`, `"number"` or `"ordinal"`; `undefined` for an axis held in a variable
+ * @internal
+ */
+export declare function axisKindOf(axis: unknown): PlanAxisKindLiteral | undefined;
+/**
+ * Builds the `time` axis declaration — `Plan.axis({ … })` / `Plan.axis.time`.
+ *
+ * @param options - Window, resolution(s), now instant and tick format ({@link PlanAxisOptions})
+ * @returns An East expression of {@link PlanAxisType} (the `time` arm), branded `"time"` — the root's canvas kind
+ *
+ * @remarks
+ * The window is half-open `[min, max)` in UTC; omit it to follow the bound
+ * slice's datetime range — a canvas states one or the other (#822). There is
+ * no fit to the data. `resolutions` lists the WEEK/DAY-style segment options
+ * (omit ⇒ no segment). When the Plan is slice-bound, slice state supersedes
+ * window + resolution after mount — the slice is the single source of truth.
+ */
+export declare function createTimeAxis(options: PlanAxisOptions): PlanAxisExpr<"time">;
+/**
+ * Builds the `number` axis declaration — `Plan.axis.number({ … })`.
+ *
+ * @param options - Window, step, now position and tick format ({@link PlanNumberAxisOptions})
+ * @returns An East expression of {@link PlanAxisType} (the `number` arm), branded `"number"` — the root's canvas kind
+ * @throws {Error} If a literal `step` is not `> 0`
+ *
+ * @remarks
+ * `[min, max)` ÷ `step` = `n` buckets, edges on whole multiples of `step`
+ * (the `TimeResolution` rule, numerically). Omit the window to follow the
+ * bound slice's `float` / `integer` range — a canvas states one or the other
+ * (#822). Element instants on this canvas are numbers — a `FloatType` /
+ * `IntegerType` accessor or a bare number wraps to the `number` arm.
+ */
+export declare function createNumberAxis(options: PlanNumberAxisOptions): PlanAxisExpr<"number">;
+/**
+ * Builds the `ordinal` axis declaration — `Plan.axis.ordinal({ … })`.
+ *
+ * @param options - The ordered values and the now value ({@link PlanOrdinalAxisOptions})
+ * @returns An East expression of {@link PlanAxisType} (the `ordinal` arm), branded `"ordinal"` — the root's canvas kind
+ * @throws {Error} If a literal `values` list is empty
+ *
+ * @remarks
+ * The declared values ARE the buckets, one each, in order; the window is
+ * the whole list, so there is no slice range to brush and the window keys
+ * idle. Element instants on this canvas are the values — a `StringType`
+ * accessor or a bare string wraps to the `ordinal` arm.
+ */
+export declare function createOrdinalAxis(options: PlanOrdinalAxisOptions): PlanAxisExpr<"ordinal">;
+/**
+ * The `Plan.axis` builder — the `time` shorthand, with the explicit
+ * per-kind builders as members (the Planner's `Planner.axis.time / .number /
+ * .ordinal` names).
+ */
+export interface PlanAxisBuilder {
+    /** The `time` axis (the shorthand — `Plan.axis({ resolution: "week", … })`). */
+    (options: PlanAxisOptions): PlanAxisExpr<"time">;
+    /** The `time` axis, explicitly. */
+    time: typeof createTimeAxis;
+    /** The `number` axis — a numeric window ÷ `step`. */
+    number: typeof createNumberAxis;
+    /** The `ordinal` axis — a declared list of values. */
+    ordinal: typeof createOrdinalAxis;
+}
+/**
+ * Builds the shared axis declaration — `Plan.axis({ … })` is the `time`
+ * shorthand; `Plan.axis.time` / `.number` / `.ordinal` declare each kind.
+ *
+ * @param options - The time-axis options ({@link PlanAxisOptions})
+ * @returns An East expression of {@link PlanAxisType}, branded with its kind
+ */
+export declare const createAxis: PlanAxisBuilder;
+/**
+ * How a quantity prints — see {@link Plan.quantity}.
+ *
+ * @property unit - The unit it is in (`"k sheets"`); quantities in different units never sum together
+ * @property format - How the value prints (a `Format.*` spec); omit ⇒ the canvas's plain number
+ * @property text - The caption to print instead of the formatted value and unit
+ */
+export interface PlanQuantityOptions {
+    /** The unit the value is in (`"k sheets"`) — printed after it, and what a rollup sums by. */
+    unit?: SubtypeExprOrValue<StringType>;
+    /** How the value prints — a `Format.*` spec (the shared `TickFormatType`), in the viewer's locale. */
+    format?: SubtypeExprOrValue<TickFormatType>;
+    /** The caption to print instead of the formatted value and unit — the value still sums and weighs. */
+    text?: SubtypeExprOrValue<StringType>;
+}
+/**
+ * Builds a quantity — a number with its unit and how it prints (#824). A run
+ * carries one as its `quantity` (its bar prints it; a parent's rollup band sums
+ * its runs' per unit), and so does a link (its weight and its caption).
+ *
+ * @param value - The amount (a number or `FloatType` expression)
+ * @param options - Its unit, format and caption override ({@link PlanQuantityOptions})
+ * @returns An East expression of {@link PlanQuantityType}
+ */
+export declare function createQuantity(value: SubtypeExprOrValue<FloatType> | number, options?: PlanQuantityOptions): ExprType<PlanQuantityType>;
+/**
+ * Flat input for {@link Plan.run} — one continuous state-run bar.
+ *
+ * @typeParam S - The `start` input's type — its axis kind brands the result ({@link PlanKindOf})
+ * @typeParam E - The `end` input's type
+ * @property key - Stable run identity (drag refs, link edges)
+ * @property start - Run start (inclusive) — an instant input (a Date / number / string, or a typed expression)
+ * @property end - Run end (exclusive)
+ * @property label - The bar text (`"RUN · J-4642"`)
+ * @property quantity - Optional quantity (`Plan.quantity(96, { unit: "k sheets" })`) — printed after the label, summed into rollup bands per unit
+ * @property state - The lifecycle state (string shorthand or `EventStateType`)
+ * @property status - Optional status tint (`"warning"` ⇒ the over-dwell ring)
+ * @property moved - Optional same-status churn counter (`moved ×k`)
+ * @property icon - Optional leading FA glyph (10px, inherits bar text colour)
+ */
+export interface PlanRunInput<S extends PlanInstantInput = PlanInstantInput, E extends PlanInstantInput = PlanInstantInput> {
+    /** Stable run identity (drag refs, link edges). */
+    key: SubtypeExprOrValue<StringType>;
+    /** Run start (inclusive) — wraps to the axis arm by its type (see {@link PlanInstantLikeType}). */
+    start: S;
+    /** Run end (exclusive). */
+    end: E;
+    /** The bar text (`"RUN · J-4642"`). */
+    label: SubtypeExprOrValue<StringType>;
+    /** Optional quantity — `Plan.quantity(96, { unit: "k sheets" })`: the bar prints its caption after the label
+     *  (the muted `.q` text), and a parent's rollup band sums it with its siblings' in the same unit. */
+    quantity?: SubtypeExprOrValue<PlanQuantityType>;
+    /** The lifecycle state — a string shorthand or an `EventStateType` value. */
+    state: SubtypeExprOrValue<EventStateType> | EventStateLiteral;
+    /** Optional status tint — `"warning"` draws the `.stuck` over-dwell ring. */
+    status?: SubtypeExprOrValue<StatusValueType> | StatusValueLiteral;
+    /** Optional same-status churn counter (rendered `moved ×k`, never extra bars). */
+    moved?: SubtypeExprOrValue<IntegerType> | number;
+    /** Optional leading FA glyph (10px, inherits the bar text colour). */
+    icon?: PlanIconInput;
+}
+/**
+ * Builds one span run from a flat input. The result is BRANDED with the axis
+ * kind `start` / `end` imply ({@link PlanKindOf}) — a `DateTimeType` accessor
+ * makes a `"time"` run, a `FloatType` one a `"number"` run — so the series and
+ * root can refuse a mismatched kind at compile time; an erased input (an
+ * `Expr<PlanInstantType>`) leaves the run unbranded.
+ *
+ * @typeParam S - The `start` input's type
+ * @typeParam E - The `end` input's type
+ * @param input - The run configuration ({@link PlanRunInput})
+ * @returns An East expression of {@link PlanRunType}, branded with its kind
+ */
+export declare function createRun<S extends PlanInstantInput, E extends PlanInstantInput>(input: PlanRunInput<S, E>): PlanRunExpr<PlanKindOf<S | E>>;
+/**
+ * Flat input for {@link Plan.decision} — a ◇/◆ diamond on a run transition.
+ *
+ * @typeParam A - The `at` input's type — its axis kind brands the result
+ * @property key - Stable decision identity
+ * @property at - The transition instant the diamond sits on
+ * @property applied - `true` fills the diamond (◆)
+ */
+export interface PlanDecisionInput<A extends PlanInstantInput = PlanInstantInput> {
+    /** Stable decision identity. */
+    key: SubtypeExprOrValue<StringType>;
+    /** The transition instant the diamond sits on (see {@link PlanInstantLikeType}). */
+    at: A;
+    /** `true` fills the diamond (◆ applied). */
+    applied: SubtypeExprOrValue<BooleanType> | boolean;
+}
+/**
+ * Builds one decision mark from a flat input, branded with `at`'s kind.
+ *
+ * @typeParam A - The `at` input's type
+ * @param input - The decision configuration ({@link PlanDecisionInput})
+ * @returns An East expression of {@link PlanDecisionMarkType}, branded with its kind
+ */
+export declare function createDecision<A extends PlanInstantInput>(input: PlanDecisionInput<A>): PlanDecisionMarkExpr<PlanKindOf<A>>;
+/**
+ * Flat input for {@link Plan.port} — a quantity in/out glyph on a span row.
+ *
+ * @typeParam A - The `at` input's type — its axis kind brands the result
+ * @property at - The instant the quantity moves
+ * @property label - Optional caption (`"−24 k sheets"`)
+ */
+export interface PlanPortInput<A extends PlanInstantInput = PlanInstantInput> {
+    /** The instant the quantity moves (see {@link PlanInstantLikeType}). */
+    at: A;
+    /** Optional caption (`"−24 k sheets"`). */
+    label?: SubtypeExprOrValue<StringType>;
+}
+/**
+ * Builds one port glyph from a flat input, branded with `at`'s kind.
+ *
+ * @typeParam A - The `at` input's type
+ * @param input - The port configuration ({@link PlanPortInput})
+ * @returns An East expression of {@link PlanPortType}, branded with its kind
+ */
+export declare function createPort<A extends PlanInstantInput>(input: PlanPortInput<A>): PlanPortExpr<PlanKindOf<A>>;
+/**
+ * Flat input for {@link Plan.event} — one bucket-row tile (the full Planner
+ * point-event grammar).
+ *
+ * @typeParam A - The `at` input's type — its axis kind brands the result
+ * @property key - Stable event identity (drag refs)
+ * @property at - The bucket instant
+ * @property lane - The lane key (`[]`-laned rows omit it; in a laned row, omitting takes the full cell)
+ * @property label - Optional tile text; omitted ⇒ the resting ✓ / `plan` chip
+ * @property icon - Optional leading FA glyph (icon-only tile when `label` omitted)
+ * @property state - The lifecycle state (string shorthand or value)
+ * @property tone - Optional semantic tile tint
+ * @property color - Optional raw colour token override
+ * @property colorPalette - Optional brand palette override
+ * @property stretch - Optional fill axis (`"horizontal"` / `"vertical"` / `"both"`)
+ * @property content - Optional two-axis content alignment
+ * @property animation - Optional attention animation (`"pulse"`)
+ */
+export interface PlanBucketEventInput<A extends PlanInstantInput = PlanInstantInput> {
+    /** Stable event identity (drag-grammar cell refs). */
+    key: SubtypeExprOrValue<StringType>;
+    /** The bucket instant (see {@link PlanInstantLikeType}). */
+    at: A;
+    /** The lane key. In a laned row, omitting takes the full cell (the mixed grammar). */
+    lane?: SubtypeExprOrValue<StringType>;
+    /** Optional tile text; omitted ⇒ ✓ (confirmed/actual) or the dashed `plan` chip (proposed). */
+    label?: SubtypeExprOrValue<StringType>;
+    /** Optional leading FA glyph (chip-sized, inherits chip colour; icon-only tile when `label` omitted). */
+    icon?: PlanIconInput;
+    /** The lifecycle state — a string shorthand or an `EventStateType` value. */
+    state: SubtypeExprOrValue<EventStateType> | EventStateLiteral;
+    /** Optional semantic tile tint (keeps the state's border-style). */
+    tone?: SubtypeExprOrValue<StatusValueType> | StatusValueLiteral;
+    /** Optional raw colour token override (`"teal.solid"`). */
+    color?: SubtypeExprOrValue<StringType>;
+    /** Optional brand palette override (`"teal"`, `"purple"`). */
+    colorPalette?: SubtypeExprOrValue<ColorSchemeType> | ColorSchemeLiteral;
+    /** Optional fill axis. */
+    stretch?: SubtypeExprOrValue<PlanStretchType> | PlanStretchLiteral;
+    /** Optional two-axis content alignment (defaults to top-left). */
+    content?: {
+        /** Horizontal content alignment (→ `justifyContent`). */
+        horizontal?: SubtypeExprOrValue<PlanContentAlignType> | PlanContentAlignLiteral;
+        /** Vertical content alignment (→ `alignItems`). */
+        vertical?: SubtypeExprOrValue<PlanContentAlignType> | PlanContentAlignLiteral;
+    };
+    /** Optional attention animation (`"pulse"` honours `prefers-reduced-motion`). */
+    animation?: SubtypeExprOrValue<PlanAnimationType> | PlanAnimationLiteral;
+}
+/**
+ * Builds one bucket event from a flat input, branded with `at`'s kind.
+ *
+ * @typeParam A - The `at` input's type
+ * @param input - The event configuration ({@link PlanBucketEventInput})
+ * @returns An East expression of {@link PlanBucketEventType}, branded with its kind
+ */
+export declare function createBucketEvent<A extends PlanInstantInput>(input: PlanBucketEventInput<A>): PlanBucketEventExpr<PlanKindOf<A>>;
+/**
+ * Flat input for {@link Plan.lane} — one bucket-row sub-slot lane.
+ *
+ * @property key - The lane key (`"am"`) — bucket events reference it via `lane`
+ * @property label - Optional printed caption (`"AM"`); omitted ⇒ an unlabelled strip
+ */
+export interface PlanLaneInput {
+    /** The lane key (`"am"`) — bucket events reference it via `lane`. */
+    key: SubtypeExprOrValue<StringType>;
+    /** Optional printed caption (`"AM"`); omitted ⇒ an unlabelled strip. */
+    label?: SubtypeExprOrValue<StringType>;
+}
+/**
+ * Builds one bucket-row lane from a flat input.
+ *
+ * @param input - The lane configuration ({@link PlanLaneInput})
+ * @returns An East expression of {@link PlanLaneType}
+ */
+export declare function createLane(input: PlanLaneInput): ExprType<PlanLaneType>;
+/**
+ * A row's id by its series and path — `Plan.ref("press-jobs", "H1", "p03")`
+ * is the row series `press-jobs` made from entry `p03` under `H1` (#822).
+ * What `links` name their ends with, and what a callback's row compares to.
+ *
+ * @remarks
+ * A segment is an entry's key as the canvas prints it: a String key as is, any
+ * other key type as its `.east` text (`printFor`), an `Array` child's index as
+ * its digits.
+ *
+ * @param series - The series key
+ * @param path - The entry keys that lead to the row, outermost first
+ * @returns The `entry` id
+ */
+export declare function createRef(series: SubtypeExprOrValue<StringType>, ...path: SubtypeExprOrValue<StringType>[]): ExprType<PlanRowIdType>;
+/**
+ * A section header's id — `Plan.sectionRef("crew-block", "H1")` is the
+ * `crew-block` section's header under entry `H1`; a top-level section's path
+ * is empty (#822).
+ *
+ * @param series - The section's series key
+ * @param path - The path of the entry the section sits under (empty at the top level)
+ * @returns The `section` id
+ */
+export declare function createSectionRef(series: SubtypeExprOrValue<StringType>, ...path: SubtypeExprOrValue<StringType>[]): ExprType<PlanRowIdType>;
+/**
+ * What a bound `ui` state starts as — see {@link Plan.uiState}.
+ *
+ * @property selected - The selected row
+ * @property collapsed - Rows folded against what they declare
+ * @property expanded - Rows opened against what they declare
+ * @property charts - Chart rows expanded from spark
+ * @property focus - A row to bring into view (a request the canvas spends)
+ */
+export interface PlanUiStateInput {
+    /** The selected row. */
+    selected?: SubtypeExprOrValue<PlanRowIdType>;
+    /** Rows folded — overriding what they declare. */
+    collapsed?: SubtypeExprOrValue<PlanRowIdType>[] | SubtypeExprOrValue<ArrayType<PlanRowIdType>>;
+    /** Rows opened — overriding what they declare. */
+    expanded?: SubtypeExprOrValue<PlanRowIdType>[] | SubtypeExprOrValue<ArrayType<PlanRowIdType>>;
+    /** Chart rows expanded from spark to full height. */
+    charts?: SubtypeExprOrValue<PlanRowIdType>[] | SubtypeExprOrValue<ArrayType<PlanRowIdType>>;
+    /** A row to bring into view — the canvas spends the request (`none`) once it has. */
+    focus?: SubtypeExprOrValue<PlanRowIdType>;
+}
+/**
+ * Builds a {@link PlanUiStateType} value — the seed of a bound `ui` state
+ * (`State.bind([Plan.Types.UiState], key, Plan.uiState())`, #824). Omitted
+ * fields are empty: nothing selected, every row as it declares, no chart
+ * expanded, nothing to bring into view.
+ *
+ * @param init - What the state starts as ({@link PlanUiStateInput})
+ * @returns An East expression of {@link PlanUiStateType}
+ */
+export declare function createUiState(init?: PlanUiStateInput): ExprType<PlanUiStateType>;
+/**
+ * Flat input for {@link Plan.link} — one run-edge quantity link of the
+ * canvas's link graph (a Plan's `links`). Each end is a row and a run on it
+ * (`from` and `fromRun`), or an event of one of the Plan's event kinds
+ * (`from: Plan.eventRef("job", key)`, no run), wherever it draws (#1191).
+ *
+ * @property key - The link's identity — what a click on its ribbon names it by (#824)
+ * @property from - The source row's id (`Plan.ref(series, …path)`), or an event (`Plan.eventRef(kind, key)`)
+ * @property fromRun - The source run key (the ribbon leaves this run's end edge); none with an event
+ * @property to - The destination row's id, or an event
+ * @property toRun - The destination run key (the ribbon lands on this run's start edge); none with an event
+ * @property quantity - The moved quantity (`Plan.quantity(34, { unit: "k sheets" })`) — the link's weight and caption
+ */
+export interface PlanLinkInput {
+    /** The link's identity — what the `link` element ref a ribbon click reports names it by (#824). */
+    key: SubtypeExprOrValue<StringType>;
+    /** The source row's id (`Plan.ref(series, …path)`), or an event (`Plan.eventRef(kind, key)`). */
+    from: SubtypeExprOrValue<PlanRowIdType> | ExprType<PlanRunRefType>;
+    /** The source run key (the ribbon leaves this run's end edge) — with a row's id; an event names its own. */
+    fromRun?: SubtypeExprOrValue<StringType>;
+    /** The destination row's id, or an event. */
+    to: SubtypeExprOrValue<PlanRowIdType> | ExprType<PlanRunRefType>;
+    /** The destination run key (the ribbon lands on this run's start edge) — with a row's id; an event names its own. */
+    toRun?: SubtypeExprOrValue<StringType>;
+    /** The moved quantity — `Plan.quantity(34, { unit: "k sheets" })`: its value's third of the family's largest
+     *  sets the link's weight (2, 4 or 8), and its caption prints on the link, on a paper knockout. Omit ⇒ the
+     *  thinnest link (1.5), no caption. */
+    quantity?: SubtypeExprOrValue<PlanQuantityType>;
+}
+/**
+ * The event kinds a link names at its ends, when they are known at build —
+ * what a Plan checks against its `events` (#1191).
+ *
+ * @param link - A link value
+ * @returns The kinds its event ends name, in order — none for a link between rows; `undefined` for a link
+ *   `Plan.link` did not build here (held in a variable, or built in East) or whose event end was held in a
+ *   variable, which a Plan checks as it is evaluated instead
+ * @internal
+ */
+export declare function linkEventKinds(link: unknown): readonly string[] | undefined;
+/**
+ * Builds one link edge from a flat input. Links are root DATA
+ * (`links={transfers.map(($, t) => Plan.link({ … }))}`): the links-focus
+ * control gathers a row's transitive upstream/downstream family over them.
+ *
+ * @param input - The link configuration ({@link PlanLinkInput})
+ * @returns An East expression of {@link PlanLinkType}
+ * @throws {Error} When an end is a row's id without its run, or an event with one
+ */
+export declare function createLink(input: PlanLinkInput): ExprType<PlanLinkType>;
+/**
+ * Flat input for {@link Plan.marker} — a bucket-cell status ring.
+ *
+ * @typeParam A - The `at` input's type — its axis kind brands the result
+ * @property at - The bucket instant the marker rings
+ * @property lane - The lane key within the cell
+ * @property status - The semantic status (default `"danger"`)
+ * @property message - The hover-tooltip text
+ */
+export interface PlanCellMarkerInput<A extends PlanInstantInput = PlanInstantInput> {
+    /** The bucket instant the marker rings (see {@link PlanInstantLikeType}). */
+    at: A;
+    /** The lane key within the cell. */
+    lane?: SubtypeExprOrValue<StringType>;
+    /** The semantic status (default `"danger"`). */
+    status?: SubtypeExprOrValue<StatusValueType> | StatusValueLiteral;
+    /** The hover-tooltip text. */
+    message: SubtypeExprOrValue<StringType>;
+}
+/**
+ * Builds one cell marker from a flat input, branded with `at`'s kind.
+ *
+ * @typeParam A - The `at` input's type
+ * @param input - The marker configuration ({@link PlanCellMarkerInput})
+ * @returns An East expression of {@link PlanCellMarkerType}, branded with its kind
+ */
+export declare function createCellMarker<A extends PlanInstantInput>(input: PlanCellMarkerInput<A>): PlanCellMarkerExpr<PlanKindOf<A>>;
+/**
+ * Flat input for {@link Plan.chip} — one cards-row shift chip.
+ *
+ * @typeParam F - The `from` input's type — its axis kind brands the result
+ * @typeParam T - The `to` input's type
+ * @property key - Stable chip identity
+ * @property from - Chip start (inclusive)
+ * @property to - Chip end (exclusive)
+ * @property label - The chip text (`"80h"`, `"+64h"`)
+ * @property state - The lifecycle state (string shorthand or value)
+ * @property icon - Optional leading FA glyph
+ */
+export interface PlanChipInput<F extends PlanInstantInput = PlanInstantInput, T extends PlanInstantInput = PlanInstantInput> {
+    /** Stable chip identity (drag refs). */
+    key: SubtypeExprOrValue<StringType>;
+    /** Chip start (inclusive) — see {@link PlanInstantLikeType}. */
+    from: F;
+    /** Chip end (exclusive). */
+    to: T;
+    /** The chip text (`"80h"`, `"+64h"`). */
+    label: SubtypeExprOrValue<StringType>;
+    /** The lifecycle state — confirmed tint · proposed dashed · removed strikethrough · estimated ghost. */
+    state: SubtypeExprOrValue<EventStateType> | EventStateLiteral;
+    /** Optional leading FA glyph (shift-type etc.). */
+    icon?: PlanIconInput;
+}
+/**
+ * Builds one cards chip from a flat input, branded with the kind `from` /
+ * `to` imply.
+ *
+ * @typeParam F - The `from` input's type
+ * @typeParam T - The `to` input's type
+ * @param input - The chip configuration ({@link PlanChipInput})
+ * @returns An East expression of {@link PlanChipType}, branded with its kind
+ */
+export declare function createChip<F extends PlanInstantInput, T extends PlanInstantInput>(input: PlanChipInput<F, T>): PlanChipExpr<PlanKindOf<F | T>>;
+/**
+ * Flat input for {@link Plan.mark} — one event-row instant mark.
+ *
+ * @typeParam A - The `at` input's type — its axis kind brands the result
+ * @property key - Stable mark identity
+ * @property at - The instant
+ * @property kind - `"milestone"` / `"exception"` / `Plan.markKind.decision(applied)`
+ * @property icon - Optional FA glyph swap (12px, kind-coloured)
+ * @property label - Optional caption (printed when there is room)
+ */
+export interface PlanEventMarkInput<A extends PlanInstantInput = PlanInstantInput> {
+    /** Stable mark identity. */
+    key: SubtypeExprOrValue<StringType>;
+    /** The instant (see {@link PlanInstantLikeType}). */
+    at: A;
+    /** The mark kind — `"milestone"` / `"exception"` string shorthand or a `PlanEventMarkKindType` value (see `Plan.markKind`). */
+    kind: SubtypeExprOrValue<PlanEventMarkKindType> | "milestone" | "exception";
+    /** Optional FA glyph swap (12px, still kind-coloured). */
+    icon?: PlanIconInput;
+    /** Optional caption (printed when there is room). */
+    label?: SubtypeExprOrValue<StringType>;
+}
+/**
+ * Builds one event mark from a flat input, branded with `at`'s kind.
+ *
+ * @typeParam A - The `at` input's type
+ * @param input - The mark configuration ({@link PlanEventMarkInput})
+ * @returns An East expression of {@link PlanEventMarkType}, branded with its kind
+ */
+export declare function createEventMark<A extends PlanInstantInput>(input: PlanEventMarkInput<A>): PlanEventMarkExpr<PlanKindOf<A>>;
+/** The `Plan.markKind` builders — non-null mark kinds. */
+export declare const markKind: {
+    /**
+     * A decision diamond mark — ◇ pending / ◆ applied.
+     *
+     * @param applied - `true` fills the diamond
+     * @returns A `PlanEventMarkKindType` expression with the `decision` arm
+     */
+    readonly decision: (applied: SubtypeExprOrValue<BooleanType> | boolean) => ExprType<PlanEventMarkKindType>;
+};
+/**
+ * A heat scale — the value at no depth, the value at full depth, and the warn
+ * threshold ({@link PlanHeatScaleType}).
+ *
+ * @property min - The value painted at no depth (default: the least shown)
+ * @property max - The value painted at full depth (default: the greatest shown)
+ * @property warnAt - Warn-ring threshold (≥ it rings the cell)
+ */
+export interface PlanHeatScaleInput {
+    /** The value painted at no depth (default: the least value shown). */
+    min?: SubtypeExprOrValue<FloatType> | number;
+    /** The value painted at full depth (default: the greatest value shown). */
+    max?: SubtypeExprOrValue<FloatType> | number;
+    /** Warn-ring threshold (≥ it rings the cell). */
+    warnAt?: SubtypeExprOrValue<FloatType> | number;
+}
+/**
+ * Build a heat scale value from its input.
+ *
+ * @param input - The scale ({@link PlanHeatScaleInput}); omit ⇒ every bound from the values shown
+ * @returns An East expression of {@link PlanHeatScaleType}
+ */
+export declare function createHeatScale(input?: PlanHeatScaleInput): ExprType<PlanHeatScaleType>;
+/**
+ * How a cells arm folds and prints (#824) — the options every cell builder
+ * takes.
+ *
+ * @property fold - How a bucket folds the cells that fall in it at a coarser resolution than theirs
+ * @property format - How the arm's values print (a `Format.*` spec)
+ */
+export interface PlanCellsFoldOptions {
+    /** How a bucket folds the cells that fall in it at a coarser resolution than theirs
+     *  (`"sum"` / `"mean"` / `"min"` / `"max"` / `"last"` / `"count"`; each builder says its default). */
+    fold?: PlanFoldInput;
+    /** How the arm's values print — a `Format.*` spec (the shared `TickFormatType`), in the viewer's locale. */
+    format?: SubtypeExprOrValue<TickFormatType>;
+}
+/**
+ * Options for {@link Plan.heatCells} — the heat scale, the warn threshold, and
+ * how the cells fold and print.
+ *
+ * @property min - Scale minimum (default: the least shown)
+ * @property max - Scale maximum (default: the greatest shown)
+ * @property warnAt - Warn-ring threshold (≥ it rings the cell)
+ * @property fold - How a bucket folds its cells (default `"mean"`)
+ * @property format - How a value prints — a cell without a `label` prints its value only when one is declared
+ */
+export interface PlanHeatCellsOptions extends PlanHeatScaleInput, PlanCellsFoldOptions {
+}
+/**
+ * Wraps per-bucket heat cells into the `heat` arm of {@link PlanHeatCellsType}.
+ * Literal records whose `at` is a `Plan.at.*` value brand the result with
+ * that kind ({@link PlanCellsInput}); an East array is kind-erased.
+ *
+ * @remarks
+ * At a coarser resolution than the cells', a bucket shows ONE cell — the
+ * `fold` of the cells in it (`"mean"` by default: a heat cell is a level).
+ * A cell prints its `label`; one without prints its value only through a
+ * declared `format` (#824).
+ *
+ * @typeParam K - The kind inferred from the literal records' `at`
+ * @param cells - The cells (`{ at, value, label }` structs; `value: none` ⇒ the no-data hatch)
+ * @param options - Scale, warn threshold, fold and format ({@link PlanHeatCellsOptions})
+ * @returns A `PlanHeatCellsType` expression, branded with the cells' kind
+ */
+export declare function createHeatCells<K extends PlanAxisKindLiteral = never>(cells: PlanCellsInput<PlanHeatCellType, K>, options?: PlanHeatCellsOptions): PlanHeatCellsExpr<K>;
+/**
+ * Wraps per-bucket weight cells into the `weight` arm of
+ * {@link PlanHeatCellsType} (booked-vs-free bars; planned ⇒ pale). Literal
+ * records with `Plan.at.*` instants brand the result with their kind.
+ *
+ * @remarks
+ * At a coarser resolution, a bucket shows ONE bar — the `fold` of its cells'
+ * fractions (`"mean"` by default: a cell is the fraction of its bucket booked,
+ * and a month's fraction is its weeks' mean), pale only when every cell in it
+ * is planned. `format` prints the fraction in the words a reader hears
+ * (default: a percent).
+ *
+ * @typeParam K - The kind inferred from the literal records' `at`
+ * @param cells - The cells (`{ at, fraction, planned }` structs)
+ * @param options - Fold and format ({@link PlanCellsFoldOptions})
+ * @returns A `PlanHeatCellsType` expression, branded with the cells' kind
+ */
+export declare function createWeightCells<K extends PlanAxisKindLiteral = never>(cells: PlanCellsInput<PlanWeightCellType, K>, options?: PlanCellsFoldOptions): PlanHeatCellsExpr<K>;
+/**
+ * Wraps per-bucket segment cells into the `segments` arm of
+ * {@link PlanHeatCellsType} (committed / pending / slack compositions).
+ * Literal records with `Plan.at.*` instants brand the result with their kind.
+ *
+ * @remarks
+ * At a coarser resolution, a bucket shows ONE composition — each fill's
+ * weights folded across the cells in it (`"sum"` by default: the weights are
+ * amounts, and the bar normalises them). `format` prints a segment's share in
+ * the words a reader hears (default: a percent).
+ *
+ * @typeParam K - The kind inferred from the literal records' `at`
+ * @param cells - The cells (`{ at, segments }` structs — build segments with `Plan.segment`)
+ * @param options - Fold and format ({@link PlanCellsFoldOptions})
+ * @returns A `PlanHeatCellsType` expression, branded with the cells' kind
+ */
+export declare function createSegmentCells<K extends PlanAxisKindLiteral = never>(cells: PlanCellsInput<PlanSegmentCellType, K>, options?: PlanCellsFoldOptions): PlanHeatCellsExpr<K>;
+/**
+ * Flat input for {@link Plan.segment} — one weighted slice of a segment cell.
+ *
+ * @property fill - The status-leveraged fill (string shorthand or `MatrixFillType`)
+ * @property weight - The proportional weight
+ * @property label - Optional in-bar text (printed when wide enough)
+ */
+export interface PlanSegmentInput {
+    /** The status-leveraged fill. */
+    fill: SubtypeExprOrValue<MatrixFillType> | MatrixFillLiteral;
+    /** The proportional weight (normalised with siblings). */
+    weight: SubtypeExprOrValue<FloatType> | number;
+    /** Optional in-bar text (printed when the segment is wide enough). */
+    label?: SubtypeExprOrValue<StringType>;
+}
+/**
+ * Builds one segment from a flat input (the Matrix segment vocabulary).
+ *
+ * @param input - The segment configuration ({@link PlanSegmentInput})
+ * @returns An East expression of {@link PlanSegmentType}
+ */
+export declare function createSegment(input: PlanSegmentInput): ExprType<typeof PlanSegmentType>;
+/**
+ * Flat input for {@link Plan.tableSeries} — one value series of a
+ * multi-series table row. Style is declared ONCE here, per position (never
+ * per cell — the wire-lean contract); the cells stay raw values.
+ *
+ * @typeParam K - The cells' axis kind (a `Plan.tableCells` result carries it)
+ * @property cells - The series' cells (a `Plan.tableCells` result / `PlanTableCellType` values)
+ * @property format - Numeral format override for this series (else the row's `format`)
+ * @property tone - Default tone for the series' values (`"muted"` de-emphasises a plan column)
+ * @property strong - Semibold emphasis for this series' values
+ * @property rollup - `true` ⇒ this series feeds declared parent aggregation (flag none ⇒ every series does)
+ * @property fold - How a bucket folds this series' cells at a coarser resolution (default `"sum"`)
+ */
+export interface PlanTableSeriesInput<K extends PlanAxisKindLiteral = never> {
+    /** The series' cells (a `Plan.tableCells` result / `PlanTableCellType` values). */
+    cells: PlanTableCellsInput<K>;
+    /** Numeral format override for THIS series — a `Format.*` spec (else the row's `format`). */
+    format?: SubtypeExprOrValue<TickFormatType>;
+    /** Default tone for the series' values; per-cell tones and the derived neg/em-dash win. */
+    tone?: SubtypeExprOrValue<PlanTableToneType> | PlanTableToneLiteral;
+    /** Semibold emphasis for this series' values (default `false`). */
+    strong?: SubtypeExprOrValue<BooleanType> | boolean;
+    /** `true` ⇒ this series feeds declared parent aggregation (default `false` — flag none and every series does). */
+    rollup?: SubtypeExprOrValue<BooleanType> | boolean;
+    /** How a bucket folds this series' cells at a coarser resolution than theirs (default `"sum"`, #824). */
+    fold?: PlanFoldInput;
+}
+/**
+ * Builds one table-row value series (see {@link Plan.table}'s `series`) —
+ * per-position style declared once, raw cells beneath it; the result carries
+ * the cells' axis kind.
+ *
+ * @typeParam K - The cells' axis kind
+ * @param input - The series configuration ({@link PlanTableSeriesInput})
+ * @returns An East expression of {@link PlanTableSeriesType}, branded with the cells' kind
+ */
+export declare function createTableSeries<K extends PlanAxisKindLiteral = never>(input: PlanTableSeriesInput<K>): PlanTableSeriesExpr<K>;
+/**
+ * The raw table-cell record — `{ at, value }`, its `at` any
+ * {@link PlanInstantLikeType} (wrapped to the axis arm by its static type).
+ */
+export type PlanRawTableCellType = StructType<{
+    at: PlanInstantLikeType;
+    value: OptionType<FloatType>;
+}>;
+/**
+ * Builds per-bucket table cells from raw values. The RENDERER prints each
+ * value through the row's `format` (a `Format.*` spec — the shared
+ * `TickFormatType`), tones negatives `neg` and renders `none` as the muted
+ * em-dash; build `PlanTableCellType` values directly for explicit `text` /
+ * `tone` overrides.
+ *
+ * @remarks
+ * The `at` of each raw cell wraps to the axis arm by its type — a
+ * `DateTimeType` field to `time`, a numeric field to `number`, a string
+ * field to `ordinal`, a {@link PlanInstantType} field as is — so a
+ * `{ at: DateTimeType, value }` dataset keeps compiling unchanged.
+ *
+ * Literal records brand the result with the kind their `at` implies
+ * ({@link PlanKindOf}); an East array is kind-erased.
+ *
+ * @typeParam A - The literal records' `at` type
+ * @param cells - The raw cells (`{ at, value }` records; `value` an `Option<Float>`)
+ * @returns An `ArrayType(PlanTableCellType)` expression, branded with the cells' kind
+ * @throws {Error} If an East array's element `at` is not an instant-typed field
+ */
+export declare function createTableCells<A extends PlanInstantInput = never>(cells: {
+    at: A;
+    value: SubtypeExprOrValue<OptionType<FloatType>>;
+}[] | SubtypeExprOrValue<ArrayType<PlanRawTableCellType>>): PlanTableCellsExpr<PlanKindOf<A>>;
+//# sourceMappingURL=builders.d.ts.map