@cosmicdrift/kumiko-renderer 0.348.1 → 0.350.0

package/dist/app/facet-count-bridge.d.ts

@@ -3,8 +3,10 @@ export type FacetCountQuery = {
     readonly key: string;
     readonly payload: Readonly<Record<string, unknown>>;
 };
-export declare function FacetCountBridges({ queryType, queries, onCount, }: {
+export declare function FacetCountBridges({ queryType, queries, onCount, refreshNonce, }: {
     readonly queryType: string;
     readonly queries: readonly FacetCountQuery[];
     readonly onCount: (key: string, count: number) => void;
+    /** Bumped after a write; every bridge refetches its count. */
+    readonly refreshNonce: number;
 }): ReactNode;

package/dist/app/facet-count-bridge.js

@@ -2,19 +2,29 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 // One invisible bridge per facet chip, mirroring ReferenceFacetBridges — the
 // chip count varies per screen, so useQuery can't be called in a loop. Each
 // bridge asks the list query for a single row plus `total`.
-// ponytail: one extra list query per chip, refetched on every list
-// invalidation; a server-side facet-count handler replaces this if it hurts.
-import { useEffect } from "react";
+// ponytail: one extra list query per chip, refetched with the list (live
+// events and `refreshNonce` bumps after writes); a server-side facet-count
+// handler replaces this if it hurts.
+import { useEffect, useRef } from "react";
 import { useQuery } from "../hooks/use-query.js";
-function FacetCountBridge({ countKey, queryType, payload, onCount, }) {
-    const result = useQuery(queryType, payload);
+function FacetCountBridge({ countKey, queryType, payload, onCount, refreshNonce, }) {
+    const result = useQuery(queryType, payload, { live: true });
     const total = result.data?.total;
     useEffect(() => {
         if (total !== undefined)
             onCount(countKey, total);
     }, [total, countKey, onCount]);
+    const { refetch } = result;
+    const seenNonce = useRef(refreshNonce);
+    useEffect(() => {
+        // skip: the mount fetch already covers the nonce the bridge started with
+        if (seenNonce.current === refreshNonce)
+            return;
+        seenNonce.current = refreshNonce;
+        void refetch();
+    }, [refreshNonce, refetch]);
     return null;
 }
-export function FacetCountBridges({ queryType, queries, onCount, }) {
-    return (_jsx(_Fragment, { children: queries.map((query) => (_jsx(FacetCountBridge, { countKey: query.key, queryType: queryType, payload: query.payload, onCount: onCount }, query.key))) }));
+export function FacetCountBridges({ queryType, queries, onCount, refreshNonce, }) {
+    return (_jsx(_Fragment, { children: queries.map((query) => (_jsx(FacetCountBridge, { countKey: query.key, queryType: queryType, payload: query.payload, onCount: onCount, refreshNonce: refreshNonce }, query.key))) }));
 }

package/dist/app/kumiko-screen.js

@@ -1193,7 +1193,11 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
         cursor,
     ]);
     const rowsQuery = useQuery(queryType, queryPayload, { live: true });
+    // Facet counts come from their own queries, which a write leaves untouched.
+    const [facetCountRefreshNonce, setFacetCountRefreshNonce] = useState(0);
+    const refreshFacetCounts = useCallback(() => setFacetCountRefreshNonce((n) => n + 1), []);
     const refreshRowsAfterWrite = useCallback(async () => {
+        refreshFacetCounts();
         if (useInfinite) {
             setAccumulated([]);
             setCursor(undefined);
@@ -1201,7 +1205,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
             return;
         }
         await refetchAfterWrite(rowsQuery.refetch);
-    }, [useInfinite, rowsQuery.refetch]);
+    }, [useInfinite, rowsQuery.refetch, refreshFacetCounts]);
     // Infinite-Scroll: bei jedem erfolgreichen Result die rows appenden +
     // hasMore aus nextCursor ableiten. Live-Updates (postgres NOTIFY) und
     // initiale Loads laufen beide hier durch — das useEffect-Dep-Array
@@ -1510,7 +1514,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     // Bei Infinite-Mode: rows kommen aus accumulated (über mehrere
     // useQuery-Calls gesammelt), bei pages/false aus dem aktuellen Result.
     const renderRows = useInfinite ? accumulated : (rowsQuery.data?.rows ?? []);
