@lovett/ui 0.0.11 → 0.2.0

package/src/thread/rich-composer.tsx

@@ -0,0 +1,195 @@
+/**
+ * RichThreadComposer — the shell around the TipTap composer.
+ *
+ * ADR-148 D5 / D6. This file satisfies `ThreadComposerProps` exactly, so
+ * `<Thread composer="rich">` cannot tell it from `ThreadComposer`, and it is
+ * the ONLY thing the package barrel exports for the rich editor. It imports
+ * no TipTap: the editor lives in `rich-composer-impl.tsx` behind the single
+ * `lazy()` boundary below, which is what keeps ProseMirror out of every
+ * consumer that renders a thread LIST (AC#10). The chunk is requested when a
+ * composer MOUNTS — not on focus, which would need a placeholder control, a
+ * swap and a caret restore for the bytes it would save.
+ *
+ * Three states, and a dead composer is never one of them (D6):
+ *
+ *   loading  — the plain composer, disabled, holding the draft. Same `rows`,
+ *              same padding, and the editor reserves the same height, so the
+ *              swap moves nothing.
+ *   ready    — the editor (the impl decides, before it mounts anything, whether
+ *              the draft is even rich-editable — D3 rule 2 — and if not,
+ *              renders the plain composer with the source untouched).
+ *   failed   — the import rejected (offline, a chunk that 404s after a deploy,
+ *              a CSP block): the plain composer with the same draft, and a
+ *              one-line notice. Nothing is lost, because the draft is markdown
+ *              (D1). Reported once, politely, never with a modal.
+ *
+ * The live region here is the composer's own. `ThreadComposerProps` carries no
+ * `announce` seam to the thread's single region, and adding one means editing
+ * composer.tsx and comment.tsx, which this ADR's scope left alone — noted in
+ * the completion report as the two-line follow-up it is.
+ */
+
+import { Component, Suspense, lazy, useCallback, useState } from 'react'
+import type { ErrorInfo, ReactNode } from 'react'
+import { Info } from 'lucide-react'
+import { ThreadComposer, type ThreadComposerProps } from './composer'
+import type { GifPickerResult } from './attachments'
+import type { MentionSuggestionItem } from './types'
+import type { UseAttachmentsOptions } from './use-attachments'
+
+const RichThreadComposerImpl = lazy(() => import('./rich-composer-impl'))
+
+/** D6, in the words the live region speaks. */
+export const RICH_FALLBACK_NOTICE = 'Rich editor unavailable, plain editor loaded'
+
+/** The one-line notice above a plain composer that stands in for the rich one. */
+export function ComposerNotice({ children }: { readonly children: ReactNode }) {
+  return (
+    <p
+      className="flex items-center gap-[var(--space-1)] text-[12px]"
+      style={{ color: 'rgb(var(--text-tertiary))' }}
+    >
+      <Info size={12} strokeWidth={1.75} aria-hidden="true" />
+      <span>{children}</span>
+    </p>
+  )
+}
+
+interface ChunkBoundaryProps {
+  readonly fallback: ReactNode
+  readonly onError: (error: unknown) => void
+  readonly children: ReactNode
+}
+
+/**
+ * `lazy()` reports a rejected import by throwing during render; a boundary is
+ * the only place React lets that be caught. It renders the plain composer in
+ * place and tells the shell, which then owns the failed state for good — a
+ * rejected `lazy` stays rejected for the life of the page anyway.
+ */
+class ChunkBoundary extends Component<ChunkBoundaryProps, { readonly failed: boolean }> {
+  override state = { failed: false }
+
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true }
+  }
+
+  override componentDidCatch(error: unknown, _info: ErrorInfo): void {
+    this.props.onError(error)
+  }
+
+  override render(): ReactNode {
+    return this.state.failed ? this.props.fallback : this.props.children
+  }
+}
+
+/**
+ * `ThreadComposerProps` plus the optional host capabilities added by ADR-149
+ * and ADR-151: mention lookup, upload + ticket verification, GIF search, and
+ * the worker's attachment limits. `<Thread composer="rich">` can still hand
+ * this component a bare `ThreadComposerProps`; absent capabilities simply do
+ * not render controls that cannot work.
+ *
+ * They stop here rather than continuing down to `ThreadComposer`: the plain
+ * textarea has neither a suggestion layer nor attachment state, so fallback
+ * paths deliberately drop them without offering inert controls.
+ */
+export interface RichComposerAttachmentProps {
+  /** Upload bytes and return the worker-verified `tup_...` ticket. */
+  readonly uploadAttachment?: NonNullable<UseAttachmentsOptions['upload']> | undefined
+  /** Turn a Giphy id into the same verified ticket shape. */
+  readonly attachGif?: NonNullable<UseAttachmentsOptions['attachGif']> | undefined
+  /** Search results stay host-owned so no API URL or key enters this package. */
+  readonly searchGifs?: ((query: string) => Promise<readonly GifPickerResult[]>) | undefined
+  /** Mirrors the worker's extension allowlist for the native file chooser. */
+  readonly attachmentAccept?: string | undefined
+  readonly attachmentMaxPerComment?: number | undefined
+  readonly attachmentMaxFileBytes?: number | undefined
+  readonly attachmentMaxTotalBytes?: number | undefined
+}
+
+export interface RichThreadComposerProps
+  extends ThreadComposerProps,
+    RichComposerAttachmentProps {
+  readonly mentionItems?: ((query: string) => readonly MentionSuggestionItem[]) | undefined
+}
+
+export function RichThreadComposer({
+  mentionItems,
+  uploadAttachment,
+  attachGif,
+  searchGifs,
+  attachmentAccept,
+  attachmentMaxPerComment,
+  attachmentMaxFileBytes,
+  attachmentMaxTotalBytes,
+  ...props
+}: RichThreadComposerProps) {
+  const [failed, setFailed] = useState(false)
+
+  // Same shape as the thread's region: a live region speaks when its text
+  // CHANGES, so the sequence alternates a trailing NBSP that screen readers
+  // trim and the DOM counts as a change.
+  const [announcement, setAnnouncement] = useState<{
+    readonly text: string
+    readonly seq: number
+  }>({ text: '', seq: 0 })
+
+  const announce = useCallback((text: string) => {
+    setAnnouncement((prev) => ({ text, seq: prev.seq + 1 }))
+  }, [])
+
+  const onError = useCallback(
+    (error: unknown) => {
+      console.warn(
+        'rich composer: the editor chunk could not load; the plain composer is rendered instead',
+        error,
+      )
+      setFailed(true)
+      announce(RICH_FALLBACK_NOTICE)
+    },
+    [announce],
+  )
+
+  const spoken =
+    announcement.text === ''
+      ? ''
+      : announcement.seq % 2 === 0
+        ? `${announcement.text}\u{00A0}`
+        : announcement.text
+
+  return (
+    <div className="flex flex-col gap-[var(--space-1)]">
+      {/* Rendered empty on mount and kept for the life of the composer: an AT
+          has to be observing the node before the text lands. */}
+      <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+        {spoken}
+      </div>
+      {failed ? (
+        <>
+          <ComposerNotice>{RICH_FALLBACK_NOTICE}</ComposerNotice>
+          <ThreadComposer {...props} />
+        </>
+      ) : (
+        <ChunkBoundary onError={onError} fallback={<ThreadComposer {...props} />}>
+          <Suspense fallback={<ThreadComposer {...props} disabled />}>
+            <RichThreadComposerImpl
+              {...props}
+              announce={announce}
+              {...(mentionItems === undefined ? {} : { mentionItems })}
+              {...(uploadAttachment === undefined ? {} : { uploadAttachment })}
+              {...(attachGif === undefined ? {} : { attachGif })}
+              {...(searchGifs === undefined ? {} : { searchGifs })}
+              {...(attachmentAccept === undefined ? {} : { attachmentAccept })}
+              {...(attachmentMaxPerComment === undefined
+                ? {}
+                : { attachmentMaxPerComment })}
+              {...(attachmentMaxFileBytes === undefined ? {} : { attachmentMaxFileBytes })}
+              {...(attachmentMaxTotalBytes === undefined ? {} : { attachmentMaxTotalBytes })}
+            />
+          </Suspense>
+        </ChunkBoundary>
+      )}
+    </div>
+  )
+}

