@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/expressions/builder/ItemList.tsx

@@ -0,0 +1,72 @@
+// A list operand: numbered items, each drawn by the caller, with remove and
+// add. After a removal focus lands on the item that took the removed one's
+// place (its kind switch), or on "add item" when none did.
+
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import { Plus, Trash2 } from 'lucide-react'
+import { Button, Tag } from '../../../index'
+import { fill } from '../../internal/labels'
+import { groupName, SlotHeading, useBuilderEnv } from './shared'
+
+/** Where focus should go after items change; resolved once the DOM has updated. */
+function useFocusLanding(dependency: unknown) {
+  const [target, setTarget] = useState<number | null>(null)
+  const holders = useRef(new Map<number, HTMLElement>())
+  const fallback = useRef<HTMLButtonElement>(null)
+  useEffect(() => {
+    if (target === null) return
+    const holder = holders.current.get(target)
+    const radio = holder?.querySelector<HTMLInputElement>('input[type="radio"]:checked') ?? holder?.querySelector<HTMLInputElement>('input[type="radio"]')
+    ;(radio ?? fallback.current)?.focus()
+    setTarget(null)
+  }, [target, dependency])
+  const holderRef = (index: number) => (el: HTMLElement | null) => {
+    if (el) holders.current.set(index, el)
+    else holders.current.delete(index)
+  }
+  return { land: setTarget, holderRef, fallback }
+}
+
+export interface ItemListProps {
+  slotKey: string
+  items: unknown[]
+  depth: number
+  onItems: (items: unknown[]) => void
+  /** Draws item `index`; `switchRef` must reach its kind switch. */
+  drawItem: (args: { index: number; item: unknown; name: string; onItem: (v: unknown) => void; switchRef: (el: HTMLElement | null) => void }) => ReactNode
+}
+
+export function ItemList({ slotKey, items, depth, onItems, drawItem }: ItemListProps) {
+  const { words, locale } = useBuilderEnv()
+  const focus = useFocusLanding(items.length)
+  const remove = (index: number) => {
+    onItems(items.filter((_, j) => j !== index))
+    focus.land(index < items.length - 1 ? index : -1)
+  }
+  const rows = items.map((item, index) => (
+    <li key={index} className="ty-expr__item">
+      <span className="ty-expr__item-number" aria-hidden="true">
+        {index + 1}
+      </span>
+      <div className="ty-expr__item-body">
+        {drawItem({
+          index,
+          item,
+          name: fill(words.item, { n: index + 1 }),
+          onItem: (v) => onItems(items.map((x, j) => (j === index ? v : x))),
+          switchRef: focus.holderRef(index),
+        })}
+      </div>
+      <Button variant="quiet" size="compact" shape="circle" iconOnly accessibleLabel={fill(words.removeItem, { n: index + 1 })} leadingIcon={<Trash2 />} onPress={() => remove(index)} />
+    </li>
+  ))
+  return (
+    <div className="ty-expr__list" role="group" aria-label={groupName(words, slotKey, depth)}>
+      <SlotHeading slotKey={slotKey} trailing={<Tag size="small">{fill(words.itemCount, { count: items.length }, locale)}</Tag>} />
+      {rows.length ? <ol className="ty-expr__items">{rows}</ol> : null}
+      <Button ref={focus.fallback} variant="secondary" size="compact" leadingIcon={<Plus />} onPress={() => onItems([...items, { value: null }])}>
+        {words.addItem}
+      </Button>
+    </div>
+  )
+}

package/src/flow/expressions/builder/leaves.tsx

