@elaraai/east-ui 1.0.80 → 1.0.82

package/dist/src/collections/sheet/sub-rows.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `Sheet.subRows` and `Sheet.subRow` — sub rows (#844,
+ * `libs/east-ui/docs/proposals/Sheet Sub Rows - DX Proposal.md`): read-only
+ * rows under a line (or a flat row) that share none of the sheet's columns.
+ *
+ * `Sheet.subRows(R, { field: (item, row) => Sheet.subRow({ … }) })` is keyed
+ * like `columns`: each key names an `Array<T>` field of the type the columns
+ * are built over, and its mapper turns one element into a sub row. Key order
+ * is display order. The builder only CAPTURES; the root compiles each mapper
+ * once and the bridge calls it inside the row projection (`bridge.ts`).
+ *
+ * @packageDocumentation
+ */
+import { type EastType, type ExprType, type SubtypeExprOrValue, ArrayType, OptionType, StringType, type StructType } from "@elaraai/east";
+import { SheetSubRowType } from "./types.js";
+import type { SheetFieldKey } from "./columns.js";
+/**
+ * The keys of a row struct whose field is an `Array` — what a sub-row source
+ * may name.
+ *
+ * @typeParam R - The type the columns are built over
+ */
+export type SheetArrayField<R extends StructType> = {
+    [K in SheetFieldKey<R>]: R["fields"][K] extends ArrayType<EastType> ? K : never;
+}[SheetFieldKey<R>];
+/**
+ * The element type one of those fields holds — a struct, a variant, a string…
+ *
+ * @typeParam R - The type the columns are built over
+ * @typeParam K - The array field
+ */
+export type SheetElementOf<R extends StructType, K extends SheetArrayField<R>> = R["fields"][K] extends ArrayType<infer T extends EastType> ? T : never;
+/**
+ * The sub-row sources — keyed by `R`'s array fields; each value maps one
+ * element (and, when it needs it, the row) to a sub row.
+ *
+ * @typeParam R - The type the columns are built over
+ */
+export type SheetSubRowSources<R extends StructType> = {
+    [K in SheetArrayField<R>]?: (item: ExprType<SheetElementOf<R, K>>, row: ExprType<R>) => SubtypeExprOrValue<SheetSubRowType>;
+};
+/**
+ * What `Sheet.subRows` returns and the `subRows` prop takes — it captures
+ * only, like a group declaration.
+ *
+ * @typeParam R - The type the columns are built over
+ */
+export interface SheetSubRowsValue<R extends StructType> {
+    /** The type the sources were declared over — checked against the columns' at build time. */
+    readonly rowType: R;
+    /** The sources, in display order. */
+    readonly sources: SheetSubRowSources<R>;
+}
+/**
+ * Declares where a sheet's sub rows come from — `Sheet.subRows(R, { … })`.
+ *
+ * @typeParam R - The type the columns are built over (a grouped sheet: the line type)
+ * @param rowType - The row type value
+ * @param sources - Array field → mapper to a sub row, in display order
+ * @returns The declaration the `subRows` prop takes
+ *
+ * @example
+ * ```tsx
+ * // .tsx file with the `@jsxImportSource @elaraai/east-ui` pragma
+ * import { ArrayType, East, FloatType, IntegerType, OptionType, StringType, StructType, VariantType, none, some, variant } from "@elaraai/east";
+ * import { Reactive, Sheet, State, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const sheet = East.function([], UIComponentType, (_$) => (
+ *     <Reactive>{$ => {
+ *         const OperationType = StructType({
+ *             id: StringType, code: StringType, name: StringType, materials: ArrayType(StringType),
+ *             station: OptionType(StringType), by: OptionType(StringType),
+ *         });
+ *         const BookingType = VariantType({
+ *             space:     StructType({ area: StringType, units: IntegerType }),
+ *             labour:    StructType({ team: StringType, people: IntegerType, hours: FloatType }),
+ *             equipment: StructType({ resource: StringType }),
+ *         });
+ *         const JobType = StructType({
+ *             task: StringType, qty: OptionType(FloatType), notes: StringType,
+ *             operations: ArrayType(OperationType),   // no column — shown as sub rows
+ *             bookings: ArrayType(BookingType),       // no column — shown as sub rows
+ *         });
+ *         const OrderType = StructType({ id: StringType, name: StringType, jobs: ArrayType(JobType) });
+ *         const orders = $.let(State.bind([ArrayType(OrderType)], "sheet_subrows_orders", [
+ *             { id: "wo-1042", name: "WO-1042 · Frames", jobs: [
+ *                 { task: "Assemble frames", qty: some(40.0), notes: "Two benches", operations: [
+ *                     { id: "WO-1042-1", code: "CUT", name: "Cut rails to length", materials: ["Rail stock × 80"], station: some("Saw 2"), by: none },
+ *                     { id: "WO-1042-2", code: "ASM", name: "Assemble frame", materials: ["M6 bolts × 12", "Frame kit"], station: some("Bench 7"), by: some("Assembly") },
+ *                 ], bookings: [
+ *                     variant("labour", { team: "Assembly", people: 2n, hours: 12.0 }),
+ *                     variant("equipment", { resource: "Torque driver" }),
+ *                 ] },
+ *                 { task: "Inspect frames", qty: some(40.0), notes: "", operations: [], bookings: [
+ *                     variant("space", { area: "Test bay", units: 2n }),
+ *                 ] },
+ *             ] },
+ *             { id: "wo-1043", name: "WO-1043 · Housings", jobs: [
+ *                 { task: "Paint housings", qty: some(250.0), notes: "Primer first", operations: [
+ *                     { id: "WO-1043-1", code: "PNT", name: "Prime and paint", materials: ["Primer", "Topcoat"], station: none, by: none },
+ *                 ], bookings: [] },
+ *             ] },
+ *         ]));
+ *         return (
+ *             <Sheet
+ *                 data={orders}
+ *                 id="id"
+ *                 group={Sheet.group(OrderType, "jobs", { title: "name", noun: { singular: "order", plural: "orders" } })}
+ *                 columns={{
+ *                     task:  Sheet.column.text(JobType, { header: "Task", width: "220px" }),
+ *                     qty:   Sheet.column.quantity(JobType, { header: "Qty", width: "96px" }),
+ *                     notes: Sheet.column.text(JobType, { header: "Notes", width: "240px" }),
+ *                 }}
+ *                 subRows={Sheet.subRows(JobType, {
+ *                     operations: (op) => Sheet.subRow({
+ *                         code:   op.code,
+ *                         name:   op.name,
+ *                         chips:  op.materials,
+ *                         facets: { station: op.station, by: op.by },   // a none drops out
+ *                         id:     op.id,
+ *                     }),
+ *                     bookings: (b) => b.match({
+ *                         space:     (_$2, s) => Sheet.subRow({ code: "CLAIM", name: East.str`${s.area} · ${s.units} units` }),
+ *                         labour:    (_$2, l) => Sheet.subRow({ code: "LABOUR", name: East.str`${l.team} · ${l.people} people · ${l.hours} person-hours` }),
+ *                         equipment: (_$2, e) => Sheet.subRow({ code: "EQUIPMENT", name: e.resource }),
+ *                     }),
+ *                 })}
+ *                 newRow={East.function([Sheet.Types.NewRow], Sheet.Types.Patch(JobType), () => Sheet.patch(JobType, { notes: "", operations: [], bookings: [] }))}
+ *                 newGroup={East.function([Sheet.Types.NewGroup], Sheet.Types.Patch(OrderType), () => Sheet.patch(OrderType, { jobs: [] }))}
+ *                 onUpdate={orders.write}
+ *                 style={{ height: "420px" }}
+ *             />
+ *         );
+ *     }}</Reactive>
+ * ));
+ * ```
+ */
+export declare function createSubRows<R extends StructType>(rowType: R, sources: SheetSubRowSources<R>): SheetSubRowsValue<R>;
+/**
+ * The literal-record input of `Sheet.subRow({ … })`.
+ *
+ * @property code - The lead's code; an `Option` becomes its value or `""`
+ * @property name - The lead's words
+ * @property chips - The detail's parameter chips
+ * @property facets - Label → value, in display order; a `none` value drops the facet
+ * @property id - The record the sub row traces to; an `Option` becomes its value or `""`
+ */
+export interface SheetSubRowInput {
+    /** The lead's code. */
+    code?: SubtypeExprOrValue<StringType | OptionType<StringType>>;
+    /** The lead's words. */
+    name: SubtypeExprOrValue<StringType>;
+    /** The detail's parameter chips. */
+    chips?: SubtypeExprOrValue<ArrayType<StringType>>;
+    /** Label → value; a `none` value drops the facet. */
+    facets?: Record<string, SubtypeExprOrValue<StringType | OptionType<StringType>>>;
+    /** The record the sub row traces to. */
+    id?: SubtypeExprOrValue<StringType | OptionType<StringType>>;
+}
+/**
+ * Builds one sub row — `Sheet.subRow({ code?, name, chips?, facets?, id? })`.
+ * What is left out is filled in: `code` and `id` become `""`, `chips` and
+ * `facets` `[]`; a facet whose value is `none` drops out.
+ *
+ * @param input - The sub row's fields ({@link SheetSubRowInput})
+ * @returns An expression of `Sheet.Types.SubRow`
+ *
+ * @example
+ * ```tsx
+ * // .tsx file with the `@jsxImportSource @elaraai/east-ui` pragma
+ * import { ArrayType, East, FloatType, IntegerType, OptionType, StringType, StructType, VariantType, none, some, variant } from "@elaraai/east";
+ * import { Reactive, Sheet, State, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const sheet = East.function([], UIComponentType, (_$) => (
+ *     <Reactive>{$ => {
+ *         const OperationType = StructType({
+ *             id: StringType, code: StringType, name: StringType, materials: ArrayType(StringType),
+ *             station: OptionType(StringType), by: OptionType(StringType),
+ *         });
+ *         const BookingType = VariantType({
+ *             space:     StructType({ area: StringType, units: IntegerType }),
+ *             labour:    StructType({ team: StringType, people: IntegerType, hours: FloatType }),
+ *             equipment: StructType({ resource: StringType }),
+ *         });
+ *         const JobType = StructType({
+ *             task: StringType, qty: OptionType(FloatType), notes: StringType,
+ *             operations: ArrayType(OperationType),   // no column — shown as sub rows
+ *             bookings: ArrayType(BookingType),       // no column — shown as sub rows
+ *         });
+ *         const OrderType = StructType({ id: StringType, name: StringType, jobs: ArrayType(JobType) });
+ *         const orders = $.let(State.bind([ArrayType(OrderType)], "sheet_subrows_orders", [
+ *             { id: "wo-1042", name: "WO-1042 · Frames", jobs: [
+ *                 { task: "Assemble frames", qty: some(40.0), notes: "Two benches", operations: [
+ *                     { id: "WO-1042-1", code: "CUT", name: "Cut rails to length", materials: ["Rail stock × 80"], station: some("Saw 2"), by: none },
+ *                     { id: "WO-1042-2", code: "ASM", name: "Assemble frame", materials: ["M6 bolts × 12", "Frame kit"], station: some("Bench 7"), by: some("Assembly") },
+ *                 ], bookings: [
+ *                     variant("labour", { team: "Assembly", people: 2n, hours: 12.0 }),
+ *                     variant("equipment", { resource: "Torque driver" }),
+ *                 ] },
+ *                 { task: "Inspect frames", qty: some(40.0), notes: "", operations: [], bookings: [
+ *                     variant("space", { area: "Test bay", units: 2n }),
+ *                 ] },
+ *             ] },
+ *             { id: "wo-1043", name: "WO-1043 · Housings", jobs: [
+ *                 { task: "Paint housings", qty: some(250.0), notes: "Primer first", operations: [
+ *                     { id: "WO-1043-1", code: "PNT", name: "Prime and paint", materials: ["Primer", "Topcoat"], station: none, by: none },
+ *                 ], bookings: [] },
+ *             ] },
+ *         ]));
+ *         return (
+ *             <Sheet
+ *                 data={orders}
+ *                 id="id"
+ *                 group={Sheet.group(OrderType, "jobs", { title: "name", noun: { singular: "order", plural: "orders" } })}
+ *                 columns={{
+ *                     task:  Sheet.column.text(JobType, { header: "Task", width: "220px" }),
+ *                     qty:   Sheet.column.quantity(JobType, { header: "Qty", width: "96px" }),
+ *                     notes: Sheet.column.text(JobType, { header: "Notes", width: "240px" }),
+ *                 }}
+ *                 subRows={Sheet.subRows(JobType, {
+ *                     operations: (op) => Sheet.subRow({
+ *                         code:   op.code,
+ *                         name:   op.name,
+ *                         chips:  op.materials,
+ *                         facets: { station: op.station, by: op.by },   // a none drops out
+ *                         id:     op.id,
+ *                     }),
+ *                     bookings: (b) => b.match({
+ *                         space:     (_$2, s) => Sheet.subRow({ code: "CLAIM", name: East.str`${s.area} · ${s.units} units` }),
+ *                         labour:    (_$2, l) => Sheet.subRow({ code: "LABOUR", name: East.str`${l.team} · ${l.people} people · ${l.hours} person-hours` }),
+ *                         equipment: (_$2, e) => Sheet.subRow({ code: "EQUIPMENT", name: e.resource }),
+ *                     }),
+ *                 })}
+ *                 newRow={East.function([Sheet.Types.NewRow], Sheet.Types.Patch(JobType), () => Sheet.patch(JobType, { notes: "", operations: [], bookings: [] }))}
+ *                 newGroup={East.function([Sheet.Types.NewGroup], Sheet.Types.Patch(OrderType), () => Sheet.patch(OrderType, { jobs: [] }))}
+ *                 onUpdate={orders.write}
+ *                 style={{ height: "420px" }}
+ *             />
+ *         );
+ *     }}</Reactive>
+ * ));
+ * ```
+ */
+export declare function createSubRow(input: SheetSubRowInput): ExprType<SheetSubRowType>;
+//# sourceMappingURL=sub-rows.d.ts.map