package/src/thread/scroll-caret.ts

@@ -0,0 +1,37 @@
+/**
+ * The scroll math behind `handleScrollToSelection` (ADR-148, owner report
+ * 2026-09-07: "when I did returns or new lines in the rich editor, the same
+ * issue happened again").
+ *
+ * It lives in its own module for one reason: it is the part that can be
+ * tested. jsdom performs no layout, so `coordsAtPos` and
+ * `getBoundingClientRect` are meaningless there — but the DECISION made from
+ * those numbers is pure arithmetic, and that is where a sign error or an
+ * off-by-a-line would hide.
+ *
+ * The rule: move the editor's own `scrollTop` by the smallest amount that puts
+ * the caret inside the box with one line of slack, and never move anything
+ * else. A single element's `scrollTop` cannot chain to an ancestor, which is
+ * the entire point — ProseMirror's default walks up and scrolls every
+ * scrollable ancestor it can find.
+ */
+
+export interface CaretBox {
+  readonly top: number
+  readonly bottom: number
+}
+
+/**
+ * How far to move `scrollTop`. Positive scrolls down, negative up, 0 means the
+ * caret is already comfortably inside.
+ *
+ * `pad` is one line height: a caret flush against the edge reads as clipped
+ * even though it is technically visible.
+ */
+export function caretScrollDelta(box: CaretBox, caret: CaretBox, pad: number): number {
+  // Above the top edge (plus slack) — pull up.
+  if (caret.top < box.top + pad) return caret.top - (box.top + pad)
+  // Below the bottom edge (minus slack) — push down.
+  if (caret.bottom > box.bottom - pad) return caret.bottom - (box.bottom - pad)
+  return 0
+}