@@ -0,0 +1,94 @@
+// Leaf editors of the expression builder: reference chips, literal text,
+// plain parameters and raw JSON. None of them nests further.
+
+import { useEffect, useReducer, useRef, useState } from 'react'
+import { ToggleButton } from 'react-aria-components'
+import { ListboxSelect, TextArea, TextField } from '../../../index'
+import { fill } from '../../internal/labels'
+import { prettyJson, readLiteral, vocabularyOf, writeLiteral, type OperandSlotSpec } from '../model'
+import { useBuilderEnv } from './shared'
+
+export function ReferencePicker({ current, offered, onPick }: { current: string; offered: readonly string[]; onPick: (ref: string) => void }) {
+  const { words } = useBuilderEnv()
+  const chips = offered.map((ref) => (
+    <ToggleButton key={ref} className="ty-expr__chip" isSelected={ref === current} onChange={() => onPick(ref)}>
+      <code dir="ltr">{ref}</code>
+    </ToggleButton>
+  ))
+  return (
+    <div className="ty-expr__reference">
+      {chips.length ? (
+        <div className="ty-expr__chips" role="group" aria-label={words.references}>
+          {chips}
+        </div>
+      ) : null}
+      <TextField label={words.referencePath} value={current} onChange={onPick} className="ty-expr__mono" />
+    </div>
+  )
+}
+
+/**
+ * Text that mirrors a value without fighting the person typing: an outside
+ * change rewrites the text, the text's own echo does not.
+ */
+function useMirroredText(value: unknown, print: (v: unknown) => string) {
+  const [text, setText] = useState(() => print(value))
+  const lastSent = useRef<unknown>(value)
+  useEffect(() => {
+    if (JSON.stringify(lastSent.current) !== JSON.stringify(value)) {
+      lastSent.current = value
+      setText(print(value))
+    }
+    // print is stable per caller
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value])
+  return { text, setText, remember: (v: unknown) => (lastSent.current = v) }
+}
+
+/** Free text, read as structured data when it parses. */
+export function LiteralText({ value, onValue }: { value: unknown; onValue: (v: unknown) => void }) {
+  const { words } = useBuilderEnv()
+  const mirror = useMirroredText(value, writeLiteral)
+  return (
+    <TextField
+      label={words.literal}
+      hint={words.literalHint}
+      value={mirror.text}
+      onChange={(typed) => {
+        mirror.setText(typed)
+        onValue(mirror.remember(readLiteral(typed)))
+      }}
+    />
+  )
+}
+
+/** A plain parameter, or a friendly select when its vocabulary is known. */
+export function ParameterField({ slot, value, onValue }: { slot: OperandSlotSpec; value: unknown; onValue: (v: unknown) => void }) {
+  const { words } = useBuilderEnv()
+  const vocabulary = vocabularyOf(slot)
+  if (!vocabulary) {
+    return <TextField label={slot.key} value={value == null ? '' : String(value)} onChange={(t) => onValue(readLiteral(t))} />
+  }
+  const options = vocabulary.map((w) => ({ value: w, label: words.vocabulary[w] ?? w }))
+  return <ListboxSelect label={slot.key} value={typeof value === 'string' ? value : null} options={options} onChange={onValue} />
+}
+
+type RawState = { text: string; problem?: string }
+
+/** JSON for operands the builder cannot shape; a broken text keeps the last good value. */
+export function RawJson({ label, value, onValue }: { label: string; value: unknown; onValue: (v: unknown) => void }) {
+  const { words } = useBuilderEnv()
+  const [state, set] = useReducer((_: RawState, next: RawState) => next, value, (v): RawState => ({ text: prettyJson(v ?? {}) }))
+  const change = (text: string) => {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(text)
+    } catch (err) {
+      set({ text, problem: fill(words.rawError, { detail: err instanceof Error ? err.message : String(err) }) })
+      return
+    }
+    set({ text })
+    onValue(parsed)
+  }
+  return <TextArea label={label} monospace rows={4} value={state.text} errorMessage={state.problem} onChange={change} />
+}

package/src/flow/expressions/builder/shared.tsx

