basalt-ui 1.11.0 → 1.13.0

package/src/agent-chat/message-affordances.ts

@@ -0,0 +1,61 @@
+/**
+ * MessageAffordances — the per-message hover-row/action contract shared by `ThreadTranscript` and
+ * a virtualized `ThreadFeedRow` (both render `MessageBlock`, so the affordance surface lives here
+ * rather than being redeclared on each consumer).
+ *
+ * Type-only module — the rendering (the actual hover row, copy button, regenerate button) lives in
+ * `thread-message.tsx`. `MessageAffordances` itself IS public (re-exported, type-only, from the
+ * agent-chat barrel and the root): it is named in `ThreadTranscriptProps.affordances` and
+ * `ThreadFeedRowProps.affordances`, so a consumer has to be able to name it. `DEFAULT_AFFORDANCES`
+ * stays internal — resolving unset fields is the components' job, not the consumer's.
+ */
+import type { ReactNode } from 'react'
+import type { ChatMessage, TranscriptPart } from '../agent'
+
+export type MessageAffordances = {
+  /**
+   * How the per-message timestamp renders.
+   * @default 'relative'
+   */
+  readonly timestamp?: 'relative' | 'absolute' | 'none'
+  /**
+   * Whether a copy action is offered on the hover row. Copies the message's COALESCED text (the
+   * same merged/de-duplicated text `coalesceParts` produces for display), not the raw `parts`
+   * array — a message can accumulate multiple adjacent/by-id text parts while streaming, and
+   * copying the raw parts would either duplicate text or copy fragments the user never saw
+   * assembled.
+   * @default true
+   */
+  readonly copy?: boolean
+  /**
+   * Regenerate action, shown on the LAST ASSISTANT message only (never on earlier turns, never on
+   * user messages). Receives that message's `id`. `useAgentThreadRuns`'s `retry` is
+   * THREAD-keyed (`retry: (threadId: string) => void`), replaying the last user input for the
+   * whole thread — the consumer bridges this messageId-keyed callback to that thread-keyed retry;
+   * the framework only ever hands back the messageId, it does not know about threads.
+   */
+  readonly onRegenerate?: (messageId: string) => void
+  /**
+   * Extra actions appended to the hover row, after the built-in copy/regenerate actions.
+   *
+   * This is a RENDER prop, not an event handler — it is called during render, once per message,
+   * and its return value is rendered. That means it is treated differently from `onRegenerate`:
+   * `onRegenerate` is identity-stabilized internally (a fresh inline literal every render costs
+   * nothing), while `actions` is compared by REFERENCE, because its reference is the only signal
+   * that its output may have changed. A fresh inline `actions={() => …}` literal therefore
+   * re-renders every message block on every render of the transcript. That is correct — an action
+   * whose output depends on consumer state (a pin/star toggle) must be allowed to update — but on
+   * a long thread it is worth avoiding: wrap `actions` in the consumer's own `useCallback`, keyed
+   * on whatever state it actually reads.
+   */
+  readonly actions?: (ctx: { readonly message: ChatMessage<TranscriptPart> }) => ReactNode
+}
+
+/**
+ * Resolved defaults for the optional {@link MessageAffordances} fields — one place, so
+ * `ThreadTranscript` and a virtualized `ThreadFeedRow` cannot drift on what "unset" means.
+ */
+export const DEFAULT_AFFORDANCES: Required<Pick<MessageAffordances, 'timestamp' | 'copy'>> = {
+  timestamp: 'relative',
+  copy: true,
+}

