@cosmicdrift/kumiko-renderer 0.387.0 → 0.388.0

package/dist/headless/format/index.js

@@ -184,73 +184,98 @@ function unitDisplaySpec(spec) {
     const v = spec["unitDisplay"];
     return isOneOf(INTL_UNIT_DISPLAYS, v) ? v : "short";
 }
+function isEmptyCellValue(value) {
+    return value === null || value === undefined || value === "";
+}
 export function applyFormatSpec(spec, value, translate) {
-    const isEmpty = value === null || value === undefined || value === "";
     // priority renders its emptyLabel for empty values — every other format
     // collapses empty to "".
-    if (isEmpty && spec.format !== "priority")
+    if (isEmptyCellValue(value) && spec.format !== "priority")
         return "";
-    switch (spec.format) {
-        case "timestamp":
-        case "date":
-            return formatDateCell(value, spec.format, {
-                locale: stringSpec(spec, "locale"),
-                dateStyle: dateStyleSpec(spec, "dateStyle"),
-                timeStyle: spec.format === "timestamp" ? dateStyleSpec(spec, "timeStyle") : undefined,
-                timeZone: spec.format === "timestamp" ? stringSpec(spec, "timeZone") : undefined,
-            });
-        case "boolean": {
-            if (value === true) {
-                const trueLabel = stringSpec(spec, "trueLabel");
-                return trueLabel === undefined ? "✓" : (translate?.(trueLabel) ?? trueLabel);
-            }
-            if (value === false) {
-                const falseLabel = stringSpec(spec, "falseLabel");
-                return falseLabel === undefined ? "" : (translate?.(falseLabel) ?? falseLabel);
-            }
-            return "";
-        }
-        case "currency": {
-            const sym = stringSpec(spec, "symbol") ?? "";
-            return sym.length > 0 ? `${value} ${sym}` : String(value);
-        }
-        case "number":
-        case "decimal":
-        case "bigInt":
-            return formatNumberCell(value, stringSpec(spec, "locale"), booleanSpec(spec, "grouping") ?? true, spec.format === "bigInt" ? {} : fractionDigitsSpec(spec));
-        case "unit":
-            return formatUnitCell(value, stringSpec(spec, "unit"), stringSpec(spec, "locale"), unitDisplaySpec(spec));
-        case "priority": {
-            const emptyLabel = stringSpec(spec, "emptyLabel") ?? EMPTY_VALUE_PLACEHOLDER;
-            const prefix = stringSpec(spec, "prefix") ?? "";
-            if (isEmpty || value === 0)
-                return emptyLabel;
-            return `${prefix}${value}`;
-        }
-        case "enumOption": {
-            const keyPrefix = stringSpec(spec, "keyPrefix");
-            const labelFor = (item) => {
-                const raw = typeof item === "string" ? item : String(item);
-                if (keyPrefix === undefined || translate === undefined)
-                    return raw;
-                const key = `${keyPrefix}${raw}`;
-                const translated = translate(key);
-                return translated === key ? raw : translated;
-            };
-            // multiSelect-style columns hold an array of option values
-            return Array.isArray(value) ? value.map(labelFor).join(", ") : labelFor(value);
-        }
-        // Thumbnails and file links are drawn by the web list cell; this is the
-        // text fallback for every other surface.
-        case "image":
-        case "file":
-            return Array.isArray(value) ? value.join(", ") : String(value);
-        case "json":
-            return stringifyJsonOrString(value, typeof spec["indent"] === "number" ? spec["indent"] : 2);
-        default:
-            if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
-                rendererWarn(`[kumiko] applyFormatSpec: unknown format key "${spec.format}" — registered via FieldFormatRegistry module augmentation?`);
-            }
-            return typeof value === "string" ? value : String(value);
+    if (!isBuiltInCellFormat(spec.format))
+        return formatUnknownCellFormat(spec, value);
+    return CELL_FORMATTERS[spec.format](spec, value, translate);
+}
+function formatTemporalCell(spec, value) {
+    const isTimestamp = spec.format === "timestamp";
+    return formatDateCell(value, spec.format, {
+        locale: stringSpec(spec, "locale"),
+        dateStyle: dateStyleSpec(spec, "dateStyle"),
+        timeStyle: isTimestamp ? dateStyleSpec(spec, "timeStyle") : undefined,
+        timeZone: isTimestamp ? stringSpec(spec, "timeZone") : undefined,
+    });
+}
+function formatBooleanCell(spec, value, translate) {
+    if (value === true) {
+        const trueLabel = stringSpec(spec, "trueLabel");
+        return trueLabel === undefined ? "✓" : (translate?.(trueLabel) ?? trueLabel);
+    }
+    if (value === false) {
+        const falseLabel = stringSpec(spec, "falseLabel");
+        return falseLabel === undefined ? "" : (translate?.(falseLabel) ?? falseLabel);
+    }
+    return "";
+}
+function formatCurrencyCell(spec, value) {
+    const sym = stringSpec(spec, "symbol") ?? "";
+    return sym.length > 0 ? `${value} ${sym}` : String(value);
+}
+function formatNumericCell(spec, value) {
+    return formatNumberCell(value, stringSpec(spec, "locale"), booleanSpec(spec, "grouping") ?? true, spec.format === "bigInt" ? {} : fractionDigitsSpec(spec));
+}
+function formatUnitSpecCell(spec, value) {
+    return formatUnitCell(value, stringSpec(spec, "unit"), stringSpec(spec, "locale"), unitDisplaySpec(spec));
+}
+function formatPriorityCell(spec, value) {
+    const emptyLabel = stringSpec(spec, "emptyLabel") ?? EMPTY_VALUE_PLACEHOLDER;
+    const prefix = stringSpec(spec, "prefix") ?? "";
+    if (isEmptyCellValue(value) || value === 0)
+        return emptyLabel;
+    return `${prefix}${value}`;
+}
+function formatEnumOptionCell(spec, value, translate) {
+    const keyPrefix = stringSpec(spec, "keyPrefix");
+    const labelFor = (item) => {
+        const raw = typeof item === "string" ? item : String(item);
+        if (keyPrefix === undefined || translate === undefined)
+            return raw;
+        const key = `${keyPrefix}${raw}`;
+        const translated = translate(key);
+        return translated === key ? raw : translated;
+    };
+    // multiSelect-style columns hold an array of option values
+    return Array.isArray(value) ? value.map(labelFor).join(", ") : labelFor(value);
+}
+// Thumbnails and file links are drawn by the web list cell; this is the
+// text fallback for every other surface.
+function formatFileCell(_spec, value) {
+    return Array.isArray(value) ? value.join(", ") : String(value);
+}
+function formatJsonCell(spec, value) {
+    return stringifyJsonOrString(value, typeof spec["indent"] === "number" ? spec["indent"] : 2);
+}
+const CELL_FORMATTERS = {
+    timestamp: formatTemporalCell,
+    date: formatTemporalCell,
+    boolean: formatBooleanCell,
+    currency: formatCurrencyCell,
+    number: formatNumericCell,
+    decimal: formatNumericCell,
+    bigInt: formatNumericCell,
+    unit: formatUnitSpecCell,
+    priority: formatPriorityCell,
+    enumOption: formatEnumOptionCell,
+    image: formatFileCell,
+    file: formatFileCell,
+    json: formatJsonCell,
+};
+// Own-key check: a format such as "toString" must not resolve to an inherited member.
+function isBuiltInCellFormat(format) {
+    return Object.hasOwn(CELL_FORMATTERS, format);
+}
+function formatUnknownCellFormat(spec, value) {
+    if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+        rendererWarn(`[kumiko] applyFormatSpec: unknown format key "${spec.format}" — registered via FieldFormatRegistry module augmentation?`);
     }
