@devalok/shilp-sutra 0.52.0 → 0.54.0

package/mcp-manifest.json

@@ -2,7 +2,7 @@
   "$schema": "./mcp-manifest.schema.json",
   "manifestVersion": "1.2.0",
   "package": "@devalok/shilp-sutra",
-  "packageVersion": "0.52.0",
+  "packageVersion": "0.54.0",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -386,7 +386,16 @@
             "name": "union",
             "raw": "AutocompleteOption | null"
           },
-          "required": false
+          "required": false,
+          "description": "controlled"
+        },
+        "defaultValue": {
+          "type": {
+            "name": "union",
+            "raw": "AutocompleteOption | null"
+          },
+          "required": false,
+          "description": "uncontrolled initial"
         },
         "onValueChange": {
           "type": {
@@ -414,6 +423,46 @@
           },
           "required": false
         },
+        "size": {
+          "type": {
+            "name": "object",
+            "raw": "(forwarded to Input)"
+          },
+          "required": false
+        },
+        "state": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "default",
+              "error",
+              "warning",
+              "success"
+            ]
+          },
+          "required": false,
+          "description": "forwarded to Input"
+        },
+        "isLoading": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false
+        },
+        "loadingText": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "defaultValue": "Loading…"
+        },
+        "renderOption": {
+          "type": {
+            "name": "function",
+            "raw": "(option, query) => ReactNode"
+          },
+          "required": false
+        },
         "className": {
           "type": {
             "name": "string"
@@ -429,25 +478,34 @@
       },
       "composition": {
         "notes": [
-          "**Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list. Pick by whether \"off-list\" values are valid (e.g. city field that accepts typos → Autocomplete; tag picker from a fixed vocabulary → Combobox).",
-          "**Value shape is an object** (`{ value, label }`), not a plain string — this preserves label/value decoupling for display-vs-storage.",
-          "**FormField:** Does NOT auto-consume FormField state. Set explicit error styling via className if needed.",
+          "**Composes `Input`** — the field is the DS `Input`, so it inherits `size`, error/`state` painting, read-only, hover, and FormField wiring. Autocomplete owns only the dropdown + behavior.",
+          "**Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list.",
+          "**Value shape is an object** (`{ value, label }`), not a plain string. Controlled via `value`, or uncontrolled via `defaultValue`.",
+          "**FormField:** auto-consumes FormField state (via the composed Input) — inside a FormField, error border + `aria-invalid`/`aria-describedby`/`required` are wired automatically. Pass `state` to override.",
+          "**Async / \"type to search\":** set `isLoading` to show a spinner (in the field + the listbox) with `loadingText`.",
+          "**Matched-text highlight:** the query substring is bolded in each option by default; override the whole row with `renderOption`.",
           "**Portal rendering:** Dropdown portals to body with z-popover (1400) — stacks above Dialog/Sheet.",
-          "**Keyboard:** ArrowDown/Up navigate suggestions, Enter selects, Esc closes. Typeahead is the input's native filtering."
+          "**Keyboard:** ArrowDown/Up/Home/End navigate, Enter selects, Esc closes."
         ]
       },
       "docPath": "docs/components/ui/autocomplete.md",
       "defaults": {
-        "emptyText": "No options"
+        "emptyText": "No options",
+        "loadingText": "Loading…"
       },
       "examples": [
         "<Autocomplete\n  options={[{ value: 'mumbai', label: 'Mumbai' }]}\n  value={selectedCity}\n  onValueChange={setSelectedCity}\n  placeholder=\"Search cities...\"\n/>"
       ],
       "gotchas": [
         "Allows free-text input (no forced selection) — use Combobox for forced selection",
-        "value is an object { value, label }, NOT just a string"
+        "value is an object { value, label }, NOT just a string",
+        "Client-side filtering only (known list). For huge/remote lists, drive `options` yourself with `isLoading` — no built-in virtualization."
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Re-parented onto the DS `Input` primitive — inherits `size`, error/`state` painting, read-only, hover, and FormField auto-consumption (previously re-rolled its own `<input>` and read FormField error but never painted it)."
+        },
         {
           "version": "0.18.0",
           "summary": "**Fixed** Added `useEffect` to sync query when external value changes"
@@ -5159,6 +5217,7 @@
           "type": {
             "name": "enum",
             "value": [
+              "xs",
               "sm",
               "md",
               "lg"
@@ -5200,7 +5259,7 @@
           "**`onClear` makes the X button appear** only when `value` is non-empty. Pair them so users can reset.",
           "**`loading={true}` swaps the clear button for a spinner** with `aria-busy=\"true\"` on the input — useful for debounced/async search.",
           "Doesn't auto-consume FormField (no `state` prop) — wrap a regular Input inside FormField for validated search fields.",
-          "Keyboard: Escape auto-triggers `onClear` when wired (handled via `type=\"search\"`'s native behavior on most browsers)."
+          "Keyboard: Escape is NOT wired to clear (the input is not `type=\"search\"`). Reset via the X button, or handle Escape yourself and call your `value` setter."
         ]
       },
       "docPath": "docs/components/ui/search-input.md",
@@ -5637,139 +5696,168 @@
       ]
     },
     "sidebar": {
-      "displayName": "AppSidebar",
-      "tier": "shell",
-      "import": "@devalok/shilp-sutra/shell/sidebar",
+      "displayName": "Sidebar",
+      "tier": "ui",
+      "import": "@devalok/shilp-sutra/ui/sidebar",
       "serverSafe": false,
       "description": "",
-      "props": {
-        "currentPath": {
-          "type": {
-            "name": "string"
+      "props": {},
+      "composition": {
+        "notes": [
+          "`Sidebar` — applies collapsed / expanded / off-canvas styles based on `state`",
+          "`SidebarTrigger` — calls `toggleSidebar()` on click; reflects aria-expanded",
+          "`SidebarMenuButton` — uses `state === 'collapsed'` to show its `tooltip` (hidden label appears only when sidebar is icon-width)",
+          "`SidebarInset` — main content area adjusts its left offset based on sidebar width + state",
+          "`SidebarRail` — invisible hit target on the outer edge for click-to-toggle",
+          "Any user component that calls `useSidebar()` — full access to open/isMobile/toggle **Desktop vs mobile:** Context tracks `isMobile` via the `use-mobile` hook and branches behavior: on desktop the sidebar collapses to an icon rail; on mobile it becomes an off-canvas drawer controlled by `openMobile`. **Controlled or uncontrolled:** `SidebarProvider` accepts `open` + `onOpenChange` (controlled) or `defaultOpen` (uncontrolled). State is synced to a cookie for cross-route persistence. **Next.js / router integration:** `SidebarMenuButton` with `asChild` wraps any link element (`next/link`, `react-router Link`, plain `<a>`) — it transfers its styling + isActive state to the child while preserving the link's navigation semantics."
+        ],
+        "parts": [
+          {
+            "name": "SidebarProvider",
+            "description": "context provider — must wrap everything"
           },
-          "required": false,
-          "description": "highlights active nav item"
-        },
-        "user": {
-          "type": {
-            "name": "union",
-            "raw": "SidebarUser | null — { name, email?, image?, designation?, role? }"
+          {
+            "name": "Sidebar",
+            "description": "root panel"
           },
-          "required": false
-        },
-        "navGroups": {
-          "type": {
-            "name": "object",
-            "raw": "NavGroup[] — { label: string, items: NavItem[], action?: ReactNode }"
+          {
+            "name": "SidebarHeader"
           },
-          "required": false
-        },
-        "logo": {
-          "type": {
-            "name": "ReactNode"
+          {
+            "name": "SidebarContent"
           },
-          "required": false
-        },
-        "footerLinks": {
-          "type": {
-            "name": "object",
-            "raw": "Array<{ label: string, href: string }>"
+          {
+            "name": "SidebarGroup"
           },
-          "required": false,
-          "description": "DEPRECATED — use footer.links"
-        },
-        "footer": {
-          "type": {
-            "name": "object",
-            "raw": "SidebarFooterConfig — structured footer"
+          {
+            "name": "SidebarGroupLabel"
           },
-          "required": false,
-          "description": "takes precedence over footerLinks"
-        },
-        "headerSlot": {
-          "type": {
-            "name": "ReactNode"
+          {
+            "name": "SidebarGroupAction"
           },
-          "required": false
-        },
-        "preFooterSlot": {
-          "type": {
-            "name": "ReactNode"
+          {
+            "name": "SidebarGroupContent"
           },
-          "required": false
-        },
-        "preFooterClassName": {
-          "type": {
-            "name": "object",
-            "raw": "string — className on preFooterSlot wrapper div"
+          {
+            "name": "SidebarMenu"
           },
-          "required": false
-        },
-        "renderItem": {
-          "type": {
-            "name": "function",
-            "raw": "(item: NavItem, defaultRender: () => ReactNode) => ReactNode | null — custom item rendering"
+          {
+            "name": "SidebarMenuItem"
           },
-          "required": false
-        },
-        "className": {
-          "type": {
-            "name": "string"
+          {
+            "name": "SidebarMenuButton",
+            "description": "tooltip, isActive"
           },
-          "required": false
-        }
-      },
-      "composition": {
-        "notes": [
-          "**Opinionated app sidebar** — data-driven via `navGroups`, with user profile header, navigation groups (with optional labels + group actions), and a configurable footer (links + version + optional promo banner).",
-          "**Required setup (three providers):** - `SidebarProvider` (from ui/sidebar) — owns expanded/collapsed state + cookie persistence - `LinkProvider` — framework router integration for nav item links - `CommandRegistryProvider` (if pairing with AppCommandPalette) — registers the same navGroups so keyboard search finds them",
-          "**renderItem escape hatch:** Custom per-item rendering (e.g. custom icons per item type, status decorations, hover previews). Return `null` to fall back to default.",
-          "**Nested navigation:** NavItem's `children: NavSubItem[]` renders a collapsible subsection. Auto-opens if a child matches the current path.",
-          "**Footer as slot:** `footer` can include links, version info, a ReactNode slot (e.g. theme toggle), and a dismissable promo banner — structure it once, compose.",
-          "**Pairs with TopBar + BottomNavbar:** Desktop layout = AppSidebar + TopBar. Mobile layout = hide AppSidebar, show BottomNavbar."
+          {
+            "name": "SidebarMenuAction"
+          },
+          {
+            "name": "SidebarMenuBadge"
+          },
+          {
+            "name": "SidebarMenuSub"
+          },
+          {
+            "name": "SidebarMenuSubItem"
+          },
+          {
+            "name": "SidebarMenuSubButton",
+            "description": "isActive"
+          },
+          {
+            "name": "SidebarFooter"
+          },
+          {
+            "name": "SidebarSeparator"
+          },
+          {
+            "name": "SidebarRail"
+          },
+          {
+            "name": "SidebarInset",
+            "description": "main content area"
+          },
+          {
+            "name": "SidebarTrigger",
+            "description": "hamburger button"
+          },
+          {
+            "name": "SidebarInput",
+            "description": "search input in sidebar"
+          },
+          {
+            "name": "SidebarMenuSkeleton",
+            "description": "loading placeholder"
+          }
         ]
       },
-      "docPath": "docs/components/shell/sidebar.md",
+      "docPath": "docs/components/ui/sidebar.md",
+      "defaults": {
+        "variant": "default",
+        "size": "md"
+      },
+      "subComponents": {
+        "SidebarMenuButton": {
+          "props": {
+            "variant": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "default",
+                  "outline"
+                ]
+              },
+              "required": false
+            },
+            "size": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "sm",
+                  "md",
+                  "lg"
+                ]
+              },
+              "required": false
+            },
+            "isActive": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "highlights as current nav item"
+            },
+            "tooltip": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false,
+              "description": "shown when sidebar is collapsed"
+            },
+            "asChild": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "render as Slot — common with next/link"
+            }
+          }
+        }
+      },
       "examples": [
-        "<AppSidebar\n  currentPath=\"/dashboard\"\n  user={{ name: 'Jane', email: 'jane@example.com' }}\n  navGroups={[{\n    label: 'Main',\n    items: [\n      { title: 'Dashboard', href: '/dashboard', icon: <IconHome /> },\n      { title: 'Projects', href: '/projects', icon: <IconFolder />, children: [\n        { title: 'Karm V2', href: '/projects/abc/board' },\n      ]},\n    ],\n  }]}\n  footer={{\n    links: [{ label: 'Terms', href: '/terms' }],\n    version: { label: 'v2.4.1', href: '/changelog' },\n  }}\n/>"
+        "<SidebarProvider>\n  <Sidebar>\n    <SidebarHeader>Logo</SidebarHeader>\n    <SidebarContent>\n      <SidebarGroup>\n        <SidebarGroupLabel>Navigation</SidebarGroupLabel>\n        <SidebarGroupContent>\n          <SidebarMenu>\n            <SidebarMenuItem>\n              <SidebarMenuButton isActive>\n                <IconHome /> Dashboard\n              </SidebarMenuButton>\n            </SidebarMenuItem>\n          </SidebarMenu>\n        </SidebarGroupContent>\n      </SidebarGroup>\n    </SidebarContent>\n  </Sidebar>\n  <SidebarInset>\n    <SidebarTrigger />\n    <main>Page content</main>\n  </SidebarInset>\n</SidebarProvider>"
       ],
       "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+\""
+        "SidebarProvider MUST wrap both Sidebar and SidebarInset",
+        "Use SidebarMenuButton for nav items (supports tooltip in collapsed state)",
+        "`tooltip` is only visible when sidebar is collapsed — providing one doesn't duplicate the visible label",
+        "Cookie-based state persistence means the sidebar defaults to its prior state on page reload — use `defaultOpen` to override if needed"
       ],
       "changes": [
-        {
-          "version": "0.19.0",
-          "summary": "**Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background"
-        },
         {
           "version": "0.18.0",
           "summary": "**Fixed** `bg-interactive-subtle` changed to `bg-accent-2` (OKLCH migration)"
         },
-        {
-          "version": "0.16.0",
-          "summary": "**Added** `preFooterClassName?: string` — custom className on preFooterSlot wrapper"
-        },
-        {
-          "version": "0.14.0",
-          "summary": "**Changed** `footer.version` now accepts `string | { label: string; href: string }` — version can link to changelog"
-        },
-        {
-          "version": "0.13.0",
-          "summary": "**Added** `SidebarPromo` type and `footer.promo` prop — dismissable promo/upsell banner"
-        },
-        {
-          "version": "0.10.0",
-          "summary": "**Added** Collapsible nav items with `children` array and `NavSubItem` type"
-        },
-        {
-          "version": "0.1.1",
-          "summary": "**Changed** Decoupled from Next.js via LinkProvider"
-        },
         {
           "version": "0.1.0",
           "summary": "**Added** Initial release"
@@ -6091,7 +6179,7 @@
           "Radix Slider primitive — keyboard navigation (arrow keys, Home/End, PageUp/PageDown) pre-wired.",
           "**Value is always an array** — single-thumb: `[50]`; range: `[25, 75]`. Don't pass a plain number.",
           "**Multi-thumb range:** Pass `[start, end]` — renders two thumbs that can cross each other by default. Use `minStepsBetweenThumbs` to enforce a gap.",
-          "**FormField:** Slider does NOT auto-consume FormField state. No validation UX — sliders usually don't need it (values are always valid by construction).",
+          "**FormField:** Slider consumes FormField for a11y wiring (`aria-invalid` / `aria-describedby` / `aria-required`) but renders no visual validation treatment — values are valid by construction, so there's no error UX to hand-wire.",
           "**No label pairing via Label** — use `aria-label` or `aria-labelledby` directly on the Slider. The thumb is the focusable/labeled element.",
           "Not portal-rendered — inline; overflow rules of parents apply."
         ]
@@ -6107,7 +6195,7 @@
       "gotchas": [
         "value is number[] (array), not a single number",
         "Multi-thumb: Pass array `defaultValue={[25, 75]}` for range sliders — renders one thumb per value",
-        "Slider does NOT auto-consume FormField — sliders don't have validation state visuals by design"
+        "Slider consumes FormField for a11y wiring (aria-invalid/describedby/required) but shows no validation visuals by design — don't hand-wire what it already does"
       ],
       "changes": [
         {
@@ -6237,9 +6325,9 @@
       "composition": {
         "notes": [
           "**Two-in-one button:** visually unified `[Action | ▼]` with the left half being the primary click and the right half opening a dropdown. Use for actions that have a most-common choice plus alternatives (Save vs. Save-As-Draft, Send vs. Schedule).",
-          "**Built on Button + Popover internally** — inherits Button's variant/color/size vocabulary and Popover's placement prop (`top-end` default works for most top-of-page toolbars).",
+          "**Composes the DS Popover internally** and shares the `color` type + a `variant`/`size` subset with Button (currently `solid`/`soft`/`outline` × the Button colors; no `ghost`/`link`/`lg`). Note: the half styling is implemented locally, not inherited from `Button` — a few Button niceties (e.g. `solid`'s `hover:shadow-brand`) don't apply. Popover placement via `top-end` default suits most top-of-page toolbars.",
           "**Dropdown content is consumer-provided** — pass any JSX via `dropdownContent` (typically a DropdownMenu, list of actions, a custom panel, or a small form). Don't try to shove a full-featured menu into the chevron; keep it focused on 2–5 alternatives.",
-          "**ButtonGroup compatibility:** Put SplitButton inside a `<ButtonGroup>` — it inherits variant/color/size from the group context just like Button does. Position-aware corners work too.",
+          "**ButtonGroup:** SplitButton does NOT consume `ButtonGroup` context — set its `variant`/`color`/`size` explicitly to match a surrounding group.",
           "**Controlled dropdown:** Pass `open` + `onOpenChange` for controlled state; omit for uncontrolled. Useful when the dropdown must close programmatically after a selection."
         ]
       },
@@ -6251,7 +6339,7 @@
       "changes": [
         {
           "version": "0.44.2",
-          "summary": "**Fixed** The dropdown is now keyboard-accessible. It previously used a hand-rolled floating panel (`role=\"menu\"`) with no focus management, arrow keys, or Escape — keyboard users couldn't reach or dismiss it. It now composes the DS **Popover** primitive: focus moves in on open, Escape and outside-click close, focus returns to the trigger, and on mobile it opens as a bottom sheet. (Full menu semantics with arrow-key item navigation via DropdownMenu are planned for 0.45.0.)"
+          "summary": "**Fixed** The dropdown is now keyboard-accessible. It previously used a hand-rolled floating panel (`role=\"menu\"`) with no focus management, arrow keys, or Escape — keyboard users couldn't reach or dismiss it. It now composes the DS **Popover** primitive: focus moves in on open, Escape and outside-click close, focus returns to the trigger, and on mobile it opens as a bottom sheet."
         },
         {
           "version": "0.33.0",
@@ -8486,6 +8574,20 @@
           },
           "required": false
         },
+        "totalCount": {
+          "type": {
+            "name": "number"
+          },
+          "required": false,
+          "description": "optional — total selectable items; enables \"Select all\""
+        },
+        "onSelectAll": {
+          "type": {
+            "name": "function",
+            "raw": "() => void (optional — called by the \"Select all\" control)"
+          },
+          "required": false
+        },
         "className": {
           "type": {
             "name": "string"
@@ -8514,10 +8616,10 @@
             "icon": {
               "type": {
                 "name": "object",
-                "raw": "ComponentType<{ className?: string }>"
+                "raw": "IconInput"
               },
               "required": false,
-              "description": "optional icon component"
+              "description": "optional — any icon component or element"
             },
             "onClick": {
               "type": {
@@ -8530,17 +8632,44 @@
               "type": {
                 "name": "enum",
                 "value": [
-                  "default",
-                  "error"
+                  "accent",
+                  "error",
+                  "success",
+                  "warning",
+                  "info",
+                  "neutral"
                 ]
               },
-              "required": false
+              "required": false,
+              "defaultValue": "accent"
             },
             "disabled": {
               "type": {
                 "name": "boolean"
               },
-              "required": false
+              "required": false,
+              "description": "optional"
+            },
+            "loading": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "optional — pending spinner on the action"
+            },
+            "requiresConfirmation": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "optional — inline confirm before executing"
+            },
+            "confirmMessage": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "description": "optional — default \"Are you sure?\""
             }
           }
         }
@@ -9809,9 +9938,30 @@
         "onReset": {
           "type": {
             "name": "function",
-            "raw": "() => void (optional retry button)"
+            "raw": "() => void (optional — renders a \"Try Again\" button)"
           },
           "required": false
+        },
+        "actions": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "optional — custom recovery actions; replaces the default button"
+        },
+        "fullPage": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false,
+          "defaultValue": "true — center in a min-h-[60vh] region; false = inline"
+        },
+        "autoFocusReset": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false,
+          "defaultValue": "false — focus the recovery button on mount"
         }
       },
       "composition": {
@@ -9824,6 +9974,48 @@
         ]
       },
       "docPath": "docs/components/composed/error-boundary.md",
