@cosmicdrift/kumiko-renderer 0.398.0 → 0.399.0

package/dist/app/entity-list-facet-specs.js

@@ -13,6 +13,7 @@ export function resolveEntityFacetSpecs(fields, featureName, entityName, transla
             options: propertyOf(rawDef, "options"),
             entity: propertyOf(rawDef, "entity"),
             labelField: propertyOf(rawDef, "labelField"),
+            optionsQuery: propertyOf(rawDef, "optionsQuery"),
         };
         if (def.filterable !== true)
             continue;
@@ -57,6 +58,7 @@ export function resolveEntityFacetSpecs(fields, featureName, entityName, transla
                     refEntity: target.entityName,
                     refFeature: target.featureName,
                     labelField: typeof def.labelField === "string" ? def.labelField : "id",
+                    ...(typeof def.optionsQuery === "string" && { optionsQuery: def.optionsQuery }),
                 },
             });
         }

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

@@ -25,7 +25,7 @@ import { isDefaultFilterActive, isListNarrowed, useListEmptyContent, } from "./l
 import { buildEntityFilterFacets, buildFacetCountRequests, buildFilterPayload, mergeReferenceFacetOptions, normalizeDefaultFilters, } from "./list-facets.js";
 import { useNav } from "./nav.js";
 import { QueryErrorBanner, QueryLoadingBanner } from "./query-state-banners.js";
-import { ReferenceFacetBridges } from "./reference-facet-bridge.js";
+import { ReferenceFacetBridges, withReferenceFacetState, } from "./reference-facet-bridge.js";
 import { navigateWithReturnTo, useReturnHost } from "./return-to.js";
 import { buildClientActionRowAction, buildDefaultEditRowAction, buildDrawerRowAction, buildProjectionToolbarActions, buildWriteHandlerRowAction, findRowClickAction, navigateActionSearchParams, runDrawerRowAction, } from "./row-actions.js";
 import { findEditScreenFor } from "./screen-access.js";
@@ -154,7 +154,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
         await refreshListAfterWrite();
     }, [refreshFacetCounts, refreshListAfterWrite]);
     const [entityReferenceFacetOptions, setEntityReferenceFacetOptions] = useState({});
-    const handleEntityFacetOptions = useCallback((field, options) => setEntityReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
+    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]);
@@ -395,7 +395,7 @@ 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, onOptions: 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: 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 }

package/dist/app/list-facets.d.ts

@@ -1,6 +1,7 @@
 import type { EntityListFacetConfig, ListFacetSpec } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Translate } from "../headless/index.ts";
 import type { DataTableFacet, DataTableFacetChip } from "../primitives.tsx";
+import type { ReferenceFacetState } from "./reference-facet-bridge.tsx";
 export type ResolvedFacetSpec = {
     readonly field: string;
     readonly type: "select" | "boolean" | "reference";
@@ -17,12 +18,14 @@ export type ResolvedFacetSpec = {
         readonly refEntity: string;
         readonly refFeature: string;
         readonly labelField: string;
+        /** Author handler that serves the options instead of the entity list. */
+        readonly optionsQuery?: string;
     };
+    /** Reference facets only: set once the bridge resolved it. Makes the facet searchable. */
+    readonly onSearchChange?: (query: string) => void;
+    readonly searching?: boolean;
 };
-export declare function mergeReferenceFacetOptions(specs: readonly ResolvedFacetSpec[], optionsByField: Readonly<Record<string, readonly {
-    readonly value: string;
-    readonly label: string;
-}[]>>): ResolvedFacetSpec[];
+export declare function mergeReferenceFacetOptions(specs: readonly ResolvedFacetSpec[], stateByField: Readonly<Record<string, ReferenceFacetState>>): ResolvedFacetSpec[];
 export declare function buildFilterFacets(specs: readonly ResolvedFacetSpec[]): DataTableFacet[];
 type FacetConfigByField = Readonly<Record<string, EntityListFacetConfig | false>>;
 export declare function buildFacetChips(spec: ResolvedFacetSpec, config: EntityListFacetConfig, translate: Translate): DataTableFacetChip[];

package/dist/app/list-facets.js

