@cosmicdrift/kumiko-renderer 0.398.0 → 0.400.0

package/dist/app/entity-edit-prefill.js

@@ -14,6 +14,12 @@ export function versionOf(record) {
     const version = record["version"];
     return typeof version === "number" ? version : 1;
 }
+// An untouched amount carries only its currency (the input needs it for display), so a typed 0
+// stays distinguishable from the seed; required-ness is enforced on the typed amount, and the
+// submit drops a currency-only value.
+function moneySeed(currency) {
+    return { currency };
+}
 export function buildInitialValues(fields, defaultCurrency, moneyCurrencyOverrides) {
     const out = {};
     for (const [name, def] of Object.entries(fields)) {
@@ -35,7 +41,7 @@ export function buildInitialValues(fields, defaultCurrency, moneyCurrencyOverrid
         if (type === "money") {
             const currency = moneyCurrencyOverrides?.[name] ?? defaultCurrency;
             if (currency !== undefined) {
-                out[name] = { amount: 0, currency };
+                out[name] = moneySeed(currency);
                 continue;
             }
         }

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/form-schema.js

@@ -1,4 +1,4 @@
-import { evalFieldCondition, findUnavailableSelectOptions, isUnchangedValue, NO_WIDGET_FIELD_TYPES, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { evalFieldCondition, findMissingConditionalRequirements, findUnavailableSelectOptions, isFieldRequired, isUnchangedValue, NO_WIDGET_FIELD_TYPES, } from "@cosmicdrift/kumiko-framework/ui-types";
 import * as z from "zod";
 import { I18N_KEY_PARAM } from "../headless/index.js";
 import { layoutEditFields } from "./layout-fields.js";
@@ -9,6 +9,9 @@ export function isPresent(value) {
         return false;
     if (Array.isArray(value) && value.length === 0)
         return false;
+    // A money field seeded with its currency only has no amount yet.
+    if (typeof value === "object" && "currency" in value && !("amount" in value))
+        return false;
     return true;
 }
 function isEmbeddedListField(field) {
@@ -21,8 +24,9 @@ function isRequiredValueMissing(spec, field, record, unchangedFrom) {
     // Screen-spec `required` overrides the entity default, mirroring
     // `view-model/edit.ts` — the rendered form is the reference, and a
     // presence check stricter than the form blocks the user for nothing.
-    const entityRequired = "required" in field && field.required === true;
-    const isRequired = spec.required === undefined ? entityRequired : evalFieldCondition(spec.required, record);
+    const isRequired = spec.required === undefined
+        ? isFieldRequired(field, record)
+        : evalFieldCondition(spec.required, record);
     if (!isRequired)
         return false;
     // Embedded LIST fields get their own EmbeddedListField grid widget
@@ -36,6 +40,39 @@ function isRequiredValueMissing(spec, field, record, unchangedFrom) {
         return false;
     return !(unchangedFrom !== undefined && isUnchangedValue(record[spec.field], unchangedFrom[spec.field]));
 }
+// Embedded sub-field `requiredWhen` (e.g. checkpoints.0.finding) — the top-level
+// conditions are already covered by isRequiredValueMissing.
+function addEmbeddedRequirementIssues(ctx, entity, record, unchangedFrom, checkedFields) {
+    for (const path of findMissingConditionalRequirements(entity.fields, record, unchangedFrom)) {
+        const segments = path.split(".");
+        const root = segments[0];
+        if (segments.length < 2 || root === undefined || !Object.hasOwn(checkedFields, root)) {
+            continue;
+        }
+        ctx.addIssue({
+            code: "custom",
+            path: segments.map((segment) => (/^\d+$/.test(segment) ? Number(segment) : segment)),
+            message: `"${path}" is required.`,
+            params: { [I18N_KEY_PARAM]: REQUIRED_FIELD_I18N_KEY },
+        });
+    }
+}
+function addUnavailableOptionIssues(ctx, record, unchangedFrom, lockedSelectFields, selectFieldsToCheck) {
+    // Against `unchangedFrom` the helper still checks a stored value whose
+    // discriminator changed — the server validates the merged row.
+    for (const issue of findUnavailableSelectOptions({ ...lockedSelectFields, ...selectFieldsToCheck }, record, unchangedFrom)) {
+        const lockedDef = lockedSelectFields[issue.field];
+        const blamedField = lockedDef !== undefined && lockedDef.type === "select"
+            ? (lockedDef.conditionalOptions?.find((rule) => rule.options.includes(issue.value) && !evalFieldCondition(rule.when, record))?.when.field ?? issue.field)
+            : issue.field;
+        ctx.addIssue({
+            code: "custom",
+            path: [blamedField],
+            message: `"${blamedField}" is not available for the current selection.`,
+            params: { [I18N_KEY_PARAM]: OPTION_NOT_AVAILABLE_I18N_KEY, allowed: issue.allowed },
+        });
+    }
+}
 // Client-side presence validation for the auto-wired entityEdit path —
 // checks that every rendered required field HAS a value, not that the
 // value has the right shape. Format/range/type validation stays server-
@@ -107,19 +144,7 @@ export function buildFormSchema(entity, screen, verb, unchangedFrom) {
                 params: { [I18N_KEY_PARAM]: REQUIRED_FIELD_I18N_KEY },
             });
         }
-        // Against `unchangedFrom` the helper still checks a stored value whose
-        // discriminator changed — the server validates the merged row.
-        for (const issue of findUnavailableSelectOptions({ ...lockedSelectFields, ...selectFieldsToCheck }, record, unchangedFrom)) {
-            const lockedDef = lockedSelectFields[issue.field];
-            const blamedField = lockedDef !== undefined && lockedDef.type === "select"
-                ? (lockedDef.conditionalOptions?.find((rule) => rule.options.includes(issue.value) && !evalFieldCondition(rule.when, record))?.when.field ?? issue.field)
-                : issue.field;
-            ctx.addIssue({
-                code: "custom",
-                path: [blamedField],
-                message: `"${blamedField}" is not available for the current selection.`,
-                params: { [I18N_KEY_PARAM]: OPTION_NOT_AVAILABLE_I18N_KEY, allowed: issue.allowed },
-            });
-        }
+        addEmbeddedRequirementIssues(ctx, entity, record, unchangedFrom, selectFieldsToCheck);
+        addUnavailableOptionIssues(ctx, record, unchangedFrom, lockedSelectFields, selectFieldsToCheck);
     });
 }

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-detail-body.js

@@ -19,6 +19,7 @@ import { useReturnHost, useReturnTarget } from "./return-to.js";
 import { useProjectionDetailActions } from "./use-projection-detail-actions.js";
 import { useProjectionDetailData } from "./use-projection-detail-data.js";
 import { useProjectionDetailLayout } from "./use-projection-detail-layout.js";
+import { useRelatedListTabCounts } from "./use-related-list-tab-counts.js";
 // Projection detail body: read-only single-row inspector over an explicit
 // query instead of an entity (see projection-detail-shim.ts for the debt
 // doc). Fetches itself via `screen.query` + `idParam` (like
@@ -75,6 +76,11 @@ export function ProjectionDetailBody({ schema, screen, translate, entityId, }) {
         reloadDetail,
     });
     const { hasMetrics, headerActionsList, hasHeaderActions, hasHeaderCard, renderedDetailScreen } = useProjectionDetailLayout({ screen, headerActions, hasTabs, detailScreen });
