@asteby/metacore-runtime-react 45.0.0 → 45.3.0

package/src/__tests__/reason-prompt.test.tsx

@@ -0,0 +1,121 @@
+// @vitest-environment happy-dom
+//
+// Mandatory reason (PER-4): the request is tried bare; a 422 errors.reason makes
+// the hook ask once and retry with the reason; cancel = nothing ran.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+
+vi.mock('react-i18next', () => ({
+    useTranslation: () => ({
+        t: (k: string, opts?: { defaultValue?: string; min?: number }) =>
+            (opts?.defaultValue ?? k).replace('{{min}}', String(opts?.min ?? '')),
+    }),
+}))
+
+import { reasonRequiredInfo, useReasonPrompt } from '../reason-prompt'
+
+afterEach(() => {
+    cleanup()
+    vi.clearAllMocks()
+})
+
+const refusal = (code: 'required' | 'min', min?: number) => ({
+    response: { status: 422, data: { success: false, errors: { reason: [{ code, params: min ? { min } : undefined }] } } },
+})
+
+describe('reasonRequiredInfo', () => {
+    it('reads required and min refusals', () => {
+        expect(reasonRequiredInfo(refusal('required'))).toEqual({ min: 3, tooShort: false })
+        expect(reasonRequiredInfo(refusal('min', 8))).toEqual({ min: 8, tooShort: true })
+    })
+    it('ignores every other error', () => {
+        expect(reasonRequiredInfo(new Error('boom'))).toBeNull()
+        expect(reasonRequiredInfo({ response: { data: { errors: { name: [{ code: 'required' }] } } } })).toBeNull()
+        expect(reasonRequiredInfo({ response: { data: { errors: { reason: [{ code: 'other' }] } } } })).toBeNull()
+        expect(reasonRequiredInfo(undefined)).toBeNull()
+    })
+})
+
+let result: unknown = 'unset'
+function Probe({ request }: { request: (r?: string) => Promise<string> }) {
+    const { run, dialog } = useReasonPrompt()
+    return (
+        <>
+            <button onClick={async () => { result = await run({ title: 'Eliminar', request }) }}>go</button>
+            {dialog}
+        </>
+    )
+}
+
+describe('useReasonPrompt', () => {
+    it('does not prompt when the server needs no reason', async () => {
+        result = 'unset'
+        const request = vi.fn().mockResolvedValue('ok')
+        render(<Probe request={request} />)
+        fireEvent.click(screen.getByText('go'))
+        await waitFor(() => expect(result).toBe('ok'))
+        expect(request).toHaveBeenCalledTimes(1)
+        expect(request).toHaveBeenCalledWith(undefined)
+        expect(screen.queryByLabelText('Motivo')).toBeNull()
+    })
+
+    it('asks once on a required refusal and retries with the trimmed reason', async () => {
+        result = 'unset'
+        const request = vi.fn().mockRejectedValueOnce(refusal('required')).mockResolvedValueOnce('done')
+        render(<Probe request={request} />)
+        fireEvent.click(screen.getByText('go'))
+        const box = await screen.findByLabelText('Motivo')
+        const confirm = screen.getByText('Continuar').closest('button') as HTMLButtonElement
+        expect(confirm.disabled).toBe(true)
+        fireEvent.change(box, { target: { value: '  captura duplicada  ' } })
+        expect(confirm.disabled).toBe(false)
+        fireEvent.click(confirm)
+        await waitFor(() => expect(result).toBe('done'))
+        expect(request).toHaveBeenNthCalledWith(2, 'captura duplicada')
+    })
+
+    it('stays open with the inline hint when the server wants a longer reason', async () => {
+        result = 'unset'
+        const request = vi
+            .fn()
+            .mockRejectedValueOnce(refusal('required'))
+            .mockRejectedValueOnce(refusal('min', 10))
+            .mockResolvedValueOnce('done')
+        render(<Probe request={request} />)
+        fireEvent.click(screen.getByText('go'))
+        fireEvent.change(await screen.findByLabelText('Motivo'), { target: { value: 'abc' } })
+        fireEvent.click(screen.getByText('Continuar'))
+        await screen.findByText('Escribe al menos 10 caracteres.')
+        fireEvent.change(screen.getByLabelText('Motivo'), { target: { value: 'un motivo bastante largo' } })
+        fireEvent.click(screen.getByText('Continuar'))
+        await waitFor(() => expect(result).toBe('done'))
+    })
+
+    it('resolves undefined when the operator cancels', async () => {
+        result = 'unset'
+        const request = vi.fn().mockRejectedValueOnce(refusal('required'))
+        render(<Probe request={request} />)
+        fireEvent.click(screen.getByText('go'))
+        await screen.findByLabelText('Motivo')
+        fireEvent.click(screen.getByText('Cancelar'))
+        await waitFor(() => expect(result).toBeUndefined())
+        expect(request).toHaveBeenCalledTimes(1)
+    })
+
+    it('rethrows a non-reason error', async () => {
+        const request = vi.fn().mockRejectedValue(new Error('network'))
+        let caught: unknown
+        function P2() {
+            const { run, dialog } = useReasonPrompt()
+            return (
+                <>
+                    <button onClick={() => run({ title: 'x', request }).catch((e) => { caught = e })}>go</button>
+                    {dialog}
+                </>
+            )
+        }
+        render(<P2 />)
+        fireEvent.click(screen.getByText('go'))
+        await waitFor(() => expect((caught as Error)?.message).toBe('network'))
+    })
+})

