@devalok/shilp-sutra 0.53.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.53.0",
+  "packageVersion": "0.54.0",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -5217,6 +5217,7 @@
           "type": {
             "name": "enum",
             "value": [
+              "xs",
               "sm",
               "md",
               "lg"
@@ -5258,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",
@@ -5695,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"
@@ -6149,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."
         ]
@@ -6165,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": [
         {
@@ -6295,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."
         ]
       },
@@ -6309,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",
@@ -8544,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"
@@ -8572,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": {
@@ -8588,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?\""
             }
           }
         }
@@ -9867,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": {
@@ -9882,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()} />"
       ],
@@ -10554,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",
@@ -10584,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": {
@@ -10604,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"
             }
           }
         }
@@ -10997,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",
@@ -11268,7 +11445,7 @@
             "onSubmit": {
               "type": {
                 "name": "function",
-                "raw": "(html: string, plainText: string) => void (REQUIRED)"
+                "raw": "(message: RichChatInputMessage) => void (REQUIRED)"
               },
               "required": false
             },
@@ -11286,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",
@@ -11322,6 +11502,19 @@
               },
               "required": false
             },
+            "charCountDisplay": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "always",
+                  "focus",
+                  "near-limit",
+                  "hidden"
+                ]
+              },
+              "required": false,
+              "defaultValue": "near-limit"
+            },
             "mentions": {
               "type": {
                 "name": "object",
@@ -11364,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",
@@ -11414,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",
@@ -11817,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."
         ]
@@ -12051,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": [
@@ -12139,8 +12395,8 @@
       },
       "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+ (composes the `Badge` primitive).",
@@ -12158,7 +12414,7 @@
       "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": [
@@ -12199,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."
         ]
@@ -12274,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.",
@@ -12297,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)",
@@ -12582,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",