@asteby/metacore-runtime-react 44.0.0 → 45.2.0

package/src/document/smart-buttons.tsx

@@ -0,0 +1,54 @@
+// SmartButtons — accesos con contador al estilo Odoo (Pagos (2) · REP (1) ·
+// Notas de crédito (0)…). Un botón sin registros se ve atenuado, no oculto,
+// salvo que la definición pida `hideWhenEmpty`.
+import { useTranslation } from 'react-i18next'
+import { cn } from '@asteby/metacore-ui/lib'
+import { DynamicIcon } from '../dynamic-icon'
+
+export interface SmartButtonItem {
+    key: string
+    label: string
+    icon?: string
+    /** undefined = botón sin contador (p. ej. «Pedido origen»). */
+    count?: number
+    /** Deshabilitado (sin destino / vacío). */
+    disabled?: boolean
+    onClick?: () => void
+}
+
+export interface SmartButtonsProps {
+    items: SmartButtonItem[]
+    className?: string
+}
+
+export function SmartButtons({ items, className }: SmartButtonsProps) {
+    const { t } = useTranslation()
+    if (items.length === 0) return null
+    return (
+        <nav aria-label={t('document.related', { defaultValue: 'Relacionados' })} className={cn('flex flex-wrap gap-2', className)} data-smart-buttons=''>
+            {items.map((it) => {
+                const empty = it.count === 0
+                return (
+                    <button
+                        key={it.key}
+                        type='button'
+                        disabled={it.disabled}
+                        onClick={it.onClick}
+                        data-smart-button={it.key}
+                        className={cn(
+                            'inline-flex items-center gap-2 rounded-md border bg-card px-3 py-1.5 text-sm transition-colors',
+                            'hover:bg-accent disabled:cursor-default disabled:opacity-50 disabled:hover:bg-card',
+                            empty && 'text-muted-foreground',
+                        )}
+                    >
+                        {it.icon ? <DynamicIcon name={it.icon} className='h-4 w-4' /> : null}
+                        <span>{t(it.label, { defaultValue: it.label })}</span>
+                        {it.count !== undefined ? (
+                            <span className='rounded-full bg-muted px-1.5 text-xs font-semibold tabular-nums'>{it.count}</span>
+                        ) : null}
+                    </button>
+                )
+            })}
+        </nav>
+    )
+}

package/src/document/status-badge.tsx

@@ -0,0 +1,44 @@
+// StatusBadge — badge semántico con texto explícito e ícono por tono: el color
+// nunca es la única señal (benchmark §6.3). El catálogo de estados de cada
+// documento vive en su `StatusMachine`; aquí solo se pinta.
+import { useTranslation } from 'react-i18next'
+import { AlertOctagon, AlertTriangle, CheckCircle2, Circle, Clock, Info, type LucideIcon } from 'lucide-react'
+import { Badge } from '@asteby/metacore-ui/primitives'
+import { cn } from '@asteby/metacore-ui/lib'
+import type { StatusDef, StatusTone } from './types'
+
+type BadgeVariant = 'muted' | 'info' | 'success' | 'warning' | 'danger'
+
+export const STATUS_TONE_STYLE: Record<StatusTone, { variant: BadgeVariant; icon: LucideIcon }> = {
+    neutral: { variant: 'muted', icon: Circle },
+    info: { variant: 'info', icon: Info },
+    success: { variant: 'success', icon: CheckCircle2 },
+    caution: { variant: 'warning', icon: Clock },
+    warning: { variant: 'warning', icon: AlertTriangle },
+    critical: { variant: 'danger', icon: AlertOctagon },
+}
+
+export interface StatusBadgeProps {
+    status: Pick<StatusDef, 'label' | 'tone' | 'strike'>
+    /** Descripción para lectores de pantalla («Estado fiscal»). */
+    srLabel?: string
+    className?: string
+}
+
+export function StatusBadge({ status, srLabel, className }: StatusBadgeProps) {
+    const { t } = useTranslation()
+    const style = STATUS_TONE_STYLE[status.tone] ?? STATUS_TONE_STYLE.neutral
+    const Icon = style.icon
+    const text = t(status.label, { defaultValue: status.label })
+    return (
+        <Badge
+            variant={style.variant}
+            data-tone={status.tone}
+            className={cn(status.strike && 'line-through', className)}
+        >
+            <Icon aria-hidden />
+            {srLabel ? <span className='sr-only'>{srLabel}: </span> : null}
+            {text}
+        </Badge>
+    )
+}

