@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/flow/forms/forms-shared.css

@@ -0,0 +1,53 @@
+/* Shared layout of the node configuration forms. Logical properties only, so
+   every form mirrors in right-to-left locales. */
+@layer tympan.components {
+  .ty-node-form {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-5);
+    min-inline-size: 0;
+    font-family: var(--ty-font-sans);
+    color: var(--ty-ink-2);
+    text-align: start;
+  }
+  .ty-node-form__fields {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-5);
+  }
+  .ty-node-form__empty {
+    margin: 0;
+    color: var(--ty-ink-3);
+  }
+  .ty-node-form-footer {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: flex-end;
+    gap: var(--ty-space-2);
+    padding-block-start: var(--ty-space-4);
+    border-block-start: 1px solid var(--ty-line);
+  }
+  .ty-node-form-footer__save {
+    display: inline-flex;
+  }
+  .ty-mono {
+    font-family: var(--ty-font-mono);
+  }
+  /* Identifiers, commands and structured text stay left-to-right inside RTL
+     pages and never reorder the surrounding text. */
+  .ty-ltr-text:is(span, code, input, textarea),
+  .ty-ltr-text input,
+  .ty-ltr-text textarea {
+    direction: ltr;
+    unicode-bidi: isolate;
+  }
+  .ty-ltr-text input,
+  .ty-ltr-text textarea {
+    text-align: start;
+  }
+  @media (forced-colors: active) {
+    .ty-node-form-footer {
+      border-block-start-color: CanvasText;
+    }
+  }
+}

package/src/flow/forms/forms.css

@@ -0,0 +1,9 @@
+/* forms group stylesheet barrel. */
+@import './forms-shared.css';
+@import './SchemaConfigForm.css';
+@import './VariableListEditor.css';
+@import './ToolServerListField.css';
+@import './StartNodeForm.css';
+@import './AgentNodeForm.css';
+@import './GroupNodeForm.css';
+@import './NewForms.css';

package/src/flow/forms/index.ts

@@ -0,0 +1,12 @@
+// @datatechsolutions/tympan/flow: forms group barrel (node configuration forms).
+export * from './NodeFormFooter'
+export * from './SchemaConfigForm'
+export * from './VariableListEditor'
+export * from './ToolServerListField'
+export * from './StartNodeForm'
+export * from './AgentNodeForm'
+export * from './GroupNodeForm'
+export * from './OutputSchemaBuilder'
+export * from './DataSourceNodeForm'
+export * from './ReportOutputNodeForm'
+export * from './DecisionNodeForm'

package/src/flow/forms/nameListModel.ts

