@estiva-app/ui 0.72.0-widgets2.2 → 0.72.0

package/dist/looks.d.ts

@@ -51,4 +51,10 @@ export declare const MENU_TRIGGER_CLASSES = "cursor-pointer rounded-md transitio
  * prefers-reduced-motion. CollapsibleSection's rows, and the rows under a NavItem.
  */
 export declare const COLLAPSIBLE_PANEL_CLASSES = "h-[var(--collapsible-panel-height)] overflow-hidden transition-[height] duration-150 ease-out motion-reduce:transition-none data-[starting-style]:h-0 data-[ending-style]:h-0";
+/**
+ * The box a message or a comment is written in: Peek's writing box (its
+ * `looks.ts`, Katerina 24 September), moved with ComposeBox. Inset, a hairline,
+ * 12px in, 16px between the text and the row under it; the focus ring in Signal.
+ */
+export declare const WRITING_BOX_CLASSES = "relative bg-bg-inset border border-border-default rounded-lg p-3 flex flex-col gap-4 signal:transition-shadow signal:focus-within:border-border-focus signal:focus-within:shadow-focus-ring";
 //# sourceMappingURL=looks.d.ts.map

package/dist/looks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,wDAAwD,CAAA;AAEvF,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,qHAAqH;AACrH,eAAO,MAAM,oBAAoB,wEAAwE,CAAA;AAEzG,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,kEAAkE,CAAA;AAEpG,2IAA2I;AAC3I,eAAO,MAAM,oBAAoB,gGAAgG,CAAA;AAEjI;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}
+{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,wDAAwD,CAAA;AAEvF,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,qHAAqH;AACrH,eAAO,MAAM,oBAAoB,wEAAwE,CAAA;AAEzG,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,kEAAkE,CAAA;AAEpG,2IAA2I;AAC3I,eAAO,MAAM,oBAAoB,gGAAgG,CAAA;AAEjI;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA;AAExN;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,gMAC+J,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.72.0-widgets2.2",
+  "version": "0.72.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -29,10 +29,6 @@
       "types": "./dist/editor.d.ts",
       "default": "./dist/editor.js"
     },
