@elaraai/e3-ui 1.0.86 → 1.0.88

package/dist/src/plan/builders.js

@@ -0,0 +1,749 @@
+/**
+ * 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 { East, Expr, ArrayType, BooleanType, DateTimeType, FloatType, IntegerType, OptionType, StringType, StructType, variant, some, none, } from "@elaraai/east";
+import { EventStateType, IconType, StatusValueType, TimeResolutionType, } from "@elaraai/east-ui";
+import { ColorSchemeType, MatrixFillType, TickFormatType, refuseNonSolid, resolveTag, } from "@elaraai/east-ui/internal";
+import { PlanAxisType, PlanInstantType, PlanPortType, PlanCellMarkerType, PlanStretchType, PlanContentAlignType, PlanContentType, PlanAnimationType, PlanEventMarkKindType, PlanHeatCellType, PlanWeightCellType, PlanSegmentType, PlanSegmentCellType, PlanHeatCellsType, PlanTableCellType, PlanTableToneType, PlanTableSeriesType, PlanLinkType, PlanRunRefType, PlanRunType, PlanDecisionMarkType, PlanBucketEventType, PlanChipType, PlanEventMarkType, PlanLaneType, PlanRowIdType, PlanFoldType, PlanQuantityType, PlanHeatScaleType, PlanUiStateType, } from "./types.js";
+import { eventRefKind } from "./refs.js";
+// ============================================================================
+// Shorthand resolvers
+// ============================================================================
+/**
+ * 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 function resolvePlanEventState(state) {
+    if (typeof state !== "string")
+        return state;
+    switch (state) {
+        case "estimated": return East.value(variant("estimated", null), EventStateType);
+        case "added": return East.value(variant("proposed", variant("added", null)), EventStateType);
+        case "recommended": return East.value(variant("proposed", variant("recommended", null)), EventStateType);
+        case "removed": return East.value(variant("proposed", variant("removed", null)), EventStateType);
+        case "confirmed": return East.value(variant("confirmed", null), EventStateType);
+        case "in-progress": return East.value(variant("in-progress", null), EventStateType);
+        case "actual": return East.value(variant("actual", null), EventStateType);
+        case "rejected": return East.value(variant("rejected", null), EventStateType);
+    }
+}
+/**
+ * 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 function resolveFold(fold, fallback) {
+    return resolveTag(fold ?? fallback, PlanFoldType);
+}
+/**
+ * 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 function resolveIcon(icon, where = "Plan icon") {
+    if (typeof icon === "string") {
+        return East.value({ prefix: "fas", name: icon, label: none, style: none }, IconType);
+    }
+    refuseNonSolid(where, icon);
+    if (typeof icon.prefix === "string") {
+        return East.value({
+            prefix: icon.prefix,
+            name: icon.name,
+            label: none,
+            style: none,
+        }, IconType);
+    }
+    return icon;
+}
+// ============================================================================
+// Instants — the axis-kind sugar
+// ============================================================================
+/**
+ * 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 function resolveInstant(v, where) {
+    if (v instanceof Date)
+        return East.value(variant("time", v), PlanInstantType);
+    if (typeof v === "number")
+        return East.value(variant("number", v), PlanInstantType);
+    if (typeof v === "bigint")
+        return East.value(variant("number", Number(v)), PlanInstantType);
+    if (typeof v === "string")
+        return East.value(variant("ordinal", v), PlanInstantType);
+    if (v instanceof Expr) {
+        const tag = Expr.type(v).type;
+        switch (tag) {
+            case "DateTime": return East.value(variant("time", v), PlanInstantType);
+            case "Float": return East.value(variant("number", v), PlanInstantType);
+            case "Integer": return East.value(variant("number", v.toFloat()), PlanInstantType);
+            case "String": return East.value(variant("ordinal", v), PlanInstantType);
+            case "Variant": return East.value(v, PlanInstantType);
+            default:
+                throw new Error(`Plan: ${where} must be an instant — a Date / number / string, a DateTime / Float / ` +
+                    `Integer / String expression, or a Plan.at.* value (got a ${tag} expression)`);
+        }
+    }
+    // A plain variant VALUE (`variant("time", d)`, a decoded instant).
+    return East.value(v, 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 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"`
+     */
+    time: (v) => East.value(variant("time", v), PlanInstantType),
+    /**
+     * A `number` instant.
+     *
+     * @param v - The position (a number or `FloatType` expression)
+     * @returns A `PlanInstantType` expression with the `number` arm, branded `"number"`
+     */
+    number: (v) => East.value(variant("number", v), PlanInstantType),
+    /**
+     * An `ordinal` instant.
+     *
+     * @param v - The declared value (a string or `StringType` expression)
+     * @returns A `PlanInstantType` expression with the `ordinal` arm, branded `"ordinal"`
+     */
+    ordinal: (v) => East.value(variant("ordinal", v), PlanInstantType),
+};
+// ============================================================================
+// Axis — the three kinds
+// ============================================================================
+/**
+ * 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 const WINDOWLESS_AXES = new WeakSet();
+/**
+ * The kind of each axis value `Plan.axis` built (#1191) — what a Plan reads to
+ * refuse event kinds on a number or ordinal axis at build. An axis held in a
+ * variable is not the value recorded here, so its Plan checks it as it is
+ * evaluated instead.
+ */
+const AXIS_KINDS = new WeakMap();
+/**
+ * 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 function axisKindOf(axis) {
+    return typeof axis === "object" && axis !== null ? AXIS_KINDS.get(axis) : 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 function createTimeAxis(options) {
+    const axis = East.value(variant("time", {
+        window: options.window !== undefined
+            ? some({ min: options.window.min, max: options.window.max })
+            : none,
+        resolution: resolveTag(options.resolution, TimeResolutionType),
+        resolutions: (options.resolutions ?? []).map(r => resolveTag(r, TimeResolutionType)),
+        now: options.now !== undefined ? some(options.now) : none,
+        format: options.format !== undefined ? some(options.format) : none,
+    }), PlanAxisType);
+    if (options.window === undefined)
+        WINDOWLESS_AXES.add(axis);
+    AXIS_KINDS.set(axis, "time");
+    return axis;
+}
+/**
+ * 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 function createNumberAxis(options) {
+    if (typeof options.step === "number" && !(options.step > 0)) {
+        throw new Error(`Plan.axis.number: \`step\` must be > 0 (got ${options.step}) — it is the bucket width`);
+    }
+    const axis = East.value(variant("number", {
+        window: options.window !== undefined
+            ? some({ min: options.window.min, max: options.window.max })
+            : none,
+        step: options.step,
+        now: options.now !== undefined ? some(options.now) : none,
+        format: options.format !== undefined ? some(options.format) : none,
+    }), PlanAxisType);
+    if (options.window === undefined)
+        WINDOWLESS_AXES.add(axis);
+    AXIS_KINDS.set(axis, "number");
+    return axis;
+}
+/**
+ * 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 function createOrdinalAxis(options) {
+    if (Array.isArray(options.values) && options.values.length === 0) {
+        throw new Error("Plan.axis.ordinal: `values` must list at least one value — the list is the axis");
+    }
+    const axis = East.value(variant("ordinal", {
+        values: East.value(options.values, ArrayType(StringType)),
+        now: options.now !== undefined ? some(options.now) : none,
+    }), PlanAxisType);
+    AXIS_KINDS.set(axis, "ordinal");
+    return axis;
+}
+/**
+ * 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 const createAxis = Object.assign(function axis(options) { return createTimeAxis(options); }, { time: createTimeAxis, number: createNumberAxis, ordinal: createOrdinalAxis });
+/**
+ * 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 function createQuantity(value, options) {
+    return East.value({
+        value,
+        unit: options?.unit !== undefined ? some(options.unit) : none,
+        format: options?.format !== undefined ? some(East.value(options.format, TickFormatType)) : none,
+        text: options?.text !== undefined ? some(options.text) : none,
+    }, PlanQuantityType);
+}
+/**
+ * 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 function createRun(input) {
+    return East.value({
+        key: input.key,
+        start: resolveInstant(input.start, "run start"),
+        end: resolveInstant(input.end, "run end"),
+        label: input.label,
+        quantity: input.quantity !== undefined ? some(East.value(input.quantity, PlanQuantityType)) : none,
+        state: resolvePlanEventState(input.state),
+        status: input.status !== undefined ? some(resolveTag(input.status, StatusValueType)) : none,
+        moved: input.moved !== undefined ? some(typeof input.moved === "number" ? BigInt(input.moved) : input.moved) : none,
+        icon: input.icon !== undefined ? some(resolveIcon(input.icon, "Plan.run icon")) : none,
+    }, PlanRunType);
+}
+/**
+ * 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 function createDecision(input) {
+    return East.value({
+        key: input.key,
+        at: resolveInstant(input.at, "decision at"),
+        applied: input.applied,
+    }, PlanDecisionMarkType);
+}
+/**
+ * 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 function createPort(input) {
+    return East.value({
+        at: resolveInstant(input.at, "port at"),
+        label: input.label !== undefined ? some(input.label) : none,
+    }, PlanPortType);
+}
+/**
+ * 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 function createBucketEvent(input) {
+    const content = input.content !== undefined
+        ? some(East.value({
+            horizontal: input.content.horizontal !== undefined ? some(resolveTag(input.content.horizontal, PlanContentAlignType)) : none,
+            vertical: input.content.vertical !== undefined ? some(resolveTag(input.content.vertical, PlanContentAlignType)) : none,
+        }, PlanContentType))
+        : none;
+    return East.value({
+        key: input.key,
+        at: resolveInstant(input.at, "event at"),
+        lane: input.lane !== undefined ? some(input.lane) : none,
+        label: input.label !== undefined ? some(input.label) : none,
+        icon: input.icon !== undefined ? some(resolveIcon(input.icon, "Plan.event icon")) : none,
+        state: resolvePlanEventState(input.state),
+        tone: input.tone !== undefined ? some(resolveTag(input.tone, StatusValueType)) : none,
+        color: input.color !== undefined ? some(input.color) : none,
+        colorPalette: input.colorPalette !== undefined ? some(resolveTag(input.colorPalette, ColorSchemeType)) : none,
+        stretch: input.stretch !== undefined ? some(resolveTag(input.stretch, PlanStretchType)) : none,
+        content,
+        animation: input.animation !== undefined ? some(resolveTag(input.animation, PlanAnimationType)) : none,
+    }, PlanBucketEventType);
+}
+/**
+ * Builds one bucket-row lane from a flat input.
+ *
+ * @param input - The lane configuration ({@link PlanLaneInput})
+ * @returns An East expression of {@link PlanLaneType}
+ */
+export function createLane(input) {
+    return East.value({
+        key: input.key,
+        label: input.label !== undefined ? some(input.label) : none,
+    }, 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 function createRef(series, ...path) {
+    return East.value(variant("entry", { series, path }), 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 function createSectionRef(series, ...path) {
+    return East.value(variant("section", { series, path }), 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 function createUiState(init) {
+    const ids = (list) => East.value((list ?? []), ArrayType(PlanRowIdType));
+    return East.value({
+        selected: init?.selected !== undefined ? some(East.value(init.selected, PlanRowIdType)) : none,
+        collapsed: ids(init?.collapsed),
+        expanded: ids(init?.expanded),
+        charts: ids(init?.charts),
+        focus: init?.focus !== undefined ? some(East.value(init.focus, PlanRowIdType)) : none,
+    }, PlanUiStateType);
+}
+/**
+ * The event kinds each link `Plan.link` built names at its ends — none for a
+ * link between rows — by the value it returned (#1191). A link whose event end
+ * was held in a variable is not recorded: its kind is not known here.
+ */
+const LINK_EVENT_KINDS = new WeakMap();
+/**
+ * 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 function linkEventKinds(link) {
+    return typeof link === "object" && link !== null ? LINK_EVENT_KINDS.get(link) : undefined;
+}
+/**
+ * Whether a link end is an event (`Plan.eventRef`'s run ref, a struct) rather
+ * than a row's id (a variant).
+ *
+ * @param end - The end
+ * @returns `true` for an event
+ */
+function isEventEnd(end) {
+    return end instanceof Expr && Expr.type(end).type === "Struct";
+}
+/**
+ * One link end on the wire: a row's id with its run, or an event's ref as it is.
+ *
+ * @param end - The end — a row's id, or an event (`Plan.eventRef`)
+ * @param run - The run on the row
+ * @param name - `"from"` or `"to"`, for the message
+ * @returns The run ref
+ * @throws {Error} When a row's end has no run, or an event's end names one
+ */
+function linkEnd(end, run, name) {
+    if (isEventEnd(end)) {
+        if (run !== undefined) {
+            throw new Error(`Plan.link: \`${name}\` is an event, which names its own run — leave out \`${name}Run\``);
+        }
+        return end;
+    }
+    if (run === undefined) {
+        throw new Error(`Plan.link: \`${name}\` is a row's id — name the run on it with \`${name}Run\`, or name an event with Plan.eventRef(kind, key)`);
+    }
+    return { row: end, run };
+}
+/**
+ * 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 function createLink(input) {
+    const link = East.value({
+        key: input.key,
+        from: linkEnd(input.from, input.fromRun, "from"),
+        to: linkEnd(input.to, input.toRun, "to"),
+        quantity: input.quantity !== undefined ? some(East.value(input.quantity, PlanQuantityType)) : none,
+    }, PlanLinkType);
+    // The kinds its event ends name, when each is `Plan.eventRef`'s own value.
+    const kinds = [input.from, input.to].filter(isEventEnd).map(eventRefKind);
+    if (kinds.every((k) => k !== undefined))
+        LINK_EVENT_KINDS.set(link, kinds);
+    return link;
+}
+/**
+ * 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 function createCellMarker(input) {
+    return East.value({
+        at: resolveInstant(input.at, "marker at"),
+        lane: input.lane !== undefined ? some(input.lane) : none,
+        status: resolveTag(input.status ?? "danger", StatusValueType),
+        message: input.message,
+    }, PlanCellMarkerType);
+}
+/**
+ * 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 function createChip(input) {
+    return East.value({
+        key: input.key,
+        from: resolveInstant(input.from, "chip from"),
+        to: resolveInstant(input.to, "chip to"),
+        label: input.label,
+        state: resolvePlanEventState(input.state),
+        icon: input.icon !== undefined ? some(resolveIcon(input.icon, "Plan.chip icon")) : none,
+    }, PlanChipType);
+}
+/**
+ * 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 function createEventMark(input) {
+    return East.value({
+        key: input.key,
+        at: resolveInstant(input.at, "mark at"),
+        kind: typeof input.kind === "string" ? East.value(variant(input.kind, null), PlanEventMarkKindType) : input.kind,
+        icon: input.icon !== undefined ? some(resolveIcon(input.icon, "Plan.mark icon")) : none,
+        label: input.label !== undefined ? some(input.label) : none,
+    }, PlanEventMarkType);
+}
+/** The `Plan.markKind` builders — non-null mark kinds. */
+export const markKind = {
+    /**
+     * A decision diamond mark — ◇ pending / ◆ applied.
+     *
+     * @param applied - `true` fills the diamond
+     * @returns A `PlanEventMarkKindType` expression with the `decision` arm
+     */
+    decision: (applied) => East.value(variant("decision", { applied }), PlanEventMarkKindType),
+};
+/**
+ * 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 function createHeatScale(input) {
+    return East.value({
+        min: input?.min !== undefined ? some(input.min) : none,
+        max: input?.max !== undefined ? some(input.max) : none,
+        warnAt: input?.warnAt !== undefined ? some(input.warnAt) : none,
+    }, PlanHeatScaleType);
+}
+/** The declared `format`, as the arm's option. */
+function formatOpt(format) {
+    return format !== undefined
+        ? East.value(some(East.value(format, TickFormatType)), OptionType(TickFormatType))
+        : East.value(none, OptionType(TickFormatType));
+}
+/**
+ * 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 function createHeatCells(cells, options) {
+    return East.value(variant("heat", {
+        cells: East.value(cells, ArrayType(PlanHeatCellType)),
+        scale: createHeatScale(options),
+        fold: resolveFold(options?.fold, "mean"),
+        format: formatOpt(options?.format),
+    }), PlanHeatCellsType);
+}
+/**
+ * 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 function createWeightCells(cells, options) {
+    return East.value(variant("weight", {
+        cells: East.value(cells, ArrayType(PlanWeightCellType)),
+        fold: resolveFold(options?.fold, "mean"),
+        format: formatOpt(options?.format),
+    }), PlanHeatCellsType);
+}
+/**
+ * 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 function createSegmentCells(cells, options) {
+    return East.value(variant("segments", {
+        cells: East.value(cells, ArrayType(PlanSegmentCellType)),
+        fold: resolveFold(options?.fold, "sum"),
+        format: formatOpt(options?.format),
+    }), PlanHeatCellsType);
+}
+/**
+ * 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 function createSegment(input) {
+    return East.value({
+        fill: resolveTag(input.fill, MatrixFillType),
+        weight: input.weight,
+        label: input.label !== undefined ? some(input.label) : none,
+    }, PlanSegmentType);
+}
+/**
+ * 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 function createTableSeries(input) {
+    return East.value({
+        cells: East.value(input.cells, ArrayType(PlanTableCellType)),
+        format: input.format !== undefined ? some(East.value(input.format, TickFormatType)) : none,
+        tone: input.tone !== undefined ? some(resolveTag(input.tone, PlanTableToneType)) : none,
+        strong: input.strong ?? false,
+        rollup: input.rollup ?? false,
+        fold: resolveFold(input.fold, "sum"),
+    }, PlanTableSeriesType);
+}
+/**
+ * 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 function createTableCells(cells) {
+    if (Array.isArray(cells)) {
+        // Each element is a literal record or a struct expression; both
+        // expose `at` / `value` (a struct expression's field accessors carry
+        // the field's static type, which is what `resolveInstant` reads).
+        const built = cells.map((c) => {
+            const rec = c;
+            return East.value({
+                at: resolveInstant(rec.at, "tableCells at"),
+                value: East.value(rec.value, OptionType(FloatType)),
+                text: none,
+                tone: none,
+            }, PlanTableCellType);
+        });
+        return East.value(built, ArrayType(PlanTableCellType));
+    }
+    // An East array — wrap `at` by its STATIC element type, once for the map.
+    const raw = cells;
+    const elem = Expr.type(raw).value;
+    const atTag = (elem.fields.at).type;
+    const wrap = (v) => {
+        switch (atTag) {
+            case "DateTime": return East.value(variant("time", v), PlanInstantType);
+            case "Float": return East.value(variant("number", v), PlanInstantType);
+            case "Integer": return East.value(variant("number", v.toFloat()), PlanInstantType);
+            case "String": return East.value(variant("ordinal", v), PlanInstantType);
+            case "Variant": return East.value(v, PlanInstantType);
+            default:
+                throw new Error("Plan.tableCells: each cell's `at` must be an instant-typed field (DateTime / Float / " +
+                    `Integer / String / Plan.Types.Instant) — got ${atTag}`);
+        }
+    };
+    return raw.map((_$, c) => East.value({
+        at: wrap(c.at),
+        value: c.value,
+        text: none,
+        tone: none,
+    }, PlanTableCellType));
+}
+//# sourceMappingURL=builders.js.map