@asteby/metacore-runtime-react 39.3.0 → 41.0.0

package/src/agent-result-registry.tsx

@@ -0,0 +1,129 @@
+// Agent result renderer registry. An agent reply carries structured tool
+// results (a record, a filtered view, a count, a chart, a plan of changes, a
+// suggested action…) next to its prose. Each result declares a `kind`; the
+// host renders it through whatever component is registered for that kind, so
+// the chat never prints a raw tool payload and an addon can teach the chat
+// to render its own results without touching the host:
+//
+//   import { registerAgentResultRenderer } from '@asteby/metacore-runtime-react'
+//
+//   registerAgentResultRenderer('record', RecordCard)              // any model
+//   registerAgentResultRenderer('record', InvoiceCard, { model: 'invoices' })
+//   registerAgentResultRenderer('shipment_quote', QuoteCard)       // addon kind
+//
+// Resolution is most specific first: `kind` + `model`, then `kind`. A result
+// with no renderer renders nothing (never a JSON dump) unless the caller
+// passes a fallback.
+//
+// Module-level singleton like the model-extension registry, but observable:
+// federated addons register after the host has already painted, so views
+// subscribe and re-render when a renderer lands.
+import * as React from 'react'
+
+/** A structured tool result shown under an agent reply. */
+export interface AgentResult {
+    /** Result type, e.g. record | view | count | chart | image | plan | proposal | action. */
+    kind: string
+    /** Model key the result belongs to, when it has one. */
+    model?: string
+    [key: string]: unknown
+}
+
+export interface AgentResultRendererProps<R extends AgentResult = AgentResult> {
+    result: R
+    /**
+     * Interactive results (approve a plan, launch a guide) report back through
+     * here; the host decides what an action means.
+     */
+    onAction?: (action: string, payload?: unknown) => void
+    /** Host is processing an action for this result. */
+    busy?: boolean
+}
+
+export type AgentResultRenderer<R extends AgentResult = AgentResult> = React.ComponentType<
+    AgentResultRendererProps<R>
+>
+
+export interface AgentResultRendererOptions {
+    /** Only for results of this model (overrides the generic renderer of the kind). */
+    model?: string
+}
+
+const renderers = new Map<string, AgentResultRenderer<any>>()
+const listeners = new Set<() => void>()
+let version = 0
+
+function keyOf(kind: string, model?: string): string {
+    return model ? `${kind}:${model}` : kind
+}
+
+function emit(): void {
+    version++
+    listeners.forEach((l) => l())
+}
+
+/**
+ * Registers the component that renders results of `kind` (optionally only
+ * for one model). Returns an unregister function; a later registration for
+ * the same key replaces the earlier one.
+ */
+export function registerAgentResultRenderer<R extends AgentResult = AgentResult>(
+    kind: string,
+    renderer: AgentResultRenderer<R>,
+    options: AgentResultRendererOptions = {},
+): () => void {
+    const key = keyOf(kind, options.model)
+    renderers.set(key, renderer)
+    emit()
+    return () => {
+        if (renderers.get(key) === renderer) {
+            renderers.delete(key)
+            emit()
+        }
+    }
+}
+
+/** Most specific renderer for a result: kind+model, then kind. */
+export function resolveAgentResultRenderer(
+    result: Pick<AgentResult, 'kind' | 'model'>,
+): AgentResultRenderer | undefined {
+    if (!result?.kind) return undefined
+    return (result.model && renderers.get(keyOf(result.kind, result.model))) || renderers.get(result.kind)
+}
+
+/** Registered keys (`kind` or `kind:model`), for diagnostics. */
+export function listAgentResultRenderers(): string[] {
+    return [...renderers.keys()]
+}
+
+export function clearAgentResultRenderers(): void {
+    renderers.clear()
+    emit()
+}
+
+function subscribe(listener: () => void): () => void {
+    listeners.add(listener)
+    return () => listeners.delete(listener)
+}
+
+/** Re-renders the caller whenever a renderer is (un)registered. */
+export function useAgentResultRegistryVersion(): number {
+    return React.useSyncExternalStore(
+        subscribe,
+        () => version,
+        () => version,
+    )
+}
+
+export interface AgentResultViewProps extends AgentResultRendererProps {
+    /** Rendered when no renderer matches. Defaults to nothing. */
+    fallback?: React.ReactNode
+}
+
+/** Renders one agent result through the registry. */
+export function AgentResultView({ result, fallback = null, ...rest }: AgentResultViewProps) {
+    useAgentResultRegistryVersion()
+    const Renderer = resolveAgentResultRenderer(result)
+    if (!Renderer) return <>{fallback}</>
+    return <Renderer result={result} {...rest} />
+}