-    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, onOptions: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount }), _jsx(RenderList, { screen: screen, entity: entity, rows: renderRows, featureName: featureName, searchable: searchable, searchValue: urlState.q, onSearchChange: urlState.setQ, sort: effectiveSort, onSortChange: urlState.setSort, ...(isEmbeddedScreen
+    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, onOptions: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount, refreshNonce: facetCountRefreshNonce }), _jsx(RenderList, { screen: screen, entity: entity, rows: renderRows, featureName: featureName, searchable: searchable, searchValue: urlState.q, onSearchChange: urlState.setQ, sort: effectiveSort, onSortChange: urlState.setSort, ...(isEmbeddedScreen
                     ? { screenPadding: false, chromeless: true }
                     : { screenPadding: true }), ...(screenFillsHeight(screen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions }), ...(useInfinite && {
                     onReachEnd: loadMore,
@@ -1528,6 +1532,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
                 }) }), _jsx(DrawerHost, { schema: schema, drawerAction: drawerAction, drawerScreen: drawerScreen, ...(drawerInitialValues !== undefined && { drawerInitialValues }), userRoles: userRoles, ...(translate !== undefined && { translate }), onClose: closeDrawer, onSuccess: () => {
                     closeDrawer();
                     invalidateExpansions();
+                    refreshFacetCounts();
                     void rowsQuery.refetch();
                 } })] }));
 }

package/dist/app/nav.d.ts

@@ -16,23 +16,28 @@ export type ObjectTarget = {
     readonly id: string;
 };
 export type NavTarget = ScreenTarget | ObjectTarget;