@@ -0,0 +1,61 @@
+// State and rules behind VariableListEditor, kept apart from the markup.
+//
+// The editor's own state is only the entry being typed, a complaint about it
+// and the last sentence for the live region; the list itself belongs to the
+// host. `nameListStep` is a reducer over that small state.
+
+export type NameIssue = 'blank' | 'duplicate'
+
+/** Why the name at `position` would not survive a save, or null. */
+export function issueAt(list: readonly string[], position: number): NameIssue | null {
+  const candidate = list[position] ?? ''
+  if (candidate.trim() === '') return 'blank'
+  return list.indexOf(candidate) < position ? 'duplicate' : null
+}
+
+/**
+ * Which remove control should hold focus once `position` has been taken out
+ * of the list (`remaining` rows now). -1 means the entry field.
+ */
+export function focusTargetAfter(position: number, remaining: number): number {
+  if (remaining === 0) return -1
+  return Math.min(position, remaining - 1)
+}
+
+export interface EntryState {
+  draft: string
+  complaint: 'duplicate' | null
+  spoken: { kind: 'added' | 'removed'; name: string } | null
+}
+
+export type EntryEvent =
+  | { type: 'typed'; text: string }
+  | { type: 'refused' }
+  | { type: 'accepted'; name: string }
+  | { type: 'dropped'; name: string }
+
+export const EMPTY_ENTRY: EntryState = { draft: '', complaint: null, spoken: null }
+
+export function nameListStep(state: EntryState, event: EntryEvent): EntryState {
+  switch (event.type) {
+    case 'typed':
+      return { ...state, draft: event.text, complaint: null }
+    case 'refused':
+      return { ...state, complaint: 'duplicate' }
+    case 'accepted':
+      return { draft: '', complaint: null, spoken: { kind: 'added', name: event.name } }
+    case 'dropped':
+      return { ...state, spoken: { kind: 'removed', name: event.name } }
+  }
+}
+
+/** Outcome of trying to add the current draft to `list`. */
+export function admit(list: readonly string[], draft: string): { kind: 'empty' } | { kind: 'taken' } | { kind: 'ok'; name: string; next: string[] } {
+  const name = draft.trim()
+  if (!name) return { kind: 'empty' }
+  if (list.includes(name)) return { kind: 'taken' }
+  return { kind: 'ok', name, next: [...list, name] }
+}
+
+export const replaceAt = (list: readonly string[], position: number, name: string): string[] => list.map((n, i) => (i === position ? name : n))
+export const withoutAt = (list: readonly string[], position: number): string[] => list.filter((_, i) => i !== position)

package/src/flow/geometry/arrange.ts

@@ -0,0 +1,74 @@
+// Arithmetic behind "align", "distribute" and "group" of SelectionArrange.
+// Works on plain boxes keyed by id; callers map results back onto nodes.
+
+import type { Point, Rect } from '../model/types'
+import { enclosingRect } from './rect'
+
+export type AlignEdge = 'left' | 'right' | 'top' | 'bottom' | 'centerHorizontal' | 'centerVertical'
+export type DistributeAxis = 'horizontal' | 'vertical'
+
+export interface Placed {
+  id: string
+  rect: Rect
+}
+
+/** New top-left corners after aligning the boxes along one edge or centre line. */
+export function alignBoxes(boxes: readonly Placed[], edge: AlignEdge): Map<string, Point> {
+  const moved = new Map<string, Point>()
+  if (boxes.length < 2) return moved
+  const lefts = boxes.map((b) => b.rect.x)
+  const tops = boxes.map((b) => b.rect.y)
+  const rights = boxes.map((b) => b.rect.x + b.rect.width)
+  const bottoms = boxes.map((b) => b.rect.y + b.rect.height)
+  const cxs = boxes.map((b) => b.rect.x + b.rect.width / 2)
+  const cys = boxes.map((b) => b.rect.y + b.rect.height / 2)
+  const midX = (Math.min(...cxs) + Math.max(...cxs)) / 2
+  const midY = (Math.min(...cys) + Math.max(...cys)) / 2
+  for (const { id, rect } of boxes) {
+    let { x, y } = rect
+    if (edge === 'left') x = Math.min(...lefts)
+    if (edge === 'right') x = Math.max(...rights) - rect.width
+    if (edge === 'top') y = Math.min(...tops)
+    if (edge === 'bottom') y = Math.max(...bottoms) - rect.height
+    // "Centre horizontally" lines centres up on a vertical line (shared x).
+    if (edge === 'centerHorizontal') x = midX - rect.width / 2
+    if (edge === 'centerVertical') y = midY - rect.height / 2
+    moved.set(id, { x, y })
+  }
+  return moved
+}
+
+/**
+ * Keeps the first and last box (by position on the axis) in place and gives
+ * every neighbouring pair the same gap.
+ */
+export function distributeBoxes(boxes: readonly Placed[], axis: DistributeAxis): Map<string, Point> {
+  const moved = new Map<string, Point>()
+  if (boxes.length < 3) return moved
+  const key = axis === 'horizontal' ? 'x' : 'y'
+  const extent = axis === 'horizontal' ? 'width' : 'height'
+  const sorted = [...boxes].sort((a, b) => a.rect[key] - b.rect[key])
+  const first = sorted[0]!
+  const last = sorted[sorted.length - 1]!
+  const occupied = sorted.reduce((sum, b) => sum + b.rect[extent], 0)
+  const span = last.rect[key] + last.rect[extent] - first.rect[key]
+  const gap = (span - occupied) / (sorted.length - 1)
+  let cursor = first.rect[key]
+  for (const b of sorted) {
+    moved.set(b.id, axis === 'horizontal' ? { x: cursor, y: b.rect.y } : { x: b.rect.x, y: cursor })
+    cursor += b.rect[extent] + gap
+  }
+  return moved
+}
+
+/** Frame box for a group around `boxes`: padding on every side plus a header band on top. */
+export function frameAround(boxes: readonly Placed[], padding: number, header: number): Rect | null {
+  const bounds = enclosingRect(boxes.map((b) => b.rect))
+  if (!bounds) return null
+  return {
+    x: bounds.x - padding,
+    y: bounds.y - padding - header,
+    width: bounds.width + padding * 2,
+    height: bounds.height + padding * 2 + header,
+  }
+}

