@asteby/metacore-runtime-react 45.0.0 → 45.3.0

package/dist/index.js

@@ -41,6 +41,9 @@ export { AddonLayoutProvider, useAddonLayout, useAddonLayoutControl, useDeclareA
 export * from './slot';
 export * from './capability-gate';
 export { PermissionsProvider, useCan, usePermissionsActive, makeCan, capabilityForActionKey, modelCapability, gateTableMetadata, resolveRowActions, } from './permissions-context';
+export { ApprovalPinDialog, approvalErrorMessage, } from './approval-pin-dialog';
+export { ApprovalGateProvider, useApprovalGate, approvalCapability, approvalRequiredInfo, approvalGateAvailable, APPROVAL_PARKED_EVENT, APPROVAL_DECIDED_EVENT, } from './approval-gate';
+export { ReasonPromptDialog, useReasonPrompt, reasonRequiredInfo, DEFAULT_REASON_MIN, } from './reason-prompt';
 export { useDynamicRowActions, } from './dynamic-row-actions';
 export { resolveRequiresAddon, setAddonInstallHandler, getAddonInstallHandler, requiresAddonName, useRequiresAddonLabel, RequiresAddonLock, RequiresAddonDialog, } from './requires-addon';
 export { ColorPickerField, DEFAULT_ROLE_COLOR, normalizeHex } from './color-picker-field';
@@ -48,6 +51,7 @@ export { PermissionsManager, moduleActionCapability, moduleCapabilities, granted
 export { applySidebarLayout, collectFolderKeys, folderAccessCapability, coreRefKey, addonModelRefKey, addonUrlRefKey, urlRefKey, leafRefFor, normalizeNavPath, slugifyFolderKey, isValidFolderKey, layoutTreeFromNavGroups, } from './apply-sidebar-layout';
 export { SidebarLayoutManager, } from './sidebar-layout-manager';
 export * from './org-runtime-context';
+export * from './business';
 export * from './org-runtime-provider';
 export * from './navigation-builder';
 export * from './i18n-provider';
@@ -99,3 +103,5 @@ export { WidgetCard, DeltaChip, WidgetEmpty, WidgetError, } from './widgets/widg
 export { formatWidgetValue, formatAxisTick, formatDelta, accentClasses, paletteColor, CHART_PALETTE, } from './widgets/widget-format';
 export { AssistInterview, AssistCardView } from './assist-interview';
 export { useAttributeClasses, resolveAttributeClasses, resetAttributeClassCache, } from './attribute-classes';
+// Página de documento (benchmark §5/§6): cabecera, badges, acciones por estado, botones inteligentes.
+export * from './document';

package/dist/reason-prompt.d.ts

@@ -0,0 +1,59 @@
+import React from 'react';
+/** What the server told us about the missing reason. */
+export interface ReasonRequiredInfo {
+    /** Minimum trimmed length the policy demands (default 3). */
+    min: number;
+    /** True when a reason WAS sent but was too short. */
+    tooShort: boolean;
+}
+export declare const DEFAULT_REASON_MIN = 3;
+/**
+ * Detects the kernel's mandatory-reason refusal in an axios error (or a bare
+ * response body): HTTP 422 with `errors.reason[0].code` of `required` | `min`.
+ * Returns null for any other error.
+ */
+export declare function reasonRequiredInfo(err: unknown): ReasonRequiredInfo | null;
+export interface ReasonPromptDialogProps {
+    open: boolean;
+    title: string;
+    description?: React.ReactNode;
+    /** Minimum trimmed length; the submit button stays disabled below it. */
+    min?: number;
+    /** Label of the confirm button (default "Continuar"). */
+    confirmLabel?: string;
+    /** Style the confirm button as destructive (delete / cancel). */
+    destructive?: boolean;
+    /** Inline error from a previous attempt. */
+    error?: string | null;
+    busy?: boolean;
+    onSubmit: (reason: string) => void;
+    onCancel: () => void;
+}
+export declare function ReasonPromptDialog({ open, title, description, min, confirmLabel, destructive, error, busy, onSubmit, onCancel, }: ReasonPromptDialogProps): React.JSX.Element;
+export interface RunWithReasonOptions<T> {
+    /** Dialog headline, e.g. "Eliminar registro". */
+    title: string;
+    description?: React.ReactNode;
+    confirmLabel?: string;
+    destructive?: boolean;
+    /**
+     * Performs the request. Called first WITHOUT a reason; when the server
+     * demands one it is called again with the operator's reason. Throw (axios
+     * style) on failure.
+     */
+    request: (reason?: string) => Promise<T>;
+    /** A reason already collected (bulk operations reuse one for every row). */
+    reason?: string;
+}
+export interface ReasonPromptApi {
+    /**
+     * Resolves the request's result, or `undefined` when the operator cancelled
+     * the reason prompt. Any error that is NOT a reason refusal is rethrown.
+     */
+    run: <T>(opts: RunWithReasonOptions<T>) => Promise<T | undefined>;
+    /** Render once near the caller: the dialog the helper opens. */
+    dialog: React.ReactNode;
+}
+/** See the module comment. Render `dialog` somewhere in the caller's tree. */
+export declare function useReasonPrompt(): ReasonPromptApi;
+//# sourceMappingURL=reason-prompt.d.ts.map

package/dist/reason-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reason-prompt.d.ts","sourceRoot":"","sources":["../src/reason-prompt.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAmD,MAAM,OAAO,CAAA;AAcvE,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IAC/B,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAA;IACX,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAA;CACpB;AAED,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAS1E;AAED,MAAM,WAAW,uBAAuB;IACpC,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,QAAQ,EAAE,MAAM,IAAI,CAAA;CACvB;AAED,wBAAgB,kBAAkB,CAAC,EAC/B,IAAI,EACJ,KAAK,EACL,WAAW,EACX,GAAwB,EACxB,YAAY,EACZ,WAAkB,EAClB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,GACX,EAAE,uBAAuB,qBAoDzB;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACnC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IACxC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC5B;;;OAGG;IACH,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IACjE,gEAAgE;IAChE,MAAM,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAUD,8EAA8E;AAC9E,wBAAgB,eAAe,IAAI,eAAe,CA6EjD"}

package/dist/reason-prompt.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Mandatory reason on destructive operations (PER-4).
+//
+// A manifest model declares `reason_required` (delete and/or actions such as
+// cancel). The kernel then answers a DELETE / action WITHOUT a reason with
+// 422 `errors.reason: [{code: "required" | "min", params: {min}}]`. Instead of
+// every screen carrying its own "motivo" prompt, `useReasonPrompt().run()` wraps
+// the request: it tries it, and when the server says a reason is needed it asks
+// once (a dialog) and retries with the reason attached. Screens that already know
+// they need one can pass `reason` up front through the same helper.
+//
+// The reason is stamped on the canonical event by the kernel, so the activity log
+// (RecordHistory) shows who removed/cancelled what, when, and why.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Loader2 } from 'lucide-react';
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Textarea, } from '@asteby/metacore-ui/primitives';
+export const DEFAULT_REASON_MIN = 3;
+/**
+ * Detects the kernel's mandatory-reason refusal in an axios error (or a bare
+ * response body): HTTP 422 with `errors.reason[0].code` of `required` | `min`.
+ * Returns null for any other error.
+ */
+export function reasonRequiredInfo(err) {
+    const data = err?.response?.data ?? err;
+    const issues = data?.errors?.reason;
+    if (!Array.isArray(issues) || issues.length === 0)
+        return null;
+    const first = issues[0];
+    const code = typeof first === 'string' ? first : first?.code;
+    if (code !== 'required' && code !== 'min')
+        return null;
+    const min = typeof first === 'object' && typeof first?.params?.min === 'number' ? first.params.min : DEFAULT_REASON_MIN;
+    return { min, tooShort: code === 'min' };
+}
+export function ReasonPromptDialog({ open, title, description, min = DEFAULT_REASON_MIN, confirmLabel, destructive = true, error, busy, onSubmit, onCancel, }) {
+    const { t } = useTranslation();
+    const [reason, setReason] = useState('');
+    useEffect(() => {
+        if (open)
+            setReason('');
+    }, [open]);
+    const ready = reason.trim().length >= min;
+    return (_jsx(Dialog, { open: open, onOpenChange: (o) => !o && !busy && onCancel(), children: _jsxs(DialogContent, { className: "sm:max-w-md", children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: title }), description ? _jsx(DialogDescription, { children: description }) : null] }), _jsxs("div", { className: "space-y-2", children: [_jsx("label", { htmlFor: "mc-reason", className: "text-sm font-medium", children: t('reason.label', { defaultValue: 'Motivo' }) }), _jsx(Textarea, { id: "mc-reason", autoFocus: true, rows: 3, value: reason, onChange: (e) => setReason(e.target.value), placeholder: t('reason.placeholder', { defaultValue: 'Explica por qué. Queda en la bitácora.' }) }), error ? _jsx("p", { className: "text-destructive text-sm", children: error }) : null, !error && reason.length > 0 && !ready ? (_jsx("p", { className: "text-muted-foreground text-xs", children: t('reason.min', { min, defaultValue: 'Escribe al menos {{min}} caracteres.' }) })) : null] }), _jsxs(DialogFooter, { children: [_jsx(Button, { variant: "outline", onClick: onCancel, disabled: busy, children: t('common.cancel', { defaultValue: 'Cancelar' }) }), _jsxs(Button, { variant: destructive ? 'destructive' : 'default', disabled: !ready || busy, onClick: () => onSubmit(reason.trim()), children: [busy ? _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }) : null, confirmLabel ?? t('reason.confirm', { defaultValue: 'Continuar' })] })] })] }) }));
+}
+/** See the module comment. Render `dialog` somewhere in the caller's tree. */
+export function useReasonPrompt() {
+    const { t } = useTranslation();
+    const [pending, setPending] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const pendingRef = useRef(null);
+    pendingRef.current = pending;
+    const run = useCallback((opts) => {
+        return new Promise((resolve, reject) => {
+            opts
+                .request(opts.reason)
+                .then((v) => resolve(v))
+                .catch((err) => {
+                const info = reasonRequiredInfo(err);
+                if (!info)
+                    return reject(err);
+                setPending({
+                    opts: opts,
+                    info,
+                    resolve: resolve,
+                    reject,
+                    error: null,
+                });
+            });
+        });
+    }, []);
+    const submit = async (reason) => {
+        const p = pendingRef.current;
+        if (!p)
+            return;
+        setBusy(true);
+        try {
+            const v = await p.opts.request(reason);
+            setPending(null);
+            p.resolve(v);
+        }
+        catch (err) {
+            const info = reasonRequiredInfo(err);
+            if (info) {
+                // Server still not satisfied (a longer minimum): stay open, say why.
+                setPending({
+                    ...p,
+                    info,
+                    error: t('reason.min', {
+                        min: info.min,
+                        defaultValue: 'Escribe al menos {{min}} caracteres.',
+                    }),
+                });
+            }
+            else {
+                setPending(null);
+                p.reject(err);
+            }
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const cancel = () => {
+        const p = pendingRef.current;
+        setPending(null);
+        p?.resolve(undefined);
+    };
+    const dialog = (_jsx(ReasonPromptDialog, { open: pending !== null, title: pending?.opts.title ?? '', description: pending?.opts.description, min: pending?.info.min, confirmLabel: pending?.opts.confirmLabel, destructive: pending?.opts.destructive, error: pending?.error, busy: busy, onSubmit: submit, onCancel: cancel }));
+    return { run, dialog };
+}

package/dist/server-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-error.d.ts","sourceRoot":"","sources":["../src/server-error.ts"],"names":[],"mappings":"AAcA,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb;;gDAE4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AA8BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAuBtF;AAED;;gFAEgF;AAChF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,KAAK,MAAM,CAAA;AAUvG;8EAC8E;AAC9E,MAAM,WAAW,UAAU;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AA6BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,GAAG,SAAS,CAazF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,EACb,CAAC,EAAE,SAAS,EACZ,QAAQ,CAAC,EAAE,MAAM,GAClB,MAAM,CAMR;AAED;6EAC6E;AAC7E,wBAAgB,qBAAqB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,EACjC,CAAC,EAAE,SAAS,EACZ,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAUD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAUN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,OAAO,EACZ,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChG,IAAI,CA4BN"}
+{"version":3,"file":"server-error.d.ts","sourceRoot":"","sources":["../src/server-error.ts"],"names":[],"mappings":"AAeA,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb;;gDAE4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AA8BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAuBtF;AAED;;gFAEgF;AAChF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,KAAK,MAAM,CAAA;AAUvG;8EAC8E;AAC9E,MAAM,WAAW,UAAU;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AA6BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,GAAG,SAAS,CAazF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,EACb,CAAC,EAAE,SAAS,EACZ,QAAQ,CAAC,EAAE,MAAM,GAClB,MAAM,CAMR;AAED;6EAC6E;AAC7E,wBAAgB,qBAAqB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,EACjC,CAAC,EAAE,SAAS,EACZ,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAUD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAUN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,OAAO,EACZ,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChG,IAAI,CA+CN"}

package/dist/server-error.js

@@ -11,6 +11,7 @@
 // the toast description, in ONE place so every call site behaves identically.
 import { toast } from 'sonner';
 import { validationCatalog, validationMessageKey } from './validation-catalog';
+import { APPROVAL_PARKED_EVENT, approvalGateAvailable, approvalRequiredInfo } from './approval-events';
 function formatIssueEntry(v) {
     if (v == null)
         return '';
@@ -187,6 +188,24 @@ export function toastServerError(err, opts) {
     const t = opts?.t;
     const lang = opts?.language;
     const cat = validationCatalog(lang);
+    // A write parked for approval is not a failure: say so, and when an
+    // <ApprovalGateProvider> is mounted offer to approve it right now with a PIN.
+    const parked = approvalRequiredInfo(err);
+    if (parked) {
+        const title = parked.label || (t ? t('approvals.sent', { defaultValue: 'Enviado a aprobación' }) : 'Enviado a aprobación');
+        toast.info(title, {
+            description: parked.roles.length
+                ? (t ? t('approvals.waiting_for', { defaultValue: 'Lo decide: {{roles}}', roles: parked.roles.join(', ') }) : parked.roles.join(', '))
+                : undefined,
+            action: parked.requestId && approvalGateAvailable()
+                ? {
+                    label: t ? t('approvals.approve_with_pin', { defaultValue: 'Aprobar con PIN' }) : 'Aprobar con PIN',
+                    onClick: () => window.dispatchEvent(new CustomEvent(APPROVAL_PARKED_EVENT, { detail: parked })),
+                }
+                : undefined,
+        });
+        return;
+    }
     const map = extractFieldErrors(err);
     if (map) {
         const localized = t

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.0.0",
+  "version": "45.3.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

package/src/__tests__/approval-gate.test.tsx

@@ -0,0 +1,134 @@
+// @vitest-environment happy-dom
+//
+// ApprovalGate: inline PIN grants + parked-request approval, and the capability
+// bypass that lets a supervisor skip their own prompt.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+
+vi.mock('react-i18next', () => ({
+    useTranslation: () => ({
+        t: (_k: string, opts?: { defaultValue?: string }) => opts?.defaultValue ?? _k,
+    }),
+}))
+vi.mock('sonner', () => ({ toast: Object.assign(vi.fn(), { info: vi.fn(), success: vi.fn(), error: vi.fn() }) }))
+
+import { ApiProvider, type ApiClient } from '../api-context'
+import { PermissionsProvider } from '../permissions-context'
+import {
+    ApprovalGateProvider,
+    useApprovalGate,
+    approvalRequiredInfo,
+    APPROVAL_PARKED_EVENT,
+    type ApprovalGrant,
+} from '../approval-gate'
+import { toastServerError } from '../server-error'
+import { toast } from 'sonner'
+
+afterEach(() => {
+    cleanup()
+    vi.clearAllMocks()
+})
+
+function makeApi(post: ApiClient['post']): ApiClient {
+    return { get: vi.fn(), post, put: vi.fn(), delete: vi.fn() } as unknown as ApiClient
+}
+
+let lastGrant: ApprovalGrant | null | undefined
+function Probe({ policy }: { policy: string }) {
+    const gate = useApprovalGate()
+    return (
+        <button
+            onClick={async () => {
+                lastGrant = await gate.requestApproval({ policy, label: 'Venta sin existencias', context: { qty: 3 } })
+            }}
+        >
+            ask
+        </button>
+    )
+}
+
+function mount(post: ApiClient['post'], caps: string[] = [], isAdmin = false) {
+    lastGrant = undefined
+    return render(
+        <ApiProvider client={makeApi(post)}>
+            <PermissionsProvider permissions={caps} isAdmin={isAdmin}>
+                <ApprovalGateProvider>
+                    <Probe policy="oversell" />
+                </ApprovalGateProvider>
+            </PermissionsProvider>
+        </ApiProvider>,
+    )
+}
+
+function fill(reason: string, pin: string) {
+    fireEvent.change(screen.getByLabelText('Motivo'), { target: { value: reason } })
+    fireEvent.change(screen.getByLabelText('PIN del supervisor'), { target: { value: pin } })
+}
+
+describe('ApprovalGate', () => {
+    it('a holder of general.approve_<policy> passes without a prompt', async () => {
+        const post = vi.fn()
+        mount(post, ['general.approve_oversell'])
+        await act(async () => fireEvent.click(screen.getByText('ask')))
+        expect(lastGrant).toEqual({ id: null, policy: 'oversell', bypassed: true })
+        expect(post).not.toHaveBeenCalled()
+        expect(screen.queryByLabelText('PIN del supervisor')).toBeNull()
+    })
+
+    it('posts pin-grant with reason + context and resolves the audit id', async () => {
+        const post = vi.fn().mockResolvedValue({ data: { success: true, data: { id: 'audit-1' } } })
+        mount(post)
+        await act(async () => fireEvent.click(screen.getByText('ask')))
+        const submit = screen.getByText('Autorizar').closest('button')!
+        expect(submit.hasAttribute('disabled')).toBe(true) // reason + PIN required
+        fill('cliente esperando', '4321')
+        await act(async () => fireEvent.click(submit))
+        await waitFor(() => expect(lastGrant).toBeDefined())
+        expect(post).toHaveBeenCalledWith(
+            '/approvals/pin-grant',
+            expect.objectContaining({ policy: 'oversell', pin: '4321', reason: 'cliente esperando', context: { qty: 3 } }),
+        )
+        expect(lastGrant).toMatchObject({ id: 'audit-1', bypassed: false })
+    })
+
+    it('a wrong PIN keeps the dialog open with an inline message and nothing resolves', async () => {
+        const post = vi.fn().mockRejectedValue({ response: { data: { error: { code: 'approval_pin_invalid' } } } })
+        mount(post)
+        await act(async () => fireEvent.click(screen.getByText('ask')))
+        fill('r', '0000')
+        await act(async () => fireEvent.click(screen.getByText('Autorizar').closest('button')!))
+        expect(await screen.findByRole('alert')).toBeTruthy()
+        expect(lastGrant).toBeUndefined()
+    })
+
+    it('cancelling resolves null (fail closed)', async () => {
+        mount(vi.fn())
+        await act(async () => fireEvent.click(screen.getByText('ask')))
+        await act(async () => fireEvent.click(screen.getByText('Cancelar')))
+        await waitFor(() => expect(lastGrant).toBeNull())
+    })
+
+    it('a parked approval_required toast offers the PIN and approves through approve-pin', async () => {
+        const post = vi.fn().mockResolvedValue({ data: { success: true } })
+        mount(post)
+        const err = {
+            response: {
+                data: { success: false, error: { code: 'approval_required' }, meta: { approval_request_id: 'req-9', approval_label: 'Precio bajo el piso', approval_roles: ['gerente'] } },
+            },
+        }
+        expect(approvalRequiredInfo(err)).toMatchObject({ requestId: 'req-9', roles: ['gerente'] })
+        toastServerError(err)
+        const opts = (toast.info as unknown as ReturnType<typeof vi.fn>).mock.calls[0][1]
+        expect(toast.error).not.toHaveBeenCalled()
+        await act(async () => opts.action.onClick())
+        fill('autorizado', '1234')
+        await act(async () => fireEvent.click(screen.getByText('Autorizar').closest('button')!))
+        await waitFor(() => expect(post).toHaveBeenCalledWith('/approvals/req-9/approve-pin', { pin: '1234', reason: 'autorizado' }))
+    })
+
+    it('without a gate mounted the parked toast has no PIN action and the event is inert', () => {
+        toastServerError({ response: { data: { error: { code: 'approval_required' }, meta: { approval_request_id: 'x' } } } })
+        expect((toast.info as unknown as ReturnType<typeof vi.fn>).mock.calls[0][1].action).toBeUndefined()
+        window.dispatchEvent(new CustomEvent(APPROVAL_PARKED_EVENT, { detail: { requestId: 'x', roles: [] } }))
+    })
+})

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 }])
+    })
+})