@@ -0,0 +1,55 @@
+// What every level of one expression builder shares (strings, catalog,
+// limits), plus the small helpers the levels use.
+
+import { createContext, useContext, type ReactNode } from 'react'
+import { fill } from '../../internal/labels'
+import type { ExpressionBuilderLabels } from '../labels'
+import type { ExpressionCatalog, LoopBinding, PickerEntry } from '../model'
+
+export interface BuilderEnv {
+  words: ExpressionBuilderLabels
+  locale: string
+  catalog: ExpressionCatalog | undefined
+  catalogPending: boolean
+  depthLimit: number
+  /** Palette below the root (always the full expression palette). */
+  innerPalette: PickerEntry[]
+}
+
+const EnvContext = createContext<BuilderEnv | null>(null)
+export const BuilderEnvProvider = EnvContext.Provider
+
+export function useBuilderEnv(): BuilderEnv {
+  const env = useContext(EnvContext)
+  if (!env) throw new Error('Expression builder parts must be inside ExpressionBuilder.')
+  return env
+}
+
+/** Name shown for a picker entry: its flattened verb when it has one, else the operation. */
+export function entryLabel(words: ExpressionBuilderLabels, entry: PickerEntry): string {
+  if (entry.verb) return words.vocabulary[entry.verb.value] ?? entry.verb.value
+  return words.operations[entry.op.name] ?? entry.op.name
+}
+
+/** Loop variables (engine identifiers) come first among the chips of their subtree. */
+export function chipsWithLoopNames(references: readonly string[], binds: readonly LoopBinding[] | undefined): string[] {
+  const extra = (binds ?? []).filter((b) => !references.includes(b))
+  return [...extra, ...references]
+}
+
+/** Accessible name of a group at `depth` (0-based) for operand `key`. */
+export function groupName(words: ExpressionBuilderLabels, key: string, depth: number): string {
+  return fill(words.level, { key, level: depth + 1 })
+}
+
+/** Header shared by operand groups: the key in mono and the level as text (depth never by colour). */
+export function SlotHeading({ slotKey, trailing }: { slotKey: string; trailing: ReactNode }) {
+  return (
+    <div className="ty-expr__slot-head">
+      <code className="ty-expr__slot-key" dir="ltr">
+        {slotKey}
+      </code>
+      {trailing}
+    </div>
+  )
+}

package/src/flow/expressions/builder/tree.tsx

