@lovett/ui 0.0.11 → 0.2.0

package/src/thread/use-attachments.ts

@@ -0,0 +1,598 @@
+/**
+ * Composer attachments — the headless half (ADR-151 D1 and D5).
+ *
+ * The primitive owns no fetch client and no base URL (ADR-147 D5's rule for
+ * this whole package), so the host injects two functions: one that puts a
+ * `Blob` somewhere and comes back with a verified ticket, and one that turns a
+ * Giphy id into the same thing. Everything else — per-file progress, cancel,
+ * the count and byte ceilings, the paste threshold, the undo — is here.
+ *
+ * ## D1: each file is its own unit
+ *
+ * An upload starts the moment a file lands and carries its own progress and its
+ * own cancel. Send stays enabled and waits for whatever is still in flight,
+ * rather than being greyed out while a 20 MB file finishes — the person is
+ * usually still typing, and disabling send is how a composer starts feeling
+ * like it is having a conversation with itself.
+ *
+ * ## D5: a large paste is an OFFER, not a seizure
+ *
+ * A paste of 2,500 characters or more becomes a `.txt` attachment through the
+ * exact same path a dropped file takes — `new Blob([text], …)` is the whole
+ * mechanism, which is why D5 is cheap once D1 exists.
+ *
+ * **The original string is kept verbatim on the chip**, so "Insert as text
+ * instead" restores it byte for byte. That is not a nicety: a paste silently
+ * becoming a file the person did not want is worse than a long comment, and it
+ * is the first thing to get wrong. The undo lives as long as the composer does.
+ *
+ * The threshold is checked on the RAW pasted string, before any markdown
+ * parsing — parsing 200 KB only to throw the AST away is work nobody asked for.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/**
+ * ADR-151 D5. Long enough that a normal paragraph, a stack trace or a pasted
+ * list is never intercepted; short enough that the thing which would have
+ * drowned the comment does not. Recorded here with the reasoning rather than
+ * scattered as a magic number.
+ */
+export const PASTE_ATTACHMENT_THRESHOLD = 2_500
+
+/**
+ * ADR-151 D4. Giphy's free tier is 100 requests/hour, and a type-as-you-search
+ * picker burns that in about a minute. This debounce and the worker's
+ * five-minute cache are the two halves of keeping the picker affordable;
+ * neither is optional.
+ */
+export const GIF_SEARCH_DEBOUNCE_MS = 300
+
+/** Mirrors the worker's D3 caps so the composer can refuse before uploading. */
+export const ATTACHMENT_LIMITS = {
+  fileMaxBytes: 25 * 1024 * 1024,
+  commentMaxBytes: 50 * 1024 * 1024,
+  maxPerComment: 10,
+} as const
+
+export type ComposerAttachmentKind = 'image' | 'gif' | 'file'
+
+export type ComposerAttachmentState = 'uploading' | 'ready' | 'failed'
+
+/** One chip in the tray. */
+export interface ComposerAttachment {
+  /** Stable for the life of the chip, including before a ticket exists. */
+  readonly localId: string
+  readonly name: string
+  readonly sizeBytes: number
+  readonly kind: ComposerAttachmentKind
+  readonly state: ComposerAttachmentState
+  /** 0..1. Meaningful only while `state === 'uploading'`. */
+  readonly progress: number
+  /** The server's ticket. Present once `state === 'ready'`. */
+  readonly ticketId?: string | undefined
+  /** A message already in the product's voice, straight from the server. */
+  readonly error?: string | undefined
+  /** A local object URL (or a GIF still). Never a stored URL. */
+  readonly previewUrl?: string | undefined
+  readonly aspectRatio?: number | undefined
+  /**
+   * D5 — the exact text this chip was made from, kept so "Insert as text
+   * instead" restores it byte for byte. Present only for a pasted-text chip.
+   */
+  readonly pastedText?: string | undefined
+  /**
+   * D5 — "the character count shown on the chip". Present only for a paste,
+   * and it is the count of CHARACTERS, not of bytes: the person pasted
+   * characters, and for anything non-ASCII the two differ enough that showing
+   * bytes under a character label would be a small lie.
+   */
+  readonly charCount?: number | undefined
+}
+
+/** What the host's uploader hands back. Mirrors the worker's ticket shape. */
+export interface AttachmentTicketLike {
+  id: string
+  kind: string
+  name: string
+  sizeBytes: number
+  mime: string
+  aspectRatio: number | null
+}
+
+export interface UseAttachmentsOptions {
+  /**
+   * Put the bytes somewhere and come back with a verified ticket.
+   *
+   * The host is expected to run the upload AND the server-side verification;
+   * this hook only tracks the result. `signal` must genuinely abort the
+   * transfer — a cancel that only hides the chip leaves the bytes uploading.
+   */
+  readonly upload?: (
+    file: Blob,
+    opts: {
+      filename: string
+      signal: AbortSignal
+      onProgress: (fraction: number) => void
+    },
+  ) => Promise<AttachmentTicketLike>
+  /** Turn a Giphy id into a ticket. Omit to disable the GIF path entirely. */
+  readonly attachGif?: ((giphyId: string) => Promise<AttachmentTicketLike>) | undefined
+  /** Told about a refusal so the surface can say it once, in its own voice. */
+  readonly onError?: ((message: string) => void) | undefined
+  readonly maxPerComment?: number | undefined
+  readonly maxFileBytes?: number | undefined
+  readonly maxTotalBytes?: number | undefined
+}
+
+export interface UseAttachmentsResult {
+  readonly attachments: readonly ComposerAttachment[]
+  /** Ready tickets in render order — what the comment POST carries. */
+  readonly ticketIds: readonly string[]
+  /** True while anything is still in flight. Send WAITS on this; it is not disabled by it. */
+  readonly isUploading: boolean
+  readonly addFiles: (files: Iterable<File>) => void
+  /**
+   * D5. Returns `true` when the paste was intercepted, so the caller can
+   * `preventDefault()` — and `false` when it was not, so a short paste keeps
+   * ADR-148 D8's existing behaviour untouched.
+   */
+  readonly addPastedText: (text: string) => boolean
+  readonly addGif: (gif: { id: string; title: string; stillUrl: string; width: number; height: number }) => void
+  /** Cancels an in-flight upload as well as dropping the chip. */
+  readonly remove: (localId: string) => void
+  /** D5's undo. Returns the original text and drops the chip; `null` if not a paste. */
+  readonly insertAsText: (localId: string) => string | null
+  readonly clear: () => void
+}
+
+let localIdCounter = 0
+function nextLocalId(): string {
+  localIdCounter += 1
+  return `att-local-${String(localIdCounter)}`
+}
+
+/** D5: derived and honest. Never a fabricated filename. */
+export function pastedTextFilename(index: number): string {
+  return `pasted-text-${String(index)}.txt`
+}
+
+/** The threshold check, on the RAW string, before any parse. */
+export function shouldAttachPaste(text: string): boolean {
+  return text.length >= PASTE_ATTACHMENT_THRESHOLD
+}
+
+function kindOf(ticketKind: string): ComposerAttachmentKind {
+  if (ticketKind === 'image' || ticketKind === 'gif') return ticketKind
+  return 'file'
+}
+
+/** An image preview costs one object URL and no round trip. */
+function previewFor(file: File): string | undefined {
+  if (!file.type.startsWith('image/')) return undefined
+  try {
+    return URL.createObjectURL(file)
+  } catch {
+    return undefined
+  }
+}
+
+export function useAttachments(options: UseAttachmentsOptions): UseAttachmentsResult {
+  const {
+    upload,
+    attachGif,
+    onError,
+    maxPerComment = ATTACHMENT_LIMITS.maxPerComment,
+    maxFileBytes = ATTACHMENT_LIMITS.fileMaxBytes,
+    maxTotalBytes = ATTACHMENT_LIMITS.commentMaxBytes,
+  } = options
+
+  const [attachments, setAttachments] = useState<readonly ComposerAttachment[]>([])
+
+  /**
+   * A synchronous mirror of the list.
+   *
+   * The ceiling checks have to run BEFORE an upload starts, and they have to
+   * see files added earlier in the same batch — drop eleven at once and the
+   * eleventh must be refused, not started against a list that has not
+   * re-rendered. Reading that from a `setState` updater would mean doing the
+   * work inside it, which React is explicitly allowed to run twice. So the
+   * mirror is the read path and `setAttachments` stays a pure write.
+   */
+  const listRef = useRef<readonly ComposerAttachment[]>([])
+
+  const commit = useCallback(
+    (next: (current: readonly ComposerAttachment[]) => readonly ComposerAttachment[]) => {
+      const value = next(listRef.current)
+      listRef.current = value
+      setAttachments(value)
+    },
+    [],
+  )
+
+  // Live handles the render never reads. Keeping them in refs is what lets a
+  // cancel reach an upload that started three renders ago.
+  const controllers = useRef(new Map<string, AbortController>())
+  const objectUrls = useRef(new Set<string>())
+  const pasteCount = useRef(0)
+  // The uploader and the error sink change identity on most renders in a
+  // typical host; reading them through a ref keeps `addFiles` stable so the
+  // composer's own memoized handlers do not churn.
+  const uploadRef = useRef(upload)
+  const errorRef = useRef(onError)
+  uploadRef.current = upload
+  errorRef.current = onError
+  const gifRef = useRef(attachGif)
+  gifRef.current = attachGif
+
+  // Revoke every object URL that is still outstanding, on unmount. Individual
+  // URLs are released by `releasePreview` as their chips go — see there for why
+  // that release is deferred rather than immediate.
+  useEffect(() => {
+    const urls = objectUrls.current
+    const inFlight = controllers.current
+    return () => {
+      for (const url of urls) URL.revokeObjectURL(url)
+      urls.clear()
+      for (const controller of inFlight.values()) controller.abort()
+      inFlight.clear()
+    }
+  }, [])
+
+  /**
+   * Release one preview's object URL, a beat after its chip is gone.
+   *
+   * Revoking immediately is wrong: a chip can be removed while its `<img>` is
+   * still painting the very frame being torn down, and pulling the URL out from
+   * under it turns the preview into a broken icon on the way out. Never
+   * revoking is also wrong, and was the previous behaviour — `clear()` runs
+   * after every successful send, so a long-lived composer accumulated the File
+   * blob of every image ever attached until it unmounted.
+   *
+   * A macrotask is enough: React has committed the removal by then, so nothing
+   * is left holding the URL.
+   */
+  const releasePreview = useCallback((url: string | undefined) => {
+    if (url === undefined || !objectUrls.current.has(url)) return
+    objectUrls.current.delete(url)
+    setTimeout(() => {
+      URL.revokeObjectURL(url)
+    }, 0)
+  }, [])
+
+  const patch = useCallback(
+    (localId: string, next: Partial<ComposerAttachment>) => {
+      commit((current) => current.map((a) => (a.localId === localId ? { ...a, ...next } : a)))
+    },
+    [commit],
+  )
+
+  const fail = useCallback((message: string) => {
+    errorRef.current?.(message)
+  }, [])
+
+  /**
+   * The one path every attachment takes — a dropped file, a pasted string, a
+   * GIF. D5's "there is no second upload mechanism" is this function having
+   * exactly one caller shape.
+   */
+  const start = useCallback(
+    (
+      blob: Blob,
+      meta: {
+        name: string
+        kind: ComposerAttachmentKind
+        previewUrl?: string | undefined
+        pastedText?: string | undefined
+        charCount?: number | undefined
+      },
+    ) => {
+      const uploader = uploadRef.current
+      // A rich composer can exist without a host upload seam. In that case
+      // files and long text stay in their native paths rather than becoming
+      // chips that can never finish.
+      if (uploader === undefined) return
+      const localId = nextLocalId()
+      const controller = new AbortController()
+      controllers.current.set(localId, controller)
+      if (meta.previewUrl !== undefined) objectUrls.current.add(meta.previewUrl)
+
+      commit((current) => [
+        ...current,
+        {
+          localId,
+          name: meta.name,
+          sizeBytes: blob.size,
+          kind: meta.kind,
+          state: 'uploading',
+          progress: 0,
+          previewUrl: meta.previewUrl,
+          pastedText: meta.pastedText,
+          charCount: meta.charCount,
+        },
+      ])
+
+      void uploader(blob, {
+        filename: meta.name,
+        signal: controller.signal,
+        onProgress: (fraction) => {
+          patch(localId, { progress: Math.max(0, Math.min(1, fraction)) })
+        },
+      })
+        .then((ticket) => {
+          controllers.current.delete(localId)
+          patch(localId, {
+            state: 'ready',
+            progress: 1,
+            ticketId: ticket.id,
+            // The server's own account wins over the local guess: it read the
+            // magic number and we read a filename.
+            name: ticket.name,
+            sizeBytes: ticket.sizeBytes,
+            kind: kindOf(ticket.kind),
+            ...(ticket.aspectRatio === null ? {} : { aspectRatio: ticket.aspectRatio }),
+          })
+        })
+        .catch((err: unknown) => {
+          controllers.current.delete(localId)
+          // A cancel is not a failure and must not leave a red chip behind —
+          // `remove` has already dropped it.
+          if (err instanceof DOMException && err.name === 'AbortError') return
+          const message =
+            err instanceof Error && err.message.length > 0
+              ? err.message
+              : "That file couldn't be attached."
+          patch(localId, { state: 'failed', error: message })
+          fail(message)
+        })
+
+      return localId
+    },
+    [commit, fail, patch],
+  )
+
+  /**
+   * The two ceilings, checked before an upload starts.
+   *
+   * A courtesy, never the check: the worker re-measures both against the bytes
+   * R2 actually holds, so a client that skipped this entirely is refused all
+   * the same. What it buys is that a 30 MB file is refused in front of the
+   * person instead of two minutes later.
+   */
+  const admits = useCallback(
+    (size: number, label: string): boolean => {
+      const current = listRef.current
+      if (current.length >= maxPerComment) {
+        fail(`You can attach up to ${String(maxPerComment)} files to a comment.`)
+        return false
+      }
+      if (size > maxFileBytes) {
+        fail(`${label} is too large. Files can be up to 25 MB.`)
+        return false
+      }
+      const total = current.reduce((sum, a) => sum + a.sizeBytes, 0)
+      if (total + size > maxTotalBytes) {
+        fail('That would put this comment over 50 MB of attachments.')
+        return false
+      }
+      return true
+    },
+    [fail, maxFileBytes, maxPerComment, maxTotalBytes],
+  )
+
+  const addFiles = useCallback(
+    (files: Iterable<File>) => {
+      if (uploadRef.current === undefined) return
+      // `start` writes through `commit`, which updates the mirror synchronously
+      // — so the ceiling check on the second file already counts the first.
+      //
+      // `continue`, NOT `break`. An earlier version stopped at the first
+      // refusal, so dropping five files where the second was 30 MB uploaded
+      // the first, reported the second, and made the last three vanish with no
+      // message at all. D3 requires every refusal be named and shown; three
+      // files disappearing silently is the exact failure that rule exists to
+      // prevent. Skipping the oversized one and carrying on is also what a
+      // person means by dropping a folder.
+      for (const file of files) {
+        if (!admits(file.size, file.name)) continue
+        const preview = previewFor(file)
+        start(file, {
+          name: file.name,
+          kind: file.type.startsWith('image/') ? 'image' : 'file',
+          previewUrl: preview,
+        })
+      }
+    },
+    [admits, start],
+  )
+
+  const addPastedText = useCallback(
+    (text: string): boolean => {
+      if (uploadRef.current === undefined) return false
+      if (!shouldAttachPaste(text)) return false
+      pasteCount.current += 1
+      const name = pastedTextFilename(pasteCount.current)
+      const blob = new Blob([text], { type: 'text/plain' })
+      if (!admits(blob.size, 'That paste')) {
+        // Refused for size or count: it stays PROSE rather than vanishing. The
+        // caller does not preventDefault, so the paste lands in the body.
+        pasteCount.current -= 1
+        return false
+      }
+      start(blob, { name, kind: 'file', pastedText: text, charCount: text.length })
+      return true
+    },
+    [admits, start],
+  )
+
+  const addGif = useCallback(
+    (gif: { id: string; title: string; stillUrl: string; width: number; height: number }) => {
+      const attach = gifRef.current
+      if (attach === undefined) return
+      if (listRef.current.length >= maxPerComment) {
+        fail(`You can attach up to ${String(maxPerComment)} files to a comment.`)
+        return
+      }
+      const localId = nextLocalId()
+      commit((current) => [
+        ...current,
+        {
+          localId,
+          name: gif.title.length > 0 ? gif.title : 'GIF',
+          sizeBytes: 0,
+          kind: 'gif',
+          state: 'uploading',
+          progress: 0,
+          previewUrl: gif.stillUrl,
+          ...(gif.height > 0 ? { aspectRatio: gif.width / gif.height } : {}),
+        },
+      ])
+
+      void attach(gif.id)
+        .then((ticket) => {
+          patch(localId, {
+            state: 'ready',
+            progress: 1,
+            ticketId: ticket.id,
+            name: ticket.name,
+            sizeBytes: ticket.sizeBytes,
+            kind: 'gif',
+            ...(ticket.aspectRatio === null ? {} : { aspectRatio: ticket.aspectRatio }),
+          })
+        })
+        .catch((err: unknown) => {
+          const message =
+            err instanceof Error && err.message.length > 0
+              ? err.message
+              : "That GIF couldn't be attached."
+          patch(localId, { state: 'failed', error: message })
+          fail(message)
+        })
+    },
+    [commit, fail, maxPerComment, patch],
+  )
+
+  const remove = useCallback(
+    (localId: string) => {
+      // Abort FIRST. A chip that disappears while its bytes keep uploading is a
+      // cancel that cancelled nothing.
+      controllers.current.get(localId)?.abort()
+      controllers.current.delete(localId)
+      releasePreview(listRef.current.find((a) => a.localId === localId)?.previewUrl)
+      commit((current) => current.filter((a) => a.localId !== localId))
+    },
+    [commit, releasePreview],
+  )
+
+  const insertAsText = useCallback(
+    (localId: string): string | null => {
+      const found = listRef.current.find((a) => a.localId === localId)
+      const text = found?.pastedText ?? null
+      if (text === null) return null
+      controllers.current.get(localId)?.abort()
+      controllers.current.delete(localId)
+      releasePreview(found?.previewUrl)
+      commit((current) => current.filter((a) => a.localId !== localId))
+      return text
+    },
+    [commit, releasePreview],
+  )
+
+  const clear = useCallback(() => {
+    for (const controller of controllers.current.values()) controller.abort()
+    controllers.current.clear()
+    for (const attachment of listRef.current) releasePreview(attachment.previewUrl)
+    commit(() => [])
+  }, [commit, releasePreview])
+
+  return {
+    attachments,
+    ticketIds: attachments
+      .filter((a) => a.state === 'ready' && a.ticketId !== undefined)
+      .map((a) => a.ticketId ?? ''),
+    isUploading: attachments.some((a) => a.state === 'uploading'),
+    addFiles,
+    addPastedText,
+    addGif,
+    remove,
+    insertAsText,
+    clear,
+  }
+}
+
+/**
+ * Resolve a posted attachment's short-lived URL, once, lazily (ADR-151 D6).
+ *
+ * The wire carries no URL — the storage key never leaves the worker — so a
+ * renderer is handed the SHAPE of the slot and asks for the bytes separately.
+ * The box is already reserved from the declared aspect ratio by the time this
+ * runs, which is the whole point of the ordering: nothing reflows when the
+ * picture lands, or fails to.
+ *
+ * `null` means "asked and could not have it", and the caller renders the
+ * placeholder — never a collapsed box.
+ */
+export function useAttachmentUrl(
+  attachmentId: string,
+  resolve: ((attachmentId: string) => Promise<string | null>) | undefined,
+): { url: string | null; failed: boolean; loading: boolean } {
+  const [url, setUrl] = useState<string | null>(null)
+  const [failed, setFailed] = useState(false)
+  /**
+   * Distinct from `failed`, and the distinction is the whole point.
+   *
+   * An earlier version rendered the broken-image placeholder whenever there was
+   * no URL — which meant every attachment showed the failure treatment for the
+   * whole time it was resolving. D6 asks for a placeholder when an image is
+   * BROKEN; showing it while the answer is still on its way tells the reader
+   * something untrue about their own comment.
+   */
+  const [loading, setLoading] = useState(resolve !== undefined)
+
+  /**
+   * The resolver is read through a ref and is NOT a dependency.
+   *
+   * This is deliberate and it is load-bearing. The resolver arrives from the
+   * host, through `ThreadProps` and the render context, and a host that writes
+   * `resolveAttachmentUrl={(id) => api.attachmentUrl(brandId, …, id)}` — which
+   * is the obvious and correct-looking way to write it — hands over a NEW
+   * function identity on every render. With that in the dependency array the
+   * effect re-runs, sets state, re-renders, and re-runs: an infinite fetch loop
+   * that presents as a hung tab or an out-of-memory test, not as an error.
+   *
+   * So the effect keys on the attachment id, which is the thing that actually
+   * identifies what to fetch, plus whether a resolver exists at all (so a host
+   * that supplies one late still resolves). A resolver whose BEHAVIOUR changes
+   * without the id changing is not a case that occurs: a different brand or a
+   * different thread brings different attachment ids with it.
+   */
+  const resolveRef = useRef(resolve)
+  resolveRef.current = resolve
+  const enabled = resolve !== undefined
+
+  useEffect(() => {
+    const current = resolveRef.current
+    if (current === undefined) return
+    let live = true
+    setUrl(null)
+    setFailed(false)
+    setLoading(true)
+    void current(attachmentId)
+      .then((next) => {
+        if (!live) return
+        if (next === null || next.length === 0) setFailed(true)
+        else setUrl(next)
+        setLoading(false)
+      })
+      .catch(() => {
+        if (!live) return
+        setFailed(true)
+        setLoading(false)
+      })
+    return () => {
+      live = false
+    }
+  }, [attachmentId, enabled])
+
+  return { url, failed, loading }
+}

