@asteby/metacore-runtime-react 49.6.0 → 49.8.0

package/src/business/line-items.ts

@@ -3,6 +3,7 @@
 // guardado de renglones fallaba (PIT-018) por mandar al API cadenas vacías y
 // claves de UI; `serializeLineItems` es la única puerta de salida hacia el backend.
 import { roundMoney, toAmount } from './format'
+import type { ProductVariant } from './product-search'
 
 export type LineItemKind = 'item' | 'section' | 'note'
 
@@ -50,6 +51,36 @@ export interface LineItem {
      * del host) — el SDK no conoce sus claves.
      */
     extensions?: Record<string, string>
+    /**
+     * Valores que el catálogo escribió en el renglón la última vez que se
+     * aplicó el producto (elegirlo, crearlo o editarlo desde la celda). Un campo
+     * cuyo valor actual difiere de su foto es un override del usuario («dirty»)
+     * y una edición del producto no lo pisa. No se serializa.
+     */
+    catalog?: LineCatalogSnapshot
+    /**
+     * Valores nuevos del catálogo que NO se aplicaron porque el usuario ya
+     * había cambiado ese campo a mano: la celda ofrece «aplicar». No se serializa.
+     */
+    catalog_pending?: Partial<Pick<LineItem, CatalogLineField>>
+}
+
+/** Campos del renglón que salen del producto y el usuario puede sobrescribir. */
+export type CatalogLineField = 'description' | 'sku' | 'unit_price' | 'tax_rate' | 'unit'
+
+export const CATALOG_LINE_FIELDS: readonly CatalogLineField[] = ['description', 'sku', 'unit_price', 'tax_rate', 'unit']
+
+/** Foto de lo que el catálogo escribió en el renglón (por campo) y de qué producto/variante. */
+export interface LineCatalogSnapshot {
+    description?: string
+    sku?: string
+    unit_price?: number
+    tax_rate?: number
+    unit?: string
+    /** Id del producto del catálogo (el registro que se edita), aunque el renglón lleve una variante. */
+    product_ref?: string
+    /** Variante elegida: al refrescar se vuelve a aplicar la misma. */
+    variant?: ProductVariant
 }
 
 /** Qué hacer si `quantity > available`. */

package/src/business/line-product-cell.tsx

@@ -8,6 +8,10 @@
 // Teclado: ↑/↓ recorren, Enter elige (el grid pasa el foco a «Cant.»), Esc
 // cierra, Tab cierra y avanza normal. El texto escrito sin elegir queda como
 // descripción libre (el renglón libre sigue funcionando igual).
+//
+// Con `onCreate`, la celda ofrece crear el producto como las apps top: «+» unido
+// al buscador y «Crear producto «texto»» al pie de la lista, prellenado con lo
+// buscado. El grid llena el renglón con el producto nuevo al guardarlo.
 import { forwardRef, useState, type KeyboardEvent } from 'react'
 import { useTranslation } from 'react-i18next'
 import { RecordPicker } from '../record-picker'
