@zuilib/text-editor 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog — @zuilib/text-editor
 
+## 0.4.0
+
+- **Block width** for tables and drawings: switch any table or drawing
+  between *full width* (spans the editor, the previous behaviour) and
+  *content width* (shrinks to fit its columns / shapes, left-aligned with
+  the text), Slab-style
+  - Tables: a floating toggle docks to the top-right of the table the caret
+    is in; content width sizes columns by their content. Persisted as a
+    `<!-- width: content -->` line directly above the GFM table (hidden by
+    other markdown renderers)
+  - Drawings: toggle at the right end of the canvas toolbar; content width
+    fits the rightmost shape and grows as shapes move. Persisted as a
+    top-level `"width":"content"` field in the ```drawing payload
+    (`DrawingData.width`, `DRAWING_DATA_JSON_SCHEMA` updated; omitted when
+    full, so existing payloads are unchanged)
+  - `useMarkdownEditor()` gains `tableWidth` / `setTableWidth` for custom
+    toolbars
+  - New exports: `BlockWidth`, `$getTableWidth`, `$setTableWidth`,
+    `$getSelectedTable`, `TABLE_WIDTH_MARKER`
+
+## 0.3.0
+
+- **Custom toolbars**
+  - `toolbar` prop accepts a render function receiving the default groups
+    (`format`, `insert`, `history`) so you can add your own buttons
+  - Compound components: `MarkdownEditor.Root` / `.Content` / `.Toolbar` /
+    `.Outline` plus `.FormatButtons` / `.InsertButtons` / `.HistoryButtons` /
+    `.ToolbarButton` / `.ToolbarDivider` — place the toolbar anywhere under
+    `Root`
+  - `useMarkdownEditor()` headless hook: `editor`, `activeFormats`,
+    `toggleFormat`, `insertTable`, `insertDrawing`, `undo`/`redo`
+- Undo/redo buttons (`HistoryButtons`; in the default toolbar via the
+  function form only — default toolbar layout unchanged)
+- Internal: `LexicalComposer` is now mounted in `edit-raw` mode too, so
+  hooks keep working across mode switches
+
 ## 0.2.1
 
 - `DRAWING_FORMAT.md`: authoritative spec of the ```drawing JSON payload,

package/DRAWING_FORMAT.md

@@ -22,8 +22,12 @@ degrades to an empty canvas (invalid shapes are dropped individually).
 
 - Origin `(0,0)` is the canvas's top-left; x grows right, y grows down.
 - Units are CSS pixels.
-- The canvas is as wide as the editor (fluid). Keep shapes within roughly
-  x ∈ [0, 700] to be safe on typical layouts.
+- The canvas is as wide as the editor by default (`width` omitted or
+  `"full"`). Keep shapes within roughly x ∈ [0, 700] to be safe on typical
+  layouts.
+- `"width":"content"` instead sizes the canvas to fit the rightmost shape
+  (plus a margin, never narrower than 240px), left-aligned with the text —
+  use it for small diagrams that shouldn't stretch across the page.
 - `height` is the canvas height in pixels (minimum 80; 300–400 is typical).
 
 ## Top-level object
@@ -32,6 +36,7 @@ degrades to an empty canvas (invalid shapes are dropped individually).
 |-----------|-----------|-----------------------------------------|
 | `version` | `1`       | Literal `1`                             |
 | `height`  | `number`  | Canvas height in px                     |
+| `width`   | `"full"` \| `"content"` | Optional; default `"full"`. `"content"` fits the shapes' extent |
 | `shapes`  | `Shape[]` | Render order: later shapes draw on top  |
 
 ## Shape object

package/README.md

@@ -13,6 +13,8 @@ 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
@@ -65,7 +67,7 @@ emits. The emitted string is always plain markdown.
 | `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 (`edit-md`) |
+| `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 |
 