package/dist/src/collections/sheet/sub-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-rows.d.ts","sourceRoot":"","sources":["../../../../src/collections/sheet/sub-rows.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EACH,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAGvB,SAAS,EACT,UAAU,EACV,UAAU,EACV,KAAK,UAAU,EAGlB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAkB,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,UAAU,IAAI;KAC/C,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK;CAClF,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,eAAe,CAAC,CAAC,CAAC,IACzE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,SAAS,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,UAAU,IAAI;KAClD,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,kBAAkB,CAAC,eAAe,CAAC;CAC9H,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,UAAU;IACnD,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAEpH;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC7B,uBAAuB;IACvB,IAAI,CAAC,EAAE,kBAAkB,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IAC/D,wBAAwB;IACxB,IAAI,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACrC,oCAAoC;IACpC,KAAK,CAAC,EAAE,kBAAkB,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAClD,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACjF,wCAAwC;IACxC,EAAE,CAAC,EAAE,kBAAkB,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;CAChE;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,QAAQ,CAAC,eAAe,CAAC,CAa/E"}

package/dist/src/collections/sheet/sub-rows.js

@@ -0,0 +1,222 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `Sheet.subRows` and `Sheet.subRow` — sub rows (#844,
+ * `libs/east-ui/docs/proposals/Sheet Sub Rows - DX Proposal.md`): read-only
+ * rows under a line (or a flat row) that share none of the sheet's columns.
+ *
+ * `Sheet.subRows(R, { field: (item, row) => Sheet.subRow({ … }) })` is keyed
+ * like `columns`: each key names an `Array<T>` field of the type the columns
+ * are built over, and its mapper turns one element into a sub row. Key order
+ * is display order. The builder only CAPTURES; the root compiles each mapper
+ * once and the bridge calls it inside the row projection (`bridge.ts`).
+ *
+ * @packageDocumentation
+ */
+import { East, Expr, ArrayType, OptionType, StringType, some, none, } from "@elaraai/east";
+import { SheetFacetType, SheetSubRowType } from "./types.js";
+/**
+ * Declares where a sheet's sub rows come from — `Sheet.subRows(R, { … })`.
+ *
+ * @typeParam R - The type the columns are built over (a grouped sheet: the line type)
+ * @param rowType - The row type value
+ * @param sources - Array field → mapper to a sub row, in display order
+ * @returns The declaration the `subRows` prop takes
+ *
+ * @example
+ * ```tsx
+ * // .tsx file with the `@jsxImportSource @elaraai/east-ui` pragma
+ * import { ArrayType, East, FloatType, IntegerType, OptionType, StringType, StructType, VariantType, none, some, variant } from "@elaraai/east";
+ * import { Reactive, Sheet, State, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const sheet = East.function([], UIComponentType, (_$) => (
+ *     <Reactive>{$ => {
+ *         const OperationType = StructType({
+ *             id: StringType, code: StringType, name: StringType, materials: ArrayType(StringType),
+ *             station: OptionType(StringType), by: OptionType(StringType),
+ *         });
+ *         const BookingType = VariantType({
+ *             space:     StructType({ area: StringType, units: IntegerType }),
+ *             labour:    StructType({ team: StringType, people: IntegerType, hours: FloatType }),
+ *             equipment: StructType({ resource: StringType }),
+ *         });
+ *         const JobType = StructType({
+ *             task: StringType, qty: OptionType(FloatType), notes: StringType,
+ *             operations: ArrayType(OperationType),   // no column — shown as sub rows
+ *             bookings: ArrayType(BookingType),       // no column — shown as sub rows
+ *         });
+ *         const OrderType = StructType({ id: StringType, name: StringType, jobs: ArrayType(JobType) });
+ *         const orders = $.let(State.bind([ArrayType(OrderType)], "sheet_subrows_orders", [
+ *             { id: "wo-1042", name: "WO-1042 · Frames", jobs: [
+ *                 { task: "Assemble frames", qty: some(40.0), notes: "Two benches", operations: [
+ *                     { id: "WO-1042-1", code: "CUT", name: "Cut rails to length", materials: ["Rail stock × 80"], station: some("Saw 2"), by: none },
+ *                     { id: "WO-1042-2", code: "ASM", name: "Assemble frame", materials: ["M6 bolts × 12", "Frame kit"], station: some("Bench 7"), by: some("Assembly") },
+ *                 ], bookings: [
+ *                     variant("labour", { team: "Assembly", people: 2n, hours: 12.0 }),
+ *                     variant("equipment", { resource: "Torque driver" }),
+ *                 ] },
+ *                 { task: "Inspect frames", qty: some(40.0), notes: "", operations: [], bookings: [
+ *                     variant("space", { area: "Test bay", units: 2n }),
+ *                 ] },
+ *             ] },
+ *             { id: "wo-1043", name: "WO-1043 · Housings", jobs: [
+ *                 { task: "Paint housings", qty: some(250.0), notes: "Primer first", operations: [
+ *                     { id: "WO-1043-1", code: "PNT", name: "Prime and paint", materials: ["Primer", "Topcoat"], station: none, by: none },
+ *                 ], bookings: [] },
+ *             ] },
+ *         ]));
+ *         return (
+ *             <Sheet
+ *                 data={orders}
+ *                 id="id"
+ *                 group={Sheet.group(OrderType, "jobs", { title: "name", noun: { singular: "order", plural: "orders" } })}
+ *                 columns={{
+ *                     task:  Sheet.column.text(JobType, { header: "Task", width: "220px" }),
+ *                     qty:   Sheet.column.quantity(JobType, { header: "Qty", width: "96px" }),
+ *                     notes: Sheet.column.text(JobType, { header: "Notes", width: "240px" }),
+ *                 }}
+ *                 subRows={Sheet.subRows(JobType, {
+ *                     operations: (op) => Sheet.subRow({
+ *                         code:   op.code,
+ *                         name:   op.name,
+ *                         chips:  op.materials,
+ *                         facets: { station: op.station, by: op.by },   // a none drops out
+ *                         id:     op.id,
+ *                     }),
+ *                     bookings: (b) => b.match({
+ *                         space:     (_$2, s) => Sheet.subRow({ code: "CLAIM", name: East.str`${s.area} · ${s.units} units` }),
+ *                         labour:    (_$2, l) => Sheet.subRow({ code: "LABOUR", name: East.str`${l.team} · ${l.people} people · ${l.hours} person-hours` }),
+ *                         equipment: (_$2, e) => Sheet.subRow({ code: "EQUIPMENT", name: e.resource }),
+ *                     }),
+ *                 })}
+ *                 newRow={East.function([Sheet.Types.NewRow], Sheet.Types.Patch(JobType), () => Sheet.patch(JobType, { notes: "", operations: [], bookings: [] }))}
+ *                 newGroup={East.function([Sheet.Types.NewGroup], Sheet.Types.Patch(OrderType), () => Sheet.patch(OrderType, { jobs: [] }))}
+ *                 onUpdate={orders.write}
+ *                 style={{ height: "420px" }}
+ *             />
+ *         );
+ *     }}</Reactive>
+ * ));
+ * ```
+ */
+export function createSubRows(rowType, sources) {
+    return { rowType, sources };
+}
+/** A `String` or `Option<String>` input as an `Option<String>` expression, its shape read once at build time. */
+function optionalText(v) {
+    if (typeof v === "string")
+        return East.value(some(v), OptionType(StringType));
+    if (v instanceof Expr) {
+        if (Expr.type(v) === StringType) {
+            return East.value(some(v), OptionType(StringType));
+        }
+        return v;
+    }
+    return East.value(v, OptionType(StringType));
+}
+/** A `String` or `Option<String>` input as display text, `""` for none. */
+function textOrBlank(v) {
+    if (v === undefined)
+        return East.value("", StringType);
+    return optionalText(v).match({ some: (_$, s) => s, none: (_$) => "" });
+}
+/**
+ * Builds one sub row — `Sheet.subRow({ code?, name, chips?, facets?, id? })`.
+ * What is left out is filled in: `code` and `id` become `""`, `chips` and
+ * `facets` `[]`; a facet whose value is `none` drops out.
+ *
+ * @param input - The sub row's fields ({@link SheetSubRowInput})
+ * @returns An expression of `Sheet.Types.SubRow`
+ *
+ * @example
+ * ```tsx
+ * // .tsx file with the `@jsxImportSource @elaraai/east-ui` pragma
+ * import { ArrayType, East, FloatType, IntegerType, OptionType, StringType, StructType, VariantType, none, some, variant } from "@elaraai/east";
+ * import { Reactive, Sheet, State, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const sheet = East.function([], UIComponentType, (_$) => (
+ *     <Reactive>{$ => {
+ *         const OperationType = StructType({
+ *             id: StringType, code: StringType, name: StringType, materials: ArrayType(StringType),
+ *             station: OptionType(StringType), by: OptionType(StringType),
+ *         });
+ *         const BookingType = VariantType({
+ *             space:     StructType({ area: StringType, units: IntegerType }),
+ *             labour:    StructType({ team: StringType, people: IntegerType, hours: FloatType }),
+ *             equipment: StructType({ resource: StringType }),
+ *         });
+ *         const JobType = StructType({
+ *             task: StringType, qty: OptionType(FloatType), notes: StringType,
+ *             operations: ArrayType(OperationType),   // no column — shown as sub rows
+ *             bookings: ArrayType(BookingType),       // no column — shown as sub rows
+ *         });
+ *         const OrderType = StructType({ id: StringType, name: StringType, jobs: ArrayType(JobType) });
+ *         const orders = $.let(State.bind([ArrayType(OrderType)], "sheet_subrows_orders", [
+ *             { id: "wo-1042", name: "WO-1042 · Frames", jobs: [
+ *                 { task: "Assemble frames", qty: some(40.0), notes: "Two benches", operations: [
+ *                     { id: "WO-1042-1", code: "CUT", name: "Cut rails to length", materials: ["Rail stock × 80"], station: some("Saw 2"), by: none },
+ *                     { id: "WO-1042-2", code: "ASM", name: "Assemble frame", materials: ["M6 bolts × 12", "Frame kit"], station: some("Bench 7"), by: some("Assembly") },
+ *                 ], bookings: [
+ *                     variant("labour", { team: "Assembly", people: 2n, hours: 12.0 }),
+ *                     variant("equipment", { resource: "Torque driver" }),
+ *                 ] },
+ *                 { task: "Inspect frames", qty: some(40.0), notes: "", operations: [], bookings: [
+ *                     variant("space", { area: "Test bay", units: 2n }),
+ *                 ] },
+ *             ] },
+ *             { id: "wo-1043", name: "WO-1043 · Housings", jobs: [
+ *                 { task: "Paint housings", qty: some(250.0), notes: "Primer first", operations: [
+ *                     { id: "WO-1043-1", code: "PNT", name: "Prime and paint", materials: ["Primer", "Topcoat"], station: none, by: none },
+ *                 ], bookings: [] },
+ *             ] },
+ *         ]));
+ *         return (
+ *             <Sheet
+ *                 data={orders}
+ *                 id="id"
+ *                 group={Sheet.group(OrderType, "jobs", { title: "name", noun: { singular: "order", plural: "orders" } })}
+ *                 columns={{
+ *                     task:  Sheet.column.text(JobType, { header: "Task", width: "220px" }),
+ *                     qty:   Sheet.column.quantity(JobType, { header: "Qty", width: "96px" }),
+ *                     notes: Sheet.column.text(JobType, { header: "Notes", width: "240px" }),
+ *                 }}
+ *                 subRows={Sheet.subRows(JobType, {
+ *                     operations: (op) => Sheet.subRow({
+ *                         code:   op.code,
+ *                         name:   op.name,
+ *                         chips:  op.materials,
+ *                         facets: { station: op.station, by: op.by },   // a none drops out
+ *                         id:     op.id,
+ *                     }),
+ *                     bookings: (b) => b.match({
+ *                         space:     (_$2, s) => Sheet.subRow({ code: "CLAIM", name: East.str`${s.area} · ${s.units} units` }),
+ *                         labour:    (_$2, l) => Sheet.subRow({ code: "LABOUR", name: East.str`${l.team} · ${l.people} people · ${l.hours} person-hours` }),
+ *                         equipment: (_$2, e) => Sheet.subRow({ code: "EQUIPMENT", name: e.resource }),
+ *                     }),
+ *                 })}
+ *                 newRow={East.function([Sheet.Types.NewRow], Sheet.Types.Patch(JobType), () => Sheet.patch(JobType, { notes: "", operations: [], bookings: [] }))}
+ *                 newGroup={East.function([Sheet.Types.NewGroup], Sheet.Types.Patch(OrderType), () => Sheet.patch(OrderType, { jobs: [] }))}
+ *                 onUpdate={orders.write}
+ *                 style={{ height: "420px" }}
+ *             />
+ *         );
+ *     }}</Reactive>
+ * ));
+ * ```
+ */
+export function createSubRow(input) {
+    const facets = Object.entries(input.facets ?? {}).map(([label, value]) => optionalText(value).match({
+        some: (_$, v) => East.value(some({ label, value: v }), OptionType(SheetFacetType)),
+        none: (_$) => East.value(none, OptionType(SheetFacetType)),
+    }));
+    return East.value({
+        code: textOrBlank(input.code),
+        name: input.name,
+        chips: input.chips ?? East.value([], ArrayType(StringType)),
+        facets: East.value(facets, ArrayType(OptionType(SheetFacetType))).filterMap((_$, f) => f),
+        id: textOrBlank(input.id),
+    }, SheetSubRowType);
+}
+//# sourceMappingURL=sub-rows.js.map

