@estiva-app/ui 0.66.0 → 0.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -136,6 +136,7 @@
     "@tiptap/core": "^3.31.3",
     "@tiptap/extension-code-block-lowlight": "^3.31.3",
     "@tiptap/extension-mention": "^3.31.3",
+    "@tiptap/extension-table": "^3.31.3",
     "@tiptap/pm": "^3.31.3",
     "@tiptap/react": "^3.31.3",
     "@tiptap/starter-kit": "^3.31.3",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.66.0",
-    "exports": 144,
-    "typeExports": 145,
+    "packageVersion": "0.68.0",
+    "exports": 162,
+    "typeExports": 152,
     "files": null
   },
   "storybook": {
@@ -15,6 +15,44 @@
     "devUrl": "http://localhost:6008"
   },
   "entries": [
+    {
+      "name": "appendTableColumn",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorTableControls.tsx",
+      "purpose": "A column after the last one: the ➕ right of the table.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editortablecontrols--docs",
+      "storyId": "primitives-editortablecontrols--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "appendTableRow",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorTableControls.tsx",
+      "purpose": "A row after the last one: the ➕ under the table.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editortablecontrols--docs",
+      "storyId": "primitives-editortablecontrols--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "applyFormat",
       "repo": "estiva-ui",
@@ -1963,6 +2001,44 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "deleteTableColumn",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorTableControls.tsx",
+      "purpose": "The same for a column: the last one deletes the table.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editortablecontrols--docs",
+      "storyId": "primitives-editortablecontrols--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "deleteTableRow",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorTableControls.tsx",
+      "purpose": "The cell's row, or the whole table when it is its only one: a table holds at least one row (prosemirror-tables refuses to delete it).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editortablecontrols--docs",
+      "storyId": "primitives-editortablecontrols--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "DialogShell",
       "repo": "estiva-ui",
@@ -2292,6 +2368,47 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "EditorTableControls",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorTableControls.tsx",
+      "purpose": "A table's own controls in a Tiptap editor: point at a cell for a handle on its row and on its column, and a ➕ bar under the table and right of it.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "editor",
+          "takes": "Editor | null",
+          "required": true,
+          "note": "The editor, with TableKit (`@tiptap/extension-table`) in its extensions."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": "The `EditorContent`."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editortablecontrols--docs",
+      "storyId": "primitives-editortablecontrols--default",
+      "docPage": "src/EditorTableControls.mdx",
+      "app": null,
+      "looks": [
+        "rounded-lg border border-border-default bg-bg-elevated shadow-lg shadow-none -translate-x-1/2 -translate-y-1/2",
+        "rounded-lg border border-border-default bg-bg-elevated shadow-lg shadow-none"
+      ]
+    },
     {
       "name": "EmptyState",
       "repo": "estiva-ui",
@@ -2612,6 +2729,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "findLinkChips",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/LinkChips.ts",
+      "purpose": "What to change in a document, and what to ask.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-linkchips--docs",
+      "storyId": "primitives-linkchips--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Form",
       "repo": "estiva-ui",
@@ -3220,6 +3356,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "isReferenceMenuOpen",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceMenu.tsx",
+      "purpose": "Whether the menu is open, for an editor's own Escape: while it is, Escape closes it rather than leaving.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencemenu--docs",
+      "storyId": "primitives-referencemenu--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "isSuggestionActive",
       "repo": "estiva-ui",
@@ -3550,6 +3705,25 @@
         "underline underline-offset-2 hover:text-text-primary truncate after:rounded-md focus-visible:outline-none"
       ]
     },
+    {
+      "name": "LinkChips",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/LinkChips.ts",
+      "purpose": "A URL in a document that the app recognises reads as a chip of what it points at, and stays that URL when the document is saved.",
+      "purposeFrom": "page",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-linkchips--docs",
+      "storyId": "primitives-linkchips--in-an-editor",
+      "docPage": "src/LinkChips.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "ListColumn",
       "repo": "estiva-ui",
@@ -4240,6 +4414,12 @@
           "required": false,
           "note": "The ⋮'s accessible name and tooltip. Default \"More options for {label}\"."
         },
