@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/steps/StepCard.tsx

@@ -0,0 +1,139 @@
+// StepCard: a research step on the canvas (250×86). Typed input chips ride
+// the top edge and the output chip the bottom edge, both from the inline
+// start; they are the connection handles. The body names the kind and the
+// title beside an icon tile, with the run badge, then one mono line: the
+// configuration summary, or the wiring problem in amber. A selected, editable
+// step shows "+" on the middle of its bottom edge (add after).
+
+import { Check, CircleAlert, LoaderCircle, Plus } from 'lucide-react'
+import { useId, useRef } from 'react'
+import { Button as AriaButton } from 'react-aria-components'
+import { fill, useFlowLocale } from '../internal/labels'
+import type { FlowNodeProps } from '../nodes/types'
+import { useNodeResult } from '../state/editorState'
+import { useSurface } from '../surface/SurfaceContext'
+import { ShapeChip } from './ShapeChip'
+import { shapeList, type DataShape } from './shapes'
+import { settingProblems, specOfNode, summaryLine } from './researchSteps'
+import { useSteps } from './StepsContext'
+import { inPort, OUT_PORT } from './wiring'
+
+export const STEP_CARD_SIZE = Object.freeze({ width: 250, height: 86 })
+
+/** Where input `index` of `count` meets the top edge (0..1): centred, spread when several. */
+export const alongEdge = (index: number, count: number) => (count <= 1 ? 0.5 : 0.35 + (0.3 * index) / (count - 1))
+
+export function StepCard({ node, locked, selected, preview, onConfigure }: FlowNodeProps) {
+  const rt = useSteps()
+  const { locale } = useFlowLocale()
+  const surface = useSurface()
+  const result = useNodeResult(node.id)
+  const addRef = useRef<HTMLButtonElement>(null)
+  const describedBy = useId()
+  const spec = specOfNode(node, rt.byId)
+  const w = rt.words
+  const title = (typeof node.data.label === 'string' && node.data.label) || spec?.name || node.kind
+  const kindWord = spec ? rt.shelves.find((s) => s.id === spec.verb)?.title ?? spec.verb : node.kind
+  const line = spec ? summaryLine(spec, node.data, locale) : null
+  const issues = rt.issues.get(node.id) ?? []
+  const Icon = spec?.icon
+  const run = result?.status === 'success' ? 'ok' : result?.status === 'running' ? 'running' : result?.status === 'error' ? 'failed' : null
+  const runWord = run === 'ok' ? w.runOk : run === 'running' ? w.runRunning : run === 'failed' ? w.runFailed : null
+  const settings = Object.entries(settingProblems(spec, node.data, rt.problems.get(node.id)))
+  const problems = [
+    ...issues.map((i) => fill(w.mismatch, { expects: shapeList(i.expects, rt.shapes), gets: i.gets ? rt.shapes[i.gets] : w.nothing }, locale)),
+    ...(settings.length ? [w.configIncomplete] : []),
+  ]
+  const editable = !locked && !preview
+  const inputs = spec?.inputs ?? []
+  const output = spec?.output ?? null
+
+  const port = (role: 'source' | 'target', id: string) => {
+    const target = surface.connectTarget?.nodeId === node.id && surface.connecting && surface.connecting.role !== role ? (surface.connectTarget.valid ? 'valid' : 'invalid') : undefined
+    return {
+      'data-role': role,
+      ...(target ? { 'data-target': target } : {}),
+      ...(preview || locked ? {} : { 'data-ty-port': '', 'data-ty-port-node': node.id, 'data-ty-port-id': id, 'data-ty-port-role': role }),
+    }
+  }
+
+  return (
+    <div className="ty-step" data-selected={selected ? 'true' : undefined} data-issue={problems.length ? 'true' : undefined} data-run={run ?? undefined}>
+      {inputs.length ? (
+        <span className="ty-step__ports" data-edge="in">
+          {inputs.map((accepts, i) => (
+            <span key={i} className="ty-step__port" {...port('target', inPort(i))}>
+              <ShapeChip shapes={accepts as DataShape[]} words={rt.shapes} aria-hidden="true" />
+            </span>
+          ))}
+        </span>
+      ) : null}
+      <AriaButton
+        className="ty-step__body"
+        data-ty-node-focus=""
+        aria-label={`${kindWord}: ${title}`}
+        aria-describedby={describedBy}
+        onPress={() => {
+          if (surface.justDragged()) return
+          onConfigure?.(node.id)
+        }}
+      >
+        <span className="ty-step__head">
+          <span className="ty-step__tile" aria-hidden="true">
+            {Icon ? <Icon focusable="false" /> : null}
+          </span>
+          <span className="ty-step__names">
+            <span className="ty-step__kind">{kindWord}</span>
+            <span className="ty-step__title" title={title} dir="auto">
+              {title}
+            </span>
+          </span>
+          {runWord ? (
+            <span className="ty-step__run" data-run={run} aria-hidden="true">
+              {run === 'ok' ? <Check focusable="false" /> : run === 'running' ? <LoaderCircle focusable="false" /> : <CircleAlert focusable="false" />}
+              {runWord}
+            </span>
+          ) : null}
+        </span>
+        {problems.length ? (
+          <span className="ty-step__line" data-problem="true" aria-hidden="true">
+            {problems[0]}
+          </span>
+        ) : (
+          <span className="ty-step__line" data-empty={line ? undefined : 'true'} dir="auto">
+            {line ?? w.notSet}
+          </span>
+        )}
+      </AriaButton>
+      <span id={describedBy} className="ty-visually-hidden">
+        {[
+          inputs.length ? `${w.inputs}: ${inputs.map((a) => shapeList(a, rt.shapes)).join(', ')}` : null,
+          output ? `${w.output}: ${rt.shapes[output]}` : null,
+          runWord,
+          ...problems,
+        ]
+          .filter(Boolean)
+          .join('. ')}
+      </span>
+      {output ? (
+        <span className="ty-step__ports" data-edge="out">
+          <span className="ty-step__port" {...port('source', OUT_PORT)}>
+            <ShapeChip shapes={[output]} words={rt.shapes} aria-hidden="true" />
+          </span>
+        </span>
+      ) : null}
+      {editable && selected && output && rt.addAfter ? (
+        <AriaButton
+          ref={addRef}
+          className="ty-step__add"
+          data-ty-surface-chrome=""
+          data-ty-add-after={node.id}
+          aria-label={fill(w.addAfter, { name: title }, locale)}
+          onPress={() => addRef.current && rt.addAfter?.(node.id, addRef.current)}
+        >
+          <Plus aria-hidden="true" focusable="false" />
+        </AriaButton>
+      ) : null}
+    </div>
+  )
+}

