@cosmicdrift/kumiko-renderer 0.402.0 → 0.404.0

package/dist/app/entity-list-screen.js

@@ -23,6 +23,8 @@ import { FacetCountBridges } from "./facet-count-bridge.js";
 import { useListBulk } from "./list-bulk-actions.js";
 import { isDefaultFilterActive, isListNarrowed, useListEmptyContent, } from "./list-empty-content.js";
 import { buildEntityFilterFacets, buildFacetCountRequests, buildFilterPayload, mergeReferenceFacetOptions, normalizeDefaultFilters, } from "./list-facets.js";
+import { buildNamedFilterFacet, routeFacetChange, withNamedFilterValues, } from "./named-filter-facet.js";
+import { NamedFilterRemove } from "./named-filter-remove.js";
 import { useNav } from "./nav.js";
 import { QueryErrorBanner, QueryLoadingBanner } from "./query-state-banners.js";
 import { ReferenceFacetBridges, withReferenceFacetState, } from "./reference-facet-bridge.js";
@@ -64,6 +66,8 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     // author default vs user choice.
     const defaultFilters = useMemo(() => normalizeDefaultFilters(screen.defaultFilters), [screen.defaultFilters]);
     const urlState = useListUrlState(screen.id, defaultFilters);
+    // Gated on the screen offering named filters, so a stale URL cannot send a param the list rejects.
+    const activeNamedFilter = screen.namedFilters === undefined ? undefined : urlState.namedFilter;
     const effectiveSort = urlState.sort ?? screen.defaultSort ?? null;
     const limit = urlState.pageSize ?? screen.pageSize ?? 50;
     const paginationMode = screen.pagination ?? "pages";
@@ -111,8 +115,11 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
         const filters = [...filterPayload, ...range.rangeFilters];
         if (filters.length > 0)
             payload["filters"] = filters;
