@estiva-app/ui 0.62.0 → 0.63.0

package/src/PastedImages.test.ts

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from 'vitest'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { PastedImages, pastedImageName, pastedImages, type ClipboardSource } from './PastedImages'
+
+const AT = new Date(2026, 8, 7, 14, 32, 5) // 2026-09-07 14:32:05, local
+
+/** A clipboard as the paste sees it. */
+function clipboard(text: string, files: File[] = []): ClipboardSource {
+  return { files, getData: (format) => (format === 'text/plain' ? text : '') }
+}
+
+const png = (name = 'image.png', type = 'image/png') => new File([new Uint8Array([1, 2, 3])], name, { type })
+
+describe('pastedImages', () => {
+  it('names a screenshot after the moment it was pasted', () => {
+    expect(pastedImageName('image/png', AT)).toBe('Screenshot 2026-09-07 14-32-05.png')
+    expect(pastedImageName('image/jpeg', AT)).toBe('Screenshot 2026-09-07 14-32-05.jpg')
+    expect(pastedImageName('image/png', AT, 1)).toBe('Screenshot 2026-09-07 14-32-05 (2).png')
+  })
+
+  it('gives an unlisted picture its own extension, so the app can refuse it by name', () => {
+    expect(pastedImageName('image/tiff', AT)).toBe('Screenshot 2026-09-07 14-32-05.tiff')
+  })
+
+  it('attaches a screenshot, renamed, its bytes and type kept', () => {
+    const [file] = pastedImages(clipboard('', [png()]), AT)
+    expect(file.name).toBe('Screenshot 2026-09-07 14-32-05.png')
+    expect(file.type).toBe('image/png')
+    expect(file.size).toBe(3)
+  })
+
+  it('leaves the clipboard to the editor when it carries text', () => {
+    expect(pastedImages(clipboard('Q3 revenue\t120', [png()]), AT)).toEqual([])
+    expect(pastedImages(clipboard('   ', [png()]), AT)).toHaveLength(1)
+  })
+
+  it('keeps a real filename', () => {
+    const [file] = pastedImages(clipboard('', [png('quarterly-chart.png')]), AT)
+    expect(file.name).toBe('quarterly-chart.png')
+  })
+
+  it('names several pictures in one paste apart', () => {
+    const files = pastedImages(clipboard('', [png(), png(), png('kept.png')]), AT)
+    expect(files.map((f) => f.name)).toEqual(['Screenshot 2026-09-07 14-32-05.png', 'Screenshot 2026-09-07 14-32-05 (2).png', 'kept.png'])
+  })
+
+  it('ignores anything that is not a picture, and an empty clipboard', () => {
+    const pdf = new File([new Uint8Array([1])], 'report.pdf', { type: 'application/pdf' })
+    expect(pastedImages(clipboard('', [pdf]), AT)).toEqual([])
+    expect(pastedImages(clipboard(''), AT)).toEqual([])
+    expect(pastedImages(null, AT)).toEqual([])
+  })
+})
+
+describe('PastedImages', () => {
+  /** A paste event as ProseMirror hands it to `handlePaste`. */
+  const paste = (editor: Editor, data: ClipboardSource) => {
+    const event = new Event('paste', { bubbles: true, cancelable: true }) as ClipboardEvent
+    Object.defineProperty(event, 'clipboardData', { value: data })
+    let handled = false
+    editor.view.someProp('handlePaste', (f) => (handled = !!f(editor.view, event, editor.state.doc.slice(0, 0)) || handled))
+    return handled
+  }
+
+  it('hands a pasted screenshot to the app, named, and stops the editor pasting it', () => {
+    const onImages = vi.fn(() => true)
+    const editor = new Editor({ extensions: [StarterKit, PastedImages.configure({ onImages })] })
+    expect(paste(editor, clipboard('', [png()]))).toBe(true)
+    expect(onImages).toHaveBeenCalledWith([expect.objectContaining({ name: expect.stringMatching(/^Screenshot .*\.png$/) })])
+    editor.destroy()
+  })
+
+  it('lets the editor paste when the app declines, or when there is text', () => {
+    const onImages = vi.fn(() => false)
+    const editor = new Editor({ extensions: [StarterKit, PastedImages.configure({ onImages })] })
+    expect(paste(editor, clipboard('', [png()]))).toBe(false)
+    expect(paste(editor, clipboard('a sentence', [png()]))).toBe(false)
+    expect(onImages).toHaveBeenCalledTimes(1)
+    editor.destroy()
+  })
+})

package/src/PastedImages.ts

