@asteby/metacore-runtime-react 43.0.0 → 45.0.0

package/src/__tests__/federated-action-modal.test.tsx

@@ -0,0 +1,315 @@
+// @vitest-environment happy-dom
+//
+// Federated action modals are deterministic: an action that declares
+// `modal: "<addon>.<action>"` shows a loading state while the remote loads,
+// swaps to the registered component when it lands, and errors after the
+// timeout — it never renders the generic ConfirmActionDialog.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render, screen } from '@testing-library/react'
+
+// Stable identities: a fresh `t` per render spins the record dialog's effects
+// into an infinite render loop (same as dynamic-kanban.test).
+const USE_TRANSLATION = {
+    t: (_k: string, opts?: { defaultValue?: string }) => opts?.defaultValue ?? _k,
+    i18n: { language: 'es' },
+}
+vi.mock('react-i18next', () => ({
+    useTranslation: () => USE_TRANSLATION,
+}))
+
+vi.mock('@tanstack/react-router', () => ({
+    useNavigate: () => () => {},
+}))
+
+import { ActionModalDispatcher, FEDERATED_ACTION_MODAL_TIMEOUT_MS } from '../action-modal-dispatcher'
+import { setFederatedActionLoader } from '../federated-action-loader'
+import { useDynamicRowActions } from '../dynamic-row-actions'
+import { ModelActionToolbar } from '../model-action-toolbar'
+import { ApiProvider, type ApiClient } from '../api-context'
+import type { ActionDefinition, TableMetadata } from '../types'
+import {
+    registerActionComponent,
+    unregisterActionComponent,
+    type ActionMetadata,
+    type ActionModalProps,
+} from '@asteby/metacore-sdk'
+
+afterEach(() => {
+    cleanup()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+    setFederatedActionLoader(null)
+    unregisterActionComponent('Order', 'return')
+    unregisterActionComponent('Device', 'create_and_connect')
+    unregisterActionComponent('Invoice', 'register_payment')
+})
+
+const noopApi: ApiClient = {
+    get: vi.fn().mockResolvedValue({ data: {} }),
+    post: vi.fn().mockResolvedValue({ data: { success: true } }),
+    delete: vi.fn().mockResolvedValue({ data: { success: true } }),
+} as unknown as ApiClient
+
+const returnAction: ActionMetadata = {
+    key: 'return',
+    label: 'Devolver',
+    icon: 'Undo2',
+    modal: 'returns.return',
+    confirm: true,
+    confirmMessage: 'Devolver?',
+    executable: true,
+}
+
+function ReturnModal({ action }: ActionModalProps) {
+    return <div data-testid="return-modal">{action.modal}</div>
+}
+
+function renderDispatcher(action: ActionMetadata = returnAction) {
+    return render(
+        <ApiProvider client={noopApi}>
+            <ActionModalDispatcher
+                open
+                onOpenChange={() => {}}
+                action={action}
+                model="Order"
+                record={{ id: '1' } as any}
+                endpoint="/data/Order"
+                onSuccess={() => {}}
+            />
+        </ApiProvider>,
+    )
+}
+
+describe('ActionModalDispatcher with a declared federated modal', () => {
+    it('shows loading, then the component once it registers late — never the confirm', () => {
+        renderDispatcher()
+        expect(screen.getByTestId('federated-action-loading')).toBeTruthy()
+        expect(screen.queryByText('Devolver?')).toBeNull()
+
+        act(() => {
+            registerActionComponent('Order', 'return', ReturnModal as never)
+        })
+        expect(screen.getByTestId('return-modal').textContent).toBe('returns.return')
+        expect(screen.queryByTestId('federated-action-loading')).toBeNull()
+        expect(screen.queryByText('Devolver?')).toBeNull()
+    })
+
+    it('shows MissingCustomActionModal after the timeout when nothing registers', () => {
+        vi.useFakeTimers()
+        const err = vi.spyOn(console, 'error').mockImplementation(() => {})
+        renderDispatcher()
+        act(() => {
+            vi.advanceTimersByTime(FEDERATED_ACTION_MODAL_TIMEOUT_MS - 1)
+        })
+        expect(screen.getByTestId('federated-action-loading')).toBeTruthy()
+        expect(screen.queryByText('No se pudo cargar el formulario')).toBeNull()
+
+        act(() => {
+            vi.advanceTimersByTime(1)
+        })
+        expect(screen.getByText('No se pudo cargar el formulario')).toBeTruthy()
+        expect(screen.queryByText('Devolver?')).toBeNull()
+        expect(err).toHaveBeenCalledWith(
+            expect.stringContaining('did not register in time'),
+            expect.objectContaining({ model: 'Order', action: 'return', modal: 'returns.return' }),
+        )
+    })
+
+    it('still asks the host and times out on a slug without a valid prefix', () => {
+        vi.useFakeTimers()
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+        const err = vi.spyOn(console, 'error').mockImplementation(() => {})
+        const loader = vi.fn()
+        setFederatedActionLoader(loader)
+        renderDispatcher({ ...returnAction, modal: 'noprefix' })
+        expect(loader).toHaveBeenCalledWith({ model: 'Order', actionKey: 'return', modal: 'noprefix' })
+        expect(warn).toHaveBeenCalled()
+        expect(screen.getByTestId('federated-action-loading')).toBeTruthy()
+
+        act(() => {
+            vi.advanceTimersByTime(FEDERATED_ACTION_MODAL_TIMEOUT_MS)
+        })
+        expect(screen.getByText('No se pudo cargar el formulario')).toBeTruthy()
+        expect(screen.queryByText('Devolver?')).toBeNull()
+        expect(err).toHaveBeenCalledWith(
+            expect.stringContaining('did not register in time'),
+            expect.objectContaining({ model: 'Order', action: 'return', modal: 'noprefix' }),
+        )
+    })
+
+    it('asks the host loader for the remote and re-asks while waiting', () => {
+        vi.useFakeTimers()
+        vi.spyOn(console, 'error').mockImplementation(() => {})
+        const loader = vi.fn()
+        setFederatedActionLoader(loader)
+        renderDispatcher()
+        expect(loader).toHaveBeenCalledTimes(1)
+        expect(loader).toHaveBeenCalledWith({ model: 'Order', actionKey: 'return', modal: 'returns.return' })
+
+        act(() => {
+            vi.advanceTimersByTime(4_000)
+        })
+        expect(loader.mock.calls.length).toBeGreaterThan(1)
+
+        // Registration stops the retries.
+        act(() => {
+            registerActionComponent('Order', 'return', ReturnModal as never)
+        })
+        const calls = loader.mock.calls.length
+        act(() => {
+            vi.advanceTimersByTime(10_000)
+        })
+        expect(loader.mock.calls.length).toBe(calls)
+        expect(screen.getByTestId('return-modal')).toBeTruthy()
+    })
+})
+
+describe('useDynamicRowActions', () => {
+    function Harness({ metadata, actionKey }: { metadata: TableMetadata; actionKey: string }) {
+        const { handleInternalAction, dialogs } = useDynamicRowActions({
+            model: 'Order',
+            metadata,
+            onRefresh: () => {},
+        })
+        return (
+            <>
+                <button onClick={() => handleInternalAction(actionKey, { id: '1' })}>run</button>
+                {dialogs}
+            </>
+        )
+    }
+
+    function renderHarness(action: Record<string, unknown>) {
+        const metadata = { actions: [action] } as unknown as TableMetadata
+        render(
+            <ApiProvider client={noopApi}>
+                <Harness metadata={metadata} actionKey={action.key as string} />
+            </ApiProvider>,
+        )
+        act(() => {
+            screen.getByText('run').click()
+        })
+    }
+
+    it('keeps `modal` on the action it hands the dispatcher', () => {
+        registerActionComponent('Order', 'return', ReturnModal as never)
+        renderHarness({ ...returnAction, name: 'return', class: '', type: 'custom' })
+        expect(screen.getByTestId('return-modal').textContent).toBe('returns.return')
+        expect(screen.queryByText('Devolver?')).toBeNull()
+    })
+
+    it('honors a host-injected `modal` override on another addon\'s confirm action', () => {
+        // customers declares Invoice.register_payment as a plain confirm; the
+        // optional collections addon overrides it and the host injects `modal`.
+        function PaymentModal({ action }: ActionModalProps) {
+            return <div data-testid="payment-modal">{action.modal}</div>
+        }
+        const override = {
+            key: 'register_payment',
+            label: 'Registrar pago',
+            icon: 'Wallet',
+            type: 'custom',
+            confirmMessage: 'Registrar pago?',
+            executable: true,
+            modal: 'collections.register_payment',
+        }
+        const metadata = { actions: [override] } as unknown as TableMetadata
+        function InvoiceHarness() {
+            const { handleInternalAction, dialogs } = useDynamicRowActions({
+                model: 'Invoice',
+                metadata,
+                onRefresh: () => {},
+            })
+            return (
+                <>
+                    <button onClick={() => handleInternalAction('register_payment', { id: '1' })}>pay</button>
+                    {dialogs}
+                </>
+            )
+        }
+        render(
+            <ApiProvider client={noopApi}>
+                <InvoiceHarness />
+            </ApiProvider>,
+        )
+        act(() => {
+            screen.getByText('pay').click()
+        })
+        expect(screen.getByTestId('federated-action-loading')).toBeTruthy()
+        expect(screen.queryByText('Registrar pago?')).toBeNull()
+        act(() => {
+            registerActionComponent('Invoice', 'register_payment', PaymentModal as never, 'collections')
+        })
+        expect(screen.getByTestId('payment-modal').textContent).toBe('collections.register_payment')
+    })
+
+    it('opens the dispatcher for a modal-only action (no fields/confirm/executable)', () => {
+        renderHarness({ key: 'return', label: 'Devolver', icon: 'Undo2', modal: 'returns.return', type: 'custom' })
+        expect(screen.getByTestId('federated-action-loading')).toBeTruthy()
+    })
+})
+
+describe('ModelActionToolbar', () => {
+    // Prod case: link-inbox's Device.create_and_connect ("Conectar WhatsApp")
+    // is a `placement: "create"` toolbar action with `modal`. The toolbar used
+    // to drop `modal`, open the generic confirm and POST the action with no
+    // record → "action payload missing the device record id".
+    it('placement create + modal: loading, then the late-registered component — never the confirm', () => {
+        vi.useFakeTimers()
+        const api = {
+            get: vi.fn().mockResolvedValue({ data: {} }),
+            post: vi.fn().mockResolvedValue({ data: { success: true } }),
+        } as unknown as ApiClient
+        const onChange = vi.fn()
+        const loader = vi.fn()
+        setFederatedActionLoader(loader)
+        const connect = {
+            key: 'create_and_connect',
+            name: 'create_and_connect',
+            label: 'Conectar WhatsApp',
+            icon: 'Plus',
+            class: '',
+            type: 'custom',
+            placement: 'create',
+            modal: 'link_inbox.create_and_connect',
+            confirm: true,
+            confirmMessage: 'Conectar?',
+            executable: true,
+        } as ActionDefinition
+        render(
+            <ApiProvider client={api}>
+                <ModelActionToolbar model="Device" actions={[connect]} onChange={onChange} />
+            </ApiProvider>,
+        )
+        act(() => {
+            screen.getByText('Conectar WhatsApp').click()
+        })
+        expect(screen.getByTestId('federated-action-loading')).toBeTruthy()
+        expect(loader).toHaveBeenCalledWith({
+            model: 'Device',
+            actionKey: 'create_and_connect',
+            modal: 'link_inbox.create_and_connect',
+        })
+
+        // The remote is slow: still loading, no confirm, nothing executed.
+        act(() => {
+            vi.advanceTimersByTime(5_000)
+        })
+        expect(screen.getByTestId('federated-action-loading')).toBeTruthy()
+        expect(screen.queryByText('Conectar?')).toBeNull()
+        expect(screen.queryByRole('alertdialog')).toBeNull()
+
+        function ConnectModal({ action }: ActionModalProps) {
+            return <div data-testid="connect-modal">{action.modal}</div>
+        }
+        act(() => {
+            registerActionComponent('Device', 'create_and_connect', ConnectModal as never, 'link_inbox')
+        })
+        expect(screen.getByTestId('connect-modal').textContent).toBe('link_inbox.create_and_connect')
+        expect(screen.queryByTestId('federated-action-loading')).toBeNull()
+        expect(screen.queryByText('Conectar?')).toBeNull()
+        expect(screen.queryByRole('alertdialog')).toBeNull()
+        expect(api.post).not.toHaveBeenCalled()
+        expect(onChange).not.toHaveBeenCalled()
+    })
+})