@@ -4,13 +4,30 @@ import { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 // Fills in a "reference" spec's initially-empty `options` from the
 // field-keyed options ReferenceFacetBridges resolved, shared by every caller.
-export function mergeReferenceFacetOptions(specs, optionsByField) {
-    return specs.map((spec) => spec.reference !== undefined
-        ? { ...spec, options: optionsByField[spec.field] ?? spec.options }
-        : spec);
+export function mergeReferenceFacetOptions(specs, stateByField) {
+    return specs.map((spec) => {
+        const state = stateByField[spec.field];
+        return spec.reference !== undefined && state !== undefined
+            ? {
+                ...spec,
+                options: state.options,
+                onSearchChange: state.onSearchChange,
+                searching: state.searching,
+            }
+            : spec;
+    });
+}
+function facetBase(spec) {
+    return {
+        field: spec.field,
+        label: spec.label,
+        options: spec.options,
+        ...(spec.onSearchChange !== undefined && { onSearchChange: spec.onSearchChange }),
+        ...(spec.searching !== undefined && { searching: spec.searching }),
+    };
 }
 export function buildFilterFacets(specs) {
-    return specs.map((spec) => ({ field: spec.field, label: spec.label, options: spec.options }));
+    return specs.map(facetBase);
 }
 // Chips are the field's own options plus the declared extra choices
 // ("Running" bundle, "All"), in the order the config's `position` asks for.
@@ -39,7 +56,7 @@ export function buildEntityFilterFacets(specs, configs, translate, counts) {
         const config = configs?.[spec.field];
         if (config === false)
             continue;
-        const base = { field: spec.field, label: spec.label, options: spec.options };
+        const base = facetBase(spec);
         if (config?.display !== "chips") {
             out.push(base);
             continue;

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

@@ -108,7 +108,7 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
         limit: query.limit,
         urlState: query.urlState,
     });
-    return (_jsxs(_Fragment, { children: [refetchErrorBanner, actions.toolbarGateQueries, _jsx(ListGroupPageBridges, { ...data.listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: query.facetSpecs, onOptions: query.handleProjectionFacetOptions }), renderProjectionList({
+    return (_jsxs(_Fragment, { children: [refetchErrorBanner, actions.toolbarGateQueries, _jsx(ListGroupPageBridges, { ...data.listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: query.facetSpecs, selected: query.urlState.filters, onState: query.handleProjectionFacetOptions }), renderProjectionList({
                 schema,
                 screen,
                 translate,

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

@@ -4,7 +4,19 @@ export type ReferenceFacetOption = {
     readonly value: string;
     readonly label: string;
 };
-export declare function ReferenceFacetBridges({ specs, onOptions, }: {
+/** What a bridge publishes for its facet: the options for the current search term plus the
+ *  handle that changes the term. */
+export type ReferenceFacetState = {
+    readonly options: readonly ReferenceFacetOption[];
+    readonly onSearchChange: (query: string) => void;
+    readonly searching: boolean;
+};
+/** Reducer step for the callers' state: same state keeps the previous object, so an unchanged
+ *  bridge does not re-render the list. */
+export declare function withReferenceFacetState(previous: Readonly<Record<string, ReferenceFacetState>>, field: string, state: ReferenceFacetState): Readonly<Record<string, ReferenceFacetState>>;
+export declare function ReferenceFacetBridges({ specs, selected, onState, }: {
     readonly specs: readonly ResolvedFacetSpec[];
-    readonly onOptions: (field: string, options: readonly ReferenceFacetOption[]) => void;
+    /** The facet selections of the list (field to chosen ids), so chosen values keep their label. */
+    readonly selected: Readonly<Record<string, readonly string[]>>;
+    readonly onState: (field: string, state: ReferenceFacetState) => void;
 }): ReactNode;

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

@@ -1,29 +1,48 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 // One bridge component per reference facet, mirroring ReferenceLookupBridge —
 // facet count varies per screen, so the hook can't be called in a loop.
-import { useEffect } from "react";
-import { rendererWarn } from "../dev-console.js";
-import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
-import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
-function ReferenceFacetOptionsBridge({ field, refEntity, refFeature, labelField, onOptions, }) {
-    const lookup = useReferenceLookup(refFeature, refEntity, labelField);
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
+import { useQuery } from "../hooks/use-query.js";
+import { referenceOptionSource, storedReferenceRowsPayload, withUnlistedSelectedRows, } from "../hooks/use-reference-lookup.js";
+/** Reducer step for the callers' state: same state keeps the previous object, so an unchanged
+ *  bridge does not re-render the list. */
+export function withReferenceFacetState(previous, field, state) {
+    const before = previous[field];
+    const unchanged = before?.options === state.options &&
+        before.searching === state.searching &&
+        before.onSearchChange === state.onSearchChange;
+    return unchanged ? previous : { ...previous, [field]: state };
+}
+function ReferenceFacetOptionsBridge({ field, refEntity, refFeature, labelField, optionsQuery, selected, onState, }) {
+    const { queryQn, labelKey } = referenceOptionSource({
+        refLabelField: labelField,
+        ...(optionsQuery !== undefined && { refOptionsQuery: optionsQuery }),
+    }, refFeature, refEntity);
+    const [searchTerm, setSearchTerm] = useState("");
+    const payload = useMemo(() => searchTerm === ""
+        ? { limit: REFERENCE_COMBOBOX_LIMIT }
+        : { limit: REFERENCE_COMBOBOX_LIMIT, search: searchTerm }, [searchTerm]);
+    const listed = useQuery(queryQn, payload);
+    // The first page can miss a chosen value; without its row the chip would show the raw id.
+    const chosen = useQuery(queryQn, storedReferenceRowsPayload(optionsQuery !== undefined ? { refOptionsQuery: optionsQuery } : {}, selected, REFERENCE_COMBOBOX_LIMIT), { enabled: selected.length > 0 });
+    const onSearchChange = useCallback((query) => setSearchTerm(query), []);
+    const options = useMemo(() => withUnlistedSelectedRows(listed.data?.rows ?? [], chosen.data?.rows ?? []).map((row) => {
+        const value = String(row["id"] ?? "");
+        return { value, label: String(row[labelKey] ?? value) };
+    }), [listed.data, chosen.data, labelKey]);
+    const searching = listed.loading;
     useEffect(() => {
-        if (lookup.loading)
-            return;
-        // The lookup is one capped list fetch; a full page means the facet may be
-        // missing values the user wants to filter by.
-        if (lookup.map.size >= REFERENCE_LIST_LOOKUP_LIMIT) {
-            rendererWarn(`[kumiko] reference facet "${field}" shows only the first ${REFERENCE_LIST_LOOKUP_LIMIT} ${refEntity} rows; further values cannot be filtered by`);
-        }
-        onOptions(field, [...lookup.map.entries()].map(([value, label]) => ({ value, label })));
-    }, [lookup.loading, lookup.map, field, refEntity, onOptions]);
+        onState(field, { options, onSearchChange, searching });
+    }, [field, options, onSearchChange, searching, onState]);
     return null;
 }
 // One invisible bridge per "reference" facet spec, each publishing its
-// resolved options back via `onOptions` once loaded.
-export function ReferenceFacetBridges({ specs, onOptions, }) {
+// resolved options back via `onState` once loaded.
+export function ReferenceFacetBridges({ specs, selected, onState, }) {
     const referenceSpecs = specs.filter((spec) => spec.reference !== undefined);
     if (referenceSpecs.length === 0)
         return null;
-    return (_jsx(_Fragment, { children: referenceSpecs.map((spec) => (_jsx(ReferenceFacetOptionsBridge, { field: spec.field, refEntity: spec.reference?.refEntity ?? "", refFeature: spec.reference?.refFeature ?? "", labelField: spec.reference?.labelField ?? "id", onOptions: onOptions }, spec.field))) }));
+    return (_jsx(_Fragment, { children: referenceSpecs.map((spec) => (_jsx(ReferenceFacetOptionsBridge, { field: spec.field, refEntity: spec.reference?.refEntity ?? "", refFeature: spec.reference?.refFeature ?? "", labelField: spec.reference?.labelField ?? "id", optionsQuery: spec.reference?.optionsQuery, selected: selected[spec.field] ?? NO_SELECTION, onState: onState }, spec.field))) }));
 }
+const NO_SELECTION = [];

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

@@ -2,7 +2,7 @@ import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framewo
 import type { Translate } from "../headless/index.ts";
 import { type ListUrlStateApi } from "../hooks/use-list-url-state.ts";
 import type { synthesizeProjectionEntity } from "./projection-list-shim.ts";
-import type { ReferenceFacetOption } from "./reference-facet-bridge.tsx";
+import { type ReferenceFacetState } from "./reference-facet-bridge.tsx";
 type ProjectionListQueryInput = {
     readonly screen: ProjectionListScreenDefinition;
     readonly featureName: string;
@@ -19,7 +19,7 @@ export declare function useProjectionListQuery(input: ProjectionListQueryInput):
     limit: number;
     usePager: boolean;
     facetSpecs: import("./list-facets.ts").ResolvedFacetSpec[];
-    handleProjectionFacetOptions: (field: string, options: readonly ReferenceFacetOption[]) => void;
+    handleProjectionFacetOptions: (field: string, state: ReferenceFacetState) => void;
     resolvedFacetSpecs: import("./list-facets.ts").ResolvedFacetSpec[];
     dateRangeFacets: import("../data-table-facet-types.ts").DataTableDateRangeFacet[];
     handleDateRangeChange: (field: string, bound: "from" | "to", value: string) => void;

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

@@ -1,6 +1,7 @@
 import { useCallback, useMemo, useState } from "react";
 import { useListUrlState } from "../hooks/use-list-url-state.js";
 import { buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "./list-facets.js";
+import { withReferenceFacetState } from "./reference-facet-bridge.js";
 import { buildListQueryPayload } from "./screen-shared.js";
 import { useProjectionDateRange } from "./use-projection-date-range.js";
 // Same predicate that makes a header clickable: a stale link onto a
@@ -30,7 +31,7 @@ export function useProjectionListQuery(input) {
     // buildFilterFacets/buildFilterPayload.
     const facetSpecs = useMemo(() => resolveProjectionFacetSpecs(screen.facets, effectiveTranslate, featureName), [screen.facets, effectiveTranslate, featureName]);
     const [projectionReferenceFacetOptions, setProjectionReferenceFacetOptions] = useState({});
-    const handleProjectionFacetOptions = useCallback((field, options) => setProjectionReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
+    const handleProjectionFacetOptions = useCallback((field, state) => setProjectionReferenceFacetOptions((prev) => withReferenceFacetState(prev, field, state)), []);
     const resolvedFacetSpecs = useMemo(() => mergeReferenceFacetOptions(facetSpecs, projectionReferenceFacetOptions), [facetSpecs, projectionReferenceFacetOptions]);
     const filterPayload = useMemo(() => buildFilterPayload(urlState.filters, (field) => facetSpecs.find((spec) => spec.field === field)?.type), [urlState.filters, facetSpecs]);
     const { dateRangePayload, dateRangeFacets, handleDateRangeChange } = useProjectionDateRange(screen.facets, effectiveTranslate, urlState);

package/dist/components/related-list-section.js

@@ -8,7 +8,7 @@ import { useListBulk } from "../app/list-bulk-actions.js";
 import { buildFilterFacets, buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "../app/list-facets.js";
 import { useNav } from "../app/nav.js";
 import { SYNTHESIZED_FIELD_PII_REASON } from "../app/projection-list-shim.js";
-import { ReferenceFacetBridges, } from "../app/reference-facet-bridge.js";
+import { ReferenceFacetBridges, withReferenceFacetState, } from "../app/reference-facet-bridge.js";
 import { navigateWithReturnTo, useReturnHost } from "../app/return-to.js";
 import { buildDefaultEditRowAction, buildProjectionRowActions, buildProjectionToolbarActions, buildRecordActions, findRowClickAction, runDrawerRowAction, runProjectionRowNavigate, } from "../app/row-actions.js";
 import { findEditScreenFor } from "../app/screen-access.js";
@@ -142,7 +142,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
     const { search, filters, sort, setSearch, setFilters, setSort, listTable, groupField } = useRelatedListState(section, nav.route?.screenId);
     const facetSpecs = useMemo(() => resolveProjectionFacetSpecs(section.facets, effectiveTranslate, featureName), [section.facets, effectiveTranslate, featureName]);
     const [referenceFacetOptions, setReferenceFacetOptions] = useState({});
-    const handleFacetOptions = useCallback((field, options) => setReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
+    const handleFacetOptions = useCallback((field, state) => setReferenceFacetOptions((prev) => withReferenceFacetState(prev, field, state)), []);
     const resolvedFacetSpecs = useMemo(() => mergeReferenceFacetOptions(facetSpecs, referenceFacetOptions), [facetSpecs, referenceFacetOptions]);
     const filterPayload = useMemo(() => buildFilterPayload(filters, (field) => resolvedFacetSpecs.find((spec) => spec.field === field)?.type), [filters, resolvedFacetSpecs]);
     const filterFacets = useMemo(() => buildFilterFacets(resolvedFacetSpecs), [resolvedFacetSpecs]);
@@ -332,7 +332,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
     // `renderer` stays DOM-free. Stacked (non-tabs) sections keep their own
     // Section card and document-flow height since they render a visible title
     // and aren't confined to a tab panel.
-    const bridges = _jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleFacetOptions });
+    const bridges = (_jsx(ReferenceFacetBridges, { specs: facetSpecs, selected: filters, onState: handleFacetOptions }));
     if (embedded === true) {
         const countSuffix = listRows.hasData
             ? ` · ${aggregates.serverGroups?.totalCount ?? listRows.rows.length}`

package/dist/components/render-edit-fields-section.js

@@ -10,7 +10,7 @@ function renderTabbedGroupsSection(rc, section, sectionKey) {
     // group cards (Card-in-Card) — the boot-validator rejects that
     // combination in tabs mode, so `sectionActionsEl` is always
     // undefined here at runtime.
-    return rc.wrapWizardStep(sectionKey, _jsx(Card, { options: { framed: false }, children: groupsGrid }, sectionKey));
+    return rc.wrapWizardStep(sectionKey, _jsx(Card, { options: { framed: false }, ...(section.description !== undefined && { slots: { subtitle: section.description } }), children: groupsGrid }, sectionKey));
 }
 function renderTabbedFieldsSection(rc, section, sectionKey) {
     if (section.groups !== undefined)

package/dist/data-table-facet-types.d.ts

@@ -16,6 +16,11 @@ export type DataTableFacet = {
     readonly showCounts?: boolean;
     /** Chips only: hide chips whose `count` is 0 (unless pressed). */
     readonly hideEmpty?: boolean;
+    /** Present: the options come from a server-side search (reference facets), so the dropdown
+     *  shows a search field and reports the typed term instead of filtering `options` itself. */
+    readonly onSearchChange?: (query: string) => void;
+    /** The search is loading; the option list may still show the previous term's rows. */
+    readonly searching?: boolean;
 };
 export type DataTableFacetChip = {
     readonly id: string;

package/dist/i18n-defaults.js

@@ -242,6 +242,14 @@ export const kumikoDefaultTranslations = {
         "kumiko.nav.expand": "Expand",
         "kumiko.nav.collapse": "Collapse",
         "kumiko.nav.search": "Search navigation…",
+        "kumiko.notifications.label": "Notifications",
+        "kumiko.notifications.labelUnread": "Notifications, {count} unread",
+        "kumiko.notifications.title": "Notifications",
+        "kumiko.notifications.empty": "No notifications yet.",
+        "kumiko.notifications.markAllRead": "Mark all as read",
+        "kumiko.notifications.loadMore": "Load more",
+        "kumiko.notifications.unread": "Unread",
+        "kumiko.notifications.loadFailed": "Notifications could not be loaded.",
         "kumiko.nav.language": "Language",
         "kumiko.workspace.switch": "Switch workspace",
         // Workspace-Switcher fallback label when activeId points at no visible workspace.

package/dist/web/layout/notification-bell.d.ts

@@ -0,0 +1,5 @@
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+export declare function NotificationBell({ screens, }: {
+    readonly screens: readonly ScreenDefinition[];
+}): ReactNode;

package/dist/web/layout/notification-bell.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Bell } from "lucide-react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { useState } from "react";
+import { lastSegment, useLocale, useNav, useTranslation } from "../../index.js";
+import { useRelativeTimeFormatter } from "../app/relative-time.js";
+import { cn } from "../lib/cn.js";
+import { useInAppInbox } from "./use-in-app-inbox.js";
+const MAX_BADGE_COUNT = 99;
+const triggerClass = "relative inline-flex size-8 shrink-0 items-center justify-center rounded-md border border-input " +
+    "bg-background text-foreground shadow-xs transition-colors hover:bg-accent " +
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+const panelClass = "z-50 flex max-h-[28rem] w-[min(22rem,calc(100vw-1.5rem))] flex-col overflow-hidden rounded-md border " +
+    "bg-popover text-popover-foreground shadow-md";
+export function NotificationBell({ screens, }) {
+    const t = useTranslation();
+    const nav = useNav();
+    const locale = useLocale().locale();
+    const formatRelative = useRelativeTimeFormatter(locale);
+    const [open, setOpen] = useState(false);
+    const inbox = useInAppInbox(open);
+    const badge = inbox.unreadCount > MAX_BADGE_COUNT ? `${MAX_BADGE_COUNT}+` : String(inbox.unreadCount);
+    const label = inbox.unreadCount > 0
+        ? t("kumiko.notifications.labelUnread", { count: badge })
+        : t("kumiko.notifications.label");
+    const openRow = async (row) => {
+        if (!row.isRead)
+            await inbox.markRead(row.id);
+        const target = row.target;
+        if (target === null)
+            return;
+        if (!screens.some((screen) => screen.id === target.screenId))
+            return;
+        const screenId = lastSegment(target.screenId);
+        setOpen(false);
+        nav.navigate(target.entityId === undefined ? { screenId } : { screenId, entityId: target.entityId });
+    };
+    return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Trigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": label, "data-kumiko-layout": "notification-bell", className: triggerClass, children: [_jsx(Bell, { className: "size-4", "aria-hidden": "true" }), inbox.unreadCount > 0 && (_jsx("span", { "data-kumiko-layout": "notification-bell-badge", className: "absolute -right-1.5 -top-1.5 flex min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-semibold leading-4 text-destructive-foreground", children: badge }))] }) }), _jsx(PopoverPrimitive.Portal, { children: _jsxs(PopoverPrimitive.Content, { align: "end", sideOffset: 6, className: panelClass, children: [_jsxs("div", { className: "flex items-center justify-between gap-2 border-b border-border px-3 py-2", children: [_jsx("h2", { className: "text-sm font-semibold", children: t("kumiko.notifications.title") }), inbox.unreadCount > 0 && (_jsx("button", { type: "button", className: "text-xs text-primary hover:underline", onClick: () => void inbox.markAllRead(), children: t("kumiko.notifications.markAllRead") }))] }), _jsxs("div", { className: "min-h-0 flex-1 overflow-y-auto", children: [inbox.failed && (_jsx("p", { role: "alert", className: "px-3 py-4 text-sm text-destructive", children: t("kumiko.notifications.loadFailed") })), !inbox.failed && !inbox.loading && inbox.rows.length === 0 && (_jsx("p", { className: "px-3 py-6 text-center text-sm text-muted-foreground", children: t("kumiko.notifications.empty") })), _jsx("ul", { children: inbox.rows.map((row) => (_jsx("li", { children: _jsxs("button", { type: "button", "data-unread": row.isRead ? undefined : "true", className: "flex w-full items-start gap-2 border-b border-border px-3 py-2 text-left hover:bg-accent focus-visible:bg-accent focus-visible:outline-none", onClick: () => void openRow(row), children: [_jsx("span", { "aria-hidden": "true", className: cn("mt-1.5 size-2 shrink-0 rounded-full", row.isRead ? "bg-transparent" : "bg-primary") }), !row.isRead && (_jsx("span", { className: "sr-only", children: t("kumiko.notifications.unread") })), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: cn("block truncate text-sm", !row.isRead && "font-semibold"), children: row.title }), row.body !== null && (_jsx("span", { className: "block truncate text-xs text-muted-foreground", children: row.body })), _jsx("span", { className: "block text-xs text-muted-foreground", children: formatRelative(Date.parse(row.createdAt)) })] })] }) }, row.id))) }), inbox.hasMore && (_jsx("button", { type: "button", className: "w-full px-3 py-2 text-sm text-primary hover:bg-accent", onClick: () => void inbox.loadMore(), children: t("kumiko.notifications.loadMore") }))] })] }) })] }));
+}

package/dist/web/layout/shell-header.js

@@ -7,6 +7,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // The `data-kumiko-layout="shell-header"` marker drives `--shell-header-height`
 // in styles.css (:has() selector) — the single source for the header height
 // that Drawer's `belowHeader` prop also reads.
+import { IN_APP_NOTIFICATION_FEATURE } from "@cosmicdrift/kumiko-types/in-app-notification-types";
 import { MoreHorizontal } from "lucide-react";
 import { Fragment, useEffect, useId, useMemo, useRef, useState, } from "react";
 import { resolveNavigation } from "../../headless/index.js";
@@ -17,6 +18,7 @@ import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbP
 import { SidebarTrigger } from "../ui/sidebar.js";
 import { HeaderOverflowMenuContext, headerOverflowMenuItemClass } from "./header-overflow-menu.js";
 import { buildNavRegistrySliceForApp } from "./nav-tree.js";
+import { NotificationBell } from "./notification-bell.js";
 import { usePageHeaderSlot } from "./page-header-slot.js";
 import { activeNavLabel, resolveDetailBreadcrumb, screenTitleKey, } from "./shell-breadcrumb.js";
 import { SHELL_HEADER_CONTROLS_CLASSES } from "./uniform-bar-controls.js";
@@ -35,6 +37,7 @@ export function ShellHeader({ schema, user, headerActions, allowedNavQns, }) {
         return resolveNavigation({ source, ...(user !== undefined && { user }) });
     }, [appSchema, user, allowedNavQns]);
     const allScreens = useMemo(() => appSchema.features.flatMap((f) => f.screens), [appSchema.features]);
+    const hasInAppChannel = appSchema.features.some((feature) => feature.featureName === IN_APP_NOTIFICATION_FEATURE);
     const slot = usePageHeaderSlot();
     const standInScreenId = slot?.breadcrumbScreenId;
     const screenId = standInScreenId ?? nav.route?.screenId;
@@ -78,7 +81,7 @@ export function ShellHeader({ schema, user, headerActions, allowedNavQns, }) {
                                                     e.preventDefault();
                                                     nav.navigate({ screenId });
                                                 }, children: crumb.label })) : isLast ? (_jsx("h1", { "aria-current": "page", title: titleOverride ?? crumb.label, className: "truncate text-lg font-semibold text-foreground", children: titleOverride ?? crumb.label })) : (_jsx(BreadcrumbPage, { className: "whitespace-nowrap text-foreground-secondary", children: crumb.label })) })] }, screenId ?? crumb.label));
-                            }) }) })), _jsx("div", { ref: setStatusElement, "data-kumiko-layout": "page-header-status", className: cn("flex items-center gap-2 empty:hidden", compact ? "min-w-0 overflow-hidden" : "shrink-0") })] }), _jsxs("div", { className: cn("ml-auto flex items-center gap-2", compact ? "min-w-0 max-w-[60%]" : "min-w-0 max-w-[50%] shrink-0 sm:max-w-none"), children: [_jsx("div", { ref: setActionsElement, "data-kumiko-layout": "page-header-actions", className: cn(SHELL_HEADER_CONTROLS_CLASSES, "flex min-w-0 items-center gap-2 empty:hidden [&_*]:min-w-0 [&_*]:max-w-full [&_button]:overflow-hidden [&_button]:whitespace-nowrap", compact && "overflow-hidden") }), !compact && headerActions !== undefined && (_jsx("div", { "data-kumiko-layout": "header-actions", className: "flex items-center gap-2", children: headerActions })), hasOverflow && _jsx(HeaderOverflow, { items: overflowItems, headerActions: headerActions })] })] }));
+                            }) }) })), _jsx("div", { ref: setStatusElement, "data-kumiko-layout": "page-header-status", className: cn("flex items-center gap-2 empty:hidden", compact ? "min-w-0 overflow-hidden" : "shrink-0") })] }), _jsxs("div", { className: cn("ml-auto flex items-center gap-2", compact ? "min-w-0 max-w-[60%]" : "min-w-0 max-w-[50%] shrink-0 sm:max-w-none"), children: [_jsx("div", { ref: setActionsElement, "data-kumiko-layout": "page-header-actions", className: cn(SHELL_HEADER_CONTROLS_CLASSES, "flex min-w-0 items-center gap-2 empty:hidden [&_*]:min-w-0 [&_*]:max-w-full [&_button]:overflow-hidden [&_button]:whitespace-nowrap", compact && "overflow-hidden") }), user !== undefined && hasInAppChannel && _jsx(NotificationBell, { screens: allScreens }), !compact && headerActions !== undefined && (_jsx("div", { "data-kumiko-layout": "header-actions", className: "flex items-center gap-2", children: headerActions })), hasOverflow && _jsx(HeaderOverflow, { items: overflowItems, headerActions: headerActions })] })] }));
 }
 // A hand-rolled menu instead of Radix DropdownMenu: app headerActions are opaque
 // nodes with their own popovers, and the panel stays mounted while closed so their

