@lobehub/editor 3.3.2 → 3.4.0

package/es/editor-kernel/lexical/LexicalSelection.d.ts

@@ -0,0 +1,368 @@
+/**
+ * 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 { TextNode } from '.';
+import type { LexicalEditor } from './LexicalEditor';
+import type { EditorState } from './LexicalEditorState';
+import type { NodeKey } from './LexicalNode';
+import { LexicalNode } from './LexicalNode';
+import type { ElementNode } from './nodes/LexicalElementNode';
+import type { TextFormatType } from './nodes/LexicalTextNode';
+
+export type TextPointType = {
+  _selection: BaseSelection;
+  getNode: () => TextNode;
+  is: (point: PointType) => boolean;
+  isBefore: (point: PointType) => boolean;
+  key: NodeKey;
+  offset: number;
+  set: (key: NodeKey, offset: number, type: 'text' | 'element', onlyIfChanged?: boolean) => void;
+  type: 'text';
+};
+export type ElementPointType = {
+  _selection: BaseSelection;
+  getNode: () => ElementNode;
+  is: (point: PointType) => boolean;
+  isBefore: (point: PointType) => boolean;
+  key: NodeKey;
+  offset: number;
+  set: (key: NodeKey, offset: number, type: 'text' | 'element', onlyIfChanged?: boolean) => void;
+  type: 'element';
+};
+export type PointType = TextPointType | ElementPointType;
+export declare class Point {
+  key: NodeKey;
+  offset: number;
+  type: 'text' | 'element';
+  _selection: BaseSelection | null;
+  constructor(key: NodeKey, offset: number, type: 'text' | 'element');
+  is(point: PointType): boolean;
+  isBefore(b: PointType): boolean;
+  getNode(): LexicalNode;
+  set(key: NodeKey, offset: number, type: 'text' | 'element', onlyIfChanged?: boolean): void;
+}
+export declare function $createPoint(
+  key: NodeKey,
+  offset: number,
+  type: 'text' | 'element',
+): PointType;
+export declare function $moveSelectionPointToEnd(point: PointType, node: LexicalNode): void;
+export interface BaseSelection {
+  _cachedNodes: Array<LexicalNode> | null;
+  dirty: boolean;
+  clone(): BaseSelection;
+  extract(): Array<LexicalNode>;
+  getNodes(): Array<LexicalNode>;
+  getTextContent(): string;
+  insertText(text: string): void;
+  insertRawText(text: string): void;
+  is(selection: null | BaseSelection): boolean;
+  insertNodes(nodes: Array<LexicalNode>): void;
+  getStartEndPoints(): null | [PointType, PointType];
+  isCollapsed(): boolean;
+  isBackward(): boolean;
+  getCachedNodes(): LexicalNode[] | null;
+  setCachedNodes(nodes: LexicalNode[] | null): void;
+}
+export declare class NodeSelection implements BaseSelection {
+  _nodes: Set<NodeKey>;
+  _cachedNodes: Array<LexicalNode> | null;
+  dirty: boolean;
+  constructor(objects: Set<NodeKey>);
+  getCachedNodes(): LexicalNode[] | null;
+  setCachedNodes(nodes: LexicalNode[] | null): void;
+  is(selection: null | BaseSelection): boolean;
+  isCollapsed(): boolean;
+  isBackward(): boolean;
+  getStartEndPoints(): null;
+  add(key: NodeKey): void;
+  delete(key: NodeKey): void;
+  clear(): void;
+  has(key: NodeKey): boolean;
+  clone(): NodeSelection;
+  extract(): Array<LexicalNode>;
+  insertRawText(text: string): void;
+  insertText(): void;
+  insertNodes(nodes: Array<LexicalNode>): void;
+  getNodes(): Array<LexicalNode>;
+  getTextContent(): string;
+  /**
+   * Remove all nodes in the NodeSelection. If there were any nodes,
+   * replace the selection with a new RangeSelection at the previous
+   * location of the first node.
+   */
+  deleteNodes(): void;
+}
+export declare function $isRangeSelection(x: unknown): x is RangeSelection;
+export declare class RangeSelection implements BaseSelection {
+  format: number;
+  style: string;
+  anchor: PointType;
+  focus: PointType;
+  _cachedNodes: Array<LexicalNode> | null;
+  dirty: boolean;
+  constructor(anchor: PointType, focus: PointType, format: number, style: string);
+  getCachedNodes(): LexicalNode[] | null;
+  setCachedNodes(nodes: LexicalNode[] | null): void;
+  /**
+   * Used to check if the provided selections is equal to this one by value,
+   * including anchor, focus, format, and style properties.
+   * @param selection - the Selection to compare this one to.
+   * @returns true if the Selections are equal, false otherwise.
+   */
+  is(selection: null | BaseSelection): boolean;
+  /**
+   * Returns whether the Selection is "collapsed", meaning the anchor and focus are
+   * the same node and have the same offset.
+   *
+   * @returns true if the Selection is collapsed, false otherwise.
+   */
+  isCollapsed(): boolean;
+  /**
+   * Gets all the nodes in the Selection. Uses caching to make it generally suitable
+   * for use in hot paths.
+   *
+   * See also the {@link CaretRange} APIs (starting with
+   * {@link $caretRangeFromSelection}), which are likely to provide a better
+   * foundation for any operation where partial selection is relevant
+   * (e.g. the anchor or focus are inside an ElementNode and TextNode)
+   *
+   * @returns an Array containing all the nodes in the Selection
+   */
+  getNodes(): Array<LexicalNode>;
+  /**
+   * Sets this Selection to be of type "text" at the provided anchor and focus values.
+   *
+   * @param anchorNode - the anchor node to set on the Selection
+   * @param anchorOffset - the offset to set on the Selection
+   * @param focusNode - the focus node to set on the Selection
+   * @param focusOffset - the focus offset to set on the Selection
+   */
+  setTextNodeRange(
+    anchorNode: TextNode,
+    anchorOffset: number,
+    focusNode: TextNode,
+    focusOffset: number,
+  ): void;
+  /**
+   * Gets the (plain) text content of all the nodes in the selection.
+   *
+   * @returns a string representing the text content of all the nodes in the Selection
+   */
+  getTextContent(): string;
+  /**
+   * Attempts to map a DOM selection range onto this Lexical Selection,
+   * setting the anchor, focus, and type accordingly
+   *
+   * @param range a DOM Selection range conforming to the StaticRange interface.
+   */
+  applyDOMRange(range: StaticRange): void;
+  /**
+   * Creates a new RangeSelection, copying over all the property values from this one.
+   *
+   * @returns a new RangeSelection with the same property values as this one.
+   */
+  clone(): RangeSelection;
+  /**
+   * Toggles the provided format on all the TextNodes in the Selection.
+   *
+   * @param format a string TextFormatType to toggle on the TextNodes in the selection
+   */
+  toggleFormat(format: TextFormatType): void;
+  /**
+   * Sets the value of the format property on the Selection
+   *
+   * @param format - the format to set at the value of the format property.
+   */
+  setFormat(format: number): void;
+  /**
+   * Sets the value of the style property on the Selection
+   *
+   * @param style - the style to set at the value of the style property.
+   */
+  setStyle(style: string): void;
+  /**
+   * Returns whether the provided TextFormatType is present on the Selection. This will be true if any node in the Selection
+   * has the specified format.
+   *
+   * @param type the TextFormatType to check for.
+   * @returns true if the provided format is currently toggled on on the Selection, false otherwise.
+   */
+  hasFormat(type: TextFormatType): boolean;
+  /**
+   * Attempts to insert the provided text into the EditorState at the current Selection.
+   * converts tabs, newlines, and carriage returns into LexicalNodes.
+   *
+   * @param text the text to insert into the Selection
+   */
+  insertRawText(text: string): void;
+  /**
+   * Insert the provided text into the EditorState at the current Selection.
+   *
+   * @param text the text to insert into the Selection
+   */
+  insertText(text: string): void;
+  /**
+   * Removes the text in the Selection, adjusting the EditorState accordingly.
+   */
+  removeText(): void;
+  /**
+   * Applies the provided format to the TextNodes in the Selection, splitting or
+   * merging nodes as necessary.
+   *
+   * @param formatType the format type to apply to the nodes in the Selection.
+   * @param alignWithFormat a 32-bit integer representing formatting flags to align with.
+   */
+  formatText(formatType: TextFormatType, alignWithFormat?: number | null): void;
+  /**
+   * Attempts to "intelligently" insert an arbitrary list of Lexical nodes into the EditorState at the
+   * current Selection according to a set of heuristics that determine how surrounding nodes
+   * should be changed, replaced, or moved to accommodate the incoming ones.
+   *
+   * @param nodes - the nodes to insert
+   */
+  insertNodes(nodes: Array<LexicalNode>): void;
+  /**
+   * Inserts a new ParagraphNode into the EditorState at the current Selection
+   *
+   * @returns the newly inserted node.
+   */
+  insertParagraph(): ElementNode | null;
+  /**
+   * Inserts a logical linebreak, which may be a new LineBreakNode or a new ParagraphNode, into the EditorState at the
+   * current Selection.
+   */
+  insertLineBreak(selectStart?: boolean): void;
+  /**
+   * Extracts the nodes in the Selection, splitting nodes where necessary
+   * to get offset-level precision.
+   *
+   * @returns The nodes in the Selection
+   */
+  extract(): Array<LexicalNode>;
+  /**
+   * Modifies the Selection according to the parameters and a set of heuristics that account for
+   * various node types. Can be used to safely move or extend selection by one logical "unit" without
+   * dealing explicitly with all the possible node types.
+   *
+   * @param alter the type of modification to perform
+   * @param isBackward whether or not selection is backwards
+   * @param granularity the granularity at which to apply the modification
+   */
+  modify(
+    alter: 'move' | 'extend',
+    isBackward: boolean,
+    granularity: 'character' | 'word' | 'lineboundary',
+  ): void;
+  /**
+   * Helper for handling forward character and word deletion that prevents element nodes
+   * like a table, columns layout being destroyed
+   *
+   * @param anchor the anchor
+   * @param anchorNode the anchor node in the selection
+   * @param isBackward whether or not selection is backwards
+   */
+  forwardDeletion(
+    anchor: PointType,
+    anchorNode: TextNode | ElementNode,
+    isBackward: boolean,
+  ): boolean;
+  /**
+   * Performs one logical character deletion operation on the EditorState based on the current Selection.
+   * Handles different node types.
+   *
+   * @param isBackward whether or not the selection is backwards.
+   */
+  deleteCharacter(isBackward: boolean): void;
+  /**
+   * Performs one logical line deletion operation on the EditorState based on the current Selection.
+   * Handles different node types.
+   *
+   * @param isBackward whether or not the selection is backwards.
+   */
+  deleteLine(isBackward: boolean): void;
+  /**
+   * Performs one logical word deletion operation on the EditorState based on the current Selection.
+   * Handles different node types.
+   *
+   * @param isBackward whether or not the selection is backwards.
+   */
+  deleteWord(isBackward: boolean): void;
+  /**
+   * Returns whether the Selection is "backwards", meaning the focus
+   * logically precedes the anchor in the EditorState.
+   * @returns true if the Selection is backwards, false otherwise.
+   */
+  isBackward(): boolean;
+  getStartEndPoints(): null | [PointType, PointType];
+}
+export declare function $isNodeSelection(x: unknown): x is NodeSelection;
+export declare function $getCharacterOffsets(selection: BaseSelection): [number, number];
+export declare function $isBlockElementNode(
+  node: LexicalNode | null | undefined,
+): node is ElementNode;
+export declare function $internalMakeRangeSelection(
+  anchorKey: NodeKey,
+  anchorOffset: number,
+  focusKey: NodeKey,
+  focusOffset: number,
+  anchorType: 'text' | 'element',
+  focusType: 'text' | 'element',
+): RangeSelection;
+export declare function $createRangeSelection(): RangeSelection;
+export declare function $createNodeSelection(): NodeSelection;
+export declare function $internalCreateSelection(
+  editor: LexicalEditor,
+  event: UIEvent | Event | null,
+): null | BaseSelection;
+export declare function $createRangeSelectionFromDom(
+  domSelection: Selection | null,
+  editor: LexicalEditor,
+): null | RangeSelection;
+export declare function $internalCreateRangeSelection(
+  lastSelection: null | BaseSelection,
+  domSelection: Selection | null,
+  editor: LexicalEditor,
+  event: UIEvent | Event | null,
+): null | RangeSelection;
+export declare function $getSelection(): null | BaseSelection;
+export declare function $getPreviousSelection(): null | BaseSelection;
+export declare function $updateElementSelectionOnCreateDeleteNode(
+  selection: RangeSelection,
+  parentNode: LexicalNode,
+  nodeOffset: number,
+  times?: number,
+): void;
+export declare function applySelectionTransforms(
+  nextEditorState: EditorState,
+  editor: LexicalEditor,
+): void;
+export declare function moveSelectionPointToSibling(
+  point: PointType,
+  node: LexicalNode,
+  parent: ElementNode,
+  prevSibling: LexicalNode | null,
+  nextSibling: LexicalNode | null,
+): void;
+export declare function adjustPointOffsetForMergedSibling(
+  point: PointType,
+  isBefore: boolean,
+  key: NodeKey,
+  target: TextNode,
+  textLength: number,
+): void;
+export declare function updateDOMSelection(
+  prevSelection: BaseSelection | null,
+  nextSelection: BaseSelection | null,
+  editor: LexicalEditor,
+  domSelection: Selection,
+  tags: Set<string>,
+  rootElement: HTMLElement,
+  nodeCount: number,
+): void;
+export declare function $insertNodes(nodes: Array<LexicalNode>): void;
+export declare function $getTextContent(): string;

