@timbal-ai/timbal-react 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to `@timbal-ai/timbal-react` are documented here.
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-06-26
+
+### Added
+
+- **`Kanban` board primitive** (`src/ui/kanban.tsx`) — A fully-featured, highly accessible Kanban board with column customization, drag-and-drop capabilities powered by `@dnd-kit`, and a read-only mode for static board rendering.
+- **App density system** (`src/app/layout/app-density-context.tsx`, `src/design/app-density.ts`) — Context-driven density controls supporting "standard" and "compact" layouts. Compact mode cascades tighter padding, smaller text, and lower default heights to descendant components (pages, charts, tables).
+- **Advanced filtering** (`src/app/data/FilterDropdown.tsx`, `src/app/data/FilterField.tsx`) — Rich multi-level filter dropdowns with searchable sub-menus and filter fields for complex data querying.
+- **Site/Marketing primitives** (`src/site/`) — A brand new `./site` subpath export containing five high-quality interactive and marketing-grade components:
+  - **`Magnetic`** — magnetic hover effect that pulls elements toward the cursor.
+  - **`Marquee`** — high-performance, infinite scrolling marquee.
+  - **`Parallax`** — scroll-driven parallax container with custom speed factors.
+  - **`Reveal`** — scroll or entrance fade-in reveal with custom directions and delays.
+  - **`TextReveal`** — character-by-character or word-by-word scroll-reveal animations.
+
+## [1.4.0] — 2026-06-05
+
+### Added
+
+- **`AppShell contentFill`** — makes the content region a bounded, non-scrolling flex column instead of the default padded scroll area. For full-bleed pages that own their own scroll (a full-page chat, a canvas, an editor, a split master–detail view): a `h-full` / `flex-1 min-h-0` child now fills exactly and a pinned footer (the chat composer) stays put instead of riding down on scroll. No `mainClassName` surgery and no `h-[calc(100dvh-…)]` guesses required.
+- **`Page fill`** — makes a `Page` a `min-h-0 flex-1` flex column (pair with `AppShell contentFill` for full-height content). Give the fill child `min-h-0 flex-1`.
+- **Headerless `Page`** — `Page.title` (and `PageHeader.title`) is now optional. Omit it to render a page with no `<h1>` header row (and no header padding), instead of dropping `Page` entirely to lose a heading.
+- **New layout recipes** (`examples/app-kit/src/recipes/`): **full-page chat** (`contentFill` + headerless `fill` + `TimbalChat`), **split view** (master–detail two-pane), and **bento dashboard** (asymmetric `SurfaceCard`/`ChartPanel`/`StatTile` grid) — surfaced in the Blocks gallery and `APP_KIT_AGENT_INSTRUCTIONS` as distinct layout archetypes so generated UIs vary beyond the single sidebar+topbar+MetricRow+table shape.
+
+### Changed
+
+- **`AppShell` `main` is now a bounded flex column by default** (`flex min-h-0 flex-col`, keeping `pb-8 md:pb-10`). Previously the content `main` was content-sized, so every full-height child had to pass `mainClassName="flex min-h-0 flex-col"` to undo a layout deficiency; `h-full` / `flex-1` children now resolve a height out of the box. Scrolling `Page` content is unaffected (the outer scroll region still scrolls).
+- **`APP_KIT_AGENT_INSTRUCTIONS`** documents a **Layout archetypes** menu (sidebar dashboard, focused, bento overview, split master–detail, full-page chat/canvas, copilot overlay, section-switcher) and the full-height contract (`contentFill` / `fill` / headerless `Page`), steering codegen away from shipping the same layout every time and away from `h-[calc(100dvh-…)]` / `min-h-[…]` sizing hacks.
+
+### Fixed
+
+- **`FieldSwitch` / `FieldSelect` id collision** — these derived their input id from `id ?? name ?? "switch"`, so multiple unlabeled instances all rendered `id="switch"` and toggling one flipped the others (and labels mis-associated). They now fall back to a `useId()`-generated id, so every instance is unique by default. `FieldInput` / `FieldTextarea` get the same `useId()` fallback (fixes silent label/control mis-association when no `name` is set).
+
 ## [1.3.0] — 2026-06-04
 
 ### Added

