@estiva-app/ui 0.44.1 → 0.45.0

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.44.1",
-    "exports": 91,
-    "typeExports": 102,
+    "packageVersion": "0.45.0",
+    "exports": 100,
+    "typeExports": 109,
     "files": null
   },
   "storybook": {
@@ -2651,6 +2651,63 @@
         "text-caption font-medium text-text-primary truncate"
       ]
     },
+    {
+      "name": "isApplePlatform",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/shortcuts.ts",
+      "purpose": "Whether this machine calls the modifier Cmd rather than Ctrl.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": null,
+      "storyId": null,
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "isSuggestionActive",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/suggestionPopup.tsx",
+      "purpose": "Open, or closed less than 100ms ago — what an Enter handler asks.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": null,
+      "storyId": null,
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "isSuggestionOpen",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/suggestionPopup.tsx",
+      "purpose": "Open *now*, with no grace period — what an Escape handler asks.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": null,
+      "storyId": null,
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Kbd",
       "repo": "estiva-ui",
@@ -2704,6 +2761,25 @@
         "border-border-tooltip-key bg-bg-tooltip-key text-text-tooltip-key signal:bg-bg-tooltip-key ship:bg-bg-tooltip-key"
       ]
     },
+    {
+      "name": "KeptSelection",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/SelectionToolbar.tsx",
+      "purpose": "The extension an editor registers so a selection can stay drawn while a field has the focus.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-selectiontoolbar--docs",
+      "storyId": "primitives-selectiontoolbar--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Lightbox",
       "repo": "estiva-ui",
@@ -3394,6 +3470,25 @@
         "text-center font-mono text-caption tabular-nums text-text-muted"
       ]
     },
+    {
+      "name": "normalizeHref",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/SelectionToolbar.tsx",
+      "purpose": "What somebody typed into the link field → an `href`, or null when it cannot be one.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-selectiontoolbar--docs",
+      "storyId": "primitives-selectiontoolbar--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Panel",
       "repo": "estiva-ui",
@@ -4658,6 +4753,84 @@
         "rounded-lg border bg-bg-field shadow-field text-left"
       ]
     },
+    {
+      "name": "SelectionToolbar",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/SelectionToolbar.tsx",
+      "purpose": "Bold, italic and underline — and code or a link where the editor has them — over text you have already selected in an editor.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "editor",
+          "takes": "Editor | null",
+          "required": true,
+          "note": "The editor whose selection the strip follows."
+        },
+        {
+          "name": "marks",
+          "takes": "readonly MarkId[]",
+          "required": false,
+          "note": "Which marks the strip toggles, in order."
+        },
+        {
+          "name": "link",
+          "takes": "true/false",
+          "required": false,
+          "note": "The Link button and its address field. Needs a link mark in the editor and `KeptSelection`."
+        }
+      ],
+      "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-selectiontoolbar--docs",
+      "storyId": "primitives-selectiontoolbar--default",
+      "docPage": "src/SelectionToolbar.mdx",
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "shortcutLabel",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/shortcuts.ts",
+      "purpose": "`Mod-B` → `Cmd+B` on a Mac, `Ctrl+B` elsewhere.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": null,
+      "storyId": null,
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Sidebar",
       "repo": "estiva-ui",