+      "subComponents": {
+        "ErrorBoundary": {
+          "props": {
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": true
+            },
+            "onReset": {
+              "type": {
+                "name": "function",
+                "raw": "() => void (optional — called after the boundary resets)"
+              },
+              "required": false
+            },
+            "onError": {
+              "type": {
+                "name": "function",
+                "raw": "(error: unknown, info: React.ErrorInfo) => void (optional — wire Sentry/logging)"
+              },
+              "required": false
+            },
+            "resetKeys": {
+              "type": {
+                "name": "object",
+                "raw": "unknown[]"
+              },
+              "required": false,
+              "description": "optional — auto-reset when any value changes; react-error-boundary parity"
+            },
+            "fallback": {
+              "type": {
+                "name": "function",
+                "raw": "(props: { error: unknown; onReset: () => void }) => ReactNode (optional — defaults to ErrorDisplay)"
+              },
+              "required": false
+            }
+          },
+          "note": "class boundary — wrap a subtree"
+        }
+      },
       "examples": [
         "<ErrorDisplay error={error} onReset={() => refetch()} />"
       ],
@@ -10496,9 +10688,31 @@
             "raw": "string | null"
           },
           "required": false,
-          "description": "ID of currently selected item; null = show list on mobile",
+          "description": "CONTROLLED selected item id; omit for uncontrolled",
           "defaultValue": "{null}"
         },
