@devalok/shilp-sutra 0.18.2 → 0.19.0

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.18.2
+> Version: 0.19.0
 
 ---
 
@@ -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}
 
@@ -273,7 +275,7 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## 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
@@ -419,6 +421,7 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## 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
@@ -707,6 +710,7 @@ import { BarChart } from '@devalok/shilp-sutra/ui/charts'
 - 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
@@ -832,8 +836,8 @@ import { BarChart } from '@devalok/shilp-sutra/ui/charts'
 ## 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")
@@ -1362,7 +1366,7 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 - 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
@@ -2163,6 +2167,7 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
     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"
@@ -2476,7 +2481,7 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 
 ## 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
@@ -2891,15 +2896,15 @@ export default function RootLayout({ children }) {
 
 ## 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
@@ -2965,7 +2970,7 @@ export default function RootLayout({ children }) {
 - 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.")
@@ -2973,7 +2978,7 @@ export default function RootLayout({ children }) {
 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
@@ -3012,7 +3017,7 @@ CommandItem shape: { id, label, description?, icon?, shortcut?, onSelect: () =>
     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
@@ -3089,8 +3094,8 @@ const [open, setOpen] = useState(false)
 ## 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
@@ -3099,9 +3104,9 @@ const [open, setOpen] = useState(false)
     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
@@ -3122,8 +3127,8 @@ const [open, setOpen] = useState(false)
     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)
@@ -3134,14 +3139,14 @@ const [open, setOpen] = useState(false)
 
 ### 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
@@ -3591,8 +3596,8 @@ MentionItem: { id: string; label: string; avatar?: string }
     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)
@@ -3670,6 +3675,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
@@ -3784,6 +3790,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
 
@@ -3892,21 +3902,21 @@ import Link from 'next/link'
 
 ## 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 }
@@ -4012,7 +4022,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
@@ -4048,6 +4058,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)
 
@@ -4083,16 +4097,54 @@ SidebarPromo: { text: string, icon?: ReactNode, action?: { label: string, href?:
 - 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 }
@@ -4106,30 +4158,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/llms.txt

@@ -245,7 +245,7 @@ NOTIFICATION SELECTION GUIDE:
 - Page skeletons: DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton (no props, server-safe)
 
 ### Shell Components (app-level layout)
-- TopBar: pageTitle, user, onNavigate, onLogout, notificationSlot, mobileLogo, userMenuItems?(UserMenuItem[]). Types: TopBarUser = { name, email?, image? }, UserMenuItem = { label, icon?, href?, onClick?, separator?, color?, badge?, disabled? }
+- TopBar: Composition-based. Subcomponents: TopBar.Left, TopBar.Center (optional, triggers grid), TopBar.Right, TopBar.Section(gap: tight|default|loose), TopBar.IconButton(icon, tooltip), TopBar.Title, TopBar.UserMenu(user, onNavigate?, onLogout?, userMenuItems?). Types: TopBarUser = { name, email?, image? }, UserMenuItem = { label, icon?, href?, onClick?, separator?, color?, badge?, disabled? }
 - AppSidebar: navigation tree with NavItem[], NavGroup[]. Types: NavItem = { title, href, icon, exact?, badge?, children?, defaultOpen? }, NavSubItem = { title, href, icon?, exact? }, NavGroup = { label, items, action? }, SidebarUser = { name, email?, image?, designation?, role? }
 
 ### AppSidebar (v0.10.0 additions)