package/dist/src/collections/sheet/sub-rows.js.map

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

package/dist/src/collections/sheet/transactions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The Sheet's names for the shared editing contract (`contracts/editing.ts`,
+ * #879) — each one the `Editing` namespace's own value (`Sheet.apply` is
+ * `Editing.apply`, `Sheet.Types.ChangeSet` is `Editing.Types.ChangeSet`) — and
+ * the transaction types only a sheet has: a new row's destination among a
+ * group's children, and the `newRow` / `newGroup` contexts.
+ *
+ * @packageDocumentation
+ */
+import { IntegerType, StringType, StructType, VariantType } from "@elaraai/east";
+export { EditingPositionType as SheetPositionType, EditingPlacementType as SheetEntryPlacementType, EditingFieldIssueType as SheetFieldIssueType, EditingReadinessType as SheetReadinessType, EditingIssueType as SheetIssueType, EditingBatchReadinessType as SheetBatchReadinessType, EditingOriginType as SheetOriginType, EditingApplyResultType as SheetApplyResultType, EditingDraftFieldType as SheetDraftFieldType, EditingDraftTypeFor as SheetDraftTypeFor, EditingBaseTypeFor as SheetBaseTypeFor, EditingChangeTypeFor as SheetChangeTypeFor, EditingChangeSetTypeFor as SheetChangeSetTypeFor, EditingAppliedTypeFor as SheetAppliedTypeFor, applyEditing as applySheet, type EditingDraftOf as SheetDraftOf, } from "../../contracts/editing.js";
+/**
+ * A new row's destination: a top-level entry's placement, or a position among
+ * a group's children.
+ *
+ * @property entry - A top-level entry, at its placement
+ * @property child - A child row of the group with this id, at this index
+ */
+export declare const SheetRowDestinationType: VariantType<{
+    readonly entry: VariantType<{
+        readonly ordered: VariantType<{
+            readonly start: import("@elaraai/east").NullType;
+            readonly end: import("@elaraai/east").NullType;
+            readonly before: StringType;
+            readonly after: StringType;
+        }>;
+        readonly keyOrder: import("@elaraai/east").NullType;
+    }>;
+    readonly child: StructType<{
+        readonly group: StringType;
+        readonly index: IntegerType;
+    }>;
+}>;
+/**
+ * What a `newRow` constructor is told.
+ *
+ * @property destination - Where the new row goes
+ */
+export declare const SheetNewRowType: StructType<{
+    readonly destination: VariantType<{
+        readonly entry: VariantType<{
+            readonly ordered: VariantType<{
+                readonly start: import("@elaraai/east").NullType;
+                readonly end: import("@elaraai/east").NullType;
+                readonly before: StringType;
+                readonly after: StringType;
+            }>;
+            readonly keyOrder: import("@elaraai/east").NullType;
+        }>;
+        readonly child: StructType<{
+            readonly group: StringType;
+            readonly index: IntegerType;
+        }>;
+    }>;
+}>;
+/**
+ * What a `newGroup` constructor is told.
+ *
+ * @property place - Where the new group goes
+ */
+export declare const SheetNewGroupType: StructType<{
+    readonly place: VariantType<{
+        readonly ordered: VariantType<{
+            readonly start: import("@elaraai/east").NullType;
+            readonly end: import("@elaraai/east").NullType;
+            readonly before: StringType;
+            readonly after: StringType;
+        }>;
+        readonly keyOrder: import("@elaraai/east").NullType;
+    }>;
+}>;
+//# sourceMappingURL=transactions.d.ts.map

