@37signals/lexxy 0.1.9-beta → 0.1.10-beta

package/README.md

@@ -341,9 +341,84 @@ The sandbox app is available at http://localhost:3000. There is also a CRUD exam
 
 ## Events
 
-* `lexxy:initialize`: Fired whenever the `<lexxy-editor>` element is attached to the DOM and is ready for use.
-* `lexxy:change`: Fired whenever the editor content changes.
-* `lexxy:file-accept`: Fired whenever a file is dropped or inserted into the editor. You can access the `File` object through the `event.detail.file` property. Call `preventDefault` on the event to cancel upload and prevent attaching the file.
+Lexxy fires a handful of custom events that you can hook into.
+Each event is dispatched on the `<lexxy-editor>` element.
+
+### `lexxy:initialize`
+
+Fired when the `<lexxy-editor>` element is attached to the DOM and ready for use.
+This is useful for one-time setup.
+
+### `lexxy:change`
+
+Fired whenever the editor content changes.
+You can use this to sync the editor state with your application.
+
+### `lexxy:file-accept`
+
+Fired when a file is dropped or inserted into the editor.
+
+- Access the file via `event.detail.file`.
+- Call `event.preventDefault()` to cancel the upload and prevent attaching the file.
+
+### `lexxy:insert-link`
+
+Fired when a plain text link is pasted into the editor.
+Access the link’s URL via `event.detail.url`.
+
+You also get a handful of callback helpers on `event.detail`:
+
+- **`replaceLinkWith(html, options)`** – replace the pasted link with your own HTML.
+- **`insertBelowLink(html, options)`** – insert custom HTML below the link.
+- **Attachment rendering** – pass `{ attachment: true }` in `options` to render as non-editable content,
+  or `{ attachment: { sgid: "your-sgid-here" } }` to provide a custom SGID.
+
+#### Example: Link Unfurling with Stimulus
+
+When a user pastes a link, you may want to turn it into a preview or embed.
+Here’s a Stimulus controller that sends the URL to your app, retrieves metadata,
+and replaces the plain text link with a richer version:
+
+```javascript
+// app/javascript/controllers/link_unfurl_controller.js
+import { Controller } from "@hotwired/stimulus"
+import { post } from "@rails/request.js"
+
+export default class extends Controller {
+  static values = {
+    url: String, // endpoint that handles unfurling
+  }
+
+  unfurl(event) {
+    this.#unfurlLink(event.detail.url, event.detail)
+  }
+
+  async #unfurlLink(url, callbacks) {
+    const { response } = await post(this.urlValue, {
+      body: JSON.stringify({ url }),
+      headers: {
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      }
+    })
+
+    const metadata = await response.json()
+    this.#insertUnfurledLink(metadata, callbacks)
+  }
+
+  #insertUnfurledLink(metadata, callbacks) {
+    // Replace the pasted link with your custom HTML
+    callbacks.replaceLinkWith(this.#renderUnfurledLinkHTML(metadata))
+
+    // Or, insert below the link as an attachment:
+    // callbacks.insertBelowLink(this.#renderUnfurledLinkHTML(metadata), { attachment: true })
+  }
+
+  #renderUnfurledLinkHTML(link) {
+    return `<a href="${link.canonical_url}">${link.title}</a>`
+  }
+}
+```
 
 ## Contributing
 

package/dist/lexxy.esm.js

@@ -1,9 +1,9 @@
 import DOMPurify from 'dompurify';
