@domternal/vanilla 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,871 @@
+import { PluginKey, IconSet, Editor, AnyExtension, Content, FocusPosition, JSONContent, ToolbarController, ToolbarLayoutEntry, ToolbarButton, ToolbarDropdown, BubbleMenuOptions, FloatingMenuController, FloatingMenuItemsOverride } from '@domternal/core';
+import { FloatingMenuOptions, FloatingMenuKeymap } from '@domternal/extension-block-menu';
+
+/**
+ * SSR-safe environment check.
+ *
+ * `@domternal/vanilla` classes construct DOM nodes and attach listeners on
+ * `document` / `window`. During SSR (Astro/Nuxt/Next.js build), the module
+ * may be imported but constructors must NOT run server-side.
+ *
+ * Class constructors call `assertBrowser()` early to throw a clear error
+ * if invoked outside a browser environment.
+ *
+ * @example
+ * ```ts
+ * import { isBrowser, assertBrowser } from '@domternal/vanilla';
+ *
+ * if (isBrowser) {
+ *   const editor = new DomternalEditor(host, { editor });
+ * }
+ *
+ * // Or, in a constructor that requires browser:
+ * class MyWrapper {
+ *   constructor(host: HTMLElement) {
+ *     assertBrowser('MyWrapper');
+ *     // ... safe to use document/window from here
+ *   }
+ * }
+ * ```
+ */
+declare const isBrowser: boolean;
+/**
+ * Assert the current environment is a browser. Throws with an actionable
+ * error message tailored to common SSR frameworks (Astro, Nuxt, Next.js).
+ *
+ * @param className - Name of the calling class, included in the error
+ *   message so users can identify the culprit constructor in a stack trace.
+ *
+ * @throws Error if called server-side.
+ */
+declare function assertBrowser(className: string): void;
+
+/**
+ * Create a unique `PluginKey` with collision-free suffix.
+ *
+ * Two instances of the same wrapper class mounted in the same editor (rare
+ * but supported) need distinct keys to avoid ProseMirror plugin clashes.
+ *
+ * Why crypto.randomUUID + Math.random fallback: matches the framework
+ * wrapper convention (angular, react, vue all use this pattern as of
+ * commit fbef072). SSR may share Math.random seed across mount cycles,
+ * giving collisions; crypto.randomUUID is collision-free by spec.
+ *
+ * @param prefix - Human-readable prefix for debugging. Convention: kebab or
+ *   camel case identifying the wrapper. e.g. `'vanillaBubbleMenu'`.
+ * @returns A `PluginKey` with format `<prefix>-<8-char-suffix>`.
+ *
+ * @example
+ * ```ts
+ * import { createPluginKey } from '@domternal/vanilla';
+ *
+ * class MyBubbleMenu {
+ *   #pluginKey = createPluginKey('myBubbleMenu');
+ *
+ *   constructor(editor: Editor) {
+ *     const plugin = createBubbleMenuPlugin({
+ *       pluginKey: this.#pluginKey,
+ *       editor,
+ *       element: this.host,
+ *     });
+ *     editor.registerPlugin(plugin);
+ *   }
+ *
+ *   destroy() {
+ *     this.editor.unregisterPlugin(this.#pluginKey);
+ *   }
+ * }
+ * ```
+ */
+declare function createPluginKey(prefix: string): PluginKey;
+
+/**
+ * Resolve and inject an icon's SVG string into a host element.
+ *
+ * Why innerHTML is safe here: icons come from the `defaultIcons` lookup
+ * table (Phosphor SVG strings shipped with core) or from a consumer-provided
+ * `IconSet` object. Both are trusted by contract because they are constants in
+ * source code, not user input. This matches the React (`dangerouslySetInnerHTML`),
+ * Angular (`bypassSecurityTrustHtml`), and Vue (`v-html`) patterns.
+ *
+ * Consumer responsibility (documented in README): never pass user-controlled
+ * strings as icon values in your `IconSet`.
+ *
+ * @param hostEl - Target element. `innerHTML` is replaced (existing children
+ *   are removed).
+ * @param iconKey - Icon name to look up in `icons` first, then `defaultIcons`.
+ *   When `undefined`, the host is emptied.
+ * @param icons - Optional consumer-provided icon overrides. Falls back to
+ *   `defaultIcons` if not provided or if the key is missing.
+ *
+ * @example
+ * ```ts
+ * import { renderIconInto } from '@domternal/vanilla';
+ *
+ * const button = document.createElement('button');
+ * const iconSpan = document.createElement('span');
+ * button.appendChild(iconSpan);
+ *
+ * renderIconInto(iconSpan, 'textB');                 // default Phosphor icon
+ * renderIconInto(iconSpan, 'bold', { bold: mySvg }); // custom override
+ * renderIconInto(iconSpan, undefined);               // clear icon
+ * ```
+ */
+declare function renderIconInto(hostEl: HTMLElement, iconKey: string | undefined, icons: IconSet | undefined): void;
+/**
+ * Resolve an icon's SVG string without injection. Useful when caller
+ * builds the final DOM tree (e.g. via `document.createElement` chain
+ * or template literal interpolation).
+ *
+ * @param iconKey - Icon name to look up. When `undefined`, returns `''`.
+ * @param icons - Optional consumer overrides; falls back to `defaultIcons`.
+ * @returns Trusted SVG string, or `''` if the icon is unknown.
+ *
+ * @example
+ * ```ts
+ * import { resolveIcon } from '@domternal/vanilla';
+ *
+ * const iconHtml = resolveIcon('textB', undefined);
+ * const button = document.createElement('button');
+ * button.innerHTML = `<span class="icon">${iconHtml}</span><span>Bold</span>`;
+ * ```
+ */
+declare function resolveIcon(iconKey: string | undefined, icons: IconSet | undefined): string;
+
+/**
+ * Helpers for typed event subscription over `EventTarget`.
+ *
+ * Each `@domternal/vanilla` class extends the platform `EventTarget` and
+ * dispatches `CustomEvent` instances. Consumers can use the platform
+ * `addEventListener('eventName', handler)` directly, OR call `subscribe()`
+ * which returns an unsubscribe function and narrows the detail type.
+ *
+ * Usage:
+ * ```ts
+ * import { subscribe } from '@domternal/vanilla';
+ *
+ * const off = subscribe<{ isOpen: boolean }>(picker, 'openchange', (detail) => {
+ *   console.log(detail.isOpen);
+ * });
+ * off(); // remove listener
+ * ```
+ *
+ * Each class JSDoc lists the events it emits + the shape of `detail`.
+ */
+declare function subscribe<TDetail = unknown>(target: EventTarget, type: string, listener: (detail: TDetail) => void): () => void;
+
+/**
+ * Shared option types reused across `@domternal/vanilla` components.
+ */
+/**
+ * Custom content slot. Pass a pre-built DOM tree the wrapper appends into
+ * its host instead of rendering the default UI.
+ *
+ * The DOM you pass stays YOURS. The wrapper does NOT mutate it after
+ * construction and does NOT clean up event handlers on it during destroy.
+ * Manage its lifecycle yourself.
+ *
+ * @example
+ * ```ts
+ * const myUi = document.createElement('div');
+ * myUi.innerHTML = `<button data-mark="bold">B</button>`;
+ * myUi.querySelector('button')!.addEventListener('click', () => {
+ *   editor.chain().focus().toggleBold().run();
+ * });
+ *
+ * const bubble = new DomternalBubbleMenu(host, {
+ *   editor,
+ *   customContent: myUi,
+ * });
+ *
+ * // Later, when YOU destroy your UI, do listener cleanup yourself:
+ * bubble.destroy();   // detaches myUi from host
+ * myUi.remove();      // your responsibility
+ * ```
+ */
+interface CustomContentOption {
+    customContent?: HTMLElement;
+}
+
+declare const DEFAULT_EXTENSIONS: AnyExtension[];
+interface DomternalEditorOptions {
+    /** Custom extensions to add. Merged on top of `DEFAULT_EXTENSIONS`. */
+    extensions?: AnyExtension[];
+    /** Initial editor content (HTML string or JSON). */
+    content?: Content;
+    /** Whether the editor is editable. @default true */
+    editable?: boolean;
+    /** Where to autofocus on mount. @default false */
+    autofocus?: FocusPosition;
+    /**
+     * Output format hint for downstream consumers (e.g. host frameworks
+     * comparing controlled-mode content). Does not change editor behavior.
+     * @default 'html'
+     */
+    outputFormat?: 'html' | 'json';
+    /** Called once when the underlying Editor instance is created. */
+    onCreate?: (editor: Editor) => void;
+    /** Called when the document content changes. */
+    onUpdate?: (ctx: {
+        editor: Editor;
+    }) => void;
+    /** Called when the selection moves without a content change. */
+    onSelectionChange?: (ctx: {
+        editor: Editor;
+    }) => void;
+    /** Called when the editor gains focus. */
+    onFocus?: (ctx: {
+        editor: Editor;
+        event: FocusEvent;
+    }) => void;
+    /** Called when the editor loses focus. */
+    onBlur?: (ctx: {
+        editor: Editor;
+        event: FocusEvent;
+    }) => void;
+    /** Called before the underlying Editor is destroyed. */
+    onDestroy?: () => void;
+}
+/**
+ * `DomternalEditor` - vanilla DOM wrapper around `@domternal/core`'s `Editor`.
+ *
+ * Mounts an editor into the host element, wires lifecycle callbacks, exposes
+ * reactive-friendly getters via plain properties, and dispatches `CustomEvent`
+ * instances for state changes (so framework adapters can bridge).
+ *
+ * Construction is browser-only - throws in SSR contexts (use Astro
+ * `<client:only="vanilla">` or similar gate).
+ *
+ * Cleanup is automatic via `destroy()` (calls `editor.destroy()` + emits
+ * `destroy` event).
+ *
+ * @example
+ * ```ts
+ * import { DomternalEditor } from '@domternal/vanilla';
+ * import { StarterKit } from '@domternal/core';
+ *
+ * const host = document.getElementById('editor')!;
+ * const wrapper = new DomternalEditor(host, {
+ *   extensions: [StarterKit],
+ *   content: '<p>Hello world</p>',
+ *   onUpdate: ({ editor }) => console.log(editor.getHTML()),
+ * });
+ *
+ * // Reactive access via getters:
+ * console.log(wrapper.htmlContent);
+ * console.log(wrapper.isEmpty);
+ *
+ * // Event subscription (CustomEvent):
+ * wrapper.addEventListener('update', () => {
+ *   console.log('content changed');
+ * });
+ *
+ * // Cleanup:
+ * wrapper.destroy();
+ * ```
+ *
+ * **Events dispatched** (CustomEvent, `detail` shape in brackets):
+ * - `create` - `{ editor: Editor }` - emitted once after Editor instantiation
+ * - `update` - `{ editor: Editor }` - emitted on every content change
+ * - `selectionchange` - `{ editor: Editor }` - emitted on selection-only updates
+ * - `focus` - `{ editor: Editor; event: FocusEvent }`
+ * - `blur` - `{ editor: Editor; event: FocusEvent }`
+ * - `destroy` - `null` - emitted just before destroy completes
+ */
+declare class DomternalEditor extends EventTarget {
+    #private;
+    /** The underlying ProseMirror-backed `Editor` instance. */
+    readonly editor: Editor;
+    /** The host element provided to the constructor. */
+    readonly host: HTMLElement;
+    constructor(host: HTMLElement, options?: DomternalEditorOptions);
+    get htmlContent(): string;
+    get jsonContent(): JSONContent;
+    get isEmpty(): boolean;
+    get isFocused(): boolean;
+    get isEditable(): boolean;
+    /**
+     * Replace editor content. Does NOT emit `update` event by default
+     * (mirrors `Editor.setContent` behavior); pass `emitUpdate=true` to fire.
+     *
+     * No-op if the wrapper has been destroyed.
+     */
+    setContent(content: Content, emitUpdate?: boolean): void;
+    /**
+     * Toggle the editor's editable state (`true` allows input, `false` makes
+     * it read-only). No-op if the wrapper has been destroyed.
+     */
+    setEditable(editable: boolean): void;
+    /**
+     * Programmatically focus the editor.
+     *
+     * @param position - Focus position (`'start' | 'end' | 'all' | number | boolean`).
+     *   Defaults to current selection. No-op if the wrapper has been destroyed.
+     */
+    focus(position?: FocusPosition): void;
+    /**
+     * Tear down the underlying editor + remove all subscriptions.
+     *
+     * Idempotent - calling twice is a no-op. Dispatches a `destroy` CustomEvent
+     * BEFORE the editor is destroyed, so listeners can read `this.editor` state
+     * one last time.
+     */
+    destroy(): void;
+}
+
+interface DomternalToolbarOptions {
+    /** Editor instance the toolbar binds to. */
+    editor: Editor;
+    /** Optional icon set override. Falls back to `defaultIcons` per key. */
+    icons?: IconSet;
+    /**
+     * Optional custom layout (item names + separators + custom dropdowns).
+     * When omitted, items are grouped by their declared `group` property and
+     * sorted by priority within each group.
+     *
+     * @example
+     * ```ts
+     * new DomternalToolbar(host, {
+     *   editor,
+     *   layout: ['bold', 'italic', 'underline', '|', 'heading', '|', 'undo', 'redo'],
+     * });
+     * ```
+     */
+    layout?: ToolbarLayoutEntry[];
+}
+/**
+ * `DomternalToolbar` - vanilla DOM toolbar bound to an editor's items.
+ *
+ * Mounts a `ToolbarController` from `@domternal/core` and renders its state
+ * (groups, active map, disabled map, dropdown state) into the host element.
+ *
+ * Re-renders are batched via `requestAnimationFrame` so transaction-rate
+ * updates don't thrash the DOM. Button DOM nodes are reused across renders
+ * (only their classes/attrs update) to preserve focus when navigating with
+ * the keyboard.
+ *
+ * @example
+ * ```ts
+ * import { Editor, StarterKit } from '@domternal/core';
+ * import { DomternalToolbar } from '@domternal/vanilla';
+ * import '@domternal/theme';
+ *
+ * const editor = new Editor({
+ *   element: document.getElementById('editor')!,
+ *   extensions: [StarterKit],
+ * });
+ *
+ * const toolbar = new DomternalToolbar(document.getElementById('toolbar')!, {
+ *   editor,
+ *   // Optional custom layout:
+ *   // layout: ['bold', 'italic', '|', 'heading'],
+ * });
+ *
+ * // Update later:
+ * toolbar.setLayout(['bold', 'italic', 'underline']);
+ *
+ * // Cleanup:
+ * toolbar.destroy();
+ * ```
+ *
+ * **Events dispatched** (CustomEvent, `detail` shape in brackets):
+ * - `dropdownopen` - `{ name: string }` - emitted when a dropdown opens
+ * - `dropdownclose` - `{ name: string }` - emitted when a dropdown closes
+ */
+declare class DomternalToolbar extends EventTarget {
+    #private;
+    readonly host: HTMLElement;
+    /** The editor instance this toolbar is bound to. */
+    get editor(): Editor;
+    /** Underlying controller. Exposed for power-user introspection. */
+    get controller(): ToolbarController;
+    constructor(host: HTMLElement, options: DomternalToolbarOptions);
+    get openDropdown(): string | null;
+    setLayout(layout: ToolbarLayoutEntry[] | undefined): void;
+    setIcons(icons: IconSet | undefined): void;
+    closeDropdown(): void;
+    destroy(): void;
+}
+
+/**
+ * Format a toolbar button's tooltip including its keyboard shortcut.
+ *
+ * On macOS uses Unicode glyphs (⌘ ⇧ ⌥); elsewhere falls back
+ * to "Ctrl+Shift+Alt" text. Mirrors Vue/React wrapper behavior.
+ */
+declare function getTooltip(item: ToolbarButton): string;
+
+declare const DROPDOWN_CARET: string;
+interface IconCache {
+    resolveSvg: (name: string) => string;
+    getIcon: (name: string) => string;
+    getTriggerLabel: (label: string, isIcon?: boolean) => string;
+    getTriggerIcon: (iconName: string) => string;
+    getItemContent: (icon: string, label: string, mode?: 'icon-text' | 'text' | 'icon') => string;
+    getDropdownTriggerHtml: (dropdown: ToolbarDropdown, activeItem: ToolbarButton | undefined) => string;
+    setIcons: (icons: IconSet | undefined) => void;
+}
+/**
+ * Resolve + cache toolbar icons. Mirrors Vue's `useToolbarIcons` logic
+ * verbatim - same cache keys, same fallback order (consumer `IconSet` ->
+ * `defaultIcons`), same dropdown trigger HTML composition.
+ *
+ * Cache is invalidated when consumer swaps `IconSet`.
+ */
+declare function createIconCache(initialIcons: IconSet | undefined): IconCache;
+
+/**
+ * Read a CSS property at the current cursor position.
+ * Prefers inline style, falls back to computed style. Used by dropdowns
+ * with `computedStyleProperty` (e.g. font-size) to show the current value
+ * in their trigger label.
+ */
+declare function getComputedStyleAtCursor(editor: Editor, prop: string): string | null;
+/**
+ * Read ONLY inline style at the current cursor position (skips browser-default
+ * computed inheritance). Used for `font-family` where computed value includes
+ * the document's default fallback that would override any user-set font in the
+ * toolbar's "current font" indicator.
+ */
+declare function getInlineStyleAtCursor(editor: Editor, prop: string): string | null;
+
+interface ResolvedPosShape {
+    parent: {
+        type: {
+            name: string;
+            spec: {
+                marks?: string;
+            };
+        };
+    };
+    depth: number;
+    node: (depth: number) => {
+        type: {
+            name: string;
+        };
+    };
+}
+interface SelectionShape {
+    empty: boolean;
+    $from: ResolvedPosShape;
+    $to: ResolvedPosShape;
+    node?: {
+        type: {
+            name: string;
+        };
+    };
+}
+interface BubbleMenuSeparator {
+    type: 'separator';
+    name: string;
+}
+type BubbleMenuItem = ToolbarButton | ToolbarDropdown | BubbleMenuSeparator;
+interface ItemMaps {
+    itemMap: Map<string, ToolbarButton>;
+    dropdownMap: Map<string, ToolbarDropdown>;
+    /** Bubble defaults indexed by context name (e.g. 'text', 'codeBlock'). */
+    bubbleDefaults: Map<string, BubbleMenuItem[]>;
+}
+/**
+ * Walks `editor.toolbarItems` and indexes them by name. Dropdowns are kept
+ * separately so the bubble menu can resolve them by name (e.g. text-align).
+ */
+declare function buildItemMaps(editor: Editor): ItemMaps;
+/**
+ * Resolve a name array to BubbleMenuItems via the item/dropdown maps.
+ * Dropdowns take priority over buttons sharing the same name. Pipe `|`
+ * tokens become separator entries.
+ */
+declare function resolveNames(names: string[], itemMap: Map<string, ToolbarButton>, dropdownMap: Map<string, ToolbarDropdown>): BubbleMenuItem[];
+/**
+ * All `format`-group buttons sorted by priority (used by `context: true`
+ * shorthand to show "all format marks for this context").
+ */
+declare function getFormatItems(itemMap: Map<string, ToolbarButton>): ToolbarButton[];
+/**
+ * Determine the active bubble-menu context based on the selection. Returns
+ * `null` when no context matches (menu should not show).
+ *
+ * Resolution order:
+ * 1. CellSelection (`$anchorCell`) - no menu inside table cell selections
+ * 2. NodeSelection (image, HR, etc.) - return the node's type name
+ * 3. Empty selection - no context (caret-only)
+ * 4. Inside a table cell - return 'table' (when from/to share a cell)
+ * 5. `$from.parent.type.name` if listed in contexts
+ * 6. 'text' if the parent allows marks
+ */
+declare function detectContext(selection: SelectionShape, ctxs: Record<string, string[] | true | null>): string | null;
+/**
+ * Filter items by what the schema actually allows in the given context.
+ * E.g. inside a `codeBlock` node, marks like Bold/Italic aren't permitted.
+ *
+ * Pass-through for 'text' and 'table' contexts (schema check would be
+ * lossy there because marks are allowed but some items still apply).
+ */
+declare function filterBySchema(editor: Editor, contextName: string, schemaItems: ToolbarButton[]): ToolbarButton[];
+/**
+ * Detect whether `$pos` is inside a table cell (cell or header).
+ */
+declare function isInsideTableCell($pos: ResolvedPosShape): boolean;
+
+/**
+ * Live state for the bubble-menu trailing buttons.
+ *
+ * Mirrors Angular's `syncTrailingButtonsState` output. Computed per editor
+ * transaction and coalesced into a single object so each transaction
+ * triggers at most one re-render.
+ */
+interface BubbleMenuTrailingState {
+    /** True when current selection is a NodeSelection (image, HR, ...). Trailing buttons hide in that case. */
+    isNodeSelection: boolean;
+    /** True when the `notionColorPicker` extension is loaded on this editor (cached once per editor). */
+    showColorPickerButton: boolean;
+    /** True when the `blockContextMenu` extension is loaded on this editor (cached once per editor). */
+    showBlockMenuButton: boolean;
+    /** True when the selection spans more than one top-level block (multi-block "..." disable). */
+    blockMenuButtonDisabled: boolean;
+    /** CSS color value for the "A" trigger glyph (e.g. `var(--dm-block-text-yellow)`), or null. */
+    currentTextColorVar: string | null;
+    /** CSS color value for the "A" trigger underline, or null. */
+    currentBgColorVar: string | null;
+    /** True when any token-based text or background color is applied at the cursor. */
+    hasAnyColor: boolean;
+}
+declare const INITIAL_TRAILING_STATE: BubbleMenuTrailingState;
+interface SyncOptions {
+    hasNotionColorPicker: boolean;
+    hasBlockContextMenu: boolean;
+}
+/**
+ * Compute trailing-button state for the current editor selection.
+ *
+ * - `isNodeSelection`: hides trailing buttons during NodeSelection (image, HR)
+ * - `blockMenuButtonDisabled`: multi-block disable via `$from.before(1) !== $to.before(1)`
+ * - `currentTextColorVar` / `currentBgColorVar` / `hasAnyColor`: read the
+ *   `textStyle` mark at cursor and project token names to CSS-var refs that
+ *   the theme resolves at paint time.
+ */
+declare function computeTrailingState(editor: Editor, opts: SyncOptions): BubbleMenuTrailingState;
+
+interface DomternalBubbleMenuOptions extends CustomContentOption {
+    /** Editor instance the bubble menu binds to. */
+    editor: Editor;
+    /** Custom visibility predicate. Replaces the default (auto-detect context). */
+    shouldShow?: BubbleMenuOptions['shouldShow'];
+    /** Placement relative to the selection. @default 'top' */
+    placement?: 'top' | 'bottom';
+    /** Pixel offset from the selection edge. @default 8 */
+    offset?: number;
+    /** Debounce delay for position updates (ms). @default 0 */
+    updateDelay?: number;
+    /** Explicit item list (overrides contexts). E.g. `['bold', 'italic', '|', 'link']`. */
+    items?: string[];
+    /**
+     * Context-aware items. Map from context name (`'text'`, `'codeBlock'`, etc.)
+     * to item name list, `true` (show all format items), or `null` (no menu for
+     * this context). Defaults to `defaultBubbleContexts(editor)`.
+     */
+    contexts?: Record<string, string[] | true | null>;
+    /** Custom icon overrides. Falls back to default Phosphor icons for unmapped keys. */
+    icons?: IconSet;
+}
+
+/**
+ * `DomternalBubbleMenu` - vanilla DOM bubble menu bound to an editor.
+ *
+ * Mounts `createBubbleMenuPlugin` from `@domternal/core` for visibility and
+ * positioning, then renders ProseMirror selection-aware buttons + dropdowns
+ * inside the host element. Trailing buttons ("A" for Notion color picker,
+ * "..." for block context menu) are rendered automatically when the
+ * corresponding extensions are loaded.
+ *
+ * Re-renders are batched via `requestAnimationFrame`. DOM is rebuilt on every
+ * transaction because the item list changes with context (selection moves
+ * between text and code-block, for example).
+ *
+ * **Stable identity convention.** Trigger buttons (including the "A" and "..."
+ * trailing triggers and dropdown triggers) are DESTROYED and RECREATED on
+ * every transaction. Consumers that store a reference to a trigger element
+ * (e.g. as a popover anchor) should:
+ * - Either listen for `selectionUpdate` / `transaction` and re-resolve the
+ *   anchor via `host.querySelector('.dm-ncp-trigger')` on demand
+ * - Or match the trigger by class + container (`closest('.dm-bubble-menu')`)
+ *   rather than DOM identity for purposes like toggle-on-second-click.
+ *
+ * @example
+ * ```ts
+ * import { DomternalBubbleMenu } from '@domternal/vanilla';
+ *
+ * const bubble = new DomternalBubbleMenu(host, { editor });
+ *
+ * // Custom item list:
+ * new DomternalBubbleMenu(host, {
+ *   editor,
+ *   items: ['bold', 'italic', '|', 'link'],
+ * });
+ *
+ * // Listen for state changes:
+ * bubble.addEventListener('dropdownopen', (e) => {
+ *   console.log('opened', (e as CustomEvent<{ name: string }>).detail.name);
+ * });
+ *
+ * bubble.destroy();
+ * ```
+ *
+ * **Events dispatched** (CustomEvent, `detail` shape in brackets):
+ * - `dropdownopen` - `{ name: string }`
+ * - `dropdownclose` - `{ name: string }`
+ */
+declare class DomternalBubbleMenu extends EventTarget {
+    #private;
+    readonly host: HTMLElement;
+    get editor(): Editor;
+    /** Current trailing-button state snapshot. */
+    get trailing(): Readonly<BubbleMenuTrailingState>;
+    /** Currently open dropdown name (e.g. text-align), or `null`. */
+    get openDropdown(): string | null;
+    constructor(host: HTMLElement, options: DomternalBubbleMenuOptions);
+    /**
+     * Emit `notionColorOpen` with the given anchor element. Listened to by
+     * `DomternalNotionColorPicker` (Phase 4) which positions its panel against
+     * the anchor. Typically called by the wrapper's internal "A" trigger but
+     * exposed publicly for power users with custom UIs.
+     */
+    openColorPicker(anchor: HTMLElement): void;
+    /**
+     * Open the block context menu against the cursor's containing block.
+     * Dispatches `dm:block-context-menu-open` on `.dm-editor`. The
+     * `BlockContextMenu` extension listens and positions itself against the
+     * provided anchor.
+     *
+     * Walks one level up when the cursor's textblock is not a direct doc
+     * child (e.g. cursor in `listItem > paragraph` targets the `listItem`),
+     * so "Delete" / "Turn into" operate on the visual block.
+     */
+    openBlockContextMenu(anchor: HTMLElement): void;
+    /**
+     * Replace the explicit item list. When `undefined`, falls back to
+     * context-aware resolution (per `contexts` or `defaultBubbleContexts`).
+     * Re-renders on next transaction; call manually if needed:
+     * `editor.dispatch(editor.state.tr)` to force an immediate re-resolve.
+     */
+    setItems(items: string[] | undefined): void;
+    /**
+     * Replace context map. When `undefined`, defaults to
+     * `defaultBubbleContexts(editor)`. Note: `shouldShow` is baked into the
+     * plugin at construction; this only changes WHICH items render once the
+     * menu is visible.
+     */
+    setContexts(contexts: Record<string, string[] | true | null> | undefined): void;
+    /** Replace the icon set. `undefined` restores default Phosphor icons. */
+    setIcons(icons: IconSet | undefined): void;
+    /** Close any open dropdown (text-align). No-op if nothing is open. */
+    closeDropdown(): void;
+    destroy(): void;
+}
+
+interface DomternalFloatingMenuOptions extends CustomContentOption {
+    /** Editor instance the floating menu binds to. */
+    editor: Editor;
+    /** Custom visibility predicate. Defaults to "cursor at start of empty paragraph". */
+    shouldShow?: FloatingMenuOptions['shouldShow'];
+    /** Pixel offset from the anchor. @default 0 */
+    offset?: number;
+    /** Items override (array replaces defaults; function filters/reorders). */
+    items?: FloatingMenuItemsOverride;
+    /** Keyboard shortcuts for entering the menu. */
+    keymap?: FloatingMenuKeymap;
+    /** Icon set override. Falls back to `defaultIcons` per key. */
+    icons?: IconSet;
+    /**
+     * When `true`, the menu opens ONLY via explicit trigger (`showFloatingMenu`
+     * call, typically from BlockHandle's `+` button). Pressing Enter to make
+     * a new empty paragraph does NOT auto-show the menu. Notion-style behavior.
+     * @default false
+     */
+    requireExplicitTrigger?: boolean;
+}
+/**
+ * `DomternalFloatingMenu` - vanilla DOM block-insert menu bound to an editor.
+ *
+ * Renders the editor's `floatingMenuItems` (collected via extensions'
+ * `addFloatingMenuItems()` hook) in groups, with roving-tabindex keyboard
+ * navigation and `requireExplicitTrigger` support for Notion-style flow.
+ *
+ * Mounts `createFloatingMenuPlugin` from `@domternal/extension-block-menu`
+ * for visibility + positioning. The plugin moves the host element inside
+ * `.dm-editor` automatically so it scrolls with the editor.
+ *
+ * @example
+ * ```ts
+ * import { DomternalFloatingMenu } from '@domternal/vanilla';
+ *
+ * // Classic: auto-shows on every empty paragraph
+ * new DomternalFloatingMenu(host, { editor });
+ *
+ * // Notion-style: only opens via "+" button or `showFloatingMenu(view)`
+ * new DomternalFloatingMenu(host, { editor, requireExplicitTrigger: true });
+ * ```
+ */
+declare class DomternalFloatingMenu extends EventTarget {
+    #private;
+    readonly host: HTMLElement;
+    get editor(): Editor;
+    /**
+     * Underlying controller. Exposed for power-user introspection.
+     *
+     * `null` when `customContent` is provided (consumer owns rendering, and
+     * therefore the item-state machine). Use the `editor.floatingMenuItems`
+     * direct API in that case.
+     */
+    get controller(): FloatingMenuController | null;
+    constructor(host: HTMLElement, options: DomternalFloatingMenuOptions);
+    /**
+     * Swap the icon set. Re-renders to refresh button SVGs. No-op when
+     * `customContent` is in use (consumer renders their own icons).
+     */
+    setIcons(icons: IconSet | undefined): void;
+    destroy(): void;
+}
+
+interface DomternalNotionColorPickerOptions {
+    /** The editor instance the picker binds to. */
+    editor: Editor;
+}
+/**
+ * `DomternalNotionColorPicker` - vanilla DOM Notion-style color picker.
+ *
+ * Listens for the `notionColorOpen` editor event (emitted by the bubble menu's
+ * "A" trigger) and renders an inline panel positioned against the trigger.
+ * Two sections (Text color / Background color), each with a 5-column grid of
+ * named-token swatches plus a default reset swatch.
+ *
+ * The panel is appended into the `.dm-editor` host so CSS variables
+ * (`--dm-block-text-{token}`, `--dm-block-bg-{token}`) cascade naturally
+ * from the editor's theme scope. **Requires the editor view to be inside a
+ * `.dm-editor` host** (matches `@domternal/theme` convention). When that
+ * ancestor is missing the picker silently no-ops on open.
+ *
+ * Unlike other `@domternal/vanilla` components, this class does NOT take a
+ * `host` element argument - it auto-resolves the `.dm-editor` parent. The
+ * resolved host is exposed via the `host` getter for power-user inspection.
+ *
+ * @example
+ * ```ts
+ * import { DomternalNotionColorPicker } from '@domternal/vanilla';
+ *
+ * const picker = new DomternalNotionColorPicker({ editor });
+ *
+ * // picker.open(anchor) opens programmatically; usually called by the
+ * // bubble menu's "A" trigger via the `notionColorOpen` editor event.
+ *
+ * picker.destroy();
+ * ```
+ *
+ * **Events dispatched** (CustomEvent, `detail` shape in brackets):
+ * - `openchange` - `{ isOpen: boolean }`
+ * - `apply` - `{ kind: 'text' | 'bg', token: string | null }`
+ */
+declare class DomternalNotionColorPicker extends EventTarget {
+    #private;
+    /** The picker's panel element (created on first open, persistent for reuse). */
+    get panel(): HTMLDivElement | null;
+    /**
+     * The `.dm-editor` host into which the panel mounts. Auto-resolved from
+     * `editor.view.dom.closest('.dm-editor')`. Returns `null` when the editor
+     * view is not inside a `.dm-editor` ancestor (in which case the picker
+     * silently no-ops on `open()`).
+     */
+    get host(): HTMLElement | null;
+    get editor(): Editor;
+    get isOpen(): boolean;
+    get currentTextToken(): string | null;
+    get currentBgToken(): string | null;
+    get palette(): readonly string[];
+    constructor(options: DomternalNotionColorPickerOptions);
+    /**
+     * Open the picker against the given anchor element. Typically called
+     * implicitly via the `notionColorOpen` editor event, but exposed publicly
+     * for power users who emit the open from custom UI.
+     *
+     * Toggle semantics: calling `open(anchor)` with the SAME anchor while the
+     * picker is already open closes the picker (with refocus). Calling with a
+     * different anchor re-anchors against the new element.
+     */
+    open(anchor: HTMLElement): void;
+    /**
+     * Close the picker. When `refocus` is `true`, returns focus to the editor
+     * view (NOT the anchor button - the anchor is on the bubble menu which
+     * vanishes on focus return).
+     */
+    close(opts?: {
+        refocus?: boolean;
+    }): void;
+    /** 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;
+    /** Display label for a palette token (title-case fallback). */
+    tokenLabel(token: string): string;
+    destroy(): void;
+}
+
+interface EmojiPickerItem {
+    emoji: string;
+    name: string;
+    group: string;
+}
+interface DomternalEmojiPickerOptions {
+    /** The editor instance the picker binds to. */
+    editor: Editor;
+    /** Full emoji set with `{ emoji, name, group }` entries. Required. */
+    emojis: EmojiPickerItem[];
+}
+/**
+ * `DomternalEmojiPicker` - vanilla DOM emoji picker.
+ *
+ * Listens for the `insertEmoji` editor event (emitted by the toolbar's emoji
+ * trigger or via custom code) and renders a panel with search input, category
+ * tabs, and an 8-column grid of swatches. Frequently-used emojis come from
+ * the `Emoji` extension's storage if available.
+ *
+ * @example
+ * ```ts
+ * import { DomternalEmojiPicker } from '@domternal/vanilla';
+ * import { emojis } from '@domternal/extension-emoji';
+ *
+ * const picker = new DomternalEmojiPicker(host, { editor, emojis });
+ *
+ * // picker.open(anchor) opens programmatically; usually triggered
+ * // implicitly by the `insertEmoji` editor event.
+ *
+ * picker.destroy();
+ * ```
+ *
+ * **Events dispatched** (CustomEvent, `detail` shape in brackets):
+ * - `openchange` - `{ isOpen: boolean }`
+ * - `select` - `{ name: string; emoji: string }`
+ */
+declare class DomternalEmojiPicker extends EventTarget {
+    #private;
+    readonly host: HTMLElement;
+    get editor(): Editor;
+    get isOpen(): boolean;
+    get searchQuery(): string;
+    get activeCategory(): string;
+    constructor(host: HTMLElement, options: DomternalEmojiPickerOptions);
+    /**
+     * Open the picker. If `anchor` is provided, panel positions against it;
+     * otherwise the panel renders un-positioned inside the host (consumer's CSS
+     * responsibility).
+     */
+    open(anchor: HTMLElement | null): void;
+    /**
+     * Close the picker. Returns focus to the editor view (so the caret stays
+     * visible). Idempotent.
+     */
+    close(): void;
+    destroy(): void;
+}
+
+export { type BubbleMenuItem, type BubbleMenuSeparator, type BubbleMenuTrailingState, type CustomContentOption, DEFAULT_EXTENSIONS, DROPDOWN_CARET, DomternalBubbleMenu, type DomternalBubbleMenuOptions, DomternalEditor, type DomternalEditorOptions, DomternalEmojiPicker, type DomternalEmojiPickerOptions, DomternalFloatingMenu, type DomternalFloatingMenuOptions, DomternalNotionColorPicker, type DomternalNotionColorPickerOptions, DomternalToolbar, type DomternalToolbarOptions, type EmojiPickerItem, INITIAL_TRAILING_STATE, type IconCache, type ItemMaps, type ResolvedPosShape, type SelectionShape, assertBrowser, buildItemMaps, computeTrailingState, createIconCache, createPluginKey, detectContext, filterBySchema, getComputedStyleAtCursor, getFormatItems, getInlineStyleAtCursor, getTooltip, isBrowser, isInsideTableCell, renderIconInto, resolveIcon, resolveNames, subscribe };