@lexical/extension 0.44.1-nightly.20260519.0 → 0.45.0

package/dist/ClickAfterLastBlockExtension.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { LexicalNode } from 'lexical';
+import { type Signal } from './signals';
+/**
+ * @experimental
+ *
+ * Default predicate matches {@link DecoratorNode} and shadow-root
+ * `ElementNode`s (e.g. `TableNode`). Apps that want to also trigger on
+ * other node types — `CodeNode`, custom non-editable blocks — should
+ * compose this default in their own predicate rather than re-deriving
+ * the check:
+ *
+ * ```ts
+ * configExtension(ClickAfterLastBlockExtension, {
+ *   $shouldInsertAfter: (node) =>
+ *     $defaultShouldInsertAfter(node) || $isCodeNode(node),
+ * });
+ * ```
+ */
+export declare function $defaultShouldInsertAfter(node: LexicalNode): boolean;
+export interface ClickAfterLastBlockConfig {
+    /** Set to `true` to disable this extension. */
+    disabled: boolean;
+    /**
+     * Called inside the editor update with the last child of the root when
+     * the user clicks the empty area below it. Return `true` to insert a
+     * new paragraph after that node and select it; return `false` to leave
+     * the click alone. Default is {@link $defaultShouldInsertAfter} — see
+     * its docs for composition patterns.
+     */
+    $shouldInsertAfter: (node: LexicalNode) => boolean;
+}
+export interface ClickAfterLastBlockOutput {
+    /** Set to `true` to disable this extension. */
+    disabled: Signal<boolean>;
+    /** Predicate signal — see {@link ClickAfterLastBlockConfig.$shouldInsertAfter}. */
+    $shouldInsertAfter: Signal<(node: LexicalNode) => boolean>;
+}
+/**
+ * Click handling for the empty area below the last block of the document.
+ *
+ * Without this extension, clicking the area below the last block when that
+ * block is a {@link DecoratorNode}, a shadow-root ElementNode (e.g.
+ * `TableNode`), or any other block that doesn't accept the click naturally
+ * leaves the selection in an awkward place — `null` for a bare decorator,
+ * or at the end of a table cell. Users typically expect a new paragraph
+ * to appear below the block with the caret in it, matching the behavior
+ * of editors like Notion.
+ *
+ * This extension intercepts clicks under those conditions, inserts a new
+ * empty paragraph after the last block, and selects it.
+ *
+ * Closes #8544.
+ */
+export declare const ClickAfterLastBlockExtension: import("lexical").LexicalExtension<ClickAfterLastBlockConfig, "@lexical/ClickAfterLastBlock", ClickAfterLastBlockOutput, unknown>;

package/{LexicalExtension.dev.js → dist/LexicalExtension.dev.js}

