@devalok/shilp-sutra 0.18.1 → 0.18.2

package/docs/components/ui/label.md

@@ -0,0 +1,25 @@
+# Label
+
+- Import: @devalok/shilp-sutra/ui/label
+- Server-safe: No
+- Category: ui
+
+## Props
+    required: boolean (shows red asterisk)
+    htmlFor: string
+    (plus standard Radix Label props)
+
+## Example
+```jsx
+<Label htmlFor="email" required>Email Address</Label>
+```
+
+## Gotchas
+- Use with FormField for automatic aria wiring
+
+## Changes
+### v0.2.0
+- **Fixed** Children rendering verified and covered by tests — issue was caused by `@primitives` type leak, not a runtime bug
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/link.md

@@ -0,0 +1,29 @@
+# Link
+
+- Import: @devalok/shilp-sutra/ui/link
+- Server-safe: No
+- Category: ui
+
+## Props
+    inline: boolean (default: true — "inline" or "block" display)
+    asChild: boolean (merge with child element, e.g. Next.js Link)
+    (plus standard anchor attributes)
+
+## Defaults
+    inline: true
+
+## Example
+```jsx
+<Link href="/docs">Documentation</Link>
+<Link asChild><NextLink href="/about">About</NextLink></Link>
+```
+
+## Gotchas
+- Use asChild with framework-specific Link components (e.g. Next.js Link)
+
+## Changes
+### v0.18.0
+- **Fixed** Color tokens — `text-info-9` changed to `text-accent-11` (links are interactive = accent scale)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/menubar.md

@@ -0,0 +1,44 @@
+# Menubar
+
+- Import: @devalok/shilp-sutra/ui/menubar
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    Menubar (root)
+      MenubarMenu
+        MenubarTrigger
+        MenubarContent
+          MenubarItem (+ MenubarShortcut)
+          MenubarCheckboxItem
+          MenubarRadioGroup > MenubarRadioItem
+          MenubarLabel
+          MenubarSeparator
+          MenubarSub > MenubarSubTrigger, MenubarSubContent
+
+## Example
+```jsx
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New<MenubarShortcut>Ctrl+N</MenubarShortcut></MenubarItem>
+      <MenubarSeparator />
+      <MenubarItem>Exit</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+## Gotchas
+- Follows the standard Radix Menubar compound pattern
+
+## Changes
+### v0.18.0
+- **Added** `MenubarContentProps`, `MenubarItemProps` type exports
+
+### v0.14.0
+- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes content rendering behind Sheet/Dialog overlays
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/navigation-menu.md

@@ -0,0 +1,46 @@
+# NavigationMenu
+
+- Import: @devalok/shilp-sutra/ui/navigation-menu
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    NavigationMenu (root)
+      NavigationMenuList
+        NavigationMenuItem
+          NavigationMenuTrigger (for items with content panels)
+          NavigationMenuContent (dropdown panel)
+          NavigationMenuLink (for direct links)
+      NavigationMenuIndicator
+      NavigationMenuViewport
+
+## Example
+```jsx
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <ul>...</ul>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+    <NavigationMenuItem>
+      <NavigationMenuLink href="/about">About</NavigationMenuLink>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+## Gotchas
+- Uses Framer Motion for enter/exit animations (v0.18.0)
+
+## Changes
+### v0.18.0
+- **Changed** Migrated to Framer Motion for enter/exit animations
+- **Added** `NavigationMenuProps`, `NavigationMenuContentProps` type exports
+
+### v0.1.1
+- **Fixed** Token compliance — icon sizes replaced with `h-ico-sm w-ico-sm`
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/number-input.md

@@ -0,0 +1,44 @@
+# NumberInput
+
+- Import: @devalok/shilp-sutra/ui/number-input
+- Server-safe: No
+- Category: ui
+
+## Props
+    value: number (default: 0)
+    onValueChange: (value: number) => void
+    min: number
+    max: number
+    step: number (default: 1)
+    disabled: boolean
+
+## Defaults
+    value: 0
+    step: 1
+    min: Number.MIN_SAFE_INTEGER
+    max: Number.MAX_SAFE_INTEGER
+
+## Example
+```jsx
+<NumberInput value={qty} onValueChange={setQty} min={1} max={99} />
+```
+
+## Gotchas
+- Controlled only — buttons won't work without onValueChange
+
+## Changes
+### v0.18.0
+- **Fixed** Replaced `parseInt` with `Number()`, handle empty input
+
+### v0.15.0
+- **Changed** `md` size font standardized to `text-ds-md` (14px)
+
+### v0.8.0
+- **Fixed** FormField context consumption, `aria-label` fallback, `parseInt` radix parameter
+
+### v0.3.0
+- **Changed** (BREAKING) `onChange` renamed to `onValueChange`
+- **Changed** Now extends HTMLAttributes — accepts all standard HTML props
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/pagination.md

