@estiva-app/ui 0.47.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.47.0",
+  "version": "0.49.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.47.0",
-    "exports": 100,
-    "typeExports": 109,
+    "packageVersion": "0.49.0",
+    "exports": 104,
+    "typeExports": 113,
     "files": null
   },
   "storybook": {
@@ -250,6 +250,25 @@
         "opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 focus-visible:opacity-100 transition-opacity"
       ]
     },
+    {
+      "name": "AttachmentNode",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/BlockNodes.tsx",
+      "purpose": "A file placed in a document — SPEC §13.3's `attachment` block (SHI-2).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-blocknodes--docs",
+      "storyId": "primitives-blocknodes--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Avatar",
       "repo": "estiva-ui",
@@ -420,6 +439,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "BlockId",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/BlockNodes.tsx",
+      "purpose": "`id` on every block, carried as the `blockId` attribute.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-blocknodes--docs",
+      "storyId": "primitives-blocknodes--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Breadcrumb",
       "repo": "estiva-ui",
@@ -4274,6 +4312,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "ReferenceNode",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/BlockNodes.tsx",
+      "purpose": "A `nostr:` reference, drawn as the thing it points at — SPEC §13.1.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-blocknodes--docs",
+      "storyId": "primitives-blocknodes--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "RichText",
       "repo": "estiva-ui",
@@ -6008,6 +6065,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "UnknownBlock",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/BlockNodes.tsx",
+      "purpose": "A block this editor has no design for, kept whole.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-blocknodes--docs",
+      "storyId": "primitives-blocknodes--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "useToast",
       "repo": "estiva-ui",

package/src/BlockNodes.mdx

@@ -0,0 +1,82 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as BlockNodesStories from './BlockNodes.stories'
+
+<Meta of={BlockNodesStories} />
+
+# BlockNodes
+
+The Tiptap nodes an editor of a block document needs beside StarterKit: an id
+on every block, a block it cannot edit kept whole, a reference, and a file.
+
+<Canvas of={BlockNodesStories.Default} />
+
+## When
+
+- **An editor that saves a block document** (SPEC §13.3) — anywhere a comment
+  can be anchored to one of its blocks. `BlockId` keeps each block's id across
+  every edit, so the anchor still finds its block after a save.
+- Always with `@estiva-app/protocol`'s `toEditorDocument` to load the document
+  and `fromEditorDocument` (or `publishableFromEditor`) to save it. The node
+  names and the `blockId` attribute are that translation's.
+
+## When not
+
+- Reading a document → **RichText**. Nothing here draws a document that is not
+  being edited.
+- A message composer that writes marker text. It has no block ids to keep.
+
+## How
+
+```tsx
+import type { JSONContent } from '@tiptap/core'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import {
+  AttachmentNode,
+  BlockId,
+  ReferenceNode,
+  UnknownBlock,
+  type AttachmentViewProps,
+  type ReferenceViewProps,
+} from '@estiva-app/ui/editor'
+
+// toEditorDocument(documentForEditing(value, format)), from @estiva-app/protocol
+const opened: JSONContent = { type: 'doc', content: [] }
+
+const Reference = ({ uri }: ReferenceViewProps) => <span>{uri}</span>
+const File = ({ attrs }: AttachmentViewProps) => <span>{String(attrs.filename)}</span>
+
+const editor = useEditor({
+  extensions: [
+    StarterKit,
+    BlockId,
+    UnknownBlock,
+    ReferenceNode.configure({ view: Reference }),
+    AttachmentNode.configure({ view: File }),
+  ],
+  content: opened,
+})
+
+<EditorContent editor={editor} />
+```
+
+- **Load and save through protocol.** `toEditorDocument(documentForEditing(value, format))`
+  opens the stored value; `publishableFromEditor(editor.getJSON())` is what a
+  save writes, with its `contentFormat`.
+- **Add TableKit** (`@tiptap/extension-table`) beside StarterKit. The
+  translation opens a table as `table`, `tableRow`, `tableHeader` and
+  `tableCell` nodes, and ProseMirror drops a node its schema does not have —
+  the save would delete the table.
+- `ReferenceNode`'s `view` gets the `uri` and draws the thing it points at,
+  resolved by the app. Without one, the URI is drawn as text.
+- `AttachmentNode`'s `view` gets the block's `imeta` fields as `attrs`.
+  Without one, the file's name is drawn as text.
+- `UnknownBlock` draws a block the editor has no design for as its text, in a
+  box. It cannot be changed here, only moved or deleted, and it is saved back
+  exactly as it arrived.
+
+<Canvas of={BlockNodesStories.WithoutViews} />
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.

package/src/BlockNodes.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { AttachmentCard } from './AttachmentCard'
+import { InlineChip } from './InlineChip'
+import { richTextClassName } from './RichText'
+import { AttachmentNode, BlockId, ReferenceNode, UnknownBlock, type AttachmentViewProps, type ReferenceViewProps } from './BlockNodes'
+
+/**
+ * The nodes an editor of a block document adds to StarterKit: an id on every
+ * block, a block it cannot edit kept whole, a reference and a file. The app
+ * draws the reference and the file with its own views.
+ */
+const meta = {
+  title: 'Primitives/BlockNodes',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+/** What an app hands `ReferenceNode`: here a chip with a fixed label. */
+function Chip({ uri }: ReferenceViewProps) {
+  return <InlineChip data-uri={uri}>Item one</InlineChip>
+}
+
+/** What an app hands `AttachmentNode`: here the package's card. */
+function File({ attrs }: AttachmentViewProps) {
+  return <AttachmentCard name={String(attrs.filename ?? 'File')} size={Number(attrs.size ?? 0)} contentType={String(attrs.m ?? '')} />
+}
+
+/*
+  The editor's own JSON, as `@estiva-app/protocol`'s `toEditorDocument` hands
+  it over: an id on each block, and an unknown block carrying its text.
+*/
+const DOCUMENT = {
+  type: 'doc',
+  content: [
+    {
+      type: 'paragraph',
+      attrs: { blockId: 'b1' },
+      content: [
+        { type: 'text', text: 'A paragraph, with a reference in it: ' },
+        { type: 'reference', attrs: { uri: 'nostr:naddr1example', marks: [] } },
+      ],
+    },
+    {
+      type: 'unknownBlock',
+      attrs: { blockId: 'b2', source: { type: 'widget', id: 'b2' }, text: 'A block this editor has no design for, kept as it is.' },
+    },
+    { type: 'attachment', attrs: { blockId: 'b3', url: '', m: 'application/pdf', x: '', size: 20480, filename: 'Label.pdf' } },
+    { type: 'paragraph', attrs: { blockId: 'b4' }, content: [{ type: 'text', text: 'Type here: every block keeps its id.' }] },
+  ],
+}
+
+function WithAnEditor({ views }: { views: boolean }) {
+  const editor = useEditor({
+    extensions: [
+      StarterKit,
+      BlockId,
+      UnknownBlock,
+      ReferenceNode.configure({ view: views ? Chip : null }),
+      AttachmentNode.configure({ view: views ? File : null }),
+    ],
+    content: DOCUMENT,
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  return <EditorContent editor={editor} className="max-w-[560px]" />
+}
+
+/** A reference and a file drawn by the app's views, and a block kept whole. */
+export const Default: Story = {
+  render: () => <WithAnEditor views />,
+}
+
+/** No views given: the reference is its URI and the file its name, as text. */
+export const WithoutViews: Story = {
+  render: () => <WithAnEditor views={false} />,
+}

package/src/BlockNodes.test.tsx

@@ -0,0 +1,117 @@
+// @vitest-environment jsdom
+/**
+ * The block nodes (MAN-9, moved from Ship's `editorSchema.tsx`): what the
+ * editor must hand back unchanged for a save to keep every anchored comment.
+ *
+ * The JSON loaded here is what `@estiva-app/protocol`'s `toEditorDocument`
+ * produces, and what `getJSON()` returns is what its `fromEditorDocument`
+ * reads — so each test is a load, an edit or none, and a read back.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { render, screen, cleanup } from '@testing-library/react'
+import { Editor } from '@tiptap/core'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { AttachmentNode, BlockId, ReferenceNode, UnknownBlock, type ReferenceViewProps } from './BlockNodes'
+
+const EXTENSIONS = [StarterKit, BlockId, UnknownBlock, ReferenceNode, AttachmentNode]
+
+const SOURCE = { type: 'widget', id: 'w1', content: [{ type: 'text', text: 'kept' }] }
+const FILE = { url: '/media/f.png', m: 'image/png', x: 'f'.repeat(64), size: 4096 }
+
+const DOCUMENT = {
+  type: 'doc',
+  content: [
+    { type: 'heading', attrs: { level: 1, blockId: 'h1' }, content: [{ type: 'text', text: 'Title' }] },
+    {
+      type: 'paragraph',
+      attrs: { blockId: 'p1' },
+      content: [
+        { type: 'text', text: 'see ' },
+        { type: 'reference', attrs: { uri: 'nostr:naddr1example', marks: ['bold'] } },
+      ],
+    },
+    { type: 'unknownBlock', attrs: { blockId: 'w1', source: SOURCE, text: 'kept' } },
+    { type: 'attachment', attrs: { blockId: 'a1', ...FILE, filename: 'shot.png' } },
+    { type: 'bulletList', attrs: { blockId: 'l1' }, content: [{ type: 'listItem', attrs: { blockId: 'i1' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'one' }] }] }] },
+  ],
+}
+
+type Json = { type: string; attrs?: Record<string, unknown>; content?: Json[] }
+
+let editor: Editor | undefined
+afterEach(() => {
+  editor?.destroy()
+  editor = undefined
+  cleanup()
+})
+
+describe('what the editor hands back', () => {
+  it('keeps every block id through a load and a read', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    const back = editor.getJSON() as Json
+    expect(back.content?.map((n) => n.attrs?.blockId)).toEqual(['h1', 'p1', 'w1', 'a1', 'l1'])
+    expect(back.content?.[4].content?.[0].attrs?.blockId).toBe('i1')
+  })
+
+  it('keeps a block id when its text is typed into', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    // The end of the heading's text: 1 opens the heading, 5 characters of "Title".
+    editor.chain().setTextSelection(6).insertContent(', edited').run()
+    const heading = (editor.getJSON() as Json).content?.[0]
+    expect(heading?.attrs?.blockId).toBe('h1')
+    expect(JSON.stringify(heading)).toContain('Title, edited')
+  })
+
+  it('carries an unknown block whole, source and all', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    const kept = (editor.getJSON() as Json).content?.[2]
+    expect(kept?.type).toBe('unknownBlock')
+    expect(kept?.attrs?.source).toEqual(SOURCE)
+  })
+
+  it('keeps a reference an atom, with its uri and the marks it carries', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    const reference = (editor.getJSON() as Json).content?.[1].content?.[1]
+    expect(reference).toEqual({ type: 'reference', attrs: { uri: 'nostr:naddr1example', marks: ['bold'] } })
+  })
+
+  it('keeps every imeta field on a file, which ProseMirror drops when undeclared', () => {
+    const rich = { ...FILE, dim: '800x600', thumb: '/media/f.thumb.jpg', alt: 'a picture', filename: 'shot.png' }
+    editor = new Editor({ extensions: EXTENSIONS, content: { type: 'doc', content: [{ type: 'attachment', attrs: { blockId: 'a1', ...rich } }] } })
+    expect((editor.getJSON() as Json).content?.[0].attrs).toEqual({ blockId: 'a1', ...rich })
+  })
+})
+
+describe('what it draws', () => {
+  function WithAnEditor({ view }: { view: ((props: ReferenceViewProps) => React.ReactNode) | null }) {
+    const e = useEditor({
+      extensions: [StarterKit, BlockId, UnknownBlock, ReferenceNode.configure({ view }), AttachmentNode],
+      content: DOCUMENT,
+    })
+    return <EditorContent editor={e} />
+  }
+
+  it('draws a reference with the view it is given', async () => {
+    render(<WithAnEditor view={({ uri }) => <span data-testid="chip">{uri}</span>} />)
+    expect((await screen.findByTestId('chip')).textContent).toBe('nostr:naddr1example')
+  })
+
+  it('draws a reference as its uri without a view', async () => {
+    const { container } = render(<WithAnEditor view={null} />)
+    await screen.findByText('Title')
+    expect(container.querySelector('[data-reference]')?.textContent).toBe('nostr:naddr1example')
+  })
+
+  it('draws an unknown block as its text, addressed by its id', async () => {
+    const { container } = render(<WithAnEditor view={null} />)
+    expect((await screen.findByText('kept')).closest('[data-block-id]')?.getAttribute('data-block-id')).toBe('w1')
+    expect(container.querySelector('[data-block-type="widget"]')).not.toBeNull()
+  })
+
+  it('puts data-block-id on each block, as RichText does', async () => {
+    const { container } = render(<WithAnEditor view={null} />)
+    await screen.findByText('Title')
+    expect(container.querySelector('h1')?.getAttribute('data-block-id')).toBe('h1')
+  })
+})

package/src/BlockNodes.tsx

@@ -0,0 +1,242 @@
+import type { ComponentType } from 'react'
+import { Extension, Node } from '@tiptap/core'
+import { NodeViewWrapper, ReactNodeViewRenderer, type ReactNodeViewProps } from '@tiptap/react'
+
+/*
+ * The four nodes an editor of a block document needs that a stock schema does
+ * not have (SPEC §13.3) — moved here from Ship's `editorSchema.tsx` (RIC-14,
+ * SHI-2) when Peek became the second editor of the same documents (MAN-9).
+ *
+ * They are one half of a pair. The other half is `@estiva-app/protocol`'s
+ * `toEditorDocument` / `fromEditorDocument`, which turn a stored document into
+ * the JSON these nodes read and back: the node names (`unknownBlock`,
+ * `reference`, `attachment`) and the `blockId` attribute are that translation's,
+ * and must not drift from it. This package does not import protocol, as
+ * `RichText` does not: the translation hands over everything a view draws.
+ *
+ * Everything else a document can contain is already a ProseMirror node of the
+ * same name — StarterKit's and TableKit's — which is why this file is short.
+ */
+
+/**
+ * The block types §13.3 puts an id on, as the editor's node names —
+ * protocol's `EDITOR_BLOCK_TYPES`, less `unknownBlock`, which declares its own.
+ */
+const BLOCK_TYPES = [
+  'paragraph',
+  'heading',
+  'bulletList',
+  'orderedList',
+  'listItem',
+  'blockquote',
+  'codeBlock',
+  'horizontalRule',
+  // A table and everything inside it (UIG-18): a row or a cell whose id was
+  // re-minted on each save would detach any comment anchored to it.
+  'table',
+  'tableRow',
+  'tableHeader',
+  'tableCell',
+  // Without this an attachment's id is re-minted on every save, and every
+  // comment anchored to it stops resolving.
+  'attachment',
+]
+
+/**
+ * `id` on every block, carried as the `blockId` attribute.
+ *
+ * A global attribute rather than one per node type, because §13.3 puts an id
+ * on **every** block and a type that quietly lacked one would mint a fresh id
+ * on every save — detaching each anchored comment on it (RFC 0.4 §6) with
+ * nothing on screen to say so.
+ *
+ * Rendered as `data-block-id`, which is what `RichText` already emits, so the
+ * reading and the editing surface address a block the same way.
+ */
+export const BlockId = Extension.create({
+  name: 'blockId',
+  addGlobalAttributes() {
+    return [
+      {
+        types: BLOCK_TYPES,
+        attributes: {
+          blockId: {
+            default: null,
+            parseHTML: (element: HTMLElement) => element.getAttribute('data-block-id'),
+            renderHTML: (attributes: Record<string, unknown>) =>
+              attributes.blockId ? { 'data-block-id': String(attributes.blockId) } : {},
+          },
+        },
+      },
+    ]
+  },
+})
+
+/** What a reference's view is handed: the `nostr:` URI it stands for. */
+export interface ReferenceViewProps {
+  uri: string
+}
+
+export interface ReferenceNodeOptions {
+  /**
+   * Draws the reference as the thing it points at — the app's own chip, which
+   * knows how to resolve it. Without one, the URI is drawn as text.
+   */
+  view: ComponentType<ReferenceViewProps> | null
+}
+
+/**
+ * A `nostr:` reference, drawn as the thing it points at — SPEC §13.1.
+ *
+ * An **atom**: it has no editable interior, because its text is the URI and
+ * nobody edits half a `naddr`. Selecting it selects the whole reference, which
+ * is also how deleting one works. `marks` carries the run's other marks, so a
+ * bold reference comes back bold.
+ */
+export const ReferenceNode = Node.create<ReferenceNodeOptions>({
+  name: 'reference',
+  group: 'inline',
+  inline: true,
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addOptions() {
+    return { view: null }
+  },
+  addAttributes() {
+    return {
+      uri: { default: '' },
+      marks: { default: [] as string[] },
+    }
+  },
+  parseHTML() {
+    return [{ tag: 'span[data-reference]' }]
+  },
+  renderHTML({ node }) {
+    // A copy to the clipboard as HTML, and the whole drawing when no view is given.
+    return ['span', { 'data-reference': String(node.attrs.uri) }, String(node.attrs.uri)]
+  },
+  addNodeView() {
+    const View = this.options.view
+    if (!View) return null
+    return ReactNodeViewRenderer(({ node }: ReactNodeViewProps) => (
+      <NodeViewWrapper as="span" className="inline">
+        <View uri={String(node.attrs.uri ?? '')} />
+      </NodeViewWrapper>
+    ))
+  },
+})
+
+/**
+ * A block this editor has no design for, kept whole.
+ *
+ * §13.3: a reader MUST render an unknown block's inline text and MUST NOT drop
+ * it silently. **An editor is the dangerous case** — ProseMirror discards a
+ * node its schema does not know, and the save after that would delete somebody
+ * else's block with no error anywhere on the way. So the block's own JSON
+ * rides in `source`, and protocol's `fromEditorDocument` hands it back
+ * untouched; `text` is its inline text, worked out by `toEditorDocument`.
+ *
+ * Not editable, deliberately: an affordance that lets a person change
+ * something they cannot see is worse than one that says the content is there
+ * and belongs to another surface.
+ */
+export const UnknownBlock = Node.create({
+  name: 'unknownBlock',
+  group: 'block',
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      blockId: { default: null },
+      source: { default: null },
+      text: { default: '' },
+    }
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-unknown-block]' }]
+  },
+  renderHTML({ node }) {
+    return ['div', { 'data-unknown-block': String(node.attrs.blockId ?? '') }, String(node.attrs.text ?? '')]
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(UnknownBlockView)
+  },
+})
+
+function UnknownBlockView({ node }: ReactNodeViewProps) {
+  const source = node.attrs.source as { id?: string; type?: string } | null
+  const text = String(node.attrs.text ?? '')
+  return (
+    <NodeViewWrapper
+      data-block-id={source?.id}
+      data-block-type={source?.type}
+      className="rounded-md border border-border-default bg-bg-inset px-2 py-1 text-text-secondary"
+    >
+      {text || `A ${source?.type ?? 'block'} this app cannot edit yet.`}
+    </NodeViewWrapper>
+  )
+}
+
+/** What an attachment's view is handed: the block's `imeta` fields. */
+export interface AttachmentViewProps {
+  attrs: Record<string, unknown>
+}
+
+export interface AttachmentNodeOptions {
+  /** Draws the file — the app's own attachment card. Without one, its name is drawn as text. */
+  view: ComponentType<AttachmentViewProps> | null
+}
+
+/**
+ * A file placed in a document — SPEC §13.3's `attachment` block (SHI-2).
+ *
+ * An atom: the file is the block, there is nothing inside it to edit, and a
+ * caret that could sit "inside" an image is a way to produce documents no
+ * reader has a rule for. Selectable and deletable, so removing one is Backspace
+ * like anything else.
+ *
+ * Its attributes are the `imeta` fields exactly, because that is what §13.3
+ * specifies. Each is declared, and that is not boilerplate: ProseMirror **drops
+ * an attribute its schema does not name**, so an undeclared `thumb` would
+ * survive the editor and vanish on save — the silent deletion `UnknownBlock`
+ * exists to prevent.
+ */
+export const AttachmentNode = Node.create<AttachmentNodeOptions>({
+  name: 'attachment',
+  group: 'block',
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addOptions() {
+    return { view: null }
+  },
+  addAttributes() {
+    return {
+      url: { default: '' },
+      m: { default: '' },
+      x: { default: '' },
+      size: { default: 0 },
+      dim: { default: null },
+      thumb: { default: null },
+      alt: { default: null },
+      filename: { default: null },
+    }
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-attachment-block]' }]
+  },
+  renderHTML({ node }) {
+    // A copy to the clipboard, and the whole drawing when no view is given.
+    return ['div', { 'data-attachment-block': String(node.attrs.x ?? '') }, String(node.attrs.filename ?? 'attachment')]
+  },
+  addNodeView() {
+    const View = this.options.view
+    if (!View) return null
+    return ReactNodeViewRenderer(({ node }: ReactNodeViewProps) => (
+      <NodeViewWrapper className="my-2">
+        <View attrs={node.attrs} />
+      </NodeViewWrapper>
+    ))
+  },
+})

