@kestack/web-platform 0.0.0-stage → 0.0.0

package/src/recipes/kabuki-devtools/scene/layout/outline.ts

@@ -0,0 +1,80 @@
+import { curve } from './shapes.ts';
+import type { Box, Branch, Label, Laid, Line } from './shapes.ts';
+
+/*
+ * An outline, top to bottom, like a tree of files: one box under another,
+ * each child indented under its parent, the root's top-left at 0, 0.
+ *
+ * 1. Rows    each box on its own row, in order.
+ * 2. Groups  children led to by the same thing sit under one label row,
+ *            indented once more; the rest straight under their parent.
+ * 3. Lines   down a spine from each box, then across to each child or label.
+ */
+
+const INDENT = 28;
+const GAP = 10;
+const LABEL = 20;
+/** Where on a box its line arrives: level with its name. */
+const ARRIVE = 21;
+
+export const outline = (root: Branch): Laid => {
+  const boxes = new Map<string, Box>();
+  const lines: Line[] = [];
+  const labels: Label[] = [];
+  let y = 0;
+
+  const visit = (branch: Branch, x: number, depth: number, parent?: string) => {
+    // 1. Rows
+    boxes.set(branch.id, {
+      x,
+      y,
+      width: branch.width,
+      height: branch.height,
+      depth,
+      ...(parent ? { parent } : {}),
+    });
+    const spine = { x: x + 14, y: y + branch.height };
+    y += branch.height + GAP;
+
+    // 2. Groups
+    let group:
+      | { readonly via: string; readonly spine: { x: number; y: number } }
+      | undefined;
+    for (const { via, branch: child } of branch.children) {
+      if (via && via !== group?.via) {
+        const labelX = x + INDENT;
+        labels.push({
+          id: `${branch.id}:${via}`,
+          owner: branch.id,
+          text: via,
+          x: labelX,
+          y: y + LABEL / 2,
+          align: 'start',
+        });
+        lines.push({
+          id: `${branch.id}->${via}`,
+          from: branch.id,
+          to: branch.id,
+          via,
+          d: curve(spine, { x: labelX - 4, y: y + LABEL / 2 }, 'across'),
+        });
+        group = { via, spine: { x: labelX + 6, y: y + LABEL } };
+        y += LABEL + GAP / 2;
+      }
+      if (!via) group = undefined;
+      const from = group && via ? group.spine : spine;
+      const childX = from.x + INDENT - 14;
+      // 3. Lines
+      lines.push({
+        id: `${branch.id}->${child.id}`,
+        from: branch.id,
+        to: child.id,
+        ...(via ? { via } : {}),
+        d: curve(from, { x: childX, y: y + ARRIVE }, 'across'),
+      });
+      visit(child, childX, depth + 1, branch.id);
+    }
+  };
+  visit(root, 0, 0);
+  return { boxes, lines, labels };
+};

package/src/recipes/kabuki-devtools/scene/layout/shapes.ts