package/src/flow/geometry/curve.ts

@@ -0,0 +1,58 @@
+import type { Point, Side } from '../model/types'
+
+/** An end of a connector: where it touches the node and which way that side faces. */
+export interface CurveEnd {
+  point: Point
+  side: Side
+}
+
+export interface CurveGeometry {
+  /** SVG path data (one cubic segment). */
+  d: string
+  /** Point halfway along the curve parameter, for labels and controls. */
+  mid: Point
+  /** Unit direction of travel where the curve meets the target. */
+  arrival: Point
+}
+
+const OUTWARD: Record<Side, Point> = {
+  start: { x: -1, y: 0 },
+  end: { x: 1, y: 0 },
+  top: { x: 0, y: -1 },
+  bottom: { x: 0, y: 1 },
+}
+
+const round = (n: number) => Math.round(n * 100) / 100
+
+/**
+ * A single cubic segment that leaves `from` perpendicular to its side and
+ * arrives at `to` perpendicular to its side. The handle length grows with the
+ * distance between the ends, within bounds, so short hops stay tight and long
+ * ones stay smooth.
+ */
+export function connectorCurve(from: CurveEnd, to: CurveEnd): CurveGeometry {
+  const span = Math.hypot(to.point.x - from.point.x, to.point.y - from.point.y)
+  const reach = Math.min(160, Math.max(24, span * 0.45))
+  const a = OUTWARD[from.side]
+  const b = OUTWARD[to.side]
+  const c1 = { x: from.point.x + a.x * reach, y: from.point.y + a.y * reach }
+  const c2 = { x: to.point.x + b.x * reach, y: to.point.y + b.y * reach }
+  // Bernstein weights at t = 1/2 are 1/8, 3/8, 3/8, 1/8.
+  const mid = {
+    x: (from.point.x + 3 * c1.x + 3 * c2.x + to.point.x) / 8,
+    y: (from.point.y + 3 * c1.y + 3 * c2.y + to.point.y) / 8,
+  }
+  const ax = to.point.x - c2.x
+  const ay = to.point.y - c2.y
+  const len = Math.hypot(ax, ay) || 1
+  const d = `M${round(from.point.x)},${round(from.point.y)} C${round(c1.x)},${round(c1.y)} ${round(c2.x)},${round(c2.y)} ${round(to.point.x)},${round(to.point.y)}`
+  return { d, mid, arrival: { x: ax / len, y: ay / len } }
+}
+
+/** Side a free pointer end should be treated as facing, given where the line comes from. */
+export function facingSide(from: Point, to: Point): Side {
+  const dx = to.x - from.x
+  const dy = to.y - from.y
+  if (Math.abs(dx) >= Math.abs(dy)) return dx >= 0 ? 'start' : 'end'
+  return dy >= 0 ? 'top' : 'bottom'
+}

