@devalok/shilp-sutra 0.18.1 → 0.18.2

package/docs/components/_header.md

@@ -0,0 +1,83 @@
+# @devalok/shilp-sutra — Full Component Reference
+
+> Exhaustive API reference for AI coding agents.
+> For a concise cheatsheet, see llms.txt instead.
+> All variant values and props verified from source CVA definitions.
+>
+> Package: @devalok/shilp-sutra
+> Version: {{VERSION}}
+
+---
+
+## Architecture Notes
+
+### The Two-Axis Variant System
+
+Many components use TWO props where shadcn/ui uses one:
+- `variant` controls SHAPE/SURFACE: solid, outline, ghost, subtle, filled, etc.
+- `color` controls INTENT/SEMANTICS: default, error, success, warning, info, etc.
+
+Components with two-axis system: Button, Badge, Alert, Chip, Banner, Progress, StatusBadge
+
+### Server-Safe Components (no "use client")
+
+These can be imported directly in Next.js Server Components:
+- UI: Text, Skeleton, Stack, Container, Table (and sub-components), Code, VisuallyHidden
+- Composed: ContentCard, PageHeader, LoadingSkeleton, PageSkeletons, PriorityIndicator
+- NOTE (v0.18.0): Spinner, EmptyState, StatusBadge are NO LONGER server-safe (Framer Motion dependency)
+
+Use per-component imports for server components:
+  import { Text } from '@devalok/shilp-sutra/ui/text'
+  import { PageHeader } from '@devalok/shilp-sutra/composed/page-header'
+
+DO NOT use barrel imports in Server Components — they include "use client" components.
+
+### Token Architecture — OKLCH 12-Step System
+
+Color tokens use OKLCH (perceptually uniform) with 12 functional steps per palette:
+
+| Step | Purpose | Example usage |
+|------|---------|---------------|
+| 1 | App background | Page bg, body |
+| 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 |
+| 9 | Solid / accent | Button bg, primary CTA |
+| 10 | Solid hover | Button hover bg |
+| 11 | Low-contrast text | Secondary accent text |
+| 12 | High-contrast text | Headings on light bg |
+
+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
+- Status: --color-{error,success,warning,info}-{3,7,9,11}
+- Category: --color-category-{teal,amber,slate,indigo,cyan,orange,emerald}
+
+Consumer rebranding: Override accent scale CSS vars or use generateScale(options) utility.
+
+Tailwind utilities: accent-1..12, secondary-1..12, surface-1..4, plus fg/border variants.
+
+### Toast Setup Pattern
+
+1. Mount <Toaster /> once at your root layout.
+2. Import { toast } from '@devalok/shilp-sutra/ui/toast' and call toast.success(), toast.error(), etc.
+3. Types: 'success' | 'error' | 'warning' | 'info' | 'loading' | 'message'
+
+### Form Accessibility Pattern
+
+Use <FormField> + useFormField() hook:
+  <FormField state="error">
+    <Label htmlFor="email">Email</Label>
+    <Input id="email" state="error" />
+    <FormHelperText>Error message here.</FormHelperText>
+  </FormField>
+
+useFormField() returns { state, helperTextId, required } from context.
+Wire manually: <Input aria-describedby={helperTextId} aria-invalid={state === 'error'} />
+
+Note: getFormFieldA11y() was removed in favor of useFormField() hook.

package/docs/components/composed/activity-feed.md

@@ -0,0 +1,43 @@
+# ActivityFeed
+
+- Import: @devalok/shilp-sutra/composed/activity-feed
+- Server-safe: No
+- Category: composed
+
+## 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
+    loading: boolean — skeleton shimmer
+    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
+
+## Example
+```jsx
+<ActivityFeed
+  items={[
+    { id: '1', actor: { name: 'Alice' }, action: 'completed task', timestamp: new Date(), color: 'success' },
+    { id: '2', action: 'System backup completed', timestamp: new Date(), detail: <pre>Details...</pre> },
+  ]}
+  hasMore
+  onLoadMore={() => fetchMore()}
+  compact
+/>
+```
+
+## Gotchas
+- `items` is required — passing an empty array renders the `emptyState` content
+- `color` on each item controls the timeline dot color
+- `actor.image` is optional — falls back to initials from `actor.name`
+- `maxInitialItems` truncates with a "Show all (N)" toggle button
+
+## Changes
+### v0.18.0
+- **Fixed** `bg-accent-9` changed to `bg-info-9` (info color, not accent)
+
+### v0.16.0
+- **Added** Initial release — vertical timeline with colored dots, actor avatars, expandable detail, compact mode, load more, maxInitialItems truncation