@@ -0,0 +1,93 @@
+/*
+ * What both layouts take and give: boxes in, placed boxes, lines and their
+ * labels out. Pure, and knows nothing of what the boxes stand for.
+ */
+
+/** One box to lay out, and what hangs below it, each marked with what led there, if anything did. */
+export interface Branch {
+  readonly id: string;
+  readonly width: number;
+  readonly height: number;
+  readonly children: ReadonlyArray<{
+    readonly via?: string;
+    readonly branch: Branch;
+  }>;
+}
+
+/** A box's place: its top-left corner. */
+export interface Box {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly depth: number;
+  readonly parent?: string;
+}
+
+/** A line from one box to one below it, as SVG path data. */
+export interface Line {
+  readonly id: string;
+  readonly from: string;
+  readonly to: string;
+  readonly via?: string;
+  readonly d: string;
+}
+
+/** What led from a box to some below it, written on their lines. */
+export interface Label {
+  readonly id: string;
+  readonly owner: string;
+  readonly text: string;
+  readonly x: number;
+  readonly y: number;
+  /** Centred on its point, or starting from it. */
+  readonly align: 'middle' | 'start';
+}
+
+export interface Laid {
+  readonly boxes: ReadonlyMap<string, Box>;
+  readonly lines: ReadonlyArray<Line>;
+  readonly labels: ReadonlyArray<Label>;
+}
+
+type Point = { readonly x: number; readonly y: number };
+
+/** How far down a curve leaves and arrives straight: half the drop. */
+const controls = (from: Point, to: Point, first: 'down' | 'across') =>
+  first === 'down'
+    ? ([
+        { x: from.x, y: from.y + (to.y - from.y) / 2 },
+        { x: to.x, y: to.y - (to.y - from.y) / 2 },
+      ] as const)
+    : ([
+        { x: from.x, y: to.y },
+        { x: from.x + (to.x - from.x) / 3, y: to.y },
+      ] as const);
+
+/**
+ * A smooth curve from one point to another, as one cubic Bézier: leaving
+ * straight down and arriving straight down, or down a spine then across.
+ * Every line is the same four points, so one can turn into another.
+ */
+export const curve = (
+  from: Point,
+  to: Point,
+  first: 'down' | 'across' = 'down',
+) => {
+  const [a, b] = controls(from, to, first);
+  return `M ${from.x} ${from.y} C ${a.x} ${a.y} ${b.x} ${b.y} ${to.x} ${to.y}`;
+};
+
+/** The point a share `t` of the way along a curve, to write on it. */
+export const along = (
+  from: Point,
+  to: Point,
+  t: number,
+  first: 'down' | 'across' = 'down',
+): Point => {
+  const [a, b] = controls(from, to, first);
+  const u = 1 - t;
+  const at = (p: number, q: number, r: number, s: number) =>
+    u * u * u * p + 3 * u * u * t * q + 3 * u * t * t * r + t * t * t * s;
+  return { x: at(from.x, a.x, b.x, to.x), y: at(from.y, a.y, b.y, to.y) };
+};

package/src/recipes/kabuki-devtools/scene/layout/tree.ts

