@cosmicdrift/kumiko-renderer 0.374.0 → 0.378.0

package/dist/headless/view-model/list.d.ts

@@ -0,0 +1,16 @@
+import type { EntityDefinition, EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ListViewModel, Translate } from "./types.ts";
+export type ComputeListViewModelInput = {
+    readonly screen: EntityListScreenDefinition;
+    readonly entity: EntityDefinition;
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly translate: Translate;
+    readonly featureName: string;
+};
+export declare function computeListViewModel(input: ComputeListViewModelInput): ListViewModel;
+export declare function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string;
+export declare function fieldOptionLabelKeyPrefix(featureName: string, entityName: string, fieldName: string): string;
+export declare function fieldOptionLabelKey(featureName: string, entityName: string, fieldName: string, value: string): string;
+export declare function embeddedCellLabelKey(featureName: string, entityName: string, fieldName: string, subFieldName: string): string;
+export declare function embeddedCellOptionLabelKey(featureName: string, entityName: string, fieldName: string, subFieldName: string, value: string): string;
+export declare function buildOptionLabels(translate: (key: string, params?: Readonly<Record<string, unknown>>) => string, keyFor: (value: string) => string, options: readonly string[]): Readonly<Record<string, string>>;

package/dist/headless/view-model/list.js

@@ -0,0 +1,229 @@
+import { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, normalizeListColumn, parseRefTarget, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { deriveListFileDisplay } from "./list-file-display.js";
+const WRITE_ONLY_SET_LABEL_KEY = "kumiko.field.writeOnly.set";
+// Pure transform: takes the declared screen + entity + incoming rows, spits
+// out the flat shape the renderer draws. No conditions, no access-checks —
+// those are list-level decisions that the caller makes BEFORE calling
+// here (e.g. filtering rows by ownership on the server / before query).
+// Field-level read-access (Level 3 of UI-architecture.md §Permission) is a
+// follow-up; this v1 assumes the caller passed a row-filter that drops any
+// field the user may not see.
+export function computeListViewModel(input) {
+    const { screen, entity, rows, translate, featureName } = input;
+    const columns = [];
+    for (const spec of screen.columns) {
+        const normalized = normalizeListColumn(spec);
+        const storedFieldType = entity.fields[normalized.field]?.type;
+        // A real non-text entity field keeps its own type (documented on
+        // ListColumnSpec.refEntity); only the all-"text" pseudo-entities of the
+        // projection shims and fields without a stored def take the declared path.
+        if (normalized.refEntity !== undefined &&
+            (storedFieldType === undefined || storedFieldType === "text")) {
+            // Declared reference metadata (ListColumnSpec.refEntity) — for
+            // projectionList/relatedList columns, which have no EntityDefinition
+            // field to carry a real "reference" type. Checked before the
+            // entity.fields lookup below so it also fires against the pseudo-
+            // entities that hardcode every field as "text" (projection-list-shim,
+            // related-list-section) — those never reach the reference branch
+            // further down since fieldDef.type is always "text" there.
+            const refTarget = parseRefTarget(normalized.refEntity, featureName);
+            columns.push({
+                field: normalized.field,
+                label: translate(normalized.label ?? fieldLabelKey(featureName, screen.entity, normalized.field)),
+                type: "reference",
+                // The declared value is the referenced id, not the resolved label —
+                // there is no column to server-sort by, same as row-meta references.
+                sortable: false,
+                refEntity: refTarget.entityName,
+                refFeature: refTarget.featureName,
+                refLabelField: normalized.refLabelField ?? "id",
+                ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+                ...(normalized.hideOnNarrow === true && { hideOnNarrow: true }),
+            });
+            continue;
+        }
+        const fieldDef = entity.fields[normalized.field];
+        if (!fieldDef) {
+            // Not a stored field — may be a read-time derived field (value appended
+            // by the list-query handler). Render it as its display valueType; derived
+            // columns carry no reference/select metadata and never server-sort.
+            const derivedDef = entity.derivedFields?.[normalized.field];
+            if (!derivedDef) {
+                // Row-meta column (id/tenantId/version/insertedAt/modifiedAt/...) —
+                // a real base-table column that's never a declared entity field, e.g.
+                // a SystemAdmin cross-tenant list exposing tenantId. Unlike the
+                // derivedFields branch above, these are actual DB columns, so
+                // server-side ORDER BY works — sortable stays true, except for the
+                // ID columns in LIST_ROW_META_REFERENCES (see their reference branch).
+                const rowMetaType = LIST_ROW_META_COLUMNS[normalized.field];
+                if (rowMetaType !== undefined) {
+                    const rowMetaRef = LIST_ROW_META_REFERENCES[normalized.field];
+                    columns.push({
+                        field: normalized.field,
+                        label: translate(normalized.label ?? fieldLabelKey(featureName, screen.entity, normalized.field)),
+                        type: rowMetaRef !== undefined ? "reference" : rowMetaType,
+                        // The DB column holds the GUID, not the resolved label — server-side
+                        // ORDER BY would sort by GUID while the cell shows the name.
+                        sortable: rowMetaRef === undefined,
+                        ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+                        ...(normalized.hideOnNarrow === true && { hideOnNarrow: true }),
+                        ...(rowMetaRef !== undefined && {
+                            refEntity: rowMetaRef.refEntity,
+                            refFeature: rowMetaRef.refFeature,
+                            refLabelField: rowMetaRef.refLabelField,
+                        }),
+                    });
+                    continue;
+                }
+                // A virtual presentational column — drawn entirely by a columnRenderer
+                // component from the row (e.g. tag chips); value is undefined and it
+                // never server-sorts. `field` is just the column key. It needs BOTH a
+                // label AND a renderer — renderer is what actually draws it; a label
+                // alone with no renderer would push an empty, unrendered column into
+                // the view model. Missing either is an author typo (or a stale
+                // field-rename) → fail loud instead of silently drawing nothing.
+                if (normalized.label !== undefined && normalized.renderer !== undefined) {
+                    columns.push({
+                        field: normalized.field,
+                        label: translate(normalized.label),
+                        type: "text",
+                        sortable: false,
+                        renderer: normalized.renderer,
+                        ...(normalized.hideOnNarrow === true && { hideOnNarrow: true }),
+                    });
+                    continue;
+                }
+                throw new Error(`computeListViewModel: screen "${screen.id}" references unknown field "${normalized.field}" on entity "${screen.entity}"`);
+            }
+            columns.push({
+                field: normalized.field,
+                label: translate(normalized.label ?? fieldLabelKey(featureName, screen.entity, normalized.field)),
+                type: derivedDef.valueType,
+                // Display-only: a header sort would round-trip to the server, which has
+                // no column to sort by (see DerivedFieldDef). Never offer the affordance.
+                sortable: false,
+                ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+                ...(normalized.hideOnNarrow === true && { hideOnNarrow: true }),
+            });
+            continue;
+        }
+        const label = translate(normalized.label ?? fieldLabelKey(featureName, screen.entity, normalized.field));
+        // Tier 2.7e-3 + Cross-Feature: Reference-Field — entity-String
+        // kann same-feature ("user") oder cross-feature ("users:user")
+        // sein. parseRefTarget gibt (featureName, entityName), der
+        // Renderer baut die Lookup-QN als
+        // `<refFeature>:query:<refEntity>:list`.
+        const refRaw = fieldDef.type === "reference"
+            ? fieldDef.entity
+            : undefined;
+        const refTarget = refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined;
+        const refEntity = refTarget?.entityName;
+        const refFeature = refTarget?.featureName;
+        const refLabelField = fieldDef.type === "reference"
+            ? (fieldDef.labelField ?? "id")
+            : undefined;
+        // For select and multiSelect fields: bake in translated option labels.
+        // Convention matches the form path → one translation source for list +
+        // form. A missing key returns the key itself per convention; the
+        // renderer then falls back to humanizeSlug.
+        const optionLabels = fieldDef.type === "select" || fieldDef.type === "multiSelect"
+            ? buildOptionLabels(translate, (value) => fieldOptionLabelKey(featureName, screen.entity, normalized.field, value), fieldDef.options)
+            : undefined;
+        const optionTones = fieldDef.type === "select" ? fieldDef.optionTones : undefined;
+        const grouping = fieldDef.type === "number" ? fieldDef.grouping : undefined;
+        const fileDisplay = deriveListFileDisplay(fieldDef, normalized.renderer);
+        const column = {
+            field: normalized.field,
+            label,
+            type: fieldDef.type,
+            sortable: fieldIsSortable(fieldDef),
+            ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+            ...(optionLabels !== undefined && { optionLabels }),
+            ...(optionTones !== undefined && { optionTones }),
+            ...(refEntity !== undefined && { refEntity }),
+            ...(refFeature !== undefined && { refFeature }),
+            ...(refLabelField !== undefined && { refLabelField }),
+            ...(grouping !== undefined && { grouping }),
+            ...(fileDisplay !== undefined && { fileDisplay }),
+            ...(normalized.hideOnNarrow === true && { hideOnNarrow: true }),
+        };
+        columns.push(column);
+    }
+    const writeOnlyFieldNames = screen.columns
+        .map((spec) => normalizeListColumn(spec).field)
+        .filter((name) => {
+        const fieldDef = entity.fields[name];
+        return fieldDef?.type === "text" && fieldDef.writeOnly === true;
+    });
+    // The wire carries `true` (set) / `null` (empty) for writeOnly fields; the cell shows a word, not "true".
+    const showWriteOnlyAsWord = (row) => {
+        const shown = { ...row };
+        for (const name of writeOnlyFieldNames) {
+            if (row[name] === true)
+                shown[name] = translate(WRITE_ONLY_SET_LABEL_KEY);
+        }
+        return shown;
+    };
+    const listRows = rows.map((row) => ({
+        id: String(row["id"] ?? ""),
+        values: showWriteOnlyAsWord(row),
+    }));
+    return {
+        screenId: screen.id,
+        entityName: screen.entity,
+        columns,
+        rows: listRows,
+        ...(screen.slots && { slots: screen.slots }),
+        isEmpty: listRows.length === 0,
+    };
+}
+// Field-i18n-key convention matches what features register translations
+// under (see packages/framework/src/i18n/ for the pattern). Duplicated
+// here as a plain function — the ui-core boundary forbids depending on
+// the i18n module directly.
+export function fieldLabelKey(featureName, entityName, fieldName) {
+    return `${featureName}:entity:${entityName}:field:${fieldName}`;
+}
+export function fieldOptionLabelKeyPrefix(featureName, entityName, fieldName) {
+    return `${fieldLabelKey(featureName, entityName, fieldName)}:option:`;
+}
+export function fieldOptionLabelKey(featureName, entityName, fieldName, value) {
+    return `${fieldOptionLabelKeyPrefix(featureName, entityName, fieldName)}${value}`;
+}
+// Embedded-list cell label key — one level deeper than fieldLabelKey,
+// keyed by the sub-field name inside an embedded-LIST field's `schema`
+// (invoice-positions-style tables built via createEmbeddedListField()).
+export function embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName) {
+    return `${featureName}:entity:${entityName}:field:${fieldName}:cell:${subFieldName}`;
+}
+export function embeddedCellOptionLabelKey(featureName, entityName, fieldName, subFieldName, value) {
+    return `${featureName}:entity:${entityName}:field:${fieldName}:cell:${subFieldName}:option:${value}`;
+}
+// Build a value→label map for a select-field's options. Convention:
+// translate() returns the input key when the lookup misses (i18next
+// default + LocaleResolver convention) — we surface the *raw value* in
+// that case so the renderer's humanizeSlug fallback can take over.
+// Without that fallback, an unlabeled option would render as the full
+// `feature:entity:field:option:value`-key.
+//
+// `keyFor` carries whichever key convention the caller needs (top-level
+// field via fieldOptionLabelKey, embedded-list cell via
+// embeddedCellOptionLabelKey) — shared between list-VM, edit-VM, and
+// embedded-list cells so all three produce identical option-translations.
+export function buildOptionLabels(translate, keyFor, options) {
+    const out = {};
+    for (const value of options) {
+        const key = keyFor(value);
+        const translated = translate(key);
+        out[value] = translated === key ? value : translated;
+    }
+    return out;
+}
+// A field can declare `sortable: true` on the FieldDefinition. This is
+// framework-level metadata used both by the server's list-query builder
+// (ORDER BY safety) and by the UI (column header click indicator). All
+// field types can bear the flag; it's off by default.
+function fieldIsSortable(field) {
+    const flag = field.sortable;
+    return flag === true;
+}