+    return typeof value === "string" ? value : String(value);
 }

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

@@ -469,6 +469,7 @@ export function computeEditViewModel(input) {
             .map((group) => ({
             title: translate(group.title),
             columns: group.columns ?? 2,
+            columnsDeclared: group.columns !== undefined,
             fields: group.fields.map((fieldSpec) => {
                 const fieldName = normalizeEditField(fieldSpec).field;
                 const fieldView = fields.find((f) => f.field === fieldName);
@@ -491,6 +492,7 @@ export function computeEditViewModel(input) {
             }),
             ...(sectionSpec.subtitle !== undefined && { subtitle: translate(sectionSpec.subtitle) }),
             columns: sectionSpec.columns ?? defaultColumns,
+            columnsDeclared: sectionSpec.columns !== undefined,
             fields,
             ...(groups !== undefined && { groups }),
             ...(sectionSpec.icon !== undefined && { icon: sectionSpec.icon }),

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

@@ -9,167 +9,202 @@ const WRITE_ONLY_SET_LABEL_KEY = "kumiko.field.writeOnly.set";
 // 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));
-        // Reference fields may target the same feature ("user") or another feature
-        // ("users:user"). parseRefTarget returns the feature and entity names, which
-        // the renderer uses to build the lookup query as
-        // `<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 { screen, rows } = input;
+    const columns = screen.columns.map((spec) => resolveListColumn(input, normalizeListColumn(spec)));
+    const listRows = rows.map(writeOnlyRowFormatter(input));
+    return {
+        screenId: screen.id,
+        entityName: screen.entity,
+        columns,
+        rows: listRows,
+        ...(screen.slots && { slots: screen.slots }),
+        isEmpty: listRows.length === 0,
+    };
+}
+// First match wins; the order encodes which metadata source a column name
+// resolves against when several could claim it.
+const LIST_COLUMN_RESOLVERS = [
+    declaredReferenceColumn,
+    storedFieldColumn,
+    derivedFieldColumn,
+    rowMetaColumn,
+    virtualRendererColumn,
+];
+function resolveListColumn(input, column) {
+    for (const resolve of LIST_COLUMN_RESOLVERS) {
+        const resolved = resolve(input, column);
+        if (resolved)
+            return resolved;
     }
+    // No metadata source claims the name: an author typo or a stale field
+    // rename, so fail loud instead of silently drawing nothing.
+    throw new Error(`computeListViewModel: screen "${input.screen.id}" references unknown field "${column.field}" on entity "${input.screen.entity}"`);
+}
+function translatedColumnLabel(input, column) {
+    return input.translate(column.label ?? fieldLabelKey(input.featureName, input.screen.entity, column.field));
+}
+// 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.
+function declaredReferenceColumn(input, column) {
+    const storedFieldType = input.entity.fields[column.field]?.type;
+    // skip: no declared reference, or a real non-text field that keeps its own type
+    if (column.refEntity === undefined ||
+        (storedFieldType !== undefined && storedFieldType !== "text")) {
+        return undefined;
+    }
+    // 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 so it also fires against the pseudo-entities
+    // that hardcode every field as "text" (projection-list-shim,
+    // related-list-section) — those never reach the stored reference branch
+    // since fieldDef.type is always "text" there.
+    const refTarget = parseRefTarget(column.refEntity, input.featureName);
+    return {
+        field: column.field,
+        label: translatedColumnLabel(input, column),
+        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: column.refLabelField ?? "id",
+        ...(column.renderer !== undefined && { renderer: column.renderer }),
+        ...(column.hideOnNarrow === true && { hideOnNarrow: true }),
+    };
+}
+function storedFieldColumn(input, column) {
+    const fieldDef = input.entity.fields[column.field];
+    // skip: not a stored field, a later resolver decides
+    if (!fieldDef)
+        return undefined;
+    return {
+        field: column.field,
+        label: translatedColumnLabel(input, column),
+        type: fieldDef.type,
+        sortable: fieldIsSortable(fieldDef),
+        ...(column.renderer !== undefined && { renderer: column.renderer }),
+        ...storedFieldMetadata(input, column, fieldDef),
+        ...(column.hideOnNarrow === true && { hideOnNarrow: true }),
+    };
+}
+// Key order is part of the serialized view model, so it stays fixed here.
+function storedFieldMetadata(input, column, fieldDef) {
+    // 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(input.translate, (value) => fieldOptionLabelKey(input.featureName, input.screen.entity, column.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, column.renderer);
+    return {
+        ...(optionLabels !== undefined && { optionLabels }),
+        ...(optionTones !== undefined && { optionTones }),
+        ...storedReferenceMetadata(fieldDef, input.featureName),
+        ...(grouping !== undefined && { grouping }),
+        ...(fileDisplay !== undefined && { fileDisplay }),
+    };
+}
+// Reference fields may target the same feature ("user") or another feature
+// ("users:user"). parseRefTarget returns the feature and entity names, which
+// the renderer uses to build the lookup query as
+// `<refFeature>:query:<refEntity>:list`.
+function storedReferenceMetadata(fieldDef, featureName) {
+    if (fieldDef.type !== "reference")
+        return {};
+    const refTarget = parseRefTarget(fieldDef.entity, featureName);
+    return {
+        refEntity: refTarget.entityName,
+        refFeature: refTarget.featureName,
+        refLabelField: fieldDef.labelField ?? "id",
+    };
+}
+// 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.
+function derivedFieldColumn(input, column) {
+    const derivedDef = input.entity.derivedFields?.[column.field];
+    // skip: not a derived field, a later resolver decides
+    if (!derivedDef)
+        return undefined;
+    return {
+        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,
+        ...(column.renderer !== undefined && { renderer: column.renderer }),
+        ...(column.hideOnNarrow === true && { hideOnNarrow: true }),
+    };
+}
+// 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 derived
+// fields, these are actual DB columns, so server-side ORDER BY works —
+// sortable stays true, except for the ID columns in LIST_ROW_META_REFERENCES.
+function rowMetaColumn(input, column) {
+    const rowMetaType = LIST_ROW_META_COLUMNS[column.field];
+    // skip: not a base-table column, a later resolver decides
+    if (rowMetaType === undefined)
+        return undefined;
+    const rowMetaRef = LIST_ROW_META_REFERENCES[column.field];
+    return {
+        field: column.field,
+        label: translatedColumnLabel(input, column),
+        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,
+        ...(column.renderer !== undefined && { renderer: column.renderer }),
+        ...(column.hideOnNarrow === true && { hideOnNarrow: true }),
+        ...(rowMetaRef !== undefined && {
+            refEntity: rowMetaRef.refEntity,
+            refFeature: rowMetaRef.refFeature,
+            refLabelField: rowMetaRef.refLabelField,
+        }),
+    };
+}
+// 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.
+function virtualRendererColumn(input, column) {
+    // skip: without both a label and a renderer the column is unknown
+    if (column.label === undefined || column.renderer === undefined)
+        return undefined;
+    return {
+        field: column.field,
+        label: input.translate(column.label),
+        type: "text",
+        sortable: false,
+        renderer: column.renderer,
+        ...(column.hideOnNarrow === true && { hideOnNarrow: true }),
+    };
+}
+// The wire carries `true` (set) / `null` (empty) for writeOnly fields; the cell shows a word, not "true".
+function writeOnlyRowFormatter(input) {
+    const { screen, entity, translate } = input;
     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) => {
+    return (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,
+        return { id: String(row["id"] ?? ""), values: shown };
     };
 }
 // Field-i18n-key convention matches what features register translations

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

@@ -300,12 +300,15 @@ export type EditFieldsSectionViewModel = {
     /** Translated `EditFieldsSection.subtitle` (wizard step rail / up-next box). */
     readonly subtitle?: string;
     readonly columns: number;
+    /** True when the author declared `columns`; false means the tabs/stacked default. */
+    readonly columnsDeclared?: boolean;
     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 columnsDeclared?: boolean;
         readonly fields: readonly EditFieldViewModel[];
     }[];
     /** From `EditFieldsSection.icon` — closed IconKey vocabulary, renders

package/dist/hooks/live-refetch-scheduler.js

@@ -12,6 +12,10 @@ export function createLiveRefetchScheduler(run, windowMs = LIVE_REFETCH_COALESCE
         try {
             await run();
         }
+        catch {
+            // The caller surfaces its own load errors in state; a failed run must
+            // neither become an unhandled rejection nor drop the queued follow-up.
+        }
         finally {
             inFlight = false;
         }

package/dist/hooks/use-reference-lookup.d.ts

@@ -13,10 +13,18 @@ export declare function referenceOptionSource(field: {
     readonly queryQn: string;
     readonly labelKey: string;
 };
-/** Empty while the query loads (or fails), so callers fall back to the raw id.
+export declare function isCompleteRowPage(data: {
+    readonly nextCursor?: string | null;
+} | null): boolean;
+/** `map` holds the resolved labels; while the query loads or has failed an id is
+ *  simply not in it. Callers decide the fallback: the raw id, or the "Unknown"
+ *  label for entities listed in `UNRESOLVED_REFERENCE_LABEL_KEYS` once the
+ *  lookup is complete.
  *  `featureName` is the reference's target feature, not the screen's. */
 export declare function useReferenceLookup(featureName: string, refEntity: string, labelField: string): {
     readonly map: ReferenceLookupMap;
     readonly loading: boolean;
     readonly failed: boolean;
+    /** False when the lookup page was capped: absent ids may still exist. */
+    readonly complete: boolean;
 };

package/dist/hooks/use-reference-lookup.js

@@ -9,7 +9,8 @@
 //     of N+1) but would have to extend the executor API with lookupTables.
 //     The renderer-side path wins for the MVP.
 //   - limit:200 is a hard UX limit: with more entries in the referenced
-//     entity, the last rows show only UUIDs. A searchable combobox plus a
+//     entity, the last rows fall back to the raw id (or "Unknown" for
+//     opt-in entities once the lookup is complete). A searchable combobox plus a
 //     server-side eager load with an ID whitelist will lift that later.
 //
 // The hook is call-stable: useQuery's internal cache shares the lookup map
@@ -44,7 +45,15 @@ export function referenceOptionSource(field, refFeature, refEntity) {
     }
     return referenceLookupSource(refFeature, refEntity, field.refLabelField ?? "id");
 }
-/** Empty while the query loads (or fails), so callers fall back to the raw id.
+// A page with a continuation cursor is only a prefix of the referenced rows,
+// so a missing id in it proves nothing about the row's existence.
+export function isCompleteRowPage(data) {
+    return data !== null && (data.nextCursor ?? null) === null;
+}
+/** `map` holds the resolved labels; while the query loads or has failed an id is
+ *  simply not in it. Callers decide the fallback: the raw id, or the "Unknown"
+ *  label for entities listed in `UNRESOLVED_REFERENCE_LABEL_KEYS` once the
+ *  lookup is complete.
  *  `featureName` is the reference's target feature, not the screen's. */
 export function useReferenceLookup(featureName, refEntity, labelField) {
     const { queryQn, labelKey } = referenceLookupSource(featureName, refEntity, labelField);
@@ -72,5 +81,10 @@ export function useReferenceLookup(featureName, refEntity, labelField) {
         }
         return out;
     }, [result.data, labelKey, systemLabel, translate]);
-    return { map, loading: result.loading, failed: result.error !== null };
+    return {
+        map,
+        loading: result.loading,
+        failed: result.error !== null,
+        complete: isCompleteRowPage(result.data),
+    };
 }

package/dist/i18n-defaults.js

@@ -1,6 +1,10 @@
-// Framework default bundle. These strings are required by renderer components (Save/Cancel/Delete buttons, empty states, search placeholder, navigation-toggle ARIA labels, and validation reasons). createKumikoApp adds this as the last fallback in LocaleProvider, while apps can override individual keys via clientFeatures.translations.
+// Framework default bundle. These strings are required by renderer components (Save/Cancel/Delete
+// buttons, empty states, search placeholder, navigation-toggle ARIA labels, and validation
+// reasons). createKumikoApp adds this as the last fallback in LocaleProvider, while apps can
+// override individual keys via clientFeatures.translations.
 //
-// All keys use the `kumiko.` prefix to avoid collisions with app keys. Subpaths group keys by area (actions / list / nav / form / validation).
+// All keys use the `kumiko.` prefix to avoid collisions with app keys. Subpaths group keys by area
+// (actions / list / nav / form / validation).
 export const kumikoDefaultTranslations = {
     en: {
         "kumiko.actions.save": "Save",