@weasel-js/diagram 1.15.0 → 1.15.2

package/README.md

@@ -265,6 +265,11 @@ const spec = edgeLabelSpec(edgeId, 'yes', { layer: 'diagram' });
 `labelSize` is the box a label's text takes. Both routes size with it, so a
 label built from data and one the action creates come out the same size.
 
+A label's `at` is `'start'`, `'mid'`, `'end'`, a fraction of the route, or
+`{ near }` a point. At `'start'` or `'end'`, `inset` stands the label's near
+side that far along the route from the end, so it clears the shape the route
+meets; that is how an edge's `endLabels` sit.
+
 ### Labels that dodge
 
 After any edit, a label that would sit on a shape, on another label, or across
@@ -522,6 +527,29 @@ useDepSource('canDropInto', () => diagramCanDropInto(scene));
 const containers = useMemo(() => diagramContainers({ scene, selected }), [scene, selected]);
 ```
 
+### Diagram types
+
+A `DiagramType` is a kind of diagram: the stencil groups (`STENCIL_GROUPS`) its Shapes panel opens with, how a new
+connector starts (`edge`: router, end markers, dash), the layout Auto layout runs, and the `notations` its graph
+pages are written in. `DIAGRAM_TYPES` ships these:
+
+| Type | Groups | Notation |
+| --- | --- | --- |
+| Flowchart | flowchart, containers | `FLOWCHART_NOTATION` |
+| Org chart, Network, BPMN | their own, containers | none: written as a flowchart |
+| UML class, Entity relationship, Mind map | their own (UML adds containers) | `class`, `er`, `mindmap` |
+| State | state: states, start, end, choice, fork or join, note, composite and concurrent states | `state` |
+| Requirement | requirement: requirements and elements, joined dashed | `requirement` |
+| C4 | C4: people, systems, containers, components, stores, queues, boundaries | `c4-context`, and the other levels on import |
+| Block | flowchart, containers, laid out on a grid | `block` |
+| Architecture | architecture: services by Mermaid's built-in icons, junctions, groups | `architecture` |
+| Kanban | kanban: a board of column lanes, cards | `kanban` |
+
+The type a scene holds is its `diagram:type` document value (`diagramTypeOf`, `setDiagramType`), and
+`diagramNotationOf(scene)` the notation a page of it is written in. A stencil's `themeRole` puts that theme role on
+the body it draws, as C4's outside elements are `muted`; `useStencilInsert` resolves its colors when given `theme`.
+A container stencil may name its `title` and the `lanes` a pool starts with.
+
 The layouts register by key through `withDiagramRegistry`, so a saved scene
 finds them again: `diagram:container`, `diagram:pool-rows`,
 `diagram:pool-columns`, `diagram:lane-rows`, and `diagram:lane-columns`.
@@ -586,7 +614,7 @@ dragged undoes in one step; `scene.history.seal()` ends the run. `parseDiagramTh
 
 ### Laying it out
 
-`layered`, `tree`, `force`, `chain`, and `radial` are plain functions of the graph. Each
+`layered`, `tree`, `force`, `chain`, `radial`, and `grid` 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.
@@ -680,6 +708,16 @@ sides are dealt in graph order and each side keeps the order its branches stand
 moves nothing. Further trees lay out the same way, stacked below the first. `direction` and groups
 are ignored.
 
+`grid` stands nodes in rows of a fixed number of columns, left to right and top to bottom, as a
+block diagram does. Its `grid` option gives the top level's `columns` (unset, everything in one
+row), each group's own under `groupColumns`, how many columns an item `spans`, and how many empty
+cells it `skips` before it, all by id. Items fill their cells in graph order, a group where its
+first member would stand. Every column of one grid is as wide as its widest item needs, a spanning
+item sharing its width over its columns, and every row as tall as its tallest item; an item is
+centered in its cells. A group (or a container fitted to what it holds) is a grid of its own in
+its cells, its inset kept around it. Columns are `nodeGap` apart and rows `rankGap`, or `nodeGap`
+when `rankGap` is unset. Edges and `direction` are ignored, so a second run moves nothing.
+
 ### From data
 
 `diagramScene` turns plain `{ nodes, edges }` into a laid-out scene, and
@@ -702,7 +740,10 @@ label row each. A `slot` row is reserved space, `height` tall and, with a
 `width`, that wide and centered; one with an `id` becomes a scene node of that
 name, `<node>/<id>`, drawn as an empty frame until you fill it by changing its
 data — with `{ image: { src } }`, say. An edge can name `fromPort`/`toPort`, its own `router`,
-`waypoints`, `labelPlacement`, and a theme role in `style`.
+`waypoints`, `labelPlacement`, and a theme role in `style`. Its `endLabels`
+`{ from, to }` draw text beside each end, a multiplicity or a role, as labels at
+`'start'` and `'end'` (`END_LABEL_PLACEMENT`) whose ids `endLabelIdOf(edge, end)`
+gives.
 
 A node, an edge, a container, or a lane can carry `colors` of its own: a node's `fill`, `stroke`,
 and `text`, an edge's `stroke`, `label`, `width`, `dash`, and markers. `diagramScene` draws them
