@asteby/metacore-runtime-react 41.0.0 → 43.0.0

package/src/dynamic-table.tsx

@@ -12,6 +12,7 @@
 //     column cells are tightly coupled to their design system).
 import { useEffect, useState, useMemo, useCallback, useRef, type MouseEvent } from 'react'
 import { useTranslation } from 'react-i18next'
+import { useTimeZone, useCurrency } from './org-runtime-context'
 import { format } from 'date-fns'
 import type { DateRange } from 'react-day-picker'
 import { useVirtualizer } from '@tanstack/react-virtual'
@@ -35,6 +36,7 @@ import {
     useReactTable,
 } from '@tanstack/react-table'
 import { cn } from '@asteby/metacore-ui/lib'
+import { preloadGlyphs } from '@asteby/metacore-ui/icons'
 import {
     Table,
     TableBody,
@@ -282,12 +284,18 @@ export function DynamicTable({
     defaultFilters,
     extraColumns = [],
     getDynamicColumns = defaultGetDynamicColumns,
-    timeZone,
-    currency,
+    timeZone: timeZoneProp,
+    currency: currencyProp,
     pagination: paginationMode,
     infiniteScroll: infiniteScrollProp = false,
     virtualizeRows,
 }: DynamicTableProps) {
+    // The org's timezone/currency: an explicit prop wins, else the app-wide
+    // OrgRuntimeProvider (without it, money fell back to USD).
+    const orgTimeZone = useTimeZone()
+    const orgCurrency = useCurrency()
+    const timeZone = timeZoneProp ?? orgTimeZone
+    const currency = currencyProp ?? orgCurrency
     // 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
@@ -754,6 +762,12 @@ export function DynamicTable({
         return gateTableMetadata(metadata, model, can, (key, fallback) => t(key, { defaultValue: fallback }))
     }, [metadata, permissionsActive, can, model, t])
 
+    // Row-action menus mount their icons on open: load them with the
+    // metadata so the first open draws every glyph at once.
+    useEffect(() => {
+        void preloadGlyphs((metadata?.actions ?? []).map((a) => a.icon))
+    }, [metadata])
+
     // Importing is offered when the host opts in explicitly (`canImport`) or,
     // when it says nothing, whenever the kernel served an import spec for the
     // model — which it does for every model with at least one importable form

package/src/index.ts

@@ -57,9 +57,15 @@ export {
     groupByStage,
     isTransitionAllowed,
     applyOptimisticMove,
+    applyStageOverrides,
+    laneDeltasFromOverrides,
     selectCardColumns,
+    visibleCardFields,
+    isEmptyCardValue,
+    nextLaneCoordinates,
     UNASSIGNED_LANE,
 } from './dynamic-kanban'
+export { PortalDragOverlay, type PortalDragOverlayProps } from './portal-drag-overlay'
 export {
     useStageAutomations,
     StageAutomationsButton,
@@ -135,6 +141,14 @@ export {
     type UseOptimisticMutationResult,
 } from './use-optimistic-mutation'
 export { useFlipAnimation, type UseFlipAnimationOptions } from './use-flip-animation'
+export {
+    usePersistedQuery,
+    createPersistedSnapshot,
+    type UsePersistedQueryOptions,
+    type PersistedSnapshot,
+    type PersistedSnapshotOptions,
+    type PersistedEntry,
+} from './use-persisted-query'
 export {
     motionDuration,
     motionEasing,

package/src/license/license-gate.tsx

@@ -19,6 +19,7 @@
  * INDEPENDIENTE del kernel: no importa su cliente ni fija su versión. Solo
  * consume `LicenseState` y una promesa `onActivate`.
  */
+import { createPortal } from 'react-dom'
 import { useState, type ReactNode } from 'react'
 import { useTranslation } from 'react-i18next'
 import { ShieldAlert, Clock, Loader2 } from 'lucide-react'
@@ -165,7 +166,9 @@ function LicenseGateModal({
         }
     }
 
-    return (
+    // In <body>: mounted inside a glass panel (backdrop-filter), a fixed veil
+    // would cover only that panel.
+    return createPortal(
         <div
             role="dialog"
             aria-modal="true"
@@ -300,6 +303,7 @@ function LicenseGateModal({
                     )}
                 </div>
             </div>
-        </div>
+        </div>,
+        document.body,
     )
 }

package/src/portal-drag-overlay.tsx

@@ -0,0 +1,20 @@
+// PortalDragOverlay — dnd-kit's <DragOverlay> rendered into <body>.
+//
+// The overlay is `position: fixed` at the viewport coordinates of the item
+// being dragged. Any ancestor with a transform, filter or backdrop-filter
+// becomes the containing block of a fixed descendant, so inside such an
+// ancestor (a glass panel from @asteby/metacore-theme/glass.css, an animated
+// dialog) the lifted item shows up shifted by that ancestor's offset instead of
+// under the pointer. Rendering it into <body> keeps the viewport as its
+// containing block wherever the board or list is mounted. React context (the
+// DndContext) still reaches it through the portal.
+import * as React from 'react'
+import { createPortal } from 'react-dom'
+import { DragOverlay } from '@dnd-kit/core'
+
+export type PortalDragOverlayProps = React.ComponentProps<typeof DragOverlay>
+
+export function PortalDragOverlay(props: PortalDragOverlayProps) {
+    if (typeof document === 'undefined') return null
+    return createPortal(<DragOverlay {...props} />, document.body)
+}

package/src/query-batch.ts

@@ -377,8 +377,11 @@ function batchForbidden(message?: string): boolean {
  * or options read. Anything the batch refuses falls back to the original GET.
  */
 export async function batchGet(api: ApiClient, url: string, config?: { params?: Record<string, unknown> }) {
+    // The fallback GET gets exactly the arguments the caller passed: no
+    // trailing `undefined` config reaching the host client.
+    const plainGet = () => (config === undefined ? api.get(url) : api.get(url, config))
     const token = tokenForGet(url, config?.params)
-    if (!token) return api.get(url, config)
+    if (!token) return plainGet()
     try {
         const part = await loadQueryPart(api, token)
         if (!part.success) {
@@ -391,13 +394,13 @@ export async function batchGet(api: ApiClient, url: string, config?: { params?:
                 err.response = { status: 403 }
                 throw err
             }
-            return api.get(url, config)
+            return plainGet()
         }
         return { data: { success: true, data: part.data, meta: part.meta } }
     } catch (err) {
         const status = (err as { status?: number; response?: { status?: number } })?.status
             ?? (err as { response?: { status?: number } })?.response?.status
         if (status === 403) throw err
-        return api.get(url, config)
+        return plainGet()
     }
 }

package/src/sidebar-layout-manager.tsx

@@ -5,7 +5,6 @@
 import * as React from 'react'
 import {
   DndContext,
-  DragOverlay,
   PointerSensor,
   closestCenter,
   useSensor,
@@ -20,6 +19,7 @@ import {
   verticalListSortingStrategy,
 } from '@dnd-kit/sortable'
 import { CSS } from '@dnd-kit/utilities'
+import { PortalDragOverlay } from './portal-drag-overlay'
 import {
   ChevronDown,
   ChevronRight,
@@ -733,13 +733,13 @@ export function SidebarLayoutManager({
                   ) : (
                     renderList(tree, [])
                   )}
-                  <DragOverlay>
+                  <PortalDragOverlay>
                     {activeLabel ? (
                       <div className="bg-background border-border rounded-md border px-3 py-1.5 text-sm shadow-lg">
                         {activeLabel}
                       </div>
                     ) : null}
-                  </DragOverlay>
+                  </PortalDragOverlay>
                 </DndContext>
 
                 <div className="mt-3 flex gap-2 px-2">

package/src/use-flip-animation.ts

@@ -23,6 +23,12 @@ export interface UseFlipAnimationOptions {
   easing?: MotionEasing | string
   /** Off switch; the hook also stays still under prefers-reduced-motion. */
   disabled?: boolean
+  /**
+   * Leave one element still on this change while still tracking where it is
+   * (e.g. the card a drag overlay is already carrying into place). Default:
+   * animate everything.
+   */
+  shouldAnimate?: (el: HTMLElement, key: string) => boolean
 }
 
 const DEFAULT_SELECTOR = '[data-flip-key]'
@@ -54,12 +60,13 @@ export function useFlipAnimation(
     duration = 'moderate',
     easing = 'standard',
     disabled = false,
+    shouldAnimate,
   } = options
   const positionsRef = useRef<Positions | null>(null)
   const triggerRef = useRef(trigger)
-  const configRef = useRef({ selector, keyOf, scrollContainer })
+  const configRef = useRef({ selector, keyOf, scrollContainer, shouldAnimate })
   useEffect(() => {
-    configRef.current = { selector, keyOf, scrollContainer }
+    configRef.current = { selector, keyOf, scrollContainer, shouldAnimate }
   })
 
   const measure = (): Positions | null => {
@@ -105,11 +112,16 @@ export function useFlipAnimation(
     schedule()
     document.addEventListener('pointerup', onInteraction, true)
     document.addEventListener('keyup', onInteraction, true)
+    // Scrolling a list inside the root moves its items without a trigger
+    // change; without a fresh snapshot the next change would replay the scroll
+    // distance as movement. (Scroll does not bubble: listen in capture.)
+    document.addEventListener('scroll', onInteraction, true)
     window.addEventListener('resize', schedule)
     return () => {
       if (timer) clearTimeout(timer)
       document.removeEventListener('pointerup', onInteraction, true)
       document.removeEventListener('keyup', onInteraction, true)
+      document.removeEventListener('scroll', onInteraction, true)
       window.removeEventListener('resize', schedule)
     }
   }, [rootRef])
@@ -127,7 +139,7 @@ export function useFlipAnimation(
     if (durationMs <= 0) return
     const timing = easing in MOTION_EASING_KEYS ? motionEasing(easing as MotionEasing) : easing
 
-    const { selector: sel, keyOf: key } = configRef.current
+    const { selector: sel, keyOf: key, shouldAnimate: animates } = configRef.current
     // A stale snapshot can report huge jumps; those would read as a glitch.
     const maxJump = root.clientHeight > 0 ? root.clientHeight * 1.5 : Infinity
     root.querySelectorAll<HTMLElement>(sel).forEach((el) => {
@@ -136,6 +148,7 @@ export function useFlipAnimation(
       const from = before.get(k)
       const to = after.get(k)
       if (!to || typeof el.animate !== 'function') return
+      if (animates && !animates(el, k)) return
       if (!from) {
         // Entered with this change: fade in instead of popping.
         el.animate([{ opacity: 0 }, { opacity: 1 }], { duration: durationMs, easing: timing })

package/src/use-persisted-query.ts

@@ -0,0 +1,152 @@
+import { useEffect, useMemo } from 'react'
+import {
+  useQuery,
+  useQueryClient,
+  type QueryKey,
+  type UseQueryOptions,
+  type UseQueryResult,
+} from '@tanstack/react-query'
+
+/**
+ * A versioned, scoped copy of a value in localStorage. Shell data that decides
+ * the first paint (navigation, the org's menu layout, installed presets,
+ * permissions) is read from here synchronously, so a reload paints the last
+ * known state instead of a default that reorders when the network answers.
+ *
+ * The entry lives under `<key>:v<version>:<scope>`. Bump `version` when the
+ * stored shape changes; old entries are simply never read again. `scope` keeps
+ * one org or user from seeing another's copy on a shared browser.
+ */
+export interface PersistedSnapshotOptions {
+  key: string
+  version: number
+  /** Entries older than this are ignored (default: 30 days). */
+  maxAgeMs?: number
+}
+
+export interface PersistedEntry<T> {
+  data: T
+  /** When the data was fetched (ms epoch). */
+  ts: number
+}
+
+export interface PersistedSnapshot<T> {
+  read(scope: string): PersistedEntry<T> | undefined
+  write(scope: string, data: T, meta?: { ts?: number }): void
+  clear(scope: string): void
+}
+
+const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000
+
+function storage(): Storage | null {
+  try {
+    return typeof localStorage === 'undefined' ? null : localStorage
+  } catch {
+    return null
+  }
+}
+
+export function createPersistedSnapshot<T>({
+  key,
+  version,
+  maxAgeMs = DEFAULT_MAX_AGE_MS,
+}: PersistedSnapshotOptions): PersistedSnapshot<T> {
+  const slot = (scope: string) => `${key}:v${version}:${scope}`
+  return {
+    read(scope) {
+      const s = storage()
+      if (!s) return undefined
+      try {
+        const raw = s.getItem(slot(scope))
+        if (!raw) return undefined
+        const parsed = JSON.parse(raw) as Partial<PersistedEntry<T>>
+        if (typeof parsed?.ts !== 'number' || !('data' in parsed)) return undefined
+        if (Date.now() - parsed.ts > maxAgeMs) return undefined
+        return { data: parsed.data as T, ts: parsed.ts }
+      } catch {
+        return undefined
+      }
+    },
+    write(scope, data, { ts = Date.now() } = {}) {
+      try {
+        storage()?.setItem(slot(scope), JSON.stringify({ data, ts }))
+      } catch {
+        // quota / private mode: the snapshot is an optimization, never fatal
+      }
+    },
+    clear(scope) {
+      try {
+        storage()?.removeItem(slot(scope))
+      } catch {
+        /* ignore */
+      }
+    },
+  }
+}
+
+export type UsePersistedQueryOptions<TQueryFnData, TData, TQueryKey extends QueryKey> = UseQueryOptions<
+  TQueryFnData,
+  Error,
+  TData,
+  TQueryKey
+> & {
+  persist: {
+    snapshot: PersistedSnapshot<TQueryFnData>
+    /**
+     * Org/user the data belongs to. Without a scope nothing is read or
+     * written (e.g. before sign-in).
+     */
+    scope: string | null | undefined
+  }
+}
+
+/**
+ * `useQuery` seeded from a {@link PersistedSnapshot}: the first render already
+ * has the last fetched value (stale-while-revalidate), and every later value —
+ * a refetch, or a `setQueryData` from a mutation — is written back. The seed is
+ * stale from the start: every page load revalidates it once in the background,
+ * so a change made elsewhere (a plantilla applied, an addon installed,
+ * permissions edited) shows on the next load even inside `staleTime`.
+ *
+ * Persist the raw server payload and derive UI shapes with `select`; the
+ * snapshot must be JSON.
+ */
+export function usePersistedQuery<
+  TQueryFnData,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: UsePersistedQueryOptions<TQueryFnData, TData, TQueryKey>,
+): UseQueryResult<TData, Error> {
+  const { persist, ...queryOptions } = options
+  const { snapshot, scope } = persist
+  const seed = useMemo(
+    () => (scope ? snapshot.read(scope) : undefined),
+    [snapshot, scope],
+  )
+  const query = useQuery<TQueryFnData, Error, TData, TQueryKey>({
+    ...queryOptions,
+    ...(seed && queryOptions.initialData === undefined
+      ? { initialData: seed.data, initialDataUpdatedAt: 0 }
+      : {}),
+  } as UseQueryOptions<TQueryFnData, Error, TData, TQueryKey>)
+
+  const queryClient = useQueryClient()
+  const { dataUpdatedAt, status, isPlaceholderData } = query
+  const queryKey = queryOptions.queryKey
+  useEffect(() => {
+    if (!scope || status !== 'success' || isPlaceholderData) return
+    // Still the seed: nothing new to store.
+    if (dataUpdatedAt === 0) return
+    // `query.data` is the selected shape; persist the raw cache value.
+    const raw = queryClient.getQueryData<TQueryFnData>(queryKey)
+    if (raw === undefined) return
+    snapshot.write(scope, raw, { ts: dataUpdatedAt })
+    // queryKey is compared by react-query's hash, not identity: a new array
+    // each render must not rewrite the snapshot.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [queryClient, scope, snapshot, seed, status, isPlaceholderData, dataUpdatedAt])
+
+  return query
+}
+