@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

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

@@ -0,0 +1,501 @@
+import { availableSelectOptions, evalFieldCondition, isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, parseRefTarget, sectionFieldSpecs, WRITE_FORM_SECTION_ENTITY, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { buildOptionLabels, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, } from "./list.js";
+// Resolves a writeForm section's own fieldDefs/fields through the same
+// per-field pipeline as a plain fields section, by reusing the pipeline
+// itself rather than duplicating it: wrap fieldDefs/fields as a throwaway
+// entityEdit screen (same "synthesize a pseudo-entity" idiom as the shims in
+// packages/renderer/src/app/*-shim.ts) and recurse into computeEditViewModel
+// once. Split out of computeEditViewModel's section-map to keep that
+// function's own complexity from absorbing this branch's decision points.
+function computeWriteFormSectionViewModel(sectionSpec, screenId, values, translate, featureName) {
+    const innerEntity = { fields: sectionSpec.fieldDefs };
+    const innerScreen = {
+        id: `${screenId}:${sectionSpec.id ?? "write-form"}`,
+        type: "entityEdit",
+        entity: WRITE_FORM_SECTION_ENTITY,
+        layout: {
+            sections: [{ kind: "fields", fields: sectionSpec.fields, columns: sectionSpec.columns }],
+        },
+    };
+    const inner = computeEditViewModel({
+        screen: innerScreen,
+        entity: innerEntity,
+        values,
+        translate,
+        featureName,
+    });
+    const innerSection = inner.sections[0];
+    const fields = innerSection?.kind === "fields" ? innerSection.fields : [];
+    return {
+        kind: "writeForm",
+        ...(sectionSpec.title !== undefined && { title: translate(sectionSpec.title) }),
+        ...(sectionSpec.description !== undefined && {
+            description: translate(sectionSpec.description),
+        }),
+        columns: sectionSpec.columns ?? 1,
+        fields,
+        ...(sectionSpec.icon !== undefined && { icon: sectionSpec.icon }),
+        handler: sectionSpec.handler,
+        ...(sectionSpec.submitLabel !== undefined && {
+            submitLabel: translate(sectionSpec.submitLabel),
+        }),
+        ...(sectionSpec.actions !== undefined && { actions: sectionSpec.actions }),
+    };
+}
+function wasEmptiedByWriteExclusion(declaredFieldSpecs, remainingFields) {
+    return declaredFieldSpecs.length > 0 && remainingFields.length === 0;
+}
+// relatedList runs its own query — nothing here to resolve against
+// entity/values, the spec passes through verbatim (fw#2166).
+export function computeRelatedListSectionViewModel(sectionSpec, translate) {
+    return {
+        kind: "relatedList",
+        title: translate(sectionSpec.title),
+        query: sectionSpec.query,
+        ...(sectionSpec.parentParam !== undefined && { parentParam: sectionSpec.parentParam }),
+        ...(sectionSpec.parentFilter !== undefined && { parentFilter: sectionSpec.parentFilter }),
+        columns: sectionSpec.columns,
+        ...(sectionSpec.entity !== undefined && { entity: sectionSpec.entity }),
+        ...(sectionSpec.description !== undefined && {
+            description: translate(sectionSpec.description),
+        }),
+        ...(sectionSpec.itemNoun !== undefined && { itemNoun: sectionSpec.itemNoun }),
+        ...(sectionSpec.pageSize !== undefined && { pageSize: sectionSpec.pageSize }),
+        ...(sectionSpec.defaultSort !== undefined && { defaultSort: sectionSpec.defaultSort }),
+        ...(sectionSpec.searchable !== undefined && { searchable: sectionSpec.searchable }),
+        ...(sectionSpec.facets !== undefined && { facets: sectionSpec.facets }),
+        ...(sectionSpec.rowClick !== undefined && { rowClick: sectionSpec.rowClick }),
+        ...(sectionSpec.rowActions !== undefined && { rowActions: sectionSpec.rowActions }),
+        ...(sectionSpec.rowActionMode !== undefined && { rowActionMode: sectionSpec.rowActionMode }),
+        ...(sectionSpec.groupBy !== undefined && { groupBy: sectionSpec.groupBy }),
+        ...(sectionSpec.rowTone !== undefined && { rowTone: sectionSpec.rowTone }),
+        ...(sectionSpec.toolbarActions !== undefined && { toolbarActions: sectionSpec.toolbarActions }),
+        ...(sectionSpec.actions !== undefined && { actions: sectionSpec.actions }),
+        ...(sectionSpec.emptyState !== undefined && {
+            emptyState: {
+                title: translate(sectionSpec.emptyState.title),
+                ...(sectionSpec.emptyState.description !== undefined && {
+                    description: translate(sectionSpec.emptyState.description),
+                }),
+                // Action stays untranslated, same convention as rowActions/
+                // toolbarActions above — the renderer's row-actions builder
+                // translates `action.label` at button-build time.
+                ...(sectionSpec.emptyState.action !== undefined && {
+                    action: sectionSpec.emptyState.action,
+                }),
+            },
+        }),
+    };
+}
+function translateAffix(affix, translate) {
+    return typeof affix === "string" ? translate(affix) : affix;
+}
+function deriveFieldAffixHints(normalized, translate) {
+    return {
+        ...(normalized.placeholder !== undefined && { placeholder: translate(normalized.placeholder) }),
+        ...(normalized.prefix !== undefined && {
+            prefix: translateAffix(normalized.prefix, translate),
+        }),
+        ...(normalized.suffix !== undefined && {
+            suffix: translateAffix(normalized.suffix, translate),
+        }),
+        ...(normalized.fillAction !== undefined && {
+            fillAction: { ...normalized.fillAction, label: translate(normalized.fillAction.label) },
+        }),
+    };
+}
+function deriveSelectOptionsQuery(fieldDef) {
+    return fieldDef.type === "select" && fieldDef.optionsQuery !== undefined
+        ? {
+            selectOptionsQuery: {
+                query: fieldDef.optionsQuery,
+                payload: fieldDef.optionsQueryPayload ?? {},
+            },
+        }
+        : {};
+}
+function deriveSelectOptionsAvailabilityQuery(fieldDef) {
+    if (fieldDef.type === "multiSelect") {
+        return fieldDef.optionsAvailabilityQuery !== undefined
+            ? {
+                selectOptionsAvailabilityQuery: { query: fieldDef.optionsAvailabilityQuery, payload: {} },
+            }
+            : {};
+    }
+    return fieldDef.type === "select" && fieldDef.optionsAvailabilityQuery !== undefined
+        ? {
+            selectOptionsAvailabilityQuery: {
+                query: fieldDef.optionsAvailabilityQuery,
+                payload: fieldDef.optionsQueryPayload ?? {},
+            },
+        }
+        : {};
+}
+// A stored value that conditionalOptions no longer allows stays listed, so the
+// form shows it (flagged on submit) instead of silently dropping it.
+function selectableOptions(fieldDef, fieldName, values) {
+    if (fieldDef.type === "multiSelect")
+        return fieldDef.options;
+    if (fieldDef.type !== "select")
+        return undefined;
+    if (!fieldDef.conditionalOptions)
+        return fieldDef.options;
+    const available = availableSelectOptions(fieldDef, values);
+    const current = values[fieldName];
+    return fieldDef.options.filter((option) => available.includes(option) || option === current);
+}
+function deriveSelectFieldHints(fieldDef, translate, featureName, entityName, fieldName, values) {
+    const options = selectableOptions(fieldDef, fieldName, values);
+    const optionLabels = options !== undefined
+        ? buildOptionLabels(translate, (value) => fieldOptionLabelKey(featureName, entityName, fieldName, value), options)
+        : undefined;
+    const declaredDisplay = fieldDef.type === "multiSelect" || fieldDef.type === "select" ? fieldDef.display : undefined;
+    // The renderer's heuristic counts options, so a filtered list would switch widgets with the discriminator.
+    const display = declaredDisplay ??
+        (fieldDef.type === "select" && fieldDef.conditionalOptions ? "dropdown" : undefined);
+    const columns = fieldDef.type === "multiSelect" ? fieldDef.columns : undefined;
+    const maxRows = fieldDef.type === "multiSelect" ? fieldDef.maxRows : undefined;
+    return {
+        ...deriveSelectOptionsQuery(fieldDef),
+        ...deriveSelectOptionsAvailabilityQuery(fieldDef),
+        ...(options !== undefined && { options }),
+        ...(optionLabels !== undefined && { optionLabels }),
+        ...(display !== undefined && { display }),
+        ...(columns !== undefined && { columns }),
+        ...(maxRows !== undefined && { maxRows }),
+    };
+}
+function deriveTextFieldHints(fieldDef) {
+    const multiline = fieldDef.type === "text" || fieldDef.type === "longText" ? fieldDef.multiline : undefined;
+    const format = fieldDef.type === "text" ? fieldDef.format : undefined;
+    const writeOnly = fieldDef.type === "text" && fieldDef.writeOnly === true;
+    const autoComplete = fieldDef.type === "text" ? fieldDef.autoComplete : undefined;
+    return {
+        ...(multiline !== undefined && { multiline }),
+        ...(autoComplete !== undefined && { autoComplete }),
+        ...(format !== undefined && { format }),
+        ...(writeOnly && { writeOnly: true }),
+        ...("sensitive" in fieldDef && fieldDef.sensitive === true && { sensitive: true }),
+    };
+}
+function deriveDateFieldHints(fieldDef) {
+    const wallClock = fieldDef.type === "timestamp" &&
+        fieldDef.locatedBy !== undefined
+        ? true
+        : undefined;
+    const dateBounds = fieldDef.type === "date" ||
+        fieldDef.type === "timestamp" ||
+        fieldDef.type === "locatedTimestamp"
+        ? fieldDef
+        : undefined;
+    return {
+        ...(wallClock !== undefined && { wallClock }),
+        ...(dateBounds?.min !== undefined && { min: dateBounds.min }),
+        ...(dateBounds?.max !== undefined && { max: dateBounds.max }),
+        ...(dateBounds?.locale !== undefined && { dateLocale: dateBounds.locale }),
+    };
+}
+function deriveNumericFieldHints(fieldDef, resolvedCurrency) {
+    const grouping = fieldDef.type === "number" ? fieldDef.grouping : undefined;
+    return {
+        ...(grouping !== undefined && { grouping }),
+        ...(fieldDef.type === "money" && { currency: resolvedCurrency }),
+        ...(fieldDef.type === "number" && fieldDef.unit !== undefined && { unit: fieldDef.unit }),
+    };
+}
+// Declared reference metadata (EditFieldSpec.refEntity) takes priority over
+// fieldDef.type — see computeEditViewModel's effectiveType, same reasoning.
+function deriveReferenceFieldHints(fieldDef, normalized, declaredRefTarget, featureName) {
+    const refRaw = declaredRefTarget === undefined && fieldDef.type === "reference"
+        ? fieldDef.entity
+        : undefined;
+    const refTarget = declaredRefTarget ?? (refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined);
+    const refLabelField = declaredRefTarget !== undefined
+        ? (normalized.refLabelField ?? "id")
+        : fieldDef.type === "reference"
+            ? (fieldDef.labelField ?? "id")
+            : undefined;
+    return {
+        ...(refTarget?.entityName !== undefined && { refEntity: refTarget.entityName }),
+        ...(refTarget?.featureName !== undefined && { refFeature: refTarget.featureName }),
+        ...(refLabelField !== undefined && { refLabelField }),
+        ...deriveReferenceMultiHints(fieldDef, declaredRefTarget),
+    };
+}
+// Declared reference metadata has no `multiple` or `optionsQuery` concept
+// (it targets row-meta/derived fields, always single-valued and resolved
+// through the target entity) — only a real ReferenceFieldDef carries them.
+function deriveReferenceMultiHints(fieldDef, declaredRefTarget) {
+    const ownReferenceDef = declaredRefTarget === undefined && fieldDef.type === "reference"
+        ? fieldDef
+        : undefined;
+    const refMultiple = ownReferenceDef === undefined ? undefined : (ownReferenceDef.multiple ?? false);
+    return {
+        ...(ownReferenceDef?.optionsQuery !== undefined && {
+            refOptionsQuery: ownReferenceDef.optionsQuery,
+        }),
+        ...(refMultiple !== undefined && { refMultiple }),
+    };
+}
+// file/image: entityType/fieldName travel with the upload POST so the
+// endpoint validates against the right field definition.
+function isFileFieldType(fieldDef) {
+    return (fieldDef.type === "file" ||
+        fieldDef.type === "image" ||
+        fieldDef.type === "files" ||
+        fieldDef.type === "images");
+}
+function deriveImageHints(fieldDef) {
+    if (fieldDef.type !== "image" && fieldDef.type !== "images")
+        return {};
+    const imageVariant = Object.keys(fieldDef.variants ?? {})[0];
+    return {
+        ...(imageVariant !== undefined && { imageVariant }),
+        ...(fieldDef.capture !== undefined && { capture: fieldDef.capture }),
+    };
+}
+function deriveFileFieldHints(fieldDef, entityName, fieldName, entityId) {
+    if (!isFileFieldType(fieldDef))
+        return {};
+    const maxCount = fieldDef.type === "files" || fieldDef.type === "images" ? fieldDef.maxCount : undefined;
+    return {
+        ...(fieldDef.accept !== undefined && { accept: fieldDef.accept }),
+        ...(fieldDef.maxSize !== undefined && { maxSize: fieldDef.maxSize }),
+        ...(maxCount !== undefined && { maxCount }),
+        entityType: entityName,
+        fieldName,
+        ...(entityId !== undefined && { entityId }),
+        ...deriveImageHints(fieldDef),
+    };
+}
+function deriveEmbeddedCellSelectHints(subField, translate, featureName, entityName, fieldName, subFieldName) {
+    if (subField.type !== "select")
+        return {};
+    const options = subField.options ?? [];
+    return {
+        options,
+        optionLabels: buildOptionLabels(translate, (value) => embeddedCellOptionLabelKey(featureName, entityName, fieldName, subFieldName, value), options),
+    };
+}
+function deriveEmbeddedCellReferenceHints(subField, featureName) {
+    if (subField.type !== "reference")
+        return {};
+    const target = subField.entity !== undefined ? parseRefTarget(subField.entity, featureName) : undefined;
+    return {
+        ...(target !== undefined && { refEntity: target.entityName, refFeature: target.featureName }),
+        ...(subField.labelField !== undefined && { refLabelField: subField.labelField }),
+        ...(subField.optionsQuery !== undefined && { refOptionsQuery: subField.optionsQuery }),
+    };
+}
+function buildEmbeddedListCell(subFieldName, subField, translate, featureName, entityName, fieldName, listSpec) {
+    return {
+        field: subFieldName,
+        label: translate(embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName)),
+        type: subField.type,
+        required: subField.required === true,
+        ...deriveEmbeddedCellSelectHints(subField, translate, featureName, entityName, fieldName, subFieldName),
+        ...deriveEmbeddedCellReferenceHints(subField, featureName),
+        ...(subField.type === "decimal" && subField.scale !== undefined && { scale: subField.scale }),
+        ...(subField.type === "select" &&
+            subField.display !== undefined && { display: subField.display }),
+        ...(listSpec?.readOnlyCells?.includes(subFieldName) === true && { readOnly: true }),
+    };
+}
+// Embedded-LIST field (`multiple: true`) — per-cell metadata for a renderer
+// to draw one row per array item (invoice-positions-style table). A plain
+// (non-list) embedded field emits none of this; the renderer tells the two
+// apart by whether embeddedListCells is set, not by `type` (which stays
+// "embedded" either way).
+function deriveEmbeddedListHints(fieldDef, translate, featureName, entityName, fieldName, resolvedCurrency, listSpec) {
+    const isEmbeddedList = fieldDef.type === "embedded" &&
+        fieldDef.multiple === true;
+    const embeddedListDef = isEmbeddedList
+        ? fieldDef
+        : undefined;
+    const embeddedListCells = embeddedListDef !== undefined
+        ? Object.entries(embeddedListDef.schema).map(([subFieldName, subField]) => buildEmbeddedListCell(subFieldName, subField, translate, featureName, entityName, fieldName, listSpec))
+        : undefined;
+    return {
+        ...(embeddedListCells !== undefined && { embeddedListCells }),
+        ...(embeddedListDef?.minItems !== undefined && {
+            embeddedListMinItems: embeddedListDef.minItems,
+        }),
+        ...(embeddedListDef?.maxItems !== undefined && {
+            embeddedListMaxItems: embeddedListDef.maxItems,
+        }),
+        ...(embeddedListDef?.derived !== undefined && {
+            embeddedListDerived: embeddedListDef.derived,
+        }),
+        ...(embeddedListDef?.totals !== undefined && {
+            embeddedListTotals: embeddedListDef.totals,
+        }),
+        // Currency lives on the head aggregate (entity.defaultCurrency), not per
+        // row — one value for the whole embedded list.
+        ...(embeddedListDef !== undefined && { embeddedListCurrency: resolvedCurrency }),
+        ...(embeddedListDef !== undefined &&
+            listSpec?.fixedRows === true && { embeddedListFixedRows: true }),
+    };
+}
+function buildExtensionSectionViewModel(sectionSpec, translate) {
+    const entityNameOverride = sectionSpec.entityName?.trim();
+    return {
+        kind: "extension",
+        ...(sectionSpec.id !== undefined && { id: sectionSpec.id }),
+        title: translate(sectionSpec.title),
+        component: sectionSpec.component,
+        contributesToFormSubmit: sectionSpec.contributesToFormSubmit === true,
+        // Blank override must fall back to the host value: the renderer's `??`
+        // would otherwise pass "" through to the mounted extension.
+        ...(entityNameOverride !== undefined &&
+            entityNameOverride.length > 0 && { entityName: entityNameOverride }),
+        ...(sectionSpec.actions !== undefined && { actions: sectionSpec.actions }),
+    };
+}
+// Pure transform from screen-def + entity-def + row-values to the flat
+// section/field tree the renderer draws. FieldConditions are evaluated here
+// so the renderer never re-runs them during React render.
+export function computeEditViewModel(input) {
+    const { screen, entity, values, translate, featureName, mode, entityId } = input;
+    const excludedFields = new Set(mode === undefined ? [] : screen.writeExcludedFields?.[mode]);
+    const isHiddenByExclusion = (fieldSpec) => mode === "create" && excludedFields.has(normalizeEditField(fieldSpec).field);
+    const sections = screen.layout.sections.map((sectionSpec) => {
+        if (isExtensionEditSection(sectionSpec)) {
+            return buildExtensionSectionViewModel(sectionSpec, translate);
+        }
+        if (isWriteFormEditSection(sectionSpec)) {
+            return computeWriteFormSectionViewModel(sectionSpec, screen.id, values, translate, featureName);
+        }
+        if (!isFieldsEditSection(sectionSpec)) {
+            return computeRelatedListSectionViewModel(sectionSpec, translate);
+        }
+        // `groups` flattens into the same per-field pipeline as plain `fields`;
+        // the group structure below just re-groups the computed views by name.
+        const declaredFieldSpecs = sectionFieldSpecs(sectionSpec);
+        const fields = declaredFieldSpecs
+            .filter((fieldSpec) => !isHiddenByExclusion(fieldSpec))
+            .map((fieldSpec) => {
+            const normalized = normalizeEditField(fieldSpec);
+            const fieldDef = entity.fields[normalized.field];
+            if (!fieldDef) {
+                throw new Error(`computeEditViewModel: screen "${screen.id}" references unknown field "${normalized.field}" on entity "${screen.entity}"`);
+            }
+            // Declared reference metadata (EditFieldSpec.refEntity) — for
+            // projectionDetail fields, which have no EntityDefinition field to
+            // carry a real "reference" type. Takes priority over fieldDef.type
+            // below so it also fires against the pseudo-entity that hardcodes
+            // every field as "text" (projection-detail-shim) — real entityEdit
+            // screens never set this, so their fieldDef.type === "reference"
+            // branch is unaffected.
+            // A real non-text field (e.g. a `reference` with `multiple`) keeps its own
+            // type and hints, as documented on EditFieldSpec.refEntity; the shim's
+            // pseudo-entity only ever declares "text".
+            const declaredRefTarget = normalized.refEntity !== undefined && fieldDef.type === "text"
+                ? parseRefTarget(normalized.refEntity, featureName)
+                : undefined;
+            const effectiveType = declaredRefTarget !== undefined ? "reference" : fieldDef.type;
+            const label = translate(screen.fieldLabels?.[normalized.field] ??
+                fieldLabelKey(featureName, screen.entity, normalized.field));
+            const visible = evalCondition(normalized.visible, true, values);
+            // `readOnly` (camelCase) is the name on both sides: EditFieldSpec
+            // in the engine, and the view-model emitted here. One convention
+            // through the stack beats translating at the boundary.
+            const readOnly = (mode === "update" && excludedFields.has(normalized.field)) ||
+                evalCondition(normalized.readOnly, false, values);
+            // `required` on the field-spec overrides the entity-default. A
+            // field that's required at the entity-level but marked required:
+            // false on the screen (e.g. a soft-onboarding wizard that
+            // collects less up-front) respects the screen override.
+            const entityRequired = fieldDef.required === true;
+            const required = evalCondition(normalized.required, entityRequired, values);
+            // ponytail: "EUR" mirrors DEFAULT_CURRENCIES[0] from
+            // framework/src/engine/field-helpers.ts — headless has no dependency
+            // on that module, so the literal is duplicated here instead of
+            // importing it just for one fallback string.
+            const resolvedCurrency = entity.defaultCurrency ?? "EUR";
+            const selectHints = deriveSelectFieldHints(fieldDef, translate, featureName, screen.entity, normalized.field, values);
+            const textHints = deriveTextFieldHints(fieldDef);
+            const dateHints = deriveDateFieldHints(fieldDef);
+            const numericHints = deriveNumericFieldHints(fieldDef, resolvedCurrency);
+            const referenceHints = deriveReferenceFieldHints(fieldDef, normalized, declaredRefTarget, featureName);
+            const fileHints = deriveFileFieldHints(fieldDef, screen.entity, normalized.field, entityId);
+            const embeddedListHints = deriveEmbeddedListHints(fieldDef, translate, featureName, screen.entity, normalized.field, resolvedCurrency, normalized.embeddedList);
+            const view = {
+                field: normalized.field,
+                label,
+                type: effectiveType,
+                value: values[normalized.field],
+                visible,
+                readOnly,
+                required,
+                ...(normalized.span !== undefined && { span: normalized.span }),
+                ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+                ...selectHints,
+                ...textHints,
+                ...dateHints,
+                ...numericHints,
+                ...referenceHints,
+                ...fileHints,
+                ...(normalized.icon !== undefined && { icon: normalized.icon }),
+                ...deriveFieldAffixHints(normalized, translate),
+                ...embeddedListHints,
+            };
+            return view;
+        });
+        // The boot-validator rejects declared-empty sections (screens.ts), but a
+        // create-excluded field list can still empty one here: then `visible` is false.
+        const visible = fields.some((field) => field.visible);
+        // Tabs mode renders this section as its own panel, where two columns reads
+        // better than the single-column default a stacked form keeps. Applies to
+        // entityEdit tabs as well since fw#3134, not just projectionDetail.
+        const defaultColumns = screen.layout.mode === "tabs" ? 2 : 1;
+        const groups = sectionSpec.groups
+            ?.map((group) => ({ ...group, fields: group.fields.filter((f) => !isHiddenByExclusion(f)) }))
+            .filter((group) => group.fields.length > 0)
+            .map((group) => ({
+            title: translate(group.title),
+            columns: group.columns ?? 2,
+            fields: group.fields.map((fieldSpec) => {
+                const fieldName = normalizeEditField(fieldSpec).field;
+                const fieldView = fields.find((f) => f.field === fieldName);
+                if (fieldView === undefined) {
+                    throw new Error(`computeEditViewModel: screen "${screen.id}" group "${group.title}" references field ` +
+                        `"${fieldName}" that failed to resolve.`);
+                }
+                return fieldView;
+            }),
+        }));
+        return {
+            kind: "fields",
+            ...(sectionSpec.id !== undefined && { id: sectionSpec.id }),
+            visible,
+            emptiedByWriteExclusion: wasEmptiedByWriteExclusion(declaredFieldSpecs, fields),
+            // Untitled section (flat form) → no h3; translate only when set.
+            ...(sectionSpec.title !== undefined && { title: translate(sectionSpec.title) }),
+            ...(sectionSpec.description !== undefined && {
+                description: translate(sectionSpec.description),
+            }),
+            ...(sectionSpec.subtitle !== undefined && { subtitle: translate(sectionSpec.subtitle) }),
+            columns: sectionSpec.columns ?? defaultColumns,
+            fields,
+            ...(groups !== undefined && { groups }),
+            ...(sectionSpec.icon !== undefined && { icon: sectionSpec.icon }),
+            ...(sectionSpec.actions !== undefined && { actions: sectionSpec.actions }),
+        };
+    });
+    const idValue = values["id"];
+    const id = typeof idValue === "string" ? idValue : null;
+    return {
+        screenId: screen.id,
+        entityName: screen.entity,
+        id,
+        sections,
+        ...(screen.slots && { slots: screen.slots }),
+    };
+}
+// Resolves a FieldCondition against the current row values.
+// `undefined` means "not declared" — caller substitutes the default.
+function evalCondition(condition, fallback, values) {
+    if (condition === undefined)
+        return fallback;
+    return evalFieldCondition(condition, values);
+}

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