@@ -0,0 +1,221 @@
+// The recursive part of the expression builder: an operation (picker plus its
+// operand slots) and an operand (kind switch plus the editor of that kind).
+// Operand kinds and slot kinds are both driven by descriptor tables.
+
+import { useMemo, useState, type ReactNode } from 'react'
+import { InlineNotice, ListboxSelect, SegmentedControl } from '../../../index'
+import { fill } from '../../internal/labels'
+import type { ExpressionBuilderLabels } from '../labels'
+import { EXPRESSION_FAMILIES, entryIdOf, findOperation, inferSlots, isLiteral, isOperation, isReference, seedOperation, type ExpressionNode, type OperandSlotSpec, type OperationNode, type PickerEntry } from '../model'
+import { ItemList } from './ItemList'
+import { LiteralText, ParameterField, RawJson, ReferencePicker } from './leaves'
+import { chipsWithLoopNames, entryLabel, groupName, SlotHeading, useBuilderEnv } from './shared'
+
+type OperandKind = 'operation' | 'reference' | 'literal'
+
+interface OperandEnv {
+  value: unknown
+  set: (v: ExpressionNode) => void
+  depth: number
+  refs: readonly string[]
+  palette: PickerEntry[]
+}
+
+/** The three shapes an expression operand can take: its switch label, its starter and its editor. */
+const OPERAND_KINDS: ReadonlyArray<{
+  kind: OperandKind
+  word: keyof ExpressionBuilderLabels
+  matches: (v: unknown) => boolean
+  starter: (e: OperandEnv) => ExpressionNode
+  editor: (e: OperandEnv) => ReactNode
+}> = [
+  {
+    kind: 'operation',
+    word: 'kindOperation',
+    matches: isOperation,
+    starter: (e) => (e.palette[0] ? seedOperation(e.palette[0]) : { operation: '' }),
+    editor: (e) => (
+      <div className="ty-expr__nested" data-depth={e.depth}>
+        <OperationEditor node={e.value as OperationNode} onNode={e.set} depth={e.depth} refs={e.refs} palette={e.palette} />
+      </div>
+    ),
+  },
+  {
+    kind: 'reference',
+    word: 'kindReference',
+    matches: isReference,
+    starter: (e) => ({ ref: e.refs[0] ?? '' }),
+    editor: (e) => <ReferencePicker current={(e.value as { ref: string }).ref} offered={e.refs} onPick={(ref) => e.set({ ref })} />,
+  },
+  {
+    kind: 'literal',
+    word: 'kindLiteral',
+    matches: () => true,
+    starter: () => ({ value: '' }),
+    editor: (e) => <LiteralText value={isLiteral(e.value) ? e.value.value : e.value} onValue={(v) => e.set({ value: v })} />,
+  },
+]
+
+const kindOf = (v: unknown) => OPERAND_KINDS.find((k) => k.matches(v))!
+
+export interface OperandEditorProps {
+  slotKey: string
+  value: unknown
+  onValue: (v: ExpressionNode) => void
+  depth: number
+  refs: readonly string[]
+  hint?: string
+  palette?: PickerEntry[]
+  switchRef?: (el: HTMLElement | null) => void
+}
+
+export function OperandEditor({ slotKey, value, onValue, depth, refs, hint, palette, switchRef }: OperandEditorProps) {
+  const { words, innerPalette } = useBuilderEnv()
+  const env: OperandEnv = { value, set: onValue, depth, refs, palette: palette ?? innerPalette }
+  const current = kindOf(value)
+  return (
+    <div className="ty-expr__slot" role="group" aria-label={groupName(words, slotKey, depth)} data-depth={depth}>
+      <SlotHeading
+        slotKey={slotKey}
+        trailing={
+          <span className="ty-expr__level" aria-hidden="true">
+            {depth + 1}
+          </span>
+        }
+      />
+      {hint ? <p className="ty-expr__hint">{hint}</p> : null}
+      <div ref={switchRef} className="ty-expr__kind">
+        <SegmentedControl
+          label={words.kindSwitch}
+          size="compact"
+          value={current.kind}
+          onChange={(k) => onValue(OPERAND_KINDS.find((d) => d.kind === k)!.starter(env))}
+          options={OPERAND_KINDS.map((d) => ({ value: d.kind, label: words[d.word] as string }))}
+        />
+      </div>
+      {current.editor(env)}
+    </div>
+  )
+}
+
+interface SlotEnv {
+  slot: OperandSlotSpec
+  value: unknown
+  set: (v: unknown) => void
+  depth: number
+  refs: string[]
+  words: ExpressionBuilderLabels
+}
+
+/** How each slot kind of an operation is edited. */
+const SLOT_EDITORS: Record<OperandSlotSpec['kind'], (s: SlotEnv) => ReactNode> = {
+  expression: (s) => (
+    <OperandEditor
+      slotKey={s.slot.key}
+      value={s.value}
+      onValue={s.set}
+      depth={s.depth + 1}
+      refs={s.refs}
+      {...(s.slot.binds?.length ? { hint: fill(s.words.loopHint, { names: s.slot.binds.map((b) => s.words.bindings[b]).join(', ') }) } : {})}
+    />
+  ),
+  list: (s) => (
+    <ItemList
+      slotKey={s.slot.key}
+      items={Array.isArray(s.value) ? s.value : []}
+      depth={s.depth}
+      onItems={s.set}
+      drawItem={({ item, name, onItem, switchRef }) => <OperandEditor slotKey={name} value={item} depth={s.depth + 1} refs={s.refs} onValue={onItem} switchRef={switchRef} />}
+    />
+  ),
+  param: (s) => <ParameterField slot={s.slot} value={s.value} onValue={s.set} />,
+  raw: (s) => <RawJson label={s.slot.key} value={s.value} onValue={s.set} />,
+}
+
+function SlotEditor({ slot, value, set, depth, refs }: { slot: OperandSlotSpec; value: unknown; set: (v: unknown) => void; depth: number; refs: readonly string[] }) {
+  const { words } = useBuilderEnv()
+  const scoped = useMemo(() => chipsWithLoopNames(refs, slot.binds), [refs, slot.binds])
+  return <>{SLOT_EDITORS[slot.kind]({ slot, value, set, depth, refs: scoped, words })}</>
+}
+
+export interface OperationEditorProps {
+  node: OperationNode | undefined
+  onNode: (n: ExpressionNode) => void
+  depth: number
+  refs: readonly string[]
+  palette: PickerEntry[]
+}
+
+/** An operation: at the depth limit a raw JSON slot; otherwise the picker and one editor per operand slot. */
+export function OperationEditor({ node, onNode, depth, refs, palette }: OperationEditorProps) {
+  const { words, catalog, depthLimit } = useBuilderEnv()
+  if (node && depth >= depthLimit) {
+    return (
+      <>
+        <InlineNotice tone="warning" urgency="none">
+          {words.depthLimit}
+        </InlineNotice>
+        <RawJson label={words.raw} value={node} onValue={(v) => onNode(v as ExpressionNode)} />
+      </>
+    )
+  }
+  const definition = node ? findOperation(catalog, node.operation) : undefined
+  const pickedId = node ? entryIdOf(node, palette) : null
+  // A flattened verb (add, subtract …) is chosen in the picker, not edited as a slot.
+  const hiddenSlot = palette.find((e) => e.id === pickedId)?.verb?.key
+  const slots = node ? (definition ? definition.operands : inferSlots(node)).filter((s) => s.key !== hiddenSlot) : []
+  const unknown = !!node && !!catalog && !definition && node.operation !== ''
+  return (
+    <div className="ty-expr__operation">
+      <OperationPicker palette={palette} pickedId={pickedId} onPick={(entry) => onNode(seedOperation(entry))} />
+      {unknown ? (
+        <InlineNotice tone="warning" urgency="none">
+          {fill(words.unknownOperation, { name: node!.operation })}
+        </InlineNotice>
+      ) : null}
+      {slots.map((slot) => (
+        <SlotEditor key={slot.key} slot={slot} value={node![slot.key]} depth={depth} refs={refs} set={(v) => onNode({ ...node!, [slot.key]: v })} />
+      ))}
+    </div>
+  )
+}
+
+/** Family, then operation. Picking another family selects that family's first operation. */
+function OperationPicker({ palette, pickedId, onPick }: { palette: PickerEntry[]; pickedId: string | null; onPick: (e: PickerEntry) => void }) {
+  const { words, catalogPending } = useBuilderEnv()
+  const families = EXPRESSION_FAMILIES.filter((f) => palette.some((e) => e.family === f))
+  const pickedFamily = palette.find((e) => e.id === pickedId)?.family
+  const [browsed, setBrowsed] = useState(pickedFamily ?? families[0])
+  if (catalogPending && palette.length === 0) {
+    return (
+      <p className="ty-expr__loading" role="status">
+        {words.loadingOperations}
+      </p>
+    )
+  }
+  const family = pickedFamily ?? browsed ?? families[0]
+  return (
+    <div className="ty-expr__picker">
+      <ListboxSelect
+        label={words.family}
+        value={family ?? null}
+        options={families.map((f) => ({ value: f, label: words.families[f] }))}
+        onChange={(f) => {
+          setBrowsed(f as typeof family)
+          const lead = palette.find((e) => e.family === f)
+          if (lead && f !== pickedFamily) onPick(lead)
+        }}
+      />
+      <ListboxSelect
+        label={words.operation}
+        placeholder={words.choose}
+        value={pickedId}
+        options={palette.filter((e) => e.family === family).map((e) => ({ value: e.id, label: entryLabel(words, e) }))}
+        onChange={(id) => {
+          const entry = palette.find((e) => e.id === id)
+          if (entry) onPick(entry)
+        }}
+      />
+    </div>
+  )
+}

