@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/flow/nodes/NodeRunIndicator.tsx

@@ -0,0 +1,139 @@
+// NodeRunIndicator: a node's state in the current or inspected run (pending,
+// running, succeeded, failed) with the duration once finished. The mark is not
+// focusable; its words join the node's accessible name through useRunWords.
+
+import { useEffect, useRef } from 'react'
+import { CircleCheck, CircleX, Clock, LoaderCircle } from 'lucide-react'
+import { runStateOf, type NodeRunState } from '../catalog/nodeState'
+import { useAnnounce } from '../internal/Announcer'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { NodeResultStatus, NodeRunResult } from '../model/types'
+import { useNodeResult } from '../state/editorState'
+
+export interface NodeRunLabels {
+  pending: string
+  running: string
+  succeeded: string
+  succeededIn: string
+  failed: string
+  failedWith: string
+  /** Live announcement for the focused node: "{node}: {state}". */
+  announce: string
+  milliseconds: string
+  seconds: string
+}
+
+export const nodeRunLabels = defineLabels<NodeRunLabels>('nodeRun', {
+  en: {
+    pending: 'waiting',
+    running: 'running',
+    succeeded: 'succeeded',
+    succeededIn: 'succeeded in {duration}',
+    failed: 'failed',
+    failedWith: 'failed: {message}',
+    announce: '{node}: {state}',
+    milliseconds: '{value, number} ms',
+    seconds: '{value} s',
+  },
+  'pt-BR': {
+    pending: 'aguardando',
+    running: 'em execução',
+    succeeded: 'concluída',
+    succeededIn: 'concluída em {duration}',
+    failed: 'falhou',
+    failedWith: 'falhou: {message}',
+    announce: '{node}: {state}',
+    milliseconds: '{value, number} ms',
+    seconds: '{value} s',
+  },
+  es: {
+    pending: 'en espera',
+    running: 'en ejecución',
+    succeeded: 'completado',
+    succeededIn: 'completado en {duration}',
+    failed: 'falló',
+    failedWith: 'falló: {message}',
+    announce: '{node}: {state}',
+    milliseconds: '{value, number} ms',
+    seconds: '{value} s',
+  },
+})
+export const defaultNodeRunLabels = nodeRunLabels.bundles.en
+
+/**
+ * Under one second: whole milliseconds ("340 ms"); otherwise seconds with one
+ * decimal ("2.5 s", "2,5 s"). SI symbols, locale digits and separators.
+ */
+export function formatRunDuration(ms: number, locale: string, l: Pick<NodeRunLabels, 'milliseconds' | 'seconds'> = defaultNodeRunLabels): string {
+  if (!Number.isFinite(ms) || ms < 0) return ''
+  if (ms < 1000) return fill(l.milliseconds, { value: Math.round(ms) }, locale)
+  const value = new Intl.NumberFormat(locale, { minimumFractionDigits: 1, maximumFractionDigits: 1 }).format(ms / 1000)
+  return fill(l.seconds, { value }, locale)
+}
+
+/** Words for a result, used in the node's accessible name. */
+export function runWords(result: NodeRunResult | undefined, locale: string, l: NodeRunLabels): string | null {
+  if (!result) return null
+  const duration = result.durationMs !== undefined ? formatRunDuration(result.durationMs, locale, l) : ''
+  switch (result.status) {
+    case 'pending':
+      return l.pending
+    case 'running':
+      return l.running
+    case 'success':
+      return duration ? fill(l.succeededIn, { duration }, locale) : l.succeeded
+    case 'error': {
+      const base = result.error ? fill(l.failedWith, { message: result.error }, locale) : l.failed
+      return duration ? `${base}, ${duration}` : base
+    }
+  }
+}
+
+/** Run state and words of a node from the editor state (nothing outside an editor). */
+export function useRunWords(nodeId: string, labels?: Partial<NodeRunLabels>): { result: NodeRunResult | undefined; runState: NodeRunState; words: string | null } {
+  const result = useNodeResult(nodeId)
+  const l = useLabels(nodeRunLabels, labels)
+  const { locale } = useFlowLocale()
+  return { result, runState: runStateOf(result?.status), words: runWords(result, locale, l) }
+}
+
+const MARKS: Record<NodeResultStatus, typeof Clock> = { pending: Clock, running: LoaderCircle, success: CircleCheck, error: CircleX }
+
+export interface NodeRunIndicatorProps {
+  nodeId: string
+  /** Node kind (kept for hosts that tint per kind; the ring uses the pending semantic colour). */
+  kind?: string
+  /** Name used in the focused-node announcement. */
+  nodeLabel?: string
+  labels?: Partial<NodeRunLabels>
+}
+
+export function NodeRunIndicator({ nodeId, kind, nodeLabel, labels }: NodeRunIndicatorProps) {
+  const result = useNodeResult(nodeId)
+  const l = useLabels(nodeRunLabels, labels)
+  const { locale } = useFlowLocale()
+  const announce = useAnnounce()
+  const ref = useRef<HTMLSpanElement>(null)
+  const previous = useRef<NodeResultStatus | undefined>(result?.status)
+
+  useEffect(() => {
+    const before = previous.current
+    previous.current = result?.status
+    if (!result || before === undefined || before === result.status) return
+    // One region per editor: announce only for the node that has focus.
+    const card = ref.current?.closest('.ty-node-card, [data-ty-node-id]')
+    if (card && card.contains(document.activeElement)) {
+      announce(fill(l.announce, { node: nodeLabel ?? nodeId, state: runWords(result, locale, l) ?? '' }, locale))
+    }
+  }, [result, announce, l, locale, nodeId, nodeLabel])
+
+  if (!result) return null
+  const Mark = MARKS[result.status]
+  const done = result.status === 'success' || result.status === 'error'
+  return (
+    <span ref={ref} className="ty-node-run-indicator" data-status={result.status} data-kind={kind} aria-hidden="true" title={result.error}>
+      <Mark className="ty-node-run-indicator__mark" focusable="false" />
+      {done && result.durationMs !== undefined ? <span className="ty-node-run-indicator__duration">{formatRunDuration(result.durationMs, locale, l)}</span> : null}
+    </span>
+  )
+}

