@asteby/metacore-runtime-react 49.8.0 → 49.9.0

package/src/business/product-display.ts

@@ -0,0 +1,62 @@
+// withOptionDisplays — completes a product search with the DECLARATIVE option
+// display of the catalog model (manifest v3 `option_display`): after the search
+// answers, ONE `GET /options/<model>?field=id&ids=…` resolves the display of
+// exactly the products found (price, stock contributed by inventory with its
+// tone — in the document's warehouse when `ctx.warehouse_id` is given —,
+// badges) and attaches it to each result. The search keeps owning the business
+// data (price, tax, unit, fiscal keys the line needs); the display only paints
+// the row. A host without the endpoint / model without display → results
+// unchanged (never fails the search).
+import type { OptionDisplayData } from '../option-display'
+import type { ProductResult } from './product-search'
+
+interface ApiLike {
+    get: (url: string, cfg?: { params?: Record<string, unknown>; signal?: AbortSignal }) => Promise<{ data: any }>
+}
+
+export interface OptionDisplaysOptions {
+    /** Catalog model the options endpoint resolves (e.g. `products.Product`). */
+    model: string
+    /** Picker context (`ctx.<key>`), e.g. `{ warehouse_id }`. Empty values are dropped. */
+    context?: Record<string, string | null | undefined>
+}
+
+/** Max ids per lookup (kernel MaxOptionsIDs). */
+const MAX_IDS = 100
+
+export function withOptionDisplays<Q>(
+    search: (query: Q, signal: AbortSignal) => Promise<ProductResult[]>,
+    api: ApiLike,
+    opts: OptionDisplaysOptions,
+): (query: Q, signal: AbortSignal) => Promise<ProductResult[]> {
+    const ctx: Record<string, string> = {}
+    for (const [k, v] of Object.entries(opts.context ?? {})) {
+        if (v != null && String(v).trim()) ctx[`ctx.${k}`] = String(v).trim()
+    }
+    return async (query, signal) => {
+        const rows = await search(query, signal)
+        const ids = [...new Set(rows.filter((r) => !r.display && r.id).map((r) => r.id))].slice(0, MAX_IDS)
+        if (ids.length === 0) return rows
+        let byId: Map<string, OptionDisplayData>
+        try {
+            const res = await api.get(`/options/${opts.model}`, { params: { field: 'id', ids: ids.join(','), ...ctx }, signal })
+            const data: unknown = res?.data?.data
+            byId = new Map()
+            if (Array.isArray(data)) {
+                for (const o of data) {
+                    const d = o && typeof o === 'object' ? (o as { display?: unknown }).display : null
+                    const id = o && typeof o === 'object' ? (o as { id?: unknown; value?: unknown }).id ?? (o as { value?: unknown }).value : null
+                    if (d && typeof d === 'object' && id != null) byId.set(String(id).toLowerCase(), d as OptionDisplayData)
+                }
+            }
+        } catch {
+            if (signal.aborted) throw new DOMException('Aborted', 'AbortError')
+            return rows
+        }
+        if (byId.size === 0) return rows
+        return rows.map((r) => {
+            const d = byId.get(String(r.id).toLowerCase())
+            return d && !r.display ? { ...r, display: d } : r
+        })
+    }
+}

package/src/business/product-options.tsx

@@ -8,6 +8,7 @@ import { useTranslation } from 'react-i18next'
 import { Badge } from '@asteby/metacore-ui/primitives'
 import { useLatestSearch, useRecordSearch } from '../record-picker'
 import { useFormatter } from './format'