package/dist/src/collections/sheet/transactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactions.d.ts","sourceRoot":"","sources":["../../../../src/collections/sheet/transactions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjF,OAAO,EACH,mBAAmB,IAAI,iBAAiB,EACxC,oBAAoB,IAAI,uBAAuB,EAC/C,qBAAqB,IAAI,mBAAmB,EAC5C,oBAAoB,IAAI,kBAAkB,EAC1C,gBAAgB,IAAI,cAAc,EAClC,yBAAyB,IAAI,uBAAuB,EACpD,iBAAiB,IAAI,eAAe,EACpC,sBAAsB,IAAI,oBAAoB,EAC9C,qBAAqB,IAAI,mBAAmB,EAC5C,mBAAmB,IAAI,iBAAiB,EACxC,kBAAkB,IAAI,gBAAgB,EACtC,oBAAoB,IAAI,kBAAkB,EAC1C,uBAAuB,IAAI,qBAAqB,EAChD,qBAAqB,IAAI,mBAAmB,EAC5C,YAAY,IAAI,UAAU,EAC1B,KAAK,cAAc,IAAI,YAAY,GACtC,MAAM,4BAA4B,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;EAGlC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;EAAuD,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;EAA8C,CAAC"}

package/dist/src/collections/sheet/transactions.js

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The Sheet's names for the shared editing contract (`contracts/editing.ts`,
+ * #879) — each one the `Editing` namespace's own value (`Sheet.apply` is
+ * `Editing.apply`, `Sheet.Types.ChangeSet` is `Editing.Types.ChangeSet`) — and
+ * the transaction types only a sheet has: a new row's destination among a
+ * group's children, and the `newRow` / `newGroup` contexts.
+ *
+ * @packageDocumentation
+ */
+import { IntegerType, StringType, StructType, VariantType } from "@elaraai/east";
+import { EditingPlacementType } from "../../contracts/editing.js";
+export { EditingPositionType as SheetPositionType, EditingPlacementType as SheetEntryPlacementType, EditingFieldIssueType as SheetFieldIssueType, EditingReadinessType as SheetReadinessType, EditingIssueType as SheetIssueType, EditingBatchReadinessType as SheetBatchReadinessType, EditingOriginType as SheetOriginType, EditingApplyResultType as SheetApplyResultType, EditingDraftFieldType as SheetDraftFieldType, EditingDraftTypeFor as SheetDraftTypeFor, EditingBaseTypeFor as SheetBaseTypeFor, EditingChangeTypeFor as SheetChangeTypeFor, EditingChangeSetTypeFor as SheetChangeSetTypeFor, EditingAppliedTypeFor as SheetAppliedTypeFor, applyEditing as applySheet, } from "../../contracts/editing.js";
+/**
+ * A new row's destination: a top-level entry's placement, or a position among
+ * a group's children.
+ *
+ * @property entry - A top-level entry, at its placement
+ * @property child - A child row of the group with this id, at this index
+ */
+export const SheetRowDestinationType = VariantType({
+    entry: EditingPlacementType,
+    child: StructType({ group: StringType, index: IntegerType }),
+});
+/**
+ * What a `newRow` constructor is told.
+ *
+ * @property destination - Where the new row goes
+ */
+export const SheetNewRowType = StructType({ destination: SheetRowDestinationType });
+/**
+ * What a `newGroup` constructor is told.
+ *
+ * @property place - Where the new group goes
+ */
+export const SheetNewGroupType = StructType({ place: EditingPlacementType });
+//# sourceMappingURL=transactions.js.map

