@asteby/metacore-runtime-react 36.1.0 → 37.0.1

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,
@@ -250,7 +265,8 @@ export {
     resolveRelationLabel,
     type DynamicColumnsHelpers,
 } from './dynamic-columns'
-export { humanizeToken } from './dynamic-columns-helpers'
+export { humanizeToken, translateMetadataLabel } from './dynamic-columns-helpers'
+export type { MetadataTranslator } from './dynamic-columns-helpers'
 export {
     UrlChip,
     FileChip,

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