package/src/flow/geometry/geometry.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import { topologicalOrder, withinHops } from '../model/graph'
+import { alignBoxes, distributeBoxes, frameAround } from './arrange'
+import { connectorCurve } from './curve'
+import { findGuides } from './guides'
+import { absoluteRect, exitPoint, pointOnSide } from './rect'
+import { fitBounds, ladderStep, revealRect, zoomAt } from './viewport'
+
+describe('graph helpers', () => {
+  it('orders topologically, keeping input order as tie-break and appending cycles', () => {
+    expect(topologicalOrder(['C', 'B', 'A'], [{ source: 'A', target: 'B' }, { source: 'B', target: 'C' }])).toEqual(['A', 'B', 'C'])
+    expect(topologicalOrder(['X', 'Y', 'Z'], [{ source: 'X', target: 'Y' }, { source: 'Y', target: 'X' }])).toEqual(['Z', 'X', 'Y'])
+  })
+
+  it('finds ids within N hops backward and forward', () => {
+    const pairs = [
+      { source: 'q', target: 'r' },
+      { source: 'r', target: 's' },
+      { source: 's', target: 'a' },
+      { source: 'a', target: 'm' },
+    ]
+    expect([...withinHops('s', pairs, 1, 'backward').keys()].sort()).toEqual(['r', 's'])
+    expect([...withinHops('s', pairs, 2, 'both').keys()].sort()).toEqual(['a', 'm', 'q', 'r', 's'])
+    expect(withinHops('s', pairs, 2, 'forward').get('m')).toBe(2)
+  })
+})
+
+describe('geometry', () => {
+  it('resolves grouped positions to absolute boxes', () => {
+    const g = { id: 'g', kind: 'group', position: { x: 100, y: 50 }, data: {}, size: { width: 400, height: 300 } }
+    const c = { id: 'c', kind: 'code', position: { x: 10, y: 20 }, data: {}, parentId: 'g', size: { width: 100, height: 40 } }
+    const byId = new Map([
+      ['g', g],
+      ['c', c],
+    ])
+    expect(absoluteRect(c, byId)).toEqual({ x: 110, y: 70, width: 100, height: 40 })
+  })
+
+  it('places points on sides and on the border towards a target', () => {
+    const r = { x: 0, y: 0, width: 100, height: 50 }
+    expect(pointOnSide(r, 'top', 0.25)).toEqual({ x: 25, y: 0 })
+    expect(exitPoint(r, { x: 500, y: 25 })).toEqual({ point: { x: 100, y: 25 }, side: 'end' })
+    expect(exitPoint(r, { x: 50, y: -300 }).side).toBe('top')
+  })
+
+  it('draws a cubic whose midpoint lies between its ends', () => {
+    const g = connectorCurve({ point: { x: 0, y: 0 }, side: 'end' }, { point: { x: 200, y: 0 }, side: 'start' })
+    expect(g.d.startsWith('M0,0 C')).toBe(true)
+    expect(g.mid.x).toBeCloseTo(100)
+    expect(g.arrival.x).toBeGreaterThan(0)
+  })
+
+  it('fits bounds, zooms around a pivot and steps the zoom ladder', () => {
+    const v = fitBounds({ x: 0, y: 0, width: 400, height: 200 }, { width: 800, height: 600 }, 0, { min: 0.1, max: 4 }, 4)
+    expect(v.zoom).toBe(2)
+    const z = zoomAt({ x: 0, y: 0, zoom: 1 }, 2, { x: 100, y: 100 })
+    expect(z).toEqual({ x: -100, y: -100, zoom: 2 })
+    expect(ladderStep(1, 1)).toBe(1.1)
+    expect(ladderStep(1, -1)).toBe(0.9)
+    const revealed = revealRect({ x: 0, y: 0, zoom: 1 }, { x: 900, y: 10, width: 100, height: 40 }, { width: 800, height: 600 }, 20)
+    expect(revealed.x).toBe(-220)
+  })
+
+  it('finds the closest alignment guide per axis within the threshold', () => {
+    const moving = { x: 102, y: 0, width: 50, height: 20 }
+    const m = findGuides(moving, [
+      { id: 'far', rect: { x: 105, y: 400, width: 10, height: 10 } },
+      { id: 'near', rect: { x: 100, y: 300, width: 10, height: 10 } },
+    ])
+    expect(m.vertical).toBe(100)
+    expect(m.verticalWith).toBe('near')
+    expect(m.horizontal).toBeNull()
+  })
+
+  it('aligns, distributes and frames boxes', () => {
+    const boxes = [
+      { id: 'a', rect: { x: 10, y: 0, width: 100, height: 20 } },
+      { id: 'b', rect: { x: 50, y: 30, width: 100, height: 20 } },
+      { id: 'c', rect: { x: 90, y: 60, width: 100, height: 20 } },
+    ]
+    expect([...alignBoxes(boxes, 'left').values()].map((p) => p.x)).toEqual([10, 10, 10])
+    const right = alignBoxes([{ id: 'a', rect: { x: 0, y: 0, width: 100, height: 10 } }, { id: 'b', rect: { x: 300, y: 0, width: 100, height: 10 } }], 'right')
+    expect([...right.values()].map((p) => p.x + 100)).toEqual([400, 400])
+    const spread = distributeBoxes(
+      [
+        { id: 'a', rect: { x: 0, y: 0, width: 20, height: 10 } },
+        { id: 'b', rect: { x: 50, y: 0, width: 20, height: 10 } },
+        { id: 'c', rect: { x: 400, y: 0, width: 20, height: 10 } },
+      ],
+      'horizontal',
+    )
+    expect(spread.get('a')!.x).toBe(0)
+    expect(spread.get('c')!.x).toBe(400)
+    expect(spread.get('b')!.x - 20).toBeCloseTo(400 - (spread.get('b')!.x + 20))
+    expect(frameAround(boxes, 10, 30)).toEqual({ x: 0, y: -40, width: 200, height: 130 })
+  })
+})

