@cosmicdrift/kumiko-renderer 0.402.0 → 0.403.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/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.403.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.403.0",
+    "@cosmicdrift/kumiko-types": "0.403.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.403.0",
+    "@cosmicdrift/kumiko-testing": "0.403.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,10 @@
 [
+  {
+    "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",