@estiva-app/ui 0.67.0 → 0.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.67.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",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.67.0",
-    "exports": 149,
-    "typeExports": 146,
+    "packageVersion": "0.68.0",
+    "exports": 162,
+    "typeExports": 152,
     "files": null
   },
   "storybook": {
@@ -2729,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",
@@ -3337,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",
@@ -3667,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",
@@ -5485,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",
@@ -5529,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",
@@ -5567,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",
@@ -5606,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",
@@ -6154,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": [],
@@ -6187,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",
@@ -7608,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>
+      )
+    })
   },
 })
 

package/src/LinkChips.mdx

@@ -0,0 +1,57 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as LinkChipsStories from './LinkChips.stories'
+
+<Meta of={LinkChipsStories} />
+
+# LinkChips
+
+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. A URL the app does not
+recognise, or has not answered for yet, stays text.
+
+<Canvas of={LinkChipsStories.InAnEditor} />
+
+## When
+
+- **An editor of a document whose URLs can name things**: pair it with
+  **ReferenceNode**, which draws the chip, and **ReferenceCards**, which places
+  the card a chip can ask for.
+
+## When not
+
+- A document that is only read → **RichText**, whose text already says which
+  runs are chips.
+- An editor with a link mark (a composer's Link button) → its links are the
+  author's words, not chips. Turn the link mark off in a document editor
+  (`StarterKit.configure({ link: false })`), or URLs are linked before this
+  sees them.
+
+## How
+
+```tsx
+import { LinkChips, ReferenceCards, ReferenceNode } from '@estiva-app/ui/editor'
+
+LinkChips.configure({
+  // What the app has resolved so far: the reference a URL names, or undefined.
+  referenceOf: (url) => known(url),
+  // Look up the rest. When it settles, the document is looked at again.
+  ask: (urls) => lookUp(urls),
+})
+```
+
+- A chip made from a URL is a `reference` node with `href` set to the URL;
+  `uri` is what it names. A document saves it as the URL.
+- A chip read from a document before its URL is answered draws as the URL, and
+  offers no card choice until it is answered.
+- The URL the caret is in, or at the end of, stays text: a half-typed address
+  never turns into a chip while it is being typed. A pasted URL is whole: it
+  is asked about and becomes its chip at once, with the caret at its end, so
+  **ReferenceMenu** can open its menu.
+- A URL in code, in a code block, or under a link mark stays text.
+- Each URL is asked about once, and one editor asks about at most `limit`
+  (24 by default), the first ones: an answer can cost the app a query.
+- Making a chip is not an undo step: undo takes back what was typed.
+
+## What it owns
+
+Nothing. It draws nothing; it turns the URLs the app recognises into chips.

package/src/LinkChips.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, ReferenceNode, type ReferenceViewProps } from './BlockNodes'
+import { Card } from './Card'
+import { InlineChip } from './InlineChip'
+import { LinkChips } from './LinkChips'
+import { ReferenceCards } from './ReferenceCards'
+import { richTextClassName } from './RichText'
+
+/**
+ * A URL the app recognises reads as a chip; one it does not stays text. Here
+ * the app is a stand-in that recognises one address, after a short wait, and
+ * the chip is a placeholder naming what it points at: the real one is the
+ * app's, which knows how to resolve it.
+ */
+const meta = {
+  title: 'Primitives/LinkChips',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const KNOWN = 'https://example.com/item/one'
+const answered = new Map<string, string>()
+
+function Placeholder({ uri }: ReferenceViewProps) {
+  return <InlineChip>Item for {uri}</InlineChip>
+}
+
+function Box() {
+  const editor = useEditor({
+    extensions: [
+      StarterKit.configure({ link: false }),
+      BlockId,
+      ReferenceNode.configure({ view: Placeholder }),
+      ReferenceCards,
+      LinkChips.configure({
+        referenceOf: (url) => answered.get(url),
+        ask: (urls) =>
+          new Promise<void>((resolve) =>
+            setTimeout(() => {
+              if (urls.includes(KNOWN)) answered.set(KNOWN, 'nostr:naddr1one')
+              resolve()
+            }, 600),
+          ),
+      }),
+    ],
+    content: {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { blockId: 'p1' }, content: [{ type: 'text', text: `Recognised: ${KNOWN}` }] },
+        { type: 'paragraph', attrs: { blockId: 'p2' }, content: [{ type: 'text', text: 'Not recognised: https://example.com/elsewhere' }] },
+      ],
+    },
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  return (
+    <Card fill="surface" className="flex w-[520px] flex-col gap-2 p-3">
+      <EditorContent editor={editor} />
+    </Card>
+  )
+}
+
+/** Two URLs: the first turns into its chip once the stand-in answers, the second stays text. */
+export const InAnEditor: Story = { render: () => <Box /> }