@devalok/shilp-sutra 0.18.1 → 0.18.2

package/docs/components/ui/collapsible.md

@@ -0,0 +1,40 @@
+# Collapsible
+
+- Import: @devalok/shilp-sutra/ui/collapsible
+- Server-safe: No
+- Category: ui
+
+## Props
+    open: boolean (controlled)
+    onOpenChange: (open: boolean) => void
+    defaultOpen: boolean
+
+## Compound Components
+    Collapsible (root)
+      CollapsibleTrigger
+      CollapsibleContent
+
+## Defaults
+    none
+
+## Example
+```jsx
+<Collapsible>
+  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+  <CollapsibleContent>Hidden content</CollapsibleContent>
+</Collapsible>
+```
+
+## Gotchas
+- Standard Radix Collapsible API
+
+## Changes
+### v0.13.0
+- **Changed** Default animation changed from fade-only to height-based expand/collapse using `animate-collapsible-down`/`animate-collapsible-up`
+- **Added** `collapsible-down` and `collapsible-up` keyframes added to Tailwind preset
+
+### v0.4.2
+- **Added** `CollapsibleProps` type export
+
+### v0.1.0
+- **Added** Initial release

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

@@ -0,0 +1,37 @@
+# ColorInput
+
+- Import: @devalok/shilp-sutra/ui/color-input
+- Server-safe: No
+- Category: ui
+
+## Props
+    value: string (hex color, e.g. "#d33163")
+    onChange: (value: string) => void
+    presets: string[] (optional preset color swatches)
+    disabled: boolean
+    className: string
+
+## Defaults
+    value="#000000", disabled=false
+
+## Example
+```jsx
+<ColorInput
+  value={color}
+  onChange={setColor}
+  presets={['#d33163', '#2563eb', '#16a34a']}
+/>
+```
+
+## Gotchas
+- Uses native color picker under the hood; value must be a valid hex string
+
+## Changes
+### v0.15.0
+- **Changed** `md` size font standardized to `text-ds-md` (14px) from mixed values
+
+### v0.8.0
+- **Fixed** Added `aria-label` to hex color input
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/combobox.md

@@ -0,0 +1,54 @@
+# Combobox
+
+- Import: @devalok/shilp-sutra/ui/combobox
+- Server-safe: No
+- Category: ui
+
+## 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
+    placeholder: string (default: "Select...")
+    searchPlaceholder: string (default: "Search...")
+    emptyMessage: string (default: "No results found")
+    disabled: boolean
+    triggerClassName: string
+    accessibleLabel: string (custom aria-label for trigger, falls back to placeholder)
+    maxVisible: number (default: 6, max dropdown items before scroll)
+    renderOption: (option, selected) => ReactNode
+
+## Defaults
+    placeholder="Select...", searchPlaceholder="Search...", emptyMessage="No results found", maxVisible=6
+
+## Example
+```jsx
+<Combobox
+  multiple
+  options={tagOptions}
+  value={selectedTags}
+  onValueChange={setSelectedTags}
+  placeholder="Select tags..."
+/>
+```
+
+## Gotchas
+- Enforces selection from list (unlike Autocomplete which allows free text)
+- In multi mode, selected items appear as pills with "+N more" overflow
+
+## Changes
+### v0.18.0
+- **Added** `accessibleLabel` prop — custom aria-label for trigger, falls back to placeholder
+
+### v0.14.0
+- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes dropdown rendering behind Sheet/Dialog overlays
+
+### v0.8.0
+- **Changed** (BREAKING) Props now use discriminated union — `multiple: true` requires `value: string[]` and `onValueChange: (value: string[]) => void`
+
+### 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/container.md

@@ -0,0 +1,26 @@
+# Container
+
+- Import: @devalok/shilp-sutra/ui/container
+- Server-safe: Yes
+- Category: ui
+
+## Props
+    maxWidth: "default" | "body" | "full"
+    as: ElementType (default: "div")
+
+## Defaults
+    maxWidth="default"
+
+## Example
+```jsx
+<Container maxWidth="body">
+  <p>Centered content</p>
+</Container>
+```
+
+## Gotchas
+- Server-safe component — can be imported directly in Next.js Server Components
+
+## Changes
+### v0.1.0
+- **Added** Initial release

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

