@cosmicdrift/kumiko-renderer 0.333.0 → 0.335.0

package/dist/primitives.d.ts

@@ -123,11 +123,28 @@ export type FieldProps = {
     readonly issues?: readonly FieldIssue[];
     readonly labelAppendix?: ReactNode;
     readonly fieldAppendix?: ReactNode;
+    /** Where `fieldAppendix` sits relative to the control. Default
+     *  `above-control` (a disclosure panel belongs under its label-row
+     *  trigger); `below-control` keeps sibling inputs on one line when the
+     *  appendix is a status line or an expanded detail. */
+    readonly appendixPlacement?: "above-control" | "below-control";
+    /** Help text directly under the label, above the control. */
+    readonly description?: ReactNode;
+    /** Status pill at the right end of the label row (e.g. "Saved", "Not set"). */
+    readonly status?: {
+        readonly tone: StatusTone;
+        readonly label: string;
+        readonly testId?: string;
+    };
     readonly children: ReactNode;
     /** Label-Layout. `stacked` (Default): Label über dem Control. `inline`:
      *  Control + Label nebeneinander (Box links, Label rechts) — für
      *  Checkbox/Switch-Felder (boolean), wie das shadcn-Muster. */
-    readonly layout?: "stacked" | "inline";
+    readonly layout?: "stacked" | "inline" | "row";
+    /** Marks a field whose value is set at this level (differs from the
+     *  inherited one). Only `layout="row"` draws it: a 2px primary line on the
+     *  row's left edge. Ignored by the other layouts. */
+    readonly accent?: boolean;
     /** Collapses the visible label to `sr-only` — stays associated via
      *  `htmlFor` (no separate `aria-label` needed). For tables/grids whose
      *  column header already carries the label for each row. */
@@ -141,6 +158,12 @@ export type FieldProps = {
 /** Discriminated union — jede Input-Sorte hat ihre eigene value/onChange
  *  Signatur. Custom-Impls dispatchen intern, rendern anders (Toggle
  *  statt Checkbox), oder nur einzelne kinds unterschiedlich. */
+export type TrailingInputAction = {
+    readonly icon: "clear" | "undo";
+    readonly label: string;
+    readonly onPress: () => void;
+    readonly testId?: string;
+};
 export type InputProps = {
     readonly kind: "text";
     readonly id: string;
@@ -198,6 +221,9 @@ export type InputProps = {
      *  Browser-Password-Manager nutzen das für die Speicherentscheidung.
      *  Native: textContentType="password" / "newPassword". */
     readonly autoComplete?: "current-password" | "new-password";
+    /** Icon button inside the field's trailing edge (clear a stored value,
+     *  undo a pending removal). `label` is its accessible name + tooltip. */
+    readonly trailingAction?: TrailingInputAction;
     readonly testId?: string;
 } | {
     readonly kind: "number";
@@ -299,8 +325,13 @@ export type InputProps = {
     readonly options: readonly string[] | readonly {
         readonly value: string;
         readonly label: string;
-        /** Second line under the label; shown by `radioVariant="card"`. */
+        /** Muted second line under the label (radio list and dropdown items;
+         *  the dropdown search matches it too). */
         readonly description?: string;
+        /** Group heading. Groups form in order of first occurrence; options
+         *  without a group stay ungrouped and come before all groups. Options
+         *  with description or group never render as a segmented control. */
+        readonly group?: string;
     }[];
     readonly disabled?: boolean;
     readonly required?: boolean;
@@ -837,8 +868,8 @@ export type FormProps = {
      *  detail screens (which also fill the height) do not set it. Native impls
      *  may ignore this prop. */
     readonly screenForm?: boolean;
-    /** Number of unsaved changes, shown in the pinned footer. Omitted in create
-     *  mode and when nothing changed — the footer then shows no status. */
+    /** Number of unsaved changes, shown in the pinned footer; 0 shows the quiet
+     *  "No unsaved changes" status. Omitted (create mode) — no status at all. */
     readonly unsavedCount?: number;
     /** Drawer-hosted forms: context box above the fields. */
     readonly summary?: {
@@ -870,6 +901,9 @@ export type SectionProps = {
      *  title-less/subtitle-less Section still draws the row when `actions`
      *  is set, so a hideTitle tabs-Section with actions isn't stranded. */
     readonly actions?: ReactNode;
+    /** "settings-list": title + subtitle form a left header column and the
+     *  children (field rows) the right one on `md:` and up. Default "stacked". */
+    readonly layout?: "stacked" | "settings-list";
     /** "destructive" marks the Section as a warning/danger area (e.g. account
      *  deletion, restrict processing) — border color only, no content change.
      *  Default "default" (normal card border). */
@@ -920,6 +954,13 @@ export type GridProps = {
     /** Fields flow left to right in wrapping rows sized by `GridCell.width`
      *  instead of equal-width tracks (screen forms and drawers). */
     readonly flow?: boolean;
+    /** One full-width row per child, separated by hairlines — the field rows of
+     *  a `settings-list` section. Wins over `columns`/`flow`. */
+    readonly list?: boolean;
+    /** Id of the element naming this grid (a Field label). Turns the grid into
+     *  a `role="group"` so a Field whose control is a set of inputs (checkbox
+     *  group) still gives screen readers a group name. */
+    readonly ariaLabelledBy?: string;
 };
 /** Width class of a field cell inside a `flow` grid: sized by what the field holds. */
 export type FieldCellWidth = "text" | "number" | "money" | "date" | "timestamp" | "select" | "full" | "toggle";
@@ -1036,19 +1077,19 @@ export type ConfigSourceBadgeProps = {
      *  rule as ConfigCascadeView's toDisplayLevels. */
     readonly screenScope?: ConfigScope;
 };
-/** Collapsible cascade-view for a config-edit field. Split into two slots
- *  (#429): "trigger" is the collapsed ▶ + source + value line for the label
- *  row; "panel" is the expanded cascade + reset shown below the input. In
- *  split mode the screen owns the `expanded` state (both slots share it);
- *  without `slot` the component renders both with its own state. */
+/** Cascade view for a config-edit field: one origin line ("Set for this
+ *  tenant", "Uses the default", …), a reset action for an own value, and a
+ *  disclosure listing every level. Owns its disclosure state. */
 export type ConfigCascadeViewProps = {
     readonly cascade: ConfigCascade;
     readonly screenScope: ConfigScope;
     readonly onReset?: (key: string, scope: ConfigScope) => void;
     readonly qualifiedKey?: string;
-    readonly slot?: "trigger" | "panel";
-    readonly expanded?: boolean;
-    readonly onToggle?: () => void;
+    /** The key declares `required: true` — a missing value reads "Not set. Required.". */
+    readonly required?: boolean;
+    /** Display form of a level value (e.g. a select's label instead of its raw
+     *  value). Absent = the raw value; a missing value keeps the no-value text. */
+    readonly renderValue?: (value: string | number | boolean) => ReactNode;
 };
 /** Card-Slots — benannte Inhalts-Regionen, alle optional. Neue Slots später =
  *  rein additiv → Consumer müssen NIE migriert werden. `header` ist der Escape-
@@ -1058,9 +1099,9 @@ export type CardSlots = {
     readonly header?: ReactNode;
     readonly title?: ReactNode;
     readonly subtitle?: ReactNode;
-    /** Free-form block content left of `headerActions`, below title/subtitle —
-     *  for a host-supplied header (projectionDetail `slots.header`) that must
-     *  share the action row instead of pushing actions into a row of their own. */
+    /** Free-form block content in its own full-width row below the
+     *  title/subtitle/`headerActions` row, within the same header block — for a
+     *  host-supplied header (projectionDetail `slots.header`). */
     readonly headerContent?: ReactNode;
     /** Rechtsbündiger Header-Slot (Range-Umschalter, Filter, Badge …). */
     readonly headerActions?: ReactNode;
@@ -1082,6 +1123,11 @@ export type CardOptions = {
     /** false drops border, background, shadow and radius but keeps padding and
      *  header slots — a panel inside a host surface such as a tab panel. Default true. */
     readonly framed?: boolean;
+    /** The card is the whole screen body (secretMint reveal and done phase):
+     *  no frame, the shared screen insets and width of form screens, children
+     *  stacked with a gap. Without it such a screen sits raw against the
+     *  shell edge. Default false. */
+    readonly screenBody?: boolean;
 };
 /** Generische Card-Chrome (border/bg/radius/shadow + Header/Body/Footer) als
  *  Primitive — eine Quelle für alle Card-Flächen, statt pro App nachgebaut.
@@ -1107,10 +1153,9 @@ export type ProgressProps = {
     readonly testId?: string;
 };
 /** Wizard step overview — numbered chips, one per step label, with the
- *  active step highlighted. With `onStepSelect`, completed steps (index
- *  below `currentIndex`) become buttons for going back; forward jumps stay
- *  impossible because step-jump validation is a separate concern
- *  (kumiko-framework#1966). Implementations render a
+ *  active step highlighted. With `onStepSelect`, completed steps become
+ *  buttons (every non-current step with `selectableSteps: "all"`); the caller
+ *  owns the validation gate for forward jumps. Implementations render a
  *  narrow-viewport fallback showing `compactLabel` instead (caller
  *  supplies it pre-translated, e.g. "Step 2 of 5 · Industry") — which of
  *  the two is visible is a responsive layout choice owned by the
@@ -1120,6 +1165,12 @@ export type StepBarProps = {
     readonly currentIndex: number;
     readonly compactLabel: string;
     readonly onStepSelect?: (index: number) => void;
+    /** Explicit done state per step index. Absent: a step is done when its
+     *  index is below `currentIndex`. The current step is never done. */
+    readonly doneSteps?: readonly boolean[];
+    /** "done" (default): only done steps are jump targets. "all": every
+     *  non-current step is, when `onStepSelect` is set. */
+    readonly selectableSteps?: "done" | "all";
     /** "label" (default) swaps the step row for `compactLabel` on narrow
      *  viewports; "steps" keeps the row there too — for short wizards whose
      *  labels fit a phone and whose done steps must stay tappable. */

package/dist/session/session-ended.d.ts

@@ -0,0 +1,16 @@
+import type { Dispatcher, DispatcherError } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode } from "react";
+export declare const SESSION_ENDED_ERROR_CODES: readonly ["session_invalid", "invalid_token", "missing_token", "unauthenticated"];
+export declare function isSessionEndedError(error: Pick<DispatcherError, "code" | "httpStatus">): boolean;
+export type SessionEndedSignal = {
+    notify(): void;
+    subscribe(listener: () => void): () => void;
+};
+export declare function createSessionEndedSignal(): SessionEndedSignal;
+export declare function withSessionEndedDetection(dispatcher: Dispatcher, signal: SessionEndedSignal): Dispatcher;
+export type SessionEndedSignalProviderProps = {
+    readonly signal: SessionEndedSignal;
+    readonly children: ReactNode;
+};
+export declare function SessionEndedSignalProvider({ signal, children, }: SessionEndedSignalProviderProps): ReactNode;
+export declare function useSessionEndedSignal(): SessionEndedSignal | undefined;

package/dist/session/session-ended.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+// Only auth-layer 401s end a session. Handlers never throw 401 otherwise and
+// 403 means "authenticated but not allowed", which must not log the user out.
+export const SESSION_ENDED_ERROR_CODES = [
+    "session_invalid",
+    "invalid_token",
+    "missing_token",
+    "unauthenticated",
+];
+export function isSessionEndedError(error) {
+    return (error.httpStatus === 401 &&
+        SESSION_ENDED_ERROR_CODES.some((sessionEndedCode) => sessionEndedCode === error.code));
+}
+function isSessionEndedThrow(thrown) {
+    if (typeof thrown !== "object" || thrown === null)
+        return false;
+    if (!("code" in thrown) || !("httpStatus" in thrown))
+        return false;
+    const { code, httpStatus } = thrown;
+    return typeof code === "string" && typeof httpStatus === "number"
+        ? isSessionEndedError({ code, httpStatus })
+        : false;
+}
+export function createSessionEndedSignal() {
+    const listeners = new Set();
+    return {
+        notify() {
+            for (const listener of [...listeners])
+                listener();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+export function withSessionEndedDetection(dispatcher, signal) {
+    async function detect(pending) {
+        const result = await pending;
+        if (!result.isSuccess && result.error !== undefined && isSessionEndedError(result.error)) {
+            signal.notify();
+        }
+        return result;
+    }
+    return {
+        write: (type, payload, opts) => detect(dispatcher.write(type, payload, opts)),
+        query: (type, payload, opts) => detect(dispatcher.query(type, payload, opts)),
+        batch: (commands, opts) => detect(dispatcher.batch(commands, opts)),
+        async *stream(type, payload, opts) {
+            try {
+                yield* dispatcher.stream(type, payload, opts);
+            }
+            catch (thrown) {
+                if (isSessionEndedThrow(thrown))
+                    signal.notify();
+                throw thrown;
+            }
+        },
+        statusStore: dispatcher.statusStore,
+        pendingWrites: () => dispatcher.pendingWrites(),
+        pendingFiles: () => dispatcher.pendingFiles(),
+    };
+}
+const SessionEndedSignalContext = createContext(undefined);
+export function SessionEndedSignalProvider({ signal, children, }) {
+    return _jsx(SessionEndedSignalContext, { value: signal, children: children });
+}
+export function useSessionEndedSignal() {
+    return useContext(SessionEndedSignalContext);
+}

package/dist/sort-by-accessor.d.ts

@@ -1,5 +1,9 @@
 import type { DataTableSort } from "./primitives.js";
+type SortValue = string | number | null;
 /** Sorts `rows` by a `DataTableSort` against a field->accessor map. Unknown
  *  field or `sort === null` returns `rows` unchanged (no-op, not an error —
- *  callers pass whatever the DataTable reports). */
-export declare function sortByAccessor<TRow>(rows: readonly TRow[], sort: DataTableSort | null, accessors: Readonly<Record<string, (row: TRow) => string | number>>): readonly TRow[];
+ *  callers pass whatever the DataTable reports). `null` values sort last in
+ *  both directions; strings compare locale-aware with numeric collation, so
+ *  numeric strings (Postgres numeric/bigint) order by value. */
+export declare function sortByAccessor<TRow>(rows: readonly TRow[], sort: DataTableSort | null, accessors: Readonly<Record<string, (row: TRow) => SortValue>>, locale?: string): readonly TRow[];
+export {};

package/dist/sort-by-accessor.js

@@ -1,16 +1,26 @@
+function compareNonNull(a, b, collator) {
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    return collator.compare(String(a), String(b));
+}
 /** Sorts `rows` by a `DataTableSort` against a field->accessor map. Unknown
  *  field or `sort === null` returns `rows` unchanged (no-op, not an error —
- *  callers pass whatever the DataTable reports). */
-export function sortByAccessor(rows, sort, accessors) {
+ *  callers pass whatever the DataTable reports). `null` values sort last in
+ *  both directions; strings compare locale-aware with numeric collation, so
+ *  numeric strings (Postgres numeric/bigint) order by value. */
+export function sortByAccessor(rows, sort, accessors, locale) {
     if (sort === null)
         return rows;
     const accessor = accessors[sort.field];
     if (accessor === undefined)
         return rows;
     const factor = sort.dir === "asc" ? 1 : -1;
+    const collator = new Intl.Collator(locale, { numeric: true, sensitivity: "base" });
     return [...rows].sort((a, b) => {
         const av = accessor(a);
         const bv = accessor(b);
-        return av < bv ? -factor : av > bv ? factor : 0;
+        if (av === null || bv === null)
+            return av === bv ? 0 : av === null ? 1 : -1;
+        return factor * compareNonNull(av, bv, collator);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.333.0",
+  "version": "0.335.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.333.0",
-    "@cosmicdrift/kumiko-headless": "0.333.0",
-    "@cosmicdrift/kumiko-types": "0.333.0",
+    "@cosmicdrift/kumiko-framework": "0.335.0",
+    "@cosmicdrift/kumiko-headless": "0.335.0",
+    "@cosmicdrift/kumiko-types": "0.335.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.333.0"
+    "@cosmicdrift/kumiko-locale-de": "0.335.0"
   },
   "repository": {
     "type": "git",

package/src/changes.json

@@ -1,4 +1,44 @@
 [
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "secretMint reveal and confirm render as one screen form with the translated screen title; new RenderEdit props leadContent and i18nScreenId"
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Router paths encode and decode each segment, so entity ids with slashes or spaces round-trip"
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Icon-only list and edit action buttons set a hover title"
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Secret delete confirmation, grouped-field conditions, scoped valid flag, tenant currency in reference-create dialog",
+    "detail": "Renderer review fixes. Deleting a secret on a secretsEdit screen now asks for confirmation first (new `config.secrets.deleteConfirm` key) and the delete button is disabled while a save or delete is running. The multiSelect checkbox group is exposed as a labelled group (`GridProps.ariaLabelledBy`). The inline reference-create dialog seeds `currency: { kind: \"tenant\" }` money fields from the tenant currency. Fields declared only inside a section `groups` entry now get their `visible`/`readOnly`/`required` conditions registered. `onChange`'s `valid` ignores issues on hidden fields and outside the `fields` scope, like submit does (shared `relevantFieldIssues` helper). Copy-link in the form footer keeps a 44px touch target on narrow viewports. A free-text sibling-field number unit longer than 8 characters is no longer rendered as a suffix."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Scoped validation matches exact paths, root refine issues are visible, tabs keep the active tab by id, update redirects use the saved FK, related list sorting handles numeric strings, nulls and locales",
+    "detail": "Form and list fixes. A scoped `validate()` entry such as `address.city` no longer reports sibling issues like `address.zip`. Root-level `.refine()` issues now show as a banner in `RenderEdit` instead of blocking submit silently. In tabs mode the active tab follows its id when a field change hides an earlier tab, and an explicit subtitle override is kept. An entityEdit update redirect with `idFrom` reads the saved projection, so a changed parent FK redirects to the new parent. A row-extractor key missing from the row no longer wipes the target field's default. `relatedList` client-side sorting orders numeric strings by value, puts empty values last and compares text locale-aware. A reference list facet warns in dev when the lookup hits its row cap."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "writeForm section shows the error banner for issues no rendered field can display",
+    "detail": "A writeForm section keeps its error banner when the server reports an issue no rendered field can show (`version`, `id`, a root-level refine, a hidden field), instead of failing the save without any visible message."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "Wizard editing an existing record shows data-based done state and allows jumping to any step; delete record actions leave the screen",
+    "detail": "Update-mode wizards compute done per step from the record (valid, non-empty fields, or passed via Next) and make every non-current step a jump target; forward jumps run the current step's validate gate. `ExtensionSectionProps.reportStepComplete` lets extension steps report completeness. `StepBar` gets `doneSteps` and `selectableSteps`. A writeHandler record action with `redirect`, or a delete of the shown record, navigates away (returnTo, redirect, listScreenId, entity list) instead of refetching.",
+    "migration": "Extension wizard steps in an entityEdit that edits an existing record should call `reportStepComplete(true)` (usually from an effect) once they hold their data, otherwise the step bar shows them as not done until the user passes them with Next. This also applies to singleton wizards (e.g. a company-setup wizard), whose steps now show done by data and are all jump targets; tests that assumed back-only chips must be updated. A delete writeHandler action on a projectionDetail or entityEdit now navigates away after success (returnTo, else listScreenId or the entity's list) instead of refetching into \"record not found\"; set `redirect` to choose another target. List row actions are unchanged."
+  },
   {
     "version": "0.333.0",
     "type": "improvement",