+        if (activeNamedFilter !== undefined)
+            payload["namedFilter"] = activeNamedFilter;
         return payload;
     }, [
+        activeNamedFilter,
         limit,
         urlState.q,
         effectiveSort,
@@ -157,7 +164,22 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     const handleEntityFacetOptions = useCallback((field, state) => setEntityReferenceFacetOptions((prev) => withReferenceFacetState(prev, field, state)), []);
     const [facetCounts, setFacetCounts] = useState({});
     const handleFacetCount = useCallback((key, count) => setFacetCounts((prev) => (prev[key] === count ? prev : { ...prev, [key]: count })), []);
-    const filterFacets = useMemo(() => buildEntityFilterFacets(mergeReferenceFacetOptions(entityFacetSpecs, entityReferenceFacetOptions), screen.facets, effectiveTranslate, facetCounts), [entityFacetSpecs, entityReferenceFacetOptions, screen.facets, effectiveTranslate, facetCounts]);
+    const filterFacets = useMemo(() => {
+        const namedFacet = buildNamedFilterFacet(screen.namedFilters, effectiveTranslate);
+        return [
+            ...(namedFacet !== undefined ? [namedFacet] : []),
+            ...buildEntityFilterFacets(mergeReferenceFacetOptions(entityFacetSpecs, entityReferenceFacetOptions), screen.facets, effectiveTranslate, facetCounts),
+        ];
+    }, [
+        entityFacetSpecs,
+        entityReferenceFacetOptions,
+        screen.facets,
+        screen.namedFilters,
+        effectiveTranslate,
+        facetCounts,
+    ]);
+    const filterValues = useMemo(() => withNamedFilterValues(urlState.filters, activeNamedFilter), [urlState.filters, activeNamedFilter]);
+    const onFilterChange = useMemo(() => routeFacetChange(urlState), [urlState]);
     const facetCountQueries = useMemo(() => buildFacetCountRequests(entityFacetSpecs, screen.facets, effectiveTranslate).map((request) => {
         const filters = [
             ...buildFilterPayload({ ...urlState.filters, [request.field]: request.values }, (field) => entity.fields[field]?.type),
@@ -171,9 +193,11 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
                 ...(urlState.q !== "" && { search: urlState.q }),
                 ...(screen.filter !== undefined && { filter: screen.filter }),
                 ...(filters.length > 0 && { filters }),
+                ...(activeNamedFilter !== undefined && { namedFilter: activeNamedFilter }),
             },
         };
     }), [
+        activeNamedFilter,
         entityFacetSpecs,
         screen.facets,
         screen.filter,
@@ -362,7 +386,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
         return _jsx(QueryLoadingBanner, {});
     }
     if (listRows.error && !listRows.hasData) {
-        return (_jsx(QueryErrorBanner, { error: listRows.error, translate: effectiveTranslate, onRetry: listRows.retry }));
+        return (_jsxs(_Fragment, { children: [_jsx(QueryErrorBanner, { error: listRows.error, translate: effectiveTranslate, onRetry: listRows.retry }), _jsx(NamedFilterRemove, { active: activeNamedFilter !== undefined, translate: effectiveTranslate, onRemove: () => urlState.setNamedFilter(undefined) })] }));
     }
     // A failed refetch keeps the last good data on screen.
     const refetchErrorBanner = listRows.error ? (_jsx(QueryErrorBanner, { error: listRows.error, translate: effectiveTranslate, onRetry: listRows.retry })) : null;
@@ -395,15 +419,16 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     // arrives async; until it is there RenderList renders the table without a
     // pager (the pager has its own total>0 guard).
     const pager = listPager({ usePager, page: listRows.page, limit, urlState });
-    return (_jsxs(_Fragment, { children: [refetchErrorBanner, _jsx(ListGroupPageBridges, { ...listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, selected: urlState.filters, onState: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount, refreshNonce: facetCountRefreshNonce }), _jsx(RenderList, { screen: screen, entity: entity, rows: listRows.rows, featureName: featureName, searchable: searchable, narrowed: isListNarrowed(urlState.q, urlState.filters, defaultFilters), defaultFilterActive: isDefaultFilterActive(urlState.q, urlState.filters, defaultFilters), ...(screen.description !== undefined && {
+    return (_jsxs(_Fragment, { children: [refetchErrorBanner, _jsx(ListGroupPageBridges, { ...listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, selected: urlState.filters, onState: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount, refreshNonce: facetCountRefreshNonce }), _jsx(RenderList, { screen: screen, entity: entity, rows: listRows.rows, featureName: featureName, searchable: searchable, narrowed: activeNamedFilter !== undefined ||
+                    isListNarrowed(urlState.q, urlState.filters, defaultFilters), defaultFilterActive: isDefaultFilterActive(urlState.q, urlState.filters, defaultFilters), ...(screen.description !== undefined && {
                     description: effectiveTranslate(screen.description),
                 }), ...(emptyContent !== undefined && { emptyContent }), 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 }), ...(bulk !== undefined && { bulk }), ...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions }), ...listRows.infinite, ...(onCreate !== undefined && { onCreate }), ...(translate !== undefined && { translate }), ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }), ...(filterFacets.length > 0 && { filterFacets, onFilterChange: urlState.setFilter }), ...(range.rangeFacets.length > 0 && {
+                    : { screenPadding: true }), ...(screenFillsHeight(screen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(bulk !== undefined && { bulk }), ...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions }), ...listRows.infinite, ...(onCreate !== undefined && { onCreate }), ...(translate !== undefined && { translate }), ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }), ...(filterFacets.length > 0 && { filterFacets, onFilterChange }), ...(range.rangeFacets.length > 0 && {
                     rangeFacets: range.rangeFacets,
                     onRangeChange: range.onRangeChange,
                 }), ...((filterFacets.length > 0 || range.rangeFacets.length > 0) && {
-                    filterValues: urlState.filters,
+                    filterValues,
                     onFilterReset: urlState.clearFilters,
                 }), ...listTable.props, ...(expandableSection !== undefined && {
                     expandedRowIds,

package/dist/app/named-filter-facet.d.ts

@@ -0,0 +1,12 @@
+import type { NamedListFilterRef } from "@cosmicdrift/kumiko-types/named-list-filters";
+import type { Translate } from "../headless/index.ts";
+import type { ListUrlStateApi } from "../hooks/use-list-url-state.ts";
+import type { DataTableFacet } from "../primitives.tsx";
+export declare const NAMED_FILTER_FACET_FIELD = "__namedFilter";
+type NamedFilterUrlState = Pick<ListUrlStateApi, "namedFilter" | "setFilter" | "setNamedFilter">;
+/** One toggle chip per named filter, rendered by the existing facet chip row. */
+export declare function buildNamedFilterFacet(refs: readonly NamedListFilterRef[] | undefined, translate: Translate): DataTableFacet | undefined;
+export declare function withNamedFilterValues(filters: Readonly<Record<string, readonly string[]>>, namedFilter: string | undefined): Readonly<Record<string, readonly string[]>>;
+/** Pressing the active chip again removes it. */
+export declare function routeFacetChange(urlState: NamedFilterUrlState): (field: string, values: readonly string[]) => void;
+export {};

package/dist/app/named-filter-facet.js

@@ -0,0 +1,30 @@
+// Not a real field: keeps the named filter out of the `.f.<field>` facet namespace.
+export const NAMED_FILTER_FACET_FIELD = "__namedFilter";
+/** One toggle chip per named filter, rendered by the existing facet chip row. */
+export function buildNamedFilterFacet(refs, translate) {
+    if (refs === undefined || refs.length === 0)
+        return undefined;
+    return {
+        field: NAMED_FILTER_FACET_FIELD,
+        label: refs.map((ref) => translate(ref.label)).join(" / "),
+        options: refs.map((ref) => ({ value: ref.id, label: translate(ref.label) })),
+        chips: refs.map((ref) => ({ id: ref.id, label: translate(ref.label), values: [ref.id] })),
+    };
+}
+export function withNamedFilterValues(filters, namedFilter) {
+    return namedFilter === undefined
+        ? filters
+        : { ...filters, [NAMED_FILTER_FACET_FIELD]: [namedFilter] };
+}
+/** Pressing the active chip again removes it. */
+export function routeFacetChange(urlState) {
+    return (field, values) => {
+        if (field !== NAMED_FILTER_FACET_FIELD) {
+            urlState.setFilter(field, values);
+            // skip: ordinary facet handled above
+            return;
+        }
+        const picked = values[0];
+        urlState.setNamedFilter(picked === urlState.namedFilter ? undefined : picked);
+    };
+}

package/dist/app/named-filter-remove.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+import type { Translate } from "../headless/index.ts";
+/** Keeps a stale or forbidden named filter removable while the list shows its error state. */
+export declare function NamedFilterRemove({ active, translate, onRemove, }: {
+    readonly active: boolean;
+    readonly translate: Translate;
+    readonly onRemove: () => void;
+}): ReactNode;

package/dist/app/named-filter-remove.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { usePrimitives } from "../primitives.js";
+/** Keeps a stale or forbidden named filter removable while the list shows its error state. */
+export function NamedFilterRemove({ active, translate, onRemove, }) {
+    const { Button } = usePrimitives();
+    if (!active)
+        return null;
+    return (_jsx(Button, { variant: "secondary", onClick: onRemove, testId: "named-filter-remove", children: translate("kumiko.list.filter.reset") }));
+}

package/dist/app/projection-list-body.js

@@ -8,6 +8,7 @@ import { usePrimitives } from "../primitives.js";
 import { useDrawerAction } from "./action-form-body.js";
 import { useAppFeatures } from "./app-features-context.js";
 import { useClientActionRuntime } from "./client-actions.js";
+import { NamedFilterRemove } from "./named-filter-remove.js";
 import { useNav } from "./nav.js";
 import { renderProjectionDrawerHost } from "./projection-drawer-host.js";
 import { renderBadShapeBanner, renderProjectionList, renderQueryRetryBanner, } from "./projection-list-render.js";
@@ -80,7 +81,7 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
         return _jsx(QueryLoadingBanner, {});
     }
     if (listRows.error && !listRows.hasData) {
-        return renderQueryRetryBanner(listRows, listRows.error, effectiveTranslate);
+        return (_jsxs(_Fragment, { children: [renderQueryRetryBanner(listRows, listRows.error, effectiveTranslate), _jsx(NamedFilterRemove, { active: query.activeNamedFilter !== undefined, translate: effectiveTranslate, onRemove: () => query.urlState.setNamedFilter(undefined) })] }));
     }
     // A failed refetch keeps the last good data on screen.
     const refetchErrorBanner = listRows.error

package/dist/app/projection-list-render-props.d.ts

@@ -50,7 +50,7 @@ export declare function projectionFacetProps(filterFacets: ReturnType<typeof use
     dateRangeFacets?: import("../data-table-facet-types.ts").DataTableDateRangeFacet[] | undefined;
     onDateRangeChange?: ((field: string, bound: "from" | "to", value: string) => void) | undefined;
 };
-export declare function projectionFilterStateProps(filterFacets: ReturnType<typeof useProjectionListData>["filterFacets"], dateRangeFacets: ReturnType<typeof useProjectionListQuery>["dateRangeFacets"], urlState: ListUrlStateApi): {
+export declare function projectionFilterStateProps(filterFacets: ReturnType<typeof useProjectionListData>["filterFacets"], dateRangeFacets: ReturnType<typeof useProjectionListQuery>["dateRangeFacets"], urlState: ListUrlStateApi, activeNamedFilter: string | undefined): {
     filterValues?: Readonly<Record<string, readonly string[]>> | undefined;
     onFilterReset?: (() => void) | undefined;
 };

package/dist/app/projection-list-render-props.js

@@ -1,4 +1,5 @@
 import { screenFillsHeight } from "../screen-fills-height.js";
+import { routeFacetChange, withNamedFilterValues } from "./named-filter-facet.js";
 export function projectionLeadProps(screen, effectiveTranslate, emptyContent) {
     return {
         ...(screen.description !== undefined && {
@@ -29,7 +30,7 @@ export function projectionFacetProps(filterFacets, dateRangeFacets, onDateRangeC
     return {
         ...(filterFacets.length > 0 && {
             filterFacets,
-            onFilterChange: urlState.setFilter,
+            onFilterChange: routeFacetChange(urlState),
         }),
         ...(dateRangeFacets.length > 0 && {
             dateRangeFacets,
@@ -37,10 +38,10 @@ export function projectionFacetProps(filterFacets, dateRangeFacets, onDateRangeC
         }),
     };
 }
-export function projectionFilterStateProps(filterFacets, dateRangeFacets, urlState) {
+export function projectionFilterStateProps(filterFacets, dateRangeFacets, urlState, activeNamedFilter) {
     return {
         ...((filterFacets.length > 0 || dateRangeFacets.length > 0) && {
-            filterValues: urlState.filters,
+            filterValues: withNamedFilterValues(urlState.filters, activeNamedFilter),
             onFilterReset: urlState.clearFilters,
         }),
     };

package/dist/app/projection-list-render.js

@@ -16,5 +16,6 @@ export function renderProjectionList(model) {
     const { urlState } = query;
     const { filterFacets, listRows, listTable } = data;
     const { dateRangeFacets } = query;
-    return (_jsx(RenderList, { screen: definitions.listScreen, entity: definitions.entity, rows: listRows.rows, featureName: schema.featureName, searchable: definitions.searchable, narrowed: isListNarrowed(query.activeSearch, urlState.filters), ...projectionLeadProps(screen, effectiveTranslate, actions.emptyContent), searchValue: urlState.q, onSearchChange: urlState.setQ, sort: query.activeSort, onSortChange: urlState.setSort, ...projectionLayoutProps(isEmbeddedScreen, screen, definitions.listScreen, pager, actions.rowActions), ...projectionActionProps(actions, translate, wrappedOnRowClick), ...projectionFacetProps(filterFacets, dateRangeFacets, query.handleDateRangeChange, urlState), ...listTable.props, ...projectionFilterStateProps(filterFacets, dateRangeFacets, urlState) }));
+    return (_jsx(RenderList, { screen: definitions.listScreen, entity: definitions.entity, rows: listRows.rows, featureName: schema.featureName, searchable: definitions.searchable, narrowed: query.activeNamedFilter !== undefined ||
+            isListNarrowed(query.activeSearch, urlState.filters), ...projectionLeadProps(screen, effectiveTranslate, actions.emptyContent), searchValue: urlState.q, onSearchChange: urlState.setQ, sort: query.activeSort, onSortChange: urlState.setSort, ...projectionLayoutProps(isEmbeddedScreen, screen, definitions.listScreen, pager, actions.rowActions), ...projectionActionProps(actions, translate, wrappedOnRowClick), ...projectionFacetProps(filterFacets, dateRangeFacets, query.handleDateRangeChange, urlState), ...listTable.props, ...projectionFilterStateProps(filterFacets, dateRangeFacets, urlState, query.activeNamedFilter) }));
 }

package/dist/app/use-projection-list-data.js

@@ -1,5 +1,6 @@
 import { useMemo } from "react";
 import { buildFilterFacets } from "./list-facets.js";
+import { buildNamedFilterFacet } from "./named-filter-facet.js";
 import { useScreenListRows } from "./use-screen-list-rows.js";
 import { useScreenListTable } from "./use-screen-list-table.js";
 export function useProjectionListData(input) {
@@ -21,6 +22,12 @@ export function useProjectionListData(input) {
         infinite: false,
         aggregates: listTable.aggregates,
     });
-    const filterFacets = useMemo(() => buildFilterFacets(resolvedFacetSpecs), [resolvedFacetSpecs]);
+    const filterFacets = useMemo(() => {
+        const namedFacet = buildNamedFilterFacet(screen.namedFilters, effectiveTranslate);
+        return [
+            ...(namedFacet !== undefined ? [namedFacet] : []),
+            ...buildFilterFacets(resolvedFacetSpecs),
+        ];
+    }, [resolvedFacetSpecs, screen.namedFilters, effectiveTranslate]);
     return { listTable, listRows, filterFacets };
 }

package/dist/app/use-projection-list-query.d.ts

@@ -24,5 +24,6 @@ export declare function useProjectionListQuery(input: ProjectionListQueryInput):
     dateRangeFacets: import("../data-table-facet-types.ts").DataTableDateRangeFacet[];
     handleDateRangeChange: (field: string, bound: "from" | "to", value: string) => void;
     queryPayload: Record<string, unknown>;
+    activeNamedFilter: string | undefined;
 };
 export {};

package/dist/app/use-projection-list-query.js

@@ -15,6 +15,7 @@ function resolveActiveSort(urlSort, input) {
 export function useProjectionListQuery(input) {
     const { screen, featureName, effectiveTranslate, searchable, paginated } = input;
     const urlState = useListUrlState(screen.id);
+    const activeNamedFilter = screen.namedFilters === undefined ? undefined : urlState.namedFilter;
     // Gated on the derived capability, not just on whether URL-state happens to
     // carry a value — a stale/hand-crafted URL (?…q=x on a non-searchable
     // screen) must not smuggle a param the query's Zod schema doesn't accept.
@@ -55,9 +56,12 @@ export function useProjectionListQuery(input) {
         if (screen.facets !== undefined && filterPayload.length > 0) {
             payload["filters"] = filterPayload;
         }
+        if (activeNamedFilter !== undefined)
+            payload["namedFilter"] = activeNamedFilter;
         Object.assign(payload, dateRangePayload);
         return payload;
     }, [
+        activeNamedFilter,
         limit,
         activeSearch,
         activeSort,
@@ -80,5 +84,6 @@ export function useProjectionListQuery(input) {
         dateRangeFacets,
         handleDateRangeChange,
         queryPayload,
+        activeNamedFilter,
     };
 }

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

@@ -15,6 +15,8 @@ export type ListUrlState = {
     /** Active faceted filters: field → selected values (strings; callers coerce
      * them according to the field type). Empty when no filter is set. */
     readonly filters: Readonly<Record<string, readonly string[]>>;
+    /** Id of the active named list filter; undefined when none is set. */
+    readonly namedFilter: string | undefined;
 };
 export type ListUrlStateApi = ListUrlState & {
     /** Atomically sets sort + dir. null means unsorted and clears both keys. */
@@ -29,7 +31,9 @@ export type ListUrlStateApi = ListUrlState & {
     /** Sets the selected values for a facet field. An empty array clears the key
      * and resets the page, like sort/search changes. */
     readonly setFilter: (field: string, values: readonly string[]) => void;
-    /** Clears all active faceted filters (for a reset button). */
+    /** Sets or (undefined) clears the named list filter and resets the page. */
+    readonly setNamedFilter: (id: string | undefined) => void;
+    /** Clears all active faceted filters and the named filter (for a reset button). */
     readonly clearFilters: () => void;
     /** Sets both bounds of a dateRange facet in ONE params update — two
      *  setFilter calls would overwrite each other, since the second still sees
@@ -43,4 +47,6 @@ export type ListUrlStateApi = ListUrlState & {
 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;
+/** URL key of the named list filter id. Distinct from the `f.` facet prefix. */
+export declare function listNamedFilterUrlKey(screenId: string): string;
 export declare function useListUrlState(screenId: string, defaultFilters?: Readonly<Record<string, readonly string[]>>): ListUrlStateApi;

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

@@ -11,6 +11,8 @@
 //   <screenId>.f.<field> — faceted filter: comma-joined selected values;
 //                          NO_FILTER_URL_VALUE = "no filter", chosen deliberately
 //                          for a field that has a declared default
+//   <screenId>.filter   — id of a named list filter (EntityDefinition.namedFilters);
+//                          while set, the screen's defaultFilters do not apply
 //
 // Uses setSearchParams (replaceState, not push) so sort/filter toggles do not
 // flood the browser history.
@@ -38,6 +40,10 @@ function key(screenId, suffix) {
 export function listFilterUrlKey(screenId, field) {
     return key(screenId, `f.${field}`);
 }
+/** URL key of the named list filter id. Distinct from the `f.` facet prefix. */
+export function listNamedFilterUrlKey(screenId) {
+    return key(screenId, "filter");
+}
 function parseDir(value) {
     return value === "asc" || value === "desc" ? value : undefined;
 }
@@ -60,6 +66,10 @@ 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 namedFilterParam = params[listNamedFilterUrlKey(screenId)];
+    const namedFilter = namedFilterParam === "" ? undefined : namedFilterParam;
+    // The named filter defines the view, so author defaults must not narrow it further.
+    const effectiveDefaultFilters = namedFilter === undefined ? defaultFilters : undefined;
     const filterPrefix = listFilterUrlKey(screenId, "");
     const filters = useMemo(() => {
         const out = {};
@@ -73,15 +83,15 @@ export function useListUrlState(screenId, defaultFilters) {
             // commas; use repeated keys if comma-containing values are ever needed.
             out[field] = v === NO_FILTER_URL_VALUE ? [] : v.split(",").filter((s) => s !== "");
         }
-        for (const [field, values] of Object.entries(defaultFilters ?? {})) {
+        for (const [field, values] of Object.entries(effectiveDefaultFilters ?? {})) {
             if (!Object.hasOwn(out, field))
                 out[field] = values;
         }
         return out;
-    }, [params, filterPrefix, defaultFilters]);
-    const clearedFilterValue = useCallback((field) => defaultFilters !== undefined && Object.hasOwn(defaultFilters, field)
+    }, [params, filterPrefix, effectiveDefaultFilters]);
+    const clearedFilterValue = useCallback((field) => effectiveDefaultFilters !== undefined && Object.hasOwn(effectiveDefaultFilters, field)
         ? NO_FILTER_URL_VALUE
-        : null, [defaultFilters]);
+        : null, [effectiveDefaultFilters]);
     const setSort = useCallback((next) => {
         // Atomically reset the page on every sort change; otherwise the user could
         // land on page 5 of the old ordering, which is visually confusing. The
@@ -124,8 +134,17 @@ export function useListUrlState(screenId, defaultFilters) {
             [key(screenId, "page")]: null,
         });
     }, [nav, screenId]);
+    const setNamedFilter = useCallback((id) => {
+        nav.setSearchParams({
+            [listNamedFilterUrlKey(screenId)]: id ?? null,
+            [key(screenId, "page")]: null,
+        });
+    }, [nav, screenId]);
     const clearFilters = useCallback(() => {
-        const updates = { [key(screenId, "page")]: null };
+        const updates = {
+            [key(screenId, "page")]: null,
+            [listNamedFilterUrlKey(screenId)]: null,
+        };
         for (const field of Object.keys(filters)) {
             updates[key(screenId, `f.${field}`)] = clearedFilterValue(field);
         }
@@ -137,11 +156,13 @@ export function useListUrlState(screenId, defaultFilters) {
         page,
         pageSize,
         filters,
+        namedFilter,
         setSort,
         setQ,
         setPage,
         setPageSize,
         setFilter,
+        setNamedFilter,
         clearFilters,
         setDateRange,
     };

package/dist/web/app/dashboard-panels.js

@@ -5,6 +5,7 @@ import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { useEffect, useState } from "react";
 import { rendererWarn } from "../../dev-console.js";
 import { EMPTY_VALUE_PLACEHOLDER } from "../../headless/index.js";
+import { listNamedFilterUrlKey } from "../../hooks/use-list-url-state.js";
 import { extensionSectionName, lastSegment, useExtensionSectionComponent, useNav, usePrimitives, useTranslation, useUserRoles, } from "../../index.js";
 import { initialWindowSelection, } from "../widgets/chart-window.js";
 import { chartToneColor, SegmentBarChart, StackedAreaChart, StackedBarChart, TimeseriesChart, } from "../widgets/charts.js";
@@ -41,6 +42,8 @@ function fallbackText(raw, placeholder) {
 }
 export function StatPanelBody({ panel, label, screenId, screenParams, translate, variant, }) {
     const formats = useDashboardFormats();
+    const nav = useNav();
+    const link = statNavigationLink(nav, panel.navigate);
     // Resolved HERE (not in a separate always-rendered child) so `icon` on
     // <StatCard> is `undefined` — not a React element that renders empty —
     // when the icon name isn't registered. StatCard gates its accent chip on
@@ -54,7 +57,9 @@ export function StatPanelBody({ panel, label, screenId, screenParams, translate,
                 `"${iconName}", which is not registered in clientFeatures.extensionSectionComponents.`);
         }
     }, [panel.icon, panel.id, iconName, Icon, screenId]);
-    const { data, error, loading, refetch } = useDashboardQuery(panel.query, panelPayload(panel, screenParams));
+    const { data, error, loading, refetch } = useDashboardQuery(panel.query, 
+    // A navigate tile counts exactly what its target list can reproduce from the URL.
+    panel.navigate === undefined ? panelPayload(panel, screenParams) : (panel.params ?? {}));
     useReportPanelLoaded(data);
     if (loading && data === null)
         return _jsx(LoadingState, { rows: 2 });
@@ -86,9 +91,21 @@ export function StatPanelBody({ panel, label, screenId, screenParams, translate,
     const subText = resolveDashboardText(sub, translate, formats) ?? fallbackText(sub, undefined);
     const icon = Icon !== undefined ? (_jsx(Icon, { entityName: screenId, entityId: null, screenId: screenId, filterParams: screenParams.filterParams })) : undefined;
     if (variant === "strip") {
-        return (_jsx(StatStripCell, { icon: icon, label: label, value: value, tone: tone ?? "default", ...(Icon !== undefined && { accentColor: panel.accentColor }), ...(subText !== undefined && { sub: subText }), ...(delta !== undefined && { delta }), ...(spark !== undefined && { spark }), testId: testId }));
+        return (_jsx(StatStripCell, { icon: icon, label: label, value: value, tone: tone ?? "default", ...(Icon !== undefined && { accentColor: panel.accentColor }), ...(subText !== undefined && { sub: subText }), ...(delta !== undefined && { delta }), ...(spark !== undefined && { spark }), testId: testId, ...(link !== undefined && { link }) }));
     }
-    return (_jsx(StatCard, { icon: icon, label: label, value: value, tone: tone ?? "default", ...(Icon !== undefined && { accentColor: panel.accentColor }), ...(subText !== undefined && { sub: subText }), ...(delta !== undefined && { delta }), ...(spark !== undefined && { spark }), testId: testId }));
+    return (_jsx(StatCard, { icon: icon, label: label, value: value, tone: tone ?? "default", ...(Icon !== undefined && { accentColor: panel.accentColor }), ...(subText !== undefined && { sub: subText }), ...(delta !== undefined && { delta }), ...(spark !== undefined && { spark }), testId: testId, ...(link !== undefined && { link }) }));
+}
+function statNavigationLink(nav, navigate) {
+    if (navigate === undefined)
+        return undefined;
+    const target = { screenId: lastSegment(navigate.screen) };
+    const options = navigate.namedFilter === undefined
+        ? undefined
+        : { searchParams: { [listNamedFilterUrlKey(target.screenId)]: navigate.namedFilter } };
+    return {
+        href: nav.hrefFor(target, options),
+        onPress: () => nav.navigate(target, options),
+    };
 }
 function readDelta(panel, record) {
     if (panel.deltaField === undefined || panel.deltaDirectionField === undefined)

package/dist/web/sse/live-events.d.ts

@@ -10,6 +10,8 @@ export type CreateEventSourceLiveEventsOptions = {
     readonly onSessionEnded?: () => void;
     /** Reconnect-timer seam; defaults to the global setTimeout/clearTimeout. */
     readonly timers?: LiveEventTimers;
+    /** Stall-watchdog timer seam; defaults to the global setTimeout/clearTimeout. */
+    readonly stallTimers?: LiveEventTimers;
     /** Jitter source in [0, 1); defaults to Math.random. */
     readonly random?: () => number;
     /** Clock for synthetic resync events; defaults to Date.now. */
@@ -21,6 +23,7 @@ export type LiveEventTimers = {
 };
 export declare const RECONNECT_BASE_DELAY_MS = 1000;
 export declare const RECONNECT_MAX_DELAY_MS = 30000;
+export declare const SSE_STALL_TIMEOUT_MS = 30000;
 export declare function reconnectDelayMs(attempt: number, random: number): number;
 /** Returns an EventSource-backed `LiveEventSubscriber`.
  *  Typically called once during app bootstrap and passed as a value to

package/dist/web/sse/live-events.js

@@ -3,6 +3,9 @@ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { isSessionEndedError, LIVE_RESYNC_EVENT_TYPE, } from "../../index.js";
 export const RECONNECT_BASE_DELAY_MS = 1_000;
 export const RECONNECT_MAX_DELAY_MS = 30_000;
+// Two missed server heartbeats (15 s each, SSE_HEARTBEAT_INTERVAL_MS in framework sse-route.ts).
+// A KEDA interceptor can leave the stream hanging without an `error` event (kedacore/http-add-on#1803).
+export const SSE_STALL_TIMEOUT_MS = 30_000;
 const defaultTimers = {
     set: (callback, delayMs) => {
         const handle = setTimeout(callback, delayMs);
@@ -67,6 +70,7 @@ async function isSessionEndedRejection(url) {
 export function createEventSourceLiveEvents(options = {}) {
     const url = options.url ?? "/api/sse";
     const timers = options.timers ?? defaultTimers;
+    const stallTimers = options.stallTimers ?? defaultTimers;
     const random = options.random ?? Math.random;
     const now = options.now ?? Date.now;
     const subscribers = new Set();
@@ -74,6 +78,25 @@ export function createEventSourceLiveEvents(options = {}) {
     const wiredEntities = new Set();
     let cancelReconnect;
     let reconnectAttempt = 0;
+    let cancelStallWatchdog;
+    const disarmStallWatchdog = () => {
+        cancelStallWatchdog?.();
+        cancelStallWatchdog = undefined;
+    };
+    const armStallWatchdog = (connection) => {
+        // skip: a frame from a connection that is no longer the current one
+        if (source !== connection)
+            return;
+        disarmStallWatchdog();
+        cancelStallWatchdog = stallTimers.set(() => {
+            cancelStallWatchdog = undefined;
+            // skip: a late timer of a connection that was already replaced
+            if (source !== connection)
+                return;
+            connection.close();
+            scheduleReconnect();
+        }, SSE_STALL_TIMEOUT_MS);
+    };
     // `subscribers` is a flat Set across all entities — the browser-side
     // addEventListener(entityName, ...) gate below only filters which frames
     // arrive at all, not which subscriber a given frame is for. Without this
@@ -119,6 +142,7 @@ export function createEventSourceLiveEvents(options = {}) {
             return;
         connection.addEventListener(entityName, (e) => {
             const data = propertyOf(e, "data");
+            armStallWatchdog(connection);
             if (typeof data === "string")
                 handleEvent(data, entityName);
         });
@@ -142,14 +166,22 @@ export function createEventSourceLiveEvents(options = {}) {
             sessionEndedSignalled = true;
             onSessionEnded?.();
         };
+        armStallWatchdog(connection);
+        connection.addEventListener("ping", () => armStallWatchdog(connection));
         connection.addEventListener("open", () => {
+            armStallWatchdog(connection);
             reconnectAttempt = 0;
             emitResync();
         });
         connection.addEventListener(SESSION_ENDED_EVENT, (e) => {
             const code = sessionEndedFrameCode(e);
-            if (code !== undefined && isSessionEndedError({ code, httpStatus: 401 }))
+            if (code !== undefined && isSessionEndedError({ code, httpStatus: 401 })) {
+                disarmStallWatchdog();
                 signalSessionEnded();
+                // skip: a reconnect after a session end would only be refused again
+                return;
+            }
+            armStallWatchdog(connection);
         });
         connection.addEventListener("error", () => {
             // skip: CONNECTING means a dropped stream the browser retries itself;
@@ -161,10 +193,12 @@ export function createEventSourceLiveEvents(options = {}) {
                 if (source !== connection)
                     return;
                 if (sessionEnded) {
+                    disarmStallWatchdog();
                     signalSessionEnded();
                     // skip: the session ended, reconnecting would only be refused again
                     return;
                 }
+                disarmStallWatchdog();
                 scheduleReconnect();
             });
         });
@@ -196,6 +230,7 @@ export function createEventSourceLiveEvents(options = {}) {
             cancelReconnect = undefined;
         }
         reconnectAttempt = 0;
+        disarmStallWatchdog();
         // skip: already closed, nothing to close
         if (source === undefined)
             return;

package/dist/web/widgets/stat.d.ts

@@ -2,6 +2,11 @@ import type { DashboardStatTone } from "@cosmicdrift/kumiko-types/screen";
 import type { ReactNode } from "react";
 export type StatTone = DashboardStatTone;
 export declare const STAT_CARD_GRID_CLASSES = "grid grid-cols-[repeat(auto-fit,minmax(min(12rem,100%),1fr))] gap-3";
+/** Makes a tile a link; `onPress` is the SPA navigation, `href` serves modified clicks and a11y. */
+export type StatLink = {
+    readonly href: string;
+    readonly onPress: () => void;
+};
 export type StatDelta = {
     readonly value: string;
     readonly direction: "up" | "down";
@@ -13,7 +18,7 @@ export declare function Sparkline({ points, className, }: {
 }): ReactNode;
 /** Icon-bearing metric tile with an optional delta chip, trend line,
  *  and sparkline. `icon` is a ready-made node (the app supplies its SVG). */
-export declare function StatCard({ icon, label, value, sub, tone, accentColor, delta, trend, spark, testId, children, }: {
+export declare function StatCard({ icon, label, value, sub, tone, accentColor, delta, trend, spark, testId, link, children, }: {
     readonly icon?: ReactNode;
     readonly label: string;
     readonly value: string;
@@ -24,13 +29,14 @@ export declare function StatCard({ icon, label, value, sub, tone, accentColor, d
     readonly trend?: string;
     readonly spark?: readonly number[];
     readonly testId?: string;
+    readonly link?: StatLink;
     /** Extra content below the built-in fields (e.g. a usage meter) — kept
      *  inside the same card chrome instead of stacking a second bordered box. */
     readonly children?: ReactNode;
 }): ReactNode;
 /** Flat KPI cell for a strip (divider instead of card): label, value with
  *  sparkline beside it, sub line. */
-export declare function StatStripCell({ icon, label, value, sub, tone, accentColor, delta, spark, testId, }: {
+export declare function StatStripCell({ icon, label, value, sub, tone, accentColor, delta, spark, testId, link, }: {
     /** Chip before the label, colored like StatCard's (`accentColor` or the tone). */
     readonly icon?: ReactNode;
     readonly label: string;
@@ -41,6 +47,7 @@ export declare function StatStripCell({ icon, label, value, sub, tone, accentCol
     readonly delta?: StatDelta;
     readonly spark?: readonly number[];
     readonly testId?: string;
+    readonly link?: StatLink;
 }): ReactNode;
 /** Compact metric tile (without an icon) — for dense KPI grids.
  *  StatCard is the icon-bearing variant. */

package/dist/web/widgets/stat.js

@@ -18,6 +18,12 @@ const TONE_VALUE = {
     warn: "text-destructive",
     negative: "text-status-bad",
 };
+function StatLinkFrame({ link, testId, children, }) {
+    const { Link } = usePrimitives();
+    if (link === undefined)
+        return children;
+    return (_jsx(Link, { href: link.href, onPress: link.onPress, className: "block min-w-0 text-inherit hover:no-underline", ...(testId !== undefined && { testId: `${testId}-link` }), children: children }));
+}
 // Inline SVG sparkline (no chart dependency for a 28px curve): line +
 // subtle area gradient, colored via currentColor (caller sets text-tone).
 export function Sparkline({ points, className, }) {
@@ -47,18 +53,19 @@ function StatIconChip({ icon, tone, accentColor, }) {
 }
 /** Icon-bearing metric tile with an optional delta chip, trend line,
  *  and sparkline. `icon` is a ready-made node (the app supplies its SVG). */
-export function StatCard({ icon, label, value, sub, tone = "default", accentColor, delta, trend, spark, testId, children, }) {
+export function StatCard({ icon, label, value, sub, tone = "default", accentColor, delta, trend, spark, testId, link, children, }) {
     const { Card } = usePrimitives();
     // StatCard is a reusable small-tile widget (a metrics dashboard grid, not
     // a whole-section frame) — an extension section mounting several of
     // these renders a grid of tiles inside its own host Card, not a
     // duplicate outer frame around the section's full content.
-    return (_jsxs(Card, { options: { padded: false }, className: "p-4", testId: testId, children: [_jsxs("div", { className: "flex flex-wrap items-start justify-between gap-x-2 gap-y-1", children: [_jsxs("div", { className: "flex min-w-0 flex-1 basis-[7rem] items-center gap-2 text-muted-foreground", children: [icon !== undefined && _jsx(StatIconChip, { icon: icon, tone: tone, accentColor: accentColor }), _jsx("span", { title: label, className: "min-w-0 line-clamp-2 text-xs font-medium", children: label })] }), delta !== undefined && (_jsxs("span", { className: cn("inline-flex shrink-0 items-center gap-0.5 whitespace-nowrap rounded-full px-1.5 py-0.5 text-xs font-medium tabular-nums", TONE_CHIP[delta.tone ?? tone]), children: [delta.direction === "up" ? "↑" : "↓", delta.value] }))] }), _jsx("div", { className: "mt-2 text-xl font-semibold tabular-nums text-foreground", children: value }), sub !== undefined && _jsx("div", { className: "mt-0.5 text-xs text-muted-foreground", children: sub }), trend !== undefined && (_jsx("div", { className: "mt-0.5 text-xs font-medium text-foreground/80", children: trend })), spark !== undefined && (_jsx(Sparkline, { points: spark, className: cn("mt-2 h-7 w-full", TONE_VALUE[tone]) })), children !== undefined && _jsx("div", { className: "mt-3", children: children })] }));
+    const tile = (_jsxs(Card, { options: { padded: false }, className: "p-4", testId: testId, children: [_jsxs("div", { className: "flex flex-wrap items-start justify-between gap-x-2 gap-y-1", children: [_jsxs("div", { className: "flex min-w-0 flex-1 basis-[7rem] items-center gap-2 text-muted-foreground", children: [icon !== undefined && _jsx(StatIconChip, { icon: icon, tone: tone, accentColor: accentColor }), _jsx("span", { title: label, className: "min-w-0 line-clamp-2 text-xs font-medium", children: label })] }), delta !== undefined && (_jsxs("span", { className: cn("inline-flex shrink-0 items-center gap-0.5 whitespace-nowrap rounded-full px-1.5 py-0.5 text-xs font-medium tabular-nums", TONE_CHIP[delta.tone ?? tone]), children: [delta.direction === "up" ? "↑" : "↓", delta.value] }))] }), _jsx("div", { className: "mt-2 text-xl font-semibold tabular-nums text-foreground", children: value }), sub !== undefined && _jsx("div", { className: "mt-0.5 text-xs text-muted-foreground", children: sub }), trend !== undefined && (_jsx("div", { className: "mt-0.5 text-xs font-medium text-foreground/80", children: trend })), spark !== undefined && (_jsx(Sparkline, { points: spark, className: cn("mt-2 h-7 w-full", TONE_VALUE[tone]) })), children !== undefined && _jsx("div", { className: "mt-3", children: children })] }));
+    return (_jsx(StatLinkFrame, { link: link, testId: testId, children: tile }));
 }
 /** Flat KPI cell for a strip (divider instead of card): label, value with
  *  sparkline beside it, sub line. */
-export function StatStripCell({ icon, label, value, sub, tone = "default", accentColor, delta, spark, testId, }) {
-    return (_jsxs("div", { "data-testid": testId, className: "flex min-w-0 flex-col gap-1 px-4 py-3", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-x-2 gap-y-1", children: [_jsxs("span", { className: "flex min-w-0 items-center gap-2 text-xs font-medium text-muted-foreground", children: [icon !== undefined && _jsx(StatIconChip, { icon: icon, tone: tone, accentColor: accentColor }), _jsx("span", { children: label })] }), delta !== undefined && (_jsxs("span", { className: cn("inline-flex shrink-0 items-center gap-0.5 whitespace-nowrap rounded-full px-1.5 py-0.5 text-xs font-medium tabular-nums", TONE_CHIP[delta.tone ?? tone]), children: [delta.direction === "up" ? "↑" : "↓", delta.value] }))] }), _jsxs("div", { className: "flex items-center gap-3", children: [_jsx("span", { className: cn("text-xl font-semibold tabular-nums", TONE_VALUE[tone]), children: value }), spark !== undefined && (_jsx(Sparkline, { points: spark, className: cn("h-7 w-20 shrink-0", TONE_VALUE[tone]) }))] }), sub !== undefined && _jsx("div", { className: "text-xs text-muted-foreground", children: sub })] }));
+export function StatStripCell({ icon, label, value, sub, tone = "default", accentColor, delta, spark, testId, link, }) {
+    return (_jsx(StatLinkFrame, { link: link, testId: testId, children: _jsxs("div", { "data-testid": testId, className: "flex min-w-0 flex-col gap-1 px-4 py-3", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-x-2 gap-y-1", children: [_jsxs("span", { className: "flex min-w-0 items-center gap-2 text-xs font-medium text-muted-foreground", children: [icon !== undefined && (_jsx(StatIconChip, { icon: icon, tone: tone, accentColor: accentColor })), _jsx("span", { children: label })] }), delta !== undefined && (_jsxs("span", { className: cn("inline-flex shrink-0 items-center gap-0.5 whitespace-nowrap rounded-full px-1.5 py-0.5 text-xs font-medium tabular-nums", TONE_CHIP[delta.tone ?? tone]), children: [delta.direction === "up" ? "↑" : "↓", delta.value] }))] }), _jsxs("div", { className: "flex items-center gap-3", children: [_jsx("span", { className: cn("text-xl font-semibold tabular-nums", TONE_VALUE[tone]), children: value }), spark !== undefined && (_jsx(Sparkline, { points: spark, className: cn("h-7 w-20 shrink-0", TONE_VALUE[tone]) }))] }), sub !== undefined && _jsx("div", { className: "text-xs text-muted-foreground", children: sub })] }) }));
 }
 /** Compact metric tile (without an icon) — for dense KPI grids.
  *  StatCard is the icon-bearing variant. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.402.0",
+  "version": "0.404.0",
   "description": "React renderer for Kumiko screens. The root export holds the platform-agnostic logic (primitives contract, hooks, KumikoScreen, navigation and SSE abstractions); ./headless the DOM-free UI logic, ./live the HTTP dispatcher, ./web the browser bindings (HTML primitives, history navigation, EventSource live events, createKumikoApp).",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -48,8 +48,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.402.0",
-    "@cosmicdrift/kumiko-types": "0.402.0",
+    "@cosmicdrift/kumiko-framework": "0.404.0",
+    "@cosmicdrift/kumiko-types": "0.404.0",
     "@types/qrcode": "^1.5.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -79,8 +79,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-locale-de": "0.402.0",
-    "@cosmicdrift/kumiko-testing": "0.402.0",
+    "@cosmicdrift/kumiko-locale-de": "0.404.0",
+    "@cosmicdrift/kumiko-testing": "0.404.0",
     "@tailwindcss/cli": "^4.3.3",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.8",

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.404.0",
+    "type": "fix",
+    "title": "SSE client reconnects after a stalled stream",
+    "detail": "createEventSourceLiveEvents arms a 30 s watchdog (two missed server heartbeats) that is reset by open, ping and every entity or session-ended frame. On expiry it closes the connection and reconnects through the existing backoff path, which resyncs all listeners. The timer is cleared on close and error. The seam is the new stallTimers option."
+  },
+  {
+    "version": "0.403.0",
+    "type": "improvement",
+    "title": "Lists and dashboard stats take named filters",
+    "detail": "entityList and projectionList take namedFilters [{ id, label }], shown as a removable chip and kept in the URL as <screenId>.filter; it reaches the list, facet and count queries, and defaultFilters are skipped while it is active. A dashboard stat takes navigate { screen, namedFilter } and becomes a link to the filtered list. The boot validator checks that ids exist, that a projectionList query accepts namedFilter, and that the tile counts with the target list's own query and namedFilter."
+  },
   {
     "version": "0.402.0",
     "type": "improvement",