@asteby/metacore-runtime-react 46.4.0 → 47.1.0

package/src/nav-permissions.ts

@@ -0,0 +1,58 @@
+// nav-permissions — the sidebar follows the role's EFFECTIVE permissions
+// (PIT-044). Before, every installed addon's entries were listed for every
+// role and only failed with a 403 after the click.
+//
+// Rules (same capability vocabulary as useCan/gateTableMetadata):
+//   - no <PermissionsProvider> mounted, or isAdmin / "*"  -> nothing hidden
+//     (useCan() is always-true then, so the predicate is a no-op);
+//   - an entry with an explicit `requires` capability     -> can(requires);
+//   - an entry pointing at a model screen (`/m/<model>`)  -> can('<model>.index');
+//   - any other entry (custom pages, activity, settings…) -> kept. Those are
+//     gated by the backend / the host's own `requires`, never guessed here.
+import { useCallback } from 'react'
+import { modelCapability, useCan, usePermissionsActive, type CanFn } from './permissions-context'
+
+/** Minimal structural shape of a sidebar leaf (matches `@asteby/metacore-ui` NavLinkItem). */
+export interface NavLeafLike {
+    url: string
+    requires?: string
+}
+
+const MODEL_URL_RE = /^\/(?:app\/)?m\/([^/?#]+)/i
+
+/** Model key of a `/m/<model>` url, or undefined for any other route. */
+export function modelFromNavUrl(url: string | undefined): string | undefined {
+    if (!url) return undefined
+    const m = MODEL_URL_RE.exec(url)
+    if (!m) return undefined
+    try {
+        return decodeURIComponent(m[1])
+    } catch {
+        return m[1]
+    }
+}
+
+/** Capability a leaf needs, or undefined when it is not gated by the SDK. */
+export function capabilityForNavItem(item: NavLeafLike): string | undefined {
+    if (item.requires) return item.requires
+    const model = modelFromNavUrl(item.url)
+    return model ? modelCapability(model, 'index') : undefined
+}
+
+/** Pure visibility predicate for a leaf given a capability checker. */
+export function isNavItemAllowed(item: NavLeafLike, can: CanFn): boolean {
+    const cap = capabilityForNavItem(item)
+    return cap ? can(cap) : true
+}
+
+/**
+ * Hook for the host's sidebar: returns a predicate for `<AppSidebar
+ * isItemVisible>` / `filterNavGroups`, or `undefined` when permission gating
+ * is not active (nothing to filter).
+ */
+export function useNavItemVisible(): ((item: NavLeafLike) => boolean) | undefined {
+    const can = useCan()
+    const active = usePermissionsActive()
+    const predicate = useCallback((item: NavLeafLike) => isNavItemAllowed(item, can), [can])
+    return active ? predicate : undefined
+}

package/src/navigation-builder.tsx

@@ -1,6 +1,7 @@
 // NavigationBuilder — merges a host's base sidebar with `manifest.navigation`
 // contributions from every loaded addon. Pure function + a React hook.
 import { useMemo } from 'react'
+import { useCan, type CanFn } from './permissions-context'
 
 export interface NavItem {
     key: string
@@ -59,8 +60,33 @@ export function mergeNavigation(base: NavItem[], contributions: AddonNavigationC
         .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
 }
 
+/**
+ * Drops items whose `requires` capability the user lacks (PIT-044). A parent
+ * left without children is dropped too, unless it links somewhere itself.
+ */
+export function filterNavigationByCapability(items: NavItem[], can: CanFn): NavItem[] {
+    const out: NavItem[] = []
+    for (const item of items) {
+        if (item.requires && !can(item.requires)) continue
+        if (item.children) {
+            const children = filterNavigationByCapability(item.children, can)
+            if (children.length === 0 && item.children.length > 0 && !item.to) continue
+            out.push({ ...item, children })
+        } else {
+            out.push(item)
+        }
+    }
+    return out
+}
+
 export function useNavigation(base: NavItem[], contributions: AddonNavigationContribution[]): NavItem[] {
-    return useMemo(() => mergeNavigation(base, contributions), [base, contributions])
+    // useCan() allows everything without a <PermissionsProvider>, so hosts that
+    // never opt in keep the full tree.
+    const can = useCan()
+    return useMemo(
+        () => filterNavigationByCapability(mergeNavigation(base, contributions), can),
+        [base, contributions, can],
+    )
 }
 
 export interface NavigationBuilderProps {

package/src/option-filter.ts

@@ -0,0 +1,88 @@
+// Option filter — lets a manifest HIDE options of a relation / dynamic picker
+// (e.g. keep cancelled invoices out of the "abonos" invoice selector, PIT-059).
+//
+// The filter runs client-side over the options the resolver already fetched, so
+// it needs no kernel change: it reads the extra scalar columns the options
+// endpoint returns (they land in `option.meta`) plus the standard `label`,
+// `name`, `description`, `color`, `icon` keys. Fully opt-in: a field without
+// `option_filter` / `optionFilter` behaves exactly as before.
+import type { ResolvedOption } from './use-options-resolver'
+
+export interface OptionFilterRule {
+    /** Option property to test: a `meta` key (e.g. `status`) or `id`/`value`/`label`/`name`/`description`/`color`/`icon`. */
+    field: string
+    /** Keep only options whose value equals this. */
+    equals?: string | number | boolean
+    /** snake_case alias of `notEquals`. */
+    not_equals?: string | number | boolean
+    /** Hide options whose value equals this. */
+    notEquals?: string | number | boolean
+    /** Keep only options whose value is one of these. */
+    in?: Array<string | number | boolean>
+    /** Hide options whose value is one of these. */
+    not_in?: Array<string | number | boolean>
+    /** camelCase alias of `not_in`. */
+    notIn?: Array<string | number | boolean>
+}
+
+/** One rule, or a list of rules that must ALL pass (AND). */
+export type OptionFilter = OptionFilterRule | OptionFilterRule[]
+
+type FilterCarrier = { optionFilter?: unknown; option_filter?: unknown }
+
+/** Reads the filter from a field (camelCase or the snake_case the kernel serves). */
+export function getOptionFilter(field: unknown): OptionFilterRule[] {
+    if (!field || typeof field !== 'object') return []
+    const f = field as FilterCarrier
+    const raw = f.optionFilter ?? f.option_filter
+    const list = Array.isArray(raw) ? raw : raw && typeof raw === 'object' ? [raw] : []
+    return list.filter(
+        (r): r is OptionFilterRule =>
+            !!r && typeof r === 'object' && typeof (r as OptionFilterRule).field === 'string' && (r as OptionFilterRule).field !== '',
+    )
+}
+
+function norm(v: unknown): string {
+    return String(v).trim().toLowerCase()
+}
+
+function readProp(opt: ResolvedOption, key: string): unknown {
+    if (key === 'id' || key === 'value' || key === 'label' || key === 'name' || key === 'description' || key === 'color' || key === 'icon' || key === 'image') {
+        return (opt as unknown as Record<string, unknown>)[key]
+    }
+    return opt.meta?.[key]
+}
+
+/** True when the option satisfies the rule. Comparison is trimmed + case-insensitive. */
+export function optionPassesRule(opt: ResolvedOption, rule: OptionFilterRule): boolean {
+    const raw = readProp(opt, rule.field)
+    const known = raw !== undefined && raw !== null
+    const v = known ? norm(raw) : ''
+    const notEquals = rule.notEquals ?? rule.not_equals
+    const notIn = rule.notIn ?? rule.not_in
+    // Positive rules need the property to exist; negative rules cannot exclude
+    // what they cannot see, so an option lacking the property is kept.
+    if (rule.equals !== undefined && !(known && v === norm(rule.equals))) return false
+    if (Array.isArray(rule.in) && !(known && rule.in.some((x) => norm(x) === v))) return false
+    if (notEquals !== undefined && known && v === norm(notEquals)) return false
+    if (Array.isArray(notIn) && known && notIn.some((x) => norm(x) === v)) return false
+    return true
+}
+
+/**
+ * Applies the field's filter to resolved options. Returns the SAME array when
+ * there is nothing to filter. `keepValue` (the current selection) is never
+ * hidden, so an existing record keeps showing its label after the option
+ * became ineligible.
+ */
+export function applyOptionFilter(
+    options: ResolvedOption[],
+    rules: OptionFilterRule[],
+    keepValue?: unknown,
+): ResolvedOption[] {
+    if (rules.length === 0) return options
+    const keep = keepValue === undefined || keepValue === null || keepValue === '' ? null : String(keepValue)
+    return options.filter(
+        (o) => (keep !== null && String(o.id) === keep) || rules.every((r) => optionPassesRule(o, r)),
+    )
+}

package/src/permissions-manager.tsx

@@ -73,7 +73,6 @@ import {
     Popover,
     PopoverContent,
     PopoverTrigger,
-    Separator,
     Skeleton,
     Collapsible,
     CollapsibleContent,
@@ -360,6 +359,31 @@ export function suggestRoleIcon(label: string): string {
     return 'Shield'
 }
 
+/** Label of the synthetic module that hosts the general (non-model) flags. */
+export const GENERAL_MODULE_LABEL = 'Permisos generales'
+
+/**
+ * The general flags (`general.work_after_hours`, …) as a synthetic module, so
+ * they are picked from the module combobox and edited in the same two-column
+ * action grid as any module's actions (#1021). Each flag keeps its full
+ * capability key through `PermissionActionDef.capability`.
+ */
+export function generalPermissionsModule(general: GeneralPermissionDef[]): PermissionModuleDef {
+    return {
+        key: 'general',
+        label: GENERAL_MODULE_LABEL,
+        icon: 'SlidersHorizontal',
+        kind: 'model',
+        actions: general.map((g) => ({
+            key: g.key.replace(/^general\./, ''),
+            label: g.label,
+            description: g.description,
+            capability: g.key,
+            kind: 'custom',
+        })),
+    }
+}
+
 /**
  * Normalize whatever `loadModules` returned into the canonical grouped shape.
  *
@@ -613,6 +637,15 @@ export function PermissionsManager({
 
     const allModules = React.useMemo(() => (groups ? flattenGroups(groups) : []), [groups])
 
+    // What the module picker lists: the catalog groups plus a trailing synthetic
+    // group for the general flags. `allModules` / "Otorgar todo" keep using the
+    // plain catalog, so that button's scope does not change.
+    const pickerGroups = React.useMemo<ModuleGroup[] | null>(() => {
+        if (!groups) return groups
+        if (!general || general.length === 0) return groups
+        return [...groups, { title: '', modules: [generalPermissionsModule(general)] }]
+    }, [groups, general])
+
     // ---- initial load: catalog + roles in parallel -------------------------
     React.useEffect(() => {
         let cancelled = false
@@ -670,8 +703,8 @@ export function PermissionsManager({
         [roles, activeRoleId],
     )
     const activeModule = React.useMemo(
-        () => moduleAtEntry(groups, activeModuleKey)?.module ?? null,
-        [groups, activeModuleKey],
+        () => moduleAtEntry(pickerGroups, activeModuleKey)?.module ?? null,
+        [pickerGroups, activeModuleKey],
     )
 
     const dirty = baseline !== null && draft !== null && !capabilitySetsEqual(baseline, draft)
@@ -841,8 +874,8 @@ export function PermissionsManager({
     const moduleTotal = activeModule?.actions.length ?? 0
     const checksDisabled = !activeRole || !draft || loadingPerms || saving
     const activeModuleGroupTitle = React.useMemo(
-        () => moduleAtEntry(groups, activeModuleKey)?.group.title ?? '',
-        [groups, activeModuleKey],
+        () => moduleAtEntry(pickerGroups, activeModuleKey)?.group.title ?? '',
+        [pickerGroups, activeModuleKey],
     )
 
     // ---- render --------------------------------------------------------------
@@ -1052,26 +1085,6 @@ export function PermissionsManager({
                                 )}
                             </div>
 
-                            {(general?.length ?? 0) > 0 && (
-                                <>
-                                    <Separator />
-                                    <div>
-                                        <h3 className="mb-2 text-sm font-semibold">Permisos Generales</h3>
-                                        <div className="flex flex-col gap-2">
-                                            {general!.map((g) => (
-                                                <CapabilityCheck
-                                                    key={g.key}
-                                                    checked={draft?.has(g.key) ?? false}
-                                                    disabled={checksDisabled}
-                                                    onToggle={() => toggleCapability(g.key)}
-                                                    label={g.label}
-                                                    description={g.description}
-                                                />
-                                            ))}
-                                        </div>
-                                    </div>
-                                </>
-                            )}
                         </CardContent>
                     </Card>
 
@@ -1122,7 +1135,7 @@ export function PermissionsManager({
                                         <CommandInput placeholder="Buscar módulo…" />
                                         <CommandList className="max-h-[360px]">
                                             <CommandEmpty>Sin módulos.</CommandEmpty>
-                                            {(groups ?? []).map((group, gi) => (
+                                            {(pickerGroups ?? []).map((group, gi) => (
                                                 <CommandGroup
                                                     key={group.title || `__untitled_${gi}`}
                                                     heading={group.title || undefined}

package/src/print-document-button.tsx

@@ -51,7 +51,15 @@ export function PrintDocumentButton({
             if (e.defaultPrevented) return
             setBusy(true)
             try {
-                await printDocument({ model, id, key: documentKey, mode, filename })
+                // A caller that handles errors itself keeps ownership of the error toast.
+                await printDocument({
+                    model,
+                    id,
+                    key: documentKey,
+                    mode,
+                    filename,
+                    feedback: onError ? { progress: true, success: true, error: false } : true,
+                })
             } catch (err) {
                 onError?.(err)
             } finally {

package/src/record-mutation-events.ts

@@ -0,0 +1,50 @@
+// record-mutation-events — a tiny window-level bus that tells every mounted
+// list (DynamicTable, DynamicKanban) "a record of model X just changed".
+//
+// Why: the lists only reloaded when the *caller* bumped `refreshTrigger`. A
+// create/edit/delete done from a dialog the shell opens (the dynamic record
+// dialog, a federated action modal, a wizard, a confirmation) never reached
+// the table, so the row stayed stale until a manual refresh (#1020). Emitting
+// here decouples the mutation site from the list that displays the model.
+
+export type RecordMutationKind = 'create' | 'update' | 'delete'
+
+export const RECORD_MUTATION_EVENT = 'metacore:record-mutated'
+
+export interface RecordMutationDetail {
+    /** Model key as the emitter knows it (matched case-insensitively). */
+    model: string
+    kind: RecordMutationKind
+}
+
+const norm = (m: string | undefined | null) => (m ?? '').trim().toLowerCase()
+
+/** Announce a successful mutation. Safe to call outside a browser (no-op). */
+export function emitRecordMutation(model: string | undefined | null, kind: RecordMutationKind): void {
+    if (!model || typeof window === 'undefined' || typeof CustomEvent === 'undefined') return
+    try {
+        window.dispatchEvent(
+            new CustomEvent<RecordMutationDetail>(RECORD_MUTATION_EVENT, { detail: { model, kind } }),
+        )
+    } catch {
+        /* a listener must never break the save flow */
+    }
+}
+
+/**
+ * Listen for mutations of `model` (case-insensitive). Returns an unsubscribe.
+ */
+export function subscribeRecordMutations(
+    model: string | undefined | null,
+    cb: (detail: RecordMutationDetail) => void,
+): () => void {
+    if (typeof window === 'undefined') return () => {}
+    const want = norm(model)
+    const handler = (e: Event) => {
+        const d = (e as CustomEvent<RecordMutationDetail>).detail
+        if (!d || !want || norm(d.model) !== want) return
+        cb(d)
+    }
+    window.addEventListener(RECORD_MUTATION_EVENT, handler)
+    return () => window.removeEventListener(RECORD_MUTATION_EVENT, handler)
+}

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { OptionFilter } from './option-filter'
 // Shared metadata shape consumed by every host. Some hosts add a `link`
 // action type with a `linkUrl` template — represented here as part of the
 // `type` union so the SDK can render it uniformly.
@@ -22,6 +23,63 @@ export interface ImportSpecMeta {
     instructions?: string[]
 }
 
+/** Paso de renglones de un tipo de documento (usa el editor de renglones del SDK). */
+export interface DocumentFormLines {
+    /** Campo del payload que recibe los renglones. Default: `lines` (o `lines_field` del manifest). */
+    field?: string
+    /** Columnas opcionales del editor (`discount`, `tax`, `unit`…). */
+    columns?: string[]
+    /** `sale` (precio de lista) o `cost` (compras). Default `sale`. */
+    price_source?: 'sale' | 'cost'
+    /** Al menos un renglón para guardar. Default true. */
+    required?: boolean
+    /** Título del paso. Default «Renglones». */
+    title?: string
+}
+
+/** Un tipo de documento (Factura, Nota de crédito, REP, Global, Traslado…). */
+export interface DocumentFormType {
+    key: string
+    label: string
+    description?: string
+    icon?: string
+    /** Valor que se escribe en `type_field` (p. ej. `"E"`). Default: `key`. */
+    value?: string
+    /** Campos del tipo, en el mismo vocabulario que los campos de una acción. */
+    fields: ActionFieldDef[]
+    /** Valores fijos que viajan en el alta de este tipo. */
+    defaults?: Record<string, unknown>
+    /** Con esto el tipo tiene paso de renglones. */
+    lines?: DocumentFormLines | boolean
+    /** Endpoint de alta propio de este tipo. Default: el del modelo. */
+    endpoint?: string
+    /** Texto del botón final. Default «Crear». */
+    submit_label?: string
+}
+
+export interface DocumentFormsManifest {
+    /** Columna discriminadora del modelo (p. ej. `"type"`). Sin ella no se escribe el tipo. */
+    type_field?: string
+    /** Campo por defecto de los renglones. Default `lines`. */
+    lines_field?: string
+    types: DocumentFormType[]
+}
+
+/**
+ * Audit columns of a model, served by the kernel (>= v0.188) on the table
+ * metadata. Each value is the COLUMN NAME (the key in the row), not a value;
+ * a key is omitted when the model lacks that column (append-only ledgers have
+ * only `created_*`). Purely additive — older kernels omit `audit` entirely.
+ */
+export interface AuditMeta {
+    created_at?: string
+    created_by?: string
+    updated_at?: string
+    updated_by?: string
+    deleted_at?: string
+    deleted_by?: string
+}
+
 export interface TableMetadata {
     title: string
     endpoint: string
@@ -36,6 +94,18 @@ export interface TableMetadata {
     canExport?: boolean
     canImport?: boolean
     canCreate?: boolean
+    /**
+     * Audit columns (when/who) of the model. Feeds `<AuditInfo>`; absent on
+     * older kernels or models without audit columns.
+     */
+    audit?: AuditMeta
+    /**
+     * Formularios de alta guiados por tipo de documento (FAC-12). Cuando trae
+     * al menos un tipo, `DynamicCRUDPage` abre `DocumentFormDialog` en lugar del
+     * formulario genérico del modelo. Lo sirve el kernel o el addon; el SDK no
+     * conoce campos fiscales.
+     */
+    document_forms?: DocumentFormsManifest
     /**
      * Cómo se pinta el alta genérica. `generic` (o ausente) es el botón Crear.
      * `hidden` lo quita. `action` lo quita porque el módulo trae la suya
@@ -331,6 +401,16 @@ export interface ColumnDefinition {
      * widgets — `searchEndpoint` stays as the legacy escape hatch.
      */
     ref?: string
+    /**
+     * Hides options of this relation/dynamic picker (e.g. cancelled invoices in
+     * the payments selector). One rule or a list (AND), tested client-side
+     * against the option's extra columns (`meta`): `{ field: 'status', not_in:
+     * ['cancelada'] }`. The options endpoint must return that column. Absent →
+     * the picker lists everything (retrocompat). See `option-filter.ts`.
+     */
+    optionFilter?: OptionFilter
+    /** snake_case alias served by the kernel manifest for `optionFilter`. */
+    option_filter?: OptionFilter
     /**
      * Write-time rules the SDK also pre-flights. Object form `{regex,min,max,custom}`
      * or a Laravel / go-playground string (`required|min:2|email`).
@@ -497,6 +577,16 @@ export interface ActionFieldDef {
      * `useOptionsResolver` against `/api/options/<ref>?field=id`.
      */
     ref?: string
+    /**
+     * Hides options of this relation/dynamic picker (e.g. cancelled invoices in
+     * the payments selector). One rule or a list (AND), tested client-side
+     * against the option's extra columns (`meta`): `{ field: 'status', not_in:
+     * ['cancelada'] }`. The options endpoint must return that column. Absent →
+     * the picker lists everything (retrocompat). See `option-filter.ts`.
+     */
+    optionFilter?: OptionFilter
+    /** snake_case alias served by the kernel manifest for `optionFilter`. */
+    option_filter?: OptionFilter
     /**
      * snake_case aliases the kernel manifest may serve for a belongs_to FK
      * target instead of `ref`. Treated as equivalent to `ref` by the SDK so a

package/src/use-options-resolver.ts

@@ -12,6 +12,7 @@
 // free; legacy callers that still ship `searchEndpoint` keep working.
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { useApi } from './api-context'
+import { applyOptionFilter, type OptionFilterRule } from './option-filter'
 import { loadQueryPart, optionsBatchToken, optionsModelFromUrl } from './query-batch'
 
 export interface ResolvedOption {
@@ -90,6 +91,13 @@ export interface UseOptionsResolverArgs {
      * `fieldKey` / `query` / `limit` exactly the same way.
      */
     endpoint?: string
+    /**
+     * Client-side rules that hide fetched options (see `option-filter.ts`).
+     * Empty/undefined → no filtering (retrocompat).
+     */
+    optionFilter?: OptionFilterRule[]
+    /** Current selection: never hidden by `optionFilter`, so its label survives. */
+    keepValue?: unknown
 }
 
 export interface UseOptionsResolverResult {
@@ -182,6 +190,8 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         enabled = true,
         endpoint,
         filterValue,
+        optionFilter,
+        keepValue,
     } = args
 
     const api = useApi()
@@ -322,8 +332,16 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         }
     }, [api, url, effectiveField, query, limit, enabled, filterValue, refreshKey])
 
+    // Rules arrive as a fresh array each render; key on their content.
+    const filterKey = optionFilter && optionFilter.length > 0 ? JSON.stringify(optionFilter) : ''
+    const visibleOptions = useMemo(
+        () => (filterKey ? applyOptionFilter(options, optionFilter ?? [], keepValue) : options),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [options, filterKey, keepValue],
+    )
+
     return {
-        options,
+        options: visibleOptions,
         meta,
         loading,
         error,

package/src/use-print-document.ts

@@ -17,6 +17,7 @@
 // The ApiClient is a PEER via <ApiProvider> (same one useAddonSettings uses), so
 // this hook constructs no client of its own.
 import { useCallback } from 'react'
+import { toast } from 'sonner'
 import { useApi } from './api-context'
 
 export interface PrintDocumentArgs {
@@ -40,6 +41,42 @@ export interface PrintDocumentArgs {
      * that is how downloads end up literally named with mustache braces.
      */
     filename?: string
+    /**
+     * User feedback. Default: a toast while the file is prepared, a success toast
+     * when it is ready and an error toast with the server's reason when it fails
+     * (a download used to give NO sign of life — PIT «Descargar Factura CFDI»).
+     * `false` silences all of it; `{ error: false }` leaves errors to the caller
+     * (the promise still rejects either way).
+     */
+    feedback?: boolean | { progress?: boolean; success?: boolean; error?: boolean }
+}
+
+const noun = (mode: 'print' | 'download' | 'open') =>
+    mode === 'download' ? 'Descargando documento…' : mode === 'open' ? 'Abriendo documento…' : 'Preparando impresión…'
+
+const readyMessage = (mode: 'print' | 'download' | 'open') =>
+    mode === 'download' ? 'Documento descargado' : mode === 'open' ? 'Documento abierto' : 'Documento listo para imprimir'
+
+/** Best-effort message from an error whose body is a Blob (responseType: 'blob'). */
+export async function documentErrorMessage(err: unknown): Promise<string> {
+    const fallback = 'No se pudo generar el documento. Inténtalo de nuevo.'
+    const e = err as { response?: { data?: unknown; status?: number }; message?: unknown } | undefined
+    let data = e?.response?.data
+    try {
+        if (typeof Blob !== 'undefined' && data instanceof Blob) {
+            data = JSON.parse(await data.text())
+        }
+    } catch {
+        data = undefined
+    }
+    const d = data as { message?: unknown; details?: unknown; error?: unknown } | string | undefined
+    if (typeof d === 'string' && d.trim()) return d.trim().slice(0, 200)
+    if (d && typeof d === 'object') {
+        const msg = [d.message, d.details, d.error].find((x) => typeof x === 'string' && x.trim()) as string | undefined
+        if (msg) return msg.trim()
+    }
+    if (e?.response?.status === 404) return 'El documento no está disponible todavía.'
+    return fallback
 }
 
 /** Parse filename from Content-Disposition (RFC 5987 / quoted). */
@@ -71,14 +108,14 @@ export function looksLikeFilenameTemplate(name: string | undefined): boolean {
  */
 export function usePrintDocument() {
     const api = useApi()
-    return useCallback(
+    const run = useCallback(
         async ({
             model,
             id,
             key,
-            mode = 'print',
+            mode,
             filename,
-        }: PrintDocumentArgs): Promise<string> => {
+        }: Required<Pick<PrintDocumentArgs, 'model' | 'id' | 'key' | 'mode'>> & Pick<PrintDocumentArgs, 'filename'>): Promise<string> => {
             const url = `/data/${encodeURIComponent(model)}/${encodeURIComponent(
                 id,
             )}/documents/${encodeURIComponent(key)}.pdf`
@@ -145,4 +182,30 @@ export function usePrintDocument() {
         },
         [api],
     )
+    return useCallback(
+        async ({
+            model,
+            id,
+            key,
+            mode = 'print',
+            filename,
+            feedback = true,
+        }: PrintDocumentArgs): Promise<string> => {
+            const fb = feedback === false ? {} : feedback === true ? { progress: true, success: true, error: true } : feedback
+            const toastId = fb.progress ? toast.loading(noun(mode)) : undefined
+            try {
+                const blobUrl = await run({ model, id, key, mode, filename })
+                if (toastId !== undefined) toast.dismiss(toastId)
+                if (fb.success) toast.success(readyMessage(mode))
+                return blobUrl
+            } catch (err) {
+                if (toastId !== undefined) toast.dismiss(toastId)
+                if (fb.error) toast.error(await documentErrorMessage(err))
+                throw err
+            } finally {
+                if (toastId !== undefined) toast.dismiss(toastId)
+            }
+        },
+        [run],
+    )
 }

package/src/use-record-mutation-tick.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from 'react'
+import { subscribeRecordMutations } from './record-mutation-events'
+
+/**
+ * A counter that increments whenever a record of `model` is created, updated
+ * or deleted anywhere in the app. Fold it into a list's refetch deps.
+ */
+export function useRecordMutationTick(model: string | undefined | null): number {
+    const [tick, setTick] = useState(0)
+    useEffect(() => subscribeRecordMutations(model, () => setTick((n) => n + 1)), [model])
+    return tick
+}

package/vitest.config.ts

@@ -5,5 +5,6 @@ export default defineConfig({
         environment: 'node',
         include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
         setupFiles: ['./vitest.setup.ts'],
+        testTimeout: 15000,
     },
 })

package/vitest.setup.ts

@@ -27,3 +27,10 @@ function installMemoryStorage(name: 'localStorage' | 'sessionStorage') {
 
 installMemoryStorage('localStorage')
 installMemoryStorage('sessionStorage')
+
+// `waitFor` defaults to 1s; the DynamicTable/DynamicKanban suites render large
+// trees and miss it when the whole monorepo's tests run in parallel (turbo).
+// A longer ceiling only affects failing waits, passing tests return immediately.
+import { configure } from '@testing-library/react'
+
+configure({ asyncUtilTimeout: 5000 })