@typeonce/effect-machine-devtools 0.24.0 → 0.25.0

package/src/internal/browser/chart-layout.ts

@@ -0,0 +1,433 @@
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import type {
+  ELK as ElkApi,
+  ELKConstructorArguments,
+  ElkExtendedEdge,
+  ElkNode,
+  ElkPoint,
+  ElkPort
+} from "elkjs/lib/elk-api.js"
+import ELKBundle from "elkjs/lib/elk.bundled.js"
+import type { ChartEdge, ChartInitial, ChartModel, ChartNode, ChartRuntimeTarget } from "./chart-model.js"
+
+export const maxVisibleFields = 4
+export const maxVisibleActivities = 3
+
+export interface ChartPoint {
+  readonly x: number
+  readonly y: number
+}
+
+export interface LaidOutChartNode {
+  readonly node: ChartNode
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+  readonly headerHeight: number
+}
+
+export interface LaidOutChartInitial {
+  readonly initial: ChartInitial
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+export interface LaidOutChartRuntimeTarget {
+  readonly target: ChartRuntimeTarget
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+export interface LaidOutChartTransition {
+  readonly kind: "transition"
+  readonly edge: ChartEdge
+  readonly points: ReadonlyArray<ChartPoint>
+  readonly label: ChartPoint
+  readonly labelWidth: number
+  readonly labelHeight: number
+}
+
+export interface LaidOutChartInitialEdge {
+  readonly kind: "initial"
+  readonly initial: ChartInitial
+  readonly points: ReadonlyArray<ChartPoint>
+}
+
+export interface LaidOutChart {
+  readonly width: number
+  readonly height: number
+  readonly nodes: ReadonlyArray<LaidOutChartNode>
+  readonly initials: ReadonlyArray<LaidOutChartInitial>
+  readonly runtimeTargets: ReadonlyArray<LaidOutChartRuntimeTarget>
+  readonly edges: ReadonlyArray<LaidOutChartTransition | LaidOutChartInitialEdge>
+}
+
+export class ChartLayoutError extends Data.TaggedError("ChartLayoutError")<{
+  readonly cause: unknown
+}> {}
+
+interface NodeMetric {
+  readonly width: number
+  readonly height: number
+  readonly headerHeight: number
+}
+
+const sectionHeight = (length: number, limit: number): number => {
+  if (length === 0) return 0
+  const visible = Math.min(length, limit)
+  return 24 + visible * 22 + (length > limit ? 18 : 0)
+}
+
+const nodeMetric = (node: ChartNode): NodeMetric => {
+  const headerHeight = Math.max(
+    78,
+    76 +
+      sectionHeight(node.fields.length, maxVisibleFields) +
+      sectionHeight(node.activities.length, maxVisibleActivities)
+  )
+  const width = node.type === "choice" || node.type === "history" ? 176 : node.children.length > 0 ? 340 : 276
+  return {
+    width,
+    height: node.children.length === 0 ? headerHeight : Math.max(240, headerHeight + 104),
+    headerHeight
+  }
+}
+
+const ELK = ELKBundle as unknown as new(args?: ELKConstructorArguments) => ElkApi
+const elk = new ELK()
+
+const sourcePortId = (edge: ChartEdge): string => `port:${edge.id}:source`
+const targetPortId = (edge: ChartEdge): string => `port:${edge.id}:target`
+const initialNodeId = (initial: ChartInitial): string => `node:${initial.id}`
+const initialTargetPortId = (initial: ChartInitial): string => `port:${initial.id}:target`
+const runtimeNodeId = (target: ChartRuntimeTarget): string => `node:${target.id}`
+const runtimeTargetPortId = (target: ChartRuntimeTarget): string => `port:${target.edgeId}:target`
+
+const portsByState = (model: ChartModel): ReadonlyMap<string, ReadonlyArray<ElkPort>> => {
+  const ports = new Map<string, Array<ElkPort>>()
+  const add = (path: string, id: string, side: "EAST" | "WEST"): void => {
+    const statePorts = ports.get(path) ?? []
+    statePorts.push({
+      id,
+      width: 6,
+      height: 6,
+      layoutOptions: {
+        "elk.port.side": side,
+        "elk.port.index": String(statePorts.length)
+      }
+    })
+    ports.set(path, statePorts)
+  }
+
+  for (const edge of model.edges) {
+    add(edge.source, sourcePortId(edge), "EAST")
+    if (edge.kind === "target" && edge.target !== null) {
+      add(edge.target, targetPortId(edge), "WEST")
+    } else if (edge.kind === "targetless") {
+      add(edge.source, targetPortId(edge), "EAST")
+    }
+  }
+  for (const initial of model.initials) add(initial.target, initialTargetPortId(initial), "WEST")
+  return ports
+}
+
+const labelMetric = (label: string): { readonly width: number; readonly height: number } => ({
+  width: Math.min(230, Math.max(72, label.length * 7 + 20)),
+  height: 26
+})
+
+const makeGraph = (model: ChartModel): ElkNode => {
+  const nodesByParent = new Map<string | null, Array<ChartNode>>()
+  for (const node of model.nodes) {
+    const siblings = nodesByParent.get(node.parent) ?? []
+    siblings.push(node)
+    nodesByParent.set(node.parent, siblings)
+  }
+  const initialsByParent = new Map<string | null, Array<ChartInitial>>()
+  for (const initial of model.initials) {
+    const siblings = initialsByParent.get(initial.parent) ?? []
+    siblings.push(initial)
+    initialsByParent.set(initial.parent, siblings)
+  }
+  const runtimeTargetsByParent = new Map<string | null, Array<ChartRuntimeTarget>>()
+  for (const target of model.runtimeTargets) {
+    const siblings = runtimeTargetsByParent.get(target.parent) ?? []
+    siblings.push(target)
+    runtimeTargetsByParent.set(target.parent, siblings)
+  }
+  const ports = portsByState(model)
+
+  const children = (parent: string | null): Array<ElkNode> => [
+    ...(initialsByParent.get(parent) ?? []).map((initial): ElkNode => ({
+      id: initialNodeId(initial),
+      width: 14,
+      height: 14
+    })),
+    ...(nodesByParent.get(parent) ?? []).map((node): ElkNode => {
+      const metric = nodeMetric(node)
+      const descendants = children(node.path)
+      const common = {
+        id: node.path,
+        ports: [...ports.get(node.path) ?? []]
+      }
+      if (descendants.length === 0) {
+        return {
+          ...common,
+          width: metric.width,
+          height: metric.height,
+          layoutOptions: {
+            "elk.portConstraints": "FIXED_ORDER",
+            "elk.spacing.portPort": "22"
+          }
+        }
+      }
+      return {
+        ...common,
+        children: descendants,
+        layoutOptions: {
+          "elk.algorithm": "layered",
+          "elk.direction": "RIGHT",
+          "elk.padding": `[top=${metric.headerHeight + 28},left=28,bottom=28,right=28]`,
+          "elk.nodeSize.constraints": "MINIMUM_SIZE",
+          "elk.nodeSize.minimum": `(${metric.width}, ${metric.height})`,
+          "elk.portConstraints": "FIXED_ORDER",
+          "elk.spacing.portPort": "22",
+          "elk.spacing.nodeNode": "44",
+          "elk.layered.spacing.nodeNodeBetweenLayers": "108"
+        }
+      }
+    }),
+    ...(runtimeTargetsByParent.get(parent) ?? []).map((target): ElkNode => ({
+      id: runtimeNodeId(target),
+      width: 118,
+      height: 34,
+      ports: [{
+        id: runtimeTargetPortId(target),
+        width: 6,
+        height: 6,
+        layoutOptions: { "elk.port.side": "WEST" }
+      }],
+      layoutOptions: { "elk.portConstraints": "FIXED_SIDE" }
+    }))
+  ]
+
+  return {
+    id: "chart-root",
+    children: children(null),
+    edges: [
+      ...model.edges.map((edge): ElkExtendedEdge => {
+        const label = labelMetric(edge.label)
+        return {
+          id: edge.id,
+          sources: [sourcePortId(edge)],
+          targets: [targetPortId(edge)],
+          labels: [{ text: edge.label, width: label.width, height: label.height }]
+        }
+      }),
+      ...model.initials.map((initial): ElkExtendedEdge => ({
+        id: initial.id,
+        sources: [initialNodeId(initial)],
+        targets: [initialTargetPortId(initial)]
+      }))
+    ],
+    layoutOptions: {
+      "elk.algorithm": "layered",
+      "elk.direction": "RIGHT",
+      "elk.hierarchyHandling": "INCLUDE_CHILDREN",
+      "elk.edgeRouting": "ORTHOGONAL",
+      "elk.padding": "[top=44,left=44,bottom=44,right=44]",
+      "elk.spacing.nodeNode": "64",
+      "elk.layered.spacing.nodeNodeBetweenLayers": "148",
+      "elk.layered.spacing.edgeNodeBetweenLayers": "42",
+      "elk.layered.spacing.edgeEdgeBetweenLayers": "26",
+      "elk.spacing.edgeNode": "28",
+      "elk.spacing.edgeEdge": "20",
+      "elk.layered.crossingMinimization.strategy": "LAYER_SWEEP",
+      "elk.layered.crossingMinimization.greedySwitchHierarchical.type": "TWO_SIDED",
+      "elk.layered.nodePlacement.favorStraightEdges": "true",
+      "elk.layered.mergeHierarchyEdges": "false",
+      "elk.layered.thoroughness": "12",
+      "elk.randomSeed": "1"
+    }
+  }
+}
+
+const add = (left: ChartPoint, right: ChartPoint): ChartPoint => ({
+  x: left.x + right.x,
+  y: left.y + right.y
+})
+
+const compactPoints = (points: ReadonlyArray<ChartPoint>): ReadonlyArray<ChartPoint> => {
+  const result: Array<ChartPoint> = []
+  for (const point of points) {
+    const previous = result.at(-1)
+    if (previous !== undefined && previous.x === point.x && previous.y === point.y) continue
+    const beforePrevious = result.at(-2)
+    if (
+      beforePrevious !== undefined && previous !== undefined &&
+      (beforePrevious.x === previous.x && previous.x === point.x ||
+        beforePrevious.y === previous.y && previous.y === point.y)
+    ) {
+      result[result.length - 1] = point
+    } else {
+      result.push(point)
+    }
+  }
+  return result
+}
+
+const edgePoints = (edge: ElkExtendedEdge, offset: ChartPoint): ReadonlyArray<ChartPoint> | undefined => {
+  const sections = edge.sections
+  if (sections === undefined || sections.length === 0) return undefined
+  const byId = new Map(sections.map((section) => [section.id, section]))
+  let section =
+    sections.find((candidate) =>
+      candidate.incomingShape !== undefined || candidate.incomingSections === undefined ||
+      candidate.incomingSections.length === 0
+    ) ?? sections[0]
+  const points: Array<ElkPoint> = []
+  const visited = new Set<string>()
+  while (section !== undefined && !visited.has(section.id)) {
+    visited.add(section.id)
+    if (points.length === 0) points.push(section.startPoint)
+    points.push(...(section.bendPoints ?? []), section.endPoint)
+    const next = section.outgoingSections?.[0]
+    section = next === undefined ? undefined : byId.get(next)
+  }
+  return points.length < 2 ? undefined : compactPoints(points.map((point) => add(point, offset)))
+}
+
+const midpoint = (points: ReadonlyArray<ChartPoint>): ChartPoint => {
+  const lengths = points.slice(1).map((point, index) => {
+    const previous = points[index]!
+    return Math.abs(point.x - previous.x) + Math.abs(point.y - previous.y)
+  })
+  const total = lengths.reduce((sum, length) => sum + length, 0)
+  let remaining = total / 2
+  for (let index = 0; index < lengths.length; index++) {
+    const length = lengths[index]!
+    const start = points[index]!
+    const end = points[index + 1]!
+    if (remaining <= length) {
+      const ratio = length === 0 ? 0 : remaining / length
+      return {
+        x: start.x + (end.x - start.x) * ratio,
+        y: start.y + (end.y - start.y) * ratio
+      }
+    }
+    remaining -= length
+  }
+  return points.at(-1)!
+}
+
+const expandTargetlessLoop = (points: ReadonlyArray<ChartPoint>): ReadonlyArray<ChartPoint> => {
+  const start = points[0]
+  const end = points.at(-1)
+  if (start === undefined || end === undefined) return points
+  const outerX = Math.max(...points.map(({ x }) => x)) + 30
+  return compactPoints([
+    start,
+    { x: outerX, y: start.y },
+    { x: outerX, y: end.y },
+    end
+  ])
+}
+
+const collectLayout = (model: ChartModel, graph: ElkNode): LaidOutChart => {
+  const chartNodes = new Map(model.nodes.map((node) => [node.path, node]))
+  const chartInitials = new Map(model.initials.map((initial) => [initialNodeId(initial), initial]))
+  const chartRuntimeTargets = new Map(model.runtimeTargets.map((target) => [runtimeNodeId(target), target]))
+  const offsets = new Map<string, ChartPoint>([[graph.id, { x: 0, y: 0 }]])
+  const nodes: Array<LaidOutChartNode> = []
+  const initials: Array<LaidOutChartInitial> = []
+  const runtimeTargets: Array<LaidOutChartRuntimeTarget> = []
+
+  const visit = (node: ElkNode, parentOffset: ChartPoint): void => {
+    const absolute = add(parentOffset, { x: node.x ?? 0, y: node.y ?? 0 })
+    offsets.set(node.id, absolute)
+    const chartNode = chartNodes.get(node.id)
+    if (chartNode !== undefined) {
+      const metric = nodeMetric(chartNode)
+      nodes.push({
+        node: chartNode,
+        x: absolute.x,
+        y: absolute.y,
+        width: node.width ?? metric.width,
+        height: node.height ?? metric.height,
+        headerHeight: metric.headerHeight
+      })
+    }
+    const initial = chartInitials.get(node.id)
+    if (initial !== undefined) {
+      initials.push({
+        initial,
+        x: absolute.x,
+        y: absolute.y,
+        width: node.width ?? 14,
+        height: node.height ?? 14
+      })
+    }
+    const runtimeTarget = chartRuntimeTargets.get(node.id)
+    if (runtimeTarget !== undefined) {
+      runtimeTargets.push({
+        target: runtimeTarget,
+        x: absolute.x,
+        y: absolute.y,
+        width: node.width ?? 118,
+        height: node.height ?? 34
+      })
+    }
+    for (const child of node.children ?? []) visit(child, absolute)
+  }
+  for (const child of graph.children ?? []) visit(child, { x: 0, y: 0 })
+
+  const chartEdges = new Map(model.edges.map((edge) => [edge.id, edge]))
+  const initialEdges = new Map(model.initials.map((initial) => [initial.id, initial]))
+  const edges = (graph.edges ?? []).flatMap((edge): ReadonlyArray<LaidOutChartTransition | LaidOutChartInitialEdge> => {
+    const offset = offsets.get(edge.container ?? graph.id) ?? { x: 0, y: 0 }
+    const points = edgePoints(edge, offset)
+    if (points === undefined) return []
+    const chartEdge = chartEdges.get(edge.id)
+    if (chartEdge !== undefined) {
+      const metric = labelMetric(chartEdge.label)
+      const label = edge.labels?.[0]
+      const transitionPoints = chartEdge.kind === "targetless" ? expandTargetlessLoop(points) : points
+      return [{
+        kind: "transition",
+        edge: chartEdge,
+        points: transitionPoints,
+        label: label?.x === undefined || label.y === undefined
+          ? midpoint(transitionPoints)
+          : add(offset, {
+            x: label.x + (label.width ?? metric.width) / 2,
+            y: label.y + (label.height ?? metric.height) / 2
+          }),
+        labelWidth: label?.width ?? metric.width,
+        labelHeight: label?.height ?? metric.height
+      }]
+    }
+    const initial = initialEdges.get(edge.id)
+    return initial === undefined ? [] : [{ kind: "initial", initial, points }]
+  })
+
+  return {
+    width: Math.max(360, graph.width ?? 0),
+    height: Math.max(280, graph.height ?? 0),
+    nodes,
+    initials,
+    runtimeTargets,
+    edges
+  }
+}
+
+export const layoutChart = (model: ChartModel): Effect.Effect<LaidOutChart, ChartLayoutError> =>
+  Effect.tryPromise({
+    try: () => elk.layout(makeGraph(model)),
+    catch: (cause) => new ChartLayoutError({ cause })
+  }).pipe(Effect.map((graph) => collectLayout(model, graph)))

package/src/internal/browser/chart-model.ts

@@ -0,0 +1,234 @@
+import type {
+  Activity as VisualizationActivity,
+  Branch as VisualizationBranch,
+  MachineDocument as VisualizationDocument,
+  State as VisualizationState,
+  Transition as VisualizationTransition
+} from "../../MachineDocument.js"
+import { type InputField, projectInputSchema } from "./input-form.js"
+import { stateLabel, triggerLabel } from "./visualizer-model.js"
+
+export interface ChartField {
+  readonly key: string
+  readonly label: string
+  readonly type: string
+  readonly required: boolean
+}
+
+export interface ChartActivity {
+  readonly id: string
+  readonly kind: VisualizationActivity["type"]
+  readonly label: string
+}
+
+export interface ChartNode {
+  readonly path: string
+  readonly label: string
+  readonly type: VisualizationState["type"]
+  readonly parent: string | null
+  readonly children: ReadonlyArray<string>
+  readonly active: boolean
+  readonly initial: boolean
+  readonly fields: ReadonlyArray<ChartField>
+  readonly activities: ReadonlyArray<ChartActivity>
+}
+
+export interface ChartEdge {
+  readonly id: string
+  readonly transitionId: string
+  readonly branchIds: ReadonlyArray<string>
+  readonly kind: "target" | "targetless" | "runtime"
+  readonly source: string
+  readonly target: string | null
+  readonly label: string
+  readonly trigger: VisualizationTransition["trigger"]
+  readonly reenter: boolean
+  readonly acceptance: VisualizationTransition["acceptance"]
+}
+
+export interface ChartRuntimeTarget {
+  readonly id: string
+  readonly edgeId: string
+  readonly parent: string | null
+  readonly label: string
+}
+
+export interface ChartInitial {
+  readonly id: string
+  readonly target: string
+  readonly parent: string | null
+}
+
+export interface ChartModel {
+  readonly machineId: string
+  readonly roots: ReadonlyArray<string>
+  readonly nodes: ReadonlyArray<ChartNode>
+  readonly edges: ReadonlyArray<ChartEdge>
+  readonly runtimeTargets: ReadonlyArray<ChartRuntimeTarget>
+  readonly initials: ReadonlyArray<ChartInitial>
+}
+
+const literalType = (value: string | number | boolean | null): string =>
+  typeof value === "string" ? JSON.stringify(value) : String(value)
+
+const fieldType = (field: InputField): string => {
+  switch (field._tag) {
+    case "String":
+      return field.format ?? "string"
+    case "Number":
+      return field.integer ? "integer" : "number"
+    case "Boolean":
+      return "boolean"
+    case "Enum":
+      return field.values.map(literalType).join(" | ")
+    case "Literal":
+      return literalType(field.value)
+    case "Object":
+      return "object"
+    case "Array":
+      return `${fieldType(field.item)}[]`
+    case "Union":
+      return field.alternatives.map(fieldType).join(" | ")
+    case "Unsupported":
+      return "unknown"
+  }
+}
+
+const stateFields = (state: VisualizationState): ReadonlyArray<ChartField> => {
+  if (state.valueSchema === null) return []
+  const projected = projectInputSchema(state.valueSchema)
+  if (projected._tag !== "Object") {
+    return [{
+      key: "value",
+      label: projected.title ?? "value",
+      type: fieldType(projected),
+      required: true
+    }]
+  }
+  return projected.fields
+    .filter(({ key }) => key !== "_tag")
+    .map(({ field, key, required }) => ({
+      key,
+      label: field.title ?? key,
+      type: fieldType(field),
+      required
+    }))
+}
+
+const activityLabel = (activity: VisualizationActivity): string => {
+  switch (activity.type) {
+    case "machine":
+      return `${activity.lifecycleId} → ${activity.child.machineId ?? activity.child.id}`
+    case "timer":
+      return `${activity.lifecycleId} · ${activity.duration}`
+    case "process":
+    case "effect":
+    case "stream":
+      return activity.lifecycleId
+  }
+}
+
+const transitionLabel = (transition: VisualizationTransition, branch: VisualizationBranch): string => {
+  const trigger = triggerLabel(transition)
+  return branch.type === "branch" ? `${trigger} · ${branch.title}` : trigger
+}
+
+interface EdgeGroup {
+  readonly kind: ChartEdge["kind"]
+  readonly target: string | null
+  readonly branches: Array<VisualizationBranch>
+}
+
+const edgeGroup = (
+  branch: VisualizationBranch,
+  states: ReadonlyMap<string, VisualizationState>
+): { readonly key: string; readonly kind: ChartEdge["kind"]; readonly target: string | null } => {
+  if (branch.target !== null && states.has(branch.target)) {
+    return { key: `target:${branch.target}`, kind: "target", target: branch.target }
+  }
+  if (branch.selection.kind === "none" || branch.selection.kind === "update") {
+    return { key: "targetless", kind: "targetless", target: null }
+  }
+  return { key: "runtime", kind: "runtime", target: null }
+}
+
+export const makeChartModel = (document: VisualizationDocument): ChartModel => {
+  const active = new Set(document.snapshot?.activePaths ?? [])
+  const initialPaths = new Set([document.initial.target])
+  const activities = new Map(document.activities.map((activity) => [activity.id, activity]))
+  const states = new Map(document.states.map((state) => [state.path, state]))
+
+  for (const state of document.states) {
+    if (state.initial !== null) initialPaths.add(state.initial)
+  }
+
+  const nodes = document.states.map((state): ChartNode => ({
+    path: state.path,
+    label: stateLabel(state),
+    type: state.type,
+    parent: state.parent,
+    children: [...state.children],
+    active: active.has(state.path),
+    initial: initialPaths.has(state.path),
+    fields: stateFields(state),
+    activities: state.activityIds.flatMap((id): ReadonlyArray<ChartActivity> => {
+      const activity = activities.get(id)
+      return activity === undefined ? [] : [{ id, kind: activity.type, label: activityLabel(activity) }]
+    })
+  }))
+
+  const edges = document.transitions.flatMap((transition): ReadonlyArray<ChartEdge> => {
+    if (!states.has(transition.source)) return []
+    const groups = new Map<string, EdgeGroup>()
+    for (const branch of transition.branches) {
+      const group = edgeGroup(branch, states)
+      const current = groups.get(group.key)
+      if (current === undefined) {
+        groups.set(group.key, { kind: group.kind, target: group.target, branches: [branch] })
+      } else {
+        current.branches.push(branch)
+      }
+    }
+    return [...groups].map(([key, { branches, kind, target }]): ChartEdge => ({
+      id: branches.length === 1 ? branches[0]!.id : `${transition.id}:${key}`,
+      transitionId: transition.id,
+      branchIds: branches.map(({ id }) => id),
+      kind,
+      source: transition.source,
+      target,
+      label: branches.length === 1
+        ? transitionLabel(transition, branches[0]!)
+        : `${triggerLabel(transition)} · ${branches.length} branches`,
+      trigger: transition.trigger,
+      reenter: transition.reenter,
+      acceptance: transition.acceptance
+    }))
+  })
+
+  const runtimeTargets = edges.flatMap((edge): ReadonlyArray<ChartRuntimeTarget> => {
+    if (edge.kind !== "runtime") return []
+    const source = states.get(edge.source)
+    return source === undefined
+      ? []
+      : [{
+        id: `runtime:${edge.id}`,
+        edgeId: edge.id,
+        parent: source.parent,
+        label: "runtime target"
+      }]
+  })
+
+  const initials = [...initialPaths].flatMap((target): ReadonlyArray<ChartInitial> => {
+    const state = states.get(target)
+    return state === undefined ? [] : [{ id: `initial:${target}`, target, parent: state.parent }]
+  })
+
+  return {
+    machineId: document.machineId,
+    roots: [...document.roots],
+    nodes,
+    edges,
+    runtimeTargets,
+    initials
+  }
+}