@estiva-app/ui 0.54.0 → 0.56.0

package/dist/looks.d.ts

@@ -34,6 +34,10 @@ export declare const CHIP_TEXT_CLASSES = "text-chip signal:font-mono signal:text
 /** Words typed straight into an input with no box of its own: SearchInput and ChipInput. */
 export declare const BARE_INPUT_CLASSES = "bg-transparent text-text-primary placeholder:text-text-muted outline-none";
 /** A sidebar row's shape and its words at rest, brightening under the pointer: NavItem, and SectionHeader's `row` (a folder among rows). */
+/** A quiet icon control: secondary, brightening on a hover fill — IconButton's `muted`. */
+export declare const MUTED_CONTROL_CLASSES = "text-text-secondary hover:bg-bg-hover hover:text-text-primary";
+/** A control that opens a menu: a hover fill, held while its menu is up — PersonTrigger's row, and a ContainerHeader title with a menu. */
+export declare const MENU_TRIGGER_CLASSES = "cursor-pointer rounded-md transition-colors hover:bg-bg-hover data-[popup-open]:bg-bg-hover";
 export declare const SIDEBAR_ROW_CLASSES = "rounded-lg transition-colors";
 export declare const SIDEBAR_ROW_TEXT_CLASSES = "text-text-secondary hover:text-text-primary";
 /**

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,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF;;;;;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,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,kEAAkE,CAAA;AAEpG,2IAA2I;AAC3I,eAAO,MAAM,oBAAoB,gGAAgG,CAAA;AAEjI,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.54.0",
+  "version": "0.56.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.54.0",
-    "exports": 122,
-    "typeExports": 129,
+    "packageVersion": "0.56.0",
+    "exports": 130,
+    "typeExports": 134,
     "files": null
   },
   "storybook": {
@@ -458,6 +458,88 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "blockAtY",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/BlockHandle.tsx",
+      "purpose": "The last of `blocks` whose top is at or above `y` — the gap between two blocks belongs to the one before.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-blockhandle--docs",
+      "storyId": "primitives-blockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "blockDropCursor",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "The drop line a dragged block shows, in the package's accent instead of the editor's default (the text's colour).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "BlockHandle",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/BlockHandle.tsx",
+      "purpose": "The handle left of the block under the pointer, as a block-document page has it, and the block's menu behind it.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "actions",
+          "takes": "a handler",
+          "required": false,
+          "note": "The caller's own rows — a link to the block, a comment on it."
+        },
+        {
+          "name": "editing",
+          "takes": "BlockHandleEditing",
+          "required": false,
+          "note": "Given by `EditorBlockHandle` (from `@estiva-app/ui/editor`)."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": "What the blocks are drawn in. Reading: a surface whose top-level elements carry `data-block-id`, as `RichText` draws."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-blockhandle--docs",
+      "storyId": "primitives-blockhandle--default",
+      "docPage": "src/BlockHandle.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "BlockId",
       "repo": "estiva-ui",
@@ -1103,6 +1185,12 @@
           "required": false,
           "note": "Remember open or closed in this browser, under this key."
         },
+        {
+          "name": "icon",
+          "takes": "anything",
+          "required": false,
+          "note": "16px, before the title; the arrow takes its place on hover — `SectionHeader`'s."
+        },
         {
           "name": "trailing",
           "takes": "anything",
@@ -1115,6 +1203,18 @@
           "required": false,
           "note": "Beside the title, revealed on hover or focus — `SectionHeader`'s."
         },
+        {
+          "name": "menu",
+          "takes": "anything",
+          "required": false,
+          "note": "Beside the actions, revealed with them: the section's \"More options\" menu, `MenuItem`s — `SectionHeader`'s."
+        },
+        {
+          "name": "menuLabel",
+          "takes": "text",
+          "required": false,
+          "note": "The ⋮'s accessible name — `SectionHeader`'s."
+        },
         {
           "name": "showActions",
           "takes": "hover | always",
@@ -1668,6 +1768,12 @@
           "required": false,
           "note": "A chevron after the title, for a title that opens something."
         },
+        {
+          "name": "titleMenu",
+          "takes": "anything",
+          "required": false,
+          "note": "The menu the title opens: `MenuItem`s — the column's views (Katerina, 5 October: Peek's Topics column, Topics or Folders)."
+        },
         {
           "name": "actions",
           "takes": "anything",
@@ -1682,13 +1788,47 @@
         }
       ],
       "variants": [],
-      "ownsBehaviours": [],
+      "ownsBehaviours": [
+        {
+          "id": "base-ui",
+          "behaviour": "Is built on Base UI"
+        },
+        {
+          "id": "role",
+          "behaviour": "Says what it is to assistive technology"
+        },
+        {
+          "id": "tab-stop",
+          "behaviour": "Is reachable with Tab"
+        }
+      ],
       "status": "stable",
       "migrationStage": null,
       "docsId": "navigation-containerheader--docs",
-      "storyId": "navigation-containerheader--default",
+      "storyId": "navigation-containerheader--with-title-menu",
       "docPage": "src/ContainerHeader.mdx",
       "app": null,
+      "looks": [
+        "cursor-pointer rounded-md transition-colors hover:bg-bg-hover"
+      ]
+    },
+    {
+      "name": "deleteBlock",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "Removes the block, the caret where it was.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
       "looks": []
     },
     {
@@ -1864,6 +2004,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "duplicateBlock",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "A copy of the block straight after it, the caret in the copy.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "EditableText",
       "repo": "estiva-ui",
@@ -1951,6 +2110,56 @@
         "rounded-md border border-transparent text-left transition-colors hover:border-border-default"
       ]
     },
+    {
+      "name": "EditorBlockHandle",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "`BlockHandle` in a Tiptap editor: drag the handle to move the block, press it for Turn into, Duplicate and Delete, then the app's rows.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "editor",
+          "takes": "Editor | null",
+          "required": true,
+          "note": "The editor. Not editable, or not there yet, and the handle reads: the caller's rows only."
+        },
+        {
+          "name": "turnInto",
+          "takes": "readonly BlockTurnInto[]",
+          "required": false,
+          "note": "Turn into's rows. Offered for a block of text — a paragraph, a heading, code."
+        },
+        {
+          "name": "actions",
+          "takes": "a handler",
+          "required": false,
+          "note": "The caller's own rows, after the editing ones."
+        },
+        {
+          "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-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": "src/EditorBlockHandle.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "EmptyState",
       "repo": "estiva-ui",
@@ -3150,6 +3359,12 @@
           "required": false,
           "note": "A chevron after the title, as `ContainerHeader` draws it."
         },
+        {
+          "name": "titleMenu",
+          "takes": "anything",
+          "required": false,
+          "note": "The menu the title opens — `ContainerHeader`'s: the column's views."
+        },
         {
           "name": "actions",
           "takes": "anything",
@@ -3594,6 +3809,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "moveBlock",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "Moves the block at `from` to `to` (a position between top-level blocks), the caret in it: what a drop in the gutter does, where the editor has no drop of its own.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "NavItem",
       "repo": "estiva-ui",
@@ -3829,6 +4063,18 @@
           "required": false,
           "note": "Beside the title, shown on hover or focus: \"Open\", typically."
         },
+        {
+          "name": "menu",
+          "takes": "anything",
+          "required": false,
+          "note": "The group's \"More options\" menu, after its actions: `MenuItem`s."
+        },
+        {
+          "name": "icon",
+          "takes": "anything",
+          "required": false,
+          "note": "16px, before the title; the arrow takes its place on hover."
+        },
         {
           "name": "defaultOpen",
           "takes": "true/false",
@@ -4131,8 +4377,8 @@
       "docPage": "src/PersonTrigger.mdx",
       "app": null,
       "looks": [
-        "cursor-pointer rounded-md text-body-2 text-text-primary transition-colors hover:bg-bg-hover",
-        "cursor-pointer rounded-md text-body-2 text-text-primary transition-colors hover:bg-bg-hover bg-bg-hover"
+        "text-body-2 text-text-primary cursor-pointer rounded-md transition-colors hover:bg-bg-hover",
+        "text-body-2 text-text-primary cursor-pointer rounded-md transition-colors hover:bg-bg-hover bg-bg-hover"
       ]
     },
     {
@@ -5008,6 +5254,12 @@
           "required": false,
           "note": "Collapsible: draws the chevron and makes the title a button that toggles."
         },
+        {
+          "name": "icon",
+          "takes": "anything",
+          "required": false,
+          "note": "16px, stroke 1.5, before the title — a folder's (Katerina, 5 October: Peek's Folders, the standard heading with a folder icon)."
+        },
         {
           "name": "isExpanded",
           "takes": "true/false",
@@ -5032,6 +5284,18 @@
           "required": false,
           "note": "Right-aligned, in the order given."
         },
+        {
+          "name": "menu",
+          "takes": "anything",
+          "required": false,
+          "note": "The heading's \"More options\" menu: `MenuItem`s — what acts on the whole section, a folder's Rename or Archive (Katerina, 5 October: Peek's Folders page goes, and its folder actions move onto the folder's heading)."
+        },
+        {
+          "name": "menuLabel",
+          "takes": "text",
+          "required": false,
+          "note": "The ⋮'s accessible name. Default \"More options for\" the title."
+        },
         {
           "name": "showActions",
           "takes": "hover | always",
@@ -5095,11 +5359,11 @@
       "docPage": "src/SectionHeader.mdx",
       "app": null,
       "looks": [
+        "opacity-0 transition-[opacity,transform] duration-150 group-hover:opacity-100",
+        "opacity-0 transition-[opacity,transform] duration-150 group-hover:opacity-100 rotate-90",
         "transition-transform duration-150 text-text-secondary rotate-90",
         "rounded-lg transition-colors text-text-secondary hover:text-text-primary",
-        "rounded-lg transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
-        "-mr-1 opacity-0 transition-opacity focus-within:opacity-100 group-hover:opacity-100",
-        "opacity-0 transition-opacity focus-within:opacity-100 group-hover:opacity-100"
+        "rounded-lg transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover"
       ]
     },
     {
@@ -5160,19 +5424,15 @@
       "docPage": "src/SectionLabel.mdx",
       "app": null,
       "looks": [
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-secondary",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-secondary truncate",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-muted",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-muted truncate",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-primary",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-primary truncate",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-secondary",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-secondary truncate",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-muted",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-muted truncate",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-primary",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-primary truncate",
-        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest",
+        "text-h5 leading-3 text-text-secondary truncate",
+        "text-h5 leading-3 text-text-muted truncate",
+        "text-h5 leading-3 text-text-primary truncate",
+        "text-h5 leading-3 leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-secondary",
+        "text-h5 leading-3 leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-secondary truncate",
+        "text-h5 leading-3 leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-muted",
+        "text-h5 leading-3 leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-muted truncate",
+        "text-h5 leading-3 leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-primary",
+        "text-h5 leading-3 leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-primary truncate",
         "leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest"
       ]
     },
@@ -5532,6 +5792,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "startBlockDrag",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "Starts the browser's own drag of the block, as ProseMirror starts one of a selected node: the block selected, its slice on `view.dragging` with `move`, and its HTML on the transfer.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "SuggestionMenu",
       "repo": "estiva-ui",

package/src/BlockHandle.mdx

@@ -0,0 +1,58 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as BlockHandleStories from './BlockHandle.stories'
+
+<Meta of={BlockHandleStories} />
+
+# BlockHandle
+
+The handle left of the block under the pointer, as a block-document page has
+it, and the block's menu behind it. Over a document being read, the menu is
+the app's rows only — a link to the block, a comment on it.
+
+<Canvas of={BlockHandleStories.Default} />
+
+## When
+
+- **A document made of blocks, read by someone who cannot edit it**, when the
+  app has something to offer on one block: a link to it, a comment on it.
+
+## When not
+
+- The same document being edited → **EditorBlockHandle**, from
+  `@estiva-app/ui/editor`: the same handle, which also drags and has Turn
+  into, Duplicate and Delete.
+- Reading a document with nothing to offer on one block → **RichText** alone.
+
+## How
+
+```tsx
+import { BlockHandle, MenuItem, RichText, type HandleBlock, type RichTextBlock } from '@estiva-app/ui'
+
+const blocks: RichTextBlock[] = [{ type: 'paragraph', id: 'b1', inline: [{ text: 'Label', marks: [] }] }]
+const rows = (block: HandleBlock) => <MenuItem label="Copy link" onClick={() => navigator.clipboard.writeText(`#${block.id}`)} />
+
+<BlockHandle actions={rows}>
+  <RichText blocks={blocks} />
+</BlockHandle>
+```
+
+- **Leave room on the left.** The handle sits 28px left of the content, in
+  the page's margin, so wrapping the content moves nothing. A surface flush
+  with its container's left edge clips it.
+- `children` is a surface whose top-level elements carry `data-block-id`, as
+  `RichText` draws them. `HandleBlock.id` is that §13.3 id: what a link or a
+  comment addresses.
+- With no `actions`, or `actions` that return nothing for a block, no handle
+  is drawn.
+- **In the main entry on purpose**: a reader must not download an editor.
+  `editing` is how `EditorBlockHandle` makes this part edit, not a prop to
+  fill by hand.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Finds the block under the pointer, by height: the gap between two blocks belongs to the one above | a pointer handler on each block | |
+| Centres the handle on the block's first line, a heading's or a paragraph's | a position for the handle | |

package/src/BlockHandle.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconLink, IconMessage } from '@tabler/icons-react'
+import { BlockHandle, type HandleBlock } from './BlockHandle'
+import { MenuItem } from './Menu'
+import { RichText, type RichTextBlock } from './RichText'
+
+/**
+ * The handle left of the block under the pointer, over a document being read:
+ * press it for the app's rows. In an editor, `EditorBlockHandle` adds the drag
+ * and the editing rows.
+ */
+const meta = {
+  title: 'Primitives/BlockHandle',
+  // The handle sits 28px left of the content, in the page's margin.
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+/** The rows an app adds: here they only say which block they were pressed on. */
+function rows(block: HandleBlock) {
+  return (
+    <>
+      <MenuItem label="Copy link" leading={<IconLink size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => console.info('copy link', block.id)} />
+      <MenuItem label="Comment" leading={<IconMessage size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => console.info('comment', block.id)} />
+    </>
+  )
+}
+
+const READING: RichTextBlock[] = [
+  { type: 'heading', level: 1, id: 'b1', inline: [{ text: 'A heading', marks: [] }] },
+  { type: 'paragraph', id: 'b2', inline: [{ text: 'Someone who cannot edit this still gets the handle, with the app’s rows only.', marks: [] }] },
+  { type: 'paragraph', id: 'b3', inline: [{ text: 'The second paragraph.', marks: [] }] },
+]
+
+/** Reading: no drag and no editing rows — only what the app adds. */
+export const Default: Story = {
+  render: () => (
+    <BlockHandle actions={rows} className="ml-8 max-w-[560px]">
+      <RichText blocks={READING} />
+    </BlockHandle>
+  ),
+}