@zuilib/text-editor 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog — @zuilib/text-editor
 
+## 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/README.md

@@ -65,7 +65,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 +96,92 @@ 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`.
 
+## 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`, `canUndo`, `canRedo`,
+`undo`, `redo`.
+
 ## Diagrams (drawing canvas)
 
 The toolbar's insert-drawing button embeds a canvas; the drawing persists
@@ -150,7 +236,9 @@ 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 |
 | `DRAWING`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + markdown transformer |
@@ -175,7 +263,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,135 @@
 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';
 
-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;
+
+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;
+    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;
 /**
@@ -281,4 +392,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, $isDrawingNode, $isFrontmatterNode, 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, Toolbar, ToolbarButton, ToolbarDivider, type ToolbarItems, parseDrawingData, serializeDrawingData, useMarkdownEditor };