@timbal-ai/timbal-react 0.8.0 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +61 -5
  3. package/dist/app.cjs +1907 -1129
  4. package/dist/app.d.cts +2 -2
  5. package/dist/app.d.ts +2 -2
  6. package/dist/app.esm.js +29 -5
  7. package/dist/{button-CIKzUrJI.d.cts → button-ClSgD6OF.d.cts} +1 -1
  8. package/dist/{button-CIKzUrJI.d.ts → button-ClSgD6OF.d.ts} +1 -1
  9. package/dist/{chart-artifact-CqqhdSR9.d.ts → chart-artifact-Bl67kre7.d.ts} +214 -1
  10. package/dist/{chart-artifact-C2m891nx.d.cts → chart-artifact-BzcvblDe.d.cts} +214 -1
  11. package/dist/chat.esm.js +3 -3
  12. package/dist/{chunk-VVTTLIGT.esm.js → chunk-5ZKLPWVN.esm.js} +1 -1
  13. package/dist/{chunk-ZEDE2TWQ.esm.js → chunk-6YVKCVEP.esm.js} +1138 -378
  14. package/dist/{chunk-ZG5NBHOS.esm.js → chunk-CFU3YDTV.esm.js} +2 -2
  15. package/dist/{chunk-YNDXBN6C.esm.js → chunk-OISVICYF.esm.js} +1 -1
  16. package/dist/{chunk-LSEUKTU5.esm.js → chunk-P4SN7M67.esm.js} +1 -1
  17. package/dist/{chunk-Z27GBSOT.esm.js → chunk-QIABF4KB.esm.js} +53 -51
  18. package/dist/{chunk-QKO67F4V.esm.js → chunk-QVAUCVQA.esm.js} +93 -93
  19. package/dist/{chunk-4AO3HCAR.esm.js → chunk-VWHHKAHN.esm.js} +5 -5
  20. package/dist/index.cjs +1191 -418
  21. package/dist/index.d.cts +2 -2
  22. package/dist/index.d.ts +2 -2
  23. package/dist/index.esm.js +32 -8
  24. package/dist/studio.cjs +3 -1
  25. package/dist/studio.esm.js +6 -6
  26. package/dist/ui.d.cts +1 -1
  27. package/dist/ui.d.ts +1 -1
  28. package/dist/ui.esm.js +3 -3
  29. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,40 @@
2
2
 
3
3
  All notable changes to `@timbal-ai/timbal-react` are documented here.
4
4
 
5
+ ## [0.8.2] — 2026-06-02
6
+
7
+ ### Added
8
+
9
+ - **Full theme personalities** — extend programmatic theming beyond brand color to **roundness, shadows, and fonts** in one intent object:
10
+ - **`createTimbalTheme`** — new options: `shadow` (`none` | `hairline` | `soft` | `medium` | `strong`), `typography` (`sans`, optional `display`/`mono`, `importUrl` for web fonts). `radius` now also sets `--radius-2xl` (composer shell). Returns `fontFamily` + `fontImportUrl` for runtime font loading.
11
+ - **`themeToCss(theme, { scope?, includeFontImport? })`** — emits a `font-family: var(--font-sans)` rule when the theme carries a font; optional `@import` for standalone stylesheets.
12
+ - **`ensureThemeFontLink(url)`** — inject/remove a managed font `<link>` in `<head>`.
13
+ - **`applyTimbalTheme` / `TimbalThemeStyle`** — auto-load preset/custom web fonts via `<link>`.
14
+ - **`TIMBAL_THEME_PRESETS`** — each preset is now a full personality (color + radius + shadow + font), not color-only. New presets: **`folio`** (Fraunces serif, sharp corners), **`carbon`** (JetBrains Mono, green accent). Existing presets (`indigo`, `violet`, …) ship distinct fonts and radii.
15
+ - **`ThemePresetGallery`** — shows font name on each swatch card.
16
+ - **`THEME_AGENT_INSTRUCTIONS`** — documents typography, shadow, and font-loading rules for UI-generation agents.
17
+
18
+ ### Changed
19
+
20
+ - **`TimbalThemePreset`** — adds optional `font` label for pickers.
21
+
22
+ ---
23
+
24
+ ## [0.8.1] — 2026-06-02
25
+
26
+ ### Added
27
+
28
+ - **Programmatic theming** — derive a complete, paired light + dark palette from a single brand color so apps and UI-generation agents never hand-author OKLCH or risk a light-only override:
29
+ - **`createTimbalTheme({ brand, accent?, radius?, tintNeutrals? })`** — owns the OKLCH math for `--primary`, its foreground, `--ring`, the full primary button gradient, and the soft playground tint. Returns paired `{ light, dark, root }` token maps.
30
+ - **`themeToCss(theme, { scope? })`** — serialize to a paired `:root` / `.dark` (or `[data-timbal-theme]`-scoped) CSS string for build-time/SSR.
31
+ - **`applyTimbalTheme(theme)` / `clearTimbalTheme()`** — runtime apply via a managed `<style>` (works with the `.dark` toggle); returns a disposer.
32
+ - **`TimbalThemeStyle`** — render a generated theme (or `preset`) as a `<style>` near the app root.
33
+ - **`TIMBAL_THEME_PRESETS`** + **`getThemePreset`**, **`applyThemePreset`**, **`getStoredThemePreset`** — a closed catalog (`platform`, `indigo`, `violet`, `forest`, `warm`, `slate`) to offer styles by stable id; persists to `STORAGE_KEYS.themePreset` (`timbal-theme-preset`).
34
+ - **`ThemePresetGallery`** — preview + pick presets with real-component swatches, scoped so the live app doesn't change until selection.
35
+ - **`THEME_AGENT_INSTRUCTIONS`** — system-prompt text directing UI-generation agents to theme via these APIs, never raw OKLCH.
36
+
37
+ ---
38
+
5
39
  ## [0.8.0] — 2026-06-02