@@ -0,0 +1,48 @@
+# Pagination
+
+- Import: @devalok/shilp-sutra/ui/pagination
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    PaginationRoot (nav)
+      PaginationContent (ul)
+        PaginationItem (li)
+          PaginationLink (isActive: boolean, asChild: boolean)
+          PaginationPrevious
+          PaginationNext
+          PaginationEllipsis
+    PaginationNav (convenience wrapper)
+
+## Utility
+    generatePagination(current: number, total: number, siblingCount: number) => (number | 'ellipsis')[]
+
+## Example
+```jsx
+<PaginationRoot>
+  <PaginationContent>
+    <PaginationItem><PaginationPrevious onClick={() => setPage(p - 1)} /></PaginationItem>
+    {generatePagination(page, totalPages, 1).map((item, i) =>
+      item === 'ellipsis'
+        ? <PaginationItem key={i}><PaginationEllipsis /></PaginationItem>
+        : <PaginationItem key={i}>
+            <PaginationLink isActive={item === page} onClick={() => setPage(item)}>
+              {item}
+            </PaginationLink>
+          </PaginationItem>
+    )}
+    <PaginationItem><PaginationNext onClick={() => setPage(p + 1)} /></PaginationItem>
+  </PaginationContent>
+</PaginationRoot>
+```
+
+## Gotchas
+- Root component is PaginationRoot (NOT Pagination)
+
+## Changes
+### v0.1.1
+- **Fixed** Pagination link padding uses `ds-*` tokens instead of Tailwind arbitrary values
+
+### v0.1.0
+- **Added** Initial release
+- **Added** PaginationNav compound wrapper with `generatePagination` helper

package/docs/components/ui/popover.md

@@ -0,0 +1,30 @@
+# Popover
+
+- Import: @devalok/shilp-sutra/ui/popover
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    Popover (root)
+      PopoverTrigger
+      PopoverContent
+      PopoverAnchor (optional anchor point)
+
+## Example
+```jsx
+<Popover>
+  <PopoverTrigger asChild><Button>Open</Button></PopoverTrigger>
+  <PopoverContent>Content here</PopoverContent>
+</Popover>
+```
+
+## Gotchas
+- Uses Framer Motion for enter/exit animations (v0.18.0)
+
+## Changes
+### v0.18.0
+- **Changed** Migrated to Framer Motion for enter/exit animations
+- **Added** `PopoverContentProps` type export
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/progress.md

@@ -0,0 +1,29 @@
+# Progress
+
+- Import: @devalok/shilp-sutra/ui/progress
+- Server-safe: No
+- Category: ui
+
+## Props
+    value: number (0-100) — omit for indeterminate
+    size: "sm" | "md" | "lg" (track height)
+    color: "default" | "success" | "warning" | "error" (indicator color)
+    showLabel: boolean (shows percentage text)
+    indicatorClassName: string
+
+## Defaults
+    size: "md"
+    color: "default"
+
+## Example
+```jsx
+<Progress value={75} color="success" showLabel />
+<Progress size="sm" />  {/* indeterminate */}
+```
+
+## Gotchas
+- Omit value (or pass undefined) for indeterminate animation
+
+## Changes
+### v0.1.0
+- **Added** Initial release with `size`, `color`, `indeterminate` variants and optional label slot

package/docs/components/ui/radio.md

@@ -0,0 +1,34 @@
+# RadioGroup
+
+- Import: @devalok/shilp-sutra/ui/radio
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    RadioGroup (root, value, onValueChange, defaultValue)
+      RadioGroupItem (value: string, REQUIRED)
+
+## Example
+```jsx
+<RadioGroup defaultValue="option-1" onValueChange={setValue}>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem value="option-1" id="r1" />
+    <Label htmlFor="r1">Option 1</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem value="option-2" id="r2" />
+    <Label htmlFor="r2">Option 2</Label>
+  </div>
+</RadioGroup>
+```
+
+## Gotchas
+- Each RadioGroupItem needs a unique `value` prop
+- Pair each item with a Label for accessibility
+
+## Changes
+### v0.4.2
+- **Added** `RadioGroupProps`, `RadioGroupItemProps` type exports
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/search-input.md