package/src/thread/suggestion-list.tsx

@@ -0,0 +1,182 @@
+/**
+ * SuggestionList — the ONE popup behind both composer triggers (ADR-149 D1).
+ *
+ * `@` and `:` are the same interaction: type a sigil, filter a list, choose
+ * with the keyboard, insert something. The differences are DATA and RENDERING
+ * — who supplies the options and what each row shows — never behaviour, so
+ * there is one listbox here and two configurations in `markdown-spec.ts`.
+ * Two popups would mean two focus models and two sets of accessibility bugs.
+ *
+ * D5, the contract this file exists to hold:
+ *
+ *   - The EDITOR keeps DOM focus throughout. Nothing in here is ever focused:
+ *     the options are buttons for their hit area and click semantics, held out
+ *     of the tab order and guarded by a `mousedown` preventDefault so a click
+ *     cannot move the caret. The editor points at the active option with
+ *     `aria-activedescendant` (set by the composer, which owns the editor's
+ *     DOM node) and at this list with `aria-controls`.
+ *   - `role="listbox"` / `role="option"` / `aria-selected`, so the pairing is
+ *     the one an AT expects from a combobox-shaped completion.
+ *   - The active option is scrolled into view INSIDE THE POPUP ONLY. This
+ *     codebase has fixed "the page scrolls while I type" twice (the composer's
+ *     `handleScrollToSelection`, then its height ceiling), and
+ *     `Element.scrollIntoView` is exactly the API that reintroduces it — it
+ *     walks up and scrolls every scrollable ancestor. So: arithmetic on this
+ *     one element's `scrollTop`, plus `overscroll-behavior: contain` in CSS
+ *     for the wheel and touch paths. A single element's `scrollTop` cannot
+ *     chain.
+ *
+ * The two pure helpers below are exported because they are the part jsdom can
+ * actually verify: wrapping and scroll arithmetic. Placement is floating-ui's
+ * job and is checked in the browser pass, not here.
+ */
+
+import { useLayoutEffect, useRef } from 'react'
+
+export interface SuggestionOption {
+  /** Stable identity for React and for the option's DOM id. */
+  readonly key: string
+  /** The row's primary text — a person's name, or `:shortcode:`. */
+  readonly label: string
+  /** Secondary text, right-aligned: the mention's kind, or an alias hit. */
+  readonly hint?: string | undefined
+  /** The leading glyph slot: an emoji character, or a person's initial. */
+  readonly glyph?: string | undefined
+  /**
+   * Whether the glyph merely repeats what the label already says.
+   *
+   * A mention's leading initial is the first letter of the name beside it, so
+   * it is decoration and is hidden from assistive technology. An EMOJI is the
+   * opposite: it is the thing being chosen, and hiding it would leave a
+   * screen-reader user choosing between shortcodes with no idea what any of
+   * them looks like. Unhidden, the option announces the emoji's own Unicode
+   * name — "party popper" — which is the whole point of the row.
+   */
+  readonly glyphDecorative?: boolean | undefined
+}
+
+/**
+ * Move `current` by `delta` through a list of `length`, wrapping at both ends
+ * (D5: "ArrowUp / ArrowDown move the active option and wrap"). An empty list
+ * has no active option, which is `0` — the popup is closed in that case
+ * anyway, and a negative index would be a worse lie.
+ */
+export function wrapIndex(current: number, length: number, delta: number): number {
+  if (length <= 0) return 0
+  return (((current + delta) % length) + length) % length
+}
+
+export interface ScrollViewport {
+  readonly scrollTop: number
+  readonly clientHeight: number
+}
+
+export interface ScrollTarget {
+  readonly offsetTop: number
+  readonly offsetHeight: number
+}
+
+/**
+ * The popup's new `scrollTop` so the active option is fully visible, moved by
+ * the smallest amount that does it — and never anything else's scrollTop.
+ */
+export function listScrollTop(view: ScrollViewport, target: ScrollTarget): number {
+  if (target.offsetTop < view.scrollTop) return target.offsetTop
+  const bottom = target.offsetTop + target.offsetHeight
+  if (bottom > view.scrollTop + view.clientHeight) return bottom - view.clientHeight
+  return view.scrollTop
+}
+
+export interface SuggestionListProps {
+  /** The listbox's DOM id — the editor's `aria-controls` points at it. */
+  readonly id: string
+  /** The listbox's accessible name ("Emoji", "Mention someone"). */
+  readonly label: string
+  readonly options: readonly SuggestionOption[]
+  readonly activeIndex: number
+  /** Option DOM ids, so the editor's `aria-activedescendant` can name one. */
+  readonly optionId: (index: number) => string
+  /** Insert the option at `index` (a click, or Enter / Tab from the editor). */
+  readonly onSelect: (index: number) => void
+  /** A pointer hover makes an option active without inserting it. */
+  readonly onActivate: (index: number) => void
+}
+
+export function SuggestionList({
+  id,
+  label,
+  options,
+  activeIndex,
+  optionId,
+  onSelect,
+  onActivate,
+}: SuggestionListProps) {
+  const listRef = useRef<HTMLDivElement>(null)
+
+  useLayoutEffect(() => {
+    const list = listRef.current
+    if (list === null) return
+    const option = list.children.item(activeIndex)
+    if (!(option instanceof HTMLElement)) return
+    list.scrollTop = listScrollTop(list, option)
+  }, [activeIndex, options])
+
+  return (
+    <div
+      ref={listRef}
+      id={id}
+      role="listbox"
+      aria-label={label}
+      className="ds-thread-suggestions"
+      // The options refuse focus one by one; this refuses it for the padding
+      // ring and the scrollbar between them. Without it a click on either
+      // blurs the contenteditable, which closes the popup and moves focus —
+      // the exact hole D5 says must not exist.
+      onMouseDown={(event) => {
+        event.preventDefault()
+      }}
+    >
+      {options.map((option, index) => {
+        const active = index === activeIndex
+        return (
+          <button
+            key={option.key}
+            type="button"
+            id={optionId(index)}
+            role="option"
+            aria-selected={active}
+            // D5: the editor keeps focus. These are buttons for their hit area
+            // and click semantics only — never for focus.
+            tabIndex={-1}
+            data-active={active}
+            className="ds-thread-suggestions__option"
+            onMouseDown={(event) => {
+              event.preventDefault()
+            }}
+            onMouseEnter={() => {
+              onActivate(index)
+            }}
+            onClick={() => {
+              onSelect(index)
+            }}
+          >
+            <span
+              // Reserved slot either way, so a hidden glyph still holds the
+              // column and the labels stay on one alignment grid.
+              {...(option.glyphDecorative === true || option.glyph === undefined
+                ? { 'aria-hidden': true as const }
+                : {})}
+              className="ds-thread-suggestions__glyph"
+            >
+              {option.glyph}
+            </span>
+            <span className="ds-thread-suggestions__label">{option.label}</span>
+            {option.hint === undefined ? null : (
+              <span className="ds-thread-suggestions__hint">{option.hint}</span>
+            )}
+          </button>
+        )
+      })}
+    </div>
+  )
+}