package/src/flow/nodes/NoteNode.tsx

@@ -0,0 +1,134 @@
+// NoteNode: a free-text annotation on the canvas. It never takes part in
+// execution or connections (no ports). Edits are written back through
+// onTextChange, one call per editing session.
+
+import { useId, useRef, useState, type KeyboardEvent } from 'react'
+import { TextArea, TextField } from 'react-aria-components'
+import { StickyNote } from 'lucide-react'
+import { defineLabels, fill, useLabels } from '../internal/labels'
+
+/** Note tones: five categorical tones of design direction §2.3 (decorative). */
+export const NOTE_TONES = ['categorical-1', 'categorical-2', 'categorical-3', 'categorical-5', 'categorical-7'] as const
+export type NoteTone = (typeof NOTE_TONES)[number]
+
+export const NOTE_SIZE = { width: 240, height: 160 } as const
+
+export interface NoteNodeLabels {
+  note: string
+  placeholder: string
+  annotation: string
+  editor: string
+}
+
+export const noteNodeLabels = defineLabels<NoteNodeLabels>('noteNode', {
+  en: { note: 'note', placeholder: 'Double-click to write a note', annotation: 'annotation, not a step', editor: 'Note text' },
+  'pt-BR': { note: 'nota', placeholder: 'Clique duas vezes para escrever uma nota', annotation: 'anotação, não é uma etapa', editor: 'Texto da nota' },
+  es: { note: 'nota', placeholder: 'Haz doble clic para escribir una nota', annotation: 'anotación, no es un paso', editor: 'Texto de la nota' },
+})
+export const defaultNoteNodeLabels = noteNodeLabels.bundles.en
+
+export interface NoteNodeProps {
+  id: string
+  text?: string
+  tone?: string
+  width?: number
+  height?: number
+  onTextChange: (text: string) => void
+  placeholder?: string
+  selected?: boolean
+  locked?: boolean
+  labels?: Partial<NoteNodeLabels>
+}
+
+/** First words of the text for the group name (by words, never by characters). */
+function firstWords(text: string, count = 6): string {
+  const words = text.trim().split(/\s+/).filter(Boolean)
+  return words.slice(0, count).join(' ') + (words.length > count ? '…' : '')
+}
+
+export function NoteNode(props: NoteNodeProps) {
+  const { text = '', tone, width = NOTE_SIZE.width, height = NOTE_SIZE.height, onTextChange, selected = false, locked = false } = props
+  const l = useLabels(noteNodeLabels, props.labels)
+  const placeholder = props.placeholder ?? l.placeholder
+  const safeTone = (NOTE_TONES as readonly string[]).includes(tone ?? '') ? (tone as NoteTone) : NOTE_TONES[0]
+  const [editing, setEditing] = useState(false)
+  const [draft, setDraft] = useState(text)
+  const rootRef = useRef<HTMLDivElement>(null)
+  const descId = useId()
+
+  const start = () => {
+    if (locked) return
+    setDraft(text)
+    setEditing(true)
+  }
+  const finish = () => {
+    setEditing(false)
+    if (draft !== text) onTextChange(draft)
+    requestAnimationFrame(() => rootRef.current?.focus())
+  }
+  const onRootKey = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (editing || e.target !== rootRef.current) return
+    if (e.key === 'Enter' || e.key === 'F2') {
+      e.preventDefault()
+      e.stopPropagation()
+      start()
+    }
+  }
+  const name = text.trim() ? `${l.note}: ${firstWords(text)}` : l.note
+
+  return (
+    <div
+      ref={rootRef}
+      className="ty-note-node"
+      role="group"
+      aria-label={name}
+      aria-describedby={descId}
+      tabIndex={0}
+      data-ty-node-focus=""
+      data-tone={safeTone}
+      data-selected={selected ? 'true' : 'false'}
+      data-locked={locked ? 'true' : 'false'}
+      data-editing={editing ? 'true' : undefined}
+      style={{ inlineSize: width, blockSize: height }}
+      onDoubleClick={start}
+      onKeyDown={onRootKey}
+      onPointerUp={(e) => {
+        // Touch: a tap on an already selected note starts editing.
+        if (e.pointerType === 'touch' && selected && !editing) start()
+      }}
+    >
+      <span id={descId} className="ty-visually-hidden">
+        {l.annotation}
+      </span>
+      <StickyNote className="ty-note-node__icon" aria-hidden="true" focusable="false" />
+      {editing ? (
+        <TextField className="ty-note-node__field" value={draft} onChange={setDraft} aria-label={l.editor} autoFocus>
+          <TextArea
+            className="ty-note-node__editor"
+            data-ty-no-drag=""
+            onBlur={finish}
+            onKeyDown={(e) => {
+              // Typing in a note never reaches canvas shortcuts.
+              e.stopPropagation()
+              if (e.key === 'Escape') {
+                e.preventDefault()
+                finish()
+              }
+            }}
+          />
+        </TextField>
+      ) : text.trim() ? (
+        <p className="ty-note-node__text">{text}</p>
+      ) : (
+        <p className="ty-note-node__text" data-empty="true">
+          {placeholder}
+        </p>
+      )}
+    </div>
+  )
+}
+
+/** Accessible name used by lists and outlines. */
+export function noteName(text: string, labels = defaultNoteNodeLabels): string {
+  return text.trim() ? fill('{note}: {words}', { note: labels.note, words: firstWords(text) }) : labels.note
+}

