@estiva-app/ui 0.72.0-widgets2.2 → 0.73.0-inline-text.1

package/src/ComposeBox.tsx

@@ -0,0 +1,183 @@
+import { useCallback, useEffect, useState, type ReactNode } from 'react'
+import { Extension } from '@tiptap/core'
+import { EditorContent, type Editor } from '@tiptap/react'
+import { IconArrowUp } from '@tabler/icons-react'
+import { IconButton } from './IconButton'
+import { Toolbar } from './Toolbar'
+import { cn } from './cn'
+import { richTextClassName } from './RichText'
+import { WRITING_BOX_CLASSES } from './looks'
+import { SelectionToolbar, type SelectionToolbarProps } from './SelectionToolbar'
+import { isSuggestionActive } from './suggestionPopup'
+
+/**
+ * The box a message, a reply or a comment is written in, from Katerina's Leaf
+ * prototype (9 October). Peek's `ComposeBox`, its look and its keys, with
+ * what only Peek knows left in Peek: drafts, uploads, highlights, its text
+ * format. The app makes the editor (its extensions are its own) and adds
+ * `ComposeKeys`; this draws the box around it and sends.
+ */
+
+/** The editor's own classes inside the box: Peek's, rich text with no outline. Put them in `editorProps.attributes.class`. */
+export const COMPOSE_EDITOR_CLASSES = richTextClassName('default', 'outline-none w-full bg-transparent min-h-[20px] [&>p+p]:-mt-1')
+
+type ComposeKeysStorage = { send: (() => boolean) | null }
+
+/**
+ * Enter sends; Shift+Enter is a new line — in a list a new item (or out of the
+ * list, on an empty one), in a quote a new line (or out of it, on an empty one).
+ * Peek's keys, as its ComposeBox has them. Enter while a `/`, `@` or `[` list is
+ * open picks a row instead. `ComposeBox` says what sending does.
+ */
+export const ComposeKeys = Extension.create<Record<string, never>, ComposeKeysStorage>({
+  name: 'composeKeys',
+  addStorage() {
+    return { send: null }
+  },
+  addKeyboardShortcuts() {
+    return {
+      Enter: () => {
+        if (isSuggestionActive()) return false
+        this.storage.send?.()
+        return true
+      },
+      'Shift-Enter': ({ editor }) => {
+        const { $from } = editor.state.selection
+        for (let d = $from.depth; d > 0; d--) {
+          const node = $from.node(d)
+          if (node.type.name === 'listItem') {
+            return node.textContent.length === 0 ? editor.commands.liftListItem('listItem') : editor.commands.splitListItem('listItem')
+          }
+          if (node.type.name === 'blockquote') {
+            if ($from.parent.textContent.length === 0) return editor.commands.lift('paragraph')
+            break
+          }
+        }
+        return editor.commands.splitBlock()
+      },
+    }
+  },
+})
+
+/** Nothing written: no text, no chip and no picture — empty lines, lists or quotes only. */
+function isEmptyDoc(editor: Editor): boolean {
+  const doc = editor.state.doc
+  if (doc.textContent.length > 0) return false
+  let empty = true
+  doc.descendants((node) => {
+    if (node.isAtom && node.type.name !== 'hardBreak') empty = false
+  })
+  return empty
+}
+
+export interface ComposeBoxProps {
+  /** The app's editor, with `ComposeKeys` in its extensions and `COMPOSE_EDITOR_CLASSES` on it. `null` while it loads. */
+  editor: Editor | null
+  /**
+   * Send what is written. The box empties afterwards — unless this returns
+   * `false`: nothing was sent, and the words stay.
+   */
+  onSend: (editor: Editor) => void | boolean
+  /** Said in the empty box: words, and a `Kbd` where a key helps ("type / for commands"). */
+  placeholder: ReactNode
+  /** The tools under the text, left: `ToolbarButton`s (attach, highlight). One Tab stop. */
+  tools?: ReactNode
+  /** What is attached, under the text: `AttachmentCard pending`s. */
+  attachments?: ReactNode
+  /** Something to send even with no words — a file ready. */
+  ready?: boolean
+  /** Sending waits — a file still uploading. */
+  holding?: boolean
+  /** The bar down the text's left: an urgent mention or a highlight, as Peek draws it. */
+  marked?: boolean
+  /** The selection strip's buttons: its marks, Link, and the app's own (`actions`). */
+  selection?: Pick<SelectionToolbarProps, 'marks' | 'link' | 'actions'>
+  className?: string
+}
+
+/**
+ * The box for writing: the text, the selection strip over it, what is
+ * attached, the tools and Send. Enter sends (`ComposeKeys`), and so does the
+ * button.
+ */
+export function ComposeBox({ editor, onSend, placeholder, tools, attachments, ready = false, holding = false, marked = false, selection, className }: ComposeBoxProps) {
+  const [empty, setEmpty] = useState(true)
+  const canSend = (!empty || ready) && !holding
+
+  const send = useCallback((): boolean => {
+    if (!editor || holding || (isEmptyDoc(editor) && !ready)) return true
+    if (onSend(editor) === false) return true
+    editor.commands.clearContent(true)
+    editor.commands.focus()
+    return true
+  }, [editor, holding, ready, onSend])
+
+  // Enter, through `ComposeKeys`, sends the way the button does.
+  useEffect(() => {
+    if (!editor) return
+    const storage = (editor.storage as unknown as { composeKeys?: ComposeKeysStorage }).composeKeys
+    if (!storage) return
+    storage.send = send
+    return () => {
+      storage.send = null
+    }
+  }, [editor, send])
+
+  useEffect(() => {
+    if (!editor) return
+    const read = () => setEmpty(isEmptyDoc(editor))
+    read()
+    editor.on('update', read)
+    return () => {
+      editor.off('update', read)
+    }
+  }, [editor])
+
+  return (
+    <div className={cn('relative', className)}>
+      <div className={cn(WRITING_BOX_CLASSES, 'focus-within:border-border-strong transition-colors')}>
+        <div data-composer-editor className={cn('relative min-h-[20px] transition-all', marked && 'border-l-4 border-border-strong pl-2')}>
+          <EditorContent editor={editor} />
+          <SelectionToolbar editor={editor} {...selection} />
+          {empty && (
+            <div className="pointer-events-none absolute inset-0 flex flex-wrap items-center gap-1 text-body-2 text-text-muted">{placeholder}</div>
+          )}
+        </div>
+
+        {attachments && <div className="flex flex-wrap gap-2">{attachments}</div>}
+
+        {/* The tools are one strip — one Tab stop, arrows along it; Send, the answer rather than a tool, keeps its own. */}
+        <div className="flex items-center justify-between">
+          {tools ? (
+            <Toolbar aria-label="Compose tools" surface={false} className="flex items-center gap-1">
+              {tools}
+            </Toolbar>
+          ) : (
+            <span />
+          )}
+          <div className="flex items-center gap-2.5">
+            <span className="hidden select-none font-mono text-menu font-normal tracking-wider text-text-muted signal:inline">Enter to send · Shift+Enter new line</span>
+            {/* Focus stays in the text: the press sends on its way down. A keyboard press is the click (`detail` 0), so a click never sends twice. */}
+            <IconButton
+              variant="primary"
+              onMouseDown={(e) => {
+                e.preventDefault()
+                send()
+              }}
+              onClick={(e) => {
+                if (e.detail === 0) send()
+              }}
+              disabled={!canSend}
+              aria-label="Send"
+              tooltip="Send"
+              tooltipShortcut="Enter"
+              glow={canSend}
+            >
+              <IconArrowUp size={16} stroke={1.5} />
+            </IconButton>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/ComposerTriggers.tsx

@@ -7,6 +7,7 @@ import { NodeViewWrapper, ReactNodeViewRenderer, type ReactNodeViewProps } from
 import { Avatar } from './Avatar'
 import { EnterHint } from './Menu'
 import { inlineChipClassName } from './InlineChip'
+import { WithTooltip } from './Tooltip'
 import type { SuggestionMenuRow } from './SuggestionMenu'
 import { suggestionPopup, type SuggestionPopupOptions } from './suggestionPopup'
 
@@ -308,9 +309,14 @@ export const CaptionedReference = Mention.extend<MentionOptions & CaptionedRefer
     const { icon, iconFor } = this.options
     return ReactNodeViewRenderer(
       ({ node }: ReactNodeViewProps) => (
-        <NodeViewWrapper as="span" className={inlineChipClassName('neutral', 'max-w-[24ch] cursor-default')}>
-          <span className="flex items-center justify-center w-4 h-4 shrink-0 text-text-secondary">{iconFor?.(node.attrs.uri ?? null) ?? icon}</span>
-          <span className="truncate">{captionOf(node.attrs.label, node.attrs.snippet)}</span>
+        // The caption is cut at 24ch, so the whole of it is on hover, in the package's tooltip (UIG-14) — as Peek's sent chip has it.
+        <NodeViewWrapper as="span">
+          <WithTooltip inline label={captionOf(node.attrs.label, node.attrs.snippet)}>
+            <span className={inlineChipClassName('neutral', 'max-w-[24ch] cursor-default')}>
+              <span className="flex items-center justify-center w-4 h-4 shrink-0 text-text-secondary">{iconFor?.(node.attrs.uri ?? null) ?? icon}</span>
+              <span className="truncate">{captionOf(node.attrs.label, node.attrs.snippet)}</span>
+            </span>
+          </WithTooltip>
         </NodeViewWrapper>
       ),
       { as: 'span' },

package/src/InlineText.mdx

@@ -0,0 +1,64 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as InlineTextStories from './InlineText.stories'
+
+<Meta of={InlineTextStories} />
+
+# InlineText
+
+A page's title, or the line under it, edited where it stands, as in a document: the text is the editor, with no box and nothing moving.
+
+<Canvas of={InlineTextStories.Default} />
+
+## When
+
+- **`variant="title"`**: a page's heading. Left empty, the saved one comes back.
+- **`variant="summary"`** with **`clearable`**: the quieter line under it. Left empty, it is saved as nothing.
+- `readOnly` for someone who cannot change it, or until the app can save: the same text in the same place.
+
+<Canvas of={InlineTextStories.Empty} />
+<Canvas of={InlineTextStories.Refused} />
+
+## When not
+
+- A field in a form, a dialog or a settings row → **TextInput** or **Textarea**, in a **Form**.
+- Text you click to open as a field, in a list or a sidebar → **EditableText**.
+- Several paragraphs, lists or links → the app's block editor, with **EditorBlockHandle** and **SelectionToolbar**.
+
+## How
+
+```tsx
+import { InlineText, type InlineTextHandle } from '@estiva-app/ui/editor'
+
+const summary = useRef<InlineTextHandle>(null)
+
+<InlineText variant="title" label="Title" placeholder="Untitled" value={title} onCommit={rename} onEnter={() => summary.current?.focus()} />
+<InlineText ref={summary} variant="summary" clearable label="Summary" placeholder="Add a summary" value={line} onCommit={summarize} onText={setCount} />
+```
+
+- **`onCommit` resolves `true` when saved.** `false` keeps your text where it is; say why under it (a `FieldLine` with `tone="error"`). A change made elsewhere is not loaded over unsaved text.
+- **`onText`** gives the text as it is written, and `null` on leaving: for a count under it.
+- **`onEnter`** says where the caret goes after Enter: the next line down. `ref.focus('start' | 'end')` puts it there.
+- `label` is required: it is the editor's accessible name.
+- Base UI has no part for an editable line of a document; the editor is Tiptap, the same kind of surface as the block editor below it.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write |
+|---|---|
+| The size and colour of a title or a summary, the same at rest and while written | a class for the text, or for a field state |
+| Line breaks and pasted lines become one line of plain text | a paste handler or a clean-up before saving |
+| An unchanged or (for a title) empty value is not a write | a compare before saving |
+| Your text stays after a refused save, and a change from elsewhere waits | a draft kept beside it |
+| The placeholder while it is empty | an empty check |
+
+## Keys
+
+| Key | What it does |
+|---|---|
+| Enter | Saves, and calls `onEnter` |
+| Escape | Stops editing and saves what was typed |
+| Ctrl+Z / Ctrl+Shift+Z | Undo / redo |
+
+<Controls />

package/src/InlineText.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useRef, useState } from 'react'
+import { FieldLine } from './Field'
+import { InlineText, type InlineTextHandle } from './InlineText'
+
+/**
+ * A page's title and the line under it, edited where they stand. Click into
+ * either and type: no box, nothing moves. Enter saves and goes on down the
+ * page; Escape or clicking away saves too.
+ */
+const meta = {
+  title: 'Primitives/InlineText',
+  component: InlineText,
+  parameters: { layout: 'padded' },
+  decorators: [
+    (Story) => (
+      <div className="w-[560px]">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof InlineText>
+
+export default meta
+type Story = StoryObj
+
+const LINE = 'A line of plain text under the title, saying in a sentence what this is about.'
+const LONG = 'A line of plain text under the title that goes on for longer than a line should, so it wraps the way the text around it does and the reader sees all of it, without anything cut off at the edge or hidden behind a control.'
+
+/** A title, the line under it, and the text below: Enter in the title goes to the line, Enter in the line goes to the text. */
+function Page({ title = 'Item one', line = LINE, refuse = false, readOnly = false }: { title?: string; line?: string; refuse?: boolean; readOnly?: boolean }) {
+  const lineRef = useRef<InlineTextHandle>(null)
+  const textRef = useRef<HTMLParagraphElement>(null)
+  const [saved, setSaved] = useState({ title, line })
+  const [refused, setRefused] = useState(false)
+  return (
+    <div className="flex flex-col">
+      <InlineText
+        variant="title"
+        label="Title"
+        placeholder="Untitled"
+        value={saved.title}
+        readOnly={readOnly}
+        onCommit={(next) => (setSaved((s) => ({ ...s, title: next })), true)}
+        onEnter={() => lineRef.current?.focus('start')}
+      />
+      <InlineText
+        ref={lineRef}
+        variant="summary"
+        label="Summary"
+        placeholder="Add a line"
+        clearable
+        value={saved.line}
+        readOnly={readOnly}
+        onText={(text) => text !== null && setRefused(false)}
+        onCommit={(next) => {
+          if (refuse) {
+            setRefused(true)
+            return false
+          }
+          setSaved((s) => ({ ...s, line: next }))
+          return true
+        }}
+        onEnter={() => textRef.current?.focus()}
+      />
+      {refused && <FieldLine tone="error">Not saved: the change was refused. Your text is still here.</FieldLine>}
+      <p ref={textRef} tabIndex={-1} className="mt-4 text-body-1 text-text-primary outline-none">
+        The text of the page starts here. Nothing above it moves while you write in the title or the line under it.
+      </p>
+    </div>
+  )
+}
+
+export const Default: Story = { render: () => <Page /> }
+
+/** Nothing written yet: what each is for, muted, in its place. */
+export const Empty: Story = { render: () => <Page title="" line="" /> }
+
+/** A long line wraps like the text around it. */
+export const Long: Story = { render: () => <Page line={LONG} /> }
+
+/** The save is refused: the text stays where you wrote it, and the app says why under it. */
+export const Refused: Story = { render: () => <Page refuse /> }
+
+/** Someone who cannot change it: the same text, in the same place. */
+export const ReadOnly: Story = { render: () => <Page readOnly /> }

package/src/InlineText.test.tsx

@@ -0,0 +1,187 @@
+// @vitest-environment jsdom
+/**
+ * What the InlineText page claims, pinned: the text is the editor, Enter saves
+ * and moves on, Escape and leaving save, nothing unchanged is written, a title
+ * left empty comes back and a summary left empty is cleared, a refused save
+ * keeps your text, a paste is one line, and read-only is text only.
+ *
+ * jsdom lays nothing out, so text goes in through the editor and the caret is
+ * put at the end by hand; the keys are real key presses.
+ */
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import type { Editor } from '@tiptap/core'
+import { InlineText, type InlineTextProps } from './InlineText'
+
+// jsdom draws nothing, so it has no rects; the editor asks for them when it scrolls to the caret.
+beforeAll(() => {
+  Element.prototype.scrollIntoView = vi.fn()
+  Element.prototype.getClientRects = () => [] as unknown as DOMRectList
+  Range.prototype.getClientRects = () => [] as unknown as DOMRectList
+  Range.prototype.getBoundingClientRect = () => new DOMRect()
+})
+
+afterEach(cleanup)
+
+const field = (name = 'Title') => screen.getByRole('textbox', { name })
+const editorOf = (box: HTMLElement) => (box as HTMLElement & { editor: Editor }).editor
+
+function draw(props: Partial<InlineTextProps> = {}) {
+  const onCommit = props.onCommit ?? vi.fn(() => true)
+  const base = { value: 'Item one', placeholder: 'Untitled', label: 'Title' }
+  const view = render(<InlineText {...base} {...props} onCommit={onCommit} />)
+  return { onCommit, rerender: (next: Partial<InlineTextProps>) => view.rerender(<InlineText {...base} {...props} {...next} onCommit={onCommit} />) }
+}
+
+/** Click into it: focus, with the caret at the end. */
+async function enter(name?: string) {
+  const box = field(name)
+  await act(async () => {
+    box.focus()
+    editorOf(box).commands.setTextSelection(editorOf(box).state.doc.content.size - 1)
+  })
+}
+
+/** Type at the caret. */
+async function type(text: string, name?: string) {
+  await act(async () => {
+    editorOf(field(name)).commands.insertContent(text)
+  })
+}
+
+/** Delete everything in it. */
+async function clear(name?: string) {
+  await act(async () => {
+    editorOf(field(name)).commands.clearContent(true)
+  })
+}
+
+describe('InlineText: the text is the editor', () => {
+  it('is an editable text box named for what it edits, holding the saved text, with no button to open it', () => {
+    draw()
+    expect(field().getAttribute('contenteditable')).toBe('true')
+    expect(field().textContent).toBe('Item one')
+    expect(screen.queryByRole('button')).toBeNull()
+  })
+
+  it('shows the placeholder while empty, and not once there is text', async () => {
+    draw({ value: '', clearable: true })
+    expect(screen.queryByText('Untitled')).not.toBeNull()
+    await enter()
+    await type('A')
+    expect(screen.queryByText('Untitled')).toBeNull()
+  })
+
+  it('read-only is the text alone: not editable and no placeholder', () => {
+    draw({ value: '', readOnly: true })
+    expect(field().getAttribute('contenteditable')).toBe('false')
+    expect(screen.queryByText('Untitled')).toBeNull()
+  })
+})
+
+describe('InlineText: keys and saving', () => {
+  it('Enter saves the text and moves on', async () => {
+    const onEnter = vi.fn()
+    const { onCommit } = draw({ onEnter })
+    await enter()
+    await type(' two')
+    await userEvent.keyboard('{Enter}')
+    expect(onCommit).toHaveBeenCalledWith('Item one two')
+    expect(onEnter).toHaveBeenCalledTimes(1)
+    expect(field().textContent).toBe('Item one two')
+  })
+
+  it('Escape stops editing and saves what was typed', async () => {
+    const { onCommit } = draw()
+    await enter()
+    await type(' two')
+    await userEvent.keyboard('{Escape}')
+    expect(document.activeElement).not.toBe(field())
+    expect(onCommit).toHaveBeenCalledWith('Item one two')
+    expect(field().textContent).toBe('Item one two')
+  })
+
+  it('leaving saves it', async () => {
+    const { onCommit } = draw()
+    await enter()
+    await type(' two')
+    await act(async () => field().blur())
+    expect(onCommit).toHaveBeenCalledWith('Item one two')
+  })
+
+  it('an unchanged text is not a write', async () => {
+    const { onCommit } = draw()
+    await enter()
+    await userEvent.keyboard('{Enter}')
+    await userEvent.keyboard('{Escape}')
+    expect(onCommit).not.toHaveBeenCalled()
+  })
+
+  it('a title left empty brings the saved one back, and is not a write', async () => {
+    const { onCommit } = draw()
+    await enter()
+    await clear()
+    await userEvent.keyboard('{Escape}')
+    expect(onCommit).not.toHaveBeenCalled()
+    expect(field().textContent).toBe('Item one')
+  })
+
+  it('a clearable one left empty is saved as nothing', async () => {
+    const { onCommit } = draw({ clearable: true, label: 'Summary' })
+    await enter('Summary')
+    await clear('Summary')
+    await userEvent.keyboard('{Escape}')
+    expect(onCommit).toHaveBeenCalledWith('')
+  })
+
+  it('a paste of several lines is one line of plain text', async () => {
+    const { onCommit } = draw({ value: '', clearable: true })
+    await enter()
+    await userEvent.paste('Line one\n\nline   two\n')
+    await userEvent.keyboard('{Enter}')
+    expect(onCommit).toHaveBeenCalledWith('Line one line two')
+  })
+
+  it('reports the text being written, and null on leaving', async () => {
+    const onText = vi.fn()
+    draw({ onText })
+    await enter()
+    expect(onText).toHaveBeenLastCalledWith('Item one')
+    await type('!')
+    expect(onText).toHaveBeenLastCalledWith('Item one!')
+    await userEvent.keyboard('{Escape}')
+    expect(onText).toHaveBeenLastCalledWith(null)
+  })
+})
+
+describe('InlineText: a refused save, and a change from elsewhere', () => {
+  it('a refused save keeps your text where it is, and a change from elsewhere does not overwrite it', async () => {
+    const onCommit = vi.fn(() => false)
+    const { rerender } = draw({ onCommit })
+    await enter()
+    await type(' two')
+    await userEvent.keyboard('{Escape}')
+    expect(onCommit).toHaveBeenCalledWith('Item one two')
+    expect(field().textContent).toBe('Item one two')
+    rerender({ value: 'Item three' })
+    expect(field().textContent).toBe('Item one two')
+  })
+
+  it('a change from elsewhere is loaded while you are not in it', async () => {
+    const { rerender } = draw()
+    rerender({ value: 'Item three' })
+    await waitFor(() => expect(field().textContent).toBe('Item three'))
+  })
+
+  it('your own save coming back is not loaded over what you go on typing', async () => {
+    const { rerender, onCommit } = draw()
+    await enter()
+    await type(' two')
+    await userEvent.keyboard('{Enter}')
+    expect(onCommit).toHaveBeenCalledWith('Item one two')
+    await type('!')
+    rerender({ value: 'Item one two' })
+    expect(field().textContent).toBe('Item one two!')
+  })
+})