package/docs/components/composed/avatar-group.md

@@ -0,0 +1,32 @@
+# AvatarGroup
+
+- Import: @devalok/shilp-sutra/composed/avatar-group
+- Server-safe: No
+- Category: composed
+
+## Props
+    users: AvatarUser[] (REQUIRED) — { name: string, image?: string | null }
+    max: number (default: 4, overflow shows "+N" badge)
+    size: "sm" | "md" | "lg"
+    showTooltip: boolean (default: true)
+
+## Defaults
+    size="md", max=4, showTooltip=true
+
+## Example
+```jsx
+<AvatarGroup
+  users={[{ name: 'Alice', image: '/alice.jpg' }, { name: 'Bob' }]}
+  max={3}
+  size="md"
+/>
+```
+
+## Gotchas
+- Wraps TooltipProvider internally — no need to add one yourself
+- Users beyond `max` are collapsed into a "+N" overflow badge
+- Missing `image` falls back to initials derived from `name`
+
+## Changes
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/command-palette.md

@@ -0,0 +1,40 @@
+# CommandPalette
+
+- Import: @devalok/shilp-sutra/composed/command-palette
+- Server-safe: No
+- Category: composed
+
+## Props
+    groups: CommandGroup[] — { label: string, items: CommandItem[] }
+    placeholder: string (default: "Search or jump to...")
+    onSearch: (query: string) => void
+    emptyMessage: string (default: "No results found.")
+
+CommandItem shape: { id, label, description?, icon?, shortcut?, onSelect: () => void }
+
+## Defaults
+    placeholder="Search or jump to...", emptyMessage="No results found."
+
+## Example
+```jsx
+<CommandPalette
+  groups={[{
+    label: 'Navigation',
+    items: [{ id: 'dash', label: 'Dashboard', onSelect: () => navigate('/') }],
+  }]}
+/>
+```
+
+## Gotchas
+- Opens with Ctrl+K / Cmd+K by default
+- Items animate in with staggered slide-up (30ms delay cascade); groups fade in; active item icon/shortcut highlight in interactive color (v0.15.0)
+
+## Changes
+### v0.15.0
+- **Added** Staggered slide-up entrance animations for items, fade-in for groups/empty state/footer, scale-in for search icon, active item icon/shortcut color transitions
+
+### v0.8.0
+- **Added** Full ARIA combobox pattern (`role="combobox"`, `aria-expanded`, `aria-activedescendant`)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/confirm-dialog.md

@@ -0,0 +1,46 @@
+# ConfirmDialog
+
+- Import: @devalok/shilp-sutra/composed/confirm-dialog
+- Server-safe: No
+- Category: composed
+
+## Props
+    open: boolean (REQUIRED, controlled)
+    onOpenChange: (open: boolean) => void (REQUIRED)
+    title: string (REQUIRED)
+    description: string (REQUIRED)
+    confirmText: string (default: "Confirm")
+    cancelText: string (default: "Cancel")
+    color: "default" | "error" (controls confirm button color)
+    loading: boolean (default: false, disables buttons and shows spinner)
+    onConfirm: () => void | Promise<void> (REQUIRED)
+
+## Defaults
+    confirmText="Confirm", cancelText="Cancel", color="default", loading=false
+
+## Example
+```jsx
+const [open, setOpen] = useState(false)
+<ConfirmDialog
+  open={open}
+  onOpenChange={setOpen}
+  title="Delete project?"
+  description="This action cannot be undone."
+  color="error"
+  confirmText="Delete"
+  loading={isDeleting}
+  onConfirm={async () => { await deleteProject(); setOpen(false) }}
+/>
+```
+
+## Gotchas
+- Dialog stays open after confirm — consumer must close it via `onOpenChange`
+- Built on AlertDialog internally
+- Fully controlled — `open` and `onOpenChange` are required
+
+## Changes
+### v0.18.0
+- **Fixed** Converted to `forwardRef` pattern
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/content-card.md