package/src/thread/use-now.ts

@@ -0,0 +1,73 @@
+/**
+ * useNowTick — ONE 60-second clock, shared by every thread on the page.
+ *
+ * ADR-147 D16 and acceptance criterion 9: `Date.now()` is never called inside
+ * a render path in the thread primitive.
+ *
+ * Two things are wrong with the obvious `useState(() => Date.now())`:
+ *
+ *   1. A lazy state initialiser still executes during the component's first
+ *      render, so the component is non-deterministic — CLAUDE.md §7 says tests
+ *      must not be time-dependent without a frozen clock, and a component that
+ *      reads the wall clock while rendering cannot be frozen from outside.
+ *   2. One interval per thread means N timers drifting against each other, so
+ *      two timestamps that should both flip from "now" to "1m" do it on
+ *      different frames.
+ *
+ * So the clock is a module-scope external store read through
+ * `useSyncExternalStore`. `Date.now()` appears exactly twice, in `tick()` and
+ * at module load — never in a component body. Every subscriber re-renders from
+ * the same value on the same frame, and a test freezes time by passing an
+ * explicit `now` (which disables the subscription entirely, so no timer runs
+ * and no fake-timer plumbing is needed).
+ */
+
+import { useSyncExternalStore } from 'react'
+
+const TICK_MS = 60_000
+
+let current = Date.now()
+let timer: ReturnType<typeof setInterval> | null = null
+const listeners = new Set<() => void>()
+
+function tick(): void {
+  current = Date.now()
+  for (const listener of listeners) listener()
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  if (timer === null) {
+    // The module may have been imported long before the first thread mounted,
+    // so refresh on the first subscriber rather than trusting load time.
+    // React re-reads the snapshot immediately after subscribing, so this is
+    // picked up without notifying mid-subscribe.
+    current = Date.now()
+    timer = setInterval(tick, TICK_MS)
+  }
+  return () => {
+    listeners.delete(listener)
+    if (listeners.size === 0 && timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+}
+
+const noopSubscribe = (): (() => void) => () => {}
+
+function getSnapshot(): number {
+  return current
+}
+
+/**
+ * @param enabled false when the caller injected its own `now` — no timer runs
+ *        and the returned value is ignored. Frozen clock, zero side effects.
+ */
+export function useNowTick(enabled: boolean): number {
+  return useSyncExternalStore(
+    enabled ? subscribe : noopSubscribe,
+    getSnapshot,
+    getSnapshot,
+  )
+}