@zuilib/text-editor 0.3.1 → 0.5.0

package/README.md

@@ -13,11 +13,14 @@ 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
-- **Block width**: tables and diagrams switch between full width and
-  content width, 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
+- **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. 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
@@ -98,26 +101,33 @@ 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`.
 
-### Full width vs content width
+### Table settings: width and density
 
-Tables span the editor by default. Place the caret in a table and a small
-toggle floats at its top-right corner: **full width** (columns share the
-editor width) or **content width** (the table shrinks to fit its columns,
-left-aligned with the text, never wider than the editor). The setting is
-persisted as an HTML comment on the line directly above the table — other
-markdown renderers hide it:
+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.
+
+Non-default settings are persisted as one HTML comment on the line directly
+above the table — other markdown renderers hide it:
 
 ```md
-<!-- width: content -->
+<!-- width: content; density: compact -->
 | Key | Value |
 | --- | --- |
 | Region | eu-west-1 |
 ```
 
-Programmatic access: `useMarkdownEditor().tableWidth` / `setTableWidth`
-(for custom toolbars), or `$getTableWidth(node)` / `$setTableWidth(node,
-width)` inside `editor.update`. The marker string is exported as
-`TABLE_WIDTH_MARKER`.
+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.
 
 ## Toolbar & custom toolbars
 
@@ -203,35 +213,86 @@ function BoldButton() {
 
 It returns `editor` (the Lexical instance), `activeFormats`,
 `toggleFormat`, `insertTable`, `insertDrawing`, `tableWidth` /
-`setTableWidth` (width of the table containing the selection, `null`
-outside tables), `canUndo`, `canRedo`, `undo`, `redo`.
+`setTableWidth` and `tableDensity` / `setTableDensity` (settings of the
+table containing the selection, `null` outside tables), `canUndo`,
+`canRedo`, `undo`, `redo`.
 
 ## 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).
+  Excalidraw-style in dark mode (`.dark` ancestor class). An optional
+  `canvasWidth` scales the drawing to fit narrower layouts.
 - **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.
 
+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
 
 `outline` docks a collapsible table-of-contents sidebar: live heading list
@@ -248,14 +309,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.
@@ -269,12 +335,17 @@ 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`, `$getTableWidth`, `$setTableWidth`, `$getSelectedTable`, `TABLE_WIDTH_MARKER` | Table full/content width helpers |
-| `DRAWING`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + 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`) |
+| `parseTableSettingsMarker`, `formatTableSettingsMarker` | Marker comment ⇄ `TableSettings` |
+| `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
 
@@ -295,13 +366,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`)