@@ -4786,6 +4959,171 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "SuggestionMenu",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/SuggestionMenu.tsx",
+      "purpose": "The list a text editor opens as you type — `/` for commands, `@` for people — while focus stays in the text.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "rect",
+          "takes": "DOMRect | null",
+          "required": true,
+          "note": "The caret's rect, from the editor. `null` closes the box."
+        },
+        {
+          "name": "editorElement",
+          "takes": "HTMLElement | null",
+          "required": false,
+          "note": "The editor's own element — told which row is active."
+        },
+        {
+          "name": "ariaLabel",
+          "takes": "text",
+          "required": true,
+          "note": "Names the list — \"Commands\", \"People\"."
+        },
+        {
+          "name": "width",
+          "takes": "text",
+          "required": true,
+          "note": "The box's width, e.g. `w-[300px]`."
+        },
+        {
+          "name": "maxHeight",
+          "takes": "text",
+          "required": true,
+          "note": "The cap before the rows scroll, e.g. `max-h-[400px]`."
+        },
+        {
+          "name": "sections",
+          "takes": "readonly SuggestionMenuSection<T>[]",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "itemKey",
+          "takes": "a handler",
+          "required": true,
+          "note": "A stable key for a row."
+        },
+        {
+          "name": "row",
+          "takes": "a handler",
+          "required": true,
+          "note": "What a row shows."
+        },
+        {
+          "name": "onSelect",
+          "takes": "a handler",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "handle",
+          "takes": "Ref<SuggestionMenuHandle>",
+          "required": false,
+          "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"
+        },
+        {
+          "id": "walking",
+          "behaviour": "Moves through its items with the arrow keys"
+        },
+        {
+          "id": "role",
+          "behaviour": "Says what it is to assistive technology"
+        }
+      ],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-suggestionmenu--docs",
+      "storyId": "primitives-suggestionmenu--default",
+      "docPage": "src/SuggestionMenu.mdx",
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "suggestionPopup",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/suggestionPopup.tsx",
+      "purpose": "The `render` of a Tiptap suggestion plugin, drawn as a `SuggestionMenu` — the popup controller Peek wrote four times (`mention.tsx`, `slashCommands.tsx`), once.",
+      "purposeFrom": "comment",
+      "props": [
+        {
+          "name": "ariaLabel",
+          "takes": "text",
+          "required": true,
+          "note": "Names the list — \"Commands\", \"People\"."
+        },
+        {
+          "name": "width",
+          "takes": "text",
+          "required": true,
+          "note": "The box's width, e.g. `w-[300px]`."
+        },
+        {
+          "name": "maxHeight",
+          "takes": "text",
+          "required": true,
+          "note": "The cap before the rows scroll, e.g. `max-h-[400px]`."
+        },
+        {
+          "name": "sections",
+          "takes": "a handler",
+          "required": false,
+          "note": "The plugin's items, and the typed query, → the sections to draw."
+        },
+        {
+          "name": "itemKey",
+          "takes": "a handler",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "row",
+          "takes": "a handler",
+          "required": true,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": null,
+      "storyId": null,
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Tabs",
       "repo": "estiva-ui",

package/src/SelectionToolbar.mdx

@@ -0,0 +1,78 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as SelectionToolbarStories from './SelectionToolbar.stories'
+
+<Meta of={SelectionToolbarStories} />
+
+# SelectionToolbar
+
+Bold, italic and underline — and code or a link where the editor has them —
+over text you have already selected in an editor.
+
+<Canvas of={SelectionToolbarStories.Default} />
+
+## When
+
+- **Inside any Tiptap editor.** It mounts with the editor and decides for
+  itself when to appear: once a selection has stood still, centred over it.
+- `marks` chooses the buttons, in order: `bold`, `italic`, `underline`, `code`.
+  The default is the first three.
+- `link` adds the Link button, which turns the strip into one field for the
+  address. Select words that are already a link and the field opens by itself,
+  their address in it.
+
+## When not
+
+- In the `/` list → **SuggestionMenu**. Typing `/` replaces the selection, so
+  there is nothing selected to apply a mark to.
+- A strip of actions on a card or an image → **Toolbar** in a **Popover**. This
+  one's placement exists to centre over a text selection.
+
+## How
+
+```tsx
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { SelectionToolbar, KeptSelection } from '@estiva-app/ui/editor'
+
+const editor = useEditor({ extensions: [StarterKit, KeptSelection], content: text })
+
+<EditorContent editor={editor} />
+<SelectionToolbar editor={editor} marks={['bold', 'italic', 'underline', 'code']} link />
+```
+
+- `editor` is the Tiptap editor, or `null` while it loads. There is nothing to
+  place: it anchors itself to the selection.
+- **`link` needs two things in the editor**: a link mark, and `KeptSelection`,
+  which keeps the words highlighted while the address field has the focus.
+  Without a link mark, leave `link` off.
+- **Each mark must be in the editor's schema.** A button for a mark the editor
+  lacks does nothing.
+- **The address field:** Enter applies it, and so does clicking away. Enter on
+  an empty field removes the link; clicking away with an empty field changes
+  nothing. Escape drops what was typed. `http`, `https` and `mailto` only; a
+  bare host gets `https://`.
+
+<Canvas of={SelectionToolbarStories.WithALink} />
+
+## What it owns
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Appears once a selection has stood still, never mid-drag or on a plain click | a selection listener, a timer | |
+| Centres itself over the selection, above it | position arithmetic | |
+| Keeps the caret in the text while a button is pressed | `preventDefault` on each button | |
+| Keeps the words highlighted while the address field has focus | a second selection | |
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Cmd/Ctrl+B, I, U, E | bold, italic, underline, code — the editor's own keys, named in each tooltip |
+| Tab | onto the strip, as any `Toolbar` |
+| ← / → | between the buttons |
+| Enter, in the address field | applies it; empty removes the link |
+| Escape, in the address field | drops what was typed and puts the caret back |
+
+## Props
+
+<Controls of={SelectionToolbarStories.Default} />

package/src/SelectionToolbar.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { richTextClassName } from './RichText'
+import { KeptSelection, SelectionToolbar, type MarkId } from './SelectionToolbar'
+
+/**
+ * Bold, italic, underline — and code or link where the editor has them — over
+ * text you have already selected. It follows the selection by itself.
+ */
+const meta = {
+  title: 'Primitives/SelectionToolbar',
+  component: SelectionToolbar,
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+/**
+ * A real editor with a few words selected as it opens, so the strip is on
+ * screen without a drag — it appears the way it always does, once the
+ * selection has stood still. Select other words to move it.
+ */
+function WithAnEditor({ marks, link, html, select }: { marks?: readonly MarkId[]; link?: boolean; html: string; select: [number, number] }) {
+  const editor = useEditor({
+    extensions: [StarterKit, KeptSelection],
+    content: html,
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+    onCreate: ({ editor: e }) => {
+      e.commands.focus()
+      e.commands.setTextSelection({ from: select[0], to: select[1] })
+    },
+  })
+  return (
+    <div className="pt-16">
+      <EditorContent editor={editor} className="max-w-[560px]" />
+      <SelectionToolbar editor={editor} marks={marks} link={link} />
+    </div>
+  )
+}
+
+const TEXT = '<p>Select a few words in this line, and the strip appears over them.</p>'
+
+/** The default strip: bold, italic, underline. */
+export const Default: Story = {
+  render: () => <WithAnEditor html={TEXT} select={[10, 19]} />,
+}
+
+/** `marks` chooses the buttons: here code as well. */
+export const WithCode: Story = {
+  render: () => <WithAnEditor html={TEXT} select={[10, 19]} marks={['bold', 'italic', 'underline', 'code']} />,
+}
+
+/** `link` adds the Link button, which opens one field for the address. */
+export const WithALink: Story = {
+  render: () => <WithAnEditor html={TEXT} select={[10, 19]} link />,
+}
+
+/** Words that are already a link open straight on the field, their address in it. */
+export const OnALink: Story = {
+  render: () => <WithAnEditor html={'<p>Select <a href="https://example.com">these words</a> to change where they go.</p>'} select={[8, 19]} link />,
+}

package/src/SelectionToolbar.test.ts

@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+/**
+ * The selection toolbar's helpers (UIG-31), carried over with it: how a key is
+ * named in a tooltip, and what the address field does to the text. Drawing the
+ * strip needs a real selection standing still, which jsdom cannot make; the
+ * stories show it in a browser.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { KeptSelection, applyLink, currentLink, normalizeHref } from './SelectionToolbar'
+import { shortcutLabel } from './shortcuts'
+
+let editor: Editor
+
+beforeEach(() => {
+  editor = new Editor({ extensions: [StarterKit, KeptSelection], content: '<p>read the linked words first</p>' })
+})
+
+afterEach(() => {
+  editor.destroy()
+})
+
+describe('shortcutLabel', () => {
+  it('says Cmd on Apple platforms', () => {
+    expect(shortcutLabel('Mod-B', true)).toBe('Cmd+B')
+    expect(shortcutLabel('Mod-Shift-B', true)).toBe('Cmd+Shift+B')
+  })
+
+  it('says Ctrl everywhere else', () => {
+    expect(shortcutLabel('Mod-B', false)).toBe('Ctrl+B')
+    expect(shortcutLabel('Mod-Shift-B', false)).toBe('Ctrl+Shift+B')
+  })
+
+  it('upper-cases a single-character key so Ctrl+b never reaches a tooltip', () => {
+    expect(shortcutLabel('Mod-b', false)).toBe('Ctrl+B')
+  })
+})
+
+describe('the marks the strip can toggle are in a standard editor', () => {
+  it.each(['bold', 'italic', 'underline', 'code', 'link'])('%s', (mark) => {
+    expect(Object.keys(editor.schema.marks)).toContain(mark)
+  })
+})
+
+describe('normalizeHref — what typing in the field becomes', () => {
+  const cases: Array<[string, string | null]> = [
+    ['https://example.com/a/b', 'https://example.com/a/b'],
+    ['http://example.com', 'http://example.com'],
+    ['mailto:someone@example.com', 'mailto:someone@example.com'],
+    ['example.com', 'https://example.com'],
+    ['  www.example.com/a?b=c  ', 'https://www.example.com/a?b=c'],
+    ['localhost:5173/page', 'https://localhost:5173/page'],
+    ['javascript:alert(1)', null],
+    ['ftp://files.example.com', null],
+    ['two words', null],
+    ['', null],
+    ['   ', null],
+  ]
+  it.each(cases)('%j → %j', (raw, href) => {
+    expect(normalizeHref(raw)).toBe(href)
+  })
+})
+
+describe('applyLink — over "linked words" in "read the linked words first"', () => {
+  /** The one linked run in the document, or null. */
+  const linkOf = (): { text: string; href: string } | null => {
+    let found: { text: string; href: string } | null = null
+    editor.state.doc.descendants((node) => {
+      const link = node.marks.find((m) => m.type.name === 'link')
+      if (node.isText && link) found = { text: node.text ?? '', href: link.attrs.href as string }
+    })
+    return found
+  }
+
+  beforeEach(() => {
+    editor.commands.setTextSelection({ from: 10, to: 22 })
+  })
+
+  it('an address links the selected words, completing a bare host', () => {
+    expect(applyLink(editor, 'example.com')).toBe(true)
+    expect(linkOf()).toEqual({ text: 'linked words', href: 'https://example.com' })
+    expect(currentLink(editor)).toBe('https://example.com')
+  })
+
+  it('an empty field removes the link', () => {
+    applyLink(editor, 'https://example.com')
+    expect(applyLink(editor, '')).toBe(true)
+    expect(linkOf()).toBeNull()
+    expect(currentLink(editor)).toBe('')
+  })
+
+  it('a scheme a reader may not follow is refused, and nothing changes', () => {
+    expect(applyLink(editor, 'javascript:alert(1)')).toBe(false)
+    expect(linkOf()).toBeNull()
+  })
+
+  it('the caret inside a link re-addresses the whole link', () => {
+    applyLink(editor, 'https://example.com')
+    editor.commands.setTextSelection(15)
+    expect(currentLink(editor)).toBe('https://example.com')
+    expect(applyLink(editor, 'https://example.org')).toBe(true)
+    expect(linkOf()).toEqual({ text: 'linked words', href: 'https://example.org' })
+  })
+})