package/dist/web/layout/use-in-app-inbox.d.ts

@@ -0,0 +1,15 @@
+import { type InAppInboxRow } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+export declare const IN_APP_INBOX_PAGE_SIZE = 20;
+export type InAppInbox = {
+    readonly unreadCount: number;
+    readonly rows: readonly InAppInboxRow[];
+    readonly hasMore: boolean;
+    readonly loading: boolean;
+    readonly failed: boolean;
+    readonly loadMore: () => Promise<void>;
+    readonly markRead: (id: number) => Promise<void>;
+    readonly markAllRead: () => Promise<void>;
+};
+/** Headless state of the notification bell: the unread count always, the list only while `open`.
+ *  The delivered signal refetches both; no polling. */
+export declare function useInAppInbox(open: boolean): InAppInbox;

package/dist/web/layout/use-in-app-inbox.js

@@ -0,0 +1,61 @@
+import { IN_APP_NOTIFICATION_DELIVERED_EVENT, IN_APP_NOTIFICATION_QUERIES, IN_APP_NOTIFICATION_WRITES, } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+import { useCallback, useEffect, useState } from "react";
+import { useDispatcher } from "../../context/dispatcher-context.js";
+import { useMutation } from "../../hooks/use-mutation.js";
+import { useQuery } from "../../hooks/use-query.js";
+import { useLiveEvents } from "../../sse/live-events.js";
+export const IN_APP_INBOX_PAGE_SIZE = 20;
+/** Headless state of the notification bell: the unread count always, the list only while `open`.
+ *  The delivered signal refetches both; no polling. */
+export function useInAppInbox(open) {
+    const dispatcher = useDispatcher();
+    const subscribe = useLiveEvents();
+    const count = useQuery(IN_APP_NOTIFICATION_QUERIES.unreadCount, {});
+    const firstPage = useQuery(IN_APP_NOTIFICATION_QUERIES.inbox, { limit: IN_APP_INBOX_PAGE_SIZE }, { enabled: open });
+    const [olderRows, setOlderRows] = useState([]);
+    const [olderCursor, setOlderCursor] = useState(undefined);
+    const markReadWrite = useMutation(IN_APP_NOTIFICATION_WRITES.markRead);
+    const markAllReadWrite = useMutation(IN_APP_NOTIFICATION_WRITES.markAllRead);
+    const refetchCount = count.refetch;
+    const refetchFirstPage = firstPage.refetch;
+    const refetchAll = useCallback(async () => {
+        setOlderRows([]);
+        setOlderCursor(undefined);
+        await Promise.all([refetchCount(), open ? refetchFirstPage() : Promise.resolve()]);
+    }, [refetchCount, refetchFirstPage, open]);
+    useEffect(() => subscribe(IN_APP_NOTIFICATION_DELIVERED_EVENT, () => void refetchAll()), [subscribe, refetchAll]);
+    const firstRows = firstPage.data?.rows ?? [];
+    const nextCursor = olderCursor === undefined ? (firstPage.data?.nextCursor ?? null) : olderCursor;
+    const loadMore = useCallback(async () => {
+        // skip: no older page left
+        if (nextCursor === null)
+            return;
+        const result = await dispatcher.query(IN_APP_NOTIFICATION_QUERIES.inbox, {
+            limit: IN_APP_INBOX_PAGE_SIZE,
+            cursor: nextCursor,
+        });
+        // skip: keep the loaded rows, the next click retries
+        if (!result.isSuccess)
+            return;
+        setOlderRows((previous) => [...previous, ...result.data.rows]);
+        setOlderCursor(result.data.nextCursor);
+    }, [dispatcher, nextCursor]);
+    const markRead = useCallback(async (id) => {
+        await markReadWrite.mutate({ id });
+        await refetchAll();
+    }, [markReadWrite.mutate, refetchAll]);
+    const markAllRead = useCallback(async () => {
+        await markAllReadWrite.mutate({});
+        await refetchAll();
+    }, [markAllReadWrite.mutate, refetchAll]);
+    return {
+        unreadCount: count.data?.count ?? 0,
+        rows: [...firstRows, ...olderRows],
+        hasMore: nextCursor !== null,
+        loading: firstPage.loading,
+        failed: firstPage.error !== null,
+        loadMore,
+        markRead,
+        markAllRead,
+    };
+}

