@timbal-ai/timbal-react 0.3.0 → 0.5.0

package/README.md

@@ -18,27 +18,36 @@ npm install react react-dom @assistant-ui/react @timbal-ai/timbal-sdk
 
 ### Tailwind setup
 
-The package ships pre-built Tailwind class names. Add this `@source` line to your CSS entry file — **without it the components will be unstyled**:
+The package ships pre-built Tailwind class names **plus a complete light + dark token set** (`bg-background`, `text-foreground`, `bg-card`, `bg-bubble-user`, `from-elevated-from`, `bg-playground-from/via/to`, etc.). Your app CSS only needs three lines:
 
 ```css
 /* src/index.css */
 @import "tailwindcss";
-
+@import "@timbal-ai/timbal-react/styles.css";
 @source "../node_modules/@timbal-ai/timbal-react/dist";
 ```
 
-> Adjust the path if your CSS file lives at a different depth relative to `node_modules`.
+That's it — no `@theme`, `:root`, or `.dark` blocks of your own. Toggling dark mode is a single `document.documentElement.classList.toggle("dark")` (or `next-themes` `attribute="class"`).
 
-### Companion stylesheet (optional)
+> Adjust the `@source` path if your CSS file lives at a different depth relative to `node_modules`.
 
-For blueprint-style polish (welcome animations, suggestion chips, tool indicators), import the shipped companion CSS once. Requires Tailwind v4 design tokens (`--primary`, etc.) in your app:
+### Overriding the palette
 
-```ts
-// src/main.tsx
-import "@timbal-ai/timbal-react/styles.css";
+Every token has a CSS-variable indirection in `styles.css`. Override individual variables to rebrand without forking:
+
+```css
+:root {
+  --primary: oklch(0.5 0.12 265);
+  --playground-from: oklch(0.95 0.04 265 / 0.6);
+}
+
+.dark {
+  --primary: oklch(0.72 0.14 265);
+  --playground-from: oklch(0.27 0.04 265);
+}
 ```
 
-You can omit this entirely and style components yourself — the package does not bundle mandatory CSS beyond what Tailwind scans from `dist/`.
+Both light AND dark blocks must be defined for every overridden token — otherwise toggling dark mode produces an inconsistent UI. The library prints a one-time dev-only console warning when it detects a mismatch.
 
 ### CSS imports
 
@@ -129,6 +138,57 @@ const [workforceId, setWorkforceId] = useState("agent-a");
 <TimbalChat workforceId={workforceId} key={workforceId} />
 ```
 
+### Studio shell (sidebar + header + chat)
+
+`TimbalStudioShell` is the most opinionated layout — a floating workforce sidebar, a top bar for actions (mode toggle, account), and a full-height `TimbalChat`. Works as a one-line app:
+
+```tsx
+import {
+  TimbalStudioShell,
+  ModeToggle,
+  TimbalMark,
+} from "@timbal-ai/timbal-react";
+import { useTheme } from "next-themes";
+
+export default function App() {
+  const { resolvedTheme, setTheme } = useTheme();
+
+  return (
+    <TimbalStudioShell
+      brand={<TimbalMark size={32} />}
+      welcome={{ heading: "How can I help you today?" }}
+      headerActions={
+        <ModeToggle theme={resolvedTheme} setTheme={setTheme} />
+      }
+      suggestions={[{ title: "Get started" }]}
+      attachments
+    />
+  );
+}
+```
+
+When `workforceId` is omitted, the shell fetches the workforce list and lets the sidebar drive selection. Pass `workforceId` to pin a single agent and hide the picker UI.
+
+Apps that need finer control can compose the public building blocks (`StudioSidebar` + `TimbalChat`) directly:
+
+```tsx
+import { StudioSidebar, TimbalChat } from "@timbal-ai/timbal-react";
+
+function MyShell() {
+  const [agent, setAgent] = useState("agent-a");
+  return (
+    <div className="relative h-dvh bg-background">
+      <StudioSidebar selectedId={agent} onSelect={setAgent} />
+      <main className="h-full pl-[var(--studio-inset-left)]">
+        <TimbalChat workforceId={agent} key={agent} />
+      </main>
+    </div>
+  );
+}
+```
+
+The `--studio-inset-left` CSS variable is automatically set on the document by `StudioSidebar`, so a normal Tailwind `pl-[var(--studio-inset-left)]` call resolves to the correct offset.
+
 ### Drop-in shell (header + agent picker)
 
 `TimbalChatShell` wraps the common blueprint layout: brand area, workforce selector, optional header actions, and a full-height chat. When `workforceId` is omitted, it fetches `{baseUrl}/workforce` and selects the first agent automatically:
