@estiva-app/ui 0.65.3 → 0.67.0

package/src/BlockNodes.tsx

@@ -1,9 +1,12 @@
 import type { ComponentType } from 'react'
-import { Extension, Node } from '@tiptap/core'
-import type { Node as ProseMirrorNode, Slice } from '@tiptap/pm/model'
-import { Plugin, PluginKey, type Transaction } from '@tiptap/pm/state'
+import { Extension, InputRule, Node, type Editor } from '@tiptap/core'
+import { DOMSerializer, type Node as ProseMirrorNode, type Slice } from '@tiptap/pm/model'
+import { Plugin, PluginKey, type EditorState, type Transaction } from '@tiptap/pm/state'
 import { Mapping, ReplaceAroundStep } from '@tiptap/pm/transform'
-import { NodeViewWrapper, ReactNodeViewRenderer, type ReactNodeViewProps } from '@tiptap/react'
+import type { EditorView, NodeView } from '@tiptap/pm/view'
+import { NodeViewWrapper, ReactNodeViewRenderer, ReactRenderer, type ReactNodeViewProps } from '@tiptap/react'
+import { Checkbox, type CheckboxProps } from './Checkbox'
+import { calloutLook } from './RichText'
 
 /*
  * The four nodes an editor of a block document needs that a stock schema does
@@ -529,3 +532,223 @@ export const AttachmentNode = Node.create<AttachmentNodeOptions>({
     ))
   },
 })
+
+const TICK = 'checklistTick'
+
+/**
+ * Whether a change is a click on a checklist item's box. The click does not
+ * focus the editor, so no blur follows it: an editor that saves on blur saves
+ * a tick straight away instead (RIC-19, Miky 2026-10-13: one click ticks).
+ */
+export function isChecklistTick(transaction: Transaction): boolean {
+  return transaction.getMeta(TICK) === true
+}
+
+/** A list or quote command by name: StarterKit's declare them, and this package builds without StarterKit. */
+type Chain = ReturnType<Editor['chain']>
+function named(chain: Chain, command: string, ...args: unknown[]): Chain {
+  const own = (chain as unknown as Record<string, ((...a: unknown[]) => Chain) | undefined>)[command]
+  return own ? own(...args) : chain
+}
+
+/** The list item the caret's paragraph is the first line of, if it is. */
+function itemAtCaret(state: EditorState): { node: ProseMirrorNode; pos: number } | null {
+  const { $from } = state.selection
+  if ($from.depth < 2) return null
+  const item = $from.node(-1)
+  if (item.type.name !== 'listItem' || $from.index(-1) !== 0) return null
+  return { node: item, pos: $from.before(-1) }
+}
+
+const sameAttrs = (a: ProseMirrorNode, b: ProseMirrorNode) =>
+  Object.keys({ ...a.attrs, ...b.attrs }).every((key) => a.attrs[key] === b.attrs[key])
+
+/**
+ * A list item, drawn with a box before it when it is a checklist item. The box
+ * is the package's `Checkbox`, as `RichText` draws it, and the item's own
+ * text and inner lists follow it in a `div`. Any change to the item's
+ * attributes draws it again, which is what a tick is.
+ *
+ * The box is named by the item's words, and follows them as they are typed.
+ * Whether it ticks follows the editor's `editable`, read again on every
+ * update — `setEditable` sends one — not only when the item was drawn
+ * (Katerina, review of #170). Not editable, it is a picture, and the box around
+ * it says done or not to a screen reader, as `RichText`'s does.
+ */
+function listItemView(editor: Editor, node: ProseMirrorNode, view: EditorView, getPos: () => number | undefined): NodeView {
+  const toDOM = node.type.spec.toDOM
+  const { dom, contentDOM } = toDOM ? DOMSerializer.renderSpec(document, toDOM(node)) : { dom: document.createElement('li'), contentDOM: undefined }
+  const checked = node.attrs.checked
+  if (typeof checked !== 'boolean') return { dom, contentDOM: contentDOM ?? dom, update: (next) => next.type === node.type && sameAttrs(next, node) }
+
+  const li = dom as HTMLElement
+  const box = document.createElement('span')
+  box.contentEditable = 'false'
+  box.setAttribute('data-checklist-box', '')
+  const body = document.createElement('div')
+  li.replaceChildren(box, body)
+  const tick = (next: boolean) => {
+    const pos = getPos()
+    if (pos === undefined || !view.editable) return
+    view.dispatch(view.state.tr.setNodeAttribute(pos, 'checked', next).setMeta(TICK, true))
+  }
+  let words = node.firstChild?.textContent.trim() || 'Item'
+  const props = (): CheckboxProps => ({ checked, onChange: view.editable ? tick : undefined, 'aria-label': words })
+  const renderer = new ReactRenderer<unknown, CheckboxProps>(Checkbox, { editor, props: props(), as: 'span' })
+  box.appendChild(renderer.element)
+  // What the box last drew: an update that changes neither leaves it alone, so typing does not draw every box again.
+  let drawn = ''
+  const sync = () => {
+    const now = `${view.editable}:${words}`
+    if (now === drawn) return
+    drawn = now
+    renderer.updateProps(props())
+    for (const [name, value] of Object.entries({ role: 'checkbox', 'aria-checked': String(checked), 'aria-readonly': 'true', 'aria-label': words })) {
+      if (view.editable) box.removeAttribute(name)
+      else box.setAttribute(name, value)
+    }
+  }
+  sync()
+  editor.on('update', sync)
+  return {
+    dom: li,
+    contentDOM: body,
+    update: (next) => {
+      if (next.type !== node.type || !sameAttrs(next, node)) return false
+      words = next.firstChild?.textContent.trim() || 'Item'
+      sync()
+      return true
+    },
+    stopEvent: (event) => box.contains(event.target as globalThis.Node),
+    ignoreMutation: (mutation) => box.contains(mutation.target),
+    destroy: () => {
+      editor.off('update', sync)
+      renderer.destroy()
+    },
+  }
+}
+
+/**
+ * A checklist item — SPEC §13.3's `checked` on a list item (RIC-19): `true`
+ * ticked, `false` not, absent a plain item. Add it beside `BlockId`.
+ *
+ * - **The box ticks with one click**, where the description is read, and the
+ *   change says so (`isChecklistTick`), so the app saves it at once.
+ * - **`[ ] ` or `[] ` at the start of a line** makes it, `[x] ` ticked; in a
+ *   list it turns that item into one.
+ * - **Enter** starts the next item unticked: a new item never takes the tick
+ *   of the one it was split from. At the start of an item, the text moves down
+ *   with its tick and the empty item above is unticked. On an empty item Enter
+ *   leaves the list, as in any list.
+ * - **Backspace** at the start of a checklist item takes its box away first;
+ *   the next one joins it to the item above, as in any list.
+ *
+ * An editor without it drops `checked` on save and keeps the item and its text.
+ */
+export const Checklist = Extension.create({
+  name: 'checklist',
+  // Before the list item's own Enter and Backspace.
+  priority: 101,
+  addGlobalAttributes() {
+    return [
+      {
+        types: ['listItem'],
+        attributes: {
+          checked: {
+            default: null,
+            keepOnSplit: false,
+            parseHTML: (element: HTMLElement) => {
+              const value = element.getAttribute('data-checked')
+              return value === 'true' ? true : value === 'false' ? false : null
+            },
+            renderHTML: (attributes: Record<string, unknown>) =>
+              typeof attributes.checked === 'boolean' ? { 'data-checked': String(attributes.checked) } : {},
+          },
+        },
+      },
+    ]
+  },
+  addInputRules() {
+    return [
+      new InputRule({
+        find: /^\[([ xX]?)\]\s$/,
+        handler: ({ state, range, match, chain }) => {
+          const checked = match[1].toLowerCase() === 'x'
+          const inList = itemAtCaret(state) !== null
+          // Without a bullet list to make, the typed text stays as it was typed.
+          if (!inList && !(chain() as unknown as Record<string, unknown>).toggleBulletList) return null
+          const deleted = chain().deleteRange(range)
+          const listed = inList ? deleted : named(deleted, 'toggleBulletList')
+          listed.updateAttributes('listItem', { checked }).run()
+        },
+      }),
+    ]
+  },
+  addKeyboardShortcuts() {
+    return {
+      Enter: () => {
+        const { state } = this.editor
+        const item = itemAtCaret(state)
+        const { $from, empty } = state.selection
+        if (!item || typeof item.node.attrs.checked !== 'boolean') return false
+        // Over a selection: the selection goes and the next item is unticked, as for a caret in the text.
+        if (!empty) return this.editor.chain().deleteSelection().splitListItem('listItem', { checked: false }).run()
+        // An empty item: the list item's own Enter, which leaves the list.
+        if ($from.parent.content.size === 0) return false
+        if ($from.parentOffset > 0) return this.editor.commands.splitListItem('listItem', { checked: false })
+        return this.editor
+          .chain()
+          .splitListItem('listItem', { checked: item.node.attrs.checked })
+          .command(({ tr }) => {
+            tr.setNodeAttribute(tr.mapping.map(item.pos), 'checked', false)
+            return true
+          })
+          .run()
+      },
+      Backspace: () => {
+        const { state } = this.editor
+        const item = itemAtCaret(state)
+        const { $from, empty } = state.selection
+        if (!item || !empty || $from.parentOffset > 0 || typeof item.node.attrs.checked !== 'boolean') return false
+        this.editor.view.dispatch(state.tr.setNodeAttribute(item.pos, 'checked', null))
+        return true
+      },
+    }
+  },
+  addProseMirrorPlugins() {
+    const editor = this.editor
+    return [
+      new Plugin({
+        key: new PluginKey('checklist'),
+        props: { nodeViews: { listItem: (node, view, getPos) => listItemView(editor, node, view, getPos) } },
+      }),
+    ]
+  },
+})
+
+/**
+ * A callout — SPEC §13.3's `tone` on a quote (RIC-19): a quote drawn to stand
+ * out, in one of GitHub's alert kinds (`note`, `tip`, `important`, `warning`,
+ * `caution`). Its look is `RichText`'s, by `data-tone`; a tone it does not
+ * know looks like `note`, and the editor keeps it as written. Add it beside
+ * `BlockId`.
+ */
+export const Callout = Extension.create({
+  name: 'callout',
+  addGlobalAttributes() {
+    return [
+      {
+        types: ['blockquote'],
+        attributes: {
+          tone: {
+            default: null,
+            parseHTML: (element: HTMLElement) => element.getAttribute('data-tone'),
+            // As `RichText` draws it: the tone as written, and the look it is drawn in.
+            renderHTML: (attributes: Record<string, unknown>) =>
+              typeof attributes.tone === 'string' ? { 'data-tone': attributes.tone, 'data-callout': calloutLook(attributes.tone) } : {},
+          },
+        },
+      },
+    ]
+  },
+})