@@ -0,0 +1,27 @@
+import type { EmbeddedDerivedCellDef } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FieldIssue } from "../dispatcher/index.ts";
+export type EmbeddedDerivedOp = EmbeddedDerivedCellDef["op"];
+export type { DerivedCellRoundingTarget } from "@cosmicdrift/kumiko-framework/ui-types";
+export { computeDerivedCellValue, roundDerivedCellValue, } from "@cosmicdrift/kumiko-framework/ui-types";
+/** Sums a numeric/money/decimal column across all rows. Non-numeric or
+ *  missing values count as 0. Money columns are minor-unit integers —
+ *  the sum stays in minor units, never rounds through a major-unit float. */
+export declare function sumEmbeddedListColumn(rows: readonly Readonly<Record<string, unknown>>[], field: string): number;
+export type EmbeddedListIssueGroups = {
+    /** Issues at exactly `listField` — e.g. min/max row-count violations. */
+    readonly listIssues: readonly FieldIssue[];
+    /** Issues at exactly `${listField}.${rowIndex}` — a row-level check
+     *  (e.g. "row incomplete") that isn't attributable to one cell. */
+    readonly rowIssues: Readonly<Record<number, readonly FieldIssue[]>>;
+    /** Issues at exactly `${listField}.${rowIndex}.${cellField}`, keyed
+     *  `${rowIndex}.${cellField}` (not the full path — the caller already
+     *  knows listField). */
+    readonly cellIssues: Readonly<Record<string, readonly FieldIssue[]>>;
+};
+/** Buckets a flat issues-by-path map (FormSnapshot.errors shape — see
+ *  packages/renderer/src/headless/form/zod-bridge.ts groupIssuesByPath) into the
+ *  three levels an embedded-list widget renders. Only keys that are
+ *  exactly `listField`, `listField.N`, or `listField.N.subfield` are
+ *  claimed; unrelated keys (other top-level fields, or deeper nesting
+ *  than this field ever produces) are ignored. */
+export declare function groupEmbeddedListIssues(allIssues: Readonly<Record<string, readonly FieldIssue[]>>, listField: string): EmbeddedListIssueGroups;

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

