@asteby/metacore-runtime-react 45.2.0 → 45.4.0

package/src/__tests__/dynamic-kanban.test.tsx

@@ -38,6 +38,10 @@ import {
     isTransitionAllowed,
     applyOptimisticMove,
     selectCardColumns,
+    isCardOverdue,
+    refLaneSource,
+    withRefLanes,
+    withGroupBy,
     cardMatchesLaneQuery,
     cardMatchesLaneFunnel,
     laneFunnelCount,
@@ -226,6 +230,143 @@ describe('selectCardColumns', () => {
     })
 })
 
+describe('selectCardColumns — explicit card layout (display_config)', () => {
+    const col = (key: string, styleConfig?: Record<string, unknown>, extra: object = {}) =>
+        ({ key, label: key, type: 'text', sortable: false, filterable: false, styleConfig, ...extra }) as any
+    const boardMeta = (columns: any[]) => ({ ...meta(), columns }) as any
+
+    it('shows every flagged field in column order and the flagged title', () => {
+        const { title, fields, explicit } = selectCardColumns(
+            boardMeta([
+                col('stage'),
+                col('folio', { card_title: true }),
+                col('customer', { card: true }),
+                col('plate', { card: true }),
+                col('promised_at', { card: true }),
+                col('amount', { card: true }),
+                col('notes'),
+            ]),
+        )
+        expect(explicit).toBe(true)
+        expect(title?.key).toBe('folio')
+        expect(fields.map((f) => f.key)).toEqual(['customer', 'plate', 'promised_at', 'amount'])
+    })
+
+    it('keeps the legacy heuristic when no column is flagged', () => {
+        expect(selectCardColumns(meta()).explicit).toBe(false)
+    })
+})
+
+describe('isCardOverdue', () => {
+    const now = Date.parse('2026-09-29T12:00:00Z')
+    const due = (cfg: Record<string, unknown>) =>
+        ({ key: 'promised_at', label: 'p', type: 'datetime', styleConfig: cfg }) as any
+
+    it('flags a past date on an opted-in column', () => {
+        expect(isCardOverdue({ promised_at: '2026-09-28T10:00:00Z' }, due({ overdue: true }), now)).toBe(true)
+    })
+    it('does not flag a future, empty or non-opted-in date', () => {
+        expect(isCardOverdue({ promised_at: '2026-09-30T10:00:00Z' }, due({ overdue: true }), now)).toBe(false)
+        expect(isCardOverdue({ promised_at: null }, due({ overdue: true }), now)).toBe(false)
+        expect(isCardOverdue({ promised_at: '2026-09-28T10:00:00Z' }, due({}), now)).toBe(false)
+    })
+    it('honours overdue_unless (delivered orders are never late)', () => {
+        const cfg = { overdue: true, overdue_unless: { stage: ['delivered'] } }
+        expect(isCardOverdue({ promised_at: '2026-09-28T10:00:00Z', stage: 'delivered' }, due(cfg), now)).toBe(false)
+        expect(isCardOverdue({ promised_at: '2026-09-28T10:00:00Z', stage: 'in_process' }, due(cfg), now)).toBe(true)
+    })
+})
+
+describe('withGroupBy (one model, several boards)', () => {
+    const boardMeta = (over: object = {}) =>
+        ({
+            columns: [
+                { key: 'stage', label: 'Etapa', type: 'text' },
+                { key: 'assigned_mechanic_id', label: 'Técnico', type: 'text', ref: 'users' },
+            ],
+            // The host projects ONE group_by per model: here another nav entry's.
+            group_by: 'assigned_mechanic_id',
+            stage_field: 'stage',
+            stages: [{ key: 'a', label: 'A' }],
+            transitions: [{ from: 'a', to: 'a' }],
+            smart_lanes: [{ key: 's', label: 'S', filters: [] }],
+            ...over,
+        }) as any
+
+    it('is the same object when there is no override or it matches the served group_by', () => {
+        const m = boardMeta()
+        expect(withGroupBy(m, undefined)).toBe(m)
+        expect(withGroupBy(m, 'assigned_mechanic_id')).toBe(m)
+        expect(withGroupBy(null, 'stage')).toBeNull()
+    })
+    it('ignores a column the model does not have', () => {
+        const m = boardMeta()
+        expect(withGroupBy(m, 'nope')).toBe(m)
+    })
+    it('keeps the stage machine when grouping by the stage column', () => {
+        const out = withGroupBy(boardMeta(), 'stage')!
+        expect(out.group_by).toBe('stage')
+        expect(out.stages).toHaveLength(1)
+        expect(out.transitions).toHaveLength(1)
+        expect(out.smart_lanes).toHaveLength(1)
+    })
+    it('falls back to the served group_by as stage column on hosts without stage_field', () => {
+        const out = withGroupBy(boardMeta({ stage_field: undefined, group_by: 'stage' }), 'assigned_mechanic_id')!
+        expect(out.stages).toBeUndefined()
+        const back = withGroupBy(boardMeta({ stage_field: undefined, group_by: 'assigned_mechanic_id' }), 'stage')
+        // no stage_field and the served group_by is not the stage column: cannot tell, machine dropped
+        expect(back!.stages).toBeUndefined()
+    })
+    it('drops the stage machine when grouping by another column', () => {
+        const out = withGroupBy(boardMeta({ group_by: 'stage' }), 'assigned_mechanic_id')!
+        expect(out.group_by).toBe('assigned_mechanic_id')
+        expect(out.stages).toBeUndefined()
+        expect(out.transitions).toBeUndefined()
+        expect(out.smart_lanes).toBeUndefined()
+        expect(refLaneSource(out)).toEqual({ ref: 'users' })
+    })
+})
+
+describe('reference lanes (group_by on a reference column)', () => {
+    const refMeta = (over: object = {}) =>
+        ({
+            columns: [{ key: 'assigned_mechanic_id', label: 'Técnico', type: 'text', ref: 'users' }],
+            group_by: 'assigned_mechanic_id',
+            ...over,
+        }) as any
+
+    it('resolves the lane source from the column ref or search endpoint', () => {
+        expect(refLaneSource(refMeta())).toEqual({ ref: 'users' })
+        expect(
+            refLaneSource(
+                refMeta({ columns: [{ key: 'assigned_mechanic_id', label: 't', type: 'text', searchEndpoint: '/options/x?field=id' }] }),
+            ),
+        ).toEqual({ endpoint: '/options/x?field=id' })
+    })
+    it('yields no source when stages or inline options already declare the lanes', () => {
+        expect(refLaneSource(refMeta({ stages: [{ key: 'a', label: 'A' }] }))).toBeNull()
+        expect(
+            refLaneSource(refMeta({ columns: [{ key: 'assigned_mechanic_id', label: 't', type: 'text', ref: 'users', options: [{ value: 'a', label: 'A' }] }] })),
+        ).toBeNull()
+        expect(refLaneSource(null)).toBeNull()
+    })
+    it('builds one lane per option, alphabetical, with no transitions', () => {
+        const out = withRefLanes(refMeta(), [
+            { value: 'u2', label: 'Zoe' },
+            { value: 'u1', label: 'Ana' },
+        ])
+        expect(deriveStages(out).map((s) => [s.key, s.label])).toEqual([
+            ['u1', 'Ana'],
+            ['u2', 'Zoe'],
+        ])
+        expect(out.transitions).toBeUndefined()
+    })
+    it('leaves the metadata alone while the options are still loading', () => {
+        const m = refMeta()
+        expect(withRefLanes(m, [])).toBe(m)
+    })
+})
+
 describe('cardMatchesLaneQuery', () => {
     const cols = [
         { key: 'title', label: 'Title', type: 'text', sortable: false, filterable: false },

package/src/__tests__/prefill-from-record.test.ts

@@ -144,3 +144,72 @@ describe('applyPrefillLock', () => {
         expect(applyPrefillLock(field)).toBe(field)
     })
 })
+
+// ---- fromField: rows seeded from a document picked in a sibling field --------
+
+import { prefillFromFieldRequests, prefillFromFieldRelationRequest } from '../action-modal-dispatcher'
+
+const receiptFields = (): ActionFieldDef[] => [
+    { key: 'purchase_order_id', label: 'OC', type: 'dynamic_select', ref: 'PurchaseOrder' } as ActionFieldDef,
+    receiveField({
+        key: 'items',
+        default: {
+            $prefillFromRecord: 'items',
+            fromField: 'purchase_order_id',
+            map: { product_id: 'product_variant_id', ordered: 'qty', received_so_far: 'qty_received' },
+            remaining: { target: 'qty_received', of: 'qty', minus: 'qty_received' },
+        },
+    } as Partial<ActionFieldDef>),
+]
+
+describe('prefillFromFieldRequests', () => {
+    it('lee el id del campo hermano y el modelo de su ref', () => {
+        const reqs = prefillFromFieldRequests(receiptFields(), { purchase_order_id: 'po-1' })
+        expect(reqs).toHaveLength(1)
+        expect(reqs[0]).toMatchObject({ fieldKey: 'items', refModel: 'PurchaseOrder', refId: 'po-1' })
+    })
+
+    it('desenvuelve {value,id} y devuelve refId vacío sin selección', () => {
+        expect(prefillFromFieldRequests(receiptFields(), { purchase_order_id: { id: 'po-2', label: 'OC-2' } })[0].refId).toBe('po-2')
+        expect(prefillFromFieldRequests(receiptFields(), { purchase_order_id: '' })[0].refId).toBe('')
+        expect(prefillFromFieldRequests(receiptFields(), {})[0].refId).toBe('')
+    })
+
+    it('ignora specs sin fromField o cuyo campo hermano no tiene ref', () => {
+        const noFrom = receiveField({ default: { $prefillFromRecord: 'items' } } as Partial<ActionFieldDef>)
+        expect(prefillFromFieldRequests([noFrom], {})).toEqual([])
+        const fields = receiptFields()
+        ;(fields[0] as any).ref = undefined
+        expect(prefillFromFieldRequests(fields, { purchase_order_id: 'x' })).toEqual([])
+    })
+})
+
+describe('prefillFromFieldRelationRequest', () => {
+    const rels = [
+        { name: 'goods_receipts', kind: 'one_to_many', through: 'GoodsReceipt', foreign_key: 'purchase_order_id' },
+        { name: 'items', kind: 'one_to_many', through: 'PurchaseOrderItem', foreign_key: 'purchase_order_id' },
+    ]
+    it('arma el request de hijos por la relación de la OC elegida', () => {
+        const [req] = prefillFromFieldRequests(receiptFields(), { purchase_order_id: 'po-1' })
+        expect(prefillFromFieldRelationRequest(req, rels)).toEqual({
+            endpoint: '/data/PurchaseOrderItem',
+            params: { f_purchase_order_id: 'eq:po-1', per_page: 200 },
+        })
+    })
+    it('null sin selección o si la relación no existe', () => {
+        const [empty] = prefillFromFieldRequests(receiptFields(), {})
+        expect(prefillFromFieldRelationRequest(empty, rels)).toBeNull()
+        const [req] = prefillFromFieldRequests(receiptFields(), { purchase_order_id: 'po-1' })
+        expect(prefillFromFieldRelationRequest(req, [])).toBeNull()
+    })
+    it('las filas resultantes descartan lo ya recibido por completo (remaining)', () => {
+        const [req] = prefillFromFieldRequests(receiptFields(), { purchase_order_id: 'po-1' })
+        const rows = buildPrefillRows(req.spec, {
+            items: [
+                { product_variant_id: 'a', qty: 10, qty_received: 4 },
+                { product_variant_id: 'b', qty: 5, qty_received: 5 },
+            ],
+        })
+        expect(rows).toEqual([{ product_id: 'a', ordered: 10, received_so_far: 4, qty_received: 6 }])
+    })
+})

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>