@@ -0,0 +1,181 @@
+import { along, curve } from './shapes.ts';
+import type { Box, Branch, Label, Laid, Line } from './shapes.ts';
+
+/*
+ * A packed tree, top-down: every row of boxes at one height, the root's top
+ * centre at 0, 0.
+ *
+ * 1. Rows     each depth as tall as its tallest box.
+ * 2. Pack     each subtree slides left until, at some depth, it would touch
+ *             the one before it: so a subtree tucks under its neighbour's
+ *             empty space, and a parent sits centred over its children.
+ * 3. Stack    more than a few boxes with nothing below them hang in one
+ *             column, down a spine, instead of one long row.
+ * 4. Lines    a smooth curve down from each box to each below it, the label of
+ *             what led there on the last stretch.
+ */
+
+const GAP = 36;
+const DROP = 64;
+/** More leaves than this stack in a column. */
+const LEAVES = 4;
+const STACK_GAP = 32;
+const INDENT = 22;
+/** Deep enough that a stack keeps its column clear all the way down. */
+const DEEP = 64;
+
+interface Shape {
+  /** The left and right edge at each depth below and including this box, from its centre. */
+  readonly left: number[];
+  readonly right: number[];
+  /** Each child's centre from this box's centre, or its left edge in a stack. */
+  readonly offsets: number[];
+  readonly stacked: boolean;
+}
+
+const isStack = (branch: Branch) =>
+  branch.children.length > LEAVES &&
+  branch.children.every(({ branch: child }) => child.children.length === 0);
+
+export const packedTree = (root: Branch): Laid => {
+  // 1. Rows
+  const tallest: number[] = [];
+  const measure = (branch: Branch, depth: number, stacked: boolean) => {
+    if (!stacked) tallest[depth] = Math.max(tallest[depth] ?? 0, branch.height);
+    const stack = isStack(branch);
+    for (const { branch: child } of branch.children)
+      measure(child, depth + 1, stack);
+  };
+  measure(root, 0, false);
+  const top: number[] = [0];
+  for (let depth = 1; depth <= tallest.length; depth++)
+    top[depth] = top[depth - 1]! + tallest[depth - 1]! + DROP;
+
+  // 2. Pack, and 3. Stack
+  const shapes = new Map<string, Shape>();
+  const shape = (branch: Branch): Shape => {
+    const half = branch.width / 2;
+    if (isStack(branch)) {
+      // A stacked leaf is placed like any box, so it needs a shape too.
+      for (const { branch: child } of branch.children) shape(child);
+      const column = Math.max(
+        ...branch.children.map(({ branch: child }) => child.width),
+      );
+      const start = -half + INDENT;
+      const made: Shape = {
+        left: [-half, ...Array<number>(DEEP).fill(start - INDENT)],
+        right: [
+          half,
+          ...Array<number>(DEEP).fill(Math.max(half, start + column)),
+        ],
+        offsets: branch.children.map(() => start),
+        stacked: true,
+      };
+      shapes.set(branch.id, made);
+      return made;
+    }
+    const children = branch.children.map(({ branch: child }) => shape(child));
+    const offsets: number[] = [];
+    const left: number[] = [];
+    const right: number[] = [];
+    children.forEach((child, index) => {
+      let at = 0;
+      if (index > 0)
+        for (let depth = 0; depth < child.left.length; depth++)
+          if (right[depth] !== undefined)
+            at = Math.max(at, right[depth]! - child.left[depth]! + GAP);
+      offsets.push(at);
+      child.left.forEach((edge, depth) => {
+        left[depth] = Math.min(left[depth] ?? Infinity, edge + at);
+        right[depth] = Math.max(
+          right[depth] ?? -Infinity,
+          child.right[depth]! + at,
+        );
+      });
+    });
+    const centre = children.length ? (offsets[0]! + offsets.at(-1)!) / 2 : 0;
+    const made: Shape = {
+      left: [-half, ...left.map((edge) => edge - centre)],
+      right: [half, ...right.map((edge) => edge - centre)],
+      offsets: offsets.map((offset) => offset - centre),
+      stacked: false,
+    };
+    shapes.set(branch.id, made);
+    return made;
+  };
+  shape(root);
+
+  // 4. Lines
+  const boxes = new Map<string, Box>();
+  const lines: Line[] = [];
+  const labels: Label[] = [];
+  const place = (
+    branch: Branch,
+    centre: number,
+    y: number,
+    depth: number,
+    parent?: string,
+  ) => {
+    const box: Box = {
+      x: centre - branch.width / 2,
+      y,
+      width: branch.width,
+      height: branch.height,
+      depth,
+      ...(parent ? { parent } : {}),
+    };
+    boxes.set(branch.id, box);
+    const { offsets, stacked } = shapes.get(branch.id)!;
+    const bottom = { x: centre, y: y + branch.height };
+    let below = top[depth + 1] ?? y + branch.height + DROP;
+    branch.children.forEach(({ via, branch: child }, index) => {
+      if (stacked) {
+        const left = centre + offsets[index]!;
+        const spine = left - INDENT / 2;
+        place(child, left + child.width / 2, below, depth + 1, branch.id);
+        lines.push({
+          id: `${branch.id}->${child.id}`,
+          from: branch.id,
+          to: child.id,
+          ...(via ? { via } : {}),
+          d: curve(
+            { x: spine, y: bottom.y },
+            { x: left, y: below + 16 },
+            'across',
+          ),
+        });
+        if (via)
+          labels.push({
+            id: `${branch.id}->${child.id}:via`,
+            owner: branch.id,
+            text: via,
+            x: left,
+            y: below - 9,
+            align: 'start',
+          });
+        below += child.height + STACK_GAP;
+        return;
+      }
+      const at = centre + offsets[index]!;
+      place(child, at, below, depth + 1, branch.id);
+      lines.push({
+        id: `${branch.id}->${child.id}`,
+        from: branch.id,
+        to: child.id,
+        ...(via ? { via } : {}),
+        d: curve(bottom, { x: at, y: below }),
+      });
+      if (via)
+        labels.push({
+          id: `${branch.id}->${child.id}:via`,
+          owner: branch.id,
+          text: via,
+          // On the curve, most of the way down, where it runs nearly straight.
+          ...along(bottom, { x: at, y: below }, 0.78),
+          align: 'middle',
+        });
+    });
+  };
+  place(root, 0, 0, 0);
+  return { boxes, lines, labels };
+};

package/src/recipes/kabuki-devtools/scene/nodes.ts