@@ -0,0 +1,63 @@
+// Canonical implementation moved to packages/framework/src/engine/embedded-derived.ts
+// (the write-schema preprocess needs it server-side too).
+export { computeDerivedCellValue, roundDerivedCellValue, } from "@cosmicdrift/kumiko-framework/ui-types";
+/** Sums a numeric/money/decimal column across all rows. Non-numeric or
+ *  missing values count as 0. Money columns are minor-unit integers —
+ *  the sum stays in minor units, never rounds through a major-unit float. */
+export function sumEmbeddedListColumn(rows, field) {
+    let sum = 0;
+    for (const row of rows) {
+        const value = row[field];
+        if (typeof value === "number" && Number.isFinite(value))
+            sum += value;
+    }
+    return sum;
+}
+/** Buckets a flat issues-by-path map (FormSnapshot.errors shape — see
+ *  packages/renderer/src/headless/form/zod-bridge.ts groupIssuesByPath) into the
+ *  three levels an embedded-list widget renders. Only keys that are
+ *  exactly `listField`, `listField.N`, or `listField.N.subfield` are
+ *  claimed; unrelated keys (other top-level fields, or deeper nesting
+ *  than this field ever produces) are ignored. */
+export function groupEmbeddedListIssues(allIssues, listField) {
+    const listIssues = [];
+    const rowIssues = {};
+    const cellIssues = {};
+    const prefix = `${listField}.`;
+    for (const [path, issues] of Object.entries(allIssues)) {
+        if (path === listField) {
+            listIssues.push(...issues);
+            continue;
+        }
+        if (!path.startsWith(prefix))
+            continue;
+        const rest = path.slice(prefix.length);
+        const segments = rest.split(".");
+        if (segments.length === 1) {
+            const rowIndex = parsePureRowIndex(segments[0]);
+            if (rowIndex === undefined)
+                continue;
+            rowIssues[rowIndex] = issues;
+            continue;
+        }
+        if (segments.length === 2) {
+            const rowIndex = parsePureRowIndex(segments[0]);
+            if (rowIndex === undefined)
+                continue;
+            const cellField = segments[1];
+            cellIssues[`${rowIndex}.${cellField}`] = issues;
+        }
+        // Deeper than `listField.N.subfield` — not a shape this field ever
+        // produces; ignore rather than misattribute to a cell.
+    }
+    return { listIssues, rowIssues, cellIssues };
+}
+function parsePureRowIndex(segment) {
+    if (segment === undefined || segment.length === 0)
+        return undefined;
+    for (const char of segment) {
+        if (char < "0" || char > "9")
+            return undefined;
+    }
+    return Number(segment);
+}

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

