@weasel-js/diagram 1.13.0 → 1.14.0

package/README.md

@@ -73,7 +73,8 @@ return <SceneCanvas ref={canvasRef} scene={scene} ambient={[contribution]} />;
 
 Dragging one port onto another authors an edge. Which pairs may be joined is
 `canConnect`, which defaults to "a port may not join itself, and two ports that
-both declare a `type` must declare the same one".
+both declare a `type` must declare the same one". It answers a `DropVerdict`
+(see "Refusing a drop with a reason").
 
 A port may name other places it can sit, in `sites`. An edge meeting it takes
 whichever place faces the edge's next point — its first waypoint, or the other
@@ -378,7 +379,33 @@ pointer moves onto an overlay. Edges answer only with `pickEdges`. For DOM
 the view does not hold, `rectOf(id)` on the ref gives a target's client rect
 and `subscribeFrame` says when to read it again.
 
-### Reordering a group's members
+### Refusing a drop with a reason
+
+Every "may this land here?" check answers a `DropVerdict`, the one shape core
+uses too: `true` lands, `false` is a silent no, and `{ refuse: string }` is a
+no the user is told about.
+
+| Check | Asked about |
+|---|---|
+| `canConnect(from, to, moving?)` | a new edge's end, or a selected edge's end being moved (`moving` names it) |
+| `canReparent(ids, container)` | nodes dragged into a container or lane they are not already in, once the diagram's own rules allow it |
+| `canDropItem(item, target)` | an item carried in from a palette (see "Dropping items from a palette") |
+
+Over a `false` the drag behaves as if the target were not there: a port is
+never snapped to, and a container is passed over for the one around it. Over a
+refusal the canvas outlines the target in the `refused` overlay role and shows
+the reason beside the pointer; a release there reports nothing, and a moved
+node goes back where it was.
+
+```tsx
+<DiagramView
+  specs={specs}
+  canConnect={(from, to) => (to.nodeId === 'source' ? { refuse: 'The source takes no inputs' } : true)}
+  canReparent={(_ids, into) => (into === 'shelf' ? { refuse: 'The shelf is locked' } : true)}
+/>
+```
+
+### Reordering a group's or a container's members
 
 A group with `reorder: 'x' | 'y'` lets `onReorder` drag any of its members
 along that axis; a member that is a group carries everything inside it. The
@@ -389,9 +416,51 @@ order given across every rank, so writing the order back is all it takes.
 
 ```tsx
 const data = { nodes, edges, groups: [...rows, { id: 'layers', members: order, reorder: 'y' }] };
-<DiagramView specs={diagramScene(data)} onReorder={({ order }) => setOrder(order)} />
+<DiagramView specs={diagramScene(data)} onReorder={({ parent, order }) => setOrder(order)} />
 ```
 
+A `DataContainer` takes `reorder` the same way, with the same drag, the same
+Alt and arrow key, and the same report: `parent` is the container's id and
+`order` its members in their new order. Nothing moves until the data does, so
+place the members by their order and write it to `members`. A body drag on a
+member of a reorderable container reorders it until the pointer leaves the
+container's box; from there it is a move, reported to `onMove` with the
+`parent` it lands in, as any shape dragged out of a container is.
+
+### Dropping items from a palette
+
+A list the host renders outside the canvas becomes a palette with
+`dragItemProps(item)`, spread on each entry: a press carries `item`, any value
+of the host's own, over the page. While it is over the diagram, the shape or
+container it would land on is outlined, and in a container marked `reorder` a
+bar marks its place. Release reports an `ItemDrop` to `onDropItem` and adds
+nothing.
+
+| Field | What it holds |
+|---|---|
+| `item` | the value `dragItemProps` was given |
+| `target` | the shape or the container it was dropped on, or `null` for the bare canvas |
+| `container` | the container or lane that would hold it: the target when that is one, else the one around the pointer; `null` at the top level |
+| `index` | its place among `container`'s members, along the container's `reorder` axis, else in reading order (top to bottom, then left to right); `null` with no container |
+| `at` | the pointer, in world units |
+
+```tsx
+<li {...dragItemProps({ kind: 'blur' })}>Blur</li>
+<DiagramView
+  specs={specs}
+  onDropItem={({ item, container, index }) => insert(item, container, index)}
+  canDropItem={(item, { container }) => (container === 'shelf' ? { refuse: 'The shelf is locked' } : true)}
+/>
+```
+
+Give each entry `touch-action: none` so a touch drag is a carry, not a scroll.
+`startItemDrag(event, item)` starts one from a pointer event of your own, and
+`createItemDropAction` (or `itemDropContribution`, to pass as `ambient`) is the
+canvas half for a `SceneCanvas` of your own; the carry travels as
+`DIAGRAM_ITEM_CARRY`. There its `report` gets the canvas's deps as well as the
+drop, and `requires` names the ones it reads, so it can add the item itself
+through `insert`. A `ToolPalette` carries from its buttons with `carryTool`.
+
 ### Stencils
 
 A `DiagramStencil` is a palette entry: an id, a label, an outline and a default