package/src/agent-chat/relative-time.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test'
+import { formatRelativeTime } from './relative-time'
+
+// Unit boundaries (ms) mirrored from relative-time.ts — kept in sync deliberately rather than
+// importing the private table, so a drift between the two shows up as a test failure.
+const YEAR_MS = 31_536_000_000
+const MONTH_MS = 2_628_000_000
+const WEEK_MS = 604_800_000
+const DAY_MS = 86_400_000
+const HOUR_MS = 3_600_000
+const MINUTE_MS = 60_000
+
+describe('formatRelativeTime', () => {
+  test('sub-minute past → "just now"', () => {
+    expect(formatRelativeTime(Date.now() - 1)).toBe('just now')
+    expect(formatRelativeTime(Date.now() - 30_000)).toBe('just now')
+    expect(formatRelativeTime(Date.now() - (MINUTE_MS - 1_000))).toBe('just now')
+  })
+
+  test('sub-minute future → "just now" (the threshold is symmetric on |diff|)', () => {
+    expect(formatRelativeTime(Date.now() + 1)).toBe('just now')
+    expect(formatRelativeTime(Date.now() + (MINUTE_MS - 1))).toBe('just now')
+  })
+
+  test('minute boundary', () => {
+    expect(formatRelativeTime(Date.now() - MINUTE_MS)).toBe('1 minute ago')
+  })
+
+  test('hour boundary', () => {
+    expect(formatRelativeTime(Date.now() - HOUR_MS)).toBe('1 hour ago')
+  })
+
+  test('day boundary', () => {
+    expect(formatRelativeTime(Date.now() - DAY_MS)).toBe('yesterday')
+  })
+
+  test('week boundary', () => {
+    expect(formatRelativeTime(Date.now() - WEEK_MS)).toBe('last week')
+  })
+
+  test('month boundary', () => {
+    expect(formatRelativeTime(Date.now() - MONTH_MS)).toBe('last month')
+  })
+
+  test('year boundary', () => {
+    expect(formatRelativeTime(Date.now() - YEAR_MS)).toBe('last year')
+  })
+
+  test('future timestamp: the function handles negative diffMs (diff = timestamp - Date.now())', () => {
+    // diffMs is positive here (timestamp is ahead of "now"), so Math.round(diffMs / unit.ms) is
+    // positive too, and Intl.RelativeTimeFormat's 'auto' numeric mode renders the "in X" / "next
+    // X" / "tomorrow" forms rather than the "X ago" / "last X" forms used for the past.
+    expect(formatRelativeTime(Date.now() + HOUR_MS)).toBe('in 1 hour')
+    expect(formatRelativeTime(Date.now() + DAY_MS)).toBe('tomorrow')
+    expect(formatRelativeTime(Date.now() + WEEK_MS)).toBe('next week')
+  })
+
+  test('non-finite/wrong-type inputs degrade to empty string instead of throwing', () => {
+    // Intl.RelativeTimeFormat.format throws a RangeError on any of these. The pre-fix code called
+    // it unguarded, so each of the following would have thrown out of formatRelativeTime — except
+    // `null`, which coerces to 0 via `timestamp - Date.now()` and produced a nonsense-but-non-
+    // throwing "X years ago" string. The guard now normalizes all six to the same '' result.
+    expect(formatRelativeTime(NaN)).toBe('')
+    expect(formatRelativeTime(Infinity)).toBe('')
+    expect(formatRelativeTime(-Infinity)).toBe('')
+    // @ts-expect-error — runtime type violation (undefined at a `number`-typed call site), the exact
+    // shape a `ThreadsStoreAdapter` bug or corrupted localStorage JSON would produce.
+    expect(formatRelativeTime(undefined)).toBe('')
+    // @ts-expect-error — runtime type violation (ISO string), the single most likely real-world
+    // adapter mistake (a server returning `created_at` as a string).
+    expect(formatRelativeTime('2024-01-01T00:00:00Z')).toBe('')
+    // @ts-expect-error — runtime type violation (null); previously coerced to 0 rather than
+    // throwing, now normalized to the same '' as every other non-finite input.
+    expect(formatRelativeTime(null)).toBe('')
+  })
+
+  test('finite-but-absurd timestamps still format instead of throwing', () => {
+    // Number.isFinite is true for both, so these fall through the new guard unchanged — the guard
+    // must not over-trigger on merely-extreme (but valid) input.
+    expect(() => formatRelativeTime(8_640_000_000_000_000)).not.toThrow() // year 275760, JS Date max
+    expect(() => formatRelativeTime(-8_640_000_000_000_000)).not.toThrow() // symmetric min
+    expect(() => formatRelativeTime(-1_000_000_000_000)).not.toThrow() // pre-1970 epoch
+  })
+
+  test('"at(-1)!" fallback path — documented as effectively unreachable', () => {
+    // RELATIVE_TIME_UNITS.find(...) ?? RELATIVE_TIME_UNITS.at(-1)! only falls through to the
+    // fallback when .find returns undefined. The array's last (smallest) entry is 'minute' at
+    // 60_000ms, exactly the threshold the "just now" early-return already guards below — so for
+    // every absMs that reaches the .find call (absMs >= 60_000), 'minute' itself always matches
+    // first-or-later, and the ?? branch is defensive dead code under the current threshold table.
+    // This test exercises the boundary that the fallback would produce if it were ever reachable
+    // (it currently is not, verified by construction): the same 'minute' unit as the last table row.
+    expect(formatRelativeTime(Date.now() - MINUTE_MS)).toBe('1 minute ago')
+  })
+})

