@cosmicdrift/kumiko-headless 0.359.0 → 0.361.0

package/dist/format/index.js

@@ -198,6 +198,11 @@ export function applyFormatSpec(spec, value, translate) {
             // 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:

package/dist/index.d.ts

@@ -10,5 +10,5 @@ export type { NavDefinition, NavNode, NavRegistrySlice, NavTree, ResolveNavigati
 export { resolveNavigation } from "./nav/index.js";
 export type { Store, WritableStore } from "./store/index.js";
 export { createStore, shallowEqual } from "./store/index.js";
-export type { ComputeEditViewModelInput, ComputeListViewModelInput, DerivedCellRoundingTarget, EditExtensionSectionViewModel, EditFieldSpec, EditFieldsSectionViewModel, EditFieldViewModel, EditFormMode, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedDerivedOp, EmbeddedListCellViewModel, EmbeddedListIssueGroups, FieldConditionCtx, FieldRenderer, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeRenderer, ScreenSlots, Translate, } from "./view-model/index.js";
+export type { ComputeEditViewModelInput, ComputeListViewModelInput, DerivedCellRoundingTarget, EditExtensionSectionViewModel, EditFieldSpec, EditFieldsSectionViewModel, EditFieldViewModel, EditFormMode, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedDerivedOp, EmbeddedListCellViewModel, EmbeddedListIssueGroups, FieldConditionCtx, FieldRenderer, ListColumnFileDisplay, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeRenderer, ScreenSlots, Translate, } from "./view-model/index.js";
 export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.js";

package/dist/nav/resolve.js

@@ -4,7 +4,9 @@ import { isUiAccessGranted } from "@cosmicdrift/kumiko-framework/ui-types";
 // access-checked; a hidden parent drops its entire subtree implicitly
 // because we never recurse into it. Siblings sort by `order` (ascending,
 // default 0), tie-broken by qualified name so renders stay deterministic
-// across registry iteration orders.
+// across registry iteration orders. A pure group (no screen, target,
+// provider or createAction) whose children are all hidden or absent is
+// dropped too.
 //
 // Pure — same inputs produce the same tree. The renderer memoizes the
 // result and only recomputes when the registry changes (rare — boot
@@ -24,6 +26,10 @@ export function resolveNavigation(options) {
             if (node !== null)
                 children.push(node);
         }
+        // A pure group (nothing to open itself) with nothing visible below it
+        // would render as an empty, unclickable heading.
+        if (children.length === 0 && isPureGroup(entry))
+            return null;
         children.sort(bySortKey);
         return {
             qualifiedName: entry.id,
@@ -47,6 +53,13 @@ export function resolveNavigation(options) {
     roots.sort(bySortKey);
     return roots;
 }
+function isPureGroup(entry) {
+    return (entry.screen === undefined &&
+        entry.target === undefined &&
+        entry.provider === undefined &&
+        entry.actions === undefined &&
+        entry.createAction === undefined);
+}
 function bySortKey(a, b) {
     // Primary key: `order` ascending. Secondary: qualifiedName alphabetic,
     // which is a stable fallback — the registry-iteration order isn't

package/dist/view-model/edit.d.ts

@@ -10,6 +10,8 @@ export type ComputeEditViewModelInput<TValues extends Readonly<Record<string, un
      *  for that verb (create hides them, update shows them read-only); omitted
      *  means no exclusion applies. */
     readonly mode?: EditFormMode;
+    /** The record being edited; omitted on create. */
+    readonly entityId?: string;
 };
 export type EditFormMode = "create" | "update";
 export declare function computeRelatedListSectionViewModel(sectionSpec: EditRelatedListSection, translate: Translate): EditRelatedListSectionViewModel;

package/dist/view-model/edit.js

@@ -220,23 +220,66 @@ function deriveReferenceMultiHints(fieldDef, declaredRefTarget) {
         ...(refMultiple !== undefined && { refMultiple }),
     };
 }
-// file/image: entityType/fieldName travel with the upload POST so the
-// endpoint validates against the right field definition.
-function deriveFileFieldHints(fieldDef, entityName, fieldName) {
-    const isFileType = fieldDef.type === "file" || fieldDef.type === "image" || fieldDef.type === "images";
-    const fileDef = isFileType
-        ? fieldDef
-        : undefined;
-    const imageVariant = fieldDef.type === "image" || fieldDef.type === "images"
-        ? Object.keys(fileDef?.variants ?? {})[0]
-        : undefined;
-    const capture = fieldDef.type === "image" ? fileDef?.capture : undefined;
+function isFileFieldType(fieldDef) {
+    return (fieldDef.type === "file" ||
+        fieldDef.type === "image" ||
+        fieldDef.type === "files" ||
+        fieldDef.type === "images");
+}
+function deriveImageHints(fieldDef, fileDef) {
+    if (fieldDef.type !== "image" && fieldDef.type !== "images")
+        return {};
+    const imageVariant = Object.keys(fileDef.variants ?? {})[0];
     return {
-        ...(fileDef?.accept !== undefined && { accept: fileDef.accept }),
-        ...(fileDef?.maxSize !== undefined && { maxSize: fileDef.maxSize }),
-        ...(isFileType && { entityType: entityName, fieldName }),
         ...(imageVariant !== undefined && { imageVariant }),
-        ...(capture !== undefined && { capture }),
+        ...(fileDef.capture !== undefined && { capture: fileDef.capture }),
+    };
+}
+function deriveFileFieldHints(fieldDef, entityName, fieldName, entityId) {
+    if (!isFileFieldType(fieldDef))
+        return {};
+    const fileDef = fieldDef;
+    return {
+        ...(fileDef.accept !== undefined && { accept: fileDef.accept }),
+        ...(fileDef.maxSize !== undefined && { maxSize: fileDef.maxSize }),
+        ...(fileDef.maxCount !== undefined && { maxCount: fileDef.maxCount }),
+        entityType: entityName,
+        fieldName,
+        ...(entityId !== undefined && { entityId }),
+        ...deriveImageHints(fieldDef, fileDef),
+    };
+}
+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
@@ -244,39 +287,14 @@ function deriveFileFieldHints(fieldDef, entityName, fieldName) {
 // (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) {
+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]) => {
-            const cellLabel = translate(embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName));
-            const cellOptions = subField.type === "select" ? (subField.options ?? []) : undefined;
-            const cellOptionLabels = cellOptions !== undefined
-                ? buildOptionLabels(translate, (value) => embeddedCellOptionLabelKey(featureName, entityName, fieldName, subFieldName, value), cellOptions)
-                : undefined;
-            const cellRef = subField.type === "reference" ? subField : undefined;
-            const cellRefTarget = cellRef?.entity !== undefined ? parseRefTarget(cellRef.entity, featureName) : undefined;
-            const cell = {
-                field: subFieldName,
-                label: cellLabel,
-                type: subField.type,
-                required: subField.required === true,
-                ...(cellOptions !== undefined && { options: cellOptions }),
-                ...(cellOptionLabels !== undefined && { optionLabels: cellOptionLabels }),
-                ...(cellRefTarget !== undefined && { refEntity: cellRefTarget.entityName }),
-                ...(cellRefTarget !== undefined && { refFeature: cellRefTarget.featureName }),
-                ...(cellRef?.labelField !== undefined && { refLabelField: cellRef.labelField }),
-                ...(cellRef?.optionsQuery !== undefined && {
-                    refOptionsQuery: cellRef.optionsQuery,
-                }),
-                ...(subField.type === "decimal" &&
-                    subField.scale !== undefined && { scale: subField.scale }),
-            };
-            return cell;
-        })
+        ? Object.entries(embeddedListDef.schema).map(([subFieldName, subField]) => buildEmbeddedListCell(subFieldName, subField, translate, featureName, entityName, fieldName, listSpec))
         : undefined;
     return {
         ...(embeddedListCells !== undefined && { embeddedListCells }),
@@ -295,6 +313,8 @@ function deriveEmbeddedListHints(fieldDef, translate, featureName, entityName, f
         // 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) {
@@ -316,7 +336,7 @@ function buildExtensionSectionViewModel(sectionSpec, translate) {
 // 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 } = 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) => {
@@ -378,8 +398,8 @@ export function computeEditViewModel(input) {
             const dateHints = deriveDateFieldHints(fieldDef);
             const numericHints = deriveNumericFieldHints(fieldDef, resolvedCurrency);
             const referenceHints = deriveReferenceFieldHints(fieldDef, normalized, declaredRefTarget, featureName);
-            const fileHints = deriveFileFieldHints(fieldDef, screen.entity, normalized.field);
-            const embeddedListHints = deriveEmbeddedListHints(fieldDef, translate, featureName, screen.entity, normalized.field, resolvedCurrency);
+            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,

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

@@ -4,4 +4,4 @@ export type { DerivedCellRoundingTarget, EmbeddedDerivedOp, EmbeddedListIssueGro
 export { computeDerivedCellValue, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./embedded-list.js";
 export type { ComputeListViewModelInput } from "./list.js";
 export { buildOptionLabels, computeListViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, } from "./list.js";
-export type { EditExtensionSectionViewModel, EditFieldSpec, EditFieldsSectionViewModel, EditFieldViewModel, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedListCellViewModel, FieldConditionCtx, FieldRenderer, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeRenderer, ScreenSlots, Translate, } from "./types.js";
+export type { EditExtensionSectionViewModel, EditFieldSpec, EditFieldsSectionViewModel, EditFieldViewModel, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedListCellViewModel, FieldConditionCtx, FieldRenderer, ListColumnFileDisplay, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeRenderer, ScreenSlots, Translate, } from "./types.js";

package/dist/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.js";
+export declare function deriveListFileDisplay(fieldDef: FieldDefinition, renderer: ListColumnViewModel["renderer"]): ListColumnFileDisplay | undefined;

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

@@ -0,0 +1,28 @@
+function firstVariantKey(fieldDef) {
+    const variants = fieldDef.variants;
+    return variants === undefined ? undefined : Object.keys(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/view-model/list.js

@@ -1,4 +1,5 @@
 import { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, normalizeListColumn, parseRefTarget, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { deriveListFileDisplay } from "./list-file-display.js";
 const WRITE_ONLY_SET_LABEL_KEY = "kumiko.field.writeOnly.set";
 // Pure transform: takes the declared screen + entity + incoming rows, spits
 // out the flat shape the renderer draws. No conditions, no access-checks —
@@ -130,6 +131,7 @@ export function computeListViewModel(input) {
             : 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,
@@ -142,6 +144,7 @@ export function computeListViewModel(input) {
             ...(refFeature !== undefined && { refFeature }),
             ...(refLabelField !== undefined && { refLabelField }),
             ...(grouping !== undefined && { grouping }),
+            ...(fileDisplay !== undefined && { fileDisplay }),
             ...(normalized.hideOnNarrow === true && { hideOnNarrow: true }),
         };
         columns.push(column);

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

@@ -1,5 +1,12 @@
 import type { EditFieldSpec, EditSectionSpec, FieldIconKey, FieldRenderer, IconKey, ListColumnSpec, ListFacetSpec, ListSortSpec, OptionsQueryPayload, PlatformComponent, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionMode, ScreenSlots, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
 export type RuntimeRenderer = (value: unknown, row?: Readonly<Record<string, unknown>>) => string;
+/** How a list cell shows a FileRef value (id or id array). */
+export type ListColumnFileDisplay = {
+    readonly kind: "image";
+    readonly variant?: string;
+} | {
+    readonly kind: "file";
+};
 export type ListColumnViewModel = {
     readonly field: string;
     readonly label: string;
@@ -34,6 +41,10 @@ export type ListColumnViewModel = {
      *  `true`). `false` renders without thousands-separators (e.g. a model
      *  year). */
     readonly grouping?: boolean;
+    /** Set for file/image columns: from the entity field type, or from a
+     *  `{ format: "image" | "file" }` renderer. The cell shows a thumbnail or the
+     *  file name instead of the FileRef UUID. */
+    readonly fileDisplay?: ListColumnFileDisplay;
 };
 export type ListRowViewModel = {
     readonly id: string;
@@ -55,6 +66,10 @@ export type EmbeddedListCellViewModel = {
     /** Only for `type: "select"`. */
     readonly options?: readonly string[];
     readonly optionLabels?: Readonly<Record<string, string>>;
+    /** Only for `type: "select"`; `"radio"` renders segmented buttons instead of a dropdown. */
+    readonly display?: "radio" | "dropdown";
+    /** Cell is shown but not editable (`EditFieldSpec.embeddedList.readOnlyCells`). */
+    readonly readOnly?: boolean;
     /** Only for `type: "reference"`. */
     readonly refEntity?: string;
     readonly refFeature?: string;
@@ -171,12 +186,17 @@ export type EditFieldViewModel = {
      *  Upload-Endpoint gegen die Field-Def. */
     readonly accept?: readonly string[];
     readonly maxSize?: string;
+    /** Only for `type: "files" | "images"` — upper bound on list length. */
+    readonly maxCount?: number;
     /** Nur bei `type: "file" | "image"` — Entity-Name + Field-Name für den
      *  Upload-POST (`/api/files`), damit der Endpoint maxSize/accept gegen
      *  die richtige Field-Def prüfen kann. */
     readonly entityType?: string;
     readonly fieldName?: string;
-    /** Only for `type: "image"` — the variant name the preview requests
+    /** Record being edited (update mode only). Sent with the upload so the
+     *  FileRef is attached to the record. */
+    readonly entityId?: string;
+    /** Only for `type: "image"` and `"images"` — the variant name the preview requests
      *  (`/api/files/:id/variant/:name`) instead of the original. The FIRST
      *  variant declared on the field def wins; a spec may legitimately carry
      *  neither `size` nor `maxEdge` (format-/blur-only), so "the smallest one"
@@ -204,6 +224,9 @@ export type EditFieldViewModel = {
     }>>;
     /** Numeric sub-field names to sum in a totals row. From EmbeddedFieldDef.totals. */
     readonly embeddedListTotals?: readonly string[];
+    /** No add, remove, duplicate or move; cells stay editable. From
+     *  EditFieldSpec.embeddedList.fixedRows. */
+    readonly embeddedListFixedRows?: boolean;
     /** Currency for the whole embedded list's money cells and totals row —
      *  currency lives on the head aggregate (EntityDefinition.defaultCurrency),
      *  not per row. Falls back to "EUR" when the entity has no defaultCurrency. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.359.0",
+  "version": "0.361.0",
   "description": "Headless UI logic for Kumiko — Dispatcher contract, Form-Controller, View-Model, Nav-Resolver. Plattform- und React-frei; jeder Renderer (renderer, renderer-web, renderer-native, …) komponiert darauf.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,8 +36,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.359.0",
-    "@cosmicdrift/kumiko-types": "0.359.0",
+    "@cosmicdrift/kumiko-framework": "0.361.0",
+    "@cosmicdrift/kumiko-types": "0.361.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

package/src/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "Edit view model carries read-only cells and fixed rows",
+    "detail": "EmbeddedListCellViewModel.readOnly and EditFieldViewModel.embeddedListFixedRows are derived from EditFieldSpec.embeddedList."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "Embedded list cells carry the select display",
+    "detail": "EmbeddedListCellViewModel.display is taken from the sub-field."
+  },
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "resolveNavigation no longer renders empty groups or entries that open nothing",
+    "detail": "A nav node with no screen, target, provider, actions and createAction is dropped when none of its children is visible, also when it never had children. Allowlisted sidebars lose groups whose children are all filtered out. Give the entry a screen or keep a child visible to retain it."
+  },
+  {
+    "version": "0.360.0",
+    "type": "improvement",
+    "title": "Edit view model carries entityId and maxCount for file fields",
+    "detail": "ComputeEditViewModelInput has an optional entityId (the record being edited, omitted on create). EditFieldViewModel gains entityId for file, image, files and images fields and maxCount for files and images. The file-field hints now also cover type files, which was missing."
+  },
   {
     "version": "0.357.0",
     "type": "improvement",