@asteby/metacore-runtime-react 39.2.10 → 41.0.0

package/src/__tests__/use-flip-animation.test.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, afterEach } from 'vitest'
+import { render } from '@testing-library/react'
+import { useRef } from 'react'
+import { useFlipAnimation } from '../use-flip-animation'
+
+function List({ order, reduced }: { order: string[]; reduced?: boolean }) {
+  const ref = useRef<HTMLUListElement>(null)
+  useFlipAnimation(ref, order.join(','), { disabled: reduced })
+  return (
+    <ul ref={ref}>
+      {order.map((k) => (
+        <li key={k} data-flip-key={k}>
+          {k}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+// happy-dom has no layout: place each item by its index in the list.
+function fakeLayout() {
+  vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+    const parent = this.parentElement
+    const index = parent && this.dataset.flipKey ? Array.from(parent.children).indexOf(this) : 0
+    const top = this.dataset.flipKey ? index * 40 : 0
+    return { top, left: 0, width: 100, height: 40, right: 100, bottom: top + 40, x: 0, y: top, toJSON() {} } as DOMRect
+  })
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.useRealTimers()
+})
+
+describe('useFlipAnimation', () => {
+  it('animates moved items from their old position', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+
+    const view = render(<List order={['a', 'b', 'c']} />)
+    vi.advanceTimersByTime(400) // at-rest snapshot
+    view.rerender(<List order={['c', 'a', 'b']} />)
+
+    const moves = animate.mock.calls.map(([frames]) => (frames as Keyframe[])[0]!.transform)
+    // c: 80 → 0, a: 0 → 40, b: 40 → 80
+    expect(moves).toContain('translate(0px, 80px)')
+    expect(moves).toContain('translate(0px, -40px)')
+    expect(animate).toHaveBeenCalledTimes(3)
+  })
+
+  it('stays still when disabled (reduced motion path)', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+
+    const view = render(<List order={['a', 'b']} reduced />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<List order={['b', 'a']} reduced />)
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('stays still under prefers-reduced-motion', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+    vi.spyOn(window, 'matchMedia').mockImplementation(
+      (query: string) => ({ matches: query.includes('reduce'), media: query }) as MediaQueryList,
+    )
+
+    const view = render(<List order={['a', 'b']} />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<List order={['b', 'a']} />)
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('works with a root resolved from the DOM instead of a wrapper element', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+    const domRef = {
+      get current() {
+        return document.querySelector<HTMLElement>('[data-slot="list"]')
+      },
+    }
+    function Resolved({ order }: { order: string[] }) {
+      useFlipAnimation(domRef, order.join(','))
+      return (
+        <ul data-slot="list">
+          {order.map((k) => (
+            <li key={k} data-flip-key={k}>
+              {k}
+            </li>
+          ))}
+        </ul>
+      )
+    }
+
+    const view = render(<Resolved order={['a', 'b']} />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<Resolved order={['b', 'a']} />)
+    expect(animate).toHaveBeenCalledTimes(2)
+  })
+})

package/src/__tests__/use-optimistic-mutation.test.tsx

@@ -0,0 +1,201 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, afterEach } from 'vitest'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import { useOptimisticMutation } from '../use-optimistic-mutation'
+
+type Doc = { template: string }
+const KEY = ['layout']
+
+function deferred<T>() {
+  let resolve!: (v: T) => void
+  let reject!: (e: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+function setup(
+  mutationFn: (template: string) => Promise<Doc>,
+  extra: { debounceMs?: number; onError?: (e: unknown, v: string) => void } = {},
+) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } })
+  qc.setQueryData<Doc>(KEY, { template: 'default' })
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+  )
+  const hook = renderHook(
+    () =>
+      useOptimisticMutation<Doc, string, Doc>({
+        queryKey: KEY,
+        mutationFn,
+        optimistic: (_current, template) => ({ template }),
+        reconcile: (data) => data,
+        ...extra,
+      }),
+    { wrapper },
+  )
+  return { qc, hook }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('useOptimisticMutation', () => {
+  it('patches the cache before the request resolves and reconciles with the response', async () => {
+    const req = deferred<Doc>()
+    const { qc, hook } = setup(() => req.promise)
+
+    act(() => hook.result.current.mutate('classic'))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+    expect(hook.result.current.isPending).toBe(true)
+    expect(hook.result.current.pendingVariables).toBe('classic')
+
+    await act(async () => req.resolve({ template: 'classic-server' }))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic-server' })
+  })
+
+  it('rolls back to the confirmed value and reports the error', async () => {
+    const req = deferred<Doc>()
+    const onError = vi.fn()
+    const { qc, hook } = setup(() => req.promise, { onError })
+
+    act(() => hook.result.current.mutate('classic'))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+
+    await act(async () => req.reject(new Error('boom')))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+    expect(onError).toHaveBeenCalledWith(expect.any(Error), 'classic')
+  })
+
+  it('ignores a repeated call while the same write is in flight (double click)', async () => {
+    const req = deferred<Doc>()
+    const fn = vi.fn(() => req.promise)
+    const { hook } = setup(fn)
+
+    act(() => {
+      hook.result.current.mutate('classic')
+      hook.result.current.mutate('classic')
+    })
+    await act(async () => req.resolve({ template: 'classic' }))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('runs writes in call order and an older response never overwrites a newer choice', async () => {
+    const first = deferred<Doc>()
+    const second = deferred<Doc>()
+    const calls: string[] = []
+    const fn = vi.fn((t: string) => {
+      calls.push(t)
+      return t === 'classic' ? first.promise : second.promise
+    })
+    const { qc, hook } = setup(fn)
+
+    act(() => {
+      hook.result.current.mutate('classic')
+      hook.result.current.mutate('default')
+    })
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+
+    await act(async () => first.resolve({ template: 'classic' }))
+    // Serialized: the second write starts only after the first settles.
+    await waitFor(() => expect(calls).toEqual(['classic', 'default']))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+    expect(hook.result.current.pendingVariables).toBe('default')
+
+    await act(async () => second.resolve({ template: 'default' }))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+  })
+
+  it('rolls back to the last server-confirmed value when only the newest write fails', async () => {
+    const first = deferred<Doc>()
+    const second = deferred<Doc>()
+    const { qc, hook } = setup((t) => (t === 'classic' ? first.promise : second.promise))
+
+    act(() => {
+      hook.result.current.mutate('classic')
+      hook.result.current.mutate('custom')
+    })
+    await act(async () => first.resolve({ template: 'classic' }))
+    await act(async () => second.reject(new Error('nope')))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+  })
+
+  it('keeps a superseded failure silent when the newest write succeeds', async () => {
+    const first = deferred<Doc>()
+    const second = deferred<Doc>()
+    const onError = vi.fn()
+    const { qc, hook } = setup((t) => (t === 'classic' ? first.promise : second.promise), { onError })
+
+    act(() => {
+      hook.result.current.mutate('classic')
+      hook.result.current.mutate('custom')
+    })
+    await act(async () => first.reject(new Error('stale')))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'custom' })
+    await act(async () => second.resolve({ template: 'custom' }))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(onError).not.toHaveBeenCalled()
+    expect(hook.result.current.error).toBeNull()
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'custom' })
+  })
+
+  it('debounces bursts: every call paints, only the last one is sent', async () => {
+    vi.useFakeTimers()
+    const fn = vi.fn((t: string) => Promise.resolve({ template: t }))
+    const { qc, hook } = setup(fn, { debounceMs: 400 })
+
+    act(() => hook.result.current.mutate('a'))
+    act(() => hook.result.current.mutate('b'))
+    act(() => hook.result.current.mutate('c'))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'c' })
+    expect(fn).not.toHaveBeenCalled()
+
+    await act(async () => {
+      vi.advanceTimersByTime(400)
+    })
+    vi.useRealTimers()
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(fn).toHaveBeenCalledWith('c')
+  })
+
+  it('flushes a pending debounced write on unmount', async () => {
+    vi.useFakeTimers()
+    const fn = vi.fn((t: string) => Promise.resolve({ template: t }))
+    const { hook } = setup(fn, { debounceMs: 400 })
+
+    act(() => hook.result.current.mutate('saved-on-close'))
+    hook.unmount()
+    vi.useRealTimers()
+    await waitFor(() => expect(fn).toHaveBeenCalledWith('saved-on-close'))
+  })
+})
+
+describe('useOptimisticMutation retry', () => {
+  it('re-sends the failed variables and re-applies them optimistically', async () => {
+    let fail = true
+    const fn = vi.fn((t: string) => (fail ? Promise.reject(new Error('offline')) : Promise.resolve({ template: t })))
+    const { qc, hook } = setup(fn)
+
+    act(() => hook.result.current.mutate('classic'))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+
+    fail = false
+    act(() => hook.result.current.retry())
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(fn).toHaveBeenCalledTimes(2)
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+  })
+})