@@ -47,10 +51,16 @@ export interface LineProductCellProps {
     className?: string
     /** Atributos de datos para que el grid ubique la celda (foco por teclado). */
     dataCell?: string
+    /** Alta del producto desde la celda, prellenada con lo buscado. */
+    onCreate?: (query: string) => void
+    /** Nombre del modelo para «Crear …» (default «producto»). */
+    entityLabel?: string
+    /** Detalle de qué se puede buscar: tooltip del buscador y estado sin coincidencias. */
+    hint?: string
 }
 
 export const LineProductCell = forwardRef<HTMLInputElement, LineProductCellProps>(function LineProductCell(
-    { search, text, onTextChange, onPick, onKeyDownClosed, warehouseId, currency, placeholder, ariaLabel, disabled, invalid, className, dataCell },
+    { search, text, onTextChange, onPick, onKeyDownClosed, warehouseId, currency, placeholder, ariaLabel, disabled, invalid, className, dataCell, onCreate, entityLabel, hint },
     ref,
 ) {
     const { t } = useTranslation()
@@ -58,6 +68,8 @@ export const LineProductCell = forwardRef<HTMLInputElement, LineProductCellProps
     // capturado no despliega «sin resultados» encima de la tabla.
     const [typing, setTyping] = useState(false)
     const { hits, loading, minChars } = useProductSearch(typing ? text : '', search, typing)
+    const entity = entityLabel ?? t('lineItems.productEntity', { defaultValue: 'producto' })
+    const searchHint = hint ?? t('lineItems.searchHint', { defaultValue: 'Busca por nombre, SKU o código de barras' })
 
     return (
         <RecordPicker<ProductHit>
@@ -66,7 +78,8 @@ export const LineProductCell = forwardRef<HTMLInputElement, LineProductCellProps
             freeText
             anchorSlot="line-product-cell"
             contentSlot="line-product-results"
-            minListWidth="22rem"
+            minListWidth="26.25rem"
+            maxListWidth="35rem"
             items={hits}
             loading={loading}
             minChars={minChars}
@@ -85,10 +98,24 @@ export const LineProductCell = forwardRef<HTMLInputElement, LineProductCellProps
             disabled={disabled}
             invalid={invalid}
             triggerClassName={className}
-            triggerProps={{ 'data-cell': dataCell }}
-            placeholder={placeholder ?? t('lineItems.searchPlaceholder', { defaultValue: 'Producto, medida (205/55R16), SKU o código de barras' })}
+            triggerProps={{ 'data-cell': dataCell, title: searchHint }}
+            placeholder={placeholder ?? t('lineItems.searchPlaceholderShort', { defaultValue: 'Buscar producto…' })}
             loadingText={t('common.searching', { defaultValue: 'Buscando…' })}
-            emptyText={t('lineItems.noProduct', { defaultValue: 'Sin coincidencias. Se usará como descripción libre.' })}
+            emptyText={
+                <span className="block space-y-1">
+                    <span className="block">{t('lineItems.noProduct', { defaultValue: 'Sin coincidencias. Se usará como descripción libre.' })}</span>
+                    <span className="block text-xs">{searchHint}</span>
+                </span>
+            }
+            onCreate={onCreate}
+            entityLabel={entity}
+            createLabel={t('lineItems.createProduct', { defaultValue: 'Crear {{entity}}', entity })}
+            createFooterLabel={(q) => (
+                <>
+                    {t('lineItems.createProduct', { defaultValue: 'Crear {{entity}}', entity })}
+                    {q ? <span className="text-muted-foreground"> «{q}»</span> : null}
+                </>
+            )}
         />
     )
 })

package/src/business/product-options.tsx