@@ -0,0 +1,36 @@
+# ContentCard
+
+- Import: @devalok/shilp-sutra/composed/content-card
+- Server-safe: Yes
+- Category: composed
+
+## Props
+    variant: "default" | "outline" | "ghost"
+    padding: "default" | "compact" | "spacious" | "none"
+    header: ReactNode (custom header content)
+    headerTitle: string (simple text header)
+    headerActions: ReactNode (actions in header area)
+    footer: ReactNode
+    children: ReactNode (body)
+
+## Defaults
+    variant="default", padding="default"
+
+## Example
+```jsx
+<ContentCard headerTitle="Team Members" headerActions={<Button size="sm">Add</Button>}>
+  <p>Member list here</p>
+</ContentCard>
+```
+
+## Gotchas
+- Server-safe: can be imported directly in Next.js Server Components
+- Use `headerTitle` for simple text headers; use `header` for custom header content
+- `header` takes precedence over `headerTitle` if both are provided
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/date-picker.md

@@ -0,0 +1,130 @@
+# DatePicker
+
+- Import: @devalok/shilp-sutra/composed/date-picker
+- Server-safe: No
+- Category: composed
+
+## Props
+
+### DatePicker
+    value: Date | null
+    onChange: (date: Date | null) => void
+    placeholder: string (default: "Pick a date")
+    formatStr: string (default: "MMM d, yyyy")
+    minDate: Date
+    maxDate: Date
+    disabledDates: (date: Date) => boolean
+    className: string
+
+### DateRangePicker
+    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
+    maxDate: Date
+    disabledDates: (date: Date) => boolean
+    presets: PresetKey[] (shows quick-select sidebar)
+    numberOfMonths: number (default: 1)
+
+### DateTimePicker
+    value: Date | null
+    onChange: (date: Date | null) => void
+    minDate: Date
+    maxDate: Date
+    disabledDates: (date: Date) => boolean
+    timeFormat: "12h" | "24h"
+    minuteStep: number
+    placeholder: string
+    className: string
+
+### TimePicker
+    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)
+    showSeconds: boolean (default: false)
+    placeholder: string (default: "Pick a time")
+    disabled: boolean (default: false)
+    className: string
+
+### CalendarGrid
+    currentMonth: Date (REQUIRED)
+    selected: Date | null
+    rangeStart: Date | null
+    rangeEnd: Date | null
+    hoverDate: Date | null
+    onSelect: (date: Date) => void (REQUIRED)
+    onHover: (date: Date | null) => void
+    onMonthChange: (date: Date) => void (REQUIRED)
+    onHeaderClick: () => void
+    disabledDates: (date: Date) => boolean
+    minDate: Date
+    maxDate: Date
+    hidePrevNav: boolean
+    hideNextNav: boolean
+    events: CalendarEvent[] — { date: Date, color?: string, label?: string }
+
+### YearPicker
+    currentYear: number (REQUIRED)
+    selectedYear: number
+    onYearSelect: (year: number) => void (REQUIRED)
+    minDate: Date
+    maxDate: Date
+
+### MonthPicker
+    currentYear: number (REQUIRED)
+    selectedMonth: number (0-11)
+    onMonthSelect: (month: number) => void (REQUIRED)
+    minDate: Date
+    maxDate: Date
+
+### Presets
+    presets: PresetKey[] (REQUIRED)
+    onSelect: (start: Date, end: Date) => void (REQUIRED)
+    className: string
+
+PresetKey: 'today' | 'yesterday' | 'last7days' | 'last30days' | 'thisMonth' | 'lastMonth' | 'thisYear'
+
+### useCalendar hook
+    useCalendar(initialMonth?: Date) => { currentMonth, setCurrentMonth, goToPreviousMonth, goToNextMonth, goToMonth, goToYear }
+
+## Defaults
+    DatePicker: placeholder="Pick a date", formatStr="MMM d, yyyy"
+    DateRangePicker: placeholder="Pick a date range", formatStr="MMM d, yyyy", numberOfMonths=1
+    TimePicker: format="12h", minuteStep=1, secondStep=1, showSeconds=false
+
+## Example
+```jsx
+<DatePicker value={date} onChange={setDate} placeholder="Select date" />
+
+<DateRangePicker
+  startDate={start}
+  endDate={end}
+  onChange={({ start, end }) => { setStart(start); setEnd(end); }}
+/>
+
+<DateTimePicker value={dateTime} onChange={setDateTime} timeFormat="12h" minuteStep={15} />
+
+<TimePicker value={time} onChange={setTime} format="24h" minuteStep={15} />
+```
+
+## Gotchas
+- TimePicker stores time inside a Date object — only hours/minutes/seconds are meaningful
+- CalendarGrid is a low-level building block — prefer DatePicker/DateRangePicker for most use cases
+- MonthPicker month values are 0-indexed (Jan=0, Dec=11) — same as JavaScript `Date.getMonth()`
+- YearPicker displays a 12-year grid based on the decade of `currentYear`
+- CalendarGrid supports up to 3 event dots per day cell
+- useCalendar is a convenience hook for managing calendar month state
+
+## Changes
+### v0.18.0
+- **Fixed** Added `aria-label` to DatePicker/DateRangePicker trigger buttons
+
+### v0.4.2
+- **Changed** DateRangePicker default `formatStr` from `'MMM d'` to `'MMM d, yyyy'`
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/empty-state.md

