@timbal-ai/timbal-react 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to `@timbal-ai/timbal-react` are documented here.
+
+## [0.7.1] — 2026-06-02
+
+### Changed
+
+- **Opaque elevated surfaces** — `--elevated-from` / `--elevated-to` no longer use alpha in light or dark themes, preserving the signature vertical gradient with no background bleed-through.
+
+### Added
+
+- **`TIMBAL_V2_ELEVATED_SURFACE`** — elevated card/list surface (gradient + border + `shadow-card`) without hover/active fill shifts, for catalog cards and connection lists.
+- **`TIMBAL_V2_LOGO_TILE`** — logo/integration mark tile pinned to the light plate in both themes so dark provider logos stay legible.
+- **`STORAGE_KEYS.theme`** — localStorage key used by `ModeToggle` in uncontrolled mode.
+
+### Fixed
+
+- **`StatTile`** typography aligned with platform metrics (normal weight, compact labels, tabular numerals).
+
+---
+
+## [0.7.0] — 2026-05-29
+
+### Added
+
+- **App kit premade components** under `@timbal-ai/timbal-react/app`:
+  - **Metrics:** `MetricRow`, `MetricChartCard`, `MetricTile` (platform-style KPI strip + flush chart)
+  - **Integrations:** `IntegrationCard`, `ConnectionRow`, `ConnectionRowList`, `IntegrationsEmptyState`, `PlanBadge`
+  - **Settings:** `SettingsSection`, `FieldRow`, `DangerZone`, `FloatingUnsavedChangesBar`
+  - **Surfaces:** `InfoCard`, `DescriptionList`, `ExpandableSection`, `ResourceCard`, `StatusDot`
+- **Charts engine** (`LineAreaChart`, `Sparkline`, `CHART_PALETTE`) — dependency-free SVG + motion; shared by app kit and chart artifacts
+- **`APP_KIT_AGENT_INSTRUCTIONS`** — codegen system-prompt text (component menu, recipes, accessibility)
+- **`TIMBAL_V2_ELEVATED_SURFACE`** and **`TIMBAL_V2_LOGO_TILE`** design tokens for catalog/resource cards
+- **`@timbal-ai/timbal-react/vite`** — `timbalReactLocalDev()` plugin: linked-package dev, `dist/` watch, src alias when `dist/` is missing
+- **`examples/app-kit`** recipe gallery and reference dashboard
+- **`AGENTS.md`** section for app kit + recipes
+
+### Changed
+
+- **`ChartPanel`** — same shell as `MetricChartCard` (title row + flush plot); `ChartArtifactView` supports `embedded` mode
+- **Chart artifacts** — area/line/bar route through `LineAreaChart` with flush layout and improved styling
+- **`Button`** — pill shape by default; re-exported from `/app` for catalog CTAs
+- **`StatTile`** — typography aligned with platform metrics (normal weight, compact labels)
+- **Integration / resource / metric cards** — elevated secondary chrome; no background flash on card click (reserved for `Button`)
+
+### Fixed
+
+- Local dev **404 on `*.esm.js`** when `dist/` is empty — vite plugin falls back to `src/` with a console warning
+
+---
+
+## [0.6.1]
+
+Subpath exports (`/chat`, `/studio`, `/ui`, `/app`), layered package architecture, initial app kit (`AppShell`, `Page`, `DataTable`, …).

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.6+)
+## Package structure (0.7+)
 
 | Subpath | Use when |
 |---------|----------|
@@ -49,7 +49,7 @@ The package ships pre-built Tailwind class names **plus a complete light + dark
 @source "../node_modules/@timbal-ai/timbal-react/dist";
 ```
 
-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"`).
+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"`). The built-in `ModeToggle` (uncontrolled) persists to `localStorage` key `timbal-theme` and restores on reload.
 
 > Adjust the `@source` path if your CSS file lives at a different depth relative to `node_modules`.
 
@@ -134,6 +134,16 @@ Suggestions also accept a function (sync or async) for per-user or server-driven
 
 Each chip supports `icon`, `description`, and `prompt` (sent instead of `title` when clicked).
 
+In `AppChatPanel` (`variant="panel"`), welcome suggestions are **off** by default. Enable them with `showWelcomeSuggestions`:
+
+```tsx
+<AppChatPanel
+  workforceId="your-workforce-id"
+  showWelcomeSuggestions
+  suggestions={[{ title: "Summarize this dashboard" }]}
+/>
+```
+
 ### Placeholder and width
 
 ```tsx
@@ -605,6 +615,7 @@ import {
 | `welcome.heading` | `string` | `"How can I help you today?"` | Welcome screen heading |
 | `welcome.subheading` | `string` | `"Send a message to start a conversation."` | Welcome screen subheading |
 | `suggestions` | `{ title: string; description?: string }[]` | — | Suggestion chips on the welcome screen |
+| `showWelcomeSuggestions` | `boolean` | `true` (`default` variant), `false` (`panel`) | Show built-in welcome suggestions when `suggestions` is set |
 | `composerPlaceholder` | `string` | `"Send a message..."` | Composer input placeholder |
 | `components` | `ThreadComponents` | — | Override individual UI slots |
 | `onArtifactEvent` | `(event: UiEventEnvelope) => void` | — | Called when a `ui` artifact fires an `emit` action |
@@ -905,11 +916,30 @@ 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) |
-| `ChartPanel` `artifact` | Built-in SVG charts without extra imports |
+| `LineAreaChart` / `Sparkline` | Dependency-free charts (smooth area/line/bar, hover tooltip, responsive) |
+| `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 |
+| `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 |
 | `FieldTextarea` / `FieldSelect` / `FieldSwitch` | Settings forms matching `FieldInput` |
 | `AppConfirmDialog` | Delete/export confirmations |
 
-Full gallery: [`examples/app-kit`](examples/app-kit) (`bun run example:app`).
+Inject `APP_KIT_AGENT_INSTRUCTIONS` into codegen / workforce prompts (same idea as `ARTIFACT_AGENT_INSTRUCTIONS`). Agents should compose **creatively** from the component menu — not clone a single demo layout.
+
+```ts
+import { APP_KIT_AGENT_INSTRUCTIONS } from "@timbal-ai/timbal-react/app";
+
+const systemPrompt = `${basePrompt}\n\n${APP_KIT_AGENT_INSTRUCTIONS}`;
+```
+
+| Examples | Purpose |
+|----------|---------|
+| [`examples/app-kit/src/recipes/`](examples/app-kit/src/recipes/) | Short patterns (metrics, table, forms, copilot, …) — **preferred for agents** |
+| [`examples/app-kit/src/reference/`](examples/app-kit/src/reference/) | One full wired dashboard — **reference only** |
+
+Browse locally: [`examples/app-kit`](examples/app-kit) (`bun run example:app`).
 
 ---
 
@@ -958,7 +988,7 @@ Everything else (the three shells, primitives, hooks, auth, artifact API, design
 ## Examples
 
 - [`examples/mock-ui`](examples/mock-ui) — chat + artifact gallery (mock `fetch`).
-- [`examples/app-kit`](examples/app-kit) — dashboard / app kit component gallery (no API).
+- [`examples/app-kit`](examples/app-kit) — app kit **recipes** + optional **reference** dashboard (see `APP_KIT_AGENT_INSTRUCTIONS`).
 
 ## Mock UI demo