@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/expressions/RuleNodeForm.tsx

@@ -0,0 +1,165 @@
+// RuleNodeForm: a rule step points at one saved rule and says whether the
+// step is active; the rule itself is authored elsewhere (onManageRules).
+
+import { useEffect, useState } from 'react'
+import { Button, InlineNotice, NativeSelect, Spinner, Switch } from '../../index'
+import { NodeFormFooter } from '../forms/NodeFormFooter'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import { conditionSummary } from './ruleCondition'
+
+export interface SavedRuleSummary {
+  id: string
+  name: string
+  condition?: unknown
+}
+
+export interface RuleNodeFormLabels {
+  rule: string
+  placeholder: string
+  option: string
+  loading: string
+  loadError: string
+  legacy: string
+  summary: string
+  newRule: string
+  manageRules: string
+  enabled: string
+  enabledHint: string
+  save: string
+  cancel: string
+}
+
+export const ruleNodeFormLabels = defineLabels<RuleNodeFormLabels>('RuleNodeForm', {
+  en: {
+    rule: 'Saved rule',
+    placeholder: 'Choose a saved rule',
+    option: '{name} ({id})',
+    loading: 'Loading rules',
+    loadError: 'Rules could not be loaded: {message}',
+    legacy: 'This step still has an inline condition. Pick a saved rule to replace it.',
+    summary: '{root} with {clauses, plural, one {# clause} other {# clauses}}',
+    newRule: 'New rule',
+    manageRules: 'Manage rules',
+    enabled: 'Step active',
+    enabledHint: 'Turns this step on or off for runs, whatever the rule’s own state.',
+    save: 'Save',
+    cancel: 'Cancel',
+  },
+  'pt-BR': {
+    rule: 'Regra salva',
+    placeholder: 'Escolha uma regra salva',
+    option: '{name} ({id})',
+    loading: 'Carregando regras',
+    loadError: 'Não foi possível carregar as regras: {message}',
+    legacy: 'Esta etapa ainda tem uma condição própria. Escolha uma regra salva para substituí-la.',
+    summary: '{root} com {clauses, plural, one {# cláusula} other {# cláusulas}}',
+    newRule: 'Nova regra',
+    manageRules: 'Gerenciar regras',
+    enabled: 'Etapa ativa',
+    enabledHint: 'Liga ou desliga esta etapa nas execuções, qualquer que seja o estado da regra.',
+    save: 'Salvar',
+    cancel: 'Cancelar',
+  },
+  es: {
+    rule: 'Regla guardada',
+    placeholder: 'Elija una regla guardada',
+    option: '{name} ({id})',
+    loading: 'Cargando reglas',
+    loadError: 'No se pudieron cargar las reglas: {message}',
+    legacy: 'Este paso aún tiene una condición propia. Elija una regla guardada para reemplazarla.',
+    summary: '{root} con {clauses, plural, one {# cláusula} other {# cláusulas}}',
+    newRule: 'Nueva regla',
+    manageRules: 'Gestionar reglas',
+    enabled: 'Paso activo',
+    enabledHint: 'Activa o desactiva este paso en las ejecuciones, sea cual sea el estado de la regla.',
+    save: 'Guardar',
+    cancel: 'Cancelar',
+  },
+})
+
+export const defaultRuleNodeFormLabels: RuleNodeFormLabels = ruleNodeFormLabels.bundles.en
+
+export interface RuleNodeFormProps {
+  value: { ruleId?: string; enabled?: boolean; [key: string]: unknown }
+  rules?: SavedRuleSummary[]
+  loadRules?: () => Promise<SavedRuleSummary[]>
+  onManageRules: () => void
+  onSave: (value: { kind: 'rule'; ruleId?: string; enabled: boolean }) => void
+  onCancel: () => void
+  labels?: Partial<RuleNodeFormLabels>
+}
+
+const LEGACY_KEYS = ['condition', 'conditions', 'expression', 'rule']
+
+export function RuleNodeForm({ value, rules, loadRules, onManageRules, onSave, onCancel, labels }: RuleNodeFormProps) {
+  const l = useLabels(ruleNodeFormLabels, labels)
+  const { locale } = useFlowLocale()
+  const [loaded, setLoaded] = useState<{ state: 'ready'; list: SavedRuleSummary[] } | { state: 'loading' } | { state: 'error'; message: string }>(() => (rules ? { state: 'ready', list: rules } : loadRules ? { state: 'loading' } : { state: 'ready', list: [] }))
+  const [ruleId, setRuleId] = useState(value.ruleId ?? '')
+  const [enabled, setEnabled] = useState(value.enabled !== false)
+
+  useEffect(() => {
+    if (rules) {
+      setLoaded({ state: 'ready', list: rules })
+      return
+    }
+    if (!loadRules) return
+    let live = true
+    setLoaded({ state: 'loading' })
+    loadRules().then(
+      (list) => {
+        if (live) setLoaded({ state: 'ready', list })
+      },
+      (e: unknown) => {
+        if (live) setLoaded({ state: 'error', message: e instanceof Error ? e.message : String(e) })
+      },
+    )
+    return () => {
+      live = false
+    }
+  }, [rules, loadRules])
+
+  const list = loaded.state === 'ready' ? loaded.list : []
+  const legacy = !value.ruleId && LEGACY_KEYS.some((k) => k in value)
+  const chosen = list.find((r) => r.id === ruleId)
+  const options = [{ value: '', label: l.placeholder }, ...list.map((r) => ({ value: r.id, label: fill(l.option, { name: r.name, id: r.id }, locale) })), ...(ruleId && !chosen ? [{ value: ruleId, label: ruleId }] : [])]
+  const summary = chosen ? conditionSummary(chosen.condition) : null
+
+  return (
+    <div className="ty-node-form ty-rule-node-form">
+      {legacy ? (
+        <InlineNotice tone="warning" urgency="polite">
+          {l.legacy}
+        </InlineNotice>
+      ) : null}
+      {loaded.state === 'error' ? (
+        <InlineNotice tone="danger" urgency="assertive">
+          {fill(l.loadError, { message: loaded.message }, locale)}
+        </InlineNotice>
+      ) : null}
+      {loaded.state === 'loading' ? (
+        <div className="ty-rule-node-form__loading" aria-busy="true">
+          <Spinner size="small" label={l.loading} showLabel />
+        </div>
+      ) : (
+        <NativeSelect label={l.rule} options={options} value={ruleId} onChange={setRuleId} />
+      )}
+      {chosen ? (
+        <div className="ty-rule-node-form__summary">
+          <p className="ty-rule-node-form__summary-name">{chosen.name}</p>
+          {summary ? <p className="ty-rule-node-form__summary-line">{fill(l.summary, { root: summary.root, clauses: summary.clauses }, locale)}</p> : null}
+        </div>
+      ) : null}
+      <Button variant="secondary" onPress={onManageRules}>
+        {loaded.state === 'ready' && list.length === 0 ? l.newRule : l.manageRules}
+      </Button>
+      <Switch label={l.enabled} description={l.enabledHint} isSelected={enabled} onChange={setEnabled} />
+      <NodeFormFooter
+        onSave={() => onSave({ kind: 'rule', ...(ruleId ? { ruleId } : {}), enabled })}
+        onCancel={onCancel}
+        saveDisabled={loaded.state === 'loading' && !value.ruleId}
+        labels={{ save: l.save, cancel: l.cancel }}
+      />
+    </div>
+  )
+}

