@lexical/clipboard 0.13.0 → 0.14.0

package/LexicalClipboard.dev.esm.js

@@ -0,0 +1,380 @@
+/**
+ * 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 { $generateHtmlFromNodes, $generateNodesFromDOM } from '@lexical/html';
+import { $addNodeStyle, $cloneWithProperties, $sliceSelectedTextNodeContent } from '@lexical/selection';
+import { objectKlassEquals } from '@lexical/utils';
+import { $getSelection, $isRangeSelection, $createTabNode, SELECTION_INSERT_CLIPBOARD_NODES_COMMAND, $getRoot, $parseSerializedNode, $isTextNode, COPY_COMMAND, COMMAND_PRIORITY_CRITICAL, isSelectionWithinEditor, $isElementNode } from '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.
+ *
+ */
+
+const CAN_USE_DOM = typeof window !== 'undefined' && typeof window.document !== 'undefined' && typeof window.document.createElement !== 'undefined';
+
+/**
+ * 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 getDOMSelection = targetWindow => CAN_USE_DOM ? (targetWindow || window).getSelection() : null;
+
+/**
+ * Returns the *currently selected* Lexical content as an HTML string, relying on the
+ * logic defined in the exportDOM methods on the LexicalNode classes. Note that
+ * this will not return the HTML content of the entire editor (unless all the content is included
+ * in the current selection).
+ *
+ * @param editor - LexicalEditor instance to get HTML content from
+ * @returns a string of HTML content
+ */
+function $getHtmlContent(editor) {
+  const selection = $getSelection();
+  if (selection == null) {
+    {
+      throw Error(`Expected valid LexicalSelection`);
+    }
+  }
+
+  // If we haven't selected anything
+  if ($isRangeSelection(selection) && selection.isCollapsed() || selection.getNodes().length === 0) {
+    return '';
+  }
+  return $generateHtmlFromNodes(editor, selection);
+}
+
+/**
+ * Returns the *currently selected* Lexical content as a JSON string, relying on the
+ * logic defined in the exportJSON methods on the LexicalNode classes. Note that
+ * this will not return the JSON content of the entire editor (unless all the content is included
+ * in the current selection).
+ *
+ * @param editor  - LexicalEditor instance to get the JSON content from
+ * @returns
+ */
+function $getLexicalContent(editor) {
+  const selection = $getSelection();
+  if (selection == null) {
+    {
+      throw Error(`Expected valid LexicalSelection`);
+    }
+  }
+
+  // If we haven't selected anything
+  if ($isRangeSelection(selection) && selection.isCollapsed() || selection.getNodes().length === 0) {
+    return null;
+  }
+  return JSON.stringify($generateJSONFromSelectedNodes(editor, selection));
+}
+
+/**
+ * Attempts to insert content of the mime-types text/plain or text/uri-list from
+ * the provided DataTransfer object into the editor at the provided selection.
+ * text/uri-list is only used if text/plain is not also provided.
+ *
+ * @param dataTransfer an object conforming to the [DataTransfer interface] (https://html.spec.whatwg.org/multipage/dnd.html#the-datatransfer-interface)
+ * @param selection the selection to use as the insertion point for the content in the DataTransfer object
+ */
+function $insertDataTransferForPlainText(dataTransfer, selection) {
+  const text = dataTransfer.getData('text/plain') || dataTransfer.getData('text/uri-list');
+  if (text != null) {
+    selection.insertRawText(text);
+  }
+}
+
+/**
+ * Attempts to insert content of the mime-types application/x-lexical-editor, text/html,
+ * text/plain, or text/uri-list (in descending order of priority) from the provided DataTransfer
+ * object into the editor at the provided selection.
+ *
+ * @param dataTransfer an object conforming to the [DataTransfer interface] (https://html.spec.whatwg.org/multipage/dnd.html#the-datatransfer-interface)
+ * @param selection the selection to use as the insertion point for the content in the DataTransfer object
+ * @param editor the LexicalEditor the content is being inserted into.
+ */
+function $insertDataTransferForRichText(dataTransfer, selection, editor) {
+  const lexicalString = dataTransfer.getData('application/x-lexical-editor');
+  if (lexicalString) {
+    try {
+      const payload = JSON.parse(lexicalString);
+      if (payload.namespace === editor._config.namespace && Array.isArray(payload.nodes)) {
+        const nodes = $generateNodesFromSerializedNodes(payload.nodes);
+        return $insertGeneratedNodes(editor, nodes, selection);
+      }
+    } catch (_unused) {
+      // Fail silently.
+    }
+  }
+  const htmlString = dataTransfer.getData('text/html');
+  if (htmlString) {
+    try {
+      const parser = new DOMParser();
+      const dom = parser.parseFromString(htmlString, 'text/html');
+      const nodes = $generateNodesFromDOM(editor, dom);
+      return $insertGeneratedNodes(editor, nodes, selection);
+    } catch (_unused2) {
+      // Fail silently.
+    }
+  }
+
+  // Multi-line plain text in rich text mode pasted as separate paragraphs
+  // instead of single paragraph with linebreaks.
+  // Webkit-specific: Supports read 'text/uri-list' in clipboard.
+  const text = dataTransfer.getData('text/plain') || dataTransfer.getData('text/uri-list');
+  if (text != null) {
+    if ($isRangeSelection(selection)) {
+      const parts = text.split(/(\r?\n|\t)/);
+      if (parts[parts.length - 1] === '') {
+        parts.pop();
+      }
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (part === '\n' || part === '\r\n') {
+          selection.insertParagraph();
+        } else if (part === '\t') {
+          selection.insertNodes([$createTabNode()]);
+        } else {
+          selection.insertText(part);
+        }
+      }
+    } else {
+      selection.insertRawText(text);
+    }
+  }
+}
+
+/**
+ * Inserts Lexical nodes into the editor using different strategies depending on
+ * some simple selection-based heuristics. If you're looking for a generic way to
+ * to insert nodes into the editor at a specific selection point, you probably want
+ * {@link lexical.$insertNodes}
+ *
+ * @param editor LexicalEditor instance to insert the nodes into.
+ * @param nodes The nodes to insert.
+ * @param selection The selection to insert the nodes into.
+ */
+function $insertGeneratedNodes(editor, nodes, selection) {
+  if (!editor.dispatchCommand(SELECTION_INSERT_CLIPBOARD_NODES_COMMAND, {
+    nodes,
+    selection
+  })) {
+    selection.insertNodes(nodes);
+  }
+  return;
+}
+function exportNodeToJSON(node) {
+  const serializedNode = node.exportJSON();
+  const nodeClass = node.constructor;
+  if (serializedNode.type !== nodeClass.getType()) {
+    {
+      throw Error(`LexicalNode: Node ${nodeClass.name} does not implement .exportJSON().`);
+    }
+  }
+  if ($isElementNode(node)) {
+    const serializedChildren = serializedNode.children;
+    if (!Array.isArray(serializedChildren)) {
+      {
+        throw Error(`LexicalNode: Node ${nodeClass.name} is an element but .exportJSON() does not have a children array.`);
+      }
+    }
+  }
+  return serializedNode;
+}
+function $appendNodesToJSON(editor, selection, currentNode, targetArray = []) {
+  let shouldInclude = selection !== null ? currentNode.isSelected(selection) : true;
+  const shouldExclude = $isElementNode(currentNode) && currentNode.excludeFromCopy('html');
+  let target = currentNode;
+  if (selection !== null) {
+    let clone = $cloneWithProperties(currentNode);
+    clone = $isTextNode(clone) && selection !== null ? $sliceSelectedTextNodeContent(selection, clone) : clone;
+    target = clone;
+  }
+  const children = $isElementNode(target) ? target.getChildren() : [];
+  const serializedNode = exportNodeToJSON(target);
+
+  // TODO: TextNode calls getTextContent() (NOT node.__text) within it's exportJSON method
+  // which uses getLatest() to get the text from the original node with the same key.
+  // This is a deeper issue with the word "clone" here, it's still a reference to the
+  // same node as far as the LexicalEditor is concerned since it shares a key.
+  // We need a way to create a clone of a Node in memory with it's own key, but
+  // until then this hack will work for the selected text extract use case.
+  if ($isTextNode(target)) {
+    const text = target.__text;
+    // If an uncollapsed selection ends or starts at the end of a line of specialized,
+    // TextNodes, such as code tokens, we will get a 'blank' TextNode here, i.e., one
+    // with text of length 0. We don't want this, it makes a confusing mess. Reset!
+    if (text.length > 0) {
+      serializedNode.text = text;
+    } else {
+      shouldInclude = false;
+    }
+  }
+  for (let i = 0; i < children.length; i++) {
+    const childNode = children[i];
+    const shouldIncludeChild = $appendNodesToJSON(editor, selection, childNode, serializedNode.children);
+    if (!shouldInclude && $isElementNode(currentNode) && shouldIncludeChild && currentNode.extractWithChild(childNode, selection, 'clone')) {
+      shouldInclude = true;
+    }
+  }
+  if (shouldInclude && !shouldExclude) {
+    targetArray.push(serializedNode);
+  } else if (Array.isArray(serializedNode.children)) {
+    for (let i = 0; i < serializedNode.children.length; i++) {
+      const serializedChildNode = serializedNode.children[i];
+      targetArray.push(serializedChildNode);
+    }
+  }
+  return shouldInclude;
+}
+
+// TODO why $ function with Editor instance?
+/**
+ * Gets the Lexical JSON of the nodes inside the provided Selection.
+ *
+ * @param editor LexicalEditor to get the JSON content from.
+ * @param selection Selection to get the JSON content from.
+ * @returns an object with the editor namespace and a list of serializable nodes as JavaScript objects.
+ */
+function $generateJSONFromSelectedNodes(editor, selection) {
+  const nodes = [];
+  const root = $getRoot();
+  const topLevelChildren = root.getChildren();
+  for (let i = 0; i < topLevelChildren.length; i++) {
+    const topLevelNode = topLevelChildren[i];
+    $appendNodesToJSON(editor, selection, topLevelNode, nodes);
+  }
+  return {
+    namespace: editor._config.namespace,
+    nodes
+  };
+}
+
+/**
+ * This method takes an array of objects conforming to the BaseSeralizedNode interface and returns
+ * an Array containing instances of the corresponding LexicalNode classes registered on the editor.
+ * Normally, you'd get an Array of BaseSerialized nodes from {@link $generateJSONFromSelectedNodes}
+ *
+ * @param serializedNodes an Array of objects conforming to the BaseSerializedNode interface.
+ * @returns an Array of Lexical Node objects.
+ */
+function $generateNodesFromSerializedNodes(serializedNodes) {
+  const nodes = [];
+  for (let i = 0; i < serializedNodes.length; i++) {
+    const serializedNode = serializedNodes[i];
+    const node = $parseSerializedNode(serializedNode);
+    if ($isTextNode(node)) {
+      $addNodeStyle(node);
+    }
+    nodes.push(node);
+  }
+  return nodes;
+}
+const EVENT_LATENCY = 50;
+let clipboardEventTimeout = null;
+
+// TODO custom selection
+// TODO potentially have a node customizable version for plain text
+/**
+ * Copies the content of the current selection to the clipboard in
+ * text/plain, text/html, and application/x-lexical-editor (Lexical JSON)
+ * formats.
+ *
+ * @param editor the LexicalEditor instance to copy content from
+ * @param event the native browser ClipboardEvent to add the content to.
+ * @returns
+ */
+async function copyToClipboard(editor, event) {
+  if (clipboardEventTimeout !== null) {
+    // Prevent weird race conditions that can happen when this function is run multiple times
+    // synchronously. In the future, we can do better, we can cancel/override the previously running job.
+    return false;
+  }
+  if (event !== null) {
+    return new Promise((resolve, reject) => {
+      editor.update(() => {
+        resolve($copyToClipboardEvent(editor, event));
+      });
+    });
+  }
+  const rootElement = editor.getRootElement();
+  const windowDocument = editor._window == null ? window.document : editor._window.document;
+  const domSelection = getDOMSelection(editor._window);
+  if (rootElement === null || domSelection === null) {
+    return false;
+  }
+  const element = windowDocument.createElement('span');
+  element.style.cssText = 'position: fixed; top: -1000px;';
+  element.append(windowDocument.createTextNode('#'));
+  rootElement.append(element);
+  const range = new Range();
+  range.setStart(element, 0);
+  range.setEnd(element, 1);
+  domSelection.removeAllRanges();
+  domSelection.addRange(range);
+  return new Promise((resolve, reject) => {
+    const removeListener = editor.registerCommand(COPY_COMMAND, secondEvent => {
+      if (objectKlassEquals(secondEvent, ClipboardEvent)) {
+        removeListener();
+        if (clipboardEventTimeout !== null) {
+          window.clearTimeout(clipboardEventTimeout);
+          clipboardEventTimeout = null;
+        }
+        resolve($copyToClipboardEvent(editor, secondEvent));
+      }
+      // Block the entire copy flow while we wait for the next ClipboardEvent
+      return true;
+    }, COMMAND_PRIORITY_CRITICAL);
+    // If the above hack execCommand hack works, this timeout code should never fire. Otherwise,
+    // the listener will be quickly freed so that the user can reuse it again
+    clipboardEventTimeout = window.setTimeout(() => {
+      removeListener();
+      clipboardEventTimeout = null;
+      resolve(false);
+    }, EVENT_LATENCY);
+    windowDocument.execCommand('copy');
+    element.remove();
+  });
+}
+
+// TODO shouldn't pass editor (pass namespace directly)
+function $copyToClipboardEvent(editor, event) {
+  const domSelection = getDOMSelection(editor._window);
+  if (!domSelection) {
+    return false;
+  }
+  const anchorDOM = domSelection.anchorNode;
+  const focusDOM = domSelection.focusNode;
+  if (anchorDOM !== null && focusDOM !== null && !isSelectionWithinEditor(editor, anchorDOM, focusDOM)) {
+    return false;
+  }
+  event.preventDefault();
+  const clipboardData = event.clipboardData;
+  const selection = $getSelection();
+  if (clipboardData === null || selection === null) {
+    return false;
+  }
+  const htmlString = $getHtmlContent(editor);
+  const lexicalString = $getLexicalContent(editor);
+  let plainString = '';
+  if (selection !== null) {
+    plainString = selection.getTextContent();
+  }
+  if (htmlString !== null) {
+    clipboardData.setData('text/html', htmlString);
+  }
+  if (lexicalString !== null) {
+    clipboardData.setData('application/x-lexical-editor', lexicalString);
+  }
+  clipboardData.setData('text/plain', plainString);
+  return true;
+}
+
+export { $generateJSONFromSelectedNodes, $generateNodesFromSerializedNodes, $getHtmlContent, $getLexicalContent, $insertDataTransferForPlainText, $insertDataTransferForRichText, $insertGeneratedNodes, copyToClipboard };