package/README.md

@@ -342,12 +342,26 @@ function MyShell() {
 To inset a main column that follows the sidebar as it collapses, use `AppShell`, which wires the tracking automatically:
 
 ```tsx
-import { AppShell, StudioSidebar } from "@timbal-ai/timbal-react";
+import { AppShell, StudioSidebar, useAppShellNav } from "@timbal-ai/timbal-react";
+
+// Rendered inside AppShell, so it can read the shell's mobile-nav controls and
+// wire the drawer. The sidebar already closes itself on selection (mobile).
+function Sidebar({ agent, onSelect }: { agent: string; onSelect: (id: string) => void }) {
+  const nav = useAppShellNav();
+  return (
+    <StudioSidebar
+      selectedId={agent}
+      onSelect={onSelect}
+      mobileOpen={nav.open}
+      onMobileOpenChange={nav.setOpen}
+    />
+  );
+}
 
 function MyShell() {
   const [agent, setAgent] = useState("agent-a");
   return (
-    <AppShell sidebar={<StudioSidebar selectedId={agent} onSelect={setAgent} />}>
+    <AppShell sidebar={<Sidebar agent={agent} onSelect={setAgent} />}>
       {/* main content insets + animates with the sidebar */}
     </AppShell>
   );
@@ -356,6 +370,16 @@ function MyShell() {
 
 For a fully custom shell, drive your own offset from `StudioSidebar`'s `onInsetChange` callback, which fires with the live inset width (px) whenever the collapse state changes.
 
+The `AppShell` content region is a padded scroll area by default. For a **full-bleed page that fills the viewport** (a full-page chat, a canvas, an editor, a split master–detail view), pass `contentFill` to `AppShell` and `fill` to `Page` (omit `Page.title` for a headerless page), then give the filling child `min-h-0 flex-1` — the composer / footer stays pinned and you avoid `h-[calc(100dvh-…)]` guesses:
+
+```tsx
+<AppShell contentFill>
+  <Page fill>
+    <TimbalChat workforceId="…" className="min-h-0 flex-1" />
+  </Page>
+</AppShell>
+```
+
 ### 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:
@@ -951,6 +975,7 @@ import { controlClass, overlaySurfaceClass, overlayItemClass } from "@timbal-ai/
 - **Layout / disclosure:** `Accordion` · `AccordionItem` · `AccordionTrigger` · `AccordionContent` · `Separator` · `AspectRatio`
 - **Input chrome:** `InputGroup` (+ addon/control/text) · `Spinner`
 - **More primitives:** `AvatarGroup` (overflow stack) · `Stepper` (wizard progress) · `Timeline` (event rail) · `Rating` (stars) · `NumberField` (stepper input) · `TagInput` (chips) · `Banner` (page notice) · `CopyButton` · `Snippet` (code + copy) · `CircularProgress` (SVG ring) — all dependency-free, on the shared tokens / control surface
+- **`Kanban`** (drag-and-drop board) — accessible columns + cards on `@dnd-kit` (pointer **and** keyboard sensors, cross-column moves, empty-column drop zones, drag overlay). Controlled (`columns` + `onColumnsChange`) or uncontrolled (`defaultColumns`); `onMove` reports `{ card, from, to }`. Variants: `density`, column `tone`, `cardVariant`. Requires the peer deps `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities`.
 
 **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.
 
@@ -1035,7 +1060,6 @@ Compose a data UI with a **floating** copilot — main content stays full width:
 ```tsx
 import {
   AppShell,
-  AppShellTopbar,
   AppCopilotProvider,
   AppChatPanel,
   Page,
@@ -1047,7 +1071,7 @@ export function OperationsApp() {
     <AppCopilotProvider value={{ page: "Operations", tab: "overview" }}>
       <AppShell
         sidebar={<StudioSidebar /* … */ />}
-        topbar={<AppShellTopbar actions={<ModeToggle />} />}
+        topbar={<div className="flex justify-end p-4"><ModeToggle /></div>}
         chat={
           <AppChatPanel workforceId="your-workforce-id" />
         }