@timbal-ai/timbal-react 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to `@timbal-ai/timbal-react` are documented here.
 
 ## [Unreleased]
 
+## [1.7.0] — 2026-06-28
+
+Hardening release: make UI generation bulletproof for codegen agents by letting
+the package speak for itself (types, defaults, JSDoc-with-examples, fail-loud
+guardrails) instead of leaning on prose instructions.
+
+### Added
+
+- **`AppShell` auto mobile-nav hamburger (no topbar required)** — when an `AppShell` has a `sidebar` but no `topbar`, it now renders its own floating hamburger (`md:hidden`, top-left) that opens the sidebar drawer. New `mobileSidebarTrigger?: "auto" | "topbar" | "none"` (default `"auto"`). A sidebar dashboard now works on mobile with **no topbar and no wiring** — detaching the long-standing "inject a topbar just for the mobile menu" coupling.
+- **`StudioSidebar` auto-syncs to the shell** — inside `AppShell`, the drawer reads the shell's mobile-nav controls automatically when `mobileOpen` isn't passed (via a neutral `src/layout/shell-nav-context.tsx` channel, mirroring the inset channel). No more manual `mobileOpen` / `onMobileOpenChange` / `StudioSidebarBackdrop` plumbing.
+- **Chart-color lint rule (`chart-token-color-fn`, error)** — flags wrapping an OKLCH token in a color function (`hsl(var(--chart-1))`, `rgb(var(--primary))`, …), the silent "empty chart that still builds" bug. New `chart-token-color` entry in `HOUSE_RULES`.
+- **JSDoc `@example` on the hot prop surface** — `LineAreaChart`, `PieChart`, `RadialChart`, `RadarChart`, `DataTable`, `StatusBadge`, `StatusDot`, `MetricRow`, `Button`, `ChartPanel`/`MetricChartCard`, `FieldSelect` now carry copyable examples + disambiguation in their `.d.ts`, killing the "grep `dist/*.d.ts` to reverse-engineer props" loop.
+- **New recipes** — `sidebar-dashboard` (canonical no-topbar sidebar dashboard) and `chat-with-drawer` (chat-first + right-side Sheet drawer with a bounded scroll region) in `examples/app-kit`, registered in the blocks catalog.
+
+### Fixed
+
+- **`SheetDescription` / `DialogDescription` no longer cause hydration errors** — they render as a `<div>` (via `asChild`) instead of Radix's default `<p>`, so block-level children (badges, pill rows) are valid HTML.
+- **`lintGeneratedUi` / `formatLintReport` fail loud on misuse** — passing a non-string source (e.g. `{ filename, source }`) or the whole `LintResult` to `formatLintReport` now throws a `TypeError` whose message states the correct signature, instead of silently mis-running.
+
+### Tooling
+
+- Anti-drift test (`src/anti-drift.test.ts`) asserts the `/app`, `/ui`, `/studio` export surface the examples/blueprint depend on (and that `Tabs` / `AppShellTopbar` are NOT exported), so API drift fails a test instead of surfacing as a codegen error.
+- `docs/agent-environment.md` captures the environmental gotchas (`bun x tsc -b` not `npx`, preview vs EFS `node_modules` paths, stale `*.tsbuildinfo`) once, out of the prompt strings.
+
+## [1.6.1] — 2026-06-27
+
+### Fixed
+
+- **recharts charts no longer white-screen under React 19** — recharts 3.6+ stores React elements inside a Redux-Toolkit/`immer` store, and `immer` **11.0.0** froze React 19's Fiber internals, so chart routes crashed with `Cannot assign to read only property 'lanes'`. The crash was always a transitive-dependency mismatch (a stale lockfile pinning `immer@11.0.0`), not a problem with the chart components — `LineAreaChart`, `PieChart`, `RadialChart`, and `RadarChart` are unchanged. The package now forces `immer` to `>=11.0.1` via `overrides`/`resolutions`, deduping to a single safe copy.
+
+### Changed
+
+- **recharts pinned to an exact tested version (`3.8.1`)** so the recharts/Redux-Toolkit/`immer` matrix the package validates against can't float into an untested 3.x range.
+- **`APP_KIT_AGENT_INSTRUCTIONS` charts section** now tells codegen agents that the React 19 chart crash is a dependency override (`"overrides": { "immer": ">=11.0.1" }`), **not** a code change — and to keep using the chart components instead of hand-rolling SVG/CSS charts as a workaround.
+
+### Tooling
+
+- **`check:deps` preflight guard** (`scripts/check-immer.mjs`, wired into CI) fails the build if any installed `immer` falls in the broken `[11.0.0, 11.0.1)` window, turning a silent runtime white-screen into a loud, actionable error. Example apps (`examples/app-kit`, `examples/mock-ui`) carry the same `immer` override.
+
 ## [1.6.0] — 2026-06-26
 
 ### Changed

package/README.md

@@ -40,6 +40,14 @@ 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.
+>
+> **Required for React 19:** pin `immer` to ≥ 11.0.1 in your app. recharts stores React elements in a Redux-Toolkit/immer store, and immer **11.0.0** freezes React 19's Fiber internals — charts crash with `Cannot assign to read only property 'lanes'` (a blank route). Add an override so a stale lockfile can't reintroduce it:
+>
+> ```json
+> { "overrides": { "immer": ">=11.0.1" } }
+> ```
+>
+> Yarn uses `"resolutions"`. Fresh installs already resolve a safe immer; the override just makes it durable.
 
 ### Tailwind setup