package/src/agent-chat/relative-time.ts

@@ -0,0 +1,55 @@
+/**
+ * formatRelativeTime — dependency-free relative-time formatting (no date-fns).
+ *
+ * Shared between `ThreadOutcomeCard` (inbox row timestamps) and `ThreadTranscript` (per-message
+ * timestamps). 'en'-hardcoded for now — see the module-level note below for the deferred locale
+ * seam.
+ *
+ * Internal to `agent-chat/` — not part of the public barrel.
+ */
+
+const RELATIVE_TIME_FORMAT = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
+
+const RELATIVE_TIME_UNITS: readonly {
+  readonly unit: Intl.RelativeTimeFormatUnit
+  readonly ms: number
+}[] = [
+  { unit: 'year', ms: 31_536_000_000 },
+  { unit: 'month', ms: 2_628_000_000 },
+  { unit: 'week', ms: 604_800_000 },
+  { unit: 'day', ms: 86_400_000 },
+  { unit: 'hour', ms: 3_600_000 },
+  { unit: 'minute', ms: 60_000 },
+]
+
+/**
+ * Formats an epoch-ms timestamp as a short relative string ("3 hours ago", "just now").
+ *
+ * A non-finite `timestamp` — `NaN`, `±Infinity`, or a non-number value that slipped past the
+ * `ChatMessage.createdAt: number` type at runtime (an ISO string or `undefined`/`null` from a
+ * hand-rolled `ThreadsStoreAdapter`, or from JSON-deserialized `localStorage` state) renders as an
+ * empty string rather than reaching `Intl.RelativeTimeFormat.format`, which throws a `RangeError`
+ * on any non-finite input. This is render-path code — one bad `createdAt` on one message must not
+ * blank the whole transcript (the standing rule `spliceText`/`coalesceParts` already hold) — so it
+ * degrades instead of throwing, and warns in dev, matching `mergePart`'s clamp-and-warn precedent
+ * (`clampOffset` in `../agent/merge.ts`). The warning is NOT deduplicated, also matching that
+ * precedent — but note the call sites differ: `clampOffset` runs once per wire event, whereas this
+ * runs during render, once per message, so a single bad `createdAt` in a long transcript warns
+ * once per message per render. That is loud on purpose (a `createdAt` that isn't a number is an
+ * adapter bug worth fixing, not worth muting), and it costs nothing in production.
+ */
+export function formatRelativeTime(timestamp: number): string {
+  if (!Number.isFinite(timestamp)) {
+    if (process.env['NODE_ENV'] !== 'production') {
+      console.warn(
+        `[basalt] formatRelativeTime: non-finite timestamp ${String(timestamp)} — rendering empty string`,
+      )
+    }
+    return ''
+  }
+  const diffMs = timestamp - Date.now()
+  const absMs = Math.abs(diffMs)
+  if (absMs < 60_000) return 'just now'
+  const unit = RELATIVE_TIME_UNITS.find(({ ms }) => absMs >= ms) ?? RELATIVE_TIME_UNITS.at(-1)!
+  return RELATIVE_TIME_FORMAT.format(Math.round(diffMs / unit.ms), unit.unit)
+}

package/src/agent-chat/thread-detail-panel.tsx

@@ -167,7 +167,9 @@ export function ThreadDetailPanel({
       <Divider color="var(--vx-divider)" />
       <Box p="sm">
         <Stack gap="xs">
-          <Composer onSubmit={onSend} disabled={streaming} />
+          {/* `onSend` stays a plain string at this component's public seam — the payload shape is
+              unwrapped here rather than pushed onto every caller. */}
+          <Composer onSubmit={({ text }) => onSend(text)} streaming={streaming} />
           {streaming && (
             <Button size="compact-sm" variant="subtle" color="red" onClick={onStop}>
               Stop