@@ -0,0 +1,43 @@
+# SearchInput
+
+- Import: @devalok/shilp-sutra/ui/search-input
+- Server-safe: No
+- Category: ui
+
+## Props
+    size: "sm" | "md" | "lg"
+    loading: boolean (shows spinner instead of clear button)
+    onClear: () => void (shows X button when value is non-empty)
+    value: string
+    onChange: ChangeEventHandler
+    (plus standard input attributes except native "size")
+
+## Defaults
+    size: "md"
+
+## Example
+```jsx
+<SearchInput
+  value={query}
+  onChange={(e) => setQuery(e.target.value)}
+  onClear={() => setQuery('')}
+  placeholder="Search tasks..."
+  loading={isSearching}
+/>
+```
+
+## Gotchas
+- HTML native "size" attribute is excluded — use CSS width instead
+
+## Changes
+### v0.15.0
+- **Changed** `lg` size font changed from `text-ds-lg` (18px) to `text-ds-md` (14px) — all input sizes now use 14px for consistency
+
+### v0.2.0
+- **Changed** `inputSize` prop renamed to `size` to match Input API
+
+### v0.1.1
+- **Fixed** Token compliance — replaced `pl-10 pr-9` and icon offsets with explicit arbitrary values
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/segmented-control.md

@@ -0,0 +1,50 @@
+# SegmentedControl
+
+- Import: @devalok/shilp-sutra/ui/segmented-control
+- Server-safe: No
+- Category: ui
+
+## Props
+    size: "sm" | "md" | "lg" (REQUIRED) — also accepts legacy "small" | "medium" | "big"
+    variant: "filled" | "tonal" (REQUIRED)
+    options: SegmentedControlOption[] (REQUIRED)
+    selectedId: string (REQUIRED)
+    onSelect: (id: string) => void (REQUIRED)
+    disabled: boolean
+
+## Types
+    SegmentedControlOption = { id: string, text: string, icon?: ComponentType<{ className?: string }> }
+    SegmentedControlSize = 'sm' | 'md' | 'lg' | 'small' | 'medium' | 'big' (legacy aliases)
+    SegmentedControlVariant = 'filled' | 'tonal'
+
+## Example
+```jsx
+<SegmentedControl
+  size="md"
+  variant="tonal"
+  options={[
+    { id: 'list', text: 'List' },
+    { id: 'grid', text: 'Grid' },
+  ]}
+  selectedId={viewMode}
+  onSelect={setViewMode}
+/>
+```
+
+## Gotchas
+- Controlled only — selectedId + onSelect are required
+- Uses data-driven API (options prop), not compound children
+
+## Changes
+### v0.18.0
+- **Fixed** `bg-interactive` changed to `bg-accent-9`, `bg-field` changed to `bg-surface-3` (OKLCH migration)
+
+### v0.4.2
+- **Changed** (BREAKING) `color` prop renamed to `variant` (values `filled`/`tonal` unchanged)
+
+### v0.1.1
+- **Fixed** `tabIndex={0}` changed to `tabIndex={-1}` on tablist wrapper — fixes double-focus keyboard navigation bug
+- **Fixed** Removed `!important` override — resolved specificity by restructuring base CVA classes
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/select.md