package/src/document/types.ts

@@ -0,0 +1,203 @@
+// Patrón «página de documento» (benchmark §5.2 / §6 / §7): cabecera con badges,
+// barra de acciones por estado, botones inteligentes con contador, pestañas e
+// historial. Todo se describe con un `DocumentSpec` de datos puros (sin
+// funciones) para que cualquier modelo lo declare y, más adelante, un manifest
+// pueda proyectarlo sin cambiar los componentes.
+import type { ReactNode } from 'react'
+
+/** Tono semántico de un estado. El color nunca es la única señal: cada tono trae ícono y texto. */
+export type StatusTone = 'neutral' | 'info' | 'success' | 'caution' | 'warning' | 'critical'
+
+/** Un estado del catálogo de un documento. */
+export interface StatusDef {
+    value: string
+    /** Texto explícito (o clave i18n; se traduce con `t`). */
+    label: string
+    tone: StatusTone
+    /** Texto tachado (Cancelada, Anulada): conserva el rastro sin alarmar. */
+    strike?: boolean
+}
+
+/** Una máquina de estados con su propio badge (p. ej. fiscal y cobro, independientes). */
+export interface StatusMachine {
+    id: string
+    /** Etiqueta accesible del badge («Estado fiscal»). */
+    label?: string
+    /** Ruta del valor en el contexto de evaluación (`record.x`, `$.x`). */
+    field: string
+    states: StatusDef[]
+    /** Estado a mostrar cuando el valor no está en el catálogo. */
+    fallback?: StatusDef
+}
+
+export type PredicateOp = 'eq' | 'neq' | 'in' | 'not_in' | 'truthy' | 'falsy' | 'gt' | 'gte' | 'lt' | 'lte'
+
+/** Condición sobre una ruta del contexto. Un arreglo de predicados es un AND. */
+export interface Predicate {
+    field: string
+    op: PredicateOp
+    value?: unknown
+}
+export type When = Predicate | Predicate[]
+
+/** Regla de bloqueo: si `when` se cumple, la acción se ve deshabilitada y `reason` explica qué hacer antes. */
+export interface BlockRule {
+    when: When
+    reason: string
+}
+
+/** Un botón del documento (acción). `key` enlaza con `ActionDefinition.key` del modelo si existe. */
+export interface DocumentActionDef {
+    key: string
+    label: string
+    /** Nombre de ícono lucide. */
+    icon?: string
+    /** Acción del modelo (metadata) que se dispara; por defecto `key`. */
+    modelAction?: string
+    /**
+     * Acciones que resuelve la propia página sin acción del modelo (las plantillas
+     * interpolan `{{campo}}` / `{{$.derivado}}`):
+     *  - `href`: navega dentro de la app (`onNavigate` del host).
+     *  - `openUrl`: abre una URL en otra pestaña (descargar PDF/XML).
+     *  - `tab`: selecciona una pestaña (ver detalle del error, ver pagos).
+     */
+    href?: string
+    openUrl?: string
+    tab?: string
+    /** Estilo crítico: siempre va en la zona destructiva. */
+    destructive?: boolean
+    /** Se muestra deshabilitada con el motivo en lugar de desaparecer. */
+    blockedWhen?: BlockRule | BlockRule[]
+    /** Se oculta por completo cuando se cumple (p. ej. sin permiso o sin conector). */
+    hiddenWhen?: When
+}
+
+/** Distribución de acciones para un estado (§5.4): 1 primaria, 2–3 secundarias, resto en «Más…». */
+export interface ActionLayout {
+    primary?: string
+    secondary?: string[]
+    more?: string[]
+    destructive?: string[]
+}
+
+/** Regla: si `when` se cumple, se usa `layout`. Gana la primera que coincide. */
+export interface ActionLayoutRule {
+    when: When
+    layout: ActionLayout
+}
+
+/** Botón inteligente con contador (estilo Odoo): navega a lo relacionado. */
+export interface SmartButtonDef {
+    key: string
+    label: string
+    icon?: string
+    /** Fuente (`DocumentSourceDef.key`) cuyo total alimenta el contador; sin ella no hay contador. */
+    source?: string
+    /** Ruta de un valor del registro cuyo truthy activa el botón sin fuente (p. ej. «Pedido origen»). */
+    field?: string
+    /** Modelo destino para navegar a la lista filtrada. */
+    href?: string
+    /** No se muestra cuando el contador es 0 (por defecto se muestra deshabilitado). */
+    hideWhenEmpty?: boolean
+    /** Selecciona esta pestaña al hacer clic. */
+    tab?: string
+}
+
+/** Consulta a un modelo relacionado con el registro (`{{id}}` se interpola). */
+export interface DocumentSourceDef {
+    key: string
+    model: string
+    /** Columna del modelo relacionado que apunta al registro. */
+    foreignKey: string
+    /** Filtros estáticos extra (`f_<col>=eq:<val>`). */
+    where?: Record<string, string>
+    limit?: number
+    /**
+     * Relación de dos saltos: en vez de filtrar por el id del registro, filtra
+     * `foreignKey` con los valores de `field` de las filas de otra fuente ya
+     * cargada (`via.source`). Ej.: los REP de una factura cuelgan del pago
+     * (`source_id = payment_id`), y los pagos salen de las aplicaciones.
+     */
+    via?: { source: string; field: string }
+}
+
+export interface DocumentFieldDef {
+    label: string
+    /** Ruta en el contexto. */
+    path: string
+    format?: 'text' | 'money' | 'date' | 'datetime' | 'mono' | 'percent' | 'boolean'
+    /** Ancho completo de la rejilla. */
+    wide?: boolean
+    /** Oculta el campo cuando el valor está vacío. */
+    hideEmpty?: boolean
+}
+
+export interface DocumentFieldGroup {
+    title?: string
+    fields: DocumentFieldDef[]
+}
+
+export interface DocumentColumnDef {
+    label: string
+    path: string
+    format?: DocumentFieldDef['format']
+    /** Catálogo de estados (id de máquina registrada) para pintar un badge. */
+    status?: string
+}
+
+export type DocumentTabDef =
+    | { key: string; label: string; kind: 'fields'; groups: DocumentFieldGroup[] }
+    | { key: string; label: string; kind: 'records'; source: string; columns: DocumentColumnDef[]; empty?: string }
+    | { key: string; label: string; kind: 'slot'; slot: string; count?: string }
+
+/** Métrica del encabezado (total, saldo, fechas…). */
+export interface DocumentMetricDef extends DocumentFieldDef {
+    tone?: 'default' | 'critical'
+}
+
+export interface DocumentSpec {
+    /** Clave del modelo (`invoices`). */
+    model: string
+    /** Rutas candidatas para el título, en orden; `{{a}}{{b}}` se interpola. */
+    title: string
+    /** Texto bajo el título (cliente…). */
+    subtitle?: DocumentFieldDef
+    /** Campo que se copia con botón (UUID). */
+    copyable?: DocumentFieldDef
+    /** Badges independientes (fiscal, cobro…). */
+    statuses: StatusMachine[]
+    /** Catálogos extra que solo pintan celdas de pestañas (`column.status`), sin badge en la cabecera. */
+    catalogs?: StatusMachine[]
+    metrics?: DocumentMetricDef[]
+    actions: DocumentActionDef[]
+    layouts: ActionLayoutRule[]
+    /** Layout si ninguna regla coincide. */
+    defaultLayout?: ActionLayout
+    smartButtons?: SmartButtonDef[]
+    sources?: DocumentSourceDef[]
+    tabs: DocumentTabDef[]
+}
+
+/** Contexto de evaluación: registro, fuentes cargadas y derivados. */
+export interface DocumentContext {
+    record: Record<string, unknown>
+    /** Filas por fuente (`sources[key]`). */
+    sources: Record<string, Record<string, unknown>[]>
+    /** Derivados (`$`). */
+    derived: Record<string, unknown>
+}
+
+export interface ResolvedAction {
+    def: DocumentActionDef
+    /** Motivo cuando la acción está bloqueada. */
+    blockedReason?: string
+}
+
+export interface ResolvedActionLayout {
+    primary?: ResolvedAction
+    secondary: ResolvedAction[]
+    more: ResolvedAction[]
+    destructive: ResolvedAction[]
+}
+
+export type DocumentSlotRenderer = (ctx: DocumentContext) => ReactNode