package/src/flow/steps/StepListView.tsx

@@ -0,0 +1,152 @@
+// StepListView: the flow as a numbered list, the keyboard view of the canvas
+// (toggled from the dock). ↑↓ move between steps, Alt+↑↓ reorder, A adds
+// after the current step, Enter opens its settings. An "add a step here" row
+// follows the current step; each row has a "…" menu.
+
+import { ArrowDown, ArrowUp, Ellipsis, Plus, Settings2, Trash2 } from 'lucide-react'
+import { useEffect, useRef, useState, type KeyboardEvent } from 'react'
+import { ActionMenu, Button } from '../../index'
+import { fill, useFlowLocale } from '../internal/labels'
+import type { FlowNode } from '../model/types'
+import { ShapeFlow } from './ShapeChip'
+import { specOfNode, summaryLine } from './researchSteps'
+import { useSteps } from './StepsContext'
+
+export interface StepListViewProps {
+  /** Steps in reading order. */
+  nodes: readonly FlowNode[]
+  locked?: boolean
+  /** Step that holds focus when the view opens. */
+  activeId?: string | null
+  onConfigure: (id: string) => void
+  onMove: (id: string, towards: -1 | 1) => void
+  onRemove: (id: string) => void
+  onAddAfter: (id: string, trigger: HTMLElement) => void
+  onActiveChange?: (id: string) => void
+}
+
+export function StepListView({ nodes, locked, activeId, onConfigure, onMove, onRemove, onAddAfter, onActiveChange }: StepListViewProps) {
+  const rt = useSteps()
+  const w = rt.words
+  const { locale } = useFlowLocale()
+  const start = Math.max(0, nodes.findIndex((n) => n.id === activeId))
+  const [at, setAt] = useState(start)
+  const rows = useRef(new Map<string, HTMLButtonElement>())
+  const pending = useRef<string | null>(null)
+  const current = nodes[Math.min(at, nodes.length - 1)]
+
+  // After a reorder the moved step keeps focus at its new place.
+  useEffect(() => {
+    if (!pending.current) return
+    const i = nodes.findIndex((n) => n.id === pending.current)
+    const el = rows.current.get(pending.current)
+    pending.current = null
+    if (i >= 0) setAt(i)
+    el?.focus()
+  }, [nodes])
+
+  const focusAt = (i: number) => {
+    const n = nodes[i]
+    if (!n) return
+    setAt(i)
+    rows.current.get(n.id)?.focus()
+    onActiveChange?.(n.id)
+  }
+
+  const onKey = (e: KeyboardEvent<HTMLButtonElement>, i: number, n: FlowNode) => {
+    const step = e.key === 'ArrowDown' ? 1 : e.key === 'ArrowUp' ? -1 : 0
+    if (step && e.altKey) {
+      e.preventDefault()
+      if (locked || !nodes[i + step]) return
+      pending.current = n.id
+      onMove(n.id, step)
+    } else if (step) {
+      e.preventDefault()
+      focusAt(i + step)
+    } else if (e.key === 'Home' || e.key === 'End') {
+      e.preventDefault()
+      focusAt(e.key === 'Home' ? 0 : nodes.length - 1)
+    } else if ((e.key === 'a' || e.key === 'A') && !e.metaKey && !e.ctrlKey && !e.altKey && !locked) {
+      e.preventDefault()
+      onAddAfter(n.id, e.currentTarget)
+    }
+  }
+
+  return (
+    <section className="ty-flow-list" aria-labelledby="ty-flow-list-title">
+      <h2 id="ty-flow-list-title" className="ty-visually-hidden">
+        {w.listTitle}
+      </h2>
+      <p className="ty-visually-hidden" id="ty-flow-list-hint">
+        {w.listHint}
+      </p>
+      <ol className="ty-flow-list__rows">
+        {nodes.map((n, i) => {
+          const spec = specOfNode(n, rt.byId)
+          const title = (typeof n.data.label === 'string' && n.data.label) || spec?.name || n.kind
+          const line = spec ? summaryLine(spec, n.data, locale) : null
+          const Icon = spec?.icon
+          const here = n.id === current?.id
+          return [
+            <li key={n.id} className="ty-flow-list__row" data-current={here ? 'true' : undefined}>
+              <span className="ty-flow-list__number" aria-hidden="true">
+                {new Intl.NumberFormat(locale).format(i + 1)}
+              </span>
+              <button
+                ref={(el) => {
+                  if (el) rows.current.set(n.id, el)
+                  else rows.current.delete(n.id)
+                }}
+                type="button"
+                className="ty-flow-list__main"
+                tabIndex={here ? 0 : -1}
+                aria-describedby="ty-flow-list-hint"
+                onFocus={() => {
+                  setAt(i)
+                  onActiveChange?.(n.id)
+                }}
+                onClick={() => onConfigure(n.id)}
+                onKeyDown={(e) => onKey(e, i, n)}
+              >
+                <span className="ty-flow-list__tile" aria-hidden="true">
+                  {Icon ? <Icon focusable="false" /> : null}
+                </span>
+                <span className="ty-flow-list__title-text" dir="auto">{title}</span>
+                <span className="ty-flow-list__line" dir="auto">{line ?? w.notSet}</span>
+                {spec && !spec.primitive ? <ShapeFlow inputs={spec.inputs} output={spec.output} words={rt.shapes} labels={w} bare /> : null}
+              </button>
+              {!locked ? (
+                <ActionMenu
+                  label={fill(w.more, { name: title }, locale)}
+                  trigger={<Button variant="quiet" size="compact" shape="circle" iconOnly accessibleLabel={fill(w.more, { name: title }, locale)} leadingIcon={<Ellipsis />} />}
+                  items={[
+                    { id: 'configure', label: w.configure, icon: Settings2 },
+                    { id: 'up', label: w.moveUp, icon: ArrowUp, disabled: i === 0 },
+                    { id: 'down', label: w.moveDown, icon: ArrowDown, disabled: i === nodes.length - 1 },
+                    { type: 'separator' },
+                    { id: 'remove', label: w.remove, icon: Trash2, tone: 'danger' },
+                  ]}
+                  onAction={(id) => {
+                    if (id === 'configure') onConfigure(n.id)
+                    else if (id === 'up' || id === 'down') {
+                      pending.current = n.id
+                      onMove(n.id, id === 'up' ? -1 : 1)
+                    } else if (id === 'remove') onRemove(n.id)
+                  }}
+                />
+              ) : null}
+            </li>,
+            here && !locked ? (
+              <li key={`${n.id}-add`} className="ty-flow-list__add">
+                <button type="button" className="ty-flow-list__add-button" onClick={(e) => onAddAfter(n.id, e.currentTarget)}>
+                  <Plus aria-hidden="true" focusable="false" />
+                  {w.addHere}
+                </button>
+              </li>
+            ) : null,
+          ]
+        })}
+      </ol>
+    </section>
+  )
+}