@@ -0,0 +1,43 @@
+# ContextMenu
+
+- Import: @devalok/shilp-sutra/ui/context-menu
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    ContextMenu (root)
+      ContextMenuTrigger (right-click target)
+      ContextMenuContent
+        ContextMenuItem
+        ContextMenuCheckboxItem
+        ContextMenuRadioGroup > ContextMenuRadioItem
+        ContextMenuLabel
+        ContextMenuSeparator
+        ContextMenuSub > ContextMenuSubTrigger, ContextMenuSubContent
+
+## Defaults
+    none
+
+## Example
+```jsx
+<ContextMenu>
+  <ContextMenuTrigger>Right-click me</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Edit</ContextMenuItem>
+    <ContextMenuItem>Delete</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## Gotchas
+- Triggered by right-click (or long-press on touch devices)
+
+## Changes
+### v0.18.0
+- **Added** `ContextMenuContentProps`, `ContextMenuItemProps` type exports
+
+### v0.14.0
+- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes dropdown rendering behind Sheet/Dialog overlays
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/data-table-toolbar.md

@@ -0,0 +1,44 @@
+# DataTableToolbar
+
+- Import: @devalok/shilp-sutra/ui/data-table-toolbar
+- Server-safe: No
+- Category: ui
+
+## Props
+    table: Table<TData> (TanStack table instance)
+    globalFilter: boolean
+    globalFilterValue: string
+    onGlobalFilterChange: (value: string) => void
+    density: 'compact' | 'standard' | 'comfortable'
+    onDensityChange: (density: Density) => void
+    enableExport: boolean
+
+## Defaults
+    none
+
+## Example
+```jsx
+import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
+
+<DataTableToolbar
+  table={table}
+  globalFilter
+  globalFilterValue={filterValue}
+  onGlobalFilterChange={setFilterValue}
+  density={density}
+  onDensityChange={setDensity}
+  enableExport
+/>
+```
+
+## Gotchas
+- Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/data-table-toolbar`, NOT the `ui` barrel
+- Companion to DataTable — provides column visibility, density toggle, and CSV export controls
+- Requires @tanstack/react-table as a peer dependency
+
+## Changes
+### v0.5.0
+- **Changed** (BREAKING) Removed from `@devalok/shilp-sutra/ui` barrel export — must use `@devalok/shilp-sutra/ui/data-table-toolbar`
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/data-table.md