+    const recordId = detailQuery.data?.["id"];
+    const tabCounts = useRelatedListTabCounts({
+        sections: hasTabs ? screen.layout.sections : [],
+        parentId: effectiveEntityId ?? (typeof recordId === "string" ? recordId : undefined),
+    });
     if (effectiveEntityId === undefined && screen.singleton !== true) {
         return renderMissingIdBanner(primitives, screen);
     }
@@ -110,6 +116,7 @@ export function ProjectionDetailBody({ schema, screen, translate, entityId, }) {
         hasMetrics,
         hasHeaderCard,
         hasTabs,
+        tabCounts,
         activeSection,
     };
     const regionPieces = deriveDetailRegionPieces(regionModel);

package/dist/app/projection-detail-header-model.d.ts

@@ -9,4 +9,4 @@ export type DetailTabItem = {
     readonly label: string;
     readonly count?: number;
 };
-export declare function buildDetailTabItems(sections: ProjectionDetailScreenDefinition["layout"]["sections"], record: Readonly<Record<string, unknown>>, translate: Translate): DetailTabItem[];
+export declare function buildDetailTabItems(sections: ProjectionDetailScreenDefinition["layout"]["sections"], record: Readonly<Record<string, unknown>>, translate: Translate, queryCounts?: Readonly<Record<string, number>>): DetailTabItem[];

package/dist/app/projection-detail-header-model.js

@@ -50,10 +50,10 @@ export function resolveSubtitleHref(header, record) {
     const value = record[header.subtitleHref];
     return typeof value === "string" && isAbsoluteHttpUrl(value) ? value : undefined;
 }
