@elaraai/e3-ui 1.0.86 → 1.0.87

package/dist/src/sheet/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../src/sheet/fields.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACH,SAAS,EACT,QAAQ,EAGR,YAAY,EACZ,UAAU,EACV,UAAU,EACV,UAAU,EAMV,KAAK,QAAQ,EAEhB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAmC,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAOtG;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGzB,CAAC;AAEH,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAEnD;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMxB,CAAC;AAEH,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGzB,CAAC;AAEH,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAuKnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACtB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EACpD,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EACzD,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC7B,QAAQ,CAAC,cAAc,CAAC,CAwB1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,qDAAS,CAAC"}

package/dist/src/sheet/fields.js

@@ -0,0 +1,280 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The Sheet's inspector forms (#1188, `Sheet Builder Spec.md` §5.3,
+ * SB10): every field of a row — a grouped sheet's line — and of a group,
+ * resolved through `Fields`, each column's kind its field's default hint and
+ * an explicit hint (`fields`, `groupFields`) winning.
+ *
+ * | The field's column | Its editor |
+ * |---|---|
+ * | `text` | Text |
+ * | `custom` | Text — the column's own `print` shows it, its `parse` reads it |
+ * | `date` | The date field, at the row's date level (the renderer sets its precision) |
+ * | `quantity`, `integer` | The number field — a quantity in the driver's unit |
+ * | `lookup`, `reference`, `enum` | A select over the register's members (`reference` of the register) |
+ * | `set`, `link` | Read only here: the renderer draws the members, and edits them in the grid |
+ * | `stamped`, a `value` projection, `editable: false` | Read only |
+ * | No column | By its type, as `Fields.specs` resolves it |
+ *
+ * A field with a column is read and written through it: its spec names the
+ * column (or the band cell, on a group), and an edit in the inspector is the
+ * cell's write, as typing in it is (SB52). A field with none is the draft's
+ * own. A hint may label a column's field, give it a help line, make it read
+ * only or hide it; an editor hint must fit the field's type, and a read-only
+ * column takes none. Each form carries the cells a patch of its struct sets
+ * (`encode`) — the projection the copilot's proposals and the templates go
+ * through — so a whole-row write (a custom inspector's `update`, SB58) lands
+ * on the cells as the grid would write them.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, BlobType, East, EastTypeType, FunctionType, OptionType, StringType, StructType, none, some, toEastTypeValue, variant, } from "@elaraai/east";
+import { FIELD_HINT, FieldSpecType, Fields, fieldSpecs, spellOut } from "@elaraai/east-ui/internal";
+import { SheetCellsType, buildPatchCells } from "./bridge.js";
+import { SheetPatchTypeFor } from "./types.js";
+// ============================================================================
+// The wire
+// ============================================================================
+/**
+ * One field of an inspector form on the wire.
+ *
+ * @property spec - What the form draws — `Fields`' spec
+ * @property column - The column it is read and written through, by key (on a group, the band cell's key); `none` for a field the draft holds alone
+ */
+export const SheetFieldType = StructType({
+    spec: FieldSpecType,
+    column: OptionType(StringType),
+});
+/**
+ * One inspector form on the wire: the struct it edits, its fields in the
+ * form's order, and the cells a patch of the struct sets.
+ *
+ * @property type - The struct the form edits — the row (a grouped sheet's line), or the group
+ * @property fields - Its fields: the hinted first, in hint order, then the rest in declared order
+ * @property columns - The struct's fields its editable columns write — a column's own, a link's other half — whatever the form shows: a whole-row write sets these through `encode`
+ * @property readonly - The struct's fields its read-only columns show — a stamped code, a `value` projection, a column `editable: false` — which a whole-row write leaves as they are, as the grid does; every other field a whole-row write sets on the draft
+ * @property encode - A `Sheet.Types.Patch` of the struct, encoded (beast2) → the cells it sets through the sheet's editable columns (or the band's cells)
+ */
+export const SheetFormType = StructType({
+    type: EastTypeType,
+    fields: ArrayType(SheetFieldType),
+    columns: ArrayType(StringType),
+    readonly: ArrayType(StringType),
+    encode: FunctionType([BlobType], SheetCellsType),
+});
+/**
+ * The inspector's forms on the wire.
+ *
+ * @property row - A row's — a grouped sheet's line's
+ * @property group - A group's own fields, on a grouped sheet
+ */
+export const SheetFormsType = StructType({
+    row: SheetFormType,
+    group: OptionType(SheetFormType),
+});
+/** Whether a value is a hint rather than a nested struct's hints. */
+function isHint(value) {
+    return value !== null && typeof value === "object" && FIELD_HINT in value;
+}
+/** Why a column's field takes no editor hint, or `undefined` when it does. */
+function readOnlyReason(meta) {
+    if (meta.derived !== undefined)
+        return "is a `value` projection, a derived read";
+    if (meta.kind === "stamped")
+        return "is stamped — a code an upstream system owns";
+    if (meta.kind === "set" || meta.kind === "link")
+        return `is a ${meta.kind} column, whose members are edited in the sheet`;
+    if (meta.kind === "custom")
+        return "is a custom column, read through its own `parse`";
+    if (!meta.editable)
+        return "is read only (`editable: false`)";
+    return undefined;
+}
+/** A hint's `reference` editor, checked against the sheet's registers: the keyed set a select lists is one of them. */
+function checkReference(editor, field, registers) {
+    if (editor.type !== "reference" || registers.has(editor.value.of))
+        return;
+    throw new Error(`Sheet: \`${field}\` is a reference to "${editor.value.of}", which is not one of the sheet's registers (${[...registers].join(", ") || "none declared"}) — declare it in \`registers\`, or name one of them`);
+}
+/** A column's field's editor with no hint: its kind's. */
+function kindEditor(meta) {
+    if (meta.derived !== undefined || !meta.editable)
+        return variant("readonly", null);
+    switch (meta.kind) {
+        case "text":
+        case "custom": return variant("text", { placeholder: none });
+        case "date": return variant("datetime", { precision: none });
+        case "quantity":
+        case "integer": return variant("number", { unit: none, step: none, min: none, max: none });
+        case "lookup":
+        case "reference":
+        case "enum": return variant("reference", { of: meta.register });
+        default: return variant("readonly", null);
+    }
+}
+/**
+ * The spec of a field read and written through a column — its kind's editor,
+ * or its hint's; the column's header (else the field's name spelled out) and
+ * its second line its label and help, unless the hint names its own.
+ */
+function columnField(name, meta, hint, where, registers) {
+    const kind = hint?.[FIELD_HINT];
+    let editor;
+    let type;
+    if (meta.derived !== undefined) {
+        // A projection's value is the cell's, never the field's.
+        type = meta.derivedOptional === true ? OptionType(meta.payloadType) : meta.payloadType;
+    }
+    else if (meta.kind === "custom") {
+        // A custom column's text: shown by its print, read by its parse.
+        type = meta.optional ? OptionType(StringType) : StringType;
+    }
+    else {
+        type = meta.fieldType;
+    }
+    if (kind === undefined || kind === "readonly") {
+        editor = kind === "readonly" ? variant("readonly", null) : kindEditor(meta);
+    }
+    else {
+        const reason = readOnlyReason(meta);
+        if (reason !== undefined) {
+            throw new Error(`Sheet: \`${where}.${name}\` gives its field an editor, but its column ${reason} — hint it Sheet.field.readonly() or Sheet.field.hidden(), or give it a label or help alone`);
+        }
+        // The hint's editor, checked against the field's type as Fields checks it, and a select's set against the registers.
+        editor = fieldSpecs(StructType({ [name]: meta.fieldType }), { [name]: hint })[0].editor;
+        checkReference(editor, `${where}.${name}`, registers);
+    }
+    return East.value({
+        spec: {
+            path: [name],
+            // The hint's label, else the column's header, else the field's name spelled out.
+            label: hint?.label ?? meta.config.header ?? spellOut(name),
+            help: hint?.help !== undefined ? some(hint.help) : meta.config.sub !== undefined ? some(meta.config.sub) : none,
+            group: none,
+            type: toEastTypeValue(type),
+            optional: type.type === "Variant" && Object.keys(type.cases).length === 2 && "some" in type.cases && "none" in type.cases,
+            editor,
+        },
+        column: some(meta.key),
+    }, SheetFieldType);
+}
+/**
+ * One inspector form: the struct's fields, each through its column or by its
+ * type, in the form's order.
+ *
+ * @param struct - The struct the form edits
+ * @param metas - The columns its fields are read through, by field
+ * @param hints - The author's hints, by field
+ * @param leave - The fields the form leaves out: an identity field, a group's lines field
+ * @param where - The prop the hints came from, for a refusal (`fields`, `groupFields`)
+ * @param registers - The sheet's registers, by name: what a `reference` hint may name
+ * @returns The form's fields
+ * @throws Error naming the field: a hint for a field the struct does not have, one that does not fit it, or a reference to a register the sheet does not declare
+ */
+function formFields(struct, metas, hints, leave, where, registers) {
+    const fields = struct.fields;
+    // A link column's other half is written through that column, never on its own.
+    const halves = new Set([...metas.values()].flatMap((m) => (m.otherField !== undefined ? [m.otherField] : [])));
+    for (const name of Object.keys(hints)) {
+        if (!(name in fields)) {
+            throw new Error(`Sheet: \`${where}\` names "${name}", which is not a field of ${where === "groupFields" ? "the group type" : "the row type"} (${Object.keys(fields).join(", ")})`);
+        }
+        if (leave.has(name) || halves.has(name)) {
+            throw new Error(`Sheet: \`${where}\` names "${name}", which the inspector does not show as a field of its own — ${halves.has(name) ? "it is a link column's other half, shown with that column" : "it is the row's identity, or the group's rows"}`);
+        }
+    }
+    const order = [...Object.keys(hints), ...Object.keys(fields).filter((name) => !(name in hints))];
+    const out = [];
+    for (const name of order) {
+        if (leave.has(name) || halves.has(name))
+            continue;
+        const hint = hints[name];
+        if (isHint(hint) && hint[FIELD_HINT] === "hidden")
+            continue;
+        const meta = metas.get(name);
+        if (meta !== undefined) {
+            if (hint !== undefined && !isHint(hint)) {
+                throw new Error(`Sheet: \`${where}.${name}\` is shown through its column — its hint is one of Sheet.field's, never a hint per nested field`);
+            }
+            out.push(columnField(name, meta, hint, where, registers));
+            continue;
+        }
+        // No column: the field by its type, as Fields resolves it — a nested struct's fields under its name.
+        const others = Object.keys(fields).filter((f) => f !== name);
+        for (const spec of fieldSpecs(struct, (hint === undefined ? {} : { [name]: hint }), others)) {
+            checkReference(spec.editor, `${where}.${spec.path.join(".")}`, registers);
+            out.push(East.value({ spec, column: none }, SheetFieldType));
+        }
+    }
+    return out;
+}
+/**
+ * The fields a whole-row write sets through the columns — the fields `encode`
+ * writes: an editable column's own and a link's other half — and the fields
+ * it leaves, under the read-only columns.
+ */
+function columnFields(metas) {
+    const writes = (m) => m.editable && m.derived === undefined;
+    const columns = new Set(metas.filter(writes).flatMap((m) => (m.otherField !== undefined ? [m.field, m.otherField] : [m.field])));
+    const readonly = new Set(metas.filter((m) => !writes(m) && !columns.has(m.field)).map((m) => m.field));
+    return { columns: [...columns], readonly: [...readonly] };
+}
+/** A form's `encode`: a patch of the struct, as bytes, through the cells it sets. */
+function encodeOf(patchType, cells) {
+    return East.function([BlobType], SheetCellsType, ($, bytes) => {
+        const encode = $.const(cells);
+        const patch = $.const(bytes.decodeBeast(patchType, "v2"));
+        return encode(patch);
+    });
+}
+/**
+ * Builds the inspector's forms (SB10): a row's (a grouped sheet's line's) and,
+ * on a grouped sheet, a group's.
+ *
+ * @param bridge - The sheet's bridge, as its root compiled it
+ * @param metas - The declared columns, described against the row (or line) type
+ * @param hints - `fields`: the author's hints for the row's fields
+ * @param groupHints - `groupFields`: the author's hints for the group's own fields
+ * @param idField - The rows' identity field, which the form leaves to the header
+ * @param registers - The sheet's registers' names, the driver's among them: what a `reference` hint may name
+ * @returns The forms on the wire
+ * @throws Error naming the prop: `groupFields` on a flat sheet, and each refusal of a hint
+ * @internal
+ */
+export function buildForms(bridge, metas, hints, groupHints, idField, registers) {
+    const named = new Set(registers);
+    const groupHalf = bridge.group;
+    if (groupHalf === undefined && groupHints !== undefined) {
+        throw new Error("Sheet: `groupFields` hints a group's fields, and this sheet declares no group — pass `group={Sheet.group(…)}`, or hint the rows with `fields`");
+    }
+    // A row's identity is its header's, never a field to edit: a flat row's, and a loose row's line beside the groups (#846).
+    const lineLeave = new Set(idField !== undefined && idField in bridge.lineType.fields ? [idField] : []);
+    const row = East.value({
+        type: toEastTypeValue(bridge.lineType),
+        fields: formFields(bridge.lineType, new Map(metas.map((m) => [m.field, m])), hints ?? {}, lineLeave, "fields", named),
+        ...columnFields(metas),
+        encode: encodeOf(bridge.patchType, bridge.encodePatch),
+    }, SheetFormType);
+    if (groupHalf === undefined)
+        return East.value({ row, group: none }, SheetFormsType);
+    const groupType = groupHalf.groupType;
+    const groupLeave = new Set([groupHalf.linesField, ...(idField !== undefined && idField in groupType.fields ? [idField] : [])]);
+    const group = East.value({
+        type: toEastTypeValue(groupType),
+        fields: formFields(groupType, new Map(groupHalf.cellMetas.map((m) => [m.field, m])), groupHints ?? {}, groupLeave, "groupFields", named),
+        ...columnFields(groupHalf.cellMetas),
+        encode: encodeOf(SheetPatchTypeFor(groupType), buildPatchCells(groupType, groupHalf.cellMetas, {})),
+    }, SheetFormType);
+    return East.value({ row, group: some(group) }, SheetFormsType);
+}
+/**
+ * `Sheet.field` — the inspector's hints, `Fields`' own (#1147): a label, a
+ * help line, an editor for a field the inspector shows by its type, a field
+ * read only or hidden. A column's field takes a label, a help line, read only
+ * or hidden, and an editor that fits its type when its column is written.
+ */
+export const SheetField = Fields;
+//# sourceMappingURL=fields.js.map