@@ -0,0 +1,7 @@
+export type { ComputeEditViewModelInput, EditFormMode } from "./edit.ts";
+export { computeEditViewModel, computeRelatedListSectionViewModel } from "./edit.ts";
+export type { DerivedCellRoundingTarget, EmbeddedDerivedOp, EmbeddedListIssueGroups, } from "./embedded-list.ts";
+export { computeDerivedCellValue, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./embedded-list.ts";
+export type { ComputeListViewModelInput } from "./list.ts";
+export { buildOptionLabels, computeListViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, } from "./list.ts";
+export type { CellLink, CellLinkItem, EditExtensionSectionViewModel, EditFieldSpec, EditFieldsSectionViewModel, EditFieldViewModel, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedListCellViewModel, FieldConditionCtx, FieldRenderer, ListColumnFileDisplay, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeCellLink, RuntimeCellLinkItems, RuntimeRenderer, ScreenSlots, Translate, } from "./types.ts";

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

@@ -0,0 +1,3 @@
+export { computeEditViewModel, computeRelatedListSectionViewModel } from "./edit.js";
+export { computeDerivedCellValue, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./embedded-list.js";
+export { buildOptionLabels, computeListViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, } from "./list.js";

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

@@ -0,0 +1,3 @@
+import type { FieldDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ListColumnFileDisplay, ListColumnViewModel } from "./types.ts";
+export declare function deriveListFileDisplay(fieldDef: FieldDefinition, renderer: ListColumnViewModel["renderer"]): ListColumnFileDisplay | undefined;

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

@@ -0,0 +1,27 @@
+function firstVariantKey(fieldDef) {
+    return Object.keys(fieldDef.variants ?? {})[0];
+}
+function fromFormatSpec(renderer) {
+    if (typeof renderer !== "object" || renderer === null || !("format" in renderer)) {
+        return undefined;
+    }
+    if (renderer.format === "file")
+        return { kind: "file" };
+    if (renderer.format !== "image")
+        return undefined;
+    return renderer.variant === undefined
+        ? { kind: "image" }
+        : { kind: "image", variant: renderer.variant };
+}
+function fromFieldType(fieldDef) {
+    if (fieldDef.type === "file" || fieldDef.type === "files")
+        return { kind: "file" };
+    if (fieldDef.type !== "image" && fieldDef.type !== "images")
+        return undefined;
+    const variant = firstVariantKey(fieldDef);
+    return variant === undefined ? { kind: "image" } : { kind: "image", variant };
+}
+// An explicit `{ format: "image" | "file" }` renderer wins over the field type.
+export function deriveListFileDisplay(fieldDef, renderer) {
+    return fromFormatSpec(renderer) ?? fromFieldType(fieldDef);
+}

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>>;