@domternal/react 0.6.2 → 0.7.1

package/README.md

@@ -3,29 +3,31 @@
 [![Version](https://img.shields.io/npm/v/@domternal/react.svg)](https://www.npmjs.com/package/@domternal/react)
 [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/domternal/domternal/blob/main/LICENSE)
 
-A lightweight, extensible rich text editor toolkit built on <u>[ProseMirror](https://prosemirror.net/)</u>. Framework-agnostic headless core with first-class Angular, React, and Vue support.  
+A lightweight, extensible rich text editor toolkit built on <u>[ProseMirror](https://prosemirror.net/)</u>. Framework-agnostic headless core with first-class Angular, React, Vue, and Vanilla wrappers.
 Use it headless with vanilla JS/TS, add the built-in toolbar and theme, or drop in ready-made framework components. Fully tree-shakeable, import only what you use, unused extensions are stripped from your bundle.
 
 ## Links
 
-<u>[Website](https://domternal.dev)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[Documentation](https://domternal.dev/v1/introduction)</u>  
-<u>[StackBlitz (Angular)](https://stackblitz.com/edit/domternal-angular-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (React)](https://stackblitz.com/edit/domternal-react-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (Vue)](https://stackblitz.com/edit/domternal-vue-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (Vanilla TS)](https://stackblitz.com/edit/domternal-vanilla-full-example)</u> 
+<u>[Website](https://domternal.dev)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[Documentation](https://domternal.dev/v1/introduction)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp;
+<u>[StackBlitz (Angular)](https://stackblitz.com/edit/domternal-angular-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (React)](https://stackblitz.com/edit/domternal-react-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (Vue)](https://stackblitz.com/edit/domternal-vue-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (Vanilla TS)](https://stackblitz.com/edit/domternal-vanilla-full-example)</u>
 
 ## Features
 
 See <u>[Packages & Bundle Size](https://domternal.dev/v1/packages)</u> for a full breakdown of all packages and what each one includes.
 
 - **Headless core** - use with any framework or vanilla JS/TS
-- **Angular components** - editor, toolbar, bubble menu, floating menu, emoji picker (signals, OnPush, zoneless-ready)
-- **React components** - composable `Domternal` component, toolbar, bubble menu, floating menu, emoji picker, custom node views (React 18+)
-- **Vue components** - composable `Domternal` component, `useEditor`/`useEditorState` composables, toolbar, bubble menu, floating menu, emoji picker, custom node views (Vue 3.3+)
-- **57 extensions across 12 packages** - 23 nodes, 9 marks, and 25 behavior extensions
-- **140+ chainable commands** - `editor.chain().focus().toggleBold().run()`
+- **Angular components** - editor, toolbar, bubble menu, floating menu, emoji picker, notion color picker (signals, OnPush, zoneless-ready)
+- **React components** - composable `Domternal` component, toolbar, bubble menu, floating menu, emoji picker, notion color picker, custom node views (React 18+)
+- **Vue components** - composable `Domternal` component, `useEditor`/`useEditorState` composables, toolbar, bubble menu, floating menu, emoji picker, notion color picker, custom node views (Vue 3.3+)
+- **Vanilla wrapper** - framework-free class-based API for Astro, Svelte, Solid, plain HTML, and Web Components - editor, toolbar, bubble menu, floating menu, emoji picker, notion color picker
+- **Notion-style block UX** - drag-to-reorder, block context menu, slash command, smart paste, keyboard reorder, floating Table of Contents
+- **65+ extensions across 15 packages** - nodes, marks, and behavior extensions
+- **120+ chainable commands** - `editor.chain().focus().toggleBold().run()`
 - **Full table support** - cell merging, column resize, row/column controls, cell toolbar, all free and MIT licensed
 - **Tree-shakeable** - import only what you use, your bundler strips the rest
-- **~38 KB gzipped** (own code), <u>[~108 KB total](https://domternal.dev/v1/packages)</u> with ProseMirror
+- **~44 KB gzipped** (own code), <u>[see Packages](https://domternal.dev/v1/packages)</u> for full bundle breakdown with ProseMirror
 - **TypeScript first** - 100% typed, zero `any`
-- **8,500+ tests** - 2,677 unit tests and 5,800+ E2E tests across 120+ Playwright specs
+- **15,000+ tests** - 4,000+ unit and 11,000+ E2E across 230+ Playwright specs and 4 demo apps
 - **Light and dark theme** - 70+ CSS custom properties for full visual control
 - **Inline styles export** - `getHTML({ styled: true })` produces inline CSS ready for email clients, CMS, and Google Docs
 - **SSR helpers** - `generateHTML`, `generateJSON`, `generateText` for server-side rendering

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as react from 'react';
-import { DependencyList, ReactNode, HTMLAttributes, Ref, ElementType, RefCallback } from 'react';
-import { AnyExtension, Content, FocusPosition, Editor, JSONContent, IconSet, ToolbarLayoutEntry, BubbleMenuOptions, FloatingMenuOptions } from '@domternal/core';
+import { DependencyList, ReactNode, HTMLAttributes, Ref, RefObject, KeyboardEvent, ElementType, RefCallback } from 'react';
+import { AnyExtension, Content, FocusPosition, Editor, JSONContent, IconSet, ToolbarLayoutEntry, BubbleMenuOptions, FloatingMenuItemsOverride } from '@domternal/core';
 export { AnyExtension, Content, Editor, FocusPosition, GenerateHTMLOptions, GenerateJSONOptions, GenerateTextOptions, JSONContent, generateHTML, generateJSON, generateText } from '@domternal/core';
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import { FloatingMenuOptions, FloatingMenuKeymap } from '@domternal/extension-block-menu';
 
 declare const DEFAULT_EXTENSIONS: AnyExtension[];
 interface UseEditorOptions {
@@ -75,10 +75,11 @@ interface UseEditorOptions {
  * // Editor is recreated when locale changes
  * ```
  */
-declare function useEditor(options?: UseEditorOptions, deps?: DependencyList): {
+interface UseEditorResult {
     editor: Editor | null;
-    editorRef: react.RefObject<HTMLDivElement | null>;
-};
+    editorRef: React.RefObject<HTMLDivElement | null>;
+}
+declare function useEditor(options?: UseEditorOptions, deps?: DependencyList): UseEditorResult;
 
 /**
  * Full editor state returned when no selector is provided.
@@ -132,12 +133,10 @@ interface EditorProviderProps {
  * </EditorProvider>
  * ```
  */
-declare function EditorProvider({ editor, children }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+declare function EditorProvider({ editor, children }: EditorProviderProps): ReactNode;
 /**
  * Access the editor instance from the nearest EditorProvider.
- *
- * @returns `{ editor }` where editor may be null if the provider has no editor yet.
- * @throws If used outside of an EditorProvider (optional - returns null editor instead).
+ * Returns `{ editor: null }` when used outside a provider, no throw.
  */
 declare function useCurrentEditor(): EditorContextValue;
 
@@ -149,7 +148,7 @@ interface DomternalToolbarProps {
     /** Custom toolbar layout. */
     layout?: ToolbarLayoutEntry[];
 }
-declare function DomternalToolbar({ editor: editorProp, icons, layout }: DomternalToolbarProps): react_jsx_runtime.JSX.Element | null;
+declare function DomternalToolbar({ editor: editorProp, icons, layout }: DomternalToolbarProps): ReactNode;
 
 interface DomternalBubbleMenuProps {
     /** The editor instance. If omitted, uses EditorProvider context. */
@@ -166,22 +165,45 @@ interface DomternalBubbleMenuProps {
     items?: string[];
     /** Context-aware: map context names to item arrays, true for all, or null to disable. */
     contexts?: Record<string, string[] | true | null>;
+    /** Custom icon overrides. Falls back to default Phosphor icons for unmapped keys. */
+    icons?: IconSet;
     /** Additional content rendered after buttons. */
     children?: React.ReactNode;
 }
-declare function DomternalBubbleMenu({ editor: editorProp, shouldShow, placement, offset, updateDelay, items, contexts, children, }: DomternalBubbleMenuProps): react_jsx_runtime.JSX.Element;
+declare function DomternalBubbleMenu({ editor: editorProp, shouldShow, placement, offset, updateDelay, items, contexts, icons, children, }: DomternalBubbleMenuProps): ReactNode;
 
 interface DomternalFloatingMenuProps {
     /** The editor instance. If omitted, uses EditorProvider context. */
     editor?: Editor;
-    /** Custom visibility function. */
+    /** Custom visibility predicate. */
     shouldShow?: FloatingMenuOptions['shouldShow'];
-    /** Pixel offset from trigger. @default 0 */
+    /** Pixel offset from trigger anchor. @default 0 */
     offset?: number;
-    /** Content to render inside the floating menu. */
-    children?: React.ReactNode;
+    /** Items override (array replaces defaults; function transforms them). */
+    items?: FloatingMenuItemsOverride;
+    /** Keyboard shortcuts for entering the menu via keyboard. */
+    keymap?: FloatingMenuKeymap;
+    /** Custom icon set (falls back to `@domternal/core`'s `defaultIcons`). */
+    icons?: IconSet;
+    /**
+     * When true, the menu does NOT auto-show on every empty paragraph;
+     * it only opens when the BlockHandle `+` button (or any caller of
+     * `showFloatingMenu`) explicitly triggers it. Notion-style behaviour.
+     * @default false
+     */
+    requireExplicitTrigger?: boolean;
+    /**
+     * Optional custom content. When provided, the default grouped-item
+     * rendering is skipped and children are rendered inside the menu element.
+     */
+    children?: ReactNode;
 }
-declare function DomternalFloatingMenu({ editor: editorProp, shouldShow, offset, children, }: DomternalFloatingMenuProps): react_jsx_runtime.JSX.Element;
+/**
+ * Block-insert floating menu. Renders defaults collected from the editor's
+ * extensions via `addFloatingMenuItems()`; pass `items` to override or
+ * `children` to render a fully custom UI.
+ */
+declare function DomternalFloatingMenu({ editor: editorProp, shouldShow, offset, items, keymap, icons, requireExplicitTrigger, children, }: DomternalFloatingMenuProps): ReactNode;
 
 interface EmojiPickerItem {
     emoji: string;
@@ -195,7 +217,7 @@ interface DomternalEmojiPickerProps {
     /** Array of emoji items with emoji, name, and group. */
     emojis: EmojiPickerItem[];
 }
-declare function DomternalEmojiPicker({ editor: editorProp, emojis }: DomternalEmojiPickerProps): react_jsx_runtime.JSX.Element;
+declare function DomternalEmojiPicker({ editor: editorProp, emojis }: DomternalEmojiPickerProps): ReactNode;
 
 interface DomternalProps extends UseEditorOptions {
     /** Optional dependency array for forced editor recreation. */
@@ -225,7 +247,7 @@ interface DomternalProps extends UseEditorOptions {
  * </Domternal>
  * ```
  */
-declare function Domternal({ children, deps, ...options }: DomternalProps): react_jsx_runtime.JSX.Element;
+declare function Domternal({ children, deps, ...options }: DomternalProps): ReactNode;
 declare namespace Domternal {
     var Content: typeof DomternalContent;
     var Loading: typeof DomternalLoading;
@@ -237,34 +259,34 @@ declare namespace Domternal {
 /** Renders the editor content area. Mounts the editor view DOM from context. */
 declare function DomternalContent({ className }: {
     className?: string;
-}): react_jsx_runtime.JSX.Element;
+}): ReactNode;
 declare namespace DomternalContent {
     var displayName: string;
 }
 /** Renders children only while editor is not yet ready (SSR loading state). */
 declare function DomternalLoading({ children }: {
     children: ReactNode;
-}): react_jsx_runtime.JSX.Element | null;
+}): ReactNode;
 declare namespace DomternalLoading {
     var displayName: string;
 }
 /** Toolbar subcomponent. Uses editor from context automatically. */
-declare function DomternalToolbarSub(props: Omit<DomternalToolbarProps, 'editor'>): react_jsx_runtime.JSX.Element;
+declare function DomternalToolbarSub(props: Omit<DomternalToolbarProps, 'editor'>): ReactNode;
 declare namespace DomternalToolbarSub {
     var displayName: string;
 }
 /** BubbleMenu subcomponent. Uses editor from context automatically. */
-declare function DomternalBubbleMenuSub(props: Omit<DomternalBubbleMenuProps, 'editor'>): react_jsx_runtime.JSX.Element;
+declare function DomternalBubbleMenuSub(props: Omit<DomternalBubbleMenuProps, 'editor'>): ReactNode;
 declare namespace DomternalBubbleMenuSub {
     var displayName: string;
 }
 /** FloatingMenu subcomponent. Uses editor from context automatically. */
-declare function DomternalFloatingMenuSub(props: Omit<DomternalFloatingMenuProps, 'editor'>): react_jsx_runtime.JSX.Element;
+declare function DomternalFloatingMenuSub(props: Omit<DomternalFloatingMenuProps, 'editor'>): ReactNode;
 declare namespace DomternalFloatingMenuSub {
     var displayName: string;
 }
 /** EmojiPicker subcomponent. Uses editor from context automatically. */
-declare function DomternalEmojiPickerSub(props: Omit<DomternalEmojiPickerProps, 'editor'>): react_jsx_runtime.JSX.Element;
+declare function DomternalEmojiPickerSub(props: Omit<DomternalEmojiPickerProps, 'editor'>): ReactNode;
 declare namespace DomternalEmojiPickerSub {
     var displayName: string;
 }
@@ -333,7 +355,76 @@ interface EditorContentProps extends HTMLAttributes<HTMLDivElement> {
  * return <EditorContent editor={editor} className="my-editor" />;
  * ```
  */
-declare function EditorContent({ editor, innerRef, ...htmlProps }: EditorContentProps): react_jsx_runtime.JSX.Element;
+declare function EditorContent({ editor, innerRef, ...htmlProps }: EditorContentProps): ReactNode;
+
+/**
+ * useNotionColorPicker
+ *
+ * State and effect plumbing for the Notion-style inline color picker. Listens
+ * for the `notionColorOpen` event emitted by the bubble menu's "A" trigger,
+ * tracks the active text/background tokens, and exposes the imperative
+ * commands consumers need (`applyText`, `applyBg`, `close`).
+ *
+ * The default component (`DomternalNotionColorPicker`) consumes this hook and
+ * renders the panel via `createPortal`. Consumers building custom UIs can
+ * call this hook directly.
+ */
+
+interface UseNotionColorPickerOptions {
+    editor: Editor | null;
+}
+interface UseNotionColorPickerResult {
+    /** Whether the picker panel is currently open. */
+    isOpen: boolean;
+    /** Editor host element (`.dm-editor`) used as the portal target. Null until the editor is ready. */
+    hostEl: HTMLElement | null;
+    /** Anchor element the picker positions against (the bubble-menu "A" trigger button). */
+    anchorEl: HTMLElement | null;
+    /** Ref to the panel root, used by the picker UI for positioning + focus management. */
+    panelRef: RefObject<HTMLDivElement | null>;
+    /** Currently applied text token at the cursor, or null when default. */
+    currentTextToken: string | null;
+    /** Currently applied background token at the cursor, or null when default. */
+    currentBgToken: string | null;
+    /** Named-token palette (read from the NotionColorPicker extension options). */
+    palette: readonly string[];
+    /** Apply a text color token to the current selection. Picker stays open. */
+    applyText: (token: string | null) => void;
+    /** Apply a background color token to the current selection. Picker stays open. */
+    applyBg: (token: string | null) => void;
+    /** Close the picker. When `refocus` is true, returns focus to the anchor button. */
+    close: (opts?: {
+        refocus?: boolean;
+    }) => void;
+    /** Display label for a palette token (defaults to title-case fallback). */
+    tokenLabel: (token: string) => string;
+    /** Arrow / Home / End keyboard navigation across the 5-column swatch grid. */
+    onPanelKeydown: (event: KeyboardEvent<HTMLDivElement>) => void;
+}
+declare function useNotionColorPicker(options: UseNotionColorPickerOptions): UseNotionColorPickerResult;
+
+/**
+ * DomternalNotionColorPicker
+ *
+ * Notion-style inline color picker rendered via `createPortal` into the
+ * `.dm-editor` host. The portal target keeps the panel inside the editor's
+ * CSS-variable scope (theme tokens cascade) without imperative DOM moves.
+ *
+ * Opens in response to the `notionColorOpen` event emitted by the bubble
+ * menu's "A" trigger. Two sections: text color (top), background color
+ * (bottom). Each section is a default-swatch plus the named-token palette.
+ *
+ * The default UI is rendered when no `children` prop is provided. Pass
+ * `children` to take over rendering while keeping the hook's lifecycle.
+ */
+
+interface DomternalNotionColorPickerProps {
+    /** The editor instance. If omitted, uses EditorProvider context. */
+    editor?: Editor;
+    /** Custom panel content. When provided, replaces the default swatch grid. */
+    children?: ReactNode | ((api: UseNotionColorPickerResult) => ReactNode);
+}
+declare function DomternalNotionColorPicker({ editor: editorProp, children, }: DomternalNotionColorPickerProps): ReactNode;
 
 /** ProseMirror node shape passed to node views. */
 interface PMNode {
@@ -402,7 +493,7 @@ interface ReactNodeViewRendererOptions {
  * }
  * ```
  */
-declare function ReactNodeViewRenderer(component: React.ComponentType<ReactNodeViewProps>, options?: ReactNodeViewRendererOptions): (node: PMNode, _view: unknown, getPos: () => number, decorations: unknown[]) => ReactNodeView;
+declare function ReactNodeViewRenderer(component: React.ComponentType<ReactNodeViewProps>, options?: ReactNodeViewRendererOptions): (node: PMNode, view: unknown, getPos: () => number, decorations: unknown[]) => ReactNodeView;
 interface ReactNodeViewInit {
     editor: Editor;
     node: PMNode;
@@ -442,7 +533,7 @@ interface NodeViewWrapperProps extends HTMLAttributes<HTMLElement> {
  * Container component for custom React node views.
  * Handles drag events and marks the element as a node view wrapper.
  */
-declare function NodeViewWrapper({ as: Tag, style, ...props }: NodeViewWrapperProps): react_jsx_runtime.JSX.Element;
+declare function NodeViewWrapper({ as: Tag, style, ...props }: NodeViewWrapperProps): ReactNode;
 
 interface NodeViewContentProps extends HTMLAttributes<HTMLElement> {
     /** The HTML element type to render. @default 'div' */
@@ -452,7 +543,7 @@ interface NodeViewContentProps extends HTMLAttributes<HTMLElement> {
  * Placeholder for editable nested content within a custom React node view.
  * ProseMirror manages the content DOM inside this element.
  */
-declare function NodeViewContent({ as: Tag, style, ...props }: NodeViewContentProps): react_jsx_runtime.JSX.Element;
+declare function NodeViewContent({ as: Tag, style, ...props }: NodeViewContentProps): ReactNode;
 
 interface ReactNodeViewContextValue {
     onDragStart: (event: DragEvent) => void;
@@ -464,4 +555,4 @@ interface ReactNodeViewContextValue {
  */
 declare function useReactNodeView(): ReactNodeViewContextValue;
 
-export { DEFAULT_EXTENSIONS, Domternal, DomternalBubbleMenu, type DomternalBubbleMenuProps, DomternalEditor, type DomternalEditorProps, type DomternalEditorRef, DomternalEmojiPicker, type DomternalEmojiPickerProps, DomternalFloatingMenu, type DomternalFloatingMenuProps, type DomternalProps, DomternalToolbar, type DomternalToolbarProps, EditorContent, type EditorContentProps, EditorProvider, type EditorProviderProps, type EditorState, type EmojiPickerItem, NodeViewContent, type NodeViewContentProps, NodeViewWrapper, type NodeViewWrapperProps, type ReactNodeViewProps, ReactNodeViewRenderer, type ReactNodeViewRendererOptions, type UseEditorOptions, useCurrentEditor, useEditor, useEditorState, useReactNodeView };
+export { DEFAULT_EXTENSIONS, Domternal, DomternalBubbleMenu, type DomternalBubbleMenuProps, DomternalEditor, type DomternalEditorProps, type DomternalEditorRef, DomternalEmojiPicker, type DomternalEmojiPickerProps, DomternalFloatingMenu, type DomternalFloatingMenuProps, DomternalNotionColorPicker, type DomternalNotionColorPickerProps, type DomternalProps, DomternalToolbar, type DomternalToolbarProps, EditorContent, type EditorContentProps, EditorProvider, type EditorProviderProps, type EditorState, type EmojiPickerItem, NodeViewContent, type NodeViewContentProps, NodeViewWrapper, type NodeViewWrapperProps, type ReactNodeViewProps, ReactNodeViewRenderer, type ReactNodeViewRendererOptions, type UseEditorOptions, type UseNotionColorPickerOptions, type UseNotionColorPickerResult, useCurrentEditor, useEditor, useEditorState, useNotionColorPicker, useReactNodeView };