@zuilib/text-editor 0.2.0 → 0.3.0

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;
 /**
@@ -104,6 +215,8 @@ type DrawingData = Readonly<{
     height: number;
     shapes: readonly DrawingShape[];
 }>;
+declare function serializeDrawingData(data: DrawingData): string;
+declare function parseDrawingData(json: string): DrawingData;
 
 type SerializedDrawingNode = Spread<{
     data: string;
@@ -147,4 +260,136 @@ declare const DRAWING: MultilineElementTransformer;
  */
 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 };
+/**
+ * JSON Schema (draft-07) for the payload of a ```drawing fenced block.
+ *
+ * Use it to validate LLM- or tool-generated drawings before embedding them,
+ * or pass it as a structured-output / tool schema so a model is forced to
+ * emit valid payloads. Kept in sync with `parseDrawingData` / `isValidShape`
+ * in drawingTypes.ts — update both together.
+ */
+declare const DRAWING_DATA_JSON_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "DrawingData";
+    readonly description: "Vector drawing embedded in markdown as a ```drawing fenced code block";
+    readonly type: "object";
+    readonly required: readonly ["version", "height", "shapes"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly version: {
+            readonly const: 1;
+        };
+        readonly height: {
+            readonly type: "number";
+            readonly minimum: 80;
+            readonly description: "Canvas height in pixels (width is fluid)";
+        };
+        readonly shapes: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/definitions/shape";
+            };
+            readonly description: "Render order: later shapes draw on top";
+        };
+    };
+    readonly definitions: {
+        readonly point: {
+            readonly type: "object";
+            readonly required: readonly ["x", "y"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly x: {
+                    readonly type: "number";
+                };
+                readonly y: {
+                    readonly type: "number";
+                };
+            };
+        };
+        readonly shape: {
+            readonly type: "object";
+            readonly required: readonly ["id", "type", "x", "y", "w", "h", "stroke", "fill", "strokeWidth"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly description: "Unique within the drawing; connector bindings reference it";
+                };
+                readonly type: {
+                    readonly enum: readonly ["rect", "ellipse", "triangle", "pentagon", "arrow", "line", "text"];
+                };
+                readonly x: {
+                    readonly type: "number";
+                    readonly description: "Boxes/text: left edge of the bounding box. Connectors: start point x.";
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly description: "Boxes/text: top edge of the bounding box. Connectors: start point y.";
+                };
+                readonly w: {
+                    readonly type: "number";
+                    readonly description: "Boxes/text: width (non-negative). Connectors: delta x to the end point (may be negative).";
+                };
+                readonly h: {
+                    readonly type: "number";
+                    readonly description: "Boxes/text: height (non-negative). Connectors: delta y to the end point (may be negative).";
+                };
+                readonly stroke: {
+                    readonly type: "string";
+                    readonly description: "CSS color of the outline (and of any text)";
+                };
+                readonly fill: {
+                    readonly type: "string";
+                    readonly description: "CSS color of the interior; \"transparent\" for none";
+                };
+                readonly strokeWidth: {
+                    readonly type: "number";
+                    readonly description: "Outline width; use 2";
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly description: "Standalone text content; center content of a box; midpoint label of a connector";
+                };
+                readonly label: {
+                    readonly type: "string";
+                    readonly description: "Boxes only: small bold heading at the top";
+                };
+                readonly footer: {
+                    readonly type: "string";
+                    readonly description: "Boxes only: small dim line at the bottom";
+                };
+                readonly startBinding: {
+                    readonly type: "string";
+                    readonly description: "Connectors only: id of the box the start attaches to. The editor re-anchors the endpoint onto that box’s border.";
+                };
+                readonly endBinding: {
+                    readonly type: "string";
+                    readonly description: "Connectors only: id of the box the end attaches to";
+                };
+                readonly bidirectional: {
+                    readonly type: "boolean";
+                    readonly description: "Arrows only: arrowheads on both ends";
+                };
+                readonly routing: {
+                    readonly const: "elbow";
+                    readonly description: "Connectors only: orthogonal (right-angled) auto-routing. Ignored when waypoints are present.";
+                };
+                readonly elbow: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 1;
+                    readonly description: "Elbow middle-segment position as a fraction of the span (default 0.5)";
+                };
+                readonly waypoints: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/definitions/point";
+                    };
+                    readonly description: "Connectors only: intermediate path points in canvas coordinates, ordered start→end. Takes precedence over routing.";
+                };
+            };
+        };
+    };
+};
+
+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 };