package/dist/src/collections/sheet/transactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactions.js","sourceRoot":"","sources":["../../../../src/collections/sheet/transactions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,EACH,mBAAmB,IAAI,iBAAiB,EACxC,oBAAoB,IAAI,uBAAuB,EAC/C,qBAAqB,IAAI,mBAAmB,EAC5C,oBAAoB,IAAI,kBAAkB,EAC1C,gBAAgB,IAAI,cAAc,EAClC,yBAAyB,IAAI,uBAAuB,EACpD,iBAAiB,IAAI,eAAe,EACpC,sBAAsB,IAAI,oBAAoB,EAC9C,qBAAqB,IAAI,mBAAmB,EAC5C,mBAAmB,IAAI,iBAAiB,EACxC,kBAAkB,IAAI,gBAAgB,EACtC,oBAAoB,IAAI,kBAAkB,EAC1C,uBAAuB,IAAI,qBAAqB,EAChD,qBAAqB,IAAI,mBAAmB,EAC5C,YAAY,IAAI,UAAU,GAE7B,MAAM,4BAA4B,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,WAAW,CAAC;IAC/C,KAAK,EAAE,oBAAoB;IAC3B,KAAK,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;CAC/D,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC,EAAE,WAAW,EAAE,uBAAuB,EAAE,CAAC,CAAC;AAEpF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC,CAAC"}