@@ -0,0 +1,91 @@
+# DataTable
+
+- Import: @devalok/shilp-sutra/ui/data-table
+- Server-safe: No
+- Category: ui
+
+## Props
+    columns: ColumnDef<TData>[] (TanStack column definitions)
+    data: TData[]
+    sortable: boolean — enable column sorting
+    onSort: (key: string, dir: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)
+    filterable: boolean — enable per-column filters
+    globalFilter: boolean — enable global search
+    paginated: boolean — enable client-side pagination
+    pagination: { page: number, pageSize: number, total: number, onPageChange: (page: number) => void } — server-side pagination (1-based page)
+    pageSize: number (default 10)
+    selectable: boolean — enable row selection with checkboxes
+    selectedIds: Set<string> — controlled selection state
+    selectableFilter: (row: TData) => boolean — disable selection on certain rows
+    getRowId: (row: TData) => string — custom row ID accessor
+    onSelectionChange: (selectedRows: TData[]) => void
+    expandable: boolean — enable row expansion
+    renderExpanded: (row: TData) => ReactNode — expanded row content
+    singleExpand: boolean — only one row expanded at a time
+    loading: boolean — show skeleton shimmer rows
+    emptyState: ReactNode — custom empty state (takes precedence over noResultsText)
+    noResultsText: string (default "No results.")
+    stickyHeader: boolean — sticky table header
+    onRowClick: (row: TData) => void — row click handler (excludes interactive element clicks)
+    bulkActions: BulkAction<TData>[] — floating action bar on selection — { label, onClick, color?: 'default'|'error', disabled? }
+    toolbar: boolean — show DataTableToolbar (column visibility, density, CSV export)
+    editable: boolean — enable double-click cell editing
+    virtualRows: boolean — virtualize rows for large datasets
+    columnPinning: { left?: string[], right?: string[] }
+    defaultDensity: 'compact' | 'standard' | 'comfortable'
+
+## Defaults
+    pageSize=10, noResultsText="No results."
+
+## Example
+```jsx
+import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
+
+<DataTable
+  columns={[
+    { accessorKey: 'name', header: 'Name' },
+    { accessorKey: 'email', header: 'Email' },
+  ]}
+  data={users}
+  sortable
+  onSort={(key, dir) => handleSort(key, dir)}
+  pagination={{ page, pageSize: 20, total: totalCount, onPageChange: setPage }}
+  loading={isLoading}
+  emptyState={<EmptyState title="No users" />}
+/>
+```
+
+## Gotchas
+- Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/data-table`, NOT the `ui` barrel
+- Requires @tanstack/react-table and @tanstack/react-virtual as peer dependencies
+- When onSort is provided, sorting is manual (server-side) — rows stay in data order
+- When pagination prop is provided, pagination is manual — pass total count
+- selectedIds syncs via useEffect — provide getRowId for custom row IDs
+- onRowClick does NOT fire when clicking checkboxes, buttons, links, or inputs
+- Use defaultDensity="compact" for Karm-style h-9 rows
+
+## Changes
+### v0.16.1
+- **Fixed** `serverPagination` object reference in `useCallback` dependency caused stale closure — now uses stable ref for `onPageChange`
+- **Fixed** `onSelectionChange` effect fired every render due to `table` in dependency array — now derives selected rows directly
+- **Fixed** `selectedRows` useMemo for bulk actions had same `table` dependency issue
+
+### v0.16.0
+- **Added** `onSort` callback for server-side sorting
+- **Added** `emptyState` ReactNode slot
+- **Added** `loading` prop with shimmer skeleton rows
+- **Added** `selectedIds` + `selectableFilter` for controlled selection
+- **Added** `pagination` prop for server-side pagination
+- **Added** `singleExpand` prop
+- **Added** `stickyHeader` prop
+- **Added** `onRowClick` handler
+- **Added** `bulkActions` floating action bar
+
+### v0.5.0
+- **Changed** (BREAKING) Removed from `@devalok/shilp-sutra/ui` barrel export — must use `@devalok/shilp-sutra/ui/data-table`
+
+### v0.1.1
+- **Fixed** `useEffect` exhaustive-deps with proper dependency array
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/dialog.md

@@ -0,0 +1,51 @@
+# Dialog
+
+- Import: @devalok/shilp-sutra/ui/dialog
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    Dialog (root)
+      DialogTrigger
+      DialogContent
+        DialogHeader
+          DialogTitle
+          DialogDescription
+        [body content]
+        DialogFooter
+      DialogClose
+
+## Defaults
+    none
+
+## Example
+```jsx
+<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Edit Profile</DialogTitle>
+      <DialogDescription>Make changes to your profile.</DialogDescription>
+    </DialogHeader>
+    <div>Form fields here</div>
+    <DialogFooter>
+      <Button>Save</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Gotchas
+- DialogTitle is required for accessibility — screen readers announce it when the dialog opens
+
+## Changes
+### v0.18.0
+- **Changed** Overlay animations migrated to Framer Motion (physics-based springs)
+- **Added** `DialogContentProps`, `DialogTitleProps` type exports
+- **Fixed** Context provider value wrapped in `useMemo` for performance
+
+### v0.3.0
+- **Fixed** DialogHeader/Footer now support ref forwarding
+
+### v0.1.0
+- **Added** Initial release

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

