@asteby/metacore-runtime-react 49.7.0 → 49.9.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-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,13 +103,21 @@ 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">
             <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/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/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-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/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

@@ -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()}`
 }