@elaraai/east-ui 1.0.85 → 1.0.87

package/dist/src/collections/plan/builders.js

@@ -1,673 +0,0 @@
-/**
- * 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 { TickFormatType } from "../../format/types.js";
-import { IconType } from "../../display/icon/types.js";
-import { StatusValueType } from "../../feedback/status/types.js";
-import { ColorSchemeType } from "../../style/scheme.js";
-import { EventStateType } from "../../contracts/states.js";
-import { TimeResolutionType } from "../../contracts/time.js";
-import { MatrixFillType } from "../matrix/types.js";
-import { PlanAxisType, PlanInstantType, PlanPortType, PlanCellMarkerType, PlanStretchType, PlanContentAlignType, PlanContentType, PlanAnimationType, PlanEventMarkKindType, PlanHeatCellType, PlanWeightCellType, PlanSegmentType, PlanSegmentCellType, PlanHeatCellsType, PlanTableCellType, PlanTableToneType, PlanTableSeriesType, PlanLinkType, PlanRunType, PlanDecisionMarkType, PlanBucketEventType, PlanChipType, PlanEventMarkType, PlanLaneType, PlanRowIdType, PlanFoldType, PlanQuantityType, PlanHeatScaleType, PlanUiStateType, } from "./types.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 null-payload variant string shorthand against its East type. */
-export function resolveTag(v, type) {
-    const value = typeof v === "string" ? variant(v, null) : v;
-    return East.value(value, type);
-}
-/**
- * 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. */
-export function resolveIcon(icon) {
-    if (typeof icon === "string") {
-        return East.value({ prefix: "fas", name: icon, label: none, style: none }, IconType);
-    }
-    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();
-/**
- * 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);
-    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);
-    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");
-    }
-    return East.value(variant("ordinal", {
-        values: East.value(options.values, ArrayType(StringType)),
-        now: options.now !== undefined ? some(options.now) : none,
-    }), PlanAxisType);
-}
-/**
- * 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 ribbon's share and 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)) : 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)) : 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("machine-jobs", "L1", "m03")`
- * is the row series `machine-jobs` made from entry `m03` under `L1` (#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", "L1")` is the
- * `crew-block` section's header under entry `L1`; 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);
-}
-/**
- * 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}
- */
-export function createLink(input) {
-    return East.value({
-        key: input.key,
-        from: { row: input.from, run: input.fromRun },
-        to: { row: input.to, run: input.toRun },
-        quantity: input.quantity !== undefined ? some(East.value(input.quantity, PlanQuantityType)) : none,
-    }, PlanLinkType);
-}
-/**
- * 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)) : 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)) : 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