package/src/__tests__/use-addon-settings.test.ts

@@ -4,7 +4,7 @@
 // itself is a thin react-query wrapper over `useApi`; the load-bearing logic
 // is this pure merge, so that's what we test directly.
 import { describe, it, expect } from 'vitest'
-import { mergeAddonSettings, addonSettingsKey } from '../use-addon-settings'
+import { mergeAddonSettings, addonSettingsKey, addonSettingsUrl } from '../use-addon-settings'
 
 interface PosSettings extends Record<string, unknown> {
     allowNegativeStock: boolean
@@ -72,3 +72,18 @@ describe('addonSettingsKey', () => {
         expect(addonSettingsKey('inventory')).toEqual(['addon-settings', 'inventory'])
     })
 })
+
+describe('branch-scoped settings (POS-1)', () => {
+    it('keys and urls carry the branch only when given', () => {
+        expect(addonSettingsKey('pos', 'b1')).toEqual(['addon-settings', 'pos', 'b1'])
+        expect(addonSettingsKey('pos', null)).toEqual(['addon-settings', 'pos'])
+        expect(addonSettingsUrl('pos')).toBe('/api/addons/pos/settings')
+        expect(addonSettingsUrl('pos', 'b 1')).toBe('/api/addons/pos/settings?branch_id=b%201')
+    })
+
+    it('an org-key prefix matches every branch read (invalidation)', () => {
+        const org = addonSettingsKey('pos')
+        const branch = addonSettingsKey('pos', 'b1')
+        expect(branch.slice(0, org.length)).toEqual([...org])
+    })
+})

package/src/action-modal-dispatcher.tsx