package/src/__tests__/requires-addon.test.tsx

@@ -0,0 +1,201 @@
+// @vitest-environment happy-dom
+//
+// requiresAddon: an action gated by a missing optional addon stays visible but
+// locked. A click must NOT reach the dispatcher / federated modal / backend; it
+// opens the "requires addon" dialog whose "Instalar" hands the key to the host
+// handler, or routes to /marketplace/<key> through the SDK router.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, renderHook, screen } from '@testing-library/react'
+
+const I18N_T = (_k: string, opts?: { defaultValue?: string; [k: string]: unknown }) =>
+    (opts?.defaultValue ?? _k).replace(/\{\{(\w+)\}\}/g, (_: string, v: string) => String(opts?.[v] ?? ''))
+const USE_TRANSLATION = { t: I18N_T, i18n: { language: 'es' } }
+vi.mock('react-i18next', () => ({
+    useTranslation: () => USE_TRANSLATION,
+}))
+
+const navigate = vi.fn()
+vi.mock('@tanstack/react-router', () => ({
+    useNavigate: () => navigate,
+}))
+
+// The dispatcher must never mount for a gated action.
+const dispatcherSpy = vi.fn()
+vi.mock('../action-modal-dispatcher', () => ({
+    ActionModalDispatcher: (props: unknown) => {
+        dispatcherSpy(props)
+        return <div data-testid="dispatcher" />
+    },
+}))
+
+import { useDynamicRowActions } from '../dynamic-row-actions'
+import { ModelActionToolbar } from '../model-action-toolbar'
+import { RowActionMenuItem } from '../dynamic-columns'
+import { ApiProvider } from '../api-context'
+import { resolveRequiresAddon, setAddonInstallHandler } from '../requires-addon'
+import type { ActionDefinition, TableMetadata } from '../types'
+import { DropdownMenu, DropdownMenuContent } from '@asteby/metacore-ui/primitives'
+
+const post = vi.fn(async () => ({ data: { success: true } }))
+const api = {
+    get: async () => ({ data: { data: {} } }),
+    post,
+    put: async () => ({ data: { success: true } }),
+    delete: async () => ({ data: { success: true } }),
+} as never
+
+const WIRE_REQUIREMENT = {
+    key: 'connector_whatsapp',
+    name: 'Conector WhatsApp',
+    reason: 'Necesitas el conector para vincular un número.',
+}
+
+// Exactly as ops serves it: snake_case, plus a federated modal + executable so
+// that, without the gate, the click would open the dispatcher.
+const gatedRowAction = {
+    key: 'connect_device',
+    name: 'connect_device',
+    label: 'Conectar WhatsApp',
+    icon: 'QrCode',
+    class: '',
+    type: 'custom',
+    modal: 'link_inbox.connect_device',
+    executable: true,
+    requires_addon: WIRE_REQUIREMENT,
+} as unknown as ActionDefinition
+
+const metadata = { title: 'Devices', actions: [gatedRowAction] } as unknown as TableMetadata
+
+function Wrapper({ children }: { children: React.ReactNode }) {
+    return <ApiProvider client={api}>{children}</ApiProvider>
+}
+
+beforeEach(() => {
+    post.mockClear()
+    navigate.mockClear()
+    dispatcherSpy.mockClear()
+    setAddonInstallHandler(null)
+})
+afterEach(cleanup)
+
+describe('resolveRequiresAddon', () => {
+    it('normalizes the snake_case requires_addon served by the host', () => {
+        expect(resolveRequiresAddon({ requires_addon: WIRE_REQUIREMENT })).toEqual(WIRE_REQUIREMENT)
+    })
+    it('reads camelCase requiresAddon', () => {
+        expect(resolveRequiresAddon({ requiresAddon: { key: 'x' } })).toEqual({ key: 'x' })
+    })
+    it('treats absent / keyless requirements as runnable', () => {
+        expect(resolveRequiresAddon({ key: 'a' })).toBeNull()
+        expect(resolveRequiresAddon({ requires_addon: { name: 'Sin key' } })).toBeNull()
+        expect(resolveRequiresAddon(undefined)).toBeNull()
+    })
+})
+
+function RowHarness() {
+    const { handleInternalAction, dialogs } = useDynamicRowActions({
+        model: 'Device',
+        metadata,
+        onRefresh: () => {},
+    })
+    return (
+        <>
+            <button onClick={() => handleInternalAction('connect_device', { id: 'r1' })}>run</button>
+            {dialogs}
+        </>
+    )
+}
+
+describe('row actions (table / kanban shared handler)', () => {
+    it('does not dispatch nor post; opens the requires-addon dialog', async () => {
+        const onAction = vi.fn()
+        const { result } = renderHook(
+            () => useDynamicRowActions({ model: 'Device', metadata, onAction, onRefresh: () => {} }),
+            { wrapper: Wrapper },
+        )
+        await act(() => result.current.handleInternalAction('connect_device', { id: 'r1' }))
+        expect(onAction).not.toHaveBeenCalled()
+
+        render(<RowHarness />, { wrapper: Wrapper })
+        await act(async () => fireEvent.click(screen.getByText('run')))
+
+        expect(screen.getByText('Esta acción requiere «Conector WhatsApp»')).toBeTruthy()
+        expect(screen.getByText(WIRE_REQUIREMENT.reason)).toBeTruthy()
+        expect(screen.queryByTestId('dispatcher')).toBeNull()
+        expect(dispatcherSpy).not.toHaveBeenCalled()
+        expect(post).not.toHaveBeenCalled()
+    })
+
+    it('Instalar invokes the host handler with the addon key', async () => {
+        const handler = vi.fn()
+        setAddonInstallHandler(handler)
+        render(<RowHarness />, { wrapper: Wrapper })
+        await act(async () => fireEvent.click(screen.getByText('run')))
+        await act(async () => fireEvent.click(screen.getByText('Instalar «Conector WhatsApp»')))
+        expect(handler).toHaveBeenCalledWith('connector_whatsapp')
+        expect(navigate).not.toHaveBeenCalled()
+    })
+
+    it('without a handler navigates through the router to /marketplace/<key>', async () => {
+        render(<RowHarness />, { wrapper: Wrapper })
+        await act(async () => fireEvent.click(screen.getByText('run')))
+        await act(async () => fireEvent.click(screen.getByText('Instalar «Conector WhatsApp»')))
+        expect(navigate).toHaveBeenCalledWith({ to: '/marketplace/connector_whatsapp' })
+    })
+
+    it('menu entry stays visible with a lock and the addon name as tooltip', () => {
+        render(
+            <DropdownMenu open>
+                <DropdownMenuContent>
+                    <RowActionMenuItem action={gatedRowAction} label="Conectar WhatsApp" onSelect={() => {}} />
+                </DropdownMenuContent>
+            </DropdownMenu>,
+        )
+        const item = screen.getByText('Conectar WhatsApp').closest('[data-requires-addon]')
+        expect(item?.getAttribute('data-requires-addon')).toBe('connector_whatsapp')
+        expect(item?.getAttribute('title')).toBe('Requiere «Conector WhatsApp»')
+    })
+})
+
+describe('ModelActionToolbar', () => {
+    const toolbarAction = {
+        ...gatedRowAction,
+        placement: 'table',
+        requires_addon: undefined,
+        requiresAddon: { key: 'connector_whatsapp', name: 'Conector WhatsApp' },
+    } as unknown as ActionDefinition
+
+    it('renders the action locked and opens the dialog instead of the dispatcher', async () => {
+        const intent = vi.fn()
+        render(
+            <Wrapper>
+                <ModelActionToolbar model="Device" actions={[toolbarAction]} onActionIntent={intent} />
+            </Wrapper>,
+        )
+        const button = screen.getByText('Conectar WhatsApp').closest('button')!
+        expect(button.getAttribute('title')).toBe('Requiere «Conector WhatsApp»')
+        expect(button.querySelector('[data-requires-addon="connector_whatsapp"]')).toBeTruthy()
+
+        await act(async () => fireEvent.click(button))
+        expect(screen.getByText('Esta acción requiere «Conector WhatsApp»')).toBeTruthy()
+        // No reason from the host → generic copy.
+        expect(screen.getByText('Instala «Conector WhatsApp» para habilitar esta acción.')).toBeTruthy()
+        expect(dispatcherSpy).not.toHaveBeenCalled()
+        expect(intent).not.toHaveBeenCalled()
+        expect(post).not.toHaveBeenCalled()
+
+        await act(async () => fireEvent.click(screen.getByText('Instalar «Conector WhatsApp»')))
+        expect(navigate).toHaveBeenCalledWith({ to: '/marketplace/connector_whatsapp' })
+    })
+
+    it('an ungated action still opens the dispatcher', async () => {
+        const plain = { ...toolbarAction, key: 'other', label: 'Otra', requiresAddon: undefined } as ActionDefinition
+        render(
+            <Wrapper>
+                <ModelActionToolbar model="Device" actions={[plain]} />
+            </Wrapper>,
+        )
+        await act(async () => fireEvent.click(screen.getByText('Otra')))
+        expect(dispatcherSpy).toHaveBeenCalled()
+    })
+})