package/src/flow/expressions/SimulationNodeForm.tsx

@@ -0,0 +1,175 @@
+// SimulationNodeForm: a repeated-sampling step (how many runs, how many steps
+// per run, the starting state, the transition) plus the values tracked per
+// step. Each expression field always has a root operation: bare values are
+// wrapped in a "first non-empty value" operation with that single candidate.
+
+import { useState } from 'react'
+import { TextArea } from '../../index'
+import { NodeFormFooter } from '../forms/NodeFormFooter'
+import { defineLabels, useLabels } from '../internal/labels'
+import { ExpressionField, type ExpressionFieldLabels } from './ExpressionField'
+import { FLOW_INPUTS_REF, isOperation, prettyJson, type ExpressionCatalog, type ExpressionNode, type OperationNode } from './model'
+
+export type SimulationField = 'runs' | 'steps' | 'initialState' | 'step'
+export const SIMULATION_FIELDS: readonly SimulationField[] = ['runs', 'steps', 'initialState', 'step']
+
+/** Operation used to give a bare value a root operation (same meaning). */
+export const FIRST_NON_EMPTY = 'coalesce'
+
+/** References the transition may use besides flow inputs and ancestors. */
+export const SIMULATION_STEP_REFS = ['state', 'run_index', 'step_index'] as const
+
+export interface SimulationNodeConfig {
+  kind: 'simulation'
+  runs: ExpressionNode
+  steps: ExpressionNode
+  initialState: ExpressionNode
+  step: ExpressionNode
+  tracking: string[]
+  [key: string]: unknown
+}
+
+export interface SimulationNodeFormLabels {
+  runs: string
+  runsHint: string
+  steps: string
+  stepsHint: string
+  initialState: string
+  initialStateHint: string
+  step: string
+  stepHint: string
+  tracking: string
+  trackingHint: string
+  trackingInvalid: string
+  field: Partial<ExpressionFieldLabels>
+  save: string
+  cancel: string
+}
+
+export const simulationNodeFormLabels = defineLabels<SimulationNodeFormLabels>('SimulationNodeForm', {
+  en: {
+    runs: 'Number of runs',
+    runsHint: 'How many independent runs to sample.',
+    steps: 'Steps per run',
+    stepsHint: 'How many steps each run takes.',
+    initialState: 'Initial state',
+    initialStateHint: 'The state every run starts from.',
+    step: 'Step transition',
+    stepHint: 'The next state; may use the current state, the run index and the step index.',
+    tracking: 'Tracked values',
+    trackingHint: 'A list (structured text) of the values recorded at each step.',
+    trackingInvalid: 'Tracked values must be a list.',
+    field: {},
+    save: 'Save',
+    cancel: 'Cancel',
+  },
+  'pt-BR': {
+    runs: 'Número de execuções',
+    runsHint: 'Quantas execuções independentes amostrar.',
+    steps: 'Passos por execução',
+    stepsHint: 'Quantos passos cada execução dá.',
+    initialState: 'Estado inicial',
+    initialStateHint: 'O estado de onde toda execução parte.',
+    step: 'Transição do passo',
+    stepHint: 'O próximo estado; pode usar o estado atual, o índice da execução e o índice do passo.',
+    tracking: 'Valores acompanhados',
+    trackingHint: 'Uma lista (texto estruturado) dos valores registrados a cada passo.',
+    trackingInvalid: 'Os valores acompanhados precisam ser uma lista.',
+    field: {},
+    save: 'Salvar',
+    cancel: 'Cancelar',
+  },
+  es: {
+    runs: 'Número de ejecuciones',
+    runsHint: 'Cuántas ejecuciones independientes muestrear.',
+    steps: 'Pasos por ejecución',
+    stepsHint: 'Cuántos pasos da cada ejecución.',
+    initialState: 'Estado inicial',
+    initialStateHint: 'El estado desde el que parte cada ejecución.',
+    step: 'Transición del paso',
+    stepHint: 'El siguiente estado; puede usar el estado actual, el índice de ejecución y el índice de paso.',
+    tracking: 'Valores seguidos',
+    trackingHint: 'Una lista (texto estructurado) de los valores registrados en cada paso.',
+    trackingInvalid: 'Los valores seguidos deben ser una lista.',
+    field: {},
+    save: 'Guardar',
+    cancel: 'Cancelar',
+  },
+})
+
+export const defaultSimulationNodeFormLabels: SimulationNodeFormLabels = simulationNodeFormLabels.bundles.en
+
+/** A tree for the visual builder: operations as they are, anything else wrapped. */
+export function seedSimulationField(value: unknown): OperationNode {
+  if (isOperation(value)) return value
+  const candidate = value && typeof value === 'object' && !Array.isArray(value) && ('ref' in value || 'value' in value) ? value : { value: value ?? null }
+  return { operation: FIRST_NON_EMPTY, values: [candidate] }
+}
+
+export interface SimulationNodeFormProps {
+  /** Each expression field is an expression tree or a bare literal. */
+  value: Partial<Record<SimulationField, unknown>> & { tracking?: string[] } & Record<string, unknown>
+  references?: string[]
+  defaults?: Partial<Record<SimulationField, unknown>>
+  catalog?: ExpressionCatalog
+  onSave: (value: SimulationNodeConfig) => void
+  onCancel: () => void
+  labels?: Partial<SimulationNodeFormLabels>
+}
+
+export function SimulationNodeForm({ value, references = [], defaults = {}, catalog, onSave, onCancel, labels }: SimulationNodeFormProps) {
+  const l = useLabels(simulationNodeFormLabels, labels)
+  const [fields, setFields] = useState<Record<SimulationField, ExpressionNode>>(() => {
+    const out = {} as Record<SimulationField, ExpressionNode>
+    for (const f of SIMULATION_FIELDS) out[f] = seedSimulationField(value[f] !== undefined ? value[f] : (defaults[f] ?? null))
+    return out
+  })
+  const [trackingText, setTrackingText] = useState(() => prettyJson(Array.isArray(value.tracking) ? value.tracking : []))
+  const [tracking, setTracking] = useState<string[]>(() => (Array.isArray(value.tracking) ? value.tracking : []))
+  const [trackingError, setTrackingError] = useState(false)
+  const baseRefs = [FLOW_INPUTS_REF, ...references.filter((r) => r !== FLOW_INPUTS_REF)]
+
+  const save = () => onSave({ ...value, kind: 'simulation', ...fields, tracking })
+
+  return (
+    <div className="ty-node-form ty-expr-form" data-form="simulation">
+      {SIMULATION_FIELDS.map((f) => (
+        <ExpressionField
+          key={f}
+          label={l[f]}
+          hint={l[`${f}Hint` as const]}
+          value={fields[f]}
+          onChange={(n) => setFields((prev) => ({ ...prev, [f]: n }))}
+          references={f === 'step' ? [...baseRefs, ...SIMULATION_STEP_REFS] : baseRefs}
+          acceptLeaves
+          labels={l.field}
+          {...(catalog ? { catalog } : {})}
+        />
+      ))}
+      <TextArea
+        className="ty-expr-form__code"
+        label={l.tracking}
+        hint={l.trackingHint}
+        monospace
+        rows={3}
+        value={trackingText}
+        onChange={(t) => {
+          setTrackingText(t)
+          try {
+            const v = JSON.parse(t) as unknown
+            if (Array.isArray(v)) {
+              setTracking(v.map(String))
+              setTrackingError(false)
+              return
+            }
+          } catch {
+            /* fall through to the error */
+          }
+          setTrackingError(true)
+        }}
+        {...(trackingError ? { errorMessage: l.trackingInvalid } : {})}
+      />
+      <NodeFormFooter onSave={save} onCancel={onCancel} labels={{ save: l.save, cancel: l.cancel }} />
+    </div>
+  )
+}