@@ -96,6 +98,114 @@ 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
+
+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:
+
+```md
+<!-- width: content -->
+| 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`.
+
+## Toolbar & custom toolbars
+
+In `edit-md` mode a toolbar offers inline formatting (bold, italic,
+strikethrough, inline code) plus **Insert table** and **Insert drawing**.
+Hide it with `toolbar={false}`.
+
+### Extending the toolbar
+
+Pass a function as `toolbar`. It receives the default button groups and
+returns the toolbar to render. Use `MarkdownEditor.ToolbarButton` for your
+own buttons so they match the built-ins and keep the editor selection when
+clicked.
+
+```tsx
+<MarkdownEditor
+  value={value}
+  onChange={setValue}
+  toolbar={(items) => (
+    <MarkdownEditor.Toolbar>
+      {items.format}
+      <MarkdownEditor.ToolbarDivider />
+      {items.insert}
+      <MarkdownEditor.ToolbarDivider />
+      {items.history}
+      <MarkdownEditor.ToolbarButton label="Save" onClick={save}>
+        💾
+      </MarkdownEditor.ToolbarButton>
+    </MarkdownEditor.Toolbar>
+  )}
+/>
+```
+
+`MarkdownEditor.Toolbar` hides itself in `view` / `edit-raw` / `readOnly`.
+
+### Placing your own toolbar (compound components)
+
+When the toolbar must live somewhere else in your layout (an app bar, a
+panel header), compose the editor from its parts. Everything under
+`MarkdownEditor.Root` shares one editor instance, so the toolbar can sit
+anywhere in that subtree.
+
+```tsx
+<MarkdownEditor.Root value={value} onChange={setValue}>
+  <header className="app-bar">
+    <MarkdownEditor.Toolbar>
+      <MarkdownEditor.FormatButtons />
+      <MarkdownEditor.ToolbarDivider />
+      <MarkdownEditor.InsertButtons />
+    </MarkdownEditor.Toolbar>
+    <MyAppButtons />
+  </header>
+  <MarkdownEditor.Content placeholder="Write…">
+    <MarkdownEditor.Outline />
+  </MarkdownEditor.Content>
+</MarkdownEditor.Root>
+```
+
+| Part | Role |
+|------|------|
+| `Root` | Lexical composer + plugins. Takes `value`, `onChange`, `mode`, `readOnly`, `autoFocus`, `className` |
+| `Content` | The editable surface. Takes `placeholder`, `foldable`; children are docked sidebars |
+| `Toolbar` | Container; renders the default groups when empty |
+| `FormatButtons`, `InsertButtons`, `HistoryButtons` | Built-in groups |
+| `ToolbarButton`, `ToolbarDivider` | Primitives for your own items |
+| `Outline` | Table-of-contents sidebar |
+
+### Headless: `useMarkdownEditor()`
+
+For fully custom UI (e.g. buttons in your own design system), call the hook
+from any component rendered under `MarkdownEditor.Root`:
+
+```tsx
+function BoldButton() {
+  const { activeFormats, toggleFormat } = useMarkdownEditor()
+  return (
+    <MyButton pressed={activeFormats.has('bold')} onClick={() => toggleFormat('bold')}>
+      B
+    </MyButton>
+  )
+}
+```
+
+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`.
+
 ## Diagrams (drawing canvas)
 
 The toolbar's insert-drawing button embeds a canvas; the drawing persists
@@ -117,6 +227,10 @@ in the markdown as a ` ```drawing ` fenced JSON block, fully specified in
   bends). One-way / two-way arrowhead toggle; midpoint **labels**.
 - **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.
 
 ## Outline & section folding
 
@@ -150,9 +264,12 @@ diagrams:
 
 | Export | Purpose |
 |--------|---------|
-| `MarkdownEditor`, `MarkdownEditorProps` | The component |
+| `MarkdownEditor`, `MarkdownEditorProps` | The component; compound parts as statics (`.Root`, `.Content`, `.Toolbar`, …) |
+| `useMarkdownEditor`, `MarkdownEditorApi` | Headless editor hook |
+| `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 |
 | `FRONTMATTER`, `FrontmatterNode`, `$createFrontmatterNode`, `$isFrontmatterNode` | Frontmatter node + transformer |
 | `DrawingData`, `DrawingShape`, `DrawingShapeType` | Drawing payload types |
@@ -175,7 +292,9 @@ ZUI convention: a `dark` class on `<html>`.
 
 ## Architecture notes (for extenders)
 
-- Source: `src/MarkdownEditor.tsx`; plugins in `src/plugins/`; drawing
+- 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/`;
   transformers in `src/transformers/`
 - Markdown import/export via `@lexical/markdown` transformers; order

package/dist/index.d.ts

@@ -1,24 +1,147 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ElementNode, NodeKey, EditorConfig, SerializedElementNode, LexicalNode, DecoratorNode, Spread, SerializedLexicalNode, DOMExportOutput, DOMConversionMap, LexicalEditor } from 'lexical';
+import { ReactNode, ReactElement } from 'react';
+import { LexicalEditor, TextFormatType, ElementNode, NodeKey, EditorConfig, SerializedElementNode, LexicalNode, DecoratorNode, Spread, SerializedLexicalNode, DOMExportOutput, DOMConversionMap } from 'lexical';
 import { MultilineElementTransformer, ElementTransformer } from '@lexical/markdown';
-import { ReactElement } from 'react';
+import { TableNode } from '@lexical/table';
 