@@ -658,6 +718,11 @@ if (res.ok) {
 
 | Export | Description |
 |---|---|
+| `TimbalStudioShell` | Floating sidebar + top bar + full-height `TimbalChat`. Most opinionated layout |
+| `StudioSidebar` | Floating workforce sidebar — collapses, mobile drawer, runtime portal anchor |
+| `ModeToggle` | Sun/moon theme toggle styled for the studio top bar |
+| `TimbalMark` | Liquid-metal brand mark — drop-in welcome icon |
+| `StudioWelcome` | Welcome screen with `TimbalMark` + staggered intro animation |
 | `TimbalChatShell` | Header + workforce picker + full-height `TimbalChat` |
 | `Thread` | Full chat UI — messages, composer, attachments, action bar |
 | `Composer` | Standalone composer bar (for custom thread layouts) |
@@ -671,10 +736,6 @@ if (res.ok) {
 | `UiCustomNodeRegistryProvider` | Register `{ kind: "custom" }` node renderers |
 | `ArtifactView` | Render a single artifact object |
 | `parseArtifactFromToolResult` | Parse tool output into an artifact |
-| `SyntaxHighlighter` | Shiki-based code highlighter (vitesse-dark / vitesse-light themes) |
-| `UserMessageAttachments` | Attachment thumbnails in user messages |
-| `ComposerAttachments` | Attachment previews inside the composer |
-| `ComposerAddAttachment` | "+" button to add attachments |
 | `TooltipIconButton` | Icon button with a tooltip |
 
 ### Hooks
@@ -685,6 +746,7 @@ if (res.ok) {
 | `useTimbalStream` | Low-level SSE chat state without `<Thread>` |
 | `useTimbalRuntime` | Access runtime context inside custom providers |
 | `useResolvedSuggestions` | Resolve static/async `SuggestionsSource` to an array |
+| `useOptionalSession` | Same as `useSession` but returns `null` when no `SessionProvider` is mounted |
 
 ### UI primitives
 
@@ -764,6 +826,42 @@ For a fully custom header, combine `useWorkforces` with `TimbalChat` instead of
 
 ---
 
+## Migrating from 0.4 to 0.5
+
+`0.5.0` slims the public API to the surface that blueprint apps actually use. Every feature still works — only the export list changed.
+
+### Re-brand via CSS variables, not internals
+
+All sizing and class composites moved to internal modules. Override the CSS variables in your own `:root` / `.dark` blocks instead of importing helper strings:
+
+```css
+:root {
+  --studio-sidebar-width: 15rem;
+  --studio-topbar-height: 3.25rem;
+}
+```
+
+For colours, override the existing semantic tokens (`--background`, `--foreground`, `--composer-bg`, `--bubble-user`, `--playground-from/via/to`, …). See [`src/styles.css`](src/styles.css) for the full list.
+
+### Removed from the public API
+
+The following symbols are no longer exported. Most have no replacement because they were never meant to be public; for the rest, prefer the high-level shells or CSS-variable overrides:
+
+- All `STUDIO_*` layout constants (`STUDIO_SIDEBAR_WIDTH`, `STUDIO_INSET_LEFT`, `STUDIO_SIDEBAR_COLLAPSED_STORAGE_KEY`, `STUDIO_SIDEBAR_PX_*`, …) — override the matching `--studio-*` CSS variables instead.
+- All `studio*Class` / `studioChromeShellStyle` helpers — re-create the look with normal Tailwind classes against semantic tokens (`bg-elevated-from`, `border-border`, `shadow-card`, …).
+- All `TIMBAL_V2_*` button token records and `TimbalV2Button` — use the standard `Button` export from this package; it covers the same variants.
+- `StudioSidebarPanel`, `StudioSidebarHeader/Nav/Footer/Entries/Backdrop/Tooltip/RuntimePortal/EntryMotion`, `StudioSidebarContext`, `useStudioSidebarLayout`, `useStudioSidebarCollapsed`, `useSidebarCollapsePhase`, `workforceItemId/Label/Initial` — use `StudioSidebar` or `TimbalStudioShell` directly.
+- `runThemeSanityCheck` — `<Thread>` already schedules the dev-only check.
+- `SyntaxHighlighter`, `UserMessageAttachments`, `ComposerAttachments`, `ComposerAddAttachment`, `MessagePartPrimitive`, `ActionBarMorePrimitive`, `ErrorPrimitive`, `useAuiState`, `buttonVariants` — internal composer/markdown details. Override the `Composer` / `AssistantMessage` slot via the `components` prop if you need a custom layout.
+
+Everything else (the three shells, primitives, hooks, auth, artifact API, design-token CSS variables) is unchanged.
+
+---
+
+## Mock UI demo
+
+An offline Vite app lives in [`examples/mock-ui`](examples/mock-ui). It uses a scripted mock `fetch` (no API keys) and includes a component gallery for artifacts. See that folder’s README for run instructions.
+
 ## Local development
 
 Install via a local path reference: