@asteby/metacore-runtime-react 39.2.10 → 41.0.0

package/src/attribute-classes.ts

@@ -0,0 +1,147 @@
+// 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, 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, useMemo, useState } from 'react'
+import type { ApiClient } from './api-context'
+
+export interface AttributeClassSection {
+    key: string
+    label?: string
+    fields: string[]
+}
+
+export interface AttributeClass {
+    key: string
+    label?: string
+    sections: AttributeClassSection[]
+}
+
+/** How many parent hops the class lookup walks (a category tree is shallow). */
+const MAX_PARENT_HOPS = 5
+
+const cache = new Map<string, Promise<{ classes: string[]; parent: string | null }>>()
+
+function refModel(ref: string | undefined): string | null {
+    if (!ref) return null
+    const i = ref.lastIndexOf('.')
+    return i >= 0 ? ref.slice(i + 1) : ref
+}
+
+function loadNode(api: ApiClient, model: string, id: string) {
+    const key = `${model}\n${id}`
+    let hit = cache.get(key)
+    if (!hit) {
+        hit = api
+            .get(`/data/${model}/${id}`)
+            .then((res) => {
+                const row = (res?.data?.data ?? {}) as Record<string, unknown>
+                const raw = row.attribute_classes
+                const classes = Array.isArray(raw) ? raw.map(String) : []
+                const parent = row.parent_id ? String(row.parent_id) : null
+                return { classes, parent }
+            })
+            .catch(() => ({ classes: [] as string[], parent: null }))
+        cache.set(key, hit)
+    }
+    return hit
+}
+
+/**
+ * Resolves the attribute classes of the record's category and its parents.
+ * Returns [] when the model serves no classes or the category is empty.
+ */
+export async function resolveAttributeClasses(api: ApiClient, model: string, id: string): Promise<string[]> {
+    const out = new Set<string>()
+    let current: string | null = id
+    for (let hop = 0; current && hop <= MAX_PARENT_HOPS; hop++) {
+        const node: { classes: string[]; parent: string | null } = await loadNode(api, model, current)
+        node.classes.forEach((c) => out.add(c))
+        current = node.parent
+    }
+    return [...out]
+}
+
+/** Test hook: forget cached category lookups. */
+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: 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'
+    const model = refModel(meta?.fields?.find((f) => f.key === classField)?.ref) ?? 'Category'
+    const id = hasClasses ? formValues[classField] : undefined
+    const idStr = id == null || id === '' ? '' : String(id)
+    const [classes, setClasses] = useState<string[]>([])
+    useEffect(() => {
+        if (!idStr) {
+            setClasses([])
+            return
+        }
+        let alive = true
+        void resolveAttributeClasses(api, model, idStr).then((c) => {
+            if (alive) setClasses(c)
+        })
+        return () => {
+            alive = false
+        }
+    }, [api, model, idStr])
+    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

@@ -60,7 +60,8 @@ import { DynamicSelectField, OptionLead, OptionThumb } from '../dynamic-select-f
 import { DynamicMultiSelectField } from '../dynamic-multi-select-field'
 import { DynamicRelations } from '../dynamic-relations'
 import { useOptionsResolver, type ResolvedOption } from '../use-options-resolver'
-import { getFieldRef, getVisibleWhen, evaluateVisibleWhen } from '../dynamic-form-schema'
+import { getFieldRef, getVisibleWhen, evaluateVisibleWhen, ATTRIBUTE_CLASSES_KEY } from '../dynamic-form-schema'
+import { useAttributeClasses, type AttributeClass } from '../attribute-classes'
 import type { VisibleWhen } from '../types'
 import { groupFieldsBySection, type FormLayout } from '../form-layout'
 import { FieldSection, WizardProgress } from '../form-layout-ui'