@@ -0,0 +1,105 @@
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+
+/** As much of a `DataTransfer` as the paste reads. */
+export interface ClipboardSource {
+  files?: ArrayLike<File> | null
+  getData(format: string): string
+}
+
+/** MIME type → the extension a pasted picture is named with. */
+const IMAGE_EXTENSIONS: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/heic': 'heic',
+  'image/heif': 'heif',
+  'image/svg+xml': 'svg',
+}
+
+/** Names a browser invents for a clipboard picture. A made-up one is better. */
+const GENERIC_STEMS = new Set(['image', 'blob', 'unknown', 'untitled', 'screenshot'])
+
+/*
+  An unlisted type keeps its own subtype rather than becoming `png`, so a
+  picture the app does not accept is refused by the app's own message instead
+  of arriving disguised as one it does.
+*/
+function extensionFor(contentType: string): string {
+  const type = contentType.toLowerCase()
+  return IMAGE_EXTENSIONS[type] ?? type.split('/')[1]?.split('+')[0] ?? 'png'
+}
+
+/** `'Screenshot 2026-09-07 14-32-05.png'`: sortable, and readable on a file card. */
+export function pastedImageName(contentType: string, at: Date = new Date(), index = 0): string {
+  const pad = (n: number) => String(n).padStart(2, '0')
+  const stamp =
+    `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ` +
+    `${pad(at.getHours())}-${pad(at.getMinutes())}-${pad(at.getSeconds())}`
+  const nth = index > 0 ? ` (${index + 1})` : ''
+  return `Screenshot ${stamp}${nth}.${extensionFor(contentType)}`
+}
+
+/** A real filename is kept; `image.png`, `blob` and '' are not names. */
+function hasUsableName(name: string): boolean {
+  const dot = name.lastIndexOf('.')
+  if (dot <= 0 || dot === name.length - 1) return false
+  return !GENERIC_STEMS.has(name.slice(0, dot).toLowerCase())
+}
+
+/**
+ * The pictures on the clipboard, named — `[]` when there is nothing to attach.
+ *
+ * **Text wins.** A copy from a spreadsheet or a document puts a rendered
+ * picture of the selection beside the text; attaching the picture instead of
+ * pasting the text is wrong every time. So a clipboard holding text is left to
+ * the editor, and a screenshot, which holds none, lands here. Pictures only:
+ * any other file comes through the app's own file picker.
+ */
+export function pastedImages(source: ClipboardSource | null | undefined, at: Date = new Date()): File[] {
+  if (!source) return []
+  if (source.getData('text/plain').trim() !== '') return []
+  const images = Array.from(source.files ?? []).filter((f) => f.type.toLowerCase().startsWith('image/'))
+  let generated = 0
+  return images.map((file) =>
+    hasUsableName(file.name)
+      ? file
+      : new File([file], pastedImageName(file.type, at, generated++), { type: file.type, lastModified: file.lastModified }),
+  )
+}
+
+export interface PastedImagesOptions {
+  /**
+   * The pictures a paste carried, named. Return `true` when the app took them
+   * (an upload started), `false` to let the editor paste as it would have —
+   * for a box that cannot upload right now.
+   */
+  onImages: (files: File[]) => boolean
+}
+
+/**
+ * Pasting a picture attaches it: a screenshot pasted into the editor reaches
+ * the app as named files, the way the app's own file picker would hand them.
+ * Text on the clipboard wins (see {@link pastedImages}).
+ */
+export const PastedImages = Extension.create<PastedImagesOptions>({
+  name: 'pastedImages',
+  addOptions() {
+    return { onImages: () => false }
+  },
+  addProseMirrorPlugins() {
+    const options = this.options
+    return [
+      new Plugin({
+        key: new PluginKey('pastedImages'),
+        props: {
+          handlePaste: (_view, event) => {
+            const files = pastedImages(event.clipboardData)
+            return files.length > 0 && options.onImages(files)
+          },
+        },
+      }),
+    ]
+  },
+})

package/src/editor.ts

@@ -8,6 +8,7 @@
  * `Toolbar`, `MenuItem`, `SuggestionMenu` — is the main entry's own, not a copy.
  */
 export { KeptSelection, SelectionToolbar, normalizeHref, type MarkId, type SelectionToolbarProps } from './SelectionToolbar'