+        {
+          "name": "action",
+          "takes": "SectionAction",
+          "required": false,
+          "note": "One button beside the ⋮, shown with it: any 16px icon, its tooltip and its handler — a `SectionHeader` action's shape."
+        },
         {
           "name": "hint",
           "takes": "anything",
@@ -5362,6 +5542,63 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "referenceAtSelection",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceCards.ts",
+      "purpose": "The chip the person has selected, with what it names and its card — or null.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencecards--docs",
+      "storyId": "primitives-referencecards--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "referenceCardPlacements",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceCards.ts",
+      "purpose": "Every line that asks for a card, in document order.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencecards--docs",
+      "storyId": "primitives-referencecards--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "ReferenceCards",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceCards.ts",
+      "purpose": "A chip in a document can ask for a card after its line: compact, detailed or none.",
+      "purposeFrom": "page",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencecards--docs",
+      "storyId": "primitives-referencecards--in-an-editor",
+      "docPage": "src/ReferenceCards.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "referenceMenu",
       "repo": "estiva-ui",
@@ -5406,6 +5643,91 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "ReferenceMenu",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceMenu.tsx",
+      "purpose": "What a chip in a document offers whoever is writing it: Open, and its Card — none, compact or detailed.",
+      "purposeFrom": "page",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencemenu--docs",
+      "storyId": "primitives-referencemenu--in-an-editor",
+      "docPage": "src/ReferenceMenu.mdx",
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "referenceMenuClick",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceMenu.tsx",
+      "purpose": "A click on the chip at `pos`, from its node view: while editing, with the menu installed, it opens the menu, and the caller stops the click there.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencemenu--docs",
+      "storyId": "primitives-referencemenu--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "ReferenceMenuView",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceMenu.tsx",
+      "purpose": "The menu `ReferenceMenu` holds, hung under its chip.",
+      "purposeFrom": "comment",
+      "props": [
+        {
+          "name": "editor",
+          "takes": "Editor | null",
+          "required": true,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [
+        {
+          "id": "portal",
+          "behaviour": "Floats on top of the page"
+        },
+        {
+          "id": "press-outside",
+          "behaviour": "Closes on a press outside"
+        },
+        {
+          "id": "page-keys",
+          "behaviour": "Takes its keys by itself"
+        },
+        {
+          "id": "focus",
+          "behaviour": "Holds focus inside while open, and gives it back"
+        },
+        {
+          "id": "follow",
+          "behaviour": "Stays attached to its anchor on scroll and resize"
+        }
+      ],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencemenu--docs",
+      "storyId": "primitives-referencemenu--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "ReferenceNode",
       "repo": "estiva-ui",
@@ -5444,6 +5766,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "refreshLinkChips",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/LinkChips.ts",
+      "purpose": "Look at the document again — after the app learned what more URLs name some other way.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-linkchips--docs",
+      "storyId": "primitives-linkchips--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "RichText",
       "repo": "estiva-ui",
@@ -5483,6 +5824,12 @@
           "required": false,
           "note": "Draws a block this part has no design for (an attachment, a widget)."
         },
+        {
+          "name": "renderAfter",
+          "takes": "a handler",
+          "required": false,
+          "note": "Draws something after a line of text: after a paragraph, a heading or a quote, and inside a list item or a table cell after its words — where a document's chip asks for its card (SPEC §13.3)."
+        },
         {
           "name": "onTick",
           "takes": "a handler",
@@ -5512,7 +5859,7 @@
         "[&_:not(pre)>code]:rounded-sm [&_:not(pre)>code]:bg-bg-code [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:py-0.5 [&_:not(pre)>code]:border [&_:not(pre)>code]:border-border-default [&_code]:font-mono [&_code]:text-[0.85em] [&_code]:text-text-primary",
         "[&_pre>code]:text-[1em] [&_pre]:whitespace-pre-wrap [&_pre]:break-words [&_pre]:rounded-md [&_pre]:bg-bg-code [&_pre]:px-3 [&_pre]:py-2.5 [&_pre]:font-mono [&_pre]:text-[0.85em] [&_pre]:leading-relaxed [&_pre]:text-text-primary",
         "[&_:is(.hljs-keyword,.hljs-doctag,.hljs-type,.hljs-template-tag,.hljs-template-variable)]:text-syntax-keyword [&_.hljs-title]:text-syntax-function [&_:is(.hljs-number,.hljs-literal,.hljs-attr,.hljs-attribute,.hljs-meta,.hljs-variable,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id)]:text-syntax-constant [&_:is(.hljs-string,.hljs-regexp)]:text-syntax-string [&_:is(.hljs-built_in,.hljs-symbol)]:text-syntax-variable [&_.hljs-comment]:text-syntax-comment [&_:is(.hljs-name,.hljs-quote,.hljs-selector-tag,.hljs-selector-pseudo)]:text-syntax-tag",
-        "[&_:is(th,td)>p]:m-0 [&_:is(th,td)]:border [&_:is(th,td)]:border-border-default [&_:is(th,td)]:px-2 [&_:is(th,td)]:py-1 [&_:is(th,td)]:text-left [&_:is(th,td)]:align-top [&_table]:w-full [&_table]:border-collapse [&_th]:bg-bg-code [&_th]:font-medium [&_th]:text-text-primary",
+        "[&_:is(th,td)>p]:m-0 [&_:is(th,td)]:border [&_:is(th,td)]:border-border-default [&_:is(th,td)]:px-2 [&_:is(th,td)]:py-1 [&_:is(th,td)]:text-left [&_:is(th,td)]:align-top [&_table]:my-2 [&_table]:w-full [&_table]:border-collapse [&_th]:bg-bg-code [&_th]:font-medium [&_th]:text-text-primary",
         "[&_em]:italic [&_strong]:font-semibold [&_strong]:text-text-primary [&_u]:underline [&_u]:decoration-text-muted [&_u]:underline-offset-2",
         "text-body-2 leading-normal [&>:is(h2,h3)]:text-body-2 [&>:is(h2,h3)]:font-semibold [&>h1]:text-h4",
         "text-caption leading-snug [&>:is(h1,h2,h3)]:mb-0.5 [&>:is(h1,h2,h3)]:mt-1.5 [&>:is(h1,h2,h3)+:is(h1,h2,h3)]:mt-1 [&>:is(h1,h2,h3):last-child]:mb-0 [&>:is(h2,h3)]:text-caption [&>:is(h2,h3)]:font-semibold [&>h1]:text-body-2 [&>h1]:font-semibold"
@@ -6031,6 +6378,12 @@
           "takes": "true/false",
           "required": false,
           "note": "The Link button and its address field. Needs a link mark in the editor and `KeptSelection`."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": false,
+          "note": "More of the strip, after the marks: the app's own `ToolbarButton`s for what is selected — a chip's card, say."
         }
       ],
       "variants": [],
@@ -6064,6 +6417,44 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "setReferenceCard",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceCards.ts",
+      "purpose": "Sets the card of the selected chip. `none` removes it.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencecards--docs",
+      "storyId": "primitives-referencecards--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "setReferenceCardAt",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceCards.ts",
+      "purpose": "Sets the card of the chip at `pos` — one that names something.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencecards--docs",
+      "storyId": "primitives-referencecards--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "shortcutLabel",
       "repo": "estiva-ui",
@@ -7485,6 +7876,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "useReferenceCards",
+      "repo": "estiva-ui",
+      "kind": "hook",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ReferenceCards.ts",
+      "purpose": "The slots to draw cards into, kept current as the document changes.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-referencecards--docs",
+      "storyId": "primitives-referencecards--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "useToast",
       "repo": "estiva-ui",

package/src/BlockNodes.test.tsx

@@ -79,7 +79,8 @@ describe('what the editor hands back', () => {
   it('keeps a reference an atom, with its uri and the marks it carries', () => {
     editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
     const reference = (editor.getJSON() as Json).content?.[1].content?.[1]
-    expect(reference).toEqual({ type: 'reference', attrs: { uri: 'nostr:naddr1example', marks: ['bold'] } })
+    // No card chosen, no key a later version added (SPEC §13.3), and not a URL chip.
+    expect(reference).toEqual({ type: 'reference', attrs: { uri: 'nostr:naddr1example', marks: ['bold'], embed: null, extra: null, href: null } })
   })
 
   it('keeps every imeta field on a file, which ProseMirror drops when undeclared', () => {

package/src/BlockNodes.tsx

@@ -1,4 +1,4 @@
-import type { ComponentType } from 'react'
+import type { ComponentType, MouseEvent } from 'react'
 import { Extension, InputRule, Node, type Editor } from '@tiptap/core'
 import { DOMSerializer, type Node as ProseMirrorNode, type Slice } from '@tiptap/pm/model'
 import { Plugin, PluginKey, type EditorState, type Transaction } from '@tiptap/pm/state'
@@ -7,6 +7,7 @@ import type { EditorView, NodeView } from '@tiptap/pm/view'
 import { NodeViewWrapper, ReactNodeViewRenderer, ReactRenderer, type ReactNodeViewProps } from '@tiptap/react'
 import { Checkbox, type CheckboxProps } from './Checkbox'
 import { calloutLook } from './RichText'
+import { referenceMenuClick } from './ReferenceMenu'
 
 /*
  * The four nodes an editor of a block document needs that a stock schema does
@@ -364,9 +365,13 @@ export const BlockId = Extension.create({
   },
 })
 
-/** What a reference's view is handed: the `nostr:` URI it stands for. */
+/** An http(s) URL, or null. */
+const webUrl = (raw: string | null): string | null => (raw && /^https?:\/\/\S+$/i.test(raw) ? raw : null)
+
+/** What a reference's view is handed: the `nostr:` URI it stands for, and the URL a URL chip was written as. */
 export interface ReferenceViewProps {
   uri: string
+  href?: string
 }
 
 export interface ReferenceNodeOptions {
@@ -384,6 +389,16 @@ export interface ReferenceNodeOptions {
  * nobody edits half a `naddr`. Selecting it selects the whole reference, which
  * is also how deleting one works. `marks` carries the run's other marks, so a
  * bold reference comes back bold.
+ *
+ * `embed` is the card its writer chose to draw after its block — `compact`,
+ * `detailed`, or null for none (SPEC §13.3, "A reference's card") — and `extra`
+ * every key of the mark this version does not know. Both are declared so that
+ * ProseMirror keeps them: an undeclared attribute is dropped when the node is
+ * made, and the card with it. `ReferenceCards` draws the cards.
+ *
+ * `href` makes it a **URL chip**: an app URL that reads as the chip of what it
+ * names, and is that URL on the wire (§13.3). `uri` is what it names, filled in
+ * by `LinkChips` once the app has resolved it; until then it draws as the URL.
  */
 export const ReferenceNode = Node.create<ReferenceNodeOptions>({
   name: 'reference',
@@ -397,8 +412,14 @@ export const ReferenceNode = Node.create<ReferenceNodeOptions>({
   },
   addAttributes() {
     return {
-      uri: { default: '' },
+      // A pasted URL chip keeps only its URL: what it names is the editor's to resolve (`LinkChips`), never
+      // the clipboard's, which could show one object while saving another URL (security review).
+      uri: { default: '', parseHTML: (element: HTMLElement) => (webUrl(element.getAttribute('data-href')) ? '' : (element.getAttribute('data-reference') ?? '')) },
       marks: { default: [] as string[] },
+      embed: { default: null as string | null, parseHTML: (element: HTMLElement) => element.getAttribute('data-embed') },
+      extra: { default: null as Record<string, unknown> | null, parseHTML: () => null },
+      // An http(s) URL only: `LinkChips` makes no other, and a pasted `javascript:` must not reach a saved link.
+      href: { default: null as string | null, parseHTML: (element: HTMLElement) => webUrl(element.getAttribute('data-href')) },
     }
   },
   parseHTML() {
@@ -406,16 +427,37 @@ export const ReferenceNode = Node.create<ReferenceNodeOptions>({
   },
   renderHTML({ node }) {
     // A copy to the clipboard as HTML, and the whole drawing when no view is given.
-    return ['span', { 'data-reference': String(node.attrs.uri) }, String(node.attrs.uri)]
+    // The card goes along, so a paste keeps it; a URL chip copies as its URL.
+    const embed = typeof node.attrs.embed === 'string' ? { 'data-embed': node.attrs.embed } : {}
+    const href = typeof node.attrs.href === 'string' && node.attrs.href ? { 'data-href': node.attrs.href } : {}
+    return ['span', { 'data-reference': String(node.attrs.uri), ...embed, ...href }, String(node.attrs.href || node.attrs.uri)]
+  },
+  renderText({ node }) {
+    return String(node.attrs.href || node.attrs.uri)
   },
   addNodeView() {
     const View = this.options.view
     if (!View) return null
-    return ReactNodeViewRenderer(({ node }: ReactNodeViewProps) => (
-      <NodeViewWrapper as="span" className="inline">
-        <View uri={String(node.attrs.uri ?? '')} />
-      </NodeViewWrapper>
-    ))
+    return ReactNodeViewRenderer(({ node, editor, getPos }: ReactNodeViewProps) => {
+      const uri = String(node.attrs.uri ?? '')
+      const href = typeof node.attrs.href === 'string' && node.attrs.href ? node.attrs.href : undefined
+      return (
+        <NodeViewWrapper
+          as="span"
+          className="inline"
+          // While editing, a click opens the chip's menu (`ReferenceMenu`) rather than following the chip.
+          onClickCapture={(event: MouseEvent) => {
+            const pos = getPos()
+            if (typeof pos !== 'number' || !referenceMenuClick(editor, pos)) return
+            event.preventDefault()
+            event.stopPropagation()
+          }}
+        >
+          {/* A URL chip not resolved yet reads as the URL it was written as. */}
+          {uri ? <View uri={uri} {...(href ? { href } : {})} /> : <span>{href}</span>}
+        </NodeViewWrapper>
+      )
+    })
   },
 })