package/src/flow/geometry/guides.ts

@@ -0,0 +1,49 @@
+import type { Rect } from '../model/types'
+
+/** Guide lines found while a node is dragged, in canvas units. */
+export interface GuidePositions {
+  /** y of a horizontal guide, or null. */
+  horizontal: number | null
+  /** x of a vertical guide, or null. */
+  vertical: number | null
+}
+
+export interface GuideMatch extends GuidePositions {
+  /** Ids of the nodes each guide aligns with (for announcements). */
+  horizontalWith: string | null
+  verticalWith: string | null
+}
+
+export const NO_GUIDES: Readonly<GuidePositions> = Object.freeze({ horizontal: null, vertical: null })
+
+/** Snap distance in canvas units within which two lines count as aligned. */
+export const GUIDE_THRESHOLD = 6
+
+const xLines = (r: Rect) => [r.x, r.x + r.width / 2, r.x + r.width]
+const yLines = (r: Rect) => [r.y, r.y + r.height / 2, r.y + r.height]
+
+/**
+ * Compares the start, centre and end lines of `moving` with those of every
+ * other box on each axis and keeps the closest match within the threshold.
+ */
+export function findGuides(moving: Rect, others: ReadonlyArray<{ id: string; rect: Rect }>, threshold = GUIDE_THRESHOLD): GuideMatch {
+  let bestX = { gap: threshold + 1, at: null as number | null, id: null as string | null }
+  let bestY = { gap: threshold + 1, at: null as number | null, id: null as string | null }
+  const mx = xLines(moving)
+  const my = yLines(moving)
+  for (const { id, rect } of others) {
+    for (const line of xLines(rect)) {
+      for (const own of mx) {
+        const gap = Math.abs(line - own)
+        if (gap <= threshold && gap < bestX.gap) bestX = { gap, at: line, id }
+      }
+    }
+    for (const line of yLines(rect)) {
+      for (const own of my) {
+        const gap = Math.abs(line - own)
+        if (gap <= threshold && gap < bestY.gap) bestY = { gap, at: line, id }
+      }
+    }
+  }
+  return { vertical: bestX.at, horizontal: bestY.at, verticalWith: bestX.id, horizontalWith: bestY.id }
+}