@@ -0,0 +1,53 @@
+# EmptyState
+
+- Import: @devalok/shilp-sutra/composed/empty-state
+- Server-safe: No
+- Category: composed
+
+Note: EmptyState was server-safe prior to v0.18.0 but is NO LONGER server-safe due to Framer Motion dependency.
+
+## Props
+    title: string (REQUIRED)
+    description: string
+    icon: ReactNode | ComponentType<{ className?: string }> (default: Devalok chakra icon)
+    action: ReactNode (e.g. a Button)
+    compact: boolean (smaller layout)
+    iconSize: 'sm' | 'md' | 'lg' (default 'md', compact defaults to 'sm') — sm=h-ico-sm, md=h-ico-lg, lg=h-ico-xl
+
+## Defaults
+    iconSize="md" (compact defaults to "sm")
+
+## Example
+```jsx
+<EmptyState
+  title="No tasks found"
+  description="Create your first task to get started."
+  action={<Button>Create Task</Button>}
+  iconSize="lg"
+/>
+```
+
+## Gotchas
+- `icon` accepts both JSX elements (`<IconFolder />`) and component references (`IconFolder`). Component references are auto-instantiated with correct sizing classes.
+- `iconSize` controls icon dimensions regardless of icon type. When `compact=true` and no `iconSize`, defaults to `'sm'`.
+- As of v0.18.0, EmptyState is NOT server-safe (Framer Motion dependency). Use per-component import in client components.
+
+## Changes
+### v0.18.0
+- **Changed** No longer server-safe due to Framer Motion dependency
+
+### v0.16.0
+- **Added** `iconSize?: 'sm' | 'md' | 'lg'` — control icon dimensions
+
+### v0.13.0
+- **Changed** `icon` prop now accepts `React.ComponentType<{ className?: string }>` in addition to `ReactNode` — component references are auto-instantiated
+
+### v0.5.0
+- **Changed** `icon` prop changed from `TablerIcon` (component ref) to `React.ReactNode` — use `icon={<MyIcon />}` instead of `icon={MyIcon}`
+- **Changed** Default icon is now the Devalok swadhisthana chakra (inline SVG)
+
+### v0.2.0
+- **Added** Identified as server-safe component (later reverted in v0.18.0)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/error-boundary.md

@@ -0,0 +1,29 @@
+# ErrorDisplay
+
+- Import: @devalok/shilp-sutra/composed/error-boundary
+- Server-safe: No
+- Category: composed
+
+## Props
+    error: unknown (REQUIRED — Error object, status object, or string)
+    onReset: () => void (optional retry button)
+
+## Defaults
+    None
+
+## Example
+```jsx
+<ErrorDisplay error={error} onReset={() => refetch()} />
+```
+
+## Gotchas
+- Auto-detects HTTP status codes (404, 403, 500) and shows appropriate icon/message
+- Shows stack trace in development mode only
+- The import path is `error-boundary` but the component is named `ErrorDisplay`
+
+## Changes
+### v0.18.0
+- **Added** ErrorBoundary tests (13 new tests)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/global-loading.md

@@ -0,0 +1,27 @@
+# GlobalLoading
+
+- Import: @devalok/shilp-sutra/composed/global-loading
+- Server-safe: No
+- Category: composed
+
+## Props
+    isLoading: boolean (REQUIRED)
+
+## Defaults
+    None
+
+## Example
+```jsx
+<GlobalLoading isLoading={isNavigating} />
+```
+
+## Gotchas
+- Fixed-position bar at top of viewport (z-toast layer)
+- Renders nothing when `isLoading` is false
+
+## Changes
+### v0.18.0
+- **Fixed** Track `setTimeout` with ref, add cleanup on unmount
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/loading-skeleton.md

