basalt-ui 1.26.0 → 1.28.0

package/src/agent/part-list.tsx

@@ -27,6 +27,7 @@
  */
 import { Fragment, useMemo } from 'react'
 import type { JSX } from 'react'
+import { assertRequiredProps } from '../common/validate'
 import { assertNever } from '../register'
 import { alpha, VX } from '../tokens'
 import type {
@@ -285,6 +286,7 @@ export function PartList<TPart extends AgentPart = AgentPart>({
   components,
   settled = true,
 }: PartListProps<TPart>): JSX.Element {
+  assertRequiredProps('PartList', { parts }, ['parts'])
   // Memoised to avoid rebuilding the renderer map on every streaming re-render (hot path).
   // Cast required because DEFAULT_RENDERERS is typed for the base AgentPart, not the generic TPart.
   const renderers = useMemo(

package/src/agent/stick-to-bottom.tsx

@@ -26,14 +26,13 @@
  */
 import { lazy, Suspense } from 'react'
 import type { CSSProperties, JSX, ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
 import { VX } from '../tokens'
 
 // ── Lazy-loaded StickToBottom ─────────────────────────────────────────────────
 
-type WrapperProps = {
+type WrapperProps = BasaltProps & {
   children: ReactNode
-  className?: string
-  style?: CSSProperties
 }
 
 /** Plain scrollable container rendered when use-stick-to-bottom peer is absent. */
@@ -110,15 +109,12 @@ const LazyStickToBottom = lazy(() =>
     })
     .catch(() => ({ default: PlainContainerFallback })),
 )
+Object.assign(LazyStickToBottom, { displayName: 'LazyStickToBottom' })
 
 // ── BasaltStickToBottom ───────────────────────────────────────────────────────
 
-export type BasaltStickToBottomProps = {
+export type BasaltStickToBottomProps = BasaltProps & {
   readonly children: ReactNode
-  /** Applied to the scroll content container. */
-  readonly className?: string
-  /** Applied to the outer StickToBottom element. */
-  readonly style?: CSSProperties
 }
 
 /**
@@ -143,9 +139,11 @@ export function BasaltStickToBottom({
   if (className !== undefined) fallbackProps.className = className
   if (style !== undefined) fallbackProps.style = style
 
-  const lazyProps: WrapperProps = { children }
-  if (className !== undefined) lazyProps.className = className
-  if (style !== undefined) lazyProps.style = style
+  const lazyProps: WrapperProps = {
+    children,
+    ...(className !== undefined && { className }),
+    ...(style !== undefined && { style }),
+  }
 
   return (
     <Suspense fallback={<div {...fallbackProps}>{children}</div>}>

package/src/agent-chat/composer.tsx

@@ -39,6 +39,8 @@
 import { ActionIcon, Group, Kbd, Stack, Text, Textarea } from '@mantine/core'
 import type { ClipboardEvent, ComponentProps, JSX, KeyboardEvent, ReactNode, Ref } from 'react'
 import { useImperativeHandle, useLayoutEffect, useRef, useSyncExternalStore } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { readPersistedValue } from '../state'
 import { VX } from '../tokens'
 
@@ -257,78 +259,83 @@ function liveSelection(el: HTMLTextAreaElement): { start: number; end: number }
   return { start: selectionStart, end: selectionEnd }
 }
 
-export type ComposerProps = {
-  /** Imperative write/focus handle — see `ComposerHandle`. */
-  readonly ref?: Ref<ComposerHandle>
-  /**
-   * Called with the trimmed text plus the pending attachments. May return `void` (fire-and-forget,
-   * validated only synchronously) or a `Promise<void>` (its outcome is awaited, its timing is not).
-   *
-   * The draft and attachments clear OPTIMISTICALLY, immediately, before this settles — a chat
-   * composer has to feel instant, so Composer never sits on the typed text for a round trip.
-   * Rejecting restores them instead:
-   *   - THROW synchronously to refuse a send outright (bad input, offline, …) — the clear never
-   *     runs, exactly as before this prop went async.
-   *   - Return a promise that REJECTS to report a failure discovered later (a network error) — the
-   *     text and attachments are put back, UNLESS something has since made that unsafe:
-   *       - the user already typed something new into the (now-empty) box — their new text wins;
-   *         the failed one is not restored (surface a retry via the failed message instead);
-   *       - a LATER submit has already gone through this same draft — that one's own optimistic
-   *         clear (whether it went on to succeed or fail) wins over restoring this older one;
-   *       - the attachments are no longer empty (the caller already put something else there), or
-   *         `draftKey` has since changed (this Composer now points at a different thread/consumer
-   *         destination) — either way the attachments are left as they are rather than risking a
-   *         leak into whatever is current now.
-   * A resolved promise clears and stays cleared, same as a `void` return.
-   */
-  readonly onSubmit: (payload: ComposerSubmit) => void | Promise<void>
-  readonly placeholder?: string
-  /** Autofocuses the textarea on mount. */
-  readonly autoFocus?: boolean
-  /** Autosize ceiling for the textarea. Default 6. */
-  readonly maxRows?: number
-  /** Hard-disable, independent of streaming (e.g. offline). */
-  readonly disabled?: boolean
-  /** A run is in flight on this thread. */
-  readonly streaming?: boolean
-  /** Default false — preserves the historical `disabled={streaming}` behaviour. */
-  readonly allowSubmitWhileStreaming?: boolean
-  /** When given, the send action becomes a Stop action while `streaming`. */
-  readonly onStop?: () => void
-  /**
-   * Opaque slot rendered before the textarea (a voice recorder, a mode switch, …). Slot content
-   * that needs to WRITE into the composer — append a transcript, insert a suggestion — does so
-   * through the `ref` handle (`ComposerHandle`), not a callback prop here; see the file's
-   * `@example`.
-   */
-  readonly leftSection?: ReactNode
-  /** Opaque slot rendered between the textarea and the send action (an attach button, …). */
-  readonly rightSection?: ReactNode
-  /**
-   * Pending attachments, owned by the caller. Composer only forwards them on submit and asks for a
-   * reset afterwards — rendering previews is the caller's job, via `leftSection`/`rightSection`.
-   */
-  readonly attachments?: readonly ComposerAttachment[]
-  /**
-   * Called with `[]` optimistically the instant a submit goes out WITH pending attachments — a
-   * submit that had none to begin with skips the call rather than reporting a no-op change — and,
-   * subject to the restoration guards documented on `onSubmit`, with the original attachments
-   * again if that submit later rejects.
-   */
-  readonly onAttachmentsChange?: (next: readonly ComposerAttachment[]) => void
-  readonly onPaste?: (event: ClipboardEvent<HTMLTextAreaElement>) => void
-  /**
-   * Persists the unsent draft under `basalt:composer-draft:<key>`; switching keys swaps drafts, and
-   * the entry is removed (not blanked) on a successful submit.
-   *
-   * "Successful" means `onSubmit` returned (or resolved) without throwing or rejecting — a send
-   * that fails, synchronously or later over the network, restores this persisted draft instead of
-   * leaving it erased (subject to the restoration guards documented on `onSubmit`).
-   */
-  readonly draftKey?: string
-  /** Replaces the whole Enter/Shift+Enter hint row. Pass `null` to drop it entirely. */
-  readonly hint?: ReactNode
-}
+/** The three boxes `Composer` paints: `root` is the outer stack, `input` is the `Textarea`,
+ * `actions` is the Stop/Send action-button group. */
+export type ComposerSlot = 'root' | 'input' | 'actions'
+
+export type ComposerProps = BasaltProps &
+  SlotStylesProps<ComposerSlot> & {
+    /** Imperative write/focus handle — see `ComposerHandle`. */
+    readonly ref?: Ref<ComposerHandle>
+    /**
+     * Called with the trimmed text plus the pending attachments. May return `void` (fire-and-forget,
+     * validated only synchronously) or a `Promise<void>` (its outcome is awaited, its timing is not).
+     *
+     * The draft and attachments clear OPTIMISTICALLY, immediately, before this settles — a chat
+     * composer has to feel instant, so Composer never sits on the typed text for a round trip.
+     * Rejecting restores them instead:
+     *   - THROW synchronously to refuse a send outright (bad input, offline, …) — the clear never
+     *     runs, exactly as before this prop went async.
+     *   - Return a promise that REJECTS to report a failure discovered later (a network error) — the
+     *     text and attachments are put back, UNLESS something has since made that unsafe:
+     *       - the user already typed something new into the (now-empty) box — their new text wins;
+     *         the failed one is not restored (surface a retry via the failed message instead);
+     *       - a LATER submit has already gone through this same draft — that one's own optimistic
+     *         clear (whether it went on to succeed or fail) wins over restoring this older one;
+     *       - the attachments are no longer empty (the caller already put something else there), or
+     *         `draftKey` has since changed (this Composer now points at a different thread/consumer
+     *         destination) — either way the attachments are left as they are rather than risking a
+     *         leak into whatever is current now.
+     * A resolved promise clears and stays cleared, same as a `void` return.
+     */
+    readonly onSubmit: (payload: ComposerSubmit) => void | Promise<void>
+    readonly placeholder?: string
+    /** Autofocuses the textarea on mount. */
+    readonly autoFocus?: boolean
+    /** Autosize ceiling for the textarea. Default 6. */
+    readonly maxRows?: number
+    /** Hard-disable, independent of streaming (e.g. offline). */
+    readonly disabled?: boolean
+    /** A run is in flight on this thread. */
+    readonly streaming?: boolean
+    /** Default false — preserves the historical `disabled={streaming}` behaviour. */
+    readonly allowSubmitWhileStreaming?: boolean
+    /** When given, the send action becomes a Stop action while `streaming`. */
+    readonly onStop?: () => void
+    /**
+     * Opaque slot rendered before the textarea (a voice recorder, a mode switch, …). Slot content
+     * that needs to WRITE into the composer — append a transcript, insert a suggestion — does so
+     * through the `ref` handle (`ComposerHandle`), not a callback prop here; see the file's
+     * `@example`.
+     */
+    readonly leftSection?: ReactNode
+    /** Opaque slot rendered between the textarea and the send action (an attach button, …). */
+    readonly rightSection?: ReactNode
+    /**
+     * Pending attachments, owned by the caller. Composer only forwards them on submit and asks for a
+     * reset afterwards — rendering previews is the caller's job, via `leftSection`/`rightSection`.
+     */
+    readonly attachments?: readonly ComposerAttachment[]
+    /**
+     * Called with `[]` optimistically the instant a submit goes out WITH pending attachments — a
+     * submit that had none to begin with skips the call rather than reporting a no-op change — and,
+     * subject to the restoration guards documented on `onSubmit`, with the original attachments
+     * again if that submit later rejects.
+     */
+    readonly onAttachmentsChange?: (next: readonly ComposerAttachment[]) => void
+    readonly onPaste?: (event: ClipboardEvent<HTMLTextAreaElement>) => void
+    /**
+     * Persists the unsent draft under `basalt:composer-draft:<key>`; switching keys swaps drafts, and
+     * the entry is removed (not blanked) on a successful submit.
+     *
+     * "Successful" means `onSubmit` returned (or resolved) without throwing or rejecting — a send
+     * that fails, synchronously or later over the network, restores this persisted draft instead of
+     * leaving it erased (subject to the restoration guards documented on `onSubmit`).
+     */
+    readonly draftKey?: string
+    /** Replaces the whole Enter/Shift+Enter hint row. Pass `null` to drop it entirely. */
+    readonly hint?: ReactNode
+  }
 
 /** The default footer: the Enter / Shift+Enter keyboard contract, in the mono micro-label voice. */
 function DefaultHint(): JSX.Element {
@@ -374,6 +381,9 @@ export function Composer({
   onPaste,
   draftKey,
   hint,
+  className,
+  style,
+  classNames,
 }: ComposerProps): JSX.Element {
   // Per-instance fallback for the un-keyed case, so two keyless Composers never share a draft.
   // A lazily-initialised ref rather than `useState` — this is a create-once value React never
@@ -557,43 +567,54 @@ export function Composer({
   if (placeholder !== undefined) textareaProps.placeholder = placeholder
   if (autoFocus !== undefined) textareaProps.autoFocus = autoFocus
   if (onPaste !== undefined) textareaProps.onPaste = onPaste
+  if (classNames?.input !== undefined) textareaProps.className = cx(classNames.input)
+
+  const showActions = showStop || showSend
 
   return (
-    <Stack gap={6}>
+    <Stack
+      gap={6}
+      className={cx(classNames?.root, className)}
+      {...(style !== undefined && { style })}
+    >
       <Group gap="xs" align="flex-end" wrap="nowrap">
         {leftSection}
         <Textarea {...textareaProps} ref={textareaRef} />
         {rightSection}
-        {showStop ? (
-          <ActionIcon
-            size={42}
-            radius="md"
-            variant="filled"
-            color="red"
-            onClick={onStop}
-            aria-label="Stop generating"
-          >
-            <StopGlyph />
-          </ActionIcon>
-        ) : null}
-        {showSend ? (
-          <ActionIcon
-            size={42}
-            radius="md"
-            variant="filled"
-            onClick={submit}
-            disabled={inputDisabled || !hasPayload}
-            aria-label="Send message"
-            // Send action (docs/DESIGN-SPEC.md §5): the one accent-filled control. It needs no color
-            // override — `filled` resolves through the theme to `--vx-accent-fill` / `--vx-on-accent`.
-            // (It used to hand-wire those two vars inline, which is why this was the ONLY filled
-            // control that stayed legible while the rest of the chrome went through Mantine's
-            // scheme-blind autoContrast. The theme owns it now, and hover works again — an inline
-            // style can't express a `:hover` state.)
-          >
-            <SendGlyph />
-          </ActionIcon>
-        ) : null}
+        {showActions && (
+          <Group gap="xs" wrap="nowrap" className={cx(classNames?.actions)}>
+            {showStop ? (
+              <ActionIcon
+                size={42}
+                radius="md"
+                variant="filled"
+                color="red"
+                onClick={onStop}
+                aria-label="Stop generating"
+              >
+                <StopGlyph />
+              </ActionIcon>
+            ) : null}
+            {showSend ? (
+              <ActionIcon
+                size={42}
+                radius="md"
+                variant="filled"
+                onClick={submit}
+                disabled={inputDisabled || !hasPayload}
+                aria-label="Send message"
+                // Send action (docs/DESIGN-SPEC.md §5): the one accent-filled control. It needs no
+                // color override — `filled` resolves through the theme to `--vx-accent-fill` /
+                // `--vx-on-accent`. (It used to hand-wire those two vars inline, which is why this
+                // was the ONLY filled control that stayed legible while the rest of the chrome went
+                // through Mantine's scheme-blind autoContrast. The theme owns it now, and hover
+                // works again — an inline style can't express a `:hover` state.)
+              >
+                <SendGlyph />
+              </ActionIcon>
+            ) : null}
+          </Group>
+        )}
       </Group>
       {hint === undefined ? <DefaultHint /> : hint}
     </Stack>

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

@@ -7,6 +7,7 @@
  *
  * Internal to `agent-chat/` — not part of the public barrel.
  */
+import { isDev } from '../utils/is-dev'
 
 const RELATIVE_TIME_FORMAT = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
 
@@ -40,7 +41,7 @@ const RELATIVE_TIME_UNITS: readonly {
  */
 export function formatRelativeTime(timestamp: number): string {
   if (!Number.isFinite(timestamp)) {
-    if (process.env['NODE_ENV'] !== 'production') {
+    if (isDev()) {
       console.warn(
         `[basalt] formatRelativeTime: non-finite timestamp ${String(timestamp)} — rendering empty string`,
       )

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

@@ -26,6 +26,8 @@ import { motion } from 'motion/react'
 import type { JSX } from 'react'
 import type { AgentPart, AgentThread, StreamStatus } from '../agent'
 import { BasaltStickToBottom } from '../agent'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
 import { MOTION_SPRING } from '../motion'
 import { Composer } from './composer'
 import { ThreadTranscript } from './thread-message'
@@ -45,9 +47,9 @@ function CloseGlyph(): JSX.Element {
   )
 }
 
-function EmptyPanel(): JSX.Element {
+function EmptyPanel({ className, style }: BasaltProps): JSX.Element {
   return (
-    <Box p="xl" style={{ height: '100%' }}>
+    <Box p="xl" className={cx(className)} style={{ height: '100%', ...style }}>
       <Stack align="center" justify="center" gap={4} h="100%">
         <Text fw={550} style={{ fontFamily: 'var(--basalt-font-head)', fontStretch: '88%' }}>
           No thread selected
@@ -73,7 +75,7 @@ function threadLabel(thread: AgentThread): string {
   return text.length > 0 ? text : 'Untitled'
 }
 
-export type ThreadDetailPanelProps = {
+export type ThreadDetailPanelProps = BasaltProps & {
   /** The open thread, or null when nothing is selected (renders an empty-state hint). */
   readonly thread: AgentThread | null
   /** The live (in-flight) assistant turn's parts for this thread, if a run is streaming. */
@@ -105,15 +107,17 @@ export function ThreadDetailPanel({
   onStop,
   onClose,
   onRetry,
+  className,
+  style,
 }: ThreadDetailPanelProps): JSX.Element {
   const reduceMotion = useReducedMotion()
 
-  if (thread === null) return <EmptyPanel />
+  if (thread === null) return <EmptyPanel className={className} style={style} />
 
   const streaming = runStatus === 'streaming'
 
   const panel = (
-    <Flex direction="column" h="100%">
+    <Flex direction="column" h="100%" className={cx(className)} style={style}>
       <Flex p="sm" align="center" justify="space-between">
         <Text
           fw={550}

package/src/agent-chat/thread-feed-row.tsx

@@ -43,6 +43,9 @@ import type {
   StreamStatus,
   TranscriptPart,
 } from '../agent'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import { VX } from '../tokens'
 import type { ComposerProps, ComposerSubmit } from './composer'
 import { Composer } from './composer'
@@ -79,6 +82,15 @@ function ChevronGlyph({ expanded }: { expanded: boolean }): JSX.Element {
   )
 }
 
+// Card idiom (docs/DESIGN-SPEC.md §5) — static across every row, so it stays a module-level
+// constant rather than a per-render literal, letting the no-override case keep a stable reference.
+const CARD_STYLE = {
+  borderRadius: VX.radiusCard,
+  boxShadow: VX.shadowCard,
+  backgroundColor: VX.surface.panel,
+  overflow: 'hidden',
+} as const
+
 type ThreadFeedRowBase = {
   /**
    * The thread this row projects. Typed against `AgentThread<TranscriptPart>` — not the plain,
@@ -128,7 +140,7 @@ type ThreadFeedRowBase = {
  * of the body growing to the thread's full length). Omit both and the row's transcript is
  * content-sized, as before.
  */
-export type ThreadFeedRowProps = ThreadFeedRowBase & VirtualizeProps
+export type ThreadFeedRowProps = ThreadFeedRowBase & VirtualizeProps & BasaltProps
 
 /** The row header's title: the resolved outcome title, else a plain placeholder — this row never
  * falls back to scanning the first user message the way `ThreadOutcomeCard`'s `promptOf` does,
@@ -159,7 +171,10 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
     onSend,
     onStop,
     composerProps,
+    className,
+    style,
   } = props
+  assertRequiredProps('ThreadFeedRow', { thread }, ['thread'])
 
   // Resolved through the shared narrowing point rather than by destructuring `virtualize`/`height`
   // apart — see `resolveVirtualize`'s doc for why the two must be read together.
@@ -191,14 +206,7 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
   const streaming = liveStatus === 'streaming'
 
   return (
-    <Box
-      style={{
-        borderRadius: VX.radiusCard,
-        boxShadow: VX.shadowCard,
-        backgroundColor: VX.surface.panel,
-        overflow: 'hidden',
-      }}
-    >
+    <Box className={cx(className)} style={style ? { ...CARD_STYLE, ...style } : CARD_STYLE}>
       <UnstyledButton
         onClick={() => onToggle(thread.id)}
         w="100%"

package/src/agent-chat/thread-feed.tsx

@@ -23,6 +23,9 @@ import { AnimatePresence, motion } from 'motion/react'
 import type { JSX, ReactNode } from 'react'
 import { useEffect, useState } from 'react'
 import type { AgentThread } from '../agent'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import { MOTION_SPRING } from '../motion'
 import type { ComposerSubmit } from './composer'
 import { ThreadFeedRow } from './thread-feed-row'
@@ -33,7 +36,7 @@ import { ThreadOutcomeCard } from './thread-outcome-card'
  * `onSend`'s doc for why an inert composer beats a live one that eats input. */
 function noopSend(): void {}
 
-export type ThreadFeedProps = {
+export type ThreadFeedProps = BasaltProps & {
   readonly threads: AgentThread[]
   /** The currently open thread id, or null when none is selected. */
   readonly activeId: string | null
@@ -113,7 +116,10 @@ export function ThreadFeed({
   variant = 'outcome',
   onSend,
   renderRow,
+  className,
+  style,
 }: ThreadFeedProps): JSX.Element {
+  assertRequiredProps('ThreadFeed', { threads }, ['threads'])
   const reduceMotion = useReducedMotion()
 
   // The inline row's own manual-collapse override — see `ThreadFeedProps.variant`'s doc. Only ever
@@ -149,7 +155,7 @@ export function ThreadFeed({
 
   if (reduceMotion) {
     return (
-      <ScrollArea style={{ height: '100%' }}>
+      <ScrollArea className={cx(className)} style={{ height: '100%', ...style }}>
         <Stack gap="sm" p="sm">
           {threads.map((thread) => (
             <Box key={thread.id}>{rowFor(thread)}</Box>
@@ -160,7 +166,7 @@ export function ThreadFeed({
   }
 
   return (
-    <ScrollArea style={{ height: '100%' }}>
+    <ScrollArea className={cx(className)} style={{ height: '100%', ...style }}>
       <Stack gap="sm" p="sm">
         <AnimatePresence mode="popLayout" initial={false}>
           {threads.map((thread) => (