package/src/flow/expressions/TraceTree.test.tsx

@@ -0,0 +1,120 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { TympanProvider } from '../../index'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { DryRunFailure, runDryRun, traceReportFromWire, type TraceReport } from './trace'
+import { TraceTree } from './TraceTree'
+
+const report: TraceReport = {
+  truncated: false,
+  frameCount: 5,
+  frameLimit: 500,
+  trace: {
+    kind: 'operation',
+    label: 'count',
+    result: 3,
+    children: [
+      {
+        kind: 'operation',
+        label: 'filter',
+        args: { order: 'asc', limit: 10 },
+        result: [1, 2, 3],
+        children: [{ kind: 'ref', label: 'air.readings', result: Array.from({ length: 12 }, (_, i) => i) }],
+      },
+    ],
+  },
+}
+
+const row = (name: RegExp) => screen.getByRole('row', { name })
+
+describe('TraceTree', () => {
+  it('shows depth 0 and 1 and keeps depth-2 children collapsed', () => {
+    render(<TraceTree report={report} />)
+    expect(row(/^count/)).toBeInTheDocument()
+    expect(row(/^filter/)).toHaveAttribute('aria-expanded', 'false')
+    expect(screen.queryByRole('row', { name: /^air\.readings/ })).toBeNull()
+    expect(row(/^filter/)).toHaveAttribute('aria-level', '2')
+  })
+
+  it('expands a collapsed row with Right Arrow', async () => {
+    render(<TraceTree report={report} />)
+    await userEvent.tab()
+    await userEvent.keyboard('{ArrowDown}')
+    expect(row(/^filter/)).toHaveFocus()
+    await userEvent.keyboard('{ArrowRight}')
+    expect(row(/^air\.readings/)).toBeInTheDocument()
+    await userEvent.keyboard('{ArrowLeft}')
+    expect(screen.queryByRole('row', { name: /^air\.readings/ })).toBeNull()
+  })
+
+  it('mirrors Left and Right in a right-to-left locale', async () => {
+    render(
+      <TympanProvider locale="ar">
+        <div dir="rtl">
+          <TraceTree report={report} />
+        </div>
+      </TympanProvider>,
+    )
+    await userEvent.tab()
+    await userEvent.keyboard('{ArrowDown}{ArrowLeft}')
+    expect(screen.getByRole('row', { name: /^air\.readings/ })).toBeInTheDocument()
+  })
+
+  it('shows the full value beneath the row when its preview is activated, and on Enter', async () => {
+    render(<TraceTree report={report} />)
+    await userEvent.click(screen.getByRole('button', { name: /Result of filter/ }))
+    expect(screen.getByRole('region', { name: 'Result of filter' })).toHaveTextContent('1')
+    await userEvent.click(screen.getByRole('button', { name: /Result of filter/ }))
+    expect(screen.queryByRole('region', { name: 'Result of filter' })).toBeNull()
+    row(/^count/).focus()
+    await userEvent.keyboard('{Enter}')
+    expect(screen.getByRole('region', { name: 'Result of count' })).toHaveTextContent('3')
+  })
+
+  it('shows the truncation notice with both counts only when truncated', () => {
+    const { rerender } = render(<TraceTree report={report} />)
+    expect(screen.queryByText(/stopped recording/)).toBeNull()
+    rerender(<TraceTree report={{ ...report, truncated: true, frameCount: 500, frameLimit: 500 }} />)
+    expect(screen.getByText(/stopped recording after 500 of 500 frames/)).toBeInTheDocument()
+  })
+
+  it('labels a reference leaf with the reference tag and summarises a 12-item list', async () => {
+    render(<TraceTree report={report} defaultExpandDepth={3} />)
+    const leaf = row(/^air\.readings/)
+    expect(leaf).toHaveTextContent('reference')
+    expect(leaf).toHaveAccessibleName('air.readings, result: list of 12 items')
+    expect(row(/^filter/)).toHaveTextContent('order: asc, limit: 10')
+  })
+
+  it('rejects the dry run with the HTTP status and server text', async () => {
+    const fetchImpl = vi.fn(async () => new Response('boom', { status: 500 }))
+    await expect(runDryRun('/dry-run', { config: {} }, fetchImpl as unknown as typeof fetch)).rejects.toMatchObject({ status: 500, message: 'boom' })
+    await expect(runDryRun('/dry-run', { config: {} }, (async () => { throw new Error('offline') }) as unknown as typeof fetch)).rejects.toBeInstanceOf(DryRunFailure)
+    const ok = vi.fn(async () => new Response(JSON.stringify({ result: 1, trace: { trace: { kind: 'value', label: '1', result: 1 }, truncated: false, frame_count: 1, frame_limit: 9 } }), { status: 200 }))
+    const res = await runDryRun('/dry-run', { config: { kind: 'compute' } }, ok as unknown as typeof fetch)
+    expect(res.trace.frameLimit).toBe(9)
+    expect(JSON.parse((ok.mock.calls[0] as unknown as [string, RequestInit])[1].body as string)).toEqual({ config: { kind: 'compute' } })
+  })
+
+  it('maps snake-case wire reports', () => {
+    expect(traceReportFromWire({ trace: { kind: 'reference', label: 'x', child_spans: [] }, is_truncated: true, frame_count: 2, frame_limit: 3 })).toEqual({
+      trace: { kind: 'ref', label: 'x' },
+      truncated: true,
+      frameCount: 2,
+      frameLimit: 3,
+    })
+  })
+
+  it('has no axe violations and keeps the rail, logical indents and forced colours', async () => {
+    const { container } = render(<TraceTree report={report} />)
+    await expectNoAxeViolations(container)
+    const css = cssOf('flow/expressions/expressions.css')
+    expect(css).toMatch(/\.ty-trace__row\s*\{[^}]*padding-inline-start/)
+    expect(css).toMatch(/\.ty-trace__line\s*\{[^}]*border-inline-start/)
+    expect(css).toMatch(/:dir\(rtl\) \.ty-rule-editor__chevron,\s*:dir\(rtl\) \.ty-trace__chevron-icon\s*\{\s*scale: -1 1/)
+    expect(mediaBlock(css, /\(prefers-reduced-motion: reduce\)/)).toMatch(/transition:\s*none/)
+    expect(mediaBlock(css, /\(forced-colors: active\)/)).toMatch(/ty-trace__line/)
+  })
+})

package/src/flow/expressions/TraceTree.tsx

@@ -0,0 +1,210 @@
+// TraceTree: how an expression evaluated, one row per evaluated sub-expression
+// (APG Tree View on React Aria Tree). Enter or the preview button toggles the
+// full result under a row; results are clamped by lines, never cut.
+
+import { useMemo, useState, type ReactNode } from 'react'
+import { Button as AriaButton, Tree, TreeItem, TreeItemContent, type Key } from 'react-aria-components'
+import { ChevronRight } from 'lucide-react'
+import { InlineNotice, Tag } from '../../index'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { TraceReport, TraceSpan } from './trace'
+
+export interface TraceTreeLabels {
+  tree: string
+  expand: string
+  collapse: string
+  viewResult: string
+  resultOf: string
+  rowName: string
+  truncated: string
+  reference: string
+  value: string
+  list: string
+  object: string
+  absent: string
+}
+
+export const traceTreeLabels = defineLabels<TraceTreeLabels>('TraceTree', {
+  en: {
+    tree: 'Evaluation trace',
+    expand: 'Expand {label}',
+    collapse: 'Collapse {label}',
+    viewResult: 'Result of {label}: {preview}',
+    resultOf: 'Result of {label}',
+    rowName: '{label}, result: {preview}',
+    truncated: 'The engine stopped recording after {frames, number} of {limit, number} frames. The final result is still correct.',
+    reference: 'reference',
+    value: 'value',
+    list: '{count, plural, one {list of # item} other {list of # items}}',
+    object: '{count, plural, one {object with # key} other {object with # keys}}',
+    absent: 'no result recorded',
+  },
+  'pt-BR': {
+    tree: 'Rastro da avaliação',
+    expand: 'Expandir {label}',
+    collapse: 'Recolher {label}',
+    viewResult: 'Resultado de {label}: {preview}',
+    resultOf: 'Resultado de {label}',
+    rowName: '{label}, resultado: {preview}',
+    truncated: 'O motor parou de registrar após {frames, number} de {limit, number} quadros. O resultado final continua correto.',
+    reference: 'referência',
+    value: 'valor',
+    list: '{count, plural, one {lista de # item} other {lista de # itens}}',
+    object: '{count, plural, one {objeto com # chave} other {objeto com # chaves}}',
+    absent: 'sem resultado registrado',
+  },
+  es: {
+    tree: 'Traza de la evaluación',
+    expand: 'Expandir {label}',
+    collapse: 'Contraer {label}',
+    viewResult: 'Resultado de {label}: {preview}',
+    resultOf: 'Resultado de {label}',
+    rowName: '{label}, resultado: {preview}',
+    truncated: 'El motor dejó de registrar tras {frames, number} de {limit, number} marcos. El resultado final sigue siendo correcto.',
+    reference: 'referencia',
+    value: 'valor',
+    list: '{count, plural, one {lista de # elemento} other {lista de # elementos}}',
+    object: '{count, plural, one {objeto con # clave} other {objeto con # claves}}',
+    absent: 'sin resultado registrado',
+  },
+})
+export const defaultTraceTreeLabels: TraceTreeLabels = traceTreeLabels.bundles.en
+
+export interface TraceTreeProps {
+  report: TraceReport
+  /** Rows shallower than this are visible when the tree opens (2: root and its children). */
+  defaultExpandDepth?: number
+  labels?: Partial<TraceTreeLabels>
+  className?: string
+}
+
+interface Row {
+  id: string
+  depth: number
+  span: TraceSpan
+  children: Row[]
+}
+
+function toRows(span: TraceSpan, id: string, depth: number): Row {
+  return { id, depth, span, children: (span.children ?? []).map((c, i) => toRows(c, `${id}.${i}`, depth + 1)) }
+}
+
+function walk(row: Row, visit: (r: Row) => void) {
+  visit(row)
+  row.children.forEach((c) => walk(c, visit))
+}
+
+/** One-line summary of a result (the full value is shown on request). */
+export function previewResult(value: unknown, l: TraceTreeLabels, locale: string, present = true): string {
+  if (!present) return l.absent
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return fill(l.list, { count: value.length }, locale)
+  if (typeof value === 'object') return fill(l.object, { count: Object.keys(value as object).length }, locale)
+  if (typeof value === 'number') return new Intl.NumberFormat(locale).format(value)
+  if (typeof value === 'string') return JSON.stringify(value)
+  return String(value)
+}
+
+function argSummary(args: Record<string, unknown> | undefined): string {
+  if (!args) return ''
+  return Object.entries(args)
+    .filter(([, v]) => v === null || ['string', 'number', 'boolean'].includes(typeof v))
+    .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+    .join(', ')
+}
+
+export function TraceTree({ report, defaultExpandDepth = 2, labels, className }: TraceTreeProps) {
+  const l = useLabels(traceTreeLabels, labels)
+  const { locale } = useFlowLocale()
+  const root = useMemo(() => toRows(report.trace, '0', 0), [report.trace])
+  const [expanded, setExpanded] = useState<Set<Key>>(() => {
+    const open = new Set<Key>()
+    // A row is open when its children are shallower than the expand depth.
+    walk(root, (r) => {
+      if (r.children.length && r.depth + 1 < defaultExpandDepth) open.add(r.id)
+    })
+    return open
+  })
+  const [details, setDetails] = useState<Set<string>>(new Set())
+  const toggleDetail = (id: string) =>
+    setDetails((prev) => {
+      const next = new Set(prev)
+      if (next.has(id)) next.delete(id)
+      else next.add(id)
+      return next
+    })
+
+  const render = (row: Row): ReactNode => {
+    const { span } = row
+    const present = 'result' in span
+    const preview = previewResult(span.result, l, locale, present)
+    const open = details.has(row.id)
+    const detailId = `ty-trace-${row.id}`
+    return (
+      <TreeItem
+        key={row.id}
+        id={row.id}
+        textValue={span.label}
+        aria-label={fill(l.rowName, { label: span.label, preview }, locale)}
+        className="ty-trace__row"
+        style={{ ['--ty-trace-level' as string]: row.depth + 1 }}
+        onAction={() => toggleDetail(row.id)}
+      >
+        <TreeItemContent>
+          {({ hasChildItems, isExpanded }) => (
+            <>
+              <div className="ty-trace__line">
+                {hasChildItems ? (
+                  <AriaButton slot="chevron" className="ty-trace__chevron" aria-label={fill(isExpanded ? l.collapse : l.expand, { label: span.label }, locale)}>
+                    <ChevronRight className="ty-trace__chevron-icon" aria-hidden="true" focusable="false" />
+                  </AriaButton>
+                ) : (
+                  <span className="ty-trace__spacer" aria-hidden="true" />
+                )}
+                {span.kind === 'operation' ? (
+                  <code className="ty-trace__op" dir="ltr">
+                    {span.label}
+                  </code>
+                ) : (
+                  <>
+                    <Tag size="small">{span.kind === 'ref' ? l.reference : l.value}</Tag>
+                    <code className="ty-trace__op" dir="ltr">
+                      {span.label}
+                    </code>
+                  </>
+                )}
+                {span.args ? (
+                  <span className="ty-trace__args" dir="ltr">
+                    {argSummary(span.args)}
+                  </span>
+                ) : null}
+                <AriaButton className="ty-trace__preview" aria-expanded={open} aria-controls={open ? detailId : undefined} aria-label={fill(l.viewResult, { label: span.label, preview }, locale)} onPress={() => toggleDetail(row.id)}>
+                  {preview}
+                </AriaButton>
+              </div>
+              {open ? (
+                <pre id={detailId} className="ty-trace__detail" role="region" aria-label={fill(l.resultOf, { label: span.label }, locale)} dir="ltr" tabIndex={0}>
+                  {present ? JSON.stringify(span.result, null, 2) : l.absent}
+                </pre>
+              ) : null}
+            </>
+          )}
+        </TreeItemContent>
+        {row.children.map(render)}
+      </TreeItem>
+    )
+  }
+
+  return (
+    <div className={['ty-trace', className].filter(Boolean).join(' ')}>
+      {report.truncated ? (
+        <InlineNotice tone="warning" urgency="none">
+          {fill(l.truncated, { frames: report.frameCount, limit: report.frameLimit }, locale)}
+        </InlineNotice>
+      ) : null}
+      <Tree aria-label={l.tree} className="ty-trace__tree" expandedKeys={expanded} onExpandedChange={(keys) => setExpanded(new Set(keys))}>
+        {render(root)}
+      </Tree>
+    </div>
+  )
+}