package/es/editor-kernel/lexical/LexicalUpdateTags.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ *
+ */
+/**
+ * Common update tags used in Lexical. These tags can be used with editor.update() or $addUpdateTag()
+ * to indicate the type/purpose of an update. Multiple tags can be used in a single update.
+ */
+/**
+ * Indicates that the update is related to history operations (undo/redo)
+ */
+export declare const HISTORIC_TAG = 'historic';
+/**
+ * Indicates that a new history entry should be pushed to the history stack
+ */
+export declare const HISTORY_PUSH_TAG = 'history-push';
+/**
+ * Indicates that the current update should be merged with the previous history entry
+ */
+export declare const HISTORY_MERGE_TAG = 'history-merge';
+/**
+ * Indicates that the update is related to a paste operation
+ */
+export declare const PASTE_TAG = 'paste';
+/**
+ * Indicates that the update is related to collaborative editing
+ */
+export declare const COLLABORATION_TAG = 'collaboration';
+/**
+ * Indicates that the update should skip collaborative sync
+ */
+export declare const SKIP_COLLAB_TAG = 'skip-collab';
+/**
+ * Indicates that the update should skip scrolling the selection into view
+ */
+export declare const SKIP_SCROLL_INTO_VIEW_TAG = 'skip-scroll-into-view';
+/**
+ * Indicates that the update should skip updating the DOM selection
+ * This is useful when you want to make updates without changing the selection or focus
+ */
+export declare const SKIP_DOM_SELECTION_TAG = 'skip-dom-selection';
+/**
+ * Indicates that after changing the selection, the editor should not focus itself
+ * This tag is ignored if {@link SKIP_DOM_SELECTION_TAG} is used
+ */
+export declare const SKIP_SELECTION_FOCUS_TAG = 'skip-selection-focus';
+/**
+ * The update was triggered by editor.focus()
+ */
+export declare const FOCUS_TAG = 'focus';
+/**
+ * The set of known update tags to help with TypeScript suggestions.
+ */
+export type UpdateTag =
+  | typeof COLLABORATION_TAG
+  | typeof FOCUS_TAG
+  | typeof HISTORIC_TAG
+  | typeof HISTORY_MERGE_TAG
+  | typeof HISTORY_PUSH_TAG
+  | typeof PASTE_TAG
+  | typeof SKIP_COLLAB_TAG
+  | typeof SKIP_DOM_SELECTION_TAG
+  | typeof SKIP_SCROLL_INTO_VIEW_TAG
+  | (string & {});