package/src/flow/nodes/RuleNode.tsx

@@ -0,0 +1,162 @@
+// RuleNode: a stored rule (adjustment, priority, categories, on/off) or an
+// inline rule-engine step. The enabled switch and remove are siblings of the
+// card's main control, so toggling never opens the editor.
+
+import { Scale } from 'lucide-react'
+import { Switch } from '../../index'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { FlowNode, LayoutDirection } from '../model/types'
+import { ConnectionPorts } from './ConnectionPorts'
+import { GraphNodeCard, NodeBadge, type CardDensity } from './GraphNodeCard'
+import { useKindPresentation } from './nodeChrome'
+import { NodeRunIndicator, useRunWords } from './NodeRunIndicator'
+import type { RuleAdjustment, RuleEngineConfig, StoredRule } from './types'
+
+export interface RuleNodeLabels {
+  kind: string
+  engine: string
+  formula: string
+  priority: string
+  variables: string
+  output: string
+  enabled: string
+  off: string
+  missing: string
+  remove: string
+}
+
+export const ruleNodeLabels = defineLabels<RuleNodeLabels>('ruleNode', {
+  en: {
+    kind: 'rule',
+    engine: 'Rule engine',
+    formula: 'formula',
+    priority: 'priority {value, number}',
+    variables: '{count, plural, one {# variable} other {# variables}}',
+    output: 'output {name}',
+    enabled: '{name} enabled',
+    off: 'off',
+    missing: 'No rule is attached to this step.',
+    remove: 'Remove {title}',
+  },
+  'pt-BR': {
+    kind: 'regra',
+    engine: 'Motor de regras',
+    formula: 'fórmula',
+    priority: 'prioridade {value, number}',
+    variables: '{count, plural, one {# variável} other {# variáveis}}',
+    output: 'saída {name}',
+    enabled: '{name} ativa',
+    off: 'desligada',
+    missing: 'Nenhuma regra está ligada a esta etapa.',
+    remove: 'Remover {title}',
+  },
+  es: {
+    kind: 'regla',
+    engine: 'Motor de reglas',
+    formula: 'fórmula',
+    priority: 'prioridad {value, number}',
+    variables: '{count, plural, one {# variable} other {# variables}}',
+    output: 'salida {name}',
+    enabled: '{name} activada',
+    off: 'desactivada',
+    missing: 'Ninguna regla está vinculada a este paso.',
+    remove: 'Quitar {title}',
+  },
+})
+export const defaultRuleNodeLabels = ruleNodeLabels.bundles.en
+
+/**
+ * Signed adjustment text: "+10%", "−5" (true minus sign), "0", or the formula
+ * word. Digits follow the locale.
+ */
+export function formatAdjustment(adj: RuleAdjustment | undefined, locale: string, formulaWord: string): string | null {
+  if (!adj) return null
+  if (adj.type === 'formula' || adj.value === undefined) return formulaWord
+  const magnitude = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(Math.abs(adj.value))
+  const sign = adj.value > 0 ? '+' : adj.value < 0 ? '−' : ''
+  return `${sign}${magnitude}${adj.type === 'percent' ? '%' : ''}`
+}
+
+export interface RuleNodeProps {
+  id: string
+  rule?: StoredRule | null
+  config?: RuleEngineConfig | null
+  label?: string
+  density?: CardDensity
+  onOpen?: (ruleOrId: StoredRule | string) => void
+  onToggleEnabled?: (rule: StoredRule) => void
+  onRemove?: (id: string) => void
+  selected?: boolean
+  locked?: boolean
+  preview?: boolean
+  direction?: LayoutDirection
+  labels?: Partial<RuleNodeLabels>
+}
+
+export function RuleNode(props: RuleNodeProps) {
+  const { id, rule, config, label, density = 'detailed', onOpen, onToggleEnabled, onRemove, selected = false, locked = false, preview = false, direction = 'right' } = props
+  const l = useLabels(ruleNodeLabels, props.labels)
+  const { locale } = useFlowLocale()
+  const node: FlowNode = { id, kind: 'rule', position: { x: 0, y: 0 }, data: {} }
+  const k = useKindPresentation(node, direction)
+  const run = useRunWords(id)
+  const canEdit = !preview && !locked
+  const title = rule?.name ?? config?.label ?? label ?? (config ? l.engine : l.kind)
+
+  let meta = null
+  if (rule) {
+    const adj = formatAdjustment(rule.adjustment, locale, l.formula)
+    meta = (
+      <>
+        {adj ? <span className="ty-rule-node__adjustment">{adj}</span> : null}
+        {rule.priority !== undefined ? <span className="ty-rule-node__priority">{fill(l.priority, { value: rule.priority }, locale)}</span> : null}
+        {(rule.categories ?? []).map((c) => (
+          <NodeBadge key={c}>{c}</NodeBadge>
+        ))}
+      </>
+    )
+  } else if (config) {
+    meta = (
+      <>
+        <span>{fill(l.variables, { count: config.contextVariables?.length ?? 0 }, locale)}</span>
+        {config.outputVariable ? <span className="ty-rule-node__output">{fill(l.output, { name: config.outputVariable }, locale)}</span> : null}
+      </>
+    )
+  }
+
+  const toggle =
+    rule && onToggleEnabled && !preview ? (
+      <span className="ty-rule-node__switch" data-ty-above="" data-ty-no-drag="">
+        <Switch size="small" isSelected={rule.enabled} accessibleLabel={fill(l.enabled, { name: rule.name })} disabled={locked} onChange={() => onToggleEnabled(rule)} />
+        {!rule.enabled ? <span className="ty-rule-node__off">{l.off}</span> : null}
+      </span>
+    ) : rule && !rule.enabled ? (
+      <span className="ty-rule-node__off">{l.off}</span>
+    ) : null
+
+  return (
+    <GraphNodeCard
+      kind="rule"
+      kindLabel={l.kind}
+      title={title}
+      icon={<Scale />}
+      tone={k.tone}
+      width="standard"
+      density={density}
+      selected={selected}
+      locked={locked}
+      runState={run.runState}
+      problem={!rule && !config ? l.missing : false}
+      {...(run.words ? { stateWords: [run.words] } : {})}
+      {...(onOpen && (canEdit || preview) && (rule || config) ? { onActivate: () => onOpen(rule ?? id) } : {})}
+      {...(onRemove && canEdit ? { onDelete: () => onRemove(id) } : {})}
+      labels={{ remove: l.remove }}
+      headerActions={toggle}
+      meta={meta}
+      className="ty-flow-node ty-rule-node"
+    >
+      <ConnectionPorts nodeId={id} nodeLabel={title} inputs={k.inputs} outputs={k.outputs} tone={k.tone} preview={preview} />
+      <NodeRunIndicator nodeId={id} kind="rule" nodeLabel={title} />
+    </GraphNodeCard>
+  )
+}