@@ -133,6 +133,177 @@ const ClearEditorExtension = lexical.defineExtension({
   }
 });
 
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+
+/**
+ * @experimental
+ *
+ * Default predicate matches {@link DecoratorNode} and shadow-root
+ * `ElementNode`s (e.g. `TableNode`). Apps that want to also trigger on
+ * other node types — `CodeNode`, custom non-editable blocks — should
+ * compose this default in their own predicate rather than re-deriving
+ * the check:
+ *
+ * ```ts
+ * configExtension(ClickAfterLastBlockExtension, {
+ *   $shouldInsertAfter: (node) =>
+ *     $defaultShouldInsertAfter(node) || $isCodeNode(node),
+ * });
+ * ```
+ */
+function $defaultShouldInsertAfter(node) {
+  if (lexical.$isDecoratorNode(node)) {
+    return true;
+  }
+  if (lexical.$isElementNode(node) && node.isShadowRoot()) {
+    return true;
+  }
+  return false;
+}
+/**
+ * Decide whether a click at `event` should be claimed by this extension.
+ * Used by both the mousedown listener (to call preventDefault on the
+ * browser's native caret pick) and the click listener (to actually
+ * insert the paragraph). Factored out so the two handlers stay in sync
+ * — they would otherwise share ~22 lines of byte-for-byte identical
+ * logic and have to be maintained together.
+ *
+ * Read-only because it is called outside an editor.update; mutation
+ * happens in the click handler's editor.update below.
+ */
+function shouldClaimClick(editor, rootElement, event, $shouldInsertAfter) {
+  if (!editor.isEditable()) {
+    return false;
+  }
+  // Only react to clicks on the root container itself. A click inside
+  // an existing block is handled by the normal caret placement path.
+  if (event.target !== rootElement) {
+    return false;
+  }
+  return editor.getEditorState().read(() => {
+    const lastChild = lexical.$getRoot().getLastChild();
+    if (lastChild === null) {
+      return false;
+    }
+    const lastChildDOM = editor.getElementByKey(lastChild.getKey());
+    if (lastChildDOM === null) {
+      return false;
+    }
+    // Exclusive lower edge — clicks at exactly the bottom pixel fall
+    // through to native handling, which is what users expect when
+    // they click on a block's visible bottom border.
+    if (event.clientY <= lastChildDOM.getBoundingClientRect().bottom) {
+      return false;
+    }
+    return $shouldInsertAfter(lastChild);
+  }, {
+    editor
+  });
+}
+
+/**
+ * Click handling for the empty area below the last block of the document.
+ *
+ * Without this extension, clicking the area below the last block when that
+ * block is a {@link DecoratorNode}, a shadow-root ElementNode (e.g.
+ * `TableNode`), or any other block that doesn't accept the click naturally
+ * leaves the selection in an awkward place — `null` for a bare decorator,
+ * or at the end of a table cell. Users typically expect a new paragraph
+ * to appear below the block with the caret in it, matching the behavior
+ * of editors like Notion.
+ *
+ * This extension intercepts clicks under those conditions, inserts a new
+ * empty paragraph after the last block, and selects it.
+ *
+ * Closes #8544.
+ */
+const ClickAfterLastBlockExtension = lexical.defineExtension({
+  build: (_editor, config) => namedSignals(config),
+  config: lexical.safeCast({
+    $shouldInsertAfter: $defaultShouldInsertAfter,
+    disabled: false
+  }),
+  name: '@lexical/ClickAfterLastBlock',
+  register: (editor, _config, _state) => j(() => {
+    const output = _state.getOutput();
+    if (output.disabled.value) {
+      return;
+    }
+    return editor.registerRootListener(rootElement => {
+      if (rootElement === null) {
+        return;
+      }
+      // Two-phase: cancel native caret-pick at the earliest browser
+      // event (mousedown), then claim the click for our own paragraph
+      // insert. Without the mousedown leg the browser places a caret
+      // on the previous text block before our editor.update lands,
+      // visible as a one-frame cursor flicker.
+      //
+      // Side effect to be aware of: cancelling mousedown also cancels
+      // native focus on that click. The subsequent paragraph.select()
+      // inside editor.update DOM-focuses the root through the
+      // reconciler, so the net effect is the same focused root, but
+      // we are now responsible for the focus transition rather than
+      // the browser.
+      //
+      // lexical core has a `pointerdown` listener that flips a
+      // module-level `isSelectionChangeFromMouseDown` flag consumed
+      // on the next selectionchange (LexicalEvents.ts). preventing
+      // mousedown means no native selectionchange fires for this
+      // click, so the flag never gets a chance to be consumed in the
+      // wrong cycle. If you swap mousedown for pointerdown here you
+      // also have to revisit that interaction.
+      const onMouseDown = event => {
+        if (shouldClaimClick(editor, rootElement, event, output.$shouldInsertAfter.peek())) {
+          event.preventDefault();
+        }
+      };
+      const onClick = event => {
+        if (!shouldClaimClick(editor, rootElement, event, output.$shouldInsertAfter.peek())) {
+          return;
+        }
+        event.preventDefault();
+        // Tell lexical's root click handler to skip this event so the
+        // default caret-placement logic in LexicalEvents.onClick exits
+        // early. Without this the previous text block briefly receives
+        // the caret before our paragraph insert lands.
+        lexical.stopLexicalPropagation(event);
+        editor.update(() => {
+          const lastChild = lexical.$getRoot().getLastChild();
+          if (lastChild === null) {
+            return;
+          }
+          // Re-check inside the update — predicate may flip between
+          // read and update if external transforms run.
+          if (!output.$shouldInsertAfter.peek()(lastChild)) {
+            return;
+          }
+          const paragraph = lexical.$createParagraphNode();
+          lastChild.insertAfter(paragraph);
+          paragraph.select();
+        });
+      };
+
+      // Capture phase so the mousedown preventDefault runs before any
+      // bubble-phase handler can react, and so the click flag is set
+      // before lexical core's bubble-phase onClick reads it.
+      rootElement.addEventListener('mousedown', onMouseDown, true);
+      rootElement.addEventListener('click', onClick, true);
+      return () => {
+        rootElement.removeEventListener('mousedown', onMouseDown, true);
+        rootElement.removeEventListener('click', onClick, true);
+      };
+    });
+  })
+});
+
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
@@ -390,6 +561,31 @@ function formatDevErrorMessage(message) {
   throw new Error(message);
 }
 
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+// `"0.45.0+dev.cjs"` is statically replaced with the build-specific
+// version string in a Rollup build, and a consumer's bundler `define` can
+// inject it the same way — so the exact `"0.45.0+dev.cjs"` member
+// expression must be preserved for that substitution to match. Reading it
+// inside a try/catch lets the source be consumed directly (via the `source`
+// export condition) in a browser bundle, where `process` is undefined and
+// nothing replaced the reference, without throwing a ReferenceError; it falls
+// back to the literal below instead. The literal is regenerated by
+// `pnpm run update-version`.
+let envLexicalVersion;
+try {
+  envLexicalVersion = "0.45.0+dev.cjs";
+} catch (_unused) {
+  // `process` is not defined in some browser bundles; use the fallback.
+}
+const LEXICAL_VERSION = envLexicalVersion ?? '0.45.0+source';
+
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
@@ -823,7 +1019,7 @@ function maybeWithBuilder(editor) {
 function normalizeExtensionArgument(arg) {
   return Array.isArray(arg) ? arg : [arg];
 }
-const PACKAGE_VERSION = "0.44.1-nightly.20260519.0+dev.cjs";
+const PACKAGE_VERSION = LEXICAL_VERSION;
 
 /** @internal */
 class LexicalBuilder {
@@ -1151,6 +1347,10 @@ class LexicalBuilder {
  *
  * It will throw if the Editor was not built using this Extension.
  *
+ * Inside an editor read/update, prefer {@link $getExtensionDependency} or
+ * {@link $getExtensionOutput} — they resolve the editor via `$getEditor()`
+ * so you don't have to thread it through.
+ *
  * @param editor - The editor that was built using extension
  * @param extension - The concrete reference to an Extension used to build this editor
  * @returns The config and output for that Extension
@@ -1176,6 +1376,10 @@ function getExtensionDependencyFromEditor(editor, extension) {
  *
  * Both the explicit Extension type and the name are required.
  *
+ * Inside an editor read/update, prefer {@link $getPeerDependency} — it
+ * resolves the editor via `$getEditor()` so you don't have to thread it
+ * through.
+ *
  *  @example
  * ```tsx
  * import type { HistoryExtension } from "@lexical/history";
@@ -1205,6 +1409,10 @@ function getPeerDependencyFromEditor(editor, extensionName) {
  *
  * Both the explicit Extension type and the name are required.
  *
+ * Inside an editor read/update, prefer {@link $getPeerDependency} (which
+ * resolves the editor via `$getEditor()`) and add your own invariant if
+ * the peer is required.
+ *
  *  @example
  * ```tsx
  * import type { EmojiExtension } from "./EmojiExtension";
@@ -1239,6 +1447,96 @@ function getPeerDependencyFromEditorOrThrow(editor, extensionName) {
   return dep;
 }
 
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+
+/**
+ * Get the finalized config and output for `extension` from the editor
+ * currently in scope. A `$`-flavored shorthand for
+ * `getExtensionDependencyFromEditor($getEditor(), extension)`.
+ *
+ * Throws if the editor was not built with `extension` as a dependency.
+ *
+ * @example
+ * ```ts
+ * import {$getExtensionDependency} from '@lexical/extension';
+ * import {KeywordsExtension} from './KeywordsExtension';
+ *
+ * class KeywordNode extends TextNode {
+ *   createDOM(config: EditorConfig): HTMLElement {
+ *     const dom = super.createDOM(config);
+ *     dom.className =
+ *       $getExtensionDependency(KeywordsExtension).config.className;
+ *     return dom;
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link getExtensionDependencyFromEditor} when you have an explicit
+ *   editor reference (e.g. outside a read/update).
+ */
+function $getExtensionDependency(extension) {
+  return getExtensionDependencyFromEditor(lexical.$getEditor(), extension);
+}
+
+/**
+ * Shorthand for `$getExtensionDependency(extension).output` — the most
+ * common reason to look up an extension dependency. Throws if the editor
+ * was not built with `extension` as a dependency.
+ *
+ * @example
+ * ```ts
+ * import {$getExtensionOutput} from '@lexical/extension';
+ * import {DOMImportExtension} from '@lexical/html';
+ *
+ * const nodes = $getExtensionOutput(DOMImportExtension).$generateNodesFromDOM(
+ *   dom,
+ * );
+ * ```
+ *
+ * @see {@link $getExtensionDependency} when you need both `.config` and
+ *   `.output` (or want to mirror the shape of
+ *   {@link getExtensionDependencyFromEditor}).
+ */
+function $getExtensionOutput(extension) {
+  return $getExtensionDependency(extension).output;
+}
+
+/**
+ * Get the finalized config and output for an optional peer extension by
+ * name, from the editor currently in scope. A `$`-flavored shorthand for
+ * `getPeerDependencyFromEditor($getEditor(), extensionName)`.
+ *
+ * Returns `undefined` if the editor was not built with the named
+ * extension. Both the explicit `Extension` type and the name are
+ * required so the returned `config` / `output` types are correct.
+ *
+ * @example
+ * ```ts
+ * import {$getPeerDependency} from '@lexical/extension';
+ * import type {HistoryExtension} from '@lexical/history';
+ *
+ * const dep = $getPeerDependency<typeof HistoryExtension>(
+ *   '@lexical/history/History',
+ * );
+ * if (dep) {
+ *   // …read dep.config / dep.output…
+ * }
+ * ```
+ *
+ * @see {@link getPeerDependencyFromEditor} when you have an explicit
+ *   editor reference.
+ */
+function $getPeerDependency(extensionName) {
+  return getPeerDependencyFromEditor(lexical.$getEditor(), extensionName);
+}
+
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
@@ -1572,6 +1870,113 @@ const NormalizeInlineElementsExtension = lexical.defineExtension({
   }
 });
 
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+const SKIP_TAGS = new Set([lexical.SKIP_SELECTION_FOCUS_TAG, lexical.SKIP_SCROLL_INTO_VIEW_TAG]);
+function $fixFocusOverselection() {
+  const selection = lexical.$getSelection();
+  if (!lexical.$isRangeSelection(selection)) {
+    return;
+  }
+  if (!selection.isCollapsed()) {
+    // Triple click causing selection to overflow into the nearest element. In that
+    // case visually it looks like a single element content is selected, focus node
+    // is actually at the beginning of the next element (if present) and any manipulations
+    // with selection (formatting) are affecting second element as well
+    const range = lexical.$getCaretRangeInDirection(lexical.$caretRangeFromSelection(selection), 'next');
+    let focusCaret = range.focus;
+    // Move it out of the next TextNode if none of it is selected
+    if (lexical.$isTextPointCaret(focusCaret) && range.anchor.origin !== focusCaret.origin && focusCaret.offset === 0) {
+      focusCaret = lexical.$rewindSiblingCaret(focusCaret.getSiblingCaret());
+    }
+    // Move it behind a single LineBreakNode
+    if (lexical.$isSiblingCaret(focusCaret) && range.anchor.origin !== focusCaret.origin && lexical.$isLineBreakNode(focusCaret.origin)) {
+      focusCaret = lexical.$rewindSiblingCaret(focusCaret);
+    }
+    // Move the focus out of the start of any elements
+    while (lexical.$isChildCaret(focusCaret) && range.anchor.origin !== focusCaret.origin) {
+      focusCaret = lexical.$rewindSiblingCaret(lexical.$getSiblingCaret(focusCaret.origin, 'next'));
+    }
+    // Move it inside the containing element
+    if (lexical.$isSiblingCaret(focusCaret) && lexical.$isElementNode(focusCaret.origin)) {
+      focusCaret = lexical.$normalizeCaret(lexical.$getChildCaret(focusCaret.origin, 'previous')).getFlipped();
+    }
+    focusCaret = lexical.$normalizeCaret(focusCaret);
+    if (!focusCaret.isSamePointCaret(range.focus)) {
+      const sel = lexical.$setSelectionFromCaretRange(lexical.$getCaretRange(range.anchor, focusCaret));
+      const editor = lexical.$getEditor();
+      const rootElement = editor.getRootElement();
+      const domSelection = rootElement && lexical.getDOMSelection(rootElement.ownerDocument.defaultView);
+      if (domSelection) {
+        lexical.$updateDOMSelection(lexical.$getPreviousSelection(), sel, lexical.$getEditor(), domSelection, SKIP_TAGS, rootElement);
+      }
+    }
+  }
+}
+
+/**
+ * This extension handles triple-click events and will move the focus
+ * towards the anchor in certain conditions to meet expectations.
+ * Simply speaking, the focus should prefer to land at the end of a node
+ * rather than the beginning of its next sibling, and it should not skip
+ * over a LineBreakNode.
+ *
+ * In order to fix the result visually and avoid a flash of over-selection
+ * it will also eagerly manipulate the DOM selection directly.
+ *
+ * It is conservative in that it only fires this
+ * `$fixFocusOverselection` callback when it has detected a triple click,
+ * but it provides the function as an output signal so that it can both
+ * be called from other places and it can be replaced or wrapped with
+ * different functionality.
+ */
+const NormalizeTripleClickSelectionExtension = lexical.defineExtension({
+  build: (editor, config, state) => namedSignals(config),
+  config: lexical.safeCast({
+    $fixFocusOverselection,
+    dateNow: Date.now,
+    disabled: false,
+    thresholdMsec: 100
+  }),
+  name: '@lexical/NormalizeTripleClickSelection',
+  register: (editor, config, state) => j(() => {
+    const stores = state.getOutput();
+    if (stores.disabled.value) {
+      return;
+    }
+    return editor.registerRootListener(rootElement => {
+      if (!rootElement) {
+        return;
+      }
+      let lastTripleClick = 0;
+      const refreshTripleClick = event => {
+        if (event ? event.detail === 3 : lastTripleClick > 0) {
+          const now = stores.dateNow.peek()();
+          lastTripleClick = event && event.type === 'mousedown' || now - lastTripleClick <= stores.thresholdMsec.peek() ? now : 0;
+        }
+        return lastTripleClick;
+      };
+      return lexical.mergeRegister(editor.registerCommand(lexical.SELECTION_CHANGE_COMMAND, () => {
+        if (refreshTripleClick(null)) {
+          lastTripleClick = 0;
+          stores.$fixFocusOverselection.peek()();
+        }
+        return false;
+      }, lexical.COMMAND_PRIORITY_BEFORE_CRITICAL), (() => {
+        const events = ['mouseup', 'mousedown'];
+        events.forEach(v => rootElement.addEventListener(v, refreshTripleClick, true));
+        return () => events.forEach(v => rootElement.removeEventListener(v, refreshTripleClick, true));
+      })());
+    });
+  })
+});
+
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
@@ -1700,10 +2105,15 @@ exports.defineExtension = lexical.defineExtension;
 exports.safeCast = lexical.safeCast;
 exports.shallowMergeConfig = lexical.shallowMergeConfig;
 exports.$createHorizontalRuleNode = $createHorizontalRuleNode;
+exports.$defaultShouldInsertAfter = $defaultShouldInsertAfter;
+exports.$getExtensionDependency = $getExtensionDependency;
+exports.$getExtensionOutput = $getExtensionOutput;
+exports.$getPeerDependency = $getPeerDependency;
 exports.$isDecoratorTextNode = $isDecoratorTextNode;
 exports.$isHorizontalRuleNode = $isHorizontalRuleNode;
 exports.AutoFocusExtension = AutoFocusExtension;
 exports.ClearEditorExtension = ClearEditorExtension;
+exports.ClickAfterLastBlockExtension = ClickAfterLastBlockExtension;
 exports.DecoratorTextExtension = DecoratorTextExtension;
 exports.DecoratorTextNode = DecoratorTextNode;
 exports.EditorStateExtension = EditorStateExtension;
@@ -1715,6 +2125,7 @@ exports.LexicalBuilder = LexicalBuilder;
 exports.NestedEditorExtension = NestedEditorExtension;
 exports.NodeSelectionExtension = NodeSelectionExtension;
 exports.NormalizeInlineElementsExtension = NormalizeInlineElementsExtension;
+exports.NormalizeTripleClickSelectionExtension = NormalizeTripleClickSelectionExtension;
 exports.SelectionAlwaysOnDisplayExtension = SelectionAlwaysOnDisplayExtension;
 exports.TabIndentationExtension = TabIndentationExtension;
 exports.applyFormatFromStyle = applyFormatFromStyle;