+import { OptionDisplayRow } from '../option-display'
 import {
     availableStock,
     parseProductQuery,
@@ -102,8 +103,16 @@ export function ProductHitTrailing({
     )
 }
 
-/** Option body: bold name (· variant), muted meta line, stock/price right. */
+/**
+ * Option body: bold name (· variant), muted meta line, stock/price right. A
+ * product whose catalog declares an `option_display` (the server resolved it,
+ * see `withOptionDisplays`) paints that row instead: avatar, two-line title,
+ * subtitle and toned metrics (price + stock contributed by inventory).
+ */
 export function ProductHitRow({ hit, warehouseId, currency, compact }: { hit: ProductHit; warehouseId?: string; currency?: string; compact?: boolean }) {
+    if (hit.product.display && !hit.variant) {
+        return <OptionDisplayRow display={hit.product.display} label={productHitLabel(hit)} currency={currency} />
+    }
     const meta = productHitMeta(hit)
     return (
         <span className="flex w-full min-w-0 items-center justify-between gap-3">

package/src/business/product-search.ts

@@ -4,6 +4,7 @@
 // la entrada para que el backend/addon elija el índice correcto.
 import type { LineItem } from './line-items'
 import { makeLine } from './line-items'
+import type { OptionDisplayData } from '../option-display'
 
 export interface TireSize {
     width: number
@@ -84,6 +85,13 @@ export interface ProductResult {
     unit?: string
     /** Campos de extensión del producto (fiscal_data.*) que se copian al renglón. */
     extensions?: Record<string, string>
+    /**
+     * Presentación declarativa del catálogo (manifest `option_display` del
+     * modelo de producto): la fila del buscador la pinta tal cual — precio,
+     * existencia aportada por inventory con su tono, badges. Ver
+     * `withOptionDisplays`.
+     */
+    display?: OptionDisplayData | null
 }
 
 /** Existencia disponible: de la variante o del producto, en un almacén o en total. */

package/src/dynamic-select-field.tsx

@@ -27,10 +27,11 @@ import { useEffect, useRef, useState } from 'react'
 import { getOptionFilter } from './option-filter'
 import { useTranslation } from 'react-i18next'
 import { Badge, Button } from '@asteby/metacore-ui/primitives'
-import { ScanLine } from 'lucide-react'
+import { Check, ScanLine } from 'lucide-react'
 import { BarcodeScanner } from './barcode-scanner'
 import { RecordPicker } from './record-picker'
 import { OptionLead } from './record-picker-option'
+import { OptionDisplayRow, OptionDisplayValue, getOptionDisplay, hasOptionDisplays } from './option-display'
 import { recordLabel, requestRecordCreate, requestRecordEdit, withSearchPrefill } from './record-picker-actions'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 import { useResolveOptionIds } from './use-option-ids'
@@ -114,6 +115,12 @@ export interface DynamicSelectFieldProps {
     createLockedFields?: string[]
     /** Paint trigger with destructive border when validation failed. */
     invalid?: boolean
+    /**
+     * Picker context for the declarative option display's contributed
+     * metrics (`?ctx.<key>=`), e.g. `{ warehouse_id }` of the document being
+     * edited so the product stock is the one of that warehouse.
+     */
+    optionsContext?: Record<string, string | null | undefined>
 }
 
 /**
@@ -137,6 +144,7 @@ export function DynamicSelectField({
     createDefaults,
     createLockedFields,
     invalid = false,
+    optionsContext,
 }: DynamicSelectFieldProps) {
     const { t } = useTranslation()
     const ph = (fallback: string) =>
@@ -186,6 +194,7 @@ export function DynamicSelectField({
         filterValue: dependsOn ? scope : undefined,
         optionFilter,
         keepValue: value,
+        context: optionsContext,
         // Fetch only while open (a held value's label comes from the `?ids=`
         // lookup below, readonly included). Blocked cascades and static lists
         // never fetch.
@@ -292,6 +301,10 @@ export function DynamicSelectField({
 
     const canMutate = !!fieldRef && !hideCreate && !useStatic && !blockedByDependency
     const fieldName = field.label ? t(field.label, { defaultValue: field.label }) : fieldRef ?? ''
+    // Declarative option display (manifest `option_display`): rich rows with
+    // avatar, two-line title, subtitle and toned metrics (price, stock…).
+    const richRows = hasOptionDisplays(options)
+    const selectedDisplay = getOptionDisplay(selectedOption)
     const badge = (opt: ResolvedOption) =>
         opt.description ? (
             <Badge variant="secondary" className="shrink-0 font-normal tabular-nums">
@@ -320,12 +333,43 @@ export function DynamicSelectField({
             readOnly={readonly}
             invalid={invalid}
             renderLead={(o, where) => <OptionLead option={o} size={where === 'option' ? 24 : 20} />}
+            renderItem={
+                richRows
+                    ? (o, st) => {
+                          const d = getOptionDisplay(o)
+                          return (
+                              <>
+                                  {d ? (
+                                      <OptionDisplayRow display={d} label={o.label} active={st.active} selected={st.selected} />
+                                  ) : (
+                                      <span className="flex w-full min-w-0 items-center gap-3">
+                                          <OptionLead option={o} size={32} />
+                                          <span className="flex min-w-0 flex-1 flex-col">
+                                              <span className="line-clamp-2 text-sm font-medium">{o.label}</span>
+                                              {o.description ? <span className="truncate text-xs text-muted-foreground">{o.description}</span> : null}
+                                          </span>
+                                      </span>
+                                  )}
+                                  <Check
+                                      className={'size-4 shrink-0 text-primary ' + (st.selected ? 'opacity-100' : 'opacity-0')}
+                                      aria-hidden
+                                  />
+                              </>
+                          )
+                      }
+                    : undefined
+            }
+            isItemDisabled={richRows ? (o) => !!getOptionDisplay(o)?.blocked : undefined}
+            minListWidth={richRows ? '26rem' : undefined}
             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 (selectedDisplay && value && !blockedByDependency) {
+                    return <OptionDisplayValue display={selectedDisplay} label={selectedOption?.label} />
+                }
                 if (readonly) {
                     return (
                         <>

package/src/index.ts

@@ -502,6 +502,16 @@ export type { RecordPickerActionProps, RecordCreateRequest, RecordEditRequest }
 export { useRecordPickerDialog } from './record-picker-dialog'
 export type { UseRecordPickerDialogOptions, UseRecordPickerDialogResult } from './record-picker-dialog'
 export { OptionLead, OptionThumb } from './record-picker-option'
+export {
+    OptionDisplayRow,
+    OptionDisplayValue,
+    getOptionDisplay,
+    hasOptionDisplays,
+    formatTrailingValue,
+    formatRelativeDate,
+    toneVariant,
+} from './option-display'
+export type { OptionDisplayData, OptionTrailingItem, OptionBadgeItem, OptionDisplayTone, OptionDisplayRowProps } from './option-display'
 export { ViewRecordDialog } from './dialogs/view-record-dialog'
 export type {
     ModelKey,

package/src/option-display.tsx

@@ -0,0 +1,255 @@
+// OptionDisplay — paints the declarative option display the kernel resolves for
+// every option of a model with `option_display` (manifest v3): avatar, title on
+// up to two lines, muted subtitle, badges, and right-aligned metrics (price,
+// stock…) with tabular numbers and a toned chip («Agotado» in danger, low
+// stock in warning). The server already evaluated formats' inputs, tones,
+// dim/block — this file only formats and paints, so every picker of the model
+// (dynamic_select, the document editor's product cell, an addon screen) reads
+// the same.
+//
+// It plugs into <RecordPicker> through its existing slots (`renderItem`,
+// `renderValue`, `isItemDisabled`), never by editing the picker itself. An
+// option without `display` keeps rendering exactly as before.
+import { useTranslation } from 'react-i18next'
+import { Badge } from '@asteby/metacore-ui/primitives'
+import { useFormatter, type Formatter } from './business/format'
+import { OptionThumb } from './record-picker-option'
+
+export type OptionDisplayTone = 'success' | 'warning' | 'danger' | 'info' | 'neutral'
+
+/** One resolved right-aligned metric (`display.trailing[]`). */
+export interface OptionTrailingItem {
+    key: string
+    label?: string
+    value: unknown
+    format?: 'money' | 'number' | 'integer' | 'percent' | 'date' | 'relative_date' | 'text' | string
+    currency?: string
+    tone?: OptionDisplayTone | string
+    /** Replaces the formatted value («Agotado»). */
+    text?: string
+}
+
+export interface OptionBadgeItem {
+    text: string
+    tone?: OptionDisplayTone | string
+}
+
+/** The `display` object of an option (kernel `OptionDisplayValue`). */
+export interface OptionDisplayData {
+    title?: string
+    subtitle?: string
+    image?: string | null
+    trailing?: OptionTrailingItem[]
+    badges?: OptionBadgeItem[]
+    tone?: OptionDisplayTone | string
+    /** Attenuated row (still selectable). */
+    dimmed?: boolean
+    /** Not selectable. */
+    blocked?: boolean
+}
+
+/** Reads a well-formed display off any option-like value (null when absent). */
+export function getOptionDisplay(option: unknown): OptionDisplayData | null {
+    const d = option && typeof option === 'object' ? (option as { display?: unknown }).display : null
+    return d && typeof d === 'object' ? (d as OptionDisplayData) : null
+}
+
+type BadgeVariant = 'success' | 'warning' | 'danger' | 'info' | 'muted'
+const TONE_VARIANT: Record<string, BadgeVariant> = {
+    success: 'success',
+    warning: 'warning',
+    danger: 'danger',
+    info: 'info',
+    neutral: 'muted',
+}
+export const toneVariant = (tone?: string): BadgeVariant => TONE_VARIANT[tone ?? ''] ?? 'muted'
+
+const asNumber = (v: unknown): number | null => {
+    if (typeof v === 'number') return Number.isFinite(v) ? v : null
+    if (typeof v === 'string' && v.trim() !== '') {
+        const n = Number(v)
+        return Number.isFinite(n) ? n : null
+    }
+    return null
+}
+
+const RELATIVE_UNITS: Array<[Intl.RelativeTimeFormatUnit, number]> = [
+    ['year', 365 * 86400],
+    ['month', 30 * 86400],
+    ['week', 7 * 86400],
+    ['day', 86400],
+    ['hour', 3600],
+    ['minute', 60],
+]
+
+/** «hace 3 días» / «en 2 semanas» in the formatter's locale. */
+export function formatRelativeDate(input: unknown, locale: string, now: Date = new Date()): string {
+    if (input == null || input === '') return ''
+    const d = new Date(input as string)
+    if (Number.isNaN(d.getTime())) return String(input)
+    const secs = (d.getTime() - now.getTime()) / 1000
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+    for (const [unit, size] of RELATIVE_UNITS) {
+        if (Math.abs(secs) >= size) return rtf.format(Math.round(secs / size), unit)
+    }
+    return rtf.format(0, 'minute')
+}
+
+/** Formats one trailing value per its declared format (org currency for money). */
+export function formatTrailingValue(item: OptionTrailingItem, fmt: Formatter, now?: Date): string {
+    const v = item.value
+    if (v == null || v === '') return ''
+    switch (item.format) {
+        case 'money':
+            return fmt.money(v, item.currency || undefined)
+        case 'number':
+            return fmt.quantity(v)
+        case 'integer': {
+            const n = asNumber(v)
+            return n == null ? String(v) : new Intl.NumberFormat(fmt.locale, { maximumFractionDigits: 0 }).format(n)
+        }
+        case 'percent': {
+            const n = asNumber(v)
+            if (n == null) return String(v)
+            // 0.16 and 16 both mean 16 %.
+            const frac = Math.abs(n) <= 1 ? n : n / 100
+            return new Intl.NumberFormat(fmt.locale, { style: 'percent', maximumFractionDigits: 1 }).format(frac)
+        }
+        case 'date':
+            return fmt.date(v)
+        case 'relative_date':
+            return formatRelativeDate(v, fmt.locale, now)
+        default:
+            return typeof v === 'number' ? fmt.quantity(v) : String(v)
+    }
+}
+
+/**
+ * One metric. A toned metric is a chip carrying its value and label («18
+ * disp.», or the tone's text «Agotado»); a plain one is the value in tabular
+ * numbers, with its label inline only when `showLabel` (several plain metrics
+ * side by side need it to tell «Saldo» from «Vencido»; a lone price does not).
+ */
+function TrailingMetric({ item, fmt, showLabel }: { item: OptionTrailingItem; fmt: Formatter; showLabel?: boolean }) {
+    const { t } = useTranslation()
+    const label = item.label ? t(item.label, { defaultValue: item.label }) : ''
+    const value = formatTrailingValue(item, fmt)
+    if (item.tone) {
+        const text = item.text ? t(item.text, { defaultValue: item.text }) : [value, label].filter(Boolean).join(' ')
+        return (
+            <Badge
+                variant={toneVariant(item.tone)}
+                className="font-medium tabular-nums"
+                title={label && item.text ? `${label}: ${value}` : undefined}
+                data-slot="option-metric-chip"
+                data-key={item.key}
+                data-tone={item.tone}
+            >
+                {text}
+            </Badge>
+        )
+    }
+    return (
+        <span className="flex items-baseline gap-1 whitespace-nowrap" title={label || undefined} data-slot="option-metric" data-key={item.key}>
+            {showLabel && label ? <span className="text-[11px] text-muted-foreground">{label}</span> : null}
+            <span className="text-sm font-semibold tabular-nums text-foreground" data-slot="option-metric-value">
+                {item.text ? t(item.text, { defaultValue: item.text }) : value}
+            </span>
+        </span>
+    )
+}
+
+export interface OptionDisplayRowProps {
+    display: OptionDisplayData
+    /** Fallback title (the option label) when the display has none. */
+    label?: string
+    /** Keyboard / pointer highlight (for the title color). */
+    active?: boolean
+    selected?: boolean
+    /** Org currency override for money metrics without their own currency. */
+    currency?: string
+    /** Avatar size in px. Default 32. */
+    avatarSize?: number
+}
+
+/**
+ * The option row: avatar 32px · title (≤2 lines) + badges · muted subtitle ·
+ * metrics aligned right. `dimmed` attenuates the content, never the hover.
+ */
+export function OptionDisplayRow({ display, label, active, selected, currency, avatarSize = 32 }: OptionDisplayRowProps) {
+    const { t } = useTranslation()
+    const fmt = useFormatter({ currency })
+    const title = display.title || label || ''
+    const trailing = display.trailing ?? []
+    const badges = display.badges ?? []
+    const plainCount = trailing.filter((i) => !i.tone).length
+    return (
+        <span
+            className="flex w-full min-w-0 items-center gap-3 py-0.5"
+            data-slot="option-display"
+            data-tone={display.tone || undefined}
+            data-dimmed={display.dimmed || undefined}
+            data-selected={selected || undefined}
+        >
+            <span className={display.dimmed ? 'opacity-60 grayscale' : undefined}>
+                <OptionThumb image={display.image ?? null} name={title} size={avatarSize} />
+            </span>
+            <span className={'flex min-w-0 flex-1 flex-col gap-0.5' + (display.dimmed ? ' opacity-60' : '')}>
+                <span className="flex min-w-0 items-start gap-1.5">
+                    <span
+                        className={'line-clamp-2 min-w-0 break-words text-sm font-medium leading-snug' + (active ? ' text-accent-foreground' : '')}
+                        title={title}
+                        data-slot="option-display-title"
+                    >
+                        {title}
+                    </span>
+                    {badges.map((b, i) => (
+                        <Badge key={i} variant={toneVariant(b.tone)} className="mt-px px-1.5 py-0 text-[10px]" data-slot="option-display-badge">
+                            {t(b.text, { defaultValue: b.text })}
+                        </Badge>
+                    ))}
+                </span>
+                {display.subtitle ? (
+                    <span className="truncate text-xs text-muted-foreground" data-slot="option-display-subtitle">
+                        {display.subtitle}
+                    </span>
+                ) : null}
+            </span>
+            {trailing.length > 0 ? (
+                // Metrics stack right-aligned (price over the stock chip): the
+                // column stays narrow so the title keeps its room, and the
+                // values line up across rows.
+                <span className="ml-auto flex shrink-0 flex-col items-end justify-center gap-1 text-right" data-slot="option-display-trailing">
+                    {trailing.map((item) => (
+                        <TrailingMetric key={item.key} item={item} fmt={fmt} showLabel={plainCount > 1} />
+                    ))}
+                </span>
+            ) : null}
+        </span>
+    )
+}
+
+/**
+ * Compact summary for a picker's trigger: small avatar, title and the most
+ * relevant metric (the toned one, else the first).
+ */
+export function OptionDisplayValue({ display, label, currency }: { display: OptionDisplayData; label?: string; currency?: string }) {
+    const fmt = useFormatter({ currency })
+    const title = display.title || label || ''
+    const trailing = display.trailing ?? []
+    const lead = trailing.find((i) => i.tone) ?? trailing[0]
+    const extra = lead && trailing.find((i) => i !== lead && !i.tone)
+    return (
+        <span className="flex min-w-0 flex-1 items-center gap-2" data-slot="option-display-value">
+            <OptionThumb image={display.image ?? null} name={title} size={20} />
+            <span className="min-w-0 flex-1 truncate">{title}</span>
+            {extra ? (
+                <span className="shrink-0 text-xs tabular-nums text-muted-foreground">{formatTrailingValue(extra, fmt)}</span>
+            ) : null}
+            {lead ? <TrailingMetric item={lead} fmt={fmt} /> : null}
+        </span>
+    )
+}
+
+/** Whether any of the options carries a display (switches a picker to rich rows). */
+export const hasOptionDisplays = (options: readonly unknown[]): boolean => options.some((o) => getOptionDisplay(o) !== null)

package/src/query-batch.ts

@@ -234,12 +234,14 @@ export function optionsBatchToken(
     query: string,
     limit: number | undefined,
     filter: string | undefined,
+    context?: Record<string, string>,
 ): string {
     const params = new URLSearchParams()
     params.set('field', field)
     if (query) params.set('q', query)
     if (typeof limit === 'number' && limit > 0) params.set('limit', String(limit))
     if (filter) params.set('filter_value', filter)
+    for (const k of Object.keys(context ?? {}).sort()) params.set(`ctx.${k}`, context![k]!)
     return `o:${model}?${params.toString()}`
 }
 

package/src/use-options-resolver.ts

@@ -14,6 +14,7 @@ import { useEffect, useMemo, useRef, useState } from 'react'
 import { useApi } from './api-context'
 import { applyOptionFilter, type OptionFilterRule } from './option-filter'
 import { loadQueryPart, optionsBatchToken, optionsModelFromUrl } from './query-batch'
+import type { OptionDisplayData } from './option-display'
 
 export interface ResolvedOption {
     /** Canonical id (server-side primary key). */
@@ -28,6 +29,12 @@ export interface ResolvedOption {
     image?: string | null
     color?: string | null
     icon?: string | null
+    /**
+     * Presentación declarativa resuelta por el kernel (manifest v3
+     * `option_display`): título, subtítulo, imagen, métricas a la derecha con
+     * tono (precio, stock…) y badges. Ausente en hosts/modelos sin display.
+     */
+    display?: OptionDisplayData | null
     /**
      * Campos extra del payload (precio, costo, sku, tasa) que no son decoración.
      * Solo se llena cuando el option trae números o strings además de id/label.
@@ -98,6 +105,12 @@ export interface UseOptionsResolverArgs {
     optionFilter?: OptionFilterRule[]
     /** Current selection: never hidden by `optionFilter`, so its label survives. */
     keepValue?: unknown
+    /**
+     * Picker context for the option display's contributed metrics, sent as
+     * `?ctx.<key>=<value>` (e.g. `{ warehouse_id }` of the document being
+     * edited → stock in that warehouse). Empty values are dropped.
+     */
+    context?: Record<string, string | null | undefined>
 }
 
 export interface UseOptionsResolverResult {
@@ -157,8 +170,34 @@ export function optionsRequestKey(
     query: string,
     limit: number | undefined,
     filter: string | undefined,
+    context?: Record<string, string>,
 ): string {
-    return [scope, url, field, query, String(limit ?? ''), filter ?? ''].join('\n')
+    const parts = [scope, url, field, query, String(limit ?? ''), filter ?? '']
+    const ctx = contextKey(context)
+    if (ctx) parts.push(ctx)
+    return parts.join('\n')
+}
+
+/** Normalized picker context: string values only, empty dropped (null when none). */
+export function normalizeOptionsContext(
+    context: Record<string, string | null | undefined> | undefined,
+): Record<string, string> | undefined {
+    if (!context) return undefined
+    const out: Record<string, string> = {}
+    for (const [k, v] of Object.entries(context)) {
+        if (v == null) continue
+        const s = String(v).trim()
+        if (s) out[k] = s
+    }
+    return Object.keys(out).length > 0 ? out : undefined
+}
+
+function contextKey(context: Record<string, string> | undefined): string {
+    if (!context) return ''
+    return Object.keys(context)
+        .sort()
+        .map((k) => `${k}=${context[k]}`)
+        .join('&')
 }
 
 /** Org + branch of the host session: part of every options cache key. */
@@ -203,6 +242,8 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         optionFilter,
         keepValue,
     } = args
+    const context = normalizeOptionsContext(args.context)
+    const ctxSig = contextKey(context)
 
     const api = useApi()
     const [options, setOptions] = useState<ResolvedOption[]>([])
@@ -251,6 +292,7 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
             query ?? '',
             limit,
             filterValue,
+            context,
         )
         if (refreshKey !== seenRefresh.current) {
             seenRefresh.current = refreshKey
@@ -278,13 +320,14 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
             if (query) params.q = query
             if (typeof limit === 'number' && limit > 0) params.limit = limit
             if (filterValue) params.filter_value = filterValue
+            for (const [k, v] of Object.entries(context ?? {})) params[`ctx.${k}`] = v
             const model = optionsModelFromUrl(url)
             pending = (async () => {
                 if (model) {
                     try {
                         const part = await loadQueryPart(
                             api,
-                            optionsBatchToken(model, effectiveField, query ?? '', limit, filterValue),
+                            optionsBatchToken(model, effectiveField, query ?? '', limit, filterValue, context),
                         )
                         if (!part.success) {
                             throw new Error(part.message || 'options resolver: unsuccessful response')
@@ -340,7 +383,8 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         return () => {
             cancelled = true
         }
-    }, [api, url, effectiveField, query, limit, enabled, filterValue, refreshKey])
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- context is keyed by ctxSig
+    }, [api, url, effectiveField, query, limit, enabled, filterValue, refreshKey, ctxSig])
 
     // Rules arrive as a fresh array each render; key on their content.
     const filterKey = optionFilter && optionFilter.length > 0 ? JSON.stringify(optionFilter) : ''
@@ -364,7 +408,7 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
  * id/value and label/name fields for legacy parity — we accept either
  * and surface a stable shape downstream.
  */
-const OPTION_KNOWN_KEYS = new Set(['id', 'value', 'label', 'name', 'description', 'image', 'color', 'icon'])
+const OPTION_KNOWN_KEYS = new Set(['id', 'value', 'label', 'name', 'description', 'image', 'color', 'icon', 'display'])
 
 export function projectOption(raw: any): ResolvedOption {
     const id = raw?.id ?? raw?.value ?? ''
@@ -385,6 +429,7 @@ export function projectOption(raw: any): ResolvedOption {
         image: raw?.image ?? null,
         color: raw?.color ?? null,
         icon: raw?.icon ?? null,
+        ...(raw?.display && typeof raw.display === 'object' ? { display: raw.display as OptionDisplayData } : {}),
         ...(Object.keys(meta).length > 0 ? { meta } : {}),
     }
 }