@@ -439,7 +508,7 @@ drawn inside a container or a lane becomes its member (`diagramDropParentAt`).
 `containerBuild` returns the ops on their own, and `addLane` and
 `releaseMembers` are the edits as functions.
 
-What a region admits is the `canDropInto` dep's call, and `diagramCanDropInto(scene)`
+What a region admits is the `canDropInto` dep's call, and `diagramCanDropInto(scene, canReparent?)`
 is the one for a diagram: containers and lanes take shapes and containers, a
 pool takes only lanes, and a stencil body, an edge, or a label takes nothing.
 `diagramContainers` returns the lane layer to register and the contribution to
@@ -517,7 +586,7 @@ dragged undoes in one step; `scene.history.seal()` ends the run. `parseDiagramTh
 
 ### Laying it out
 
-`layered`, `tree`, `force` and `chain` are plain functions of the graph. Each
+`layered`, `tree`, `force`, `chain`, and `radial` are plain functions of the graph. Each
 hands back the new top-left for every node that **moves** — a node already
 standing where the layout wants it is absent, so re-running a layout on an
 unchanged diagram writes nothing at all.
@@ -601,6 +670,14 @@ naming ports that face each other, runs on a track of its own in the gap
 between them, so a fan of them never crosses; the gap grows to keep tracks 12
 apart. Groups are ignored.
 
+`radial` is the mind-map layout. The first root `tree` would find sits in the middle, and its
+children are dealt to its right and its left, in graph order, each to whichever side holds fewer
+nodes so far. Each side grows away from the root as a horizontal `tree`, one band per depth
+`rankGap` apart, its subtrees packed as blocks `nodeGap` apart and centered on the root. Because
+sides are dealt in graph order and each side keeps the order its branches stand in, a second run
+moves nothing. Further trees lay out the same way, stacked below the first. `direction` and groups
+are ignored.
+
 ### From data
 
 `diagramScene` turns plain `{ nodes, edges }` into a laid-out scene, and
@@ -611,6 +688,11 @@ const specs = useMemo(() => diagramScene(data, { nodeStyle }), [data]);
 return <DiagramView specs={specs} width={360} height={600} selected={id} onSelect={setId} />;
 ```
 
+`onSelect(id, ids)` reports the latest pick and every id picked. With
+`selectionMode="multiple"`, Shift-click adds a node, group or edge to the pick
+or takes it out; `selected` takes one id or an array, and handing back the
+reported `id` leaves the rest picked.
+
 Every box is a `buildBody` body, so a data node takes the same knobs a body
 does — `outline`, `rows`, `padding`, `gap`, `verticalAlign`, `ports` — plus `pinned`, a
 starting `at`, and a minimum `width`/`height`; `lines` is shorthand for one
@@ -628,12 +710,24 @@ give the style an item is drawn in, for a writer that needs it without drawing;
 no width, `NODE_STROKE_WIDTH`, `LANE_STROKE_WIDTH`, and `EDGE_STROKE_WIDTH` are what is drawn. `layer` puts every
 spec on a layer other than `'main'`.
 
