@devalok/shilp-sutra 0.34.1 → 0.36.0

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

@@ -1,143 +1,143 @@
-# TopBar
-
-- Import: @devalok/shilp-sutra/shell/top-bar
-- 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
-
-### 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
-    userMenuItems?: UserMenuItem[]
-    className?: string
-
-TopBarUser: { name: string, email?: string, image?: string | null }
-UserMenuItem: { label: string, icon?: ReactNode, href?: string, onClick?: () => void, separator?: boolean, color?: string, badge?: string | boolean, disabled?: boolean }
-
-UserMenuItem fields:
-- href — navigates via onNavigate callback
-- onClick — custom action (takes precedence over href)
-- separator — renders a DropdownMenuSeparator before this item
-- color — semantic text color (e.g. "error" for text-error)
-- badge — string for count badge, true for dot indicator
-- disabled — greys out the item
-
-## Example
-
-### Two-zone (standard)
-```jsx
-<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
-- 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.27.2
-- **Fixed** UserMenu email truncation — long emails now truncate instead of overflowing the dropdown
-
-### v0.7.0
-- **Added** `userMenuItems` prop for custom dropdown items
-
-### v0.1.1
-- **Changed** Decoupled from Next.js via LinkProvider
-- **Fixed** Added `aria-label` to search/AI buttons
-- **Fixed** Added `type="button"` to search/AI/avatar buttons to prevent form submission
-
-### v0.1.0
-- **Added** Initial release
+# TopBar
+
+- Import: @devalok/shilp-sutra/shell/top-bar
+- 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
+
+### 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
+    userMenuItems?: UserMenuItem[]
+    className?: string
+
+TopBarUser: { name: string, email?: string, image?: string | null }
+UserMenuItem: { label: string, icon?: ReactNode, href?: string, onClick?: () => void, separator?: boolean, color?: string, badge?: string | boolean, disabled?: boolean }
+
+UserMenuItem fields:
+- href — navigates via onNavigate callback
+- onClick — custom action (takes precedence over href)
+- separator — renders a DropdownMenuSeparator before this item
+- color — semantic text color (e.g. "error" for text-error)
+- badge — string for count badge, true for dot indicator
+- disabled — greys out the item
+
+## Example
+
+### Two-zone (standard)
+```jsx
+<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
+- 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.27.2
+- **Fixed** UserMenu email truncation — long emails now truncate instead of overflowing the dropdown
+
+### v0.7.0
+- **Added** `userMenuItems` prop for custom dropdown items
+
+### v0.1.1
+- **Changed** Decoupled from Next.js via LinkProvider
+- **Fixed** Added `aria-label` to search/AI buttons
+- **Fixed** Added `type="button"` to search/AI/avatar buttons to prevent form submission
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/accordion.md