package/dist/src/sheet/fields.js.map

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

package/dist/src/sheet/group.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `Sheet.group` and `Sheet.group.cell.*` — grouped rows (#740): the group is
+ * the row, its lines live in one `Array<L>` field of its own type, and the
+ * band a group draws above its lines shows the group's own fields under the
+ * line columns.
+ *
+ * `Sheet.group(P, "lines", { title, sub?, cells?, folded?, noun? })` names
+ * the lines field and the band; each `cells` entry is a group field declared
+ * over the group's row with `Sheet.group.cell.<kind>(P, "field", cfg)` — the
+ * same builders as `Sheet.column.<kind>` minus the header, keyed in `cells`
+ * by the LINE column it sits under. A band cell edits like any cell: the
+ * edit joins the sheet's batch and reaches the host through `onUpdate` or
+ * `onApply`. `editable: false` and a `value:` projection are read-only.
+ *
+ * The builders only CAPTURE; the root describes each cell against the group's
+ * row type and reifies the accessors (`root.ts`, `bridge.ts`).
+ *
+ * @packageDocumentation
+ */
+import type { EastType, ExprType, SubtypeExprOrValue, BooleanType, DateTimeType, FloatType, IntegerType, OptionType, StringType, StructType } from "@elaraai/east";
+import type { TickFormatType } from "@elaraai/east-ui/internal";
+import type { SheetColumnKindLiteral, SheetLinesField, SheetLineOf } from "./types.js";
+import type { SheetAnyColumnConfig, SheetFieldKey } from "./columns.js";
+/**
+ * A built band cell — what a `Sheet.group.cell.*` builder returns and the
+ * `cells` map holds.
+ *
+ * @typeParam P - The group's row type
+ */
+export interface SheetGroupCell<P extends StructType> {
+    /** The cell's kind. */
+    readonly kind: SheetColumnKindLiteral;
+    /** The group field the cell reads and writes. */
+    readonly field: SheetFieldKey<P>;
+    /** The author's config, as given. @internal */
+    readonly config: SheetAnyColumnConfig;
+    /** The register the cell resolves against. @internal */
+    readonly register?: string;
+    /** Phantom — the row type. @internal */
+    readonly __row?: (r: P) => void;
+}
+/** The keys of a group row whose field is `A` or its `Option`. */
+export type SheetFieldOf<P extends StructType, A extends EastType> = {
+    [K in SheetFieldKey<P>]: P["fields"][K] extends A | OptionType<A> ? K : never;
+}[SheetFieldKey<P>];
+/**
+ * What every band cell takes.
+ *
+ * @property editable - `false` makes the cell read-only
+ */
+export interface SheetGroupCellBaseConfig {
+    /** `false` makes the cell read-only. */
+    editable?: boolean;
+}
+/**
+ * A derived read — the cell displays the projection over the group row and
+ * is read-only; it may reach into the group's lines.
+ *
+ * @typeParam P - The group's row type
+ * @typeParam T - The kind's payload type
+ */
+export interface SheetGroupValueConfig<P extends StructType, T extends EastType> {
+    /** The projection over the group row. */
+    value: (row: ExprType<P>) => SubtypeExprOrValue<T | OptionType<T>>;
+}
+/** Config for `Sheet.group.cell.date`. */
+export interface SheetGroupDateConfig extends SheetGroupCellBaseConfig {
+    /** A display pattern (East date tokens). */
+    format?: SubtypeExprOrValue<StringType>;
+}
+/**
+ * Config for `Sheet.group.cell.quantity`. A band has no driver member, so a
+ * band quantity carries no unit; the line column's unit is the driver's.
+ */
+export interface SheetGroupQuantityConfig extends SheetGroupCellBaseConfig {
+    /** A display format. */
+    format?: SubtypeExprOrValue<TickFormatType>;
+}
+/** Config for `Sheet.group.cell.stamped`. */
+export interface SheetGroupStampedConfig {
+    /** The owning system. */
+    owner?: SubtypeExprOrValue<StringType>;
+}
+/** A text band cell — `Sheet.group.cell.text(P, "field", cfg)` on a `String` / `Option<String>` field, or a `value:` projection on any field. */
+export declare function text<P extends StructType>(groupType: P, field: SheetFieldKey<P>, config: SheetGroupCellBaseConfig & SheetGroupValueConfig<P, StringType>): SheetGroupCell<P>;
+export declare function text<P extends StructType>(groupType: P, field: SheetFieldOf<P, StringType>, config?: SheetGroupCellBaseConfig): SheetGroupCell<P>;
+/** A date band cell — `Sheet.group.cell.date(P, "field", cfg)` on a `DateTime` / `Option<DateTime>` field. */
+export declare function date<P extends StructType>(groupType: P, field: SheetFieldKey<P>, config: SheetGroupDateConfig & SheetGroupValueConfig<P, DateTimeType>): SheetGroupCell<P>;
+export declare function date<P extends StructType>(groupType: P, field: SheetFieldOf<P, DateTimeType>, config?: SheetGroupDateConfig): SheetGroupCell<P>;
+/** A quantity band cell — `Sheet.group.cell.quantity(P, "field", cfg)` on a `Float` / `Option<Float>` field, or a `value:` projection (a total over the lines, say). */
+export declare function quantity<P extends StructType>(groupType: P, field: SheetFieldKey<P>, config: SheetGroupQuantityConfig & SheetGroupValueConfig<P, FloatType>): SheetGroupCell<P>;
+export declare function quantity<P extends StructType>(groupType: P, field: SheetFieldOf<P, FloatType>, config?: SheetGroupQuantityConfig): SheetGroupCell<P>;
+/** An integer band cell — `Sheet.group.cell.integer(P, "field", cfg)` on an `Integer` / `Option<Integer>` field. */
+export declare function integer<P extends StructType>(groupType: P, field: SheetFieldKey<P>, config: SheetGroupCellBaseConfig & SheetGroupValueConfig<P, IntegerType>): SheetGroupCell<P>;
+export declare function integer<P extends StructType>(groupType: P, field: SheetFieldOf<P, IntegerType>, config?: SheetGroupCellBaseConfig): SheetGroupCell<P>;
+/** A reference band cell — `Sheet.group.cell.reference(P, register, "field", cfg)`: a lookup over a flat member list, on a `String` / `Option<String>` field. */
+export declare function reference<P extends StructType>(_groupType: P, register: string, field: SheetFieldOf<P, StringType>, config?: SheetGroupCellBaseConfig): SheetGroupCell<P>;
+/** An enum band cell — `Sheet.group.cell.enum(P, register, "field", cfg)`: an upper-cased register word with its valence dot, on a `String` / `Option<String>` field. */
+export declare function enumCell<P extends StructType>(_groupType: P, register: string, field: SheetFieldOf<P, StringType>, config?: SheetGroupCellBaseConfig): SheetGroupCell<P>;
+/** A stamped band cell — `Sheet.group.cell.stamped(P, "field", cfg)`: a read-only code an upstream system owns, on a `String` / `Option<String>` field. */
+export declare function stamped<P extends StructType>(_groupType: P, field: SheetFieldOf<P, StringType>, config?: SheetGroupStampedConfig): SheetGroupCell<P>;
+/**
+ * What `Sheet.group(P, "lines", …)` takes.
+ *
+ * @typeParam P - The group's row type
+ * @typeParam L - The line type the lines field holds
+ * @property title - The band's title — a `String` field of the group row; ⏎ / F2 on the band renames it
+ * @property sub - The band's eyebrow — an accessor over the group row, display only
+ * @property cells - Band cells keyed by the LINE column they sit under
+ * @property folded - Whether a group opens folded — an accessor over the group row
+ * @property noun - The word the renderer prints for a group — fold-all, the footer count, hints, the new-group button (#844); omitted, the renderer's own word in the viewer's language (`"group"` / `"groups"` in English, #861)
+ */
+export interface SheetGroupConfig<P extends StructType, L extends StructType = StructType> {
+    /** The band's title — a `String` field of the group row. */
+    title: SheetFieldOf<P, StringType>;
+    /** The band's eyebrow — display only. */
+    sub?: (row: ExprType<P>) => SubtypeExprOrValue<StringType>;
+    /** Band cells keyed by the line column they sit under. */
+    cells?: {
+        [K in SheetFieldKey<L>]?: SheetGroupCell<P>;
+    };
+    /** Whether a group opens folded. */
+    folded?: (row: ExprType<P>) => SubtypeExprOrValue<BooleanType>;
+    /** The word the renderer prints for a group. */
+    noun?: {
+        /** One group (`"order"`). */
+        singular: SubtypeExprOrValue<StringType>;
+        /** Several (`"orders"`). */
+        plural: SubtypeExprOrValue<StringType>;
+    };
+}
+/**
+ * A built group declaration — what `Sheet.group(…)` returns and the `group`
+ * prop takes.
+ *
+ * @typeParam P - The group's row type
+ * @typeParam F - The lines field
+ */
+export interface SheetGroupValue<P extends StructType, F extends string> {
+    /** The group's row type. */
+    readonly rowType: P;
+    /** The field holding the lines. */
+    readonly lines: F;
+    /** The author's config, as given. @internal */
+    readonly config: SheetGroupConfig<P, StructType>;
+}
+/**
+ * Declares grouped rows — `Sheet.group(P, "lines", { title, sub?, cells?, folded?, noun? })`
+ * (#740): the group is the row, `lines` names the `Array<Line>` field
+ * holding its lines, and the band draws the title, the eyebrow and the
+ * `cells` under their line columns.
+ *
+ * @typeParam P - The group's row type
+ * @typeParam F - The lines field — an `Array<Line>` field of `P`
+ * @param rowType - The group's row type value
+ * @param lines - The lines field
+ * @param config - The band ({@link SheetGroupConfig})
+ * @returns The declaration the `group` prop takes
+ */
+export declare function createGroup<P extends StructType, F extends SheetLinesField<P>>(rowType: P, lines: F, config: SheetGroupConfig<P, SheetLineOf<P, F>>): SheetGroupValue<P, F>;
+//# sourceMappingURL=group.d.ts.map

package/dist/src/sheet/group.d.ts.map

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

package/dist/src/sheet/group.js

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+// ============================================================================
+// Builders
+// ============================================================================
+/** Build one band cell value. */
+function cell(kind, field, config, extra = {}) {
+    return { kind, field, config: config, ...extra };
+}
+export function text(_groupType, field, config = {}) {
+    return cell("text", field, config);
+}
+export function date(_groupType, field, config = {}) {
+    return cell("date", field, config);
+}
+export function quantity(_groupType, field, config = {}) {
+    return cell("quantity", field, config);
+}
+export function integer(_groupType, field, config = {}) {
+    return cell("integer", field, config);
+}
+/** A reference band cell — `Sheet.group.cell.reference(P, register, "field", cfg)`: a lookup over a flat member list, on a `String` / `Option<String>` field. */
+export function reference(_groupType, register, field, config = {}) {
+    return cell("reference", field, config, { register });
+}
+/** An enum band cell — `Sheet.group.cell.enum(P, register, "field", cfg)`: an upper-cased register word with its valence dot, on a `String` / `Option<String>` field. */
+export function enumCell(_groupType, register, field, config = {}) {
+    return cell("enum", field, config, { register });
+}
+/** A stamped band cell — `Sheet.group.cell.stamped(P, "field", cfg)`: a read-only code an upstream system owns, on a `String` / `Option<String>` field. */
+export function stamped(_groupType, field, config = {}) {
+    return cell("stamped", field, config);
+}
+/**
+ * Declares grouped rows — `Sheet.group(P, "lines", { title, sub?, cells?, folded?, noun? })`
+ * (#740): the group is the row, `lines` names the `Array<Line>` field
+ * holding its lines, and the band draws the title, the eyebrow and the
+ * `cells` under their line columns.
+ *
+ * @typeParam P - The group's row type
+ * @typeParam F - The lines field — an `Array<Line>` field of `P`
+ * @param rowType - The group's row type value
+ * @param lines - The lines field
+ * @param config - The band ({@link SheetGroupConfig})
+ * @returns The declaration the `group` prop takes
+ */
+export function createGroup(rowType, lines, config) {
+    return { rowType, lines, config: config };
+}
+//# sourceMappingURL=group.js.map

package/dist/src/sheet/group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.js","sourceRoot":"","sources":["../../../src/sheet/group.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkHH,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,iCAAiC;AACjC,SAAS,IAAI,CACT,IAA4B,EAC5B,KAAuB,EACvB,MAAc,EACd,QAA+B,EAAE;IAEjC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAA8B,EAAE,GAAG,KAAK,EAAE,CAAC;AAC7E,CAAC;AAKD,MAAM,UAAU,IAAI,CAAuB,UAAa,EAAE,KAAa,EAAE,SAAiB,EAAE;IACxF,OAAO,IAAI,CAAC,MAAM,EAAE,KAAyB,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC;AAKD,MAAM,UAAU,IAAI,CAAuB,UAAa,EAAE,KAAa,EAAE,SAAiB,EAAE;IACxF,OAAO,IAAI,CAAC,MAAM,EAAE,KAAyB,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC;AAKD,MAAM,UAAU,QAAQ,CAAuB,UAAa,EAAE,KAAa,EAAE,SAAiB,EAAE;IAC5F,OAAO,IAAI,CAAC,UAAU,EAAE,KAAyB,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC;AAKD,MAAM,UAAU,OAAO,CAAuB,UAAa,EAAE,KAAa,EAAE,SAAiB,EAAE;IAC3F,OAAO,IAAI,CAAC,SAAS,EAAE,KAAyB,EAAE,MAAM,CAAC,CAAC;AAC9D,CAAC;AAED,iKAAiK;AACjK,MAAM,UAAU,SAAS,CAAuB,UAAa,EAAE,QAAgB,EAAE,KAAkC,EAAE,SAAmC,EAAE;IACtJ,OAAO,IAAI,CAAC,WAAW,EAAE,KAAyB,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,yKAAyK;AACzK,MAAM,UAAU,QAAQ,CAAuB,UAAa,EAAE,QAAgB,EAAE,KAAkC,EAAE,SAAmC,EAAE;IACrJ,OAAO,IAAI,CAAC,MAAM,EAAE,KAAyB,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,2JAA2J;AAC3J,MAAM,UAAU,OAAO,CAAuB,UAAa,EAAE,KAAkC,EAAE,SAAkC,EAAE;IACjI,OAAO,IAAI,CAAC,SAAS,EAAE,KAAyB,EAAE,MAAM,CAAC,CAAC;AAC9D,CAAC;AAmDD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAqD,OAAU,EAAE,KAAQ,EAAE,MAA8C;IAChJ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAyC,EAAE,CAAC;AACjF,CAAC"}