@asteby/metacore-runtime-react 46.2.3 → 46.4.0

package/src/business/line-items.ts

@@ -16,10 +16,22 @@ export interface LineItem {
     description: string
     quantity: number
     unit_price: number
-    /** Descuento en porcentaje 0-100. */
+    /**
+     * Descuento. Porcentaje 0-100 salvo `discount_kind: 'amount'`, donde es importe.
+     */
     discount: number
+    /** `percent` (default, se omite al serializar) o `amount`. */
+    discount_kind?: 'percent' | 'amount'
     /** Tasa de impuesto como fracción (0.16). Viene de la config fiscal de la org. */
     tax_rate: number
+    /** Unidad de medida (pza, juego…). Solo se serializa si viene informada. */
+    unit?: string
+    /** Precio o costo de catálogo, para mostrarlo junto al precio editado. */
+    catalog_price?: number
+    /** Costo conocido. Aviso si el precio de venta queda por debajo. No se serializa. */
+    cost?: number
+    /** Tope de cantidad (NC: facturado − acreditado; devolución: vendido − devuelto). */
+    max_quantity?: number
     technician_id?: string
     lot?: string
     dot?: string
@@ -37,6 +49,8 @@ export interface LineItemsPolicy {
     allowNegative?: boolean
     /** Exige al menos un renglón `item`. Default true. */
     requireItems?: boolean
+    /** Permite cantidad 0 (renglón de origen que no se acredita/devuelve). Default false. */
+    allowZeroQuantity?: boolean
 }
 
 let seq = 0
@@ -67,10 +81,16 @@ export interface LineAmounts {
     total: number
 }
 
-export function computeLine(l: Pick<LineItem, 'kind' | 'quantity' | 'unit_price' | 'discount' | 'tax_rate'>): LineAmounts {
+export function computeLine(
+    l: Pick<LineItem, 'kind' | 'quantity' | 'unit_price' | 'discount' | 'tax_rate'> & { discount_kind?: LineItem['discount_kind'] },
+): LineAmounts {
     if (l.kind !== 'item') return { gross: 0, discount: 0, net: 0, tax: 0, total: 0 }
     const gross = roundMoney(toAmount(l.quantity) * toAmount(l.unit_price))
-    const discount = roundMoney(gross * (toAmount(l.discount) / 100))
+    const raw = toAmount(l.discount)
+    const discount =
+        l.discount_kind === 'amount'
+            ? roundMoney(Math.min(Math.max(raw, 0), Math.max(gross, 0)))
+            : roundMoney(gross * (raw / 100))
     const net = roundMoney(gross - discount)
     const tax = roundMoney(net * toAmount(l.tax_rate))
     return { gross, discount, net, tax, total: roundMoney(net + tax) }
@@ -102,6 +122,25 @@ export function computeTotals(lines: LineItem[]): LineItemsTotals {
     return t
 }
 
+/** Impuesto agrupado por tasa, sumando el impuesto ya redondeado de cada renglón. */
+export function taxBreakdown(lines: LineItem[]): Array<{ rate: number; base: number; tax: number }> {
+    const map = new Map<number, { base: number; tax: number }>()
+    for (const l of lines) {
+        if (l.kind !== 'item') continue
+        const a = computeLine(l)
+        const rate = toAmount(l.tax_rate)
+        const cur = map.get(rate) ?? { base: 0, tax: 0 }
+        cur.base += a.net
+        cur.tax += a.tax
+        map.set(rate, cur)
+    }
+    return [...map.entries()].map(([rate, v]) => ({
+        rate,
+        base: roundMoney(v.base),
+        tax: roundMoney(v.tax),
+    }))
+}
+
 export interface LineItemsValidation {
     /** Errores por celda `"<índice>.<campo>"` (mismo formato que DynamicLineItems). */
     errors: Record<string, string>
@@ -113,7 +152,7 @@ export interface LineItemsValidation {
 }
 
 export function validateLineItems(lines: LineItem[], policy: LineItemsPolicy = {}): LineItemsValidation {
-    const { stockPolicy = 'warn', allowNegative = false, requireItems = true } = policy
+    const { stockPolicy = 'warn', allowNegative = false, requireItems = true, allowZeroQuantity = false } = policy
     const errors: Record<string, string> = {}
     const warnings: Record<string, string> = {}
     let items = 0
@@ -127,10 +166,22 @@ export function validateLineItems(lines: LineItem[], policy: LineItemsPolicy = {
         const price = toAmount(l.unit_price)
         const disc = toAmount(l.discount)
         if (!l.description.trim() && !l.product_id) errors[`${i}.description`] = 'Elige un producto o escribe una descripción'
-        if (qty === 0) errors[`${i}.quantity`] = 'La cantidad debe ser distinta de cero'
+        if (qty === 0 && !allowZeroQuantity) errors[`${i}.quantity`] = 'La cantidad debe ser distinta de cero'
         else if (qty < 0 && !allowNegative) errors[`${i}.quantity`] = 'La cantidad no puede ser negativa'
+        if (l.max_quantity != null && qty > toAmount(l.max_quantity)) {
+            errors[`${i}.quantity`] = `El máximo es ${l.max_quantity}`
+        }
         if (price < 0 && !allowNegative) errors[`${i}.unit_price`] = 'El precio no puede ser negativo'
-        if (disc < 0 || disc > 100) errors[`${i}.discount`] = 'El descuento debe estar entre 0 y 100%'
+        if (l.cost != null && price < toAmount(l.cost)) {
+            warnings[`${i}.unit_price`] = 'El precio está por debajo del costo'
+        }
+        if (l.discount_kind === 'amount') {
+            const gross = roundMoney(qty * price)
+            if (disc < 0) errors[`${i}.discount`] = 'El descuento no puede ser negativo'
+            else if (disc > gross) errors[`${i}.discount`] = 'El descuento no puede superar el importe'
+        } else if (disc < 0 || disc > 100) {
+            errors[`${i}.discount`] = 'El descuento debe estar entre 0 y 100%'
+        }
         if (l.available != null && qty > l.available && stockPolicy !== 'allow') {
             const msg = `Solo hay ${l.available} disponibles`
             if (stockPolicy === 'block') errors[`${i}.quantity`] ??= msg
@@ -157,7 +208,9 @@ export function serializeLineItems(lines: LineItem[]): Array<Record<string, unkn
             out.unit_price = toAmount(l.unit_price)
             out.discount = toAmount(l.discount)
             out.tax_rate = toAmount(l.tax_rate)
-            for (const k of ['product_id', 'sku', 'technician_id', 'lot', 'dot'] as const) {
+            if (l.discount_kind === 'amount') out.discount_kind = 'amount'
+            if (l.catalog_price != null) out.catalog_price = toAmount(l.catalog_price)
+            for (const k of ['product_id', 'sku', 'technician_id', 'lot', 'dot', 'unit'] as const) {
                 const v = l[k]
                 if (typeof v === 'string' && v.trim()) out[k] = v.trim()
             }
@@ -181,7 +234,12 @@ export function parseLineItems(rows: unknown): LineItem[] {
             quantity: o.quantity == null ? 1 : toAmount(o.quantity),
             unit_price: toAmount(o.unit_price),
             discount: toAmount(o.discount),
+            discount_kind: o.discount_kind === 'amount' ? 'amount' : undefined,
             tax_rate: toAmount(o.tax_rate),
+            unit: str(o.unit),
+            catalog_price: o.catalog_price == null || o.catalog_price === '' ? undefined : toAmount(o.catalog_price),
+            cost: o.cost == null || o.cost === '' ? undefined : toAmount(o.cost),
+            max_quantity: o.max_quantity == null || o.max_quantity === '' ? undefined : toAmount(o.max_quantity),
             technician_id: str(o.technician_id),
             lot: str(o.lot),
             dot: str(o.dot),

package/src/business/product-search.ts

@@ -58,6 +58,8 @@ export interface ProductVariant {
     sku?: string
     barcode?: string
     price?: number
+    /** Costo de catálogo (compras). Opcional; el precio de lista sigue en `price`. */
+    cost?: number
     stock?: StockByWarehouse[]
 }
 
@@ -70,6 +72,8 @@ export interface ProductResult {
     supplier_sku?: string
     kind?: 'product' | 'tire' | 'service' | 'bundle'
     price?: number
+    /** Costo de catálogo (compras). */
+    cost?: number
     tax_rate?: number
     tire?: TireSize
     variants?: ProductVariant[]
@@ -96,12 +100,16 @@ export function productToLine(
     opts: { warehouseId?: string; quantity?: number } = {},
 ): LineItem {
     const src = variant ?? p
+    const list = variant?.price ?? p.price
+    const cost = variant?.cost ?? p.cost
     return makeLine({
         product_id: variant?.id ?? p.id,
         sku: variant?.sku ?? p.sku,
         description: variant ? `${p.name} · ${variant.label}` : p.name,
         quantity: opts.quantity ?? 1,
-        unit_price: variant?.price ?? p.price ?? 0,
+        unit_price: list ?? 0,
+        catalog_price: list,
+        cost,
         tax_rate: p.tax_rate ?? 0,
         available: availableStock(src, opts.warehouseId) ?? availableStock(p, opts.warehouseId),
     })

package/src/dynamic-crud-page.tsx

@@ -37,6 +37,7 @@ import { ExportDialog } from './dialogs/export'
 import { ImportDialog } from './dialogs/import'
 import { getModelExtension } from './model-extension-registry'
 import { ModelActionToolbar } from './model-action-toolbar'
+import { resolveListPrimaryAction } from './list-primary-action'
 import { useCan, modelCapability } from './permissions-context'
 import type { TableMetadata } from './types'
 
@@ -159,10 +160,17 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
     }, [title])
 
     const enableCRUD = metadata?.enableCRUDActions ?? false
-    // A "create"-placement action ships a custom create experience — it
-    // replaces the generic create button (the ModelActionToolbar renders it).
-    const hasCreateAction = metadata?.actions?.some((a) => a.placement === 'create') ?? false
-    const effectiveHideCreate = hideCreate || ext?.hideCreate || hasCreateAction
+    // Una sola primaria: placement create, replaces_create, create_mode o la
+    // extensión del modelo ocultan el Crear genérico. El shell de ops debe
+    // usar el mismo resolveListPrimaryAction.
+    const primary = resolveListPrimaryAction({
+        enableCRUD,
+        canCreate: metadata?.canCreate,
+        hideCreate: hideCreate || ext?.hideCreate,
+        createMode: ext?.createMode ?? metadata?.create_mode,
+        primaryActionKey: ext?.primaryActionKey,
+        actions: metadata?.actions,
+    })
     const effectiveHideExport = hideExport || ext?.hideExport
     const effectiveHideImport = hideImport || ext?.hideImport
     // Refresh defaults to hidden in the page header — <DynamicTable> ships
@@ -174,7 +182,7 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
     // (useCan defaults to always-true), in which case create/export/import
     // require `lowercase(model).create|export|import`.
     const can = useCan()
-    const showCreate = enableCRUD && !effectiveHideCreate && can(modelCapability(model, 'create'))
+    const showCreate = primary.showGenericCreate && can(modelCapability(model, 'create'))
     const showImport = enableCRUD && !effectiveHideImport && can(modelCapability(model, 'import'))
     const showExport = !effectiveHideExport && can(modelCapability(model, 'export'))
     const showRefresh = !effectiveHideRefresh
@@ -239,11 +247,13 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
                             model={model}
                             endpoint={dataEndpoint}
                             actions={metadata?.actions}
+                            primaryActionKey={ext?.primaryActionKey}
                             onChange={handleRefresh}
                         />
                         {showCreate && (
                             <button
                                 type='button'
+                                data-primary='true'
                                 onClick={() => setOpenCreate(true)}
                                 className='inline-flex items-center gap-2 h-9 px-3 rounded-md bg-primary text-primary-foreground hover:opacity-90 text-sm font-medium'
                             >

package/src/dynamic-form-schema.ts

@@ -177,6 +177,66 @@ export function applyLineItemRowFormulas(
     return out
 }
 
+const AUTOFILL_PRICE_KEYS = new Set(['unit_price', 'price', 'sale_price'])
+const AUTOFILL_COST_KEYS = new Set(['cost', 'unit_cost', 'catalog_cost', 'catalog_price'])
+
+function metaNumber(meta: Record<string, unknown>, keys: string[]): number | undefined {
+    for (const k of keys) {
+        const v = meta[k]
+        if (typeof v === 'number' && Number.isFinite(v)) return v
+        if (typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v))) return Number(v)
+    }
+    return undefined
+}
+
+/**
+ * Al elegir un producto en una grilla declarativa, copia precio/costo/SKU/tasa
+ * que vengan en `option.meta` a las columnas hermanas y recalcula el importe.
+ * No-op si el meta no trae datos útiles (el journal entry no se toca).
+ */
+export function autofillLineFromOption(
+    itemFields: ActionFieldDef[],
+    row: Record<string, any>,
+    option: { label?: string; meta?: Record<string, unknown> },
+): Record<string, any> {
+    const meta = option.meta
+    if (!meta || Object.keys(meta).length === 0) return row
+    const next: Record<string, any> = { ...row }
+    let changed = false
+    for (const f of itemFields) {
+        if (AUTOFILL_PRICE_KEYS.has(f.key)) {
+            const v = metaNumber(meta, ['unit_price', 'price', 'sale_price'])
+            if (v != null) {
+                next[f.key] = v
+                changed = true
+            }
+        } else if (AUTOFILL_COST_KEYS.has(f.key)) {
+            const v = metaNumber(meta, ['cost', 'unit_cost', 'catalog_price', 'catalog_cost'])
+            if (v != null) {
+                next[f.key] = v
+                changed = true
+            }
+        } else if (f.key === 'tax_rate' || f.key === 'tax') {
+            const v = metaNumber(meta, ['tax_rate', 'tax'])
+            if (v != null) {
+                next[f.key] = v
+                changed = true
+            }
+        } else if (f.key === 'sku' || f.key === 'code') {
+            const v = meta.sku ?? meta.code
+            if (typeof v === 'string' && v.trim()) {
+                next[f.key] = v.trim()
+                changed = true
+            }
+        } else if ((f.key === 'description' || f.key === 'name') && !next[f.key] && option.label) {
+            next[f.key] = option.label
+            changed = true
+        }
+    }
+    if (!changed) return row
+    return applyLineItemRowFormulas(itemFields, next)
+}
+
 export interface BalanceState {
     debit: number
     credit: number

package/src/dynamic-line-items.tsx

@@ -26,6 +26,7 @@ import {
     getItemFields,
     computeLineItemTotals,
     applyLineItemRowFormulas,
+    autofillLineFromOption,
     evaluateBalance,
     toNumber,
     getDependsOn,
@@ -139,6 +140,16 @@ export function DynamicLineItems({ field, value, onChange, disabled = false, for
         updateCell(idx, key, cellValue)
     }
 
+    const handlePick = (idx: number, key: string, opt: ResolvedOption) => {
+        onChange(
+            rows.map((r, i) =>
+                i === idx
+                    ? autofillLineFromOption(itemFields, { ...r, [key]: String(opt.id) }, opt)
+                    : r,
+            ),
+        )
+    }
+
     const totalCols = itemFields.filter((c) => c.total)
 
     return (
@@ -189,6 +200,7 @@ export function DynamicLineItems({ field, value, onChange, disabled = false, for
                                         field={col}
                                         value={row?.[col.key]}
                                         onChange={(v: any) => handleCell(idx, col.key, v)}
+                                        onPick={(opt) => handlePick(idx, col.key, opt)}
                                         disabled={disabled}
                                         formValues={formValues}
                                         rowValues={row}
@@ -260,6 +272,7 @@ export function DynamicLineItems({ field, value, onChange, disabled = false, for
                                             field={col}
                                             value={row?.[col.key]}
                                             onChange={(v: any) => handleCell(idx, col.key, v)}
+                                            onPick={(opt) => handlePick(idx, col.key, opt)}
                                             disabled={disabled}
                                             formValues={formValues}
                                             rowValues={row}
@@ -377,6 +390,7 @@ interface CellRendererProps {
     field: ActionFieldDef
     value: any
     onChange: (v: any) => void
+    onPick?: (opt: ResolvedOption) => void
     disabled?: boolean
     /** Header form values — for resolving a cell's `dependsOn` to a header field. */
     formValues?: Record<string, any>
@@ -390,7 +404,7 @@ interface CellRendererProps {
 // without the per-field Label (the column header is the label) and sized for a
 // table cell. Nested line-items inside a row are not supported (a row column is
 // a scalar widget).
-function CellRenderer({ field, value, onChange, disabled, formValues, rowValues, invalid }: CellRendererProps) {
+function CellRenderer({ field, value, onChange, onPick, disabled, formValues, rowValues, invalid }: CellRendererProps) {
     const widget = resolveWidget(field)
     const invalidCls = invalid
         ? 'border-destructive ring-1 ring-destructive/30 focus-visible:ring-destructive'
@@ -434,6 +448,7 @@ function CellRenderer({ field, value, onChange, disabled, formValues, rowValues,
                 field={field}
                 value={value}
                 onChange={onChange}
+                onPick={onPick}
                 dependsValue={dependsValue}
                 readonly={ro}
                 invalid={invalid}
@@ -446,6 +461,7 @@ function CellRenderer({ field, value, onChange, disabled, formValues, rowValues,
                 field={field}
                 value={value}
                 onChange={onChange}
+                onPick={onPick}
                 disabled={disabled}
                 formValues={formValues}
                 rowValues={rowValues}
@@ -541,7 +557,7 @@ function CellRenderer({ field, value, onChange, disabled, formValues, rowValues,
     }
 }
 
-function RefCell({ field, value, onChange, disabled, formValues, rowValues }: CellRendererProps) {
+function RefCell({ field, value, onChange, onPick, disabled, formValues, rowValues }: CellRendererProps) {
     // Cascade: resolve the value of the field this cell `dependsOn` from the
     // row (sibling) first, then the header form. While empty, the picker is
     // disabled with a hint instead of listing the whole (unscoped) table.
@@ -581,7 +597,11 @@ function RefCell({ field, value, onChange, disabled, formValues, rowValues }: Ce
     return (
         <Select
             value={value || ''}
-            onValueChange={onChange}
+            onValueChange={(v) => {
+                onChange(v)
+                const opt = options.find((o) => String(o.id) === String(v))
+                if (opt) onPick?.(opt)
+            }}
             disabled={disabled || loading || blockedByDependency}
         >
             <SelectTrigger className="w-full" data-depends-blocked={blockedByDependency ? '' : undefined}>

package/src/dynamic-select-field.tsx

@@ -149,6 +149,8 @@ export interface DynamicSelectFieldProps {
     field: ActionFieldDef
     value: any
     onChange: (v: any) => void
+    /** Opción completa recién elegida (incluye `meta` para autollenar columnas hermanas). */
+    onPick?: (opt: ResolvedOption) => void
     /**
      * Pre-resolved option for the CURRENT value (label + image/color/icon) the
      * caller already has — e.g. the relation sibling the table served. Lets the
@@ -212,6 +214,7 @@ export function DynamicSelectField({
     field,
     value,
     onChange,
+    onPick,
     seedOption,
     dependsValue,
     dependsHint,
@@ -327,6 +330,7 @@ export function DynamicSelectField({
     const handlePick = (opt: ResolvedOption) => {
         setPicked(opt)
         onChange(String(opt.id))
+        onPick?.(opt)
         setOpen(false)
         setSearch('')
     }

package/src/index.ts

@@ -188,6 +188,14 @@ export {
     type ModelActionToolbarProps,
     type ActionPlacement,
 } from './model-action-toolbar'
+export {
+    resolveListPrimaryAction,
+    actionReplacesCreate,
+    type ListPrimaryActionInput,
+    type ListPrimaryActionResult,
+    type ListActionRef,
+    type CreateMode,
+} from './list-primary-action'
 export * from './addon-loader'
 export {
     PURGE_ADDON_MESSAGE,

package/src/list-primary-action.ts

@@ -0,0 +1,71 @@
+// Una sola acción primaria de alta por pantalla (UX-1).
+// Puro: DynamicCRUDPage y ModelActionToolbar lo usan, y el shell de ops
+// (`/m/$model`) debe llamarlo también para no pintar un segundo «Crear».
+
+export type CreateMode = 'generic' | 'hidden' | 'action'
+
+export interface ListActionRef {
+    key: string
+    placement?: string
+    /** El kernel sirve snake_case. CamelCase se acepta por si el host ya lo normalizó. */
+    replaces_create?: boolean
+    replacesCreate?: boolean
+}
+
+export interface ListPrimaryActionInput {
+    /** `metadata.enableCRUDActions`. Sin él no hay Crear genérico. */
+    enableCRUD?: boolean
+    /** `metadata.canCreate`. `false` oculta el genérico; `undefined` no cambia nada. */
+    canCreate?: boolean
+    hideCreate?: boolean
+    createMode?: CreateMode
+    /** Si apunta a una acción de toolbar, esa es la primaria y oculta el genérico. */
+    primaryActionKey?: string
+    actions?: ListActionRef[]
+}
+
+export interface ListPrimaryActionResult {
+    showGenericCreate: boolean
+    primaryAction?: ListActionRef
+    /** Acciones de toolbar que no son la primaria (siguen visibles, en secundario). */
+    secondaryActions: ListActionRef[]
+    /** Más de una acción reclama ser la primaria. Solo una se usa. */
+    conflict: boolean
+}
+
+/** `placement: create`, o el flag declarativo para una acción que hoy es `table`. */
+export function actionReplacesCreate(action: ListActionRef): boolean {
+    return action.placement === 'create' || action.replaces_create === true || action.replacesCreate === true
+}
+
+function isToolbar(action: ListActionRef): boolean {
+    const placement = action.placement ?? 'row'
+    return placement === 'table' || placement === 'create' || actionReplacesCreate(action)
+}
+
+export function resolveListPrimaryAction(input: ListPrimaryActionInput): ListPrimaryActionResult {
+    const actions = input.actions ?? []
+    const claimants = actions.filter(actionReplacesCreate)
+
+    let primary: ListActionRef | undefined
+    if (input.primaryActionKey) {
+        const keyed = actions.find((a) => a.key === input.primaryActionKey)
+        if (keyed && isToolbar(keyed)) primary = keyed
+    }
+    if (!primary && claimants.length > 0) primary = claimants[0]
+
+    const hideGeneric =
+        input.hideCreate === true ||
+        input.canCreate === false ||
+        input.createMode === 'hidden' ||
+        input.createMode === 'action' ||
+        input.enableCRUD !== true ||
+        primary != null
+
+    return {
+        showGenericCreate: !hideGeneric,
+        primaryAction: primary,
+        secondaryActions: actions.filter((a) => isToolbar(a) && a.key !== primary?.key),
+        conflict: claimants.length > 1,
+    }
+}

package/src/model-action-toolbar.tsx

@@ -32,6 +32,7 @@ import {
     useRequiresAddonLabel,
 } from './requires-addon'
 import type { ActionDefinition, ActionMetadata, RequiresAddon, TableMetadata } from './types'
+import { resolveListPrimaryAction } from './list-primary-action'
 
 export type ActionPlacement = 'row' | 'table' | 'create'
 
@@ -58,6 +59,12 @@ export interface ModelActionToolbarProps {
      * lazy load without blocking first paint of the list page.
      */
     onActionIntent?: (action: ActionDefinition) => void
+    /**
+     * Acción que queda como único botón primario (`data-primary`). El resto de
+     * las que reclaman el alta bajan a `outline`. Lo resuelve igual
+     * `resolveListPrimaryAction`.
+     */
+    primaryActionKey?: string
 }
 
 const DEFAULT_PLACEMENTS: ActionPlacement[] = ['table', 'create']
@@ -139,6 +146,7 @@ export function ModelActionToolbar({
     onChange,
     className,
     onActionIntent,
+    primaryActionKey,
 }: ModelActionToolbarProps) {
     const { t } = useTranslation()
     const all = useModelActions(model, placements, actions)
@@ -153,6 +161,11 @@ export function ModelActionToolbar({
     const [missingAddon, setMissingAddon] = useState<RequiresAddon | null>(null)
     const requiresAddonLabel = useRequiresAddonLabel()
     const dataEndpoint = endpoint ?? `/data/${model}/me`
+    const primary = resolveListPrimaryAction({
+        enableCRUD: true,
+        primaryActionKey,
+        actions: surfaced,
+    })
 
     if (surfaced.length === 0) return null
 
@@ -160,16 +173,18 @@ export function ModelActionToolbar({
         <>
             <div className={className ?? 'flex items-center gap-2'}>
                 {surfaced.map((a) => {
-                    const isCreate = (a.placement ?? 'row') === 'create'
+                    const isPrimary = primary.primaryAction?.key === a.key
+                    const isCreate = isPrimary || (a.placement ?? 'row') === 'create'
                     // Locked while its optional addon is missing: still shown,
                     // but a click explains + offers install instead of running.
                     const requirement = resolveRequiresAddon(a)
                     return (
                         <Button
                             key={a.key}
-                            variant={isCreate ? 'default' : 'outline'}
+                            variant={isPrimary ? 'default' : 'outline'}
+                            data-primary={isPrimary ? 'true' : undefined}
                             data-aby-target={
-                                isCreate
+                                isPrimary
                                     ? `model.${model}.create`
                                     : `model.${model}.action.${a.key}`
                             }

package/src/model-extension-registry.tsx

@@ -24,6 +24,13 @@ export interface ModelExtension {
     headerExtras?: React.ComponentType<ModelExtensionProps>
     toolbarExtras?: React.ComponentType<ModelExtensionProps>
     hideCreate?: boolean
+    /**
+     * `hidden` quita el Crear genérico. `action` también, porque la acción del
+     * módulo (ver `primaryActionKey`) es la alta. `generic` lo deja.
+     */
+    createMode?: 'generic' | 'hidden' | 'action'
+    /** Acción de toolbar que queda como único botón primario y oculta el Crear genérico. */
+    primaryActionKey?: string
     hideExport?: boolean
     hideImport?: boolean
     hideRefresh?: boolean

package/src/types.ts

@@ -36,6 +36,13 @@ export interface TableMetadata {
     canExport?: boolean
     canImport?: boolean
     canCreate?: boolean
+    /**
+     * Cómo se pinta el alta genérica. `generic` (o ausente) es el botón Crear.
+     * `hidden` lo quita. `action` lo quita porque el módulo trae la suya
+     * (`placement: create` o `replaces_create`). Lo sirve el kernel; un host
+     * también puede fijarlo con `ModelExtension.createMode` sin cambio de kernel.
+     */
+    create_mode?: 'generic' | 'hidden' | 'action'
     /**
      * The model's spreadsheet-import declaration, served by the kernel: the
      * columns of the generated template and the headers accepted when parsing
@@ -702,6 +709,13 @@ export interface ActionDefinition {
      *   "create"        — toolbar button that replaces the generic create button.
      */
     placement?: 'row' | 'table' | 'create'
+    /**
+     * Esta acción de toolbar sustituye al Crear genérico aunque su `placement`
+     * sea `table`. El kernel tiene que reenviar el campo; si lo recorta, el
+     * host usa `ModelExtension.primaryActionKey` o `createMode`.
+     */
+    replaces_create?: boolean
+    replacesCreate?: boolean
     /**
      * Optional addon this action depends on, stamped by the host only while it
      * is NOT installed (served as `requires_addon`; read through

package/src/use-options-resolver.ts

@@ -27,6 +27,11 @@ export interface ResolvedOption {
     image?: string | null
     color?: string | null
     icon?: string | 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.
+     */
+    meta?: Record<string, unknown>
 }
 
 export interface OptionsMeta {
@@ -331,9 +336,18 @@ 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'])
+
 export function projectOption(raw: any): ResolvedOption {
     const id = raw?.id ?? raw?.value ?? ''
     const label = String(raw?.label ?? raw?.name ?? id ?? '')
+    const meta: Record<string, unknown> = {}
+    if (raw && typeof raw === 'object') {
+        for (const [k, v] of Object.entries(raw)) {
+            if (OPTION_KNOWN_KEYS.has(k)) continue
+            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') meta[k] = v
+        }
+    }
     return {
         id,
         value: raw?.value ?? id,
@@ -343,5 +357,6 @@ export function projectOption(raw: any): ResolvedOption {
         image: raw?.image ?? null,
         color: raw?.color ?? null,
         icon: raw?.icon ?? null,
+        ...(Object.keys(meta).length > 0 ? { meta } : {}),
     }
 }