package/src/document/use-document-sources.ts

@@ -0,0 +1,91 @@
+import { useCallback, useEffect, useState } from 'react'
+import { useApi } from '../api-context'
+import { buildRelationFilterParams } from '../dynamic-relation-helpers'
+import type { DocumentSourceDef } from './types'
+
+const DEFAULT_LIMIT = 50
+// El kernel ≥ 0.139.2 acepta listas `in:` largas; se parte para no exceder la URL.
+const VIA_CHUNK = 40
+
+type Rows = Record<string, unknown>[]
+
+export interface DocumentSourcesState {
+    sources: Record<string, Record<string, unknown>[]>
+    loading: boolean
+    /** Vuelve a pedir todas las fuentes (tras ejecutar una acción). */
+    reload: () => void
+}
+
+/**
+ * Carga las filas relacionadas con el documento (pagos, REP, notas de crédito…)
+ * que alimentan contadores, pestañas y derivados. Un fallo en una fuente deja
+ * esa fuente vacía: la página sigue siendo usable.
+ */
+export function useDocumentSources(
+    defs: DocumentSourceDef[] | undefined,
+    recordId: string | number | undefined,
+): DocumentSourcesState {
+    const api = useApi()
+    const [sources, setSources] = useState<Record<string, Record<string, unknown>[]>>({})
+    const [loading, setLoading] = useState(false)
+    const [nonce, setNonce] = useState(0)
+    const reload = useCallback(() => setNonce((n) => n + 1), [])
+
+    useEffect(() => {
+        if (!defs || defs.length === 0 || recordId === undefined || recordId === null) {
+            setSources({})
+            return
+        }
+        let cancelled = false
+        setLoading(true)
+        const fetchRows = async (d: DocumentSourceDef, params: Record<string, string>): Promise<Rows> => {
+            try {
+                const res = await api.get(`/data/${d.model}`, {
+                    params: { ...params, page: 1, per_page: d.limit ?? DEFAULT_LIMIT },
+                })
+                const body = res.data
+                const rows = (body?.data ?? body) as unknown
+                return Array.isArray(rows) ? (rows as Rows) : []
+            } catch {
+                return []
+            }
+        }
+        const direct = defs.filter((d) => !d.via)
+        const hopped = defs.filter((d) => d.via)
+        ;(async () => {
+            const out: Record<string, Rows> = {}
+            await Promise.all(
+                direct.map(async (d) => {
+                    out[d.key] = await fetchRows(d, buildRelationFilterParams(d.foreignKey, recordId, d.where))
+                }),
+            )
+            // Segundo salto: depende de las filas del primero.
+            for (const d of hopped) {
+                const ids = Array.from(
+                    new Set((out[d.via!.source] ?? []).map((r) => r[d.via!.field]).filter((v) => v != null && v !== '').map(String)),
+                )
+                const chunks: string[][] = []
+                for (let i = 0; i < ids.length; i += VIA_CHUNK) chunks.push(ids.slice(i, i + VIA_CHUNK))
+                const parts = await Promise.all(
+                    chunks.map((c) => {
+                        const params: Record<string, string> = { [`f_${d.foreignKey}`]: `in:${c.join(',')}` }
+                        for (const [k, v] of Object.entries(d.where ?? {})) params[`f_${k}`] = `eq:${v}`
+                        return fetchRows(d, params)
+                    }),
+                )
+                out[d.key] = parts.flat()
+            }
+            return out
+        })()
+            .then((out) => {
+                if (cancelled) return
+                setSources(out)
+                setLoading(false)
+            })
+        return () => {
+            cancelled = true
+        }
+    }, [api, defs, recordId, nonce])
+
+    return { sources, loading, reload }
+}