-export function buildDetailTabItems(sections, record, translate) {
+export function buildDetailTabItems(sections, record, translate, queryCounts = {}) {
     return sections.map((section) => {
         const countField = isWriteFormEditSection(section) ? undefined : section.countField;
-        const countValue = countField !== undefined ? record[countField] : undefined;
+        const countValue = countField !== undefined ? record[countField] : queryCounts[section.id ?? ""];
         const count = typeof countValue === "number" && Number.isFinite(countValue) ? countValue : undefined;
         return {
             id: section.id ?? "",

package/dist/app/projection-detail-header-region.d.ts

@@ -10,6 +10,7 @@ export type DetailRegionModel = DetailHeaderModel & {
     readonly hasMetrics: boolean;
     readonly hasHeaderCard: boolean;
     readonly hasTabs: boolean;
+    readonly tabCounts: Readonly<Record<string, number>>;
     readonly activeSection: ProjectionDetailScreenDefinition["layout"]["sections"][number] | undefined;
 };
 export type DetailRegionPieces = {

package/dist/app/projection-detail-header-region.js

@@ -68,7 +68,7 @@ function renderHeaderCardBranch(model, pieces, headerSlot) {
 }
 function renderDetailTabs(model, activeSection, Tabs) {
     const { screen, record, effectiveTranslate, nav } = model;
-    return (_jsx(Tabs, { testId: "kumiko-screen-projection-detail-tabs", items: buildDetailTabItems(screen.layout.sections, record, effectiveTranslate), activeId: activeSection.id ?? "", onSelect: (id) => requestLeave(() => nav.setSearchParams({ tab: id })) }));
+    return (_jsx(Tabs, { testId: "kumiko-screen-projection-detail-tabs", items: buildDetailTabItems(screen.layout.sections, record, effectiveTranslate, model.tabCounts), activeId: activeSection.id ?? "", onSelect: (id) => requestLeave(() => nav.setSearchParams({ tab: id })) }));
 }
 export function renderDetailHeaderContent(model, pieces, headerSlot) {
     const { hasTabs, activeSection } = model;

package/dist/app/projection-detail-header.js

@@ -3,7 +3,7 @@ import { Fragment } from "react";
 import { ErrorReference } from "./error-reference.js";
 import { HeaderActionsBar } from "./header-actions-bar.js";
 import { headerStatusTone, resolveHeaderStatusText, resolveSubtitleHref, } from "./projection-detail-header-model.js";
-import { buildSubtitleParts, runMetricNavigate } from "./projection-detail-navigation.js";
+import { buildSubtitleParts, metricNavigateResolves, runMetricNavigate, } from "./projection-detail-navigation.js";
 import { navigateTargetAllows } from "./screen-access.js";
 export function renderHeaderActionsContent(model) {
     const { screen, primitives, headerActionsList, setActionError } = model;
@@ -58,7 +58,9 @@ export function buildMetricItems(model) {
         const tone = rawValue === 0 ? undefined : metric.tone;
         const testId = `kumiko-screen-projection-detail-metric-${field}`;
         const navigate = metric.navigate;
-        const onPress = navigate !== undefined && navigateTargetAllows(navigate, appFeatures, userRoles)
+        const onPress = navigate !== undefined &&
+            metricNavigateResolves(navigate, record) &&
+            navigateTargetAllows(navigate, appFeatures, userRoles)
             ? () => runMetricNavigate(nav, navigate, record, host)
             : undefined;
         return Metric !== undefined ? (_jsx(Metric, { label: label, value: value, testId: testId, ...(onPress !== undefined && { onPress }), ...(tiles && { tile: true }), ...(tone !== undefined && { tone }), ...(metric.icon !== undefined && { icon: metric.icon }) }, field)) : (_jsxs(GridCell, { children: [_jsx(Text, { variant: "small", testId: `${testId}-label`, children: label }), _jsx(Text, { testId: `${testId}-value`, children: value })] }, field));

package/dist/app/projection-detail-navigation.d.ts

@@ -10,4 +10,5 @@ export type SubtitlePartView = {
     readonly href?: string;
     readonly onPress?: () => void;
 };
+export declare function metricNavigateResolves(navigate: MetricNavigate, record: Readonly<Record<string, unknown>>): boolean;
 export declare function buildSubtitleParts(parts: readonly RecordHeaderSubtitlePart[], record: Readonly<Record<string, unknown>>, nav: NavApi, appFeatures: readonly FeatureSchema[], userRoles: readonly string[] | undefined, host: ReturnHost | undefined): SubtitlePartView[];

package/dist/app/projection-detail-navigation.js

@@ -47,12 +47,20 @@ export function runMetricNavigate(nav, navigate, record, host) {
 export function isAbsoluteHttpUrl(value) {
     return /^https?:\/\//i.test(value) && isSafeHref(value);
 }
+function recordEntityId(navigate, record) {
+    return navigate.entityId !== undefined ? String(record[navigate.entityId] ?? "") : undefined;
+}
+// A metric whose declared entityId field is empty on this record has nowhere to go, so it must
+// not look clickable. Tab-only navigation always resolves.
+export function metricNavigateResolves(navigate, record) {
+    return recordEntityId(navigate, record) !== "";
+}
 // hrefFor throws for an entity without a detailFor screen; outside
 // createKumikoApp the feature list is empty, so navigateTargetAllows can't
 // rule that out beforehand. The NavApi owns target resolution, so asking it
 // and falling back to plain text covers both cases.
 function hrefForNavigate(nav, navigate, record) {
-    const entityId = navigate.entityId !== undefined ? String(record[navigate.entityId] ?? "") : undefined;
+    const entityId = recordEntityId(navigate, record);
     try {
         if (navigate.entity !== undefined) {
             return entityId === undefined || entityId === ""

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/app/use-related-list-tab-counts.d.ts

@@ -0,0 +1,5 @@
+import type { EditSectionSpec } from "@cosmicdrift/kumiko-framework/ui-types";
+export declare function useRelatedListTabCounts(args: {
+    readonly sections: readonly EditSectionSpec[];
+    readonly parentId: string | undefined;
+}): Readonly<Record<string, number>>;

package/dist/app/use-related-list-tab-counts.js

@@ -0,0 +1,68 @@
+import { useEffect, useMemo, useState } from "react";
+import { useOptionalDispatcher } from "../context/dispatcher-context.js";
+import { liveEntitiesForQuery, subscribeToEntities } from "../hooks/live-query-entities.js";
+import { createLiveRefetchScheduler } from "../hooks/live-refetch-scheduler.js";
+import { buildRelatedListParentPayload } from "../hooks/related-list-parent-payload.js";
+import { useLiveEvents } from "../sse/live-events.js";
+import { useAppFeatures } from "./app-features-context.js";
+// Tab badges come from each section's own query (`limit: 1, totalCount: true` → `total`), so
+// they match the tab's rows and refresh on the same live events.
+export function useRelatedListTabCounts(args) {
+    const { sections, parentId } = args;
+    const dispatcher = useOptionalDispatcher();
+    const features = useAppFeatures();
+    const subscribeLive = useLiveEvents();
+    const [counts, setCounts] = useState({});
+    const requests = useMemo(() => {
+        if (parentId === undefined)
+            return [];
+        const out = [];
+        for (const section of sections) {
+            if (section.kind !== "relatedList" || section.count !== true || section.id === undefined) {
+                continue;
+            }
+            out.push({
+                sectionId: section.id,
+                query: section.query,
+                payload: {
+                    ...buildRelatedListParentPayload(section, parentId),
+                    limit: 1,
+                    totalCount: true,
+                },
+            });
+        }
+        return out;
+    }, [sections, parentId]);
+    useEffect(() => {
+        // skip: nothing to count, or no dispatcher mounted
+        if (requests.length === 0 || dispatcher === undefined)
+            return;
+        const ctrl = new AbortController();
+        const load = async () => {
+            const results = await Promise.all(requests.map((request) => dispatcher.query(request.query, request.payload, {
+                signal: ctrl.signal,
+            })));
+            // skip: unmounted or superseded while the queries were in flight
+            if (ctrl.signal.aborted)
+                return;
+            const next = {};
+            results.forEach((result, index) => {
+                const total = result.isSuccess ? result.data?.total : undefined;
+                const request = requests[index];
+                if (request !== undefined && typeof total === "number")
+                    next[request.sectionId] = total;
+            });
+            setCounts(next);
+        };
+        void load();
+        const scheduler = createLiveRefetchScheduler(load);
+        const entities = [...new Set(requests.flatMap((r) => liveEntitiesForQuery(r.query, features)))];
+        const unsubscribe = subscribeToEntities(subscribeLive, entities, scheduler.trigger);
+        return () => {
+            ctrl.abort();
+            unsubscribe();
+            scheduler.dispose();
+        };
+    }, [requests, dispatcher, features, subscribeLive]);
+    return counts;
+}