-    "./widgets-2": {
-      "types": "./dist/widgets-2.d.ts",
-      "default": "./dist/widgets-2.js"
-    },
     "./gates": {
       "types": "./dist/gates/index.d.ts",
       "default": "./dist/gates/index.js"

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.72.0-widgets2.2",
-    "exports": 166,
-    "typeExports": 155,
+    "packageVersion": "0.72.0",
+    "exports": 177,
+    "typeExports": 162,
     "files": null
   },
   "storybook": {
@@ -15,6 +15,25 @@
     "devUrl": "http://localhost:6008"
   },
   "entries": [
+    {
+      "name": "anchorOfSelection",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/CommentHighlights.ts",
+      "purpose": "The anchor a comment on the selection carries, as §13.6 writes it: the selected blocks, and the selected words in one block or the words where it starts and ends across several.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-commenthighlights--docs",
+      "storyId": "primitives-commenthighlights--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "appendTableColumn",
       "repo": "estiva-ui",
@@ -1832,6 +1851,186 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "commentElement",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/CommentHighlights.ts",
+      "purpose": "What a comment's card stands beside: its drawn highlight, or — its words gone — its first block.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-commenthighlights--docs",
+      "storyId": "primitives-commenthighlights--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "CommentHighlights",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/CommentHighlights.ts",
+      "purpose": "Comments drawn where they are in an editor of a block document: on a few words, on a passage across blocks, or on whole blocks, in a light fill, the open one underlined.",
+      "purposeFrom": "page",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-commenthighlights--docs",
+      "storyId": "primitives-commenthighlights--default",
+      "docPage": "src/CommentHighlights.mdx",
+      "app": null,
+      "looks": [
+        "cursor-pointer rounded-sm bg-warning-muted underline decoration-warning-default decoration-2 underline-offset-4"
+      ]
+    },
+    {
+      "name": "commentPlace",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/CommentHighlights.ts",
+      "purpose": "Where a comment is now: on its words or blocks, beside its blocks with its words gone, or detached.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-commenthighlights--docs",
+      "storyId": "primitives-commenthighlights--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "COMPOSE_EDITOR_CLASSES",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposeBox.tsx",
+      "purpose": "The editor's own classes inside the box: Peek's, rich text with no outline.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composebox--docs",
+      "storyId": "primitives-composebox--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "ComposeBox",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposeBox.tsx",
+      "purpose": "The box a message, a reply or a comment is written in: the text, the selection strip over it, what is attached, the tools and Send.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "editor",
+          "takes": "Editor | null",
+          "required": true,
+          "note": "The app's editor, with `ComposeKeys` in its extensions and `COMPOSE_EDITOR_CLASSES` on it."
+        },
+        {
+          "name": "onSend",
+          "takes": "a handler",
+          "required": true,
+          "note": "Send what is written. The box empties afterwards — unless this returns `false`: nothing was sent, and the words stay."
+        },
+        {
+          "name": "placeholder",
+          "takes": "anything",
+          "required": true,
+          "note": "Said in the empty box: words, and a `Kbd` where a key helps (\"type / for commands\")."
+        },
+        {
+          "name": "tools",
+          "takes": "anything",
+          "required": false,
+          "note": "The tools under the text, left: `ToolbarButton`s (attach, highlight)."
+        },
+        {
+          "name": "attachments",
+          "takes": "anything",
+          "required": false,
+          "note": "What is attached, under the text: `AttachmentCard pending`s."
+        },
+        {
+          "name": "ready",
+          "takes": "true/false",
+          "required": false,
+          "note": "Something to send even with no words — a file ready."
+        },
+        {
+          "name": "holding",
+          "takes": "true/false",
+          "required": false,
+          "note": "Sending waits — a file still uploading."
+        },
+        {
+          "name": "marked",
+          "takes": "true/false",
+          "required": false,
+          "note": "The bar down the text's left: an urgent mention or a highlight, as Peek draws it."
+        },
+        {
+          "name": "selection",
+          "takes": "Pick<SelectionToolbarProps, 'marks' | 'link' | 'actions'>",
+          "required": false,
+          "note": "The selection strip's buttons: its marks, Link, and the app's own (`actions`)."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composebox--docs",
+      "storyId": "primitives-composebox--default",
+      "docPage": "src/ComposeBox.mdx",
+      "app": null,
+      "looks": [
+        "bg-bg-inset border border-border-default rounded-lg signal:transition-shadow signal:focus-within:border-border-focus signal:focus-within:shadow-focus-ring focus-within:border-border-strong transition-colors",
+        "select-none font-mono text-menu font-normal tracking-wider text-text-muted"
+      ]
+    },
+    {
+      "name": "ComposeKeys",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposeBox.tsx",
+      "purpose": "Enter sends; Shift+Enter is a new line — in a list a new item (or out of the list, on an empty one), in a quote a new line (or out of it, on an empty one).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composebox--docs",
+      "storyId": "primitives-composebox--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "ConfirmDialog",
       "repo": "estiva-ui",
@@ -3465,6 +3664,25 @@
         "border-border-tooltip-key bg-bg-tooltip-key text-text-tooltip-key signal:bg-bg-tooltip-key ship:bg-bg-tooltip-key"
       ]
     },
+    {
+      "name": "keepSelection",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/SelectionToolbar.tsx",
+      "purpose": "Draw the selection as it is now, until `releaseSelection`.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-selectiontoolbar--docs",
+      "storyId": "primitives-selectiontoolbar--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "KeptSelection",
       "repo": "estiva-ui",
@@ -5359,6 +5577,50 @@
         "text-menu uppercase tracking-widest text-text-secondary"
       ]
     },