package/src/flow/steps/StepPalette.tsx

@@ -0,0 +1,194 @@
+// StepPalette: research steps shelved by verb. A search field ("/" jumps to
+// it), a filter (all, without AI, recent), then one list per shelf with its
+// purpose. Each entry shows its typed "takes → gives" chips; AI steps carry a
+// dashed "AI" tag and are unavailable when the project allows no agents.
+// Shelves with nothing to show are left out; engine primitives sit on a
+// folded shelf. Enter or a tap places a step; a drag drops it on the canvas.
+
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Button as AriaButton, Disclosure, DisclosurePanel, GridList, GridListItem, Heading, Input, Label, SearchField, ToggleButton, ToggleButtonGroup, useDragAndDrop, useFilter, type Key } from 'react-aria-components'
+import { ChevronDown, GripVertical, Search } from 'lucide-react'
+import { fill, useFlowLocale } from '../internal/labels'
+import { ShapeFlow } from './ShapeChip'
+import type { ReadyShelf, ReadyStep } from './researchSteps'
+import { useSteps } from './StepsContext'
+
+/** Drag payload type of a palette step. */
+export const STEP_MEDIA_TYPE = 'application/x-tympan-step'
+
+/** A second, empty drag type that names the step, readable while dragging over (payloads are not). */
+export const stepDragType = (stepId: string) => `${STEP_MEDIA_TYPE}-${stepId.toLowerCase()}`
+
+/** The step id a drag names, if any. */
+export function stepOfDrag(types: readonly string[]): string | null {
+  const prefix = `${STEP_MEDIA_TYPE}-`
+  const hit = types.find((t) => t.startsWith(prefix))
+  return hit ? hit.slice(prefix.length) : null
+}
+
+export type PaletteFilter = 'all' | 'no-ai' | 'recent'
+
+export interface StepPaletteProps {
+  onPlace: (stepId: string) => void
+  /** Step ids placed lately, newest first. */
+  recent?: readonly string[]
+  /** Which step is being dragged (null when the drag ends). */
+  onDragChange?: (stepId: string | null) => void
+  className?: string
+}
+
+const isTyping = (el: EventTarget | null) => el instanceof HTMLElement && !!el.closest('input, textarea, select, [contenteditable="true"]')
+
+export function StepPalette({ onPlace, recent = [], onDragChange, className }: StepPaletteProps) {
+  const rt = useSteps()
+  const w = rt.words
+  const { locale } = useFlowLocale()
+  const { contains } = useFilter({ sensitivity: 'base' })
+  const [query, setQuery] = useState('')
+  const [filter, setFilter] = useState<PaletteFilter>('all')
+  const fieldRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== '/' || e.metaKey || e.ctrlKey || e.altKey || isTyping(e.target)) return
+      e.preventDefault()
+      fieldRef.current?.focus()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [])
+
+  const keep = (s: ReadyStep) => {
+    if (query && !contains(`${s.name} ${s.description}`, query)) return false
+    if (filter === 'no-ai' && s.usesAI) return false
+    if (filter === 'recent' && !recent.includes(s.id)) return false
+    return true
+  }
+  const shelves = useMemo(() => {
+    const out: ReadyShelf[] = []
+    for (const sh of rt.shelves) {
+      const steps = sh.steps.filter(keep)
+      if (filter === 'recent') steps.sort((a, b) => recent.indexOf(a.id) - recent.indexOf(b.id))
+      if (steps.length) out.push({ ...sh, steps })
+    }
+    return out
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rt.shelves, query, filter, recent, contains])
+
+  const emptyWord = filter === 'recent' && !query ? w.noRecent : fill(w.noMatch, { query }, locale)
+
+  return (
+    <section className={['ty-step-palette', className].filter(Boolean).join(' ')} aria-label={w.paletteTitle}>
+      <div className="ty-step-palette__top">
+        <SearchField className="ty-step-palette__search" value={query} onChange={setQuery}>
+          <Label className="ty-visually-hidden">{w.search}</Label>
+          <Search className="ty-step-palette__search-icon" aria-hidden="true" focusable="false" />
+          <Input ref={fieldRef} className="ty-step-palette__input" placeholder={w.search} aria-keyshortcuts="/" />
+          <kbd className="ty-step-palette__key" title={w.searchKey}>
+            /
+          </kbd>
+        </SearchField>
+        <ToggleButtonGroup
+          className="ty-step-palette__filters"
+          aria-label={w.show}
+          selectionMode="single"
+          disallowEmptySelection
+          selectedKeys={[filter]}
+          onSelectionChange={(keys) => {
+            const next = [...keys][0]
+            if (next) setFilter(next as PaletteFilter)
+          }}
+        >
+          <ToggleButton id="all" className="ty-step-palette__filter">
+            {w.all}
+          </ToggleButton>
+          <ToggleButton id="no-ai" className="ty-step-palette__filter">
+            {w.noAI}
+          </ToggleButton>
+          <ToggleButton id="recent" className="ty-step-palette__filter">
+            {w.recent}
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="ty-step-palette__shelves">
+        {!rt.aiAllowed ? <p className="ty-step-palette__note">{w.aiOff}</p> : null}
+        {shelves.length ? (
+          shelves.map((sh) =>
+            sh.folded && !query ? (
+              <Disclosure key={sh.id} className="ty-step-palette__shelf" data-folded="true">
+                <div className="ty-step-palette__shelf-head">
+                  <Heading level={3} className="ty-step-palette__shelf-title">
+                    <AriaButton slot="trigger" className="ty-step-palette__fold">
+                      <ChevronDown className="ty-step-palette__chevron" aria-hidden="true" focusable="false" />
+                      {sh.title}
+                    </AriaButton>
+                  </Heading>
+                  {sh.purpose ? <span className="ty-step-palette__purpose">{sh.purpose}</span> : null}
+                </div>
+                <DisclosurePanel>
+                  <ShelfList shelf={sh} onPlace={onPlace} {...(onDragChange ? { onDragChange } : {})} />
+                </DisclosurePanel>
+              </Disclosure>
+            ) : (
+              <section key={sh.id} className="ty-step-palette__shelf" aria-labelledby={`ty-shelf-${sh.id}`}>
+                <div className="ty-step-palette__shelf-head">
+                  <h3 id={`ty-shelf-${sh.id}`} className="ty-step-palette__shelf-title">
+                    {sh.title}
+                  </h3>
+                  {sh.purpose ? <span className="ty-step-palette__purpose">{sh.purpose}</span> : null}
+                </div>
+                <ShelfList shelf={sh} onPlace={onPlace} {...(onDragChange ? { onDragChange } : {})} />
+              </section>
+            ),
+          )
+        ) : (
+          <p className="ty-step-palette__empty">{emptyWord}</p>
+        )}
+      </div>
+    </section>
+  )
+}
+
+function ShelfList({ shelf, onPlace, onDragChange }: { shelf: ReadyShelf; onPlace: (id: string) => void; onDragChange?: (id: string | null) => void }) {
+  const rt = useSteps()
+  const w = rt.words
+  const blocked = (s: ReadyStep) => !!s.usesAI && !rt.aiAllowed
+  const { dragAndDropHooks } = useDragAndDrop({
+    getItems: (keys) =>
+      shelf.steps
+        .filter((s) => keys.has(s.id))
+        .map((s) => ({
+          [STEP_MEDIA_TYPE]: JSON.stringify({ stepId: s.id }),
+          [stepDragType(s.id)]: '',
+          'text/plain': s.name,
+        })),
+    onDragStart: (e) => onDragChange?.(String([...e.keys][0] ?? '')),
+    onDragEnd: () => onDragChange?.(null),
+  })
+  const disabled: Key[] = shelf.steps.filter(blocked).map((s) => s.id)
+  return (
+    <GridList className="ty-step-palette__list" aria-label={shelf.title} items={shelf.steps} disabledKeys={disabled} dragAndDropHooks={dragAndDropHooks} onAction={(key) => onPlace(String(key))}>
+      {(s) => {
+        const Icon = s.icon
+        return (
+          <GridListItem id={s.id} textValue={s.name} className="ty-step-palette__item" data-ai={s.usesAI ? 'true' : undefined}>
+            <AriaButton slot="drag" className="ty-step-palette__grip" aria-label={fill(w.dragItem, { name: s.name })}>
+              <GripVertical aria-hidden="true" focusable="false" />
+            </AriaButton>
+            <span className="ty-step-palette__tile" aria-hidden="true">
+              <Icon focusable="false" />
+            </span>
+            <span className="ty-step-palette__name">
+              {s.name}
+              {s.usesAI ? <span className="ty-step-palette__ai">{w.ai}</span> : null}
+            </span>
+            <span className="ty-step-palette__about" title={s.description} dir="auto">
+              {blocked(s) ? w.aiOff : s.description}
+            </span>
+            {s.primitive ? null : <ShapeFlow inputs={s.inputs} output={s.output} words={rt.shapes} labels={w} />}
+          </GridListItem>
+        )
+      }}
+    </GridList>
+  )
+}

