@asteby/metacore-runtime-react 43.0.0 → 45.0.0

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,8 +11,10 @@
 //   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`.
-//   custom (fields/confirm/
-//   executable) action     → opens the ActionModal via the dispatcher.
+//   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).
 //
 // The host `onAction` contract is a STRING action key on purpose — the existing
@@ -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))
@@ -120,24 +129,20 @@ export function useDynamicRowActions({
             return
         }
         const actionDef = metadata?.actions?.find((a) => a.key === action)
-        // Open the dispatcher when there is ANY UI surface (fields, wizard
-        // steps, confirm bool, confirmMessage, or host `executable`). A
-        // confirm_message without confirm:true used to fall through / open and
-        // then render null — derive confirm so the ConfirmActionDialog path wins.
-        if (actionDef && (actionDef.fields?.length || actionDef.steps?.length || actionDef.confirm || actionDef.confirmMessage || actionDef.executable)) {
+        // Open the dispatcher when there is ANY UI surface (federated `modal`,
+        // fields, wizard steps, confirm bool, confirmMessage, or host
+        // `executable`). A confirm_message without confirm:true used to fall
+        // through / open and then render null — derive confirm so the
+        // ConfirmActionDialog path wins. Pass the WHOLE definition: a
+        // cherry-picked copy dropped `modal` and the dispatcher fell back to
+        // the generic confirm while the remote was still loading.
+        if (actionDef && (actionDef.modal || actionDef.fields?.length || actionDef.steps?.length || actionDef.confirm || actionDef.confirmMessage || actionDef.executable)) {
             setActionModal({
                 open: true,
                 action: {
-                    key: actionDef.key,
-                    label: actionDef.label,
+                    ...actionDef,
                     icon: actionDef.icon || 'Zap',
-                    color: actionDef.color,
                     confirm: !!(actionDef.confirm || actionDef.confirmMessage),
-                    confirmMessage: actionDef.confirmMessage,
-                    fields: actionDef.fields,
-                    steps: actionDef.steps,
-                    requiresState: actionDef.requiresState,
-                    executable: actionDef.executable,
                 },
                 record: row,
             })
@@ -204,6 +209,11 @@ export function useDynamicRowActions({
                     onSuccess={onRefresh}
                 />
             )}
+
+            <RequiresAddonDialog
+                requirement={missingAddon}
+                onOpenChange={(open: boolean) => !open && setMissingAddon(null)}
+            />
         </>
     )
 

package/src/federated-action-loader.ts

@@ -0,0 +1,40 @@
+// Host hook that loads the federated remote behind an action's `modal` slug.
+//
+// The SDK does not know how the host resolves addon remotes (Module Federation
+// manifests, fibers, lazy bundles). When ActionModalDispatcher opens an action
+// that declares `modal` and no component is registered yet, it asks the host to
+// load it through this hook and waits for the registry to report the component.
+// The dispatcher re-invokes the loader while it waits, so a loader installed
+// after the first click still gets called.
+
+export type FederatedActionLoader = (req: {
+    model: string
+    actionKey: string
+    modal?: string
+}) => void | Promise<void>
+
+let loader: FederatedActionLoader | null = null
+
+/** Install (or clear with `null`) the host's federated action loader. */
+export function setFederatedActionLoader(fn: FederatedActionLoader | null): void {
+    loader = fn
+}
+
+/**
+ * Ask the host to load the remote for (model, actionKey). No-op without a
+ * loader; loader errors are logged, never thrown — the dispatcher keeps waiting
+ * until its timeout and then shows the explicit error.
+ */
+export function requestFederatedAction(req: { model: string; actionKey: string; modal?: string }): void {
+    if (!loader) return
+    try {
+        const pending = loader(req)
+        if (pending && typeof (pending as Promise<void>).catch === 'function') {
+            ;(pending as Promise<void>).catch((err) => {
+                console.warn('[metacore] federated action loader failed', req, err)
+            })
+        }
+    } catch (err) {
+        console.warn('[metacore] federated action loader failed', req, err)
+    }
+}

package/src/index.ts

@@ -174,8 +174,10 @@ export * from './form-layout-ui'
 export { FieldGrid, FieldCell, FieldLabel } from './field-grid'
 export {
     ActionModalDispatcher,
+    FEDERATED_ACTION_MODAL_TIMEOUT_MS,
     type ActionModalProps,
 } from './action-modal-dispatcher'
+export { setFederatedActionLoader, type FederatedActionLoader } from './federated-action-loader'
 export {
     ModelActionToolbar,
     useModelActions,
@@ -221,6 +223,17 @@ export {
     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,

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'
 
@@ -83,18 +89,9 @@ export function humanizeActionLabel(label: string): string {
 }
 
 function toActionMetadata(a: ActionDefinition): ActionMetadata {
-    return {
-        key: a.key,
-        label: a.label,
-        icon: a.icon || 'Zap',
-        color: a.color,
-        confirm: a.confirm,
-        confirmMessage: a.confirmMessage,
-        fields: a.fields,
-        requiresState: a.requiresState,
-        executable: a.executable,
-        placement: a.placement,
-    }
+    // Spread, don't cherry-pick: a hand-picked copy dropped `modal`/`steps`
+    // and the dispatcher fell back to generics for federated/wizard actions.
+    return { ...a, icon: a.icon || 'Zap' }
 }
 
 /**
@@ -153,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
@@ -162,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}
@@ -171,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" />
@@ -188,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>
                     )
                 })}
@@ -209,6 +218,13 @@ export function ModelActionToolbar({
                     }}
                 />
             )}
+
+            <RequiresAddonDialog
+                requirement={missingAddon}
+                onOpenChange={(open) => {
+                    if (!open) setMissingAddon(null)
+                }}
+            />
         </>
     )
 }

package/src/requires-addon.tsx

@@ -0,0 +1,160 @@
+// requiresAddon — an action that depends on an OPTIONAL addon the org has not
+// installed yet (e.g. link_inbox "Conectar WhatsApp" needs connector_whatsapp).
+//
+// The manifest declares `compatibility.requires[].enables: ["action:<Model>.<key>"]`
+// and the host stamps each affected action's metadata, only while the required
+// addon is missing:
+//
+//   "requires_addon": { "key": "connector_whatsapp", "name": "Conector WhatsApp", "reason": "…" }
+//
+// The action is NOT hidden (the user should discover the feature) and NOT
+// executed: row menus / kanban cards / the model toolbar render it with a lock
+// and a tooltip, and a click opens <RequiresAddonDialog> instead of the action
+// dispatcher. "Instalar" delegates to the host (setAddonInstallHandler) or, when
+// none is registered, navigates to `/marketplace/<key>` through the SDK router so
+// the host basepath (ops lives under /app) is respected.
+import { useNavigate } from '@tanstack/react-router'
+import { useTranslation } from 'react-i18next'
+import { Lock } from 'lucide-react'
+import {
+    AlertDialog,
+    AlertDialogAction,
+    AlertDialogCancel,
+    AlertDialogContent,
+    AlertDialogDescription,
+    AlertDialogFooter,
+    AlertDialogHeader,
+    AlertDialogTitle,
+} from '@asteby/metacore-ui/primitives'
+import type { RequiresAddon } from './types'
+
+export type { RequiresAddon }
+
+/**
+ * Reads the addon requirement off an action, tolerating both the camelCase
+ * `requiresAddon` and the snake_case `requires_addon` the host serves. Returns
+ * null when the action is freely executable (no requirement, or a malformed one
+ * without a `key` — degrade to "runs", never to "locked forever").
+ */
+export function resolveRequiresAddon(action: any): RequiresAddon | null {
+    const raw = action?.requiresAddon ?? action?.requires_addon
+    if (!raw || typeof raw !== 'object') return null
+    const key = typeof raw.key === 'string' ? raw.key.trim() : ''
+    if (!key) return null
+    const out: RequiresAddon = { key }
+    if (typeof raw.name === 'string' && raw.name) out.name = raw.name
+    if (typeof raw.reason === 'string' && raw.reason) out.reason = raw.reason
+    return out
+}
+
+type AddonInstallHandler = (key: string) => void
+
+let installHandler: AddonInstallHandler | null = null
+
+/**
+ * Registers the host's "install this addon" flow (e.g. open the marketplace
+ * install drawer). Pass `null` to unregister. Without a handler the SDK
+ * navigates to `/marketplace/<key>` via the router.
+ */
+export function setAddonInstallHandler(fn: AddonInstallHandler | null): void {
+    installHandler = fn
+}
+
+/** Current host install handler, or null when none is registered. */
+export function getAddonInstallHandler(): AddonInstallHandler | null {
+    return installHandler
+}
+
+/** Display name for a requirement: the host-provided name, else the key. */
+export function requiresAddonName(req: RequiresAddon): string {
+    return req.name || req.key
+}
+
+/** Tooltip text for a gated action: "Requiere «<name>»". */
+export function useRequiresAddonLabel(): (req: RequiresAddon) => string {
+    const { t } = useTranslation()
+    return (req) =>
+        t('dynamic.requires_addon_badge', {
+            defaultValue: 'Requiere «{{name}}»',
+            name: requiresAddonName(req),
+        })
+}
+
+/** Lock marker rendered next to a gated action's label (hover = addon name). */
+export function RequiresAddonLock({ requirement }: { requirement: RequiresAddon }) {
+    const label = useRequiresAddonLabel()(requirement)
+    return (
+        <span
+            className="ml-auto inline-flex shrink-0 items-center pl-2 text-muted-foreground"
+            title={label}
+            aria-label={label}
+            data-requires-addon={requirement.key}
+        >
+            <Lock className="h-3.5 w-3.5" />
+        </span>
+    )
+}
+
+export interface RequiresAddonDialogProps {
+    /** The requirement to explain; the dialog renders nothing while null. */
+    requirement: RequiresAddon | null
+    onOpenChange: (open: boolean) => void
+}
+
+/**
+ * Compact "this action requires <addon>" dialog. Never touches the backend:
+ * "Instalar" hands the key to the host handler or routes to the marketplace.
+ */
+export function RequiresAddonDialog({ requirement, onOpenChange }: RequiresAddonDialogProps) {
+    const { t } = useTranslation()
+    const navigate = useNavigate()
+    if (!requirement) return null
+    const name = requiresAddonName(requirement)
+
+    const install = () => {
+        onOpenChange(false)
+        const handler = installHandler
+        if (handler) handler(requirement.key)
+        else navigate({ to: `/marketplace/${encodeURIComponent(requirement.key)}` })
+    }
+
+    return (
+        <AlertDialog open onOpenChange={onOpenChange}>
+            <AlertDialogContent className="sm:max-w-md">
+                <AlertDialogHeader>
+                    <AlertDialogTitle className="flex items-center gap-2">
+                        <Lock className="h-4 w-4 shrink-0 text-muted-foreground" />
+                        {t('dynamic.requires_addon_title', {
+                            defaultValue: 'Esta acción requiere «{{name}}»',
+                            name,
+                        })}
+                    </AlertDialogTitle>
+                    <AlertDialogDescription>
+                        {requirement.reason
+                            ? t(requirement.reason, { defaultValue: requirement.reason })
+                            : t('dynamic.requires_addon_description', {
+                                  defaultValue: 'Instala «{{name}}» para habilitar esta acción.',
+                                  name,
+                              })}
+                    </AlertDialogDescription>
+                </AlertDialogHeader>
+                <AlertDialogFooter>
+                    <AlertDialogCancel>
+                        {t('dynamic.requires_addon_cancel', { defaultValue: 'Cancelar' })}
+                    </AlertDialogCancel>
+                    <AlertDialogAction
+                        onClick={(e: React.MouseEvent) => {
+                            e.preventDefault()
+                            install()
+                        }}
+                    >
+                        {t('dynamic.requires_addon_install', {
+                            defaultValue: 'Instalar «{{name}}»',
+                            name,
+                        })}
+                    </AlertDialogAction>
+                </AlertDialogFooter>
+            </AlertDialogContent>
+        </AlertDialog>
+    )
+}

package/src/types.ts

@@ -654,6 +654,16 @@ export interface FieldOptionsConfig {
     image?: string
 }
 
+/** An optional addon an action needs before it can run. */
+export interface RequiresAddon {
+    /** Addon key, e.g. "connector_whatsapp". */
+    key: string
+    /** Localized display name, e.g. "Conector WhatsApp". Falls back to `key`. */
+    name?: string
+    /** Why the action needs it (literal or i18n key). */
+    reason?: string
+}
+
 export interface ActionDefinition {
     key: string
     name: string
@@ -671,6 +681,8 @@ export interface ActionDefinition {
     steps?: ActionStep[]
     requiresState?: string[]
     executable?: boolean
+    /** Federated modal slug "<addon_key>.<action_key>" (manifest `modal`). */
+    modal?: string
     /**
      * Where the host surfaces the trigger. Mirrors manifest/v3 Action.placement.
      *   "row" (default) — per-row table action.
@@ -678,6 +690,13 @@ export interface ActionDefinition {
      *   "create"        — toolbar button that replaces the generic create button.
      */
     placement?: 'row' | 'table' | 'create'
+    /**
+     * Optional addon this action depends on, stamped by the host only while it
+     * is NOT installed (served as `requires_addon`; read through
+     * resolveRequiresAddon). The action stays visible but locked: a click opens
+     * the "requires addon" dialog instead of executing.
+     */
+    requiresAddon?: RequiresAddon
 }
 
 export interface ApiResponse<T> {
@@ -719,5 +738,14 @@ export interface ActionMetadata {
     steps?: ActionStep[]
     requiresState?: string[]
     executable?: boolean
+    /** Federated modal slug "<addon_key>.<action_key>"; see ActionModalDispatcher. */
+    modal?: string
     placement?: 'row' | 'table' | 'create'
+    /**
+     * Optional addon this action depends on, stamped by the host only while it
+     * is NOT installed (served as `requires_addon`; read through
+     * resolveRequiresAddon). The action stays visible but locked: a click opens
+     * the "requires addon" dialog instead of executing.
+     */
+    requiresAddon?: RequiresAddon
 }