@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/editor/FlowOutline.tsx

@@ -0,0 +1,196 @@
+// FlowOutline: the keyboard and screen-reader alternative to the canvas. Every
+// step in reading order (rank, then position), with its outgoing connections,
+// and every editing operation as an ordinary button or menu: add, configure,
+// connect ("Connect to…"), remove a connection, move earlier or later, delete.
+
+import { useMemo, useState } from 'react'
+import { ArrowDown, ArrowUp, Crosshair, Link2, Pencil, Trash2, Unlink } from 'lucide-react'
+import { ActionMenu, Button, NativeSelect } from '../../index'
+import { useRenderCatalog } from '../catalog/RenderCatalog'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { FlowConnector, FlowNode } from '../model/types'
+import { flowReadingOrder } from './FlowPreview'
+import { nodeName, nodeTitle } from './nodeBridge'
+
+export interface FlowOutlineLabels {
+  outline: string
+  steps: string
+  empty: string
+  addKind: string
+  add: string
+  configure: string
+  connect: string
+  noTargets: string
+  disconnect: string
+  moveUp: string
+  moveDown: string
+  delete: string
+  show: string
+  leadsTo: string
+  branch: string
+  count: string
+}
+
+export const flowOutlineLabels = defineLabels<FlowOutlineLabels>('FlowOutline', {
+  en: {
+    outline: 'Flow as a list',
+    steps: 'Steps in reading order',
+    empty: 'This flow has no steps yet.',
+    addKind: 'Step to add',
+    add: 'Add step',
+    configure: 'Configure {name}',
+    connect: 'Connect {name} to',
+    noTargets: 'No step can receive a connection from here',
+    disconnect: 'Remove connection from {source} to {target}',
+    moveUp: 'Move {name} earlier',
+    moveDown: 'Move {name} later',
+    delete: 'Delete {name}',
+    show: 'Show {name} on the canvas',
+    leadsTo: 'Leads to',
+    branch: '{branch} branch',
+    count: '{count, plural, one {# step} other {# steps}}',
+  },
+  'pt-BR': {
+    outline: 'Fluxo como lista',
+    steps: 'Passos em ordem de leitura',
+    empty: 'Este fluxo ainda não tem passos.',
+    addKind: 'Passo a adicionar',
+    add: 'Adicionar passo',
+    configure: 'Configurar {name}',
+    connect: 'Conectar {name} a',
+    noTargets: 'Nenhum passo pode receber uma conexão daqui',
+    disconnect: 'Remover a conexão de {source} para {target}',
+    moveUp: 'Mover {name} para antes',
+    moveDown: 'Mover {name} para depois',
+    delete: 'Excluir {name}',
+    show: 'Mostrar {name} no canvas',
+    leadsTo: 'Leva a',
+    branch: 'ramo {branch}',
+    count: '{count, plural, one {# passo} other {# passos}}',
+  },
+  es: {
+    outline: 'Flujo como lista',
+    steps: 'Pasos en orden de lectura',
+    empty: 'Este flujo aún no tiene pasos.',
+    addKind: 'Paso para añadir',
+    add: 'Añadir paso',
+    configure: 'Configurar {name}',
+    connect: 'Conectar {name} con',
+    noTargets: 'Ningún paso puede recibir una conexión desde aquí',
+    disconnect: 'Quitar la conexión de {source} a {target}',
+    moveUp: 'Mover {name} antes',
+    moveDown: 'Mover {name} después',
+    delete: 'Eliminar {name}',
+    show: 'Mostrar {name} en el lienzo',
+    leadsTo: 'Lleva a',
+    branch: 'rama {branch}',
+    count: '{count, plural, one {# paso} other {# pasos}}',
+  },
+})
+export const defaultFlowOutlineLabels: FlowOutlineLabels = flowOutlineLabels.bundles.en
+
+export interface FlowOutlineProps {
+  nodes: FlowNode[]
+  connectors: FlowConnector[]
+  /** Kinds the "add" picker offers. */
+  addableKinds?: Array<{ kind: string; label: string }>
+  locked?: boolean
+  horizontal?: boolean
+  canConnect: (source: FlowNode, target: FlowNode) => boolean
+  onAdd?: (kind: string) => void
+  onConfigure?: (id: string) => void
+  onConnect?: (sourceId: string, targetId: string) => void
+  onDisconnect?: (connectorId: string) => void
+  /** Swap with the neighbour before (-1) or after (+1) in reading order. */
+  onMove?: (id: string, towards: -1 | 1) => void
+  onDelete?: (id: string) => void
+  onShow?: (id: string) => void
+  labels?: Partial<FlowOutlineLabels>
+  className?: string
+}
+
+export function FlowOutline(props: FlowOutlineProps) {
+  const { nodes, connectors, addableKinds = [], locked = false, horizontal = false, canConnect } = props
+  const l = useLabels(flowOutlineLabels, props.labels)
+  const { locale } = useFlowLocale()
+  const catalog = useRenderCatalog()
+  const [kindToAdd, setKindToAdd] = useState(addableKinds[0]?.kind ?? '')
+  const ordered = useMemo(() => flowReadingOrder(nodes, connectors, horizontal), [nodes, connectors, horizontal])
+  const byId = new Map(nodes.map((n) => [n.id, n]))
+  const edit = !locked
+
+  return (
+    <section className={['ty-flow-outline', props.className].filter(Boolean).join(' ')} aria-label={l.outline}>
+      {edit && props.onAdd && addableKinds.length ? (
+        <div className="ty-flow-outline__add">
+          <NativeSelect label={l.addKind} options={addableKinds.map((k) => ({ value: k.kind, label: k.label }))} value={kindToAdd} onChange={setKindToAdd} />
+          <Button variant="secondary" onPress={() => kindToAdd && props.onAdd?.(kindToAdd)}>
+            {l.add}
+          </Button>
+        </div>
+      ) : null}
+      <h3 className="ty-flow-outline__title">
+        {l.steps} <span className="ty-flow-outline__count">{fill(l.count, { count: ordered.length }, locale)}</span>
+      </h3>
+      {ordered.length === 0 ? <p className="ty-flow-outline__empty">{l.empty}</p> : null}
+      <ol className="ty-flow-outline__list">
+        {ordered.map((n, i) => {
+          const name = nodeName(n, catalog)
+          const title = nodeTitle(n, catalog)
+          const out = connectors.filter((c) => c.source === n.id)
+          const targets = edit ? ordered.filter((t) => t.id !== n.id && !out.some((c) => c.target === t.id) && canConnect(n, t)) : []
+          return (
+            <li key={n.id} className="ty-flow-outline__item" data-kind={n.kind}>
+              <div className="ty-flow-outline__row">
+                <span className="ty-flow-outline__bubble" data-tone={catalog.tone(n.kind)} aria-hidden="true" />
+                <span className="ty-flow-outline__name">{name}</span>
+                <div className="ty-flow-outline__actions">
+                  {props.onShow ? <Button variant="quiet" size="compact" iconOnly accessibleLabel={fill(l.show, { name: title }, locale)} leadingIcon={<Crosshair />} onPress={() => props.onShow!(n.id)} /> : null}
+                  {edit && props.onConfigure ? <Button variant="quiet" size="compact" iconOnly accessibleLabel={fill(l.configure, { name: title }, locale)} leadingIcon={<Pencil />} onPress={() => props.onConfigure!(n.id)} /> : null}
+                  {edit && props.onConnect && n.kind !== 'note' ? (
+                    <ActionMenu
+                      label={fill(l.connect, { name: title }, locale)}
+                      trigger={<Button variant="quiet" size="compact" iconOnly accessibleLabel={fill(l.connect, { name: title }, locale)} leadingIcon={<Link2 />} />}
+                      items={targets.length ? targets.map((t) => ({ id: t.id, label: nodeName(t, catalog) })) : [{ id: '__none', label: l.noTargets, disabled: true }]}
+                      onAction={(id) => {
+                        if (id !== '__none') props.onConnect!(n.id, id)
+                      }}
+                    />
+                  ) : null}
+                  {edit && props.onMove ? (
+                    <>
+                      <Button variant="quiet" size="compact" iconOnly accessibleLabel={fill(l.moveUp, { name: title }, locale)} leadingIcon={<ArrowUp />} disabled={i === 0} onPress={() => props.onMove!(n.id, -1)} />
+                      <Button variant="quiet" size="compact" iconOnly accessibleLabel={fill(l.moveDown, { name: title }, locale)} leadingIcon={<ArrowDown />} disabled={i === ordered.length - 1} onPress={() => props.onMove!(n.id, 1)} />
+                    </>
+                  ) : null}
+                  {edit && props.onDelete ? <Button variant="quiet" size="compact" iconOnly accessibleLabel={fill(l.delete, { name: title }, locale)} leadingIcon={<Trash2 />} onPress={() => props.onDelete!(n.id)} /> : null}
+                </div>
+              </div>
+              {out.length ? (
+                <ul className="ty-flow-outline__links" aria-label={`${l.leadsTo}: ${title}`}>
+                  {out.map((c) => {
+                    const t = byId.get(c.target)
+                    if (!t) return null
+                    const tTitle = nodeTitle(t, catalog)
+                    const branch = c.label ?? c.sourcePort
+                    return (
+                      <li key={c.id} className="ty-flow-outline__link">
+                        <span>
+                          {l.leadsTo} {nodeName(t, catalog)}
+                          {branch && branch !== 'out' ? <span className="ty-flow-outline__branch"> · {fill(l.branch, { branch }, locale)}</span> : null}
+                        </span>
+                        {edit && props.onDisconnect ? (
+                          <Button variant="quiet" size="compact" iconOnly accessibleLabel={fill(l.disconnect, { source: title, target: tTitle }, locale)} leadingIcon={<Unlink />} onPress={() => props.onDisconnect!(c.id)} />
+                        ) : null}
+                      </li>
+                    )
+                  })}
+                </ul>
+              ) : null}
+            </li>
+          )
+        })}
+      </ol>
+    </section>
+  )
+}