package/src/ComposerTriggers.test.tsx

@@ -27,6 +27,7 @@ import {
   type SlashSection,
 } from './ComposerTriggers'
 import { isSuggestionActive, isSuggestionOpen } from './suggestionPopup'
+import { Callout, Checklist } from './BlockNodes'
 
 const KEY = 'b'.repeat(64)
 const PEOPLE: MentionPerson[] = [
@@ -549,3 +550,25 @@ describe('/', () => {
     expect(hint(formatSection())).toBe('`')
   })
 })
+
+describe('/ in a block editor — RIC-19', () => {
+  function BlockComposer({ blocks }: { blocks: boolean }) {
+    const made = useEditor({
+      extensions: [StarterKit, ...(blocks ? [Checklist, Callout] : []), SlashCommands.configure({ sections: [formatSection('block')] })],
+    })
+    editor = made
+    return <EditorContent editor={made} />
+  }
+
+  it('offers Checklist, Note and Warning where the editor has Checklist and Callout', async () => {
+    render(<BlockComposer blocks />)
+    await type('/')
+    expect(options()?.slice(-3)).toEqual(['Checklist[]', 'Note', 'Warning'])
+  })
+
+  it('offers none of them where it has not: they would make a plain bullet and a plain quote (Katerina, review of #170)', async () => {
+    render(<BlockComposer blocks={false} />)
+    await type('/')
+    expect(options()).toEqual(['Text', 'Heading#', 'Subheading##', 'Quote>', 'Code```', 'Bulleted list-', 'Numbered list1.'])
+  })
+})

