@lovett/ui 0.0.11 → 0.2.0

package/src/thread/use-thread.ts

@@ -0,0 +1,316 @@
+/**
+ * useThread — the headless core. It renders nothing.
+ *
+ * ADR-147 T3. Everything that is genuinely thread LOGIC lives here: building
+ * the tree, sorting it, collapse state, the depth cap, "show N more replies",
+ * the root draft, and which comment (if any) has an open reply composer.
+ * `<Thread>` is one skin over this; a consumer that wants different chrome
+ * uses the hook and draws its own.
+ *
+ * What this hook deliberately does NOT own:
+ *
+ *   • No fetch client, no base URL, no query key, no brand id. It takes
+ *     already-shaped data and reports intent through callbacks. T4 wires it.
+ *   • No persistence. The draft is in-memory here; ADR-147 D17 routes it
+ *     through `useResumableDraft` with a brand-partitioned key at the call
+ *     site, because a comment draft is EDITOR state — a bare `key={brand.id}`
+ *     on the thread would destroy an unsent comment on a brand switch.
+ *   • No reaction or vote state. Correction 3 to the port: the reference held
+ *     vote state in local `useState`, so a vote was lost the moment the dialog
+ *     closed. Engagement is props in, callbacks out, always.
+ *
+ * Every piece of local state here is genuinely local VIEW state — what is
+ * collapsed, what is expanded, what is being typed — and losing it on unmount
+ * is correct. That is the line.
+ */
+
+import { useCallback, useMemo, useState } from 'react'
+import { buildCommentTree, countCommentTree, sortCommentTree } from './comment-tree'
+import { useNowTick } from './use-now'
+import type {
+  CommentNode,
+  ThreadComment,
+  ThreadEngagement,
+  ThreadSort,
+} from './types'
+
+/**
+ * Nesting is UNCAPPED by default.
+ *
+ * The port inherited a cap of 2 plus "Continue this thread", and that cap was
+ * paying for a rendering problem rather than solving a reading one: when every
+ * level cost a 24px gutter and its own collapse button, depth was expensive and
+ * had to be rationed. Depth is now an indent and a hairline (rail.tsx), so it
+ * is cheap, and a dead-end control that hides half a conversation behind a
+ * click is a worse answer than simply showing it. The INDENT is what gets
+ * clamped instead (`indentClampDepth`), which is the thing that actually breaks
+ * in a narrow column.
+ *
+ * The cap machinery stays for a consumer that genuinely wants one — a preview
+ * strip on a card, a permalink view that pages by subtree. Set a finite
+ * `maxDepth` and "Continue this thread" comes back.
+ */
+export const DEFAULT_MAX_DEPTH = Number.POSITIVE_INFINITY
+/** Three replies visible, then "Show N more replies". */
+export const DEFAULT_REPLIES_VISIBLE = 3
+
+export interface UseThreadOptions {
+  readonly comments: readonly ThreadComment[]
+  /**
+   * Epoch ms. Omit and the hook subscribes to the shared 60s ticker; pass one
+   * and the clock is frozen and no timer runs (tests, SSR, a replay view).
+   */
+  readonly now?: number | undefined
+  /** Controlled sort. Omit for uncontrolled. */
+  readonly sort?: ThreadSort | undefined
+  readonly defaultSort?: ThreadSort | undefined
+  readonly onSortChange?: ((sort: ThreadSort) => void) | undefined
+  /** Render depth cap. Storage depth is always true (D3). */
+  readonly maxDepth?: number | undefined
+  readonly repliesVisible?: number | undefined
+  readonly engagement?: ThreadEngagement | undefined
+  /** Controlled collapse set. Omit for uncontrolled. */
+  readonly collapsed?: readonly string[] | undefined
+  readonly onCollapse?: ((commentId: string, collapsed: boolean) => void) | undefined
+  /** Controlled root draft — the seam T4 hands `useResumableDraft`. */
+  readonly draft?: string | undefined
+  readonly defaultDraft?: string | undefined
+  readonly onDraftChange?: ((value: string) => void) | undefined
+  /**
+   * Verified attachment ticket ids are the third argument so the existing
+   * `(body, parentId?)` seam stays source-compatible (ADR-151 D1).
+   */
+  readonly onSubmit?:
+    | ((body: string, parentId?: string, attachmentIds?: readonly string[]) => void)
+    | undefined
+}
+
+export interface VisibleReplies {
+  readonly visible: readonly CommentNode[]
+  readonly hidden: number
+}
+
+export interface UseThreadResult {
+  readonly now: number
+  readonly roots: readonly CommentNode[]
+  /** Every comment at every depth, tombstones included. */
+  readonly totalCount: number
+  readonly maxDepth: number
+  readonly repliesVisible: number
+  readonly engagement: ThreadEngagement
+
+  readonly sort: ThreadSort
+  readonly setSort: (sort: ThreadSort) => void
+
+  readonly isCollapsed: (commentId: string) => boolean
+  readonly setCollapsed: (commentId: string, collapsed: boolean) => void
+  readonly toggleCollapse: (commentId: string) => void
+
+  readonly isRepliesExpanded: (commentId: string) => boolean
+  readonly expandReplies: (commentId: string) => void
+  readonly visibleReplies: (node: CommentNode) => VisibleReplies
+
+  /** Whether the surface accepts new comments at all (an `onSubmit` exists). */
+  readonly canReply: boolean
+  readonly draft: string
+  readonly setDraft: (value: string) => void
+  readonly canSubmit: boolean
+  readonly submit: (attachmentIds?: readonly string[]) => void
+
+  readonly replyingTo: string | null
+  readonly isReplyingTo: (commentId: string) => boolean
+  readonly startReply: (commentId: string) => void
+  readonly cancelReply: () => void
+  readonly replyDraft: string
+  readonly setReplyDraft: (value: string) => void
+  readonly canSubmitReply: boolean
+  readonly submitReply: (attachmentIds?: readonly string[]) => void
+}
+
+export function useThread(options: UseThreadOptions): UseThreadResult {
+  const {
+    comments,
+    now: injectedNow,
+    sort: controlledSort,
+    defaultSort = 'top',
+    onSortChange,
+    maxDepth = DEFAULT_MAX_DEPTH,
+    repliesVisible = DEFAULT_REPLIES_VISIBLE,
+    engagement = 'reactions',
+    collapsed: controlledCollapsed,
+    onCollapse,
+    draft: controlledDraft,
+    defaultDraft = '',
+    onDraftChange,
+    onSubmit,
+  } = options
+
+  const tick = useNowTick(injectedNow === undefined)
+  const now = injectedNow ?? tick
+
+  const [uncontrolledSort, setUncontrolledSort] = useState<ThreadSort>(defaultSort)
+  const sort = controlledSort ?? uncontrolledSort
+
+  const [uncontrolledCollapsed, setUncontrolledCollapsed] = useState<ReadonlySet<string>>(
+    () => new Set<string>(),
+  )
+  const collapsedSet = useMemo(
+    () =>
+      controlledCollapsed === undefined
+        ? uncontrolledCollapsed
+        : new Set(controlledCollapsed),
+    [controlledCollapsed, uncontrolledCollapsed],
+  )
+
+  const [expanded, setExpanded] = useState<ReadonlySet<string>>(() => new Set<string>())
+
+  const [uncontrolledDraft, setUncontrolledDraft] = useState(defaultDraft)
+  const draft = controlledDraft ?? uncontrolledDraft
+
+  const [replyingTo, setReplyingTo] = useState<string | null>(null)
+  const [replyDraft, setReplyDraft] = useState('')
+
+  const tree = useMemo(() => buildCommentTree(comments), [comments])
+  const roots = useMemo(() => sortCommentTree(tree, sort), [tree, sort])
+  const totalCount = useMemo(() => countCommentTree(tree), [tree])
+
+  const setSort = useCallback(
+    (next: ThreadSort) => {
+      if (controlledSort === undefined) setUncontrolledSort(next)
+      onSortChange?.(next)
+    },
+    [controlledSort, onSortChange],
+  )
+
+  const isCollapsed = useCallback(
+    (commentId: string) => collapsedSet.has(commentId),
+    [collapsedSet],
+  )
+
+  const setCollapsed = useCallback(
+    (commentId: string, next: boolean) => {
+      if (controlledCollapsed === undefined) {
+        setUncontrolledCollapsed((prev) => {
+          if (prev.has(commentId) === next) return prev
+          const copy = new Set(prev)
+          if (next) copy.add(commentId)
+          else copy.delete(commentId)
+          return copy
+        })
+      }
+      onCollapse?.(commentId, next)
+    },
+    [controlledCollapsed, onCollapse],
+  )
+
+  const toggleCollapse = useCallback(
+    (commentId: string) => {
+      setCollapsed(commentId, !collapsedSet.has(commentId))
+    },
+    [collapsedSet, setCollapsed],
+  )
+
+  const isRepliesExpanded = useCallback(
+    (commentId: string) => expanded.has(commentId),
+    [expanded],
+  )
+
+  const expandReplies = useCallback((commentId: string) => {
+    setExpanded((prev) => {
+      if (prev.has(commentId)) return prev
+      const copy = new Set(prev)
+      copy.add(commentId)
+      return copy
+    })
+  }, [])
+
+  const visibleReplies = useCallback(
+    (node: CommentNode): VisibleReplies => {
+      const all = node.replies
+      if (expanded.has(node.id) || all.length <= repliesVisible) {
+        return { visible: all, hidden: 0 }
+      }
+      const visible = all.slice(0, repliesVisible)
+      return { visible, hidden: all.length - visible.length }
+    },
+    [expanded, repliesVisible],
+  )
+
+  const setDraft = useCallback(
+    (value: string) => {
+      if (controlledDraft === undefined) setUncontrolledDraft(value)
+      onDraftChange?.(value)
+    },
+    [controlledDraft, onDraftChange],
+  )
+
+  const canReply = onSubmit !== undefined
+  const canSubmit = draft.trim() !== '' && canReply
+
+  const submit = useCallback((attachmentIds?: readonly string[]) => {
+    const body = draft.trim()
+    if (body === '' || onSubmit === undefined) return
+    if (attachmentIds === undefined || attachmentIds.length === 0) onSubmit(body)
+    else onSubmit(body, undefined, attachmentIds)
+    setDraft('')
+  }, [draft, onSubmit, setDraft])
+
+  const isReplyingTo = useCallback(
+    (commentId: string) => replyingTo === commentId,
+    [replyingTo],
+  )
+
+  const startReply = useCallback((commentId: string) => {
+    setReplyingTo(commentId)
+    // A reply draft belongs to the comment it answers. Switching targets
+    // clears it rather than silently re-aiming half a sentence at someone else.
+    setReplyDraft('')
+  }, [])
+
+  const cancelReply = useCallback(() => {
+    setReplyingTo(null)
+    setReplyDraft('')
+  }, [])
+
+  const canSubmitReply =
+    replyingTo !== null && replyDraft.trim() !== '' && onSubmit !== undefined
+
+  const submitReply = useCallback((attachmentIds?: readonly string[]) => {
+    const body = replyDraft.trim()
+    if (body === '' || replyingTo === null || onSubmit === undefined) return
+    if (attachmentIds === undefined || attachmentIds.length === 0) onSubmit(body, replyingTo)
+    else onSubmit(body, replyingTo, attachmentIds)
+    setReplyDraft('')
+    setReplyingTo(null)
+  }, [replyDraft, replyingTo, onSubmit])
+
+  return {
+    now,
+    roots,
+    totalCount,
+    maxDepth,
+    repliesVisible,
+    engagement,
+    sort,
+    setSort,
+    isCollapsed,
+    setCollapsed,
+    toggleCollapse,
+    isRepliesExpanded,
+    expandReplies,
+    visibleReplies,
+    canReply,
+    draft,
+    setDraft,
+    canSubmit,
+    submit,
+    replyingTo,
+    isReplyingTo,
+    startReply,
+    cancelReply,
+    replyDraft,
+    setReplyDraft,
+    canSubmitReply,
+    submitReply,
+  }
+}

