@asteby/metacore-runtime-react 39.3.0 → 42.0.0

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/__tests__/use-persisted-query.test.tsx

@@ -0,0 +1,132 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, beforeEach, vi } from 'vitest'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import { createPersistedSnapshot, usePersistedQuery } from '../use-persisted-query'
+
+type Layout = { order: string[] }
+
+function deferred<T>() {
+  let resolve!: (v: T) => void
+  const promise = new Promise<T>((res) => {
+    resolve = res
+  })
+  return { promise, resolve }
+}
+
+function wrapperFor(qc: QueryClient) {
+  return ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+  )
+}
+
+const newClient = () => new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+describe('createPersistedSnapshot', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('round-trips per scope and version', () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    const ts = Date.now() - 1000
+    snap.write('org-a', { order: ['a'] }, { ts })
+    expect(snap.read('org-a')).toEqual({ data: { order: ['a'] }, ts })
+    expect(snap.read('org-b')).toBeUndefined()
+    const v2 = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 2 })
+    expect(v2.read('org-a')).toBeUndefined()
+  })
+
+  it('ignores expired and corrupt entries', () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1, maxAgeMs: 1000 })
+    snap.write('org-a', { order: ['a'] }, { ts: Date.now() - 5000 })
+    expect(snap.read('org-a')).toBeUndefined()
+    localStorage.setItem('test:layout:v1:org-b', '{not json')
+    expect(snap.read('org-b')).toBeUndefined()
+  })
+})
+
+describe('usePersistedQuery', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('paints the persisted value on the first render, then revalidates and persists', async () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    snap.write('org-a', { order: ['cached'] }, { ts: Date.now() - 60_000 })
+    const net = deferred<Layout>()
+    const renders: (Layout | undefined)[] = []
+    const { result } = renderHook(
+      () => {
+        const q = usePersistedQuery({
+          queryKey: ['layout'],
+          queryFn: () => net.promise,
+          staleTime: 1000,
+          persist: { snapshot: snap, scope: 'org-a' },
+        })
+        renders.push(q.data)
+        return q
+      },
+      { wrapper: wrapperFor(newClient()) },
+    )
+    expect(renders[0]).toEqual({ order: ['cached'] })
+    await act(async () => net.resolve({ order: ['fresh'] }))
+    await waitFor(() => expect(result.current.data).toEqual({ order: ['fresh'] }))
+    expect(snap.read('org-a')?.data).toEqual({ order: ['fresh'] })
+  })
+
+  it('revalidates a seed once per load even when it is younger than staleTime', async () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    snap.write('org-a', { order: ['cached'] }, { ts: Date.now() - 1000 })
+    const queryFn = vi.fn(async () => ({ order: ['changed-elsewhere'] }))
+    const { result } = renderHook(
+      () =>
+        usePersistedQuery({
+          queryKey: ['layout'],
+          queryFn,
+          staleTime: 60_000,
+          persist: { snapshot: snap, scope: 'org-a' },
+        }),
+      { wrapper: wrapperFor(newClient()) },
+    )
+    expect(result.current.data).toEqual({ order: ['cached'] })
+    await waitFor(() => expect(result.current.data).toEqual({ order: ['changed-elsewhere'] }))
+    expect(queryFn).toHaveBeenCalledTimes(1)
+    expect(snap.read('org-a')?.data).toEqual({ order: ['changed-elsewhere'] })
+  })
+
+  it('persists the raw payload, not the selected shape, and setQueryData writes back', async () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    const qc = newClient()
+    const { result } = renderHook(
+      () =>
+        usePersistedQuery({
+          queryKey: ['layout'],
+          queryFn: async () => ({ order: ['x', 'y'] }),
+          select: (d: Layout) => d.order.length,
+          persist: { snapshot: snap, scope: 'org-a' },
+        }),
+      { wrapper: wrapperFor(qc) },
+    )
+    await waitFor(() => expect(result.current.data).toBe(2))
+    await waitFor(() => expect(snap.read('org-a')?.data).toEqual({ order: ['x', 'y'] }))
+    act(() => {
+      qc.setQueryData<Layout>(['layout'], { order: ['z'] })
+    })
+    await waitFor(() => expect(snap.read('org-a')?.data).toEqual({ order: ['z'] }))
+  })
+
+  it('does not read or write without a scope', async () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    snap.write('org-a', { order: ['cached'] })
+    const { result } = renderHook(
+      () =>
+        usePersistedQuery({
+          queryKey: ['layout'],
+          queryFn: async () => ({ order: ['fresh'] }),
+          persist: { snapshot: snap, scope: null },
+        }),
+      { wrapper: wrapperFor(newClient()) },
+    )
+    expect(result.current.data).toBeUndefined()
+    await waitFor(() => expect(result.current.data).toEqual({ order: ['fresh'] }))
+    expect(snap.read('org-a')?.data).toEqual({ order: ['cached'] })
+  })
+})

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

@@ -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.