+        "defaultSelected": {
+          "type": {
+            "name": "union",
+            "raw": "string | null"
+          },
+          "required": false,
+          "description": "uncontrolled initial selection"
+        },
+        "onSelect": {
+          "type": {
+            "name": "function",
+            "raw": "(value: string) => void (called with a row's `value` when chosen)"
+          },
+          "required": false
+        },
+        "label": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "description": "accessible name for the listbox; default \"Items\""
+        },
         "onBack": {
           "type": {
             "name": "function",
@@ -10526,6 +10740,20 @@
           "required": false,
           "description": "below this, stacked mobile mode activates",
           "defaultValue": "md"
+        },
+        "emptyState": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "shown in the detail pane when nothing is selected"
+        },
+        "onNavigate": {
+          "type": {
+            "name": "function",
+            "raw": "(direction: \"up\" | \"down\") => void"
+          },
+          "required": false
         }
       },
       "composition": {
@@ -10546,12 +10774,19 @@
       "subComponents": {
         "MasterDetail.ListItem": {
           "props": {
+            "value": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "description": "row id — enables derived selection + auto-fires onSelect on activate"
+            },
             "active": {
               "type": {
                 "name": "boolean"
               },
               "required": false,
-              "description": "highlights the item"
+              "description": "explicit highlight; omit to derive from value === selected"
             }
           }
         }
@@ -10939,9 +11174,9 @@
         "notes": [
           "**Full-page skeleton layouts** for route-level loading states. Each mimics a common page shape (dashboard tiles, project list with filters, task detail with sidebar).",
           "**Server-safe** — use in Next.js app router `loading.tsx` files for instant route-transition feedback while data streams.",
-          "**Built on LoadingSkeleton + ui/Skeleton** — these just assemble the pre-built regional skeletons into page-shaped layouts.",
+          "**Assembled from `ui/Skeleton`** — these compose the base `Skeleton` primitive directly into page-shaped layouts (they do NOT wrap the `LoadingSkeleton` regional exports). Each root is a `role=\"status\"` / `aria-busy` region with an sr-only label.",
           "**When to use which skeleton tier:** - `<Skeleton>` (ui) — single shape for a single element - `<CardSkeleton>` / `<TableSkeleton>` (LoadingSkeleton) — individual region shape - `<DashboardSkeleton>` / etc. (PageSkeletons) — full page placeholder",
-          "**Fixed layout structure** — the className prop adjusts the outer container, but internal layout isn't customizable. For custom page skeletons, compose LoadingSkeleton pieces yourself."
+          "**Fixed layout structure** — the className prop adjusts the outer container, but internal layout isn't customizable. For custom page skeletons, compose `ui/Skeleton` (or the `LoadingSkeleton` regional exports) yourself."
         ]
       },
       "docPath": "docs/components/composed/page-skeletons.md",
