@devalok/shilp-sutra 0.17.0 → 0.17.1

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:
@@ -1631,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={[
@@ -1724,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" />
@@ -1881,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' }}
@@ -1903,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"
@@ -2021,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"
@@ -2053,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
@@ -2088,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>
@@ -2120,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
@@ -2201,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,7 +183,7 @@ 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: standalone time selector — value(Date|null), onChange, format('12h'|'24h'), minuteStep, showSeconds, disabled
@@ -195,14 +195,15 @@ NOTIFICATION SELECTION GUIDE:
 - 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
 - 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
@@ -214,11 +215,15 @@ 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 }). Also: import { toast } from '@devalok/shilp-sutra/hooks/use-toast' for imperative usage without hook
 - useColorMode(): returns { colorMode, setColorMode, toggleColorMode }

package/package.json

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