@@ -14,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, useSyncExternalStore } from 'react'
+import { useState, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
 import { useTranslation } from 'react-i18next'
 import {
     Dialog,
@@ -57,6 +57,7 @@ import {
 } from './field-validation-ui'
 import { validationCatalog } from './validation-catalog'
 import { useApi } from './api-context'
+import { useReasonPrompt } from './reason-prompt'
 import { buildRelationFilterParams } from './dynamic-relation-helpers'
 import { DynamicIcon } from './dynamic-icon'
 import { DynamicLineItems } from './dynamic-line-items'
@@ -112,6 +113,16 @@ export interface PrefillSpec {
      * flow (which carries no prefill spec); only the prefilled action locks them.
      */
     lock?: string[]
+    /**
+     * Key of a SIBLING action field (a dynamic_select with a `ref`) whose selected
+     * value is the id of the document the rows are seeded from. Without it the
+     * rows come from the record the action was opened on (row actions); with it
+     * a `create`-placed action — which has no record — seeds its grid as soon as
+     * the user picks the source document (e.g. a goods receipt picking its
+     * purchase order). `$prefillFromRecord` then names a one_to_many relation of
+     * the REFERENCED model. Clearing the selection empties the grid.
+     */
+    fromField?: string
 }
 
 export function isPrefillSpec(v: unknown): v is PrefillSpec {
@@ -222,6 +233,64 @@ export function prefillRelationRequests(
     return out
 }
 
+// ---- prefill lines from a document picked in a sibling field ----------------
+//
+// A create-placed action has no record, so `$prefillFromRecord` alone can only
+// seed an empty grid. With `fromField` the spec follows a sibling ref field:
+// when the user selects the source document the modal loads its relation rows
+// and seeds the grid (see PrefillSpec.fromField).
+
+export interface PrefillFromFieldRequest {
+    fieldKey: string
+    spec: PrefillSpec
+    /** Model key the sibling field references (its `ref`). */
+    refModel: string
+    /** Selected document id; '' when nothing is selected (grid must clear). */
+    refId: string
+}
+
+export function prefillFromFieldRequests(
+    fields: ActionFieldDef[] | undefined,
+    formData: Record<string, any>,
+): PrefillFromFieldRequest[] {
+    const out: PrefillFromFieldRequest[] = []
+    if (!fields) return out
+    for (const field of fields) {
+        if (!isLineItemsField(field)) continue
+        const spec = lineItemsDefault(field)
+        if (!isPrefillSpec(spec) || !spec.fromField) continue
+        const source = fields.find((f) => f.key === spec.fromField)
+        const refModel = source ? getFieldRef(source) : undefined
+        if (!refModel) continue
+        const raw = unwrapRecordScalar(formData?.[spec.fromField])
+        const refId = raw === undefined || raw === null ? '' : String(raw)
+        out.push({ fieldKey: field.key, spec, refModel, refId })
+    }
+    return out
+}
+
+// prefillFromFieldRelationRequest resolves the child-rows request for a
+// selected document, from the referenced model's declared relations. Null when
+// the relation is missing or not a plain one_to_many.
+export function prefillFromFieldRelationRequest(
+    req: PrefillFromFieldRequest,
+    relations: Array<{ name?: string; kind?: string; through?: string; foreign_key?: string; scope?: Record<string, unknown> }>,
+): { endpoint: string; params: Record<string, string | number> } | null {
+    if (!req.refId) return null
+    const rel = (relations || []).find(
+        (r) => r?.name === req.spec.$prefillFromRecord && (r.kind ?? 'one_to_many') === 'one_to_many',
+    )
+    if (!rel?.through || !rel.foreign_key) return null
+    const scope: Record<string, string> = {}
+    for (const [k, v] of Object.entries(rel.scope ?? {})) {
+        if (v !== undefined && v !== null) scope[k] = String(v)
+    }
+    return {
+        endpoint: `/data/${rel.through}`,
+        params: { ...buildRelationFilterParams(rel.foreign_key, req.refId, scope), per_page: 200 },
+    }
+}
+
 // ---- scalar prefill from the acted-on record --------------------------------
 //
 // Row actions (stamp / refactura / cancel-with-reason) should open with the
@@ -728,6 +797,9 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
     const { t, i18n } = useTranslation()
     const api = useApi()
     const [executing, setExecuting] = useState(false)
+    // Actions listed in the model's `reason_required.actions` (cancel, void…)
+    // answer 422 errors.reason without a motive; the prompt asks and retries.
+    const reasonPrompt = useReasonPrompt()
     // `action.label` is an addon-contributed i18n key; its locale bundle loads
     // asynchronously, so translate at render (defaultValue keeps an already
     // localized label unchanged).
@@ -737,7 +809,13 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
         setExecuting(true)
         try {
             const url = buildActionUrl(endpoint, model, record.id, action.key)
-            const res = await api.post(url, {})
+            const res = await reasonPrompt.run({
+                title: label,
+                description: t('actions.reason_desc', { defaultValue: 'Esta acción pide el motivo. Queda en la bitácora del documento.' }),
+                request: (reason) => api.post(url, reason ? { reason } : {}),
+            })
+            // Operator cancelled the reason prompt: nothing ran.
+            if (!res) return
             if (res.data.success) {
                 toastServerSuccess(res.data, { t })
                 onOpenChange(false)
@@ -753,6 +831,8 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
     }
 
     return (
+        <>
+        {reasonPrompt.dialog}
         <AlertDialog open={open} onOpenChange={onOpenChange}>
             <AlertDialogContent>
                 <AlertDialogHeader>
@@ -778,6 +858,7 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
                 </AlertDialogFooter>
             </AlertDialogContent>
         </AlertDialog>
+        </>
     )
 }
 
@@ -788,6 +869,7 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
     // defaultValue keeps an already-localized string unchanged.
     const tl = (s: string) => t(s, { defaultValue: s })
     const api = useApi()
+    const reasonPrompt = useReasonPrompt()
     const branchGate = useBranchCreateGate()
     const [formData, setFormData] = useState<Record<string, any>>({})
     const [executing, setExecuting] = useState(false)
@@ -850,6 +932,60 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
         }
     }, [open, action.fields, record, relations, api])
 
