@zuilib/text-editor 0.4.0 → 0.6.0

package/README.md

@@ -13,11 +13,15 @@ document outline, and collapsible sections.
   blockquotes, links, fenced code (with syntax highlighting), tables
 - **Tables**: GFM pipe tables, edited in place (tab between cells, ranges,
   inline formatting), styled like Claude artifacts
-- **Table settings**: full/content width and row density per table;
-  diagrams switch between full and content width too — Slab-style
-- **Diagrams**: a drawing canvas embedded in the document — cards with
-  attached text slots, bound arrows that follow their cards, elbow and
-  multi-waypoint routing, labels, color palettes, dark mode
+- **Text measure and block width**: an opt-in readable text column
+  (`measure="48rem"`); each table and diagram picks *full* / *text* /
+  *content* width, Slab-style; row density per table
+- **Diagrams**: a drawing canvas embedded in the document. Eight box
+  shapes (rectangle, ellipse, diamond, note, database, cloud, queue, actor)
+  with attached text slots, bound arrows that follow their boxes and attach
+  to a chosen side, auto-routed elbows that avoid other boxes, multi-select,
+  color palettes, dark mode, Mermaid export. LLMs author diagrams as a
+  coordinate-free ` ```diagram ` skeleton that the editor lays out
 - **Outline**: optional table-of-contents sidebar with click-to-scroll and
   current-section highlight
 - **Section folding**: collapse everything under a heading, view-layer only
@@ -70,6 +74,8 @@ emits. The emitted string is always plain markdown.
 | `toolbar` | `boolean \| (items) => ReactNode` | `true` | Formatting/insert toolbar (`edit-md`); function form customises it |
 | `outline` | `boolean` | `false` | Table-of-contents sidebar |
 | `foldable` | `boolean` | `true` | Collapse sections under headings |
+| `measure` | `string` | — | Max width of the text column, a CSS length (`'48rem'` recommended). Sugar for `--zui-text-editor-measure` |
+| `defaultBlockWidth` | `{ table?, drawing? }` | — | `BlockWidth` written when the toolbar inserts a table / drawing |
 
 ### Modes
 
@@ -98,16 +104,12 @@ Editing is in place: Tab/arrows between cells, cell range selection, inline
 formatting inside cells. Cell content is single-line in markdown; newlines
 are escaped as `\n`.
 
-### Table settings: width and density
+### Table density
 
 Place the caret in a table and a small toolbar floats at its top-right
-corner:
-
-- **Width** — *full* (default: columns share the editor width) or
-  *content* (the table shrinks to fit its columns, left-aligned with the
-  text, never wider than the editor).
-- **Density** — *compact*, *comfortable* (default), or *spacious* cell
-  padding and font size.
+corner with the table's width (see [Block width and text
+measure](#block-width-and-text-measure)) and its **density** — *compact*,
+*comfortable* (default), or *spacious* cell padding and font size.
 
 Non-default settings are persisted as one HTML comment on the line directly
 above the table — other markdown renderers hide it:
@@ -119,12 +121,70 @@ above the table — other markdown renderers hide it:
 | Region | eu-west-1 |
 ```
 