@@ -10968,7 +11203,7 @@
       "displayName": "PriorityIndicator",
       "tier": "composed",
       "import": "@devalok/shilp-sutra/composed/priority-indicator",
-      "serverSafe": true,
+      "serverSafe": false,
       "description": "",
       "props": {
         "priority": {
@@ -10978,6 +11213,13 @@
           },
           "required": false
         },
+        "iconOnly": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false,
+          "description": "icon-only chip, no visible text"
+        },
         "display": {
           "type": {
             "name": "enum",
@@ -10987,31 +11229,41 @@
             ]
           },
           "required": false,
-          "defaultValue": "full"
+          "description": "@deprecated — use iconOnly"
+        },
+        "children": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "override the label, e.g. i18n"
         }
       },
       "composition": {
         "notes": [
-          "**Server-safe priority label** — icon + color + text for task / issue priority.",
+          "**Composes `Badge`** — radius, color semantics, a11y labelling, and reduced-motion handling all come from one place (no bespoke re-roll).",
           "**Composes inside list rows, DataTable cells, Card headers, task panels** — anywhere a priority flag fits.",
-          "**display=\"compact\"** shows only the icon (with priority text as title attribute for tooltip). Use in tight cells; use `display=\"full\"` (default) in free space.",
-          "**Case-insensitive priority** — accepts both UPPERCASE (LOW/MEDIUM/HIGH/URGENT) and lowercase. Designed to match both backend conventions without manual coercion.",
-          "Color semantics: LOW=success, MEDIUM=warning, HIGH=error, URGENT=error with bolder icon."
+          "**`iconOnly`** shows only the icon with a real accessible name (`role=\"img\"` + `aria-label`), for tight cells. Omit it (default) for icon + label.",
+          "**Severity by weight, not motion** — URGENT renders as a solid fill so the top tier reads at a glance; the others are soft. No animation (removes the prior perpetual pulse).",
+          "**Case-insensitive priority** — accepts both UPPERCASE and lowercase; unknown values fall back to MEDIUM instead of throwing.",
+          "**`children`** overrides the label for i18n / custom copy.",
+          "Color semantics: LOW = slate (neutral), MEDIUM = warning, HIGH = error (soft), URGENT = error (solid)."
         ]
       },
       "docPath": "docs/components/composed/priority-indicator.md",
