@timbal-ai/timbal-react 0.8.2 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to `@timbal-ai/timbal-react` are documented here.
 
+## [Unreleased]
+
+### Changed
+
+- **App-kit charts now run on [recharts](https://recharts.org)** (native shadcn chart layer). `LineAreaChart`, `PieChart`, `RadialChart`, and `RadarChart` keep the same public props but render via recharts under the shadcn `ChartContainer` / `ChartTooltipContent` / `ChartLegendContent` chrome — so tooltips, hover states, and animation match shadcn exactly across every chart kind. Series colors still flow from the theme `--chart-1..6` tokens.
+- Fixes from feedback: in-card legends no longer clip outside the card; line/area charts use a thin crosshair cursor (not a wide band); tooltips animate in; and radial/radar charts now have hover tooltips.
+
+### Added
+
+- **shadcn chart primitives exported from `/ui`**: `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `useChart`, and the `ChartConfig` type.
+
+### Dependencies
+
+- Adds **`recharts`** as a dependency and **`react-is`** as a peer dependency (`react-is` must match your React version).
+
+## [1.1.0] — 2026-06-03
+
+### Added
+
+- **`DataTable` scales to real datasets** — three additive props (all backward-compatible):
+  - **`pageSize`** — built-in client-side pagination with a compact footer pager (row range + prev/next). Controlled via `pageIndex` / `onPageChange`, or uncontrolled with `defaultPageIndex`; out-of-range pages snap back after filtering.
+  - **`selectable`** + **`selectedKeys`** / **`defaultSelectedKeys`** / **`onSelectionChange`** — a leading checkbox column with header select-all (indeterminate state) for bulk actions (acknowledge/resolve/export). Toggling a checkbox never triggers `onRowClick`.
+  - **`loading`** (+ **`loadingRows`**) — shaped skeleton rows that preserve the header/columns so the table doesn't jump when data arrives.
+- **Loading states across the data kit** — `MetricRow`, `MetricChartCard`, and `ChartPanel` accept **`loading`**, rendering skeleton tiles / plot-height skeletons. Every async dashboard gets a consistent pending state without re-inventing one.
+- **`useLiveQuery` / `useInterval`** (root + `/app`) — poll an async source on an interval for live dashboards (alerts, metrics, logs). Handles loading vs. background `refreshing`, drops stale/post-unmount responses, pauses while the tab is hidden + refetches on focus, and exposes `lastUpdated` + a manual `refetch`. Pairs with `authFetch`.
+- **`AppShell` owns the mobile nav** — `AppShell` manages the drawer open-state (`navOpen` / `defaultNavOpen` / `onNavOpenChange`), renders the mobile backdrop automatically, and provides **`useAppShellNav()`** + **`AppShellSidebarTrigger`** (an `md:hidden` hamburger). Wiring a responsive `StudioSidebar` drops from ~30 lines of `isMobile`/resize/backdrop boilerplate to passing `mobileOpen={nav.open}` / `onMobileOpenChange={nav.setOpen}`.
+- **`StatusBadge` `tone="danger"`** — a destructive/red tone for critical severity, so error/critical states aren't forced onto the brand `primary` tone.
+
+## [1.0.0] — 2026-06-02
+
+First stable release. The `@timbal-ai/timbal-react/ui` primitive layer, the control-surface contract, and the app-kit are now a settled public surface.
+
+### Added
+
+- **Built-in motion engine** — Dialog, AlertDialog, Sheet, Popover, DropdownMenu, Select, Tooltip, Toast, NavigationMenu, and Accordion / Collapsible now animate (fade / zoom / slide / height) out of the box. The `animate-in` / `animate-out` / `fade-*` / `zoom-*` / `slide-*` utilities and the `accordion` / `collapsible` / `caret-blink` keyframes are **inlined in `styles.css`** — no `tailwindcss-animate` / `tw-animate-css` dependency and no consumer config. Duration flows from any `duration-*` utility via `--tw-duration` (default 150ms). Compose `overlayAnimationClass` for custom overlays.
+- **Complete vendored primitive catalog** on the control-surface contract: `Form`, `AspectRatio`, `Toolbar`, `Menubar`, `NavigationMenu`, `Breadcrumb`, `Pagination`, `Command` (cmdk), `Calendar` (react-day-picker), `Combobox`, `DatePicker`, `InputOTP`, `Kbd`, `Spinner`, `InputGroup` — alongside the existing `Input`, `Select`, `Dialog`, `Sheet`, `AlertDialog`, `Table`, `Toast`, `Card`, `Badge`, `Slider`, `Progress`, and more.
+- **`overlayListPanelClass`** + **`PopoverContent` `variant="list"`** — one shared listbox/menu chrome so `Select`, `DropdownMenu`, `Combobox`, and `Command` panels are visually identical. `Combobox` uses `ComboboxTrigger` (control skin), not a `Button`.
+- **App-kit organized into two libraries** (example): a **UI primitives** catalog (per-family audit, sidebar) and a **Blocks** library (composed sections — Project settings, Settings form, Metrics, Analytics, Charts, Table, Integrations, Resources, Confirm & destructive, Detail sheet, Empty states, Sign-in). Driven by `primitives-catalog.ts` / `blocks-catalog.ts`.
+
+### Changed
+
+- `overlayAnimationClass` is now exported from `@timbal-ai/timbal-react/ui` and the root for composing custom overlays.
+
+### Removed (breaking)
+
+- **`Tabs` / `TabsList` / `TabsTrigger` / `TabsContent` are no longer exported.** Radix/shadcn Tabs are intentionally not part of this package. Use **`PillSegmentedTabs`** (`trackVariant="flush"`) or the app-kit **`SubNav`** for section bars; switch panel content with local state or the router. Use `Accordion` / `Collapsible` for expand-collapse.
+
+---
+
 ## [0.8.2] — 2026-06-02
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 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**.
 
-## Package structure (0.8+)
+## Package structure (1.0)
 
 | Subpath | Use when |
 |---------|----------|
@@ -35,9 +35,11 @@ bun add @timbal-ai/timbal-react
 **Peer dependencies:**
 
 ```bash
-npm install react react-dom @assistant-ui/react @timbal-ai/timbal-sdk
+npm install react react-dom react-is @assistant-ui/react @timbal-ai/timbal-sdk
 ```
 
+> The app-kit charts are built on [recharts](https://recharts.org) (installed automatically). `react-is` is a recharts peer and **must match your React version** — install it explicitly if your package manager doesn't hoist peers.
+
 ### Tailwind setup
 
 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:
@@ -61,15 +63,51 @@ Every token has a CSS-variable indirection in `styles.css`. Override individual
 :root {
   --primary: oklch(0.5 0.12 265);
   --playground-from: oklch(0.95 0.04 265 / 0.6);
+  /* Chart series — override any to rebrand every dashboard chart at once */
+  --chart-1: var(--primary);
+  --chart-2: oklch(0.62 0.13 184);
 }
 
 .dark {
   --primary: oklch(0.72 0.14 265);
   --playground-from: oklch(0.27 0.04 265);
+  --chart-1: var(--primary);
 }
 ```
 
-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.
+Both light AND dark blocks must define 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.
+
+### Charts (app kit + artifacts)
+
+Dashboard and in-chat charts use the **native shadcn/recharts layer** — animated tooltips, hover crosshairs, and legends that match shadcn/ui out of the box.
+
+| Import from | Components |
+|-------------|------------|
+| `@timbal-ai/timbal-react` or `/app` | `LineAreaChart`, `PieChart`, `RadialChart`, `RadarChart`, `Sparkline`, `ChartPanel`, `MetricChartCard` |
+| `@timbal-ai/timbal-react/ui` | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartConfig` |
+
+**Dependencies:** `recharts` ships with the package. Install **`react-is`** alongside React (same major version) — it is a recharts peer and must match your React version.
+
+**Rebrand:** override `--chart-1` … `--chart-6` in `:root` / `.dark` (series 1 defaults to `--primary`). Per-series overrides: `series[].color` on `LineAreaChart` or `colors` on pie/radial artifacts.
+
+**`ChartArtifact` kinds:** `bar`, `horizontalBar`, `line`, `area`, `pie`, `donut`, `radial`, `radar` — see `ChartPanel` + the app-kit **Chart catalog** recipe.
+
+**Custom charts** (same pattern as shadcn docs):
+
+```tsx
+import { Bar, BarChart, XAxis } from "recharts";
+import { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from "@timbal-ai/timbal-react/ui";
+
+const config = { revenue: { label: "Revenue", color: "var(--chart-1)" } } satisfies ChartConfig;
+
+<ChartContainer config={config} className="h-[240px] w-full">
+  <BarChart data={rows} accessibilityLayer>
+    <XAxis dataKey="month" hide />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Bar dataKey="revenue" fill="var(--color-revenue)" radius={4} />
+  </BarChart>
+</ChartContainer>
+```
 
 ### Programmatic theming (no hand-authored OKLCH)
 
@@ -120,6 +158,33 @@ import { ThemePresetGallery, applyThemePreset } from "@timbal-ai/timbal-react";
 
 **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`.
 
+### Anti-slop guardrails for generated UIs
+
+When an agent composes app-kit UIs, taste is enforced — not just suggested — through three layers built on one shared vocabulary (`HOUSE_RULES`, `SEMANTIC_COLOR_TOKENS`, `SLOP_BUDGETS`):
+
+```ts
+import {
+  lintGeneratedUi,
+  reviewGeneratedUi,
+  UI_REVIEW_AGENT_INSTRUCTIONS,
+} from "@timbal-ai/timbal-react"; // or "/app"
+
+// 1. Prompt: APP_KIT_AGENT_INSTRUCTIONS renders its anti-slop checklist from
+//    HOUSE_RULES; add UI_REVIEW_AGENT_INSTRUCTIONS so the model self-reviews.
+const systemPrompt = `${basePrompt}\n\n${APP_KIT_AGENT_INSTRUCTIONS}\n\n${UI_REVIEW_AGENT_INSTRUCTIONS}`;
+
+// 2. Lint: deterministic checks reject hardcoded palette colors / hex / oklch
+//    (errors) and flag icon-spam, bold giant values, per-row dividers, and
+//    gradients on data surfaces (warnings).
+const { ok, findings } = lintGeneratedUi(generatedTsx);
+
+// 3. Critique loop: review → fix → re-review until it passes clean.
+const review = reviewGeneratedUi(generatedTsx, { strict: true });
+if (!review.passed) regenerate(review.revisionPrompt); // names the exact lines + fixes
+```
+
+Color decisions belong to the theme generator and semantic tokens, never to the per-component agent — the linter enforces exactly that.
+
 ### CSS imports
 
 Import these stylesheets once in your app entry:
@@ -851,6 +916,17 @@ if (res.ok) {
 
 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.
 
+**Control-surface contract.** Every input, select / dropdown trigger, and search field shares **one** skin so they match side by side regardless of origin. Build custom controls by composing it — never hand-roll a `rounded-* border-input bg-…` surface:
+
+```tsx
+import { controlClass, overlaySurfaceClass, overlayItemClass } from "@timbal-ai/timbal-react/ui";
+
+<input className={controlClass({}, "w-full")} />            {/* field shape, h-10 */}
+<button className={controlClass({ shape: "pill", size: "sm" })} />  {/* chrome pill */}
+```
+
+`controlClass({ size, shape })` — `size`: `"sm" | "default"`; `shape`: `"field"` (rounded-lg, default) or `"pill"` (chrome rows). Floating panels (popover, menu, listbox) compose `overlaySurfaceClass` + `overlayItemClass`. Vendoring a new shadcn primitive means swapping its inline surface string for these before shipping.
+
 - **Button:** `Button`
 - **Dialog:** `Dialog` · `DialogTrigger` · `DialogContent` · `DialogTitle` · `DialogDescription` · `DialogHeader` · `DialogFooter` · `DialogClose` · `DialogOverlay` · `DialogPortal`
 - **Dropdown menu:** `DropdownMenu` · `DropdownMenuTrigger` · `DropdownMenuContent` · `DropdownMenuItem` · `DropdownMenuCheckboxItem` · `DropdownMenuRadioGroup` · `DropdownMenuRadioItem` · `DropdownMenuLabel` · `DropdownMenuSeparator` · `DropdownMenuShortcut` · `DropdownMenuGroup` · `DropdownMenuSub` · `DropdownMenuSubTrigger` · `DropdownMenuSubContent`
@@ -858,7 +934,22 @@ Radix-backed wrappers pre-styled with the design tokens (`bg-popover`, `border-b
 - **Select:** `Select` · `SelectTrigger` · `SelectValue` · `SelectContent` · `SelectItem` · `SelectGroup` · `SelectLabel` · `SelectSeparator` · `SelectScrollUpButton` · `SelectScrollDownButton`
 - **Tooltip:** `Tooltip` · `TooltipTrigger` · `TooltipContent` · `TooltipProvider`
 - **Avatar:** `Avatar` · `AvatarImage` · `AvatarFallback`
-- **Misc:** `Shimmer`
+- **Form:** `Input` · `Textarea` · `Label` · `Checkbox` · `Switch` · `RadioGroup` · `RadioGroupItem` · `Form` (+ field/item/label/control/message/submit)
+- **Navigation / chrome:** `Breadcrumb` (+ list/item/link/page/separator/ellipsis) · `Pagination` (+ content/item/link/previous/next/ellipsis) · `Menubar` (+ sub-parts) · `NavigationMenu` (+ sub-parts) · `Toolbar` (+ button/separator/toggle/link)
+- **Command & date:** `Command` (+ dialog/input/list/group/item/…) · `Calendar` · `Combobox` (Popover + Command) · `DatePicker` (Popover + Calendar)
+- **Input OTP:** `InputOTP` · `InputOTPGroup` · `InputOTPSlot` · `InputOTPHiddenInput` · `InputOTPSeparator` (Radix OTP field via unified `radix-ui`)
+- **Misc:** `Kbd` · `KbdGroup` · `Shimmer`
+- **Feedback / data:** `Slider` · `Progress` · `Badge`
+- **Overlays:** `Sheet` · `AlertDialog` · `HoverCard` · `ContextMenu` (+ sub-parts) · `Toast` / `Toaster` / `toast()` / `useToast`
+- **Surfaces:** `Card` (+ header/footer/title/description/content) · `Alert` · `Skeleton` · `Table` (+ header/body/row/cell)
+- **Toggles:** `Toggle` · `ToggleGroup` · `Collapsible` · `ScrollArea`
+- **Section navigation (pill switcher):** `PillSegmentedTabs` · `SubNav` (app kit) — **not** shadcn `Tabs`; Radix `Tabs` is not exported
+- **Layout / disclosure:** `Accordion` · `AccordionItem` · `AccordionTrigger` · `AccordionContent` · `Separator` · `AspectRatio`
+- **Input chrome:** `InputGroup` (+ addon/control/text) · `Spinner`
+
+**Motion is built in.** Dialog, AlertDialog, Sheet, Popover, DropdownMenu, Select, Tooltip, Toast, NavigationMenu, and Accordion / Collapsible animate out of the box (fade / zoom / slide / height). The animation engine is **inlined in `styles.css`** — no `tailwindcss-animate` / `tw-animate-css` dependency and no consumer config. Duration flows from any `duration-*` utility (`--tw-duration`, default 150ms). When composing a custom overlay, reuse `overlayAnimationClass` rather than adding another animation library.
+
+All primitives are Radix-backed (via the unified `radix-ui` package) or thin wrappers (`cmdk` for Command, `react-day-picker` for Calendar) and styled with the design tokens + the control-surface contract, so a new primitive matches the rest on arrival. Browse them live in the app-kit example: the **UI primitives** library (per-family audit) and the **Blocks** library (composed sections — Project settings, Confirm flow, Detail sheet, Empty states, Sign-in).
 
 ---
 
@@ -972,10 +1063,13 @@ The shell renders a rounded floating panel (bottom-right) and a **text-only** pi
 | `AppCopilotProvider` | Page context via `useAppCopilotContext` (not shown in UI) |
 | `AppChatPanel` | Full-height floating thread; dismiss via **X** in the corner |
 | `AppShell` `chat` | Floating overlay — `chatWidth`; optional `chatHeight` (default: stretch top–bottom) |
-| `LineAreaChart` / `Sparkline` | Dependency-free charts (smooth area/line/bar, hover tooltip, responsive) |
+| `LineAreaChart` | Cartesian engine on **recharts** — area/line/bar, stacked, horizontal bars, `monotone`/`linear`/`step` curves, dots, shadcn-style hover tooltip (`dot`/`line`/`dashed` indicators), responsive |
+| `PieChart` / `RadialChart` / `RadarChart` | Pie & donut (center KPI), concentric progress rings, and spider charts — native shadcn/recharts charts |
+| `ChartContainer` / `ChartTooltip` / `ChartTooltipContent` / `ChartLegend` / `ChartLegendContent` (`/ui`) | shadcn chart primitives (recharts wrappers); colors flow from `ChartConfig` → `--color-*` |
+| `Sparkline` | Tiny inline trend for table cells and tiles |
 | `MetricRow` | Platform KPI strip in one card (overview metrics, no chart) |
 | `MetricChartCard` | `MetricRow` + selectable flush chart (Analytics / Infrastructure) |
-| `ChartPanel` `artifact` | Chrome around a `ChartArtifact` or any chart |
+| `ChartPanel` `artifact` | Chrome around a `ChartArtifact` (`chartType`: `bar`/`horizontalBar`/`line`/`area`/`pie`/`donut`/`radial`/`radar`) or any chart |
 | `SettingsSection` / `FieldRow` / `DangerZone` / `FloatingUnsavedChangesBar` | Two-column settings page building blocks |
 | `IntegrationCard` / `ConnectionRow` / `PlanBadge` / `IntegrationsEmptyState` | Integration catalog + connected list |
 | `InfoCard` / `DescriptionList` / `ExpandableSection` / `ResourceCard` / `StatusDot` | Surfaces & detail views |