@zuilib/text-editor 0.0.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @zuilib/text-editor
 
-Markdown editor for ZUI built on [Lexical](https://lexical.dev/): rich editing with shortcuts, raw markdown mode, read-only view, checklists, and fenced code highlighting.
+Markdown editor for ZUI built on [Lexical](https://lexical.dev/): rich editing with shortcuts, raw markdown mode, read-only view, checklists, fenced code highlighting, GFM tables, and an embedded drawing canvas for diagrams.
 
 ## When to use
 
@@ -22,6 +22,8 @@ Peer dependencies (install in the consuming app):
 | `@lexical/code` | `^0.35.0` |
 | `@lexical/list` | `^0.35.0` |
 | `@lexical/link` | `^0.35.0` |
+| `@lexical/table` | `^0.35.0` |
+| `@lexical/utils` | `^0.35.0` |
 | `@zuilib/core` | workspace / published — import core styles |
 
 ## Installation
@@ -29,7 +31,7 @@ Peer dependencies (install in the consuming app):
 ```bash
 pnpm add @zuilib/text-editor @zuilib/core \
   lexical @lexical/react @lexical/markdown @lexical/rich-text \
-  @lexical/code @lexical/list @lexical/link
+  @lexical/code @lexical/list @lexical/link @lexical/table @lexical/utils
 ```
 
 Monorepo:
@@ -45,7 +47,9 @@ Monorepo:
     "@lexical/rich-text": "^0.35.0",
     "@lexical/code": "^0.35.0",
     "@lexical/list": "^0.35.0",
-    "@lexical/link": "^0.35.0"
+    "@lexical/link": "^0.35.0",
+    "@lexical/table": "^0.35.0",
+    "@lexical/utils": "^0.35.0"
   }
 }
 ```
@@ -115,15 +119,62 @@ Toggle modes in parent state; the editor preserves content via an internal ref w
 | `readOnly` | `boolean` | `false` | Disables editing in Lexical modes |
 | `autoFocus` | `boolean` | `false` | Focus on mount |
 | `className` | `string` | — | Root wrapper class |
+| `toolbar` | `boolean` | `true` | Formatting/insert toolbar in `edit-md` mode |
+| `outline` | `boolean` | `false` | Table-of-contents sidebar listing headings |
+| `foldable` | `boolean` | `true` | Collapse sections under their headings |
 
 ## Markdown features
 
-**Shortcuts (edit-md):** headings (`#`), lists, blockquote, links, fenced code (via `CodeBlockShortcutPlugin`), checklists (`- [ ]` via `ChecklistShortcutPlugin`).
+**Shortcuts (edit-md):** headings (`#`), lists, blockquote, links, fenced code (via `CodeBlockShortcutPlugin`), checklists (`- [ ]` via `ChecklistShortcutPlugin`), tables (`| a | b |`).
 
-**Built-in plugins:** history (undo/redo), lists, checklists, links, markdown sync (`MarkdownSyncPlugin`), code highlighting (`CodeHighlightPlugin`).
+**Built-in plugins:** history (undo/redo), lists, checklists, links, tables (`TablePlugin`), markdown sync (`MarkdownSyncPlugin`), code highlighting (`CodeHighlightPlugin`), toolbar (`ToolbarPlugin`).
 
 **Not included:** file uploads, collaborative editing, or custom Lexical node registration — extend by forking or wrapping `MarkdownEditor`.
 