-      "defaults": {
-        "display": "full"
-      },
       "examples": [
-        "<PriorityIndicator priority=\"HIGH\" />\n<PriorityIndicator priority=\"low\" display=\"compact\" />"
+        "<PriorityIndicator priority=\"HIGH\" />\n<PriorityIndicator priority=\"low\" iconOnly />\n<PriorityIndicator priority=\"URGENT\">Critical</PriorityIndicator>"
       ],
       "gotchas": [
-        "Case-insensitive — \"low\" and \"LOW\" both work",
-        "Server-safe: can be imported directly in Next.js Server Components",
-        "`compact` display shows only the icon; `full` shows icon + text label"
+        "Case-insensitive — \"low\" and \"LOW\" both work; unknown values fall back to MEDIUM",
+        "`iconOnly` shows only the icon (accessible-named); default shows icon + text label",
+        "`display` is deprecated — use `iconOnly`"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Recomposed on the `Badge` primitive (was a bespoke re-rolled chip): inherits pill radius, color semantics, accessible labelling."
+        },
         {
           "version": "0.2.0",
           "summary": "**Added** Identified as server-safe component"
@@ -11193,7 +11445,7 @@
             "onSubmit": {
               "type": {
                 "name": "function",
-                "raw": "(html: string, plainText: string) => void (REQUIRED)"
+                "raw": "(message: RichChatInputMessage) => void (REQUIRED)"
               },
               "required": false
             },
@@ -11211,24 +11463,27 @@
               "required": false,
               "defaultValue": false
             },