-Programmatic access: `useMarkdownEditor().tableWidth` / `setTableWidth` and
-`tableDensity` / `setTableDensity` (for custom toolbars), or
-`$getTableSettings(node)` / `$setTableSettings(node, { width, density })`
-inside `editor.update`. `parseTableSettingsMarker` /
-`formatTableSettingsMarker` convert between the comment line and a
-`TableSettings` object.
+Programmatic access: `useMarkdownEditor().tableDensity` / `setTableDensity`
+(for custom toolbars), or `$getTableSettings(node)` /
+`$setTableSettings(node, { width, density })` inside `editor.update`.
+`parseTableSettingsMarker` / `formatTableSettingsMarker` convert between
+the comment line and a `TableSettings` object.
+
+## Block width and text measure
+
+By default every block spans the content pane. Set a **measure** to get a
+readable text column instead: paragraphs, headings, lists, quotes, code,
+frontmatter are capped at that width and centred in the pane, while each
+table and drawing chooses its own width.
+
+```tsx
+<MarkdownEditor value={value} onChange={setValue} measure="48rem" />
+```
+
+The prop is sugar for the CSS custom property `--zui-text-editor-measure`,
+which is the actual contract — set it in a stylesheet on `.zui-text-editor`
+(or any ancestor) and never touch the prop:
+
+```css
+.zui-text-editor { --zui-text-editor-measure: 48rem; }
+```
+
+**Adopting:** set `measure` (or the variable) and delete any external
+`max-width` / `margin-inline` overrides on `.zui-text-editor-content > *`;
+the library now owns that layout.
+
+Every table and drawing has a `BlockWidth`, picked from the floating table
+toolbar or the right end of the drawing toolbar:
+
+| `BlockWidth` | Layout | Markdown |
+|--------------|--------|----------|
+| `full` | The content pane, edge to edge (never under the outline sidebar). The default | Omitted |
+| `text` | The text column: edges align with the paragraphs. Identical to `full` until a measure is set | `<!-- width: text -->` / `"width":"text"` |
+| `content` | Shrinks to its columns / shapes, left-aligned with the text, never wider than the column | `<!-- width: content -->` / `"width":"content"` |
+
+Absence of a marker always means `full`, in every app. `defaultBlockWidth`
+only changes what the toolbar / `insertTable` / `insertDrawing` write into
+*new* blocks — and that value is written explicitly, even when it is
+`full`, so the document reads the same elsewhere:
+
+```tsx
+<MarkdownEditor measure="48rem" defaultBlockWidth={{ table: 'text', drawing: 'text' }} … />
+```
+
+Headless: `useMarkdownEditor().blockWidth` / `setBlockWidth` act on the
+block containing the selection — the focused drawing, or else the table
+the caret is in. (`tableWidth` / `setTableWidth` still work and are
+deprecated in favour of these.)
+
+Styling: the layout is driven by low-specificity `:where()` rules and two
+derived custom properties on `.zui-text-editor-main` —
+`--zui-text-editor-gutter` (the pane padding, `2rem` without a measure)
+and `--zui-text-editor-bleed` (how far a full-width block extends past the
+column, `0` without a measure). Each top-level block reads
+`--zui-text-editor-block-bleed`, so a single class rule overrides any block
+kind: `.zui-code { --zui-text-editor-block-bleed: var(--zui-text-editor-bleed) }`
+makes code blocks full width; `.zui-table { --zui-text-editor-block-bleed: 0px }`
+keeps every table inside the column. Block classes: `.zui-paragraph`,
+`.zui-heading` (+ `.zui-heading-1`…`6`), `.zui-list` (+ `-ordered` /
+`-unordered`, `.zui-checklist`), `.zui-quote`, `.zui-code`,
+`.zui-frontmatter`, `.zui-table`, `.zui-drawing`.
 
 ## Toolbar & custom toolbars
 