-import { $getSelection, $isRangeSelection, $isTextNode, DecoratorNode, $getNodeByKey, HISTORY_MERGE_TAG, FORMAT_TEXT_COMMAND, PASTE_COMMAND, COMMAND_PRIORITY_LOW, $isNodeSelection, $getRoot, $isLineBreakNode, $isElementNode, KEY_ARROW_LEFT_COMMAND, KEY_ARROW_UP_COMMAND, KEY_ARROW_RIGHT_COMMAND, KEY_ARROW_DOWN_COMMAND, KEY_DELETE_COMMAND, KEY_BACKSPACE_COMMAND, SELECTION_CHANGE_COMMAND, $createNodeSelection, $setSelection, $createParagraphNode, $isParagraphNode, $insertNodes, $createTextNode, $createLineBreakNode, CLEAR_HISTORY_COMMAND, $addUpdateTag, SKIP_DOM_SELECTION_TAG, createEditor, KEY_ENTER_COMMAND, COMMAND_PRIORITY_NORMAL, COMMAND_PRIORITY_HIGH, KEY_TAB_COMMAND, KEY_SPACE_COMMAND } from 'lexical';
+import { $getSelection, $isRangeSelection, $isTextNode, DecoratorNode, $getNodeByKey, HISTORY_MERGE_TAG, FORMAT_TEXT_COMMAND, PASTE_COMMAND, COMMAND_PRIORITY_LOW, $isNodeSelection, $getRoot, $isLineBreakNode, $isElementNode, KEY_ARROW_LEFT_COMMAND, KEY_ARROW_UP_COMMAND, KEY_ARROW_RIGHT_COMMAND, KEY_ARROW_DOWN_COMMAND, KEY_DELETE_COMMAND, KEY_BACKSPACE_COMMAND, SELECTION_CHANGE_COMMAND, $createNodeSelection, $setSelection, $createParagraphNode, $createTextNode, $isParagraphNode, $insertNodes, $createLineBreakNode, CLEAR_HISTORY_COMMAND, $addUpdateTag, SKIP_DOM_SELECTION_TAG, createEditor, KEY_ENTER_COMMAND, COMMAND_PRIORITY_NORMAL, COMMAND_PRIORITY_HIGH, KEY_TAB_COMMAND, KEY_SPACE_COMMAND } from 'lexical';
 import { $isListNode, $isListItemNode, INSERT_UNORDERED_LIST_COMMAND, INSERT_ORDERED_LIST_COMMAND, ListNode, ListItemNode, registerList } from '@lexical/list';
 import { $isQuoteNode, $isHeadingNode, $createQuoteNode, $createHeadingNode, QuoteNode, HeadingNode, registerRichText } from '@lexical/rich-text';
 import { $isCodeNode, $isCodeHighlightNode, CodeNode, CodeHighlightNode, registerCodeHighlighting, CODE_LANGUAGE_FRIENDLY_NAME_MAP, normalizeCodeLang } from '@lexical/code';
-import { $isLinkNode, $toggleLink, LinkNode, AutoLinkNode } from '@lexical/link';
+import { $isLinkNode, $toggleLink, $createLinkNode, LinkNode, AutoLinkNode } from '@lexical/link';
 import { $generateNodesFromDOM, $generateHtmlFromNodes } from '@lexical/html';
 import { registerMarkdownShortcuts, TRANSFORMERS } from '@lexical/markdown';
 import { registerHistory, createEmptyHistoryState } from '@lexical/history';
@@ -1520,6 +1520,105 @@ class Selection {
   }
 }
 
+class CustomActionTextAttachmentNode extends DecoratorNode {
+  static getType() {
+    return "custom_action_text_attachment"
+  }
+
+  static clone(node) {
+    return new CustomActionTextAttachmentNode({ ...node }, node.__key)
+  }
+
+  static importJSON(serializedNode) {
+    return new CustomActionTextAttachmentNode({ ...serializedNode })
+  }
+
+  static importDOM() {
+    return {
+      "action-text-attachment": (attachment) => {
+        const content = attachment.getAttribute("content");
+        if (!attachment.getAttribute("content")) {
+          return null
+        }
+
+        return {
+          conversion: () => {
+            // Preserve initial space if present since Lexical removes it
+            const nodes = [];
+            const previousSibling = attachment.previousSibling;
+            if (previousSibling && previousSibling.nodeType === Node.TEXT_NODE && /\s$/.test(previousSibling.textContent)) {
+              nodes.push($createTextNode(" "));
+            }
+
+            nodes.push(new CustomActionTextAttachmentNode({
+              sgid: attachment.getAttribute("sgid"),
+              innerHtml: JSON.parse(content),
+              contentType: attachment.getAttribute("content-type")
+            }));
+
+            nodes.push($createTextNode(" "));
+
+            return { node: nodes }
+          },
+          priority: 2
+        }
+      }
+    }
+  }
+
+  constructor({ sgid, contentType, innerHtml }, key) {
+    super(key);
+
+    this.sgid = sgid;
+    this.contentType = contentType || "application/vnd.actiontext.unknown";
+    this.innerHtml = innerHtml;
+  }
+
+  createDOM() {
+    const figure = createElement("action-text-attachment", { "content-type": this.contentType, "data-lexxy-decorator": true });
+
+    figure.addEventListener("click", (event) => {
+      dispatchCustomEvent(figure, "lexxy:internal:select-node", { key: this.getKey() });
+    });
+
+    figure.insertAdjacentHTML("beforeend", this.innerHtml);
+
+    return figure
+  }
+
+  updateDOM() {
+    return true
+  }
+
+  isInline() {
+    return true
+  }
+
+  exportDOM() {
+    const attachment = createElement("action-text-attachment", {
+      sgid: this.sgid,
+      content: JSON.stringify(this.innerHtml),
+      "content-type": this.contentType
+    });
+
+    return { element: attachment }
+  }
+
+  exportJSON() {
+    return {
+      type: "custom_action_text_attachment",
+      version: 1,
+      sgid: this.sgid,
+      contentType: this.contentType,
+      innerHtml: this.innerHtml
+    }
+  }
+
+  decorate() {
+    return null
+  }
+}
+
 class Contents {
   constructor(editorElement) {
     this.editorElement = editorElement;
@@ -1638,6 +1737,24 @@ class Contents {
     });
   }
 