package/dist/web/primitives/facet-filter.js

@@ -6,6 +6,7 @@ import { Button as UiButton } from "../ui/button.js";
 import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuTrigger, } from "./dropdown-menu.js";
 import "../react-css-custom-properties.js";
 import { DefaultButton } from "./button.js";
+import { FacetSearchFilter } from "./facet-search-filter.js";
 // ---- DataTable (shadcn: Table) ----
 function sameValueSet(a, b) {
     return a.length === b.length && a.every((value) => b.includes(value));
@@ -26,6 +27,9 @@ export function FacetFilter({ facet, selected, onChange, dense = false, }) {
     if (facet.chips !== undefined) {
         return _jsx(FacetChips, { facet: facet, selected: selected, onChange: onChange });
     }
+    if (facet.onSearchChange !== undefined) {
+        return (_jsx(FacetSearchFilter, { facet: facet, onSearchChange: facet.onSearchChange, selected: selected, onChange: onChange, dense: dense }));
+    }
     return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(UiButton, { variant: "outline", size: "sm", className: cn("h-9", dense && "border-border-strong px-2.5"), "data-testid": `facet-${facet.field}`, children: [facet.label, selected.length > 0 && (_jsx(Badge, { variant: "secondary", className: "ml-1 rounded-sm px-1 font-normal tabular-nums", children: selected.length })), _jsx(ChevronDown, { className: "text-muted-foreground" })] }) }), _jsx(DropdownMenuContent, { align: "start", className: "max-h-[var(--radix-dropdown-menu-content-available-height)] w-44 overflow-y-auto", children: facet.options.map((opt) => (_jsx(DropdownMenuCheckboxItem, { checked: selected.includes(opt.value), onCheckedChange: (checked) => toggle(opt.value, checked), onSelect: (e) => e.preventDefault(), "data-testid": `facet-${facet.field}-${opt.value}`, children: opt.label }, opt.value))) })] }));
 }
 // Time-range filter: two native <input type="date"> instead of a

