@cosmicdrift/kumiko-headless 0.333.0 → 0.335.0

package/dist/form/form-controller.js

@@ -1,5 +1,5 @@
 import { createStore } from "../store/index.js";
-import { groupIssuesByPath, zodErrorToFieldIssues } from "./zod-bridge.js";
+import { groupIssuesByPath, relevantFieldIssues, zodErrorToFieldIssues } from "./zod-bridge.js";
 // Paths without the prefix (hook-level errors, "(root)") pass through unchanged.
 function stripServerFieldPathPrefix(issues, prefix) {
     return issues.map((issue) => issue.path.startsWith(prefix) ? { ...issue, path: issue.path.slice(prefix.length) } : issue);
@@ -139,15 +139,15 @@ export function createFormController(options) {
     // the scope — a step-2 validate() that comes back clean must not wipe
     // step-1's still-unresolved errors from an earlier submit() (or vice
     // versa when step-2 newly has issues).
-    function replaceScopedErrors(scopeSet, grouped) {
-        if (scopeSet === undefined) {
+    function replaceScopedErrors(isInScope, grouped) {
+        if (isInScope === undefined) {
             errors = Object.freeze(grouped);
             // skip: unscoped replace — wholesale overwrite, nothing left to merge
             return;
         }
         const merged = {};
         for (const [path, issues] of Object.entries(errors)) {
-            if (!scopeSet.has(path))
+            if (!isInScope(path))
                 merged[path] = issues;
         }
         Object.assign(merged, grouped);
@@ -155,13 +155,15 @@ export function createFormController(options) {
     }
     function runValidate(scope, opts) {
         // See the validate() doc comment in types.ts for the scope contract.
-        // Normalize nested scope entries (`address.city` → `address`) so wizard
-        // callers that pass dotted paths still match issue root segments (#1898).
-        const scopeSet = scope === undefined ? undefined : new Set(scope.map((s) => s.split(".")[0] ?? s));
+        // A scope entry matches its exact path and everything below it, but not
+        // siblings: `address.city` must not pull in `address.zip` (#1898).
+        const isInScope = scope === undefined
+            ? undefined
+            : (path) => scope.some((entry) => path === entry || path.startsWith(`${entry}.`));
         const includeRoot = opts?.includeRoot === true;
         if (!options.schema) {
             if (Object.keys(errors).length > 0) {
-                replaceScopedErrors(scopeSet, {});
+                replaceScopedErrors(isInScope, {});
                 invalidate();
             }
             return true;
@@ -170,7 +172,7 @@ export function createFormController(options) {
         const parsed = options.schema.safeParse(values);
         if (parsed.success) {
             if (Object.keys(errors).length > 0) {
-                replaceScopedErrors(scopeSet, {});
+                replaceScopedErrors(isInScope, {});
                 invalidate();
             }
             return true;
@@ -180,28 +182,22 @@ export function createFormController(options) {
             if (!state.visible)
                 hiddenFields.add(fieldKey);
         }
-        const allIssues = zodErrorToFieldIssues(parsed.error);
-        const relevantIssues = allIssues.filter((issue) => {
-            const rootField = issue.path.split(".")[0] ?? "";
-            if (hiddenFields.has(rootField))
-                return false;
-            // Root-level .refine() issues use path "(root)". Wizard step validate()
-            // still drops them (#1885); submit() passes includeRoot so RenderEdit
-            // fields={…} cannot silently skip cross-field rules (#1907).
-            const isRootIssue = issue.path === "(root)";
-            if (scopeSet && !(includeRoot && isRootIssue) && !scopeSet.has(rootField)) {
-                return false;
-            }
-            return true;
+        // Root-level .refine() issues use path "(root)". Wizard step validate()
+        // still drops them (#1885); submit() passes includeRoot so RenderEdit
+        // fields={…} cannot silently skip cross-field rules (#1907).
+        const relevantIssues = relevantFieldIssues(zodErrorToFieldIssues(parsed.error), {
+            hiddenFields,
+            ...(scope !== undefined && { scope }),
+            includeRoot,
         });
         if (relevantIssues.length === 0) {
             if (Object.keys(errors).length > 0) {
-                replaceScopedErrors(scopeSet, {});
+                replaceScopedErrors(isInScope, {});
                 invalidate();
             }
             return true;
         }
-        replaceScopedErrors(scopeSet, groupIssuesByPath(relevantIssues));
+        replaceScopedErrors(isInScope, groupIssuesByPath(relevantIssues));
         invalidate();
         return false;
     }

package/dist/form/index.d.ts

@@ -1,3 +1,3 @@
 export { createFormController } from "./form-controller.js";
 export type { FieldConditionPredicate, FieldConditions, FieldConditionValue, FieldState, FormController, FormControllerOptions, FormSnapshot, FormValues, SubmitConfig, SubmitPayloadMode, SubmitResult, } from "./types.js";
-export { groupIssuesByPath, I18N_KEY_PARAM, zodErrorToFieldIssues } from "./zod-bridge.js";
+export { groupIssuesByPath, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./zod-bridge.js";

package/dist/form/index.js

@@ -1,2 +1,2 @@
 export { createFormController } from "./form-controller.js";
-export { groupIssuesByPath, I18N_KEY_PARAM, zodErrorToFieldIssues } from "./zod-bridge.js";
+export { groupIssuesByPath, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./zod-bridge.js";

package/dist/form/zod-bridge.d.ts

@@ -1,5 +1,10 @@
 import type { ZodError } from "zod";
 import type { FieldIssue } from "../dispatcher/index.js";
 export declare function zodErrorToFieldIssues(error: ZodError): FieldIssue[];
+export declare function relevantFieldIssues(issues: readonly FieldIssue[], opts: {
+    readonly hiddenFields: ReadonlySet<string>;
+    readonly scope?: readonly string[];
+    readonly includeRoot?: boolean;
+}): FieldIssue[];
 export declare const I18N_KEY_PARAM = "i18nKey";
 export declare function groupIssuesByPath(issues: readonly FieldIssue[]): Record<string, readonly FieldIssue[]>;

package/dist/form/zod-bridge.js

@@ -44,6 +44,24 @@ export function zodErrorToFieldIssues(error) {
         };
     });
 }
+// The issues that count for validity: hidden fields never block, and a
+// scope narrows to the listed paths (an entry matches itself and everything
+// below it, not siblings — #1898). `includeRoot` keeps "(root)" refine issues
+// inside a scope (submit passes it, #1907). Shared by the controller's
+// validate() and RenderEdit's `valid` dry-run so the two cannot drift.
+export function relevantFieldIssues(issues, opts) {
+    const { hiddenFields, scope, includeRoot } = opts;
+    return issues.filter((issue) => {
+        const rootField = issue.path.split(".")[0] ?? "";
+        if (hiddenFields.has(rootField))
+            return false;
+        if (scope === undefined)
+            return true;
+        if (includeRoot === true && issue.path === "(root)")
+            return true;
+        return scope.some((entry) => issue.path === entry || issue.path.startsWith(`${entry}.`));
+    });
+}
 // Same magic key both sides of a superRefine can set to opt out of the
 // generic `errors.validation.custom` message — see form-schema.ts.
 export const I18N_KEY_PARAM = "i18nKey";

package/dist/index.d.ts

@@ -4,11 +4,11 @@ export type { AssetResolution, AssetResolveContext, AssetResolver, BadgeProps, B
 export type { BatchResult, Command, Dispatcher, DispatcherError, DispatcherStatus, FieldIssue, PendingFile, PendingWrite, QueryOpts, QueryResult, StreamOpts, WriteOpts, WriteResult, } from "./dispatcher/index.js";
 export { StreamFrame, type StreamFrameEvent } from "./dispatcher/index.js";
 export type { FieldConditionPredicate, FieldConditions, FieldConditionValue, FieldState, FormController, FormControllerOptions, FormSnapshot, FormValues, SubmitConfig, SubmitPayloadMode, SubmitResult, } from "./form/index.js";
-export { createFormController, I18N_KEY_PARAM } from "./form/index.js";
+export { createFormController, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./form/index.js";
 export { applyFormatSpec, currencyDecimals, escapeHtml, escapeHtmlAttr, escapeXml, type HtmlValue, html, isSafeHref, RawHtml, raw, stripControlChars, toInstant, } from "./format/index.js";
 export type { NavDefinition, NavNode, NavRegistrySlice, NavTree, ResolveNavigationOptions, } from "./nav/index.js";
 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, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedDerivedOp, EmbeddedListCellViewModel, EmbeddedListIssueGroups, FieldConditionCtx, FieldRenderer, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeRenderer, ScreenSlots, Translate, } from "./view-model/index.js";
-export { computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.js";
+export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.js";

package/dist/index.js

@@ -2,8 +2,8 @@
 // Parser nutzt wie der Server-Boot-Validator (Cross-Feature-Refs).
 export { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 export { StreamFrame } from "./dispatcher/index.js";
-export { createFormController, I18N_KEY_PARAM } from "./form/index.js";
+export { createFormController, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./form/index.js";
 export { applyFormatSpec, currencyDecimals, escapeHtml, escapeHtmlAttr, escapeXml, html, isSafeHref, RawHtml, raw, stripControlChars, toInstant, } from "./format/index.js";
 export { resolveNavigation } from "./nav/index.js";
 export { createStore, shallowEqual } from "./store/index.js";
-export { computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.js";
+export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.js";

package/dist/locale-routing/index.d.ts

@@ -25,7 +25,9 @@ export type WrapUrlLocaleResolverOptions = {
     resolvePage: (pathname: string) => string | undefined;
     detectLang: (pathname: string) => string;
     pathname?: () => string | undefined;
-    /** Optional pathname-change subscription (browser default: popstate). */
+    /** Optional pathname-change subscription. Browser default listens to `popstate` only,
+     *  which does not fire on `history.pushState`/`replaceState`: apps with a client-side
+     *  router must supply this themselves. */
     subscribePathname?: (listener: () => void) => () => void;
     /** When set, translate against the URL-resolved locale instead of base.translate
      *  (needed for fixed-T / cloneInstance resolvers that are not locale-live). */

package/dist/view-model/edit.js

@@ -95,9 +95,7 @@ function deriveSelectOptionsQuery(fieldDef) {
         : {};
 }
 function deriveSelectFieldHints(fieldDef, translate, featureName, entityName, fieldName) {
-    const options = fieldDef.type === "select" || fieldDef.type === "multiSelect"
-        ? (fieldDef.options ?? [])
-        : undefined;
+    const options = fieldDef.type === "select" || fieldDef.type === "multiSelect" ? fieldDef.options : undefined;
     const optionLabels = options !== undefined
         ? buildOptionLabels(translate, (value) => fieldOptionLabelKey(featureName, entityName, fieldName, value), options)
         : undefined;
@@ -120,9 +118,11 @@ function deriveTextFieldHints(fieldDef) {
     const format = fieldDef.type === "text"
         ? fieldDef.format
         : undefined;
+    const writeOnly = fieldDef.type === "text" && fieldDef.writeOnly === true;
     return {
         ...(multiline !== undefined && { multiline }),
         ...(format !== undefined && { format }),
+        ...(writeOnly && { writeOnly: true }),
     };
 }
 function deriveDateFieldHints(fieldDef) {
@@ -262,13 +262,17 @@ function deriveEmbeddedListHints(fieldDef, translate, featureName, entityName, f
     };
 }
 function buildExtensionSectionViewModel(sectionSpec, translate) {
+    const entityNameOverride = sectionSpec.entityName?.trim();
     return {
         kind: "extension",
         ...(sectionSpec.id !== undefined && { id: sectionSpec.id }),
         title: translate(sectionSpec.title),
         component: sectionSpec.component,
         contributesToFormSubmit: sectionSpec.contributesToFormSubmit === true,
-        ...(sectionSpec.entityName !== undefined && { entityName: sectionSpec.entityName }),
+        // Blank override must fall back to the host value: the renderer's `??`
+        // would otherwise pass "" through to the mounted extension.
+        ...(entityNameOverride !== undefined &&
+            entityNameOverride.length > 0 && { entityName: entityNameOverride }),
         ...(sectionSpec.actions !== undefined && { actions: sectionSpec.actions }),
     };
 }

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

@@ -3,5 +3,5 @@ export { computeEditViewModel, computeRelatedListSectionViewModel } from "./edit
 export type { DerivedCellRoundingTarget, EmbeddedDerivedOp, EmbeddedListIssueGroups, } from "./embedded-list.js";
 export { computeDerivedCellValue, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./embedded-list.js";
 export type { ComputeListViewModelInput } from "./list.js";
-export { computeListViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, } 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";

package/dist/view-model/index.js

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

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";
+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 —
 // those are list-level decisions that the caller makes BEFORE calling
@@ -116,7 +117,7 @@ export function computeListViewModel(input) {
         // 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 ?? [])
+            ? 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;
@@ -136,9 +137,24 @@ export function computeListViewModel(input) {
         };
         columns.push(column);
     }
+    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) => {
+        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: row,
+        values: showWriteOnlyAsWord(row),
     }));
     return {
         screenId: screen.id,

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

@@ -1,4 +1,4 @@
-import type { EditFieldSpec, EditSectionSpec, FieldIconKey, FieldRenderer, IconKey, ListColumnSpec, ListFacetSpec, ListSortSpec, PlatformComponent, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionMode, ScreenSlots, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
+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;
 export type ListColumnViewModel = {
     readonly field: string;
@@ -85,12 +85,13 @@ export type EditFieldViewModel = {
      *  `<feature>:entity:<entity>:field:<field>:option:<value>`. */
     readonly optionLabels?: Readonly<Record<string, string>>;
     /** Set for `type: "select"` when SelectFieldDef.optionsQuery is set: the
-     *  renderer loads the options from this query (`{ rows: { value, label }[] }`,
-     *  labels verbatim) instead of `options`. `payload` is the static
-     *  optionsQueryPayload, `{}` when absent. */
+     *  renderer loads the options from this query (`{ rows: { value, label,
+     *  description?, group? }[] }`, labels verbatim) instead of `options`. `payload`
+     *  is optionsQueryPayload (`{ field }` refs are resolved by the renderer against
+     *  the live form values), `{}` when absent. */
     readonly selectOptionsQuery?: {
         readonly query: string;
-        readonly payload: Readonly<Record<string, string | number | boolean>>;
+        readonly payload: OptionsQueryPayload;
     };
     /** Set for `type: "multiSelect"` when MultiSelectFieldDef.display is
      *  "checkboxes" — the renderer shows a checkbox grid with a select-all
@@ -116,6 +117,8 @@ export type EditFieldViewModel = {
     };
     /** From TextFieldDef.format — `password` makes the renderer mask the input. */
     readonly format?: "email" | "url" | "phone" | "password";
+    /** From TextFieldDef.writeOnly — value is `true` (set) / `null` (empty), never plaintext. */
+    readonly writeOnly?: true;
     /** Nur bei `type: "timestamp"` gesetzt wenn TimestampFieldDef.locatedBy
      *  existiert — Wall-Clock-Zeit ohne Offset. Der Renderer emittiert
      *  dann lokale Zeit ohne `Z` statt eines UTC-Instants. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.333.0",
+  "version": "0.335.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,7 +36,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.333.0",
+    "@cosmicdrift/kumiko-framework": "0.335.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },