@devalok/shilp-sutra 0.34.0 → 0.36.0

package/docs/components/shell/command-registry.md

@@ -1,48 +1,48 @@
-# CommandRegistry
-
-- Import: @devalok/shilp-sutra/shell/command-registry
-- Server-safe: No
-- Category: shell
-
-Exports: CommandRegistryProvider, useCommandRegistry
-
-## Props
-
-### CommandRegistryProvider
-    children: ReactNode
-    registry: CommandRegistry (REQUIRED)
-
-CommandRegistry: { pages: CommandPageItem[], adminPages: CommandPageItem[] }
-CommandPageItem: { id: string, label: string, icon: ReactNode, path: string, keywords?: string[] }
-
-### useCommandRegistry hook
-    Returns: CommandRegistry | null
-
-## Defaults
-    None
-
-## Example
-```jsx
-<CommandRegistryProvider
-  registry={{
-    pages: [
-      { id: 'dashboard', label: 'Dashboard', icon: <IconHome />, path: '/dashboard' },
-      { id: 'projects', label: 'Projects', icon: <IconFolder />, path: '/projects' },
-    ],
-    adminPages: [
-      { id: 'users', label: 'Manage Users', icon: <IconUsers />, path: '/admin/users' },
-    ],
-  }}
->
-  <App />
-</CommandRegistryProvider>
-```
-
-## Gotchas
-- Provides the command registry context consumed by AppCommandPalette
-- Place at app root, wrapping both AppCommandPalette and the rest of the app
-- `useCommandRegistry()` returns `null` if no provider is found — handle this case
-
-## Changes
-### v0.1.0
-- **Added** Initial release
+# CommandRegistry
+
+- Import: @devalok/shilp-sutra/shell/command-registry
+- Server-safe: No
+- Category: shell
+
+Exports: CommandRegistryProvider, useCommandRegistry
+
+## Props
+
+### CommandRegistryProvider
+    children: ReactNode
+    registry: CommandRegistry (REQUIRED)
+
+CommandRegistry: { pages: CommandPageItem[], adminPages: CommandPageItem[] }
+CommandPageItem: { id: string, label: string, icon: ReactNode, path: string, keywords?: string[] }
+
+### useCommandRegistry hook
+    Returns: CommandRegistry | null
+
+## Defaults
+    None
+
+## Example
+```jsx
+<CommandRegistryProvider
+  registry={{
+    pages: [
+      { id: 'dashboard', label: 'Dashboard', icon: <IconHome />, path: '/dashboard' },
+      { id: 'projects', label: 'Projects', icon: <IconFolder />, path: '/projects' },
+    ],
+    adminPages: [
+      { id: 'users', label: 'Manage Users', icon: <IconUsers />, path: '/admin/users' },
+    ],
+  }}
+>
+  <App />
+</CommandRegistryProvider>
+```
+
+## Gotchas
+- Provides the command registry context consumed by AppCommandPalette
+- Place at app root, wrapping both AppCommandPalette and the rest of the app
+- `useCommandRegistry()` returns `null` if no provider is found — handle this case
+
+## Changes
+### v0.1.0
+- **Added** Initial release

package/docs/components/shell/link-context.md

@@ -1,41 +1,41 @@
-# LinkProvider
-
-- Import: @devalok/shilp-sutra/shell/link-context
-- Server-safe: No
-- Category: shell
-
-Exports: LinkProvider, useLink
-
-## Props
-
-### LinkProvider
-    component: ForwardRefComponent (e.g. Next.js Link, Remix Link)
-    children: ReactNode
-
-### useLink hook
-    Returns: LinkComponent
-
-## Defaults
-    Without LinkProvider, shell components render plain `<a>` tags
-
-## Example
-```jsx
-import Link from 'next/link'
-
-<LinkProvider component={Link}>
-  <AppSidebar ... />
-  <BottomNavbar ... />
-</LinkProvider>
-```
-
-## Gotchas
-- Without LinkProvider, shell components render plain `<a>` tags (full page reloads)
-- Place at app root, wrapping all shell components that render navigation links
-- The `component` prop must be a forwardRef component (Next.js Link, Remix Link, etc.)
-
-## Changes
-### v0.1.1
-- **Added** Shell components decoupled from Next.js — replaced hard `next/link` import with polymorphic `LinkProvider`/`useLink` context
-
-### v0.1.0
-- **Added** Initial release (with hardcoded Next.js Link dependency)
+# LinkProvider
+
+- Import: @devalok/shilp-sutra/shell/link-context
+- Server-safe: No
+- Category: shell
+
+Exports: LinkProvider, useLink
+
+## Props
+
+### LinkProvider
+    component: ForwardRefComponent (e.g. Next.js Link, Remix Link)
+    children: ReactNode
+
+### useLink hook
+    Returns: LinkComponent
+
+## Defaults
+    Without LinkProvider, shell components render plain `<a>` tags
+
+## Example
+```jsx
+import Link from 'next/link'
+
+<LinkProvider component={Link}>
+  <AppSidebar ... />
+  <BottomNavbar ... />
+</LinkProvider>
+```
+
+## Gotchas
+- Without LinkProvider, shell components render plain `<a>` tags (full page reloads)
+- Place at app root, wrapping all shell components that render navigation links
+- The `component` prop must be a forwardRef component (Next.js Link, Remix Link, etc.)
+
+## Changes
+### v0.1.1
+- **Added** Shell components decoupled from Next.js — replaced hard `next/link` import with polymorphic `LinkProvider`/`useLink` context
+
+### v0.1.0
+- **Added** Initial release (with hardcoded Next.js Link dependency)

package/docs/components/shell/notification-center.md

@@ -1,63 +1,63 @@
-# NotificationCenter
-
-- Import: @devalok/shilp-sutra/shell/notification-center
-- Server-safe: No
-- Category: shell
-
-## Props
-    notifications?: Notification[]
-    unreadCount?: number (derived from notifications if not provided)
-    open?: boolean (controlled mode)
-    onOpenChange?: (open: boolean) => void
-    isLoading?: boolean
-    hasMore?: boolean
-    onFetchMore?: () => void
-    onMarkRead?: (id: string) => void
-    onMarkAllRead?: () => void
-    onNavigate?: (path: string) => void — called when a notification with a route is clicked
-    getNotificationRoute?: (notification: Notification) => string | null — returns route for a notification; defaults to () => null
-    footerSlot?: ReactNode — content rendered in a sticky footer below the scroll area
-    emptyState?: ReactNode — replaces default empty state UI
-    headerActions?: ReactNode — extra action buttons after "Mark all read"
-    popoverClassName?: string — override default popover dimensions
-    onDismiss?: (id: string) => void — when provided, each notification shows a dismiss button
-
-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[] }
-NotificationAction: { label: string, variant?: 'primary' | 'default' | 'danger', onClick: (id: string) => void }
-
-## Defaults
-    getNotificationRoute defaults to () => null (no hardcoded routes)
-
-## Example
-```jsx
-<NotificationCenter
-  notifications={notifications}
-  onMarkRead={markAsRead}
-  onMarkAllRead={markAllAsRead}
-  onNavigate={(path) => router.push(path)}
-  getNotificationRoute={(n) => n.entityType === 'task' ? `/tasks/${n.entityId}` : null}
-  onDismiss={(id) => dismissNotification(id)}
-  footerSlot={<Link href="/notifications">View all notifications</Link>}
-  emptyState={<p>You're all caught up!</p>}
-  headerActions={<Button variant="ghost" size="sm">Settings</Button>}
-  popoverClassName="w-[480px]"
-/>
-```
-
-## Gotchas
-- Typically rendered inside TopBar's `notificationSlot` prop
-- `getNotificationRoute` must be provided for clickable notifications — no hardcoded routes
-- Tier dot doubles as read/unread marker (opacity-based)
-- `onDismiss` enables per-notification dismiss buttons when provided
-
-## Changes
-### v0.13.0
-- **Added** `NotificationAction` type and `actions` prop on `Notification` — inline action buttons per notification row
-- **Fixed** Tier dot now doubles as read/unread marker (opacity-based) — removed separate unread indicator dot
-
-### v0.1.1
-- **Changed** Decoupled from Next.js via LinkProvider
-- **Fixed** Added `aria-label` to bell button
-
-### v0.1.0
-- **Added** Initial release
+# NotificationCenter
+
+- Import: @devalok/shilp-sutra/shell/notification-center
+- Server-safe: No
+- Category: shell
+
+## Props
+    notifications?: Notification[]
+    unreadCount?: number (derived from notifications if not provided)
+    open?: boolean (controlled mode)
+    onOpenChange?: (open: boolean) => void
+    isLoading?: boolean
+    hasMore?: boolean
+    onFetchMore?: () => void
+    onMarkRead?: (id: string) => void
+    onMarkAllRead?: () => void
+    onNavigate?: (path: string) => void — called when a notification with a route is clicked
+    getNotificationRoute?: (notification: Notification) => string | null — returns route for a notification; defaults to () => null
+    footerSlot?: ReactNode — content rendered in a sticky footer below the scroll area
+    emptyState?: ReactNode — replaces default empty state UI
+    headerActions?: ReactNode — extra action buttons after "Mark all read"
+    popoverClassName?: string — override default popover dimensions
+    onDismiss?: (id: string) => void — when provided, each notification shows a dismiss button
+
+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[] }
+NotificationAction: { label: string, variant?: 'primary' | 'default' | 'danger', onClick: (id: string) => void }
+
+## Defaults
+    getNotificationRoute defaults to () => null (no hardcoded routes)
+
+## Example
+```jsx
+<NotificationCenter
+  notifications={notifications}
+  onMarkRead={markAsRead}
+  onMarkAllRead={markAllAsRead}
+  onNavigate={(path) => router.push(path)}
+  getNotificationRoute={(n) => n.entityType === 'task' ? `/tasks/${n.entityId}` : null}
+  onDismiss={(id) => dismissNotification(id)}
+  footerSlot={<Link href="/notifications">View all notifications</Link>}
+  emptyState={<p>You're all caught up!</p>}
+  headerActions={<Button variant="ghost" size="sm">Settings</Button>}
+  popoverClassName="w-[480px]"
+/>
+```
+
+## Gotchas
+- Typically rendered inside TopBar's `notificationSlot` prop
+- `getNotificationRoute` must be provided for clickable notifications — no hardcoded routes
+- Tier dot doubles as read/unread marker (opacity-based)
+- `onDismiss` enables per-notification dismiss buttons when provided
+
+## Changes
+### v0.13.0
+- **Added** `NotificationAction` type and `actions` prop on `Notification` — inline action buttons per notification row
+- **Fixed** Tier dot now doubles as read/unread marker (opacity-based) — removed separate unread indicator dot
+
+### v0.1.1
+- **Changed** Decoupled from Next.js via LinkProvider
+- **Fixed** Added `aria-label` to bell button
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/shell/notification-preferences.md

@@ -1,42 +1,42 @@
-# NotificationPreferences
-
-- Import: @devalok/shilp-sutra/shell/notification-preferences
-- Server-safe: No
-- Category: shell
-
-## Props
-    preferences?: NotificationPreference[]
-    projects?: NotificationProject[]
-    isLoading?: boolean
-    onSave?: (preference: { projectId, channel, minTier, muted }) => void | Promise<void>
-    onToggleMute?: (preference: NotificationPreference) => void | Promise<void>
-    onUpdateTier?: (preference: NotificationPreference, newTier: string) => void | Promise<void>
-    onDelete?: (preferenceId: string) => void | Promise<void>
-    className?: string
-
-NotificationPreference: { id: string, userId?: string, projectId: string | null, channel: string, minTier: string, muted: boolean }
-NotificationProject: { id: string, title: string }
-
-## Defaults
-    None
-
-## Example
-```jsx
-<NotificationPreferences
-  preferences={prefs}
-  projects={projectList}
-  onSave={handleSavePref}
-  onToggleMute={handleToggleMute}
-  onUpdateTier={handleUpdateTier}
-  onDelete={handleDeletePref}
-/>
-```
-
-## Gotchas
-- Manages per-project notification preferences (channel, tier, mute)
-- All callback props support async (Promise<void>) for server-side operations
-- Typically rendered on a settings/preferences page
-
-## Changes
-### v0.1.0
-- **Added** Initial release
+# NotificationPreferences
+
+- Import: @devalok/shilp-sutra/shell/notification-preferences
+- Server-safe: No
+- Category: shell
+
+## Props
+    preferences?: NotificationPreference[]
+    projects?: NotificationProject[]
+    isLoading?: boolean
+    onSave?: (preference: { projectId, channel, minTier, muted }) => void | Promise<void>
+    onToggleMute?: (preference: NotificationPreference) => void | Promise<void>
+    onUpdateTier?: (preference: NotificationPreference, newTier: string) => void | Promise<void>
+    onDelete?: (preferenceId: string) => void | Promise<void>
+    className?: string
+
+NotificationPreference: { id: string, userId?: string, projectId: string | null, channel: string, minTier: string, muted: boolean }
+NotificationProject: { id: string, title: string }
+
+## Defaults
+    None
+
+## Example
+```jsx
+<NotificationPreferences
+  preferences={prefs}
+  projects={projectList}
+  onSave={handleSavePref}
+  onToggleMute={handleToggleMute}
+  onUpdateTier={handleUpdateTier}
+  onDelete={handleDeletePref}
+/>
+```
+
+## Gotchas
+- Manages per-project notification preferences (channel, tier, mute)
+- All callback props support async (Promise<void>) for server-side operations
+- Typically rendered on a settings/preferences page
+
+## Changes
+### v0.1.0
+- **Added** Initial release