package/src/tokens.css

@@ -33,6 +33,14 @@
  *                  --destructive(-bg, -foreground)
  *     • Folder:    --folder-red/amber/emerald/teal/blue/violet/pink/
  *                  slate/ink (categorical palette for folder accents)
+ *     • Series:    --series-1…8 (categorical CHART palette; ADR-146 D2.
+ *                  theme-INDEPENDENT, and the SLOT ORDER IS LOAD-BEARING
+ *                  — see the block near the end of this file before
+ *                  "tidying" it)
+ *     • Chart:     --chart-grid, --chart-axis, --chart-band (chart
+ *                  structure — gridlines, the darker baseline rule, and
+ *                  the hover band; ADR-146 D3. Theme-tuned, and all
+ *                  three ALREADY CARRY ALPHA — never add a second one)
  *     • Spacing:   --space-1…12 (4 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48)
  *     • Radius:    --radius-xs/sm/md/lg/xl/2xl/full, --radius (legacy)
  *     • Motion:    --ease-out, --ease-spring, --ease-in-out,
@@ -188,6 +196,34 @@
 
   --border: 255 255 255 / 0.08;
   --border-strong: 255 255 255 / 0.14;
+
+  /* ============================================================
+     CHART STRUCTURE — PUBLIC, theme-tuned (ADR-146 D3).
+     The greys a chart needs that are NOT a card border, plus the
+     hover-band fill. This is the "structure is required, not banned"
+     layer of the data-display recipe (CLAUDE.md §2): gridlines and a
+     baseline are what make a plot legible, and deleting them is the
+     flat/floating defect, not a cleanup.
+
+     --chart-axis IS DELIBERATELY DARKER THAN --chart-grid. The
+     baseline rule must outrank the gridlines. Every chart in the
+     Metoric kit draws it that way (#111111 baseline vs #dfe1e6 grid)
+     and it is the single detail that does most for chart legibility.
+     It lives as its own token precisely so it cannot drift back to
+     "same grey as the grid".
+
+     ALL THREE ALREADY CARRY AN ALPHA — they composite onto whichever
+     panel they sit on, so the panel stays opaque and the structure
+     stays translucent. Consume as `rgb(var(--chart-grid))` and NEVER
+     as `rgb(var(--chart-grid) / 0.5)`: a second alpha expands to
+     `rgb(255 255 255 / 0.07 / 0.5)`, which is invalid CSS and is
+     SILENTLY DISCARDED. `__tests__/token-shape.test.ts` fails on
+     exactly that shape.
+     ============================================================ */
+  --chart-grid: 255 255 255 / 0.07;
+  --chart-axis: 255 255 255 / 0.22;
+  --chart-band: 255 255 255 / 0.05;
+
   /* Semantic — PUBLIC */
   --success: 16 185 129;
   --success-bg: 16 185 129 / 0.12;