package/src/ComposerTriggers.tsx

@@ -433,14 +433,23 @@ export interface SlashCommand {
   keywords?: readonly string[]
   /** Runs once the `/query` that summoned the list has been removed. */
   run: (editor: Editor) => void
+  /**
+   * The extensions (by name) the row needs: an editor without one of them is
+   * not offered the row, so no row makes something the editor cannot hold.
+   */
+  needs?: readonly string[]
 }
 
+/** Whether an editor has every extension a row needs. */
+const offers = (editor: Editor, command: SlashCommand) =>
+  !command.needs || command.needs.every((name) => editor.extensionManager.extensions.some((extension) => extension.name === name))
+
 export interface SlashSection {
   label: string
   commands: readonly SlashCommand[]
 }
 
-export type FormatId = 'paragraph' | 'heading' | 'subheading' | 'quote' | 'bulletList' | 'orderedList' | 'code'
+export type FormatId = 'paragraph' | 'heading' | 'subheading' | 'quote' | 'bulletList' | 'orderedList' | 'code' | 'checklist' | 'note' | 'warning'
 
 export interface FormatDef {
   id: FormatId
@@ -466,6 +475,19 @@ export const FORMATS: readonly FormatDef[] = [
   { id: 'orderedList', label: 'Numbered list', trigger: '1.' },
 ]
 
+/**
+ * What only a document holds — a checklist item and a callout (RIC-19) — so
+ * only a block editor's `/` offers them (`formatSection('block')`): a
+ * message's text has no spelling for either. They need the `Checklist` and
+ * `Callout` extensions. Note and Warning are the two callouts offered (Miky,
+ * 2026-10-13); the other tones are read and kept, not offered.
+ */
+const DOCUMENT_FORMATS: readonly FormatDef[] = [
+  { id: 'checklist', label: 'Checklist', trigger: '[]' },
+  { id: 'note', label: 'Note' },
+  { id: 'warning', label: 'Warning' },
+]
+
 /** Code as a mark inside the line, or as a block of its own. */
 export type CodeFormat = 'inline' | 'block'
 
@@ -501,19 +523,50 @@ export function applyFormat(editor: Editor, id: FormatId, code: CodeFormat = 'in
       return run('toggleOrderedList')
     case 'code':
       return run(code === 'block' ? 'toggleCodeBlock' : 'toggleCode')
+    case 'checklist': {
+      // In a list, that item becomes one; elsewhere, the line becomes a list of one.
+      if (!editor.isActive('listItem') && !run('toggleBulletList')) return false
+      // An item already a checklist item keeps its tick.
+      if (typeof editor.getAttributes('listItem').checked === 'boolean') return true
+      return editor.chain().updateAttributes('listItem', { checked: false }).run()
+    }
+    case 'note':
+    case 'warning': {
+      if (!editor.isActive('blockquote') && !run('toggleBlockquote')) return false
+      return editor.chain().updateAttributes('blockquote', { tone: id }).run()
+    }
     default:
       return false
   }
 }
 
