@asteby/metacore-runtime-react 36.1.0 → 37.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @asteby/metacore-runtime-react
 
+## 37.0.0
+
+### Minor Changes
+
+- a0616e1: `DynamicTable` acepta la prop opcional `allowedActionKeys?: string[]`: un allowlist de acciones de fila (por `key` del manifest v3) a renderizar para ESA instancia de la tabla, en vez de todas las acciones que el modelo declara. Permite que dos vistas del mismo modelo (una tabla genérica y una pantalla de propósito específico, ej. una cola de aprobación de crédito) muestren distintas acciones sin tocar el manifest ni duplicar el modelo. `undefined` conserva el comportamiento actual (todas las acciones).
+- d1ffa4f: Realtime en React: `RealtimeProvider`, `useRealtime`, `useRealtimeInvalidate` (invalida las queries del QueryClient del host cuya key menciona el modelo/tabla), `useRealtimeStatus`, `useRealtimeTick` y `queryKeyMatchesEvent`. `DynamicTable` y `DynamicKanban` aceptan la prop opt-in `realtime` (apagada por default; `<RealtimeProvider defaultRealtime>` cambia el default) para refetch en vivo ante `DATA_EVENT` del modelo.
+
+### Patch Changes
+
+- Updated dependencies [d1ffa4f]
+  - @asteby/metacore-sdk@3.7.0
+
 ## 36.1.0
 
 ### Minor Changes

package/README.md