@@ -0,0 +1,49 @@
+# Select
+
+- Import: @devalok/shilp-sutra/ui/select
+- Server-safe: No
+- Category: ui
+
+## Props
+### SelectTrigger
+    size: "sm" | "md" | "lg"
+
+## Compound Components
+    Select (root — value, onValueChange, defaultValue)
+      SelectTrigger (size goes HERE, not on Select root)
+        SelectValue (placeholder)
+      SelectContent
+        SelectGroup (optional grouping)
+          SelectLabel (group header)
+          SelectItem (value: string, REQUIRED)
+        SelectSeparator
+
+## Defaults
+    SelectTrigger size: "md"
+
+## Example
+```jsx
+<Select onValueChange={setValue}>
+  <SelectTrigger size="lg">
+    <SelectValue placeholder="Choose..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="a">Option A</SelectItem>
+    <SelectItem value="b">Option B</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Gotchas
+- Size goes on SelectTrigger, NOT on Select root
+- `<Select size="lg">` is silently ignored (no TypeScript error)
+
+## Changes
+### v0.15.0
+- **Changed** `lg` size font changed from `text-ds-lg` (18px) to `text-ds-md` (14px) — all input sizes now use 14px for consistency
+
+### v0.14.0
+- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes content rendering behind Sheet/Dialog overlays
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/separator.md

@@ -0,0 +1,29 @@
+# Separator
+
+- Import: @devalok/shilp-sutra/ui/separator
+- Server-safe: No
+- Category: ui
+
+## Props
+    orientation: "horizontal" | "vertical"
+    decorative: boolean
+
+## Defaults
+    orientation: "horizontal"
+    decorative: true
+
+## Example
+```jsx
+<Separator />
+<Separator orientation="vertical" className="h-6" />
+```
+
+## Gotchas
+- When decorative is true, the separator is hidden from screen readers
+
+## Changes
+### v0.4.2
+- **Added** `SeparatorProps` type export
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/sheet.md

@@ -0,0 +1,47 @@
+# Sheet
+
+- Import: @devalok/shilp-sutra/ui/sheet
+- Server-safe: No
+- Category: ui
+
+## Props
+### SheetContent
+    side: "top" | "bottom" | "left" | "right"
+
+## Compound Components
+    Sheet (root)
+      SheetTrigger
+      SheetContent (side prop)
+        SheetHeader
+          SheetTitle
+          SheetDescription
+        [body content]
+        SheetFooter
+      SheetClose
+
+## Example
+```jsx
+<Sheet>
+  <SheetTrigger asChild><Button>Open</Button></SheetTrigger>
+  <SheetContent side="right">
+    <SheetHeader>
+      <SheetTitle>Settings</SheetTitle>
+    </SheetHeader>
+    <div>Content</div>
+  </SheetContent>
+</Sheet>
+```
+
+## Gotchas
+- Uses Framer Motion for slide enter/exit animations (v0.18.0)
+
+## Changes
+### v0.18.0
+- **Changed** Migrated to Framer Motion for enter/exit animations
+- **Added** `SheetContentProps` type export
+
+### v0.3.0
+- **Fixed** SheetHeader/Footer now support ref forwarding
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/sidebar.md

@@ -0,0 +1,72 @@
+# Sidebar
+
+- Import: @devalok/shilp-sutra/ui/sidebar
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    SidebarProvider (context provider — must wrap everything)
+      Sidebar (root panel)
+        SidebarHeader
+        SidebarContent
+          SidebarGroup
+            SidebarGroupLabel
+            SidebarGroupAction
+            SidebarGroupContent
+              SidebarMenu
+                SidebarMenuItem
+                  SidebarMenuButton (tooltip, isActive)
+                  SidebarMenuAction
+                  SidebarMenuBadge
+                  SidebarMenuSub
+                    SidebarMenuSubItem
+                      SidebarMenuSubButton (isActive)
+        SidebarFooter
+        SidebarSeparator
+        SidebarRail
+      SidebarInset (main content area)
+      SidebarTrigger (hamburger button)
+      SidebarInput (search input in sidebar)
+      SidebarMenuSkeleton (loading placeholder)
+
+## Hook
+    useSidebar() => { state, open, setOpen, openMobile, setOpenMobile, isMobile, toggleSidebar }
+
+## Example
+```jsx
+<SidebarProvider>
+  <Sidebar>
+    <SidebarHeader>Logo</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton isActive>
+                <IconHome /> Dashboard
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <SidebarInset>
+    <SidebarTrigger />
+    <main>Page content</main>
+  </SidebarInset>
+</SidebarProvider>
+```
+
+## Gotchas
+- SidebarProvider MUST wrap both Sidebar and SidebarInset
+- Use SidebarMenuButton for nav items (supports tooltip in collapsed state)
+
+## Changes
+### v0.18.0
+- **Fixed** `bg-interactive-subtle` changed to `bg-accent-2` (OKLCH migration)
+- **Added** `SidebarProps` type export
+
+### v0.1.0
+- **Added** Initial release