@domternal/vanilla 0.14.0 → 1.0.0

package/README.md

@@ -4,9 +4,10 @@
 [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/domternal/domternal/blob/main/LICENSE)
 
 Framework-free DOM components for the [Domternal](https://domternal.dev) editor.
-Each component is a class you instantiate against a host element:
-`DomternalEditor`, `DomternalToolbar`, `DomternalBubbleMenu`, `DomternalFloatingMenu`,
-`DomternalEmojiPicker`, and `DomternalNotionColorPicker`. Every class extends
+Most are classes you instantiate against a host element: `DomternalEditor`,
+`DomternalToolbar`, `DomternalBubbleMenu`, `DomternalFloatingMenu`, and
+`DomternalEmojiPicker`. `DomternalNotionColorPicker` is the exception: it takes only an
+options object and resolves its own `.dm-editor` host from the editor. Every class extends
 `EventTarget`, exposes plain getters and mutator methods, dispatches `CustomEvent`s for state
 changes, and tears down with an idempotent `destroy()`. Use it in Astro, Svelte, Solid,
 Lit, Web Components, or plain HTML - anywhere without a framework runtime.
@@ -21,8 +22,8 @@ Lit, Web Components, or plain HTML - anywhere without a framework runtime.
 pnpm add @domternal/core @domternal/theme @domternal/vanilla
 ```
 
-`@domternal/core` is a peer dependency. `@domternal/theme` supplies the editor styles
-(import it once in your app).
+`@domternal/core` (>=1.0.0) is a peer dependency. `@domternal/theme` supplies the editor
+styles (import it once in your app).
 
 ## Usage
 
@@ -70,6 +71,24 @@ The matching mount points:
 > SSR. Module-scope imports stay SSR-safe, so gate instantiation behind a client-side
 > entry point (e.g. an Astro `<script>` block or `client:only`).
 
+## Options
+
+`DomternalEditorOptions`, the second constructor argument:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `extensions` | `AnyExtension[]` | `[]` | Extensions merged on top of `DEFAULT_EXTENSIONS`. |
+| `history` | `boolean` | `true` | Whether the built-in History extension is loaded. Turn it off when an extension brings its own undo. |
+| `content` | `Content` | `''` | Initial content, HTML string or JSON. |
+| `editable` | `boolean` | `true` | Whether the editor is editable. |
+| `preset` | `'classic' \| 'notion'` | `'classic'` | `'notion'` paints `dm-notion-mode` on the `.dm-editor` host and switches preset-aware extensions to their Notion behavior. Create-time only. |
+| `autofocus` | `FocusPosition` | `false` | Where to place the caret on mount. |
+| `outputFormat` | `'html' \| 'json'` | `'html'` | Format hint for host frameworks comparing controlled content. Does not change editor behavior. |
+
+`onCreate`, `onUpdate`, `onSelectionChange`, `onFocus`, `onBlur`, and `onDestroy` callbacks are
+accepted alongside them, and the same moments are dispatched on the instance as `create`,
+`update`, `selectionchange`, `focus`, `blur`, and `destroy` `CustomEvent`s.
+
 ## Exports
 
 - `DomternalEditor` / `DomternalEditorOptions` - wraps core's `Editor`, plus

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { PluginKey, IconSet, Editor, AnyExtension, Content, FocusPosition, JSONContent, ToolbarController, ToolbarLayoutEntry, ToolbarButton, ToolbarDropdown, BubbleMenuOptions, FloatingMenuController, FloatingMenuOptions, FloatingMenuItemsOverride, FloatingMenuKeymap } from '@domternal/core';
+import { PluginKey, IconSet, AnyExtension, Editor, Content, EditorPreset, FocusPosition, JSONContent, ToolbarController, ToolbarLayoutEntry, ToolbarButton, ToolbarDropdown, BubbleMenuOptions, BubbleContexts, FloatingMenuController, FloatingMenuOptions, FloatingMenuItemsOverride, FloatingMenuKeymap } from '@domternal/core';
+export { BubbleMenuItem, BubbleMenuSeparator, BubbleItemMaps as ItemMaps, ResolvedPosShape, SelectionShape, buildBubbleItemMaps as buildItemMaps, detectBubbleContext as detectContext, filterBubbleItemsBySchema as filterBySchema, getBubbleFormatItems as getFormatItems, isInsideTableCell, resolveBubbleNames as resolveNames } from '@domternal/core';
 
 /**
  * SSR-safe environment check.
@@ -200,6 +201,12 @@ interface DomternalEditorOptions {
     content?: Content;
     /** Whether the editor is editable. @default true */
     editable?: boolean;
+    /**
+     * Editing experience preset. `'notion'` paints `dm-notion-mode` on the
+     * `.dm-editor` host and switches preset-aware extensions to their Notion
+     * behavior, replacing the hand-written class. Create-time only.
+     */
+    preset?: EditorPreset;
     /** Where to autofocus on mount. @default false */
     autofocus?: FocusPosition;
     /**
@@ -434,85 +441,6 @@ declare function getComputedStyleAtCursor(editor: Editor, prop: string): string
  */
 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.
  *
@@ -570,7 +498,7 @@ interface DomternalBubbleMenuOptions extends CustomContentOption {
      * 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>;
+    contexts?: BubbleContexts;
     /** Custom icon overrides. Falls back to default Phosphor icons for unmapped keys. */
     icons?: IconSet;
 }
@@ -584,14 +512,13 @@ interface DomternalBubbleMenuOptions extends CustomContentOption {
  * "..." 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).
+ * Re-renders are batched via `requestAnimationFrame`. The structure is rebuilt
+ * only when the item list changes; a state-only render updates the nodes on
+ * screen, so a press that outlives a transaction still produces a click.
  *
- * **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:
+ * **Stable identity convention.** A trigger survives a state-only render but
+ * NOT an item-list change, so consumers holding a reference to one (e.g. as a
+ * popover anchor) should still:
  * - 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')`)
@@ -661,7 +588,7 @@ declare class DomternalBubbleMenu extends EventTarget {
      * plugin at construction; this only changes WHICH items render once the
      * menu is visible.
      */
-    setContexts(contexts: Record<string, string[] | true | null> | undefined): void;
+    setContexts(contexts: BubbleContexts | 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. */
@@ -873,4 +800,4 @@ declare class DomternalEmojiPicker extends EventTarget {
     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 };
+export { 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, assertBrowser, computeTrailingState, createIconCache, createPluginKey, getComputedStyleAtCursor, getInlineStyleAtCursor, getTooltip, isBrowser, renderIconInto, resolveIcon, subscribe };