-`outline` is `'rect'`, `'diamond'`, `'stadium'`, `'parallelogram'`,
-`'trapezoid'` (a demultiplexer: tall at the right, short at the left),
-`'hexagon'` (pointed at the left and right, its rows kept between the points), or a
-`Path` drawn in a unit square — `(0, 0)` the box's top-left, `(1, 1)` its
-bottom-right — which is stretched over the box, so it follows its node as
-marks do.
+`outline` is a name from the outline table, or a `Path` drawn in a unit square
+— `(0, 0)` the box's top-left, `(1, 1)` its bottom-right — which is stretched
+over the box, so it follows its node as marks do. The built-in names are the
+flowchart shapes `'rect'`, `'diamond'`, `'stadium'`, `'ellipse'`, `'parallelogram'`,
+`'trapezoid'` (a demultiplexer: tall at the right, short at the left), and
+`'hexagon'` (pointed at the left and right, its rows kept between the points);
+`'roundRect'`, `'triangle'`, `'octagon'`, `'cloud'`, `'doubleEllipse'`, and
+`'actor'` (a stick figure, its label in the strip beneath it); and `'cylinder'`,
+`'document'`, `'note'`, `'folder'`, and `'cube'`. Each keeps its rows inside the
+visible shape, clear of a cylinder's cap or a note's fold. Some draw a detail,
+stroked over the fill: a cylinder's rim, a note's fold, a cube's front edges.
+
+`registerOutline(name, def)` adds a name, or shadows a built-in until its
+disposer runs. An `OutlineDef` builds `path` in a node's bounds, and optionally
+`detail`, `content` (the box rows lay out in), and `boxForContent` (its inverse,
+for sizing a node to its rows). `outlineFromD(d, { detail, content })` builds one
+from SVG path data in a unit square. A saved name that is not registered paints
+as `'rect'` and warns once.
 
 `marks` draws more over a box than its rows. A mark with `d` is SVG path data
 in a unit square, stretched over the node's box; it takes `fill`, `stroke`,
@@ -720,7 +814,8 @@ A pool always has a box: 600 across and 120 along per lane when it gives none
 (`'y'`, rows, by default) at their `size`, and lanes giving none share what
 the pool's box leaves. An edge with an end inside a boxed region ranks against
 the outermost one holding it, and keeps none of layout's route. `pinned`
-leaves a box where it is. Under `theme`, a region naming a `style` role takes
+leaves a box where it is. A container's `reorder` lets `onReorder` drag its
+members along that axis (see "Reordering a group's or a container's members"). Under `theme`, a region naming a `style` role takes
 that role's colors; otherwise a container takes the theme's `container`, a
 pool its `lane.header`, and lanes the `lane.bodies` in turn; titles are set in
 the diagram's face, the theme's when `font` is unset. `router="avoid"`
