@cosmicdrift/kumiko-renderer 0.398.0 → 0.400.0

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 }),
     };

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

@@ -1,4 +1,4 @@
-import type { EditFieldSpec, EditSectionSpec, FieldAffix, FieldFillAction, FieldIconKey, FieldRenderer, IconKey, ListBulkAction, ListColumnSpec, ListFacetSpec, ListSortSpec, ListTableOptions, OptionsQueryPayload, PlatformComponent, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionMode, ScreenSlots, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { EditFieldSpec, EditSectionSpec, EmbeddedDerivedCellDef, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, IconKey, ListBulkAction, ListColumnSpec, ListFacetSpec, ListSortSpec, ListTableOptions, OptionsQueryPayload, PlatformComponent, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionMode, ScreenSlots, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
 export type RuntimeRenderer = (value: unknown, row?: Readonly<Record<string, unknown>>) => string;
 /** Where a cell's text links to. `href` comes from NavApi.hrefFor (new-tab and
  *  copy-link work); `onPress` is the in-app navigation for a plain click. */
@@ -79,15 +79,26 @@ export type ListViewModel = {
 export type EmbeddedListCellViewModel = {
     readonly field: string;
     readonly label: string;
-    readonly type: "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp";
+    readonly type: "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp" | "images" | "files";
     readonly required: boolean;
+    /** Per-row state: hidden / required for a row where the condition holds. */
+    readonly visibleWhen?: Exclude<FieldCondition, boolean>;
+    readonly requiredWhen?: Exclude<FieldCondition, boolean>;
     /** Only for `type: "select"`. */
     readonly options?: readonly string[];
+    /** Only for `type: "select"`; tone of each option's badge or selected segment. */
+    readonly optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>;
+    /** Only for `type: "images" | "files"`. */
+    readonly capture?: "user" | "environment";
+    readonly maxCount?: number;
+    readonly accept?: 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;
+    /** Not shown on phone cards (`EditFieldSpec.embeddedList.cardHiddenCells`). */
+    readonly hiddenInCard?: boolean;
     /** Only for `type: "reference"`. */
     readonly refEntity?: string;
     readonly refFeature?: string;
@@ -140,6 +151,8 @@ export type EditFieldViewModel = {
      *  `type: "select"` when SelectFieldDef.display is "radio" or "dropdown" —
      *  the renderer then skips its own radio-vs-dropdown heuristic. */
     readonly display?: "checkboxes" | "dropdown" | "radio";
+    /** `type: "select"` only: tone per option, shown on the selected radio segment. */
+    readonly optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>;
     /** Set for `type: "multiSelect"` when MultiSelectFieldDef.columns is
      *  defined — column count for the checkbox grid at the widest breakpoint.
      *  Ignored unless `display` is "checkboxes". */
@@ -249,10 +262,7 @@ export type EditFieldViewModel = {
     readonly embeddedListMaxItems?: number;
     /** Sub-field name → how to compute its cell from other sub-fields of the
      *  same row. From EmbeddedFieldDef.derived. */
-    readonly embeddedListDerived?: Readonly<Record<string, {
-        readonly op: "multiply" | "sum" | "subtract" | "percent";
-        readonly from: readonly string[];
-    }>>;
+    readonly embeddedListDerived?: Readonly<Record<string, EmbeddedDerivedCellDef>>;
     /** Footer totals: a sub-field name, or a labelled sum of several. From EmbeddedFieldDef.totals. */
     readonly embeddedListTotals?: readonly (string | {
         readonly label: string;
@@ -261,6 +271,13 @@ export type EditFieldViewModel = {
     /** No add, remove, duplicate or move; cells stay editable. From
      *  EditFieldSpec.embeddedList.fixedRows. */
     readonly embeddedListFixedRows?: boolean;
+    /** Where photos of a row's file cells are uploaded: the entity and the top-level list field;
+     *  the cell name travels as `subField`. Set when the list has a file cell. */
+    readonly embeddedListUploadTarget?: {
+        readonly entityType: string;
+        readonly fieldName: string;
+        readonly entityId?: string;
+    };
     /** 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/dist/hooks/related-list-parent-payload.d.ts

@@ -0,0 +1,2 @@
+import type { EditRelatedListSection } from "@cosmicdrift/kumiko-framework/ui-types";
+export declare function buildRelatedListParentPayload(section: Pick<EditRelatedListSection, "parentFilter" | "parentParam">, parentId: string): Readonly<Record<string, unknown>>;

package/dist/hooks/related-list-parent-payload.js

@@ -0,0 +1,7 @@
+// `parentFilter` sends the parent id as a server-side `filter` clause: the generic
+// `<entity>:list` query understands `filter`, not an arbitrary `parentParam` key.
+export function buildRelatedListParentPayload(section, parentId) {
+    return section.parentFilter !== undefined
+        ? { filter: { field: section.parentFilter.field, op: "eq", value: parentId } }
+        : { [section.parentParam ?? "id"]: parentId };
+}

package/dist/i18n-defaults.js

@@ -50,6 +50,9 @@ export const kumikoDefaultTranslations = {
         "kumiko.field.writeOnly.willRemove": "Removed on save",
         "kumiko.field.embedded-list.actions": "Actions",
         "kumiko.field.embedded-list.cell-label": "{column}, row {row}",
+        "kumiko.field.embedded-list.limit-range": "Limit {min} to {max}",
+        "kumiko.field.embedded-list.limit-min": "At least {min}",
+        "kumiko.field.embedded-list.limit-max": "At most {max}",
         "kumiko.field.file-list.add": "Add file",
         "kumiko.field.file-list.move-up": "Move file up",
         "kumiko.field.file-list.move-down": "Move file down",
@@ -242,6 +245,14 @@ export const kumikoDefaultTranslations = {
         "kumiko.nav.expand": "Expand",
         "kumiko.nav.collapse": "Collapse",
         "kumiko.nav.search": "Search navigation…",
+        "kumiko.notifications.label": "Notifications",
+        "kumiko.notifications.labelUnread": "Notifications, {count} unread",
+        "kumiko.notifications.title": "Notifications",
+        "kumiko.notifications.empty": "No notifications yet.",
+        "kumiko.notifications.markAllRead": "Mark all as read",
+        "kumiko.notifications.loadMore": "Load more",
+        "kumiko.notifications.unread": "Unread",
+        "kumiko.notifications.loadFailed": "Notifications could not be loaded.",
         "kumiko.nav.language": "Language",
         "kumiko.workspace.switch": "Switch workspace",
         // Workspace-Switcher fallback label when activeId points at no visible workspace.

package/dist/primitives.d.ts

@@ -4,8 +4,10 @@ import { type ComponentType, type FormEvent, type KeyboardEvent, type ReactNode,
 import type { DataTableBulk } from "./data-table-bulk-types.ts";
 import type { DataTableDateRangeFacet, DataTableFacet } from "./data-table-facet-types.ts";
 import type { DataTableTableBlock } from "./data-table-view-types.ts";
+import type { EmbeddedListInputProps } from "./embedded-list-types.ts";
 import type { FieldIssue, ListColumnViewModel, ListRowViewModel, RuntimeRenderer } from "./headless/index.ts";
 import type { MetricBandProps, MetricProps } from "./metric-types.ts";
+export type { EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, } from "./embedded-list-types.ts";
 export type { RuntimeRenderer };
 /** Escape hatch for `data-*` test hooks (e.g. an E2E selector) that don't
  *  warrant a dedicated typed prop. Web merges these onto the rendered
@@ -460,6 +462,8 @@ export type InputProps = {
      *  decides; the web impl keeps its short-option-set heuristic. Custom
      *  impls may ignore it — it is a request, not a contract. */
     readonly display?: "radio" | "dropdown";
+    /** Tone per option value; the selected segment of a radio presentation takes its colors. */
+    readonly optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>;
 } | ({
     readonly kind: "combobox";
     readonly id: string;
@@ -797,94 +801,6 @@ export type DataTableProps = {
     readonly renderExpandedRow?: (row: ListRowViewModel) => ReactNode;
 } & DataTableTableBlock;
 export type DataTableTableBlockProps = Pick<DataTableProps, keyof DataTableTableBlock>;
-/** 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";
-/** 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;
-    /** 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;
-};
-/** 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;
-    /** 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;
-};
 export type { FormWidth };
 /** One entry of a form's "on this page" navigation: `id` matches the
  *  `SectionProps.id` of the section it scrolls to. */

package/dist/web/layout/notification-bell.d.ts

@@ -0,0 +1,5 @@
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+export declare function NotificationBell({ screens, }: {
+    readonly screens: readonly ScreenDefinition[];
+}): ReactNode;

package/dist/web/layout/notification-bell.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Bell } from "lucide-react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { useState } from "react";
+import { lastSegment, useLocale, useNav, useTranslation } from "../../index.js";
+import { useRelativeTimeFormatter } from "../app/relative-time.js";
+import { cn } from "../lib/cn.js";
+import { useInAppInbox } from "./use-in-app-inbox.js";
+const MAX_BADGE_COUNT = 99;
+const triggerClass = "relative inline-flex size-8 shrink-0 items-center justify-center rounded-md border border-input " +
+    "bg-background text-foreground shadow-xs transition-colors hover:bg-accent " +
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+const panelClass = "z-50 flex max-h-[28rem] w-[min(22rem,calc(100vw-1.5rem))] flex-col overflow-hidden rounded-md border " +
+    "bg-popover text-popover-foreground shadow-md";
+export function NotificationBell({ screens, }) {
+    const t = useTranslation();
+    const nav = useNav();
+    const locale = useLocale().locale();
+    const formatRelative = useRelativeTimeFormatter(locale);
+    const [open, setOpen] = useState(false);
+    const inbox = useInAppInbox(open);
+    const badge = inbox.unreadCount > MAX_BADGE_COUNT ? `${MAX_BADGE_COUNT}+` : String(inbox.unreadCount);
+    const label = inbox.unreadCount > 0
+        ? t("kumiko.notifications.labelUnread", { count: badge })
+        : t("kumiko.notifications.label");
+    const openRow = async (row) => {
+        if (!row.isRead)
+            await inbox.markRead(row.id);
+        const target = row.target;
+        if (target === null)
+            return;
+        if (!screens.some((screen) => screen.id === target.screenId))
+            return;
+        const screenId = lastSegment(target.screenId);
+        setOpen(false);
+        nav.navigate(target.entityId === undefined ? { screenId } : { screenId, entityId: target.entityId });
+    };
+    return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Trigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": label, "data-kumiko-layout": "notification-bell", className: triggerClass, children: [_jsx(Bell, { className: "size-4", "aria-hidden": "true" }), inbox.unreadCount > 0 && (_jsx("span", { "data-kumiko-layout": "notification-bell-badge", className: "absolute -right-1.5 -top-1.5 flex min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-semibold leading-4 text-destructive-foreground", children: badge }))] }) }), _jsx(PopoverPrimitive.Portal, { children: _jsxs(PopoverPrimitive.Content, { align: "end", sideOffset: 6, className: panelClass, children: [_jsxs("div", { className: "flex items-center justify-between gap-2 border-b border-border px-3 py-2", children: [_jsx("h2", { className: "text-sm font-semibold", children: t("kumiko.notifications.title") }), inbox.unreadCount > 0 && (_jsx("button", { type: "button", className: "text-xs text-primary hover:underline", onClick: () => void inbox.markAllRead(), children: t("kumiko.notifications.markAllRead") }))] }), _jsxs("div", { className: "min-h-0 flex-1 overflow-y-auto", children: [inbox.failed && (_jsx("p", { role: "alert", className: "px-3 py-4 text-sm text-destructive", children: t("kumiko.notifications.loadFailed") })), !inbox.failed && !inbox.loading && inbox.rows.length === 0 && (_jsx("p", { className: "px-3 py-6 text-center text-sm text-muted-foreground", children: t("kumiko.notifications.empty") })), _jsx("ul", { children: inbox.rows.map((row) => (_jsx("li", { children: _jsxs("button", { type: "button", "data-unread": row.isRead ? undefined : "true", className: "flex w-full items-start gap-2 border-b border-border px-3 py-2 text-left hover:bg-accent focus-visible:bg-accent focus-visible:outline-none", onClick: () => void openRow(row), children: [_jsx("span", { "aria-hidden": "true", className: cn("mt-1.5 size-2 shrink-0 rounded-full", row.isRead ? "bg-transparent" : "bg-primary") }), !row.isRead && (_jsx("span", { className: "sr-only", children: t("kumiko.notifications.unread") })), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: cn("block truncate text-sm", !row.isRead && "font-semibold"), children: row.title }), row.body !== null && (_jsx("span", { className: "block truncate text-xs text-muted-foreground", children: row.body })), _jsx("span", { className: "block text-xs text-muted-foreground", children: formatRelative(Date.parse(row.createdAt)) })] })] }) }, row.id))) }), inbox.hasMore && (_jsx("button", { type: "button", className: "w-full px-3 py-2 text-sm text-primary hover:bg-accent", onClick: () => void inbox.loadMore(), children: t("kumiko.notifications.loadMore") }))] })] }) })] }));
+}

package/dist/web/layout/shell-header.js

@@ -7,6 +7,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // The `data-kumiko-layout="shell-header"` marker drives `--shell-header-height`
 // in styles.css (:has() selector) — the single source for the header height
 // that Drawer's `belowHeader` prop also reads.
+import { IN_APP_NOTIFICATION_FEATURE } from "@cosmicdrift/kumiko-types/in-app-notification-types";
 import { MoreHorizontal } from "lucide-react";
 import { Fragment, useEffect, useId, useMemo, useRef, useState, } from "react";
 import { resolveNavigation } from "../../headless/index.js";
@@ -17,6 +18,7 @@ import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbP
 import { SidebarTrigger } from "../ui/sidebar.js";
 import { HeaderOverflowMenuContext, headerOverflowMenuItemClass } from "./header-overflow-menu.js";
 import { buildNavRegistrySliceForApp } from "./nav-tree.js";
+import { NotificationBell } from "./notification-bell.js";
 import { usePageHeaderSlot } from "./page-header-slot.js";
 import { activeNavLabel, resolveDetailBreadcrumb, screenTitleKey, } from "./shell-breadcrumb.js";
 import { SHELL_HEADER_CONTROLS_CLASSES } from "./uniform-bar-controls.js";
@@ -35,6 +37,7 @@ export function ShellHeader({ schema, user, headerActions, allowedNavQns, }) {
         return resolveNavigation({ source, ...(user !== undefined && { user }) });
     }, [appSchema, user, allowedNavQns]);
     const allScreens = useMemo(() => appSchema.features.flatMap((f) => f.screens), [appSchema.features]);
+    const hasInAppChannel = appSchema.features.some((feature) => feature.featureName === IN_APP_NOTIFICATION_FEATURE);
     const slot = usePageHeaderSlot();
     const standInScreenId = slot?.breadcrumbScreenId;
     const screenId = standInScreenId ?? nav.route?.screenId;
@@ -78,7 +81,7 @@ export function ShellHeader({ schema, user, headerActions, allowedNavQns, }) {
                                                     e.preventDefault();
                                                     nav.navigate({ screenId });
                                                 }, children: crumb.label })) : isLast ? (_jsx("h1", { "aria-current": "page", title: titleOverride ?? crumb.label, className: "truncate text-lg font-semibold text-foreground", children: titleOverride ?? crumb.label })) : (_jsx(BreadcrumbPage, { className: "whitespace-nowrap text-foreground-secondary", children: crumb.label })) })] }, screenId ?? crumb.label));