+export type NavigateOptions = {
+    /** Search params of the target route, set in the same history entry as
+     *  the path. Without them the target starts with an empty query. */
+    readonly searchParams?: Readonly<Record<string, string>>;
+};
 export type NavApi = {
     /** Current route — `undefined` when the URL is at the root / there's
      *  no route selected. Caller's initial fallback kicks in then. */
     readonly route: NavRoute | undefined;
     /** Push a new route. Platform-specific Impl writes to
      *  history/stack and notifies subscribers. */
-    readonly navigate: (target: NavTarget) => void;
+    readonly navigate: (target: NavTarget, options?: NavigateOptions) => void;
     /** Replace the current route in place. Same effect as navigate from
      *  the user's perspective, but doesn't add a history entry — used for
      *  mount-time URL fills (e.g. WorkspaceShell defaulting to `/admin/x`
      *  when the user typed `/`). Browser Back must take the user out of
      *  the app, not back to the original empty path. */
-    readonly replace: (target: NavTarget) => void;
+    readonly replace: (target: NavTarget, options?: NavigateOptions) => void;
     /** Build the href a click on {target} would produce. Used by
      *  platform-specific Link-Komponenten (Web: `<a href>`; Native
      *  typically doesn't need this). */
-    readonly hrefFor: (target: NavTarget) => string;
+    readonly hrefFor: (target: NavTarget, options?: NavigateOptions) => string;
     /** Lese-Snapshot der aktuellen Search-Params (Browser: ?key=value-
      *  Pairs nach dem Pfad). Native-Impls die kein URL-Konzept haben
      *  liefern ein leeres Object. Wert ist ein Plain-Record (kein Map)

package/dist/hooks/use-list-url-state.d.ts

@@ -41,4 +41,6 @@ export type ListUrlStateApi = ListUrlState & {
     }) => void;
 };
 export declare const PAGE_SIZE_OPTIONS: readonly number[];
+/** URL key of a list facet filter. Its value is the comma-joined selected values. */
+export declare function listFilterUrlKey(screenId: string, field: string): string;
 export declare function useListUrlState(screenId: string, defaultFilters?: Readonly<Record<string, readonly string[]>>): ListUrlStateApi;

package/dist/hooks/use-list-url-state.js

@@ -33,6 +33,10 @@ function parsePageSize(value) {
 function key(screenId, suffix) {
     return `${screenId}.${suffix}`;
 }
+/** URL key of a list facet filter. Its value is the comma-joined selected values. */
+export function listFilterUrlKey(screenId, field) {
+    return key(screenId, `f.${field}`);
+}
 function parseDir(value) {
     return value === "asc" || value === "desc" ? value : undefined;
 }
@@ -55,7 +59,7 @@ export function useListUrlState(screenId, defaultFilters) {
     const q = params[key(screenId, "q")] ?? "";
     const page = parsePage(params[key(screenId, "page")]);
     const pageSize = parsePageSize(params[key(screenId, "size")]);
-    const filterPrefix = `${screenId}.f.`;
+    const filterPrefix = listFilterUrlKey(screenId, "");
     const filters = useMemo(() => {
         const out = {};
         for (const [k, v] of Object.entries(params)) {
@@ -110,7 +114,7 @@ export function useListUrlState(screenId, defaultFilters) {
     }, [nav, screenId]);
     const setFilter = useCallback((field, values) => {
         nav.setSearchParams({
-            [key(screenId, `f.${field}`)]: values.length === 0 ? clearedFilterValue(field) : values.join(","),
+            [listFilterUrlKey(screenId, field)]: values.length === 0 ? clearedFilterValue(field) : values.join(","),
             [key(screenId, "page")]: null,
         });
     }, [nav, screenId, clearedFilterValue]);

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export type { KumikoScreenProps } from "./app/kumiko-screen.js";
 export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen.js";
 export type { DateRangeBound, DateRangeValue, ResolvedDateRangeFacet } from "./app/list-facets.js";
 export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.js";
-export type { NavApi, NavProviderProps, NavRoute, NavTarget, ObjectTarget, ScreenTarget, } from "./app/nav.js";
+export type { NavApi, NavigateOptions, NavProviderProps, NavRoute, NavTarget, ObjectTarget, ScreenTarget, } from "./app/nav.js";
 export { formatPath, hasDetailScreen, NavProvider, parsePath, resolveTarget, useNav, useNavigateWithInitialValues, } from "./app/nav.js";
 export { lastSegment } from "./app/qn.js";
 export type { ReturnHost, ReturnTo } from "./app/return-to.js";
@@ -57,7 +57,7 @@ export { useDisclosure } from "./hooks/use-disclosure.js";
 export type { UseFormOptions, UseFormResult } from "./hooks/use-form.js";
 export { useForm } from "./hooks/use-form.js";
 export type { ListSort, ListSortDir, ListUrlState, ListUrlStateApi, } from "./hooks/use-list-url-state.js";
-export { useListUrlState } from "./hooks/use-list-url-state.js";
+export { listFilterUrlKey, useListUrlState } from "./hooks/use-list-url-state.js";
 export type { UseMutationResult } from "./hooks/use-mutation.js";
 export { useMutation } from "./hooks/use-mutation.js";
 export type { UseQueryOptions, UseQueryResult } from "./hooks/use-query.js";

package/dist/index.js

@@ -42,7 +42,7 @@ export { REFERENCE_COMBOBOX_LIMIT, REFERENCE_LIST_LOOKUP_LIMIT, REFERENCE_SEARCH
 export { AI_TEXT_RUN_QN, useAiTextAction, useCompletion } from "./hooks/use-ai-text.js";
 export { useDisclosure } from "./hooks/use-disclosure.js";
 export { useForm } from "./hooks/use-form.js";
-export { useListUrlState } from "./hooks/use-list-url-state.js";
+export { listFilterUrlKey, useListUrlState } from "./hooks/use-list-url-state.js";
 export { useMutation } from "./hooks/use-mutation.js";
 export { entityFromQueryType, useQuery } from "./hooks/use-query.js";
 export { useReportStepComplete } from "./hooks/use-report-step-complete.js";

package/dist/primitives.d.ts

@@ -1081,6 +1081,12 @@ type LightboxBaseProps = {
     readonly open: boolean;
     readonly onOpenChange: (open: boolean) => void;
     readonly testId?: string;
+    /** Controls for the shown image, e.g. a download button. Rendered in the
+     *  top-left corner; with a set the app picks the image from its `index`. */
+    readonly actions?: ReactNode;
+    /** `false` hides the `{current} / {total}` counter of a set, for images
+     *  that carry their own. Default `true`. */
+    readonly showPosition?: boolean;
 };
 /** Image lightbox — full-size preview on click. Web renders Radix overlay;
  *  trigger (thumbnail) and open state live in the app. Takes either one image

package/package.json

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