package/src/flow/editor/FlowPreview.tsx

@@ -0,0 +1,149 @@
+// FlowPreview: a read-only picture of a flow for chat replies, run inspection
+// and live previews. Layout and fit follow the graph only; selection and
+// statuses never move the view.
+
+import { useId, useLayoutEffect, useMemo, useRef, type ReactNode, type Ref } from 'react'
+import { PreviewStatusMark, usePreviewStatusWord } from '../nodes/nodeChrome'
+import { builtInNodeComponents } from '../nodes/registry'
+import { useRenderCatalog } from '../catalog/RenderCatalog'
+import { absoluteRect } from '../geometry/rect'
+import { defineLabels, useFlowLocale, useLabels } from '../internal/labels'
+import { autoLayout, rankDirectionOf } from '../layout/autoLayout'
+import { layerIndex } from '../model/graph'
+import type { FlowConnector, FlowNode, RunStatus } from '../model/types'
+import { CanvasSurface } from '../surface/CanvasSurface'
+import type { CanvasApi, SurfaceNode } from '../surface/types'
+import type { FlowReferenceData } from '../nodes/types'
+import { focusAfter } from './focusOut'
+import { anchorFor, componentForKind, sizeForNode } from './nodeBridge'
+
+export interface FlowPreviewLabels {
+  canvas: string
+}
+
+export const flowPreviewLabels = defineLabels<FlowPreviewLabels>('FlowPreview', {
+  en: { canvas: 'Flow preview' },
+  'pt-BR': { canvas: 'Prévia do fluxo' },
+  es: { canvas: 'Vista previa del flujo' },
+})
+export const defaultFlowPreviewLabels: FlowPreviewLabels = flowPreviewLabels.bundles.en
+
+/**
+ * Status mark for node kinds whose card does not draw one (the generic card
+ * does): glyph and word over the card, the word added to the card's
+ * accessible description, and a "not run" pattern instead of opacity alone.
+ */
+function StatusFrame({ status, children }: { status: RunStatus; children: ReactNode }) {
+  const ref = useRef<HTMLDivElement>(null)
+  const id = useId()
+  const word = usePreviewStatusWord(status)
+  useLayoutEffect(() => {
+    const target = ref.current?.querySelector<HTMLElement>('[data-ty-node-focus]')
+    if (!target) return
+    const own = (target.getAttribute('aria-describedby') ?? '').split(/\s+/).filter((t) => t && t !== id)
+    target.setAttribute('aria-describedby', [...own, id].join(' '))
+  })
+  return (
+    <div ref={ref} className="ty-flow-preview__frame" data-status={status}>
+      {children}
+      <PreviewStatusMark status={status} />
+      <span id={id} className="ty-visually-hidden">
+        {word}
+      </span>
+    </div>
+  )
+}
+
+export interface FlowPreviewProps {
+  graph: { nodes: FlowNode[]; connectors: FlowConnector[] }
+  /** When given, nodes without an entry read as "not run". */
+  nodeStatuses?: Record<string, RunStatus>
+  selectedNodeId?: string | null
+  onNodeActivate?: (nodeId: string) => void
+  layout?: 'auto' | 'preserve'
+  direction?: 'top-down' | 'left-right'
+  /** Keep a horizontal auto layout left to right in right-to-left locales. */
+  keepLtrLayout?: boolean
+  /** Inside a chat bubble: no pinch and no wheel zoom, so the page keeps scrolling. */
+  embedded?: boolean
+  reference?: FlowReferenceData
+  apiRef?: Ref<CanvasApi>
+  label?: string
+  labels?: Partial<FlowPreviewLabels>
+  className?: string
+}
+
+/** Reading order: layer, then position across the layer. */
+export function flowReadingOrder(nodes: FlowNode[], connectors: FlowConnector[], horizontal: boolean): FlowNode[] {
+  const layer = layerIndex(
+    nodes.map((n) => n.id),
+    connectors,
+  )
+  return [...nodes].sort((a, b) => (layer.get(a.id) ?? 0) - (layer.get(b.id) ?? 0) || (horizontal ? a.position.y - b.position.y : a.position.x - b.position.x))
+}
+
+export function FlowPreview(props: FlowPreviewProps) {
+  const { graph, nodeStatuses, selectedNodeId = null, onNodeActivate, layout = 'auto', direction = 'top-down', keepLtrLayout = false, embedded = false, reference, apiRef, className } = props
+  const l = useLabels(flowPreviewLabels, props.labels)
+  const catalog = useRenderCatalog()
+  const { rtl } = useFlowLocale()
+  const rootRef = useRef<HTMLDivElement>(null)
+  const editorDirection = direction === 'left-right' ? 'right' : 'down'
+
+  // Recomputed only when the graph (or its layout settings) change.
+  const placed = useMemo(() => {
+    const sized = graph.nodes.map((n) => ({ ...n, size: sizeForNode(n, 'detailed') }))
+    const laid = layout === 'auto' ? autoLayout(sized, graph.connectors, rankDirectionOf(editorDirection, rtl, keepLtrLayout)) : sized
+    return flowReadingOrder(laid, graph.connectors, editorDirection === 'right')
+  }, [graph, layout, editorDirection, rtl, keepLtrLayout])
+
+  const byId = useMemo(() => new Map(placed.map((n) => [n.id, n])), [placed])
+  const surfaceNodes: SurfaceNode[] = placed.map((n) => ({
+    id: n.id,
+    rect: absoluteRect(n, byId),
+    layer: n.kind === 'group' ? 0 : 1,
+    fixedHeight: n.kind === 'group' || n.kind === 'note',
+    selected: n.id === selectedNodeId,
+    ...(n.hidden ? { hidden: true } : {}),
+    tone: catalog.tone(n.kind),
+  }))
+
+  return (
+    <div ref={rootRef} className={['ty-flow-preview', className].filter(Boolean).join(' ')}>
+      <CanvasSurface
+        label={props.label ?? l.canvas}
+        nodes={surfaceNodes}
+        connectors={graph.connectors}
+        fitKey={placed}
+        wheel={embedded ? 'none' : 'zoom'}
+        pinch={!embedded}
+        {...(apiRef ? { apiRef } : {})}
+        portAnchor={(id, port, role) => {
+          const n = byId.get(id)
+          return n ? anchorFor(n, port, role, editorDirection, catalog) : 'border'
+        }}
+        onLeave={() => focusAfter(rootRef.current)}
+        renderNode={(sn) => {
+          const node = byId.get(sn.id)!
+          const Card = componentForKind(node.kind)
+          const status: RunStatus | undefined = nodeStatuses ? (nodeStatuses[node.id] ?? 'unknown') : undefined
+          const card = (
+            <Card
+              node={node}
+              density="detailed"
+              direction={editorDirection}
+              locked
+              preview
+              selected={node.id === selectedNodeId}
+              {...(status ? { runStatus: status } : {})}
+              {...(onNodeActivate ? { onConfigure: onNodeActivate } : {})}
+              {...(reference ? { reference } : {})}
+            />
+          )
+          // The generic card draws its own status mark; other kinds get the frame.
+          return status && builtInNodeComponents[node.kind] ? <StatusFrame status={status}>{card}</StatusFrame> : card
+        }}
+      />
+    </div>
+  )
+}