+    // Lines seeded from a document picked in a sibling field (PrefillSpec.fromField).
+    // Re-runs only when the picked id changes; each pick loads the referenced
+    // model's relations (cached per model for the life of the modal) and then
+    // the child rows.
+    const fromFieldReqs = useMemo(
+        () => prefillFromFieldRequests(action.fields, formData),
+        [action.fields, formData],
+    )
+    const fromFieldSig = fromFieldReqs.map((r) => `${r.fieldKey}=${r.refModel}:${r.refId}`).join('|')
+    const refRelationsCache = useRef<Map<string, Promise<any[]>>>(new Map())
+    useEffect(() => {
+        if (!open || fromFieldReqs.length === 0) return
+        let cancelled = false
+        for (const req of fromFieldReqs) {
+            if (!req.refId) {
+                setFormData((prev: Record<string, any>) =>
+                    Array.isArray(prev[req.fieldKey]) && prev[req.fieldKey].length === 0
+                        ? prev
+                        : { ...prev, [req.fieldKey]: [] },
+                )
+                continue
+            }
+            let relsPromise = refRelationsCache.current.get(req.refModel)
+            if (!relsPromise) {
+                relsPromise = api
+                    .get(`/metadata/table/${req.refModel}`)
+                    .then((res: any) => {
+                        const rels = res?.data?.relations ?? res?.data?.data?.relations ?? []
+                        return Array.isArray(rels) ? rels : []
+                    })
+                    .catch(() => [] as any[])
+                refRelationsCache.current.set(req.refModel, relsPromise)
+            }
+            relsPromise
+                .then((rels) => {
+                    const call = prefillFromFieldRelationRequest(req, rels)
+                    if (!call) return
+                    return api.get(call.endpoint, { params: call.params }).then((res: any) => {
+                        if (cancelled) return
+                        const rows = res?.data?.data ?? res?.data ?? []
+                        if (!Array.isArray(rows)) return
+                        const built = buildPrefillRows(req.spec, { [req.spec.$prefillFromRecord]: rows })
+                        setFormData((prev: Record<string, any>) => ({ ...prev, [req.fieldKey]: built }))
+                    })
+                })
+                .catch(() => {})
+        }
+        return () => {
+            cancelled = true
+        }
+        // fromFieldSig captures every dependency of fromFieldReqs that matters.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open, fromFieldSig, api])
+
     const updateField = (key: string, value: any) => {
         setFormData((prev: Record<string, any>) => ({ ...prev, [key]: value }))
         setFieldErrors((prev) => clearFieldErrorTree(prev, key))
@@ -914,7 +1050,12 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                 if (branchId) payload = { ...payload, branch_id: branchId }
             }
             const url = buildActionUrl(endpoint, model, record?.id, action.key)
-            const res = await api.post(url, payload)
+            const res = await reasonPrompt.run({
+                title: tl(action.label),
+                description: t('actions.reason_desc', { defaultValue: 'Esta acción pide el motivo. Queda en la bitácora del documento.' }),
+                request: (reason) => api.post(url, reason ? { ...payload, reason } : payload),
+            })
+            if (!res) return
             if (res.data.success) {
                 toastServerSuccess(res.data, { t })
                 onOpenChange(false)
@@ -1022,6 +1163,7 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                         {tl(action.label)}
                     </Button>
                 </DialogFooter>
+                {reasonPrompt.dialog}
             </DialogContent>
         </Dialog>
     )

package/src/activity-diff.tsx

@@ -50,6 +50,8 @@ export interface ActivityEvent {
      */
     changes?: Record<string, { from: unknown; to: unknown }> | null
     summary?: string | null
+    /** Motive the operator stated for a delete / reason_required action (PER-4). */
+    reason?: string | null
     occurred_at: string
 }
 
@@ -204,7 +206,7 @@ export const ActivityDiff: React.FC<ActivityDiffProps> = ({
 
     const variantBadge = VARIANT_BADGE[variant] ?? VARIANT_BADGE.other
 
-    if (allKeys.length === 0 && !event.summary) {
+    if (allKeys.length === 0 && !event.summary && !event.reason) {
         return (
             <div className={cn('text-sm text-muted-foreground italic py-1', className)}>
                 Sin campos registrados.
@@ -235,6 +237,13 @@ export const ActivityDiff: React.FC<ActivityDiffProps> = ({
                 )}
             </div>
 
+            {/* Mandatory-reason motive (delete / cancel with reason_required) */}
+            {event.reason && (
+                <p className="text-sm" data-testid="activity-reason">
+                    <span className="font-medium">Motivo:</span> {event.reason}
+                </p>
+            )}
+
             {/* Summary line (if backend provided one) */}
             {event.summary && (
                 <p className="text-sm text-muted-foreground italic">{event.summary}</p>

package/src/approval-events.ts

@@ -0,0 +1,39 @@
+// approval-events — dependency-free glue between server-error.ts (which sees a
+// parked `approval_required` write) and <ApprovalGateProvider> (which owns the
+// PIN dialog). Kept apart so the error toaster never imports React/UI code.
+
+/** Window event toastServerError fires for a parked `approval_required` write. */
+export const APPROVAL_PARKED_EVENT = 'metacore:approval-parked'
+/** Fired after a parked request was approved (and replayed) with a PIN. */
+export const APPROVAL_DECIDED_EVENT = 'metacore:approval-decided'
+
+let gateMounted = 0
+/** @internal provider bookkeeping. */
+export function gateMountedDelta(d: number): void {
+    gateMounted += d
+}
+
+/** True while an <ApprovalGateProvider> is mounted (toastServerError offers the PIN action only then). */
+export function approvalGateAvailable(): boolean {
+    return gateMounted > 0
+}
+
+export interface ApprovalRequiredInfo {
+    requestId: string
+    label?: string
+    roles: string[]
+}
+
+/** Extracts the parked-request info from an axios error / response body, or null. */
+export function approvalRequiredInfo(err: unknown): ApprovalRequiredInfo | null {
+    const data = ((err as { response?: { data?: unknown } })?.response?.data ?? err) as
+        | { error?: { code?: string }; meta?: { approval_request_id?: string; approval_label?: string; approval_roles?: string[] } }
+        | undefined
+    if (data?.error?.code !== 'approval_required') return null
+    return {
+        requestId: data.meta?.approval_request_id ?? '',
+        label: data.meta?.approval_label,
+        roles: data.meta?.approval_roles ?? [],
+    }
+}
+

package/src/approval-gate.tsx

@@ -0,0 +1,180 @@
+// ApprovalGate — one place for "this needs a supervisor" in hosts that mount an
+// ApiProvider. It answers two situations with the same PIN dialog:
+//
+//   1. INLINE policy (POS oversell, discount over the cap, refund…): the client
+//      calls `requestApproval({policy, …})`. A user who already holds the policy's
+//      `general.approve_<policy>` capability passes straight through (`bypassed`);
+//      everyone else gets the dialog, which posts `/approvals/pin-grant`.
+//   2. PARKED request: a write answered 422 `approval_required`. toastServerError
+//      shows "Enviado a aprobación" with an "Aprobar con PIN" action that opens the
+//      dialog against `/approvals/:id/approve-pin` (kernel approvals_pin.go).
+//
+// Federated addons with their own HTTP client use <ApprovalPinDialog> directly
+// (approval-pin-dialog.tsx) and post to the same endpoints.
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { toast } from 'sonner'
+import { useApi } from './api-context'
+import { useCan } from './permissions-context'
+import { ApprovalPinDialog, type ApprovalPinSubmit } from './approval-pin-dialog'
+import {
+    APPROVAL_DECIDED_EVENT,
+    APPROVAL_PARKED_EVENT,
+    gateMountedDelta,
+    type ApprovalRequiredInfo,
+} from './approval-events'
+
+export {
+    APPROVAL_DECIDED_EVENT,
+    APPROVAL_PARKED_EVENT,
+    approvalGateAvailable,
+    approvalRequiredInfo,
+    type ApprovalRequiredInfo,
+} from './approval-events'
+
+/** Capability that authorizes `policy` (and lets its holder skip the prompt). */
+export function approvalCapability(policy: string): string {
+    return `general.approve_${policy}`
+}
+
+export interface ApprovalGrant {
+    /** Audit row id (ApprovalRequest.kind=pin); null when the caller bypassed. */
+    id: string | null
+    policy: string
+    bypassed: boolean
+    reason?: string
+}
+
+export interface RequestApprovalOptions {
+    /** Policy key: oversell | discount | price_below_min | refund | cancel_cfdi | inventory_adjust | <addon-declared>. */
+    policy: string
+    label: string
+    description?: React.ReactNode
+    /** Free-form audit data stored with the grant (product, qty, before → after…). */
+    context?: Record<string, unknown>
+    model?: string
+    recordId?: string
+    addonKey?: string
+}
+
+export interface ApprovalGateValue {
+    /** Resolves the grant, or null when the operator cancelled. */
+    requestApproval: (opts: RequestApprovalOptions) => Promise<ApprovalGrant | null>
+    /** True when the current user may do `policy` without asking anyone. */
+    canSelfApprove: (policy: string) => boolean
+}
+
+const ApprovalGateContext = createContext<ApprovalGateValue | null>(null)
+
+type Pending =
+    | { kind: 'inline'; opts: RequestApprovalOptions; resolve: (g: ApprovalGrant | null) => void }
+    | { kind: 'parked'; info: ApprovalRequiredInfo }
+
+export function ApprovalGateProvider({ children }: { children: React.ReactNode }) {
+    const { t } = useTranslation()
+    const api = useApi()
+    const can = useCan()
+    const [pending, setPending] = useState<Pending | null>(null)
+    const pendingRef = useRef<Pending | null>(null)
+    pendingRef.current = pending
+
+    useEffect(() => {
+        gateMountedDelta(1)
+        const onParked = (e: Event) => {
+            const info = (e as CustomEvent<ApprovalRequiredInfo>).detail
+            if (info?.requestId) setPending({ kind: 'parked', info })
+        }
+        window.addEventListener(APPROVAL_PARKED_EVENT, onParked)
+        return () => {
+            gateMountedDelta(-1)
+            window.removeEventListener(APPROVAL_PARKED_EVENT, onParked)
+        }
+    }, [])
+
+    const canSelfApprove = useCallback((policy: string) => can(approvalCapability(policy)), [can])
+
+    const requestApproval = useCallback(
+        (opts: RequestApprovalOptions) => {
+            if (can(approvalCapability(opts.policy))) {
+                return Promise.resolve<ApprovalGrant>({ id: null, policy: opts.policy, bypassed: true })
+            }
+            return new Promise<ApprovalGrant | null>((resolve) => {
+                pendingRef.current?.kind === 'inline' && pendingRef.current.resolve(null)
+                setPending({ kind: 'inline', opts, resolve })
+            })
+        },
+        [can],
+    )
+
+    const close = () => {
+        const p = pendingRef.current
+        if (p?.kind === 'inline') p.resolve(null)
+        setPending(null)
+    }
+
+    const submit = async ({ pin, reason }: ApprovalPinSubmit) => {
+        const p = pendingRef.current
+        if (!p) return
+        if (p.kind === 'inline') {
+            const res = await api.post('/approvals/pin-grant', {
+                policy: p.opts.policy,
+                label: p.opts.label,
+                pin,
+                reason,
+                context: p.opts.context,
+                model: p.opts.model,
+                record_id: p.opts.recordId,
+                addon_key: p.opts.addonKey,
+            })
+            const row = res.data?.data
+            p.resolve({ id: row?.id ?? null, policy: p.opts.policy, bypassed: false, reason })
+        } else {
+            await api.post(`/approvals/${p.info.requestId}/approve-pin`, { pin, reason })
+            toast.success(t('approvals.approved_applied', { defaultValue: 'Aprobado y aplicado' }))
+            window.dispatchEvent(new CustomEvent(APPROVAL_DECIDED_EVENT, { detail: p.info }))
+        }
+        setPending(null)
+    }
+
+    const value = useMemo<ApprovalGateValue>(() => ({ requestApproval, canSelfApprove }), [requestApproval, canSelfApprove])
+
+    const title =
+        pending?.kind === 'inline'
+            ? pending.opts.label
+            : pending?.kind === 'parked'
+              ? pending.info.label || t('approvals.parked_title', { defaultValue: 'Requiere aprobación' })
+              : ''
+
+    return (
+        <ApprovalGateContext.Provider value={value}>
+            {children}
+            <ApprovalPinDialog
+                open={pending !== null}
+                title={title}
+                description={pending?.kind === 'inline' ? pending.opts.description : undefined}
+                onSubmit={submit}
+                onCancel={close}
+            />
+        </ApprovalGateContext.Provider>
+    )
+}
+
+/**
+ * Access the gate. Without a provider the gate fails CLOSED for inline requests
+ * (resolves null) — never silently authorizes — but honours the capability
+ * bypass, and `canSelfApprove` follows `useCan()` (always-true with no
+ * <PermissionsProvider>, i.e. legacy hosts keep today's behaviour).
+ */
+export function useApprovalGate(): ApprovalGateValue {
+    const ctx = useContext(ApprovalGateContext)
+    const can = useCan()
+    return useMemo<ApprovalGateValue>(
+        () =>
+            ctx ?? {
+                canSelfApprove: (policy) => can(approvalCapability(policy)),
+                requestApproval: async (opts) =>
+                    can(approvalCapability(opts.policy)) ? { id: null, policy: opts.policy, bypassed: true } : null,
+            },
+        [ctx, can],
+    )
+}