-type Props = Readonly<{
+type EditorMode = 'edit-raw' | 'edit-md' | 'view';
+type EditorRootProps = Readonly<{
     value?: string;
     onChange?: (value: string) => void;
-    placeholder?: string;
     readOnly?: boolean;
     className?: string;
-    mode?: 'edit-raw' | 'edit-md' | 'view';
+    mode?: EditorMode;
     autoFocus?: boolean;
-    /** Show the formatting/insert toolbar in edit-md mode (default true) */
-    toolbar?: boolean;
+    children: ReactNode;
+}>;
+/**
+ * Owns the Lexical composer and every non-visual plugin. Anything rendered
+ * beneath it (`Content`, `Toolbar`, `Outline`, or your own components using
+ * `useMarkdownEditor`) shares the same editor instance.
+ */
+declare function EditorRoot({ value, onChange, readOnly, className, mode, autoFocus, children, }: EditorRootProps): ReactElement;
+
+type EditorContentProps = Readonly<{
+    placeholder?: string;
+    /** Allow collapsing sections under their headings (default true) */
+    foldable?: boolean;
+    /** Sidebars docked next to the content, e.g. `<MarkdownEditor.Outline />` */
+    children?: ReactNode;
+}>;
+/**
+ * The editable surface. Renders a plain textarea in `edit-raw` mode and the
+ * Lexical rich-text surface otherwise.
+ */
+declare function EditorContent({ placeholder, foldable, children, }: EditorContentProps): ReactElement;
+
+/**
+ * Docked, collapsible table-of-contents sidebar. Lists the document's
+ * headings (live), scrolls to a heading on click, and highlights the section
+ * the viewport is currently in. Pure UI — nothing is added to the document.
+ */
+declare function OutlinePlugin(): ReactElement;
+
+/**
+ * Horizontal sizing of a block that would otherwise span the editor:
+ * `full` stretches to the content column, `content` shrinks to fit what is
+ * inside (table columns, drawing shapes) and left-aligns with the text.
+ */
+type BlockWidth = 'full' | 'content';
+
+type MarkdownEditorApi = Readonly<{
+    /** The underlying Lexical editor, for dispatching your own commands */
+    editor: LexicalEditor;
+    /** Text formats active at the current selection */
+    activeFormats: ReadonlySet<TextFormatType>;
+    toggleFormat: (format: TextFormatType) => void;
+    insertTable: (options?: {
+        rows?: number;
+        columns?: number;
+    }) => void;
+    insertDrawing: () => void;
+    /** Width of the table containing the selection; `null` outside tables */
+    tableWidth: BlockWidth | null;
+    /** Resize the table containing the selection; no-op outside tables */
+    setTableWidth: (width: BlockWidth) => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+}>;
+/**
+ * Headless access to the editor. Must be rendered under `MarkdownEditor.Root`
+ * (or `MarkdownEditor`). Use it to wire editor actions into your own buttons.
+ */
+declare function useMarkdownEditor(): MarkdownEditorApi;
+
+/** Default toolbar groups, handed to a `toolbar` render function */
+type ToolbarItems = Readonly<{
+    format: ReactElement;
+    insert: ReactElement;
+    history: ReactElement;
+}>;
+type Props = Omit<EditorRootProps, 'children'> & Readonly<{
+    placeholder?: string;
+    /**
+     * Toolbar in edit-md mode (default true). Pass a function to customise
+     * it: it receives the default groups and returns the toolbar to render.
+     */
+    toolbar?: boolean | ((items: ToolbarItems) => ReactNode);
     /** 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, toolbar, outline, foldable, }: Props): react_jsx_runtime.JSX.Element;
+/**
+ * Toolbar that only shows while the document is editable in `edit-md` mode.
+ * Used by `MarkdownEditor` and available as `MarkdownEditor.Toolbar` for
+ * compound layouts.
+ */
+declare function EditorToolbar({ children, className, }: Readonly<{
+    children?: ReactNode;
+    className?: string;
+}>): ReactElement | null;
+declare function MarkdownEditor({ placeholder, toolbar, outline, foldable, ...rootProps }: Props): react_jsx_runtime.JSX.Element;
+declare namespace MarkdownEditor {
+    var Root: typeof EditorRoot;
+    var Content: typeof EditorContent;
+    var Toolbar: typeof EditorToolbar;
+    var ToolbarButton: typeof ToolbarButton;
+    var ToolbarDivider: typeof ToolbarDivider;
+    var FormatButtons: typeof FormatButtons;
+    var InsertButtons: typeof InsertButtons;
+    var HistoryButtons: typeof HistoryButtons;
+    var Outline: typeof OutlinePlugin;
+    var useEditor: typeof useMarkdownEditor;
+}
+
+type ToolbarProps = Readonly<{
+    children?: ReactNode;
+    className?: string;
+}>;
+/** Toolbar container. Renders the default items when given no children. */
+declare function Toolbar({ children, className }: ToolbarProps): ReactElement;
+declare function ToolbarDivider(): ReactElement;
+type ToolbarButtonProps = Readonly<{
+    label: string;
+    onClick: () => void;
+    /** Icon content — an SVG, emoji, or text. 16px SVGs match the built-ins. */
+    children: ReactNode;
+    active?: boolean;
+    disabled?: boolean;
+    className?: string;
+}>;
+/**
+ * Button styled like the built-in toolbar buttons. Prevents focus from
+ * leaving the editor on click so the selection is preserved.
+ */
+declare function ToolbarButton({ label, onClick, children, active, disabled, className, }: ToolbarButtonProps): ReactElement;
+/** Bold / italic / strikethrough / inline-code buttons */
+declare function FormatButtons(): ReactElement;
+/** Insert-table / insert-drawing buttons */
+declare function InsertButtons(): ReactElement;
+/** Undo / redo buttons */
+declare function HistoryButtons(): ReactElement;
 
 type SerializedFrontmatterNode = SerializedElementNode;
 /**
@@ -102,6 +225,11 @@ type DrawingShape = Readonly<{
 type DrawingData = Readonly<{
     version: 1;
     height: number;
+    /**
+     * Canvas width: `full` (default, omitted when serialized) spans the editor;
+     * `content` fits the shapes' horizontal extent.
+     */
+    width?: BlockWidth;
     shapes: readonly DrawingShape[];
 }>;
 declare function serializeDrawingData(data: DrawingData): string;
@@ -146,9 +274,23 @@ 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.
+ * A `<!-- width: content -->` line directly above the table marks it as
+ * content-width (see tableWidth.ts); it is consumed on import and re-emitted
+ * on export.
  */
 declare const TABLE: ElementTransformer;
 
+/**
+ * A content-width table is persisted in markdown as a GFM table preceded by
+ * this HTML comment on its own line. Renderers that don't know the marker
+ * simply hide the comment.
+ */
+declare const TABLE_WIDTH_MARKER = "<!-- width: content -->";
+declare function $getTableWidth(table: TableNode): BlockWidth;
+declare function $setTableWidth(table: TableNode, width: BlockWidth): void;
+/** The table containing the current selection (caret or cell range), if any */
+declare function $getSelectedTable(): TableNode | null;
+
 /**
  * JSON Schema (draft-07) for the payload of a ```drawing fenced block.
  *
@@ -171,7 +313,11 @@ declare const DRAWING_DATA_JSON_SCHEMA: {
         readonly height: {
             readonly type: "number";
             readonly minimum: 80;
-            readonly description: "Canvas height in pixels (width is fluid)";
+            readonly description: "Canvas height in pixels";
+        };
+        readonly width: {
+            readonly enum: readonly ["full", "content"];
+            readonly description: "Canvas width: \"full\" (default) spans the editor; \"content\" fits the shapes' horizontal extent and left-aligns with the text";
         };
         readonly shapes: {
             readonly type: "array";
@@ -281,4 +427,4 @@ declare const DRAWING_DATA_JSON_SCHEMA: {
     };
 };
 
-export { $createDrawingNode, $createFrontmatterNode, $isDrawingNode, $isFrontmatterNode, DRAWING, DRAWING_DATA_JSON_SCHEMA, type DrawingData, DrawingNode, type DrawingShape, type DrawingShapeType, FRONTMATTER, FrontmatterNode, MarkdownEditor, type Props as MarkdownEditorProps, type SerializedDrawingNode, type SerializedFrontmatterNode, TABLE, parseDrawingData, serializeDrawingData };
+export { $createDrawingNode, $createFrontmatterNode, $getSelectedTable, $getTableWidth, $isDrawingNode, $isFrontmatterNode, $setTableWidth, type BlockWidth, DRAWING, DRAWING_DATA_JSON_SCHEMA, type DrawingData, DrawingNode, type DrawingShape, type DrawingShapeType, type EditorContentProps, type EditorMode, type EditorRootProps, FRONTMATTER, FormatButtons, FrontmatterNode, HistoryButtons, InsertButtons, MarkdownEditor, type MarkdownEditorApi, type Props as MarkdownEditorProps, type SerializedDrawingNode, type SerializedFrontmatterNode, TABLE, TABLE_WIDTH_MARKER, Toolbar, ToolbarButton, ToolbarDivider, type ToolbarItems, parseDrawingData, serializeDrawingData, useMarkdownEditor };