package/dist/web/primitives/facet-search-filter.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+import { type DataTableFacet } from "../../index.ts";
+export declare function FacetSearchFilter({ facet, onSearchChange, selected, onChange, dense, }: {
+    facet: DataTableFacet;
+    onSearchChange: (query: string) => void;
+    selected: readonly string[];
+    onChange: (field: string, values: readonly string[]) => void;
+    dense: boolean;
+}): ReactNode;

package/dist/web/primitives/facet-search-filter.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Facet dropdown with a server-side search field, for reference facets whose option list is a
+// capped page. A Radix DropdownMenu would swallow the typed keys for its typeahead, so this is a
+// Popover + cmdk list like ComboboxInput, with the facet's own trigger button.
+import { Command } from "cmdk";
+import { Check, ChevronDown, Loader2 } from "lucide-react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { useEffect, useState } from "react";
+import { REFERENCE_SEARCH_DEBOUNCE_MS, useTranslation } from "../../index.js";
+import { cn } from "../lib/cn.js";
+import { Badge } from "../ui/badge.js";
+import { Button as UiButton } from "../ui/button.js";
+export function FacetSearchFilter({ facet, onSearchChange, selected, onChange, dense, }) {
+    const t = useTranslation();
+    const [open, setOpen] = useState(false);
+    const [searchTerm, setSearchTerm] = useState("");
+    useEffect(() => {
+        const timer = setTimeout(() => onSearchChange(searchTerm), REFERENCE_SEARCH_DEBOUNCE_MS);
+        return () => clearTimeout(timer);
+    }, [searchTerm, onSearchChange]);
+    useEffect(() => {
+        if (!open && searchTerm !== "")
+            setSearchTerm("");
+    }, [open, searchTerm]);
+    const toggle = (value) => {
+        onChange(facet.field, selected.includes(value) ? selected.filter((v) => v !== value) : [...selected, value]);
+    };
+    return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Trigger, { asChild: true, children: _jsxs(UiButton, { variant: "outline", size: "sm", className: cn("h-9", dense && "border-border-strong px-2.5"), "data-testid": `facet-${facet.field}`, children: [facet.label, selected.length > 0 && (_jsx(Badge, { variant: "secondary", className: "ml-1 rounded-sm px-1 font-normal tabular-nums", children: selected.length })), _jsx(ChevronDown, { className: "text-muted-foreground" })] }) }), _jsx(PopoverPrimitive.Portal, { children: _jsx(PopoverPrimitive.Content, { align: "start", sideOffset: 4, className: "z-50 w-64 rounded-md border bg-popover p-0 text-popover-foreground shadow-md outline-none", children: _jsxs(Command, { shouldFilter: false, children: [_jsxs("div", { className: "relative", children: [_jsx(Command.Input, { value: searchTerm, onValueChange: setSearchTerm, placeholder: t("kumiko.combobox.search-placeholder"), "data-testid": `facet-${facet.field}-search`, className: "flex h-9 w-full border-0 border-b border-border bg-transparent px-3 py-1 text-sm outline-none placeholder:text-muted-foreground" }), facet.searching === true && (_jsx(Loader2, { className: "absolute right-2 top-2.5 h-4 w-4 animate-spin text-muted-foreground" }))] }), _jsxs(Command.List, { className: "max-h-64 overflow-y-auto p-1", children: [_jsx(Command.Empty, { className: "py-3 text-center text-sm text-muted-foreground", children: facet.searching === true
+                                            ? t("kumiko.combobox.loading")
+                                            : t("kumiko.combobox.empty") }), facet.options.map((opt) => (_jsxs(Command.Item, { value: opt.value, onSelect: () => toggle(opt.value), "data-testid": `facet-${facet.field}-${opt.value}`, className: "relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none aria-selected:bg-accent aria-selected:text-accent-foreground", children: [selected.includes(opt.value) && (_jsx("span", { className: "absolute left-2 flex h-3.5 w-3.5 items-center justify-center", children: _jsx(Check, { className: "h-4 w-4" }) })), opt.label] }, opt.value)))] })] }) }) })] }));
+}

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