@@ -718,15 +759,20 @@ 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'`,
+`'roundRect'`, `'triangle'`, `'octagon'`, `'cloud'`, `'doubleEllipse'`,
+`'actor'` (a stick figure, its label in the strip beneath it), and `'person'` (a head over a body
+with rounded shoulders, its rows in the body); 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.
+The state-machine figures `'start'` (a filled dot), `'end'` (a ring around a
+dot), and `'bar'` (a fork or join, 6 thick along the box's longer side) keep
+their proportions centered in any box, and fill their solid part in the
+stroke's color.
 
 `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,
+`detail`, `solid` (filled in the stroke's color over the fill), `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.
@@ -919,6 +965,69 @@ blank. The view opens fitted to the diagram and fits again when `width` or
 `height` changes or a layout run settles, until the user pans or zooms. `minScale` stops the fit from
 shrinking a wide diagram past readable; the rest is a pan away.
 
+### Sequence diagrams
+
+A `SequenceData` is participants left to right and steps top to bottom:
+messages, notes, activations, `create` and `destroy`, and fragments (`loop`,
+`alt`, `opt`, `par`, `critical`, `break`, and a colored `region`) holding runs
+of steps in sections. `boxes` draw around participants' columns, and
+`autonumber` numbers the messages from a start.
+
+```tsx
+const data: SequenceData = {
+  participants: [{ id: 'a', label: 'Alice', outline: 'actor' }, { id: 'b', label: 'Bob' }],
+  steps: [
+    { kind: 'message', id: 'm1', from: 'a', to: 'b', text: 'Hello', line: 'solid', head: 'arrow', activate: 'to' },
+    { kind: 'message', id: 'm2', from: 'b', to: 'a', text: 'Hi', line: 'dashed', head: 'arrow', deactivate: 'from' },
+  ],
+};
+const [seq, setSeq] = useState(data);
+const specs = useMemo(() => sequenceSpecs(seq, { id: 'hello' }), [seq]);
+<DiagramView specs={specs} onEditSequence={(edit) => setSeq(edit.data)} />;
+```
+
+`sequenceSpecs(data, { id, at, theme, measure })` lays the data out
+(`sequenceLayout` gives the geometry alone): lifelines spaced so the widest
+text between neighbors fits, a row per step sized to its text, self-messages
+looped, a head started at its `create` and a lifeline ended at its `destroy`,
+nested activations stepped right, and each fragment boxed over the lifelines
+its steps touch, with its type in a tab and a dashed line between sections. It
+returns one root node, `id`, holding the data, and every part as a child of it
+that takes no press. Heads wear the participant's outline: `actor`, `boundary`,
+`control`, `entity`, `cylinder` for a database, `collections`, and `queue`
+besides any other. Every part is drawn in the theme: a head and its
+activations in the participant's role, a message in the connector style, a
+note in `SEQUENCE_ROLES.note`, a fragment or a box as a container.
+
+The edits are pure functions of the data: `moveStep` (into or out of a
+fragment's section), `moveParticipant`, `reconnectMessage`, and
+`setSequenceText`. `DiagramView`'s `onEditSequence` turns them on as drags — a
+message or note to another row, a head sideways, a message end onto another
+lifeline — and double-click text editing, each reported as the sequence's new
+data. On a scene that is the document, `diagramSequence({ scene, measure })`
+gives the layer and contribution that commit each edit as one undo entry
+(`commitSequence`), and `foldSequenceText` turns a text edit on a part into one
+edit of the data. A theme applied with `applyDiagramTheme` draws every sequence
+again.
+
+A sequence is built from nothing with more pure edits: `addParticipant` and
+`removeParticipant` (which takes every message, mark, and note naming it),
+`insertMessage` with an arrow from `SEQ_ARROWS`, `insertNote`, `insertMark` for
+activations, creations, and destructions, `wrapSteps` to put a run of steps in
+a fragment and `addSection` for an alt's next branch, `removeStep`, `addBox`, and
+`setAutonumber`, among others. `useSequenceTools` builds the tools in
+`SEQUENCE_TOOLS` that make them on the canvas: Participant clicks a lifeline in
+between two (or starts a sequence on empty canvas), Message drags from one
+lifeline to another, Note clicks or drags across lifelines, and Fragment drags
+across rows, and Mark clicks an activation's start or end, a creation, or a
+destruction onto a lifeline. Pass them as `tools` to `DiagramView` or
+`<SceneCanvas>`. `sequenceSelectionOf(scene, ids)` reads a selection as one
+sequence's participants, messages, notes, fragments, and boxes, for a panel
+that offers the edits fitting it. A click
+on a sequence's part selects it, and `createSequenceDeleteAction` (which
+`DiagramView` installs with `onEditSequence`) makes Delete remove it from the
+data.
+
 ### Effect charts
 
 `@weasel-js/diagram/effect` draws an effects pipeline: the stages a signal