package/src/agent-result-registry.test.tsx

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { renderToStaticMarkup } from 'react-dom/server'
+import {
+    AgentResultView,
+    clearAgentResultRenderers,
+    listAgentResultRenderers,
+    registerAgentResultRenderer,
+    resolveAgentResultRenderer,
+    type AgentResultRendererProps,
+} from './agent-result-registry'
+
+const Generic = ({ result }: AgentResultRendererProps) => <span>generic:{String(result.title)}</span>
+const Invoice = ({ result }: AgentResultRendererProps) => <span>invoice:{String(result.title)}</span>
+
+afterEach(() => clearAgentResultRenderers())
+
+describe('agent result registry', () => {
+    it('renders a result through the renderer of its kind', () => {
+        registerAgentResultRenderer('record', Generic)
+        const html = renderToStaticMarkup(
+            <AgentResultView result={{ kind: 'record', model: 'products', title: 'Llanta' }} />,
+        )
+        expect(html).toBe('<span>generic:Llanta</span>')
+    })
+
+    it('prefers a model-specific renderer over the generic one', () => {
+        registerAgentResultRenderer('record', Generic)
+        registerAgentResultRenderer('record', Invoice, { model: 'invoices' })
+        expect(resolveAgentResultRenderer({ kind: 'record', model: 'invoices' })).toBe(Invoice)
+        expect(resolveAgentResultRenderer({ kind: 'record', model: 'products' })).toBe(Generic)
+    })
+
+    it('renders nothing (never the raw payload) for an unknown kind', () => {
+        const html = renderToStaticMarkup(
+            <AgentResultView result={{ kind: 'mystery', secret: 'Model: warehouses' }} />,
+        )
+        expect(html).toBe('')
+        expect(
+            renderToStaticMarkup(
+                <AgentResultView result={{ kind: 'mystery' }} fallback={<i>sin vista</i>} />,
+            ),
+        ).toBe('<i>sin vista</i>')
+    })
+
+    it('unregister only removes its own registration', () => {
+        const off = registerAgentResultRenderer('count', Generic)
+        registerAgentResultRenderer('count', Invoice)
+        off()
+        expect(resolveAgentResultRenderer({ kind: 'count' })).toBe(Invoice)
+        expect(listAgentResultRenderers()).toEqual(['count'])
+    })
+})

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

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from 'vitest'
+import { classesCarriedByRecord, resolveAttributeClasses, resetAttributeClassCache } from './attribute-classes'
+import { ATTRIBUTE_CLASSES_KEY, evaluateVisibleWhen, getVisibleWhen } from './dynamic-form-schema'
+import { filterVisibleFields } from './dialogs/dynamic-record'
+
+describe('visible_when.class', () => {
+    it('shows a class field only when the record carries the class', () => {
+        const cond = getVisibleWhen({ visible_when: { class: 'tire' } })
+        expect(cond).toEqual({ class: 'tire' })
+        expect(evaluateVisibleWhen(cond, { [ATTRIBUTE_CLASSES_KEY]: ['tire'] })).toBe(true)
+        expect(evaluateVisibleWhen(cond, { [ATTRIBUTE_CLASSES_KEY]: ['battery'] })).toBe(false)
+        expect(evaluateVisibleWhen(cond, {})).toBe(false)
+    })
+
+    it('filters dialog fields by the resolved classes and keeps the rest', () => {
+        const fields = [
+            { key: 'name', label: 'Nombre', type: 'text' },
+            { key: 'TireSpec.rim_diameter_in', label: 'Rin', type: 'number', visible_when: { class: 'tire' } },
+        ] as never
+        const values = { name: 'x' }
+        expect(filterVisibleFields(fields, 'create', values, []).map((f) => f.key)).toEqual(['name'])
+        expect(filterVisibleFields(fields, 'create', values, ['tire']).map((f) => f.key)).toEqual([
+            'name',
+            'TireSpec.rim_diameter_in',
+        ])
+    })
+})
+
+describe('resolveAttributeClasses', () => {
+    it('walks the category parents and caches each node', async () => {
+        resetAttributeClassCache()
+        const rows: Record<string, unknown> = {
+            c1: { attribute_classes: [], parent_id: 'c0' },
+            c0: { attribute_classes: ['tire'], parent_id: null },
+        }
+        const get = vi.fn(async (url: string) => ({ data: { data: rows[url.split('/').pop() as string] } }))
+        const api = { get, post: vi.fn(), put: vi.fn(), delete: vi.fn() }
+        expect(await resolveAttributeClasses(api as never, 'Category', 'c1')).toEqual(['tire'])
+        await resolveAttributeClasses(api as never, 'Category', 'c1')
+        expect(get).toHaveBeenCalledTimes(2)
+        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([])
+    })
+})