package/src/flow/editor/FlowSwitcherBar.tsx

@@ -0,0 +1,141 @@
+// FlowSwitcherBar: the person's flows above the editor. Each flow is a button
+// (aria-current on the open one) followed by its own delete button, never
+// nested. Arrow keys move between flow buttons. Below 640 px: a select.
+
+import { useRef, type KeyboardEvent } from 'react'
+import { CircleCheck, PencilLine, Plus, Trash2 } from 'lucide-react'
+import { Button, NativeSelect, Skeleton, StatusPill, useMediaQuery } from '../../index'
+import { formatRelative } from '../internal/format'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+
+export interface FlowSummary {
+  id: string
+  name: string
+  version: number
+  isDraft: boolean
+  updatedAt?: string | Date
+}
+
+export interface FlowSwitcherLabels {
+  bar: string
+  draft: string
+  published: string
+  newFlow: string
+  delete: string
+  loading: string
+  version: string
+  select: string
+}
+
+export const flowSwitcherLabels = defineLabels<FlowSwitcherLabels>('FlowSwitcherBar', {
+  en: { bar: 'Flows', draft: 'Draft', published: 'Published', newFlow: 'New flow', delete: 'Delete flow {name}', loading: 'Loading flows', version: 'v{version}', select: 'Open flow' },
+  'pt-BR': { bar: 'Fluxos', draft: 'Rascunho', published: 'Publicado', newFlow: 'Novo fluxo', delete: 'Excluir o fluxo {name}', loading: 'Carregando os fluxos', version: 'v{version}', select: 'Abrir fluxo' },
+  es: { bar: 'Flujos', draft: 'Borrador', published: 'Publicado', newFlow: 'Nuevo flujo', delete: 'Eliminar el flujo {name}', loading: 'Cargando los flujos', version: 'v{version}', select: 'Abrir flujo' },
+})
+export const defaultFlowSwitcherLabels: FlowSwitcherLabels = flowSwitcherLabels.bundles.en
+
+export interface FlowSwitcherBarProps {
+  flows: FlowSummary[]
+  activeFlowId: string | null
+  isLoading: boolean
+  onSelect: (flow: FlowSummary) => void
+  onCreate: () => void
+  onDelete: (id: string, name: string) => void
+  labels?: Partial<FlowSwitcherLabels>
+  /** Reference time for relative dates (tests). */
+  now?: Date
+  className?: string
+}
+
+export function FlowSwitcherBar({ flows, activeFlowId, isLoading, onSelect, onCreate, onDelete, labels, now, className }: FlowSwitcherBarProps) {
+  const l = useLabels(flowSwitcherLabels, labels)
+  const { locale } = useFlowLocale()
+  const narrow = !useMediaQuery('(min-width: 640px)', true)
+  const listRef = useRef<HTMLUListElement>(null)
+  const canDelete = flows.length > 1
+
+  if (isLoading) {
+    return (
+      <nav className={['ty-flow-switcher', className].filter(Boolean).join(' ')} aria-label={l.bar} aria-busy="true">
+        <span role="status" className="ty-visually-hidden">
+          {l.loading}
+        </span>
+        <div className="ty-flow-switcher__skeletons" aria-hidden="true">
+          {[0, 1, 2].map((i) => (
+            <Skeleton key={i} shape="rect" width="160px" />
+          ))}
+        </div>
+      </nav>
+    )
+  }
+
+  if (narrow) {
+    const active = flows.find((f) => f.id === activeFlowId)
+    return (
+      <nav className={['ty-flow-switcher', className].filter(Boolean).join(' ')} aria-label={l.bar} data-narrow="">
+        <NativeSelect
+          label={l.select}
+          options={flows.map((f) => ({ value: f.id, label: `${f.name} · ${fill(l.version, { version: f.version }, locale)}` }))}
+          value={activeFlowId ?? ''}
+          onChange={(id) => {
+            const f = flows.find((x) => x.id === id)
+            if (f) onSelect(f)
+          }}
+        />
+        {active && canDelete ? <Button variant="quiet" iconOnly accessibleLabel={fill(l.delete, { name: active.name }, locale)} leadingIcon={<Trash2 />} onPress={() => onDelete(active.id, active.name)} /> : null}
+        <Button variant="secondary" leadingIcon={<Plus />} onPress={onCreate}>
+          {l.newFlow}
+        </Button>
+      </nav>
+    )
+  }
+
+  const onKeyDown = (e: KeyboardEvent<HTMLUListElement>) => {
+    const keys = ['ArrowLeft', 'ArrowRight', 'Home', 'End']
+    if (!keys.includes(e.key)) return
+    const buttons = [...(listRef.current?.querySelectorAll<HTMLElement>('[data-flow-button]') ?? [])]
+    const at = buttons.indexOf(document.activeElement as HTMLElement)
+    if (at < 0) return
+    e.preventDefault()
+    const rtl = getComputedStyle(listRef.current!).direction === 'rtl'
+    const forward = (e.key === 'ArrowRight') !== rtl
+    const next = e.key === 'Home' ? 0 : e.key === 'End' ? buttons.length - 1 : (at + (forward ? 1 : -1) + buttons.length) % buttons.length
+    buttons[next]?.focus()
+  }
+
+  return (
+    <nav className={['ty-flow-switcher', className].filter(Boolean).join(' ')} aria-label={l.bar}>
+      <ul className="ty-flow-switcher__list" ref={listRef} onKeyDown={onKeyDown}>
+        {flows.map((f) => {
+          const current = f.id === activeFlowId
+          const when = f.updatedAt ? formatRelative(f.updatedAt, locale, now) : ''
+          return (
+            <li key={f.id} className="ty-flow-switcher__item" data-current={current || undefined}>
+              <button type="button" className="ty-flow-switcher__flow" data-flow-button="" aria-current={current ? 'page' : undefined} onClick={() => onSelect(f)}>
+                <span className="ty-flow-switcher__name">{f.name}</span>
+                <span className="ty-flow-switcher__meta">
+                  <code className="ty-flow-switcher__version">{fill(l.version, { version: f.version }, locale)}</code>
+                  {when ? <time dateTime={new Date(f.updatedAt!).toISOString()}>{when}</time> : null}
+                </span>
+              </button>
+              <StatusPill
+                status={f.isDraft ? 'draft' : 'published'}
+                size="small"
+                statusMap={{
+                  draft: { label: l.draft, tone: 'warning', icon: <PencilLine /> },
+                  published: { label: l.published, tone: 'success', icon: <CircleCheck /> },
+                }}
+              />
+              {canDelete ? (
+                <Button className="ty-flow-switcher__delete" variant="quiet" size="compact" iconOnly accessibleLabel={fill(l.delete, { name: f.name }, locale)} leadingIcon={<Trash2 />} onPress={() => onDelete(f.id, f.name)} />
+              ) : null}
+            </li>
+          )
+        })}
+      </ul>
+      <Button variant="secondary" leadingIcon={<Plus />} onPress={onCreate}>
+        {l.newFlow}
+      </Button>
+    </nav>
+  )
+}