@@ -1,51 +1,51 @@
-# Accordion
-
-- Import: @devalok/shilp-sutra/ui/accordion
-- Server-safe: No
-- Category: ui
-
-## Props
-    type: "single" | "multiple" (REQUIRED)
-    defaultValue: string (single) | string[] (multiple)
-    value: string | string[] (controlled)
-    onValueChange: (value) => void
-    collapsible: boolean (only valid when type="single")
-
-## Compound Components
-    Accordion (root)
-      AccordionItem (value: string, REQUIRED)
-        AccordionTrigger (clickable header, chevron auto-renders; chevronPosition: "left" | "right")
-        AccordionContent (collapsible body)
-
-## Defaults
-    none (type is required); AccordionTrigger: chevronPosition="right"
-
-## Example
-```jsx
-<Accordion type="single" defaultValue="item-1" collapsible>
-  <AccordionItem value="item-1">
-    <AccordionTrigger>Question?</AccordionTrigger>
-    <AccordionContent>Answer.</AccordionContent>
-  </AccordionItem>
-</Accordion>
-```
-
-## Gotchas
-- type is REQUIRED — omitting it causes runtime error
-- collapsible only works with type="single"
-
-## Changes
-### v0.29.0
-- **Added** `chevronPosition` prop on AccordionTrigger: `"left"` | `"right"` (default: `"right"`) — controls which side the chevron icon renders
-
-### v0.18.0
-- **Changed** Accordion content fade animation migrated to Framer Motion (height animation still uses CSS keyframes)
-
-### v0.13.0
-- **Added** `accordion-down` and `accordion-up` keyframes added to Tailwind preset using Radix CSS custom properties
-
-### v0.4.2
-- **Added** `AccordionItemProps`, `AccordionTriggerProps`, `AccordionContentProps` type exports
-
-### v0.1.0
-- **Added** Initial release
+# Accordion
+
+- Import: @devalok/shilp-sutra/ui/accordion
+- Server-safe: No
+- Category: ui
+
+## Props
+    type: "single" | "multiple" (REQUIRED)
+    defaultValue: string (single) | string[] (multiple)
+    value: string | string[] (controlled)
+    onValueChange: (value) => void
+    collapsible: boolean (only valid when type="single")
+
+## Compound Components
+    Accordion (root)
+      AccordionItem (value: string, REQUIRED)
+        AccordionTrigger (clickable header, chevron auto-renders; chevronPosition: "left" | "right")
+        AccordionContent (collapsible body)
+
+## Defaults
+    none (type is required); AccordionTrigger: chevronPosition="right"
+
+## Example
+```jsx
+<Accordion type="single" defaultValue="item-1" collapsible>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Question?</AccordionTrigger>
+    <AccordionContent>Answer.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Gotchas
+- type is REQUIRED — omitting it causes runtime error
+- collapsible only works with type="single"
+
+## Changes
+### v0.29.0
+- **Added** `chevronPosition` prop on AccordionTrigger: `"left"` | `"right"` (default: `"right"`) — controls which side the chevron icon renders
+
+### v0.18.0
+- **Changed** Accordion content fade animation migrated to Framer Motion (height animation still uses CSS keyframes)
+
+### v0.13.0
+- **Added** `accordion-down` and `accordion-up` keyframes added to Tailwind preset using Radix CSS custom properties
+
+### v0.4.2
+- **Added** `AccordionItemProps`, `AccordionTriggerProps`, `AccordionContentProps` type exports
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/alert-dialog.md

@@ -1,61 +1,61 @@
-# AlertDialog
-
-- Import: @devalok/shilp-sutra/ui/alert-dialog
-- Server-safe: No
-- Category: ui
-
-## Props
-    open: boolean (controlled)
-    onOpenChange: (open: boolean) => void
-    defaultOpen: boolean
-
-## Compound Components
-    AlertDialog (root)
-      AlertDialogTrigger
-      AlertDialogContent
-        AlertDialogHeader
-          AlertDialogTitle
-          AlertDialogDescription
-        AlertDialogFooter
-          AlertDialogCancel
-          AlertDialogAction
-
-## Defaults
-    none
-
-## Example
-```jsx
-<AlertDialog>
-  <AlertDialogTrigger asChild>
-    <Button color="error">Delete</Button>
-  </AlertDialogTrigger>
-  <AlertDialogContent>
-    <AlertDialogHeader>
-      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
-      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
-    </AlertDialogHeader>
-    <AlertDialogFooter>
-      <AlertDialogCancel>Cancel</AlertDialogCancel>
-      <AlertDialogAction>Delete</AlertDialogAction>
-    </AlertDialogFooter>
-  </AlertDialogContent>
-</AlertDialog>
-```
-
-## Gotchas
-- 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
-- **Fixed** Context provider value wrapped in `useMemo` for performance
-
-### v0.4.2
-- **Fixed** AlertDialogHeader/Footer now wrapped in `React.forwardRef` (matches Dialog/Sheet pattern)
-
-### v0.1.0
-- **Added** Initial release
+# AlertDialog
+
+- Import: @devalok/shilp-sutra/ui/alert-dialog
+- Server-safe: No
+- Category: ui
+
+## Props
+    open: boolean (controlled)
+    onOpenChange: (open: boolean) => void
+    defaultOpen: boolean
+
+## Compound Components
+    AlertDialog (root)
+      AlertDialogTrigger
+      AlertDialogContent
+        AlertDialogHeader
+          AlertDialogTitle
+          AlertDialogDescription
+        AlertDialogFooter
+          AlertDialogCancel
+          AlertDialogAction
+
+## Defaults
+    none
+
+## Example
+```jsx
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button color="error">Delete</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Gotchas
+- 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
+- **Fixed** Context provider value wrapped in `useMemo` for performance
+
+### v0.4.2
+- **Fixed** AlertDialogHeader/Footer now wrapped in `React.forwardRef` (matches Dialog/Sheet pattern)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/alert.md