package/dist/headless/view-model/types.d.ts

@@ -0,0 +1,382 @@
+import type { EditFieldSpec, EditSectionSpec, FieldAffix, FieldFillAction, FieldIconKey, FieldRenderer, IconKey, ListColumnSpec, ListFacetSpec, ListSortSpec, OptionsQueryPayload, PlatformComponent, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionMode, ScreenSlots, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
+export type RuntimeRenderer = (value: unknown, row?: Readonly<Record<string, unknown>>) => string;
+/** Where a cell's text links to. `href` comes from NavApi.hrefFor (new-tab and
+ *  copy-link work); `onPress` is the in-app navigation for a plain click. */
+export type CellLink = {
+    readonly href: string;
+    readonly onPress: () => void;
+};
+/** Runtime-only like RuntimeRenderer; undefined means the cell stays plain text. */
+export type RuntimeCellLink = (value: unknown, row?: Readonly<Record<string, unknown>>) => CellLink | undefined;
+/** One entry of a multi-reference cell: its label, linked when the target is readable. */
+export type CellLinkItem = {
+    readonly id: string;
+    readonly label: string;
+    readonly link?: CellLink;
+};
+/** Runtime-only like RuntimeCellLink; undefined means the cell uses its single renderer. */
+export type RuntimeCellLinkItems = (value: unknown, row?: Readonly<Record<string, unknown>>) => readonly CellLinkItem[] | undefined;
+/** How a list cell shows a FileRef value (id or id array). */
+export type ListColumnFileDisplay = {
+    readonly kind: "image";
+    readonly variant?: string;
+} | {
+    readonly kind: "file";
+};
+export type ListColumnViewModel = {
+    readonly field: string;
+    readonly label: string;
+    readonly type: string;
+    readonly renderer?: FieldRenderer | RuntimeRenderer;
+    readonly linkFor?: RuntimeCellLink;
+    readonly linkItemsFor?: RuntimeCellLinkItems;
+    readonly sortable: boolean;
+    /** Only for `type: "select"` or `type: "multiSelect"` — translated option
+     *  labels keyed by raw value. The renderer renders `optionLabels[value]`
+     *  instead of humanizeSlug when present. Convention key:
+     *  `<feature>:entity:<entity>:field:<field>:option:<value>`. */
+    readonly optionLabels?: Readonly<Record<string, string>>;
+    /** Only for `type: "select"` — declared tone per raw option value. */
+    readonly optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>;
+    /** Only for `type: "reference"` — referenced entity name for the bulk
+     *  lookup in the renderer (`<refFeature>:query:<refEntity>:list`). */
+    readonly refEntity?: string;
+    /** Only for `type: "reference"` — name of the feature the referenced
+     *  entity lives in. Default = current feature. Cross-feature via the
+     *  qualified form ("feature:entity") on ReferenceFieldDef. */
+    readonly refFeature?: string;
+    /** Only for `type: "reference"` — which field of the referenced entity
+     *  appears as the display value in the cell (default "id"). */
+    readonly refLabelField?: string;
+    /** Set by the caller at runtime (not schema-derived) to emphasize one
+     *  column — e.g. the currently selected base-year column in a
+     *  multi-year statement grid. DataTable renders it with a distinct
+     *  header/cell background. */
+    readonly highlighted?: boolean;
+    /** Mirrors `ListColumnSpec.hideOnNarrow`: card layout skips the column. */
+    readonly hideOnNarrow?: boolean;
+    /** Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default
+     *  `true`). `false` renders without thousands-separators (e.g. a model
+     *  year). */
+    readonly grouping?: boolean;
+    /** Set for file/image columns: from the entity field type, or from a
+     *  `{ format: "image" | "file" }` renderer. The cell shows a thumbnail or the
+     *  file name instead of the FileRef UUID. */
+    readonly fileDisplay?: ListColumnFileDisplay;
+};
+export type ListRowViewModel = {
+    readonly id: string;
+    readonly values: Readonly<Record<string, unknown>>;
+};
+export type ListViewModel = {
+    readonly screenId: string;
+    readonly entityName: string;
+    readonly columns: readonly ListColumnViewModel[];
+    readonly rows: readonly ListRowViewModel[];
+    readonly slots?: ScreenSlots;
+    readonly isEmpty: boolean;
+};
+export type EmbeddedListCellViewModel = {
+    readonly field: string;
+    readonly label: string;
+    readonly type: "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp";
+    readonly required: boolean;
+    /** Only for `type: "select"`. */
+    readonly options?: readonly string[];
+    readonly optionLabels?: Readonly<Record<string, string>>;
+    /** Only for `type: "select"`; `"radio"` renders segmented buttons instead of a dropdown. */
+    readonly display?: "radio" | "dropdown";
+    /** Cell is shown but not editable (`EditFieldSpec.embeddedList.readOnlyCells`). */
+    readonly readOnly?: boolean;
+    /** Only for `type: "reference"`. */
+    readonly refEntity?: string;
+    readonly refFeature?: string;
+    readonly refLabelField?: string;
+    readonly refOptionsQuery?: string;
+    /** Only for `type: "decimal"`. */
+    readonly scale?: number;
+};
+export type EditFieldViewModel = {
+    readonly field: string;
+    readonly label: string;
+    readonly type: string;
+    readonly value: unknown;
+    readonly visible: boolean;
+    readonly readOnly: boolean;
+    readonly required: boolean;
+    readonly span?: number;
+    readonly renderer?: FieldRenderer;
+    /** Set for `type: "select"` and `type: "multiSelect"` — the allowed
+     *  values. The renderer uses these as dropdown/combobox options.
+     *  Source is SelectFieldDef.options / MultiSelectFieldDef.options on
+     *  the EntityDefinition. */
+    readonly options?: readonly string[];
+    /** Set for `type: "select"` and `type: "multiSelect"` — translated
+     *  labels per option, keyed by raw value. The renderer shows
+     *  `optionLabels[value]` as the dropdown/combobox label instead of the
+     *  raw value. Convention key:
+     *  `<feature>:entity:<entity>:field:<field>:option:<value>`. */
+    readonly optionLabels?: Readonly<Record<string, string>>;
+    /** Set for `type: "select"` when SelectFieldDef.optionsQuery is set: the
+     *  renderer loads the options from this query (`{ rows: { value, label,
+     *  description?, group? }[] }`, labels verbatim) instead of `options`. `payload`
+     *  is optionsQueryPayload (`{ field }` refs are resolved by the renderer against
+     *  the live form values), `{}` when absent. */
+    readonly selectOptionsQuery?: {
+        readonly query: string;
+        readonly payload: OptionsQueryPayload;
+    };
+    /** Set for `type: "select"` / `"multiSelect"` when optionsAvailabilityQuery is set:
+     *  the renderer loads `{ rows: { value, disabled?, hint? }[] }` from this query and
+     *  merges it onto `options`. `payload` is optionsQueryPayload, `{}` when absent
+     *  (always `{}` for multiSelect). */
+    readonly selectOptionsAvailabilityQuery?: {
+        readonly query: string;
+        readonly payload: OptionsQueryPayload;
+    };
+    /** Set for `type: "multiSelect"` when MultiSelectFieldDef.display is
+     *  "checkboxes" — the renderer shows a checkbox grid with a select-all
+     *  toggle instead of the default combobox dropdown. Set for
+     *  `type: "select"` when SelectFieldDef.display is "radio" or "dropdown" —
+     *  the renderer then skips its own radio-vs-dropdown heuristic. */
+    readonly display?: "checkboxes" | "dropdown" | "radio";
+    /** Set for `type: "multiSelect"` when MultiSelectFieldDef.columns is
+     *  defined — column count for the checkbox grid at the widest breakpoint.
+     *  Ignored unless `display` is "checkboxes". */
+    readonly columns?: 1 | 2 | 3 | 4;
+    /** Set for `type: "multiSelect"` when MultiSelectFieldDef.maxRows is
+     *  defined — grid rows visible before the checkbox grid becomes
+     *  scrollable. Ignored unless `display` is "checkboxes". */
+    readonly maxRows?: number;
+    /** For `type: "text"`, set when TextFieldDef.multiline is true — the
+     *  renderer then renders a textarea instead of a single-line input.
+     *  `type: "longText"` always renders a textarea regardless of this
+     *  value; here it only carries an optional `{ rows }` override.
+     *  `true` = default rows, `{ rows }` = explicit height. */
+    readonly multiline?: boolean | {
+        readonly rows?: number;
+    };
+    /** From TextFieldDef.format — `password` makes the renderer mask the input. */
+    readonly format?: "email" | "url" | "phone" | "password" | "month";
+    /** From TextFieldDef.autoComplete — HTML autocomplete token for the text input. */
+    readonly autoComplete?: string;
+    /** From TextFieldDef.writeOnly — value is `true` (set) / `null` (empty), never plaintext. */
+    readonly writeOnly?: true;
+    /** From the field's `sensitive: true` — the value must not leave the form (drafts, URL prefill). */
+    readonly sensitive?: true;
+    /** Only set for `type: "timestamp"` when TimestampFieldDef.locatedBy
+     *  exists — wall-clock time without offset. The renderer then emits
+     *  local time without `Z` instead of a UTC instant. */
+    readonly wallClock?: boolean;
+    /** Only for `type: "date" | "timestamp"` — date bounds (ISO) and
+     *  format/locale override from the FieldDefinition. The renderer limits
+     *  the picker with them; write validation runs separately via Zod. */
+    readonly min?: string;
+    readonly max?: string;
+    readonly dateLocale?: string;
+    /** Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default
+     *  `true`). `false` renders without thousands-separators (e.g. a model
+     *  year). */
+    readonly grouping?: boolean;
+    /** Only set for `type: "reference"`.
+     *  The referenced entity (short, without feature prefix). The renderer
+     *  builds the query QN as `<refFeature>:query:<refEntity>:list`. */
+    readonly refEntity?: string;
+    /** Only set for `type: "reference"` — name of the feature the
+     *  referenced entity lives in. Same-feature default = current
+     *  feature. Cross-feature is detected via "feature:entity" on
+     *  ReferenceFieldDef.entity. */
+    readonly refFeature?: string;
+    /** Only set for `type: "reference"` — which field of the referenced
+     *  entity appears as the display label in the dropdown. Default: "id". */
+    readonly refLabelField?: string;
+    /** Only for `type: "reference"` — query handler QN the picker sources its
+     *  options from (fw#2780), replacing the referenced entity's list handler.
+     *  Rows carry `{ id, label }`; `refLabelField` is then unused for the
+     *  picker but still drives list cells. */
+    readonly refOptionsQuery?: string;
+    /** Only for `type: "reference"` — multi mode:
+     *  the value is a UUID array, the renderer mounts a multi-combobox with tags. */
+    readonly refMultiple?: boolean;
+    /** Only for `type: "file" | "image"` — allowed extensions/MIME (e.g.
+     *  ["jpg","png"]) + max size ("5mb"). The renderer sets the `accept`
+     *  attribute and shows the limit; validation runs server-side in the
+     *  upload endpoint against the field def. */
+    readonly accept?: readonly string[];
+    readonly maxSize?: string;
+    /** Only for `type: "files" | "images"` — upper bound on list length. */
+    readonly maxCount?: number;
+    /** Only for `type: "file" | "image"` — entity name + field name for the
+     *  upload POST (`/api/files`), so the endpoint can check maxSize/accept
+     *  against the right field def. */
+    readonly entityType?: string;
+    readonly fieldName?: string;
+    /** Record being edited (update mode only). Sent with the upload so the
+     *  FileRef is attached to the record. */
+    readonly entityId?: string;
+    /** Only for `type: "image"` and `"images"` — the variant name the preview requests
+     *  (`/api/files/:id/variant/:name`) instead of the original. The FIRST
+     *  variant declared on the field def wins; a spec may legitimately carry
+     *  neither `size` nor `maxEdge` (format-/blur-only), so "the smallest one"
+     *  is not a rule that always has an answer. Absent when the field declares
+     *  no variants — the preview then loads the original. */
+    readonly imageVariant?: string;
+    /** Only for `type: "image"` — forwarded to the file input's `capture`
+     *  attribute so a phone opens the camera instead of the file picker. */
+    readonly capture?: "environment" | "user";
+    /** Closed FieldIconKey from EditFieldSpec.icon (FIELD_ICONS registry). */
+    readonly icon?: FieldIconKey;
+    /** From EditFieldSpec.placeholder, already translated — hint shown while the input is empty. */
+    readonly placeholder?: string;
+    /** From EditFieldSpec.prefix / suffix. A string affix is already translated;
+     *  a `{ field }` affix stays a reference, the renderer reads it from the live form values. */
+    readonly prefix?: FieldAffix;
+    readonly suffix?: FieldAffix;
+    /** From EditFieldSpec.fillAction, `label` already translated. */
+    readonly fillAction?: FieldFillAction;
+    /** Only set for an embedded-LIST field (`multiple: true`) — the per-cell
+     *  metadata the renderer needs to draw each column/cell. Absent for a
+     *  plain (non-list) embedded field. */
+    readonly embeddedListCells?: readonly EmbeddedListCellViewModel[];
+    /** Minimum row count for the embedded list. From EmbeddedFieldDef.minItems. */
+    readonly embeddedListMinItems?: number;
+    /** Maximum row count for the embedded list. From EmbeddedFieldDef.maxItems. */
+    readonly embeddedListMaxItems?: number;
+    /** Sub-field name → how to compute its cell from other sub-fields of the
+     *  same row. From EmbeddedFieldDef.derived. */
+    readonly embeddedListDerived?: Readonly<Record<string, {
+        readonly op: "multiply" | "sum" | "subtract" | "percent";
+        readonly from: readonly string[];
+    }>>;
+    /** Numeric sub-field names to sum in a totals row. From EmbeddedFieldDef.totals. */
+    readonly embeddedListTotals?: readonly string[];
+    /** No add, remove, duplicate or move; cells stay editable. From
+     *  EditFieldSpec.embeddedList.fixedRows. */
+    readonly embeddedListFixedRows?: boolean;
+    /** Currency for the whole embedded list's money cells and totals row —
+     *  currency lives on the head aggregate (EntityDefinition.defaultCurrency),
+     *  not per row. Falls back to "EUR" when the entity has no defaultCurrency. */
+    readonly embeddedListCurrency?: string;
+    /** Only set for a plain (non-list, non-embedded) `type: "money"` field —
+     *  same source as embeddedListCurrency (EntityDefinition.defaultCurrency,
+     *  falls back to "EUR"). The renderer needs this to build the payload's
+     *  `{amount, currency}` shape (kumiko-framework#1923). */
+    readonly currency?: string;
+    /** Only set for `type: "number"` when NumberFieldDef.unit is set — a static
+     *  suffix string, or a sibling-field reference the renderer resolves against
+     *  the live row values. Display-only, never converts the stored number. */
+    readonly unit?: string | {
+        readonly field: string;
+    };
+};
+export type EditSectionViewModel = EditFieldsSectionViewModel | EditExtensionSectionViewModel | EditRelatedListSectionViewModel | EditWriteFormSectionViewModel;
+export type EditFieldsSectionViewModel = {
+    readonly kind: "fields";
+    /** From `EditFieldsSection.id`. The boot-validator makes it mandatory under
+     *  `layout.mode: "tabs"` so the tab strip has a stable key per tab; other
+     *  layouts leave it unset. */
+    readonly id?: string;
+    /** False when the section has fields but none of them is visible.
+     *  The renderer then draws nothing, but the section stays in the array
+     *  (key stability). */
+    readonly visible: boolean;
+    /** Set when every declared field was hidden by the create handler's
+     *  `excludeFields`. Unlike a declared-empty section (review step), the
+     *  renderer must not give it a tab or wizard step. */
+    readonly emptiedByWriteExclusion?: boolean;
+    /** Optional — eine titellose Section rendert nur ihre Felder (flache Form). */
+    readonly title?: string;
+    /** Translated help text under the block heading, from
+     *  `EditFieldsSection.description`. Renders even without `title`. */
+    readonly description?: string;
+    /** Translated `EditFieldsSection.subtitle` (wizard step rail / up-next box). */
+    readonly subtitle?: string;
+    readonly columns: number;
+    readonly fields: readonly EditFieldViewModel[];
+    /** From `EditFieldsSection.groups` — each entry's `fields` are the same
+     *  view-model objects as `fields` above, re-grouped (not recomputed). */
+    readonly groups?: readonly {
+        readonly title: string;
+        readonly columns: number;
+        readonly fields: readonly EditFieldViewModel[];
+    }[];
+    /** From `EditFieldsSection.icon` — closed IconKey vocabulary, renders
+     *  left of the title. No effect without `title`. */
+    readonly icon?: IconKey;
+    /** From `EditFieldsSection.actions` — rendered in the Section's
+     *  title row, same slot as the projectionDetail head card's actions. */
+    readonly actions?: readonly RowAction[];
+};
+export type EditExtensionSectionViewModel = {
+    readonly kind: "extension";
+    /** From `EditExtensionSection.id` — same tab-strip role as on a "fields"
+     *  section, see EditFieldsSectionViewModel.id. */
+    readonly id?: string;
+    readonly title: string;
+    readonly component: PlatformComponent;
+    readonly contributesToFormSubmit: boolean;
+    /** Section-declared override — see `EditExtensionSection.entityName`. */
+    readonly entityName?: string;
+    /** From `EditExtensionSection.actions`. */
+    readonly actions?: readonly RowAction[];
+};
+export type EditRelatedListSectionViewModel = {
+    readonly kind: "relatedList";
+    readonly title: string;
+    readonly query: string;
+    readonly parentParam?: string;
+    readonly parentFilter?: {
+        readonly field: string;
+    };
+    readonly columns: readonly ListColumnSpec[];
+    readonly entity?: string;
+    readonly description?: string;
+    /** Untranslated plural-forms key, resolved with the row count by the list footer. */
+    readonly itemNoun?: string;
+    readonly pageSize?: number;
+    readonly defaultSort?: ListSortSpec;
+    readonly searchable?: boolean;
+    readonly facets?: readonly ListFacetSpec[];
+    readonly rowClick?: {
+        readonly entity: string;
+        readonly idColumn?: string;
+    };
+    readonly rowActions?: readonly RowAction[];
+    readonly rowActionMode?: RowActionMode;
+    readonly groupBy?: RelatedListGroupBy;
+    readonly rowTone?: RelatedListRowTone;
+    readonly toolbarActions?: readonly RelatedListToolbarAction[];
+    /** From `EditRelatedListSection.actions` — rendered in the
+     *  Section's title row, distinct from `toolbarActions` (which render
+     *  above the table itself). */
+    readonly actions?: readonly RowAction[];
+    /** From `EditRelatedListSection.emptyState` — forwarded to the
+     *  DataTable's `emptyState` prop when the section has zero rows. */
+    readonly emptyState?: {
+        readonly title: string;
+        readonly description?: string;
+        readonly action?: RowAction;
+    };
+};
+export type EditWriteFormSectionViewModel = {
+    readonly kind: "writeForm";
+    readonly title?: string;
+    readonly description?: string;
+    readonly columns: number;
+    readonly fields: readonly EditFieldViewModel[];
+    readonly icon?: IconKey;
+    readonly handler: string;
+    readonly submitLabel?: string;
+    /** From `EditWriteFormSection.actions`. */
+    readonly actions?: readonly RowAction[];
+};
+export type EditViewModel = {
+    readonly screenId: string;
+    readonly entityName: string;
+    readonly id: string | null;
+    readonly sections: readonly EditSectionViewModel[];
+    readonly slots?: ScreenSlots;
+};
+export type Translate = (key: string, params?: Readonly<Record<string, unknown>>) => string;
+export type FieldConditionCtx = unknown;
+export type { EditFieldSpec, EditSectionSpec, FieldRenderer, ListColumnSpec, ScreenSlots };

package/dist/headless/view-model/types.js

@@ -0,0 +1 @@
+export {};

package/dist/hooks/use-ai-text.d.ts

@@ -1,4 +1,4 @@
-import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import type { DispatcherError } from "../headless/index.ts";
 export declare const AI_TEXT_RUN_QN = "ai-text:query:run";
 export type AiTextMode = "complete" | "correct" | "translate" | "rewrite";
 export type AiTextRewriteStyle = "formal" | "casual" | "concise" | "expand";

package/dist/hooks/use-form.d.ts

@@ -1,4 +1,4 @@
-import type { FormController, FormControllerOptions, FormSnapshot, FormValues } from "@cosmicdrift/kumiko-headless";
+import type { FormController, FormControllerOptions, FormSnapshot, FormValues } from "../headless/index.ts";
 export type UseFormOptions<TValues extends FormValues, TCtx = unknown> = FormControllerOptions<TValues, TCtx>;
 export type UseFormResult<TValues extends FormValues> = {
     readonly controller: FormController<TValues>;

package/dist/hooks/use-form.js

@@ -1,6 +1,6 @@
-import { createFormController } from "@cosmicdrift/kumiko-headless";
 import { useMemo, useSyncExternalStore } from "react";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
+import { createFormController } from "../headless/index.js";
 export function useForm(options) {
     // Optional: a form with no `submit` config (or one with an explicit
     // dispatcher) never needs the ambient one, and mounting without a

package/dist/hooks/use-mutation.d.ts

@@ -1,4 +1,4 @@
-import type { DispatcherError, WriteResult } from "@cosmicdrift/kumiko-headless";
+import type { DispatcherError, WriteResult } from "../headless/index.ts";
 export type UseMutationResult<TData> = {
     readonly mutate: (payload: unknown) => Promise<WriteResult<TData>>;
     readonly pending: boolean;