package/LexicalClipboard.esm.js

@@ -0,0 +1,17 @@
+/**
+ * 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 * as modDev from './LexicalClipboard.dev.esm.js';
+import * as modProd from './LexicalClipboard.prod.esm.js';
+const mod = process.env.NODE_ENV === 'development' ? modDev : modProd;
+export const $generateJSONFromSelectedNodes = mod.$generateJSONFromSelectedNodes;
+export const $generateNodesFromSerializedNodes = mod.$generateNodesFromSerializedNodes;
+export const $getHtmlContent = mod.$getHtmlContent;
+export const $getLexicalContent = mod.$getLexicalContent;
+export const $insertDataTransferForPlainText = mod.$insertDataTransferForPlainText;
+export const $insertDataTransferForRichText = mod.$insertDataTransferForRichText;
+export const $insertGeneratedNodes = mod.$insertGeneratedNodes;
+export const copyToClipboard = mod.copyToClipboard;

package/LexicalClipboard.js

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 'use strict'
-const LexicalClipboard = process.env.NODE_ENV === 'development' ? require('./LexicalClipboard.dev.js') : require('./LexicalClipboard.prod.js')
+const LexicalClipboard = process.env.NODE_ENV === 'development' ? require('./LexicalClipboard.dev.js') : require('./LexicalClipboard.prod.js');
 module.exports = LexicalClipboard;

package/LexicalClipboard.prod.esm.js

@@ -0,0 +1,7 @@
+/**
+ * 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{$generateHtmlFromNodes as e,$generateNodesFromDOM as t}from"@lexical/html";import{$addNodeStyle as n,$cloneWithProperties as o,$sliceSelectedTextNodeContent as l}from"@lexical/selection";import{objectKlassEquals as r}from"@lexical/utils";import{$getSelection as i,$isRangeSelection as a,$createTabNode as c,SELECTION_INSERT_CLIPBOARD_NODES_COMMAND as s,$getRoot as u,$parseSerializedNode as d,$isTextNode as f,COPY_COMMAND as p,COMMAND_PRIORITY_CRITICAL as m,isSelectionWithinEditor as h,$isElementNode as x}from"lexical";var g=function(e){const t=new URLSearchParams;t.append("code",e);for(let e=1;e<arguments.length;e++)t.append("v",arguments[e]);throw Error(`Minified Lexical error #${e}; visit https://lexical.dev/docs/error?${t} for the full message or use the non-minified dev environment for full errors and additional helpful warnings.`)};const w="undefined"!=typeof window&&void 0!==window.document&&void 0!==window.document.createElement,y=e=>w?(e||window).getSelection():null;function v(t){const n=i();if(null==n)throw Error("Expected valid LexicalSelection");return a(n)&&n.isCollapsed()||0===n.getNodes().length?"":e(t,n)}function D(e){const t=i();if(null==t)throw Error("Expected valid LexicalSelection");return a(t)&&t.isCollapsed()||0===t.getNodes().length?null:JSON.stringify(T(e,t))}function C(e,t){const n=e.getData("text/plain")||e.getData("text/uri-list");null!=n&&t.insertRawText(n)}function E(e,n,o){const l=e.getData("application/x-lexical-editor");if(l)try{const e=JSON.parse(l);if(e.namespace===o._config.namespace&&Array.isArray(e.nodes)){return N(o,_(e.nodes),n)}}catch(e){}const r=e.getData("text/html");if(r)try{const e=(new DOMParser).parseFromString(r,"text/html");return N(o,t(o,e),n)}catch(e){}const i=e.getData("text/plain")||e.getData("text/uri-list");if(null!=i)if(a(n)){const e=i.split(/(\r?\n|\t)/);""===e[e.length-1]&&e.pop();for(let t=0;t<e.length;t++){const o=e[t];"\n"===o||"\r\n"===o?n.insertParagraph():"\t"===o?n.insertNodes([c()]):n.insertText(o)}}else n.insertRawText(i)}function N(e,t,n){e.dispatchCommand(s,{nodes:t,selection:n})||n.insertNodes(t)}function S(e,t,n,r=[]){let i=null===t||n.isSelected(t);const a=x(n)&&n.excludeFromCopy("html");let c=n;if(null!==t){let e=o(n);e=f(e)&&null!==t?l(t,e):e,c=e}const s=x(c)?c.getChildren():[],u=function(e){const t=e.exportJSON(),n=e.constructor;if(t.type!==n.getType()&&g(58,n.name),x(e)){const e=t.children;Array.isArray(e)||g(59,n.name)}return t}(c);if(f(c)){const e=c.__text;e.length>0?u.text=e:i=!1}for(let o=0;o<s.length;o++){const l=s[o],r=S(e,t,l,u.children);!i&&x(n)&&r&&n.extractWithChild(l,t,"clone")&&(i=!0)}if(i&&!a)r.push(u);else if(Array.isArray(u.children))for(let e=0;e<u.children.length;e++){const t=u.children[e];r.push(t)}return i}function T(e,t){const n=[],o=u().getChildren();for(let l=0;l<o.length;l++){S(e,t,o[l],n)}return{namespace:e._config.namespace,nodes:n}}function _(e){const t=[];for(let o=0;o<e.length;o++){const l=e[o],r=d(l);f(r)&&n(r),t.push(r)}return t}let A=null;async function R(e,t){if(null!==A)return!1;if(null!==t)return new Promise(((n,o)=>{e.update((()=>{n(P(e,t))}))}));const n=e.getRootElement(),o=null==e._window?window.document:e._window.document,l=y(e._window);if(null===n||null===l)return!1;const i=o.createElement("span");i.style.cssText="position: fixed; top: -1000px;",i.append(o.createTextNode("#")),n.append(i);const a=new Range;return a.setStart(i,0),a.setEnd(i,1),l.removeAllRanges(),l.addRange(a),new Promise(((t,n)=>{const l=e.registerCommand(p,(n=>(r(n,ClipboardEvent)&&(l(),null!==A&&(window.clearTimeout(A),A=null),t(P(e,n))),!0)),m);A=window.setTimeout((()=>{l(),A=null,t(!1)}),50),o.execCommand("copy"),i.remove()}))}function P(e,t){const n=y(e._window);if(!n)return!1;const o=n.anchorNode,l=n.focusNode;if(null!==o&&null!==l&&!h(e,o,l))return!1;t.preventDefault();const r=t.clipboardData,a=i();if(null===r||null===a)return!1;const c=v(e),s=D(e);let u="";return null!==a&&(u=a.getTextContent()),null!==c&&r.setData("text/html",c),null!==s&&r.setData("application/x-lexical-editor",s),r.setData("text/plain",u),!0}export{T as $generateJSONFromSelectedNodes,_ as $generateNodesFromSerializedNodes,v as $getHtmlContent,D as $getLexicalContent,C as $insertDataTransferForPlainText,E as $insertDataTransferForRichText,N as $insertGeneratedNodes,R as copyToClipboard};

package/README.md

@@ -1,3 +1,5 @@
 # `@lexical/clipboard`
 
+[![See API Documentation](https://lexical.dev/img/see-api-documentation.svg)](https://lexical.dev/docs/api/modules/lexical_clipboard)
+
 This package contains the functionality for the clipboard feature of Lexical.

package/package.json

@@ -9,20 +9,22 @@
     "paste"
   ],
   "license": "MIT",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "main": "LexicalClipboard.js",
   "peerDependencies": {
-    "lexical": "0.13.0"
+    "lexical": "0.14.0"
   },
   "dependencies": {
-    "@lexical/utils": "0.13.0",
-    "@lexical/list": "0.13.0",
-    "@lexical/selection": "0.13.0",
-    "@lexical/html": "0.13.0"
+    "@lexical/utils": "0.14.0",
+    "@lexical/list": "0.14.0",
+    "@lexical/selection": "0.14.0",
+    "@lexical/html": "0.14.0"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/facebook/lexical",
     "directory": "packages/lexical-clipboard"
-  }
+  },
+  "module": "LexicalClipboard.esm.js",
+  "sideEffects": false
 }