@@ -1,46 +1,46 @@
-# Alert
-
-- Import: @devalok/shilp-sutra/ui/alert
-- Server-safe: No
-- Category: ui
-
-## Props
-    variant: "subtle" | "filled" | "outline"
-    color: "info" | "success" | "warning" | "error" | "neutral"
-    title: string (optional)
-    onDismiss: () => void (optional, shows X button when provided)
-    children: ReactNode (body text)
-
-## Defaults
-    variant="subtle", color="info"
-
-## Example
-```jsx
-<Alert color="error" title="Save failed" onDismiss={() => setError(null)}>
-  Your changes could not be saved.
-</Alert>
-```
-
-## Gotchas
-- NOT a compound component — use title prop, NOT <AlertTitle>
-- DO NOT use variant="destructive" — use color="error"
-- Renders role="alert" automatically
-- Icon is auto-selected by color (info=circle, success=check, warning=triangle, error=alert)
-
-## Changes
-### v0.31.0
-- **Added** `size` prop: `sm | md | lg`. Default `md` (non-breaking).
-
-### v0.18.0
-- **Changed** Exit animation migrated to Framer Motion
-- **Fixed** `onDismiss` JSDoc documenting it fires after exit animation completes
-- **Changed** OKLCH color token migration
-
-### v0.3.1
-- **Fixed** AlertProps uses `Omit<HTMLAttributes, 'color'>` to resolve TypeScript conflict with CVA `color` variant
-
-### v0.3.0
-- **Changed** (BREAKING) `variant` prop renamed to `color` for semantic intent
-
-### v0.1.0
-- **Added** Initial release
+# Alert
+
+- Import: @devalok/shilp-sutra/ui/alert
+- Server-safe: No
+- Category: ui
+
+## Props
+    variant: "subtle" | "filled" | "outline"
+    color: "info" | "success" | "warning" | "error" | "neutral"
+    title: string (optional)
+    onDismiss: () => void (optional, shows X button when provided)
+    children: ReactNode (body text)
+
+## Defaults
+    variant="subtle", color="info"
+
+## Example
+```jsx
+<Alert color="error" title="Save failed" onDismiss={() => setError(null)}>
+  Your changes could not be saved.
+</Alert>
+```
+
+## Gotchas
+- NOT a compound component — use title prop, NOT <AlertTitle>
+- DO NOT use variant="destructive" — use color="error"
+- Renders role="alert" automatically
+- Icon is auto-selected by color (info=circle, success=check, warning=triangle, error=alert)
+
+## Changes
+### v0.31.0
+- **Added** `size` prop: `sm | md | lg`. Default `md` (non-breaking).
+
+### v0.18.0
+- **Changed** Exit animation migrated to Framer Motion
+- **Fixed** `onDismiss` JSDoc documenting it fires after exit animation completes
+- **Changed** OKLCH color token migration
+
+### v0.3.1
+- **Fixed** AlertProps uses `Omit<HTMLAttributes, 'color'>` to resolve TypeScript conflict with CVA `color` variant
+
+### v0.3.0
+- **Changed** (BREAKING) `variant` prop renamed to `color` for semantic intent
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/aspect-ratio.md

@@ -1,25 +1,25 @@
-# AspectRatio
-
-- Import: @devalok/shilp-sutra/ui/aspect-ratio
-- Server-safe: No
-- Category: ui
-
-## Props
-    ratio: number (e.g. 16/9, 4/3, 1)
-
-## Defaults
-    none
-
-## Example
-```jsx
-<AspectRatio ratio={16 / 9}>
-  <img src="/photo.jpg" alt="Photo" className="object-cover w-full h-full" />
-</AspectRatio>
-```
-
-## Gotchas
-- ratio is a number, not a string — use `16/9` not `"16/9"`
-
-## Changes
-### v0.1.0
-- **Added** Initial release
+# AspectRatio
+
+- Import: @devalok/shilp-sutra/ui/aspect-ratio
+- Server-safe: No
+- Category: ui
+
+## Props
+    ratio: number (e.g. 16/9, 4/3, 1)
+
+## Defaults
+    none
+
+## Example
+```jsx
+<AspectRatio ratio={16 / 9}>
+  <img src="/photo.jpg" alt="Photo" className="object-cover w-full h-full" />
+</AspectRatio>
+```
+
+## Gotchas
+- ratio is a number, not a string — use `16/9` not `"16/9"`
+
+## Changes
+### v0.1.0
+- **Added** Initial release