@estiva-app/ui 0.54.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.54.0",
+  "version": "0.55.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.55.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",
@@ -1691,6 +1773,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "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": []
+    },
     {
       "name": "DialogShell",
       "repo": "estiva-ui",
@@ -1864,6 +1965,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 +2071,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",
@@ -3594,6 +3764,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",
@@ -5532,6 +5721,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>
+  ),
+}

package/src/BlockHandle.test.tsx

@@ -0,0 +1,216 @@
+// @vitest-environment jsdom
+/**
+ * The block handle (RIC-18): what its rows do to the document, and which rows
+ * it offers. The drag itself is the browser's and is driven in real Chromium
+ * (the PR says how); here, the slice it starts with and what a drop of it keeps.
+ */
+import { afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { act, cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockHandle } from './BlockHandle'
+import { BlockId } from './BlockNodes'
+import { EditorBlockHandle, deleteBlock, duplicateBlock, moveBlock, startBlockDrag } from './EditorBlockHandle'
+import { MenuItem } from './Menu'
+
+const DOCUMENT = {
+  type: 'doc',
+  content: [
+    { type: 'paragraph', attrs: { blockId: 'p1' }, content: [{ type: 'text', text: 'one' }] },
+    { type: 'paragraph', attrs: { blockId: 'p2' }, content: [{ type: 'text', text: 'two' }] },
+  ],
+}
+
+type Json = { type: string; attrs?: Record<string, unknown>; content?: Json[] }
+const editors: Editor[] = []
+function editor(content: object = DOCUMENT) {
+  const e = new Editor({ extensions: [StarterKit, BlockId], content })
+  editors.push(e)
+  return e
+}
+const ids = (e: Editor) => (e.getJSON().content as Json[]).map((b) => b.attrs?.blockId)
+const posOf = (e: Editor, id: string) => {
+  let at = -1
+  e.state.doc.forEach((node, pos) => {
+    if (node.attrs.blockId === id) at = pos
+  })
+  return at
+}
+
+/**
+ * Press and release on the handle. Base UI opens a menu on the press; under
+ * jsdom `user.click`'s own move-press-release-click left it shut, while the
+ * same handle opens on a click in Chromium (the story, driven in the PR).
+ */
+async function press(user: ReturnType<typeof userEvent.setup>, target: HTMLElement) {
+  await user.pointer({ keys: '[MouseLeft>]', target })
+  await user.pointer({ keys: '[/MouseLeft]', target })
+  await screen.findByRole('menu')
+}
+
+// jsdom lays nothing out, so a Range has no rects. The editor measures the caret
+// a frame after Duplicate, Delete or a move gives it the focus back; under load
+// that frame came while a test still ran (CI, 5 October), and threw.
+beforeAll(() => {
+  const none = { top: 0, bottom: 0, left: 0, right: 0, width: 0, height: 0, x: 0, y: 0, toJSON: () => ({}) }
+  Range.prototype.getClientRects = () => [] as unknown as DOMRectList
+  Range.prototype.getBoundingClientRect = () => none as DOMRect
+})
+
+afterEach(() => {
+  cleanup()
+  for (const e of editors.splice(0)) e.destroy()
+})
+
+describe('duplicateBlock', () => {
+  it('puts a copy after the block, and the copy gets an id of its own', () => {
+    const e = editor()
+    duplicateBlock(e, posOf(e, 'p1'))
+    const [first, copy, last] = ids(e)
+    expect(first).toBe('p1')
+    expect(copy).toMatch(/^[0-9a-f]{12}$/)
+    expect(last).toBe('p2')
+    expect(e.getText()).toBe('one\n\none\n\ntwo')
+  })
+
+  it('then deleting the copy gives back the document it started from', () => {
+    const e = editor()
+    const before = e.getJSON()
+    duplicateBlock(e, posOf(e, 'p2'))
+    deleteBlock(e, posOf(e, ids(e)[2] as string))
+    expect(e.getJSON()).toEqual(before)
+  })
+})
+
+describe('deleteBlock', () => {
+  it('removes the block and leaves the others their ids', () => {
+    const e = editor()
+    deleteBlock(e, posOf(e, 'p1'))
+    expect(ids(e)).toEqual(['p2'])
+  })
+
+  it('leaves an empty paragraph when it was the only block', () => {
+    const e = editor({ type: 'doc', content: [DOCUMENT.content[0]] })
+    deleteBlock(e, 0)
+    expect(e.getText()).toBe('')
+    expect(e.state.doc.childCount).toBe(1)
+  })
+})
+
+describe('moveBlock', () => {
+  it('moves the block whole, so it keeps its id, as a drop in the gutter does', () => {
+    const e = editor()
+    moveBlock(e, posOf(e, 'p1'), e.state.doc.content.size)
+    expect(ids(e)).toEqual(['p2', 'p1'])
+    expect(e.getText()).toBe('two\n\none')
+  })
+
+  it('does nothing when the block would land where it is', () => {
+    const e = editor()
+    const before = e.getJSON()
+    expect(moveBlock(e, posOf(e, 'p2'), posOf(e, 'p2'))).toBe(false)
+    expect(e.getJSON()).toEqual(before)
+  })
+})
+
+describe('startBlockDrag', () => {
+  it('selects the block and drags its slice, with its id, as a move', () => {
+    const e = editor()
+    const transfer = { data: {} as Record<string, string>, clearData() {}, setData(type: string, value: string) { this.data[type] = value }, effectAllowed: '' }
+    startBlockDrag(e, posOf(e, 'p2'), { dataTransfer: transfer as unknown as DataTransfer })
+    expect(e.view.dragging?.move).toBe(true)
+    expect(e.view.dragging?.slice.content.firstChild?.attrs.blockId).toBe('p2')
+    expect(e.state.selection.from).toBe(posOf(e, 'p2'))
+    expect(transfer.data['text/plain']).toBe('two')
+  })
+
+  it('a drop of that slice, as ProseMirror makes it, keeps the id', () => {
+    const e = editor()
+    startBlockDrag(e, posOf(e, 'p1'), { dataTransfer: null })
+    // ProseMirror's drop: delete the selection, then insert the slice's node at the drop point.
+    const node = e.view.dragging!.slice.content.firstChild!
+    const tr = e.state.tr.deleteSelection()
+    tr.insert(tr.doc.content.size, node)
+    e.view.dispatch(tr)
+    expect(ids(e)).toEqual(['p2', 'p1'])
+  })
+})
+
+describe('BlockHandle', () => {
+  it('reading, offers only the caller’s rows and does not drag', async () => {
+    render(
+      <BlockHandle actions={(b) => <MenuItem label={`Copy link ${b.id}`} onClick={() => {}} />}>
+        <div>
+          <p data-block-id="r1">read me</p>
+        </div>
+      </BlockHandle>,
+    )
+    const user = userEvent.setup()
+    await user.hover(screen.getByText('read me'))
+    const handle = screen.getByRole('button', { name: 'Block menu' })
+    expect(handle.getAttribute('draggable')).toBe('false')
+    await press(user, handle)
+    expect(screen.getAllByRole('menuitem').map((r) => r.textContent)).toEqual(['Copy link r1'])
+  })
+
+  it('reading with no rows of the caller’s, draws no handle', async () => {
+    render(
+      <BlockHandle>
+        <div>
+          <p data-block-id="r1">read me</p>
+        </div>
+      </BlockHandle>,
+    )
+    await userEvent.setup().hover(screen.getByText('read me'))
+    expect(screen.queryByRole('button', { name: 'Block menu' })).toBeNull()
+  })
+
+  it('editing, Delete from the menu removes the block', async () => {
+    const e = editor()
+    const { EditorContent } = await import('@tiptap/react')
+    render(
+      <EditorBlockHandle editor={e}>
+        <EditorContent editor={e} />
+      </EditorBlockHandle>,
+    )
+    const user = userEvent.setup()
+    // jsdom lays nothing out: every block's top is 0, so the pointer is on the last.
+    await act(async () => user.hover(screen.getByText('two')))
+    await press(user, screen.getByRole('button', { name: 'Block menu' }))
+    expect(screen.getAllByRole('menuitem').map((r) => r.textContent)).toEqual(['Duplicate', 'Delete'])
+    await user.click(screen.getByRole('menuitem', { name: 'Delete' }))
+    // The editor takes the focus back a frame later and measures the caret then: wait for it, so it is part of the test.
+    await act(() => new Promise<void>((done) => requestAnimationFrame(() => done())))
+    expect(ids(e)).toEqual(['p1'])
+  })
+
+  it('an editor that cannot be edited gets the caller’s rows only, and no drag', async () => {
+    const e = editor()
+    e.setEditable(false)
+    const { EditorContent } = await import('@tiptap/react')
+    render(
+      <EditorBlockHandle editor={e} actions={(b) => <MenuItem label={`Copy link ${b.id}`} onClick={() => {}} />}>
+        <EditorContent editor={e} />
+      </EditorBlockHandle>,
+    )
+    const user = userEvent.setup()
+    await act(async () => user.hover(screen.getByText('two')))
+    const handle = screen.getByRole('button', { name: 'Block menu' })
+    expect(handle.getAttribute('draggable')).toBe('false')
+    await press(user, handle)
+    expect(screen.getAllByRole('menuitem').map((r) => r.textContent)).toEqual(['Copy link p2'])
+  })
+
+  it('draws no handle before its editor exists', async () => {
+    render(
+      <EditorBlockHandle editor={null} actions={() => <MenuItem label="Copy link" onClick={() => {}} />}>
+        <div>
+          <p data-block-id="r1">not yet</p>
+        </div>
+      </EditorBlockHandle>,
+    )
+    await userEvent.setup().hover(screen.getByText('not yet'))
+    expect(screen.queryByRole('button', { name: 'Block menu' })).toBeNull()
+  })
+})