package/src/attribute-classes.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { resolveAttributeClasses, resetAttributeClassCache } from './attribute-classes'
+import { classesCarriedByRecord, resolveAttributeClasses, resetAttributeClassCache } from './attribute-classes'
 import { ATTRIBUTE_CLASSES_KEY, evaluateVisibleWhen, getVisibleWhen } from './dynamic-form-schema'
 import { filterVisibleFields } from './dialogs/dynamic-record'
 
@@ -41,3 +41,39 @@ describe('resolveAttributeClasses', () => {
         expect(get).toHaveBeenCalledWith('/data/Category/c1')
     })
 })
+
+describe('classesCarriedByRecord', () => {
+    const meta = {
+        attribute_classes: [
+            { key: 'tire', sections: [{ key: 'size', fields: ['section_width_mm', 'rim_diameter_in'] }] },
+            { key: 'battery', sections: [{ key: 'b', fields: ['capacity_ah'] }] },
+        ],
+        fields: [
+            { key: 'name' },
+            { key: 'TireSpec.section_width_mm' },
+            { key: 'TireSpec.rim_diameter_in' },
+            { key: 'BatterySpec.capacity_ah' },
+        ],
+    }
+
+    it('a saved tire with a spec sheet keeps its fields without a category class', () => {
+        expect(classesCarriedByRecord(meta, { name: 'x', 'TireSpec.rim_diameter_in': 16 })).toEqual(['tire'])
+        // nested shape
+        expect(classesCarriedByRecord(meta, { TireSpec: { section_width_mm: 205 } })).toEqual(['tire'])
+        const fields = [
+            { key: 'name', label: 'Nombre', type: 'text' },
+            { key: 'TireSpec.rim_diameter_in', label: 'Rin', type: 'number', visible_when: { class: 'tire' } },
+        ] as never
+        const carried = classesCarriedByRecord(meta, { 'TireSpec.rim_diameter_in': 16 })
+        expect(filterVisibleFields(fields, 'edit', { name: 'x' }, carried).map((f) => f.key)).toEqual([
+            'name',
+            'TireSpec.rim_diameter_in',
+        ])
+    })
+
+    it('a record without data in the class fields carries nothing', () => {
+        expect(classesCarriedByRecord(meta, { name: 'x', 'TireSpec.rim_diameter_in': null, 'TireSpec.section_width_mm': '' })).toEqual([])
+        expect(classesCarriedByRecord(meta, null)).toEqual([])
+        expect(classesCarriedByRecord({ fields: meta.fields }, { 'TireSpec.rim_diameter_in': 16 })).toEqual([])
+    })
+})

package/src/attribute-classes.ts

@@ -1,14 +1,15 @@
 // Attribute classes (CONTRACT-item-master §3.2): an extension table's columns
 // are grouped into classes, and each organization assigns classes to its
 // categories. A field with `visible_when.class` shows when the record's
-// category (or one of its parents) carries the class.
+// category (or one of its parents) carries the class, or when the saved record
+// already has data in the class's fields (existing data is never hidden).
 //
 // The host serves the classes on the modal metadata (`attribute_classes`) and,
 // optionally, the field whose referenced record carries them
 // (`attribute_class_field`, default `category_id`). The referenced record
 // exposes its classes as `attribute_classes` (array of keys) and its parent as
 // `parent_id`.