package/docs/components/shell/sidebar.md

@@ -1,92 +1,92 @@
-# AppSidebar
-
-- Import: @devalok/shilp-sutra/shell/sidebar
-- Server-safe: No
-- Category: shell
-
-## Props
-    currentPath?: string (highlights active nav item)
-    user?: SidebarUser | null — { name, email?, image?, designation?, role? }
-    navGroups?: NavGroup[] — { label: string, items: NavItem[], action?: ReactNode }
-    logo?: ReactNode
-    footerLinks?: Array<{ label: string, href: string }> (DEPRECATED — use footer.links)
-    footer?: SidebarFooterConfig — structured footer (takes precedence over footerLinks)
-    headerSlot?: ReactNode — content between user info and navigation
-    preFooterSlot?: ReactNode — content between navigation and footer
-    preFooterClassName?: string — className on preFooterSlot wrapper div
-    renderItem?: (item: NavItem, defaultRender: () => ReactNode) => ReactNode | null — custom item rendering
-    className?: string
-
-NavItem: { title: string, href: string, icon: ReactNode, exact?: boolean, badge?: string | number, children?: NavSubItem[], defaultOpen?: boolean }
-NavSubItem: { title: string, href: string, icon?: ReactNode, exact?: boolean }
-NavGroup: { label: string, items: NavItem[], action?: ReactNode }
-SidebarUser: { name: string, email?: string, image?: string | null, designation?: string, role?: string }
-SidebarFooterConfig: { links?: Array<{ label: string, href: string }>, version?: string | { label: string, href: string }, slot?: ReactNode, promo?: SidebarPromo }
-SidebarPromo: { text: string, icon?: ReactNode, action?: { label: string, href?: string, onClick?: () => void }, onDismiss?: () => void }
-
-## Defaults
-    None
-
-## Example
-```jsx
-<AppSidebar
-  currentPath="/dashboard"
-  user={{ name: 'Jane', email: 'jane@example.com' }}
-  navGroups={[{
-    label: 'Main',
-    items: [
-      { title: 'Dashboard', href: '/dashboard', icon: <IconHome /> },
-      { title: 'Projects', href: '/projects', icon: <IconFolder />, children: [
-        { title: 'Karm V2', href: '/projects/abc/board' },
-      ]},
-    ],
-  }]}
-  footer={{
-    links: [{ label: 'Terms', href: '/terms' }],
-    version: { label: 'v2.4.1', href: '/changelog' },
-  }}
-/>
-```
-
-## Gotchas
-- Must be wrapped in SidebarProvider (from ui/sidebar)
-- Requires LinkProvider for framework-specific link components
-- `footerLinks` is deprecated — use `footer.links` instead
-- `renderItem` returning `null` falls back to default rendering
-- Collapsible nav items auto-open when a child is active (matching `currentPath`)
-- Badge numbers > 99 display as "99+"
-
-## Changes
-### v0.19.0
-- **Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background
-- **Changed** Interactive hover states bumped from `surface-2` to `surface-3`
-
-### v0.18.0
-- **Fixed** `bg-interactive-subtle` changed to `bg-accent-2` (OKLCH migration)
-
-### v0.16.0
-- **Added** `preFooterClassName?: string` — custom className on preFooterSlot wrapper
-
-### v0.14.0
-- **Changed** `footer.version` now accepts `string | { label: string; href: string }` — version can link to changelog
-
-### v0.13.0
-- **Added** `SidebarPromo` type and `footer.promo` prop — dismissable promo/upsell banner
-- **Changed** Footer links and version now render on a single line separated by dividers
-- **Fixed** Collapsible chevron wrapped in fixed-height container to prevent drift
-- **Fixed** Collapsible chevron no longer drifts into child elements when sub-list expands
-
-### v0.10.0
-- **Added** Collapsible nav items with `children` array and `NavSubItem` type
-- **Added** Nav item `badge` prop for counts/labels, caps at 99+
-- **Added** Nav group `action` prop for buttons next to group labels
-- **Added** Structured `footer` prop with `SidebarFooterConfig` — links, version, slot
-- **Added** `headerSlot` and `preFooterSlot` content slots
-- **Added** `renderItem` escape hatch for custom item rendering
-- **Deprecated** `footerLinks` prop — use `footer.links` instead
-
-### v0.1.1
-- **Changed** Decoupled from Next.js via LinkProvider
-
-### v0.1.0
-- **Added** Initial release
+# AppSidebar
+
+- Import: @devalok/shilp-sutra/shell/sidebar
+- Server-safe: No
+- Category: shell
+
+## Props
+    currentPath?: string (highlights active nav item)
+    user?: SidebarUser | null — { name, email?, image?, designation?, role? }
+    navGroups?: NavGroup[] — { label: string, items: NavItem[], action?: ReactNode }
+    logo?: ReactNode
+    footerLinks?: Array<{ label: string, href: string }> (DEPRECATED — use footer.links)
+    footer?: SidebarFooterConfig — structured footer (takes precedence over footerLinks)
+    headerSlot?: ReactNode — content between user info and navigation
+    preFooterSlot?: ReactNode — content between navigation and footer
+    preFooterClassName?: string — className on preFooterSlot wrapper div
+    renderItem?: (item: NavItem, defaultRender: () => ReactNode) => ReactNode | null — custom item rendering
+    className?: string
+
+NavItem: { title: string, href: string, icon: ReactNode, exact?: boolean, badge?: string | number, children?: NavSubItem[], defaultOpen?: boolean }
+NavSubItem: { title: string, href: string, icon?: ReactNode, exact?: boolean }
+NavGroup: { label: string, items: NavItem[], action?: ReactNode }
+SidebarUser: { name: string, email?: string, image?: string | null, designation?: string, role?: string }
+SidebarFooterConfig: { links?: Array<{ label: string, href: string }>, version?: string | { label: string, href: string }, slot?: ReactNode, promo?: SidebarPromo }
+SidebarPromo: { text: string, icon?: ReactNode, action?: { label: string, href?: string, onClick?: () => void }, onDismiss?: () => void }
+
+## Defaults
+    None
+
+## Example
+```jsx
+<AppSidebar
+  currentPath="/dashboard"
+  user={{ name: 'Jane', email: 'jane@example.com' }}
+  navGroups={[{
+    label: 'Main',
+    items: [
+      { title: 'Dashboard', href: '/dashboard', icon: <IconHome /> },
+      { title: 'Projects', href: '/projects', icon: <IconFolder />, children: [
+        { title: 'Karm V2', href: '/projects/abc/board' },
+      ]},
+    ],
+  }]}
+  footer={{
+    links: [{ label: 'Terms', href: '/terms' }],
+    version: { label: 'v2.4.1', href: '/changelog' },
+  }}
+/>
+```
+
+## Gotchas
+- Must be wrapped in SidebarProvider (from ui/sidebar)
+- Requires LinkProvider for framework-specific link components
+- `footerLinks` is deprecated — use `footer.links` instead
+- `renderItem` returning `null` falls back to default rendering
+- Collapsible nav items auto-open when a child is active (matching `currentPath`)
+- Badge numbers > 99 display as "99+"
+
+## Changes
+### v0.19.0
+- **Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background
+- **Changed** Interactive hover states bumped from `surface-2` to `surface-3`
+
+### v0.18.0
+- **Fixed** `bg-interactive-subtle` changed to `bg-accent-2` (OKLCH migration)
+
+### v0.16.0
+- **Added** `preFooterClassName?: string` — custom className on preFooterSlot wrapper
+
+### v0.14.0
+- **Changed** `footer.version` now accepts `string | { label: string; href: string }` — version can link to changelog
+
+### v0.13.0
+- **Added** `SidebarPromo` type and `footer.promo` prop — dismissable promo/upsell banner
+- **Changed** Footer links and version now render on a single line separated by dividers
+- **Fixed** Collapsible chevron wrapped in fixed-height container to prevent drift
+- **Fixed** Collapsible chevron no longer drifts into child elements when sub-list expands
+
+### v0.10.0
+- **Added** Collapsible nav items with `children` array and `NavSubItem` type
+- **Added** Nav item `badge` prop for counts/labels, caps at 99+
+- **Added** Nav group `action` prop for buttons next to group labels
+- **Added** Structured `footer` prop with `SidebarFooterConfig` — links, version, slot
+- **Added** `headerSlot` and `preFooterSlot` content slots
+- **Added** `renderItem` escape hatch for custom item rendering
+- **Deprecated** `footerLinks` prop — use `footer.links` instead
+
+### v0.1.1
+- **Changed** Decoupled from Next.js via LinkProvider
+
+### v0.1.0
+- **Added** Initial release