@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/flow/nodes/AgentIdentity.tsx

@@ -0,0 +1,145 @@
+// AgentIdentity: who an automated agent is, the same way everywhere. Design
+// direction §2.11: an agent is a rounded square with a dashed boundary, never
+// a round face or initials, and the word "agent" is always visible. No
+// external avatar service: the optional generated mark is drawn here from a
+// hash of the name.
+
+import { useState } from 'react'
+import { Bot } from 'lucide-react'
+import { defineLabels, fill, useLabels } from '../internal/labels'
+
+export type AgentTier = 'beginner' | 'intermediate' | 'advanced' | 'expert'
+
+/** Default rating thresholds (a, b, c): below a beginner … at or above c expert. Hosts pass their own. */
+export const DEFAULT_TIER_THRESHOLDS: readonly [number, number, number] = [25, 50, 75]
+
+/** Maps a rating to one of four ordered tiers; a missing rating counts as the lowest. */
+export function agentTier(rating?: number | null, thresholds: readonly [number, number, number] = DEFAULT_TIER_THRESHOLDS): AgentTier {
+  if (rating === undefined || rating === null || Number.isNaN(rating)) return 'beginner'
+  const [a, b, c] = thresholds
+  if (rating < a) return 'beginner'
+  if (rating < b) return 'intermediate'
+  if (rating < c) return 'advanced'
+  return 'expert'
+}
+
+/** FNV-1a over UTF-16 code units: small, stable, no dependency. */
+export function nameHash(name: string): number {
+  let h = 0x811c9dc5
+  for (let i = 0; i < name.length; i++) {
+    h ^= name.charCodeAt(i)
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return h >>> 0
+}
+
+/**
+ * Deterministic geometric mark: a 5 × 5 grid mirrored left to right, cells
+ * switched on by bits of the name hash. Same name, same picture; no faces.
+ */
+export function GeneratedAgentMark({ name }: { name: string }) {
+  const h = nameHash(name)
+  const cells: Array<[number, number]> = []
+  for (let row = 0; row < 5; row++) {
+    for (let col = 0; col < 3; col++) {
+      if ((h >>> (row * 3 + col)) & 1) {
+        cells.push([col, row])
+        if (col < 2) cells.push([4 - col, row])
+      }
+    }
+  }
+  const tone = (h % 8) + 1
+  return (
+    <svg className="ty-agent-mark__generated" viewBox="0 0 5 5" data-tone={`categorical-${tone}`} data-hash={h.toString(16)} aria-hidden="true" focusable="false">
+      {cells.map(([x, y]) => (
+        <rect key={`${x}-${y}`} x={x} y={y} width={1} height={1} />
+      ))}
+    </svg>
+  )
+}
+
+export interface AgentMarkProps {
+  name: string
+  image?: string | null
+  size?: 'sm' | 'md'
+  /** 'bot': the bot glyph without an image; 'generated': the name's geometric mark. */
+  fallback?: 'bot' | 'generated'
+}
+
+/** The square, dashed mark of an agent. Decorative: the name is text elsewhere. */
+export function AgentMark({ name, image, size = 'md', fallback = 'bot' }: AgentMarkProps) {
+  const [failedSrc, setFailedSrc] = useState<string | null>(null)
+  const showImage = !!image && failedSrc !== image
+  return (
+    <span className="ty-agent-mark" data-size={size} data-content={showImage ? 'image' : fallback} aria-hidden="true">
+      {showImage ? (
+        <img className="ty-agent-mark__image" src={image!} alt="" onError={() => setFailedSrc(image!)} />
+      ) : fallback === 'generated' ? (
+        <GeneratedAgentMark name={name} />
+      ) : (
+        <Bot className="ty-agent-mark__bot" focusable="false" />
+      )}
+      <span className="ty-agent-mark__badge">
+        <Bot focusable="false" />
+      </span>
+    </span>
+  )
+}
+
+export interface AgentIdentityLabels {
+  agent: string
+  /** Name when the identity sits inside a link or button. */
+  name: string
+  modelLine: string
+}
+
+export const agentIdentityLabels = defineLabels<AgentIdentityLabels>('agentIdentity', {
+  en: { agent: 'agent', name: '{name}, agent', modelLine: '{provider} · {model}' },
+  'pt-BR': { agent: 'agente', name: '{name}, agente', modelLine: '{provider} · {model}' },
+  es: { agent: 'agente', name: '{name}, agente', modelLine: '{provider} · {model}' },
+})
+export const defaultAgentIdentityLabels = agentIdentityLabels.bundles.en
+
+export interface AgentIdentityProps {
+  agent: { name: string; image?: string; role?: string; provider?: string; model?: string }
+  size?: 'sm' | 'md'
+  fallbackRole?: string
+  /** Show the word "agent"; hide only where a column header already says it. */
+  showKindWord?: boolean
+  /** Mark without an image: the bot glyph (default) or the generated mark. */
+  markFallback?: 'bot' | 'generated'
+  labels?: Partial<AgentIdentityLabels>
+  className?: string
+}
+
+/** "provider · model" or whichever is present. */
+export function modelLineOf(provider: string | undefined, model: string | undefined, template = defaultAgentIdentityLabels.modelLine): string | null {
+  if (provider && model) return fill(template, { provider, model })
+  return provider || model || null
+}
+
+export function AgentIdentity({ agent, size = 'md', fallbackRole, showKindWord = true, markFallback = 'bot', labels, className }: AgentIdentityProps) {
+  const l = useLabels(agentIdentityLabels, labels)
+  const modelLine = modelLineOf(agent.provider, agent.model, l.modelLine)
+  const role = agent.role || fallbackRole
+  const secondary = role ?? modelLine
+  return (
+    <span className={['ty-agent-identity', className].filter(Boolean).join(' ')} data-size={size}>
+      <AgentMark name={agent.name} image={agent.image ?? null} size={size} fallback={markFallback} />
+      <span className="ty-agent-identity__text">
+        <span className="ty-agent-identity__line">
+          <span className="ty-agent-identity__name" title={agent.name}>
+            {agent.name}
+          </span>
+          {showKindWord ? <span className="ty-agent-identity__kind">{l.agent}</span> : null}
+        </span>
+        {secondary ? (
+          <span className="ty-agent-identity__secondary" title={secondary}>
+            {secondary}
+          </span>
+        ) : null}
+        {role && modelLine ? <span className="ty-agent-identity__model">{modelLine}</span> : null}
+      </span>
+    </span>
+  )
+}

package/src/flow/nodes/AgentNode.tsx

@@ -0,0 +1,152 @@
+// AgentNode: a configured AI agent placed in a flow: name, role and model
+// family (full model id on focus or hover). The body is shared with agent
+// galleries outside the canvas (AgentCardBody).
+
+import type { ReactNode } from 'react'
+import { Focusable, Tooltip, TooltipTrigger } from 'react-aria-components'
+import { Bot } from 'lucide-react'
+import { defineLabels, fill, useLabels } from '../internal/labels'
+import type { FlowNode, LayoutDirection } from '../model/types'
+import { AgentMark } from './AgentIdentity'
+import { ConnectionPorts } from './ConnectionPorts'
+import { GraphNodeCard, type CardDensity } from './GraphNodeCard'
+import { useKindPresentation } from './nodeChrome'
+import { NodeRunIndicator, useRunWords } from './NodeRunIndicator'
+import type { AgentSummary } from './types'
+
+export interface AgentNodeLabels {
+  kind: string
+  name: string
+  nameWithRole: string
+  remove: string
+  notFound: string
+  model: string
+  agentWord: string
+}
+
+export const agentNodeLabels = defineLabels<AgentNodeLabels>('agentNode', {
+  en: {
+    kind: 'agent',
+    name: 'agent: {name}',
+    nameWithRole: 'agent: {name}, {role}',
+    remove: 'Remove {title} from canvas',
+    notFound: 'Agent not found. It may have been deleted.',
+    model: 'model {model}',
+    agentWord: 'agent',
+  },
+  'pt-BR': {
+    kind: 'agente',
+    name: 'agente: {name}',
+    nameWithRole: 'agente: {name}, {role}',
+    remove: 'Remover {title} do canvas',
+    notFound: 'Agente não encontrado. Ele pode ter sido excluído.',
+    model: 'modelo {model}',
+    agentWord: 'agente',
+  },
+  es: {
+    kind: 'agente',
+    name: 'agente: {name}',
+    nameWithRole: 'agente: {name}, {role}',
+    remove: 'Quitar {title} del lienzo',
+    notFound: 'Agente no encontrado. Puede haber sido eliminado.',
+    model: 'modelo {model}',
+    agentWord: 'agente',
+  },
+})
+export const defaultAgentNodeLabels = agentNodeLabels.bundles.en
+
+/** Family shown on the mark: the explicit provider, else the id's first segment. */
+export function modelFamily(modelId: string, provider?: string): string {
+  if (provider) return provider
+  const head = modelId.split(/[/:]/)[0] ?? modelId
+  return head.split(/[-_.]/)[0] || head
+}
+
+/** Model family as text; the full id on focus or hover (no brand logos). */
+export function ModelMark({ modelId, provider, labels }: { modelId: string; provider?: string; labels?: Partial<AgentNodeLabels> }) {
+  const l = useLabels(agentNodeLabels, labels)
+  return (
+    <TooltipTrigger delay={300}>
+      <Focusable>
+        <span className="ty-model-mark" role="img" aria-label={fill(l.model, { model: modelId })} tabIndex={0} data-ty-above="" data-ty-no-drag="">
+          {modelFamily(modelId, provider)}
+        </span>
+      </Focusable>
+      <Tooltip className="ty-model-mark__tooltip" offset={6}>
+        {modelId}
+      </Tooltip>
+    </TooltipTrigger>
+  )
+}
+
+/** Agent card body shared with galleries: mark, name, role, the word "agent", model. */
+export function AgentCardBody({ agent, density = 'detailed', actions, labels }: { agent: AgentSummary; density?: CardDensity; actions?: ReactNode; labels?: Partial<AgentNodeLabels> }) {
+  const l = useLabels(agentNodeLabels, labels)
+  return (
+    <div className="ty-agent-body" data-density={density}>
+      <AgentMark name={agent.name} image={agent.avatar ?? null} fallback="generated" />
+      <div className="ty-agent-body__text">
+        <span className="ty-agent-body__line">
+          <span className="ty-agent-body__kind">{l.agentWord}</span>
+          {agent.modelId ? <ModelMark modelId={agent.modelId} {...(agent.provider ? { provider: agent.provider } : {})} labels={labels} /> : null}
+        </span>
+        {density === 'detailed' && agent.role ? <span className="ty-agent-body__role">{agent.role}</span> : null}
+      </div>
+      {actions ? <div className="ty-agent-body__actions">{actions}</div> : null}
+    </div>
+  )
+}
+
+export interface AgentNodeProps {
+  id: string
+  agent: AgentSummary | null
+  /** Title when the agent is missing. */
+  label?: string
+  density?: CardDensity
+  onOpen?: () => void
+  onRemove?: (id: string) => void
+  /** Extra header actions (gallery use). */
+  actions?: ReactNode
+  selected?: boolean
+  locked?: boolean
+  preview?: boolean
+  direction?: LayoutDirection
+  labels?: Partial<AgentNodeLabels>
+}
+
+export function AgentNode(props: AgentNodeProps) {
+  const { id, agent, label, density = 'detailed', onOpen, onRemove, actions, selected = false, locked = false, preview = false, direction = 'right' } = props
+  const l = useLabels(agentNodeLabels, props.labels)
+  const node: FlowNode = { id, kind: 'agent', position: { x: 0, y: 0 }, data: {} }
+  const k = useKindPresentation(node, direction)
+  const run = useRunWords(id)
+  const title = agent?.name ?? label ?? l.kind
+  const name = agent ? (agent.role ? fill(l.nameWithRole, { name: agent.name, role: agent.role }) : fill(l.name, { name: agent.name })) : undefined
+  const canEdit = !preview && !locked
+  return (
+    <GraphNodeCard
+      kind="agent"
+      kindLabel={l.kind}
+      title={title}
+      icon={<Bot />}
+      tone={k.tone}
+      width="wide"
+      density={density}
+      selected={selected}
+      locked={locked}
+      runState={run.runState}
+      problem={agent ? false : l.notFound}
+      {...(name ? { accessibleName: run.words ? `${name}, ${run.words}` : name } : {})}
+      {...(run.words && !name ? { stateWords: [run.words] } : {})}
+      {...(onOpen && (canEdit || preview) ? { onActivate: onOpen } : {})}
+      {...(onRemove && canEdit ? { onDelete: () => onRemove(id) } : {})}
+      labels={{ remove: l.remove }}
+      headerActions={actions}
+      meta={agent ? <AgentCardBody agent={agent} density={density} labels={props.labels} /> : undefined}
+      className="ty-flow-node"
+    >
+      <ConnectionPorts nodeId={id} nodeLabel={title} inputs={k.inputs} outputs={k.outputs} tone={k.tone} preview={preview} />
+      <NodeRunIndicator nodeId={id} kind="agent" nodeLabel={title} />
+    </GraphNodeCard>
+  )
+}

package/src/flow/nodes/AlignmentGuides.tsx

@@ -0,0 +1,108 @@
+// AlignmentGuides: while nodes move (pointer drag or arrow keys), show a
+// horizontal and/or vertical line where an edge or centre lines up with
+// another node. Detection is geometry/guides (findGuides); this file holds the
+// hook, the decorative overlay and the keyboard announcement.
+
+import { useCallback, useRef, useState } from 'react'
+import { findGuides, GUIDE_THRESHOLD, NO_GUIDES, type GuidePositions } from '../geometry/guides'
+import { useAnnounce } from '../internal/Announcer'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { Rect } from '../model/types'
+
+export interface AlignmentGuidesLabels {
+  aligned: string
+}
+
+export const alignmentGuidesLabels = defineLabels<AlignmentGuidesLabels>('alignmentGuides', {
+  en: { aligned: 'aligned with {name}' },
+  'pt-BR': { aligned: 'alinhado com {name}' },
+  es: { aligned: 'alineado con {name}' },
+})
+export const defaultAlignmentGuidesLabels = alignmentGuidesLabels.bundles.en
+
+export interface GuideCandidate {
+  id: string
+  rect: Rect
+}
+
+export interface UseAlignmentGuidesOptions {
+  threshold?: number
+  /** Node name for the keyboard announcement. */
+  nameOf?: (id: string) => string
+  labels?: Partial<AlignmentGuidesLabels>
+}
+
+export interface AlignmentGuidesApi {
+  guides: GuidePositions
+  /**
+   * Returns the drag handler for the current graph: call it with the moving
+   * reference box (the node under the pointer), its id and every dragged id.
+   * Dragged nodes are never compared with each other.
+   */
+  createDragHandler: (all: readonly GuideCandidate[]) => (moving: Rect, referenceId: string, draggedIds: readonly string[]) => void
+  onDragStop: () => void
+  /** Same detection after an arrow-key move; announces "aligned with …" when a guide appears. */
+  onKeyboardMove: (all: readonly GuideCandidate[], moving: Rect, movedId: string) => void
+}
+
+export function useAlignmentGuides(options: UseAlignmentGuidesOptions = {}): AlignmentGuidesApi {
+  const { threshold = GUIDE_THRESHOLD, nameOf } = options
+  const l = useLabels(alignmentGuidesLabels, options.labels)
+  const { locale } = useFlowLocale()
+  const announce = useAnnounce()
+  const [guides, setGuides] = useState<GuidePositions>(NO_GUIDES)
+  const lastAnnounced = useRef<string | null>(null)
+
+  const detect = useCallback(
+    (all: readonly GuideCandidate[], moving: Rect, excluded: ReadonlySet<string>) => {
+      const m = findGuides(
+        moving,
+        all.filter((c) => !excluded.has(c.id)),
+        threshold,
+      )
+      setGuides((prev) => (prev.horizontal === m.horizontal && prev.vertical === m.vertical ? prev : { horizontal: m.horizontal, vertical: m.vertical }))
+      return m
+    },
+    [threshold],
+  )
+
+  const createDragHandler = useCallback(
+    (all: readonly GuideCandidate[]) => (moving: Rect, referenceId: string, draggedIds: readonly string[]) => {
+      detect(all, moving, new Set([referenceId, ...draggedIds]))
+    },
+    [detect],
+  )
+
+  const onDragStop = useCallback(() => {
+    setGuides(NO_GUIDES)
+    lastAnnounced.current = null
+  }, [])
+
+  const onKeyboardMove = useCallback(
+    (all: readonly GuideCandidate[], moving: Rect, movedId: string) => {
+      const m = detect(all, moving, new Set([movedId]))
+      const partner = m.verticalWith ?? m.horizontalWith
+      if (partner && partner !== lastAnnounced.current) {
+        announce(fill(l.aligned, { name: nameOf?.(partner) ?? partner }, locale))
+      }
+      lastAnnounced.current = partner
+    },
+    [detect, announce, l, nameOf, locale],
+  )
+
+  return { guides, createDragHandler, onDragStop, onKeyboardMove }
+}
+
+/** Reach of a guide line in canvas units (it spans the whole canvas). */
+const REACH = 100_000
+
+/** Decorative overlay in canvas coordinates; renders nothing without guides. */
+export function AlignmentGuidesOverlay({ guides }: { guides: GuidePositions }) {
+  if (guides.horizontal === null && guides.vertical === null) return null
+  return (
+    <svg className="ty-alignment-guides" aria-hidden="true" focusable="false">
+      {guides.vertical !== null ? <line className="ty-alignment-guides__line" data-axis="vertical" x1={guides.vertical} x2={guides.vertical} y1={-REACH} y2={REACH} /> : null}
+      {guides.horizontal !== null ? <line className="ty-alignment-guides__line" data-axis="horizontal" x1={-REACH} x2={REACH} y1={guides.horizontal} y2={guides.horizontal} /> : null}
+    </svg>
+  )
+}

package/src/flow/nodes/ConnectionPorts.tsx

@@ -0,0 +1,277 @@
+// ConnectionPorts: the points on a node where connectors start and end. Ports
+// are not tab stops; the canvas surface reads their data attributes to draw a
+// connection, and the keyboard path is the "Connect to…" command below.
+
+import { useMemo, useState, type CSSProperties } from 'react'
+import { Button as AriaButton, ComboBox, Input, Label, ListBox, ListBoxItem, Popover } from 'react-aria-components'
+import { Check, ChevronDown, Info, Minus, TriangleAlert, X } from 'lucide-react'
+import { Button, ModalDialog, NativeSelect } from '../../index'
+import type { BranchTone } from '../catalog/kindCatalog'
+import { defineLabels, fill, useLabels } from '../internal/labels'
+import type { LayoutDirection, Side } from '../model/types'
+import { useSurface } from '../surface/SurfaceContext'
+import type { PortRef } from '../surface/types'
+import { evenSpread, portSetIds, sideForLayout, type PlacedPort } from './ports'
+
+export interface ConnectionPortsLabels {
+  input: string
+  output: string
+  /** "{direction} {label} of {node}"; label may be empty. */
+  name: string
+}
+
+export const connectionPortsLabels = defineLabels<ConnectionPortsLabels>('connectionPorts', {
+  en: { input: 'input', output: 'output', name: '{direction}{label} of {node}' },
+  'pt-BR': { input: 'entrada', output: 'saída', name: '{direction}{label} de {node}' },
+  es: { input: 'entrada', output: 'salida', name: '{direction}{label} de {node}' },
+})
+export const defaultConnectionPortsLabels = connectionPortsLabels.bundles.en
+
+const TONE_ICON: Record<BranchTone, typeof Check> = { success: Check, error: X, info: Info, warning: TriangleAlert, neutral: Minus }
+
+/** Small label beside an output: icon and word by tone, never colour alone. */
+export function BranchLabel({ label, tone = 'neutral' }: { label: string; tone?: BranchTone }) {
+  const Icon = TONE_ICON[tone]
+  return (
+    <span className="ty-branch-label" data-branch-tone={tone} aria-hidden="true">
+      <Icon focusable="false" />
+      {label}
+    </span>
+  )
+}
+
+export interface ConnectionPortProps {
+  /** Receives (input) or emits (output) connectors. */
+  direction: 'input' | 'output'
+  /** Preferred side before the layout mapping. */
+  side: Side
+  id: string
+  nodeId: string
+  /** Node name used in the port's accessible name. */
+  nodeLabel: string
+  /** Kind tone (categorical token name) of the point. */
+  tone?: string
+  branchTone?: BranchTone
+  /** Position along the side, in percent; centred when absent. */
+  offset?: number
+  label?: string
+  layout?: LayoutDirection
+  /** Read-only picture: decorative, not a connection point. */
+  preview?: boolean
+  labels?: Partial<ConnectionPortsLabels>
+}
+
+/** One port. */
+export function ConnectionPort(props: ConnectionPortProps) {
+  const { direction, side, id, nodeId, nodeLabel, tone = 'neutral', branchTone, offset, label, layout = 'right', preview = false } = props
+  const placed: PlacedPort = {
+    id,
+    role: direction === 'output' ? 'source' : 'target',
+    side: sideForLayout(side, layout),
+    along: offset !== undefined ? offset / 100 : 0.5,
+    ...(label ? { label } : {}),
+    ...(branchTone ? { tone: branchTone } : {}),
+  }
+  return <PortDot port={placed} nodeId={nodeId} nodeLabel={nodeLabel} tone={tone} preview={preview} labels={props.labels} />
+}
+
+export interface PortSetProps extends Omit<ConnectionPortProps, 'id' | 'offset'> {
+  count: number
+  idPrefix: string
+  /** Stable keys for items that can be reordered; replaces prefix-index ids. */
+  keys?: readonly string[]
+}
+
+/** Several ports spread evenly along one side (ids prefix-0, prefix-1 …). */
+export function PortSet({ count, idPrefix, keys, ...rest }: PortSetProps) {
+  return (
+    <>
+      {portSetIds(count, idPrefix, keys).map((id, i) => (
+        <ConnectionPort key={id} {...rest} id={id} offset={evenSpread(i, count) * 100} />
+      ))}
+    </>
+  )
+}
+
+export interface ConnectionPortsProps {
+  nodeId: string
+  nodeLabel: string
+  inputs: readonly PlacedPort[]
+  outputs: readonly PlacedPort[]
+  tone?: string
+  preview?: boolean
+  labels?: Partial<ConnectionPortsLabels>
+}
+
+/** All ports of a node (see portsOf). */
+export function ConnectionPorts({ nodeId, nodeLabel, inputs, outputs, tone = 'neutral', preview = false, labels }: ConnectionPortsProps) {
+  return (
+    <>
+      {[...inputs, ...outputs].map((p) => (
+        <PortDot key={`${p.role}-${p.id}`} port={p} nodeId={nodeId} nodeLabel={nodeLabel} tone={tone} preview={preview} labels={labels} />
+      ))}
+    </>
+  )
+}
+
+function PortDot({ port, nodeId, nodeLabel, tone, preview, labels }: { port: PlacedPort; nodeId: string; nodeLabel: string; tone: string; preview: boolean; labels: Partial<ConnectionPortsLabels> | undefined }) {
+  const l = useLabels(connectionPortsLabels, labels)
+  const surface = useSurface()
+  const name = fill(l.name, { direction: port.role === 'source' ? l.output : l.input, label: port.label ? ` ${port.label}` : '', node: nodeLabel })
+  const target = surface.connectTarget?.nodeId === nodeId && surface.connecting && surface.connecting.role !== port.role ? (surface.connectTarget.valid ? 'valid' : 'invalid') : undefined
+  const connectingFromHere = surface.connecting?.nodeId === nodeId && surface.connecting.portId === port.id && surface.connecting.role === port.role
+  const style = { '--ty-port-along': `${port.along * 100}%` } as CSSProperties
+  const common = {
+    className: 'ty-port',
+    'data-side': port.side,
+    'data-role': port.role,
+    'data-tone': tone,
+    ...(port.tone ? { 'data-branch-tone': port.tone } : {}),
+    'data-hidden': surface.floating ? 'true' : undefined,
+    'data-target': target,
+    'data-origin': connectingFromHere ? 'true' : undefined,
+    style,
+  }
+  if (preview) {
+    return (
+      <span {...common} data-preview="true" aria-hidden="true">
+        <span className="ty-port__dot" />
+      </span>
+    )
+  }
+  return (
+    <span {...common} data-ty-port="" data-ty-port-node={nodeId} data-ty-port-id={port.id} data-ty-port-role={port.role} data-port-id={port.id}>
+      <span className="ty-port__dot" aria-hidden="true" />
+      <span className="ty-visually-hidden">{name}</span>
+      {port.label ? <BranchLabel label={port.label} {...(port.tone ? { tone: port.tone } : {})} /> : null}
+    </span>
+  )
+}
+
+// ---- keyboard alternative -----------------------------------------------
+
+export interface ConnectToLabels {
+  title: string
+  description: string
+  output: string
+  target: string
+  targetPlaceholder: string
+  noTargets: string
+  connect: string
+  cancel: string
+}
+
+export const connectToLabels = defineLabels<ConnectToLabels>('connectTo', {
+  en: {
+    title: 'Connect {node} to…',
+    description: 'Choose the step that receives this connection.',
+    output: 'Output',
+    target: 'Target step',
+    targetPlaceholder: 'Type a step name',
+    noTargets: 'No step can receive this connection.',
+    connect: 'Connect',
+    cancel: 'Cancel',
+  },
+  'pt-BR': {
+    title: 'Conectar {node} a…',
+    description: 'Escolha a etapa que recebe esta conexão.',
+    output: 'Saída',
+    target: 'Etapa de destino',
+    targetPlaceholder: 'Digite o nome de uma etapa',
+    noTargets: 'Nenhuma etapa pode receber esta conexão.',
+    connect: 'Conectar',
+    cancel: 'Cancelar',
+  },
+  es: {
+    title: 'Conectar {node} con…',
+    description: 'Elige el paso que recibe esta conexión.',
+    output: 'Salida',
+    target: 'Paso de destino',
+    targetPlaceholder: 'Escribe el nombre de un paso',
+    noTargets: 'Ningún paso puede recibir esta conexión.',
+    connect: 'Conectar',
+    cancel: 'Cancelar',
+  },
+})
+export const defaultConnectToLabels = connectToLabels.bundles.en
+
+export interface ConnectTarget {
+  nodeId: string
+  label: string
+  kindLabel?: string
+}
+
+export interface ConnectToDialogProps {
+  isOpen: boolean
+  onOpenChange: (open: boolean) => void
+  sourceId: string
+  sourceLabel: string
+  /** Outputs of the source; a list to choose from when there is more than one. */
+  outputs: readonly PlacedPort[]
+  /** Valid targets only (the host filters with canConnect). */
+  targets: readonly ConnectTarget[]
+  /** Same call a pointer drop makes. */
+  onConnect: (from: PortRef, to: PortRef) => void
+  labels?: Partial<ConnectToLabels>
+}
+
+/** "Connect to…": the keyboard way to create a connector from the focused node. */
+export function ConnectToDialog({ isOpen, onOpenChange, sourceId, sourceLabel, outputs, targets, onConnect, labels }: ConnectToDialogProps) {
+  const l = useLabels(connectToLabels, labels)
+  const [output, setOutput] = useState<string | undefined>(outputs[0]?.id)
+  const [target, setTarget] = useState<string | null>(null)
+  const items = useMemo(() => targets.map((t) => ({ id: t.nodeId, ...t })), [targets])
+  const submit = () => {
+    if (!target) return
+    onConnect({ nodeId: sourceId, role: 'source', ...(output ? { portId: output } : {}) }, { nodeId: target, role: 'target' })
+    onOpenChange(false)
+  }
+  return (
+    <ModalDialog
+      isOpen={isOpen}
+      onOpenChange={onOpenChange}
+      width="narrow"
+      title={fill(l.title, { node: sourceLabel })}
+      description={l.description}
+      actions={
+        <>
+          <Button variant="secondary" onPress={() => onOpenChange(false)}>
+            {l.cancel}
+          </Button>
+          <Button variant="primary" disabled={!target} onPress={submit}>
+            {l.connect}
+          </Button>
+        </>
+      }
+    >
+      <div className="ty-connect-to">
+        {outputs.length > 1 ? (
+          <NativeSelect label={l.output} options={outputs.map((o) => ({ value: o.id, label: o.label ?? o.id }))} value={output ?? ''} onChange={setOutput} />
+        ) : null}
+        {items.length ? (
+          <ComboBox className="ty-connect-to__combo" items={items} selectedKey={target} onSelectionChange={(k) => setTarget(k === null ? null : String(k))} menuTrigger="focus">
+            <Label className="ty-connect-to__label">{l.target}</Label>
+            <div className="ty-connect-to__field">
+              <Input className="ty-connect-to__input" placeholder={l.targetPlaceholder} />
+              <AriaButton className="ty-connect-to__toggle">
+                <ChevronDown aria-hidden="true" focusable="false" />
+              </AriaButton>
+            </div>
+            <Popover className="ty-connect-to__popover">
+              <ListBox className="ty-connect-to__list">
+                {(item: (typeof items)[number]) => (
+                  <ListBoxItem id={item.id} textValue={item.label} className="ty-connect-to__option">
+                    {item.label}
+                    {item.kindLabel ? <span className="ty-connect-to__kind">{item.kindLabel}</span> : null}
+                  </ListBoxItem>
+                )}
+              </ListBox>
+            </Popover>
+          </ComboBox>
+        ) : (
+          <p className="ty-connect-to__empty">{l.noTargets}</p>
+        )}
+      </div>
+    </ModalDialog>
+  )
+}