@@ -209,36 +269,89 @@ function BoldButton() {
 ```
 
 It returns `editor` (the Lexical instance), `activeFormats`,
-`toggleFormat`, `insertTable`, `insertDrawing`, `tableWidth` /
-`setTableWidth` and `tableDensity` / `setTableDensity` (settings of the
-table containing the selection, `null` outside tables), `canUndo`,
-`canRedo`, `undo`, `redo`.
+`toggleFormat`, `insertTable`, `insertDrawing`, `blockWidth` /
+`setBlockWidth` (width of the table or drawing containing the selection,
+`null` outside both), `tableDensity` / `setTableDensity` (`null` outside
+tables), `canUndo`, `canRedo`, `undo`, `redo`. `tableWidth` /
+`setTableWidth` remain as deprecated aliases limited to tables.
 
 ## Diagrams (drawing canvas)
 
 The toolbar's insert-drawing button embeds a canvas; the drawing persists
-in the markdown as a ` ```drawing ` fenced JSON block, fully specified in
-**[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)**.
+in the markdown as a ` ```drawing ` fenced JSON block (format version 2),
+fully specified in **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)**.
 
-- **Shapes**: rectangle, ellipse, triangle, pentagon, arrow, line, text —
-  with stroke/fill palettes. Draw by picking a tool and dragging.
+- **Shapes**: rectangle, ellipse, diamond, note (sticky note), database
+  (cylinder), cloud, queue, actor (stick figure), arrow, line, text. The
+  toolbar shows the common tools and a "more shapes" popover for the rest.
+  Draw by picking a tool and dragging.
 - **Cards**: every box carries three text slots that move, resize, and wrap
-  with it — a bold **label** on top, **content** in the center, a dim
-  **footer** at the bottom. Click a selected box (or double-click its
-  top/middle/bottom strip, or press Enter) to edit a slot.
+  with it: a bold **label** on top, **content** in the center, a dim
+  **footer** at the bottom (actor has only the name under the figure).
+  Click a selected box (or double-click its top/middle/bottom strip, or
+  press Enter) to edit a slot.
 - **Bound connectors**: an arrow drawn from one card to another attaches to
-  both — moving a card moves its arrows, endpoints anchored to the border.
-  Drag an endpoint off/onto a card to detach/re-attach.
-- **Routing**: straight (diagonal) by default; toggle **elbow** for right
-  angles, or drag the dashed "+" handles on a selected connector to add any
-  number of **waypoints** (they snap to neighbors' axes for clean 90°
-  bends). One-way / two-way arrowhead toggle; midpoint **labels**.
+  both; moving a card moves its arrows, endpoints anchored to the outline.
+  An endpoint either auto-aims at the other end or sticks to a fixed point
+  on the box (a side, or a ratio inside the box). Drag an endpoint off/onto
+  a card to detach/re-attach.
+- **Routing**: straight (diagonal) by default; toggle **elbow** for an
+  auto-routed right-angled path that leaves the box perpendicular to its
+  attach side and avoids the other boxes, or drag the dashed "+" handles on
+  a selected connector to add any number of **waypoints** (they snap to
+  neighbors' axes for clean 90° bends). One-way / two-way arrowhead toggle;
+  midpoint **labels**.
+- **Multi-select**: shift-click, or drag a marquee on empty canvas, then
+  move, delete, or recolor the selection together. A contextual property
+  bar shows the options for whatever is selected.
+- **Copy as Mermaid**: a canvas button copies the drawing as a Mermaid
+  `flowchart` (also available as `drawingToMermaid(data)`).
 - **Canvas**: resizable height, dot grid, white surface that inverts
-  Excalidraw-style in dark mode (`.dark` ancestor class).
-- **Width**: the toggle at the right end of the canvas toolbar switches
-  between **full width** (spans the editor) and **content width** (the
-  canvas fits the rightmost shape and grows as shapes move). Stored as
-  `"width":"content"` in the payload; omitted when full.
+  Excalidraw-style in dark mode (`.dark` ancestor class). An optional
+  `canvasWidth` scales the drawing to fit narrower layouts.
+- **Width**: the buttons at the right end of the canvas toolbar switch
+  between **full** (spans the pane), **text** (aligns with the text column,
+  see [Block width and text measure](#block-width-and-text-measure)) and
+  **content** (the canvas fits the rightmost shape and grows as shapes
+  move). Stored as `"width":"text"` / `"width":"content"` in the payload;
+  omitted when full.
+
+A stored drawing looks like this:
+
+````md
+```drawing
+{"version":2,"canvasHeight":260,"shapes":[
+  {"id":"web","type":"rect","x":40,"y":70,"w":170,"h":100,"stroke":"#1971c2","fill":"#a5d8ff","strokeWidth":2,"label":"CLIENT","text":"Web App"},
+  {"id":"api","type":"rect","x":330,"y":70,"w":170,"h":100,"stroke":"#2f9e44","fill":"#b2f2bb","strokeWidth":2,"label":"SERVICE","text":"API"},
+  {"id":"e1","type":"arrow","x":216,"y":120,"w":108,"h":0,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":{"id":"web"},"endBinding":{"id":"api"},"text":"REST"}
+]}
+```
+````
+
+### The ` ```diagram ` skeleton
+
+Generators (LLMs, scripts) do not need coordinates. A ` ```diagram ` block
+holds a skeleton: boxes, connectors, colors. On import the editor lays it
+out along `direction` (`right` by default, or `down`), sizes boxes to their
+text, and stores the result as a normal ` ```drawing ` block (one-way
+expansion).
+
+````md
+```diagram
+{"boxes":[
+  {"id":"web","label":"CLIENT","text":"Web App","color":"blue"},
+  {"id":"api","label":"SERVICE","text":"API","color":"green"},
+  {"id":"db","type":"cylinder","text":"Postgres"}
+],"connectors":[
+  {"from":"web","to":"api","text":"REST"},
+  {"from":"api","to":"db","routing":"elbow"}
+]}
+```
+````
+
+The full skeleton spec (attach sides, explicit positions, free texts) is
+in [DRAWING_FORMAT.md](./DRAWING_FORMAT.md). Programmatic access:
+`parseDrawingSkeleton`, `expandSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA`.
 
 ## Outline & section folding
 
@@ -256,14 +369,19 @@ remount; a folded section auto-expands if the cursor enters it.
 Documents are plain markdown, so LLMs can generate them — including
 diagrams:
 
-- **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)** is the authoritative
-  ` ```drawing ` payload spec, written to be pasted into a prompt (ships in
-  the npm package next to this README).
-- `DRAWING_DATA_JSON_SCHEMA` (exported) is the same contract as JSON Schema
-  — use it to validate generated payloads or as a structured-output/tool
-  schema.
-- `parseDrawingData(json)` is the editor's own lenient parser (invalid
-  shapes drop out; never throws); `serializeDrawingData` is its inverse.
+- Emit ` ```diagram ` skeleton blocks: no coordinates, the editor lays them
+  out. Use ` ```drawing ` (format v2) only to edit an existing concrete
+  payload.
+- **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)** is the authoritative spec of
+  both payloads, written to be pasted into a prompt (ships in the npm
+  package next to this README).
+- `DRAWING_SKELETON_JSON_SCHEMA` and `DRAWING_DATA_JSON_SCHEMA` (exported)
+  are the same contracts as JSON Schema: use them to validate generated
+  payloads or as structured-output/tool schemas.
+- `parseDrawingSkeleton(json)` / `expandSkeleton(skeleton)` turn a skeleton
+  into `DrawingData`. `parseDrawingData(json)` is the editor's own lenient
+  parser (invalid shapes drop out; never throws); `serializeDrawingData` is
+  its inverse. `drawingToMermaid(data)` exports a Mermaid `flowchart`.
 - A ready-made Claude Code skill lives in the monorepo at
   `.claude/skills/text-editor-documents/` — copy it into consuming repos so
   agents there know the dialect.
@@ -277,14 +395,18 @@ diagrams:
 | `Toolbar`, `ToolbarButton`, `ToolbarDivider`, `FormatButtons`, `InsertButtons`, `HistoryButtons` | Toolbar primitives |
 | `@zuilib/text-editor/styles.css` | Editor chrome + theme styles (required) |
 | `TABLE` | GFM table markdown transformer |
-| `BlockWidth`, `TableDensity`, `TableSettings`, `DEFAULT_TABLE_SETTINGS` | Table setting types |
-| `$getTableSettings`, `$setTableSettings`, `$getTableWidth`, `$setTableWidth`, `$getTableDensity`, `$setTableDensity`, `$getSelectedTable` | Table setting helpers (inside `editor.update`/`read`) |
+| `BlockWidth`, `BLOCK_WIDTHS`, `isBlockWidth`, `BlockWidthDefaults` | Block width (`full` / `text` / `content`) type, values, guard, insertion defaults |
+| `TableDensity`, `TableSettings`, `TableSettingsOptions`, `DEFAULT_TABLE_SETTINGS` | Table setting types |
+| `$getTableSettings`, `$setTableSettings`, `$isTableWidthExplicit`, `$getTableWidth`, `$setTableWidth`, `$getTableDensity`, `$setTableDensity`, `$getSelectedTable` | Table setting helpers (inside `editor.update`/`read`) |
 | `parseTableSettingsMarker`, `formatTableSettingsMarker` | Marker comment ⇄ `TableSettings` |
-| `DRAWING`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + markdown transformer |
+| `DRAWING`, `DIAGRAM`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + markdown transformers (` ```drawing ` and ` ```diagram `) |
 | `FRONTMATTER`, `FrontmatterNode`, `$createFrontmatterNode`, `$isFrontmatterNode` | Frontmatter node + transformer |
 | `DrawingData`, `DrawingShape`, `DrawingShapeType` | Drawing payload types |
 | `parseDrawingData`, `serializeDrawingData` | Drawing payload (de)serialization |
 | `DRAWING_DATA_JSON_SCHEMA` | JSON Schema of the drawing payload |
+| `DrawingSkeleton`, `SkeletonBox`, `SkeletonConnector` | Skeleton types |
+| `parseDrawingSkeleton`, `expandSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA` | Skeleton parsing, expansion to `DrawingData`, JSON Schema |
+| `drawingToMermaid` | Mermaid `flowchart` export |
 
 ## Form integration
 
@@ -305,13 +427,15 @@ ZUI convention: a `dark` class on `<html>`.
 - Source: `src/EditorRoot.tsx` (composer + plugins), `src/EditorContent.tsx`,
   `src/MarkdownEditor.tsx` (default composition), `src/useMarkdownEditor.ts`,
   `src/components/Toolbar.tsx`; plugins in `src/plugins/`; drawing
-  canvas in `src/components/`; custom nodes in `src/nodes/`;
+  canvas in `src/drawing/`; custom nodes in `src/nodes/`;
   transformers in `src/transformers/`
 - Markdown import/export via `@lexical/markdown` transformers; order
-  matters: `FRONTMATTER` and `DRAWING` claim their blocks before `CODE`,
-  `CHECK_LIST` before `UNORDERED_LIST`
-- Drawing geometry (bindings resolver, elbow/waypoint paths, wrapping) is
-  pure and lives in `src/components/drawingGeometry.ts`
+  matters: `FRONTMATTER`, `DRAWING` and `DIAGRAM` claim their blocks before
+  `CODE`, `CHECK_LIST` before `UNORDERED_LIST`
+- `src/drawing/` keeps the format (`types.ts`, `schema.ts`), shape
+  definitions (`shapes/`), pure geometry (`geometry.ts`), the Mermaid
+  exporter (`mermaid.ts`) and the React canvas (`canvas/`) apart, so the
+  router, bindings and skeleton expansion run without a DOM
 - Tests: `pnpm test` runs a headless-Lexical markdown round-trip suite
   (`tests/roundtrip.mjs`)