@lexical/html 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LexicalHtml.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 {
+  LexicalEditor,
+  LexicalNode,
+  RangeSelection,
+  NodeSelection,
+  GridSelection,
+} from 'lexical';
+
+export function $generateHtmlFromNodes(
+  editor: LexicalEditor,
+  selection?: RangeSelection | NodeSelection | GridSelection | null,
+): string;
+
+export function $generateNodesFromDOM(
+  editor: LexicalEditor,
+  dom: Document,
+): Array<LexicalNode>;

package/LexicalHtml.dev.js

@@ -0,0 +1,192 @@
+/**
+ * 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.
+ */
+'use strict';
+
+var selection = require('@lexical/selection');
+var lexical = require('lexical');
+
+/**
+ * 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.
+ *
+ */
+/**
+ * How you parse your html string to get a document is left up to you. In the browser you can use the native
+ * DOMParser API to generate a document (see clipboard.ts), but to use in a headless environment you can use JSDom
+ * or an equivilant library and pass in the document here.
+ */
+
+function $generateNodesFromDOM(editor, dom) {
+  let lexicalNodes = [];
+  const elements = dom.body ? Array.from(dom.body.childNodes) : [];
+  const elementsLength = elements.length;
+
+  for (let i = 0; i < elementsLength; i++) {
+    const element = elements[i];
+
+    if (!IGNORE_TAGS.has(element.nodeName)) {
+      const lexicalNode = $createNodesFromDOM(element, editor);
+
+      if (lexicalNode !== null) {
+        lexicalNodes = lexicalNodes.concat(lexicalNode);
+      }
+    }
+  }
+
+  return lexicalNodes;
+}
+function $generateHtmlFromNodes(editor, selection) {
+  if (document == null || window == null) {
+    throw new Error('To use $generateHtmlFromNodes in headless mode please initialize a headless browser implementation such as JSDom before calling this function.');
+  }
+
+  const container = document.createElement('div');
+  const root = lexical.$getRoot();
+  const topLevelChildren = root.getChildren();
+
+  for (let i = 0; i < topLevelChildren.length; i++) {
+    const topLevelNode = topLevelChildren[i];
+    $appendNodesToHTML(editor, selection, topLevelNode, container);
+  }
+
+  return container.innerHTML;
+}
+
+function $appendNodesToHTML(editor, selection$1, currentNode, parentElement) {
+  let shouldInclude = selection$1 != null ? currentNode.isSelected() : true;
+  const shouldExclude = lexical.$isElementNode(currentNode) && currentNode.excludeFromCopy('html');
+  let clone = selection.$cloneWithProperties(currentNode);
+  clone = lexical.$isTextNode(clone) && selection$1 != null ? selection.$sliceSelectedTextNodeContent(selection$1, clone) : clone;
+  const children = lexical.$isElementNode(clone) ? clone.getChildren() : [];
+  const {
+    element,
+    after
+  } = clone.exportDOM(editor);
+
+  if (!element) {
+    return false;
+  }
+
+  const fragment = new DocumentFragment();
+
+  for (let i = 0; i < children.length; i++) {
+    const childNode = children[i];
+    const shouldIncludeChild = $appendNodesToHTML(editor, selection$1, childNode, fragment);
+
+    if (!shouldInclude && lexical.$isElementNode(currentNode) && shouldIncludeChild && currentNode.extractWithChild(childNode, selection$1, 'html')) {
+      shouldInclude = true;
+    }
+  }
+
+  if (shouldInclude && !shouldExclude) {
+    element.append(fragment);
+    parentElement.append(element);
+
+    if (after) {
+      const newElement = after.call(clone, element);
+      if (newElement) element.replaceWith(newElement);
+    }
+  } else {
+    parentElement.append(fragment);
+  }
+
+  return shouldInclude;
+}
+
+function getConversionFunction(domNode, editor) {
+  const {
+    nodeName
+  } = domNode;
+
+  const cachedConversions = editor._htmlConversions.get(nodeName.toLowerCase());
+
+  let currentConversion = null;
+
+  if (cachedConversions !== undefined) {
+    cachedConversions.forEach(cachedConversion => {
+      const domConversion = cachedConversion(domNode);
+
+      if (domConversion !== null) {
+        if (currentConversion === null || currentConversion.priority < domConversion.priority) {
+          currentConversion = domConversion;
+        }
+      }
+    });
+  }
+
+  return currentConversion !== null ? currentConversion.conversion : null;
+}
+
+const IGNORE_TAGS = new Set(['STYLE']);
+
+function $createNodesFromDOM(node, editor, forChildMap = new Map(), parentLexicalNode) {
+  let lexicalNodes = [];
+
+  if (IGNORE_TAGS.has(node.nodeName)) {
+    return lexicalNodes;
+  }
+
+  let currentLexicalNode = null;
+  const transformFunction = getConversionFunction(node, editor);
+  const transformOutput = transformFunction ? transformFunction(node) : null;
+  let postTransform = null;
+
+  if (transformOutput !== null) {
+    postTransform = transformOutput.after;
+    currentLexicalNode = transformOutput.node;
+
+    if (currentLexicalNode !== null) {
+      for (const [, forChildFunction] of forChildMap) {
+        currentLexicalNode = forChildFunction(currentLexicalNode, parentLexicalNode);
+
+        if (!currentLexicalNode) {
+          break;
+        }
+      }
+
+      if (currentLexicalNode) {
+        lexicalNodes.push(currentLexicalNode);
+      }
+    }
+
+    if (transformOutput.forChild != null) {
+      forChildMap.set(node.nodeName, transformOutput.forChild);
+    }
+  } // If the DOM node doesn't have a transformer, we don't know what
+  // to do with it but we still need to process any childNodes.
+
+
+  const children = node.childNodes;
+  let childLexicalNodes = [];
+
+  for (let i = 0; i < children.length; i++) {
+    childLexicalNodes.push(...$createNodesFromDOM(children[i], editor, new Map(forChildMap), currentLexicalNode));
+  }
+
+  if (postTransform != null) {
+    childLexicalNodes = postTransform(childLexicalNodes);
+  }
+
+  if (currentLexicalNode == null) {
+    // If it hasn't been converted to a LexicalNode, we hoist its children
+    // up to the same level as it.
+    lexicalNodes = lexicalNodes.concat(childLexicalNodes);
+  } else {
+    if (lexical.$isElementNode(currentLexicalNode)) {
+      // If the current node is a ElementNode after conversion,
+      // we can append all the children to it.
+      currentLexicalNode.append(...childLexicalNodes);
+    }
+  }
+
+  return lexicalNodes;
+}
+
+exports.$generateHtmlFromNodes = $generateHtmlFromNodes;
+exports.$generateNodesFromDOM = $generateNodesFromDOM;