package/src/action-modal-dispatcher.tsx

@@ -1,7 +1,11 @@
 // ActionModalDispatcher — renders the right modal for a custom action:
 // 1) Custom component from the SDK registry → use it
-// 2) action.modal set but no registered component → MissingCustomActionModal
-//    (NEVER fall back to confirm/fields — that hides a broken federated UI)
+// 2) action.modal set but no registered component → loading state while the
+//    host loads the remote (setFederatedActionLoader); the registry is reactive,
+//    so the component renders the moment it registers. Timeout →
+//    MissingCustomActionModal (a malformed slug still asks the host, then
+//    times out). NEVER falls back to confirm/fields — that
+//    hides a broken federated UI.
 // 3) action.fields[] / action.steps[] → GenericActionModal / WizardActionModal
 // 4) action.confirm OR action.confirmMessage → ConfirmActionDialog
 // 5) action.executable (host opened the modal; no modal/fields/confirm) →
@@ -10,7 +14,7 @@
 //
 // The host injects its axios-like client via <ApiProvider>; we no longer
 // depend on a bundler alias to `@/lib/api`.
-import { useState, useEffect, useMemo } from 'react'
+import { useState, useEffect, useMemo, useSyncExternalStore } from 'react'
 import { useTranslation } from 'react-i18next'
 import {
     Dialog,
@@ -76,7 +80,9 @@ import {
     type ActionMetadata,
     type ActionModalProps,
     getActionComponent,
+    subscribeActionComponents,
 } from '@asteby/metacore-sdk'
+import { requestFederatedAction } from './federated-action-loader'
 
 export type { ActionMetadata, ActionModalProps }
 
@@ -284,10 +290,10 @@ export function ActionModalDispatcher({
     endpoint,
     onSuccess,
 }: ActionModalProps) {
-    const CustomComponent = useMemo(
-        () => getActionComponent(model, action.key),
-        [model, action.key],
-    )
+    // Reactive read: a federated remote usually registers AFTER the first
+    // render, and a memoized lookup would pin the fallback forever.
+    const readComponent = () => getActionComponent(model, action.key)
+    const CustomComponent = useSyncExternalStore(subscribeActionComponents, readComponent, readComponent)
 
     if (CustomComponent) {
         return (
@@ -303,11 +309,12 @@ export function ActionModalDispatcher({
         )
     }
 
-    // Declarative custom slot (`modal: "addon.action"`). Prefer a hard error
-    // over confirm/fields generics — those look "fine" and hide a missing remote.
+    // Declarative custom slot (`modal: "addon.action"`). Wait for the remote,
+    // then a hard error — confirm/fields generics look "fine" and hide a
+    // missing remote.
     if (action.modal) {
         return (
-            <MissingCustomActionModal
+            <PendingCustomActionModal
                 open={open}
                 onOpenChange={onOpenChange}
                 action={action}
@@ -367,6 +374,91 @@ export function ActionModalDispatcher({
     return null
 }
 
+/** How long an action with `modal` waits for its federated component. */
+export const FEDERATED_ACTION_MODAL_TIMEOUT_MS = 20_000
+/** How often the host loader is re-invoked while waiting. */
+const FEDERATED_ACTION_RETRY_MS = 2_000
+const MODAL_SLUG_RE = /^[\w-]+(\.[\w-]+)+$/
+
+/**
+ * `modal` declared, component not registered yet: show a loading dialog, ask
+ * the host to load the remote (re-asking periodically), and give up with
+ * MissingCustomActionModal after the timeout. The dispatcher swaps this out
+ * for the real component as soon as the registry reports it. `modal` is
+ * honored wherever it came from — the addon's own manifest or a host-injected
+ * override from another addon that registerAction()s over it.
+ */
+function PendingCustomActionModal({
+    open,
+    onOpenChange,
+    action,
+    model,
+}: {
+    open: boolean
+    onOpenChange: (open: boolean) => void
+    action: ActionMetadata
+    model: string
+}) {
+    const { t } = useTranslation()
+    const slug = action.modal || ''
+    const [timedOut, setTimedOut] = useState(false)
+
+    useEffect(() => {
+        if (!open) return
+        // A slug without a valid `<addon>.<name>` prefix still goes to the
+        // host loader (it decides which remote to load) and still times out —
+        // the component is looked up by (model, action.key), never by slug.
+        // Warn so a malformed manifest is diagnosable before the timeout.
+        const validSlug = MODAL_SLUG_RE.test(slug)
+        if (!validSlug) {
+            console.warn('[metacore] action modal slug has no valid "<addon>.<name>" prefix', {
+                model,
+                action: action.key,
+                modal: slug,
+            })
+        }
+        setTimedOut(false)
+        const req = { model, actionKey: action.key, modal: slug }
+        requestFederatedAction(req)
+        const retry = setInterval(() => requestFederatedAction(req), FEDERATED_ACTION_RETRY_MS)
+        const giveUp = setTimeout(() => {
+            clearInterval(retry)
+            console.error('[metacore] federated action modal did not register in time', {
+                model,
+                action: action.key,
+                modal: slug,
+                validSlug,
+                timeoutMs: FEDERATED_ACTION_MODAL_TIMEOUT_MS,
+            })
+            setTimedOut(true)
+        }, FEDERATED_ACTION_MODAL_TIMEOUT_MS)
+        return () => {
+            clearInterval(retry)
+            clearTimeout(giveUp)
+        }
+    }, [open, model, action.key, slug])
+
+    if (timedOut) {
+        return <MissingCustomActionModal open={open} onOpenChange={onOpenChange} action={action} model={model} />
+    }
+
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent>
+                <DialogHeader>
+                    <DialogTitle>{t(action.label, { defaultValue: action.label })}</DialogTitle>
+                    <DialogDescription>
+                        {t('dynamic.action_modal_loading', { defaultValue: 'Cargando…' })}
+                    </DialogDescription>
+                </DialogHeader>
+                <div className="flex justify-center py-6" data-testid="federated-action-loading">
+                    <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+                </div>
+            </DialogContent>
+        </Dialog>
+    )
+}
+
 /** Shown when the action declares `modal` but no federated component registered. */
 function MissingCustomActionModal({
     open,