@cosmicdrift/kumiko-renderer 0.346.0 → 0.348.0

package/dist/app/kumiko-screen.js

@@ -13,8 +13,10 @@ import { RenderList } from "../components/render-list.js";
 import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useIsEmbeddedScreen } from "../context/embedded-screen-context.js";
 import { useUserRoles } from "../context/user-roles-context.js";
+import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
 import { PAGE_SIZE_OPTIONS, useListUrlState } from "../hooks/use-list-url-state.js";
 import { useQuery } from "../hooks/use-query.js";
+import { referenceLookupSource } from "../hooks/use-reference-lookup.js";
 import { useLocale, useOptionalTimeZone, useTranslation } from "../i18n.js";
 import { InsideDrawerProvider, useInsideDrawer } from "../inside-drawer.js";
 import { PageHeaderSlotAvailableProvider, usePageHeaderCompact, usePageHeaderSlotAvailable, } from "../page-header-slot.js";
@@ -86,7 +88,8 @@ export function KumikoScreen({ schema, qn, translate, entityId, onRowClick, onCo
     return _jsx(ReturnHostProvider, { value: ownHost, children: body });
 }
 function ScreenVisibilityGate({ featureName, visibleWhen, fallback, translate, children, }) {
-    const { Banner } = usePrimitives();
+    const { Banner, PageHeader } = usePrimitives();
+    const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
     const t = useTranslation();
     const result = useQuery(visibleWhen.query, {}, { live: true });
     const verdict = evalVisibleWhen(visibleWhen, result);
@@ -95,10 +98,9 @@ function ScreenVisibilityGate({ featureName, visibleWhen, fallback, translate, c
     if (verdict === "loading") {
         return (_jsx(Banner, { padded: true, variant: "loading", testId: "kumiko-screen-loading", children: "Loading\u2026" }));
     }
-    if (fallback !== undefined) {
-        return _jsx(FallbackScreen, { featureName: featureName, fallback: fallback, translate: translate });
-    }
-    return (_jsx(Banner, { padded: true, variant: "info", testId: "kumiko-screen-unavailable", children: t("kumiko.screen.unavailable") }));
+    // The route still names the locked screen; its breadcrumb must not label what stands in for it.
+    const hideLockedBreadcrumb = PageHeader !== undefined && pageHeaderSlotAvailable ? _jsx(PageHeader, { hideBreadcrumb: true }) : null;
+    return (_jsxs(_Fragment, { children: [hideLockedBreadcrumb, fallback !== undefined ? (_jsx(FallbackScreen, { featureName: featureName, fallback: fallback, translate: translate })) : (_jsx(Banner, { padded: true, variant: "info", testId: "kumiko-screen-unavailable", children: t("kumiko.screen.unavailable") }))] }));
 }
 function FallbackScreen({ featureName, fallback, translate, }) {
     const target = useEmbeddedScreen(featureName, fallback);
@@ -125,9 +127,12 @@ function renderScreenBody({ schema, screen, translate, entityId, onRowClick, onC
         case "secretMint":
             return _jsx(SecretMintBody, { schema: schema, screen: screen, translate: translate });
         case "configEdit":
-            return _jsx(ConfigEditBody, { schema: schema, screen: screen, translate: translate });
+            // Keyed by screen id: the form state is seeded once at mount, so switching
+            // between two settings screens must remount instead of carrying the
+            // previous screen's (empty) field state over.
+            return (_jsx(ConfigEditBody, { schema: schema, screen: screen, translate: translate }, screen.id));
         case "secretsEdit":
-            return _jsx(SecretsEditBody, { screen: screen, translate: translate });
+            return _jsx(SecretsEditBody, { screen: screen, translate: translate }, screen.id);
         case "custom":
             return _jsx(CustomScreenBody, { screenId: screen.id, featureName: schema.featureName });
     }
@@ -360,6 +365,27 @@ function formatSummaryValue(value, locale) {
 function formatSummaryParams(prefill, locale) {
     return Object.fromEntries(Object.entries(prefill ?? {}).map(([name, value]) => [name, formatSummaryValue(value, locale)]));
 }
+// Placeholders of `successMessage`: formatted submitted values, with a
+// reference field resolved to the chosen record's label. A lookup that fails or
+// misses the row (the lookup list is capped) falls back to the raw id.
+async function resolveSuccessMessageParams(screen, featureName, values, dispatcher, locale) {
+    const params = formatSummaryParams(values, locale);
+    await Promise.all(Object.entries(screen.fields).map(async ([name, def]) => {
+        const raw = values[name];
+        if (def.type !== "reference" || typeof raw !== "string" || raw === "")
+            return;
+        const target = parseRefTarget(def.entity, featureName);
+        const { queryQn, labelKey } = referenceLookupSource(target.featureName, target.entityName, def.labelField ?? "id");
+        const lookup = await dispatcher.query(queryQn, { limit: REFERENCE_LIST_LOOKUP_LIMIT });
+        if (!lookup.isSuccess)
+            return;
+        const row = lookup.data.rows.find((candidate) => candidate["id"] === raw);
+        const label = row?.[labelKey];
+        if (label !== undefined && label !== null)
+            params[name] = String(label);
+    }));
+    return params;
+}
 function resolveActionFormSummary(summary, prefill, translate, locale) {
     if (summary === undefined)
         return undefined;
@@ -2323,13 +2349,34 @@ function ActionFormBody({ schema, screen, translate, initialOverrides, onSuccess
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const summary = useMemo(() => resolveActionFormSummary(screen.summary, initialOverrides, effectiveTranslate, locale), [screen.summary, initialOverrides, effectiveTranslate, locale]);
-    const handleSubmitted = useCallback((result) => {
+    const dispatcher = useDispatcher();
+    const [successText, setSuccessText] = useState(undefined);
+    // A slow label lookup of an earlier submit must not overwrite the banner of a later one.
+    const successSequence = useRef(0);
+    useEffect(() => () => {
+        successSequence.current += 1;
+    }, []);
+    const handleSubmitted = useCallback((result, values) => {
+        successSequence.current += 1;
+        const sequence = successSequence.current;
+        setSuccessText(undefined);
         if (!result.isSuccess)
             return;
         if (onSuccess !== undefined) {
             onSuccess();
             return;
         }
+        if (screen.successMessage !== undefined && screen.redirect === undefined) {
+            const messageKey = screen.successMessage;
+            const show = (params) => {
+                if (successSequence.current === sequence) {
+                    setSuccessText(effectiveTranslate(messageKey, params));
+                }
+            };
+            void resolveSuccessMessageParams(screen, schema.featureName, values, dispatcher, locale)
+                .then(show)
+                .catch(() => show(formatSummaryParams(values, locale)));
+        }
         // Without a redirect the form stays put; returnTo only replaces an existing
         // navigation, and never one to a record screen (see redirectTargetsRecord).
         if (screen.redirect !== undefined) {
@@ -2341,7 +2388,17 @@ function ActionFormBody({ schema, screen, translate, initialOverrides, onSuccess
                 nav.navigate({ screenId, ...(entityId !== undefined && { entityId }) });
             }
         }
-    }, [nav, screen.redirect, onSuccess, schema, appFeatures, returnTarget]);
+    }, [
+        nav,
+        screen,
+        onSuccess,
+        schema,
+        appFeatures,
+        returnTarget,
+        dispatcher,
+        locale,
+        effectiveTranslate,
+    ]);
     // Cancel ist nur sinnvoll wenn ein Navigations-Ziel existiert —
     // sonst hätte der Button nirgendwo hin zu navigieren. cancelTarget
     // gewinnt über redirect; `false` schaltet den Button explizit ab
@@ -2366,7 +2423,9 @@ function ActionFormBody({ schema, screen, translate, initialOverrides, onSuccess
         // (inkl. searchParams-Prefill, z.B. ?incidentId=…) als initialValues
         // — anders als im entityEdit gibt es hier keinen record, aus dem
         // sie Kontext ziehen könnten.
-        extensionInitialValues: initial, writeCommand: screen.handler, payloadMode: "values", onSubmit: handleSubmitted, ...(handleCancel !== undefined && { onCancel: handleCancel }), ...(onDirtyChange !== undefined && { onDirtyChange }), ...((insideDrawer || screenFillsHeight(screen)) && { fillScreenHeight: true }), ...((screen.submitLabel ?? submitLabelFallback) !== undefined && {
+        extensionInitialValues: initial, ...(successText !== undefined && {
+            leadContent: (_jsx(Banner, { variant: "info", testId: "action-form-success", children: successText })),
+        }), writeCommand: screen.handler, payloadMode: "values", onSubmit: handleSubmitted, ...(handleCancel !== undefined && { onCancel: handleCancel }), ...(onDirtyChange !== undefined && { onDirtyChange }), ...((insideDrawer || screenFillsHeight(screen)) && { fillScreenHeight: true }), ...((screen.submitLabel ?? submitLabelFallback) !== undefined && {
             submitLabel: screen.submitLabel ?? submitLabelFallback,
         }), ...(screen.submitStyle !== undefined && { submitVariant: screen.submitStyle }), ...(screen.footerActions !== undefined && { footerActions: screen.footerActions }), ...(summary !== undefined && { summary }), ...(translate !== undefined && { translate }) }));
 }

package/dist/components/render-edit-types.d.ts

@@ -35,7 +35,8 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
     readonly translate?: Translate;
     readonly ctx?: TCtx;
     readonly schema?: z.ZodType;
-    readonly onSubmit?: (result: SubmitResult<unknown>) => void;
+    /** `values` are the form values at the moment the submit succeeded. */
+    readonly onSubmit?: (result: SubmitResult<unknown>, values: TValues) => void;
     readonly payloadMode?: "values" | "changes";
     readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
     /** Prefix to strip from server validation issue paths before mapping them

package/dist/components/render-edit.js

@@ -1001,8 +1001,9 @@ export function RenderEdit(props) {
             // skip: on entity-success-but-extension-failure the extension-error
             // banner is showing — don't notify (the caller navigates away on success
             // and would unmount it before the user sees the failure).
-            if (shouldNotifyCaller(result, extensionsPersisted))
-                onSubmit?.(result);
+            if (shouldNotifyCaller(result, extensionsPersisted)) {
+                onSubmit?.(result, controller.getSnapshot().values);
+            }
         }
         finally {
             isSubmittingRef.current = false;

package/dist/context/dispatcher-context.d.ts

@@ -1,10 +1,12 @@
 import type { Dispatcher, DispatcherStatus } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import { type QueryPools } from "./query-pool.js";
 export type DispatcherProviderProps = {
     readonly dispatcher: Dispatcher;
     readonly children: ReactNode;
 };
 export declare function DispatcherProvider({ dispatcher, children }: DispatcherProviderProps): ReactNode;
+export declare function useOptionalQueryPools(): QueryPools | undefined;
 export declare function useDispatcher(): Dispatcher;
 export declare function useOptionalDispatcher(): Dispatcher | undefined;
 export declare function useDispatcherStatus(): DispatcherStatus;

package/dist/context/dispatcher-context.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext } from "react";
+import { createContext, useContext, useState } from "react";
 import { useStore } from "../hooks/use-store.js";
+import { createQueryPools } from "./query-pool.js";
 // React Context threading the Dispatcher through the tree. An app
 // wraps its root in <DispatcherProvider dispatcher={createLiveDispatcher()}>
 // and every hook below reaches into that context instead of taking the
@@ -11,8 +12,14 @@ import { useStore } from "../hooks/use-store.js";
 // dispatcher per app (rebuilding would wipe its in-flight tracking and
 // status listeners). Tests wire a fake dispatcher in directly.
 const DispatcherContext = createContext(null);
+const QueryPoolsContext = createContext(null);
 export function DispatcherProvider({ dispatcher, children }) {
-    return _jsx(DispatcherContext, { value: dispatcher, children: children });
+    // Pools live with the provider so every hook of one query name shares them.
+    const [queryPools] = useState(createQueryPools);
+    return (_jsx(DispatcherContext, { value: dispatcher, children: _jsx(QueryPoolsContext, { value: queryPools, children: children }) }));
+}
+export function useOptionalQueryPools() {
+    return useContext(QueryPoolsContext) ?? undefined;
 }
 // Reads the ambient Dispatcher. Throws instead of returning null when
 // no provider is mounted — a dispatcher-less hook is always a

package/dist/context/query-pool.d.ts

@@ -0,0 +1,11 @@
+export type QuerySlot = {
+    readonly release: () => void;
+};
+export type QueryPools = {
+    /** Resolves with a slot once fewer than `limit` requests of this query name
+     *  run, or with null when `signal` aborts first (a waiter that gives up
+     *  never holds a slot). The caller must release a granted slot exactly once. Hooks of one
+     *  query name are expected to pass the same limit. */
+    readonly acquire: (name: string, limit: number, signal: AbortSignal) => Promise<QuerySlot | null>;
+};
+export declare function createQueryPools(): QueryPools;

package/dist/context/query-pool.js

@@ -0,0 +1,64 @@
+export function createQueryPools() {
+    const pools = new Map();
+    const poolFor = (name) => {
+        const existing = pools.get(name);
+        if (existing)
+            return existing;
+        const created = { running: 0, waiting: [] };
+        pools.set(name, created);
+        return created;
+    };
+    const makeSlot = (name, pool) => {
+        let released = false;
+        return {
+            release: () => {
+                if (!released) {
+                    released = true;
+                    pool.running -= 1;
+                    drain(name, pool);
+                }
+            },
+        };
+    };
+    const drain = (name, pool) => {
+        let next = pool.waiting[0];
+        while (next !== undefined && pool.running < next.limit) {
+            pool.waiting.shift();
+            pool.running += 1;
+            next.grant(makeSlot(name, pool));
+            next = pool.waiting[0];
+        }
+        if (pool.running === 0 && pool.waiting.length === 0)
+            pools.delete(name);
+    };
+    return {
+        acquire: (name, limit, signal) => {
+            if (signal.aborted)
+                return Promise.resolve(null);
+            const pool = poolFor(name);
+            if (pool.waiting.length === 0 && pool.running < limit) {
+                pool.running += 1;
+                return Promise.resolve(makeSlot(name, pool));
+            }
+            return new Promise((resolve) => {
+                const waiter = {
+                    limit,
+                    grant: (slot) => {
+                        signal.removeEventListener("abort", onAbort);
+                        resolve(slot);
+                    },
+                };
+                const onAbort = () => {
+                    const index = pool.waiting.indexOf(waiter);
+                    if (index >= 0)
+                        pool.waiting.splice(index, 1);
+                    signal.removeEventListener("abort", onAbort);
+                    resolve(null);
+                    drain(name, pool);
+                };
+                signal.addEventListener("abort", onAbort);
+                pool.waiting.push(waiter);
+            });
+        },
+    };
+}

package/dist/hooks/use-query.d.ts

@@ -9,6 +9,7 @@ export type UseQueryOptions = {
     readonly enabled?: boolean;
     readonly live?: boolean;
     readonly refetchIntervalMs?: number;
+    readonly concurrency?: number;
 };
 export declare function entityFromQueryType(type: string): string | undefined;
 export declare function useQuery<TData = unknown>(type: string, payload: unknown, options?: UseQueryOptions): UseQueryResult<TData>;

package/dist/hooks/use-query.js

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { useDispatcher } from "../context/dispatcher-context.js";
+import { useDispatcher, useOptionalQueryPools } from "../context/dispatcher-context.js";
 import { useLiveEvents } from "../sse/live-events.js";
 // Extract the entity-name from a standard Kumiko query type. Returns
 // undefined for non-conforming types so the live-mode silently skips
@@ -13,9 +13,13 @@ export function entityFromQueryType(type) {
         return undefined;
     return parts[2];
 }
+function isValidConcurrency(value) {
+    return value !== undefined && Number.isFinite(value) && value >= 1;
+}
 export function useQuery(type, payload, options = {}) {
     const dispatcher = useDispatcher();
-    const { enabled = true, live = false, refetchIntervalMs } = options;
+    const { enabled = true, live = false, refetchIntervalMs, concurrency } = options;
+    const queryPools = useOptionalQueryPools();
     const [data, setData] = useState(null);
     const [error, setError] = useState(null);
     const [loading, setLoading] = useState(enabled);
@@ -45,10 +49,21 @@ export function useQuery(type, payload, options = {}) {
         if (!background)
             setLoading(true);
         let result;
+        let slot = null;
         try {
+            if (queryPools !== undefined && isValidConcurrency(concurrency)) {
+                slot = await queryPools.acquire(type, Math.floor(concurrency), ctrl.signal);
+                // skip: aborted while queued, the superseding run owns the state
+                if (slot === null)
+                    return;
+                // skip: slot granted just as the run was superseded, finally frees it
+                if (ctrl.signal.aborted)
+                    return;
+            }
             result = await dispatcher.query(type, payload, { signal: ctrl.signal });
         }
         finally {
+            slot?.release();
             // A rejected fetch must not leave polling stuck; a superseded one must
             // not clear the newer fetch's flag.
             if (activeCtrl.current === ctrl)
@@ -69,7 +84,7 @@ export function useQuery(type, payload, options = {}) {
             setError(result.error);
         }
         setLoading(false);
-    }, [dispatcher, type, payloadKey]);
+    }, [dispatcher, type, payloadKey, queryPools, concurrency]);
     const run = useCallback(() => runFetch(false), [runFetch]);
     useEffect(() => {
         if (!enabled) {

package/dist/primitives.d.ts

@@ -1305,6 +1305,9 @@ export type PageHeaderProps = {
     readonly actions?: ReactNode;
     /** Land in the shell header's overflow menu at phone width. */
     readonly overflowItems?: readonly ActionMenuItemSpec[];
+    /** Hide the shell header's breadcrumb while mounted, for a screen that stands in
+     *  for the one the route names (a locked screen's fallback). */
+    readonly hideBreadcrumb?: boolean;
 };
 /** One item in an `ActionOverflowMenu` (A7: header/row actions beyond the
  *  primary one collapse into this menu instead of a wall of buttons). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.346.0",
+  "version": "0.348.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.346.0",
-    "@cosmicdrift/kumiko-headless": "0.346.0",
-    "@cosmicdrift/kumiko-types": "0.346.0",
+    "@cosmicdrift/kumiko-framework": "0.348.0",
+    "@cosmicdrift/kumiko-headless": "0.348.0",
+    "@cosmicdrift/kumiko-types": "0.348.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.346.0"
+    "@cosmicdrift/kumiko-locale-de": "0.348.0"
   },
   "repository": {
     "type": "git",

package/src/changes.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "0.348.0",
+    "type": "improvement",
+    "title": "ModeSwitch gains a pill variant and className, LanguageSwitcher gains a compact chip variant",
+    "detail": "ModeSwitch pill variant and LanguageSwitcher chip variant\n`ModeSwitch` gets `variant=\"pill\"` (grey track, raised active segment, dark mode aware) and a `className` prop; `outline` stays the default. `LanguageSwitcher` gets `variant=\"chip\"`, a compact monospace chip with the uppercase locale code in a border; `default` stays as it was."
+  },
+  {
+    "version": "0.348.0",
+    "type": "improvement",
+    "title": "TimeseriesChart takes a height, an optional y-axis with gridlines and a date axis with n labels",
+    "detail": "TimeseriesChart: height, y-axis gridlines and a date axis\n`height` (px) replaces the fixed `h-16`; without it the chart looks as before. `yAxis: { ticks, format? }` draws that many gridlines with rounded value labels (0/200/400/600) in a left gutter, and the y-scale reaches the top tick. `xAxis: { ticks, format }` renders n evenly spaced date labels instead of the fixed start/mid/end of `axisLabels`."
+  },
+  {
+    "version": "0.348.0",
+    "type": "improvement",
+    "title": "useQuery accepts concurrency to cap parallel requests per query name through a pool in the DispatcherProvider",
+    "detail": "useQuery option `concurrency` caps parallel requests per query name\n`useQuery(type, payload, { concurrency: n })` lets at most n `dispatcher.query` calls of that query name run at once. The pool lives in the DispatcherProvider and is shared by every hook with the same name; the rest wait in line with `loading` still true. A hook that unmounts, refetches or changes its payload while waiting leaves the line without holding a slot, and a finished or failed request hands its slot to the next waiter. Without the option nothing changes."
+  },
+  {
+    "version": "0.347.0",
+    "type": "improvement",
+    "title": "actionForm successMessage names the chosen record's label after a successful submit",
+    "detail": "actionForm screens can confirm a submit with the chosen record\nA new `successMessage` i18n key on an `actionForm` screen shows a confirmation above the form after a successful submit, for screens that stay put (no `redirect`, not in a drawer). `{field}` placeholders take the submitted values, and a `reference` field shows the chosen record's label instead of its id. The tier-engine admin form uses it: \"Tier assigned: Acme → Pro\", so choosing the wrong tenant is visible right away. New i18n key: `tier-admin.success` (en/de/es). `RenderEdit`'s `onSubmit` receives the submitted values as a second argument."
+  },
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Switching between generated config screens no longer shows empty fields for stored values",
+    "detail": "Settings screens show their stored values after switching screens\nMoving from one generated settings screen to another kept the previous screen's form state, so the fields of the new screen rendered empty and a select showed no active option even though a tenant value was set. Each config and secrets screen now mounts its own form."
+  },
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "The shell header drops the locked screen's breadcrumb while a visibleWhen fallback or notice is shown",
+    "detail": "A locked screen's fallback shows no breadcrumb\nWhen `visibleWhen` is unmet, the route still names the locked screen, so the shell header kept that screen's breadcrumb above the fallback or the unavailable notice. The gate now mounts `<PageHeader hideBreadcrumb />`, and the shell header drops the breadcrumb while it is mounted. Embedded screens (dashboard panels, drawers) are not affected."
+  },
   {
     "version": "0.343.0",
     "type": "improvement",