@devalok/shilp-sutra 0.18.2 → 0.19.0

package/dist/ui/sidebar.js

@@ -98,7 +98,7 @@ const te = i(
       "div",
       {
         className: r(
-          "flex h-full w-[--sidebar-width] flex-col bg-surface-1 text-surface-fg",
+          "flex h-full w-[--sidebar-width] flex-col bg-surface-2 text-surface-fg",
           d
         ),
         ref: u,
@@ -110,7 +110,7 @@ const te = i(
       {
         "data-sidebar": "sidebar",
         "data-mobile": "true",
-        className: "w-[--sidebar-width] bg-surface-1 p-0 text-surface-fg [&>button]:hidden",
+        className: "w-[--sidebar-width] bg-surface-2 p-0 text-surface-fg [&>button]:hidden",
         style: {
           "--sidebar-width": Q
         },
@@ -152,7 +152,7 @@ const te = i(
                 "div",
                 {
                   "data-sidebar": "sidebar",
-                  className: "flex h-full w-full flex-col bg-surface-1 group-data-[variant=floating]:rounded-ds-lg group-data-[variant=floating]:border group-data-[variant=floating]:border-surface-border group-data-[variant=floating]:shadow",
+                  className: "flex h-full w-full flex-col bg-surface-2 group-data-[variant=floating]:rounded-ds-lg group-data-[variant=floating]:border group-data-[variant=floating]:border-surface-border group-data-[variant=floating]:shadow",
                   children: o
                 }
               )
@@ -202,7 +202,7 @@ const re = i(
           "hover:after:bg-surface-border-strong absolute inset-y-0 z-raised hidden w-4 -translate-x-1/2 transition-colors ease-linear after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] group-data-[side=left]:-right-4 group-data-[side=right]:left-0 sm:flex",
           "[[data-side=left]_&]:cursor-w-resize [[data-side=right]_&]:cursor-e-resize",
           "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
-          "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full group-data-[collapsible=offcanvas]:hover:bg-surface-2",
+          "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full group-data-[collapsible=offcanvas]:hover:bg-surface-3",
           "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
           "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
           a
@@ -234,7 +234,7 @@ const de = i(({ className: a, ...e }, t) => /* @__PURE__ */ s(
     ref: t,
     "data-sidebar": "input",
     className: r(
-      "h-ds-sm w-full bg-surface-1 shadow-none focus-visible:ring-2 focus-visible:ring-accent-9",
+      "h-ds-sm w-full bg-surface-2 shadow-none focus-visible:ring-2 focus-visible:ring-accent-9",
       a
     ),
     ...e
@@ -325,7 +325,7 @@ const pe = i(({ className: a, asChild: e = !1, ...t }, d) => /* @__PURE__ */ s(
     ref: d,
     "data-sidebar": "group-action",
     className: r(
-      "hover:bg-surface-2 absolute right-ds-04 top-ds-04 flex aspect-square w-5 items-center justify-center rounded-ds-md p-0 text-surface-fg outline-none ring-accent-9 transition-transform hover:text-surface-fg focus-visible:ring-2 [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
+      "hover:bg-surface-3 absolute right-ds-04 top-ds-04 flex aspect-square w-5 items-center justify-center rounded-ds-md p-0 text-surface-fg outline-none ring-accent-9 transition-transform hover:text-surface-fg focus-visible:ring-2 [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
       "after:absolute after:-inset-2 after:md:hidden",
       "group-data-[collapsible=icon]:hidden",
       a
@@ -371,12 +371,12 @@ const ge = i(
 );
 ge.displayName = "SidebarMenuItem";
 const he = T(
-  "peer/menu-button hover:bg-surface-2 active:bg-accent-2 data-[active=true]:bg-accent-2 data-[state=open]:hover:bg-surface-2 flex w-full items-center gap-ds-03 overflow-hidden rounded-ds-md p-ds-03 text-left outline-none ring-accent-9 transition-[width,height,padding] hover:text-surface-fg focus-visible:ring-2 active:text-surface-fg disabled:pointer-events-none disabled:opacity-action-disabled group-has-[[data-sidebar=menu-action]]/menu-item:pr-ds-07 aria-disabled:pointer-events-none aria-disabled:opacity-action-disabled data-[active=true]:font-medium data-[active=true]:text-surface-fg data-[state=open]:hover:text-surface-fg group-data-[collapsible=icon]:!size-8 group-data-[collapsible=icon]:!p-ds-03 [&>span:last-child]:truncate [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
+  "peer/menu-button hover:bg-surface-3 active:bg-accent-2 data-[active=true]:bg-accent-2 data-[state=open]:hover:bg-surface-3 flex w-full items-center gap-ds-03 overflow-hidden rounded-ds-md p-ds-03 text-left outline-none ring-accent-9 transition-[width,height,padding] hover:text-surface-fg focus-visible:ring-2 active:text-surface-fg disabled:pointer-events-none disabled:opacity-action-disabled group-has-[[data-sidebar=menu-action]]/menu-item:pr-ds-07 aria-disabled:pointer-events-none aria-disabled:opacity-action-disabled data-[active=true]:font-medium data-[active=true]:text-surface-fg data-[state=open]:hover:text-surface-fg group-data-[collapsible=icon]:!size-8 group-data-[collapsible=icon]:!p-ds-03 [&>span:last-child]:truncate [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
   {
     variants: {
       variant: {
-        default: "hover:bg-surface-2 hover:text-surface-fg",
-        outline: "hover:bg-surface-2 bg-surface-1 shadow-[0_0_0_1px_var(--color-surface-border)] hover:text-surface-fg hover:shadow-[0_0_0_1px_var(--color-surface-border-strong)]"
+        default: "hover:bg-surface-3 hover:text-surface-fg",
+        outline: "hover:bg-surface-3 bg-surface-2 shadow-[0_0_0_1px_var(--color-surface-border)] hover:text-surface-fg hover:shadow-[0_0_0_1px_var(--color-surface-border-strong)]"
       },
       size: {
         md: "h-ds-sm text-ds-md",
@@ -445,7 +445,7 @@ const xe = i(({ className: a, asChild: e = !1, showOnHover: t = !1, ...d }, o) =
     ref: o,
     "data-sidebar": "menu-action",
     className: r(
-      "hover:bg-surface-2 absolute right-ds-02 top-ds-02b flex aspect-square w-5 items-center justify-center rounded-ds-md p-0 text-surface-fg outline-none ring-accent-9 transition-transform hover:text-surface-fg focus-visible:ring-2 peer-hover/menu-button:text-surface-fg [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
+      "hover:bg-surface-3 absolute right-ds-02 top-ds-02b flex aspect-square w-5 items-center justify-center rounded-ds-md p-0 text-surface-fg outline-none ring-accent-9 transition-transform hover:text-surface-fg focus-visible:ring-2 peer-hover/menu-button:text-surface-fg [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
       "after:absolute after:-inset-2 after:md:hidden",
       "peer-data-[size=sm]/menu-button:top-1",
       "peer-data-[size=md]/menu-button:top-ds-02b",
@@ -538,7 +538,7 @@ const Me = i(({ asChild: a = !1, size: e = "md", isActive: t, className: d, ...o
     "data-size": e,
     "data-active": t,
     className: r(
-      "hover:bg-surface-2 active:bg-accent-2 flex h-ds-xs-plus min-w-0 -translate-x-px items-center gap-ds-03 overflow-hidden rounded-ds-md px-ds-03 text-surface-fg outline-none ring-accent-9 hover:text-surface-fg focus-visible:ring-2 active:text-surface-fg disabled:pointer-events-none disabled:opacity-action-disabled aria-disabled:pointer-events-none aria-disabled:opacity-action-disabled [&>span:last-child]:truncate [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0 [&>svg]:text-surface-fg",
+      "hover:bg-surface-3 active:bg-accent-2 flex h-ds-xs-plus min-w-0 -translate-x-px items-center gap-ds-03 overflow-hidden rounded-ds-md px-ds-03 text-surface-fg outline-none ring-accent-9 hover:text-surface-fg focus-visible:ring-2 active:text-surface-fg disabled:pointer-events-none disabled:opacity-action-disabled aria-disabled:pointer-events-none aria-disabled:opacity-action-disabled [&>span:last-child]:truncate [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0 [&>svg]:text-surface-fg",
       "data-[active=true]:bg-accent-2 data-[active=true]:text-surface-fg",
       e === "sm" && "text-ds-sm",
       e === "md" && "text-ds-md",

package/docs/components/_header.md

@@ -42,10 +42,10 @@ Color tokens use OKLCH (perceptually uniform) with 12 functional steps per palet
 | 2 | Subtle background | Sidebar, card alt |
 | 3 | Component bg | Input bg, badge bg |
 | 4 | Component bg hover | Button hover state |
-| 5 | Component bg active | Active/pressed state |
-| 6 | Border subtle | Dividers, soft borders |
-| 7 | Border default | Input borders, card borders |
-| 8 | Border strong | Focus rings, emphasis borders |
+| 5 | Border subtle | Semantic `surface-border` in light mode |
+| 6 | Border default | Semantic `surface-border-strong` in light mode |
+| 7 | Border strong | Focus rings, emphasis borders |
+| 8 | Border emphasis | High-contrast outlines |
 | 9 | Solid / accent | Button bg, primary CTA |
 | 10 | Solid hover | Button hover bg |
 | 11 | Low-contrast text | Secondary accent text |
@@ -54,7 +54,9 @@ Color tokens use OKLCH (perceptually uniform) with 12 functional steps per palet
 Semantic layer:
 - Accent (swappable): --color-accent-{1-12} + --color-accent-fg
 - Secondary: --color-secondary-{1-12} + --color-secondary-fg
-- Surface: --color-surface-{1-4} + --color-surface-fg / fg-muted / fg-subtle / border
+- Surface: --color-surface-{1-4} + --color-surface-fg / fg-muted / fg-subtle / border / border-strong
+  - Border mapping: light mode border=step5, border-strong=step6; dark mode border=step3, border-strong=step4
+  - Shell chrome (sidebar, topbar, bottom nav) uses surface-2 for elevation above surface-1 app background
 - Status: --color-{error,success,warning,info}-{3,7,9,11}
 - Category: --color-category-{teal,amber,slate,indigo,cyan,orange,emerald}
 

package/docs/components/composed/activity-feed.md

@@ -6,15 +6,15 @@
 
 ## Props
     items: ActivityItem[] (REQUIRED) — { id, actor?: { name, image? }, action: string|ReactNode, timestamp: Date|string, icon?, color?: 'default'|'success'|'warning'|'error'|'info', detail?: ReactNode }
-    onLoadMore: () => void — "Load more" button callback
+    onLoadMore?: () => void — "Load more" button callback
     loading: boolean — skeleton shimmer
-    hasMore: boolean — shows "Load more" button
-    emptyState: ReactNode — empty state content
+    hasMore?: boolean — shows "Load more" button
+    emptyState?: ReactNode — empty state content
     compact: boolean — tighter spacing, no avatars, smaller text
     maxInitialItems: number — truncate with "Show all (N)" toggle
 
 ## Defaults
-    loading=false, compact=false
+    loading=false, compact=false, hasMore=false
 
 ## Example
 ```jsx

package/docs/components/composed/command-palette.md

@@ -5,7 +5,7 @@
 - Category: composed
 
 ## Props
-    groups: CommandGroup[] — { label: string, items: CommandItem[] }
+    groups?: CommandGroup[] (default: []) — { label: string, items: CommandItem[] }
     placeholder: string (default: "Search or jump to...")
     onSearch: (query: string) => void
     emptyMessage: string (default: "No results found.")
@@ -13,7 +13,7 @@
 CommandItem shape: { id, label, description?, icon?, shortcut?, onSelect: () => void }
 
 ## Defaults
-    placeholder="Search or jump to...", emptyMessage="No results found."
+    placeholder="Search or jump to...", emptyMessage="No results found.", groups=[]
 
 ## Example
 ```jsx

package/docs/components/composed/confirm-dialog.md

@@ -12,7 +12,7 @@
     confirmText: string (default: "Confirm")
     cancelText: string (default: "Cancel")
     color: "default" | "error" (controls confirm button color)
-    loading: boolean (default: false, disables buttons and shows spinner)
+    loading: boolean (default: false, disables buttons and replaces confirm button text with 'Processing...')
     onConfirm: () => void | Promise<void> (REQUIRED)
 
 ## Defaults

package/docs/components/composed/date-picker.md

@@ -7,8 +7,8 @@
 ## Props
 
 ### DatePicker
-    value: Date | null
-    onChange: (date: Date | null) => void
+    value?: Date | null
+    onChange?: (date: Date | null) => void
     placeholder: string (default: "Pick a date")
     formatStr: string (default: "MMM d, yyyy")
     minDate: Date
@@ -17,9 +17,9 @@
     className: string
 
 ### DateRangePicker
-    startDate: Date | null
-    endDate: Date | null
-    onChange: (range: { start: Date | null, end: Date | null }) => void
+    startDate?: Date | null
+    endDate?: Date | null
+    onChange?: (range: { start: Date | null, end: Date | null }) => void
     placeholder: string (default: "Pick a date range")
     formatStr: string (default: "MMM d, yyyy")
     minDate: Date
@@ -40,8 +40,8 @@
     className: string
 
 ### TimePicker
-    value: Date | null (time stored as a Date object)
-    onChange: (date: Date) => void
+    value?: Date | null (time stored as a Date object)
+    onChange?: (date: Date) => void
     format: "12h" | "24h" (default: "12h")
     minuteStep: number (default: 1)
     secondStep: number (default: 1)
@@ -52,14 +52,14 @@
 
 ### CalendarGrid
     currentMonth: Date (REQUIRED)
-    selected: Date | null
-    rangeStart: Date | null
-    rangeEnd: Date | null
-    hoverDate: Date | null
+    selected?: Date | null
+    rangeStart?: Date | null
+    rangeEnd?: Date | null
+    hoverDate?: Date | null
     onSelect: (date: Date) => void (REQUIRED)
-    onHover: (date: Date | null) => void
+    onHover?: (date: Date | null) => void
     onMonthChange: (date: Date) => void (REQUIRED)
-    onHeaderClick: () => void
+    onHeaderClick?: () => void
     disabledDates: (date: Date) => boolean
     minDate: Date
     maxDate: Date

package/docs/components/composed/schedule-view.md

@@ -8,8 +8,8 @@
     view: "day" | "week" (REQUIRED)
     date: Date (REQUIRED — current day or any date in target week)
     events: ScheduleEvent[] (REQUIRED) — { id, title, start: Date, end: Date, color? }
-    onEventClick: (event: ScheduleEvent) => void
-    onSlotClick: (start: Date, end: Date) => void
+    onEventClick?: (event: ScheduleEvent) => void
+    onSlotClick?: (start: Date, end: Date) => void
     startHour: number (default: 8)
     endHour: number (default: 18, exclusive)
     slotDuration: number (minutes, default: 30)

package/docs/components/composed/status-badge.md

@@ -15,6 +15,7 @@ Note: StatusBadge was server-safe prior to v0.18.0 but is NO LONGER server-safe
 
 ## Defaults
     size="md", hideDot=false
+    When neither status nor color is passed, defaults to status='pending' styling
 
 ## Example
 ```jsx

package/docs/components/shell/bottom-navbar.md

@@ -35,6 +35,10 @@ BottomNavbarUser: { name: string, role?: string }
 - Requires LinkProvider for framework-specific link components (e.g., Next.js Link)
 
 ## Changes
+### v0.19.0
+- **Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background
+- **Changed** "More" menu and interactive items bumped accordingly
+
 ### v0.18.0
 - **Fixed** Removed incorrect `role="button"` and `tabIndex` from overlay
 

package/docs/components/shell/notification-center.md

@@ -6,21 +6,21 @@
 
 ## Props
     notifications?: Notification[]
-    unreadCount: number (derived from notifications if not provided)
-    open: boolean (controlled mode)
-    onOpenChange: (open: boolean) => void
-    isLoading: boolean
-    hasMore: boolean
-    onFetchMore: () => void
-    onMarkRead: (id: string) => void
-    onMarkAllRead: () => void
-    onNavigate: (path: string) => void — called when a notification with a route is clicked
-    getNotificationRoute: (notification: Notification) => string | null — returns route for a notification; defaults to () => null
-    footerSlot: ReactNode — content rendered in a sticky footer below the scroll area
-    emptyState: ReactNode — replaces default empty state UI
-    headerActions: ReactNode — extra action buttons after "Mark all read"
-    popoverClassName: string — override default popover dimensions
-    onDismiss: (id: string) => void — when provided, each notification shows a dismiss button
+    unreadCount?: number (derived from notifications if not provided)
+    open?: boolean (controlled mode)
+    onOpenChange?: (open: boolean) => void
+    isLoading?: boolean
+    hasMore?: boolean
+    onFetchMore?: () => void
+    onMarkRead?: (id: string) => void
+    onMarkAllRead?: () => void
+    onNavigate?: (path: string) => void — called when a notification with a route is clicked
+    getNotificationRoute?: (notification: Notification) => string | null — returns route for a notification; defaults to () => null
+    footerSlot?: ReactNode — content rendered in a sticky footer below the scroll area
+    emptyState?: ReactNode — replaces default empty state UI
+    headerActions?: ReactNode — extra action buttons after "Mark all read"
+    popoverClassName?: string — override default popover dimensions
+    onDismiss?: (id: string) => void — when provided, each notification shows a dismiss button
 
 Notification: { id: string, title: string, body?: string | null, tier: 'INFO' | 'IMPORTANT' | 'CRITICAL', isRead: boolean, createdAt: string, entityType?: string | null, entityId?: string | null, projectId?: string | null, project?: { title: string } | null, actions?: NotificationAction[] }
 NotificationAction: { label: string, variant?: 'primary' | 'default' | 'danger', onClick: (id: string) => void }

package/docs/components/shell/sidebar.md

@@ -21,7 +21,7 @@ NavItem: { title: string, href: string, icon: ReactNode, exact?: boolean, badge?
 NavSubItem: { title: string, href: string, icon?: ReactNode, exact?: boolean }
 NavGroup: { label: string, items: NavItem[], action?: ReactNode }
 SidebarUser: { name: string, email?: string, image?: string | null, designation?: string, role?: string }
-SidebarFooterConfig: { links: Array<{ label: string, href: string }>, version: string | { label: string, href: string }, slot: ReactNode, promo: SidebarPromo }
+SidebarFooterConfig: { links?: Array<{ label: string, href: string }>, version?: string | { label: string, href: string }, slot?: ReactNode, promo?: SidebarPromo }
 SidebarPromo: { text: string, icon?: ReactNode, action?: { label: string, href?: string, onClick?: () => void }, onDismiss?: () => void }
 
 ## Defaults
@@ -57,6 +57,10 @@ SidebarPromo: { text: string, icon?: ReactNode, action?: { label: string, href?:
 - Badge numbers > 99 display as "99+"
 
 ## Changes
+### v0.19.0
+- **Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background
+- **Changed** Interactive hover states bumped from `surface-2` to `surface-3`
+
 ### v0.18.0
 - **Fixed** `bg-interactive-subtle` changed to `bg-accent-2` (OKLCH migration)
 

package/docs/components/shell/top-bar.md

@@ -4,16 +4,54 @@
 - Server-safe: No
 - Category: shell
 
+## Overview
+
+Composition-based application top bar. Uses dot-notation subcomponents for flexible layout.
+
+## Subcomponents
+
+| Component | Purpose |
+|-----------|---------|
+| `TopBar` | Root — bg-surface-2, border-b, sticky. Auto-switches to grid when Center is present. |
+| `TopBar.Left` | Left zone — sidebar trigger, title, breadcrumbs |
+| `TopBar.Center` | Optional center zone — search bar, tabs. Triggers 3-column grid layout. |
+| `TopBar.Right` | Right zone — action buttons, user menu. Gets ml-auto in flex mode. |
+| `TopBar.Section` | Groups items with configurable gap |
+| `TopBar.IconButton` | Circular icon button with tooltip (bg-surface-3, hover:bg-surface-4) |
+| `TopBar.Title` | Page title heading, hidden on mobile |
+| `TopBar.UserMenu` | Avatar dropdown with color mode toggle, profile, logout |
+
 ## Props
-    pageTitle?: string (default: "")
-    user?: TopBarUser | null — { name, email?, image? }
+
+### TopBar (root)
+    children: ReactNode
+    className?: string
+
+### TopBar.Left / TopBar.Center / TopBar.Right
+    children: ReactNode
+    className?: string
+
+### TopBar.Section
+    gap?: "tight" | "default" | "loose" (default: "default")
+    children: ReactNode
+    className?: string
+
+Gap values: tight = gap-ds-02, default = gap-ds-04, loose = gap-ds-06
+
+### TopBar.IconButton
+    icon: ReactNode
+    tooltip: string
+    ...ButtonHTMLAttributes
+
+### TopBar.Title
+    children: ReactNode
+    className?: string
+
+### TopBar.UserMenu
+    user: TopBarUser — { name, email?, image? }
     onNavigate?: (path: string) => void
     onLogout?: () => void
-    onSearchClick?: () => void
-    onAiChatClick?: () => void
-    mobileLogo?: ReactNode
-    notificationSlot?: ReactNode (render NotificationCenter here)
-    userMenuItems?: UserMenuItem[] — custom items between Profile and Dark/Light Mode toggle
+    userMenuItems?: UserMenuItem[]
     className?: string
 
 TopBarUser: { name: string, email?: string, image?: string | null }
@@ -27,30 +65,69 @@ UserMenuItem fields:
 - badge — string for count badge, true for dot indicator
 - disabled — greys out the item
 
-## Defaults
-    None
-
 ## Example
+
+### Two-zone (standard)
 ```jsx
-<TopBar
-  pageTitle="Dashboard"
-  user={{ name: 'John', email: 'john@example.com' }}
-  onNavigate={(p) => router.push(p)}
-  onLogout={handleLogout}
-  notificationSlot={<NotificationCenter notifications={notifications} />}
-  userMenuItems={[
-    { label: 'Changelog', icon: <IconNews />, href: '/changelog', badge: '3' },
-    { label: 'Shortcuts', icon: <IconKeyboard />, onClick: () => openModal() },
-  ]}
-/>
+<TopBar>
+  <TopBar.Left>
+    <SidebarTrigger />
+    <TopBar.Title>Dashboard</TopBar.Title>
+  </TopBar.Left>
+  <TopBar.Right>
+    <TopBar.Section gap="tight">
+      <TopBar.IconButton icon={<IconSearch />} tooltip="Search (Ctrl+K)" onClick={openSearch} />
+      <NotificationCenter notifications={notifications} />
+      <TopBar.IconButton icon={<IconSparkles />} tooltip="AI Chat" onClick={openAI} />
+    </TopBar.Section>
+    <TopBar.UserMenu
+      user={{ name: 'John', email: 'john@example.com' }}
+      onNavigate={(p) => router.push(p)}
+      onLogout={handleLogout}
+      userMenuItems={[
+        { label: 'Changelog', icon: <IconNews />, href: '/changelog', badge: '3' },
+      ]}
+    />
+  </TopBar.Right>
+</TopBar>
+```
+
+### Three-zone (centered search bar)
+```jsx
+<TopBar>
+  <TopBar.Left>
+    <SidebarTrigger />
+    <TopBar.Title>Dashboard</TopBar.Title>
+  </TopBar.Left>
+  <TopBar.Center>
+    <SearchBarTrigger />
+  </TopBar.Center>
+  <TopBar.Right>
+    <TopBar.Section gap="tight">
+      <TopBar.IconButton icon={<IconBell />} tooltip="Notifications" onClick={fn} />
+    </TopBar.Section>
+    <TopBar.UserMenu user={user} onLogout={logout} />
+  </TopBar.Right>
+</TopBar>
 ```
 
 ## Gotchas
-- `notificationSlot` is where NotificationCenter should be rendered
-- `userMenuItems` are inserted between the Profile link and the Dark/Light Mode toggle in the user dropdown
-- Requires LinkProvider for framework-specific navigation
+- Without `TopBar.Center`, layout is flex (two-zone). With it, layout switches to CSS grid `1fr auto 1fr` for true centering.
+- `TopBar.IconButton` renders any number of action buttons — no artificial limit. Use responsive hiding (`className="hidden md:flex"`) for mobile.
+- `TopBar.UserMenu` includes Profile link, color mode toggle, and logout automatically. `userMenuItems` are inserted between Profile and the toggle.
+- Requires SidebarProvider wrapper for SidebarTrigger to work.
 
 ## Changes
+### v0.19.0
+- **BREAKING** Rewritten as composition API. Old props-based API removed (`pageTitle`, `onSearchClick`, `onAiChatClick`, `notificationSlot`, `mobileLogo` props).
+- **Added** `TopBar.Left`, `TopBar.Center`, `TopBar.Right` zone components
+- **Added** `TopBar.Section` with `gap` prop (`tight` | `default` | `loose`)
+- **Added** `TopBar.IconButton` — reusable circular icon button with tooltip
+- **Added** `TopBar.Title` — responsive page title (hidden on mobile)
+- **Added** `TopBar.UserMenu` — extracted user dropdown as standalone subcomponent
+- **Added** Auto grid/flex layout detection based on Center zone presence
+- **Changed** Background elevated from `bg-surface-1` to `bg-surface-2`
+
 ### v0.7.0
 - **Added** `userMenuItems` prop for custom dropdown items
 

package/docs/components/ui/autocomplete.md

@@ -7,7 +7,7 @@
 ## Props
     options: AutocompleteOption[] (REQUIRED) — { value: string, label: string }
     value: AutocompleteOption | null
-    onValueChange: (option: AutocompleteOption) => void
+    onValueChange?: (option: AutocompleteOption) => void
     placeholder: string
     emptyText: string (default: "No options")
     disabled: boolean

package/docs/components/ui/banner.md

@@ -23,6 +23,7 @@
 ## Gotchas
 - Banner is full-width (spans container). Alert is inline.
 - Renders role="alert" automatically
+- `onDismiss` fires after the exit animation completes, not immediately on dismiss button click
 
 ## Changes
 ### v0.3.1

package/docs/components/ui/chip.md

@@ -30,6 +30,7 @@
 - MUST use label prop — children are NOT rendered
 - `<Chip>text</Chip>` is WRONG — use `<Chip label="text" />`
 - Wrap dynamic chip lists in `<ChipGroup>` for exit animations
+- `color="primary"` will be renamed to `color="brand"` in v1.0 — use `color="primary"` for now
 
 ## Changes
 ### v0.4.2

package/docs/components/ui/combobox.md

@@ -7,8 +7,8 @@
 ## Props
     options: ComboboxOption[] (REQUIRED) — { value: string, label: string, description?: string, icon?: ReactNode, disabled?: boolean }
     DISCRIMINATED UNION — type depends on `multiple` flag:
-    Single (default): multiple?: false, value: string, onValueChange: (value: string) => void
-    Multiple: multiple: true, value: string[], onValueChange: (value: string[]) => void
+    Single (default): multiple?: false, value?: string, onValueChange: (value: string) => void
+    Multiple: multiple: true, value?: string[], onValueChange: (value: string[]) => void
     placeholder: string (default: "Select...")
     searchPlaceholder: string (default: "Search...")
     emptyMessage: string (default: "No results found")

package/docs/components/ui/input.md

@@ -26,7 +26,7 @@
 - HTML native "size" attribute is excluded — use CSS width instead
 - state="error" sets aria-invalid automatically
 - Inside FormField: auto-inherits state, aria-describedby, aria-required from context (explicit props override)
-- Resting border is border-subtle (soft); focus ring is ring-1 at 50% opacity (v0.12.0)
+- Resting border is border-subtle (soft); focus ring is `ring-1 ring-accent-7` (v0.12.0)
 - All sizes (sm, md, lg) use text-ds-md (14px) font — size only affects height and padding (v0.15.0)
 
 ## Changes

package/docs/components/ui/spinner.md

@@ -10,6 +10,7 @@
     variant: "filled" | "bare"
     delay: number (ms — render delay to avoid flicker on fast operations)
     onComplete: () => void (callback after success/error state transition)
+    className: string
 
 ## Defaults
     size: "md"

package/docs/components/ui/tabs.md

@@ -43,7 +43,7 @@
 
 ## Gotchas
 - variant goes on TabsList, NOT on individual TabsTrigger (propagates via context)
-- DO NOT put variant on TabsTrigger — it inherits from TabsList
+- Normally omit `variant` on TabsTrigger — it inherits from TabsList via context. You CAN set it per-trigger to override.
 
 ## Changes
 ### v0.18.0