package/src/DialogShell.stories.tsx

@@ -53,6 +53,24 @@ export const Default: Story = {
   },
 }
 
+/**
+ * **A long title keeps to its one line** and ends in "…", so the bar stays
+ * 48px and the ✕ stays where it is. A title that names something a person
+ * typed — a file's name in "Archive “…”?" — is the one that gets long.
+ */
+export const ALongTitle: Story = {
+  args: {
+    title: 'Archive “Interesting Claude-generated docs - Renamed 4, with notes from the second review”?',
+    footer: (
+      <>
+        <Button variant="muted">Cancel</Button>
+        <Button variant="primary">Archive topic</Button>
+      </>
+    ),
+    children: <p className="text-body-2 text-text-primary">This hides the topic from every list.</p>,
+  },
+}
+
 /**
  * **`headerContent` replaces the title text** — a back button beside it, a
  * count after it — and the ✕ stays. The dialog is then named by its `title`

package/src/DialogShell.tsx

@@ -115,11 +115,13 @@ export function DialogShell({ title, onClose, headerContent, footer, children, b
             className="bg-bg-elevated border border-border-subtle rounded-lg shadow-lg pointer-events-auto flex flex-col overflow-hidden outline-none"
             style={{ width }}
           >
-            {/* Header: the package's one header bar, with the dialog's own title in it (UIG-22). */}
+            {/* Header: the package's one header bar, with the dialog's own title in it (UIG-22).
+                The title keeps to its one line and ends in "…": a long name wrapped to
+                two lines in the 48px bar and lost its top (Katerina, 1 October). */}
             <ContainerHeader
               title={
                 headerContent ?? (
-                  <Parts.Title className="text-h4 text-text-primary" render={<span />}>
+                  <Parts.Title className="block truncate text-h4 text-text-primary" render={<span />}>
                     {title}
                   </Parts.Title>
                 )