@tarviks/lexical-rich-editor 1.2.1 → 1.3.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import React from 'react';
+import { InitialConfigType } from '@lexical/react/LexicalComposer';
+import { LexicalEditor } from 'lexical';
 
 /** How the suggestion was accepted */
 /**
@@ -83,45 +85,203 @@ type BlockSpec = {
  * Allows programmatic read/write, focus control, and state checks.
  */
 type ContentEditorRef = {
-    /** Replace the entire document content with the provided HTML. */
+    /**
+     * Replace the entire document with the provided HTML string.
+     *
+     * The HTML is sanitized before import, so event handlers and dangerous
+     * URL schemes are automatically stripped.
+     *
+     * ⚠️ Do NOT call this inside an effect that watches the same `value` prop —
+     * it will create an infinite update loop.  Use the controlled `value` prop
+     * for external state synchronization instead.
+     *
+     * @param html - HTML to load.  Pass an empty string to clear the editor.
+     *
+     * @example
+     * editorRef.current?.setValue('<p>Hello <strong>world</strong></p>');
+     */
     setValue: (html: string) => void;
-    /** Return the current document as HTML. */
+    /**
+     * Return the current document as an HTML string.
+     *
+     * The returned HTML is Lexical-normalized (class names, data-attributes, etc.)
+     * and is safe to store and later reload via `value` prop or `setValue()`.
+     *
+     * @example
+     * const html = editorRef.current?.getValue();
+     * await saveToDatabase(html);
+     */
     getValue: () => string;
-    /** Clear the document to an empty state. */
+    /**
+     * Clear the editor to a completely empty state.
+     *
+     * Equivalent to `setValue('')` but more efficient — skips HTML parsing.
+     */
     clear: () => void;
-    /** Move focus to the editable area. */
+    /**
+     * Move keyboard focus into the editable content area.
+     *
+     * Useful for auto-focus after a modal opens or a dialog is confirmed.
+     */
     focus: () => void;
-    /** Remove focus from the editable area. */
+    /**
+     * Remove keyboard focus from the editable content area.
+     */
     blur: () => void;
-    /** Whether the editor currently contains no user content. */
+    /**
+     * Returns `true` when the editor contains no visible user content.
+     *
+     * Note: system blocks inserted via `upsertBlock` may still affect this check
+     * unless the implementation explicitly excludes `HtmlBlockNode` content.
+     *
+     * @example
+     * if (editorRef.current?.isEmpty()) {
+     *   alert('Please write something before sending.');
+     * }
+     */
     isEmpty: () => boolean;
-    /** Whether the editor currently has input focus. */
-    isFocused: () => boolean;
     /**
-     * Display one or more error messages inside the editor immediately.
-     * These are shown alongside any prop-based `errors`.
-     * Example: ref.current.setErrors(['Attachment too large', 'Subject is required'])
+     * Returns `true` when the editor's content area currently has input focus.
      */
-    setErrors: (messages: string[]) => void;
-    /** Remove all errors that were set via `setErrors`. */
-    clearErrors: () => void;
+    isFocused: () => boolean;
     /**
-     * Access the underlying Lexical editor instance for advanced usage.
-     * Returned type is `any` to avoid leaking internal Lexical types.
+     * Access the underlying Lexical `LexicalEditor` instance.
+     *
+     * Use only for advanced integrations (custom commands, plugins, etc.).
+     * The return type is `any` to avoid coupling consumers to Lexical's internal
+     * types; cast to `LexicalEditor` from the `lexical` package if needed.
+     *
+     * @example
+     * import { $getRoot } from 'lexical';
+     * const lexical = editorRef.current?.getEditor();
+     * lexical?.getEditorState().read(() => console.log($getRoot().getTextContent()));
      */
     getEditor: () => any;
     /**
-     * Insert or update a block identified by `spec.kind`.
+     * Insert or update a named system block in the document.
+     *
+     * System blocks (signature, footer, banner, etc.) are tracked by `kind` and
+     * rendered as non-editable regions. The user can delete them but cannot type
+     * inside them. They do **not** affect `checkDirty()` or `isEmpty()`.
+     *
+     * If a block with the same `kind` already exists it is replaced in-place;
+     * otherwise a new block is appended (or prepended if `position = 'start'`).
      *
-     * If a block with the same `kind` exists, it will be updated;
-     * otherwise a new block is inserted. `position` controls whether
-     * the insertion occurs at the document 'start' or 'end'.
+     * @param spec.kind     - Unique identifier, e.g. `'signature'` or `'footer'`.
+     * @param spec.html     - HTML content for the block. Sanitized before import.
+     * @param spec.position - Where to insert when creating: `'start'` | `'end'` (default `'end'`).
+     *
+     * @example
+     * editorRef.current?.upsertBlock({
+     *   kind: 'signature',
+     *   html: '<p><strong>Vikram Singh</strong></p><p>Senior Engineer</p>',
+     *   position: 'end',
+     * });
      */
     upsertBlock: (spec: BlockSpec) => void;
-    /** Remove a previously inserted block by its `kind` identifier. */
+    /**
+     * Remove a system block by its `kind` identifier.
+     *
+     * No-op if no block with that `kind` exists.
+     *
+     * @param kind - The same identifier used when calling `upsertBlock`.
+     *
+     * @example
+     * editorRef.current?.removeBlock('signature');
+     */
     removeBlock: (kind: string) => void;
-    /** Check whether a block with the given `kind` exists. */
+    /**
+     * Returns `true` if a system block with the given `kind` is present in the document.
+     *
+     * @example
+     * const hasSig = editorRef.current?.hasBlock('signature'); // true | false
+     */
     hasBlock: (kind: string) => boolean;
+    /**
+     * Returns `true` when the editor's user content differs from the clean baseline.
+     *
+     * **What counts as user content:**
+     * Text the user typed in paragraphs, headings, lists, etc., plus any media
+     * (images, YouTube embeds) inserted via the toolbar. System blocks added via
+     * `upsertBlock` are **excluded** from the comparison.
+     *
+     * **What is always `false` (clean):**
+     * - Empty editor (placeholder visible).
+     * - Editor containing only a default / pre-loaded value that has not been changed.
+     * - Editor cleared back to empty after the user had typed something.
+     *
+     * **Baseline:** captured automatically after the editor finishes loading its
+     * initial content. Call `markClean()` to reset it after a successful save.
+     *
+     * @example
+     * window.onbeforeunload = () => {
+     *   if (editorRef.current?.checkDirty()) return 'You have unsaved changes.';
+     * };
+     */
+    checkDirty: () => boolean;
+    /**
+     * Reset the dirty baseline to the editor's current content.
+     *
+     * Call this after successfully saving so that `checkDirty()` compares against
+     * the saved state going forward, rather than the original mount-time value.
+     *
+     * @example
+     * const html = editorRef.current?.getValue();
+     * await api.save(html);
+     * editorRef.current?.markClean(); // checkDirty() now returns false
+     */
+    markClean: () => void;
+};
+/**
+ * Built-in default messages used when no custom `validationMessages` entry is
+ * provided for that rule. Export this to inspect or copy individual defaults.
+ */
+declare const DEFAULT_VALIDATION_MESSAGES: {
+    readonly required: "This field is required.";
+    readonly minWords: (current: number, min: number) => string;
+    readonly maxWords: (current: number, max: number) => string;
+    readonly minChars: (current: number, min: number) => string;
+    readonly maxChars: (current: number, max: number) => string;
+    readonly noImages: "Images are not allowed in this field.";
+    readonly maxImages: (current: number, max: number) => string;
+    readonly noLinks: "Hyperlinks are not allowed in this field.";
+    readonly maxLinks: (current: number, max: number) => string;
+    readonly noTables: "Tables are not allowed in this field.";
+    readonly imageTooLarge: (fileMB: number, maxMB: number) => string;
+};
+/** A single active validation error on the editor. */
+type EditorValidationError = {
+    type: 'required' | 'minWords' | 'maxWords' | 'minChars' | 'maxChars' | 'noImages' | 'maxImages' | 'noLinks' | 'maxLinks' | 'noTables';
+    message: string;
+};
+/**
+ * Custom messages for each validation rule.
+ * Each entry accepts either a static string or a function that receives
+ * the relevant counts and returns a string.
+ */
+type ValidationMessages = {
+    /** Shown when the editor is empty and `required` is true. */
+    required?: string;
+    /** Shown when word count is below `minWords`. Receives (current, min). */
+    minWords?: string | ((current: number, min: number) => string);
+    /** Shown when word count exceeds `maxWords`. Receives (current, max). */
+    maxWords?: string | ((current: number, max: number) => string);
+    /** Shown when character count is below `minChars`. Receives (current, min). */
+    minChars?: string | ((current: number, min: number) => string);
+    /** Shown when character count exceeds `maxChars`. Receives (current, max). */
+    maxChars?: string | ((current: number, max: number) => string);
+    /** Shown when content contains images and `noImages` is true. */
+    noImages?: string;
+    /** Shown when image count exceeds `maxImages`. Receives (current, max). */
+    maxImages?: string | ((current: number, max: number) => string);
+    /** Shown when content contains links and `noLinks` is true. */
+    noLinks?: string;
+    /** Shown when link count exceeds `maxLinks`. Receives (current, max). */
+    maxLinks?: string | ((current: number, max: number) => string);
+    /** Shown when content contains tables and `noTables` is true. */
+    noTables?: string;
+    /** Shown in the image dialog when an uploaded file exceeds `maxImageSizeMB`. Receives (fileMB, maxMB). */
+    imageTooLarge?: string | ((fileMB: number, maxMB: number) => string);
 };
 interface ContentEditorProps {
     /** Optional editor namespace used by Lexical for scoping. */
@@ -142,6 +302,118 @@ interface ContentEditorProps {
     contentHeight?: string;
     /** Feature level controlling which toolbar groups are enabled. */
     level?: ContentEditorLevel;
+    /**
+     * Fully custom toolbar layout that overrides the `level` preset.
+     *
+     * Pass a 2-D array of **token strings**. Each inner array is rendered in order.
+     * Use `'|'` inside a group (including at the end) to render a divider.
+     * Every token renders as its own **standalone** control — there are no
+     * hidden dropdowns.  Items like `'Strikethrough'` or `'H1'` that were
+     * previously only reachable inside aggregate dropdowns can now be placed
+     * directly in the toolbar.  Unknown tokens are silently ignored.
+     *
+     * ---
+     * ### Text formatting (standalone toggle buttons)
+     *
+     * | Token            | What it renders                  |
+     * |------------------|----------------------------------|
+     * | `'Bold'`         | Bold toggle                      |
+     * | `'Italic'`       | Italic toggle                    |
+     * | `'Underline'`    | Underline toggle                 |
+     * | `'Strikethrough'`| Strikethrough toggle             |
+     * | `'Subscript'`    | Subscript toggle                 |
+     * | `'Superscript'`  | Superscript toggle               |
+     * | `'Highlight'`    | Highlight toggle                 |
+     * | `'Uppercase'`    | Uppercase transform toggle       |
+     * | `'Lowercase'`    | Lowercase transform toggle       |
+     * | `'Capitalize'`   | Capitalize transform toggle      |
+     *
+     * ### Lists (standalone toggle buttons)
+     *
+     * | Token               | What it renders          |
+     * |---------------------|--------------------------|
+     * | `'BulletList'`      | Unordered list toggle    |
+     * | `'NumberList'`      | Ordered list toggle      |
+     * | `'AlphabeticalList'`| Alphabetical list toggle |
+     *
+     * ### Block-level (standalone buttons)
+     *
+     * | Token        | What it renders                     |
+     * |--------------|-------------------------------------|
+     * | `'Quote'`    | Blockquote toggle                   |
+     * | `'PageBreak'`| Insert page-break                   |
+     *
+     * ### Heading levels (standalone toggle buttons)
+     *
+     * Clicking an active heading level reverts the block to normal paragraph.
+     *
+     * | Token | What it renders         |
+     * |-------|-------------------------|
+     * | `'H1'`| Heading 1 toggle button |
+     * | `'H2'`| Heading 2 toggle button |
+     * | `'H3'`| Heading 3 toggle button |
+     * | `'H4'`| Heading 4 toggle button |
+     * | `'H5'`| Heading 5 toggle button |
+     * | `'H6'`| Heading 6 toggle button |
+     *
+     * ### Dropdowns / rich plugins
+     *
+     * | Token           | What it renders                                   |
+     * |-----------------|---------------------------------------------------|
+     * | `'Heading'`     | Dropdown: Normal + H1–H6 (all heading levels)     |
+     * | `'Decorators'`  | Dropdown: all text / list / block decorator items |
+     * | `'Align'`       | Dropdown: left / center / right / justify         |
+     * | `'FontFamily'`  | Font-family dropdown                              |
+     * | `'FontSize'`    | Font-size dropdown                                |
+     * | `'ColorPicker'` | Text color picker                                 |
+     * | `'Link'`        | Insert / edit hyperlink                           |
+     * | `'Table'`       | Insert table                                      |
+     * | `'Image'`       | Upload block image                                |
+     * | `'InlineImage'` | Insert inline image                               |
+     * | `'Youtube'`     | Embed YouTube video                               |
+     * | `'|'`           | Inline divider within a group                     |
+     *
+     * ---
+     * ### Examples
+     *
+     * **Only bold, italic, underline and strikethrough as standalone buttons:**
+     * ```tsx
+     * customToolbar={[['Bold', 'Italic', 'Underline', 'Strikethrough']]}
+     * ```
+     *
+     * **Pick specific heading levels without a dropdown:**
+     * ```tsx
+     * customToolbar={[['H1', 'H2', 'H3'], ['Bold', 'Italic']]}
+     * ```
+     *
+     * **Mix standalone items and aggregate dropdowns:**
+     * ```tsx
+     * customToolbar={[
+     *   ['Bold', 'Italic', 'Underline', 'Strikethrough', 'Highlight'],
+     *   ['BulletList', 'NumberList'],
+     *   ['H1', 'H2', 'H3'],
+     *   ['Link', 'Image'],
+     * ]}
+     * ```
+     *
+     * **Full toolbar using aggregate dropdowns:**
+     * ```tsx
+     * customToolbar={[
+     *   ['Heading', 'FontFamily', 'FontSize'],
+     *   ['Bold', 'Italic', 'Underline', '|', 'ColorPicker'],
+     *   ['Align'],
+     *   ['Link', 'Image', 'InlineImage', 'Youtube', 'Table'],
+     *   ['Decorators'],
+     * ]}
+     * ```
+     *
+     * ---
+     * ### Notes
+     * - When `customToolbar` is set the `level` prop has no effect.
+     * - Token order within each group is preserved exactly as written.
+     * - Avoid duplicate tokens in the same render (each renders once per occurrence).
+     */
+    customToolbar?: string[][];
     /**
      * @deprecated Not used by the component. Prefer styling overrides instead.
      */
@@ -260,64 +532,92 @@ interface ContentEditorProps {
     spellCheckEnabled?: boolean;
     /** When true, shows the floating formatting toolbar near text selections. */
     showFloatingToolbar?: boolean;
-    /** Maximum words allowed. Shows a live counter; turns red when exceeded. */
+    /**
+     * Maximum word count allowed. When set, a live counter is shown
+     * below the editor. Exceeding the limit turns the counter red.
+     * Example: wordLimit={500}
+     */
     wordLimit?: number;
-    /** Minimum words required. Error shown after blur if not met. */
-    minWords?: number;
-    /** Maximum characters allowed. Error shown when exceeded. */
-    maxChars?: number;
-    /** Minimum characters required. Error shown after blur if not met. */
-    minChars?: number;
-    /** When true, shows a required-field error after blur if the editor is empty. */
-    required?: boolean;
     /**
      * Fires when the content crosses the configured word limit boundary.
-     * exceeded: true → user just exceeded; false → came back within limit.
+     *
+     * - exceeded: true  -> user just exceeded the limit
+     * - exceeded: false -> user came back within the limit
      */
     onWordLimitExceeded?: (info: {
         wordCount: number;
         wordLimit: number;
         exceeded: boolean;
     }) => void;
+    /** When true, the editor must not be empty. Equivalent to `minWords: 1`. */
+    required?: boolean;
+    /** Minimum number of words required. */
+    minWords?: number;
+    /** Maximum number of words allowed. Shows a validation error when exceeded. */
+    maxWords?: number;
+    /** Minimum number of characters required. */
+    minChars?: number;
+    /** Maximum number of characters allowed. Shows a validation error when exceeded. */
+    maxChars?: number;
+    /** When true, the editor must not contain any images. */
+    noImages?: boolean;
+    /** Maximum number of images allowed in the content. */
+    maxImages?: number;
+    /** When true, the editor must not contain any hyperlinks. */
+    noLinks?: boolean;
+    /** Maximum number of hyperlinks allowed in the content. */
+    maxLinks?: number;
+    /** When true, the editor must not contain any tables. */
+    noTables?: boolean;
     /**
-     * Extra error messages to display (on top of any built-in validation).
-     * Use this for errors that originate outside the editor (e.g. file too large,
-     * subject empty, API failure).
-     *
-     * Example: errors={['Attachment exceeds 5 MB', 'Subject is required']}
+     * Maximum image file size in megabytes. When set, the image upload dialogs
+     * reject files that are larger and display an error inside the dialog.
      */
-    errors?: string[];
+    maxImageSizeMB?: number;
     /**
-     * Override the text of any built-in validation message.
-     * Every key accepts a plain string OR a function receiving the live counts.
-     *
-     * Covered errors:
-     * - wordLimitExceeded  — fires when wordCount > wordLimit
-     * - required           — fires on blur when editor is empty and required=true
-     * - minWords           — fires on blur when wordCount < minWords
-     * - maxCharsExceeded   — fires when charCount > maxChars
-     * - minCharsRequired   — fires on blur when charCount < minChars
+     * Override the default error messages shown for each validation rule.
+     * Accepts static strings or functions for dynamic messages.
+     */
+    validationMessages?: ValidationMessages;
+    /**
+     * Called whenever the set of active validation errors changes.
+     * Receives the current array of errors (empty array means valid).
+     */
+    onValidationChange?: (errors: EditorValidationError[]) => void;
+    /**
+     * Pass any string here to display it as a custom error message below the
+     * editor and turn the border red. Useful for server-side or form-level
+     * errors that live outside the component's own validation rules.
      *
      * Example:
      * ```tsx
-     * errorMessages={{
-     *   wordLimitExceeded: (count, limit) => `Too long — ${count}/${limit} words used.`,
-     *   required: 'Email body cannot be empty.',
-     *   minWords: (count, min) => `Write at least ${min} words (${count} so far).`,
-     *   maxCharsExceeded: (count, max) => `${count}/${max} characters — please shorten.`,
-     *   minCharsRequired: (count, min) => `At least ${min} characters needed (${count} entered).`,
-     * }}
+     * errorMessage={submitFailed ? 'Please fill in the email body before sending.' : undefined}
      * ```
      */
-    errorMessages?: {
-        wordLimitExceeded?: string | ((wordCount: number, wordLimit: number) => string);
-        required?: string;
-        minWords?: string | ((wordCount: number, minWords: number) => string);
-        maxCharsExceeded?: string | ((charCount: number, maxChars: number) => string);
-        minCharsRequired?: string | ((charCount: number, minChars: number) => string);
-    };
+    errorMessage?: string;
+    /**
+     * Called once before `LexicalComposer` is initialized.
+     *
+     * Receives the `InitialConfigType` object that will be passed to
+     * `LexicalComposer`. You may mutate it (e.g. add custom nodes, override the
+     * theme or namespace) — Lexical reads this config only once on mount, so
+     * this is the only safe window to modify it.
+     *
+     * Note: called only on the initial mount, never on re-renders.
+     */
+    onBeforeInitialize?: (config: InitialConfigType) => void;
+    /**
+     * Called once when the Lexical editor instance is ready for use.
+     *
+     * Receives the live `LexicalEditor` instance. Use it for operations that
+     * require the editor to be mounted — programmatic focus, registering
+     * external commands, or handing the instance to an external controller.
+     *
+     * Note: called only once on mount, never on re-renders.
+     */
+    onReady?: (editor: LexicalEditor) => void;
 }
 
 declare const ContentEditorComponent: React.ForwardRefExoticComponent<ContentEditorProps & React.RefAttributes<ContentEditorRef>>;
 
-export { type AcceptMethod, ContentEditorComponent, ContentEditorLevel, type ContentEditorProps, type ContentEditorRef, type SearchPromise, type SpellCheckIssue, type SpellCheckPayload, type SpellCheckResult };
+export { type AcceptMethod, ContentEditorComponent, ContentEditorLevel, type ContentEditorProps, type ContentEditorRef, DEFAULT_VALIDATION_MESSAGES, type EditorValidationError, type SearchPromise, type SpellCheckIssue, type SpellCheckPayload, type SpellCheckResult, type ValidationMessages };