@lexical/list 0.44.1-nightly.20260519.0 → 0.45.1-dev.0

package/src/LexicalListNode.ts

@@ -0,0 +1,393 @@
+/**
+ * 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 {
+  addClassNamesToElement,
+  isHTMLElement,
+  removeClassNamesFromElement,
+} from '@lexical/utils';
+import {
+  $applyNodeReplacement,
+  $createTextNode,
+  $isElementNode,
+  $setDirectionFromDOM,
+  buildImportMap,
+  DOMConversionOutput,
+  DOMExportOutput,
+  EditorConfig,
+  EditorThemeClasses,
+  ElementNode,
+  LexicalEditor,
+  LexicalNode,
+  LexicalUpdateJSON,
+  NodeKey,
+  normalizeClassNames,
+  SerializedElementNode,
+  Spread,
+} from 'lexical';
+
+import {$createListItemNode, $isListItemNode, ListItemNode} from '.';
+import {
+  mergeNextSiblingListIfSameType,
+  updateChildrenListItemValue,
+} from './formatList';
+import {$getListDepth} from './utils';
+
+export type SerializedListNode = Spread<
+  {
+    listType: ListType;
+    start: number;
+    tag: ListNodeTagType;
+  },
+  SerializedElementNode
+>;
+
+export type ListType = 'number' | 'bullet' | 'check';
+
+export type ListNodeTagType = 'ul' | 'ol';
+
+/** @noInheritDoc */
+export class ListNode extends ElementNode {
+  /** @internal */
+  __tag: ListNodeTagType;
+  /** @internal */
+  __start: number;
+  /** @internal */
+  __listType: ListType;
+
+  /** @internal */
+  $config() {
+    return this.config('list', {
+      $transform: (node: ListNode): void => {
+        mergeNextSiblingListIfSameType(node);
+        updateChildrenListItemValue(node);
+      },
+      extends: ElementNode,
+      importDOM: buildImportMap({
+        ol: () => ({
+          conversion: $convertListNode,
+          priority: 0,
+        }),
+        ul: () => ({
+          conversion: $convertListNode,
+          priority: 0,
+        }),
+      }),
+    });
+  }
+
+  constructor(listType: ListType = 'number', start: number = 1, key?: NodeKey) {
+    super(key);
+    const _listType = TAG_TO_LIST_TYPE[listType] || listType;
+    this.__listType = _listType;
+    this.__tag = _listType === 'number' ? 'ol' : 'ul';
+    this.__start = start;
+  }
+
+  afterCloneFrom(prevNode: this): void {
+    super.afterCloneFrom(prevNode);
+    this.__listType = prevNode.__listType;
+    this.__tag = prevNode.__tag;
+    this.__start = prevNode.__start;
+  }
+
+  getTag(): ListNodeTagType {
+    return this.getLatest().__tag;
+  }
+
+  setListType(type: ListType): this {
+    const writable = this.getWritable();
+    writable.__listType = type;
+    writable.__tag = type === 'number' ? 'ol' : 'ul';
+    return writable;
+  }
+
+  getListType(): ListType {
+    return this.getLatest().__listType;
+  }
+
+  getStart(): number {
+    return this.getLatest().__start;
+  }
+
+  setStart(start: number): this {
+    const self = this.getWritable();
+    self.__start = start;
+    return self;
+  }
+
+  // View
+
+  createDOM(config: EditorConfig, _editor?: LexicalEditor): HTMLElement {
+    const tag = this.__tag;
+    const dom = document.createElement(tag);
+
+    if (this.__start !== 1) {
+      dom.setAttribute('start', String(this.__start));
+    }
+    // @ts-expect-error Internal field.
+    dom.__lexicalListType = this.__listType;
+    $setListThemeClassNames(dom, config.theme, this);
+
+    return dom;
+  }
+
+  updateDOM(prevNode: this, dom: HTMLElement, config: EditorConfig): boolean {
+    if (
+      prevNode.__tag !== this.__tag ||
+      prevNode.__listType !== this.__listType
+    ) {
+      return true;
+    }
+
+    $setListThemeClassNames(dom, config.theme, this);
+
+    if (prevNode.__start !== this.__start) {
+      dom.setAttribute('start', String(this.__start));
+    }
+
+    return false;
+  }
+
+  updateFromJSON(serializedNode: LexicalUpdateJSON<SerializedListNode>): this {
+    return super
+      .updateFromJSON(serializedNode)
+      .setListType(serializedNode.listType)
+      .setStart(serializedNode.start);
+  }
+
+  exportDOM(editor: LexicalEditor): DOMExportOutput {
+    const element = this.createDOM(editor._config, editor);
+    if (isHTMLElement(element)) {
+      if (this.__start !== 1) {
+        element.setAttribute('start', String(this.__start));
+      }
+      if (this.__listType === 'check') {
+        element.setAttribute('__lexicalListType', 'check');
+      }
+    }
+    return {
+      element,
+    };
+  }
+
+  exportJSON(): SerializedListNode {
+    return {
+      ...super.exportJSON(),
+      listType: this.getListType(),
+      start: this.getStart(),
+      tag: this.getTag(),
+    };
+  }
+
+  canBeEmpty(): false {
+    return false;
+  }
+
+  canIndent(): false {
+    return false;
+  }
+
+  splice(
+    start: number,
+    deleteCount: number,
+    nodesToInsert: LexicalNode[],
+  ): this {
+    let listItemNodesToInsert = nodesToInsert;
+    for (let i = 0; i < nodesToInsert.length; i++) {
+      const node = nodesToInsert[i];
+      if (!$isListItemNode(node)) {
+        if (listItemNodesToInsert === nodesToInsert) {
+          listItemNodesToInsert = [...nodesToInsert];
+        }
+        listItemNodesToInsert[i] = this.createListItemNode().append(
+          $isElementNode(node) && !($isListNode(node) || node.isInline())
+            ? $createTextNode(node.getTextContent())
+            : node,
+        );
+      }
+    }
+    return super.splice(start, deleteCount, listItemNodesToInsert);
+  }
+
+  extractWithChild(child: LexicalNode): boolean {
+    return $isListItemNode(child);
+  }
+
+  /**
+   * Create an appropriate ListItemNode to be a child of this ListNode,
+   * {@link $createListItemNode} is the default implementation.
+   *
+   * @returns A new ListItemNode.
+   */
+  createListItemNode(): ListItemNode {
+    return $createListItemNode();
+  }
+}
+
+function $setListThemeClassNames(
+  dom: HTMLElement,
+  editorThemeClasses: EditorThemeClasses,
+  node: ListNode,
+): void {
+  const classesToAdd = [];
+  const classesToRemove = [];
+  const listTheme = editorThemeClasses.list;
+
+  if (listTheme !== undefined) {
+    const listLevelsClassNames = listTheme[`${node.__tag}Depth`] || [];
+    const listDepth = $getListDepth(node) - 1;
+    const normalizedListDepth = listDepth % listLevelsClassNames.length;
+    const listLevelClassName = listLevelsClassNames[normalizedListDepth];
+    const listClassName = listTheme[node.__tag];
+    let nestedListClassName;
+    const nestedListTheme = listTheme.nested;
+    const checklistClassName = listTheme.checklist;
+
+    if (nestedListTheme !== undefined && nestedListTheme.list) {
+      nestedListClassName = nestedListTheme.list;
+    }
+
+    if (listClassName !== undefined) {
+      classesToAdd.push(listClassName);
+    }
+
+    if (checklistClassName !== undefined && node.__listType === 'check') {
+      classesToAdd.push(checklistClassName);
+    }
+
+    if (listLevelClassName !== undefined) {
+      classesToAdd.push(...normalizeClassNames(listLevelClassName));
+      for (let i = 0; i < listLevelsClassNames.length; i++) {
+        if (i !== normalizedListDepth) {
+          classesToRemove.push(node.__tag + i);
+        }
+      }
+    }
+
+    if (nestedListClassName !== undefined) {
+      const nestedListItemClasses = normalizeClassNames(nestedListClassName);
+
+      if (listDepth > 1) {
+        classesToAdd.push(...nestedListItemClasses);
+      } else {
+        classesToRemove.push(...nestedListItemClasses);
+      }
+    }
+  }
+
+  if (classesToRemove.length > 0) {
+    removeClassNamesFromElement(dom, ...classesToRemove);
+  }
+
+  if (classesToAdd.length > 0) {
+    addClassNamesToElement(dom, ...classesToAdd);
+  }
+}
+
+/*
+ * This function normalizes the children of a ListNode after the conversion from HTML,
+ * ensuring that they are all ListItemNodes and contain either a single nested ListNode
+ * or some other inline content.
+ */
+function $normalizeChildren(
+  nodes: LexicalNode[],
+  listNode: ListNode,
+): ListItemNode[] {
+  const $createWrapperItem = listNode.createListItemNode.bind(listNode);
+
+  const normalizedListItems: ListItemNode[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    if ($isListItemNode(node)) {
+      normalizedListItems.push(node);
+      const children = node.getChildren();
+      if (children.length > 1) {
+        children.forEach(child => {
+          if ($isListNode(child)) {
+            normalizedListItems.push($createWrapperItem().append(child));
+          }
+        });
+      }
+    } else {
+      normalizedListItems.push($createWrapperItem().append(node));
+    }
+  }
+  return normalizedListItems;
+}
+
+function isDomChecklist(domNode: HTMLElement) {
+  if (
+    domNode.getAttribute('__lexicallisttype') === 'check' ||
+    // is github checklist
+    domNode.classList.contains('contains-task-list') ||
+    // is joplin checklist
+    domNode.getAttribute('data-is-checklist') === '1'
+  ) {
+    return true;
+  }
+  // if children are checklist items, the node is a checklist ul. Applicable for googledoc checklist pasting.
+  for (const child of domNode.childNodes) {
+    if (isHTMLElement(child) && child.hasAttribute('aria-checked')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isHTMLOListElement(node: unknown): node is HTMLOListElement {
+  return isHTMLElement(node) && node.nodeName.toLowerCase() === 'ol';
+}
+
+function $convertListNode(
+  domNode: HTMLOListElement | HTMLUListElement,
+): DOMConversionOutput {
+  let node: ListNode;
+  if (isHTMLOListElement(domNode)) {
+    const start = domNode.start;
+    node = $createListNode('number', start);
+  } else if (isDomChecklist(domNode)) {
+    node = $createListNode('check');
+  } else {
+    node = $createListNode('bullet');
+  }
+  $setDirectionFromDOM(node, domNode);
+  return {
+    after: children => $normalizeChildren(children, node),
+    node,
+  };
+}
+
+const TAG_TO_LIST_TYPE: Record<string, ListType> = {
+  ol: 'number',
+  ul: 'bullet',
+};
+
+/**
+ * Creates a ListNode of listType.
+ * @param listType - The type of list to be created. Can be 'number', 'bullet', or 'check'.
+ * @param start - Where an ordered list starts its count, start = 1 if left undefined.
+ * @returns The new ListNode
+ */
+export function $createListNode(
+  listType: ListType = 'number',
+  start = 1,
+): ListNode {
+  return $applyNodeReplacement(new ListNode(listType, start));
+}
+
+/**
+ * Checks to see if the node is a ListNode.
+ * @param node - The node to be checked.
+ * @returns true if the node is a ListNode, false otherwise.
+ */
+export function $isListNode(
+  node: LexicalNode | null | undefined,
+): node is ListNode {
+  return node instanceof ListNode;
+}

package/src/ListImportExtension.ts

@@ -0,0 +1,319 @@
+/**
+ * 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 type {ChildSchema, DOMImportContext} from '@lexical/html';
+
+import {
+  $isBlockLevel,
+  $propagateTextAlignToBlockChildren,
+  defineImportRule,
+  DOMImportExtension,
+  isElementOfTag,
+  sel,
+} from '@lexical/html';
+import {
+  $createLineBreakNode,
+  $isElementNode,
+  $isParagraphNode,
+  $setDirectionFromDOM,
+  $setFormatFromDOM,
+  configExtension,
+  defineExtension,
+  type LexicalNode,
+} from 'lexical';
+
+import {ListExtension} from './LexicalListExtension';
+import {
+  $createListItemNode,
+  $isListItemNode,
+  type ListItemNode,
+} from './LexicalListItemNode';
+import {$createListNode, $isListNode} from './LexicalListNode';
+
+/**
+ * Mirrors the legacy `isDomChecklist` heuristic from
+ * `@lexical/list`.
+ */
+function isDomChecklist(domNode: HTMLElement): boolean {
+  return (
+    domNode.matches(
+      '[__lexicallisttype="check"], .contains-task-list, [data-is-checklist="1"]',
+    ) || domNode.querySelector(':scope > [aria-checked]') !== null
+  );
+}
+
+/**
+ * Lift nested `ListNode`s out of `ListItemNode`s into sibling
+ * `ListItemNode`s (the legacy `$normalizeChildren` shape). Also wraps any
+ * non-`ListItemNode` children in a new `ListItemNode`.
+ */
+function $normalizeListChildren(children: LexicalNode[]): ListItemNode[] {
+  const out: ListItemNode[] = [];
+  for (const child of children) {
+    if ($isListItemNode(child)) {
+      out.push(child);
+      const innerChildren = child.getChildren();
+      if (innerChildren.length > 1) {
+        for (const inner of innerChildren) {
+          if ($isListNode(inner)) {
+            out.push($createListItemNode().append(inner));
+          }
+        }
+      }
+    } else {
+      out.push($createListItemNode().append(child));
+    }
+  }
+  return out;
+}
+
+const ListRule = defineImportRule({
+  $import: (ctx, el) => {
+    let node;
+    if (isElementOfTag(el, 'ol')) {
+      node = $createListNode('number', el.start);
+    } else if (isDomChecklist(el)) {
+      node = $createListNode('check');
+    } else {
+      node = $createListNode('bullet');
+    }
+    $setDirectionFromDOM(node, el);
+    // Propagate the list's `text-align` onto each `ListItemNode` child
+    // (legacy `wrapContinuousInlines` did the same), so pasting
+    // `<ul style="text-align: left"><li>…</li></ul>` ends up with the
+    // alignment on the list items where the reconciler renders it as
+    // `style="text-align: left"`.
+    return [
+      node.splice(
+        0,
+        0,
+        $propagateTextAlignToBlockChildren(
+          $normalizeListChildren(ctx.$importChildren(el)),
+          el,
+        ),
+      ),
+    ];
+  },
+  match: sel.tag('ol', 'ul'),
+  name: '@lexical/list/list',
+});
+
+/**
+ * Apply formatting from the first child paragraph of `<li>` to the list
+ * item itself, then unwrap that paragraph (Google Docs sets the alignment
+ * of the `<p>` inside the `<li>`). Mirrors the legacy
+ * `setFormatFromChildren`.
+ */
+function $liftFormatFromSingleParagraph(
+  listItemNode: ListItemNode,
+  children: LexicalNode[],
+): LexicalNode[] {
+  if (children.length !== 1) {
+    return children;
+  }
+  const firstChild = children[0];
+  if (
+    $isParagraphNode(firstChild) &&
+    !listItemNode.getFormatType() &&
+    firstChild.getFormatType()
+  ) {
+    listItemNode.setFormat(firstChild.getFormatType());
+    return firstChild.getChildren();
+  }
+  return children;
+}
+
+/**
+ * Collapse block children of a `<li>` into inline-with-line-break form: a
+ * `ListItemNode` is an inline-level container, so any block child marks a
+ * boundary. Contiguous inline siblings are kept together as a single run and
+ * one {@link $createLineBreakNode} is inserted between runs — reproducing the
+ * legacy `wrapContinuousInlines` + `$unwrapArtificialNodes` shape
+ * (`<li>1<div>2</div>3</li>` → `1<br>2<br>3`) without the
+ * `ArtificialNode__DO_NOT_USE` marker.
+ *
+ * Boundaries are detected with {@link $isBlockLevel}, NOT `$isParagraphNode`:
+ * the `<div>`/`<section>`/… `TransparentBlockRule` happens to emit
+ * `ParagraphNode`s, but a `<blockquote>` (`QuoteNode`), heading
+ * (`HeadingNode`), or block decorator (`HorizontalRuleNode`, …) is just as
+ * much a block boundary and must not be silently spliced into the list item
+ * as-is. A nested `ListNode` is the one deliberate exception — it is a valid
+ * list-item child that {@link $normalizeListChildren} lifts into a sibling,
+ * so it is preserved here rather than unwrapped.
+ */
+function $flattenListItemBlocks(children: LexicalNode[]): LexicalNode[] {
+  const $isBoundary = (node: LexicalNode): boolean =>
+    $isBlockLevel(node) && !$isListNode(node);
+  if (!children.some($isBoundary)) {
+    return children;
+  }
+  // Partition into segments — each maximal run of inline siblings, and each
+  // boundary's own content — then join the segments with a single line break.
+  const segments: LexicalNode[][] = [];
+  let inlineRun: LexicalNode[] = [];
+  const flushInlineRun = () => {
+    if (inlineRun.length > 0) {
+      segments.push(inlineRun);
+      inlineRun = [];
+    }
+  };
+  for (const child of children) {
+    if ($isBoundary(child)) {
+      flushInlineRun();
+      // Unwrap a block ElementNode to its inline content; a childless block
+      // DecoratorNode stands on its own line.
+      segments.push($isElementNode(child) ? child.getChildren() : [child]);
+    } else {
+      inlineRun.push(child);
+    }
+  }
+  flushInlineRun();
+  const out: LexicalNode[] = [];
+  for (const segment of segments) {
+    if (out.length > 0) {
+      out.push($createLineBreakNode());
+    }
+    out.push(...segment);
+  }
+  return out;
+}
+
+const ListItemRule = defineImportRule({
+  $import: (ctx, el) => {
+    const ariaChecked = el.getAttribute('aria-checked');
+    const checked =
+      ariaChecked === 'true'
+        ? true
+        : ariaChecked === 'false'
+          ? false
+          : undefined;
+    const node = $createListItemNode(checked);
+    $setFormatFromDOM(node, el);
+    $setDirectionFromDOM(node, el);
+    return [
+      node.splice(
+        0,
+        0,
+        // Lift a sole wrapping paragraph's format onto the item *before*
+        // flattening, otherwise the paragraph would already be unwrapped and
+        // its alignment lost.
+        $flattenListItemBlocks(
+          $liftFormatFromSingleParagraph(node, ctx.$importChildren(el)),
+        ),
+      ),
+    ];
+  },
+  match: sel.tag('li'),
+  name: '@lexical/list/li',
+});
+
+function $buildChecklistItem(
+  ctx: DOMImportContext,
+  el: HTMLElement,
+  checkboxOwner: Element,
+): LexicalNode[] {
+  const checkboxInput = isElementOfTag(checkboxOwner, 'input')
+    ? checkboxOwner
+    : checkboxOwner.querySelector<HTMLInputElement>('input[type="checkbox"]');
+  if (!checkboxInput || checkboxInput.getAttribute('type') !== 'checkbox') {
+    return [];
+  }
+  const checked = checkboxInput.hasAttribute('checked');
+  const node = $createListItemNode(checked);
+  $setFormatFromDOM(node, el);
+  $setDirectionFromDOM(node, el);
+  return [
+    node.splice(
+      0,
+      0,
+      $flattenListItemBlocks(
+        $liftFormatFromSingleParagraph(node, ctx.$importChildren(el)),
+      ),
+    ),
+  ];
+}
+
+const TaskListItemRule = defineImportRule({
+  $import: (ctx, el, $next) => {
+    const input = el.querySelector(':scope > input[type="checkbox"]');
+    if (!input) {
+      return $next();
+    }
+    return $buildChecklistItem(ctx, el, input);
+  },
+  match: sel.tag('li').classAll('task-list-item'),
+  name: '@lexical/list/li-task-list-item',
+});
+
+const JoplinChecklistItemRule = defineImportRule({
+  $import: (ctx, el, $next) => {
+    const wrapper = el.querySelector(':scope > .checkbox-wrapper');
+    if (!wrapper) {
+      return $next();
+    }
+    const input = wrapper.querySelector(':scope > input[type="checkbox"]');
+    if (!input) {
+      return $next();
+    }
+    return $buildChecklistItem(ctx, el, input);
+  },
+  match: sel.tag('li').classAll('joplin-checkbox'),
+  name: '@lexical/list/li-joplin-checkbox',
+});
+
+/**
+ * A {@link ChildSchema} that enforces ListNode invariants: only
+ * `ListItemNode` and (immediately-nested) `ListNode` children are
+ * accepted; runs of other children get wrapped in a fresh
+ * `ListItemNode`.
+ *
+ * @experimental
+ */
+export const ListSchema: ChildSchema = {
+  $accepts: child => $isListItemNode(child) || $isListNode(child),
+  // Inline runs inside a `<ul>`/`<ol>` (e.g. text between two `<li>`s)
+  // become the children of a synthetic `ListItemNode`. `ListItemNode`
+  // is itself a block-level container of inlines, so no intermediate
+  // `ParagraphNode` is needed (and the demoted-paragraph normalization
+  // would strip one anyway).
+  $packageRun: run => [$createListItemNode().splice(0, 0, run)],
+  name: 'ListSchema',
+};
+
+/**
+ * Import rules for {@link ListNode} and {@link ListItemNode}, including
+ * GitHub task-list and Joplin checkbox heuristics.
+ *
+ * @experimental
+ */
+export const ListImportRules = [
+  // More specific rules (class-restricted) must precede the generic `li`
+  // rule so they win the dispatch race (lower array index = higher
+  // priority).
+  TaskListItemRule,
+  JoplinChecklistItemRule,
+  ListRule,
+  ListItemRule,
+];
+
+/**
+ * Bundles {@link ListImportRules} together with the runtime
+ * {@link ListExtension}. The application is expected to already have
+ * `CoreImportExtension` (or some equivalent) in its dependency graph —
+ * the core/text/paragraph/inline-format rules are a shared baseline,
+ * not something this leaf importer should re-declare.
+ *
+ * @experimental
+ */
+export const ListImportExtension = defineExtension({
+  dependencies: [
+    ListExtension,
+    configExtension(DOMImportExtension, {rules: ListImportRules}),
+  ],
+  name: '@lexical/list/Import',
+});