-import { useEffect, useState } from 'react'
+import { useEffect, useMemo, useState } from 'react'
 import type { ApiClient } from './api-context'
 
 export interface AttributeClassSection {
@@ -73,14 +74,54 @@ export function resetAttributeClassCache(): void {
     cache.clear()
 }
 
+function readPath(rec: Record<string, unknown>, key: string): unknown {
+    if (key in rec) return rec[key]
+    let cur: unknown = rec
+    for (const part of key.split('.')) {
+        if (cur == null || typeof cur !== 'object') return undefined
+        cur = (cur as Record<string, unknown>)[part]
+    }
+    return cur
+}
+
+/**
+ * The classes a saved record already carries by its own data: a class whose
+ * section fields hold a value in the record. Its fields stay visible even when
+ * the category lacks the class (a tire with a spec sheet but no category, or a
+ * category the org has not tagged yet) — hiding a class must never hide data
+ * that exists. Field keys are matched as served, bare or `<Extension>.<column>`.
+ */
+export function classesCarriedByRecord(
+    meta: { attribute_classes?: AttributeClass[]; fields?: { key: string }[] } | null | undefined,
+    record: Record<string, unknown> | null | undefined,
+): string[] {
+    if (!record || !Array.isArray(meta?.attribute_classes)) return []
+    const keys = (meta?.fields ?? []).map((f) => f.key)
+    const out: string[] = []
+    for (const cls of meta!.attribute_classes!) {
+        const cols = new Set((cls.sections ?? []).flatMap((s) => s.fields ?? []))
+        const carried = keys.some((k) => {
+            const col = k.includes('.') ? k.slice(k.lastIndexOf('.') + 1) : k
+            if (!cols.has(col) && !cols.has(k)) return false
+            const v = readPath(record, k)
+            return v != null && v !== ''
+        })
+        if (carried) out.push(cls.key)
+    }
+    return out
+}
+
 /**
- * The classes that apply to the form's current category. `meta` is the modal
- * metadata; `fields` its field list (to find the class field's ref).
+ * The classes that apply to the form: those of its current category plus
+ * those the saved record carries by its data (classesCarriedByRecord). `meta`
+ * is the modal metadata; `fields` its field list (to find the class field's
+ * ref). `record` is the record as loaded (null on create).
  */
 export function useAttributeClasses(
     api: ApiClient,
     meta: { attribute_classes?: AttributeClass[]; attribute_class_field?: string; fields?: { key: string; ref?: string }[] } | null | undefined,
     formValues: Record<string, unknown>,
+    record?: Record<string, unknown> | null,
 ): string[] {
     const hasClasses = Array.isArray(meta?.attribute_classes) && meta!.attribute_classes!.length > 0
     const classField = meta?.attribute_class_field || 'category_id'
@@ -101,5 +142,6 @@ export function useAttributeClasses(
             alive = false
         }
     }, [api, model, idStr])
-    return classes
+    const carried = useMemo(() => classesCarriedByRecord(meta, record), [meta, record])
+    return useMemo(() => (carried.length ? [...new Set([...classes, ...carried])] : classes), [classes, carried])
 }

package/src/dialogs/dynamic-record.tsx