-                            }) }) })), _jsx("div", { ref: setStatusElement, "data-kumiko-layout": "page-header-status", className: cn("flex items-center gap-2 empty:hidden", compact ? "min-w-0 overflow-hidden" : "shrink-0") })] }), _jsxs("div", { className: cn("ml-auto flex items-center gap-2", compact ? "min-w-0 max-w-[60%]" : "min-w-0 max-w-[50%] shrink-0 sm:max-w-none"), children: [_jsx("div", { ref: setActionsElement, "data-kumiko-layout": "page-header-actions", className: cn(SHELL_HEADER_CONTROLS_CLASSES, "flex min-w-0 items-center gap-2 empty:hidden [&_*]:min-w-0 [&_*]:max-w-full [&_button]:overflow-hidden [&_button]:whitespace-nowrap", compact && "overflow-hidden") }), !compact && headerActions !== undefined && (_jsx("div", { "data-kumiko-layout": "header-actions", className: "flex items-center gap-2", children: headerActions })), hasOverflow && _jsx(HeaderOverflow, { items: overflowItems, headerActions: headerActions })] })] }));
+                            }) }) })), _jsx("div", { ref: setStatusElement, "data-kumiko-layout": "page-header-status", className: cn("flex items-center gap-2 empty:hidden", compact ? "min-w-0 overflow-hidden" : "shrink-0") })] }), _jsxs("div", { className: cn("ml-auto flex items-center gap-2", compact ? "min-w-0 max-w-[60%]" : "min-w-0 max-w-[50%] shrink-0 sm:max-w-none"), children: [_jsx("div", { ref: setActionsElement, "data-kumiko-layout": "page-header-actions", className: cn(SHELL_HEADER_CONTROLS_CLASSES, "flex min-w-0 items-center gap-2 empty:hidden [&_*]:min-w-0 [&_*]:max-w-full [&_button]:overflow-hidden [&_button]:whitespace-nowrap", compact && "overflow-hidden") }), user !== undefined && hasInAppChannel && _jsx(NotificationBell, { screens: allScreens }), !compact && headerActions !== undefined && (_jsx("div", { "data-kumiko-layout": "header-actions", className: "flex items-center gap-2", children: headerActions })), hasOverflow && _jsx(HeaderOverflow, { items: overflowItems, headerActions: headerActions })] })] }));
 }
 // A hand-rolled menu instead of Radix DropdownMenu: app headerActions are opaque
 // nodes with their own popovers, and the panel stays mounted while closed so their

package/dist/web/layout/use-in-app-inbox.d.ts

@@ -0,0 +1,15 @@
+import { type InAppInboxRow } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+export declare const IN_APP_INBOX_PAGE_SIZE = 20;
+export type InAppInbox = {
+    readonly unreadCount: number;
+    readonly rows: readonly InAppInboxRow[];
+    readonly hasMore: boolean;
+    readonly loading: boolean;
+    readonly failed: boolean;
+    readonly loadMore: () => Promise<void>;
+    readonly markRead: (id: number) => Promise<void>;
+    readonly markAllRead: () => Promise<void>;
+};
+/** Headless state of the notification bell: the unread count always, the list only while `open`.
+ *  The delivered signal refetches both; no polling. */
+export declare function useInAppInbox(open: boolean): InAppInbox;