@@ -0,0 +1,45 @@
+# DropdownMenu
+
+- Import: @devalok/shilp-sutra/ui/dropdown-menu
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    DropdownMenu (root)
+      DropdownMenuTrigger
+      DropdownMenuContent
+        DropdownMenuLabel
+        DropdownMenuSeparator
+        DropdownMenuItem (+ DropdownMenuShortcut for keyboard hints)
+        DropdownMenuCheckboxItem
+        DropdownMenuRadioGroup > DropdownMenuRadioItem
+        DropdownMenuGroup
+        DropdownMenuSub > DropdownMenuSubTrigger, DropdownMenuSubContent
+
+## Defaults
+    none
+
+## Example
+```jsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild><Button variant="ghost">Menu</Button></DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Logout</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Gotchas
+- Use `asChild` on DropdownMenuTrigger to render your own button element
+
+## Changes
+### v0.18.0
+- **Added** `DropdownMenuContentProps`, `DropdownMenuItemProps` type exports
+
+### v0.14.0
+- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes dropdown rendering behind Sheet/Dialog overlays
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/file-upload.md

@@ -0,0 +1,41 @@
+# FileUpload
+
+- Import: @devalok/shilp-sutra/ui/file-upload
+- Server-safe: No
+- Category: ui
+
+## Props
+    onFiles: (files: File[]) => void (REQUIRED)
+    accept: string (MIME or extension, e.g. "image/*", ".pdf,.doc")
+    maxSize: number (bytes, default: 10MB)
+    multiple: boolean
+    uploading: boolean
+    progress: number (0-100)
+    error: string
+    compact: boolean (inline button mode vs drop zone)
+    disabled: boolean
+    label: string
+    sublabel: string
+
+## Defaults
+    compact: false
+    maxSize: 10MB (10485760 bytes)
+
+## Example
+```jsx
+<FileUpload
+  accept="image/*"
+  maxSize={2 * 1024 * 1024}
+  onFiles={(files) => uploadAvatar(files[0])}
+  label="Upload profile photo"
+  sublabel="PNG, JPG up to 2MB"
+/>
+```
+
+## Gotchas
+- compact=true renders a small inline button; false (default) renders a large drag-and-drop zone
+- Client-side validation: invalid files are rejected before onFiles is called
+
+## Changes
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/form.md

@@ -0,0 +1,51 @@
+# FormField / FormHelperText / useFormField
+
+- Import: @devalok/shilp-sutra/ui/form
+- Server-safe: No
+- Category: ui
+
+## Props
+### FormField
+    state: "helper" | "error" | "warning" | "success" (default: "helper")
+    helperTextId: string (auto-generated if omitted)
+    required: boolean
+
+### FormHelperText
+    state: "helper" | "error" | "warning" | "success" (inherits from FormField context)
+
+## Types
+    FormHelperState = 'helper' | 'error' | 'warning' | 'success'
+
+## Hook
+    useFormField() => { state, helperTextId, required }
+
+## Defaults
+    state: "helper"
+
+## Example
+```jsx
+<FormField state="error">
+  <Label htmlFor="email">Email</Label>
+  <Input id="email" state="error" />
+  <FormHelperText>Please enter a valid email.</FormHelperText>
+</FormField>
+```
+
+## Gotchas
+- getFormFieldA11y() was REMOVED — use useFormField() hook instead
+- FormHelperText auto-reads state and id from FormField context
+- FormHelperText renders role="alert" when state="error"
+
+## Changes
+### v0.18.0
+- **Fixed** Wrapped FormField context provider value in `useMemo` for performance
+
+### v0.8.0
+- **Fixed** Input/Textarea now consume FormField context automatically (`aria-describedby`, `aria-invalid`, `aria-required`)
+
+### v0.3.0
+- **Added** `useFormField()` hook for automatic aria-describedby wiring
+- **Changed** (BREAKING) FormField auto-wires `aria-describedby` via context. `getFormFieldA11y()` removed
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/hover-card.md

@@ -0,0 +1,32 @@
+# HoverCard
+
+- Import: @devalok/shilp-sutra/ui/hover-card
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    HoverCard (root)
+      HoverCardTrigger
+      HoverCardContent
+
+## Example
+```jsx
+<HoverCard>
+  <HoverCardTrigger asChild><span>Hover me</span></HoverCardTrigger>
+  <HoverCardContent>Preview content</HoverCardContent>
+</HoverCard>
+```
+
+## Gotchas
+- Overlay component — uses Framer Motion for enter/exit animations (v0.18.0)
+
+## Changes
+### v0.18.0
+- **Changed** Migrated to Framer Motion for enter/exit animations
+- **Added** `HoverCardContentProps` type export
+
+### 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/icon-button.md

@@ -0,0 +1,33 @@
+# IconButton
+
+- Import: @devalok/shilp-sutra/ui/icon-button
+- Server-safe: No
+- Category: ui
+
+## Props
+    icon: ReactNode (REQUIRED)
+    aria-label: string (REQUIRED — WCAG AA mandatory)
+    shape: "square" | "circle"
+    size: "sm" | "md" | "lg"
+    variant: same as Button (solid, outline, ghost, link)
+    color: same as Button (default, error)
+    loading: boolean
+    disabled: boolean
+
+## Defaults
+    shape: "square"
+    size: "md"
+
+## Example
+```jsx
+<IconButton icon={<IconEdit />} variant="ghost" aria-label="Edit item" />
+<IconButton icon={<IconX />} shape="circle" variant="ghost" size="sm" aria-label="Close" />
+```
+
+## Gotchas
+- aria-label is enforced by TypeScript — you MUST provide it
+- Prefer IconButton over Button with size="icon-*" for icon-only buttons
+
+## Changes
+### v0.1.0
+- **Added** Initial release

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

@@ -0,0 +1,44 @@
+# InputOTP
+
+- Import: @devalok/shilp-sutra/ui/input-otp
+- Server-safe: No
+- Category: ui
+
+## Props
+    Standard input-otp props (maxLength, pattern, etc.)
+
+## Compound Components
+    InputOTP (root)
+      InputOTPGroup
+        InputOTPSlot (index: number, REQUIRED)
+      InputOTPSeparator
+
+## Example
+```jsx
+<InputOTP maxLength={6}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+## Gotchas
+- Each InputOTPSlot requires an `index` prop (0-based)
+
+## Changes
+### v0.18.0
+- **Added** `InputOTPProps` type export
+
+### v0.1.1
+- **Fixed** `animate-caret-blink` keyframe added to Tailwind preset — caret animation was silently broken
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/input.md