package/src/flow/steps/StepsContext.tsx

@@ -0,0 +1,70 @@
+// What the step parts share inside one editor: the catalog with its words,
+// whether AI steps are allowed, the current wiring issues and the "add after"
+// action. The editor provides it; stand-alone parts fall back to defaults.
+
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import { useLabels } from '../internal/labels'
+import { readyCatalog, researchStepCatalog, researchStepWords, type ReadyShelf, type ReadyStep, type StepCatalog } from './researchSteps'
+import { shapeCountWords, shapeWords, type ShapeWords } from './shapes'
+import { stepEditorWords, type StepEditorWords } from './stepLabels'
+import type { WiringIssue } from './wiring'
+
+export interface StepsRuntime {
+  shelves: ReadyShelf[]
+  steps: ReadyStep[]
+  byId: ReadonlyMap<string, ReadyStep>
+  aiAllowed: boolean
+  words: StepEditorWords
+  shapes: ShapeWords
+  /** Counted shape messages (ICU, `n`). */
+  counts: ShapeWords
+  /** Wiring issues by receiving node id. */
+  issues: ReadonlyMap<string, WiringIssue[]>
+  /** Settings problems the host reported, by node id then field key. */
+  problems: ReadonlyMap<string, Record<string, string>>
+  /** Opens the add picker after a node, anchored to `trigger`. */
+  addAfter?: (nodeId: string, trigger: HTMLElement) => void
+}
+
+const Ctx = createContext<StepsRuntime | null>(null)
+const EMPTY_ISSUES: ReadonlyMap<string, WiringIssue[]> = new Map()
+const EMPTY_PROBLEMS: ReadonlyMap<string, Record<string, string>> = new Map()
+
+export interface StepsProviderProps {
+  catalog?: StepCatalog
+  aiAllowed?: boolean
+  issues?: ReadonlyMap<string, WiringIssue[]>
+  problems?: ReadonlyMap<string, Record<string, string>>
+  addAfter?: (nodeId: string, trigger: HTMLElement) => void
+  words?: Partial<StepEditorWords>
+  children: ReactNode
+}
+
+/** Catalog words resolved for the provider locale. */
+export function useReadyCatalog(catalog: StepCatalog = researchStepCatalog) {
+  const words = useLabels(researchStepWords, undefined)
+  return useMemo(() => readyCatalog(catalog, words), [catalog, words])
+}
+
+export function StepsProvider({ catalog, aiAllowed = true, issues, problems, addAfter, words, children }: StepsProviderProps) {
+  const ready = useReadyCatalog(catalog)
+  const w = useLabels(stepEditorWords, words)
+  const shapes = useLabels(shapeWords, undefined)
+  const counts = useLabels(shapeCountWords, undefined)
+  const value = useMemo<StepsRuntime>(
+    () => ({ ...ready, aiAllowed, words: w, shapes, counts, issues: issues ?? EMPTY_ISSUES, problems: problems ?? EMPTY_PROBLEMS, ...(addAfter ? { addAfter } : {}) }),
+    [ready, aiAllowed, w, shapes, counts, issues, problems, addAfter],
+  )
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>
+}
+
+
+/** The runtime of the nearest StepsProvider, or the built-in catalog. */
+export function useSteps(): StepsRuntime {
+  const got = useContext(Ctx)
+  const ready = useReadyCatalog()
+  const words = useLabels(stepEditorWords, undefined)
+  const shapes = useLabels(shapeWords, undefined)
+  const counts = useLabels(shapeCountWords, undefined)
+  return got ?? { ...ready, aiAllowed: true, words, shapes, counts, issues: EMPTY_ISSUES, problems: EMPTY_PROBLEMS }
+}

package/src/flow/steps/index.ts

@@ -0,0 +1,15 @@
+// Research steps: typed steps shelved by research verb and the editor parts
+// built on them (palette, add picker, card, issue bar, side panel, list view).
+export * from './shapes'
+export * from './researchSteps'
+export * from './stepLabels'
+export * from './wiring'
+export { StepsProvider, useSteps, useReadyCatalog, type StepsRuntime, type StepsProviderProps } from './StepsContext'
+export { ShapeChip, ShapeFlow, type ShapeChipProps } from './ShapeChip'
+export { StepCard, STEP_CARD_SIZE, alongEdge } from './StepCard'
+export { StepPalette, STEP_MEDIA_TYPE, stepDragType, stepOfDrag, type StepPaletteProps, type PaletteFilter } from './StepPalette'
+export { AddStepPicker, type AddStepPickerProps } from './AddStepPicker'
+export { IssueBar, type IssueBarProps } from './IssueBar'
+export { FlowSidePanel, type FlowSidePanelProps, type FlowFacts, type OutputPreview } from './FlowSidePanel'
+export { StepListView, type StepListViewProps } from './StepListView'
+export { stepToolItems, type StepToolOptions } from './stepTools'