@@ -527,6 +563,14 @@
 
   --border: 0 0 0 / 0.12;
   --border-strong: 0 0 0 / 0.20;
+
+  /* Chart structure — see the :root block for the reasoning. The same
+     two invariants hold in light: --chart-axis stays darker than
+     --chart-grid, and all three already carry their alpha. */
+  --chart-grid: 0 0 0 / 0.08;
+  --chart-axis: 0 0 0 / 0.24;
+  --chart-band: 0 0 0 / 0.04;
+
   /* Bumped from 0.16 → 0.22 — inputs on a white --bg-input (above) sitting
    * inside a Card (--bg-card = 255 / same as input) need a stronger border
    * to delineate. The 0.16 value worked when --bg-input was slate-tinted; on
@@ -813,3 +857,71 @@
   --media-on-scrim: 255 255 255 / 0.88;
   --media-overlay-btn: 255 255 255 / 0.14;
 }
+
+/* ============================================================
+   CATEGORICAL SERIES PALETTE (theme-INDEPENDENT) — PUBLIC
+   ------------------------------------------------------------
+   The chart series palette (ADR-146 D2). Hues carried over from
+   `theme-v2.css`, which designed them at constant lightness ~0.62
+   and then never shipped a consumer.
+
+   THEME-INDEPENDENT ON PURPOSE, and verified rather than assumed:
+   lightness 0.62 sits inside BOTH the light band (0.43-0.77) and the
+   dark band (0.48-0.67), and all eight clear 3:1 against #ffffff,
+   against --surface-frame (#f7f7f9) and against dark --surface-card
+   (#1b1b1e). Same precedent as --hierarchy-* and --platform-* above:
+   one block, no light/dark override.
+
+   BARE TRIPLES. The call site owns the alpha — a line is
+   `rgb(var(--series-1))` and the area under it is
+   `rgb(var(--series-1) / 0.12)`. A baked-in alpha would expand to
+   `rgb(2 137 234 / 0.3 / 0.12)`, which is invalid and silently
+   dropped, and it would make the token un-shareable between the two
+   uses.
+
+   ------------------------------------------------------------
+   THE SLOT ORDER IS LOAD-BEARING. DO NOT "TIDY" IT.
+   ------------------------------------------------------------
+   The order was chosen by measurement (the dataviz skill's
+   validate_palette.js, adjacent-pair list, both modes), not by eye.
+   The order declared in theme-v2.css FAILS — teal against pink is
+   ΔE 1.2 for a deuteranope. This order passes all five checks in
+   both themes: worst adjacent pair ΔE 13.2 deutan / 21.0 normal,
+   identical light and dark. Re-ordering the slots breaks that, and
+   nothing in the build will tell you.
+
+   Three placements are deliberate:
+     • BLUE IS SLOT 1, not red. Slot 1 is the single-series default,
+       so a red slot 1 would paint every one-series chart in the
+       brand accent and destroy accent scarcity. Blue carries no
+       product meaning.
+     • RED IS SLOT 8. Red is reserved for --accent and
+       --destructive. It only enters a chart at eight series, where
+       the reader has bigger problems. It stays in the palette so
+       the eight-slot contract holds rather than being deleted.
+     • GREEN (slot 2) AND RED (slot 8) ARE FAR APART, so a
+       two-series chart never accidentally reads as pass/fail.
+
+   THE SCATTER / ALL-PAIRS CAP. Forms where any two marks can touch
+   — scatter, bubble, choropleth, small multiples — take the harder
+   all-pairs test, which no ordering of these eight can pass. Those
+   forms use ONLY slots 1, 6 and 7 (blue / amber / teal: verified
+   all-pairs in both modes, worst ΔE 14.8, all five checks PASS) and
+   CAP AT THREE SERIES. A fourth folds into "Other" or facets into
+   small multiples. Never generate a ninth hue.
+
+   Resolution is a frozen literal lookup in the primitive, never a
+   constructed name (ADR-146 D8): `--series-${i}` that misses yields
+   an undefined property, which makes rgb() invalid, which the
+   browser discards in silence with every gate still green.
+   ============================================================ */
+:root {
+  --series-1: 2 137 234;    /* blue   */
+  --series-2: 9 160 93;     /* green  */
+  --series-3: 153 100 229;  /* violet */
+  --series-4: 113 149 3;    /* olive  */
+  --series-5: 212 73 150;   /* pink   */
+  --series-6: 186 116 4;    /* amber  */
+  --series-7: 14 154 148;   /* teal   */
+  --series-8: 226 74 62;    /* red    */
+}