@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/flow/state/store.ts

@@ -0,0 +1,67 @@
+// A minimal external store (subscribe / getState / setState) and a selector
+// hook with memoised selection, so components re-render only for their slice.
+
+import { useCallback, useRef, useSyncExternalStore } from 'react'
+
+export interface Store<S> {
+  getState(): S
+  setState(next: Partial<S> | ((prev: S) => Partial<S>)): void
+  subscribe(listener: () => void): () => void
+}
+
+export function createStore<S extends object>(initial: S): Store<S> {
+  let state = initial
+  const listeners = new Set<() => void>()
+  return {
+    getState: () => state,
+    setState(next) {
+      const patch = typeof next === 'function' ? next(state) : next
+      let changed = false
+      for (const k of Object.keys(patch) as Array<keyof S>) {
+        if (!Object.is(state[k], patch[k])) {
+          changed = true
+          break
+        }
+      }
+      if (!changed) return
+      state = { ...state, ...patch }
+      for (const l of [...listeners]) l()
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+}
+
+/** Shallow equality for arrays and plain records (selector results). */
+export function shallowEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (typeof a !== 'object' || typeof b !== 'object' || !a || !b) return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  if (ka.length !== kb.length) return false
+  for (const k of ka) if (!Object.is((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])) return false
+  return true
+}
+
+/** Subscribes to `selector(state)`; re-renders only when the selection changes under `isEqual`. */
+export function useStoreSelector<S, T>(store: Store<S>, selector: (s: S) => T, isEqual: (a: T, b: T) => boolean = Object.is): T {
+  const memo = useRef<{ state: S; selector: (s: S) => T; value: T } | null>(null)
+  const select = useCallback(() => {
+    const state = store.getState()
+    const prev = memo.current
+    if (prev && prev.state === state && prev.selector === selector) return prev.value
+    const value = selector(state)
+    if (prev && isEqual(prev.value, value)) {
+      memo.current = { state, selector, value: prev.value }
+      return prev.value
+    }
+    memo.current = { state, selector, value }
+    return value
+    // selector identity is allowed to change each render; the state check keeps it cheap
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [store, selector])
+  return useSyncExternalStore(store.subscribe, select, select)
+}

package/src/flow/steps/AddStepPicker.tsx

@@ -0,0 +1,108 @@
+// AddStepPicker: "Add after “…”". Lists only the steps whose input takes what
+// the anchor step gives; type to narrow, ↑↓ to move, Enter to insert, Esc to
+// close. A popover on wide screens, a bottom drawer below 640 px.
+
+import { useMemo, useState, type RefObject } from 'react'
+import { Autocomplete, Dialog, Heading, Input, ListBox, ListBoxItem, Popover, SearchField, Text, useFilter } from 'react-aria-components'
+import { Search } from 'lucide-react'
+import { Drawer, useMediaQuery } from '../../index'
+import { fill, useFlowLocale } from '../internal/labels'
+import { ShapeChip } from './ShapeChip'
+import type { DataShape } from './shapes'
+import type { ReadyStep } from './researchSteps'
+import { useSteps } from './StepsContext'
+
+export interface AddStepPickerProps {
+  /** Heading: after a step, between two steps, or free. */
+  title: string
+  /** Search placeholder (defaults to the title). */
+  placeholder?: string
+  /** Shape arriving at the new step (undefined: anything). */
+  arriving?: DataShape | null
+  options: readonly ReadyStep[]
+  triggerRef: RefObject<HTMLElement | null>
+  onPick: (stepId: string) => void
+  onClose: () => void
+}
+
+function PickerBody({ title, placeholder, arriving, options, onPick, onClose, headed }: Omit<AddStepPickerProps, 'triggerRef'> & { headed: boolean }) {
+  const rt = useSteps()
+  const w = rt.words
+  const { locale } = useFlowLocale()
+  const { contains } = useFilter({ sensitivity: 'base' })
+  const [query, setQuery] = useState('')
+  const shown = useMemo(() => (query ? options.filter((o) => contains(`${o.name} ${o.description}`, query)) : [...options]), [options, query, contains])
+  return (
+    <div className="ty-add-picker__body">
+      {headed ? (
+        <Heading slot="title" className="ty-visually-hidden">
+          {title}
+        </Heading>
+      ) : null}
+      <Autocomplete inputValue={query} onInputChange={setQuery} filter={() => true}>
+        <SearchField className="ty-add-picker__field" autoFocus aria-label={title}>
+          <Search className="ty-add-picker__glass" aria-hidden="true" focusable="false" />
+          <Input className="ty-add-picker__input" placeholder={placeholder ?? title} />
+        </SearchField>
+        {arriving ? (
+          <p className="ty-add-picker__only">
+            <span>{w.pickerOnly}</span>
+            <ShapeChip shapes={[arriving]} words={rt.shapes} />
+          </p>
+        ) : null}
+        <ListBox
+          className="ty-add-picker__list"
+          aria-label={title}
+          items={shown}
+          renderEmptyState={() => <p className="ty-add-picker__empty">{arriving && !options.length ? fill(w.nothingAccepts, { shape: rt.shapes[arriving] }, locale) : fill(w.noMatch, { query }, locale)}</p>}
+          onAction={(key) => {
+            onPick(String(key))
+            onClose()
+          }}
+        >
+          {(item) => {
+            const Icon = item.icon
+            return (
+              <ListBoxItem id={item.id} textValue={item.name} className="ty-add-picker__option">
+                <span className="ty-add-picker__tile" aria-hidden="true">
+                  <Icon focusable="false" />
+                </span>
+                <Text slot="label" className="ty-add-picker__name">
+                  {item.name}
+                </Text>
+                <Text slot="description" className="ty-add-picker__about">
+                  {item.description}
+                </Text>
+              </ListBoxItem>
+            )
+          }}
+        </ListBox>
+      </Autocomplete>
+      <p className="ty-add-picker__keys" aria-hidden="true">
+        {w.pickerKeys}
+      </p>
+      <p className="ty-visually-hidden" role="status">
+        {fill(w.results, { count: shown.length }, locale)}
+      </p>
+    </div>
+  )
+}
+
+export function AddStepPicker(props: AddStepPickerProps) {
+  const narrow = !useMediaQuery('(min-width: 640px)', true)
+  const { triggerRef, onClose, title } = props
+  if (narrow) {
+    return (
+      <Drawer open onOpenChange={(open) => !open && onClose()} title={title} placement="bottom">
+        <PickerBody {...props} headed={false} />
+      </Drawer>
+    )
+  }
+  return (
+    <Popover isOpen onOpenChange={(open) => !open && onClose()} triggerRef={triggerRef} placement="bottom start" offset={10} className="ty-add-picker">
+      <Dialog className="ty-add-picker__dialog">
+        <PickerBody {...props} headed />
+      </Dialog>
+    </Popover>
+  )
+}

package/src/flow/steps/FlowSidePanel.tsx

@@ -0,0 +1,318 @@
+// FlowSidePanel: the editor's inline-end panel. With nothing selected it
+// sums the flow up (version, the edition it runs on, steps, AI use,
+// determinism, citable outputs by shape) with "run" and "validate"; with a
+// step selected it shows the step's settings, a preview of its output and
+// "test" / "remove".
+
+import { ArrowRight, Check, Ellipsis } from 'lucide-react'
+import { useEffect, useMemo, useState } from 'react'
+import { ActionMenu, Button, ListboxSelect, Switch, TextArea, TextField } from '../../index'
+import { fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { FlowNode } from '../model/types'
+import { ShapeFlow } from './ShapeChip'
+import { researchStepWords, settingProblems, settingsOf, specOfNode, type ReadyStep, type StepField } from './researchSteps'
+import { shapeCounts, type DataShape } from './shapes'
+import { useSteps } from './StepsContext'
+
+/** Facts about the flow the host knows (the editor counts the rest). */
+export interface FlowFacts {
+  /** The flow's name (panel title). */
+  name?: string
+  /** Version and state, as the host words it ("v3 · draft"). */
+  version?: string
+  /** What it runs on ("edition 2026-09-20"). */
+  runsOn?: string
+  runsOverEdition?: number
+  deterministic?: boolean
+  seed?: string | number
+}
+
+/** A few rows of a step's output. */
+export interface OutputPreview {
+  columns: readonly string[]
+  rows: ReadonlyArray<ReadonlyArray<string | number>>
+}
+
+export interface FlowSidePanelProps {
+  nodes: readonly FlowNode[]
+  selected: FlowNode | null
+  facts?: FlowFacts
+  preview?: OutputPreview | null
+  locked?: boolean
+  /** Result line of the last validation, when there was one. */
+  validation?: string | null
+  onRunFlow?: () => void
+  onValidate: () => void
+  onTestStep?: (nodeId: string) => void
+  onRemove: (nodeId: string) => void
+  onEdit: (nodeId: string, patch: Record<string, unknown>) => void
+  onBack: () => void
+}
+
+const DRAWN = (n: FlowNode) => n.kind !== 'note' && n.kind !== 'group'
+
+export function FlowSidePanel(p: FlowSidePanelProps) {
+  const rt = useSteps()
+  const spec = p.selected ? specOfNode(p.selected, rt.byId) : undefined
+  return p.selected ? <StepSettings {...p} node={p.selected} spec={spec} /> : <FlowOverview {...p} />
+}
+
+function Fact({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="ty-flow-side__fact">
+      <dt>{label}</dt>
+      <dd>{value}</dd>
+    </div>
+  )
+}
+
+function FlowOverview({ nodes, facts = {}, validation, onRunFlow, onValidate }: FlowSidePanelProps) {
+  const rt = useSteps()
+  const w = rt.words
+  const { locale } = useFlowLocale()
+  const specs = nodes.filter(DRAWN).map((n) => specOfNode(n, rt.byId))
+  const ai = specs.some((s) => s?.usesAI)
+  const outputs = specs.filter((s): s is ReadyStep => s?.verb === 'output' && !!s.output).map((s) => s.output as DataShape)
+  const num = (v: number) => new Intl.NumberFormat(locale).format(v)
+  return (
+    <section className="ty-flow-side" aria-labelledby="ty-flow-side-title">
+      <span className="ty-flow-side__eyebrow">{w.eyebrowFlow}</span>
+      <h2 id="ty-flow-side-title" className="ty-flow-side__title">
+        {facts.name ?? w.summaryTitle}
+      </h2>
+      <dl className="ty-flow-side__facts">
+        {facts.version ? <Fact label={w.version} value={facts.version} /> : null}
+        {facts.runsOn ? <Fact label={w.runsOn} value={facts.runsOn} /> : null}
+        {facts.runsOverEdition !== undefined ? <Fact label={w.runs} value={num(facts.runsOverEdition)} /> : null}
+        <Fact label={w.stepCount} value={num(specs.length)} />
+        <Fact label={w.usesAI} value={ai ? w.yes : w.no} />
+        {facts.deterministic !== undefined ? (
+          <Fact label={w.deterministic} value={[facts.deterministic ? w.yes : w.no, facts.seed !== undefined ? fill(w.seed, { seed: String(facts.seed) }, locale) : null].filter(Boolean).join(' · ')} />
+        ) : null}
+        <Fact label={w.citable} value={outputs.length ? shapeCounts(outputs, rt.counts, locale) : w.none} />
+      </dl>
+      <div className="ty-flow-side__stack">
+        {onRunFlow ? (
+          <Button variant="primary" fullWidth leadingIcon={<ArrowRight className="ty-flow-side__arrow" />} onPress={onRunFlow}>
+            {w.runFlow}
+          </Button>
+        ) : null}
+        <Button variant="secondary" fullWidth leadingIcon={<Check />} onPress={onValidate}>
+          {w.validate}
+        </Button>
+      </div>
+      <p className="ty-flow-side__hint">{w.nothingSelected}</p>
+      <p className="ty-flow-side__status" role="status">
+        {validation ?? ''}
+      </p>
+    </section>
+  )
+}
+
+function StepSettings({ node, spec, preview, locked, onTestStep, onRemove, onEdit, onBack }: FlowSidePanelProps & { node: FlowNode; spec: ReadyStep | undefined }) {
+  const rt = useSteps()
+  const w = rt.words
+  const title = (typeof node.data.label === 'string' && node.data.label) || spec?.name || node.kind
+  const settings = settingsOf(spec, node.data)
+  const problems = settingProblems(spec, node.data, rt.problems.get(node.id))
+  /** A field's new value, at the top of the node data or inside the object `configIn` names (undefined removes it). */
+  const commit = (key: string, v: unknown) => {
+    if (!spec?.configIn) return onEdit(node.id, { [key]: v })
+    const next = { ...settings }
+    if (v === undefined) delete next[key]
+    else next[key] = v
+    onEdit(node.id, { [spec.configIn]: next })
+  }
+  return (
+    <section className="ty-flow-side" aria-labelledby="ty-flow-side-title" data-step={node.id}>
+      <div className="ty-flow-side__top">
+        <span className="ty-flow-side__eyebrow">{w.eyebrowStep}</span>
+        <ActionMenu
+          label={w.moreStep}
+          trigger={<Button variant="quiet" size="compact" shape="circle" iconOnly accessibleLabel={w.moreStep} leadingIcon={<Ellipsis />} />}
+          items={[
+            { id: 'back', label: w.backToSummary },
+            ...(!locked ? [{ id: 'remove', label: w.remove, tone: 'danger' as const }] : []),
+          ]}
+          onAction={(id) => (id === 'back' ? onBack() : onRemove(node.id))}
+        />
+      </div>
+      <h2 id="ty-flow-side-title" className="ty-flow-side__title" dir="auto">
+        {title}
+      </h2>
+      {spec && !spec.primitive ? <ShapeFlow inputs={spec.inputs} output={spec.output} words={rt.shapes} labels={w} /> : null}
+      <form className="ty-flow-side__form" onSubmit={(e) => e.preventDefault()} noValidate>
+        {problems[''] ? (
+          <p className="ty-flow-side__problem" role="alert">
+            {problems['']}
+          </p>
+        ) : null}
+        {(spec?.fields ?? []).map((f) => (
+          <Field key={f.key} field={f} value={settings[f.key]} error={problems[f.key]} disabled={!!locked} onCommit={(v) => commit(f.key, v)} />
+        ))}
+        <Draft label={w.stepName} value={typeof node.data.label === 'string' ? node.data.label : ''} placeholder={spec?.name ?? ''} disabled={!!locked} onCommit={(v) => onEdit(node.id, { label: v || undefined })} />
+      </form>
+      <span className="ty-flow-side__eyebrow">{w.preview}</span>
+      {preview && preview.rows.length ? (
+        <div className="ty-flow-side__preview">
+          <table>
+            <thead>
+              <tr>
+                {preview.columns.map((c) => (
+                  <th key={c} scope="col">
+                    {c}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {preview.rows.map((r, i) => (
+                <tr key={i}>
+                  {r.map((v, j) => (
+                    <td key={j} data-kind={j === 0 ? 'key' : typeof v === 'number' || /^\[?n\]?$/.test(String(v)) ? 'number' : 'value'}>
+                      {v}
+                    </td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      ) : (
+        <p className="ty-flow-side__hint">{w.noPreview}</p>
+      )}
+      {!locked ? (
+        <div className="ty-flow-side__row">
+          {onTestStep ? (
+            <Button variant="secondary" leadingIcon={<ArrowRight className="ty-flow-side__arrow" />} onPress={() => onTestStep(node.id)}>
+              {w.testStep}
+            </Button>
+          ) : null}
+          <Button variant="quiet" onPress={() => onRemove(node.id)}>
+            {w.remove}
+          </Button>
+        </div>
+      ) : null}
+    </section>
+  )
+}
+
+/** A settings field: a choice, a switch, or text / number / list / structured text committed on blur or Enter. */
+function Field({ field, value, error, disabled, onCommit }: { field: StepField; value: unknown; error?: string; disabled: boolean; onCommit: (v: unknown) => void }) {
+  const words = useLabels(researchStepWords, undefined)
+  const rt = useSteps()
+  const { locale } = useFlowLocale()
+  const current = value === undefined || value === null ? '' : typeof value === 'object' ? '' : String(value)
+  const options = useMemo(() => {
+    const values = [...(field.options ?? [])]
+    if (current && !values.includes(current)) values.unshift(current)
+    return values.map((v) => ({ value: v, label: words[`option.${v}`] ?? v }))
+  }, [field.options, current, words])
+  const label = field.label ?? field.key
+  const req = field.required ? { required: true } : {}
+  if (field.type === 'choice') {
+    return (
+      <div className="ty-flow-side__field">
+        <ListboxSelect label={label} options={options} value={current || null} disabled={disabled} {...req} {...(error ? { errorMessage: error } : {})} onChange={(v) => v !== current && onCommit(v)} />
+      </div>
+    )
+  }
+  if (field.type === 'boolean') {
+    return (
+      <div className="ty-flow-side__field">
+        <Switch label={label} isSelected={value === true} disabled={disabled} onChange={(on) => onCommit(on)} {...(error ? { description: <span className="ty-flow-side__problem">{error}</span> } : {})} />
+      </div>
+    )
+  }
+  if (field.type === 'json') return <JsonDraft label={label} value={value} error={error} disabled={disabled} required={!!field.required} invalid={(detail) => fill(rt.words.invalidJson, { detail }, locale)} onCommit={onCommit} />
+  if (field.type === 'list') {
+    const text = Array.isArray(value) ? value.map(String).join(', ') : current
+    return (
+      <Draft
+        label={label}
+        value={text}
+        hint={rt.words.valuesHint}
+        error={error}
+        required={!!field.required}
+        disabled={disabled}
+        onCommit={(v) => {
+          const items = v.split(',').map((x) => x.trim()).filter(Boolean)
+          onCommit(items.length ? items : undefined)
+        }}
+      />
+    )
+  }
+  return (
+    <Draft
+      label={label}
+      value={current}
+      numeric={field.type === 'number'}
+      error={error}
+      required={!!field.required}
+      disabled={disabled}
+      onCommit={(v) => onCommit(v === '' ? undefined : field.type === 'number' && Number.isFinite(Number(v)) ? Number(v) : v)}
+    />
+  )
+}
+
+/** Structured text (JSON) committed when it leaves the field; text that does not parse stays with its error. */
+function JsonDraft({ label, value, error, disabled, required, invalid, onCommit }: { label: string; value: unknown; error?: string; disabled: boolean; required: boolean; invalid: (detail: string) => string; onCommit: (v: unknown) => void }) {
+  const text = value === undefined ? '' : JSON.stringify(value, null, 2)
+  const [draft, setDraft] = useState(text)
+  const [parseError, setParseError] = useState<string | null>(null)
+  useEffect(() => {
+    setDraft(text)
+    setParseError(null)
+  }, [text])
+  const commit = () => {
+    const t = draft.trim()
+    if (!t) {
+      setParseError(null)
+      if (value !== undefined) onCommit(undefined)
+      return
+    }
+    try {
+      const parsed: unknown = JSON.parse(t)
+      setParseError(null)
+      if (JSON.stringify(parsed) !== JSON.stringify(value)) onCommit(parsed)
+    } catch (e) {
+      setParseError(invalid(e instanceof Error ? e.message : String(e)))
+    }
+  }
+  const shown = parseError ?? error
+  return (
+    <div className="ty-flow-side__field" onBlur={commit}>
+      <TextArea label={label} value={draft} onChange={setDraft} monospace autoGrow rows={3} maxRows={12} disabled={disabled} {...(required ? { required: true } : {})} {...(shown ? { errorMessage: shown } : {})} />
+    </div>
+  )
+}
+
+/** A text field that reports its value when it loses focus or on Enter (one undo step per edit). */
+function Draft({ label, value, placeholder, numeric, hint, error, required, disabled, onCommit }: { label: string; value: string; placeholder?: string; numeric?: boolean; hint?: string; error?: string; required?: boolean; disabled: boolean; onCommit: (v: string) => void }) {
+  const [draft, setDraft] = useState(value)
+  useEffect(() => setDraft(value), [value])
+  const commit = () => {
+    if (draft.trim() !== value) onCommit(draft.trim())
+  }
+  return (
+    <div
+      className="ty-flow-side__field"
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') commit()
+      }}
+    >
+      <TextField
+        label={label}
+        value={draft}
+        onChange={setDraft}
+        onBlur={commit}
+        disabled={disabled}
+        {...(placeholder ? { placeholder } : {})}
+        {...(numeric ? { inputType: 'number' as const } : {})}
+        {...(hint ? { hint } : {})}
+        {...(error ? { errorMessage: error } : {})}
+        {...(required ? { required: true } : {})}
+      />
+    </div>
+  )
+}

package/src/flow/steps/IssueBar.tsx

@@ -0,0 +1,58 @@
+// IssueBar: a strip at the top of the canvas while any link carries a shape
+// its receiving step does not take. It says which step expects what and
+// receives what, and offers the repair in one press: swap the step for one of
+// the same kind that takes what arrives, insert a bridging step, or unlink.
+
+import { TriangleAlert } from 'lucide-react'
+import { Button } from '../../index'
+import { fill, useFlowLocale } from '../internal/labels'
+import { ShapeChip } from './ShapeChip'
+import { useSteps } from './StepsContext'
+import type { WiringIssue } from './wiring'
+
+export interface IssueBarProps {
+  issues: readonly WiringIssue[]
+  nameOf: (nodeId: string) => string
+  locked?: boolean
+  onRepair: (issue: WiringIssue) => void
+  /** Moves to the step with the problem. */
+  onShow?: (nodeId: string) => void
+}
+
+export function IssueBar({ issues, nameOf, locked, onRepair, onShow }: IssueBarProps) {
+  const rt = useSteps()
+  const w = rt.words
+  const { locale } = useFlowLocale()
+  const first = issues[0]
+  if (!first) return <p className="ty-visually-hidden" role="status" />
+  const names = { from: nameOf(first.sourceId), to: nameOf(first.nodeId) }
+  const stepName = (id: string) => rt.byId.get(id)?.name ?? id
+  const fix =
+    first.repair.kind === 'replace'
+      ? fill(w.fixReplace, { step: stepName(first.repair.stepId) }, locale)
+      : first.repair.kind === 'insert'
+        ? fill(w.fixInsert, { step: stepName(first.repair.stepId), ...names }, locale)
+        : fill(w.fixUnlink, names, locale)
+  return (
+    <div className="ty-issue-bar" data-ty-surface-chrome="">
+      <TriangleAlert className="ty-issue-bar__icon" aria-hidden="true" focusable="false" />
+      <p className="ty-issue-bar__text" role="status">
+        <strong>{fill(w.issueCount, { count: issues.length }, locale)}:</strong>{' '}
+        {onShow ? (
+          <button type="button" className="ty-issue-bar__link" onClick={() => onShow(first.nodeId)}>
+            {fill(w.issueSentence, { to: names.to }, locale)}
+          </button>
+        ) : (
+          fill(w.issueSentence, { to: names.to }, locale)
+        )}{' '}
+        <ShapeChip shapes={first.expects} words={rt.shapes} /> {w.andGets}{' '}
+        {first.gets ? <ShapeChip shapes={[first.gets]} words={rt.shapes} /> : w.nothing}.
+      </p>
+      {!locked ? (
+        <Button className="ty-issue-bar__fix" variant="secondary" size="compact" onPress={() => onRepair(first)}>
+          {fix}
+        </Button>
+      ) : null}
+    </div>
+  )
+}

package/src/flow/steps/ShapeChip.tsx

@@ -0,0 +1,41 @@
+// Shape chips: a data shape as glyph + word on its tone (never colour alone),
+// and the "takes → gives" line of a step.
+
+import { ArrowRight } from 'lucide-react'
+import type { HTMLAttributes } from 'react'
+import type { DataShape, ShapeWords } from './shapes'
+import type { StepEditorWords } from './stepLabels'
+
+export interface ShapeChipProps extends HTMLAttributes<HTMLSpanElement> {
+  shapes: readonly DataShape[]
+  words: ShapeWords
+}
+
+/** One outlined chip in the shape's colour; several accepted shapes share it ("records / table"). */
+export function ShapeChip({ shapes, words, className, ...rest }: ShapeChipProps) {
+  return (
+    <span {...rest} className={['ty-shape-chip', className].filter(Boolean).join(' ')} data-shape={shapes.length === 1 ? shapes[0] : 'several'}>
+      {shapes.map((s, i) => (
+        <span key={s} className="ty-shape-chip__word" data-shape={s}>
+          {i > 0 ? '/' : ''}
+          {words[s]}
+        </span>
+      ))}
+    </span>
+  )
+}
+
+/** "records → table" (or "start → records" for a source step). */
+export function ShapeFlow({ inputs, output, words, labels, bare = false }: { inputs: ReadonlyArray<readonly DataShape[]>; output: DataShape | null; words: ShapeWords; labels: Pick<StepEditorWords, 'inputs' | 'output' | 'nothing' | 'origin'>; bare?: boolean }) {
+  // Inputs taking the same shapes show once ("table" for a join of two tables).
+  const distinct = inputs.filter((a, i) => inputs.findIndex((b) => b.join() === a.join()) === i)
+  return (
+    <span className="ty-shape-flow">
+      <span className="ty-visually-hidden">{labels.inputs}: </span>
+      {distinct.length ? distinct.map((accepts, i) => <ShapeChip key={i} shapes={accepts} words={words} />) : <span className={bare ? 'ty-visually-hidden' : 'ty-shape-flow__origin'}>{labels.origin}</span>}
+      <ArrowRight className="ty-shape-flow__arrow" aria-hidden="true" focusable="false" />
+      <span className="ty-visually-hidden">{labels.output}: </span>
+      {output ? <ShapeChip shapes={[output]} words={words} /> : <span className="ty-shape-flow__none">{labels.nothing}</span>}
+    </span>
+  )
+}