@cosmicdrift/kumiko-renderer 0.396.0 → 0.398.0

package/dist/app/screen-shared.js

@@ -7,7 +7,7 @@ import { rendererWarn } from "../dev-console.js";
 import { applyFormatSpec } from "../headless/index.js";
 import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
 import { PAGE_SIZE_OPTIONS } from "../hooks/use-list-url-state.js";
-import { referenceLookupSource } from "../hooks/use-reference-lookup.js";
+import { referenceLookupSource, referenceRowsByIdsPayload } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
 import { ISO_DATE_PATTERN, isMoneyValue } from "./entity-edit-prefill.js";
@@ -139,14 +139,7 @@ export async function resolveSuccessMessageParams(screen, featureName, values, d
             return;
         const target = parseRefTarget(def.entity, featureName);
         const { queryQn, labelKey } = referenceLookupSource(target.featureName, target.entityName, def.labelField ?? "id");
-        // Ask for exactly the chosen record so it cannot fall beyond the lookup cap: `ids` is the
-        // by-id input of directory sources, `filters` that of entity list handlers. A source that
-        // knows neither returns its capped list and the scan below still finds the row if present.
-        const lookup = await dispatcher.query(queryQn, {
-            limit: REFERENCE_LIST_LOOKUP_LIMIT,
-            ids: [raw],
-            filters: [{ field: "id", op: "in", value: [raw] }],
-        });
+        const lookup = await dispatcher.query(queryQn, referenceRowsByIdsPayload([raw], REFERENCE_LIST_LOOKUP_LIMIT));
         if (!lookup.isSuccess)
             return;
         const row = lookup.data.rows.find((candidate) => candidate["id"] === raw);

package/dist/components/embedded-list-field.js

@@ -4,9 +4,18 @@ import { computeDerivedCellValue, currencyDecimals, groupEmbeddedListIssues, rou
 import { pluralKey } from "../headless/plural-key.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
+import { referenceOptionSource, storedReferenceRowsPayload, withUnlistedSelectedRows, } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
+function storedCellIds(rows, cellField) {
+    const ids = new Set();
+    for (const row of rows) {
+        const value = row[cellField];
+        if (typeof value === "string" && value !== "")
+            ids.add(value);
+    }
+    return [...ids].sort();
+}
 function withRecomputedDerived(row, derived, cells) {
     if (derived === undefined)
         return row;
@@ -124,6 +133,12 @@ function EmbeddedListFieldInner({ field, id, onChange, allIssues, featureName, }
     useQuery(source.queryQn, {
         limit: REFERENCE_COMBOBOX_LIMIT,
     }));
+    // The first options page can miss a stored value; without its row the cell shows no label.
+    const storedReferenceQueries = referenceCells.map((cell, idx) => {
+        const storedIds = storedCellIds(rows, cell.field);
+        // biome-ignore lint/correctness/useHookAtTopLevel: same fixed per-mount hook count as referenceQueries above.
+        return useQuery(referenceSources[idx]?.queryQn ?? "", storedReferenceRowsPayload(cell, storedIds, REFERENCE_COMBOBOX_LIMIT), { enabled: storedIds.length > 0 });
+    });
     if (EmbeddedListInput === undefined)
         return null;
     const columns = cells.map((cell) => {
@@ -132,7 +147,7 @@ function EmbeddedListFieldInner({ field, id, onChange, allIssues, featureName, }
             const idx = referenceCells.indexOf(cell);
             const query = referenceQueries[idx];
             const labelKey = referenceSources[idx]?.labelKey ?? "id";
-            const referenceOptions = (query?.data?.rows ?? []).map((row) => ({
+            const referenceOptions = withUnlistedSelectedRows(query?.data?.rows ?? [], storedReferenceQueries[idx]?.data?.rows ?? []).map((row) => ({
                 value: String(row["id"] ?? ""),
                 label: String(row[labelKey] ?? row["id"] ?? ""),
             }));

package/dist/components/render-field-reference.js

@@ -5,11 +5,11 @@ import { useReferenceLinkResolver } from "../app/reference-link.js";
 import { EMPTY_VALUE_PLACEHOLDER } from "../headless/index.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { isCompleteRowPage, referenceOptionSource } from "../hooks/use-reference-lookup.js";
+import { isCompleteRowPage, referenceOptionSource, referenceRowsByIdsPayload, storedReferenceRowsPayload, withUnlistedSelectedRows, } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
 import { ReferenceCreateDialog } from "./reference-create-dialog.js";
-import { stringArrayOf } from "./render-field-values.js";
+import { selectedReferenceIds, stringArrayOf } from "./render-field-values.js";
 import { useReferenceInputState } from "./use-reference-input-state.js";
 // ReferenceInput renders a searchable combobox populated by a live query for
 // the referenced entity. With the default limit of 200, larger datasets miss
@@ -64,19 +64,17 @@ export function ReadOnlyReferenceValue({ field, featureName, }) {
     const resolveReferenceLink = useReferenceLinkResolver();
     const refEntity = field.refEntity ?? "";
     const refFeature = field.refFeature ?? featureName;
-    const isMultiple = field.refMultiple === true;
     const { queryQn, labelKey } = referenceOptionSource(field, refFeature, refEntity);
-    const queryResult = useQuery(queryQn, {
-        limit: REFERENCE_COMBOBOX_LIMIT,
-    });
-    const ids = isMultiple
-        ? stringArrayOf(field.value)
-        : typeof field.value === "string" && field.value !== ""
-            ? [field.value]
-            : [];
+    const ids = selectedReferenceIds(field);
+    // An author `refOptionsQuery` keeps its capped picker page; a strict handler schema
+    // that rejects `ids` then only fails the extra stored-rows query.
+    const queryResult = useQuery(queryQn, field.refOptionsQuery === undefined
+        ? referenceRowsByIdsPayload(ids, REFERENCE_COMBOBOX_LIMIT)
+        : { limit: REFERENCE_COMBOBOX_LIMIT }, { enabled: ids.length > 0 });
+    const storedResult = useQuery(queryQn, storedReferenceRowsPayload(field, ids, REFERENCE_COMBOBOX_LIMIT), { enabled: field.refOptionsQuery !== undefined && ids.length > 0 });
     if (ids.length === 0)
         return _jsx(Text, { testId: `field-value-${field.field}`, children: EMPTY_VALUE_PLACEHOLDER });
-    const rows = queryResult.data?.rows ?? [];
+    const rows = withUnlistedSelectedRows(queryResult.data?.rows ?? [], storedResult.data?.rows ?? []);
     // System-scope ids (e.g. SYSTEM_TENANT_ID) never have a backing row —
     // same central fallback as useReferenceLookup (render-list.tsx), so a
     // reference field showing one on the detail path also gets a label

package/dist/components/render-field-values.d.ts

@@ -8,6 +8,10 @@ export declare function resolveNumberUnit(unit: string | {
 } | undefined, row: Readonly<Record<string, unknown>> | undefined): string | undefined;
 export declare function resolveAffix(affix: FieldAffix | undefined, row: Readonly<Record<string, unknown>> | undefined): string | undefined;
 export declare function stringArrayOf(value: unknown): readonly string[];
+export declare function selectedReferenceIds(field: {
+    readonly value: unknown;
+    readonly refMultiple?: boolean;
+}): readonly string[];
 export declare function withPinnedValues(next: readonly string[], options: readonly SelectOptionEntry[], current: readonly string[]): readonly string[];
 export declare function moneyMinorValue(v: unknown, currency: string): number | "";
 export declare function moneyPayload(minorUnits: number | undefined, currency: string): unknown;

package/dist/components/render-field-values.js

@@ -67,6 +67,13 @@ export function stringArrayOf(value) {
         ? value.filter((item) => typeof item === "string")
         : [];
 }
+// The ids a reference field currently points at: the array of a `refMultiple`
+// field, else the single non-empty id.
+export function selectedReferenceIds(field) {
+    if (field.refMultiple === true)
+        return stringArrayOf(field.value);
+    return typeof field.value === "string" && field.value !== "" ? [field.value] : [];
+}
 // The combobox cannot disable a single option, so removals of disabled options
 // the form already holds are merged back.
 export function withPinnedValues(next, options, current) {

package/dist/components/render-list-reference-bridge.d.ts

@@ -1,3 +1,4 @@
 import type { ReactNode } from "react";
-import type { PublishedReferenceLookup, ReferenceColumnSpec } from "./render-list-reference-columns.ts";
-export declare function renderReferenceLookupBridges(referenceColumns: readonly ReferenceColumnSpec[], onMap: (field: string, lookup: PublishedReferenceLookup) => void): ReactNode;
+import { type PublishedReferenceChunk, type ReferenceLookupRequest } from "./render-list-reference-columns.ts";
+export type ReferenceChunkPublisher = (field: string, chunkIndex: number, lookup: PublishedReferenceChunk) => void;
+export declare function renderReferenceLookupBridges(referenceRequests: readonly ReferenceLookupRequest[], onMap: ReferenceChunkPublisher): ReactNode;

package/dist/components/render-list-reference-bridge.js

@@ -1,12 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect } from "react";
 import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
+import { referenceChunkKey, } from "./render-list-reference-columns.js";
 // Bridge component for each reference column. It is mounted once per
 // column, calls useReferenceLookup unconditionally, and publishes the map
 // to the parent through onMap. React manages mounting and unmounting when
 // the schema changes through the key prop in the parent's map loop.
-function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMap, }) {
-    const lookup = useReferenceLookup(featureName, refEntity, labelField);
+function ReferenceLookupBridge({ field, chunkIndex, ids, refEntity, labelField, featureName, onMap, }) {
+    const lookup = useReferenceLookup(featureName, refEntity, labelField, ids);
     // Use an effect rather than calling directly so setState runs outside the
     // render path; otherwise React warns about updating one component while
     // rendering another.
@@ -14,12 +15,15 @@ function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMa
     // "not resolved", whereas an empty published map means "nothing found".
     // Only the latter may display "Unknown".
     const resolved = !lookup.loading && !lookup.failed;
+    const idsKey = referenceChunkKey(ids);
+    // The parent keys this bridge by its ids, so a changed id set remounts it and
+    // useQuery starts loading instead of handing back the previous ids' rows.
     useEffect(() => {
         if (resolved)
-            onMap(field, { map: lookup.map, complete: lookup.complete });
-    }, [field, lookup.map, lookup.complete, resolved, onMap]);
+            onMap(field, chunkIndex, { map: lookup.map, complete: lookup.complete, idsKey });
+    }, [field, chunkIndex, idsKey, lookup.map, lookup.complete, resolved, onMap]);
     return null;
 }
-export function renderReferenceLookupBridges(referenceColumns, onMap) {
-    return referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: onMap }, rc.field)));
+export function renderReferenceLookupBridges(referenceRequests, onMap) {
+    return referenceRequests.flatMap((request) => request.idChunks.map((ids, chunkIndex) => (_jsx(ReferenceLookupBridge, { field: request.field, chunkIndex: chunkIndex, ids: ids, refEntity: request.refEntity, labelField: request.labelField, featureName: request.refFeature, onMap: onMap }, `${request.field}:${referenceChunkKey(ids)}`))));
 }

package/dist/components/render-list-reference-columns.d.ts

@@ -4,6 +4,8 @@ import type { ReferenceLookupMap } from "../hooks/use-reference-lookup.ts";
 export type PublishedReferenceLookup = {
     readonly map: ReferenceLookupMap;
     readonly complete: boolean;
+    /** The map is from an earlier id set; the current ids are still loading. */
+    readonly pending?: true;
 };
 export type ReferenceColumnSpec = {
     readonly field: string;
@@ -11,6 +13,15 @@ export type ReferenceColumnSpec = {
     readonly refFeature: string;
     readonly labelField: string;
 };
+export type ReferenceLookupRequest = ReferenceColumnSpec & {
+    readonly idChunks: readonly (readonly string[])[];
+};
+export declare function referenceIdChunks(rows: readonly Readonly<Record<string, unknown>>[], field: string, chunkSize: number): string[][];
+export type PublishedReferenceChunk = PublishedReferenceLookup & {
+    readonly idsKey: string;
+};
+export declare function referenceChunkKey(ids: readonly string[]): string;
+export declare function mergeChunkLookups(idChunks: readonly (readonly string[])[], published: Readonly<Record<number, PublishedReferenceChunk>> | undefined): PublishedReferenceLookup | undefined;
 type ResolveReferenceLink = ReturnType<typeof useReferenceLinkResolver>;
 export declare function selectReferenceColumns(columns: readonly ListColumnViewModel[], featureName: string): ReferenceColumnSpec[];
 export type EnrichReferenceColumnsInput = {

package/dist/components/render-list-reference-columns.js

@@ -1,5 +1,47 @@
 import { UNRESOLVED_REFERENCE_LABEL_KEYS } from "@cosmicdrift/kumiko-framework/ui-types";
 import { EMPTY_VALUE_PLACEHOLDER } from "../headless/index.js";
+// Chunks in first-seen order, so appending an infinite-scroll page only
+// re-queries the last chunk; the chunk size stays within the list handler's limit.
+export function referenceIdChunks(rows, field, chunkSize) {
+    const ids = new Set();
+    for (const row of rows) {
+        const value = row[field];
+        for (const entry of Array.isArray(value) ? value : [value]) {
+            if (typeof entry === "string" && entry !== "")
+                ids.add(entry);
+        }
+    }
+    const ordered = [...ids];
+    const chunks = [];
+    for (let start = 0; start < ordered.length; start += chunkSize) {
+        chunks.push(ordered.slice(start, start + chunkSize));
+    }
+    return chunks;
+}
+export function referenceChunkKey(ids) {
+    return ids.join("\n");
+}
+// A chunk last resolved for other ids keeps its labels on screen, but it is
+// `pending` and cannot prove absence until the current ids have loaded.
+export function mergeChunkLookups(idChunks, published) {
+    const chunks = idChunks.map((ids, chunkIndex) => {
+        const chunk = published?.[chunkIndex];
+        return { chunk, current: chunk?.idsKey === referenceChunkKey(ids) };
+    });
+    const resolved = chunks.flatMap(({ chunk }) => (chunk === undefined ? [] : [chunk]));
+    if (resolved.length === 0)
+        return undefined;
+    const pending = !chunks.every(({ current }) => current);
+    const complete = !pending && resolved.every((chunk) => chunk.complete);
+    const only = resolved.length === 1 && chunks.length === 1 ? resolved[0] : undefined;
+    if (only !== undefined && !pending)
+        return only;
+    const map = new Map();
+    for (const chunk of resolved)
+        for (const [id, label] of chunk.map)
+            map.set(id, label);
+    return { map, complete, ...(pending && { pending }) };
+}
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -32,7 +74,7 @@ export function selectReferenceColumns(columns, featureName) {
 function unresolvedLabelFor(unknownKey, published, translate) {
     return (id) => unknownKey === undefined
         ? id
-        : published === undefined
+        : published === undefined || published.pending === true
             ? EMPTY_VALUE_PLACEHOLDER
             : published.complete
                 ? translate(unknownKey)

package/dist/components/render-list.js

@@ -24,7 +24,7 @@ export function RenderList(props) {
     const [menuActionBusyId, setMenuActionBusyId] = useState(null);
     const [menuActionError, setMenuActionError] = useState(null);
     const { localQ, setLocalQ } = useRenderListSearch(searchValue, onSearchChange);
-    const { referenceColumns, handleLookupMap, enrichedVm } = useRenderListColumns({
+    const { referenceRequests, handleLookupMap, enrichedVm } = useRenderListColumns({
         screen,
         entity,
         rows,
@@ -93,7 +93,7 @@ export function RenderList(props) {
     const toolbarTitle = resolveToolbarTitle(screen, translate);
     return (_jsxs(_Fragment, { children: [headerActions !== undefined &&
                 PageHeader !== undefined &&
-                renderPageHeader(PageHeader, headerActions, split.promotedInOverflowMenu, promotedMenuItems), menuActionError !== null && renderMenuActionError(Banner, menuActionError), renderReferenceLookupBridges(referenceColumns, handleLookupMap), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...tableChromeProps({
+                renderPageHeader(PageHeader, headerActions, split.promotedInOverflowMenu, promotedMenuItems), menuActionError !== null && renderMenuActionError(Banner, menuActionError), renderReferenceLookupBridges(referenceRequests, handleLookupMap), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...tableChromeProps({
                     onRowClick,
                     composedEmptyState,
                     toolbarStart,

package/dist/components/use-reference-input-state.js

@@ -5,8 +5,8 @@ import { useUserRoles } from "../context/user-roles-context.js";
 import { rendererError } from "../dev-console.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
-import { stringArrayOf } from "./render-field-values.js";
+import { referenceOptionSource, storedReferenceRowsPayload, withUnlistedSelectedRows, } from "../hooks/use-reference-lookup.js";
+import { selectedReferenceIds, stringArrayOf } from "./render-field-values.js";
 export function useReferenceInputState(field, featureName, onChange) {
     const refEntity = field.refEntity ?? "";
     const refFeature = field.refFeature ?? featureName;
@@ -41,6 +41,9 @@ export function useReferenceInputState(field, featureName, onChange) {
         ? { limit: REFERENCE_COMBOBOX_LIMIT }
         : { limit: REFERENCE_COMBOBOX_LIMIT, search: searchTerm }, [searchTerm]);
     const queryResult = useQuery(queryQn, queryPayload);
+    // The first page can miss the stored value; without its row the combobox shows no label.
+    const selectedIds = selectedReferenceIds(field);
+    const selectedResult = useQuery(queryQn, storedReferenceRowsPayload(field, selectedIds, REFERENCE_COMBOBOX_LIMIT), { enabled: selectedIds.length > 0 });
     const handleSearchChange = useCallback((q) => setSearchTerm(q), []);
     const createTarget = !field.readOnly && refCreateScreen !== undefined && refEntityDef !== undefined
         ? { screen: refCreateScreen, entity: refEntityDef }
@@ -63,13 +66,13 @@ export function useReferenceInputState(field, featureName, onChange) {
         }
     }, [isMultiple, field.value, onChange, queryResult.refetch]);
     const options = useMemo(() => {
-        const rows = queryResult.data?.rows ?? [];
+        const rows = withUnlistedSelectedRows(queryResult.data?.rows ?? [], selectedResult.data?.rows ?? []);
         return rows.map((row) => {
             const idVal = String(row["id"] ?? "");
             const label = String(row[labelKey] ?? idVal);
             return { value: idVal, label };
         });
-    }, [queryResult.data, labelKey]);
+    }, [queryResult.data, selectedResult.data, labelKey]);
     return {
         refFeature,
         isMultiple,

package/dist/components/use-render-list-columns.d.ts

@@ -1,7 +1,7 @@
 import type { EntityDefinition, EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import { type ScreenLinkResolver } from "../app/reference-link.ts";
 import type { ListColumnViewModel, ListViewModel, Translate } from "../headless/index.ts";
-import { type PublishedReferenceLookup } from "./render-list-reference-columns.ts";
+import { type PublishedReferenceChunk, type ReferenceLookupRequest } from "./render-list-reference-columns.ts";
 export declare function withScreenLinks(columns: readonly ListColumnViewModel[], screen: EntityListScreenDefinition, resolveScreenLink: ScreenLinkResolver): readonly ListColumnViewModel[];
 type RenderListColumnsInput = {
     readonly screen: EntityListScreenDefinition;
@@ -11,8 +11,8 @@ type RenderListColumnsInput = {
     readonly translate: Translate;
 };
 export declare function useRenderListColumns(input: RenderListColumnsInput): {
-    referenceColumns: import("./render-list-reference-columns.ts").ReferenceColumnSpec[];
-    handleLookupMap: (field: string, lookup: PublishedReferenceLookup) => void;
+    referenceRequests: readonly ReferenceLookupRequest[];
+    handleLookupMap: (field: string, chunkIndex: number, lookup: PublishedReferenceChunk) => void;
     enrichedVm: Omit<ListViewModel, "columns"> & {
         columns: readonly ListColumnViewModel[];
     };

package/dist/components/use-render-list-columns.js

@@ -2,7 +2,8 @@ import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
 import { useCallback, useMemo, useState } from "react";
 import { useReferenceLinkResolver, useScreenLinkResolver, } from "../app/reference-link.js";
 import { computeListViewModel } from "../headless/index.js";
-import { enrichReferenceColumns, selectReferenceColumns, } from "./render-list-reference-columns.js";
+import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
+import { enrichReferenceColumns, mergeChunkLookups, referenceIdChunks, selectReferenceColumns, } from "./render-list-reference-columns.js";
 // A column whose rows name their own target screen links each cell there.
 export function withScreenLinks(columns, screen, resolveScreenLink) {
     const linkFields = new Map();
@@ -37,18 +38,34 @@ export function useRenderListColumns(input) {
     // through onMap. Each bridge makes a constant number of hook calls (one),
     // and React manages its lifecycle when the schema changes via key.
     const referenceColumns = useMemo(() => selectReferenceColumns(vm.columns, featureName), [vm.columns, featureName]);
-    const [referenceLookups, setReferenceLookups] = useState({});
-    const handleLookupMap = useCallback((field, lookup) => {
-        setReferenceLookups((prev) => {
+    const referenceRequests = useMemo(() => referenceColumns.map((column) => ({
+        ...column,
+        idChunks: referenceIdChunks(rows, column.field, REFERENCE_LIST_LOOKUP_LIMIT),
+    })), [referenceColumns, rows]);
+    const [chunkLookups, setChunkLookups] = useState({});
+    const handleLookupMap = useCallback((field, chunkIndex, lookup) => {
+        setChunkLookups((prev) => {
             // Skip the update when the lookup is identical. Otherwise the bridge
             // would re-render and send the same map back until React entered
             // an infinite loop.
-            const current = prev[field];
-            if (current?.map === lookup.map && current.complete === lookup.complete)
+            const current = prev[field]?.[chunkIndex];
+            const unchanged = current?.map === lookup.map &&
+                current.complete === lookup.complete &&
+                current.idsKey === lookup.idsKey;
+            if (unchanged)
                 return prev;
-            return { ...prev, [field]: lookup };
+            return { ...prev, [field]: { ...prev[field], [chunkIndex]: lookup } };
         });
     }, []);
+    const referenceLookups = useMemo(() => {
+        const merged = {};
+        for (const request of referenceRequests) {
+            const lookup = mergeChunkLookups(request.idChunks, chunkLookups[request.field]);
+            if (lookup !== undefined)
+                merged[request.field] = lookup;
+        }
+        return merged;
+    }, [referenceRequests, chunkLookups]);
     const resolveReferenceLink = useReferenceLinkResolver();
     const resolveScreenLink = useScreenLinkResolver();
     const enrichedColumns = useMemo(() => withScreenLinks(enrichReferenceColumns({
@@ -72,5 +89,5 @@ export function useRenderListColumns(input) {
         ...vm,
         columns: enrichedColumns,
     }), [vm, enrichedColumns]);
-    return { referenceColumns, handleLookupMap, enrichedVm };
+    return { referenceRequests, handleLookupMap, enrichedVm };
 }

package/dist/hooks/use-reference-lookup.d.ts

@@ -13,18 +13,27 @@ export declare function referenceOptionSource(field: {
     readonly queryQn: string;
     readonly labelKey: string;
 };
+export declare function referenceRowsByIdsPayload(ids: readonly string[], capLimit: number): Record<string, unknown>;
+type ReferenceRow = Readonly<Record<string, unknown>>;
+export declare function withUnlistedSelectedRows(listedRows: readonly ReferenceRow[], selectedRows: readonly ReferenceRow[]): readonly ReferenceRow[];
+export declare function storedReferenceRowsPayload(field: {
+    readonly refOptionsQuery?: string;
+}, ids: readonly string[], capLimit: number): Record<string, unknown>;
 export declare function isCompleteRowPage(data: {
     readonly nextCursor?: string | null;
 } | null): boolean;
-/** `map` holds the resolved labels; while the query loads or has failed an id is
+/** Without `ids` the lookup reads the first capped page, as an option source does;
+ *  with `ids` it asks for exactly those rows.
+ *  `map` holds the resolved labels; while the query loads or has failed an id is
  *  simply not in it. Callers decide the fallback: the raw id, or the "Unknown"
  *  label for entities listed in `UNRESOLVED_REFERENCE_LABEL_KEYS` once the
  *  lookup is complete.
  *  `featureName` is the reference's target feature, not the screen's. */
-export declare function useReferenceLookup(featureName: string, refEntity: string, labelField: string): {
+export declare function useReferenceLookup(featureName: string, refEntity: string, labelField: string, ids?: readonly string[]): {
     readonly map: ReferenceLookupMap;
     readonly loading: boolean;
     readonly failed: boolean;
     /** False when the lookup page was capped: absent ids may still exist. */
     readonly complete: boolean;
 };
+export {};

package/dist/hooks/use-reference-lookup.js

@@ -1,21 +1,16 @@
 // Renderer-side eager load for reference fields.
 //
 // Each reference column of a list calls `<feature>:query:
-// <refEntity>:list` (limit:200) once, builds a Map<uuid, displayValue>,
-// and the renderer uses it as the cell display renderer.
+// <refEntity>:list` for the ids on screen (in chunks of 200), builds a
+// Map<uuid, displayValue>, and the renderer uses it as the cell display renderer.
 //
 // Strategy trade-offs:
 //   - Server-side Drizzle joins would be more efficient (one query instead
 //     of N+1) but would have to extend the executor API with lookupTables.
 //     The renderer-side path wins for the MVP.
-//   - limit:200 is a hard UX limit: with more entries in the referenced
-//     entity, the last rows fall back to the raw id (or "Unknown" for
-//     opt-in entities once the lookup is complete). A searchable combobox plus a
-//     server-side eager load with an ID whitelist will lift that later.
-//
-// The hook is call-stable: useQuery's internal cache shares the lookup map
-// between list and edit form for the same entity, and live updates arrive
-// via SSE (use-query-live).
+//   - A source that ignores both by-id inputs still answers its first 200 rows,
+//     so later ids fall back to the raw id (or "Unknown" for opt-in entities
+//     once the lookup is complete).
 import { REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "@cosmicdrift/kumiko-framework/ui-types";
 import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-types/kms-adapter-types";
 import { useMemo } from "react";
@@ -45,21 +40,48 @@ export function referenceOptionSource(field, refFeature, refEntity) {
     }
     return referenceLookupSource(refFeature, refEntity, field.refLabelField ?? "id");
 }
+// Asks a label source for exactly these rows, so a stored id cannot fall beyond a
+// lookup cap: `ids` is the by-id input of directory sources, `filters` that of entity
+// list handlers. Both only narrow the caller's own read scope. A hand-written handler
+// that knows neither still answers its first `capLimit` rows, as before.
+export function referenceRowsByIdsPayload(ids, capLimit) {
+    return {
+        limit: Math.max(ids.length, capLimit),
+        ids,
+        filters: [{ field: "id", op: "in", value: ids }],
+    };
+}
+// Option rows of a picker plus the stored ones its first page did not carry, so a
+// stored value keeps its label without dropping the picker's own order.
+export function withUnlistedSelectedRows(listedRows, selectedRows) {
+    const listedIds = new Set(listedRows.map((row) => String(row["id"] ?? "")));
+    const unlisted = selectedRows.filter((row) => !listedIds.has(String(row["id"] ?? "")));
+    return unlisted.length === 0 ? listedRows : [...listedRows, ...unlisted];
+}
+// An author `refOptionsQuery` takes `{ limit, search? }` for its picker page and `ids`
+// for stored values; it knows no list filters.
+export function storedReferenceRowsPayload(field, ids, capLimit) {
+    return field.refOptionsQuery === undefined
+        ? referenceRowsByIdsPayload(ids, capLimit)
+        : { limit: Math.max(ids.length, capLimit), ids };
+}
 // A page with a continuation cursor is only a prefix of the referenced rows,
 // so a missing id in it proves nothing about the row's existence.
 export function isCompleteRowPage(data) {
     return data !== null && (data.nextCursor ?? null) === null;
 }
-/** `map` holds the resolved labels; while the query loads or has failed an id is
+/** Without `ids` the lookup reads the first capped page, as an option source does;
+ *  with `ids` it asks for exactly those rows.
+ *  `map` holds the resolved labels; while the query loads or has failed an id is
  *  simply not in it. Callers decide the fallback: the raw id, or the "Unknown"
  *  label for entities listed in `UNRESOLVED_REFERENCE_LABEL_KEYS` once the
  *  lookup is complete.
  *  `featureName` is the reference's target feature, not the screen's. */
-export function useReferenceLookup(featureName, refEntity, labelField) {
+export function useReferenceLookup(featureName, refEntity, labelField, ids) {
     const { queryQn, labelKey } = referenceLookupSource(featureName, refEntity, labelField);
-    const result = useQuery(queryQn, {
-        limit: REFERENCE_LIST_LOOKUP_LIMIT,
-    });
+    const result = useQuery(queryQn, ids === undefined
+        ? { limit: REFERENCE_LIST_LOOKUP_LIMIT }
+        : referenceRowsByIdsPayload(ids, REFERENCE_LIST_LOOKUP_LIMIT), { enabled: ids === undefined || ids.length > 0 });
     const translate = useTranslation();
     const systemLabel = SYSTEM_REFERENCE_LABELS[`${featureName}:${refEntity}`];
     const map = useMemo(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.396.0",
+  "version": "0.398.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.396.0",
-    "@cosmicdrift/kumiko-types": "0.396.0",
+    "@cosmicdrift/kumiko-framework": "0.398.0",
+    "@cosmicdrift/kumiko-types": "0.398.0",
     "@types/qrcode": "^1.5.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -67,8 +67,8 @@
     "zod": "^4.6.7"
   },
   "peerDependencies": {
-    "@tailwindcss/cli": "^4.3.0",
-    "tailwindcss": "^4.3.0"
+    "@tailwindcss/cli": "^4.3.3",
+    "tailwindcss": "^4.3.3"
   },
   "peerDependenciesMeta": {
     "@tailwindcss/cli": {
@@ -79,15 +79,15 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-locale-de": "0.396.0",
-    "@cosmicdrift/kumiko-testing": "0.396.0",
-    "@tailwindcss/cli": "^4.3.0",
-    "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.1",
+    "@cosmicdrift/kumiko-locale-de": "0.398.0",
+    "@cosmicdrift/kumiko-testing": "0.398.0",
+    "@tailwindcss/cli": "^4.3.3",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
-    "tailwindcss": "^4.3.0"
+    "tailwindcss": "^4.3.3"
   },
   "repository": {
     "type": "git",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.398.0",
+    "type": "fix",
+    "title": "Reference labels resolve by id beyond the lookup caps",
+    "detail": "ReadOnlyReferenceValue, the reference combobox and embedded-list reference cells request the stored ids next to their first options page; list reference columns request the ids on screen in chunks of 200 instead of the first 200 rows of the target. The ids go out as `ids` for directory sources and an id-in filter for entity list handlers, which only narrow the caller's list query, so tenant, ownership and field-read rules keep applying. Author `optionsQuery` handlers on reference fields keep their capped `{ limit, search? }` picker page and are additionally asked for stored values with `{ limit, ids }`; a handler that ignores `ids` keeps the previous capped behaviour. List columns keep labels already known while the ids of a new page load and only claim \"Unknown\" once the current ids have resolved."
+  },
   {
     "version": "0.395.0",
     "type": "improvement",