@@ -977,7 +1072,7 @@ and a `color(type)` for the ports. `EFFECT_LOOKS` holds `nodeGraph`, `rack`, `la
 | Look | Draws | Options |
 | --- | --- | --- |
 | `nodeGraph` (default) | Every port a named row on its stage, a wire from port to port, flowing left to right. | `router` (default `'bezier'`), `nodeGap`, `rankGap`, `colors`, `showParams`, `showValues`, `showPreviews`, `previewSize`, `branch` |
-| `rack` | The main signal on one straight line, and everything else hung beside the stage on the line it is nearest to, whichever way the wire runs. | `chain`, `side`, `nodeGap`, `rankGap`, `colors`, `showParams`, `showValues`, `showPreviews`, `previewSize`, `branch`, `collapseSkips` |
+| `rack` | The main signal on one straight line, and everything else hung beside the stage on the line it is nearest to, whichever way the wire runs. | `chain`, `direction`, `side`, `nodeGap`, `rankGap`, `colors`, `showParams`, `showValues`, `showPreviews`, `previewSize`, `branch`, `collapseSkips` |
 | `lanes` | A horizontal lane per value type, and each stage standing across the lanes of the types it reads and writes, as tall as they are, its ports in their own lanes. | `lanes`, `laneHeight`, `rankGap`, `router`, `colors`, `showParams`, `showValues`, `showPreviews`, `previewSize`, `branch`, `measure` |
 | `compact` | Each stage one line, its title alone, no ports drawn, and one line between two stages however many wires join them. For a pipeline too big to read as a node graph. | `router`, `nodeGap`, `rankGap`, `colors`, `branch` |
 
@@ -986,8 +1081,16 @@ true) shows the `params` of ordinary stages, sources and sinks; `showValues`
 (default false) keeps a row per output on those stages for a run's values, and
 `showPreviews` (default false) a slot per output for its previews. `rack` runs
 along `chain`, a list of stage ids that defaults to the longest path over data
-wires (`mainChain(pipeline)` returns it); `side` is `'below'` (default) or
-`'above'`.
+wires (`mainChain(pipeline)` returns it). Its `direction` is `'right'`
+(default), the line running left to right, or `'down'`, a column the main
+signal enters at each stage's top and leaves at its bottom, which a reorder
+drags along vertically. `side` is `'below'` (default) or `'above'`; in a
+column, `'below'` hangs the side stages on the column's right and `'above'`
+on its left, and a collapsed skip's arc runs down the other edge. A wire from
+a stage's main output into the side input of a stage further down the line,
+past at least one stage, leaves from a tap on the side stages' edge (a port
+named `~tap:<output>`), so it runs beside the stages between rather than
+through them; the editor and a run read it as the output it taps.
 
 `lanes` puts the lanes top down in the order their types first appear on the
 pipeline's ports, after any it is given in `lanes`. A stage stands
@@ -1200,7 +1303,9 @@ reports, so the editor gathers them and reports one edit once the drag is done
 reporting, a microtask later.
 
 `selectedGroup` and `onSelectGroup` are the group pick, beside `selected` and
-`onSelect`, under every look. The ref's `group(ids)` and `ungroup(id)` report
+`onSelect`, under every look. Shift-click adds a stage or group to the pick or
+takes it out, and `onSelect`'s second argument lists every stage and group
+picked, ready for `group(ids)`. The ref's `group(ids)` and `ungroup(id)` report
 `'Group'` and `'Ungroup'`, and `renameGroup(id)` opens the title field. The
 edits are plain functions too:
 
@@ -1317,7 +1422,7 @@ resize; `rayHit` moves it onto the shape. Don't store outline-relative anchors.
 connect is routing, and lives in the binding's `target`. Which ports a live
 connect may land on cannot be routing — the dispatcher never re-reads the
 affordance under a moving pointer — so `canConnect` filters the candidate set
-instead. Neither is an action body inspecting a hit and bailing.
+instead, and a refusal stays a candidate so it can be drawn refused. Neither is an action body inspecting a hit and bailing.
 
 **A live run does not re-anchor; the one-shot layouts do.** The anchor
 translation keeps a single 300-tick jump from moving the diagram off where the

package/dist/{chunk-Y72FK3Y7.js → chunk-5VNPLOIX.js}

@@ -1,4 +1,4 @@
-import { labelCenter, samePoints } from './chunk-L4H444QI.js';
+import { labelCenter, DEFAULT_NODE_GAP, DEFAULT_RANK_GAP, forestOf, subtreeBlocks, graphOrder, translated, pinnedSet, samePoints } from './chunk-VB6HUKNG.js';
 import { polylineFromPoints } from '@weasel-js/core/math';
 
 // src/hops/types.ts
@@ -1342,7 +1342,7 @@ function candidatesOf(label, route, tries, spacing) {
   const length = route.length;
   if (length === 0) return out;
   const start = typeof at === "object" ? arcNearest(route.points, at.near) : (typeof at === "number" ? at : NAMED[at] ?? 0.5) * length;
-  const sides = offset === 0 ? [0] : [offset, -offset];
+  const sides2 = offset === 0 ? [0] : [offset, -offset];
   const push = (s, side) => {
     const spot = { at: s / length, offset: side };
     out.push({ placement: { at: spot.at, offset: side }, spot });
@@ -1353,7 +1353,7 @@ function candidatesOf(label, route, tries, spacing) {
     for (const dir of [1, -1]) {
       const s = start + dir * k * step;
       if (s < 0 || s > length) continue;
-      for (const side of sides) push(s, side);
+      for (const side of sides2) push(s, side);
     }
   }
   return out;
@@ -1426,6 +1426,94 @@ function placeLabels(input, opts = {}) {
   return out;
 }
 
-export { AVOID_DEFAULTS, DEFAULT_HOP_SIZE, HOPS_DOC_KEY, createAvoidRouter, edgeHops, placeLabels, simplifyStops };
-//# sourceMappingURL=chunk-Y72FK3Y7.js.map
-//# sourceMappingURL=chunk-Y72FK3Y7.js.map
+// src/radial.ts
+var radial = (graph, opts = {}) => {
+  const nodeGap = opts.nodeGap ?? DEFAULT_NODE_GAP;
+  const rankGap = opts.rankGap ?? DEFAULT_RANK_GAP;
+  const { roots, children } = forestOf(graph, "y");
+  const blocks2 = subtreeBlocks(children, "y", nodeGap);
+  const order2 = graphOrder(graph);
+  const placed = /* @__PURE__ */ new Map();
+  let top = 0;
+  for (const root of roots) {
+    const tree = mindMap(root, children, order2, blocks2, nodeGap, rankGap);
+    for (const [id, p] of tree.at) placed.set(id, { x: p.x, y: p.y - tree.top + top });
+    top += tree.bottom - tree.top + nodeGap;
+  }
+  return translated(graph, placed, pinnedSet(graph, opts), opts.tolerance);
+};
+function mindMap(root, children, order2, blocks2, nodeGap, rankGap) {
+  const at = /* @__PURE__ */ new Map([[root.id, { x: -root.bounds.width / 2, y: -root.bounds.height / 2 }]]);
+  let top = -root.bounds.height / 2;
+  let bottom = root.bounds.height / 2;
+  const [right, left] = sides(root, children, order2);
+  for (const [sign2, branches] of [[1, right], [-1, left]]) {
+    if (branches.length === 0) continue;
+    const span = branches.reduce((sum, b) => sum + blocks2.span(b), 0) + (branches.length - 1) * nodeGap;
+    const ys = /* @__PURE__ */ new Map();
+    let cursor = -span / 2;
+    for (const branch of branches) {
+      blocks2.lay(branch, cursor, ys);
+      cursor += blocks2.span(branch) + nodeGap;
+    }
+    top = Math.min(top, -span / 2);
+    bottom = Math.max(bottom, span / 2);
+    for (const [id, x] of sideColumns(branches, children, root.bounds.width / 2 + rankGap, rankGap, sign2)) {
+      at.set(id, { x, y: ys.get(id) });
+    }
+  }
+  return { at, top, bottom };
+}
+function sides(root, children, order2) {
+  const weight = (node) => 1 + (children.get(node.id) ?? []).reduce((sum, k) => sum + weight(k), 0);
+  const kids = children.get(root.id) ?? [];
+  const half = root.bounds.width / 2;
+  const mid = root.bounds.x + half;
+  const standing = (k) => {
+    const c = k.bounds.x + k.bounds.width / 2 - mid;
+    return c > half ? 1 : c < -half ? -1 : 0;
+  };
+  const stands = new Map(kids.map((k) => [k, standing(k)]));
+  const arranged = [...stands.values()].includes(1) && [...stands.values()].includes(-1);
+  const right = /* @__PURE__ */ new Set();
+  let r = 0;
+  let l = 0;
+  const dealt = arranged ? kids.filter((k) => stands.get(k) !== 0) : [];
+  for (const k of dealt) {
+    if (stands.get(k) === 1) {
+      right.add(k);
+      r += weight(k);
+    } else l += weight(k);
+  }
+  for (const child of kids.filter((k) => !dealt.includes(k)).sort((a, b) => order2(a.id) - order2(b.id))) {
+    const w = weight(child);
+    if (r <= l) {
+      right.add(child);
+      r += w;
+    } else l += w;
+  }
+  return [kids.filter((k) => right.has(k)), kids.filter((k) => !right.has(k))];
+}
+function sideColumns(branches, children, from, rankGap, sign2) {
+  const rows = [];
+  const visit = (node, depth) => {
+    (rows[depth] ??= []).push(node);
+    for (const kid of children.get(node.id) ?? []) visit(kid, depth + 1);
+  };
+  for (const branch of branches) visit(branch, 0);
+  const xs = /* @__PURE__ */ new Map();
+  let start = from;
+  for (const row of rows) {
+    const band = Math.max(...row.map((n) => n.bounds.width));
+    for (const node of row) {
+      const near = start + (band - node.bounds.width) / 2;
+      xs.set(node.id, sign2 === 1 ? near : -near - node.bounds.width);
+    }
+    start += band + rankGap;
+  }
+  return xs;
+}
+
+export { AVOID_DEFAULTS, DEFAULT_HOP_SIZE, HOPS_DOC_KEY, createAvoidRouter, edgeHops, placeLabels, radial, simplifyStops };
+//# sourceMappingURL=chunk-5VNPLOIX.js.map
+//# sourceMappingURL=chunk-5VNPLOIX.js.map