+  createLink(url) {
+    let linkNodeKey = null;
+
+    this.editor.update(() => {
+      const textNode = $createTextNode(url);
+      const linkNode = $createLinkNode(url);
+      linkNode.append(textNode);
+
+      const selection = $getSelection();
+      if ($isRangeSelection(selection)) {
+        selection.insertNodes([linkNode]);
+        linkNodeKey = linkNode.getKey();
+      }
+    });
+
+    return linkNodeKey
+  }
+
   createLinkWithSelectedText(url) {
     if (!this.hasSelectedText()) return
 
@@ -1766,6 +1883,47 @@ class Contents {
     });
   }
 
+  replaceNodeWithHTML(nodeKey, html, options = {}) {
+    this.editor.update(() => {
+      const node = $getNodeByKey(nodeKey);
+      if (!node) return
+
+      const selection = $getSelection();
+      let wasSelected = false;
+
+      if ($isRangeSelection(selection)) {
+        const selectedNodes = selection.getNodes();
+        wasSelected = selectedNodes.includes(node) || selectedNodes.some(n => n.getParent() === node);
+
+        if (wasSelected) {
+          $setSelection(null);
+        }
+      }
+
+      const replacementNode = options.attachment ? this.#createCustomAttachmentNodeWithHtml(html, options.attachment) : this.#createHtmlNodeWith(html);
+      node.replace(replacementNode);
+
+      if (wasSelected) {
+        replacementNode.selectEnd();
+      }
+    });
+  }
+
+  insertHTMLBelowNode(nodeKey, html, options = {}) {
+    this.editor.update(() => {
+      const node = $getNodeByKey(nodeKey);
+      if (!node) return
+
+      let previousNode = node;
+      try {
+        previousNode = node.getTopLevelElementOrThrow();
+      } catch {}
+
+      const newNode = options.attachment ? this.#createCustomAttachmentNodeWithHtml(html, options.attachment) : this.#createHtmlNodeWith(html);
+      previousNode.insertAfter(newNode);
+    });
+  }
+
   get #selection() {
     return this.editorElement.selection
   }
@@ -2008,6 +2166,21 @@ class Contents {
     }
   }
 
+  #createCustomAttachmentNodeWithHtml(html, options = {}) {
+    const attachmentConfig = typeof options === 'object' ? options : {};
+
+    return new CustomActionTextAttachmentNode({
+      sgid: attachmentConfig.sgid || null,
+      contentType: "text/html",
+      innerHtml: html
+    })
+  }
+
+  #createHtmlNodeWith(html) {
+    const htmlNodes = $generateNodesFromDOM(this.editor, parseHtml(html));
+    return htmlNodes[0] || $createParagraphNode()
+  }
+
   #shouldUploadFile(file) {
     return dispatch(this.editorElement, 'lexxy:file-accept', { file }, true)
   }
@@ -2063,12 +2236,27 @@ class Clipboard {
     item.getAsString((text) => {
       if (isUrl(text) && this.contents.hasSelectedText()) {
         this.contents.createLinkWithSelectedText(text);
+      } else if (isUrl(text)) {
+        const nodeKey = this.contents.createLink(text);
+        this.#dispatchLinkInsertEvent(nodeKey, { url: text });
       } else {
         this.#pasteMarkdown(text);
       }
     });
   }
 