package/LexicalHtml.js

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+'use strict'
+const LexicalHtml = process.env.NODE_ENV === 'development' ? require('./LexicalHtml.dev.js') : require('./LexicalHtml.prod.js')
+module.exports = LexicalHtml;

package/LexicalHtml.js.flow

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ *
+ * @flow strict
+ */
+
+import type {
+  LexicalEditor,
+  LexicalNode,
+  EditorState,
+  EditorThemeClasses,
+  RangeSelection,
+  NodeSelection,
+  GridSelection,
+} from 'lexical';
+
+declare export function $generateHtmlFromNodes(
+  editor: LexicalEditor,
+  selection?: RangeSelection | NodeSelection | GridSelection | null,
+): string;
+
+declare export function $generateNodesFromDOM(
+  editor: LexicalEditor,
+  dom: Document,
+): Array<LexicalNode>;

package/LexicalHtml.prod.js

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+'use strict';var l=require("@lexical/selection"),p=require("lexical");
+function q(d,b,e,c){let a=null!=b?e.isSelected():!0,f=p.$isElementNode(e)&&e.excludeFromCopy("html"),g=l.$cloneWithProperties(e);g=p.$isTextNode(g)&&null!=b?l.$sliceSelectedTextNodeContent(b,g):g;let k=p.$isElementNode(g)?g.getChildren():[],{element:h,after:r}=g.exportDOM(d);if(!h)return!1;let m=new DocumentFragment;for(let n=0;n<k.length;n++){let t=k[n],w=q(d,b,t,m);!a&&p.$isElementNode(e)&&w&&e.extractWithChild(t,b,"html")&&(a=!0)}a&&!f?(h.append(m),c.append(h),r&&(d=r.call(g,h))&&h.replaceWith(d)):
+c.append(m);return a}function u(d,b){let {nodeName:e}=d;b=b._htmlConversions.get(e.toLowerCase());let c=null;void 0!==b&&b.forEach(a=>{a=a(d);null!==a&&(null===c||c.priority<a.priority)&&(c=a)});return null!==c?c.conversion:null}let v=new Set(["STYLE"]);
+function x(d,b,e=new Map,c){let a=[];if(v.has(d.nodeName))return a;let f=null;var g=u(d,b);let k=g?g(d):null;g=null;if(null!==k){g=k.after;f=k.node;if(null!==f){for(var [,h]of e)if(f=h(f,c),!f)break;f&&a.push(f)}null!=k.forChild&&e.set(d.nodeName,k.forChild)}d=d.childNodes;c=[];for(h=0;h<d.length;h++)c.push(...x(d[h],b,new Map(e),f));null!=g&&(c=g(c));null==f?a=a.concat(c):p.$isElementNode(f)&&f.append(...c);return a}
+exports.$generateHtmlFromNodes=function(d,b){if(null==document||null==window)throw Error("To use $generateHtmlFromNodes in headless mode please initialize a headless browser implementation such as JSDom before calling this function.");let e=document.createElement("div"),c=p.$getRoot().getChildren();for(let a=0;a<c.length;a++)q(d,b,c[a],e);return e.innerHTML};
+exports.$generateNodesFromDOM=function(d,b){let e=[];b=b.body?Array.from(b.body.childNodes):[];let c=b.length;for(let f=0;f<c;f++){var a=b[f];v.has(a.nodeName)||(a=x(a,d),null!==a&&(e=e.concat(a)))}return e}

