@cosmicdrift/kumiko-renderer 0.399.0 → 0.401.0

package/dist/components/render-edit-helpers.js

@@ -73,7 +73,7 @@ export function wizardStepKey(section, index) {
     return declaredId ?? section.title ?? `step-${index}`;
 }
 function isMoneyValue(value) {
-    return typeof value === "object" && value !== null && "amount" in value;
+    return typeof value === "object" && value !== null && ("amount" in value || "currency" in value);
 }
 // The seeds buildInitialValues writes for NULL columns of an existing record.
 function isEmptyFormValue(value) {
@@ -82,7 +82,7 @@ function isEmptyFormValue(value) {
     }
     if (Array.isArray(value))
         return value.length === 0;
-    return isMoneyValue(value) && value.amount === 0;
+    return isMoneyValue(value) && (value.amount === 0 || value.amount === undefined);
 }
 // select/boolean are excluded from the "holds user data" check: they are
 // often pre-filled (defaults, server-set values), so they say nothing about

package/dist/components/render-field-choice-inputs.js

@@ -25,7 +25,7 @@ export function renderSelectInput({ field, Input, onChange }, { common }) {
     // `display` is shared with multiSelect's "checkboxes", which is not a
     // select presentation — narrow to the two a select field can request.
     const display = field.display === "radio" || field.display === "dropdown" ? field.display : undefined;
-    return (_jsx(Input, { kind: "select", ...common, value: stringValue(field.value), onChange: (v) => onChange(v), options: selectOptions, ...(display !== undefined && { display }) }));
+    return (_jsx(Input, { kind: "select", ...common, value: stringValue(field.value), onChange: (v) => onChange(v), options: selectOptions, ...(display !== undefined && { display }), ...(field.optionTones !== undefined && { optionTones: field.optionTones }) }));
 }
 export function renderFileInput({ field, Input, onChange }, { common }) {
     const kind = field.type === "image" ? "image" : "file";

package/dist/components/use-reference-column-lookups.d.ts

@@ -0,0 +1,6 @@
+import { type PublishedReferenceChunk, type PublishedReferenceLookup, type ReferenceColumnSpec, type ReferenceLookupRequest } from "./render-list-reference-columns.ts";
+export declare function useReferenceColumnLookups(rows: readonly Readonly<Record<string, unknown>>[], referenceColumns: readonly ReferenceColumnSpec[]): {
+    referenceRequests: readonly ReferenceLookupRequest[];
+    handleLookupMap: (field: string, chunkIndex: number, lookup: PublishedReferenceChunk) => void;
+    referenceLookups: Record<string, PublishedReferenceLookup>;
+};

package/dist/components/use-reference-column-lookups.js

@@ -0,0 +1,36 @@
+import { useCallback, useMemo, useState } from "react";
+import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
+import { mergeChunkLookups, referenceIdChunks, } from "./render-list-reference-columns.js";
+// Bridge components (renderReferenceLookupBridges) publish each id chunk's
+// lookup through handleLookupMap; the merged result feeds enrichReferenceColumns.
+export function useReferenceColumnLookups(rows, referenceColumns) {
+    const referenceRequests = useMemo(() => referenceColumns.map((column) => ({
+        ...column,
+        idChunks: referenceIdChunks(rows, column.field, REFERENCE_LIST_LOOKUP_LIMIT),
+    })), [referenceColumns, rows]);
+    const [chunkLookups, setChunkLookups] = useState({});
+    const handleLookupMap = useCallback((field, chunkIndex, lookup) => {
+        setChunkLookups((prev) => {
+            // Skip the update when the lookup is identical. Otherwise the bridge
+            // would re-render and send the same map back until React entered
+            // an infinite loop.
+            const current = prev[field]?.[chunkIndex];
+            const unchanged = current?.map === lookup.map &&
+                current.complete === lookup.complete &&
+                current.idsKey === lookup.idsKey;
+            if (unchanged)
+                return prev;
+            return { ...prev, [field]: { ...prev[field], [chunkIndex]: lookup } };
+        });
+    }, []);
+    const referenceLookups = useMemo(() => {
+        const merged = {};
+        for (const request of referenceRequests) {
+            const lookup = mergeChunkLookups(request.idChunks, chunkLookups[request.field]);
+            if (lookup !== undefined)
+                merged[request.field] = lookup;
+        }
+        return merged;
+    }, [referenceRequests, chunkLookups]);
+    return { referenceRequests, handleLookupMap, referenceLookups };
+}

package/dist/components/use-render-list-columns.d.ts

@@ -1,7 +1,6 @@
 import type { EntityDefinition, EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import { type ScreenLinkResolver } from "../app/reference-link.ts";
 import type { ListColumnViewModel, ListViewModel, Translate } from "../headless/index.ts";
-import { type PublishedReferenceChunk, type ReferenceLookupRequest } from "./render-list-reference-columns.ts";
 export declare function withScreenLinks(columns: readonly ListColumnViewModel[], screen: EntityListScreenDefinition, resolveScreenLink: ScreenLinkResolver): readonly ListColumnViewModel[];
 type RenderListColumnsInput = {
     readonly screen: EntityListScreenDefinition;
@@ -11,8 +10,8 @@ type RenderListColumnsInput = {
     readonly translate: Translate;
 };
 export declare function useRenderListColumns(input: RenderListColumnsInput): {
-    referenceRequests: readonly ReferenceLookupRequest[];
-    handleLookupMap: (field: string, chunkIndex: number, lookup: PublishedReferenceChunk) => void;
+    referenceRequests: readonly import("./render-list-reference-columns.ts").ReferenceLookupRequest[];
+    handleLookupMap: (field: string, chunkIndex: number, lookup: import("./render-list-reference-columns.ts").PublishedReferenceChunk) => void;
     enrichedVm: Omit<ListViewModel, "columns"> & {
         columns: readonly ListColumnViewModel[];
     };

package/dist/components/use-render-list-columns.js

@@ -1,9 +1,9 @@
 import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
-import { useCallback, useMemo, useState } from "react";
+import { useMemo } from "react";
 import { useReferenceLinkResolver, useScreenLinkResolver, } from "../app/reference-link.js";
 import { computeListViewModel } from "../headless/index.js";
-import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
-import { enrichReferenceColumns, mergeChunkLookups, referenceIdChunks, selectReferenceColumns, } from "./render-list-reference-columns.js";
+import { enrichReferenceColumns, selectReferenceColumns } from "./render-list-reference-columns.js";
+import { useReferenceColumnLookups } from "./use-reference-column-lookups.js";
 // A column whose rows name their own target screen links each cell there.
 export function withScreenLinks(columns, screen, resolveScreenLink) {
     const linkFields = new Map();
@@ -38,34 +38,7 @@ export function useRenderListColumns(input) {
     // through onMap. Each bridge makes a constant number of hook calls (one),
     // and React manages its lifecycle when the schema changes via key.
     const referenceColumns = useMemo(() => selectReferenceColumns(vm.columns, featureName), [vm.columns, featureName]);
-    const referenceRequests = useMemo(() => referenceColumns.map((column) => ({
-        ...column,
-        idChunks: referenceIdChunks(rows, column.field, REFERENCE_LIST_LOOKUP_LIMIT),
-    })), [referenceColumns, rows]);
-    const [chunkLookups, setChunkLookups] = useState({});
-    const handleLookupMap = useCallback((field, chunkIndex, lookup) => {
-        setChunkLookups((prev) => {
-            // Skip the update when the lookup is identical. Otherwise the bridge
-            // would re-render and send the same map back until React entered
-            // an infinite loop.
-            const current = prev[field]?.[chunkIndex];
-            const unchanged = current?.map === lookup.map &&
-                current.complete === lookup.complete &&
-                current.idsKey === lookup.idsKey;
-            if (unchanged)
-                return prev;
-            return { ...prev, [field]: { ...prev[field], [chunkIndex]: lookup } };
-        });
-    }, []);
-    const referenceLookups = useMemo(() => {
-        const merged = {};
-        for (const request of referenceRequests) {
-            const lookup = mergeChunkLookups(request.idChunks, chunkLookups[request.field]);
-            if (lookup !== undefined)
-                merged[request.field] = lookup;
-        }
-        return merged;
-    }, [referenceRequests, chunkLookups]);
+    const { referenceRequests, handleLookupMap, referenceLookups } = useReferenceColumnLookups(rows, referenceColumns);
     const resolveReferenceLink = useReferenceLinkResolver();
     const resolveScreenLink = useScreenLinkResolver();
     const enrichedColumns = useMemo(() => withScreenLinks(enrichReferenceColumns({

package/dist/embedded-list-types.d.ts

@@ -0,0 +1,117 @@
+import type { SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FieldIssue } from "./headless/index.ts";
+/** Cell type for one column of an embedded-list field. Mirrors
+ *  EmbeddedListCellViewModel["type"] from `@cosmicdrift/kumiko-renderer/headless`. */
+export type EmbeddedListCellType = "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp" | "images" | "files";
+/** One column of an embedded-list table (one entry per key of the source
+ *  EmbeddedFieldDef's `schema`). */
+export type EmbeddedListColumn = {
+    readonly field: string;
+    readonly label: string;
+    readonly type: EmbeddedListCellType;
+    readonly required: boolean;
+    /** Read-only, value supplied by the caller (already computed from
+     *  sibling cells) — not directly user-editable. */
+    readonly derived: boolean;
+    /** Shown but not editable by the user; unlike `derived` it is not computed. */
+    readonly readOnly?: boolean;
+    /** Phone cards skip this column; the table still shows it. */
+    readonly hiddenInCard?: boolean;
+    /** Phone cards show the row's min/max (sub-field names) as a hint under this column's control. */
+    readonly cardLimits?: {
+        readonly min: string;
+        readonly max: string;
+    };
+    /** Phone cards render this column unlabeled beside the named column's control. */
+    readonly cardAttachedTo?: string;
+    /** Only for `type: "select"`. */
+    readonly options?: readonly string[];
+    readonly optionLabels?: Readonly<Record<string, string>>;
+    /** Only for `type: "select"`; `"radio"` renders segmented buttons, the
+     *  default is a dropdown. */
+    readonly display?: "radio" | "dropdown";
+    /** Only for `type: "reference"` — pre-fetched by the caller, ONE query
+     *  per column shared across every row (not one query per cell). */
+    readonly referenceOptions?: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly referenceLoading?: boolean;
+    /** Only for `type: "select"`; tone per option (selected segment, derived badge). */
+    readonly optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>;
+    /** Only for `type: "images" | "files"`. */
+    readonly capture?: "user" | "environment";
+    readonly maxCount?: number;
+    readonly accept?: readonly string[];
+    /** Per-row state, evaluated by the caller (conditions are engine logic the primitive must not import).
+     *  A hidden cell keeps its value but shows no control. */
+    readonly isHiddenInRow?: (row: Readonly<Record<string, unknown>>) => boolean;
+    readonly isRequiredInRow?: (row: Readonly<Record<string, unknown>>) => boolean;
+    /** Overrides `derived` per row: a conditional derived cell is editable on rows where it does not apply. */
+    readonly isDerivedInRow?: (row: Readonly<Record<string, unknown>>) => boolean;
+};
+/** One entry of an embedded-list totals row (e.g. an invoice's total
+ *  amount, summed across all rows by the caller). */
+export type EmbeddedListTotal = {
+    readonly field: string;
+    readonly label: string;
+    readonly value: number;
+    /** Set for labelled multi-column totals, which have no single column to
+     *  read the money type from. */
+    readonly money?: boolean;
+};
+/** Row-array + totals table for a `createEmbeddedListField` (invoice-
+ *  positions-style) field — structurally too different from `Input`'s
+ *  value/onChange union to fit there, so it's its own primitive, same as
+ *  `DataTable`. Controlled: the caller (the eventual form-field wrapper)
+ *  computes rows/derived values/issue groups and wires every callback;
+ *  this primitive only renders and reports interaction. */
+export type EmbeddedListInputProps = {
+    readonly id: string;
+    readonly columns: readonly EmbeddedListColumn[];
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly totals?: readonly EmbeddedListTotal[];
+    /** Currency for money cells and the totals row — one value for the whole
+     *  list (currency lives on the head aggregate, not the row). Web impl
+     *  falls back to "EUR" when absent. */
+    readonly currency?: string;
+    /** Whole-list read-only (e.g. a released invoice) — hides row-mutation
+     *  affordances and disables every cell. */
+    readonly disabled?: boolean;
+    /** Rows are fixed: no add, remove, duplicate or move; cells stay editable. */
+    readonly fixedRows?: boolean;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    /** Upload target of file cells: `entityType`/`entityId`/`fieldName` of the list, the column name is the `subField`. */
+    readonly uploadTarget?: {
+        readonly entityType: string;
+        readonly fieldName: string;
+        readonly entityId?: string;
+    };
+    /** Shown under the whole list (e.g. under the totals row). */
+    readonly listIssues?: readonly FieldIssue[];
+    /** Keyed by row index. */
+    readonly rowIssues?: Readonly<Record<number, readonly FieldIssue[]>>;
+    /** Keyed `${rowIndex}.${field}`. */
+    readonly cellIssues?: Readonly<Record<string, readonly FieldIssue[]>>;
+    readonly onCellChange: (rowIndex: number, field: string, value: unknown) => void;
+    readonly onAddRow: () => void;
+    readonly onRemoveRow: (rowIndex: number) => void;
+    readonly onDuplicateRow: (rowIndex: number) => void;
+    readonly onMoveRow: (fromIndex: number, toIndex: number) => void;
+    /** Tab/newline-delimited clipboard paste starting at (rowIndex,
+     *  columnIndex) — parsed to a 2D string grid by the Web impl (paste
+     *  events are a browser-only concept); undefined caller = no paste
+     *  handling wired up. */
+    readonly onPasteCells?: (rowIndex: number, columnIndex: number, grid: readonly (readonly string[])[]) => void;
+    readonly addLabel: string;
+    /** Accessible name of the (otherwise headerless) row-actions column. */
+    readonly actionsLabel: string;
+    readonly removeLabel: string;
+    readonly duplicateLabel: string;
+    readonly moveUpLabel: string;
+    readonly moveDownLabel: string;
+    readonly emptyLabel: string;
+    readonly emptyCtaLabel: string;
+    readonly testId?: string;
+};

package/dist/embedded-list-types.js

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

package/dist/headless/form/form-controller.js

@@ -62,6 +62,13 @@ function valuesDiff(current, initial) {
 // of being omitted — no validation error surfaces it, unlike the "" case.
 // Fixing that needs real per-field seed-tracking (which value was actually
 // user-set vs. defaulted), not just a wider strip predicate here.
+// The seed of an untouched optional money field (buildInitialValues); never a valid payload value.
+function isCurrencyOnlyMoney(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "currency" in value &&
+        !("amount" in value && value.amount !== undefined));
+}
 function stripUntouchedEmptyStrings(values, initial, forceIncludeEmpty) {
     const v = values; // @cast-boundary form-values
     const ini = initial; // @cast-boundary form-values
@@ -69,7 +76,8 @@ function stripUntouchedEmptyStrings(values, initial, forceIncludeEmpty) {
     for (const key of Object.keys(v)) {
         // Value-based seed strip, except keys previously submitted as "" after a
         // real clear — those must survive post-rebase submits.
-        if (!forceIncludeEmpty.has(key) && v[key] === "" && ini[key] === "") {
+        const untouchedEmptyString = !forceIncludeEmpty.has(key) && v[key] === "" && ini[key] === "";
+        if (untouchedEmptyString || isCurrencyOnlyMoney(v[key])) {
             out ??= { ...v };
             delete out[key];
         }

package/dist/headless/index.d.ts

@@ -12,4 +12,4 @@ export { pluralKey } from "./plural-key.ts";
 export type { Store, WritableStore } from "./store/index.ts";
 export { createStore, shallowEqual } from "./store/index.ts";
 export type { CellLink, CellLinkItem, ComputeEditViewModelInput, ComputeListViewModelInput, DerivedCellRoundingTarget, EditExtensionSectionViewModel, EditFieldSpec, EditFieldsSectionViewModel, EditFieldViewModel, EditFormMode, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedDerivedOp, EmbeddedListCellViewModel, EmbeddedListIssueGroups, FieldConditionCtx, FieldRenderer, ListColumnFileDisplay, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeCellLink, RuntimeCellLinkItems, RuntimeRenderer, ScreenSlots, Translate, } from "./view-model/index.ts";
-export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.ts";
+export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, withDerivedCells, } from "./view-model/index.ts";

package/dist/headless/index.js

@@ -7,4 +7,4 @@ export { applyFormatSpec, currencyDecimals, DOCUMENT_FALLBACK_CURRENCY, EMPTY_VA
 export { resolveNavigation } from "./nav/index.js";
 export { pluralKey } from "./plural-key.js";
 export { createStore, shallowEqual } from "./store/index.js";
-export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.js";
+export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, withDerivedCells, } from "./view-model/index.js";

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

@@ -1,5 +1,6 @@
-import { availableSelectOptions, evalFieldCondition, isExtensionEditSection, isFieldsEditSection, isFormDerivationInputMode, isUnusedFallbackOperand, isWriteFormEditSection, normalizeEditField, parseRefTarget, sectionFieldSpecs, WRITE_FORM_SECTION_ENTITY, } from "@cosmicdrift/kumiko-framework/ui-types";
-import { buildOptionLabels, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, } from "./list.js";
+import { availableSelectOptions, evalFieldCondition, isExtensionEditSection, isFieldRequired, isFieldsEditSection, isFieldVisible, isFormDerivationInputMode, isUnusedFallbackOperand, isWriteFormEditSection, normalizeEditField, parseRefTarget, sectionFieldSpecs, WRITE_FORM_SECTION_ENTITY, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { buildEmbeddedListCell } from "./embedded-list-cells.js";
+import { buildOptionLabels, 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
@@ -161,15 +162,22 @@ function selectableOptions(fieldDef, fieldName, values) {
     const current = values[fieldName];
     return fieldDef.options.filter((option) => available.includes(option) || option === current);
 }
+function deriveSelectDisplay(fieldDef) {
+    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);
+    return {
+        ...(display !== undefined && { display }),
+        ...(fieldDef.type === "select" &&
+            fieldDef.optionTones !== undefined && { optionTones: fieldDef.optionTones }),
+    };
+}
 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 {
@@ -177,7 +185,7 @@ function deriveSelectFieldHints(fieldDef, translate, featureName, entityName, fi
         ...deriveSelectOptionsAvailabilityQuery(fieldDef),
         ...(options !== undefined && { options }),
         ...(optionLabels !== undefined && { optionLabels }),
-        ...(display !== undefined && { display }),
+        ...deriveSelectDisplay(fieldDef),
         ...(columns !== undefined && { columns }),
         ...(maxRows !== undefined && { maxRows }),
     };
@@ -195,10 +203,6 @@ function deriveTextFieldHints(fieldDef) {
         ...("sensitive" in fieldDef && fieldDef.sensitive === true && { sensitive: true }),
     };
 }
-// files/images field defs carry no `required` property.
-function isRequiredByEntity(fieldDef) {
-    return "required" in fieldDef && fieldDef.required === true;
-}
 function deriveDateFieldHints(fieldDef) {
     const wallClock = fieldDef.type === "timestamp" && fieldDef.locatedBy !== undefined ? true : undefined;
     const dateBounds = fieldDef.type === "date" ||
@@ -287,48 +291,16 @@ function deriveFileFieldHints(fieldDef, entityName, fieldName, entityId, actionF
         ...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) {
+function deriveEmbeddedListHints(fieldDef, translate, featureName, entityName, fieldName, resolvedCurrency, listSpec, entityId) {
     const embeddedListDef = fieldDef.type === "embedded" && fieldDef.multiple === true ? fieldDef : undefined;
+    const cellContext = { translate, featureName, entityName, fieldName, listSpec };
     const embeddedListCells = embeddedListDef !== undefined
-        ? Object.entries(embeddedListDef.schema).map(([subFieldName, subField]) => buildEmbeddedListCell(subFieldName, subField, translate, featureName, entityName, fieldName, listSpec))
+        ? Object.entries(embeddedListDef.schema).map(([subFieldName, subField]) => buildEmbeddedListCell(subFieldName, subField, cellContext))
         : undefined;
     return {
         ...(embeddedListCells !== undefined && { embeddedListCells }),
@@ -349,6 +321,14 @@ function deriveEmbeddedListHints(fieldDef, translate, featureName, entityName, f
         ...(embeddedListDef !== undefined && { embeddedListCurrency: resolvedCurrency }),
         ...(embeddedListDef !== undefined &&
             listSpec?.fixedRows === true && { embeddedListFixedRows: true }),
+        ...(embeddedListCells?.some((cell) => cell.type === "images" || cell.type === "files") ===
+            true && {
+            embeddedListUploadTarget: {
+                entityType: entityName,
+                fieldName,
+                ...(entityId !== undefined && { entityId }),
+            },
+        }),
     };
 }
 function buildExtensionSectionViewModel(sectionSpec, translate) {
@@ -378,6 +358,17 @@ function isLockedByDerivation(derivation, values, field) {
         !isFormDerivationInputMode(derivation, values, field);
     return isDerivedAndLocked || isUnusedFallbackOperand(derivation, values, field);
 }
+// A screen-spec condition overrides the entity's own visibleWhen / required / requiredWhen.
+function isEditFieldVisible(normalized, fieldDef, values) {
+    return normalized.visible !== undefined
+        ? evalFieldCondition(normalized.visible, values)
+        : isFieldVisible(fieldDef, values);
+}
+function isEditFieldRequired(normalized, fieldDef, values) {
+    return normalized.required !== undefined
+        ? evalFieldCondition(normalized.required, values)
+        : isFieldRequired(fieldDef, values);
+}
 export function computeEditViewModel(input) {
     const { screen, entity, values, translate, featureName, mode, entityId, derivation, actionFormScreenQn, } = input;
     const excludedFields = new Set(mode === undefined ? [] : screen.writeExcludedFields?.[mode]);
@@ -419,7 +410,7 @@ export function computeEditViewModel(input) {
             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);
+            const visible = isEditFieldVisible(normalized, fieldDef, 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.
@@ -431,8 +422,7 @@ export function computeEditViewModel(input) {
             // 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 = isRequiredByEntity(fieldDef);
-            const required = !lockedByDerivation && evalCondition(normalized.required, entityRequired, values);
+            const required = !lockedByDerivation && isEditFieldRequired(normalized, fieldDef, 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
@@ -444,7 +434,7 @@ export function computeEditViewModel(input) {
             const numericHints = deriveNumericFieldHints(fieldDef, resolvedCurrency);
             const referenceHints = deriveReferenceFieldHints(fieldDef, normalized, declaredRefTarget, featureName);
             const fileHints = deriveFileFieldHints(fieldDef, screen.entity, normalized.field, entityId, actionFormScreenQn);
-            const embeddedListHints = deriveEmbeddedListHints(fieldDef, translate, featureName, screen.entity, normalized.field, resolvedCurrency, normalized.embeddedList);
+            const embeddedListHints = deriveEmbeddedListHints(fieldDef, translate, featureName, screen.entity, normalized.field, resolvedCurrency, normalized.embeddedList, entityId);
             const view = {
                 field: normalized.field,
                 label,

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

@@ -0,0 +1,12 @@
+import type { EmbeddedListEditSpec } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { EmbeddedSubFieldDef } from "@cosmicdrift/kumiko-types/fields";
+import type { EmbeddedListCellViewModel, Translate } from "./types.ts";
+type CellContext = {
+    readonly translate: Translate;
+    readonly featureName: string;
+    readonly entityName: string;
+    readonly fieldName: string;
+    readonly listSpec: EmbeddedListEditSpec | undefined;
+};
+export declare function buildEmbeddedListCell(subFieldName: string, subField: EmbeddedSubFieldDef, ctx: CellContext): EmbeddedListCellViewModel;
+export {};

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

@@ -0,0 +1,49 @@
+import { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
+import { buildOptionLabels, embeddedCellLabelKey, embeddedCellOptionLabelKey } from "./list.js";
+function selectHints(subField, subFieldName, ctx) {
+    if (subField.type !== "select")
+        return {};
+    return {
+        options: subField.options,
+        optionLabels: buildOptionLabels(ctx.translate, (value) => embeddedCellOptionLabelKey(ctx.featureName, ctx.entityName, ctx.fieldName, subFieldName, value), subField.options),
+        ...(subField.display !== undefined && { display: subField.display }),
+        ...(subField.optionTones !== undefined && { optionTones: subField.optionTones }),
+    };
+}
+function referenceHints(subField, featureName) {
+    if (subField.type !== "reference")
+        return {};
+    const target = parseRefTarget(subField.entity, featureName);
+    return {
+        refEntity: target.entityName,
+        refFeature: target.featureName,
+        ...(subField.labelField !== undefined && { refLabelField: subField.labelField }),
+        ...(subField.optionsQuery !== undefined && { refOptionsQuery: subField.optionsQuery }),
+    };
+}
+function fileHints(subField) {
+    if (subField.type !== "images" && subField.type !== "files")
+        return {};
+    return {
+        ...(subField.maxCount !== undefined && { maxCount: subField.maxCount }),
+        ...(subField.accept !== undefined && { accept: subField.accept }),
+        ...(subField.type === "images" &&
+            subField.capture !== undefined && { capture: subField.capture }),
+    };
+}
+export function buildEmbeddedListCell(subFieldName, subField, ctx) {
+    return {
+        field: subFieldName,
+        label: ctx.translate(embeddedCellLabelKey(ctx.featureName, ctx.entityName, ctx.fieldName, subFieldName)),
+        type: subField.type,
+        required: subField.required === true,
+        ...(subField.visibleWhen !== undefined && { visibleWhen: subField.visibleWhen }),
+        ...(subField.requiredWhen !== undefined && { requiredWhen: subField.requiredWhen }),
+        ...selectHints(subField, subFieldName, ctx),
+        ...referenceHints(subField, ctx.featureName),
+        ...(subField.type === "decimal" && subField.scale !== undefined && { scale: subField.scale }),
+        ...fileHints(subField),
+        ...(ctx.listSpec?.readOnlyCells?.includes(subFieldName) === true && { readOnly: true }),
+        ...(ctx.listSpec?.cardHiddenCells?.includes(subFieldName) === true && { hiddenInCard: true }),
+    };
+}

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

@@ -2,7 +2,7 @@ import type { EmbeddedDerivedCellDef } from "@cosmicdrift/kumiko-framework/ui-ty
 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";
+export { computeDerivedCellValue, roundDerivedCellValue, withDerivedCells, } 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. */

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

@@ -1,6 +1,6 @@
 // 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";
+export { computeDerivedCellValue, roundDerivedCellValue, withDerivedCells, } 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. */

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

@@ -1,7 +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 { computeDerivedCellValue, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, withDerivedCells, } 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

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

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

@@ -136,9 +136,8 @@ function derivedFieldColumn(input, column) {
         field: column.field,
         label: translatedColumnLabel(input, column),
         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,
+        // The client schema carries only `sortable` (never `sql`), so test the flag, not the SQL shape.
+        sortable: "sortable" in derivedDef && derivedDef.sortable === true,
         ...(column.renderer !== undefined && { renderer: column.renderer }),
         ...(column.hideOnNarrow === true && { hideOnNarrow: true }),
     };