@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/flags/flags.test.tsx

@@ -0,0 +1,140 @@
+import { render, screen, waitFor } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { TympanProvider } from '../internal/provider'
+import { expectNoAxeViolations } from '../../test/axe'
+import { cssOf } from '../../test/css'
+import { renderRtl } from '../../test/rtl'
+import { FLAG_CODES, Flag, flagName, isFlagCode, loadFlagSvg, normalizeFlagCode } from './index'
+
+const loaded = (el: Element) => waitFor(() => expect(el).toHaveAttribute('data-loaded'))
+
+describe('flag codes', () => {
+  it('covers countries, UK and Spanish subdivisions and organisations in both aspects', async () => {
+    expect(FLAG_CODES.length).toBeGreaterThanOrEqual(250)
+    for (const code of ['br', 'jp', 'gb-sct', 'gb-wls', 'es-ct', 'eu', 'un', 'asean', 'xx']) expect(isFlagCode(code), code).toBe(true)
+    const [wide, square] = await Promise.all([loadFlagSvg('gb-sct', '4x3'), loadFlagSvg('gb-sct', '1x1')])
+    expect(wide).toMatch(/viewBox="0 0 640 480"/)
+    expect(square).toMatch(/viewBox="0 0 512 512"/)
+    expect(await loadFlagSvg('zz-unknown')).toBeNull()
+  })
+
+  it('keeps internal ids apart between aspects', async () => {
+    const [wide, square] = await Promise.all([loadFlagSvg('us', '4x3'), loadFlagSvg('us', '1x1')])
+    expect(wide).toContain('id="ty-flag-4x3-us-a"')
+    expect(square).toContain('id="ty-flag-1x1-us-a"')
+    expect(wide).not.toContain('id="flag-icons-us"')
+  })
+
+  it('normalises codes', () => {
+    expect(normalizeFlagCode(' GB_SCT ')).toBe('gb-sct')
+  })
+})
+
+describe('flagName', () => {
+  it('names countries in the reader locale (Intl.DisplayNames)', () => {
+    expect(flagName('BR', 'en')).toBe('Brazil')
+    expect(flagName('br', 'pt-BR')).toBe('Brasil')
+    expect(flagName('de', 'ja')).toBe('ドイツ')
+    expect(flagName('eu', 'es')).toBe('Unión Europea')
+    expect(flagName('sh-ta', 'en')).toBe('Tristan da Cunha')
+  })
+
+  it('names subdivisions and organisations CLDR does not know', () => {
+    expect(flagName('gb-sct', 'en')).toBe('Scotland')
+    expect(flagName('gb-sct', 'pt-BR')).toBe('Escócia')
+    expect(flagName('es-ct', 'es')).toBe('Cataluña')
+    expect(flagName('es-ct', 'ja')).toBe('Catalonia')
+  })
+
+  it('falls back to the code', () => {
+    expect(flagName('qq', 'en')).toBe('QQ')
+    expect(flagName('xx-yy', 'en')).toBe('XX-YY')
+  })
+})
+
+describe('Flag', () => {
+  it('is an image named after the region in the active locale', async () => {
+    render(
+      <TympanProvider locale="pt-BR">
+        <Flag code="JP" />
+      </TympanProvider>,
+    )
+    const flag = screen.getByRole('img', { name: 'Japão' })
+    await loaded(flag)
+    const img = flag.querySelector('img')!
+    expect(img).toHaveAttribute('alt', '')
+    expect(img.getAttribute('src')).toMatch(/^data:image\/svg\+xml/)
+  })
+
+  it('names the flag in English, Japanese and Arabic', () => {
+    for (const [locale, name] of [
+      ['en', 'Germany'],
+      ['ja', 'ドイツ'],
+      ['ar', 'ألمانيا'],
+    ] as const) {
+      const { unmount } = render(
+        <TympanProvider locale={locale}>
+          <Flag code="de" />
+        </TympanProvider>,
+      )
+      expect(screen.getByRole('img', { name })).toBeInTheDocument()
+      unmount()
+    }
+  })
+
+  it('takes a label, and hides itself when decorative', () => {
+    const { container } = render(
+      <>
+        <Flag code="br" label="Brazil (host)" />
+        <Flag code="br" decorative />
+      </>,
+    )
+    expect(screen.getByRole('img', { name: 'Brazil (host)' })).toBeInTheDocument()
+    expect(container.querySelectorAll('.ty-flag')[1]).toHaveAttribute('aria-hidden', 'true')
+    expect(screen.getAllByRole('img')).toHaveLength(1)
+  })
+
+  it('draws square art for 1x1 and circle, and the unknown flag for an unknown code', async () => {
+    const { container } = render(
+      <>
+        <Flag code="ca" aspect="1x1" />
+        <Flag code="ca" aspect="circle" size="small" />
+        <Flag code="qq" />
+      </>,
+    )
+    const [square, circle, unknown] = [...container.querySelectorAll('.ty-flag')]
+    await Promise.all([loaded(square!), loaded(circle!), loaded(unknown!)])
+    expect(decodeURIComponent(square!.querySelector('img')!.src)).toContain('viewBox="0 0 512 512"')
+    expect(circle).toHaveAttribute('data-aspect', 'circle')
+    expect(unknown).toHaveAttribute('aria-label', 'QQ')
+    expect(decodeURIComponent(unknown!.querySelector('img')!.src)).toContain('data-flag="xx"')
+    const css = cssOf('flags/Flag.css')
+    expect(css).toMatch(/\[data-aspect='circle'\]\s*\{\s*border-radius:\s*50%/)
+  })
+
+  it('has no axe violations', async () => {
+    const { container } = render(
+      <div>
+        <Flag code="br" />
+        <Flag code="gb-sct" aspect="1x1" />
+        <Flag code="eu" aspect="circle" />
+        <span>
+          <Flag code="jp" decorative /> Japan
+        </span>
+      </div>,
+    )
+    await Promise.all([...container.querySelectorAll('.ty-flag')].map(loaded))
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('Flag in right-to-left (ar)', () => {
+  it('names the region in Arabic, does not mirror and passes axe', async () => {
+    const { container } = renderRtl(<Flag code="sa" />)
+    const flag = screen.getByRole('img', { name: 'المملكة العربية السعودية' })
+    await loaded(flag)
+    expect(flag.className).not.toMatch(/mirror/)
+    expect(cssOf('flags/Flag.css')).not.toMatch(/scaleX\(-1\)/)
+    await expectNoAxeViolations(container)
+  })
+})

package/src/flags/index.ts

@@ -0,0 +1,7 @@
+// @datatechsolutions/tympan/flags (FSL-1.1-ALv2): country, territory and
+// regional flags from flag-icons (MIT), one lazily loaded chunk per flag.
+// Flags stand for places, never for languages.
+export { Flag, type FlagProps, type FlagAspect, type FlagSize } from './Flag'
+export { flagName, normalizeFlagCode } from './names'
+export { loadFlagSvg, isFlagCode, type FlagArt } from './loadFlag'
+export { FLAG_CODES, FLAG_ICONS_VERSION, type FlagCode } from './art'

package/src/flags/loadFlag.ts

@@ -0,0 +1,29 @@
+import { FLAG_CODES, loaders1by1, loaders4by3, type FlagCode } from './art'
+
+export type FlagArt = '4x3' | '1x1'
+
+const known = new Set<string>(FLAG_CODES)
+const cache = new Map<string, string>()
+
+export function isFlagCode(code: string): code is FlagCode {
+  return known.has(code)
+}
+
+/** Cached SVG of a flag, if it has been loaded already. */
+export function cachedFlagSvg(code: FlagCode, art: FlagArt): string | undefined {
+  return cache.get(`${art}/${code}`)
+}
+
+/**
+ * Loads one flag's SVG (its own chunk, so a page pays only for the flags it
+ * shows). Unknown codes resolve to null.
+ */
+export async function loadFlagSvg(code: string, art: FlagArt = '4x3'): Promise<string | null> {
+  if (!isFlagCode(code)) return null
+  const key = `${art}/${code}`
+  const hit = cache.get(key)
+  if (hit) return hit
+  const mod = await (art === '1x1' ? loaders1by1 : loaders4by3)[code]()
+  cache.set(key, mod.default)
+  return mod.default
+}

package/src/flags/names.ts

@@ -0,0 +1,65 @@
+// Accessible names of flags. Countries and territories come from
+// Intl.DisplayNames in the reader's locale; the few flags CLDR has no region
+// for (UK nations, Spanish communities, regional organisations) carry their
+// own names in English, Portuguese and Spanish, and English elsewhere.
+
+/** flag-icons codes that CLDR knows under another region code. */
+const REGION_ALIAS: Record<string, string> = { 'sh-ac': 'AC', 'sh-hl': 'SH', 'sh-ta': 'TA', xx: 'ZZ' }
+
+type Names = { en: string; pt?: string; es?: string }
+const OWN_NAMES: Record<string, Names> = {
+  'gb-eng': { en: 'England', pt: 'Inglaterra', es: 'Inglaterra' },
+  'gb-nir': { en: 'Northern Ireland', pt: 'Irlanda do Norte', es: 'Irlanda del Norte' },
+  'gb-sct': { en: 'Scotland', pt: 'Escócia', es: 'Escocia' },
+  'gb-wls': { en: 'Wales', pt: 'País de Gales', es: 'Gales' },
+  'es-ct': { en: 'Catalonia', pt: 'Catalunha', es: 'Cataluña' },
+  'es-ga': { en: 'Galicia', pt: 'Galiza', es: 'Galicia' },
+  'es-pv': { en: 'Basque Country', pt: 'País Basco', es: 'País Vasco' },
+  arab: { en: 'Arab League', pt: 'Liga Árabe', es: 'Liga Árabe' },
+  asean: { en: 'ASEAN' },
+  cefta: { en: 'CEFTA' },
+  eac: { en: 'East African Community', pt: 'Comunidade da África Oriental', es: 'Comunidad de África Oriental' },
+  pc: { en: 'Pacific Community', pt: 'Comunidade do Pacífico', es: 'Comunidad del Pacífico' },
+}
+
+/** Lower-case, hyphenated flag key: `BR` → `br`, `GB_SCT` → `gb-sct`. */
+export function normalizeFlagCode(code: string): string {
+  return code.trim().toLowerCase().replace(/_/g, '-')
+}
+
+const displayNames = new Map<string, Intl.DisplayNames | null>()
+function regionNames(locale: string): Intl.DisplayNames | null {
+  if (!displayNames.has(locale)) {
+    let names: Intl.DisplayNames | null = null
+    try {
+      names = new Intl.DisplayNames([locale, 'en'], { type: 'region', fallback: 'none' })
+    } catch {
+      names = null
+    }
+    displayNames.set(locale, names)
+  }
+  return displayNames.get(locale)!
+}
+
+/**
+ * The name of the country, territory or region a flag stands for, in
+ * `locale`; the code in upper case when no name is known.
+ */
+export function flagName(code: string, locale = 'en'): string {
+  const key = normalizeFlagCode(code)
+  const own = OWN_NAMES[key]
+  if (own) {
+    const lang = locale.toLowerCase().split('-')[0] as 'pt' | 'es'
+    return own[lang] ?? own.en
+  }
+  const region = REGION_ALIAS[key] ?? (/^[a-z]{2}$/.test(key) ? key.toUpperCase() : null)
+  if (region) {
+    try {
+      const name = regionNames(locale)?.of(region)
+      if (name && name !== region) return name
+    } catch {
+      /* not a valid region subtag */
+    }
+  }
+  return key.toUpperCase()
+}

package/src/flow/CLEAN-ROOM.md

@@ -0,0 +1,110 @@
+# Clean-room record
+
+> **Licence note (2026-09-26).** This record was written when the packages
+> were planned as MIT. They are published under FSL-1.1-ALv2 (see `LICENSE`
+> at the repository root); the clean-room process below is unchanged.
+
+> **Rename note (2026-09-26).** The repository is now Tympan, an
+> Astrlabe-family component published by Datatech. `packages/ui` is
+> `@datatechsolutions/tympan` (called `@fakhir/ui` in this record, before
+> that `@fakhir/design-system`), `packages/flow` is
+> `@datatechsolutions/tympan-flow` (here `@fakhir/flow`, before that
+> `@fakhir/flow-canvas`) and `packages/tokens` is
+> `@datatechsolutions/tympan-tokens` (here `@fakhir/tokens`). The `fk-` class
+> and `--fk-` custom-property prefix and the `data-fk-*` attributes named here
+> are now `ty-`, `--ty-` and `data-ty-*`; `FakhirProvider` is `TympanProvider`;
+> the Fakhir look is the `fakhir` theme preset. This record is otherwise kept
+> as written.
+
+> **Merge note (2026-09-26).** `packages/flow`
+> (`@datatechsolutions/tympan-flow`) was later folded into `packages/ui`: its
+> sources are in `packages/ui/src/flow` and it ships as the
+> `@datatechsolutions/tympan/flow` subpath with the
+> `@datatechsolutions/tympan/flow.css` stylesheet. Paths under
+> `packages/flow` named here are now under `packages/ui/src/flow`.
+
+Date: 2026-09-26. Author: Natalia Mesquita. Branch: `ds/wave-3` (from
+`ds/clean-room`), worktree `~/datatech/fakhir-ds-canvas`, a sparse checkout
+without the forked packages and the old platform app.
+
+## Why
+
+The previous workflow canvas package (part of the "fork") is partly derived
+from commercial templates whose licence forbids publishing derivatives. This
+package recreates its behaviour, and adds the provenance graph viewer the
+research platform needs, as new MIT-licensed code without Tailwind, written
+only from behaviour specifications and public documentation.
+
+## Roles and who read what
+
+| Role | Who | Read | Did not read |
+|---|---|---|---|
+| Spec writer | a separate agent session, before this work | the fork's sources, stories and tests | n/a (does not implement) |
+| Implementer (coordinating) | Claude (agent session `01Ui9nSds3quCVK9RtvTPvgj`), acting for Natalia Mesquita | the allowed inputs below | the fork, its `dist` or stylesheet, any `ui-components` folder, `~/datatech/astrlabe*`, the old platform, the thesis repository's `platform/`, any commercial template material or archive |
+| Implementer (sub-sessions G1–G6b) | eight forked sub-sessions of the same implementer, each writing one group of components in its own folders | the same allowed inputs, plus the code already written in this worktree | same exclusions |
+| Coordinator | the session that assigned the work | both sides; runs the similarity audit from outside the clean room | n/a |
+
+The implementer did not open, search, run or copy the fork, did not change the
+sparse checkout, did not inspect other branches, other worktrees or the
+excluded paths with git, and did not modify `packages/ui` or
+`packages/tokens` (a separate session extends them). No spec question needed
+to go back to the spec writer; ambiguities were resolved from the design
+direction and recorded in `PROVENANCE.md`.
+
+## Allowed inputs (the only sources used)
+
+1. `docs/clean-room/specs/**`: `README.md`, `INVENTORY.md`, all
+   `wave-3/*.md` (63 specs; `wave-3/data-source-node.md` only as history,
+   superseded) and the canvas-related wave-4 specs: `run-view-modes.md`,
+   `rule-action-catalog.md`, `data-source-node.md`, `node-state-styles.md`,
+   `flow-palette-tokens.md` (and `floating-action-bar.md` for the dock item
+   shape only).
+2. `docs/infra/design-direction-fakhir.md` in the thesis repository (visual
+   and interaction source of truth: `--fk-*` tokens, proof states and actor
+   language §2.11, canvas and provenance screens §3.10 and §3.13).
+3. React Aria Components documentation and its published type definitions in
+   `node_modules/react-aria-components/dist/types` (Apache-2.0).
+4. WAI-ARIA Authoring Practices Guide patterns (Toolbar, Tree View, Tabs,
+   Listbox, Combobox, Menu, Menu Button, Disclosure, Dialog, Radio Group,
+   Switch, Grid) and WCAG 2.2.
+5. MDN (Pointer Events, ResizeObserver, CSS logical properties, `:dir()`,
+   cascade layers, `forced-colors`, `prefers-*` media, `line-clamp`,
+   `Intl.*`).
+6. W3C PROV-O / PROV-DM (entity, activity, agent; `wasDerivedFrom`, `used`,
+   `wasGeneratedBy`, `wasAttributedTo`) for the provenance model.
+7. Public documentation and MIT source of `@xyflow/react` were allowed; the
+   implementer did not need them (see `PROVENANCE.md`).
+8. `@dagrejs/dagre` public API documentation (MIT) for `autoLayout`.
+9. The public ICU MessageFormat syntax description, for the label templates.
+10. The project's own canvas storyboards (rendered PNGs and their HTML
+    sources: F2, Q2–Q6 for the flow editor; Proveniência, P2–P6 for
+    provenance), authored for this project and supplied by the coordinator
+    as the visual spec. Only measurements, colours and hierarchy were taken
+    from them; no code was copied (they are static inline-styled mocks).
+
+## Process
+
+1. Foundations first, by the coordinating implementer: graph model and pure
+   geometry, `autoLayout`, the node kind catalog with palette tokens and node
+   state attributes, the per-editor state store and dialog stack, the canvas
+   surface, `GraphNodeCard`, dock-ready canvas tools, locale-aware labels
+   (en, pt-BR, es) with an ICU subset, and right-to-left support.
+2. Eight sub-sessions implemented the component groups in parallel, each only
+   inside its own folders, against written contracts: provenance viewer (G1),
+   node kinds, ports and connectors (G2), editor and chrome (G3), run views
+   and trace (G4), expressions and rule forms (G5a), node forms (G5b),
+   dialogs and agent editors (G6a), assistant and report view (G6b).
+3. The coordinating implementer integrated the groups, wrote the gallery,
+   and ran build, typecheck, tests, guardrails and the gallery build.
+4. Every acceptance test of every spec became an automated test (Testing
+   Library + user-event) with an axe-core check; facts jsdom cannot compute
+   (hit areas, reduced motion, forced colours) are asserted on stylesheets.
+5. Guardrails `check:no-tailwind` and `check:provenance` scan this package.
+   The similarity audit against the fork is run by the coordinator (see
+   `tools/provenance/README.md`).
+
+## Statement
+
+To the best of the implementer's knowledge, no code, markup, class string,
+style value, comment or documentation wording from the fork or from any
+commercial template entered this package.

package/src/flow/PROVENANCE.md

@@ -0,0 +1,169 @@
+# Provenance
+
+> **Rename note (2026-09-26).** The repository is now Tympan, an
+> Astrlabe-family component published by Datatech. `packages/ui` is
+> `@datatechsolutions/tympan` (called `@fakhir/ui` in this record, before
+> that `@fakhir/design-system`), `packages/flow` is
+> `@datatechsolutions/tympan-flow` (here `@fakhir/flow`, before that
+> `@fakhir/flow-canvas`) and `packages/tokens` is
+> `@datatechsolutions/tympan-tokens` (here `@fakhir/tokens`). The `fk-` class
+> and `--fk-` custom-property prefix and the `data-fk-*` attributes named here
+> are now `ty-`, `--ty-` and `data-ty-*`; `FakhirProvider` is `TympanProvider`;
+> the Fakhir look is the `fakhir` theme preset. This record is otherwise kept
+> as written.
+
+> **Merge note (2026-09-26).** `packages/flow`
+> (`@datatechsolutions/tympan-flow`) was later folded into `packages/ui`: its
+> sources are in `packages/ui/src/flow` and it ships as the
+> `@datatechsolutions/tympan/flow` subpath with the
+> `@datatechsolutions/tympan/flow.css` stylesheet. Paths under
+> `packages/flow` named here are now under `packages/ui/src/flow`.
+
+Author: Natalia Mesquita. Per component: the spec it implements, the sources
+used, and the decisions taken where the spec left room. Specs live in
+`docs/clean-room/specs/`; "DD" is the design direction
+(`docs/infra/design-direction-fakhir.md`); RAC is React Aria Components (used
+from its documentation and published type definitions); APG is the WAI-ARIA
+Authoring Practices Guide. No fork or commercial template material was used
+for any row. Every test file includes axe-core checks and stylesheet
+assertions for reduced motion and forced colours where the component moves or
+draws state.
+
+## Foundations (coordinating implementer)
+
+| Part | Spec | Sources | Decisions |
+|---|---|---|---|
+| Graph model, `topologicalOrder`, `layerIndex`, `withinHops` | none (infrastructure) | Kahn ordering, longest-path layering | Stable tie-break by input order; cycles appended |
+| Geometry (`rect`, `viewport`, `curve`, `guides`, `arrange`) | wave-3 alignment-guides, selection-arrange (arithmetic) | Bernstein cubic, ray/box intersection | Own zoom ladder (0.2–2.5); "centre horizontally" shares x |
+| `autoLayout` | wave-3/auto-layout | @dagrejs/dagre (MIT) | Rank gap 64, sibling 32, margin 24 (§2.1); `right-left` rank direction for RTL |
+| NodeKindCatalog, icon registry, RenderCatalog | wave-3/node-kind-catalog | lucide icons (§4.4) | Picker kinds (agent, rule, datasource) have no default config |
+| FlowPaletteTokens (`kindTone`, `kindTokens`, `connectorTokens`) | wave-4/flow-palette-tokens | DD §2.3; WCAG contrast (static test) | Resting connector uses `--fk-input` (≥ 3:1) instead of `--fk-line-strong` (≈ 2:1), per WCAG 1.4.11 |
+| NodeStateStyles (`nodeStateAttributes`, frame CSS) | wave-4/node-state-styles | DD §2.6, §2.11, §3.13 | Selection ring outside, run ring inside; proof state as border line style |
+| FlowEditorState, dialog stack | wave-3/flow-editor-state | own minimal external store + `useSyncExternalStore` | One store per provider; paste cascades via the clipboard |
+| CanvasSurface | wave-3/flow-editor, flow-preview (surface parts) | Pointer Events, ResizeObserver (MDN) | Own engine instead of @xyflow/react: DOM reading order, jsdom-testable geometry, logical RTL port sides; `minFitZoom` keeps text readable |
+| ConnectionPreviewLine | wave-3/connection-preview-line | — | Not-allowed glyph beside the pointer end |
+| GraphNodeCard | wave-3/graph-node-card | RAC Button, TextField; APG Button | Title button stretched over the card; siblings above it; clamps by lines |
+| Canvas tools, CanvasToolbar, CanvasNodeSearch | brief (dock toolbar); wave-4/floating-action-bar (item shape) | RAC Toolbar, ToggleButton, Autocomplete, SearchField, ListBox; APG Toolbar | Tools are data so the DS dock can render them; `aria-keyshortcuts` set through a ref (RAC does not forward it) |
+| Labels, `FlowMessagesProvider`, ICU subset, `useFlowLocale` | user requirement (i18n) | RAC `useLocale`; ICU syntax; `Intl.PluralRules` | en complete; pt-BR and es shipped; host catalogue per component key |
+| SectionedModal, DockedPanel, ConfirmProvider (internal) | stand-ins for wave-2 SectionedModal and ConfirmService | DS ModalDialog, Tabs, Button | Replace with the DS components when wave 2 lands |
+
+## Components by group
+
+| Group | Components (spec) | Tests | Sources | Decisions |
+|---|---|---|---|---|
+| Provenance | ProvenanceGraph (question bar and five views), ProvenanceTree, ProvenanceInspector, ProvenanceFilters, ProvenanceLegend, ProvenanceNode, HashCheck, model helpers (`provenanceView`, `proofPath`, `bandLayout`, `bandGeometryFrom`) (no spec; brief priority 1 and the author's storyboards) | 44 | W3C PROV-O/PROV-DM; DD §2.11, §3.7, §3.13; RAC ComboBox, Tree, Popover; APG Combobox, Tree View | Bands stacked top to bottom in research order, only bands with items; proof path down column 0, off-path dimmed with the word "off the proof path", focus halo, "only the proof path" hides the rest; relation shown by line style (derived solid, used dashed, attributed dotted, generated dash-dot) with the word in the legend, inspector and tree, not on the line (it covered cards between close bands); arrows point back to origins as in PROV diagrams; band sizes read from `--fk-flow-*` tokens; steps back and forward are separate; tree is the default below 1024 px and the inspector opens on selection there; Enter in the tree shows the node in the graph |
+| Provenance side views | ProvenanceTimeline, ProvenanceCertificate, EditionCompare, NumberTrace (storyboards; types in `proofTypes.ts`) | 19 | RAC Tree; DS ActorChip, ProofBadge, SegmentedControl; APG Tree View, Radio Group, Disclosure | Timeline: one lane per actor, close events stacked in rows, axis inset so no event hangs over an edge; certificate states the verifier is deterministic and uses no language model; comparison marks changes by icon, word and border style and shows before/after cards; number trace opens a non-modal region and returns focus to the number |
+| Nodes | GenericNode, AgentNode, RuleNode, NoteNode, GroupNode, DataSourceNode (wave-4), NodeRunIndicator, ConnectionPorts, AgentIdentity, AlignmentGuides, DecisionNode (B-002) | 48 + 10 | RAC Button, Toolbar, Switch, TextField, ComboBox; DD §2.3, §2.11 | Agent avatar is a geometric mark from a hash of the name (no external service); source marks from a local registry with a database glyph fallback, dialect always text; decision probabilities as text plus bar, "needs review" word |
+| Connectors | ConditionalConnector, ConnectorInsertMenu, `splitConnector`, Connect to command | 18 | RAC Button, Autocomplete, ListBox, Popover; DS Drawer; APG Combobox | Branch word is the focusable handle (Delete removes, Enter opens insert); true solid, false dashed, loop dotted; bottom drawer below 640 px |
+| Editor | FlowEditor, FlowEditorProvider, AutosaveController, EditorShortcuts, SelectionArrange, CanvasContextMenus, CanvasCommandBar, NodePalette, FlowOutline, FlowPreview, FlowSwitcherBar, SaveStatus, RunControls | 19 + 42 | DS ActionMenu; RAC Toolbar, Popover, GridList (drag and drop), Disclosure, SearchField; APG Toolbar, Menu, Dialog | Shortcuts listen in the capture phase scoped to the canvas; Escape clears then leaves to the toolbar; the L key is not implemented (auto-layout is a tool); step list as keyboard alternative, open by default below 1024 px |
+| Runs | useFlowExecution, applyRunEvent, useRunProjection, RunPanel, RunPreviewPanel, RunDrawer, RunViews (wave-4 run-view-modes), RunInputDialog, RunReplayDialog, RunRewindDialog, lineage and diff helpers, ExecutionTimeline, VariableInspector, VersionHistoryPanel | 43 | RAC Tabs, ListBox, Disclosure, Dialog; DS ActorChip, StatusPill; DD §2.8, §3.10 | Default timeline selection is the first failed step; a failed run forces the drawer on the failing node; the version panel does not confirm restores (host does) |
+| Expressions | ExpressionBuilder, ExpressionField, TraceTree (+ `runDryRun`), ComputeNodeForm, SimulationNodeForm, RuleEditor (+ condition and action builders, `normalizeRuleCondition`, `defaultRule`), rule action catalog (wave-4), RuleNodeForm | 14 + 9 + 33 | RAC Tree, NumberField, Disclosure, RadioGroup; APG Tree View, Radio Group, Disclosure | Operation vocabulary comes from a host catalog; simulation wraps bare values in `coalesce`; legacy rule shapes are this package's own reading and must be checked against the engine normaliser; native date-time input until the DS has a DatePicker |
+| Forms | SchemaConfigForm (+ NodeFormFooter), VariableListEditor, ToolServerListField, StartNodeForm, AgentNodeForm, DataSourceNodeForm, ReportOutputNodeForm, GroupNodeForm, OutputSchemaBuilder, DecisionNodeForm (B-002) | 71 | RAC RadioGroup, ListBox; DS fields, CheckboxGroup, Switch; APG Tabs, Radio Group, Listbox | No vendor logos; `maxLimit` prop for the row limit; decision needs two unique options and an input reference |
+| Dialogs | NodeConfigDialog, FlowSettingsDialog, DefinitionExportDialog, DefinitionImportDialog | 40 | RAC DropZone, FileTrigger, Modal, Dialog, Switch; APG Dialog | Export file name keeps Unicode letters; copy failure is reported (not claimed as success) |
+| Agents | AgentEditorDialog, AgentCreationWizard (with local StepList, ChoiceTiles, TagInput) | 18 | RAC Slider, ToggleButtonGroup, Tabs (vertical), RadioGroup, Disclosure; APG Dialog, Tabs, Slider, Radio Group | Capability tiers and presets come from props; slider value text names the tier; wizard Enter advances only outside fields |
+| Assistant and report | useAssistantSession, AssistantConversation, MarkdownView, AssistantVisualBlock (+ `parseAssistantVisual`, `envelopeToReport`), ConversationShell (+ `groupThreadsByDay`, ThreadMetaLine), ReportView | 39 | RAC TextField, ToggleButton; DS Drawer, Skeleton; APG log region | Composer stays editable while busy; pt, en and es payload key aliases; currency only when the host gives a code; date groups by calendar day in a time zone |
+
+Total: 508 tests in 36 files (Vitest count; the per-group numbers above count `it` blocks).
+
+## Similarity rework
+
+After the coordinator's outside audit, 23 files were restructured with
+their own vocabulary and decomposition (reducers and lookup tables instead
+of chained state and switches, extracted pure helpers and subcomponents):
+run lineage, run data, run types, the run input, replay and rewind dialogs,
+the number input, the assistant hook and conversation shell, announcer,
+confirm, render catalog, schema and start forms, variable list, agent
+parts, expression builder, compute form, trace client, flow settings,
+autosave, auto-layout and the provenance legend. Behaviour and tests were
+kept.
+
+## Ambiguities resolved (summary)
+
+- **Canvas library.** Own pointer-event surface instead of @xyflow/react,
+  which the brief allowed and which was not used: the canvas needs its node
+  boxes in reading order in the DOM (Tab order and the list/tree alternative
+  follow the picture), deterministic geometry that jsdom can test without
+  layout, logical (RTL-aware) port sides, and an internal structure of its
+  own. A small pointer-event surface (`src/surface/`) covers pan, zoom, pinch,
+  marquee, node drag and connection drawing. (Moved here from
+  `THIRD_PARTY_NOTICES.md` on 2026-09-26.)
+- **Right to left.** Canvas geometry keeps a physical origin; logical port
+  sides and the horizontal rank direction mirror; everything else uses
+  logical CSS. Identifiers, hashes and code stay left to right.
+- **Languages.** Strings ship in en, pt-BR and es; other locales (for example
+  ar and ja in the gallery) get English labels until the host supplies a
+  catalogue through `FlowMessagesProvider`, while data, numbers and dates
+  already follow the locale.
+- **Connector contrast.** `--fk-input` for resting connectors (≥ 3:1).
+
+## Canvas tokens (upstreamed into @fakhir/tokens)
+
+The `--fk-flow-*` tokens first lived in this package's `src/tokens.css`. They
+now live in `@fakhir/tokens` (`src/flow.ts`, DTCG aliases of theme roles in
+`dist/dtcg/flow.tokens.json`, emitted into `tokens.css`): the kind tones
+`--fk-flow-tone-{categorical-1…8,neutral}` with `-ink`, `-soft`, `-text` and
+the `[data-tone]` mapping; connectors (`--fk-flow-connector`, `-active`,
+`-true`, `-false`, `-rule`, `-width`, `-width-active`); node frame
+(`--fk-flow-node-border`, `-border-hover`, `-surface`, `-radius`) and rings
+(`--fk-flow-ring-selected`, `-running`, `-succeeded`, `-failed`); canvas
+(`--fk-flow-plane`, `--fk-flow-grid-dot`, `--fk-flow-guide`,
+`--fk-flow-marquee`); provenance bands (`--fk-flow-band` 96px,
+`--fk-flow-band-label` 130px, `--fk-flow-node-h` 72px, `--fk-flow-node-w`
+236px, `--fk-flow-col-gap` 56px); research steps (`--fk-flow-step-w` 250px,
+`--fk-flow-step-h` 86px) and data shapes (`--fk-flow-shape-records` accent,
+`-table` categorical-1, `-number` warning, `-chart` categorical-8, `-decision`
+danger). Values are unchanged; this package only reads them.
+
+## Gallery data
+
+All gallery data is fictional and labelled "Dados de exemplo / Sample data":
+the Vila Aurora urban air-quality study of Example Lab (Laboratório
+Exemplo), with invented monitoring stations (Centro, Harbour, Park, North,
+Riverside), readings (for example retrieval `rd-0714`), the assertion
+`air.pm25_days_above_limit = 12`, record `station-centro-2026`, edition
+2026-09 (a manifest of 312 hashes) and people with `@example.org` addresses.
+Form and expression specimens use neutral placeholders (Fonte de dados A,
+Opção A, [hash]). The provenance items carry no proof state ("no proof"),
+because the verifier (G7a) does not exist yet.
+
+## Similarity rework, round 2
+
+`useAssistantChat` became `useAssistantSession` with a new vocabulary
+(renames listed at the end of `wave-3/assistant-chat.md` and
+`wave-3/conversation-shell.md`); ConversationShell was split into
+`threadDays`, `ThreadHistory`, `LiveCanvasPanel` and a layout shell; the
+rewind dialog moved its logic to `rewindPlan.ts`; ExpressionBuilder moved its
+levels into `expressions/builder/`; ComputeNodeForm into `computeDraft`,
+`ComputeInsertPanel` and `ComputeTrial`; VariableListEditor into
+`nameListModel` and a parts table. Behaviour and tests unchanged.
+
+## Storyboard alignment (DAG editor)
+
+The canvas storyboards (our own designs F2, Q2–Q6) are the visual spec.
+The gallery renders the editor inside the design system's research shell
+(`gallery/src/shell/ResearchShell.tsx`: `AppFrame layout="rail"`, the
+editorial `PageHeader` and a `FloatingActionBar` dock fed by
+`dockItemsFromCanvasTools`; the first versions used a stand-in drawn before
+the rail layout existed) at 1440×960,
+with the storyboard states reachable as `#/editor?state=canvas|picker|drag|
+search|mismatch|list|selected` (`&lang=` for the locale). Measurements come
+from the storyboards' inline styles. Side-by-side comparisons (reference |
+implementation) were made for each state.
+
+Deliberate differences:
+
+- The whole flow is fitted (about 85% zoom) instead of clipping the right
+  branch at the canvas edge, and input chips sit on a 14px top padding so they
+  no longer overlap the kind label (both known issues of the storyboards).
+- The status bar for a mismatched link is laid out as one sentence with the
+  shape chips and the repair button, instead of the storyboard's overlapping
+  columns; the chart branch is also flagged when it receives the wrong shape.
+- A visible "Dados de exemplo" tag sits in the header actions (project rule:
+  no invented research data); "Filtrar: tipo = case" is shown as "Filtrar"
+  (the filter condition is not a known value).
+- Interaction mocks are shown only while interacting: the "+" on links
+  appears on hover or focus, and the dragged palette entry is highlighted by
+  the browser drag, not in a still frame.
+- The side panel's selects use the design system's trigger as is (40px on
+  desktop, 44px below 1024px, value centred), fixed upstream.
+- Picker descriptions reuse the palette's (slightly longer) descriptions.

package/src/flow/README.md

@@ -0,0 +1,117 @@
+# @datatechsolutions/tympan/flow
+
+Tympan's accessible React canvases for research platforms: a **W3C PROV
+provenance graph viewer** with a synced keyboard list, a **DAG workflow
+editor** for analyses (including a generic decision step), run inspection
+(panel and drawer, timeline, trace, replay and rewind), and the forms and
+dialogs around them. Built on the `@datatechsolutions/tympan` components and
+React Aria Components, styled with plain CSS in `@layer tympan.components`.
+Part of `@datatechsolutions/tympan` (this folder was the separate
+`@datatechsolutions/tympan-flow` package until 2026-09-26). Licence:
+FSL-1.1-ALv2 (Functional Source License, Version 1.1, Apache 2.0 Future
+License), Copyright 2026 Natalia Mesquita; see `LICENSE` of the package.
+
+Built, tested and shown with the package:
+
+```sh
+npm run build -w @datatechsolutions/tympan     # dist/flow.js, flow.d.ts, flow.css (next to index.js, styles.css)
+npm test -w @datatechsolutions/tympan          # vitest + Testing Library + axe-core
+npm run gallery -w @datatechsolutions/tympan   # http://localhost:3310/#/flow/provenance (also #/flow/editor, #/flow/components)
+```
+
+## Usage
+
+`@dagrejs/dagre` (behind `autoLayout`) is an optional peer dependency of
+`@datatechsolutions/tympan`: install it when you use this entry.
+
+```tsx
+import '@datatechsolutions/tympan/styles.css'
+import '@datatechsolutions/tympan/flow.css'
+import { TympanProvider } from '@datatechsolutions/tympan'
+import { ProvenanceGraph, FlowEditor } from '@datatechsolutions/tympan/flow'
+
+<TympanProvider locale="pt-BR">
+  <ProvenanceGraph items={items} statements={statements} defaultFocusId="as-reg-position" defaultHops={3} />
+</TympanProvider>
+```
+
+## What is inside
+
+- **Provenance** (`ProvenanceGraph`, `ProvenanceTree`, `ProvenanceInspector`,
+  `ProvenanceFilters`, `ProvenanceLegend`, model helpers): query → retrieval →
+  source → assertion → record → analysis/edition → manuscript sentence, with
+  `wasDerivedFrom`, `used`, `wasGeneratedBy` and `wasAttributedTo` relations;
+  focus N hops backward/forward/both; filters by kind, actor and proof state;
+  proof-state border styles and the person/agent/system actor language of the
+  design direction (§2.11); an APG tree view synced with the canvas, so the
+  canvas is never the only way in.
+- **Research steps** (`StepPalette`, `AddStepPicker`, `StepCard`,
+  `IssueBar`, `FlowSidePanel`, `StepListView`, `ShapeChip`, `stepToolItems`,
+  typed wiring helpers): steps shelved by research verb (input, prepare,
+  analyse, decide, output; engine primitives on a folded "advanced" shelf),
+  each with typed ports (records, table, number, chart, decision). A step is
+  added after a step ("+" under it or the A key), inside a link ("+" on the
+  link), from the palette (tap, Enter or drag) or from the dock; every way
+  links and lays the flow out. Mismatched links are marked on the step and in
+  a status bar with a one-press repair (swap the step, insert a bridge, or
+  unlink). The list view is the keyboard view of the canvas.
+- **Editor** (`FlowEditor`, `FlowEditorProvider`, `AutosaveController`,
+  `CanvasCommandBar`, `CanvasContextMenus`, `NodePalette`, `FlowOutline`,
+  `FlowPreview`, `FlowSwitcherBar`, `SaveStatus`, `RunControls`, editor
+  shortcuts, selection arrange, alignment guides).
+- **Nodes and connectors** (`GraphNodeCard`, `GenericNode`, `AgentNode`,
+  `RuleNode`, `NoteNode`, `GroupNode`, `DataSourceNode`, `DecisionNode`,
+  `NodeRunIndicator`, `ConnectionPorts`, `ConditionalConnector`,
+  `ConnectorInsertMenu`, `ConnectionPreviewLine`, `AgentIdentity`).
+- **Runs** (`RunViews` with `RunPreviewPanel` and `RunDrawer`, `RunPanel`,
+  `ExecutionTimeline`, `VariableInspector`, `VersionHistoryPanel`,
+  `RunInputDialog`, `RunReplayDialog`, `RunRewindDialog`, run state and
+  lineage/diff helpers).
+- **Forms and dialogs** (schema-driven and per-kind node forms, the decision
+  form, `ExpressionBuilder`, `TraceTree`, `RuleEditor` with the rule action
+  catalog, `NodeConfigDialog`, `FlowSettingsDialog`, definition export and
+  import, `AgentEditorDialog`, `AgentCreationWizard`).
+- **Assistant** (`useAssistantSession`, `AssistantConversation`,
+  `AssistantVisualBlock`, `ConversationShell`, `ReportView`).
+- **Foundations**: `CanvasSurface` (pan, zoom, pinch, marquee, node drag,
+  connection drawing, overview map), `autoLayout` (dagre), `NodeKindCatalog`,
+  `FlowPaletteTokens` (`kindTone`, `kindTokens`, `connectorTokens`),
+  `nodeStateAttributes`, `createFlowEditorStore` and the dialog stack.
+
+## Canvas tools in the bottom dock
+
+`canvasToolItems({ zoom, mode, onModeChange, onZoomIn, onZoomOut,
+onZoomReset, onFit, onAutoLayout, onToggleListView, onSearch, locale })`
+returns the canvas tools as dock items (select, pan, zoom out, zoom level as a
+percentage, zoom in, fit, auto-layout, list view, find a node), each with a
+label, icon, toggle state and `aria-keyshortcuts`. Hand them to the design
+system's bottom dock, or render them with `CanvasToolbar`. The flow editor
+uses `stepToolItems` instead: select, move | add a step (A), rearrange, fit |
+show as list, find a step; `FlowEditor` passes them to `renderTools`, so a host
+can place the dock at sheet level.
+
+## Languages and direction
+
+Every visible string is a label. Components ship English, Brazilian
+Portuguese and Spanish bundles (`defineLabels`), resolved from the React Aria
+locale that `TympanProvider` sets; hosts add any language through
+`<FlowMessagesProvider messages={{ ComponentKey: {...} }}>` or per-component
+`labels`. Templates use an ICU MessageFormat subset (plural, select, number).
+Numbers, dates and durations go through `Intl` with the provider locale.
+Styles use logical properties only; in right-to-left locales panels and
+toolbars mirror, directional glyphs flip, logical port sides mirror and a
+horizontal auto-layout runs right to left (each canvas has a `keepLtr` option).
+Node titles clamp by lines, never by characters.
+
+## Accessibility
+
+Canvases are labelled groups whose nodes sit in reading order in the DOM;
+every operation has a keyboard path (list or tree alternative, "Connect to…",
+context menus by Shift+F10); Escape leaves the canvas; colour is never the
+only carrier (words, icons, line styles); 44 px hit areas; reduced motion,
+reduced transparency and forced colours are handled in every stylesheet.
+
+## Records
+
+`CLEAN-ROOM.md` (process and inputs), `PROVENANCE.md` (per component) in
+this folder; `THIRD_PARTY_NOTICES.md` and `LICENSE` of the package.