+    {
+      "name": "quoteText",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/CommentHighlights.ts",
+      "purpose": "A quote in one line, as a card says it: its start and end words around an ellipsis.",
+      "purposeFrom": "comment",
+      "props": [
+        {
+          "name": "start",
+          "takes": "text",
+          "required": true,
+          "note": "The selection's words in one block, or its first words when it runs across blocks."
+        },
+        {
+          "name": "end",
+          "takes": "text",
+          "required": false,
+          "note": "Its last words, in the run's last block."
+        },
+        {
+          "name": "prefix",
+          "takes": "text",
+          "required": false,
+          "note": "A few characters before `start`, only when the words repeat in their block."
+        },
+        {
+          "name": "suffix",
+          "takes": "text",
+          "required": false,
+          "note": "A few characters after the end, only when the words repeat in their block."
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-commenthighlights--docs",
+      "storyId": "primitives-commenthighlights--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Rail",
       "repo": "estiva-ui",
@@ -5804,6 +6066,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "releaseSelection",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/SelectionToolbar.tsx",
+      "purpose": "Stop drawing it. Nothing kept, nothing dispatched.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-selectiontoolbar--docs",
+      "storyId": "primitives-selectiontoolbar--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "RichText",
       "repo": "estiva-ui",
@@ -6403,6 +6684,12 @@
           "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."
+        },
+        {
+          "name": "actions",
+          "takes": "readonly SelectionAction[]",
+          "required": false,
+          "note": "The app's own buttons after the marks, past a separator: \"Comment\"."
         }
       ],
       "variants": [],
@@ -6436,6 +6723,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "setCommentAnchors",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/CommentHighlights.ts",
+      "purpose": "Draw these comments, `active` the one being read.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-commenthighlights--docs",
+      "storyId": "primitives-commenthighlights--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "setReferenceCard",
       "repo": "estiva-ui",

package/src/CommentHighlights.mdx

@@ -0,0 +1,61 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as CommentHighlightsStories from './CommentHighlights.stories'
+
+<Meta of={CommentHighlightsStories} />
+
+# CommentHighlights
+
+Comments drawn where they are in an editor of a block document: on a few words, on a passage across blocks, or on whole blocks, in a light fill, the open one underlined.
+
+<Canvas of={CommentHighlightsStories.Default} />
+
+## When
+
+- **A comment on words or blocks of a block document.** SPEC §13.6 anchors a comment to a run of blocks; the words where its selection starts and ends travel with it as a quote and are found again in the run's first and last blocks when the document is drawn.
+- `setCommentAnchors(editor, anchors, active)` draws them; `active` is the one being read.
+- The editor's `commentSelect` event says which highlight was clicked. Where two overlap, the narrower one is.
+- `commentPlace` says where a comment is now: `resolved` (drawn, on its words or on its whole blocks), `reworded` (its blocks are there, its words are not: nothing is drawn) or `detached` (its blocks are gone). A reworded comment's words are shown as what its writer quoted, never as what the page says; neither state is ever shown as a comment on the whole document.
+- `commentElement` is what its card stands beside: the highlight, or the first block of a reworded comment.
+- `anchorOfSelection` is what a comment on the selection carries: the selected blocks, and their words unless whole blocks are selected. `quoteText` puts a quote in one line.
+
+<Canvas of={CommentHighlightsStories.NoneOpen} />
+
+## When not
+
+- Showing a selection while a field has the focus → **SelectionToolbar**'s kept selection.
+
+No alternative: a comment on the whole document has no place to draw. Say where it belongs in words.
+
+## How
+
+```tsx
+import { useEffect } from 'react'
+import { useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, CommentHighlights, setCommentAnchors } from '@estiva-app/ui/editor'
+
+const editor = useEditor({ extensions: [StarterKit, BlockId, CommentHighlights] })
+
+// threads: [{ id, blocks: ['b2', 'b3'], quote: { start: 'first words', end: 'last words' } }, …]
+useEffect(() => {
+  if (!editor) return
+  setCommentAnchors(editor, threads, openId)
+  const select = ({ id }: { id: string }) => open(id)
+  editor.on('commentSelect', select)
+  return () => { editor.off('commentSelect', select) }
+}, [editor, threads, openId])
+```
+
+- **Nothing is written into the document.** The highlight is a decoration: a save never carries it.
+- `BlockId` must be in the editor: the anchors find their blocks by their ids.
+- Words are matched exactly, never trimmed or guessed. Words that repeat in their block are told apart by the few characters around them; without those, the first is drawn.
+- `commentPlace` reads the document as it is: call it again after an edit.
+
+## What it owns
+
+| It does | So you never write |
+|---|---|
+| Finds the run and its words again, after every edit | position arithmetic |
+| Draws words inline and whole blocks whole, the open one underlined | a mark in the document |
+| Tells drawn, reworded and detached apart | a "not found" guess |
+| Says which highlight was clicked | a click handler on the text |

package/src/CommentHighlights.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useEffect, useState } from 'react'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId } from './BlockNodes'
+import { CommentHighlights, commentPlace, setCommentAnchors, type CommentAnchor } from './CommentHighlights'
+import { richTextClassName } from './RichText'
+
+/**
+ * Comments drawn where they are. Click a highlight: it becomes the open one.
+ * Type over highlighted words and the line under the text says where each
+ * comment is now.
+ */
+const meta = {
+  title: 'Primitives/CommentHighlights',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const DOCUMENT = {
+  type: 'doc',
+  content: [
+    { type: 'heading', attrs: { level: 1, blockId: 'b1' }, content: [{ type: 'text', text: 'Heading' }] },
+    { type: 'paragraph', attrs: { blockId: 'b2' }, content: [{ type: 'text', text: 'A highlight is drawn on the words a comment quotes, found again in its block.' }] },
+    { type: 'paragraph', attrs: { blockId: 'b3' }, content: [{ type: 'text', text: 'A selection across blocks keeps the words where it starts and where it ends.' }] },
+    { type: 'paragraph', attrs: { blockId: 'b4' }, content: [{ type: 'text', text: 'A comment on whole blocks keeps no words, and is drawn on every block of its run.' }] },
+    { type: 'paragraph', attrs: { blockId: 'b5' }, content: [{ type: 'text', text: 'Words that changed are not drawn.' }] },
+  ],
+}
+
+const ANCHORS: CommentAnchor[] = [
+  { id: 'one', blocks: ['b2'], quote: { start: 'the words a comment quotes' } },
+  { id: 'two', blocks: ['b2', 'b3'], quote: { start: 'found again in its block.', end: 'A selection across blocks' } },
+  { id: 'three', blocks: ['b4'] },
+  { id: 'four', blocks: ['b5'], quote: { start: 'Items that changed' } },
+  { id: 'five', blocks: ['gone'], quote: { start: 'Label' } },
+]
+
+function Highlighted({ initial }: { initial: string | null }) {
+  const [active, setActive] = useState<string | null>(initial)
+  const [, setVersion] = useState(0)
+  const editor = useEditor({
+    extensions: [StarterKit, BlockId, CommentHighlights],
+    content: DOCUMENT,
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+    onUpdate: () => setVersion((v) => v + 1),
+  })
+  useEffect(() => {
+    if (!editor) return
+    setCommentAnchors(editor, ANCHORS, active)
+    const select = ({ id }: { id: string }) => setActive(id)
+    editor.on('commentSelect', select)
+    return () => {
+      editor.off('commentSelect', select)
+    }
+  }, [editor, active])
+  const states = editor ? ANCHORS.map((a) => `${a.id}: ${commentPlace(editor, a).state}`).join(' · ') : ''
+  return (
+    <div className="flex max-w-[560px] flex-col gap-3">
+      <EditorContent editor={editor} />
+      <p className="text-caption text-text-muted">{`Open: ${active ?? 'none'} · ${states}`}</p>
+    </div>
+  )
+}
+
+/** Words, a run across two blocks and a whole block, the open one underlined. Click another to open it. */
+export const Default: Story = { render: () => <Highlighted initial="two" /> }
+
+/** Nothing open: every comment in the same light fill. */
+export const NoneOpen: Story = { render: () => <Highlighted initial={null} /> }

package/src/CommentHighlights.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+/**
+ * Where a comment on a selection is anchored (§13.6), and where an anchor is
+ * found again: what `anchorOfSelection` hands the app to write on the
+ * comment, and what `commentPlace` says when the page has changed since.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId } from './BlockNodes'
+import { CommentHighlights, anchorOfSelection, commentPlace } from './CommentHighlights'
+
+let editor: Editor | undefined
+
+afterEach(() => {
+  editor?.destroy()
+  editor = undefined
+})
+
+const paragraph = (blockId: string, text: string) => ({ type: 'paragraph', attrs: { blockId }, content: [{ type: 'text', text }] })
+
+/** Two paragraphs: "alpha beta gamma" (text at 1–17) and "delta epsilon" (text at 19–32). */
+function open(content: object[] = [paragraph('p1', 'alpha beta gamma'), paragraph('p2', 'delta epsilon')]) {
+  editor = new Editor({ extensions: [StarterKit, BlockId, CommentHighlights], content: { type: 'doc', content } })
+  return editor
+}
+
+describe('anchorOfSelection', () => {
+  it('quotes the first word of a paragraph, not the whole paragraph', () => {
+    const e = open()
+    e.commands.setTextSelection({ from: 1, to: 6 })
+    expect(anchorOfSelection(e)).toEqual({ blocks: ['p1'], quote: { start: 'alpha' } })
+  })
+
+  it('quotes the last word of a paragraph, not the whole paragraph', () => {
+    const e = open()
+    e.commands.setTextSelection({ from: 12, to: 17 })
+    expect(anchorOfSelection(e)).toEqual({ blocks: ['p1'], quote: { start: 'gamma' } })
+  })
+
+  it('anchors a selection of a whole paragraph to the block, with no words', () => {
+    const e = open()
+    e.commands.setTextSelection({ from: 1, to: 17 })
+    expect(anchorOfSelection(e)).toEqual({ blocks: ['p1'] })
+  })
+
+  it('quotes where a selection across blocks starts and where it ends', () => {
+    const e = open()
+    e.commands.setTextSelection({ from: 7, to: 24 })
+    expect(anchorOfSelection(e)).toEqual({ blocks: ['p1', 'p2'], quote: { start: 'beta gamma', end: 'delta' } })
+  })
+
+  it('anchors nothing when only the edge between two blocks is selected', () => {
+    const e = open()
+    e.commands.setTextSelection({ from: 17, to: 19 })
+    expect(anchorOfSelection(e)).toBeNull()
+  })
+
+  it('anchors two lines of a quote to the quote', () => {
+    const e = open([
+      { type: 'blockquote', attrs: { blockId: 'q1' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'one line' }] }, { type: 'paragraph', content: [{ type: 'text', text: 'two line' }] }] },
+    ])
+    // The quote opens at 0, its first line's text at 2–10, the second's at 12–20.
+    e.commands.setTextSelection({ from: 6, to: 15 })
+    expect(anchorOfSelection(e)).toEqual({ blocks: ['q1'], quote: { start: 'linetwo' } })
+  })
+
+  it('keeps the words around a quote only when the quoted words repeat', () => {
+    const e = open([paragraph('p1', 'see it, then see it again')])
+    e.commands.setTextSelection({ from: 14, to: 20 })
+    expect(anchorOfSelection(e)).toEqual({ blocks: ['p1'], quote: { start: 'see it', prefix: 'see it, then ', suffix: ' again' } })
+  })
+})
+
+describe('commentPlace', () => {
+  it('finds quoted words on the words', () => {
+    const e = open()
+    expect(commentPlace(e, { id: 'c', blocks: ['p1'], quote: { start: 'beta' } })).toEqual({ state: 'resolved', from: 7, to: 11, words: true })
+  })
+
+  it('draws a comment with no words on its whole blocks', () => {
+    const e = open()
+    expect(commentPlace(e, { id: 'c', blocks: ['p1', 'p2'] })).toEqual({ state: 'resolved', from: 0, to: 33, words: false })
+  })
+
+  it('says reworded when the blocks are there and the words are not', () => {
+    const e = open()
+    expect(commentPlace(e, { id: 'c', blocks: ['p1'], quote: { start: 'omega' } })).toEqual({ state: 'reworded', from: 0, to: 18 })
+  })
+
+  it('says detached when none of the blocks is left', () => {
+    const e = open()
+    expect(commentPlace(e, { id: 'c', blocks: ['gone'], quote: { start: 'alpha' } })).toEqual({ state: 'detached' })
+  })
+
+  it('picks the repeated words whose context matches', () => {
+    const e = open([paragraph('p1', 'see it, then see it again')])
+    expect(commentPlace(e, { id: 'c', blocks: ['p1'], quote: { start: 'see it', suffix: ' again' } })).toEqual({ state: 'resolved', from: 14, to: 20, words: true })
+  })
+})