+export { PastedImages, pastedImages, pastedImageName, type PastedImagesOptions, type ClipboardSource } from './PastedImages'
 export { suggestionPopup, isSuggestionActive, isSuggestionOpen, type SuggestionPopupOptions } from './suggestionPopup'
 export { EditorBlockHandle, blockDropCursor, deleteBlock, moveBlock, duplicateBlock, startBlockDrag, type EditorBlockHandleProps, type BlockTurnInto } from './EditorBlockHandle'
 export {

package/src/eslint/no-restyled-part.ts

@@ -131,6 +131,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
   Card: ['fill', 'hover', 'attention', 'selected', 'active', 'hovered', 'quietUntilHover', 'unreadable', 'clip'],
   Checkbox: ['row'],
   Chip: ['type'],
+  KindIcon: ['tone'],
   CollapsibleSection: ['look'],
   Divider: ['tone', 'orientation'],
   EmptyState: ['scope'],

package/src/index.ts

@@ -55,6 +55,7 @@ export { Link, type LinkProps, type LinkVariant } from './Link'
 export { RichText, richTextClassName, type RichTextProps, type RichTextBlock, type RichTextRun, type RichTextSize } from './RichText'
 export { IconButton, type IconButtonProps, type IconButtonVariant } from './IconButton'
 export { Kbd, type KbdProps } from './Kbd'
+export { KindIcon, thingKindOf, type KindIconProps, type ThingKind } from './KindIcon'
 export { IdentityMenu, IdentityPanel, type Identity, type IdentityMenuProps, type IdentityPanelProps } from './IdentityMenu'
 export { Tooltip, TooltipProvider, WithTooltip, type TooltipProps, type TooltipProviderProps, type WithTooltipProps } from './Tooltip'
 export { Field, FieldLine, type FieldLineProps, type FieldLineTone, type FieldProps } from './Field'

package/src/pages.test.ts

@@ -38,7 +38,10 @@ const WAITING: string[] = []
 
 const NOTHING = 'Nothing. It only draws. Clicks and keys are yours.'
 /** A part that draws nothing at all says so instead: it only holds what the parts below it ask for. */
-const HOLDS_ONLY: Record<string, string> = { AppProvider: 'Nothing. It draws nothing; it holds two answers for the parts below it.' }
+const HOLDS_ONLY: Record<string, string> = {
+  AppProvider: 'Nothing. It draws nothing; it holds two answers for the parts below it.',
+  PastedImages: 'Nothing. It draws nothing; it hands a pasted picture to the app, named.',
+}
 
 const dir = new URL('.', import.meta.url)
 const read = (file: string) => readFileSync(new URL(file, dir), 'utf8').replace(/\r\n/g, '\n')

package/src/registry/registry.test.ts

@@ -26,7 +26,7 @@ import { SCHEMA_VERSION, validateRegistry, type Registry, type RegistryEntry } f
 const root = process.cwd()
 const registry = buildRegistry({ root })
 /** Editor extensions: named like components by the catalogue, and not React components. */
-const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands']
+const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages']
 const entry = (name: string): RegistryEntry => {
   const found = registry.entries.find((candidate) => candidate.name === name)
   if (!found) throw new Error(`no entry for ${name}`)
@@ -48,20 +48,20 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 134 names over 73 files: 104 components, 29 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, and AppProvider on 8 October)', () => {
+  it('counts 139 names over 75 files: 106 components, 32 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     // The ten `EDITOR_EXTENSIONS` count as components by their names; they are
     // editor extensions, documented on SelectionToolbar's, BlockNodes' and
     // ComposerTriggers' pages.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 104, helper: 29, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(73)
+    expect(kinds).toEqual({ component: 106, helper: 32, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(75)
   })
 
   it('gives every entry a purpose, from its own page or from the comment above it', () => {
     expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
-    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(69)
-    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(65)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(71)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(68)
   })
 
   it('takes a name with a page of its own from the page, and a name without one from the code', () => {

package/stories/Choosing.mdx

@@ -96,7 +96,9 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | Where am I, and the way back up | **Breadcrumb** |
 | A link — in text, on a title, beside a note, or a whole box | **Link** — `text`, `quiet`, `underlined`, `plain`; `external` for a new tab |
 | A document or an image attached to something, posted or waiting to be sent | **AttachmentCard** — the file decides the shape; `pending` in a composer |
+| A picture pasted into an editor, attached rather than pasted | **PastedImages** — from `@estiva-app/ui/editor`; the app hands it its upload |
 | A person or a thing named inside a sentence | **InlineChip** — one line high, level with the words; `href` makes it a link |
+| What kind of thing a name stands for — a topic, a project, an issue, a file, a message | **KindIcon** — before the name in a row, or inside an **InlineChip**; `thingKindOf` turns an event kind into one |
 | Formatted text: headings, lists, a quote, code, a table, links | **RichText** — pass the parsed tree; `small` inside a card |
 | The key that does this too | **Kbd** — or the `shortcut` prop on **MenuItem**, **Tooltip** and **SearchInput** |