@@ -203,6 +204,14 @@ interface ModalMetadata {
     form_layout?: FormLayout
     /** camelCase alias for `form_layout`. */
     formLayout?: FormLayout
+    /**
+     * Attribute classes of the model's extensions enabled for the org
+     * (CONTRACT-item-master §3.2); fields with `visible_when.class` show when
+     * the record's category carries the class.
+     */
+    attribute_classes?: AttributeClass[]
+    /** Field whose referenced record carries the classes (default category_id). */
+    attribute_class_field?: string
     /**
      * Backend-localized CRUD success messages (modal metadata). Preferred over
      * the raw response message which is not localized.
@@ -552,11 +561,13 @@ export function filterVisibleFields(
     fields: FieldDef[] | undefined,
     mode: 'view' | 'edit' | 'create',
     formValues?: Record<string, any>,
+    attributeClasses?: string[],
 ): FieldDef[] {
+    const values = formValues && attributeClasses ? { ...formValues, [ATTRIBUTE_CLASSES_KEY]: attributeClasses } : formValues
     return (fields ?? []).filter(f => {
         if (f.hidden) return false
         if (mode === 'create' && f.readonly) return false
-        if (formValues && !evaluateVisibleWhen(getVisibleWhen(f), formValues)) return false
+        if (values && !evaluateVisibleWhen(getVisibleWhen(f), values)) return false
         return true
     })
 }
@@ -573,8 +584,9 @@ export function stripHiddenFieldValues(
     values: Record<string, any>,
     fields: FieldDef[] | undefined,
     mode: 'view' | 'edit' | 'create',
+    attributeClasses?: string[],
 ): Record<string, any> {
-    const visibleKeys = new Set(filterVisibleFields(fields, mode, values).map(f => f.key))
+    const visibleKeys = new Set(filterVisibleFields(fields, mode, values, attributeClasses).map(f => f.key))
     const out: Record<string, any> = {}
     for (const [key, value] of Object.entries(values)) {
         const field = (fields ?? []).find(f => f.key === key)
@@ -632,6 +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 (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.
@@ -846,7 +861,7 @@ export function DynamicRecordDialog({
             }
             setFieldErrors(next)
             const visibleKeys = new Set(
-                filterVisibleFields(modalMeta?.fields ?? [], mode, formValues).map(f => f.key),
+                filterVisibleFields(modalMeta?.fields ?? [], mode, formValues, attributeClasses).map(f => f.key),
             )
             const orphans = Object.entries(next).filter(([k]) => !visibleKeys.has(k))
             const description = orphans.length
@@ -868,7 +883,7 @@ export function DynamicRecordDialog({
         if (isEditable) {
             // Laravel-style: collect every issue from the shared validator
             // (required + rule strings / min/max / email…) on visible fields only.
-            const visible = filterVisibleFields(modalMeta.fields, mode, formValues)
+            const visible = filterVisibleFields(modalMeta.fields, mode, formValues, attributeClasses)
             let bag = validateValues(visible as ActionFieldDef[], formValues)
             // Edit: a legacy value re-sent unchanged is not re-judged by a rule
             // added after it was written (same grandfathering as the kernel).
@@ -909,7 +924,7 @@ export function DynamicRecordDialog({
         // filter, so a DiscountRule with scope=category never submits the
         // product_id / customer_id it isn't showing. Mirrors dynamic-form.tsx,
         // which builds its Zod only over visibleFields.
-        const submittedValues = stripHiddenFieldValues(formValues, modalMeta.fields, mode)
+        const submittedValues = stripHiddenFieldValues(formValues, modalMeta.fields, mode, attributeClasses)
 
         // Empty reference pickers → null (not "" / nil-UUID) so nullable FK
         // columns accept them instead of raising a 23503 FK violation.
@@ -1002,7 +1017,7 @@ export function DynamicRecordDialog({
             ? 'Editar registro'
             : 'Ver registro'
 
-    const visibleFields = filterVisibleFields(modalMeta?.fields, mode, formValues)
+    const visibleFields = filterVisibleFields(modalMeta?.fields, mode, formValues, attributeClasses)
 
     // Declarative form layout: group the (already visibility-filtered) fields by
     // their section. Empty sections drop out for free. Steps mode only drives a

package/src/dynamic-form-schema.ts

@@ -404,9 +404,16 @@ export function getVisibleWhen(
 ): VisibleWhen | undefined {
     if (!field) return undefined
     const vw = field.visible_when ?? field.visibleWhen
-    return vw && typeof vw === 'object' && typeof vw.field === 'string' ? vw : undefined
+    return vw && typeof vw === 'object' && (typeof vw.field === 'string' || typeof vw.class === 'string') ? vw : undefined
 }
 
+/**
+ * Form-values key that carries the record's attribute classes (resolved from
+ * its category) so `visible_when.class` evaluates with the same pure function
+ * as the sibling-field predicates. Never submitted.
+ */
+export const ATTRIBUTE_CLASSES_KEY = '__attribute_classes'
+
 /**
  * Evaluates a `visible_when` predicate against the current flat form values.
  * Pure — no React, no side effects.
@@ -426,6 +433,10 @@ export function evaluateVisibleWhen(
     cond: VisibleWhen | null | undefined,
     formValues: Record<string, any> | null | undefined,
 ): boolean {
+    if (cond && typeof cond.class === 'string' && cond.class !== '') {
+        const classes = formValues ? formValues[ATTRIBUTE_CLASSES_KEY] : undefined
+        return Array.isArray(classes) && classes.includes(cond.class)
+    }
     if (!cond || typeof cond.field !== 'string' || cond.field.trim() === '') return true
     const raw = formValues ? formValues[cond.field.trim()] : undefined
     const current = raw == null ? '' : String(raw)
@@ -513,6 +524,7 @@ export function evaluateVisibleWhenForListScope(
     cond: VisibleWhen | null | undefined,
     scope: Record<string, any> | null | undefined,
 ): boolean {
+    // A class predicate depends on each row's category: a list keeps the column.
     if (!cond || typeof cond.field !== 'string' || cond.field.trim() === '') return true
     const key = cond.field.trim()
     if (!scope || !(key in scope)) return true

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,
@@ -431,6 +458,7 @@ export {
     resolveOptionsSource,
     getVisibleWhen,
     evaluateVisibleWhen,
+    ATTRIBUTE_CLASSES_KEY,
     scopeValueFromFilterToken,
     buildListScopeValues,
     evaluateVisibleWhenForListScope,
@@ -519,3 +547,10 @@ export {
 } from './widgets/widget-format'
 export { AssistInterview, AssistCardView } from './assist-interview'
 export type { AssistSession, AssistTurn, AssistQuestion, AssistCard, AssistProgressStep } from './assist-interview'
+export {
+    useAttributeClasses,
+    resolveAttributeClasses,
+    resetAttributeClassCache,
+    type AttributeClass,
+    type AttributeClassSection,
+} from './attribute-classes'

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/types.ts

@@ -386,9 +386,16 @@ export interface ActionCondition {
  * values; a hidden field never gates submit (its required-check is skipped).
  */
 export interface VisibleWhen {
-    field: string
+    field?: string
     equals?: string
     in?: string[]
+    /**
+     * Attribute class (kernel v3 `visible_when.class`, CONTRACT-item-master):
+     * the field shows when the record's category carries this class. Used
+     * alone, without `field`. Evaluated against the classes the dialog
+     * resolves for the record (see `useAttributeClasses`).
+     */
+    class?: string
 }
 
 // Write-time + client-side constraints. The kernel enforces these on

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