@mdaemon/html-editor 1.2.1 → 1.4.0

package/README.md

@@ -75,6 +75,8 @@ const editor = new HTMLEditor(container, {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `basicEditor` | boolean | false | Use simplified toolbar for notes/tasks |
+| `readonly` | boolean | false | Start the editor in read-only mode (see `setReadOnly`) |
+| `forced_root_block` | 'p' \| 'div' | 'p' | Block element produced on Enter. `'div'` gives CKEditor `ENTER_DIV` parity |
 | `includeTemplates` | boolean | false | Show template dropdown |
 | `templates` | Template[] | [] | Array of templates |
 | `dropbox` | boolean | false | Enable Dropbox integration |
@@ -83,8 +85,15 @@ const editor = new HTMLEditor(container, {
 | `images_upload_base_path` | string | '/' | Base path prefix for uploaded image URLs |
 | `images_upload_max_size` | number | 10485760 | Maximum upload file size in bytes (default 10 MB) |
 | `images_upload_headers` | Record\<string, string\> | - | Custom HTTP headers for upload requests |
+| `images_file_types` | string | *(permissive)* | Comma/space-separated accepted extensions (e.g. `'jpg,jpeg,png,gif,bmp'`). Restricts uploads when set |
+| `images_upload_validate` | (file: File) => string \| null | - | Pre-upload hook; return a message to reject the file, or null to allow |
+| `images_upload_error` | (message: string) => void | - | Caller-supplied alert for drag-drop/paste upload rejections & failures (no dialog to show errors in) |
 | `font_family_formats` | string | *(TinyMCE defaults)* | Semicolon-separated font list (`Name=family,...`) |
 | `font_size_formats` | string | '8pt 9pt 10pt 12pt 14pt 18pt 24pt 36pt' | Space-separated font sizes |
+| `font_names` | string | - | CKEditor alias for `font_family_formats` |
+| `fontSize_sizes` | string | - | CKEditor alias for `font_size_formats` |
+| `block_formats` | string | 'Paragraph=p;Heading 1=h1;…' | Block-format dropdown definitions (`blocks` button) |
+| `style_formats` | StyleFormat[] | *(subset)* | Named styles for the Styles dropdown (`styles` button) |
 | `fontName` | string | - | Default font family |
 | `fontSize` | string | - | Default font size |
 | `directionality` | 'ltr' \| 'rtl' | 'ltr' | Text direction |
@@ -104,6 +113,7 @@ const editor = new HTMLEditor(container, {
 | `convert_unsafe_embeds` | boolean | true | Sanitize embedded content |
 | `format_empty_lines` | boolean | true | Format empty lines |
 | `paste_from_office` | boolean | true | Clean and preserve formatting when pasting from Microsoft Word and Excel |
+| `speech_to_text` | boolean | true | Enable Speech to Text and Dictate toolbar buttons (requires Web Speech API: Chrome, Edge, Safari) |
 | `setup` | (editor) => void | - | Callback invoked before init — use to register custom buttons |
 
 ### Toolbar Toggle
@@ -131,6 +141,8 @@ If your custom toolbar string contains no `||`, all buttons render in a single f
 - `execCommand(cmd: string, ui?: boolean, value?: any): boolean` - Execute editor command
 - `isDirty(): boolean` - Check if content has changed
 - `setDirty(state: boolean): void` - Set dirty state
+- `setReadOnly(state: boolean): void` - Toggle read-only mode (disables editing and dims the toolbar)
+- `isReadOnly(): boolean` - Check if the editor is read-only
 - `focus(): void` - Focus the editor
 - `hasFocus(): boolean` - Check if editor has focus
 - `setLanguage(code: string): void` - Change UI language at runtime (rebuilds toolbar)
@@ -229,6 +241,8 @@ All built-in toolbar button names that can be used in the `toolbar` config strin
 | `italic` | Toggle italic |
 | `underline` | Toggle underline |
 | `strikethrough` | Toggle strikethrough |
+| `subscript` | Toggle subscript |
+| `superscript` | Toggle superscript |
 | `bullist` | Toggle bullet list |
 | `numlist` | Toggle numbered list |
 | `outdent` | Decrease indent |
@@ -237,6 +251,10 @@ All built-in toolbar button names that can be used in the `toolbar` config strin
 | `fontfamily` | Font family dropdown |
 | `fontsize` | Font size dropdown |
 | `lineheight` | Line height dropdown (1, 1.2, 1.4, 1.6, 2) |
+| `blocks` | Block format dropdown (Paragraph, Heading 1–6; alias `formatselect`) |
+| `styles` | Named styles dropdown (configurable via `style_formats`) |
+| `table` | Table dropdown (insert table + row/column/cell operations) |
+| `hr` | Insert horizontal rule |
 | `template` | Template dropdown (requires `includeTemplates: true`) |
 | `alignleft` | Align left |
 | `aligncenter` | Align center |
@@ -255,10 +273,14 @@ All built-in toolbar button names that can be used in the `toolbar` config strin
 | `emoticons` | Emoji picker with search (smileys, gestures, hearts, objects, symbols, arrows) |
 | `code` | Open HTML source code editor dialog |
 | `link` | Open Insert/Edit Link dialog |
+| `unlink` | Remove the link at the cursor |
+| `anchor` | Insert a named anchor (`<a id>` target) |
 | `codesample` | Toggle code sample block |
 | `fullscreen` | Toggle fullscreen editing mode |
 | `preview` | Open content preview in a new window |
 | `searchreplace` | Open Find & Replace dialog |
+| `speechtotext` | Open Speech to Text dialog (browser support required) |
+| `dictate` | Toggle inline dictation — inserts speech directly at cursor (browser support required) |
 | `ltr` | Set text direction to left-to-right |
 | `rtl` | Set text direction to right-to-left |
 
@@ -267,13 +289,13 @@ All built-in toolbar button names that can be used in the `toolbar` config strin
 **Full toolbar** (default when `basicEditor: false`):
 
 ```
-bold italic underline strikethrough | bullist numlist outdent indent blockquote | fontfamily fontsize || lineheight alignleft aligncenter alignright alignjustify | forecolor backcolor | removeformat copy cut paste | undo redo | image charmap emoticons | fullscreen preview | code link codesample | ltr rtl | searchreplace
+bold italic underline strikethrough subscript superscript | blocks styles | bullist numlist outdent indent blockquote | fontfamily fontsize | lineheight alignleft aligncenter alignright alignjustify | forecolor backcolor | removeformat copy cut paste | undo redo | image table charmap emoticons hr | fullscreen preview | code link unlink anchor codesample | ltr rtl | searchreplace
 ```
 
 **Basic toolbar** (when `basicEditor: true`):
 
 ```
-bold italic underline strikethrough | bullist numlist outdent indent | fontfamily fontsize blockquote || lineheight alignleft aligncenter alignright alignjustify | forecolor backcolor | removeformat copy cut paste | undo redo | charmap emoticons | link | ltr rtl | searchreplace
+bold italic underline strikethrough subscript superscript | bullist numlist outdent indent | fontfamily fontsize blockquote | lineheight alignleft aligncenter alignright alignjustify | forecolor backcolor | removeformat copy cut paste | undo redo | charmap emoticons | link unlink | ltr rtl | searchreplace
 ```
 
 ## Image Upload
@@ -299,6 +321,25 @@ const editor = new HTMLEditor(container, {
 });
 ```
 
+### Restricting file types and rejecting uploads
+
+`images_file_types` restricts which extensions are accepted (matched against the
+file name, falling back to MIME for clipboard pastes that have no name). The
+`images_upload_validate` hook runs before every upload — return a message to
+reject the file. For drag-drop and clipboard-paste uploads there is no dialog to
+show the message in, so rejections and failures are routed to `images_upload_error`
+(supply your own alert/notification — the CKEditor `simpleuploads` `newAlert` flow).
+
+```typescript
+const editor = new HTMLEditor(container, {
+  images_upload_url: '/api/upload',
+  images_file_types: 'jpg,jpeg,png,gif,bmp', // CKEditor simpleuploads parity
+  images_upload_validate: (file) =>
+    file.size === 0 ? 'Empty files are not allowed' : null,
+  images_upload_error: (message) => myApp.showAlert(message),
+});
+```
+
 ## Source Code Editor
 
 The `code` toolbar button opens a modal dialog for viewing and editing the raw HTML source of the editor content. The dialog features a full-size monospace textarea with the current HTML, **Cancel** and **Save** buttons, and supports Escape to close and Tab to indent.
@@ -314,7 +355,69 @@ The `link` toolbar button opens a modal dialog for inserting or editing hyperlin
 - **Title** — the HTML `title` attribute (shown as a tooltip on hover)
 - **Open link in…** — dropdown to choose between _Current window_ or _New window_ (`target="_blank"`)
 
-When editing an existing link, all fields are pre-populated from the current link attributes. Clearing the URL and saving removes the link. The dialog inherits the active skin theme.
+When editing an existing link, all fields are pre-populated from the current link attributes. Clearing the URL and saving removes the link. The dialog inherits the active skin theme. The separate `unlink` toolbar button removes the link at the cursor without opening the dialog.
+
+## Named Anchors
+
+The `anchor` toolbar button opens a dialog to insert a named anchor — an `<a id="name">` target for in-page linking. The anchor name is required and may not contain spaces. Existing anchors in loaded content (`<a id>` with no `href`) are preserved through the editor's parse/serialize cycle.
+
+```typescript
+// Programmatic insertion via the TipTap command:
+editor.getTipTap()?.commands.setAnchor('section-1');
+```
+
+## Tables
+
+The `table` toolbar button is a dropdown that inserts a table and edits the one under the cursor:
+
+- **Insert table** — inserts a 3×3 table with a header row.
+- **Insert/delete row**, **Insert/delete column**, **Merge cells**, **Split cell**, **Toggle header row**, **Delete table**.
+
+Tables are resizable by dragging column borders.
+
+## Block & Style Formats
+
+- The `blocks` button (alias `formatselect`) is a block-format dropdown — Paragraph and Heading 1–6 by default. Customize it with `block_formats` (TinyMCE syntax):
+
+  ```typescript
+  const editor = new HTMLEditor(container, {
+    block_formats: 'Paragraph=p;Title=h1;Subtitle=h2',
+  });
+  ```
+
+- The `styles` button is a named-styles dropdown driven by `style_formats` (CKEditor `stylesSet`-compatible). Each entry applies a block element and/or inline color/background/class to the selection:
+
+  ```typescript
+  const editor = new HTMLEditor(container, {
+    style_formats: [
+      { title: 'Blue Title', block: 'h3', styles: { color: 'Blue' } },
+      { title: 'Marker', inline: 'span', styles: { 'background-color': 'Yellow' } },
+      { title: 'Callout', inline: 'span', classes: 'callout' },
+    ],
+  });
+  ```
+
+  > Note: block elements map to headings/paragraph, `color`/`background-color` map to the editor's text-color/highlight marks, and `classes` apply a CSS class to the selection. Arbitrary element wrapping from CKEditor's stylesSet (e.g. `big`, `tt`, `cite`) is not supported by the underlying TipTap schema.
+
+## Read-Only Mode
+
+Start the editor read-only with `readonly: true`, or toggle it at runtime. Read-only mode disables editing and dims/blocks the toolbar.
+
+```typescript
+const editor = new HTMLEditor(container, { readonly: true });
+
+editor.setReadOnly(false); // make editable
+editor.setReadOnly(true);  // back to read-only
+console.log(editor.isReadOnly());
+```
+
+## Enter Behavior (`forced_root_block`)
+
+By default, pressing Enter creates a new `<p>` block. Set `forced_root_block: 'div'` for CKEditor `ENTER_DIV` parity, so new blocks (and the serialized output) use `<div>` instead. The `<div id="signature">` signature block is still preserved in either mode.
+
+```typescript
+const editor = new HTMLEditor(container, { forced_root_block: 'div' });
+```
 
 ## Search & Replace
 

package/dist/index.d.ts

@@ -2,6 +2,34 @@ import { Editor } from '@tiptap/core';
 import { Extension } from '@tiptap/core';
 import { Node as Node_2 } from '@tiptap/core';
 
+export declare const Anchor: Node_2<AnchorOptions, any>;
+
+export declare class AnchorDialog {
+    private options;
+    private overlay;
+    private dialog;
+    private nameInput;
+    private errorEl;
+    constructor(options: AnchorDialogOptions);
+    private get tiptap();
+    open(): void;
+    close(): void;
+    private clearError;
+    private showError;
+    private save;
+    private createDialog;
+    destroy(): void;
+}
+
+export declare interface AnchorDialogOptions {
+    editor: HTMLEditor;
+    trans: (key: string) => string;
+}
+
+export declare interface AnchorOptions {
+    HTMLAttributes: Record<string, unknown>;
+}
+
 /** List of all supported locale codes */
 export declare const availableLocales: string[];
 
@@ -75,6 +103,37 @@ export declare function createTranslateFunction(code: string): TranslateFunction
  */
 export declare const DEFAULT_ICONS: IconSet;
 
+export declare class Dictation {
+    private options;
+    private recognition;
+    private _isActive;
+    private restartTimer;
+    private interimStart;
+    private interimLength;
+    constructor(options: DictationOptions);
+    get isActive(): boolean;
+    toggle(): void;
+    start(): void;
+    stop(): void;
+    destroy(): void;
+    private getSpeechLang;
+    private handleResult;
+    /** Replace the current interim text in the editor with new interim text */
+    private replaceInterim;
+    /** Remove interim text without inserting anything */
+    private clearInterim;
+    private needsLeadingSpace;
+    private handleError;
+    private handleEnd;
+}
+
+export declare interface DictationOptions {
+    editor: HTMLEditor;
+    trans: (key: string) => string;
+    /** Called when dictation starts or stops so the toolbar can update the button state */
+    onStateChange?: (isActive: boolean) => void;
+}
+
 declare type DirtyCallback = (dirty: boolean) => void;
 
 /**
@@ -106,6 +165,13 @@ export declare interface DropboxFile {
  */
 export declare interface EditorConfig {
     basicEditor?: boolean;
+    /** Start the editor in read-only mode. */
+    readonly?: boolean;
+    /**
+     * Root block element produced when the user presses Enter.
+     * 'p' (default) emits <p>; 'div' emits <div> (CKEditor ENTER_DIV parity).
+     */
+    forced_root_block?: 'p' | 'div';
     includeTemplates?: boolean;
     templates?: Template[];
     dropbox?: boolean;
@@ -114,10 +180,36 @@ export declare interface EditorConfig {
     images_upload_base_path?: string;
     images_upload_max_size?: number;
     images_upload_headers?: Record<string, string>;
+    /**
+     * Comma- or space-separated list of accepted image file extensions
+     * (e.g. 'jpg,jpeg,png,gif,bmp'). When set, restricts uploads to these
+     * types. When omitted, the default permissive set is used.
+     */
+    images_file_types?: string;
+    /**
+     * Optional validation hook run before an image upload starts. Return a
+     * non-null string to reject the file (the string is shown via
+     * images_upload_error / the dialog). Return null to allow.
+     */
+    images_upload_validate?: (file: File) => string | null;
+    /**
+     * Caller-supplied alert/notification used to report upload rejections and
+     * failures from drag-drop / paste (which have no dialog to show errors in).
+     * Mirrors the CKEditor simpleuploads newAlert flow.
+     */
+    images_upload_error?: (message: string) => void;
     font_family_formats?: string;
     font_size_formats?: string;
+    /** CKEditor alias for font_size_formats (space-separated sizes). */
+    fontSize_sizes?: string;
+    /** CKEditor alias for font_family_formats (semicolon list). */
+    font_names?: string;
     fontName?: string;
     fontSize?: string;
+    /** Block format dropdown definitions, TinyMCE-style 'Paragraph=p;Heading 1=h1;...'. */
+    block_formats?: string;
+    /** Named style definitions for the Styles dropdown (CKEditor stylesSet-compatible). */
+    style_formats?: StyleFormat[];
     directionality?: 'ltr' | 'rtl';
     language?: string;
     height?: string | number;
@@ -139,6 +231,7 @@ export declare interface EditorConfig {
     quickbars_image_toolbar?: boolean;
     quickbars_insert_toolbar?: boolean;
     paste_from_office?: boolean;
+    speech_to_text?: boolean;
     browser_spellcheck?: boolean;
     elementpath?: boolean;
     entity_encoding?: 'raw' | 'named' | 'numeric';
@@ -269,6 +362,12 @@ export declare class HTMLEditor implements MDHTMLEditor {
     execCommand(command: string, _ui?: boolean, value?: unknown): boolean;
     isDirty(): boolean;
     setDirty(state: boolean): void;
+    /**
+     * Toggle read-only mode. Disables editing and dims the toolbar.
+     * Mirrors CKEditor's editor.setReadOnly(bool).
+     */
+    setReadOnly(state: boolean): void;
+    isReadOnly(): boolean;
     focus(): void;
     hasFocus(): boolean;
     on<K extends keyof EditorEventMap>(event: K, callback: EditorEventMap[K]): void;
@@ -316,6 +415,17 @@ export declare interface ImageUploadResult {
  */
 declare type InitCallback = (editor: MDHTMLEditor) => void;
 
+export declare const InlineStyle: Extension<InlineStyleOptions, any>;
+
+export declare interface InlineStyleOptions {
+    types: string[];
+}
+
+/**
+ * Check if the Web Speech API is available in the current browser
+ */
+export declare function isSpeechRecognitionSupported(): boolean;
+
 export declare type LanguageChangeCallback = (code: string) => void;
 
 export declare const LineHeight: Extension<LineHeightOptions, any>;
@@ -362,6 +472,8 @@ export declare interface MDHTMLEditor {
     execCommand(command: string, ui?: boolean, value?: unknown): boolean;
     isDirty(): boolean;
     setDirty(state: boolean): void;
+    setReadOnly(state: boolean): void;
+    isReadOnly(): boolean;
     focus(): void;
     hasFocus(): boolean;
     on<K extends keyof EditorEventMap>(event: K, callback: EditorEventMap[K]): void;
@@ -461,6 +573,73 @@ export declare interface SourceEditorOptions {
     trans: (key: string) => string;
 }
 
+export declare class SpeechToText {
+    private options;
+    private overlay;
+    private dialog;
+    private recognition;
+    private isListening;
+    private finalTranscript;
+    private interimTranscript;
+    private lastConfidence;
+    private restartTimer;
+    private transcriptArea;
+    private confidenceEl;
+    private statusEl;
+    private startStopBtn;
+    private insertBtn;
+    private clearBtn;
+    private languageSelect;
+    constructor(options: SpeechToTextOptions);
+    open(): void;
+    close(): void;
+    destroy(): void;
+    private get editorLanguage();
+    private getDefaultSpeechLang;
+    private createDialog;
+    private toggleRecognition;
+    private startRecognition;
+    private handleResult;
+    private handleError;
+    private handleEnd;
+    private stopRecognition;
+    private updateButtonState;
+    private setStatus;
+    private updateTranscriptDisplay;
+    private updateConfidenceDisplay;
+    private insertTranscript;
+    private clearTranscript;
+    private escapeHtml;
+}
+
+export declare interface SpeechToTextOptions {
+    editor: HTMLEditor;
+    trans: (key: string) => string;
+}
+
+/**
+ * Named style definition for the Styles dropdown.
+ * CKEditor stylesSet-compatible shape. Either `inline` or `block` identifies
+ * how the style is applied; `element` is the legacy/CKEditor tag name and is
+ * treated as inline unless `block` is set.
+ */
+export declare interface StyleFormat {
+    /** Display name in the Styles dropdown. */
+    title: string;
+    /** Inline element to apply (e.g. 'span'). */
+    inline?: string;
+    /** Block element to apply (e.g. 'h3', 'p'). */
+    block?: string;
+    /** CKEditor-style element name (mapped to inline unless block is set). */
+    element?: string;
+    /** Inline CSS styles to apply (e.g. { color: 'Blue' }). */
+    styles?: Record<string, string>;
+    /** Space-separated CSS class names to apply. */
+    classes?: string;
+    /** HTML attributes to apply (e.g. { dir: 'rtl' }). */
+    attributes?: Record<string, string>;
+}
+
 /**
  * Template object for email templates
  */
@@ -493,6 +672,9 @@ export declare class Toolbar {
     private searchReplace;
     private sourceEditor;
     private linkEditor;
+    private anchorDialog;
+    private speechToText;
+    private dictation;
     private updateInterval;
     private boundClickHandler;
     private boundKeydownHandler;
@@ -520,6 +702,17 @@ export declare class Toolbar {
     private createFontSizeDropdown;
     private createLineHeightDropdown;
     private createTemplateDropdown;
+    private createFormatDropdown;
+    private getStyleFormats;
+    private createStylesDropdown;
+    /**
+     * Apply a StyleFormat to the current selection. Block elements map to
+     * heading/paragraph; color and background map to the existing Color /
+     * Highlight marks; classes map to the InlineStyle textStyle class.
+     * (Arbitrary element wrapping from CKEditor stylesSet is not supported.)
+     */
+    private applyStyleFormat;
+    private createTableDropdown;
     /**
      * Position a fixed-position menu below its trigger button.
      * Uses getBoundingClientRect so the menu escapes any overflow:hidden ancestor.
@@ -534,9 +727,17 @@ export declare class Toolbar {
     private updateButtonStates;
     private openImageDialog;
     private openLinkDialog;
+    private openAnchorDialog;
+    /**
+     * Enable or disable the whole toolbar (used for read-only mode).
+     * Blocks pointer interaction and dims the toolbar via CSS.
+     */
+    setEnabled(enabled: boolean): void;
     private openCharMap;
     private openEmojiPicker;
     private openSearchReplace;
+    private openSpeechToText;
+    private toggleDictation;
     private openSourceCode;
     private openPreview;
     private toggleFullscreen;
@@ -641,3 +842,25 @@ declare module '@tiptap/core' {
         };
     }
 }
+
+
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        anchor: {
+            /** Insert a named anchor at the cursor. */
+            setAnchor: (name: string) => ReturnType;
+        };
+    }
+}
+
+
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        inlineStyle: {
+            /** Apply a CSS class to the current selection via the textStyle mark. */
+            setInlineClass: (className: string) => ReturnType;
+            /** Remove the textStyle class. */
+            unsetInlineClass: () => ReturnType;
+        };
+    }
+}