@@ -0,0 +1,48 @@
+# Input
+
+- Import: @devalok/shilp-sutra/ui/input
+- Server-safe: No
+- Category: ui
+
+## Props
+    size: "sm" | "md" | "lg"
+    state: InputState
+    startIcon: ReactNode
+    endIcon: ReactNode
+    (plus all standard HTML input attributes except native "size")
+
+## Types
+    InputState = 'default' | 'error' | 'warning' | 'success'
+
+## Defaults
+    size: "md"
+
+## Example
+```jsx
+<Input type="email" placeholder="you@example.com" state="error" startIcon={<IconMail />} />
+```
+
+## Gotchas
+- 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)
+- All sizes (sm, md, lg) use text-ds-md (14px) font — size only affects height and padding (v0.15.0)
+
+## 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
+- **Changed** `md` size font standardized to `text-ds-md` (14px) from mixed values
+
+### v0.12.0
+- **Changed** Softer resting border (`border-border-subtle` instead of `border-border`), subtler focus ring (`ring-1 ring-focus/50` instead of `ring-2 ring-focus`)
+- **Changed** Reverted split `pl-*/pr-*` size variants back to `px-*`; icon padding uses `pl-ds-07`/`pr-ds-07`
+
+### v0.8.0
+- **Fixed** Now consumes FormField context automatically (`aria-describedby`, `aria-invalid`, `aria-required`)
+
+### v0.4.2
+- **Added** `inputVariants` export
+
+### v0.1.0
+- **Added** Initial release