+  #dispatchLinkInsertEvent(nodeKey, payload) {
+    const linkManipulationMethods = {
+      replaceLinkWith: (html, options) => this.contents.replaceNodeWithHTML(nodeKey, html, options),
+      insertBelowLink: (html, options) => this.contents.insertHTMLBelowNode(nodeKey, html, options)
+    };
+
+    dispatch(this.editorElement, "lexxy:insert-link", {
+      ...payload,
+      ...linkManipulationMethods
+    });
+  }
+
   #pasteMarkdown(text) {
     const html = marked(text);
     this.contents.insertHtml(html);
@@ -2101,105 +2289,6 @@ class Clipboard {
   }
 }
 
-class CustomActionTextAttachmentNode extends DecoratorNode {
-  static getType() {
-    return "custom_action_text_attachment"
-  }
-
-  static clone(node) {
-    return new CustomActionTextAttachmentNode({ ...node }, node.__key)
-  }
-
-  static importJSON(serializedNode) {
-    return new CustomActionTextAttachmentNode({ ...serializedNode })
-  }
-
-  static importDOM() {
-    return {
-      "action-text-attachment": (attachment) => {
-        const content = attachment.getAttribute("content");
-        if (!attachment.getAttribute("content")) {
-          return null
-        }
-
-        return {
-          conversion: () => {
-            // Preserve initial space if present since Lexical removes it
-            const nodes = [];
-            const previousSibling = attachment.previousSibling;
-            if (previousSibling && previousSibling.nodeType === Node.TEXT_NODE && /\s$/.test(previousSibling.textContent)) {
-              nodes.push($createTextNode(" "));
-            }
-
-            nodes.push(new CustomActionTextAttachmentNode({
-              sgid: attachment.getAttribute("sgid"),
-              innerHtml: JSON.parse(content),
-              contentType: attachment.getAttribute("content-type")
-            }));
-
-            nodes.push($createTextNode(" "));
-
-            return { node: nodes }
-          },
-          priority: 2
-        }
-      }
-    }
-  }
-
-  constructor({ sgid, contentType, innerHtml }, key) {
-    super(key);
-
-    this.sgid = sgid;
-    this.contentType = contentType || "application/vnd.actiontext.unknown";
-    this.innerHtml = innerHtml;
-  }
-
-  createDOM() {
-    const figure = createElement("action-text-attachment", { "content-type": this.contentType, "data-lexxy-decorator": true });
-
-    figure.addEventListener("click", (event) => {
-      dispatchCustomEvent(figure, "lexxy:internal:select-node", { key: this.getKey() });
-    });
-
-    figure.insertAdjacentHTML("beforeend", this.innerHtml);
-
-    return figure
-  }
-
-  updateDOM() {
-    return true
-  }
-
-  isInline() {
-    return true
-  }
-
-  exportDOM() {
-    const attachment = createElement("action-text-attachment", {
-      sgid: this.sgid,
-      content: JSON.stringify(this.innerHtml),
-      "content-type": this.contentType
-    });
-
-    return { element: attachment }
-  }
-
-  exportJSON() {
-    return {
-      type: "custom_action_text_attachment",
-      version: 1,
-      sgid: this.sgid,
-      contentType: this.contentType,
-      innerHtml: this.innerHtml
-    }
-  }
-
-  decorate() {
-    return null
-  }
-}
-
 class LexicalEditorElement extends HTMLElement {
   static formAssociated = true
   static debug = true
@@ -2434,6 +2523,7 @@ class LexicalEditorElement extends HTMLElement {
       this.cachedValue = null;
       this.#internalFormValue = this.value;
       this.#toggleEmptyStatus();
+      this.#validateRequired();
     }));
   }
 
@@ -2540,6 +2630,14 @@ class LexicalEditorElement extends HTMLElement {
     return !this.editorContentElement.textContent.trim() && !containsVisuallyRelevantChildren(this.editorContentElement)
   }
 
+  #validateRequired() {
+    if (this.hasAttribute("required") && this.#isEmpty) {
+      this.internals.setValidity({ valueMissing: true }, "Please fill out this field.", this.editorContentElement);
+    } else {
+      this.internals.setValidity({});
+    }
+  }
+
   #reset() {
     this.#unregisterHandlers();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@37signals/lexxy",
-  "version": "0.1.9-beta",
+  "version": "0.1.10-beta",
   "description": "Lexxy - A modern rich text editor for Rails.",
   "module": "dist/lexxy.esm.js",
   "type": "module",