-/** The Format section every app's `/` opens with. */
+/** Words a row is also found by, beyond its id. */
+const KEYWORDS: Partial<Record<FormatId, string[]>> = {
+  checklist: ['todo', 'task'],
+  note: ['callout'],
+  warning: ['callout'],
+}
+
+/** The extension a row's block needs: without it the row would make a plain bullet or a plain quote (Katerina, review of #170). */
+const NEEDS: Partial<Record<FormatId, string[]>> = {
+  checklist: ['checklist'],
+  note: ['callout'],
+  warning: ['callout'],
+}
+
+/**
+ * The Format section every app's `/` opens with. A block editor's also offers
+ * a checklist and the callouts — only where the editor has the `Checklist` and
+ * `Callout` extensions (`SlashCommand.needs`).
+ */
 export function formatSection(code: CodeFormat = 'inline'): SlashSection {
   return {
     label: 'Format',
-    commands: FORMATS.map((format) => ({
+    commands: (code === 'block' ? [...FORMATS, ...DOCUMENT_FORMATS] : FORMATS).map((format) => ({
       key: `format-${format.id}`,
       row: { label: format.label, shortcut: (code === 'block' && format.blockTrigger) || format.trigger },
-      keywords: [format.id],
+      keywords: [format.id, ...(KEYWORDS[format.id] ?? [])],
+      ...(NEEDS[format.id] ? { needs: NEEDS[format.id] } : {}),
       run: (editor) => {
         applyFormat(editor, format.id, code)
       },
@@ -565,7 +618,10 @@ export const SlashCommands = Extension.create<SlashCommandsOptions>({
         char: '/',
         startOfLine: false,
         pluginKey: new PluginKey('slashCommands'),
-        items: ({ query }) => filterSlashSections(sections, query).flatMap((section, at) => section.commands.map((command) => ({ ...command, section: at }))),
+        items: ({ query, editor }) =>
+          filterSlashSections(sections, query).flatMap((section, at) =>
+            section.commands.filter((command) => offers(editor, command)).map((command) => ({ ...command, section: at })),
+          ),
         command: ({ editor, range, props }) => {
           editor.chain().focus().deleteRange(range).run()
           props.run(editor)

package/src/EditorTableControls.mdx

@@ -0,0 +1,78 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as EditorTableControlsStories from './EditorTableControls.stories'
+
+<Meta of={EditorTableControlsStories} />
+
+# EditorTableControls
+
+A table's own controls in a Tiptap editor: point at a cell for a handle on its
+row and on its column, and a ➕ bar under the table and right of it.
+
+<Canvas of={EditorTableControlsStories.Default} />
+
+## When
+
+- **An editor whose documents hold tables** — with TableKit
+  (`@tiptap/extension-table`) in its extensions. Point at a cell: the row's
+  handle sits on the table's left edge, the column's on its top edge; each
+  opens Insert (above and below, or left and right), Delete, and Delete
+  table. A header row offers nothing above it, and deleting it makes the next
+  row the header, so a table always opens with its header. From the last row, a ➕ under the table adds a row after it; from the
+  last column, a ➕ right of the table adds a column after it.
+- **Not editable**: nothing is drawn.
+
+## When not
+
+- Moving, duplicating or deleting the table as one block → **EditorBlockHandle**,
+  whose handle stays the table's, in the gutter. Wrap this inside it.
+- A table being read, with no editor → **RichText** draws it; there is nothing
+  to change.
+
+## How
+
+```tsx
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { TableKit } from '@tiptap/extension-table'
+import { BlockId, EditorBlockHandle, EditorTableControls } from '@estiva-app/ui/editor'
+
+const editor = useEditor({ extensions: [StarterKit, TableKit.configure({ table: { resizable: false } }), BlockId] })
+
+<EditorBlockHandle editor={editor}>
+  <EditorTableControls editor={editor}>
+    <EditorContent editor={editor} />
+  </EditorTableControls>
+</EditorBlockHandle>
+```
+
+- **Every control leaves the editor focused**, in the cell it acted on, as the
+  block menu does. An editor that saves when the person leaves it saves these
+  the same way.
+- A table cannot be left with no row or no column: **deleting its only row, or
+  its only column, deletes the table**.
+- The column ➕ hangs 16px right of the table; give the editor that room, as
+  the block handle has its 28px on the left. The row ➕ lies 16px over the top
+  of the block under the table, only while the pointer is on the last row.
+- `appendTableRow`, `appendTableColumn`, `deleteTableRow` and
+  `deleteTableColumn` are the controls' own actions, for a caller that offers
+  them elsewhere (a shortcut, a test).
+
+## 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 |
+|---|---|---|
+| Runs TableKit's own commands with the caret in the cell pointed at | a selection before `addRowAfter` | |
+| Gives new rows and cells fresh ids, the old ones keeping theirs (`BlockId` decides) | an id for a new cell | |
+| Turns a delete that would leave the table empty into a delete of the table | a check of the table's size | |
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Tab, in the last cell | adds a row and moves into it — TableKit's own |
+| Tab / Shift+Tab, in a cell | to the next / previous cell — TableKit's own |
+
+The handles and the ➕ bars are for the pointer: there is no hover on a touch
+screen, and nothing here draws them there yet.

package/src/EditorTableControls.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 { TableKit } from '@tiptap/extension-table'
+import { BlockId } from './BlockNodes'
+import { EditorBlockHandle, blockDropCursor } from './EditorBlockHandle'
+import { EditorTableControls } from './EditorTableControls'
+import { richTextClassName } from './RichText'
+
+/**
+ * A table's controls in an editor. Point at a cell: a handle on its row's left
+ * edge and on its column's top edge, and a ➕ bar under the table and right of
+ * it.
+ */
+const meta = {
+  title: 'Primitives/EditorTableControls',
+  // The block handle sits 28px left of the content, and the column ➕ 16px right of the table.
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const text = (t: string) => [{ type: 'paragraph', content: [{ type: 'text', text: t }] }]
+const row = (type: 'tableHeader' | 'tableCell', ...cells: string[]) => ({ type: 'tableRow', content: cells.map((c) => ({ type, content: text(c) })) })
+
+const DOCUMENT = {
+  type: 'doc',
+  content: [
+    { type: 'paragraph', content: [{ type: 'text', text: 'Point at a cell for its row and column handles.' }] },
+    {
+      type: 'table',
+      content: [row('tableHeader', 'Label', 'Label', 'Label'), row('tableCell', 'Item one', 'Value', 'Value'), row('tableCell', 'Item two', 'Value', 'Value')],
+    },
+    { type: 'paragraph', content: [{ type: 'text', text: 'The bar under the table adds a row; the one right of it, a column.' }] },
+  ],
+}
+
+function Editing({ editable }: { editable: boolean }) {
+  const editor = useEditor({
+    extensions: [StarterKit.configure({ dropcursor: blockDropCursor }), TableKit.configure({ table: { resizable: false } }), BlockId],
+    content: DOCUMENT,
+    editable,
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  return (
+    <EditorBlockHandle editor={editor} className="ml-8 max-w-[560px]">
+      <EditorTableControls editor={editor}>
+        <EditorContent editor={editor} />
+      </EditorTableControls>
+    </EditorBlockHandle>
+  )
+}
+
+/** Point at a cell; press a handle for Insert and Delete, or a ➕ bar to add a row or a column at the end. */
+export const Default: Story = {
+  render: () => <Editing editable />,
+}
+
+/** An editor that is not editable: no controls. */
+export const NotEditable: Story = {
+  render: () => <Editing editable={false} />,
+}