package/es/editor-kernel/lexical/LexicalUpdates.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 {
+  CommandPayloadType,
+  EditorUpdateOptions,
+  LexicalCommand,
+  LexicalEditor,
+  SetListeners,
+  Transform,
+} from './LexicalEditor';
+import type { SerializedEditorState } from './LexicalEditorState';
+import { EditorState } from './LexicalEditorState';
+import type { LexicalNode, SerializedLexicalNode } from './LexicalNode';
+
+export declare function isCurrentlyReadOnlyMode(): boolean;
+export declare function errorOnReadOnly(): void;
+export declare function errorOnInfiniteTransforms(): void;
+export declare function getActiveEditorState(): EditorState;
+export declare function getActiveEditor(): LexicalEditor;
+export declare function internalGetActiveEditor(): LexicalEditor | null;
+export declare function internalGetActiveEditorState(): EditorState | null;
+export declare function $applyTransforms(
+  editor: LexicalEditor,
+  node: LexicalNode,
+  transformsCache: Map<string, Array<Transform<LexicalNode>>>,
+): void;
+export declare function $parseSerializedNode(serializedNode: SerializedLexicalNode): LexicalNode;
+export declare function parseEditorState(
+  serializedEditorState: SerializedEditorState,
+  editor: LexicalEditor,
+  updateFn: void | ((editorState: EditorState) => void),
+): EditorState;
+export declare function readEditorState<V>(
+  editor: LexicalEditor | null,
+  editorState: EditorState,
+  callbackFn: () => V,
+): V;
+export declare function $commitPendingUpdates(
+  editor: LexicalEditor,
+  recoveryEditorState?: EditorState,
+): void;
+export declare function triggerListeners<T extends keyof SetListeners>(
+  type: T,
+  editor: LexicalEditor,
+  isCurrentlyEnqueuingUpdates: boolean,
+  ...payload: SetListeners[T]
+): void;
+export declare function triggerCommandListeners<TCommand extends LexicalCommand<unknown>>(
+  editor: LexicalEditor,
+  type: TCommand,
+  payload: CommandPayloadType<TCommand>,
+): boolean;
+/**
+ * A variant of updateEditor that will not defer if it is nested in an update
+ * to the same editor, much like if it was an editor.dispatchCommand issued
+ * within an update
+ */
+export declare function updateEditorSync(
+  editor: LexicalEditor,
+  updateFn: () => void,
+  options?: EditorUpdateOptions,
+): void;
+export declare function updateEditor(
+  editor: LexicalEditor,
+  updateFn: () => void,
+  options?: EditorUpdateOptions,
+): void;