package/src/flow/expressions/catalogContext.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext, type ReactNode } from 'react'
+import type { ExpressionCatalog } from './model'
+
+export interface ExpressionCatalogState {
+  /** Undefined while the host is still loading the engine's vocabulary. */
+  catalog?: ExpressionCatalog
+  loading?: boolean
+}
+
+const Ctx = createContext<ExpressionCatalogState>({})
+
+/** Supplies the engine's operation vocabulary to every builder below it. */
+export function ExpressionCatalogProvider({ catalog, loading, children }: ExpressionCatalogState & { children: ReactNode }) {
+  return <Ctx.Provider value={{ ...(catalog ? { catalog } : {}), ...(loading !== undefined ? { loading } : {}) }}>{children}</Ctx.Provider>
+}
+
+/** A prop catalog wins over the provider's. */
+export function useExpressionCatalog(own?: ExpressionCatalog): ExpressionCatalogState {
+  const ctx = useContext(Ctx)
+  return own ? { catalog: own, loading: false } : ctx
+}

package/src/flow/expressions/computeDraft.ts

@@ -0,0 +1,105 @@
+// State of the compute form's expression, independent of its markup: the tree,
+// its JSON text and the text's problem move together through one reducer, so
+// a bad text never loses the last good tree.
+
+import { useEffect, useReducer, useRef } from 'react'
+import { fill } from '../internal/labels'
+import { FLOW_INPUTS_REF, parseExpressionText, prettyJson, type ExpressionCatalog, type ExpressionTextError, type OperationNode } from './model'
+
+/** Seeded into a blank document: hands the flow's inputs through unchanged. */
+export const PASS_THROUGH: OperationNode = { operation: 'identity', value: { ref: FLOW_INPUTS_REF } }
+
+/** Keys of the earlier script-based compute step, dropped on load. */
+export const LEGACY_SCRIPT_KEYS = ['script', 'code', 'language', 'runtime'] as const
+
+/** The stored configuration minus the old script keys. */
+export function withoutScriptKeys(config: Record<string, unknown>): Record<string, unknown> {
+  const legacy = new Set<string>(LEGACY_SCRIPT_KEYS)
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(config)) if (!legacy.has(key)) out[key] = config[key]
+  return out
+}
+
+/** The tree to start from: the stored operation, or the pass-through. */
+export function openingTree(config: Record<string, unknown>): OperationNode {
+  const candidate = config.expression
+  const usable = !!candidate && typeof candidate === 'object' && typeof (candidate as { operation?: unknown }).operation === 'string'
+  return usable ? (candidate as OperationNode) : PASS_THROUGH
+}
+
+type ProblemWords = { unparseable: string; missingOperation: string; unknownOperation: string }
+
+/** Sentence for a text problem; null for an empty document (no message). */
+export function textErrorMessage(error: ExpressionTextError, words: ProblemWords, locale?: string): string | null {
+  if (error.kind === 'empty') return null
+  if (error.kind === 'missing-operation') return words.missingOperation
+  if (error.kind === 'unparseable') return fill(words.unparseable, { detail: error.detail }, locale)
+  return fill(words.unknownOperation, { name: error.operation }, locale)
+}
+
+/** Sample data text: blank means "none"; otherwise a JSON object is required. */
+export function sampleFromText(text: string): { ok: true; value: Record<string, unknown> | undefined } | { ok: false; reason: string } {
+  if (text.trim() === '') return { ok: true, value: undefined }
+  try {
+    const value: unknown = JSON.parse(text)
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) return { ok: true, value: value as Record<string, unknown> }
+    return { ok: false, reason: 'object expected' }
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+interface DraftState {
+  tree: OperationNode
+  text: string
+  problem: ExpressionTextError | null
+}
+
+type DraftMove = { to: 'text'; text: string; catalog: ExpressionCatalog | undefined } | { to: 'tree'; tree: OperationNode } | { to: 'reprint' }
+
+function draftReducer(state: DraftState, move: DraftMove): DraftState {
+  if (move.to === 'tree') return { ...state, tree: move.tree }
+  if (move.to === 'reprint') return { ...state, text: prettyJson(state.tree), problem: null }
+  const read = parseExpressionText(move.text, move.catalog)
+  return read.ok ? { tree: read.value, text: move.text, problem: null } : { ...state, text: move.text, problem: read.error }
+}
+
+/**
+ * The expression as tree and text. `splice` inserts a fragment at the caret
+ * (or replaces a blank document) and puts the caret after it.
+ */
+export function useComputeDraft(start: OperationNode, catalog: ExpressionCatalog | undefined) {
+  const [state, move] = useReducer(draftReducer, start, (tree) => ({ tree, text: prettyJson(tree), problem: null }))
+  const textArea = useRef<HTMLTextAreaElement>(null)
+  const pendingCaret = useRef<number | null>(null)
+
+  useEffect(() => {
+    const at = pendingCaret.current
+    if (at === null || !textArea.current) return
+    pendingCaret.current = null
+    textArea.current.focus()
+    textArea.current.setSelectionRange(at, at)
+  }, [state.text])
+
+  const editText = (text: string) => move({ to: 'text', text, catalog })
+  const splice = (fragment: string) => {
+    if (state.text.trim() === '') {
+      pendingCaret.current = fragment.length
+      editText(fragment)
+      return
+    }
+    const el = textArea.current
+    const start = el?.selectionStart ?? state.text.length
+    const end = el?.selectionEnd ?? start
+    pendingCaret.current = start + fragment.length
+    editText(state.text.slice(0, start) + fragment + state.text.slice(end))
+  }
+  return {
+    ...state,
+    textArea,
+    editText,
+    splice,
+    setTree: (tree: OperationNode) => move({ to: 'tree', tree }),
+    reprint: () => move({ to: 'reprint' }),
+  }
+}

package/src/flow/expressions/exampleCatalog.ts

@@ -0,0 +1,42 @@
+// A small sample vocabulary for the gallery and tests. It is NOT the engine's
+// catalog: hosts pass the one their backend serves. The names below match the
+// shapes produced by normalizeRuleCondition (compare, and, or, not, matches,
+// coalesce) so rules render in the visual builder.
+
+import type { ExpressionCatalog } from './model'
+
+export const exampleExpressionCatalog: ExpressionCatalog = {
+  operations: [
+    { name: 'count', family: 'aggregation', yields: 'number', operands: [{ key: 'list', kind: 'expression' }] },
+    { name: 'sum', family: 'aggregation', yields: 'number', operands: [{ key: 'list', kind: 'expression' }] },
+    { name: 'map', family: 'list', yields: 'list', operands: [{ key: 'list', kind: 'expression' }, { key: 'body', kind: 'expression', binds: ['item', 'index'] }] },
+    { name: 'filter', family: 'list', yields: 'list', operands: [{ key: 'list', kind: 'expression' }, { key: 'where', kind: 'expression', binds: ['item', 'index'] }] },
+    { name: 'sort', family: 'list', yields: 'list', operands: [{ key: 'list', kind: 'expression' }, { key: 'order', kind: 'param', vocabulary: 'sortOrder' }] },
+    {
+      name: 'fold',
+      family: 'list',
+      yields: 'any',
+      operands: [
+        { key: 'list', kind: 'expression' },
+        { key: 'initial', kind: 'expression' },
+        { key: 'body', kind: 'expression', binds: ['accumulator', 'item', 'index'] },
+      ],
+    },
+    { name: 'union', family: 'set', yields: 'list', operands: [{ key: 'lists', kind: 'list' }] },
+    { name: 'pick', family: 'object', yields: 'object', operands: [{ key: 'object', kind: 'expression' }, { key: 'keys', kind: 'raw' }] },
+    { name: 'arithmetic', family: 'arithmetic', yields: 'number', operands: [{ key: 'op', kind: 'param', vocabulary: 'arithmetic' }, { key: 'left', kind: 'expression' }, { key: 'right', kind: 'expression' }] },
+    { name: 'concat', family: 'text', yields: 'string', operands: [{ key: 'parts', kind: 'list' }] },
+    { name: 'compare', family: 'logic', yields: 'boolean', operands: [{ key: 'op', kind: 'param', vocabulary: 'comparison' }, { key: 'left', kind: 'expression' }, { key: 'right', kind: 'expression' }] },
+    { name: 'and', family: 'logic', yields: 'boolean', operands: [{ key: 'conditions', kind: 'list' }] },
+    { name: 'or', family: 'logic', yields: 'boolean', operands: [{ key: 'conditions', kind: 'list' }] },
+    { name: 'not', family: 'logic', yields: 'boolean', operands: [{ key: 'condition', kind: 'expression' }] },
+    { name: 'is_empty', family: 'logic', yields: 'boolean', operands: [{ key: 'value', kind: 'expression' }] },
+    { name: 'in', family: 'logic', yields: 'boolean', operands: [{ key: 'value', kind: 'expression' }, { key: 'list', kind: 'expression' }] },
+    { name: 'to_number', family: 'conversion', yields: 'number', operands: [{ key: 'value', kind: 'expression' }] },
+    { name: 'days_between', family: 'datetime', yields: 'number', operands: [{ key: 'from', kind: 'expression' }, { key: 'to', kind: 'expression' }] },
+    { name: 'matches', family: 'pattern', yields: 'boolean', operands: [{ key: 'text', kind: 'expression' }, { key: 'pattern', kind: 'expression' }] },
+    { name: 'lookup', family: 'utility', yields: 'any', operands: [{ key: 'key', kind: 'expression' }, { key: 'table', kind: 'raw' }] },
+    { name: 'coalesce', family: 'core', yields: 'any', operands: [{ key: 'values', kind: 'list' }] },
+    { name: 'identity', family: 'core', yields: 'any', operands: [{ key: 'value', kind: 'expression' }] },
+  ],
+}