@devalok/shilp-sutra 0.16.1 → 0.17.1

package/dist/ui/table.js

@@ -1,22 +1,22 @@
 import { jsx as o } from "react/jsx-runtime";
 import * as l from "react";
-import { c as r } from "../_chunks/utils.js";
-const s = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o("div", { className: "relative w-full overflow-auto", children: /* @__PURE__ */ o(
+import { c as s } from "../_chunks/utils.js";
+const r = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o("div", { className: "relative w-full overflow-auto", children: /* @__PURE__ */ o(
   "table",
   {
     ref: t,
-    className: r("w-full caption-bottom text-ds-md", e),
+    className: s("w-full caption-bottom text-ds-md", e),
     ...a
   }
 ) }));
-s.displayName = "Table";
-const d = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o("thead", { ref: t, className: r("", e), ...a }));
+r.displayName = "Table";
+const d = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o("thead", { ref: t, className: s("", e), ...a }));
 d.displayName = "TableHeader";
 const c = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o(
   "tbody",
   {
     ref: t,
-    className: r("[&_tr:last-child]:border-0", e),
+    className: s("[&_tr:last-child]:border-0", e),
     ...a
   }
 ));
@@ -25,7 +25,7 @@ const m = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o(
   "tfoot",
   {
     ref: t,
-    className: r(
+    className: s(
       "bg-[color-mix(in_srgb,var(--color-layer-02)_50%,transparent)] font-medium [&>tr]:last:border-b-0",
       e
     ),
@@ -37,7 +37,7 @@ const b = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o(
   "tr",
   {
     ref: t,
-    className: r(
+    className: s(
       "transition-colors hover:bg-layer-02 data-[state=selected]:bg-interactive-selected",
       e
     ),
@@ -50,7 +50,7 @@ const i = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o(
   {
     ref: t,
     scope: "col",
-    className: r(
+    className: s(
       "h-ds-md px-ds-03 text-left font-medium text-text-secondary [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
       e
     ),
@@ -62,8 +62,8 @@ const f = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o(
   "td",
   {
     ref: t,
-    className: r(
-      "py-ds-03 px-0 [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+    className: s(
+      "py-ds-03 px-ds-03 [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
       e
     ),
     ...a
@@ -74,13 +74,13 @@ const n = l.forwardRef(({ className: e, ...a }, t) => /* @__PURE__ */ o(
   "caption",
   {
     ref: t,
-    className: r("mt-ds-05 text-ds-md text-text-secondary", e),
+    className: s("mt-ds-05 text-ds-md text-text-secondary", e),
     ...a
   }
 ));
 n.displayName = "TableCaption";
 export {
-  s as Table,
+  r as Table,
   c as TableBody,
   n as TableCaption,
   f as TableCell,

package/llms-full.txt

@@ -187,6 +187,7 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
     <AvatarImage src={user.photoUrl} alt={user.name} />
     <AvatarFallback>JD</AvatarFallback>
   </Avatar>
+- Type: AvatarStatus = 'online' | 'offline' | 'busy' | 'away'
 - Gotchas:
     - Status dot renders with role="img" and aria-label (accessible, not decorative)
     - Dot size scales automatically with avatar size
@@ -534,6 +535,7 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
     required: boolean
 - Props (FormHelperText):
     state: "helper" | "error" | "warning" | "success" (inherits from FormField context)
+- Type: FormHelperState = 'helper' | 'error' | 'warning' | 'success'
 - Hook: useFormField() => { state, helperTextId, required }
 - Example:
   <FormField state="error">
@@ -581,9 +583,10 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## Input
 - Import: @devalok/shilp-sutra/ui/input
 - Server-safe: No
+- Type: InputState = 'default' | 'error' | 'warning' | 'success'
 - Props:
     size: "sm" | "md" | "lg"
-    state: "default" | "error" | "warning" | "success"
+    state: InputState
     startIcon: ReactNode
     endIcon: ReactNode
     (plus all standard HTML input attributes except native "size")
@@ -814,10 +817,13 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Props (SegmentedControl root):
     size: "sm" | "md" | "lg" (REQUIRED) — also accepts legacy "small" | "medium" | "big"
     variant: "filled" | "tonal" (REQUIRED)
-    options: SegmentedControlOption[] (REQUIRED) — { id: string, text: string, icon?: ComponentType }
+    options: SegmentedControlOption[] (REQUIRED)
     selectedId: string (REQUIRED)
     onSelect: (id: string) => void (REQUIRED)
     disabled: boolean
+- Type: SegmentedControlOption = { id: string, text: string, icon?: ComponentType<{ className?: string }> }
+- Type: SegmentedControlSize = 'sm' | 'md' | 'lg' | 'small' | 'medium' | 'big' (legacy aliases)
+- Type: SegmentedControlVariant = 'filled' | 'tonal'
 - Defaults: None — size and variant are required
 - Example:
   <SegmentedControl
@@ -1111,8 +1117,9 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## Text
 - Import: @devalok/shilp-sutra/ui/text
 - Server-safe: Yes
+- Type: TextVariant = 'heading-2xl' | 'heading-xl' | 'heading-lg' | 'heading-md' | 'heading-sm' | 'heading-xs' | 'body-lg' | 'body-md' | 'body-sm' | 'body-xs' | 'label-lg' | 'label-md' | 'label-sm' | 'label-xs' | 'caption' | 'overline'
 - Props:
-    variant: "heading-2xl" | "heading-xl" | "heading-lg" | "heading-md" | "heading-sm" | "heading-xs" | "body-lg" | "body-md" | "body-sm" | "body-xs" | "label-lg" | "label-md" | "label-sm" | "label-xs" | "caption" | "overline"
+    variant: TextVariant
     as: ElementType (override the auto-selected HTML element)
 - Defaults: variant="body-md"
 - Default element mapping:
@@ -1481,6 +1488,124 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Example:
   <DateTimePicker value={dateTime} onChange={setDateTime} timeFormat="12h" minuteStep={15} />
 
+## TimePicker
+- Import: @devalok/shilp-sutra/composed/date-picker
+- Server-safe: No
+- Props:
+    value: Date | null (time stored as a Date object)
+    onChange: (date: Date) => void
+    format: "12h" | "24h" (default: "12h")
+    minuteStep: number (default: 1) — step interval for minutes column
+    secondStep: number (default: 1) — step interval for seconds column
+    showSeconds: boolean (default: false) — whether to show the seconds column
+    placeholder: string (default: "Pick a time")
+    disabled: boolean (default: false)
+    className: string
+- Defaults: format="12h", minuteStep=1, secondStep=1, showSeconds=false
+- Example:
+  <TimePicker value={time} onChange={setTime} format="24h" minuteStep={15} />
+  <TimePicker value={time} onChange={setTime} showSeconds />
+- Gotchas:
+    - Time is stored inside a Date object — only hours/minutes/seconds are meaningful
+    - Opens as a popover with scrollable columns for hours, minutes, (optional) seconds, and AM/PM
+    - When no value is set, selecting a time part creates a Date from the current date/time
+
+## CalendarGrid
+- Import: @devalok/shilp-sutra/composed/date-picker
+- Server-safe: No
+- Props:
+    currentMonth: Date (REQUIRED) — which month to display
+    selected: Date | null — single selected date
+    rangeStart: Date | null — range selection start
+    rangeEnd: Date | null — range selection end
+    hoverDate: Date | null — date currently hovered (for range preview)
+    onSelect: (date: Date) => void (REQUIRED) — called when user clicks a date
+    onHover: (date: Date | null) => void — called on mouse enter/leave
+    onMonthChange: (date: Date) => void (REQUIRED) — called for prev/next month navigation
+    onHeaderClick: () => void — called when month/year header is clicked (e.g. to switch to month/year picker view)
+    disabledDates: (date: Date) => boolean
+    minDate: Date
+    maxDate: Date
+    hidePrevNav: boolean — hide previous-month arrow
+    hideNextNav: boolean — hide next-month arrow
+    events: CalendarEvent[] — dot indicators on dates. CalendarEvent: { date: Date, color?: string, label?: string }
+- Example:
+  <CalendarGrid
+    currentMonth={currentMonth}
+    selected={selectedDate}
+    onSelect={setSelectedDate}
+    onMonthChange={setCurrentMonth}
+    events={[{ date: new Date('2026-03-15'), color: 'var(--color-success)' }]}
+  />
+- Gotchas:
+    - This is a low-level building block — prefer DatePicker/DateRangePicker for most use cases
+    - Full keyboard navigation: ArrowLeft/Right/Up/Down, Home/End, Enter/Space
+    - Up to 3 event dots render per day cell
+
+## YearPicker
+- Import: @devalok/shilp-sutra/composed/date-picker
+- Server-safe: No
+- Props:
+    currentYear: number (REQUIRED) — centers the decade grid
+    selectedYear: number — highlights the selected year
+    onYearSelect: (year: number) => void (REQUIRED)
+    minDate: Date — disables years before this date's year
+    maxDate: Date — disables years after this date's year
+- Example:
+  <YearPicker currentYear={2026} selectedYear={2026} onYearSelect={handleYear} />
+- Gotchas:
+    - Displays a 12-year grid (3 columns x 4 rows) based on the decade of currentYear
+    - This is a low-level building block used internally by DatePicker
+
+## MonthPicker
+- Import: @devalok/shilp-sutra/composed/date-picker
+- Server-safe: No
+- Props:
+    currentYear: number (REQUIRED) — which year's months to display
+    selectedMonth: number (0-11) — highlights the selected month
+    onMonthSelect: (month: number) => void (REQUIRED) — returns 0-11
+    minDate: Date — disables months before this date
+    maxDate: Date — disables months after this date
+- Example:
+  <MonthPicker currentYear={2026} selectedMonth={2} onMonthSelect={handleMonth} />
+- Gotchas:
+    - Month values are 0-indexed (Jan=0, Dec=11) — same as JavaScript Date.getMonth()
+    - Displays a 4-column grid of abbreviated month names (Jan, Feb, Mar, ...)
+    - This is a low-level building block used internally by DatePicker
+
+## Presets (Date Range Presets)
+- Import: @devalok/shilp-sutra/composed/date-picker
+- Server-safe: No
+- Types:
+    PresetKey: 'today' | 'yesterday' | 'last7days' | 'last30days' | 'thisMonth' | 'lastMonth' | 'thisYear'
+- Props:
+    presets: PresetKey[] (REQUIRED) — which preset buttons to show
+    onSelect: (start: Date, end: Date) => void (REQUIRED) — called with the computed date range
+    className: string
+- Example:
+  <Presets
+    presets={['today', 'last7days', 'last30days', 'thisMonth']}
+    onSelect={(start, end) => setRange({ start, end })}
+  />
+- Gotchas:
+    - Typically used alongside DateRangePicker (pass presets prop to DateRangePicker for built-in sidebar)
+    - Each preset computes start-of-day / end-of-day boundaries using date-fns
+
+## useCalendar
+- Import: @devalok/shilp-sutra/composed/date-picker
+- Hook: useCalendar(initialMonth?: Date)
+- Returns:
+    currentMonth: Date — the current displayed month
+    setCurrentMonth: (date: Date) => void
+    goToPreviousMonth: () => void
+    goToNextMonth: () => void
+    goToMonth: (month: number) => void — 0-indexed month
+    goToYear: (year: number) => void
+- Example:
+  const { currentMonth, goToNextMonth, goToPreviousMonth, goToMonth, goToYear } = useCalendar()
+  <CalendarGrid currentMonth={currentMonth} onMonthChange={setCurrentMonth} ... />
+- Gotchas: This is a convenience hook for managing calendar month state — used internally by DatePicker
+
 ## EmptyState
 - Import: @devalok/shilp-sutra/composed/empty-state
 - Server-safe: Yes
@@ -1513,6 +1638,7 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
     emptyState: ReactNode — empty state content
     compact: boolean — tighter spacing, no avatars, smaller text
     maxInitialItems: number — truncate with "Show all (N)" toggle
+- Type: ActivityItem = { id: string, actor?: { name: string, image?: string }, action: string | ReactNode, timestamp: Date | string, icon?: ReactNode, color?: 'default' | 'success' | 'warning' | 'error' | 'info', detail?: ReactNode }
 - Example:
   <ActivityFeed
     items={[
@@ -1606,8 +1732,9 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## PriorityIndicator
 - Import: @devalok/shilp-sutra/composed/priority-indicator
 - Server-safe: Yes
+- Type: Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'urgent'
 - Props:
-    priority: "LOW" | "MEDIUM" | "HIGH" | "URGENT" (case-insensitive)
+    priority: Priority
     display: "compact" | "full" (default: "full")
 - Example:
   <PriorityIndicator priority="HIGH" />
@@ -1710,6 +1837,42 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
   <StatusBadge color="warning" label="In Review" size="sm" />
 - Gotchas: When color is set, it takes priority over status for styling
 
+## UploadProgress
+- Import: @devalok/shilp-sutra/composed/upload-progress
+- Server-safe: No
+- Types:
+    UploadFile: { id: string, name: string, size: number (bytes), progress?: number (0-100, undefined = indeterminate), status: 'pending' | 'uploading' | 'processing' | 'complete' | 'error', error?: string, previewUrl?: string }
+- Props:
+    files: UploadFile[] (REQUIRED)
+    onRemove: (fileId: string) => void — called when user cancels/removes a file
+    onRetry: (fileId: string) => void — called when user retries a failed upload
+    onDismissAll: () => void — "Dismiss all" button appears when all files are terminal (complete or error)
+    variant: "default" | "compact" (default: "default") — default = two-line layout with progress bar; compact = single-line layout
+    showSize: boolean (default: true) — show file size (default variant only)
+    className: string
+- Also exported: formatFileSize(bytes: number) => string — utility to format bytes as human-readable (B, KB, MB, GB)
+- Defaults: variant="default", showSize=true
+- Example:
+  <UploadProgress
+    files={[
+      { id: '1', name: 'report.pdf', size: 1048576, status: 'uploading', progress: 45 },
+      { id: '2', name: 'photo.jpg', size: 204800, status: 'complete', previewUrl: '/thumb.jpg' },
+      { id: '3', name: 'data.csv', size: 51200, status: 'error', error: 'Network timeout' },
+    ]}
+    onRemove={(id) => removeFile(id)}
+    onRetry={(id) => retryUpload(id)}
+    onDismissAll={() => clearAll()}
+  />
+  <UploadProgress files={uploads} variant="compact" onRemove={removeFile} />
+- Gotchas:
+    - Returns null when files array is empty
+    - Summary header shows completion count and error count
+    - Border color changes based on state: green when all complete, red tint when all terminal with errors
+    - File icon auto-detects image files by extension or previewUrl presence
+    - Status 'processing' renders a spinner icon and indeterminate progress
+    - Screen reader announcements via aria-live region for completion/error events
+    - Staggered slide-up animation (30ms delay per file)
+
 ---
 
 # SHELL COMPONENTS
@@ -1727,9 +1890,11 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
     extraGroups: CommandGroup[]
     onNavigate: (path: string) => void
     onSearch: (query: string) => void
-    searchResults: SearchResult[] — { id, title, snippet?, entityType, projectId?, metadata? }
+    searchResults: SearchResult[]
     isSearching: boolean (shows loading state while search is in progress)
     onSearchResultSelect: (result: SearchResult) => void
+- Type: SearchResult = { id: string, title: string, snippet?: string, entityType: string, projectId?: string | null, metadata?: Record<string, unknown> }
+- Type: AppCommandPaletteUser = { name: string, role?: string }
 - Example:
   <AppCommandPalette
     user={{ name: 'John', role: 'admin' }}
@@ -1749,7 +1914,10 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
     logo: ReactNode
     footerLinks: Array<{ label: string, href: string }>
     className: string
-- NavItem shape: { title, href, icon: ReactNode, exact?: boolean }
+- Type: NavItem = { title: string, href: string, icon: ReactNode, exact?: boolean, badge?: string | number, children?: NavSubItem[], defaultOpen?: boolean }
+- Type: NavSubItem = { title: string, href: string, icon?: ReactNode, exact?: boolean }
+- Type: NavGroup = { label: string, items: NavItem[], action?: ReactNode }
+- Type: SidebarUser = { name: string, email?: string, image?: string | null, designation?: string, role?: string }
 - Example:
   <AppSidebar
     currentPath="/dashboard"
@@ -1867,10 +2035,12 @@ Deprecated props:
 - Server-safe: No
 - Props:
     currentPath: string
-    user: BottomNavbarUser | null (optional) — { name, role? }. Not required to render.
-    primaryItems: BottomNavItem[] (max 4 recommended) — { title, href, icon, exact?, badge?: number }
+    user: BottomNavbarUser | null (optional). Not required to render.
+    primaryItems: BottomNavItem[] (max 4 recommended)
     moreItems: BottomNavItem[] (overflow items in "More" menu)
     className: string
+- Type: BottomNavItem = { title: string, href: string, icon: ReactNode, exact?: boolean, badge?: number }
+- Type: BottomNavbarUser = { name: string, role?: string }
 - Example:
   <BottomNavbar
     currentPath="/dashboard"
@@ -1899,8 +2069,9 @@ Deprecated props:
 - Import: @devalok/shilp-sutra/shell/notification-center
 - Server-safe: No
 - Props:
-    notifications: Notification[] — { id, title, body?, tier: "INFO"|"IMPORTANT"|"CRITICAL", isRead, createdAt, entityType?, entityId?, projectId?, project?, actions?: NotificationAction[] }
-    NotificationAction: { label: string, variant?: "primary"|"default"|"danger", onClick: (id: string) => void }
+    notifications: Notification[]
+- Type: Notification = { id: string, title: string, body?: string | null, tier: 'INFO' | 'IMPORTANT' | 'CRITICAL', isRead: boolean, createdAt: string, entityType?: string | null, entityId?: string | null, projectId?: string | null, project?: { title: string } | null, actions?: NotificationAction[] }
+- Type: NotificationAction = { label: string, variant?: 'primary' | 'default' | 'danger', onClick: (id: string) => void }
     unreadCount: number (derived from notifications if not provided)
     open: boolean (controlled mode)
     onOpenChange: (open: boolean) => void
@@ -1934,8 +2105,10 @@ Deprecated props:
 - Import: @devalok/shilp-sutra/shell/notification-preferences
 - Server-safe: No
 - Props:
-    preferences: NotificationPreference[] — { id, userId?, projectId, channel, minTier, muted }
-    projects: NotificationProject[] — { id, title }
+    preferences: NotificationPreference[]
+    projects: NotificationProject[]
+- Type: NotificationPreference = { id: string, userId?: string, projectId: string | null, channel: string, minTier: string, muted: boolean }
+- Type: NotificationProject = { id: string, title: string }
     isLoading: boolean
     onSave: (preference: { projectId, channel, minTier, muted }) => void | Promise<void>
     onToggleMute: (preference: NotificationPreference) => void | Promise<void>
@@ -1966,7 +2139,8 @@ Deprecated props:
     notificationSlot: ReactNode (render NotificationCenter here)
     userMenuItems?: UserMenuItem[] — custom items between Profile and Dark/Light Mode toggle
     className: string
-- UserMenuItem: { label: string, icon?: ReactNode, href?: string, onClick?: () => void, separator?: boolean, color?: string, badge?: string | boolean, disabled?: boolean }
+- Type: TopBarUser = { name: string, email?: string, image?: string | null }
+- Type: UserMenuItem = { label: string, icon?: ReactNode, href?: string, onClick?: () => void, separator?: boolean, color?: string, badge?: string | boolean, disabled?: boolean }
     href — navigates via onNavigate callback
     onClick — custom action (takes precedence over href)
     separator — renders a DropdownMenuSeparator before this item
@@ -2047,3 +2221,10 @@ Deprecated props:
 ## motion / duration / easings / durations
 - Import: @devalok/shilp-sutra (barrel export)
 - Design system motion tokens for custom animations
+- Type: MotionMode = 'productive' | 'expressive'
+- Type: MotionCategory = 'standard' | 'entrance' | 'exit'
+- Type: DurationToken = 'instant' | 'fast-01' | 'fast-02' | 'moderate-01' | 'moderate-02' | 'slow-01' | 'slow-02'
+- Function: motion(category: MotionCategory, mode: MotionMode) => string — returns CSS cubic-bezier string
+- Function: duration(token: DurationToken) => string — returns CSS duration string (e.g. '150ms')
+- Object: easings — Record<MotionMode, Record<MotionCategory, string>> — all cubic-bezier values
+- Object: durations — Record<DurationToken, string> — { instant: '0ms', fast-01: '70ms', fast-02: '110ms', moderate-01: '150ms', moderate-02: '240ms', slow-01: '400ms', slow-02: '700ms' }

package/llms.txt

@@ -108,7 +108,7 @@ Components with two-axis system: Button, Badge, Alert, Chip, Toast, Banner, Prog
 ### Inputs & Controls
 - Button: variant(solid|default|outline|ghost|link) color(default|error) size(sm|md|lg|icon) + loading, startIcon, endIcon, asChild
 - IconButton: icon(ReactNode, required) shape(square|circle) size(sm|md|lg) + aria-label required
-- Input: size(sm|md|lg) state(default|error|warning|success) + startIcon, endIcon
+- Input: size(sm|md|lg) state(InputState) + startIcon, endIcon. Type: InputState = 'default' | 'error' | 'warning' | 'success'
 - SearchInput: size(sm|md|lg) + loading, onClear
 - NumberInput: value + onValueChange, min, max, step (controlled only)
 - Textarea: size(sm|md|lg) state(default|error|warning|success)
@@ -119,7 +119,7 @@ Components with two-axis system: Button, Badge, Alert, Chip, Toast, Banner, Prog
 - Select > SelectTrigger(size) > SelectValue; SelectContent > SelectItem(value)
 - Toggle: variant(default|outline) size(sm|md|lg)
 - ToggleGroup > ToggleGroupItem (variant/size propagate from root)
-- SegmentedControl > SegmentedControlItem: variant(filled|tonal) size(sm|md|lg)
+- SegmentedControl > SegmentedControlItem: variant(filled|tonal) size(sm|md|lg). Types: SegmentedControlOption = { id, text, icon? }, SegmentedControlSize = 'sm' | 'md' | 'lg', SegmentedControlVariant = 'filled' | 'tonal'
 - Slider: standard Radix slider
 
 ### Feedback & Notifications
@@ -137,10 +137,10 @@ NOTIFICATION SELECTION GUIDE:
 ### Data Display
 - Badge: variant(subtle|solid|outline) color(default|info|success|error|warning|brand|accent + 7 category colors) size(xs|sm|md|lg) + onDismiss
 - Chip: variant(subtle|outline) color(default|primary|success|error|warning|info + 7 category) size(sm|md|lg) label(string, REQUIRED) + onDismiss, onClick
-- Avatar: size(xs|sm|md|lg|xl) shape(circle|square|rounded) status(online|offline|busy|away) > AvatarImage + AvatarFallback
+- Avatar: size(xs|sm|md|lg|xl) shape(circle|square|rounded) status(AvatarStatus) > AvatarImage + AvatarFallback. Type: AvatarStatus = 'online' | 'offline' | 'busy' | 'away'
 - Card: variant(default|elevated|outline|flat) interactive(boolean) > CardHeader > CardTitle, CardDescription; CardContent; CardFooter
 - Table > TableHeader > TableRow > TableHead; TableBody > TableRow > TableCell; TableFooter; TableCaption
-- Text: variant(heading-2xl|heading-xl|heading-lg|heading-md|heading-sm|heading-xs|body-lg|body-md|body-sm|body-xs|label-lg|label-md|label-sm|label-xs|caption|overline) as(element)
+- Text: variant(TextVariant) as(element). Type: TextVariant = 'heading-2xl' | 'heading-xl' | 'heading-lg' | 'heading-md' | 'heading-sm' | 'heading-xs' | 'body-lg' | 'body-md' | 'body-sm' | 'body-xs' | 'label-lg' | 'label-md' | 'label-sm' | 'label-xs' | 'caption' | 'overline'
 - Code: variant(inline|block)
 - Skeleton: variant(rectangle|circle|text) animation(pulse|shimmer|none)
 - StatCard: title, value, description, trend, icon
@@ -171,7 +171,7 @@ NOTIFICATION SELECTION GUIDE:
 - Sidebar: complex — see llms-full.txt for complete tree
 
 ### Form Pattern
-- FormField: state(helper|error|warning|success) > Label + Input + FormHelperText
+- FormField: state(FormHelperState) > Label + Input + FormHelperText. Type: FormHelperState = 'helper' | 'error' | 'warning' | 'success'
 - useFormField() hook returns { state, helperTextId, required } from FormField context
 - Wire accessibility: const { state, helperTextId } = useFormField(); then aria-describedby={helperTextId}, aria-invalid={state === 'error'}
 - Input/Textarea auto-wire from FormField context (no manual hookup needed). Explicit props override.
@@ -183,18 +183,27 @@ NOTIFICATION SELECTION GUIDE:
 - StatusBadge: DISCRIMINATED UNION — pass status OR color, not both. status(active|pending|approved|rejected|completed|blocked|cancelled|draft) color(success|warning|error|info|neutral) size(sm|md)
 - ContentCard: variant(default|outline|ghost) padding(default|compact|spacious|none)
 - EmptyState: icon(ReactNode or ComponentType), title(required), description, action(ReactNode), compact
-- PriorityIndicator: priority(LOW|MEDIUM|HIGH|URGENT) display(compact|full)
+- PriorityIndicator: priority(Priority) display(compact|full). Type: Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'urgent'
 - SimpleTooltip: wraps Tooltip compound into single component
-- DatePicker, DateRangePicker, DateTimePicker, TimePicker
+- DatePicker, DateRangePicker, DateTimePicker
+- TimePicker: standalone time selector — value(Date|null), onChange, format('12h'|'24h'), minuteStep, showSeconds, disabled
+- CalendarGrid: low-level calendar widget — currentMonth, selected, rangeStart/End, onSelect, onMonthChange, events(CalendarEvent[])
+- YearPicker: decade year grid — currentYear, selectedYear, onYearSelect, minDate, maxDate
+- MonthPicker: month grid — currentYear, selectedMonth(0-11), onMonthSelect, minDate, maxDate
+- Presets: date range quick-select buttons — presets(PresetKey[]), onSelect(start, end). Keys: today, yesterday, last7days, last30days, thisMonth, lastMonth, thisYear
+- useCalendar: hook for calendar month state — returns currentMonth, goToPreviousMonth, goToNextMonth, goToMonth, goToYear
+- UploadProgress: file upload tracker — files(UploadFile[]), onRemove, onRetry, onDismissAll, variant(default|compact), showSize. Status: pending|uploading|processing|complete|error. Also exports formatFileSize()
 - RichTextEditor: Tiptap editor — bold/italic/underline/strike/highlight, headings, blockquote, lists (bullet/ordered/task), code, links, images (paste/drop/upload), file attachments, @mentions, emoji picker + :shortcode:, text alignment, HR. Props: onImageUpload?, onFileUpload?, mentions?, onMentionSearch?, onMentionSelect?
 - RichTextViewer: read-only renderer for RichTextEditor HTML content (renders all above content types)
+- ActivityFeed: items(ActivityItem[]), onLoadMore, loading, hasMore, emptyState, compact, maxInitialItems. Type: ActivityItem = { id, actor?, action, timestamp, icon?, color?, detail? }
 - CommandPalette, MemberPicker
 - ErrorDisplay, GlobalLoading
-- Loading skeletons: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton, DashboardSkeleton, etc.
+- Loading skeletons: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton
+- Page skeletons: DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton (no props, server-safe)
 
 ### Shell Components (app-level layout)
-- TopBar: pageTitle, user, onNavigate, onLogout, notificationSlot, mobileLogo, userMenuItems?(UserMenuItem[] — custom items between Profile and theme toggle, supports icon, href, onClick, separator, badge, disabled, color)
-- AppSidebar: navigation tree with NavItem[], NavGroup[]
+- TopBar: pageTitle, user, onNavigate, onLogout, notificationSlot, mobileLogo, userMenuItems?(UserMenuItem[]). Types: TopBarUser = { name, email?, image? }, UserMenuItem = { label, icon?, href?, onClick?, separator?, color?, badge?, disabled? }
+- AppSidebar: navigation tree with NavItem[], NavGroup[]. Types: NavItem = { title, href, icon, exact?, badge?, children?, defaultOpen? }, NavSubItem = { title, href, icon?, exact? }, NavGroup = { label, items, action? }, SidebarUser = { name, email?, image?, designation?, role? }
 
 ### AppSidebar (v0.10.0 additions)
 - NavItem.children?: NavSubItem[] — collapsible sub-list with chevron toggle
@@ -206,14 +215,20 @@ NOTIFICATION SELECTION GUIDE:
 - preFooterSlot?: ReactNode — content between navigation and footer
 - renderItem?: (item, defaultRender) => ReactNode | null — custom item rendering
 
-- BottomNavbar: mobile navigation, user is optional (not required to render)
-- NotificationCenter: notifications[], onMarkRead, onMarkAllRead, onNavigate, getNotificationRoute?(returns string|null, fallback null), footerSlot?, emptyState?, headerActions?, popoverClassName?, onDismiss?(id). Notification.actions?: NotificationAction[] for inline buttons (e.g. Approve/Deny)
-- AppCommandPalette: user, isAdmin, onNavigate, onSearch, searchResults, isSearching, onSearchResultSelect
+- BottomNavbar: mobile navigation, user is optional. Types: BottomNavItem = { title, href, icon, exact?, badge? }, BottomNavbarUser = { name, role? }
+- NotificationCenter: notifications[], onMarkRead, onMarkAllRead, onNavigate, getNotificationRoute?, footerSlot?, emptyState?, headerActions?, popoverClassName?, onDismiss?(id). Types: Notification = { id, title, body?, tier, isRead, createdAt, entityType?, entityId?, projectId?, project?, actions? }, NotificationAction = { label, variant?, onClick }
+- NotificationPreferences: preferences[], projects[], onSave, onToggleMute, onUpdateTier, onDelete. Types: NotificationPreference = { id, userId?, projectId, channel, minTier, muted }, NotificationProject = { id, title }
+- AppCommandPalette: user, isAdmin, onNavigate, onSearch, searchResults, isSearching, onSearchResultSelect. Types: SearchResult = { id, title, snippet?, entityType, projectId?, metadata? }, AppCommandPaletteUser = { name, role? }
+- LinkProvider: wraps app with router-agnostic Link component — component(ForwardRefComponent), children. useLink() hook returns the Link component.
+
+### Motion Tokens
+- motion(category, mode) => CSS cubic-bezier string. duration(token) => CSS duration string. easings: Record<MotionMode, Record<MotionCategory, string>>. durations: Record<DurationToken, string> = { instant: '0ms', fast-01: '70ms', fast-02: '110ms', moderate-01: '150ms', moderate-02: '240ms', slow-01: '400ms', slow-02: '700ms' }
 
 ### Hooks
-- useToast(): returns { toast, toasts, dismiss } — toast({ title, description, color })
+- useToast(): returns { toast, toasts, dismiss } — toast({ title, description, color }). Also: import { toast } from '@devalok/shilp-sutra/hooks/use-toast' for imperative usage without hook
 - useColorMode(): returns { colorMode, setColorMode, toggleColorMode }
 - useMobile(): returns boolean (true if viewport < 768px)
+- useLink(): returns router-agnostic Link component from LinkProvider context (shell/link-context)
 
 ## Server-Safe Components (no "use client")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "Devalok Design System — tokens, components, and patterns for Next.js",
   "license": "MIT",
   "type": "module",