@@ -78,10 +78,21 @@ export function createEventSourceLiveEvents(options = {}) {
     // addEventListener(entityName, ...) gate below only filters which frames
     // arrive at all, not which subscriber a given frame is for. Without this
     // filter, an `invoice` subscriber would also fire on every `user` frame.
-    const handleEvent = (raw) => {
+    // Frames without an aggregateType (channel-in-app:event:delivered) are named after their
+    // event type, so the frame name is the subscription key and the signal is synthesized.
+    const handleEvent = (raw, frameName) => {
         let parsed;
         try {
-            parsed = JSON.parse(raw);
+            const body = JSON.parse(raw);
+            const aggregateType = propertyOf(body, "aggregateType");
+            parsed =
+                typeof aggregateType === "string"
+                    ? body
+                    : {
+                        aggregateType: frameName,
+                        eventType: frameName,
+                        createdAt: Temporal.Instant.fromEpochMilliseconds(now()).toString(),
+                    };
         }
         catch {
             // skip: malformed SSE payload, drop it rather than crash all subscribers
@@ -109,7 +120,7 @@ export function createEventSourceLiveEvents(options = {}) {
         connection.addEventListener(entityName, (e) => {
             const data = propertyOf(e, "data");
             if (typeof data === "string")
-                handleEvent(data);
+                handleEvent(data, entityName);
         });
         wiredEntities.add(entityName);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.398.0",
+  "version": "0.399.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.398.0",
-    "@cosmicdrift/kumiko-types": "0.398.0",
+    "@cosmicdrift/kumiko-framework": "0.399.0",
+    "@cosmicdrift/kumiko-types": "0.399.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.398.0",
-    "@cosmicdrift/kumiko-testing": "0.398.0",
+    "@cosmicdrift/kumiko-locale-de": "0.399.0",
+    "@cosmicdrift/kumiko-testing": "0.399.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,22 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Notification bell in the shell header",
+    "detail": "With the channel-in-app feature in the schema and a signed-in user, ShellHeader renders a bell with an unread badge (99+ from 100) and a popover list with title, body, relative time, mark all read and load more. A click marks the entry read and opens its target screen when the schema has it. The delivered signal refetches the count and the open list; there is no polling. SSE frames without an aggregateType now reach subscribers keyed by the frame name. New keys `kumiko.notifications.*` in the default bundle and in all four locale packages."
+  },
+  {
+    "version": "0.399.0",
+    "type": "fix",
+    "title": "Tab description is rendered on groups tabs",
+    "detail": "The `description` of a section with tabbed groups was dropped; only fields and relatedList tabs showed it. The outer card of a groups tab now renders it as its subtitle, also when a relatedList tab has no rows."
+  },
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Searchable reference facets",
+    "detail": "A reference facet in entityList, projectionList and relatedList loads a page of options and a search field narrows them on the server (300 ms debounce), so values beyond the first page can be filtered by. Chosen values keep their label from a separate by-id request, also after a reload from the URL. A reference field with `optionsQuery` uses that handler for the facet. The 200-row warning is gone; `DataTableFacet` gets optional `onSearchChange` and `searching`."
+  },
   {
     "version": "0.398.0",
     "type": "fix",