@@ -108,7 +108,7 @@ export function ProductHitRow({ hit, warehouseId, currency, compact }: { hit: Pr
     return (
         <span className="flex w-full min-w-0 items-center justify-between gap-3">
             <span className="min-w-0">
-                <span className="block truncate font-medium">{productHitLabel(hit)}</span>
+                <span className="line-clamp-2 break-words font-medium" title={productHitLabel(hit)}>{productHitLabel(hit)}</span>
                 {meta && <span className="block truncate text-xs text-muted-foreground">{meta}</span>}
             </span>
             <span className="flex shrink-0 items-center gap-2">

package/src/dialogs/dynamic-record.tsx

@@ -1334,7 +1334,7 @@ function FieldRow({ field, record, value, mode, onChange, error, locked }: Field
 
     return (
         <div className="flex flex-col gap-1.5" data-aby-field={field.key}>
-            <Label className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+            <Label className="text-sm font-medium text-foreground/80">
                 {localizeFieldLabel(field.label, t)}
                 {field.required && mode !== 'view' && !isEditReadonly && (
                     <span className="text-destructive ml-0.5">*</span>

package/src/dynamic-multi-select-field.tsx

@@ -17,11 +17,17 @@
 // (segments, tags, categories — tens, not thousands of rows); a field with a
 // genuinely large option set should keep using a single dynamic_select per
 // value instead.
+//
+// Selected ids outside that page (or hidden by an option_filter) are labelled
+// with ONE `?ids=` lookup (useResolveOptionIds): a chip reads "Cargando…" while
+// it resolves and "(registro eliminado)" when the record is gone — never the id.
 import { useMemo, useState } from 'react'
 import { getOptionFilter } from './option-filter'
 import { RecordPicker } from './record-picker'
 import { OptionLead } from './record-picker-option'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
+import { useResolveOptionIds } from './use-option-ids'
+import { DELETED_RECORD_LABEL } from './dynamic-select-field'
 import { getFieldRef } from './dynamic-form-schema'
 import type { ActionFieldDef } from './types'
 
@@ -35,7 +41,7 @@ export interface DynamicMultiSelectFieldProps {
 export function DynamicMultiSelectField({ field, value, onChange }: DynamicMultiSelectFieldProps) {
     const ref = getFieldRef(field)
     const [query, setQuery] = useState('')
-    const { options, loading } = useOptionsResolver({
+    const { options, loading, meta, error } = useOptionsResolver({
         modelKey: '',
         fieldKey: 'id',
         ref,
@@ -45,13 +51,19 @@ export function DynamicMultiSelectField({ field, value, onChange }: DynamicMulti
     })
 
     const selected = useMemo(() => (Array.isArray(value) ? value.map(String) : []), [value])
-    const selectedItems = useMemo(
-        () =>
-            selected
-                .map((id) => options.find((o) => String(o.id) === id))
-                .filter((o): o is ResolvedOption => !!o),
-        [selected, options],
-    )
+    const endpoint = !ref && field.searchEndpoint ? field.searchEndpoint : undefined
+    // Ask for the ids the loaded page does not cover — only once it is in.
+    const pageSettled = !loading && (meta !== null || error !== null)
+    const unresolved = pageSettled ? selected.filter((id) => !options.some((o) => String(o.id) === id)) : []
+    const { resolved } = useResolveOptionIds({ ref, endpoint, field: 'id', ids: unresolved, enabled: unresolved.length > 0 })
+    const selectedItems = selected.map((id): ResolvedOption => {
+        const loaded = options.find((o) => String(o.id) === id)
+        if (loaded) return loaded
+        const r = pageSettled ? resolved.get(id) : undefined
+        if (r?.status === 'found') return r.option
+        const label = !r ? 'Cargando…' : r.status === 'missing' ? DELETED_RECORD_LABEL : id
+        return { id, value: id, label, name: label }
+    })
     const shown = useMemo(() => {
         const q = query.trim().toLowerCase()
         return q ? options.filter((o) => String(o.label ?? '').toLowerCase().includes(q)) : options

package/src/dynamic-select-field.tsx

@@ -18,10 +18,11 @@
 //   1. field.ref          → /options/<ref>?field=id        (canonical, preferred)
 //   2. field.searchEndpoint→ used verbatim as the options endpoint (escape hatch)
 //
-// Edit-mode caveat: resolving an EXISTING value's label requires the id to be
-// in a fetched page (we match by id against loaded options, else show the raw
-// value). A dedicated `?ids=` lookup is a follow-up; create flows — the common
-// case — start empty and never hit this.
+// Edit mode: an EXISTING value is labelled from (in order) the option the user
+// just picked, the loaded page, the caller's `seedOption`, and otherwise one
+// `?ids=` lookup (useResolveOptionIds — batched and shared with every picker of
+// the same ref on screen). While it resolves the trigger reads "Cargando…",
+// never the raw id; an id that no longer exists reads "(registro eliminado)".
 import { useEffect, useRef, useState } from 'react'
 import { getOptionFilter } from './option-filter'
 import { useTranslation } from 'react-i18next'
@@ -32,6 +33,7 @@ import { RecordPicker } from './record-picker'
 import { OptionLead } from './record-picker-option'
 import { recordLabel, requestRecordCreate, requestRecordEdit, withSearchPrefill } from './record-picker-actions'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
+import { useResolveOptionIds } from './use-option-ids'
 import { useDebouncedValue } from './use-debounced-value'
 import { getDependsOn, getFieldRef, resolveOptionsSource } from './dynamic-form-schema'
 import type { ActionFieldDef } from './types'
@@ -45,6 +47,9 @@ export { OptionLead, OptionThumb } from './record-picker-option'
  */
 export const DEFAULT_DEPENDS_HINT = 'Selecciona primero el campo del que depende'
 
+/** Label of a held value whose record no longer exists (or is not visible). */
+export const DELETED_RECORD_LABEL = '(registro eliminado)'
+
 export interface DynamicSelectFieldProps {
     field: ActionFieldDef
     value: any
@@ -168,21 +173,23 @@ export function DynamicSelectField({
     const useStatic = Array.isArray(staticOptions)
     const optionFilter = getOptionFilter(field)
 
+    // optionsConfig.source → `/options/<source>`. Else searchEndpoint only
+    // drives the URL when there's no ref (ref is canonical and wins).
+    const optionsEndpoint = source.endpoint ?? (source.ref ? undefined : field.searchEndpoint)
     const { options: fetchedOptions, loading: fetchLoading } = useOptionsResolver({
         modelKey: '',
         fieldKey: source.fieldKey,
         ref: source.ref,
-        // optionsConfig.source → `/options/<source>`. Else searchEndpoint only
-        // drives the URL when there's no ref (ref is canonical and wins).
-        endpoint: source.endpoint ?? (source.ref ? undefined : field.searchEndpoint),
+        endpoint: optionsEndpoint,
         query: debounced,
         limit: 20,
         filterValue: dependsOn ? scope : undefined,
         optionFilter,
         keepValue: value,
-        // Fetch only while open; a readonly cell fetches eagerly so its label
-        // resolves to the name. Blocked cascades and static lists never fetch.
-        enabled: !useStatic && (open || readonly) && !blockedByDependency,
+        // Fetch only while open (a held value's label comes from the `?ids=`
+        // lookup below, readonly included). Blocked cascades and static lists
+        // never fetch.
+        enabled: !useStatic && open && !blockedByDependency,
     })
 
     const options = useStatic
@@ -208,12 +215,37 @@ export function DynamicSelectField({
         }
     }, [dependsOn, scope, value, onChange])
 
-    const selectedOption =
-        (picked && String(picked.id) === String(value) ? picked : null) ??
-        options.find((o) => String(o.id) === String(value)) ??
-        (seedOption && String(seedOption.id) === String(value) ? seedOption : null) ??
+    const valueKey = value != null && value !== '' ? String(value) : ''
+    const knownOption =
+        (picked && String(picked.id) === valueKey ? picked : null) ??
+        options.find((o) => String(o.id) === valueKey) ??
+        (seedOption && String(seedOption.id) === valueKey ? seedOption : null) ??
         null
-    const selectedLabel = selectedOption?.label ?? (value ? String(value) : '')
+    // A held value nobody has labelled yet: one `?ids=` lookup (no popover).
+    const needsLookup = !!valueKey && !knownOption && !useStatic
+    const { resolved, loading: idsLoading } = useResolveOptionIds({
+        ref: source.ref,
+        endpoint: optionsEndpoint,
+        field: source.fieldKey,
+        ids: needsLookup ? [valueKey] : [],
+        enabled: needsLookup,
+    })
+    const resolution = needsLookup ? resolved.get(valueKey) : undefined
+    const selectedOption = knownOption ?? (resolution?.status === 'found' ? resolution.option : null)
+    const valueResolving = needsLookup && !selectedOption && idsLoading
+    const valueMissing = needsLookup && !selectedOption && resolution?.status === 'missing'
+    const selectedLabel =
+        selectedOption?.label ?? (valueResolving ? '' : valueMissing ? DELETED_RECORD_LABEL : valueKey)
+    const resolvingNode = (
+        <span className="min-w-0 flex-1 truncate animate-pulse text-muted-foreground" data-slot="record-picker-value-loading">
+            Cargando…
+        </span>
+    )
+    const missingNode = (
+        <span className="min-w-0 flex-1 truncate italic text-muted-foreground" data-slot="record-picker-value-missing">
+            {DELETED_RECORD_LABEL}
+        </span>
+    )
 
     const handlePick = (opt: ResolvedOption) => {
         setPicked(opt)
@@ -291,13 +323,15 @@ export function DynamicSelectField({
             getDescription={descriptionAsBadge ? undefined : (o) => o.description}
             renderTrailing={descriptionAsBadge ? (o) => badge(o) : undefined}
             renderValue={() => {
+                // Never flash the raw id while the label resolves.
+                if (valueResolving) return resolvingNode
+                if (valueMissing) return missingNode
                 if (readonly) {
                     return (
                         <>
                             {selectedOption ? <OptionLead option={selectedOption} size={20} /> : null}
                             <span className={'min-w-0 flex-1 truncate ' + (selectedOption ? '' : 'text-muted-foreground')}>
-                                {/* Never flash the raw id while the eager fetch resolves. */}
-                                {selectedOption?.label ?? (loading ? 'Cargando…' : ph('—'))}
+                                {selectedOption?.label ?? ph('—')}
                             </span>
                         </>
                     )

package/src/field-grid.tsx

@@ -42,15 +42,16 @@ export function FieldCell({
 export function FieldLabel({
     htmlFor,
     required,
-    tone = 'caps',
+    tone = 'sentence',
     children,
 }: {
     htmlFor?: string
     required?: boolean
     /**
-     * `caps` (default): small uppercase eyebrow of the CRUD modals. `sentence`:
-     * sentence-case label for dense editors (DocumentEditor) where a column of
-     * uppercase labels reads as shouting.
+     * `sentence` (default): sentence-case label — every form of the runtime
+     * (CRUD modal, action modal, DocumentEditor) reads the same and a column of
+     * uppercase labels no longer shouts. `caps`: small uppercase eyebrow, for
+     * callers that still want it.
      */
     tone?: 'caps' | 'sentence'
     children: ReactNode

package/src/index.ts

@@ -588,6 +588,14 @@ export {
     type UseOptionsResolverArgs,
     type UseOptionsResolverResult,
 } from './use-options-resolver'
+export {
+    useResolveOptionIds,
+    OPTION_IDS_CHUNK,
+    type OptionIdResolution,
+    type UseResolveOptionIdsArgs,
+    type UseResolveOptionIdsResult,
+} from './use-option-ids'
+export { DELETED_RECORD_LABEL } from './dynamic-select-field'
 export {
     setOrgConfigBridge,
     getOrgConfigBridge,

package/src/query-batch.ts

@@ -375,6 +375,9 @@ export function tokenForGet(url: string, params?: Record<string, unknown>): stri
             if (value != null && value !== '') search.set(key, String(value))
         }
     }
+    // An `?ids=` resolve is not a page: the `o:` token has no slot for it, so
+    // it goes as its own GET instead of being turned into a first-page read.
+    if (search.has('ids')) return null
     const limit = Number(search.get('limit'))
     return optionsBatchToken(
         opt[1],

package/src/record-picker.tsx

@@ -268,6 +268,8 @@ export interface RecordPickerProps<T> {
     inputRef?: Ref<HTMLInputElement>
     /** Floor for the list width (CSS length). Default 14rem. */
     minListWidth?: string
+    /** Ceiling for the list width (CSS length), e.g. under a very wide trigger. Default: none. */
+    maxListWidth?: string
     /** Rendered after the joined group (e.g. a scan button). */
     after?: ReactNode
     /** Rendered under the control (badges, hints). */
@@ -351,6 +353,7 @@ export function RecordPicker<T>(props: RecordPickerProps<T>) {
         triggerProps,
         inputRef,
         minListWidth = '14rem',
+        maxListWidth,
         after,
         below,
         beforeList,
@@ -555,7 +558,15 @@ export function RecordPicker<T>(props: RecordPickerProps<T>) {
         )
 
     const list = (
-        <div className="max-h-72 overflow-y-auto overflow-x-hidden overscroll-contain" data-slot="record-picker-list">
+        <div
+            className="overflow-y-auto overflow-x-hidden overscroll-contain"
+            data-slot="record-picker-list"
+            // Never taller than the room Radix measured on the side it opened
+            // (flipped above the field near the bottom of a modal it used to
+            // spill past the top of the viewport): 18rem at most, minus the
+            // search box in button mode; the list scrolls inside.
+            style={{ maxHeight: `min(18rem, calc(var(--radix-popover-content-available-height, 18rem) - ${isInput ? '2px' : '2.75rem'}))` }}
+        >
             {beforeList}
             {status}
             <ul
@@ -596,7 +607,7 @@ export function RecordPicker<T>(props: RecordPickerProps<T>) {
                                     ) : null}
                                     {renderLead?.(item, 'option')}
                                     <span className="flex min-w-0 flex-1 flex-col">
-                                        <span className="truncate">{getLabel(item)}</span>
+                                        <span className="line-clamp-2 break-words">{getLabel(item)}</span>
                                         {desc != null && desc !== '' ? (
                                             <span className="truncate text-xs text-muted-foreground">{desc}</span>
                                         ) : null}
@@ -636,7 +647,9 @@ export function RecordPicker<T>(props: RecordPickerProps<T>) {
     )
 
     const contentStyle = {
-        width: `max(var(--radix-popover-trigger-width), ${minListWidth})`,
+        width: maxListWidth
+            ? `min(max(var(--radix-popover-trigger-width), ${minListWidth}), ${maxListWidth})`
+            : `max(var(--radix-popover-trigger-width), ${minListWidth})`,
         maxWidth: 'calc(100vw - 1rem)',
         zIndex: RECORD_PICKER_Z_INDEX,
     }

package/src/use-option-ids.ts

@@ -0,0 +1,168 @@
+// useResolveOptionIds — labels for values a picker already holds.
+//
+// A RecordPicker editing a saved record (a product with its brand) holds an id
+// whose label is in no loaded page: options load only once the popover opens,
+// so the trigger used to show the raw UUID unless the caller had a seed (the
+// relation sibling the table served). This hook asks the canonical options
+// endpoint for exactly those ids:
+//
+//   GET /api/options/<ref>?field=id&ids=a,b
+//
+// - One react-query entry per (org/branch, endpoint, field, id): two pickers
+//   on the same value share it, and nothing is refetched for 30 s.
+// - Every id requested within a few ms for the same endpoint + field travels in
+//   ONE request (a column of cells, a multi-select's chips), chunked at the
+//   kernel's 100-id cap.
+// - A host that predates `ids` ignores the parameter and answers a first page.
+//   The answer is then filtered by id: a hit still resolves, a miss stays
+//   `unknown` (the caller shows the value as before) instead of being reported
+//   as deleted. A response that only holds requested ids is a host that
+//   understood `ids`, so a requested id absent from it is `missing`.
+import { useContext, useMemo } from 'react'
+import { QueryClient, QueryClientContext, useQueries } from '@tanstack/react-query'
+import { useApi, type ApiClient } from './api-context'
+import { onOptionsCacheInvalidated, optionsScope, projectOption, type ResolvedOption } from './use-options-resolver'
+
+export type OptionIdResolution =
+    | { status: 'found'; option: ResolvedOption }
+    /** The host resolved the ids and this one is not there (deleted, or not visible). */
+    | { status: 'missing' }
+    /** Could not tell (old host, error): show the raw value. */
+    | { status: 'unknown' }
+
+/** Ids the kernel accepts per request (dynamic.MaxOptionsIDs). */
+export const OPTION_IDS_CHUNK = 100
+const OPTION_IDS_TTL_MS = 30_000
+const OPTION_IDS_WINDOW_MS = 5
+const QUERY_ROOT = 'metacore-option-ids'
+
+// Hosts without a QueryClientProvider still get dedup + cache.
+let fallbackClient: QueryClient | null = null
+function getFallbackClient(): QueryClient {
+    if (!fallbackClient) fallbackClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+    return fallbackClient
+}
+
+const knownClients = new Set<QueryClient>()
+onOptionsCacheInvalidated(() => {
+    for (const client of knownClients) void client.invalidateQueries({ queryKey: [QUERY_ROOT] })
+})
+
+type Waiter = { resolve: (r: OptionIdResolution) => void }
+type Pending = { api: ApiClient; url: string; field: string; waiters: Map<string, Waiter[]> }
+const pendingBatches = new Map<string, Pending>()
+
+function enqueue(api: ApiClient, scope: string, url: string, field: string, id: string): Promise<OptionIdResolution> {
+    const key = [scope, url, field].join('\n')
+    // Keyed without the client: useApi() hands each component its own wrapper
+    // of the same host client, and pickers of one ref must share the request.
+    let batch = pendingBatches.get(key)
+    if (!batch) {
+        batch = { api, url, field, waiters: new Map() }
+        pendingBatches.set(key, batch)
+        const flushing = batch
+        setTimeout(() => {
+            if (pendingBatches.get(key) === flushing) pendingBatches.delete(key)
+            void flush(flushing)
+        }, OPTION_IDS_WINDOW_MS)
+    }
+    const target = batch
+    return new Promise((resolve) => {
+        const list = target.waiters.get(id) ?? []
+        list.push({ resolve })
+        target.waiters.set(id, list)
+    })
+}
+
+async function flush(batch: Pending): Promise<void> {
+    const ids = [...batch.waiters.keys()]
+    for (let i = 0; i < ids.length; i += OPTION_IDS_CHUNK) {
+        const chunk = ids.slice(i, i + OPTION_IDS_CHUNK)
+        const result = await fetchIds(batch.api, batch.url, batch.field, chunk)
+        for (const id of chunk) {
+            const r = result.get(id) ?? { status: 'unknown' as const }
+            for (const w of batch.waiters.get(id) ?? []) w.resolve(r)
+        }
+    }
+}
+
+async function fetchIds(api: ApiClient, url: string, field: string, ids: string[]): Promise<Map<string, OptionIdResolution>> {
+    const out = new Map<string, OptionIdResolution>()
+    try {
+        const res = await api.get(url, { params: { field, ids: ids.join(',') } })
+        const body = (res as { data: any })?.data
+        if (!body || body.success !== true || !Array.isArray(body.data)) return out
+        const options = (body.data as unknown[]).map(projectOption)
+        const byId = new Map<string, ResolvedOption>()
+        for (const o of options) byId.set(String(o.id).toLowerCase(), o)
+        const asked = new Set(ids.map((id) => id.toLowerCase()))
+        // Only requested ids back → the host honoured `ids`.
+        const honoured = options.every((o) => asked.has(String(o.id).toLowerCase()))
+        for (const id of ids) {
+            const hit = byId.get(id.toLowerCase())
+            if (hit) out.set(id, { status: 'found', option: hit })
+            else if (honoured) out.set(id, { status: 'missing' })
+        }
+    } catch {
+        // Network / permission error: leave every id `unknown`.
+    }
+    return out
+}
+
+export interface UseResolveOptionIdsArgs {
+    /** FK target: `/options/<ref>`. */
+    ref?: string
+    /** Explicit options endpoint (wins over `ref`), as in useOptionsResolver. */
+    endpoint?: string
+    /** `?field=`; defaults to `id` with a `ref`. */
+    field?: string
+    /** Ids to label. Pass only those not already loaded / seeded. */
+    ids: readonly (string | number)[]
+    enabled?: boolean
+}
+
+export interface UseResolveOptionIdsResult {
+    /** Settled resolutions by id (as given, stringified). */
+    resolved: ReadonlyMap<string, OptionIdResolution>
+    /** Some id is still being resolved. */
+    loading: boolean
+}
+
+export function useResolveOptionIds(args: UseResolveOptionIdsArgs): UseResolveOptionIdsResult {
+    const { ref, endpoint, field, ids, enabled = true } = args
+    const api = useApi()
+    const contextClient = useContext(QueryClientContext)
+    const client = contextClient ?? getFallbackClient()
+    knownClients.add(client)
+
+    const url = endpoint || (ref ? `/options/${ref}` : '')
+    const effectiveField = field || (ref ? 'id' : '')
+    const scope = optionsScope()
+    const list = useMemo(() => [...new Set(ids.map(String).filter((id) => id !== ''))], [ids.map(String).join('\u0001')])
+    const active = enabled && !!url && !!effectiveField && list.length > 0
+
+    const results = useQueries(
+        {
+            queries: (active ? list : []).map((id) => ({
+                queryKey: [QUERY_ROOT, scope, url, effectiveField, id],
+                queryFn: () => enqueue(api, scope, url, effectiveField, id),
+                staleTime: OPTION_IDS_TTL_MS,
+                retry: false,
+                refetchOnWindowFocus: false,
+            })),
+        },
+        client,
+    )
+
+    const resolved = new Map<string, OptionIdResolution>()
+    let loading = false
+    if (active) {
+        list.forEach((id, i) => {
+            const r = results[i]
+            if (r?.data) resolved.set(id, r.data)
+            else if (r?.isError) resolved.set(id, { status: 'unknown' })
+            else loading = true
+        })
+    }
+    return { resolved, loading }
+}

package/src/use-options-resolver.ts

@@ -139,6 +139,15 @@ export function invalidateOptionsCache(): void {
     optionsGeneration++
     optionsCache.clear()
     optionsInflight.clear()
+    for (const fn of invalidationListeners) fn()
+}
+
+const invalidationListeners = new Set<() => void>()
+
+/** Runs `fn` on every invalidateOptionsCache (id-label lookups drop with it). */
+export function onOptionsCacheInvalidated(fn: () => void): () => void {
+    invalidationListeners.add(fn)
+    return () => invalidationListeners.delete(fn)
 }
 
 export function optionsRequestKey(
@@ -152,7 +161,8 @@ export function optionsRequestKey(
     return [scope, url, field, query, String(limit ?? ''), filter ?? ''].join('\n')
 }
 
-function optionsScope(): string {
+/** Org + branch of the host session: part of every options cache key. */
+export function optionsScope(): string {
     if (typeof localStorage === 'undefined') return ''
     let org = ''
     try {