+            "content": {
+              "type": {
+                "name": "object",
+                "raw": "string — initial HTML"
+              },
+              "required": false,
+              "description": "not reactive; use for message editing"
+            },
             "variant": {
               "type": {
                 "name": "enum",
                 "value": [
                   "compact",
                   "expanded",
-                  "minimal"
+                  "minimal",
+                  "inline"
                 ]
               },
               "required": false,
               "defaultValue": "compact"
             },
-            "maxRows": {
-              "type": {
-                "name": "number"
-              },
-              "required": false
-            },
             "enterBehavior": {
               "type": {
                 "name": "enum",
@@ -11247,6 +11502,19 @@
               },
               "required": false
             },
+            "charCountDisplay": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "always",
+                  "focus",
+                  "near-limit",
+                  "hidden"
+                ]
+              },
+              "required": false,
+              "defaultValue": "near-limit"
+            },
             "mentions": {
               "type": {
                 "name": "object",
@@ -11289,6 +11557,34 @@
               },
               "required": false
             },
+            "onVoiceRecord": {
+              "type": {
+                "name": "function",
+                "raw": "(audio: Blob, duration: number) => void"
+              },
+              "required": false
+            },
+            "onTranscribe": {
+              "type": {
+                "name": "function",
+                "raw": "(blob: Blob, duration: number) => Promise<string | null> — transcribe after recording; return null to attach as a voice note"
+              },
+              "required": false
+            },
+            "maxDuration": {
+              "type": {
+                "name": "object",
+                "raw": "number — max voice-recording seconds"
+              },
+              "required": false
+            },
+            "replyTo": {
+              "type": {
+                "name": "function",
+                "raw": "{ id: string; author: string; preview: string; onDismiss: () => void } — reply banner above the input"
+              },
+              "required": false
+            },
             "onTyping": {
               "type": {
                 "name": "function",
@@ -11339,16 +11635,50 @@
             "toolbar": {
               "type": {
                 "name": "union",
-                "raw": "boolean | ChatToolbarItem[]"
+                "raw": "boolean | ChatToolbarItem[] | ReactNode (default: true) — true = default toolbar, array = whitelist, ReactNode = custom, false = hidden"
+              },
+              "required": false
+            },
+            "actionButton": {
+              "type": {
+                "name": "ReactNode"
               },
               "required": false,
-              "defaultValue": true
+              "description": "replaces the default attach button; false hides it"
+            },
+            "emojiSet": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "native",
+                  "apple",
+                  "google",
+                  "twitter",
+                  "facebook"
+                ]
+              },
+              "required": false,
+              "defaultValue": "native"
+            },
+            "onSchedule": {
+              "type": {
+                "name": "function",
+                "raw": "(message: RichChatInputMessage, scheduledAt: Date) => void — if set, a schedule button appears next to send"
+              },
+              "required": false
+            },
+            "sendOptions": {
+              "type": {
+                "name": "function",
+                "raw": "Array<{ label: string; icon?: ComponentType<{ className?: string }>; onSelect: () => void }> — split-send dropdown options"
+              },
+              "required": false
             }
           }
         }
       },
       "examples": [
-        "<RichChatInput\n  onSubmit={(html, text) => sendMessage(html)}\n  mentions={teamMembers}\n  onFileUpload={uploadFile}\n  slashCommands={[{ label: 'Actions', commands: [...] }]}\n/>\n\n<RichChatInput\n  variant=\"expanded\"\n  onSubmit={handleSubmit}\n  maxLength={2000}\n  disclaimer=\"AI-generated content may be inaccurate.\"\n/>\n\n<RichChatInput\n  variant=\"minimal\"\n  enterBehavior=\"newline\"\n  onSubmit={handleReply}\n/>"
+        "<RichChatInput\n  onSubmit={(message) => sendMessage(message.html)}\n  mentions={teamMembers}\n  onFileUpload={uploadFile}\n  slashCommands={[{ label: 'Actions', commands: [...] }]}\n/>\n\n<RichChatInput\n  variant=\"expanded\"\n  onSubmit={handleSubmit}\n  maxLength={2000}\n  disclaimer=\"AI-generated content may be inaccurate.\"\n/>\n\n<RichChatInput\n  variant=\"minimal\"\n  enterBehavior=\"newline\"\n  onSubmit={handleReply}\n/>"
       ],
       "gotchas": [
         "Tiptap is bundled — no need to install `@tiptap/*` packages separately",
@@ -11596,13 +11926,55 @@
           "required": false,
           "description": "minutes, default: 30",
           "defaultValue": 30
+        },
+        "selectedEventId": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "description": "rings the active event"
+        },
+        "renderEvent": {
+          "type": {
+            "name": "function",
+            "raw": "(event) => ReactNode (custom event body)"
+          },
+          "required": false
+        },
+        "header": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "toolbar slot above the grid"
+        },
+        "emptyState": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "shown when events is empty"
+        },
+        "height": {
+          "type": {
+            "name": "union",
+            "raw": "number | string"
+          },
+          "required": false,
+          "description": "grid body height, default 480",
+          "defaultValue": 480
         }
       },
       "composition": {
         "notes": [
           "**Day / Week calendar view** for time-block display (meetings, shifts, availability). Not a full calendar app — no month view, no drag-to-create.",
           "**Event data is consumer-owned:** You pass `events` as an array; ScheduleView doesn't fetch, doesn't cache, doesn't expand recurring events. All scheduling logic lives in your app.",
-          "**Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot).",
+          "**Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot). **Slots are only interactive (focusable + keyboard-navigable) when `onSlotClick` is set** — otherwise they render as inert grid lines, so a read-only schedule adds no keyboard/AT tab stops.",
+          "**Keyboard (interactive slots):** roving tabindex — Arrow keys move between slots (up/down within a day, left/right across days, RTL-aware), Home/End jump within the day; only one slot is in the tab order at a time.",
+          "**Overlapping events** are partitioned into side-by-side columns automatically so double-booked times stay legible.",
+          "**Live now-line** ticks every minute and scrolls into view on mount.",
+          "**`renderEvent`** customizes the event block body; **`header`** adds a toolbar; **`selectedEventId`** rings the active event; **`emptyState`** shows when there are no events.",
+          "**Composes the DS card shell tokens** (`surface-2` + `rounded-surface` + border) and is RTL-safe (logical properties throughout).",
           "**Color vocabulary matches the DS** — `accent/success/warning/error/info/neutral`. Map your event types to these at the data layer.",
           "**endHour is exclusive:** `endHour=18` means the last visible slot starts at 17:30 (with 30min slots). Match your UX expectation: 9-5 typically means `startHour=9, endHour=18`.",
           "**Pairs with date-picker/composed** — use DatePicker or DateRangePicker to choose which date to show; pass that as ScheduleView's `date`."
@@ -11612,7 +11984,8 @@
       "defaults": {
         "startHour": 8,
         "endHour": 18,
-        "slotDuration": 30
+        "slotDuration": 30,
+        "height": 480
       },
       "examples": [
         "<ScheduleView\n  view=\"week\"\n  date={new Date()}\n  events={calendarEvents}\n  onEventClick={(e) => openEvent(e.id)}\n/>"
@@ -11623,6 +11996,10 @@
         "Events that span outside `startHour`/`endHour` may be clipped"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Read-only schedules no longer flood the tab order — slots are interactive only when `onSlotClick` is set; otherwise inert grid lines. Interactive slots use roving tabindex + Arrow/Home/End keyboard navigation (RTL-aware)."
+        },
         {
           "version": "0.49.0",
           "summary": "**BREAKING** `ScheduleEvent.color` value `\"primary\"` renamed `\"accent\"` (DS colour vocabulary). It was the default, so untyped events are unaffected."
@@ -11695,7 +12072,7 @@
         "notes": [
           "**One-liner Tooltip** — wraps TooltipProvider + Tooltip + TooltipTrigger + TooltipContent so consumers don't have to manually compose them for a simple label.",
           "**When to use:** 90% of tooltip use cases (icon-only button labels, abbreviated text expansions, secondary info). Use the ui/Tooltip compound for advanced cases (controlled open, nested triggers, custom animations).",
-          "**Auto-provides its own TooltipProvider** — safe to drop anywhere. You can still wrap a broader TooltipProvider at layout level for shared `delayDuration`; SimpleTooltip respects it if present.",
+          "**Always mounts its own TooltipProvider** — safe to drop anywhere. Note it does NOT inherit an ancestor `TooltipProvider`'s `delayDuration`; its own `delayDuration` prop (default 300ms) always wins. Set it per-tooltip via the prop.",
           "**Content must be inert** — same rule as ui/Tooltip. For interactive popped content, use Popover or HoverCard.",
           "**Pairs with IconButton** — the canonical pattern for labeled icon buttons."
         ]
@@ -11929,11 +12306,12 @@
       },
       "docPath": "docs/components/shell/app-command-palette.md",
       "examples": [
-        "<AppCommandPalette\n  user={{ name: 'John', role: 'admin' }}\n  isAdmin={true}\n  onNavigate={(path) => router.push(path)}\n  searchResults={results}\n  onSearchResultSelect={(r) => router.push(`/${r.entityType}/${r.id}`)}\n/>"
+        "<AppCommandPalette\n  user={{ name: 'John', role: 'Admin' }}\n  isAdmin={true}\n  onNavigate={(path) => router.push(path)}\n  searchResults={results}\n  onSearchResultSelect={(r) => router.push(`/${r.entityType}/${r.id}`)}\n/>"
       ],
       "gotchas": [
         "Uses CommandRegistry context for page navigation items (see CommandRegistryProvider)",
         "`isAdmin` takes precedence over `user.role` for showing admin command groups",
+        "**Role detection is case-sensitive:** `user.role` only auto-enables admin groups when it is exactly `'Admin'` or `'SuperAdmin'`. `'admin'` (lowercase) silently shows nothing — pass `isAdmin` explicitly if your role strings differ.",
         "Should be placed at the app root level, typically alongside TopBar"
       ],
       "changes": [
@@ -11967,7 +12345,7 @@
             "raw": "BottomNavbarUser | null"
           },
           "required": false,
-          "description": "optional"
+          "description": "drives per-item role gating, optional"
         },
         "primaryItems": {
           "type": {
@@ -11983,7 +12361,30 @@
             "raw": "BottomNavItem[]"
           },
           "required": false,
-          "description": "overflow items in \"More\" menu, optional"
+          "description": "overflow items in \"More\" sheet, optional"
+        },
+        "indicator": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "pill",
+              "underline",
+              "tint",
+              "none"
+            ]
+          },
+          "required": false,
+          "description": "active-item indicator; default 'pill'"
+        },
+        "labelVisibility": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "always",
+              "selected"
+            ]
+          },
+          "required": false
         },
         "className": {
           "type": {
@@ -11994,11 +12395,15 @@
       },
       "composition": {
         "notes": [
-          "**Mobile-only bottom nav** — fixed to bottom of viewport. Desktop should use AppSidebar instead.",
-          "**Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render AppSidebar (desktop) or BottomNavbar (mobile). Example: ```jsx const isMobile = useIsMobile() return isMobile ? <BottomNavbar ... /> : <AppSidebar ... /> ```",
+          "**Mobile-only bottom nav** — fixed to bottom of viewport. Desktop should use Sidebar instead.",
+          "**Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render Sidebar (desktop) or BottomNavbar (mobile). Example: ```jsx const isMobile = useIsMobile() return isMobile ? <BottomNavbar ... /> : <Sidebar ... /> ```",
           "**Primary vs overflow:** `primaryItems` (max 4) for the always-visible slots; `moreItems` go into a \"More\" sheet that opens on tap. Don't exceed 4 primary — the bar becomes cramped.",
           "**Router integration via LinkProvider:** Each nav item is rendered using the framework-specific Link component registered in LinkProvider. Without LinkProvider, you get full-page reloads on tap.",
-          "**Badge numbers** cap at 99+ (same as BadgeIndicator pattern).",
+          "**Badge numbers** cap at 99+ (composes the `Badge` primitive).",
+          "**Role gating:** each item may declare `roles: string[]` (shown only when `user.role` matches) or a `canView(user)` predicate for arbitrary logic (`canView` wins). Items with neither are always visible. Gating applies to both `primaryItems` and `moreItems`.",
+          "**Overflow sheet:** the \"More\" surface is the DS `Sheet` (`side=\"bottom\"`) — it inherits focus trap, scroll lock, return-focus, and `aria-modal`; the trigger is wired with `aria-haspopup`/`aria-controls` automatically.",
+          "**Indicator (animated):** the active indicator slides to the selected item (shared-element `layoutId`) and fades in on first appearance. Modes: `pill` (default, Material-3 tonal pill behind the icon), `underline` (top accent bar), `tint` (subtle bg on the whole active cell), `none` (no shape — pair with `activeIcon` for the iOS filled-icon look). `labelVisibility=\"selected\"` shows labels only for the active item.",
+          "**Filled-when-active:** set `activeIcon` on an item (e.g. a Tabler `*Filled` variant) to swap the icon for a filled version while it's the active route; falls back to `icon`.",
           "**Not for desktop:** The viewport-fixed positioning + touch-optimized sizing don't translate well to desktop. Hide behind `md:hidden`."
         ]
       },
@@ -12009,10 +12414,14 @@
       "gotchas": [
         "Designed for mobile viewports — fixed to bottom of screen",
         "Max 4 `primaryItems` recommended; overflow goes in `moreItems` shown in a \"More\" sheet",
-        "Use with `useIsMobile()` hook to conditionally render instead of AppSidebar",
+        "Use with `useIsMobile()` hook to conditionally render instead of Sidebar",
         "Requires LinkProvider for framework-specific link components (e.g., Next.js Link)"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Overflow \"More\" menu re-founded on the DS `Sheet` primitive — inherits focus trap, scroll lock, return-focus, `aria-modal`, and trigger↔panel ARIA wiring (was a hand-rolled `role=\"dialog\"` with none of these). Composes `Badge` for notification counts and the Sheet's built-in close (≥ touch target)."
+        },
         {
           "version": "0.19.0",
           "summary": "**Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background"
@@ -12046,7 +12455,7 @@
         "notes": [
           "**Context provider for AppCommandPalette.** Registers page-level navigation items that the command palette surfaces as commands.",
           "**Place at app root** — wrap both AppCommandPalette and the rest of the app inside `<CommandRegistryProvider>`. Positioning matters: any AppCommandPalette outside the provider gets `useCommandRegistry() === null` and falls back to minimal functionality.",
-          "**Separation of pages vs adminPages** — the palette filters based on user role / `isAdmin` flag. Keep admin-only routes in the adminPages array to avoid leaking them to regular users.",
+          "**Separation of pages vs adminPages** — this is an ORGANIZATIONAL split, not access control. The component does NOT enforce anything: YOU populate `adminPages` conditionally (e.g. only when the signed-in user is an admin). Anything you put in `adminPages` is still shipped to the client — do real authorization on the server, not here.",
           "**useCommandRegistry()** is the consumer hook — returns the full registry or null. Use in your own command-aware components (e.g. a Spotlight-style keyboard-search embed elsewhere in the app).",
           "**Works with LinkProvider** — CommandPaletteItems navigate via `onNavigate` prop on AppCommandPalette, which routes to your framework's Link component."
         ]
@@ -12121,7 +12530,7 @@
       },
       "composition": {
         "notes": [
-          "**The framework router bridge for all shell components.** Without LinkProvider, AppSidebar / BottomNavbar / TopBar.UserMenu / AppCommandPalette render plain `<a>` tags — that means full page reloads instead of client-side navigation.",
+          "**The framework router bridge for all shell components.** Without LinkProvider, Sidebar / BottomNavbar / TopBar.UserMenu / AppCommandPalette render plain `<a>` tags — that means full page reloads instead of client-side navigation.",
           "**Required setup:** ```tsx // Next.js import Link from 'next/link' <LinkProvider component={Link}> <App /> </LinkProvider> ```",
           "**Place at app root** — above every shell component that renders nav links.",
           "**component must be forwardRef** (Next.js Link, Remix Link, react-router Link all qualify). Custom components need to forward ref + forward className + forward all anchor props.",
@@ -12144,7 +12553,7 @@
         }
       },
       "examples": [
-        "import Link from 'next/link'\n\n<LinkProvider component={Link}>\n  <AppSidebar ... />\n  <BottomNavbar ... />\n</LinkProvider>"
+        "import Link from 'next/link'\n\n<LinkProvider component={Link}>\n  <Sidebar ... />\n  <BottomNavbar ... />\n</LinkProvider>"
       ],
       "gotchas": [
         "Without LinkProvider, shell components render plain `<a>` tags (full page reloads)",
@@ -12429,7 +12838,7 @@
           "**NotificationCenter lives inside TopBar.Right** — it's a complete bell+popover component. Drop it in a TopBar.Section next to other icon buttons.",
           "**UserMenu is composable:** `userMenuItems` inserts custom items between the built-in Profile and the color-mode toggle. Each item can navigate (href), run an action (onClick), or show a separator/badge/color decoration.",
           "**Responsive hiding:** Actions that shouldn't appear on mobile use `className=\"hidden md:flex\"` on the IconButton — the component doesn't enforce mobile hiding; that's layout responsibility.",
-          "**Pairs with AppSidebar** — desktop app shell is typically `<TopBar>` + `<AppSidebar>` + main content region."
+          "**Pairs with Sidebar** — desktop app shell is typically `<TopBar>` + `<Sidebar>` + main content region."
         ]
       },
       "docPath": "docs/components/shell/top-bar.md",