package/src/dynamic-columns.tsx

@@ -57,6 +57,7 @@ import { DynamicIcon, isLucideIconName } from './dynamic-icon'
 import { CollectionCell } from './collection-cell'
 import { isNilUuid, normalizeNilUuid } from './nil-uuid'
 import { useOptionsResolver } from './use-options-resolver'
+import { RequiresAddonLock, resolveRequiresAddon, useRequiresAddonLabel } from './requires-addon'
 import type { TableMetadata, ColumnDefinition } from './types'
 import { isColumnVisibleInTable } from './column-visibility'
 import type {
@@ -207,6 +208,36 @@ const CodeCell: React.FC<{ text: string; maxLength?: number }> = ({ text, maxLen
     )
 }
 
+/**
+ * One entry of the row "…" menu. An action gated by a missing optional addon
+ * (`requiresAddon`) stays listed with a lock + tooltip; the click still goes to
+ * `onAction`, whose shared handler (useDynamicRowActions) opens the
+ * requires-addon dialog instead of executing.
+ */
+export function RowActionMenuItem({
+    action,
+    label,
+    onSelect,
+}: {
+    action: any
+    label: React.ReactNode
+    onSelect: (e: React.MouseEvent) => void
+}) {
+    const requirement = resolveRequiresAddon(action)
+    const requiresAddonLabel = useRequiresAddonLabel()
+    return (
+        <DropdownMenuItem
+            onClick={onSelect}
+            title={requirement ? requiresAddonLabel(requirement) : undefined}
+            data-requires-addon={requirement?.key}
+        >
+            <DynamicIcon name={action.icon || 'Zap'} className="mr-2 h-4 w-4" />
+            {label}
+            {requirement && <RequiresAddonLock requirement={requirement} />}
+        </DropdownMenuItem>
+    )
+}
+
 /**
  * Lifecycle column used by `requiresState`: prefer `status` (workshop, vehicles,
  * …) and fall back to `state` (purchases, inventory transfers, …). Empty string
@@ -1528,13 +1559,12 @@ export function makeDefaultGetDynamicColumns(
                                 {resolvedActions
                                     .filter((action) => isRowActionVisible(action, row.original))
                                     .map((action) => (
-                                        <DropdownMenuItem
+                                        <RowActionMenuItem
                                             key={action.key}
-                                            onClick={() => onAction && onAction(action.key, row.original)}
-                                        >
-                                            <DynamicIcon name={action.icon} className="mr-2 h-4 w-4" />
-                                            {translateMetadataLabel(action.label, t)}
-                                        </DropdownMenuItem>
+                                            action={action}
+                                            label={translateMetadataLabel(action.label, t)}
+                                            onSelect={() => onAction && onAction(action.key, row.original)}
+                                        />
                                     ))}
                             </DropdownMenuContent>
                         </DropdownMenu>

package/src/dynamic-kanban.tsx

@@ -96,7 +96,6 @@ import {
     CardContent,
     DropdownMenu,
     DropdownMenuContent,
-    DropdownMenuItem,
     DropdownMenuTrigger,
     Input,
     Popover,
@@ -161,6 +160,7 @@ import {
     formatAggregateTotal,
     isRowActionVisible,
     relationKeyFor,
+    RowActionMenuItem,
 } from './dynamic-columns'
 import { useCan, usePermissionsActive, resolveRowActions } from './permissions-context'
 import { useDynamicRowActions } from './dynamic-row-actions'
@@ -3113,16 +3113,15 @@ function KanbanCard({
                 </DropdownMenuTrigger>
                 <DropdownMenuContent align="end" onClick={(e) => e.stopPropagation()}>
                     {visibleActions.map((a) => (
-                        <DropdownMenuItem
+                        <RowActionMenuItem
                             key={a.key}
-                            onClick={(e) => {
+                            action={a}
+                            label={a.label}
+                            onSelect={(e) => {
                                 e.stopPropagation()
                                 onAction(a.key, card)
                             }}
-                        >
-                            <DynamicIcon name={a.icon || 'Zap'} className="mr-2 h-4 w-4" />
-                            {a.label}
-                        </DropdownMenuItem>
+                        />
                     ))}
                 </DropdownMenuContent>
             </DropdownMenu>

package/src/dynamic-row-actions.tsx

@@ -11,6 +11,8 @@
 //   view / edit            → host `onAction(action, row)` when provided (string
 //                            contract), else the built-in record dialog.
 //   link action            → navigate to the action's templated `linkUrl`.
+//   requiresAddon          → opens the "requires addon" dialog; the action is
+//                            never dispatched (no modal, no backend call).
 //   custom (modal/fields/
 //   confirm/executable)    → opens the ActionModal via the dispatcher.
 //   anything else          → host `onAction` + refresh (or just refresh).
@@ -34,7 +36,8 @@ import {
 import { useApi } from './api-context'
 import { ActionModalDispatcher } from './action-modal-dispatcher'
 import { DynamicRecordDialog } from './dialogs/dynamic-record'
-import type { TableMetadata, ActionMetadata } from './types'
+import { RequiresAddonDialog, resolveRequiresAddon } from './requires-addon'
+import type { TableMetadata, ActionMetadata, RequiresAddon } from './types'
 
 export interface UseDynamicRowActionsParams {
     /** Model key as registered on the backend (e.g. "issue"). */
@@ -106,7 +109,13 @@ export function useDynamicRowActions({
         record: any | null
     }>({ open: false, action: null, record: null })
 
+    const [missingAddon, setMissingAddon] = useState<RequiresAddon | null>(null)
+
     const handleInternalAction = useCallback(async (action: string, row: any) => {
+        // A missing optional addon gates the action BEFORE any other routing:
+        // it must not reach the dispatcher, the host, or the backend.
+        const requirement = resolveRequiresAddon(metadata?.actions?.find((a) => a.key === action))
+        if (requirement) { setMissingAddon(requirement); return }
         if (action === 'delete') { setRowToDelete(row); return }
         if (action === 'view' || action === 'edit') {
             if (onAction) await Promise.resolve(onAction(action, row))
@@ -200,6 +209,11 @@ export function useDynamicRowActions({
                     onSuccess={onRefresh}
                 />
             )}
+
+            <RequiresAddonDialog
+                requirement={missingAddon}
+                onOpenChange={(open: boolean) => !open && setMissingAddon(null)}
+            />
         </>
     )
 

package/src/index.ts

@@ -218,11 +218,41 @@ export {
     type CanFn,
     type PermissionsProviderProps,
 } from './permissions-context'
+export {
+    ApprovalPinDialog,
+    approvalErrorMessage,
+    type ApprovalPinDialogProps,
+    type ApprovalPinSubmit,
+} from './approval-pin-dialog'
+export {
+    ApprovalGateProvider,
+    useApprovalGate,
+    approvalCapability,
+    approvalRequiredInfo,
+    approvalGateAvailable,
+    APPROVAL_PARKED_EVENT,
+    APPROVAL_DECIDED_EVENT,
+    type ApprovalGateValue,
+    type ApprovalGrant,
+    type ApprovalRequiredInfo,
+    type RequestApprovalOptions,
+} from './approval-gate'
 export {
     useDynamicRowActions,
     type UseDynamicRowActionsParams,
     type DynamicRowActions,
 } from './dynamic-row-actions'
+export {
+    resolveRequiresAddon,
+    setAddonInstallHandler,
+    getAddonInstallHandler,
+    requiresAddonName,
+    useRequiresAddonLabel,
+    RequiresAddonLock,
+    RequiresAddonDialog,
+    type RequiresAddon,
+    type RequiresAddonDialogProps,
+} from './requires-addon'
 export { ColorPickerField, DEFAULT_ROLE_COLOR, normalizeHex } from './color-picker-field'
 export {
     PermissionsManager,
@@ -271,6 +301,7 @@ export {
     type SidebarLayoutManagerProps,
 } from './sidebar-layout-manager'
 export * from './org-runtime-context'
+export * from './business'
 export * from './org-runtime-provider'
 export * from './navigation-builder'
 export * from './i18n-provider'
@@ -570,3 +601,6 @@ export {
     type AttributeClass,
     type AttributeClassSection,
 } from './attribute-classes'
+
+// Página de documento (benchmark §5/§6): cabecera, badges, acciones por estado, botones inteligentes.
+export * from './document'

package/src/model-action-toolbar.tsx

@@ -25,7 +25,13 @@ import { useMetadataCache } from './metadata-cache'
 import { DynamicIcon } from './dynamic-icon'
 import { ActionModalDispatcher } from './action-modal-dispatcher'
 import { useCan, modelCapability } from './permissions-context'
-import type { ActionDefinition, ActionMetadata, TableMetadata } from './types'
+import {
+    RequiresAddonDialog,
+    RequiresAddonLock,
+    resolveRequiresAddon,
+    useRequiresAddonLabel,
+} from './requires-addon'
+import type { ActionDefinition, ActionMetadata, RequiresAddon, TableMetadata } from './types'
 
 export type ActionPlacement = 'row' | 'table' | 'create'
 
@@ -144,6 +150,8 @@ export function ModelActionToolbar({
         [all, can, model],
     )
     const [active, setActive] = useState<ActionMetadata | null>(null)
+    const [missingAddon, setMissingAddon] = useState<RequiresAddon | null>(null)
+    const requiresAddonLabel = useRequiresAddonLabel()
     const dataEndpoint = endpoint ?? `/data/${model}/me`
 
     if (surfaced.length === 0) return null
@@ -153,6 +161,9 @@ export function ModelActionToolbar({
             <div className={className ?? 'flex items-center gap-2'}>
                 {surfaced.map((a) => {
                     const isCreate = (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}
@@ -162,12 +173,18 @@ export function ModelActionToolbar({
                                     ? `model.${model}.create`
                                     : `model.${model}.action.${a.key}`
                             }
+                            data-requires-addon={requirement?.key}
+                            title={requirement ? requiresAddonLabel(requirement) : undefined}
                             onClick={() => {
+                                if (requirement) {
+                                    setMissingAddon(requirement)
+                                    return
+                                }
                                 onActionIntent?.(a)
                                 setActive(toActionMetadata(a))
                             }}
-                            onMouseEnter={() => onActionIntent?.(a)}
-                            onFocus={() => onActionIntent?.(a)}
+                            onMouseEnter={() => !requirement && onActionIntent?.(a)}
+                            onFocus={() => !requirement && onActionIntent?.(a)}
                             style={a.color && !isCreate ? { borderColor: a.color, color: a.color } : undefined}
                         >
                             <DynamicIcon name={a.icon || (isCreate ? 'Plus' : 'Zap')} className="mr-2 h-4 w-4" />
@@ -179,6 +196,7 @@ export function ModelActionToolbar({
                                 already-localized label untouched; humanizeLastSegment avoids
                                 flashing the full dotted key when the bundle is still in flight. */}
                             {t(a.label, { defaultValue: humanizeActionLabel(a.label) })}
+                            {requirement && <RequiresAddonLock requirement={requirement} />}
                         </Button>
                     )
                 })}
@@ -200,6 +218,13 @@ export function ModelActionToolbar({
                     }}
                 />
             )}
+
+            <RequiresAddonDialog
+                requirement={missingAddon}
+                onOpenChange={(open) => {
+                    if (!open) setMissingAddon(null)
+                }}
+            />
         </>
     )
 }