@lovett/ui 0.0.10 → 0.1.0

package/src/detail/activity-pane.tsx

@@ -0,0 +1,507 @@
+/**
+ * ActivityPane — Everything · Comments · Activity, with one composer.
+ *
+ * `docs/design-briefs/tasks-item-detail-full.md` §5.
+ *
+ * ## The composer is pinned to the bottom of the pane on EVERY tab
+ *
+ * Including Activity, which is the instruction that decides the whole
+ * structure. `Thread` pins a root composer of its own at the foot of the
+ * comments list, so mounting it inside the Comments tab and a second one for
+ * the other tabs would put two composers on screen at once — and switching
+ * tabs would unmount whichever one you were typing in. So the composer lives
+ * OUTSIDE the tab panels, mounted once, and `Thread` is asked to draw no root
+ * composer (`rootComposer={false}`, added to that primitive for this). Replies
+ * still work: they are gated on `onReply`, not on the root composer.
+ *
+ * The three panels are all mounted and toggled with `hidden` for the same
+ * reason — a scroll position, an expanded reply and a half-read thread all
+ * survive a tab change, and `hidden` takes them out of the accessibility tree
+ * and the tab ring while they are away.
+ *
+ * ## It fetches nothing
+ *
+ * Comments and activity arrive as props, already shaped. §6 is explicit that
+ * the activity feed is written server-side in the same transaction as the
+ * change — never derived on the client — so this component has no business
+ * inferring history from an item, and does not.
+ *
+ * ## Everything is read-only
+ *
+ * The merged feed interleaves both by time so you can see what happened in
+ * order. Reacting, replying and collapsing live in Comments, where the thread
+ * is drawn in full — a feed that is half interactive and half not is worse
+ * than one that is honestly neither.
+ */
+
+import { useId, useMemo, useState, type ReactNode } from 'react'
+import { Tabs } from '../tabs'
+import { Avatar, asAvatarTint } from '../avatar'
+import { cn } from '../lib/utils'
+import { CommentBody } from '../thread/comment-body'
+import { RelativeTime } from '../thread/relative-time'
+import { Thread } from '../thread/thread'
+import { ThreadComposer } from '../thread/composer'
+import { useNowTick } from '../thread/use-now'
+import type { ThreadAuthor, ThreadComment } from '../thread/types'
+import type { ActivityEntry, FieldPerson } from './types'
+
+export type ActivityTab = 'everything' | 'comments' | 'activity'
+
+const TAB_ORDER: readonly ActivityTab[] = ['everything', 'comments', 'activity']
+
+/**
+ * The tabs a given pane actually shows.
+ *
+ * A host with no comment backend gets Everything and Activity, and Everything
+ * then means "the activity feed" rather than a merge of two sources — which is
+ * still true, just shorter. Dropping the tab rather than showing an empty
+ * Comments panel is the honest version: a tab that can never have content is a
+ * promise the product does not keep.
+ */
+function tabsFor(withComments: boolean): readonly ActivityTab[] {
+  return withComments ? TAB_ORDER : TAB_ORDER.filter((id) => id !== 'comments')
+}
+
+const TAB_LABEL: Readonly<Record<ActivityTab, string>> = {
+  everything: 'Everything',
+  comments: 'Comments',
+  activity: 'Activity',
+}
+
+/** In the interface's own voice: what this is, and what will appear here. */
+const DEFAULT_EMPTY: Readonly<Record<ActivityTab, string>> = {
+  everything: 'Nothing here yet. Comments and changes to this record show up together.',
+  comments: 'No comments yet. Start the conversation.',
+  activity: 'No activity yet. Every change to this record is recorded here.',
+}
+
+export interface ActivityPaneProps {
+  /** Controlled tab. Omit for internal state. */
+  tab?: ActivityTab | undefined
+  defaultTab?: ActivityTab | undefined
+  onTabChange?: ((next: ActivityTab) => void) | undefined
+
+  /**
+   * Already shaped. The pane fetches nothing.
+   *
+   * Omit it — along with the composer trio below — for a host that has no
+   * comment backend at all. The Comments tab is then not rendered, rather than
+   * rendered empty. See `tabsFor`.
+   */
+  comments?: readonly ThreadComment[] | undefined
+  /** Item history, in any order — the pane sorts by time. */
+  activity: readonly ActivityEntry[]
+
+  /**
+   * The composer's draft, controlled by the host so it survives a remount.
+   *
+   * The trio is all-or-nothing: supply `onSubmit` and you get a composer,
+   * omit it and the pane draws none. `onSubmit` is the one that decides,
+   * because a composer with nowhere to post is worse than no composer.
+   */
+  draft?: string | undefined
+  onDraftChange?: ((next: string) => void) | undefined
+  /** A new root comment. Omitted, the pane renders no composer. */
+  onSubmit?: ((body: string) => void) | undefined
+  /** A reply. Omitted, the thread offers no reply control at all. */
+  onReply?: ((body: string, parentId: string) => void) | undefined
+  sending?: boolean | undefined
+  composerAvatar?: ReactNode | undefined
+  composerPlaceholder?: string | undefined
+  composerLabel?: string | undefined
+  composerMaxLength?: number | undefined
+  submitLabel?: string | undefined
+
+  /** Frozen clock, epoch ms. Omit and the shared 60s ticker drives the times. */
+  now?: number | undefined
+  locale?: string | undefined
+  /** Override any tab's empty state. */
+  emptyStates?: Partial<Record<ActivityTab, ReactNode>> | undefined
+  className?: string | undefined
+}
+
+export function ActivityPane({
+  tab,
+  defaultTab = 'everything',
+  onTabChange,
+  comments = [],
+  activity,
+  draft = '',
+  onDraftChange,
+  onSubmit,
+  onReply,
+  sending = false,
+  composerAvatar,
+  composerPlaceholder = 'Add a comment…',
+  composerLabel = 'Add a comment',
+  composerMaxLength,
+  submitLabel = 'Comment',
+  now,
+  locale,
+  emptyStates,
+  className,
+}: ActivityPaneProps) {
+  const reactId = useId()
+  const [internalTab, setInternalTab] = useState<ActivityTab>(defaultTab)
+  const withComments = onSubmit !== undefined
+  const tabs = tabsFor(withComments)
+  const requested = tab ?? internalTab
+  // A host that drops Comments while it is the active tab (or that defaults to
+  // it) must not land on a panel that is not rendered.
+  const active = tabs.includes(requested) ? requested : (tabs[0] as ActivityTab)
+  const ticked = useNowTick(now === undefined)
+  const clock = now ?? ticked
+
+  const sortedActivity = useMemo(
+    () => [...activity].sort((a, b) => a.at - b.at),
+    [activity],
+  )
+
+  // Oldest first, so the newest sits nearest the composer.
+  const merged = useMemo(() => {
+    const entries: FeedEntry[] = [
+      ...comments.map((comment) => ({
+        kind: 'comment' as const,
+        at: comment.createdAt,
+        comment,
+      })),
+      ...sortedActivity.map((entry) => ({
+        kind: 'activity' as const,
+        at: entry.at,
+        entry,
+      })),
+    ]
+    return entries.sort((a, b) => a.at - b.at)
+  }, [comments, sortedActivity])
+
+  const empty = (id: ActivityTab): ReactNode => emptyStates?.[id] ?? DEFAULT_EMPTY[id]
+
+  // Tab -> panel wiring. The strip alone was a tablist whose tabs
+  // controlled nothing; each tab now points `aria-controls` at the panel it
+  // shows, and each panel is focusable so keyboard users can reach its
+  // scrolling content.
+  const idPrefix = `activity-${reactId.replace(/[^a-zA-Z0-9_-]/g, '')}`
+  const panelDomId = (id: ActivityTab) => `${idPrefix}-panel-${id}`
+
+  return (
+    <section
+      data-slot="activity-pane"
+      aria-label="Activity"
+      className={cn('flex min-h-0 flex-1 flex-col', className)}
+    >
+      {/*
+        Matched to the field-list header on the other side of the split, so
+        the two panes' first rows sit on one line: same `--space-2` block
+        padding, same bottom border, and a control the same 36px tall (the
+        segmented track is 26 + 4 + 4 + 1 + 1, the same as that header's
+        SegmentedChoice). Change one and change the other.
+      */}
+      <div
+        className="shrink-0 border-b"
+        style={{
+          paddingInline: 'var(--space-4)',
+          paddingBlock: 'var(--space-2)',
+          borderColor: 'rgb(var(--border))',
+        }}
+      >
+        <Tabs
+          size="sm"
+          variant="segmented"
+          stretch
+          idPrefix={idPrefix}
+          activeTabId={active}
+          onTabChange={(next) => {
+            const id = next as ActivityTab
+            if (tab === undefined) setInternalTab(id)
+            onTabChange?.(id)
+          }}
+          tabs={tabs.map((id) => ({
+            id,
+            label: TAB_LABEL[id],
+            panelId: panelDomId(id),
+            // A badge only when there is something to count. "Comments 0"
+            // says nothing the empty state does not, and in a segmented
+            // strip at the pane's 280px floor that zero is bought with the
+            // label — "Co… 0" instead of "Comments".
+            ...(id === 'comments' && comments.length > 0
+              ? { count: comments.length }
+              : {}),
+            ...(id === 'activity' && activity.length > 0
+              ? { count: activity.length }
+              : {}),
+          }))}
+        />
+      </div>
+
+      {/* EVERYTHING */}
+      <div
+        role="tabpanel"
+        id={panelDomId('everything')}
+        // Named by `aria-label`, not `aria-labelledby` back at the tab: two
+        // of the three tabs carry a count badge, so borrowing the tab's text
+        // would name the panel "Comments 3".
+        aria-label={TAB_LABEL.everything}
+        tabIndex={0}
+        hidden={active !== 'everything'}
+        className="flex min-h-0 flex-1 flex-col overflow-y-auto"
+        style={{ paddingInline: 'var(--space-4)', paddingBlock: 'var(--space-3)' }}
+      >
+        {merged.length === 0 ? (
+          <EmptyLine>{empty('everything')}</EmptyLine>
+        ) : (
+          <ol className="flex list-none flex-col" style={{ gap: 'var(--space-3)', margin: 0, padding: 0 }}>
+            {merged.map((item) =>
+              item.kind === 'comment' ? (
+                <li key={`comment-${item.comment.id}`}>
+                  <FeedLine
+                    author={item.comment.author ?? null}
+                    at={item.at}
+                    now={clock}
+                    locale={locale}
+                    body={
+                      item.comment.deletedAt === null || item.comment.deletedAt === undefined ? (
+                        <CommentBody bodyMd={item.comment.bodyMd} />
+                      ) : (
+                        <span style={{ color: 'rgb(var(--text-tertiary))' }}>
+                          Comment deleted
+                        </span>
+                      )
+                    }
+                    lead="commented"
+                  />
+                </li>
+              ) : (
+                <li key={`activity-${item.entry.id}`}>
+                  <ActivityLine entry={item.entry} now={clock} locale={locale} />
+                </li>
+              ),
+            )}
+          </ol>
+        )}
+      </div>
+
+      {/* COMMENTS — omitted entirely without a backend, not rendered empty. */}
+      {!withComments ? null : (
+      <div
+        role="tabpanel"
+        id={panelDomId('comments')}
+        // Named by `aria-label`, not `aria-labelledby` back at the tab: two
+        // of the three tabs carry a count badge, so borrowing the tab's text
+        // would name the panel "Comments 3".
+        aria-label={TAB_LABEL.comments}
+        tabIndex={0}
+        hidden={active !== 'comments'}
+        className="flex min-h-0 flex-1 flex-col"
+        style={{ paddingInline: 'var(--space-4)', paddingBlock: 'var(--space-3)' }}
+      >
+        <Thread
+          variant="bare"
+          rootComposer={false}
+          comments={comments}
+          emptyState={empty('comments')}
+          {...(now === undefined ? {} : { now })}
+          {...(locale === undefined ? {} : { locale })}
+          {...(onReply === undefined
+            ? {}
+            : {
+                onSubmit: (body: string, parentId?: string) => {
+                  // Root submissions come from the pinned composer below, so
+                  // anything arriving here without a parent is dropped rather
+                  // than posted twice.
+                  if (parentId !== undefined) onReply(body, parentId)
+                },
+              })}
+        />
+      </div>
+      )}
+
+      {/* ACTIVITY */}
+      <div
+        role="tabpanel"
+        id={panelDomId('activity')}
+        // Named by `aria-label`, not `aria-labelledby` back at the tab: two
+        // of the three tabs carry a count badge, so borrowing the tab's text
+        // would name the panel "Comments 3".
+        aria-label={TAB_LABEL.activity}
+        tabIndex={0}
+        hidden={active !== 'activity'}
+        className="flex min-h-0 flex-1 flex-col overflow-y-auto"
+        style={{ paddingInline: 'var(--space-4)', paddingBlock: 'var(--space-3)' }}
+      >
+        {sortedActivity.length === 0 ? (
+          <EmptyLine>{empty('activity')}</EmptyLine>
+        ) : (
+          <ol className="flex list-none flex-col" style={{ gap: 'var(--space-3)', margin: 0, padding: 0 }}>
+            {sortedActivity.map((entry) => (
+              <li key={entry.id}>
+                <ActivityLine entry={entry} now={clock} locale={locale} />
+              </li>
+            ))}
+          </ol>
+        )}
+      </div>
+
+      {/* THE COMPOSER — one, mounted once, below every panel. Absent when
+          there is nowhere to post to; a composer that discards what you typed
+          is worse than no composer. */}
+      {onSubmit === undefined ? null : (
+      <div
+        data-slot="activity-composer"
+        className="shrink-0 border-t"
+        style={{
+          borderColor: 'rgb(var(--border))',
+          paddingInline: 'var(--space-4)',
+          paddingBlock: 'var(--space-3)',
+        }}
+      >
+        <ThreadComposer
+          label={composerLabel}
+          placeholder={composerPlaceholder}
+          submitLabel={submitLabel}
+          value={draft}
+          onChange={onDraftChange ?? (() => {})}
+          onSubmit={() => {
+            const body = draft.trim()
+            if (body === '') return
+            onSubmit(body)
+          }}
+          sending={sending}
+          {...(composerAvatar === undefined ? {} : { avatar: composerAvatar })}
+          {...(composerMaxLength === undefined ? {} : { maxLength: composerMaxLength })}
+        />
+      </div>
+      )}
+    </section>
+  )
+}
+
+type FeedEntry =
+  | { kind: 'comment'; at: number; comment: ThreadComment }
+  | { kind: 'activity'; at: number; entry: ActivityEntry }
+
+function EmptyLine({ children }: { children: ReactNode }) {
+  return (
+    <p
+      className="text-[12.5px] leading-[1.5]"
+      style={{ margin: 0, color: 'rgb(var(--text-tertiary))' }}
+    >
+      {children}
+    </p>
+  )
+}
+
+/** Never fabricate a name (thread D5) — fall back through what exists. */
+function actorName(actor: FieldPerson | ThreadAuthor | null | undefined): string {
+  if (actor === null || actor === undefined) return 'Someone'
+  if ('name' in actor && typeof actor.name === 'string' && actor.name.length > 0) {
+    return actor.name
+  }
+  if ('email' in actor && typeof actor.email === 'string' && actor.email.length > 0) {
+    return actor.email
+  }
+  return 'Someone'
+}
+
+function FeedLine({
+  author,
+  at,
+  now,
+  locale,
+  lead,
+  body,
+}: {
+  author: FieldPerson | ThreadAuthor | null
+  at: number
+  now: number
+  locale?: string | undefined
+  lead: ReactNode
+  body?: ReactNode | undefined
+}) {
+  const tint = asAvatarTint(author?.tint)
+  const name = actorName(author)
+  return (
+    <div className="flex items-start" style={{ gap: 'var(--space-2)' }}>
+      <Avatar
+        name={author?.name ?? null}
+        size="sm"
+        src={author?.avatarUrl ?? null}
+        {...(author?.id === undefined || author.id === null ? {} : { seed: author.id })}
+        {...(tint === undefined ? {} : { tint })}
+      />
+      <div className="min-w-0 flex-1">
+        <p className="text-[12.5px] leading-[1.5]" style={{ margin: 0, color: 'rgb(var(--text-secondary))' }}>
+          <span className="font-semibold" style={{ color: 'rgb(var(--foreground))' }}>
+            {name}
+          </span>{' '}
+          {lead}{' '}
+          <RelativeTime value={at} now={now} locale={locale} />
+        </p>
+        {body === undefined ? null : (
+          <div className="text-[12.5px] leading-[1.55]" style={{ marginBlockStart: 'var(--space-1)' }}>
+            {body}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * `‹who› moved from ‹A› to ‹B› ‹when›` (§5), and the three degenerate cases
+ * the sentence has to cover — set, cleared, and a change the server described
+ * itself. Field names arrive user-facing ("Status"), never as schema words:
+ * §7's copy rule is a host responsibility this component cannot enforce, but
+ * it never invents one either.
+ */
+function ActivityLine({
+  entry,
+  now,
+  locale,
+}: {
+  entry: ActivityEntry
+  now: number
+  locale?: string | undefined
+}) {
+  const lead = ((): ReactNode => {
+    if (entry.summary !== undefined) return entry.summary
+    const { field, from, to } = entry
+    if (field === undefined) return 'updated this item'
+    const has = (value: string | null | undefined): value is string =>
+      typeof value === 'string' && value.length > 0
+    if (has(from) && has(to)) {
+      return (
+        <>
+          changed {field} from <Value>{from}</Value> to <Value>{to}</Value>
+        </>
+      )
+    }
+    if (has(to)) {
+      return (
+        <>
+          set {field} to <Value>{to}</Value>
+        </>
+      )
+    }
+    if (has(from)) return <>cleared {field}</>
+    return <>updated {field}</>
+  })()
+
+  return (
+    <FeedLine
+      author={entry.actor ?? null}
+      at={entry.at}
+      now={now}
+      locale={locale}
+      lead={lead}
+    />
+  )
+}
+
+function Value({ children }: { children: ReactNode }) {
+  return (
+    <span className="font-medium" style={{ color: 'rgb(var(--foreground))' }}>
+      {children}
+    </span>
+  )
+}