@asteby/metacore-runtime-react 45.2.0 → 45.3.0

package/dist/use-addon-settings.d.ts

@@ -1,5 +1,11 @@
-/** Stable react-query key for an addon's per-org settings. */
-export declare function addonSettingsKey(addonKey: string): readonly ["addon-settings", string];
+/** Stable react-query key for an addon's per-org settings (per branch when given). */
+export declare function addonSettingsKey(addonKey: string, branchId?: string | null): readonly ["addon-settings", string, string] | readonly ["addon-settings", string];
+/**
+ * Settings URL. With a branch, the host answers the settings the addon runs
+ * with there: org values with each `scope: branch` key replaced by the branch's
+ * override (POS-1). Without one, the org values (legacy behaviour).
+ */
+export declare function addonSettingsUrl(addonKey: string, branchId?: string | null): string;
 /**
  * Merge saved org values over the caller's defaults so a never-saved setting
  * falls back to its default. Pure + exported for unit testing. Only keys that
@@ -19,6 +25,12 @@ export interface UseAddonSettingsOptions<T> {
     staleTime?: number;
     /** Defer fetching (e.g. until the addon key is known). */
     enabled?: boolean;
+    /**
+     * Read the settings as one branch sees them (manifest `scope: branch` keys
+     * resolve to the branch override, else the org value). Omit for org values.
+     * A terminal passes its active branch here.
+     */
+    branchId?: string | null;
 }
 export interface UseAddonSettingsResult<T> {
     /** Saved org values merged over `defaults`. Never null. */
@@ -52,5 +64,7 @@ export declare function useAddonSettings<T extends Record<string, unknown> = Rec
  * const update = useUpdateAddonSettings('pos')
  * update.mutate({ allowNegativeStock: true })
  */
-export declare function useUpdateAddonSettings<T extends Record<string, unknown> = Record<string, unknown>>(addonKey: string): import("@tanstack/react-query").UseMutationResult<Partial<T>, Error, Partial<T>, unknown>;
+export declare function useUpdateAddonSettings<T extends Record<string, unknown> = Record<string, unknown>>(addonKey: string, 
+/** Write branch overrides (only `scope: branch` keys; `null` clears one) instead of org values. */
+branchId?: string | null): import("@tanstack/react-query").UseMutationResult<Partial<T>, Error, Partial<T>, unknown>;
 //# sourceMappingURL=use-addon-settings.d.ts.map

package/dist/use-addon-settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-addon-settings.d.ts","sourceRoot":"","sources":["../src/use-addon-settings.ts"],"names":[],"mappings":"AA6BA,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,uCAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,EAChC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GACtC,CAAC,CAQH;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACrB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,EAAE,CAAC,CAAA;IACX,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxF,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,uBAAuB,CAAC,CAAC,CAAM,GACtC,sBAAsB,CAAC,CAAC,CAAC,CA8B3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9F,QAAQ,EAAE,MAAM,6FAgBnB"}
+{"version":3,"file":"use-addon-settings.d.ts","sourceRoot":"","sources":["../src/use-addon-settings.ts"],"names":[],"mappings":"AA6BA,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,qFAE1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGnF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,EAChC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GACtC,CAAC,CAQH;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACrB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,EAAE,CAAC,CAAA;IACX,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxF,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,uBAAuB,CAAC,CAAC,CAAM,GACtC,sBAAsB,CAAC,CAAC,CAAC,CA8B3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9F,QAAQ,EAAE,MAAM;AAChB,mGAAmG;AACnG,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,6FAiB3B"}

package/dist/use-addon-settings.js

@@ -22,9 +22,18 @@
 import { useMemo } from 'react';
 import { useMutation, useQuery, useQueryClient, } from '@tanstack/react-query';
 import { useApi } from './api-context';
-/** Stable react-query key for an addon's per-org settings. */
-export function addonSettingsKey(addonKey) {
-    return ['addon-settings', addonKey];
+/** Stable react-query key for an addon's per-org settings (per branch when given). */
+export function addonSettingsKey(addonKey, branchId) {
+    return branchId ? ['addon-settings', addonKey, branchId] : ['addon-settings', addonKey];
+}
+/**
+ * Settings URL. With a branch, the host answers the settings the addon runs
+ * with there: org values with each `scope: branch` key replaced by the branch's
+ * override (POS-1). Without one, the org values (legacy behaviour).
+ */
+export function addonSettingsUrl(addonKey, branchId) {
+    const base = `/api/addons/${addonKey}/settings`;
+    return branchId ? `${base}?branch_id=${encodeURIComponent(branchId)}` : base;
 }
 /**
  * Merge saved org values over the caller's defaults so a never-saved setting
@@ -59,11 +68,11 @@ export function mergeAddonSettings(defaults, stored) {
  */
 export function useAddonSettings(addonKey, opts = {}) {
     const api = useApi();
-    const { defaults, staleTime, enabled } = opts;
+    const { defaults, staleTime, enabled, branchId } = opts;
     const query = useQuery({
-        queryKey: addonSettingsKey(addonKey),
+        queryKey: addonSettingsKey(addonKey, branchId),
         queryFn: async () => {
-            const res = await api.get(`/api/addons/${addonKey}/settings`);
+            const res = await api.get(addonSettingsUrl(addonKey, branchId));
             const body = res.data;
             // Host envelope: { success, data: { <key>: <value> } }.
             const values = body?.success ? body.data : body;
@@ -92,17 +101,20 @@ export function useAddonSettings(addonKey, opts = {}) {
  * const update = useUpdateAddonSettings('pos')
  * update.mutate({ allowNegativeStock: true })
  */
-export function useUpdateAddonSettings(addonKey) {
+export function useUpdateAddonSettings(addonKey, 
+/** Write branch overrides (only `scope: branch` keys; `null` clears one) instead of org values. */
+branchId) {
     const api = useApi();
     const qc = useQueryClient();
     return useMutation({
         mutationFn: async (values) => {
-            const res = await api.put(`/api/addons/${addonKey}/settings`, values);
+            const res = await api.put(addonSettingsUrl(addonKey, branchId), values);
             const body = res.data;
             const saved = body?.success ? body.data : body;
             return (saved ?? values);
         },
         onSuccess: () => {
+            // Prefix match: refreshes the org read and every branch read.
             void qc.invalidateQueries({ queryKey: addonSettingsKey(addonKey) });
         },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "45.2.0",
+  "version": "45.3.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

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>

package/src/business/business.test.ts

@@ -162,3 +162,49 @@ describe('product search', () => {
         expect(line).toMatchObject({ product_id: 'v1', unit_price: 1200, tax_rate: 0.16, available: 3, description: 'Llanta X · 205/55R16' })
     })
 })
+
+import { canTransitionRma, computeReturnTotals, creditNoteRelation, returnSteps, serializeReturn, validateReturnChoices, type ReturnableLine } from './return'
+
+describe('return', () => {
+    const lines: ReturnableLine[] = [
+        { key: 'a', product_id: 'p1', description: 'Llanta', sold: 4, alreadyReturned: 1, unit_price: 1000, tax_rate: 0.16 },
+        { key: 'b', description: 'Servicio', sold: 1, unit_price: 200 },
+    ]
+    const ch = (q: number) => ({ a: { quantity: q, condition: 'sellable' as const, destination: 'stock' as const } })
+    it('tope por devolver = vendido − ya devuelto', () => {
+        expect(validateReturnChoices(lines, ch(4), 'x').errors['a.quantity']).toBeTruthy()
+        expect(validateReturnChoices(lines, ch(3), 'x').valid).toBe(true)
+    })
+    it('exige renglón y motivo; destino coherente con la condición', () => {
+        expect(validateReturnChoices(lines, {}, 'x').valid).toBe(false)
+        expect(validateReturnChoices(lines, ch(1), '').valid).toBe(false)
+        const bad = { a: { quantity: 1, condition: 'sellable' as const, destination: 'scrap' as const } }
+        expect(validateReturnChoices(lines, bad, 'x').errors['a.destination']).toBeTruthy()
+    })
+    it('totales con IVA y relación 03/01', () => {
+        expect(computeReturnTotals(lines, ch(2)).total).toBe(2320)
+        expect(creditNoteRelation(lines, ch(2))).toBe('03')
+        expect(creditNoteRelation(lines, { b: { quantity: 1, condition: 'sellable', destination: 'stock' } })).toBe('01')
+    })
+    it('sin almacén, Recibir es un paso; con almacén no', () => {
+        expect(returnSteps({ warehouseConnected: false })).toContain('receive')
+        expect(returnSteps({ warehouseConnected: true })).not.toContain('receive')
+    })
+    it('serializeReturn omite renglones en 0 y añade NC solo si hay reembolso a NC', () => {
+        const p = serializeReturn({ lines, choices: ch(2), reason: ' defecto ', received: true, refund: [{ kind: 'credit_note', amount: 2320 }] })
+        expect(p.lines).toHaveLength(1)
+        expect(p.reason).toBe('defecto')
+        expect(p.credit_note).toEqual({ relation: '03' })
+        expect(serializeReturn({ lines, choices: ch(2), reason: 'x', received: true, refund: [{ kind: 'cash', amount: 2320 }] }).credit_note).toBeUndefined()
+    })
+})
+
+describe('rma states', () => {
+    it('flujo feliz y motivo obligatorio al rechazar/cancelar', () => {
+        expect(canTransitionRma('draft', 'authorized').ok).toBe(true)
+        expect(canTransitionRma('received', 'settled').ok).toBe(true)
+        expect(canTransitionRma('authorized', 'rejected').ok).toBe(false)
+        expect(canTransitionRma('authorized', 'rejected', 'no aplica').ok).toBe(true)
+        expect(canTransitionRma('closed', 'draft').ok).toBe(false)
+    })
+})

package/src/business/catalog.ts

@@ -57,4 +57,12 @@ export const BUSINESS_COMPONENTS: readonly BusinessComponentSpec[] = [
         usedBy: ['ReturnWizard', 'Cancelación de apartado', 'Anticipos'],
         helpers: ['validateRefund', 'singleDestination', 'DEFAULT_REFUND_DESTINATIONS'],
     },
+    {
+        name: 'ReturnWizard',
+        value: 'lines: ReturnableLine[]',
+        events: ['onSubmit', 'onCancel'],
+        permissions: [],
+        usedBy: ['POS', 'Pedido', 'Factura', 'RMA', 'OT'],
+        helpers: ['computeReturnTotals', 'validateReturnChoices', 'creditNoteRelation', 'returnSteps', 'serializeReturn'],
+    },
 ] as const