@timbal-ai/timbal-react 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `@timbal-ai/timbal-react` are documented here.
 
 ## [Unreleased]
 
+## [1.6.0] — 2026-06-26
+
+### Changed
+
+- **Condensed layout density across all UI primitives** — heights, paddings, and gaps were stepped down one notch library-wide for a tighter, more data-dense default. Driven from the shared tokens (`CONTROL_SIZE` h-10→h-9 / h-9→h-8 in `src/design/control-surface.ts`, `TOPBAR_HEIGHT_PX` 48→44 and `PILL_HEIGHT_PX` 40→36 in `src/design/tokens.ts`, `TIMBAL_V2_SIZE_HEIGHT`/`SIZE_ICON`/`SIZE_LABEL_PX` in `src/design/button-tokens.ts`, segmented-control paddings in `src/design/pill-segmented-classes.ts`) and applied consistently to `Button`, `UntitledButton`, `Card`, `Table`, `Alert`, `Dialog`, `Sheet`, `Popover`, `Accordion`, `Select`, `DropdownMenu`, `Menubar`, `Command`, `TagInput`, `Toolbar`, `Toast`, `Avatar`, `Calendar`, `Textarea`, `CopyButton`, `Snippet`, `InputOTP`, and `Breadcrumb`. Non-breaking: all component APIs and size variant names are unchanged.
+
+### Fixed
+
+- **Badges no longer stretch inside flex-column layouts** — `StatusBadge` (`src/app/surfaces/StatusBadge.tsx`) and the artifact `badge` node (`src/artifacts/ui/nodes.tsx`) now carry `w-fit shrink-0`, so a badge placed in a vertical flex container (e.g. a `Kanban` card) hugs its label instead of expanding to the full column width.
+
+## [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`) — `FilterDropdown` is a **data-driven** multi-facet filter popover: pass `fields` describing your actual columns (`multiselect` / `text` / `daterange` / `numeric`) and it adapts to the table's content. State is keyed by field `id`, controlled (`value` + `onChange`) or uncontrolled (`defaultValue`); every control is on the shared control-surface contract. It renders **removable active-filter pills** (with "Clear all") next to the trigger by default (`showActiveChips`). `FilterField` is the labeled single-control wrapper for `FilterBar`.
+- **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.
+
+### Agent instructions & exports
+
+- **`SITE_AGENT_INSTRUCTIONS`** — a new codegen prompt (exported from `./site` and the package root) documenting the `/site` motion primitives, their props, reduced-motion/SSR guarantees, and dosing/anti-overuse guidance.
+- **`/site` primitives re-exported from the package root** — `Reveal`, `TextReveal`, `Parallax`, `Marquee`, `Magnetic` (plus the `EASE` / `DURATION` / `SPRING` motion tokens) are now reachable from both `@timbal-ai/timbal-react` and `@timbal-ai/timbal-react/site`, matching `/studio`, `/app`, and `/ui`.
+- **`APP_KIT_AGENT_INSTRUCTIONS` expanded** — documents `FilterDropdown` and surfaces the new dependency-free `/ui` primitives (`Stepper`, `Rating`, `NumberField`, `TagInput`, `AvatarGroup`, `CircularProgress`, `CopyButton`, `Snippet`) so codegen agents discover them.
+
 ## [1.4.0] — 2026-06-05
 
 ### Added

package/README.md

@@ -11,6 +11,7 @@ React components and runtime for building Timbal chat UIs and studio apps. Drop
 | `@timbal-ai/timbal-react/studio` | Studio chrome — `TimbalChatShell`, `TimbalStudioShell`, sidebar |
 | `@timbal-ai/timbal-react/ui` | Primitives — `Button`, `Dialog`, `DropdownMenu`, `Popover`, `Select`, `Tooltip`, `Avatar`, `Shimmer` |
 | `@timbal-ai/timbal-react/app` | Dashboards — `AppShell`, `Page`, `DataTable`, `StatTile`, … |
+| `@timbal-ai/timbal-react/site` | Marketing/brand motion — `Reveal`, `TextReveal`, `Parallax`, `Marquee`, `Magnetic` |
 | `@timbal-ai/timbal-react/styles.css` | Theme tokens (required once) |
 
 ### API tiers
@@ -342,12 +343,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>
   );
@@ -961,6 +976,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.
 
@@ -968,6 +984,30 @@ All primitives are Radix-backed (via the unified `radix-ui` package) or thin wra
 
 ---
 
+## Site kit (`@timbal-ai/timbal-react/site`)
+
+Expressive **motion & interaction primitives** for marketing, brand, landing, and editorial pages — the counterpart to the `/app` dashboard kit. They animate whatever you put inside them (mechanics, not art direction), are **reduced-motion-aware** and **SSR-safe**, and build on the bundled `motion` engine (no extra dependencies).
+
+```tsx
+import { Reveal, TextReveal, Parallax, Marquee, Magnetic } from "@timbal-ai/timbal-react/site";
+```
+
+- **`Reveal`** — fade/slide a block in as it scrolls into view. `variant` (`fade` / `fade-up` / `fade-down` / `fade-left` / `fade-right` / `blur` / `scale` / `mask-up`), `delay`, `duration`, `distance`, `amount`, `repeat`, `as`.
+- **`TextReveal`** — editorial headline entrance; a **string** child rides up token-by-token from a clip. `splitBy` (`words` / `lines`), `stagger`, `delay`, `duration`, `amount`, `repeat`, `as` (`span` / `h1`–`h4` / `p`).
+- **`Parallax`** — translate a layer relative to scroll for depth. `speed` (-0.6…0.6), `axis` (`x` / `y`), `smooth`.
+- **`Marquee`** — seamless infinite scrolling row (logo walls, tickers). `speed`, `direction`, `pauseOnHover`, `gap`.
+- **`Magnetic`** — pointer-following affordance for a single interactive child (primary CTA / nav). `strength`, `max`, `spring`.
+
+Motion tokens `EASE`, `DURATION`, and `SPRING` are exported for custom `motion` work that should match the kit's feel. For codegen agents, inject **`SITE_AGENT_INSTRUCTIONS`** (component menu + dosing guidance) into the system prompt:
+
+```ts
+import { SITE_AGENT_INSTRUCTIONS } from "@timbal-ai/timbal-react/site";
+```
+
+Use `/site` for the marketing/brand surface — not dashboards (`/app`) or in-chat widgets (artifacts).
+
+---
+
 ## Full example
 
 App shell with optional auth, using `TimbalChatShell` (agent list + chat in one component):
@@ -1045,7 +1085,6 @@ Compose a data UI with a **floating** copilot — main content stays full width:
 ```tsx
 import {
   AppShell,
-  AppShellTopbar,
   AppCopilotProvider,
   AppChatPanel,
   Page,
@@ -1057,7 +1096,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" />
         }