@@ -0,0 +1,116 @@
+import type { Instance } from '@kestack/kabuki';
+
+/*
+ * What the Map is made of, before it is laid out: one Node per place an
+ * Actor can run, standing for every Instance there now.
+ *
+ * A Node is a card: its Actor's name, the States it can be in, as options,
+ * and the Workers written in it, as rows. All three come from the Actor,
+ * never the data, so a card's size never changes and the Map never moves:
+ * the Snapshot only says how many Instances run there, which State each is
+ * in, and which Worker keys run now.
+ */
+
+/** Whether a Worker key is running, finished or failed; `on` away from the live app, where only its Condition is known. */
+export type WorkerStatus = 'running' | 'finished' | 'failed' | 'on';
+
+/** One Worker key a Condition names now. */
+export interface WorkerKey {
+  /** Unique on the Map. */
+  readonly id: string;
+  /** `''` for the one Worker of a kind other than `each`. */
+  readonly key: string;
+  readonly instance: Instance;
+  readonly status: WorkerStatus;
+}
+
+/** One Worker an Actor has, written at its top or in one State, and the keys it runs now. */
+export interface WorkerRow {
+  readonly name: string;
+  /** The State it is written in; none at the top. */
+  readonly state?: string;
+  readonly keys: ReadonlyArray<WorkerKey>;
+}
+
+/** One State an Actor can be in, and how many of its Instances are in it. */
+export interface StateOption {
+  readonly tag: string;
+  readonly count: number;
+}
+
+export interface ActorNode {
+  readonly id: string;
+  readonly name: string;
+  /** A slot of keyed Children: one card for many Instances, showing one at a time. */
+  readonly many: boolean;
+  /** Every Instance at this place, under the Instances chosen above it. */
+  readonly instances: ReadonlyArray<Instance>;
+  /** The Instance a place of many shows: its State, its Workers, and what hangs below it. */
+  readonly chosen?: Instance;
+  /** Its States, in lines as the card draws them; none for an Actor without States. */
+  readonly states?: ReadonlyArray<ReadonlyArray<StateOption>>;
+  readonly workers: ReadonlyArray<WorkerRow>;
+  /** Its size, from the Actor alone. */
+  readonly width: number;
+  readonly height: number;
+}
+
+/** A Node with what hangs below it, each by the State that Invokes it, if one does. */
+export interface Item {
+  readonly node: ActorNode;
+  readonly children: ReadonlyArray<{
+    readonly via?: string;
+    readonly item: Item;
+  }>;
+}
+
+/** The card's measures, shared by the layout and the drawing so they always agree. */
+export const CARD = {
+  pad: 10,
+  header: 22,
+  line: 22,
+  row: 22,
+  gap: 6,
+  min: 168,
+  max: 264,
+} as const;
+
+const optionWidth = (tag: string, many: boolean) =>
+  10 + 6 + tag.length * 6.6 + (many ? 22 : 0) + 12;
+
+/** A card's size and the lines its States fall into, from its Actor alone. */
+export const measure = (
+  name: string,
+  many: boolean,
+  states: ReadonlyArray<string> | undefined,
+  workers: ReadonlyArray<string>,
+) => {
+  // A place of many has a switcher in its header.
+  const header = 16 + 8 + name.length * 7.4 + (many ? 92 : 0);
+  const rows = workers.reduce(
+    (widest, worker) => Math.max(widest, 16 + worker.length * 6.8 + 72),
+    0,
+  );
+  const inner = Math.min(
+    CARD.max - CARD.pad * 2,
+    Math.max(CARD.min - CARD.pad * 2, header, rows),
+  );
+  // States wrap into as many lines as they need inside the card's width.
+  const lines: string[][] = [];
+  let used = Infinity;
+  for (const tag of states ?? []) {
+    const width = optionWidth(tag, many);
+    if (used + width > inner) {
+      lines.push([]);
+      used = 0;
+    }
+    lines.at(-1)!.push(tag);
+    used += width;
+  }
+  const height =
+    CARD.pad * 2 +
+    CARD.header +
+    (lines.length ? CARD.gap + lines.length * CARD.line : 0) +
+    (workers.length ? CARD.gap + workers.length * CARD.row : 0);
+  return { width: inner + CARD.pad * 2, height, lines };
+};