+## Tables
+
+GFM pipe tables round-trip through markdown and render artifact-style (rounded outer border, shaded header row, per-cell rules):
+
+```md
+| Metric | Q1 | Q2 |
+| --- | --- | --- |
+| Revenue | $1.2M | $1.8M |
+```
+
+Insert a 3×3 table from the toolbar, or type a `| a | b |` row. Tab/arrow navigation, cell selection, and row/column operations come from Lexical's `TablePlugin`. Inline formatting (`**bold**`, `*italic*`, `` `code` ``) works inside cells.
+
+## Drawing canvas
+
+The toolbar's "Insert drawing" button embeds an Excalidraw-style canvas for simple diagrams: rectangles, ellipses, triangles, pentagons, arrows, lines, and text labels, with a stroke and fill color palette.
+
+- Draw a shape by picking a tool and dragging; the tool returns to **Select** after each shape
+- Select to move, resize (corner handles), or re-point arrows/lines (endpoint handles)
+- Color swatches restyle the selected shape (or set defaults for the next one)
+- `Delete`/`Backspace` removes the selected shape; drag the bottom pill to resize the canvas
+- Boxes (rects/ellipses) have three built-in text slots that move with the shape: a bold **label** at the top, main **content** in the center, and a dimmer **footer** at the bottom. Double-click the top strip of a box to edit the label, the middle for content, the bottom strip for the footer (or click a selected box again, or press Enter for content). Clearing a slot removes it; the box stays.
+- **Arrows bind to boxes**: draw an arrow starting or ending on a box and it attaches to the box border — moving or resizing the box drags the arrow along. Endpoints re-anchor toward the other end automatically. Drag an endpoint off a box to detach it; drop it on another box to re-attach. Deleting a box releases its arrows.
+- A selected arrow shows a **direction toggle** in the toolbar: one-way (head at the end) or two-way (heads on both ends).
+- A selected connector also shows a **routing toggle**: straight (freely diagonal) or **elbow** — an orthogonal path with right-angle bends. The elbow's middle segment has a drag handle to reposition the bend; its position is stored as a fraction of the span so it stays put while bound boxes move.
+- **Waypoints** for arbitrary multi-segment paths: a selected connector shows dashed "+" handles at each segment midpoint — drag one to insert a bend point there. Waypoints snap to their neighbors' axes near-alignment so right angles are easy; drag freely for diagonals. Double-click a waypoint to remove it. Adding a point to an elbow connector converts its corners into editable waypoints. Selecting a routing mode from the toolbar clears waypoints.
+- **Arrows and lines can carry a label**: double-click the connector (or select it and press Enter) to edit text that rides the midpoint on a small backing plate, and moves as the connector moves.
+- The standalone **Text** tool is for free-floating annotations (e.g. labeling an arrow); double-click to edit
+
+Drawings persist inside the markdown as a fenced block, so the document stays a plain string:
+
+````md
+```drawing
+{"version":1,"height":320,"shapes":[...]}
+```
+````
+
+In `view` mode (or `readOnly`) the canvas renders the shapes without any editing chrome.
+
+## Outline & section folding
+
+`outline` docks a collapsible table-of-contents sidebar on the right: it lists the document's headings live (indented by level), scrolls to a heading on click, and highlights the section currently in view. Pure UI — nothing is added to the document. Works in `edit-md` and `view` modes (not `edit-raw`).
+
+`foldable` (on by default) adds a chevron in the left gutter of every heading (visible on hover). Clicking it collapses the section — everything up to the next heading of the same or higher level — marked by a trailing `…` on the heading. Folding is view-layer only: the markdown string is unaffected, and fold state resets on remount. If the cursor enters a folded section (e.g. via arrow keys), it auto-expands so content can never be edited invisibly.
+
 ## Form integration
 
 With `@zuilib/form`:

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ElementNode, NodeKey, EditorConfig, SerializedElementNode, LexicalNode } from 'lexical';
-import { MultilineElementTransformer } from '@lexical/markdown';
+import { ElementNode, NodeKey, EditorConfig, SerializedElementNode, LexicalNode, DecoratorNode, Spread, SerializedLexicalNode, DOMExportOutput, DOMConversionMap, LexicalEditor } from 'lexical';
+import { MultilineElementTransformer, ElementTransformer } from '@lexical/markdown';
+import { ReactElement } from 'react';
 
 type Props = Readonly<{
     value?: string;
@@ -10,8 +11,14 @@ type Props = Readonly<{
     className?: string;
     mode?: 'edit-raw' | 'edit-md' | 'view';
     autoFocus?: boolean;
+    /** Show the formatting/insert toolbar in edit-md mode (default true) */
+    toolbar?: boolean;
+    /** Show a table-of-contents sidebar listing the document's headings */
+    outline?: boolean;
+    /** Allow collapsing sections under their headings (default true) */
+    foldable?: boolean;
 }>;
-declare function MarkdownEditor({ value, onChange, placeholder, readOnly, className, mode, autoFocus, }: Props): react_jsx_runtime.JSX.Element;
+declare function MarkdownEditor({ value, onChange, placeholder, readOnly, className, mode, autoFocus, toolbar, outline, foldable, }: Props): react_jsx_runtime.JSX.Element;
 
 type SerializedFrontmatterNode = SerializedElementNode;
 /**
@@ -54,4 +61,90 @@ declare function $isFrontmatterNode(node: LexicalNode | null | undefined): node
  */
 declare const FRONTMATTER: MultilineElementTransformer;
 
-export { $createFrontmatterNode, $isFrontmatterNode, FRONTMATTER, FrontmatterNode, MarkdownEditor, type Props as MarkdownEditorProps, type SerializedFrontmatterNode };
+type DrawingShapeType = 'rect' | 'ellipse' | 'triangle' | 'pentagon' | 'arrow' | 'line' | 'text';
+type DrawingShape = Readonly<{
+    id: string;
+    type: DrawingShapeType;
+    /** Top-left corner (rect/ellipse/text) or start point (arrow/line) */
+    x: number;
+    y: number;
+    /** Size (rect/ellipse) or delta to the end point (arrow/line) */
+    w: number;
+    h: number;
+    stroke: string;
+    fill: string;
+    strokeWidth: number;
+    /** Standalone text, main (center) content of a box, or connector label */
+    text?: string;
+    /** Small heading rendered at the top of a box */
+    label?: string;
+    /** Small line rendered at the bottom of a box */
+    footer?: string;
+    /** Arrow/line: id of the box the start point is attached to */
+    startBinding?: string;
+    /** Arrow/line: id of the box the end point is attached to */
+    endBinding?: string;
+    /** Arrow: render arrowheads on both ends */
+    bidirectional?: boolean;
+    /** Connector routing: right-angled elbow path instead of a straight line */
+    routing?: 'elbow';
+    /** Elbow middle-segment position as a fraction of the span (default 0.5) */
+    elbow?: number;
+    /**
+     * Connector: intermediate path points between start and end (absolute
+     * canvas coordinates). Takes precedence over `routing`.
+     */
+    waypoints?: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+}>;
+type DrawingData = Readonly<{
+    version: 1;
+    height: number;
+    shapes: readonly DrawingShape[];
+}>;
+
+type SerializedDrawingNode = Spread<{
+    data: string;
+}, SerializedLexicalNode>;
+/**
+ * A block-level decorator node embedding a vector drawing (rectangles,
+ * ellipses, arrows, lines, text) edited on an Excalidraw-style canvas.
+ *
+ * The drawing is stored as a JSON string and round-trips through markdown as
+ * a ```drawing fenced code block, so documents remain plain markdown.
+ */
+declare class DrawingNode extends DecoratorNode<ReactElement> {
+    __data: string;
+    static getType(): string;
+    static clone(node: DrawingNode): DrawingNode;
+    constructor(data: string, key?: NodeKey);
+    static importJSON(serializedNode: SerializedDrawingNode): DrawingNode;
+    exportJSON(): SerializedDrawingNode;
+    createDOM(config: EditorConfig): HTMLElement;
+    updateDOM(): false;
+    exportDOM(): DOMExportOutput;
+    static importDOM(): DOMConversionMap | null;
+    getData(): DrawingData;
+    setData(data: DrawingData): void;
+    isInline(): false;
+    decorate(_editor: LexicalEditor, _config: EditorConfig): ReactElement;
+}
+declare function $createDrawingNode(data?: string): DrawingNode;
+declare function $isDrawingNode(node: LexicalNode | null | undefined): node is DrawingNode;
+/**
+ * Markdown transformer persisting drawings as fenced ```drawing blocks with a
+ * JSON payload. Must be ordered before the built-in CODE transformer so it
+ * claims the fence first on import.
+ */
+declare const DRAWING: MultilineElementTransformer;
+
+/**
+ * Markdown transformer for GFM tables. Adapted from the Lexical playground.
+ * Rows are matched line-by-line on import and stitched into a single
+ * TableNode; the divider row promotes the row above it to a header row.
+ */
+declare const TABLE: ElementTransformer;
+
+export { $createDrawingNode, $createFrontmatterNode, $isDrawingNode, $isFrontmatterNode, DRAWING, type DrawingData, DrawingNode, type DrawingShape, type DrawingShapeType, FRONTMATTER, FrontmatterNode, MarkdownEditor, type Props as MarkdownEditorProps, type SerializedDrawingNode, type SerializedFrontmatterNode, TABLE };