@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/steps/researchSteps.ts

@@ -0,0 +1,269 @@
+// Research steps: what a researcher adds to an analysis flow, shelved by
+// research verb (take in, prepare, analyse, decide, give out). A host may pass
+// its own shelves and steps; the built-in set below is the default. Engine
+// primitives (start, end, branch) stay reachable on a collapsed shelf.
+
+import { Bot, ChartColumn, CornerDownRight, FileText, Filter, Flag, GitBranch, Hash, Lock, Play, Scale, Shapes, Sigma, Split, SunMedium, Table2, UserCheck } from 'lucide-react'
+import type { IconComponent } from '../../index'
+import { resolveIcon } from '../catalog/icons'
+import { defineLabels, fill } from '../internal/labels'
+import type { FlowNode } from '../model/types'
+import type { DataShape } from './shapes'
+
+/** A value field of a step's configuration form. */
+export interface StepField {
+  key: string
+  /**
+   * `choice` picks one of `options` (the current value is always offered); `boolean` is a switch; `list` is a list of
+   * short values typed with commas; `json` is structured text (objects, lists of objects, bindings).
+   */
+  type: 'text' | 'number' | 'choice' | 'boolean' | 'list' | 'json'
+  /** Visible label; the built-in word for `key`, else the key. */
+  label?: string
+  /** Option values of a choice; each shows its built-in word `option.<value>` when there is one. */
+  options?: readonly string[]
+  /** The setting must be filled (marked on the field). */
+  required?: boolean
+  /** A number setting takes whole numbers only. */
+  integer?: boolean
+}
+
+export interface StepSpec {
+  id: string
+  /** Shelf id (research verb). */
+  verb: string
+  icon: IconComponent | string
+  /** Node kind created on the canvas: 'step' unless an engine primitive. */
+  kind?: string
+  name?: string
+  description?: string
+  /** Accepted shapes per input, in port order (empty for a source step). */
+  inputs: ReadonlyArray<readonly DataShape[]>
+  output: DataShape | null
+  usesAI?: boolean
+  /** ICU template over the node data: the one-line summary on the card. */
+  summary?: string
+  fields?: readonly StepField[]
+  /**
+   * Where the fields live in the node data: at its top level (default), or inside one object of it (e.g. `config`,
+   * as the host's graph stores a step's configuration). The card's summary reads the same place.
+   */
+  configIn?: string
+  /** Problems of the step's settings, as the host words them, by field key ('' for the whole configuration). */
+  check?: (values: Record<string, unknown>) => Record<string, string>
+  defaults?: Record<string, unknown>
+  /** Engine primitive: no typed ports. */
+  primitive?: boolean
+}
+
+export interface VerbShelf {
+  id: string
+  title?: string
+  purpose?: string
+  /** Starts folded (the engine primitives). */
+  folded?: boolean
+}
+
+export interface StepCatalog {
+  shelves: readonly VerbShelf[]
+  steps: readonly StepSpec[]
+}
+
+/** A spec with its words for the current locale. */
+export interface ReadyStep extends Omit<StepSpec, 'icon'> {
+  icon: IconComponent
+  kind: string
+  name: string
+  description: string
+}
+
+export interface ReadyShelf extends VerbShelf {
+  title: string
+  purpose: string
+  steps: ReadyStep[]
+}
+
+// ---- built-in words ------------------------------------------------------
+
+type Words = Record<string, string>
+
+export const researchStepWords = defineLabels<Words>('researchSteps', {
+  en: {
+    'shelf.input': 'Input', 'shelf.input.purpose': 'Where the data comes in',
+    'shelf.prepare': 'Prepare', 'shelf.prepare.purpose': 'Get the data ready',
+    'shelf.analyse': 'Analyse', 'shelf.analyse.purpose': 'Calculate',
+    'shelf.decide': 'Decide', 'shelf.decide.purpose': 'Recorded choices',
+    'shelf.output': 'Output', 'shelf.output.purpose': 'What becomes citable',
+    'shelf.advanced': 'Advanced', 'shelf.advanced.purpose': 'Engine pieces: start, end and branch',
+    'frozen-edition': 'Frozen edition', 'frozen-edition.about': 'records of a citable edition', 'frozen-edition.line': '{edition} · {count, plural, one {# record} other {# records}}',
+    'dataset': 'Dataset', 'dataset.about': 'imported table, with codebook', 'dataset.line': '{name}',
+    'instrument-answers': 'Instrument answers', 'instrument-answers.about': 'submitted answers, by assignment', 'instrument-answers.line': '{instrument}',
+    'filter': 'Filter', 'filter.about': 'keeps what meets a condition', 'filter.line': '{before} → {after} records',
+    'join': 'Join', 'join.about': 'joins two inputs on a key', 'join.line': 'on {key}',
+    'group': 'Group', 'group.about': 'groups by fields and summarises', 'group.line': 'by {keys}',
+    'recode': 'Recode', 'recode.about': 'maps values to categories', 'recode.line': '{column}: {scheme}',
+    'describe': 'Counts and descriptives', 'describe.about': 'frequencies, mean, median, CI', 'describe.line': '{counts}',
+    'reliability': 'Reliability', 'reliability.about': 'Krippendorff\'s α, Gwet\'s AC1', 'reliability.line': '{measure}',
+    'composite-index': 'Composite index', 'composite-index.about': 'declared × lived, gap per dimension', 'composite-index.line': '{formula}',
+    'person-decision': 'Decision by a person', 'person-decision.about': 'a person chooses between options', 'person-decision.line': '{question}',
+    'agent-decision': 'Decision by an agent', 'agent-decision.about': 'typed choice with probabilities', 'agent-decision.line': '{model}',
+    'rule': 'Rule', 'rule.about': 'deterministic condition, no model', 'rule.line': '{rule}',
+    'citable-table': 'Citable table', 'citable-table.about': 'with edition, version and hash', 'citable-table.line': '{caption}',
+    'citable-chart': 'Citable chart', 'citable-chart.about': 'Vega-Lite generated from the run', 'citable-chart.line': '{caption}',
+    'manuscript-number': 'Number for the manuscript', 'manuscript-number.about': 'links a value to a sentence', 'manuscript-number.line': '{name}',
+    'start': 'Start', 'start.about': 'Where the engine begins',
+    'end': 'End', 'end.about': 'Where the engine stops',
+    'branch': 'Branch', 'branch.about': 'Follows one of two paths',
+    'field.edition': 'Edition', 'field.count': 'Records', 'field.name': 'Name', 'field.instrument': 'Instrument', 'field.criterion': 'Condition', 'field.before': 'Records in', 'field.after': 'Records out', 'field.key': 'Key', 'field.keys': 'Group by', 'field.aggregate': 'Summary per group', 'field.column': 'Column', 'field.scheme': 'Scheme', 'field.counts': 'Counts', 'field.measure': 'Measure', 'field.formula': 'Formula', 'field.question': 'Question', 'field.model': 'Model', 'field.rule': 'Rule', 'field.caption': 'Caption',
+    'option.count': 'count of records', 'option.mean': 'mean', 'option.median': 'median',
+  },
+  'pt-BR': {
+    'shelf.input': 'Entrada', 'shelf.input.purpose': 'Onde os dados entram',
+    'shelf.prepare': 'Preparar', 'shelf.prepare.purpose': 'Deixar os dados prontos',
+    'shelf.analyse': 'Analisar', 'shelf.analyse.purpose': 'Calcular',
+    'shelf.decide': 'Decidir', 'shelf.decide.purpose': 'Escolhas registradas',
+    'shelf.output': 'Saída', 'shelf.output.purpose': 'O que vira citável',
+    'shelf.advanced': 'Avançado', 'shelf.advanced.purpose': 'Peças do motor: início, fim e desvio',
+    'frozen-edition': 'Edição congelada', 'frozen-edition.about': 'registros de uma edição citável', 'frozen-edition.line': '{edition} · {count, plural, one {# registro} other {# registros}}',
+    'dataset': 'Conjunto de dados', 'dataset.about': 'tabela importada, com codebook', 'dataset.line': '{name}',
+    'instrument-answers': 'Respostas de instrumento', 'instrument-answers.about': 'respostas enviadas, por atribuição', 'instrument-answers.line': '{instrument}',
+    'filter': 'Filtrar', 'filter.about': 'mantém o que atende a uma condição', 'filter.line': '{before} → {after} registros',
+    'join': 'Juntar', 'join.about': 'une duas entradas por uma chave', 'join.line': 'por {key}',
+    'group': 'Agrupar', 'group.about': 'agrupa por campos e resume', 'group.line': 'por {keys}',
+    'recode': 'Recodificar', 'recode.about': 'mapeia valores para categorias', 'recode.line': '{column}: {scheme}',
+    'describe': 'Contagem e descritivas', 'describe.about': 'frequências, média, mediana, IC', 'describe.line': '{counts}',
+    'reliability': 'Confiabilidade', 'reliability.about': 'α de Krippendorff, AC1 de Gwet', 'reliability.line': '{measure}',
+    'composite-index': 'Índice composto', 'composite-index.about': 'declarado × vivido, lacuna por dimensão', 'composite-index.line': '{formula}',
+    'person-decision': 'Decisão por pessoa', 'person-decision.about': 'uma pessoa escolhe entre opções', 'person-decision.line': '{question}',
+    'agent-decision': 'Decisão por agente', 'agent-decision.about': 'escolha tipada com probabilidades', 'agent-decision.line': '{model}',
+    'rule': 'Regra', 'rule.about': 'condição determinística, sem modelo', 'rule.line': '{rule}',
+    'citable-table': 'Tabela citável', 'citable-table.about': 'com edição, versão e hash', 'citable-table.line': '{caption}',
+    'citable-chart': 'Gráfico citável', 'citable-chart.about': 'Vega-Lite gerado da execução', 'citable-chart.line': '{caption}',
+    'manuscript-number': 'Número para o manuscrito', 'manuscript-number.about': 'liga um valor a uma frase', 'manuscript-number.line': '{name}',
+    'start': 'Início', 'start.about': 'Onde o motor começa',
+    'end': 'Fim', 'end.about': 'Onde o motor para',
+    'branch': 'Desvio', 'branch.about': 'Segue por um de dois caminhos',
+    'field.edition': 'Edição', 'field.count': 'Registros', 'field.name': 'Nome', 'field.instrument': 'Instrumento', 'field.criterion': 'Condição', 'field.before': 'Registros de entrada', 'field.after': 'Registros de saída', 'field.key': 'Chave', 'field.keys': 'Agrupar por', 'field.aggregate': 'Resumo por grupo', 'field.column': 'Coluna', 'field.scheme': 'Esquema', 'field.counts': 'Contagens', 'field.measure': 'Medida', 'field.formula': 'Fórmula', 'field.question': 'Pergunta', 'field.model': 'Modelo', 'field.rule': 'Regra', 'field.caption': 'Legenda',
+    'option.count': 'contagem de registros', 'option.mean': 'média', 'option.median': 'mediana',
+  },
+  es: {
+    'shelf.input': 'Entrada', 'shelf.input.purpose': 'Dónde entran los datos',
+    'shelf.prepare': 'Preparar', 'shelf.prepare.purpose': 'Dejar los datos listos',
+    'shelf.analyse': 'Analizar', 'shelf.analyse.purpose': 'Calcular',
+    'shelf.decide': 'Decidir', 'shelf.decide.purpose': 'Elecciones registradas',
+    'shelf.output': 'Salida', 'shelf.output.purpose': 'Lo que se vuelve citable',
+    'shelf.advanced': 'Avanzado', 'shelf.advanced.purpose': 'Piezas del motor: inicio, fin y desvío',
+    'frozen-edition': 'Edición congelada', 'frozen-edition.about': 'registros de una edición citable', 'frozen-edition.line': '{edition} · {count, plural, one {# registro} other {# registros}}',
+    'dataset': 'Conjunto de datos', 'dataset.about': 'tabla importada, con libro de códigos', 'dataset.line': '{name}',
+    'instrument-answers': 'Respuestas de instrumento', 'instrument-answers.about': 'respuestas enviadas, por asignación', 'instrument-answers.line': '{instrument}',
+    'filter': 'Filtrar', 'filter.about': 'conserva lo que cumple una condición', 'filter.line': '{before} → {after} registros',
+    'join': 'Unir', 'join.about': 'une dos entradas por una clave', 'join.line': 'por {key}',
+    'group': 'Agrupar', 'group.about': 'agrupa por campos y resume', 'group.line': 'por {keys}',
+    'recode': 'Recodificar', 'recode.about': 'asigna valores a categorías', 'recode.line': '{column}: {scheme}',
+    'describe': 'Conteo y descriptivos', 'describe.about': 'frecuencias, media, mediana, IC', 'describe.line': '{counts}',
+    'reliability': 'Fiabilidad', 'reliability.about': 'α de Krippendorff, AC1 de Gwet', 'reliability.line': '{measure}',
+    'composite-index': 'Índice compuesto', 'composite-index.about': 'declarado × vivido, brecha por dimensión', 'composite-index.line': '{formula}',
+    'person-decision': 'Decisión de una persona', 'person-decision.about': 'una persona elige entre opciones', 'person-decision.line': '{question}',
+    'agent-decision': 'Decisión de un agente', 'agent-decision.about': 'elección tipada con probabilidades', 'agent-decision.line': '{model}',
+    'rule': 'Regla', 'rule.about': 'condición determinista, sin modelo', 'rule.line': '{rule}',
+    'citable-table': 'Tabla citable', 'citable-table.about': 'con edición, versión y hash', 'citable-table.line': '{caption}',
+    'citable-chart': 'Gráfico citable', 'citable-chart.about': 'Vega-Lite generado de la ejecución', 'citable-chart.line': '{caption}',
+    'manuscript-number': 'Número para el manuscrito', 'manuscript-number.about': 'vincula un valor a una frase', 'manuscript-number.line': '{name}',
+    'start': 'Inicio', 'start.about': 'Donde empieza el motor',
+    'end': 'Fin', 'end.about': 'Donde se detiene el motor',
+    'branch': 'Desvío', 'branch.about': 'Sigue uno de dos caminos',
+    'field.edition': 'Edición', 'field.count': 'Registros', 'field.name': 'Nombre', 'field.instrument': 'Instrumento', 'field.criterion': 'Condición', 'field.before': 'Registros de entrada', 'field.after': 'Registros de salida', 'field.key': 'Clave', 'field.keys': 'Agrupar por', 'field.aggregate': 'Resumen por grupo', 'field.column': 'Columna', 'field.scheme': 'Esquema', 'field.counts': 'Conteos', 'field.measure': 'Medida', 'field.formula': 'Fórmula', 'field.question': 'Pregunta', 'field.model': 'Modelo', 'field.rule': 'Regla', 'field.caption': 'Leyenda',
+    'option.count': 'conteo de registros', 'option.mean': 'media', 'option.median': 'mediana',
+  },
+})
+
+// ---- built-in catalog ----------------------------------------------------
+
+const f = (...keys: string[]): StepField[] => keys.map((key) => ({ key, type: key === 'count' || key === 'before' || key === 'coders' ? 'number' : 'text' }))
+const R = ['records'] as const
+const T = ['table'] as const
+
+const BUILT_IN: StepCatalog = {
+  shelves: [{ id: 'input' }, { id: 'prepare' }, { id: 'analyse' }, { id: 'decide' }, { id: 'output' }, { id: 'advanced', folded: true }],
+  steps: [
+    { id: 'frozen-edition', verb: 'input', icon: Lock, inputs: [], output: 'records', fields: f('edition', 'count') },
+    { id: 'dataset', verb: 'input', icon: Table2, inputs: [], output: 'table', fields: f('name') },
+    { id: 'instrument-answers', verb: 'input', icon: FileText, inputs: [], output: 'table', fields: f('instrument') },
+    { id: 'filter', verb: 'prepare', icon: Filter, inputs: [R], output: 'records', fields: f('criterion', 'before', 'after') },
+    { id: 'join', verb: 'prepare', icon: CornerDownRight, inputs: [T, T], output: 'table', fields: f('key') },
+    { id: 'group', verb: 'prepare', icon: Split, inputs: [R], output: 'table', fields: [{ key: 'keys', type: 'choice' }, { key: 'aggregate', type: 'choice', options: ['count', 'mean', 'median'] }] },
+    { id: 'recode', verb: 'prepare', icon: SunMedium, inputs: [R], output: 'records', fields: f('column', 'scheme') },
+    { id: 'describe', verb: 'analyse', icon: Sigma, inputs: [T], output: 'table', fields: f('counts') },
+    { id: 'reliability', verb: 'analyse', icon: ChartColumn, inputs: [T], output: 'number', fields: f('measure') },
+    { id: 'composite-index', verb: 'analyse', icon: Shapes, inputs: [T], output: 'table', fields: f('formula') },
+    { id: 'person-decision', verb: 'decide', icon: UserCheck, inputs: [R], output: 'decision', fields: f('question') },
+    { id: 'agent-decision', verb: 'decide', icon: Bot, inputs: [R], output: 'decision', usesAI: true, fields: f('model') },
+    { id: 'rule', verb: 'decide', icon: Scale, inputs: [R], output: 'decision', fields: f('rule') },
+    { id: 'citable-table', verb: 'output', icon: Table2, inputs: [T], output: 'table', fields: f('caption') },
+    { id: 'citable-chart', verb: 'output', icon: ChartColumn, inputs: [T], output: 'chart', fields: f('caption') },
+    { id: 'manuscript-number', verb: 'output', icon: Hash, inputs: [['number']], output: 'number', fields: f('name') },
+    { id: 'start', verb: 'advanced', icon: Play, kind: 'start', inputs: [], output: null, primitive: true },
+    { id: 'end', verb: 'advanced', icon: Flag, kind: 'end', inputs: [], output: null, primitive: true },
+    { id: 'branch', verb: 'advanced', icon: GitBranch, kind: 'if-else', inputs: [], output: null, primitive: true },
+  ],
+}
+export const researchStepCatalog: StepCatalog = Object.freeze(BUILT_IN)
+
+/** Node kind research steps are drawn with. */
+export const STEP_KIND = 'step'
+
+/** Words for a catalog in one locale: host text wins, then the built-in words, then the id. */
+export function readyCatalog(catalog: StepCatalog, words: Words): { shelves: ReadyShelf[]; steps: ReadyStep[]; byId: Map<string, ReadyStep> } {
+  const steps: ReadyStep[] = catalog.steps.map((s) => ({
+    ...s,
+    icon: typeof s.icon === 'string' ? resolveIcon(s.icon) : s.icon,
+    kind: s.kind ?? STEP_KIND,
+    name: s.name ?? words[s.id] ?? s.id,
+    description: s.description ?? words[`${s.id}.about`] ?? '',
+    ...(s.summary ?? words[`${s.id}.line`] ? { summary: s.summary ?? words[`${s.id}.line`] } : {}),
+    ...(s.fields ? { fields: s.fields.map((x) => ({ ...x, label: x.label ?? words[`field.${x.key}`] ?? x.key })) } : {}),
+  }))
+  const shelves = catalog.shelves.map((sh) => ({
+    ...sh,
+    title: sh.title ?? words[`shelf.${sh.id}`] ?? sh.id,
+    purpose: sh.purpose ?? words[`shelf.${sh.id}.purpose`] ?? '',
+    steps: steps.filter((s) => s.verb === sh.id),
+  }))
+  return { shelves, steps, byId: new Map(steps.map((s) => [s.id, s])) }
+}
+
+/** The spec a node was made from (research steps and the engine primitives). */
+export function specOfNode(node: Pick<FlowNode, 'kind' | 'data'>, byId: ReadonlyMap<string, ReadyStep>): ReadyStep | undefined {
+  if (node.kind === STEP_KIND) return typeof node.data.stepId === 'string' ? byId.get(node.data.stepId) : undefined
+  for (const s of byId.values()) if (s.primitive && s.kind === node.kind) return s
+  return undefined
+}
+
+const SLOT = /\{(\w+)/g
+
+/** The values a step's fields edit: the node data, or the object of it named by `configIn`. */
+export function settingsOf(step: Pick<ReadyStep, 'configIn'> | undefined, data: Record<string, unknown>): Record<string, unknown> {
+  if (!step?.configIn) return data
+  const inner = data[step.configIn]
+  return inner && typeof inner === 'object' && !Array.isArray(inner) ? (inner as Record<string, unknown>) : {}
+}
+
+/** Problems of a node's settings by field key: the spec's own check, then what the host reports for this node. */
+export function settingProblems(step: Pick<ReadyStep, 'configIn' | 'check'> | undefined, data: Record<string, unknown>, reported?: Record<string, string>): Record<string, string> {
+  return { ...(step?.check ? step.check(settingsOf(step, data)) : {}), ...(reported ?? {}) }
+}
+
+/** The card's one-line summary (a host `line` wins), or null while a value it names is not set. */
+export function summaryLine(step: Pick<ReadyStep, 'summary' | 'configIn'>, data: Record<string, unknown>, locale: string): string | null {
+  if (typeof data.line === 'string' && data.line) return data.line
+  if (!step.summary) return null
+  const values: Record<string, string | number> = {}
+  const settings = settingsOf(step, data)
+  for (const [, key] of step.summary.matchAll(SLOT)) {
+    const v = data[key!] ?? settings[key!]
+    if (v === undefined || v === null || v === '') return null
+    if (typeof v === 'string' || typeof v === 'number') values[key!] = v
+    else return null
+  }
+  return fill(step.summary, values, locale)
+}

package/src/flow/steps/shapes.ts

@@ -0,0 +1,46 @@
+// Data shapes that travel between research steps. Every shape has a word, a
+// glyph and a tone, so a port chip never relies on colour alone.
+
+import { ChartColumn, Hash, Rows3, Split, Table2 } from 'lucide-react'
+import type { IconComponent } from '../../index'
+import { defineLabels, fill } from '../internal/labels'
+
+export type DataShape = 'records' | 'table' | 'number' | 'chart' | 'decision'
+
+export const DATA_SHAPES: readonly DataShape[] = ['records', 'table', 'number', 'chart', 'decision']
+
+export type ShapeWords = Record<DataShape, string>
+
+export const shapeWords = defineLabels<ShapeWords>('dataShapes', {
+  en: { records: 'records', table: 'table', number: 'number', chart: 'chart', decision: 'decision' },
+  'pt-BR': { records: 'registros', table: 'tabela', number: 'número', chart: 'gráfico', decision: 'decisão' },
+  es: { records: 'registros', table: 'tabla', number: 'número', chart: 'gráfico', decision: 'decisión' },
+})
+
+/** Glyph of each shape (lists and menus; the chips carry the word only). */
+export const SHAPE_LOOK: Readonly<Record<DataShape, { icon: IconComponent; tone: string }>> = Object.freeze({
+  records: { icon: Rows3, tone: 'categorical-1' },
+  table: { icon: Table2, tone: 'categorical-3' },
+  number: { icon: Hash, tone: 'categorical-5' },
+  chart: { icon: ChartColumn, tone: 'categorical-6' },
+  decision: { icon: Split, tone: 'categorical-7' },
+})
+
+/** "records / table": the shapes one input accepts, in the reader's words. */
+export function shapeList(shapes: readonly DataShape[], words: ShapeWords): string {
+  return shapes.map((s) => words[s]).join(' / ')
+}
+
+/** Counted shapes ("1 table · 2 charts"), one ICU message per shape. */
+export const shapeCountWords = defineLabels<ShapeWords>('dataShapeCounts', {
+  en: { records: '{n, plural, one {# record set} other {# record sets}}', table: '{n, plural, one {# table} other {# tables}}', number: '{n, plural, one {# number} other {# numbers}}', chart: '{n, plural, one {# chart} other {# charts}}', decision: '{n, plural, one {# decision} other {# decisions}}' },
+  'pt-BR': { records: '{n, plural, one {# conjunto de registros} other {# conjuntos de registros}}', table: '{n, plural, one {# tabela} other {# tabelas}}', number: '{n, plural, one {# número} other {# números}}', chart: '{n, plural, one {# gráfico} other {# gráficos}}', decision: '{n, plural, one {# decisão} other {# decisões}}' },
+  es: { records: '{n, plural, one {# conjunto de registros} other {# conjuntos de registros}}', table: '{n, plural, one {# tabla} other {# tablas}}', number: '{n, plural, one {# número} other {# números}}', chart: '{n, plural, one {# gráfico} other {# gráficos}}', decision: '{n, plural, one {# decisión} other {# decisiones}}' },
+})
+
+/** "1 table · 1 chart" for a list of output shapes, in shape order. */
+export function shapeCounts(shapes: readonly DataShape[], words: ShapeWords, locale: string): string {
+  return DATA_SHAPES.filter((s) => shapes.includes(s))
+    .map((s) => fill(words[s], { n: shapes.filter((x) => x === s).length }, locale))
+    .join(' · ')
+}

package/src/flow/steps/stepLabels.ts

@@ -0,0 +1,160 @@
+// Interface words of the research-step editor parts (palette, add picker,
+// card, issue bar, side panel, list view, dock items).
+
+import { defineLabels } from '../internal/labels'
+
+export interface StepEditorWords {
+  paletteTitle: string
+  search: string
+  searchKey: string
+  show: string
+  all: string
+  noAI: string
+  recent: string
+  ai: string
+  aiOff: string
+  noMatch: string
+  noRecent: string
+  dragHint: string
+  dragItem: string
+  addNamed: string
+  pickerAfter: string
+  pickerBetween: string
+  pickerFree: string
+  pickerSearch: string
+  accepts: string
+  nothingAccepts: string
+  results: string
+  addAfter: string
+  notSet: string
+  /** Card line when the step has configuration problems. */
+  configIncomplete: string
+  /** Error of a structured (JSON) setting that does not parse. */
+  invalidJson: string
+  /** Hint of a list setting. */
+  valuesHint: string
+  runOk: string
+  runRunning: string
+  runFailed: string
+  mismatch: string
+  nothing: string
+  inputs: string
+  origin: string
+  pickerOnly: string
+  pickerKeys: string
+  eyebrowFlow: string
+  eyebrowStep: string
+  runsOn: string
+  nothingSelected: string
+  saved: string
+  issueSentence: string
+  andGets: string
+  fixReplace: string
+  stepName: string
+  moreStep: string
+  output: string
+  dropHere: string
+  issueCount: string
+  fixInsert: string
+  fixUnlink: string
+  flowOk: string
+  summaryTitle: string
+  version: string
+  runs: string
+  stepCount: string
+  usesAI: string
+  yes: string
+  no: string
+  deterministic: string
+  seed: string
+  citable: string
+  none: string
+  runFlow: string
+  validate: string
+  validOk: string
+  stepTitle: string
+  preview: string
+  noPreview: string
+  testStep: string
+  remove: string
+  backToSummary: string
+  listTitle: string
+  listHint: string
+  addHere: string
+  more: string
+  moveUp: string
+  moveDown: string
+  configure: string
+  toolAdd: string
+  toolArrange: string
+  toolFit: string
+  toolList: string
+  toolSearch: string
+  toolSelect: string
+  toolPan: string
+  added: string
+  moved: string
+}
+
+export const stepEditorWords = defineLabels<StepEditorWords>('stepEditor', {
+  en: {
+    origin: 'start', pickerOnly: 'Only steps that take', pickerKeys: '↑↓ choose · Enter adds and links · Esc closes', eyebrowFlow: 'Flow', eyebrowStep: 'Selected step', runsOn: 'Runs on', nothingSelected: 'Nothing selected. Click a step to configure it, or use + to add one.', saved: 'saved', issueSentence: '“{to}” expects', andGets: 'and gets', fixReplace: 'Replace with {step}', stepName: 'Step name', moreStep: 'More for this step', 
+    paletteTitle: 'Steps', search: 'Find a step', searchKey: 'Shortcut: /', show: 'Show', all: 'All', noAI: 'Without AI', recent: 'Recent',
+    ai: 'AI', aiOff: 'AI is off in this project', noMatch: 'No step matches “{query}”', noRecent: 'Steps you add appear here', dragItem: 'Drag {name}',
+    dragHint: 'Drag onto the canvas or press Enter', addNamed: 'Add {name}',
+    pickerAfter: 'Add after “{name}”', pickerBetween: 'Insert between “{from}” and “{to}”', pickerFree: 'Add a step', pickerSearch: 'Find a step',
+    accepts: 'Takes {shape}', nothingAccepts: 'No step takes {shape}', results: '{count, plural, =0 {No steps} one {# step} other {# steps}}',
+    addAfter: 'Add a step after “{name}”', notSet: 'not configured', configIncomplete: 'configuration incomplete', invalidJson: 'Not valid JSON: {detail}', valuesHint: 'Separate the values with commas.', runOk: 'ok', runRunning: 'running', runFailed: 'failed',
+    mismatch: 'expects {expects}; gets {gets}', nothing: 'nothing', inputs: 'Takes', output: 'Gives', dropHere: 'Drop to add “{name}”',
+    issueCount: '{count, plural, one {# problem} other {# problems}}',
+    fixInsert: 'Insert “{step}” between “{from}” and “{to}”', fixUnlink: 'Remove the link from “{from}” to “{to}”', flowOk: 'Every link fits',
+    summaryTitle: 'Flow summary', version: 'Version', runs: 'Runs over the edition', stepCount: 'Steps', usesAI: 'Uses AI', yes: 'yes', no: 'no',
+    deterministic: 'Deterministic', seed: 'seed {seed}', citable: 'Citable outputs', none: 'none', runFlow: 'Run over the edition', validate: 'Validate flow',
+    validOk: 'No problems found', stepTitle: 'Title', preview: 'Output preview', noPreview: 'No preview yet. Test this step to see its output.',
+    testStep: 'Test this step', remove: 'Remove', backToSummary: 'Back to the summary',
+    listTitle: 'Flow steps', listHint: 'Arrows move, Alt+arrows reorder, A adds, Enter configures', addHere: 'Add a step here', more: 'More for “{name}”',
+    moveUp: 'Move up', moveDown: 'Move down', configure: 'Configure',
+    toolAdd: 'Add a step', toolArrange: 'Rearrange', toolFit: 'Fit to view', toolList: 'Show as list', toolSearch: 'Find a step', toolSelect: 'Select', toolPan: 'Move the view',
+    added: '{name} added', moved: '{name} moved to position {position}',
+  },
+  'pt-BR': {
+    origin: 'início', pickerOnly: 'Só passos que aceitam', pickerKeys: '↑↓ escolhe · Enter adiciona e liga · Esc fecha', eyebrowFlow: 'Fluxo', eyebrowStep: 'Passo selecionado', runsOn: 'Roda sobre', nothingSelected: 'Nada selecionado. Clique num passo para configurá-lo, ou use + para adicionar.', saved: 'salvo', issueSentence: '“{to}” espera', andGets: 'e recebe', fixReplace: 'Trocar por {step}', stepName: 'Nome do passo', moreStep: 'Mais ações do passo', 
+    paletteTitle: 'Passos', search: 'Buscar passo', searchKey: 'Atalho: /', show: 'Mostrar', all: 'Todos', noAI: 'Sem IA', recent: 'Recentes',
+    ai: 'IA', aiOff: 'IA desativada neste projeto', noMatch: 'Nenhum passo corresponde a “{query}”', noRecent: 'Os passos que você adicionar aparecem aqui', dragItem: 'Arrastar {name}',
+    dragHint: 'Arraste para o canvas ou pressione Enter', addNamed: 'Adicionar {name}',
+    pickerAfter: 'Adicionar depois de “{name}”', pickerBetween: 'Inserir entre “{from}” e “{to}”', pickerFree: 'Adicionar passo', pickerSearch: 'Buscar passo',
+    accepts: 'Recebe {shape}', nothingAccepts: 'Nenhum passo recebe {shape}', results: '{count, plural, =0 {Nenhum passo} one {# passo} other {# passos}}',
+    addAfter: 'Adicionar passo depois de “{name}”', notSet: 'não configurado', configIncomplete: 'configuração incompleta', invalidJson: 'JSON inválido: {detail}', valuesHint: 'Separe os valores por vírgula.', runOk: 'ok', runRunning: 'rodando', runFailed: 'falhou',
+    mismatch: 'espera {expects}; recebe {gets}', nothing: 'nada', inputs: 'Recebe', output: 'Entrega', dropHere: 'Solte para adicionar “{name}”',
+    issueCount: '{count, plural, one {# problema} other {# problemas}}',
+    fixInsert: 'Inserir “{step}” entre “{from}” e “{to}”', fixUnlink: 'Remover a ligação de “{from}” para “{to}”', flowOk: 'Todas as ligações encaixam',
+    summaryTitle: 'Resumo do fluxo', version: 'Versão', runs: 'Execuções sobre a edição', stepCount: 'Passos', usesAI: 'Usa IA', yes: 'sim', no: 'não',
+    deterministic: 'Determinístico', seed: 'semente {seed}', citable: 'Saídas citáveis', none: 'nenhuma', runFlow: 'Executar sobre a edição', validate: 'Validar fluxo',
+    validOk: 'Nenhum problema encontrado', stepTitle: 'Título', preview: 'Prévia da saída', noPreview: 'Ainda sem prévia. Teste este passo para ver a saída.',
+    testStep: 'Testar este passo', remove: 'Remover', backToSummary: 'Voltar ao resumo',
+    listTitle: 'Passos do fluxo', listHint: 'Setas movem, Alt+setas reordenam, A adiciona, Enter configura', addHere: 'Adicionar passo aqui', more: 'Mais ações para “{name}”',
+    moveUp: 'Subir', moveDown: 'Descer', configure: 'Configurar',
+    toolAdd: 'Adicionar passo', toolArrange: 'Reorganizar', toolFit: 'Ajustar à tela', toolList: 'Ver como lista', toolSearch: 'Buscar passo', toolSelect: 'Selecionar', toolPan: 'Mover',
+    added: '{name} adicionado', moved: '{name} movido para a posição {position}',
+  },
+  es: {
+    origin: 'inicio', pickerOnly: 'Solo pasos que aceptan', pickerKeys: '↑↓ elige · Enter añade y enlaza · Esc cierra', eyebrowFlow: 'Flujo', eyebrowStep: 'Paso seleccionado', runsOn: 'Se ejecuta sobre', nothingSelected: 'Nada seleccionado. Haz clic en un paso para configurarlo, o usa + para añadir.', saved: 'guardado', issueSentence: '“{to}” espera', andGets: 'y recibe', fixReplace: 'Cambiar por {step}', stepName: 'Nombre del paso', moreStep: 'Más acciones del paso', 
+    paletteTitle: 'Pasos', search: 'Buscar paso', searchKey: 'Atajo: /', show: 'Mostrar', all: 'Todos', noAI: 'Sin IA', recent: 'Recientes',
+    ai: 'IA', aiOff: 'IA desactivada en este proyecto', noMatch: 'Ningún paso coincide con “{query}”', noRecent: 'Los pasos que añadas aparecen aquí', dragItem: 'Arrastrar {name}',
+    dragHint: 'Arrastra al lienzo o pulsa Enter', addNamed: 'Añadir {name}',
+    pickerAfter: 'Añadir después de “{name}”', pickerBetween: 'Insertar entre “{from}” y “{to}”', pickerFree: 'Añadir paso', pickerSearch: 'Buscar paso',
+    accepts: 'Recibe {shape}', nothingAccepts: 'Ningún paso recibe {shape}', results: '{count, plural, =0 {Ningún paso} one {# paso} other {# pasos}}',
+    addAfter: 'Añadir paso después de “{name}”', notSet: 'sin configurar', configIncomplete: 'configuración incompleta', invalidJson: 'JSON no válido: {detail}', valuesHint: 'Separa los valores con comas.', runOk: 'ok', runRunning: 'en curso', runFailed: 'falló',
+    mismatch: 'espera {expects}; recibe {gets}', nothing: 'nada', inputs: 'Recibe', output: 'Entrega', dropHere: 'Suelta para añadir “{name}”',
+    issueCount: '{count, plural, one {# problema} other {# problemas}}',
+    fixInsert: 'Insertar “{step}” entre “{from}” y “{to}”', fixUnlink: 'Quitar el enlace de “{from}” a “{to}”', flowOk: 'Todos los enlaces encajan',
+    summaryTitle: 'Resumen del flujo', version: 'Versión', runs: 'Ejecuciones sobre la edición', stepCount: 'Pasos', usesAI: 'Usa IA', yes: 'sí', no: 'no',
+    deterministic: 'Determinista', seed: 'semilla {seed}', citable: 'Salidas citables', none: 'ninguna', runFlow: 'Ejecutar sobre la edición', validate: 'Validar flujo',
+    validOk: 'No se encontraron problemas', stepTitle: 'Título', preview: 'Vista previa de la salida', noPreview: 'Aún sin vista previa. Prueba este paso para ver la salida.',
+    testStep: 'Probar este paso', remove: 'Quitar', backToSummary: 'Volver al resumen',
+    listTitle: 'Pasos del flujo', listHint: 'Flechas mueven, Alt+flechas reordenan, A añade, Enter configura', addHere: 'Añadir paso aquí', more: 'Más acciones para “{name}”',
+    moveUp: 'Subir', moveDown: 'Bajar', configure: 'Configurar',
+    toolAdd: 'Añadir paso', toolArrange: 'Reorganizar', toolFit: 'Ajustar a la vista', toolList: 'Ver como lista', toolSearch: 'Buscar paso', toolSelect: 'Seleccionar', toolPan: 'Mover',
+    added: '{name} añadido', moved: '{name} movido a la posición {position}',
+  },
+})

package/src/flow/steps/stepTools.ts

@@ -0,0 +1,37 @@
+// Dock items of the research-step editor, in three groups:
+// select, move | add a step (A), rearrange, fit | list view, find a step.
+
+import { Hand, ListOrdered, Maximize, MousePointer2, Network, Plus, Search } from 'lucide-react'
+import type { CanvasToolItem } from '../toolbar/canvasTools'
+import type { StepEditorWords } from './stepLabels'
+
+export interface StepToolOptions {
+  words: Pick<StepEditorWords, 'toolSelect' | 'toolPan' | 'toolAdd' | 'toolArrange' | 'toolFit' | 'toolList' | 'toolSearch'>
+  mode: 'select' | 'pan'
+  onModeChange: (mode: 'select' | 'pan') => void
+  /** Absent while the flow is locked. */
+  onAdd?: (() => void) | undefined
+  onArrange?: (() => void) | undefined
+  onFit: () => void
+  listView: boolean
+  onToggleList: () => void
+  onSearch: () => void
+}
+
+export function stepToolItems(o: StepToolOptions): CanvasToolItem[] {
+  const w = o.words
+  const pointer: CanvasToolItem[] = [
+    { id: 'select', label: w.toolSelect, icon: MousePointer2, kind: 'mode', pressed: o.mode === 'select', shortcut: 'V', group: 'mode', onPress: () => o.onModeChange('select') },
+    { id: 'pan', label: w.toolPan, icon: Hand, kind: 'mode', pressed: o.mode === 'pan', shortcut: 'H', group: 'mode', onPress: () => o.onModeChange('pan') },
+  ]
+  const shaping: CanvasToolItem[] = [
+    ...(o.onAdd ? [{ id: 'add-step', label: w.toolAdd, icon: Plus, kind: 'action' as const, shortcut: 'A', group: 'layout' as const, onPress: o.onAdd }] : []),
+    ...(o.onArrange ? [{ id: 'auto-layout', label: w.toolArrange, icon: Network, kind: 'action' as const, group: 'layout' as const, onPress: o.onArrange }] : []),
+    { id: 'fit', label: w.toolFit, icon: Maximize, kind: 'action', shortcut: 'Control+1', group: 'layout', onPress: o.onFit },
+  ]
+  const finding: CanvasToolItem[] = [
+    { id: 'list-view', label: w.toolList, icon: ListOrdered, kind: 'toggle', pressed: o.listView, group: 'find', onPress: o.onToggleList },
+    { id: 'search', label: w.toolSearch, icon: Search, kind: 'action', shortcut: 'Control+F', group: 'find', onPress: o.onSearch },
+  ]
+  return [...pointer, ...shaping, ...finding]
+}