6
40
 
7
41
  ### Added
package/README.md CHANGED
@@ -2,14 +2,14 @@
2
2
 
3
3
  React components and runtime for building Timbal chat UIs and studio apps. Drop in a single component to get a fully-featured streaming chat interface connected to a Timbal workforce agent, or compose dashboards with the **app kit**.
4
4
 
5
- ## Package structure (0.7+)
5
+ ## Package structure (0.8+)
6
6
 
7
7
  | Subpath | Use when |
8
8
  |---------|----------|
9
9
  | `@timbal-ai/timbal-react` | Full surface (chat shells, auth, artifacts, app kit) |
10
10
  | `@timbal-ai/timbal-react/chat` | Chat-only apps — `Thread`, `Composer`, runtime, layout helpers |
11
11
  | `@timbal-ai/timbal-react/studio` | Studio chrome — `TimbalChatShell`, `TimbalStudioShell`, sidebar |
12
- | `@timbal-ai/timbal-react/ui` | Primitives — `Button`, `Dialog`, `Avatar`, `Shimmer` |
12
+ | `@timbal-ai/timbal-react/ui` | Primitives — `Button`, `Dialog`, `DropdownMenu`, `Popover`, `Select`, `Tooltip`, `Avatar`, `Shimmer` |
13
13
  | `@timbal-ai/timbal-react/app` | Dashboards — `AppShell`, `Page`, `DataTable`, `StatTile`, … |
14
14
  | `@timbal-ai/timbal-react/styles.css` | Theme tokens (required once) |
15
15
 
@@ -71,6 +71,55 @@ Every token has a CSS-variable indirection in `styles.css`. Override individual
71
71
 
72
72
  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.
73
73
 
74
+ ### Programmatic theming (no hand-authored OKLCH)
75
+
76
+ Instead of hand-writing paired `:root` / `.dark` blocks, derive a complete **personality** — color, roundness, shadows, and fonts — from a single intent object. The package owns the OKLCH math for every color token (primary, foreground, ring, the full button gradient, the playground tint):
77
+
78
+ ```ts
79
+ import { createTimbalTheme, themeToCss, applyTimbalTheme } from "@timbal-ai/timbal-react";
80
+
81
+ const theme = createTimbalTheme({
82
+ brand: "#4f46e5",
83
+ radius: 0.875, // corner roundness (rem) → --radius + --radius-2xl
84
+ shadow: "soft", // "none" | "hairline" | "soft" | "medium" | "strong"
85
+ typography: { // optional — re-skins every component's font
86
+ sans: '"Geist", ui-sans-serif, system-ui, sans-serif',
87
+ importUrl: "https://fonts.googleapis.com/css2?family=Geist:wght@400..600&display=swap",
88
+ },
89
+ });
90
+
91
+ // Build-time / SSR — paste into index.css (paired light + dark, always in sync):
92
+ const css = themeToCss(theme);
93
+
94
+ // Runtime — inject a managed <style> (+ font <link>), swappable, returns a disposer:
95
+ const dispose = applyTimbalTheme(theme);
96
+ ```
97
+
98
+ > **Fonts must be loaded.** `applyTimbalTheme` and `TimbalThemeStyle` inject the `<link>` for `typography.importUrl` automatically. For build-time `themeToCss`, add the `<link rel="stylesheet">` to `index.html` yourself (or pass `themeToCss(theme, { includeFontImport: true })` when the result is a standalone stylesheet).
99
+
100
+ Or render it as a component near your app root:
101
+
102
+ ```tsx
103
+ import { TimbalThemeStyle } from "@timbal-ai/timbal-react";
104
+
105
+ <TimbalThemeStyle theme={createTimbalTheme({ brand: "#4f46e5" })} />
106
+ // or: <TimbalThemeStyle preset="indigo" />
107
+ ```
108
+
109
+ ### Presets + the picker
110
+
111
+ A small closed catalog (`TIMBAL_THEME_PRESETS`) lets you offer styles by stable id and apply on selection. Each preset is a **full personality** (color + radius + shadows + font), not just a color: `platform` (system), `indigo` (Geist), `violet` (Sora), `forest`/`warm` (Lexend), `slate` (Inter), `folio` (Fraunces serif), `carbon` (JetBrains Mono). `ThemePresetGallery` previews each option with real components, scoped so the live app doesn't change until the user picks:
112
+
113
+ ```tsx
114
+ import { ThemePresetGallery, applyThemePreset } from "@timbal-ai/timbal-react";
115
+
116
+ <ThemePresetGallery value={id} onSelect={(next) => { setId(next); applyThemePreset(next); }} />
117
+ ```
118
+
119
+ `applyThemePreset` persists the choice to `localStorage` (`timbal-theme-preset`); `getStoredThemePreset()` restores it on reload.
120
+
121
+ **For UI-generation agents:** inject `THEME_AGENT_INSTRUCTIONS` into the system prompt so the model themes via these APIs (and never emits raw OKLCH), mirroring `APP_KIT_AGENT_INSTRUCTIONS`.
122
+
74
123
  ### CSS imports
75
124
 
76
125
  Import these stylesheets once in your app entry:
@@ -800,9 +849,16 @@ if (res.ok) {
800
849
 
801
850
  ### UI primitives
802
851
 
803
- Re-exported Radix UI wrappers pre-styled to match the Timbal design system:
852
+ Radix-backed wrappers pre-styled with the design tokens (`bg-popover`, `border-border`, `shadow-card`, …) — import from `@timbal-ai/timbal-react/ui` or the root. Use these instead of `npx shadcn`; raw shadcn references token names the app doesn't define and renders unstyled.
804
853
 
805
- `Button` · `Tooltip` · `TooltipTrigger` · `TooltipContent` · `TooltipProvider` · `Avatar` · `AvatarImage` · `AvatarFallback` · `Dialog` · `DialogContent` · `DialogTitle` · `DialogTrigger` · `Shimmer`
854
+ - **Button:** `Button`
855
+ - **Dialog:** `Dialog` · `DialogTrigger` · `DialogContent` · `DialogTitle` · `DialogDescription` · `DialogHeader` · `DialogFooter` · `DialogClose` · `DialogOverlay` · `DialogPortal`
856
+ - **Dropdown menu:** `DropdownMenu` · `DropdownMenuTrigger` · `DropdownMenuContent` · `DropdownMenuItem` · `DropdownMenuCheckboxItem` · `DropdownMenuRadioGroup` · `DropdownMenuRadioItem` · `DropdownMenuLabel` · `DropdownMenuSeparator` · `DropdownMenuShortcut` · `DropdownMenuGroup` · `DropdownMenuSub` · `DropdownMenuSubTrigger` · `DropdownMenuSubContent`
857
+ - **Popover:** `Popover` · `PopoverTrigger` · `PopoverContent` · `PopoverAnchor`
858
+ - **Select:** `Select` · `SelectTrigger` · `SelectValue` · `SelectContent` · `SelectItem` · `SelectGroup` · `SelectLabel` · `SelectSeparator` · `SelectScrollUpButton` · `SelectScrollDownButton`
859
+ - **Tooltip:** `Tooltip` · `TooltipTrigger` · `TooltipContent` · `TooltipProvider`
860
+ - **Avatar:** `Avatar` · `AvatarImage` · `AvatarFallback`
861
+ - **Misc:** `Shimmer`
806
862
 
807
863
  ---
808
864
 
@@ -976,7 +1032,7 @@ The following symbols are no longer exported. Most have no replacement because t
976
1032
 
977
1033
  - 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.
978
1034
  - All `studio*Class` / `studioChromeShellStyle` helpers — re-create the look with normal Tailwind classes against semantic tokens (`bg-elevated-from`, `border-border`, `shadow-card`, …).
979
- - All `TIMBAL_V2_*` button token records and `TimbalV2Button` — use the standard `Button` export from this package; it covers the same variants.
1035
+ - All `TIMBAL_V2_*` button token records and `TimbalV2Button` — use the standard `Button` export from this package; it covers the same variants. (Note: `TimbalV2Button` and several `TIMBAL_V2_*` surface tokens were re-introduced as public exports in 0.7 for catalog/list surfaces — see the CHANGELOG.)
980
1036
  - `StudioSidebarPanel`, `StudioSidebarHeader/Nav/Footer/Entries/Backdrop/Tooltip/RuntimePortal/EntryMotion`, `StudioSidebarContext`, `useStudioSidebarLayout`, `useStudioSidebarCollapsed`, `useSidebarCollapsePhase`, `workforceItemId/Label/Initial` — use `StudioSidebar` or `TimbalStudioShell` directly.
981
1037
  - `runThemeSanityCheck` — `<Thread>` already schedules the dev-only check.
982
1038
  - `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.