package/src/flow/geometry/rect.ts

@@ -0,0 +1,101 @@
+import type { FlowNode, Point, Rect, Side, Size } from '../model/types'
+
+/** Size assumed for a node that neither declares nor has a measured size. */
+export const FALLBACK_NODE_SIZE: Readonly<Size> = Object.freeze({ width: 256, height: 96 })
+
+/** Measured size, else declared size, else the fallback. */
+export function sizeOf(node: Pick<FlowNode, 'size' | 'measured'>, fallback: Size = FALLBACK_NODE_SIZE): Size {
+  const m = node.measured
+  if (m && m.width > 0 && m.height > 0) return { width: m.width, height: m.height }
+  const d = node.size
+  if (d && d.width > 0 && d.height > 0) return { width: d.width, height: d.height }
+  return { width: fallback.width, height: fallback.height }
+}
+
+/**
+ * Absolute box of a node on the canvas. Positions of grouped nodes are
+ * relative to their frame, so the frame chain is followed.
+ */
+export function absoluteRect(node: FlowNode, byId: ReadonlyMap<string, FlowNode>, fallback?: Size): Rect {
+  let x = node.position.x
+  let y = node.position.y
+  let parent = node.parentId ? byId.get(node.parentId) : undefined
+  const seen = new Set<string>([node.id])
+  while (parent && !seen.has(parent.id)) {
+    seen.add(parent.id)
+    x += parent.position.x
+    y += parent.position.y
+    parent = parent.parentId ? byId.get(parent.parentId) : undefined
+  }
+  return { x, y, ...sizeOf(node, fallback) }
+}
+
+export function centreOf(r: Rect): Point {
+  return { x: r.x + r.width / 2, y: r.y + r.height / 2 }
+}
+
+/** Smallest box holding every rect, or null for none. */
+export function enclosingRect(rects: readonly Rect[]): Rect | null {
+  if (!rects.length) return null
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+  for (const r of rects) {
+    minX = Math.min(minX, r.x)
+    minY = Math.min(minY, r.y)
+    maxX = Math.max(maxX, r.x + r.width)
+    maxY = Math.max(maxY, r.y + r.height)
+  }
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+}
+
+export function growRect(r: Rect, by: number): Rect {
+  return { x: r.x - by, y: r.y - by, width: r.width + by * 2, height: r.height + by * 2 }
+}
+
+export function containsPoint(r: Rect, p: Point): boolean {
+  return p.x >= r.x && p.x <= r.x + r.width && p.y >= r.y && p.y <= r.y + r.height
+}
+
+export function rectsOverlap(a: Rect, b: Rect): boolean {
+  return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height
+}
+
+/**
+ * Point on a side of a box. `along` is 0..1 from the top (inline sides) or
+ * from the start (block sides); 0.5 is the middle.
+ */
+export function pointOnSide(r: Rect, side: Side, along = 0.5): Point {
+  const t = Math.min(1, Math.max(0, along))
+  switch (side) {
+    case 'start':
+      return { x: r.x, y: r.y + r.height * t }
+    case 'end':
+      return { x: r.x + r.width, y: r.y + r.height * t }
+    case 'top':
+      return { x: r.x + r.width * t, y: r.y }
+    case 'bottom':
+      return { x: r.x + r.width * t, y: r.y + r.height }
+  }
+}
+
+/**
+ * Where the ray from the centre of `r` towards `towards` leaves the box, and
+ * which side it crosses. Used by border-attached ("floating") connectors.
+ */
+export function exitPoint(r: Rect, towards: Point): { point: Point; side: Side } {
+  const c = centreOf(r)
+  const dx = towards.x - c.x
+  const dy = towards.y - c.y
+  if (dx === 0 && dy === 0) return { point: { x: r.x + r.width, y: c.y }, side: 'end' }
+  const halfW = r.width / 2
+  const halfH = r.height / 2
+  // Scale factor at which the ray meets each pair of sides; the smaller wins.
+  const tx = dx === 0 ? Infinity : halfW / Math.abs(dx)
+  const ty = dy === 0 ? Infinity : halfH / Math.abs(dy)
+  if (tx <= ty) {
+    return { point: { x: c.x + dx * tx, y: c.y + dy * tx }, side: dx > 0 ? 'end' : 'start' }
+  }
+  return { point: { x: c.x + dx * ty, y: c.y + dy * ty }, side: dy > 0 ? 'bottom' : 'top' }
+}

package/src/flow/geometry/viewport.ts

@@ -0,0 +1,70 @@
+import type { Point, Rect, Size, Viewport } from '../model/types'
+
+export interface ZoomLimits {
+  min: number
+  max: number
+}
+
+export const DEFAULT_ZOOM_LIMITS: Readonly<ZoomLimits> = Object.freeze({ min: 0.2, max: 2.5 })
+
+/** Zoom steps used by the zoom in / zoom out tools (a readable ladder, not a factor). */
+export const ZOOM_LADDER = [0.2, 0.25, 0.33, 0.5, 0.67, 0.75, 0.9, 1, 1.1, 1.25, 1.5, 1.75, 2, 2.5] as const
+
+export function clampZoom(z: number, limits: ZoomLimits = DEFAULT_ZOOM_LIMITS): number {
+  return Math.min(limits.max, Math.max(limits.min, z))
+}
+
+export function screenToCanvas(v: Viewport, p: Point): Point {
+  return { x: (p.x - v.x) / v.zoom, y: (p.y - v.y) / v.zoom }
+}
+
+export function canvasToScreen(v: Viewport, p: Point): Point {
+  return { x: p.x * v.zoom + v.x, y: p.y * v.zoom + v.y }
+}
+
+/** New viewport with zoom `z` that keeps the canvas point under `pivot` (screen) still. */
+export function zoomAt(v: Viewport, z: number, pivot: Point, limits?: ZoomLimits): Viewport {
+  const zoom = clampZoom(z, limits)
+  const anchor = screenToCanvas(v, pivot)
+  return { zoom, x: pivot.x - anchor.x * zoom, y: pivot.y - anchor.y * zoom }
+}
+
+/** Next step of the zoom ladder above (`+1`) or below (`-1`) the current zoom. */
+export function ladderStep(current: number, direction: 1 | -1, limits?: ZoomLimits): number {
+  const eps = 0.001
+  const steps = direction > 0 ? ZOOM_LADDER.filter((s) => s > current + eps) : [...ZOOM_LADDER].reverse().filter((s) => s < current - eps)
+  return clampZoom(steps[0] ?? current, limits)
+}
+
+/** Viewport that shows `bounds` centred in a container, with `padding` screen px around it. */
+export function fitBounds(bounds: Rect | null, container: Size, padding = 48, limits: ZoomLimits = DEFAULT_ZOOM_LIMITS, maxFitZoom = 1): Viewport {
+  if (!bounds || container.width <= 0 || container.height <= 0) return { x: 0, y: 0, zoom: 1 }
+  const availW = Math.max(1, container.width - padding * 2)
+  const availH = Math.max(1, container.height - padding * 2)
+  const raw = Math.min(availW / Math.max(1, bounds.width), availH / Math.max(1, bounds.height))
+  const zoom = clampZoom(Math.min(raw, maxFitZoom), limits)
+  const x = (container.width - bounds.width * zoom) / 2 - bounds.x * zoom
+  const y = (container.height - bounds.height * zoom) / 2 - bounds.y * zoom
+  return { x, y, zoom }
+}
+
+/** Viewport shifted just enough to bring `target` (canvas rect) inside the container, with a margin. */
+export function revealRect(v: Viewport, target: Rect, container: Size, margin = 32): Viewport {
+  const left = target.x * v.zoom + v.x
+  const top = target.y * v.zoom + v.y
+  const right = left + target.width * v.zoom
+  const bottom = top + target.height * v.zoom
+  let dx = 0
+  let dy = 0
+  if (left < margin) dx = margin - left
+  else if (right > container.width - margin) dx = container.width - margin - right
+  if (top < margin) dy = margin - top
+  else if (bottom > container.height - margin) dy = container.height - margin - bottom
+  if (!dx && !dy) return v
+  return { ...v, x: v.x + dx, y: v.y + dy }
+}
+
+/** The part of the canvas currently on screen. */
+export function visibleArea(v: Viewport, container: Size): Rect {
+  return { x: -v.x / v.zoom, y: -v.y / v.zoom, width: container.width / v.zoom, height: container.height / v.zoom }
+}