@@ -33,6 +33,39 @@ Peers: `react`, `react-dom`, `react-i18next`, `i18next`, `@tanstack/react-router
 | `<LicenseGate state={…} onActivate={…}>` | El blindaje del negocio: envuelve la app; bloquea con un modal full-screen no descartable cuando la licencia de instancia falta/venció, degrada con banner en `grace`/`stale`. Branding-aware. |
 | `<LicenseExpiryBanner state={…} />` / `<LicenseStatusBadge status={…} />` | Piezas sueltas del gate para Ajustes u otros lugares. |
 | `isLicenseOperable` / `isLicenseBlocking` / `isPresetEntitled` / `isTrialExpired` | Helpers puros sobre `LicenseState`, espejo de `State.Operable()/Blocking()` del backend. |
+| `<RealtimeProvider client={…} />` / `useRealtime()` / `useRealtimeInvalidate()` / `useRealtimeStatus()` / `useRealtimeTick()` | Reacción en vivo a `DATA_EVENT` del host (ver [Realtime](#realtime)). |
+
+## Realtime
+
+El host expone un `RealtimeAPI` (`@asteby/metacore-sdk`) — en ops viaja como
+`host.realtime` a las rutas inmersivas y como `api.realtime` a `register(api)`.
+Los frames son org-scoped y **sin valores de fila** (identidad + qué llaves
+cambiaron); la reacción típica es "refetch lo que muestro".
+
+```tsx
+// Host: montar una vez, dentro del QueryClientProvider y del provider de WS.
+<RealtimeProvider client={realtimeClient}>…</RealtimeProvider>
+
+// Addon federado: pasar el cliente explícito — el contexto React NO cruza la
+// frontera de module federation, el objeto plano sí.
+useRealtime({ models: ['SalesOrder'], client: host.realtime }, (e) => {
+  if (e.action === 'resync' || e.id === currentId) refetch()
+})
+
+// Invalidar react-query (usa SIEMPRE el QueryClient del host — nunca crees otro):
+useRealtimeInvalidate({ models: ['SalesOrder', 'sales_order_items'], client: host.realtime })
+
+// Tablas y kanbans: opt-in por prop (apagado por default).
+<DynamicTable model="SalesOrder" realtime />
+<DynamicKanban model="WorkOrder" realtime />
+// …o global para todo lo que cuelgue del provider:
+<RealtimeProvider client={realtimeClient} defaultRealtime>
+```
+
+`useRealtimeInvalidate` invalida toda query cuya key (string, array anidado u
+objeto) mencione el modelo, la tabla o `addon.Model` — también como segmento de
+una ruta (`/data/sales_orders?…`). Se puede reemplazar el matcher con `match`.
+Todos los hooks son no-op cuando no hay cliente (host sin realtime).
 
 ## Blindaje de licencia (`LicenseGate`)
 

package/dist/dynamic-kanban.d.ts

@@ -106,6 +106,12 @@ export interface DynamicKanbanProps {
     endpoint?: string;
     /** Bump to force a metadata + records refetch (same contract as DynamicTable). */
     refreshTrigger?: any;
+    /**
+     * Refetch the board when the host's realtime client reports a data event
+     * for this model (same contract as DynamicTable's `realtime`). Off by
+     * default; `<RealtimeProvider defaultRealtime>` flips the default.
+     */
+    realtime?: boolean;
     /** Called when a card is clicked (outside its action menu). */
     onCardClick?: (row: any) => void;
     /**
@@ -136,5 +142,5 @@ export interface DynamicKanbanProps {
      */
     defaultFilters?: Record<string, any>;
 }
-export declare function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, onAction, pageSize, lanePageSize, timeZone, currency, defaultFilters, }: DynamicKanbanProps): React.JSX.Element;
+export declare function DynamicKanban({ model, endpoint, refreshTrigger, realtime: realtimeProp, onCardClick, onAction, pageSize, lanePageSize, timeZone, currency, defaultFilters, }: DynamicKanbanProps): React.JSX.Element;
 //# sourceMappingURL=dynamic-kanban.d.ts.map

package/dist/dynamic-kanban.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-kanban.d.ts","sourceRoot":"","sources":["../src/dynamic-kanban.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"dynamic-kanban.d.ts","sourceRoot":"","sources":["../src/dynamic-kanban.tsx"],"names":[],"mappings":"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"}

package/dist/dynamic-kanban.js

@@ -12,6 +12,7 @@ import { Badge, Button, Card, CardContent, DropdownMenu, DropdownMenuContent, Dr
 import { ColumnFilterControl, FilterValueCombobox } from '@asteby/metacore-ui/data-table';
 import { generateBadgeStyles, optionColor } from '@asteby/metacore-ui/lib';
 import { useApi } from './api-context';
+import { useRealtimeDefault, useRealtimeTick } from './realtime-context';
 import { useStageAutomations, StageAutomationsButton, } from './stage-automations';
 import { useCustomStages, splitCustomStages, mergeLaneStages, resolveSmartLanes, cardMatchesStageFilters, smartLaneParams, AddStageColumn, CustomStageDialog, CustomStageDeleteDialog, StageConfigDialog, SmartLane, } from './custom-stages';
 import { useStageOverrides } from './stage-overrides';
@@ -261,10 +262,17 @@ function useIsDarkTheme() {
     }, []);
     return isDark;
 }
-export function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, onAction, pageSize = 50, lanePageSize = 25, timeZone, currency, defaultFilters, }) {
+export function DynamicKanban({ model, endpoint, refreshTrigger, realtime: realtimeProp, onCardClick, onAction, pageSize = 50, lanePageSize = 25, timeZone, currency, defaultFilters, }) {
     const { t, i18n } = useTranslation();
     const api = useApi();
     const isDark = useIsDarkTheme();
+    // Realtime refetch (opt-in) — debounced counter bumped by DATA_EVENTs for
+    // this model; folded into the board refetch effect next to refreshTrigger.
+    const realtimeDefault = useRealtimeDefault();
+    const realtimeTick = useRealtimeTick({
+        models: [model],
+        enabled: realtimeProp ?? realtimeDefault,
+    });
     // Stage automations (Bitrix-style per-lane rules). Degrades to no-op when
     // the host has no `/stage-automations` endpoint — the ⚡ affordance hides.
     const automations = useStageAutomations(model);
@@ -518,7 +526,9 @@ export function DynamicKanban({ model, endpoint, refreshTrigger, onCardClick, on
             void fetchData();
         }, 200);
         return () => clearTimeout(handle);
-    }, [fetchData, metadata, refreshTrigger]);
+        // realtimeTick: data events for this model (see the `realtime` prop).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fetchData, metadata, refreshTrigger, realtimeTick]);
     // Filterable fields for the toolbar, in metadata order (explicit filters
     // first, then filterable columns), each labeled from its metadata source.
     const filterFields = useMemo(() => {

package/dist/dynamic-table.d.ts

@@ -20,6 +20,17 @@ export interface DynamicTableProps {
     /** Hide the export action on this view. See `hideImport`. */
     hideExport?: boolean;
     hiddenColumns?: string[];
+    /**
+     * Row-action ALLOWLIST for this table instance, by action key (manifest
+     * v3 NavItem.actions, carried through the host's nav item for this route).
+     * When set, only these row actions render — even though the model may
+     * declare more. Lets two views of the SAME model differ: a generic list
+     * keeps every action, while a purpose-built screen (e.g. a credit-approval
+     * queue) shows only authorize_credit/reject_credit instead of every action
+     * SalesOrder declares (Generar factura, Cancelar, etc. included).
+     * Undefined → every row action the model declares (unchanged default).
+     */
+    allowedActionKeys?: string[];
     onAction?: (action: string, row: any) => void;
     /**
      * Called when the user clicks anywhere on a data row (not on a checkbox,
@@ -29,6 +40,13 @@ export interface DynamicTableProps {
      */
     onRowClick?: (row: any) => void;
     refreshTrigger?: any;
+    /**
+     * Refetch when the host's realtime client reports a data event for this
+     * model (created/updated/deleted by anyone in the org, or a `resync`).
+     * Off by default; `<RealtimeProvider defaultRealtime>` turns it on for
+     * every table, and an explicit prop always wins. No-op without a client.
+     */
+    realtime?: boolean;
     defaultFilters?: Record<string, any>;
     extraColumns?: ColumnDef<any>[];
     /**
@@ -73,5 +91,5 @@ export interface DynamicTableProps {
      */
     infiniteScroll?: boolean;
 }
-export declare function DynamicTable({ model, endpoint, mutationEndpoint, enableUrlSync, hideImport, hideExport, hiddenColumns, onAction, onRowClick, refreshTrigger, defaultFilters, extraColumns, getDynamicColumns, timeZone, currency, pagination: paginationMode, infiniteScroll: infiniteScrollProp, }: DynamicTableProps): import("react").JSX.Element;
+export declare function DynamicTable({ model, endpoint, mutationEndpoint, enableUrlSync, hideImport, hideExport, hiddenColumns, allowedActionKeys, onAction, onRowClick, refreshTrigger, realtime: realtimeProp, defaultFilters, extraColumns, getDynamicColumns, timeZone, currency, pagination: paginationMode, infiniteScroll: infiniteScrollProp, }: DynamicTableProps): import("react").JSX.Element;
 //# sourceMappingURL=dynamic-table.d.ts.map

package/dist/dynamic-table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-table.d.ts","sourceRoot":"","sources":["../src/dynamic-table.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAKH,KAAK,SAAS,EAajB,MAAM,uBAAuB,CAAA;AAgC9B,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AA4FnF,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC/B,cAAc,CAAC,EAAE,GAAG,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACpC,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAA;IAC/B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,UAAU,CAAA;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,wBAAgB,YAAY,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,aAAoB,EACpB,UAAU,EACV,UAAU,EACV,aAAkB,EAClB,QAAQ,EACR,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAiB,EACjB,iBAA4C,EAC5C,QAAQ,EACR,QAAQ,EACR,UAAU,EAAE,cAAc,EAC1B,cAAc,EAAE,kBAA0B,GAC7C,EAAE,iBAAiB,+BAkvCnB"}
+{"version":3,"file":"dynamic-table.d.ts","sourceRoot":"","sources":["../src/dynamic-table.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAKH,KAAK,SAAS,EAajB,MAAM,uBAAuB,CAAA;AAiC9B,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AA4FnF,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC/B,cAAc,CAAC,EAAE,GAAG,CAAA;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACpC,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAA;IAC/B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,UAAU,CAAA;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,wBAAgB,YAAY,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,aAAoB,EACpB,UAAU,EACV,UAAU,EACV,aAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,UAAU,EACV,cAAc,EACd,QAAQ,EAAE,YAAY,EACtB,cAAc,EACd,YAAiB,EACjB,iBAA4C,EAC5C,QAAQ,EACR,QAAQ,EACR,UAAU,EAAE,cAAc,EAC1B,cAAc,EAAE,kBAA0B,GAC7C,EAAE,iBAAiB,+BAuwCnB"}

package/dist/dynamic-table.js

@@ -23,6 +23,7 @@ import { toast } from 'sonner';
 import { Progress } from './dialogs/_primitives';
 import { useMetadataCache } from './metadata-cache';
 import { useApi, useCurrentBranch } from './api-context';
+import { useRealtimeDefault, useRealtimeTick } from './realtime-context';
 import { defaultGetDynamicColumns, DATE_CELL_TYPES, aggregateOf, formatAggregateTotal } from './dynamic-columns';
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders';
 import { translateOptionLabels } from './filter-chips';
@@ -104,13 +105,20 @@ function writeStoredPageSize(model, size) {
         // quota / private mode — persistence is a nicety, never fatal
     }
 }
-export function DynamicTable({ model, endpoint, mutationEndpoint, enableUrlSync = true, hideImport, hideExport, hiddenColumns = [], onAction, onRowClick, refreshTrigger, defaultFilters, extraColumns = [], getDynamicColumns = defaultGetDynamicColumns, timeZone, currency, pagination: paginationMode, infiniteScroll: infiniteScrollProp = false, }) {
+export function DynamicTable({ model, endpoint, mutationEndpoint, enableUrlSync = true, hideImport, hideExport, hiddenColumns = [], allowedActionKeys, onAction, onRowClick, refreshTrigger, realtime: realtimeProp, defaultFilters, extraColumns = [], getDynamicColumns = defaultGetDynamicColumns, timeZone, currency, pagination: paginationMode, infiniteScroll: infiniteScrollProp = false, }) {
     // The explicit `pagination` prop wins; the legacy `infiniteScroll` boolean
     // still selects the mode when `pagination` is absent (back-compat).
     const infiniteScroll = paginationMode ? paginationMode === 'infinite' : infiniteScrollProp;
     const { t, i18n } = useTranslation();
     const api = useApi();
     const currentBranch = useCurrentBranch();
+    // Realtime refetch (opt-in): a debounced counter that bumps on every
+    // DATA_EVENT for this model and rides the same deps as `refreshTrigger`.
+    const realtimeDefault = useRealtimeDefault();
+    const realtimeTick = useRealtimeTick({
+        models: [model],
+        enabled: realtimeProp ?? realtimeDefault,
+    });
     const prevBranchId = useRef(currentBranch?.id);
     const { getMetadata, setMetadata: cacheMetadata } = useMetadataCache();
     const cachedMeta = getMetadata(model);
@@ -611,7 +619,8 @@ export function DynamicTable({ model, endpoint, mutationEndpoint, enableUrlSync
         finally {
             setLoadingData(false);
         }
-    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, endpoint, currentBranch?.id, api, enableUrlSync]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, realtimeTick, endpoint, currentBranch?.id, api, enableUrlSync]);
     // Columns whose metadata opts into a footer total (display_config.aggregate
     // → styleConfig.aggregate). When empty, no footer row is rendered and no
     // aggregate request is made.
@@ -772,8 +781,9 @@ export function DynamicTable({ model, endpoint, mutationEndpoint, enableUrlSync
         // matching the classic path (fetchData carries refreshTrigger in its
         // deps). Without it the comment above lied: infinite lists silently
         // failed to reload after a create ("a veces no recarga la tabla").
+        // realtimeTick plays the same role for data events (see the `realtime` prop).
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [infiniteScroll, metadata, filterSignature, refreshTrigger]);
+    }, [infiniteScroll, metadata, filterSignature, refreshTrigger, realtimeTick]);
     const handleRefresh = useCallback(() => {
         // Infinite mode owns its own list: refresh reloads page 1 and drops the
         // accumulated pages (a classic fetchData would collapse it to one small
@@ -999,15 +1009,27 @@ export function DynamicTable({ model, endpoint, mutationEndpoint, enableUrlSync
         // Row-action column only renders per-row actions. Table-level placements
         // ("table"/"create") are surfaced by <ModelActionToolbar> at the page
         // level, so strip them here to avoid a meaningless per-row button.
-        const rowMetadata = viewMetadata.actions?.some((a) => a.placement === 'table' || a.placement === 'create')
-            ? { ...viewMetadata, actions: viewMetadata.actions.filter((a) => !a.placement || a.placement === 'row') }
-            : viewMetadata;
+        // `allowedActionKeys`, when given, further narrows the row set to a
+        // per-VIEW allowlist — two nav entries on the same model (a generic
+        // list vs. a purpose-built approval queue) can then show different
+        // actions instead of every action the model declares.
+        const rowMetadata = (() => {
+            let actions = viewMetadata.actions;
+            if (actions?.some((a) => a.placement === 'table' || a.placement === 'create')) {
+                actions = actions.filter((a) => !a.placement || a.placement === 'row');
+            }
+            if (allowedActionKeys && actions) {
+                const allowed = new Set(allowedActionKeys);
+                actions = actions.filter((a) => allowed.has(a.key));
+            }
+            return actions === viewMetadata.actions ? viewMetadata : { ...viewMetadata, actions };
+        })();
         const baseColumns = getDynamicColumns(rowMetadata, handleInternalAction, t, i18n.language, columnFilterConfigs, timeZone, currency);
         const filteredBase = baseColumns.filter((col) => !hiddenColumns.includes(col.id));
         const actionsCol = filteredBase.find((c) => c.id === 'actions');
         const otherCols = filteredBase.filter((c) => c.id !== 'actions');
         return [...otherCols, ...extraColumns, ...(actionsCol ? [actionsCol] : [])];
-    }, [viewMetadata, handleInternalAction, hiddenColumns, extraColumns, t, i18n.language, columnFilterConfigs, getDynamicColumns, timeZone, currency]);
+    }, [viewMetadata, handleInternalAction, hiddenColumns, allowedActionKeys, extraColumns, t, i18n.language, columnFilterConfigs, getDynamicColumns, timeZone, currency]);
     const filters = useMemo(() => [], []);
     const table = useReactTable({
         data,

package/dist/index.d.ts

@@ -41,6 +41,7 @@ export * from './print-document-button';
 export * from './use-org-document-templates';
 export * from './document-template-editor';
 export * from './metadata-cache';
+export { RealtimeProvider, useRealtimeClient, useRealtimeDefault, useRealtime, useRealtimeStatus, useRealtimeInvalidate, useRealtimeTick, queryKeyMatchesEvent, type RealtimeContextValue, type RealtimeProviderProps, type UseRealtimeOptions, type UseRealtimeInvalidateOptions, type UseRealtimeTickOptions, } from './realtime-context';
 export { ADDON_MANIFEST_CHANGED_TYPE, wireHotSwapInvalidation, useManifestHotSwapSubscriber, type AddonManifestChangedMessage, type ManifestHotSwapClient, type WireHotSwapInvalidationOptions, } from './manifest-hotswap-subscriber';
 export { useHotSwapReload, applyHotSwapReload, withVersionParam, clearFederationContainer, shortenHash, type HotSwapReloadStrategy, type HotSwapReloadConfig, type HotSwapReloadAction, type HotSwapReloadDeps, type UseHotSwapReloadResult, } from './hotswap-reload-policy';
 export * from './dynamic-icon';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -46,6 +46,7 @@ export * from './print-document-button';
 export * from './use-org-document-templates';
 export * from './document-template-editor';
 export * from './metadata-cache';
+export { RealtimeProvider, useRealtimeClient, useRealtimeDefault, useRealtime, useRealtimeStatus, useRealtimeInvalidate, useRealtimeTick, queryKeyMatchesEvent, } from './realtime-context';
 export { ADDON_MANIFEST_CHANGED_TYPE, wireHotSwapInvalidation, useManifestHotSwapSubscriber, } from './manifest-hotswap-subscriber';
 export { useHotSwapReload, applyHotSwapReload, withVersionParam, clearFederationContainer, shortenHash, } from './hotswap-reload-policy';
 export * from './dynamic-icon';

package/dist/realtime-context.d.ts

@@ -0,0 +1,82 @@
+import type { QueryKey } from '@tanstack/react-query';
+import type { DataEvent, DataEventHandler, RealtimeAPI, RealtimeStatus, RealtimeSubscribeOptions } from '@asteby/metacore-sdk';
+export interface RealtimeContextValue {
+    /** Host-provided client, or null when the host has no realtime. */
+    client: RealtimeAPI | null;
+    /**
+     * When true, `DynamicTable` / `DynamicKanban` refetch on data events
+     * unless a component passes `realtime={false}`. Default false (opt-in).
+     */
+    defaultRealtime: boolean;
+}
+export interface RealtimeProviderProps {
+    client: RealtimeAPI | null | undefined;
+    /** Turn realtime refetch on for every dynamic table/kanban below. Default false. */
+    defaultRealtime?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Mount once, inside the host's WebSocket provider and QueryClientProvider.
+ * `client` may be null while the host is still connecting — hooks become
+ * no-ops and re-subscribe when a client appears.
+ */
+export declare function RealtimeProvider({ client, defaultRealtime, children }: RealtimeProviderProps): import("react").JSX.Element;
+/** The host realtime client from context (null when none is mounted). */
+export declare function useRealtimeClient(explicit?: RealtimeAPI | null): RealtimeAPI | null;
+/** Whether dynamic components should refetch on data events by default. */
+export declare function useRealtimeDefault(): boolean;
+export interface UseRealtimeOptions extends RealtimeSubscribeOptions {
+    /** Pass `host.realtime` / `api.realtime` to bypass the context. */
+    client?: RealtimeAPI | null;
+    /** Set false to pause the subscription without unmounting. Default true. */
+    enabled?: boolean;
+}
+/**
+ * Subscribe to data events for the given models. The handler is kept in a
+ * ref so callers don't need to memoise it; the subscription is torn down on
+ * unmount and re-created when models/events/client change.
+ *
+ *   useRealtime({ models: ['SalesOrder'], client: host.realtime }, (e) => {
+ *     if (e.action === 'resync' || e.id === currentId) refetch()
+ *   })
+ */
+export declare function useRealtime(options: UseRealtimeOptions, handler: DataEventHandler): void;
+/** Live status of the realtime client ('closed' when none). */
+export declare function useRealtimeStatus(explicit?: RealtimeAPI | null): RealtimeStatus;
+/** Default matcher: any string segment of the query key (case-insensitive)
+ *  equals the event's model, table or `addon.model`, or contains the model
+ *  as a path segment (`/data/sales_orders`). */
+export declare function queryKeyMatchesEvent(queryKey: QueryKey, event: DataEvent): boolean;
+export interface UseRealtimeInvalidateOptions extends UseRealtimeOptions {
+    /** Override which queries a given event invalidates. Default: `queryKeyMatchesEvent`. */
+    match?: (queryKey: QueryKey, event: DataEvent) => boolean;
+    /** Coalesce bursts before invalidating (ms). Default 250. */
+    debounceMs?: number;
+    /** Observe each event after it was scheduled for invalidation. */
+    onEvent?: DataEventHandler;
+}
+/**
+ * Invalidate every react-query query whose key mentions the event's model /
+ * table (see `queryKeyMatchesEvent`). Uses the host's QueryClient. Bursts
+ * are debounced so a coalesced frame storm becomes a single refetch round.
+ *
+ *   useRealtimeInvalidate({ models: ['SalesOrder', 'sales_order_items'], client: host.realtime })
+ */
+export declare function useRealtimeInvalidate(options: UseRealtimeInvalidateOptions): void;
+export interface UseRealtimeTickOptions {
+    /** Models/tables to watch. */
+    models: string[];
+    /** Explicit client (federated addons). */
+    client?: RealtimeAPI | null;
+    /** Master switch — the caller resolves prop vs provider default. */
+    enabled: boolean;
+    /** Coalesce bursts before ticking (ms). Default 300. */
+    debounceMs?: number;
+}
+/**
+ * A counter that increments (debounced) whenever a data event lands for one
+ * of `models`. Fold it into a refetch effect's dependencies — that is exactly
+ * what `DynamicTable` / `DynamicKanban` do behind their `realtime` prop.
+ */
+export declare function useRealtimeTick(options: UseRealtimeTickOptions): number;
+//# sourceMappingURL=realtime-context.d.ts.map

package/dist/realtime-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-context.d.ts","sourceRoot":"","sources":["../src/realtime-context.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAErD,OAAO,KAAK,EACR,SAAS,EAET,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,wBAAwB,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,MAAM,WAAW,oBAAoB;IACjC,mEAAmE;IACnE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IAC1B;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAA;CAC3B;AAID,MAAM,WAAW,qBAAqB;IAClC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAA;IACtC,oFAAoF;IACpF,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,MAAM,EAAE,eAAuB,EAAE,QAAQ,EAAE,EAAE,qBAAqB,+BAMpG;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAGnF;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,MAAM,WAAW,kBAAmB,SAAQ,wBAAwB;IAChE,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAoBxF;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,cAAc,CAa/E;AAED;;gDAEgD;AAChD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAelF;AAgBD,MAAM,WAAW,4BAA6B,SAAQ,kBAAkB;IACpE,yFAAyF;IACzF,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,KAAK,OAAO,CAAA;IACzD,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,IAAI,CAiCjF;AAED,MAAM,WAAW,sBAAsB;IACnC,8BAA8B;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;IAC3B,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAuBvE"}

package/dist/realtime-context.js

@@ -0,0 +1,182 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// realtime-context — React surface over the host's RealtimeAPI
+// (`@asteby/metacore-sdk`): a provider the host mounts once, `useRealtime`
+// for handlers, `useRealtimeInvalidate` to refresh react-query caches, and
+// `useRealtimeTick` — the opt-in refetch signal `DynamicTable` /
+// `DynamicKanban` consume through their `realtime` prop.
+//
+// Module-federation note: a federated addon may run its OWN copy of this
+// module, in which case React context from the host is invisible to it. Every
+// hook therefore accepts an explicit `client` (pass `host.realtime` or
+// `api.realtime`) that wins over the context — the plain object crosses the
+// federation boundary, the context does not.
+//
+// react-query: `useRealtimeInvalidate` uses `useQueryClient()` so it always
+// targets the QueryClient the host mounted (single instance per page).
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+const RealtimeContext = createContext({ client: null, defaultRealtime: false });
+/**
+ * Mount once, inside the host's WebSocket provider and QueryClientProvider.
+ * `client` may be null while the host is still connecting — hooks become
+ * no-ops and re-subscribe when a client appears.
+ */
+export function RealtimeProvider({ client, defaultRealtime = false, children }) {
+    const value = useMemo(() => ({ client: client ?? null, defaultRealtime }), [client, defaultRealtime]);
+    return _jsx(RealtimeContext.Provider, { value: value, children: children });
+}
+/** The host realtime client from context (null when none is mounted). */
+export function useRealtimeClient(explicit) {
+    const ctx = useContext(RealtimeContext);
+    return explicit ?? ctx.client;
+}
+/** Whether dynamic components should refetch on data events by default. */
+export function useRealtimeDefault() {
+    return useContext(RealtimeContext).defaultRealtime;
+}
+/**
+ * Subscribe to data events for the given models. The handler is kept in a
+ * ref so callers don't need to memoise it; the subscription is torn down on
+ * unmount and re-created when models/events/client change.
+ *
+ *   useRealtime({ models: ['SalesOrder'], client: host.realtime }, (e) => {
+ *     if (e.action === 'resync' || e.id === currentId) refetch()
+ *   })
+ */
+export function useRealtime(options, handler) {
+    const client = useRealtimeClient(options.client);
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const enabled = options.enabled ?? true;
+    const modelsKey = (options.models ?? []).map((m) => m.trim().toLowerCase()).sort().join('|');
+    const eventsKey = (options.events ?? []).slice().sort().join('|');
+    useEffect(() => {
+        if (!client || !enabled || !modelsKey)
+            return;
+        const models = modelsKey.split('|');
+        const events = eventsKey ? eventsKey.split('|') : undefined;
+        let off = () => { };
+        try {
+            off = client.subscribe({ models, events }, (event) => handlerRef.current(event));
+        }
+        catch {
+            /* a host client must not throw, but never take the page down */
+        }
+        return off;
+    }, [client, enabled, modelsKey, eventsKey]);
+}
+/** Live status of the realtime client ('closed' when none). */
+export function useRealtimeStatus(explicit) {
+    const client = useRealtimeClient(explicit);
+    const [status, setStatus] = useState(() => client?.status() ?? 'closed');
+    useEffect(() => {
+        if (!client) {
+            setStatus('closed');
+            return;
+        }
+        setStatus(client.status());
+        if (!client.onStatus)
+            return;
+        return client.onStatus(setStatus);
+    }, [client]);
+    return status;
+}
+/** Default matcher: any string segment of the query key (case-insensitive)
+ *  equals the event's model, table or `addon.model`, or contains the model
+ *  as a path segment (`/data/sales_orders`). */
+export function queryKeyMatchesEvent(queryKey, event) {
+    const needles = [event.model, event.table ?? '', `${event.addon}.${event.model}`]
+        .map((s) => s.toLowerCase())
+        .filter(Boolean);
+    const parts = flattenKey(queryKey);
+    for (const part of parts) {
+        const p = part.toLowerCase();
+        for (const n of needles) {
+            if (p === n)
+                return true;
+            // '/data/sales_orders?x=1' or 'pos/SalesOrder' style segments.
+            const segs = p.split(/[/?&=]/);
+            if (segs.includes(n))
+                return true;
+        }
+    }
+    return false;
+}
+function flattenKey(key, out = [], depth = 0) {
+    if (depth > 4)
+        return out;
+    for (const item of key) {
+        if (typeof item === 'string')
+            out.push(item);
+        else if (Array.isArray(item))
+            flattenKey(item, out, depth + 1);
+        else if (item && typeof item === 'object') {
+            for (const v of Object.values(item)) {
+                if (typeof v === 'string')
+                    out.push(v);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Invalidate every react-query query whose key mentions the event's model /
+ * table (see `queryKeyMatchesEvent`). Uses the host's QueryClient. Bursts
+ * are debounced so a coalesced frame storm becomes a single refetch round.
+ *
+ *   useRealtimeInvalidate({ models: ['SalesOrder', 'sales_order_items'], client: host.realtime })
+ */
+export function useRealtimeInvalidate(options) {
+    const queryClient = useQueryClient();
+    const { match = queryKeyMatchesEvent, debounceMs = 250, onEvent } = options;
+    const pendingRef = useRef([]);
+    const timerRef = useRef(null);
+    const matchRef = useRef(match);
+    matchRef.current = match;
+    const onEventRef = useRef(onEvent);
+    onEventRef.current = onEvent;
+    const flush = useCallback(() => {
+        timerRef.current = null;
+        const batch = pendingRef.current;
+        pendingRef.current = [];
+        if (batch.length === 0)
+            return;
+        void queryClient.invalidateQueries({
+            predicate: (query) => batch.some((event) => matchRef.current(query.queryKey, event)),
+        });
+    }, [queryClient]);
+    useRealtime(options, (event) => {
+        pendingRef.current.push(event);
+        onEventRef.current?.(event);
+        if (timerRef.current)
+            return;
+        timerRef.current = setTimeout(flush, debounceMs);
+    });
+    useEffect(() => () => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+    }, []);
+}
+/**
+ * A counter that increments (debounced) whenever a data event lands for one
+ * of `models`. Fold it into a refetch effect's dependencies — that is exactly
+ * what `DynamicTable` / `DynamicKanban` do behind their `realtime` prop.
+ */
+export function useRealtimeTick(options) {
+    const [tick, setTick] = useState(0);
+    const timerRef = useRef(null);
+    const debounceMs = options.debounceMs ?? 300;
+    useRealtime({ models: options.models, client: options.client, enabled: options.enabled }, () => {
+        if (timerRef.current)
+            return;
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            setTick((t) => t + 1);
+        }, debounceMs);
+    });
+    useEffect(() => () => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+    }, []);
+    return tick;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "36.1.0",
+  "version": "37.0.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -37,7 +37,7 @@
     "react-i18next": ">=13",
     "sonner": ">=1.7",
     "zustand": ">=5",
-    "@asteby/metacore-sdk": "^3.6.0",
+    "@asteby/metacore-sdk": "^3.7.0",
     "@asteby/metacore-ui": "^2.17.3"
   },
   "peerDependenciesMeta": {
@@ -67,7 +67,7 @@
     "typescript": "^6.0.0",
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
-    "@asteby/metacore-sdk": "3.6.0",
+    "@asteby/metacore-sdk": "3.7.0",
     "@asteby/metacore-ui": "2.17.3"
   },
   "scripts": {

package/src/__tests__/realtime-context.test.tsx

@@ -0,0 +1,195 @@
+// @vitest-environment happy-dom
+//
+// Realtime hooks over a fake RealtimeAPI: useRealtime subscribes/unsubscribes
+// with normalised models, an explicit client beats the context (federation
+// boundary), useRealtimeInvalidate targets the host QueryClient by key match,
+// and useRealtimeTick debounces bursts into one bump.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, renderHook } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import type { DataEvent, DataEventHandler, RealtimeAPI, RealtimeSubscribeOptions } from '@asteby/metacore-sdk'
+import {
+    RealtimeProvider,
+    queryKeyMatchesEvent,
+    useRealtime,
+    useRealtimeInvalidate,
+    useRealtimeStatus,
+    useRealtimeTick,
+} from '../realtime-context'
+
+afterEach(cleanup)
+
+function fakeClient() {
+    const subs: Array<{ opts: RealtimeSubscribeOptions; handler: DataEventHandler }> = []
+    const statusListeners = new Set<(s: 'connecting' | 'open' | 'closed') => void>()
+    let status: 'connecting' | 'open' | 'closed' = 'open'
+    const client: RealtimeAPI & { subs: typeof subs; emit: (e: DataEvent) => void; setStatus: (s: typeof status) => void } = {
+        subs,
+        subscribe(opts, handler) {
+            const entry = { opts, handler }
+            subs.push(entry)
+            return () => {
+                const i = subs.indexOf(entry)
+                if (i >= 0) subs.splice(i, 1)
+            }
+        },
+        status: () => status,
+        onStatus(l) {
+            statusListeners.add(l)
+            return () => statusListeners.delete(l)
+        },
+        emit(e) {
+            subs.forEach((s) => s.handler(e))
+        },
+        setStatus(s) {
+            status = s
+            statusListeners.forEach((l) => l(s))
+        },
+    }
+    return client
+}
+
+const event = (over: Partial<DataEvent> = {}): DataEvent => ({
+    org_id: 'org',
+    addon: 'pos',
+    model: 'SalesOrder',
+    table: 'sales_orders',
+    action: 'updated',
+    id: '1',
+    at: '2026-08-31T00:00:00Z',
+    ...over,
+})
+
+describe('useRealtime', () => {
+    it('subscribes through the context client with normalised models and tears down on unmount', () => {
+        const client = fakeClient()
+        const handler = vi.fn()
+        const wrapper = ({ children }: { children: ReactNode }) => (
+            <RealtimeProvider client={client}>{children}</RealtimeProvider>
+        )
+        const { unmount } = renderHook(() => useRealtime({ models: [' SalesOrder ', 'WorkOrder'] }, handler), { wrapper })
+        expect(client.subs).toHaveLength(1)
+        expect(client.subs[0]!.opts.models).toEqual(['salesorder', 'workorder'])
+        client.emit(event())
+        expect(handler).toHaveBeenCalledTimes(1)
+        unmount()
+        expect(client.subs).toHaveLength(0)
+    })
+
+    it('prefers an explicit client over the context (federated addons)', () => {
+        const ctxClient = fakeClient()
+        const explicit = fakeClient()
+        const wrapper = ({ children }: { children: ReactNode }) => (
+            <RealtimeProvider client={ctxClient}>{children}</RealtimeProvider>
+        )
+        renderHook(() => useRealtime({ models: ['SalesOrder'], client: explicit }, () => {}), { wrapper })
+        expect(explicit.subs).toHaveLength(1)
+        expect(ctxClient.subs).toHaveLength(0)
+    })
+
+    it('is a no-op without a client, without models, or when disabled', () => {
+        const client = fakeClient()
+        renderHook(() => useRealtime({ models: ['SalesOrder'] }, () => {}))
+        renderHook(() => useRealtime({ models: [], client }, () => {}))
+        renderHook(() => useRealtime({ models: ['SalesOrder'], client, enabled: false }, () => {}))
+        expect(client.subs).toHaveLength(0)
+    })
+})
+
+describe('useRealtimeStatus', () => {
+    it('tracks the client status', () => {
+        const client = fakeClient()
+        const { result } = renderHook(() => useRealtimeStatus(client))
+        expect(result.current).toBe('open')
+        act(() => client.setStatus('connecting'))
+        expect(result.current).toBe('connecting')
+        const { result: none } = renderHook(() => useRealtimeStatus(null))
+        expect(none.current).toBe('closed')
+    })
+})
+
+describe('queryKeyMatchesEvent', () => {
+    it('matches model, table, qualified name and path segments (case-insensitive)', () => {
+        const e = event()
+        expect(queryKeyMatchesEvent(['salesorder', 'list'], e)).toBe(true)
+        expect(queryKeyMatchesEvent(['data', 'sales_orders', { page: 1 }], e)).toBe(true)
+        expect(queryKeyMatchesEvent(['pos.SalesOrder'], e)).toBe(true)
+        expect(queryKeyMatchesEvent(['/data/sales_orders?page=1'], e)).toBe(true)
+        expect(queryKeyMatchesEvent([{ model: 'SalesOrder' }], e)).toBe(true)
+        expect(queryKeyMatchesEvent(['work_orders'], e)).toBe(false)
+        expect(queryKeyMatchesEvent(['sales_orders_archive'], e)).toBe(false)
+    })
+})
+
+describe('useRealtimeInvalidate', () => {
+    it('invalidates only the queries whose key mentions the event model, debounced', async () => {
+        vi.useFakeTimers()
+        try {
+            const client = fakeClient()
+            const queryClient = new QueryClient()
+            queryClient.setQueryData(['sales_orders', 'list'], [])
+            queryClient.setQueryData(['work_orders', 'list'], [])
+            const invalidate = vi.spyOn(queryClient, 'invalidateQueries')
+            const wrapper = ({ children }: { children: ReactNode }) => (
+                <QueryClientProvider client={queryClient}>
+                    <RealtimeProvider client={client}>{children}</RealtimeProvider>
+                </QueryClientProvider>
+            )
+            const onEvent = vi.fn()
+            renderHook(() => useRealtimeInvalidate({ models: ['SalesOrder'], debounceMs: 100, onEvent }), { wrapper })
+
+            act(() => {
+                client.emit(event({ id: '1' }))
+                client.emit(event({ id: '2' }))
+            })
+            expect(onEvent).toHaveBeenCalledTimes(2)
+            expect(invalidate).not.toHaveBeenCalled()
+            act(() => {
+                vi.advanceTimersByTime(120)
+            })
+            expect(invalidate).toHaveBeenCalledTimes(1)
+            const predicate = (invalidate.mock.calls[0]![0] as { predicate: (q: { queryKey: unknown[] }) => boolean }).predicate
+            expect(predicate({ queryKey: ['sales_orders', 'list'] })).toBe(true)
+            expect(predicate({ queryKey: ['work_orders', 'list'] })).toBe(false)
+            expect(queryClient.getQueryState(['sales_orders', 'list'])?.isInvalidated).toBe(true)
+            expect(queryClient.getQueryState(['work_orders', 'list'])?.isInvalidated).toBe(false)
+        } finally {
+            vi.useRealTimers()
+        }
+    })
+})
+
+describe('useRealtimeTick', () => {
+    it('bumps once per burst and stays quiet when disabled', () => {
+        vi.useFakeTimers()
+        try {
+            const client = fakeClient()
+            const { result, rerender } = renderHook(
+                ({ enabled }: { enabled: boolean }) =>
+                    useRealtimeTick({ models: ['SalesOrder'], client, enabled, debounceMs: 50 }),
+                { initialProps: { enabled: true } },
+            )
+            expect(result.current).toBe(0)
+            act(() => {
+                client.emit(event())
+                client.emit(event({ id: '2' }))
+                client.emit(event({ id: '3' }))
+            })
+            expect(result.current).toBe(0)
+            act(() => {
+                vi.advanceTimersByTime(60)
+            })
+            expect(result.current).toBe(1)
+
+            rerender({ enabled: false })
+            expect(client.subs).toHaveLength(0)
+            act(() => {
+                vi.advanceTimersByTime(100)
+            })
+            expect(result.current).toBe(1)
+        } finally {
+            vi.useRealTimers()
+        }
+    })
+})

package/src/dynamic-kanban.tsx

@@ -90,6 +90,7 @@ import {
 import { ColumnFilterControl, FilterValueCombobox, type ColumnFilterType } from '@asteby/metacore-ui/data-table'
 import { generateBadgeStyles, optionColor } from '@asteby/metacore-ui/lib'
 import { useApi } from './api-context'
+import { useRealtimeDefault, useRealtimeTick } from './realtime-context'
 import {
     useStageAutomations,
     StageAutomationsButton,
@@ -462,6 +463,12 @@ export interface DynamicKanbanProps {
     endpoint?: string
     /** Bump to force a metadata + records refetch (same contract as DynamicTable). */
     refreshTrigger?: any
+    /**
+     * Refetch the board when the host's realtime client reports a data event
+     * for this model (same contract as DynamicTable's `realtime`). Off by
+     * default; `<RealtimeProvider defaultRealtime>` flips the default.
+     */
+    realtime?: boolean
     /** Called when a card is clicked (outside its action menu). */
     onCardClick?: (row: any) => void
     /**
@@ -497,6 +504,7 @@ export function DynamicKanban({
     model,
     endpoint,
     refreshTrigger,
+    realtime: realtimeProp,
     onCardClick,
     onAction,
     pageSize = 50,
@@ -508,6 +516,13 @@ export function DynamicKanban({
     const { t, i18n } = useTranslation()
     const api = useApi()
     const isDark = useIsDarkTheme()
+    // Realtime refetch (opt-in) — debounced counter bumped by DATA_EVENTs for
+    // this model; folded into the board refetch effect next to refreshTrigger.
+    const realtimeDefault = useRealtimeDefault()
+    const realtimeTick = useRealtimeTick({
+        models: [model],
+        enabled: realtimeProp ?? realtimeDefault,
+    })
 
     // Stage automations (Bitrix-style per-lane rules). Degrades to no-op when
     // the host has no `/stage-automations` endpoint — the ⚡ affordance hides.
@@ -782,7 +797,9 @@ export function DynamicKanban({
             void fetchData()
         }, 200)
         return () => clearTimeout(handle)
-    }, [fetchData, metadata, refreshTrigger])
+        // realtimeTick: data events for this model (see the `realtime` prop).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fetchData, metadata, refreshTrigger, realtimeTick])
 
     // Filterable fields for the toolbar, in metadata order (explicit filters
     // first, then filterable columns), each labeled from its metadata source.

package/src/dynamic-table.tsx

@@ -64,6 +64,7 @@ import { toast } from 'sonner'
 import { Progress } from './dialogs/_primitives'
 import { useMetadataCache } from './metadata-cache'
 import { useApi, useCurrentBranch } from './api-context'
+import { useRealtimeDefault, useRealtimeTick } from './realtime-context'
 import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-shim'
 import { defaultGetDynamicColumns, DATE_CELL_TYPES, aggregateOf, formatAggregateTotal } from './dynamic-columns'
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders'
@@ -176,6 +177,17 @@ export interface DynamicTableProps {
     /** Hide the export action on this view. See `hideImport`. */
     hideExport?: boolean
     hiddenColumns?: string[]
+    /**
+     * Row-action ALLOWLIST for this table instance, by action key (manifest
+     * v3 NavItem.actions, carried through the host's nav item for this route).
+     * When set, only these row actions render — even though the model may
+     * declare more. Lets two views of the SAME model differ: a generic list
+     * keeps every action, while a purpose-built screen (e.g. a credit-approval
+     * queue) shows only authorize_credit/reject_credit instead of every action
+     * SalesOrder declares (Generar factura, Cancelar, etc. included).
+     * Undefined → every row action the model declares (unchanged default).
+     */
+    allowedActionKeys?: string[]
     onAction?: (action: string, row: any) => void
     /**
      * Called when the user clicks anywhere on a data row (not on a checkbox,
@@ -185,6 +197,13 @@ export interface DynamicTableProps {
      */
     onRowClick?: (row: any) => void
     refreshTrigger?: any
+    /**
+     * Refetch when the host's realtime client reports a data event for this
+     * model (created/updated/deleted by anyone in the org, or a `resync`).
+     * Off by default; `<RealtimeProvider defaultRealtime>` turns it on for
+     * every table, and an explicit prop always wins. No-op without a client.
+     */
+    realtime?: boolean
     defaultFilters?: Record<string, any>
     extraColumns?: ColumnDef<any>[]
     /**
@@ -238,9 +257,11 @@ export function DynamicTable({
     hideImport,
     hideExport,
     hiddenColumns = [],
+    allowedActionKeys,
     onAction,
     onRowClick,
     refreshTrigger,
+    realtime: realtimeProp,
     defaultFilters,
     extraColumns = [],
     getDynamicColumns = defaultGetDynamicColumns,
@@ -255,6 +276,13 @@ export function DynamicTable({
     const { t, i18n } = useTranslation()
     const api = useApi()
     const currentBranch = useCurrentBranch()
+    // Realtime refetch (opt-in): a debounced counter that bumps on every
+    // DATA_EVENT for this model and rides the same deps as `refreshTrigger`.
+    const realtimeDefault = useRealtimeDefault()
+    const realtimeTick = useRealtimeTick({
+        models: [model],
+        enabled: realtimeProp ?? realtimeDefault,
+    })
 
     const prevBranchId = useRef(currentBranch?.id)
 
@@ -742,7 +770,8 @@ export function DynamicTable({
         } finally {
             setLoadingData(false)
         }
-    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, endpoint, currentBranch?.id, api, enableUrlSync])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, realtimeTick, endpoint, currentBranch?.id, api, enableUrlSync])
 
     // Columns whose metadata opts into a footer total (display_config.aggregate
     // → styleConfig.aggregate). When empty, no footer row is rendered and no
@@ -911,8 +940,9 @@ export function DynamicTable({
         // matching the classic path (fetchData carries refreshTrigger in its
         // deps). Without it the comment above lied: infinite lists silently
         // failed to reload after a create ("a veces no recarga la tabla").
+        // realtimeTick plays the same role for data events (see the `realtime` prop).
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [infiniteScroll, metadata, filterSignature, refreshTrigger])
+    }, [infiniteScroll, metadata, filterSignature, refreshTrigger, realtimeTick])
 
     const handleRefresh = useCallback(() => {
         // Infinite mode owns its own list: refresh reloads page 1 and drops the
@@ -1124,15 +1154,27 @@ export function DynamicTable({
         // Row-action column only renders per-row actions. Table-level placements
         // ("table"/"create") are surfaced by <ModelActionToolbar> at the page
         // level, so strip them here to avoid a meaningless per-row button.
-        const rowMetadata = viewMetadata.actions?.some((a) => a.placement === 'table' || a.placement === 'create')
-            ? { ...viewMetadata, actions: viewMetadata.actions.filter((a) => !a.placement || a.placement === 'row') }
-            : viewMetadata
+        // `allowedActionKeys`, when given, further narrows the row set to a
+        // per-VIEW allowlist — two nav entries on the same model (a generic
+        // list vs. a purpose-built approval queue) can then show different
+        // actions instead of every action the model declares.
+        const rowMetadata = (() => {
+            let actions = viewMetadata.actions
+            if (actions?.some((a) => a.placement === 'table' || a.placement === 'create')) {
+                actions = actions.filter((a) => !a.placement || a.placement === 'row')
+            }
+            if (allowedActionKeys && actions) {
+                const allowed = new Set(allowedActionKeys)
+                actions = actions.filter((a) => allowed.has(a.key))
+            }
+            return actions === viewMetadata.actions ? viewMetadata : { ...viewMetadata, actions }
+        })()
         const baseColumns = getDynamicColumns(rowMetadata, handleInternalAction, t, i18n.language, columnFilterConfigs, timeZone, currency)
         const filteredBase = baseColumns.filter((col: ColumnDef<any>) => !hiddenColumns.includes(col.id as string))
         const actionsCol = filteredBase.find((c: ColumnDef<any>) => c.id === 'actions')
         const otherCols = filteredBase.filter((c: ColumnDef<any>) => c.id !== 'actions')
         return [...otherCols, ...extraColumns, ...(actionsCol ? [actionsCol] : [])]
-    }, [viewMetadata, handleInternalAction, hiddenColumns, extraColumns, t, i18n.language, columnFilterConfigs, getDynamicColumns, timeZone, currency])
+    }, [viewMetadata, handleInternalAction, hiddenColumns, allowedActionKeys, extraColumns, t, i18n.language, columnFilterConfigs, getDynamicColumns, timeZone, currency])
 
     const filters = useMemo(() => [], [])
 

package/src/index.ts

@@ -213,6 +213,21 @@ export * from './print-document-button'
 export * from './use-org-document-templates'
 export * from './document-template-editor'
 export * from './metadata-cache'
+export {
+    RealtimeProvider,
+    useRealtimeClient,
+    useRealtimeDefault,
+    useRealtime,
+    useRealtimeStatus,
+    useRealtimeInvalidate,
+    useRealtimeTick,
+    queryKeyMatchesEvent,
+    type RealtimeContextValue,
+    type RealtimeProviderProps,
+    type UseRealtimeOptions,
+    type UseRealtimeInvalidateOptions,
+    type UseRealtimeTickOptions,
+} from './realtime-context'
 export {
     ADDON_MANIFEST_CHANGED_TYPE,
     wireHotSwapInvalidation,

package/src/realtime-context.tsx

@@ -0,0 +1,248 @@
+// realtime-context — React surface over the host's RealtimeAPI
+// (`@asteby/metacore-sdk`): a provider the host mounts once, `useRealtime`
+// for handlers, `useRealtimeInvalidate` to refresh react-query caches, and
+// `useRealtimeTick` — the opt-in refetch signal `DynamicTable` /
+// `DynamicKanban` consume through their `realtime` prop.
+//
+// Module-federation note: a federated addon may run its OWN copy of this
+// module, in which case React context from the host is invisible to it. Every
+// hook therefore accepts an explicit `client` (pass `host.realtime` or
+// `api.realtime`) that wins over the context — the plain object crosses the
+// federation boundary, the context does not.
+//
+// react-query: `useRealtimeInvalidate` uses `useQueryClient()` so it always
+// targets the QueryClient the host mounted (single instance per page).
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+import type { QueryKey } from '@tanstack/react-query'
+import { useQueryClient } from '@tanstack/react-query'
+import type {
+    DataEvent,
+    DataEventAction,
+    DataEventHandler,
+    RealtimeAPI,
+    RealtimeStatus,
+    RealtimeSubscribeOptions,
+} from '@asteby/metacore-sdk'
+
+export interface RealtimeContextValue {
+    /** Host-provided client, or null when the host has no realtime. */
+    client: RealtimeAPI | null
+    /**
+     * When true, `DynamicTable` / `DynamicKanban` refetch on data events
+     * unless a component passes `realtime={false}`. Default false (opt-in).
+     */
+    defaultRealtime: boolean
+}
+
+const RealtimeContext = createContext<RealtimeContextValue>({ client: null, defaultRealtime: false })
+
+export interface RealtimeProviderProps {
+    client: RealtimeAPI | null | undefined
+    /** Turn realtime refetch on for every dynamic table/kanban below. Default false. */
+    defaultRealtime?: boolean
+    children: React.ReactNode
+}
+
+/**
+ * Mount once, inside the host's WebSocket provider and QueryClientProvider.
+ * `client` may be null while the host is still connecting — hooks become
+ * no-ops and re-subscribe when a client appears.
+ */
+export function RealtimeProvider({ client, defaultRealtime = false, children }: RealtimeProviderProps) {
+    const value = useMemo<RealtimeContextValue>(
+        () => ({ client: client ?? null, defaultRealtime }),
+        [client, defaultRealtime],
+    )
+    return <RealtimeContext.Provider value={value}>{children}</RealtimeContext.Provider>
+}
+
+/** The host realtime client from context (null when none is mounted). */
+export function useRealtimeClient(explicit?: RealtimeAPI | null): RealtimeAPI | null {
+    const ctx = useContext(RealtimeContext)
+    return explicit ?? ctx.client
+}
+
+/** Whether dynamic components should refetch on data events by default. */
+export function useRealtimeDefault(): boolean {
+    return useContext(RealtimeContext).defaultRealtime
+}
+
+export interface UseRealtimeOptions extends RealtimeSubscribeOptions {
+    /** Pass `host.realtime` / `api.realtime` to bypass the context. */
+    client?: RealtimeAPI | null
+    /** Set false to pause the subscription without unmounting. Default true. */
+    enabled?: boolean
+}
+
+/**
+ * Subscribe to data events for the given models. The handler is kept in a
+ * ref so callers don't need to memoise it; the subscription is torn down on
+ * unmount and re-created when models/events/client change.
+ *
+ *   useRealtime({ models: ['SalesOrder'], client: host.realtime }, (e) => {
+ *     if (e.action === 'resync' || e.id === currentId) refetch()
+ *   })
+ */
+export function useRealtime(options: UseRealtimeOptions, handler: DataEventHandler): void {
+    const client = useRealtimeClient(options.client)
+    const handlerRef = useRef(handler)
+    handlerRef.current = handler
+    const enabled = options.enabled ?? true
+    const modelsKey = (options.models ?? []).map((m) => m.trim().toLowerCase()).sort().join('|')
+    const eventsKey = (options.events ?? []).slice().sort().join('|')
+
+    useEffect(() => {
+        if (!client || !enabled || !modelsKey) return
+        const models = modelsKey.split('|')
+        const events = eventsKey ? (eventsKey.split('|') as DataEventAction[]) : undefined
+        let off: () => void = () => {}
+        try {
+            off = client.subscribe({ models, events }, (event) => handlerRef.current(event))
+        } catch {
+            /* a host client must not throw, but never take the page down */
+        }
+        return off
+    }, [client, enabled, modelsKey, eventsKey])
+}
+
+/** Live status of the realtime client ('closed' when none). */
+export function useRealtimeStatus(explicit?: RealtimeAPI | null): RealtimeStatus {
+    const client = useRealtimeClient(explicit)
+    const [status, setStatus] = useState<RealtimeStatus>(() => client?.status() ?? 'closed')
+    useEffect(() => {
+        if (!client) {
+            setStatus('closed')
+            return
+        }
+        setStatus(client.status())
+        if (!client.onStatus) return
+        return client.onStatus(setStatus)
+    }, [client])
+    return status
+}
+
+/** Default matcher: any string segment of the query key (case-insensitive)
+ *  equals the event's model, table or `addon.model`, or contains the model
+ *  as a path segment (`/data/sales_orders`). */
+export function queryKeyMatchesEvent(queryKey: QueryKey, event: DataEvent): boolean {
+    const needles = [event.model, event.table ?? '', `${event.addon}.${event.model}`]
+        .map((s) => s.toLowerCase())
+        .filter(Boolean)
+    const parts = flattenKey(queryKey)
+    for (const part of parts) {
+        const p = part.toLowerCase()
+        for (const n of needles) {
+            if (p === n) return true
+            // '/data/sales_orders?x=1' or 'pos/SalesOrder' style segments.
+            const segs = p.split(/[/?&=]/)
+            if (segs.includes(n)) return true
+        }
+    }
+    return false
+}
+
+function flattenKey(key: QueryKey, out: string[] = [], depth = 0): string[] {
+    if (depth > 4) return out
+    for (const item of key as unknown[]) {
+        if (typeof item === 'string') out.push(item)
+        else if (Array.isArray(item)) flattenKey(item as QueryKey, out, depth + 1)
+        else if (item && typeof item === 'object') {
+            for (const v of Object.values(item as Record<string, unknown>)) {
+                if (typeof v === 'string') out.push(v)
+            }
+        }
+    }
+    return out
+}
+
+export interface UseRealtimeInvalidateOptions extends UseRealtimeOptions {
+    /** Override which queries a given event invalidates. Default: `queryKeyMatchesEvent`. */
+    match?: (queryKey: QueryKey, event: DataEvent) => boolean
+    /** Coalesce bursts before invalidating (ms). Default 250. */
+    debounceMs?: number
+    /** Observe each event after it was scheduled for invalidation. */
+    onEvent?: DataEventHandler
+}
+
+/**
+ * Invalidate every react-query query whose key mentions the event's model /
+ * table (see `queryKeyMatchesEvent`). Uses the host's QueryClient. Bursts
+ * are debounced so a coalesced frame storm becomes a single refetch round.
+ *
+ *   useRealtimeInvalidate({ models: ['SalesOrder', 'sales_order_items'], client: host.realtime })
+ */
+export function useRealtimeInvalidate(options: UseRealtimeInvalidateOptions): void {
+    const queryClient = useQueryClient()
+    const { match = queryKeyMatchesEvent, debounceMs = 250, onEvent } = options
+    const pendingRef = useRef<DataEvent[]>([])
+    const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+    const matchRef = useRef(match)
+    matchRef.current = match
+    const onEventRef = useRef(onEvent)
+    onEventRef.current = onEvent
+
+    const flush = useCallback(() => {
+        timerRef.current = null
+        const batch = pendingRef.current
+        pendingRef.current = []
+        if (batch.length === 0) return
+        void queryClient.invalidateQueries({
+            predicate: (query) => batch.some((event) => matchRef.current(query.queryKey, event)),
+        })
+    }, [queryClient])
+
+    useRealtime(options, (event) => {
+        pendingRef.current.push(event)
+        onEventRef.current?.(event)
+        if (timerRef.current) return
+        timerRef.current = setTimeout(flush, debounceMs)
+    })
+
+    useEffect(
+        () => () => {
+            if (timerRef.current) clearTimeout(timerRef.current)
+        },
+        [],
+    )
+}
+
+export interface UseRealtimeTickOptions {
+    /** Models/tables to watch. */
+    models: string[]
+    /** Explicit client (federated addons). */
+    client?: RealtimeAPI | null
+    /** Master switch — the caller resolves prop vs provider default. */
+    enabled: boolean
+    /** Coalesce bursts before ticking (ms). Default 300. */
+    debounceMs?: number
+}
+
+/**
+ * A counter that increments (debounced) whenever a data event lands for one
+ * of `models`. Fold it into a refetch effect's dependencies — that is exactly
+ * what `DynamicTable` / `DynamicKanban` do behind their `realtime` prop.
+ */
+export function useRealtimeTick(options: UseRealtimeTickOptions): number {
+    const [tick, setTick] = useState(0)
+    const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+    const debounceMs = options.debounceMs ?? 300
+
+    useRealtime(
+        { models: options.models, client: options.client, enabled: options.enabled },
+        () => {
+            if (timerRef.current) return
+            timerRef.current = setTimeout(() => {
+                timerRef.current = null
+                setTick((t) => t + 1)
+            }, debounceMs)
+        },
+    )
+
+    useEffect(
+        () => () => {
+            if (timerRef.current) clearTimeout(timerRef.current)
+        },
+        [],
+    )
+    return tick
+}