@@ -0,0 +1,51 @@
+# LoadingSkeleton
+
+- Import: @devalok/shilp-sutra/composed/loading-skeleton
+- Server-safe: Yes
+- Category: composed
+
+Exports: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton
+
+## Props
+
+### CardSkeleton
+    className: string
+
+### TableSkeleton
+    rows: number (default: 5)
+    columns: number (default: 4)
+    className: string
+
+### BoardSkeleton
+    columns: number (default: 4)
+    cardsPerColumn: number (default: 3)
+    className: string
+
+### ListSkeleton
+    rows: number (default: 6)
+    showAvatar: boolean (default: true)
+    className: string
+
+## Defaults
+    TableSkeleton: rows=5, columns=4
+    BoardSkeleton: columns=4, cardsPerColumn=3
+    ListSkeleton: rows=6, showAvatar=true
+
+## Example
+```jsx
+<CardSkeleton />
+<TableSkeleton rows={8} columns={5} />
+<BoardSkeleton columns={3} cardsPerColumn={4} />
+<ListSkeleton rows={10} showAvatar={false} />
+```
+
+## Gotchas
+- Server-safe: can be imported directly in Next.js Server Components
+- These are pre-composed skeleton layouts — for individual skeleton shapes, use the `Skeleton` UI component
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/member-picker.md

@@ -0,0 +1,35 @@
+# MemberPicker
+
+- Import: @devalok/shilp-sutra/composed/member-picker
+- Server-safe: No
+- Category: composed
+
+## Props
+    members: MemberPickerMember[] (REQUIRED) — { id, name, avatar? }
+    selectedIds: string[] (REQUIRED)
+    onSelect: (memberId: string) => void (REQUIRED)
+    multiple: boolean (default: false)
+    placeholder: string (default: "Search members...")
+    children: ReactNode (trigger element)
+
+## Defaults
+    multiple=false, placeholder="Search members..."
+
+## Example
+```jsx
+<MemberPicker members={teamMembers} selectedIds={assignees} onSelect={toggleAssignee} multiple>
+  <Button variant="outline">Assign Members</Button>
+</MemberPicker>
+```
+
+## Gotchas
+- `children` is used as the trigger element (e.g., a Button)
+- `onSelect` is called with a single `memberId` — toggle logic is up to the consumer
+- When `multiple=false`, selecting a new member replaces the previous selection
+
+## Changes
+### v0.18.0
+- **Fixed** Added `aria-label` to search input
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/page-header.md

@@ -0,0 +1,41 @@
+# PageHeader
+
+- Import: @devalok/shilp-sutra/composed/page-header
+- Server-safe: Yes
+- Category: composed
+
+## Props
+    title: string (falls back to last breadcrumb label if omitted)
+    subtitle: string
+    actions: ReactNode (action buttons)
+    breadcrumbs: Breadcrumb[] — { label: string, href?: string }
+    titleClassName: string
+
+## Defaults
+    None
+
+## Example
+```jsx
+<PageHeader
+  title="Project Settings"
+  subtitle="Configure your project preferences"
+  breadcrumbs={[
+    { label: 'Home', href: '/' },
+    { label: 'Projects', href: '/projects' },
+    { label: 'Settings' },
+  ]}
+  actions={<Button>Save</Button>}
+/>
+```
+
+## Gotchas
+- Server-safe: can be imported directly in Next.js Server Components
+- If `title` is omitted, the last breadcrumb's `label` is used as the page title
+- The last breadcrumb should not have an `href` (it represents the current page)
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/page-skeletons.md

@@ -0,0 +1,32 @@
+# PageSkeletons
+
+- Import: @devalok/shilp-sutra/composed/page-skeletons
+- Server-safe: Yes
+- Category: composed
+
+Exports: DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton
+
+## Props
+    className?: string (plus all standard HTML div attributes via React.ComponentPropsWithoutRef<'div'>)
+
+## Defaults
+    None
+
+## Example
+```jsx
+<DashboardSkeleton />
+<ProjectListSkeleton />
+<TaskDetailSkeleton />
+```
+
+## Gotchas
+- Server-safe: can be imported directly in Next.js Server Components
+- These are full-page skeleton layouts — for smaller skeleton sections, use LoadingSkeleton components
+- Accept `className` and standard div attributes but render fixed layout structures
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release