package/src/flow/index.ts

@@ -0,0 +1,58 @@
+// @datatechsolutions/tympan/flow (FSL-1.1-ALv2), the flow and provenance canvas
+// (formerly the @datatechsolutions/tympan-flow package). It needs the optional
+// peer @dagrejs/dagre. Import the stylesheets once, design system first:
+//   import '@datatechsolutions/tympan/styles.css'
+//   import '@datatechsolutions/tympan/flow.css'
+
+// Model and pure helpers
+export * from './model/types'
+export * from './model/graph'
+export * from './geometry/rect'
+export * from './geometry/viewport'
+export * from './geometry/curve'
+export * from './geometry/guides'
+export * from './geometry/arrange'
+export * from './layout/autoLayout'
+
+// Catalog, palette tokens and node state attributes
+export * from './catalog/kindCatalog'
+export * from './catalog/icons'
+export * from './catalog/palette'
+export * from './catalog/nodeState'
+export * from './catalog/RenderCatalog'
+
+// Editor state
+export * from './state/store'
+export * from './state/graphEdits'
+export * from './state/editorState'
+export * from './state/dialogStack'
+
+// Shared infrastructure
+export { AnnouncerProvider, useAnnounce } from './internal/Announcer'
+export { ConfirmProvider, useConfirm, type ConfirmFn, type ConfirmOptions } from './internal/confirm'
+export { SectionedModal, type SectionedModalProps, type ModalSection } from './internal/SectionedModal'
+export { DockedPanel, type DockedPanelProps } from './internal/DockedPanel'
+export { formatDuration, formatRelative, formatDateTime } from './internal/format'
+/** Host i18n adapter: `messages[componentKey]` overrides a component's labels (ICU templates). */
+export { FlowMessagesProvider, builtInLabels, BUILT_IN_LOCALES, type LabelDefinition } from './internal/labels'
+
+// Canvas surface
+export * from './surface/types'
+export { CanvasSurface, type CanvasSurfaceProps } from './surface/CanvasSurface'
+export { useSurface, type SurfaceContextValue } from './surface/SurfaceContext'
+
+// Component groups
+export * from './nodes'
+export * from './connectors'
+export * from './decision'
+export * from './provenance'
+export * from './editor'
+export * from './steps'
+export * from './toolbar'
+export * from './run'
+export * from './forms'
+export * from './expressions'
+export * from './dialogs'
+export * from './agents'
+export * from './assistant'
+export * from './report'