@@ -644,8 +644,9 @@ export function DynamicRecordDialog({
     const [relations, setRelations] = useState<RelationMeta[]>([])
     const [record, setRecord] = useState<any | null>(null)
     const [formValues, setFormValues] = useState<Record<string, any>>({})
-    // Classes of the record's category, for `visible_when.class` fields.
-    const attributeClasses = useAttributeClasses(api, modalMeta, formValues)
+    // Classes of the record's category (plus those its saved data carries), for
+    // `visible_when.class` fields.
+    const attributeClasses = useAttributeClasses(api, modalMeta, formValues, record)
     // Per-field validation errors (localized strings), keyed by field.key. Shown
     // inline under each input; populated from a 422 `errors` map or the client
     // required-field check, cleared per-field on change and wholesale on reopen.

package/src/index.ts

@@ -129,6 +129,20 @@ export {
     type UseDynamicFiltersResult,
 } from './use-dynamic-filters'
 export { useDebouncedValue, SEARCH_DEBOUNCE_MS } from './use-debounced-value'
+export {
+    useOptimisticMutation,
+    type UseOptimisticMutationOptions,
+    type UseOptimisticMutationResult,
+} from './use-optimistic-mutation'
+export { useFlipAnimation, type UseFlipAnimationOptions } from './use-flip-animation'
+export {
+    motionDuration,
+    motionEasing,
+    prefersReducedMotion,
+    MOTION_DEFAULTS,
+    type MotionDuration,
+    type MotionEasing,
+} from './motion'
 export {
     useResource,
     useMutation,
@@ -385,6 +399,19 @@ export {
     type ModelExtension,
     type ModelExtensionProps,
 } from './model-extension-registry'
+export {
+    registerAgentResultRenderer,
+    resolveAgentResultRenderer,
+    listAgentResultRenderers,
+    clearAgentResultRenderers,
+    useAgentResultRegistryVersion,
+    AgentResultView,
+    type AgentResult,
+    type AgentResultRenderer,
+    type AgentResultRendererOptions,
+    type AgentResultRendererProps,
+    type AgentResultViewProps,
+} from './agent-result-registry'
 export {
     isColumnVisibleInTable,
     isColumnVisibleInModal,

package/src/motion.ts

@@ -0,0 +1,47 @@
+/**
+ * Runtime access to the theme's motion tokens (`--motion-duration-*`,
+ * `--motion-ease-*` from @asteby/metacore-theme/tokens.css). Hosts that do
+ * not ship those variables get the same defaults, so JS-driven animations
+ * (WAAPI, dnd-kit) and CSS transitions stay on one scale.
+ */
+export type MotionDuration = 'instant' | 'fast' | 'moderate' | 'slow'
+export type MotionEasing = 'standard' | 'emphasized' | 'exit'
+
+export const MOTION_DEFAULTS = {
+  duration: { instant: 100, fast: 150, moderate: 220, slow: 320 } as Record<MotionDuration, number>,
+  easing: {
+    standard: 'cubic-bezier(0.2, 0, 0, 1)',
+    emphasized: 'cubic-bezier(0.3, 0, 0, 1)',
+    exit: 'cubic-bezier(0.4, 0, 1, 1)',
+  } as Record<MotionEasing, string>,
+}
+
+function cssVar(name: string): string {
+  if (typeof document === 'undefined' || typeof getComputedStyle !== 'function') return ''
+  return getComputedStyle(document.documentElement).getPropertyValue(name).trim()
+}
+
+/** True when the user asked the OS for reduced motion. */
+export function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  )
+}
+
+/** Duration token in ms (0 under prefers-reduced-motion). */
+export function motionDuration(token: MotionDuration): number {
+  if (prefersReducedMotion()) return 0
+  const raw = cssVar(`--motion-duration-${token}`)
+  if (raw) {
+    const n = parseFloat(raw)
+    if (Number.isFinite(n)) return raw.endsWith('ms') || !raw.endsWith('s') ? n : n * 1000
+  }
+  return MOTION_DEFAULTS.duration[token]
+}
+
+/** Easing token as a CSS timing function. */
+export function motionEasing(token: MotionEasing): string {
+  return cssVar(`--motion-ease-${token}`) || MOTION_DEFAULTS.easing[token]
+}

package/src/use-flip-animation.ts

@@ -0,0 +1,157 @@
+import { useEffect, useLayoutEffect, useRef, type RefObject } from 'react'
+import {
+  motionDuration,
+  motionEasing,
+  prefersReducedMotion,
+  type MotionDuration,
+  type MotionEasing,
+} from './motion'
+
+export interface UseFlipAnimationOptions {
+  /** Elements to animate, queried inside the root. */
+  selector?: string
+  /** Stable identity of an element across renders. Default: data-flip-key, then href, then text. */
+  keyOf?: (el: HTMLElement) => string | null
+  /**
+   * Scroll container used as the coordinate origin, so scrolling between two
+   * snapshots does not read as movement. Default: the root.
+   */
+  scrollContainer?: (root: HTMLElement) => HTMLElement | null
+  /** Motion token (default `moderate`) or explicit ms. */
+  duration?: MotionDuration | number
+  /** Motion token (default `standard`) or a CSS timing function. */
+  easing?: MotionEasing | string
+  /** Off switch; the hook also stays still under prefers-reduced-motion. */
+  disabled?: boolean
+}
+
+const DEFAULT_SELECTOR = '[data-flip-key]'
+const MOTION_EASING_KEYS = { standard: 1, emphasized: 1, exit: 1 }
+
+const defaultKeyOf = (el: HTMLElement): string | null =>
+  el.dataset.flipKey ?? el.getAttribute('href') ?? (el.textContent?.trim() || null)
+
+type Positions = Map<string, { top: number; left: number }>
+
+/**
+ * FLIP reorder animation: when `trigger` changes, elements that exist before
+ * and after the change glide from their old position to the new one.
+ *
+ * Positions are snapshotted when the list is at rest (after mount, after each
+ * animation, and after pointer interaction inside the root), never in the
+ * render path, so a re-render costs nothing. Uses the Web Animations API on
+ * `transform` only; with prefers-reduced-motion the change is instant.
+ */
+export function useFlipAnimation(
+  rootRef: RefObject<HTMLElement | null>,
+  trigger: unknown,
+  options: UseFlipAnimationOptions = {},
+): void {
+  const {
+    selector = DEFAULT_SELECTOR,
+    keyOf = defaultKeyOf,
+    scrollContainer,
+    duration = 'moderate',
+    easing = 'standard',
+    disabled = false,
+  } = options
+  const positionsRef = useRef<Positions | null>(null)
+  const triggerRef = useRef(trigger)
+  const configRef = useRef({ selector, keyOf, scrollContainer })
+  useEffect(() => {
+    configRef.current = { selector, keyOf, scrollContainer }
+  })
+
+  const measure = (): Positions | null => {
+    const root = rootRef.current
+    if (!root) return null
+    const { selector: sel, keyOf: key, scrollContainer: sc } = configRef.current
+    const origin = (sc ? sc(root) : null) ?? root
+    const box = origin.getBoundingClientRect()
+    const out: Positions = new Map()
+    root.querySelectorAll<HTMLElement>(sel).forEach((el) => {
+      const k = key(el)
+      if (!k || out.has(k)) return
+      const r = el.getBoundingClientRect()
+      if (r.width === 0 && r.height === 0) return
+      out.set(k, {
+        top: r.top - box.top + origin.scrollTop,
+        left: r.left - box.left + origin.scrollLeft,
+      })
+    })
+    return out
+  }
+  const measureRef = useRef(measure)
+  useEffect(() => {
+    measureRef.current = measure
+  })
+
+  // Snapshot at rest: after mount and after interactions that move things
+  // without a trigger change (expanding a collapsible, for instance).
+  // Listens on the document and resolves the root per event, so a ref whose
+  // element is swapped (remount, mobile sheet) keeps working.
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const schedule = () => {
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => {
+        positionsRef.current = measureRef.current()
+      }, 350)
+    }
+    const onInteraction = (e: Event) => {
+      const root = rootRef.current
+      if (root && e.target instanceof Node && root.contains(e.target)) schedule()
+    }
+    schedule()
+    document.addEventListener('pointerup', onInteraction, true)
+    document.addEventListener('keyup', onInteraction, true)
+    window.addEventListener('resize', schedule)
+    return () => {
+      if (timer) clearTimeout(timer)
+      document.removeEventListener('pointerup', onInteraction, true)
+      document.removeEventListener('keyup', onInteraction, true)
+      window.removeEventListener('resize', schedule)
+    }
+  }, [rootRef])
+
+  useLayoutEffect(() => {
+    if (Object.is(triggerRef.current, trigger)) return
+    triggerRef.current = trigger
+    const before = positionsRef.current
+    const root = rootRef.current
+    if (!root) return
+    const after = measureRef.current()
+    positionsRef.current = after
+    if (!before || !after || disabled || prefersReducedMotion()) return
+    const durationMs = typeof duration === 'number' ? duration : motionDuration(duration)
+    if (durationMs <= 0) return
+    const timing = easing in MOTION_EASING_KEYS ? motionEasing(easing as MotionEasing) : easing
+
+    const { selector: sel, keyOf: key } = 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) => {
+      const k = key(el)
+      if (!k) return
+      const from = before.get(k)
+      const to = after.get(k)
+      if (!to || typeof el.animate !== 'function') return
+      if (!from) {
+        // Entered with this change: fade in instead of popping.
+        el.animate([{ opacity: 0 }, { opacity: 1 }], { duration: durationMs, easing: timing })
+        return
+      }
+      const dy = from.top - to.top
+      const dx = from.left - to.left
+      if (Math.abs(dy) < 1 && Math.abs(dx) < 1) return
+      if (Math.abs(dy) > maxJump) return
+      el.animate(
+        [
+          { transform: `translate(${dx}px, ${dy}px)` },
+          { transform: 'translate(0, 0)' },
+        ],
+        { duration: durationMs, easing: timing },
+      )
+    })
+  }, [trigger, rootRef, disabled, duration, easing])
+}