@devalok/shilp-sutra 0.18.2 → 0.19.1

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/alert-dialog.md

@@ -46,6 +46,9 @@
 - AlertDialogAction does NOT have color="error" styling — add it yourself via className or wrap a Button
 
 ## Changes
+### v0.19.1
+- **Fixed** AlertDialog not centered after Framer Motion animation completes — same `transform: none` fix as Dialog.
+
 ### v0.18.0
 - **Changed** Overlay animations migrated to Framer Motion (physics-based springs)
 - **Added** `AlertDialogContentProps`, `AlertDialogActionProps`, `AlertDialogCancelProps` type exports

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,8 +30,12 @@
 - 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.19.1
+- **Fixed** `active:scale-95` tap feedback broken by Framer Motion transform override — replaced with `whileTap={{ scale: 0.95 }}`
+
 ### v0.4.2
 - **Changed** (BREAKING) `variant="filled"` renamed to `"subtle"`, `variant="outlined"` renamed to `"outline"`, `onDelete` renamed to `onDismiss`
 

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/dialog.md

@@ -39,6 +39,9 @@
 - DialogTitle is required for accessibility — screen readers announce it when the dialog opens
 
 ## Changes
+### v0.19.1
+- **Fixed** Dialog not centered after Framer Motion animation completes — `transform: none` inline style overrode Tailwind `translate-x/y` classes. Centering now handled via Framer Motion `x`/`y` properties.
+
 ### v0.18.0
 - **Changed** Overlay animations migrated to Framer Motion (physics-based springs)
 - **Added** `DialogContentProps`, `DialogTitleProps` type exports

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