package/README.md

@@ -0,0 +1,35 @@
+# `@lexical/html`
+
+# HTML
+This package exports utility functions for converting `Lexical` -> `HTML` and `HTML` -> `Lexical`. These same functions are also used in the `lexical-clipboard` package for copy and paste.
+
+[Full documentation can be found here.](https://lexical.dev/docs/concepts/serialization)
+
+### Exporting
+```js
+// When converting to HTML you can pass in a selection object to narrow it
+// down to a certain part of the editor's contents.
+const htmlString = $generateHtmlFromNodes(editor, selection | null);
+```
+
+### Importing
+First we need to parse the HTML string into a DOM instance.
+```js
+// In the browser you can use the native DOMParser API to parse the HTML string.
+const parser = new DOMParser();
+const dom = parser.parseFromString(htmlString, textHtmlMimeType);
+
+// In a headless environment you can use a package such as JSDom to parse the HTML string.
+const dom = new JSDOM(htmlString);
+```
+And once you have the DOM instance.
+```js
+const nodes = $generateNodesFromDOM(editor, dom);
+
+// Once you have the lexical nodes you can initialize an editor instance with the parsed nodes.
+const editor = createEditor({ ...config, nodes });
+
+// Or insert them at a selection.
+const selection = $getSelection();
+selection.insertNodes(nodes);
+```

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@lexical/html",
+  "description": "This package contains HTML helpers and functionality for Lexical.",
+  "keywords": [
+    "lexical",
+    "editor",
+    "rich-text",
+    "html"
+  ],
+  "license": "MIT",
+  "version": "0.3.0",
+  "main": "LexicalHtml.js",
+  "peerDependencies": {
+    "lexical": "0.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/lexical",
+    "directory": "packages/lexical-html"
+  }
+}