@xsolla/xui-b2b-sidebar 0.150.0 → 0.151.0

package/README.md

@@ -1,18 +1,43 @@
-# B2B Sidebar
+# Sidebar
 
-A composable navigation sidebar for B2B admin surfaces. Renders an expanded panel with grouped menu items and a parallel collapsed icon strip with hover-popovers, both driven by the same `SidebarProvider` so the active route, link component, and collapsed state stay in sync.
+A composable navigation sidebar for B2B admin surfaces. Renders an expanded panel with grouped menu items and a parallel collapsed icon strip with hover popovers, both driven by the same `SidebarProvider` so the active route, link component, and collapsed state stay in sync.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-b2b-sidebar
-# or
-yarn add @xsolla/xui-b2b-sidebar
 ```
 
-## Demo
+## Imports
 
-### Basic usage
+```tsx
+import {
+  Sidebar,
+  SidebarProvider,
+  useSidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuCollapsible,
+  SidebarMenuSub,
+  SidebarTrigger,
+  SidebarChatButton,
+  SidebarCollapsed,
+  type SidebarProps,
+  type SidebarProviderProps,
+  type SidebarMenuItemProps,
+  type SidebarMenuCollapsibleProps,
+  type SidebarCollapsedProps,
+  type SidebarItemType,
+  type SidebarLinkProps,
+  type SidebarLinkActiveCheck,
+  type SidebarLinkClickHandler,
+} from '@xsolla/xui-b2b-sidebar';
+```
+
+## Quick start
 
 Wrap the sidebar in `SidebarProvider`, supplying the current `pathname`, the controlled `collapsed` state, and your app's link component (React Router, Next.js `Link`, etc.). The default link is a plain `<a>` if you omit `linkComponent`.
 
@@ -32,7 +57,7 @@ import {
   SidebarTrigger,
 } from '@xsolla/xui-b2b-sidebar';
 
-export default function AppShell({ pathname }: { pathname: string }) {
+function AppShell({ pathname }: { pathname: string }) {
   const [collapsed, setCollapsed] = useState(false);
 
   return (
@@ -40,22 +65,18 @@ export default function AppShell({ pathname }: { pathname: string }) {
       collapsed={collapsed}
       onCollapsedChange={setCollapsed}
       pathname={pathname}
-      linkComponent={MyRouterLink}
     >
-      <Sidebar
-        collapsedItems={mainNavItems}
-        collapsedBottomItems={workspaceNavItems}
-      >
+      <Sidebar>
         <SidebarContent>
           <SidebarGroup label="Main">
             <SidebarMenu>
               <SidebarMenuItem
                 to="/dashboard"
-                icon={<Home size={18} variant="line" />}
+                icon={<Home size={18} variant="line" aria-hidden />}
                 label="Dashboard"
               />
               <SidebarMenuCollapsible
-                icon={<Wallet size={18} variant="line" />}
+                icon={<Wallet size={18} variant="line" aria-hidden />}
                 label="Finance"
                 matchPaths={['/finance']}
               >
@@ -70,7 +91,7 @@ export default function AppShell({ pathname }: { pathname: string }) {
             <SidebarMenu>
               <SidebarMenuItem
                 to="/settings"
-                icon={<Settings size={18} variant="line" />}
+                icon={<Settings size={18} variant="line" aria-hidden />}
                 label="Settings"
               />
             </SidebarMenu>
@@ -85,9 +106,176 @@ export default function AppShell({ pathname }: { pathname: string }) {
 }
 ```
 
+## API Reference
+
+None of the sidebar components extend `ThemeOverrideProps` — they read theme via `useResolvedTheme()` from the surrounding provider. Wrap the app in a theme provider if you need to override mode or product context.
+
+### `<SidebarProvider>`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `collapsed` | `boolean` | uncontrolled | Controlled collapsed state. Omit to use the internal state. |
+| `onCollapsedChange` | `(collapsed: boolean) => void` | — | Called when the user toggles via `SidebarTrigger` or the collapsed-mode toggle. |
+| `pathname` | `string` | `""` | Current route, used for active-state matching and `matchPaths` auto-expand. |
+| `linkComponent` | `ComponentType<SidebarLinkProps>` | plain `<a>` | Router link component. |
+| `children` | `ReactNode` | — | Sidebar tree. |
+
+### `useSidebar()`
+
+Read the provider's state from anywhere inside the tree.
+
+```ts
+function useSidebar(): {
+  collapsed: boolean;
+  onCollapsedChange: (collapsed: boolean) => void;
+  pathname: string;
+  LinkComponent: React.ComponentType<SidebarLinkProps>;
+  expandedId: string | null;
+  onExpandedIdChange: (id: string | null) => void;
+};
+```
+
+`expandedId` / `onExpandedIdChange` coordinate which `SidebarMenuCollapsible` is open — only one at a time.
+
+### `<Sidebar>`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `collapsedItems` | `SidebarItemType[]` | `[]` | Top icons in the collapsed strip. |
+| `collapsedToolItems` | `SidebarItemType[]` | `[]` | Tool icons rendered after a spacer. |
+| `collapsedBottomItems` | `SidebarItemType[]` | `[]` | Bottom icons (e.g. Settings, Billing). |
+| `showChat` | `boolean` | `true` | Render the chat button in the collapsed footer. |
+| `onChatClick` | `() => void` | — | Click handler for the chat button. |
+| `chatBadge` | `boolean` | `false` | Show an unread-indicator dot on the chat button. |
+| `children` | `ReactNode` | — | The expanded tree (`SidebarContent`, `SidebarFooter`). |
+
+### `<SidebarMenuItem>`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `to` | `string` | — | Route URL passed through to `linkComponent`. |
+| `label` | `ReactNode` | — | Text label. |
+| `icon` | `ReactNode` | — | Leading icon (hidden when `isNested`). |
+| `exact` | `boolean` | — | Exact-match flag forwarded to the link component. |
+| `external` | `boolean` | — | Marks the link as external (sets `target`/`rel`). |
+| `hasExternalIcon` | `boolean` | — | Shows the external-link icon at the trailing edge. |
+| `target` | `string \| null` | — | Anchor target. |
+| `onClick` | `SidebarLinkClickHandler` | — | Click handler. |
+| `dataId` | `string` | — | `data-id` attribute for tests/analytics. |
+| `isActive` | `SidebarLinkActiveCheck` | — | Custom active-check forwarded to the link. |
+| `isPinned` | `boolean` | — | Renders the icon at 12px to indicate a pinned item. |
+| `showBadge` | `boolean` | — | Shows a small alert dot next to the label. |
+| `hasTooltip` | `boolean` | — | Truncates labels longer than 20 chars and shows the full text on hover. |
+| `beta` | `boolean` | — | Renders a "Beta" tag at the trailing edge. |
+| `multiLine` | `boolean` | — | Allows the label to wrap to multiple lines. |
+| `extra` | `ReactNode` | — | Slot rendered between the icon and the label. |
+| `isNested` | `boolean` | `false` | Set when rendered inside `SidebarMenuSub` (drops the icon, indents under the rail). |
+
+### `<SidebarMenuCollapsible>`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `ReactNode` | — | Leading icon. |
+| `label` | `ReactNode` | — | Section label. |
+| `dataId` | `string` | — | `data-id` attribute. Also seeds the stable id used by `aria-controls`. |
+| `matchPaths` | `string[]` | `[]` | Route prefixes that auto-expand this section. |
+| `children` | `ReactNode` | — | Nested items, typically a `SidebarMenuSub` of `SidebarMenuItem isNested`. |
+
+### `<SidebarCollapsed>`
+
+Lower-level collapsed-strip renderer. The `<Sidebar>` component composes this for you; reach for it when you need to render the collapsed strip outside the standard layout.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `SidebarItemType[]` | — | Top icon items. |
+| `toolItems` | `SidebarItemType[]` | `[]` | Tool icons after a spacer. |
+| `bottomItems` | `SidebarItemType[]` | `[]` | Bottom icons. |
+| `onToggleCollapse` | `() => void` | — | Click handler for the toggle button in the footer. |
+| `onChatClick` | `() => void` | — | Click handler for the chat button. |
+| `showChat` | `boolean` | `true` | Render the chat button. |
+| `chatBadge` | `boolean` | `false` | Show the unread dot. |
+
+### `<SidebarContent>`
+
+Scrollable body container rendered inside `<Sidebar>`. Adds the configured padding and a hover-visible scrollbar.
+
+### `<SidebarFooter>`
+
+Bordered footer row for the bottom of the sidebar; typically wraps the chat button and trigger.
+
+### `<SidebarTrigger>`
+
+Collapse/expand toggle button. Reads/writes state from the surrounding `SidebarProvider`.
+
+### `<SidebarChatButton>`
+
+Branded chat button for the footer. Props: `onClick: () => void`, `badge?: boolean`.
+
+### `<SidebarGroup>`
+
+Section container with an optional uppercase label. Props: `label?: ReactNode`, `children: ReactNode`.
+
+### `<SidebarMenu>`
+
+Flex-column wrapper around `SidebarMenuItem` / `SidebarMenuCollapsible` children.
+
+### `<SidebarMenuSub>`
+
+Fragment used as a structural marker inside collapsibles to group nested menu items.
+
+### Types
+
+```ts
+type SidebarItemType = {
+  to?: string;
+  label: ReactNode;
+  icon?: ReactNode;
+  dataId?: string;
+  exact?: boolean;
+  external?: boolean;
+  hasExternalIcon?: boolean;
+  target?: string | null;
+  onClick?: SidebarLinkClickHandler;
+  hasTooltip?: boolean;
+  beta?: boolean;
+  multiLine?: boolean;
+  isPinned?: boolean;
+  showBadge?: boolean;
+  reverse?: boolean;        // reserved for legacy reversed-layout items
+  isActive?: SidebarLinkActiveCheck;
+  children?: SidebarItemType[];
+  privileges?: string[];
+  visibility?: string;
+  disallowedIntegrationTypes?: string[];
+  extra?: ReactNode;
+};
+
+interface SidebarLinkProps {
+  to?: string;
+  exact?: boolean;
+  external?: boolean;
+  target?: string | null;
+  className?: string;
+  activeClassName?: string;
+  isActive?: SidebarLinkActiveCheck;
+  onClick?: SidebarLinkClickHandler;
+  dataId?: string;
+  children: ReactNode;
+}
+
+type SidebarLinkActiveCheck = (
+  match: unknown,
+  location: { pathname: string; search?: string; hash?: string }
+) => boolean;
+
+type SidebarLinkClickHandler = (event?: React.MouseEvent<HTMLElement>) => void;
+```
+
+## Examples
+
 ### Custom link component
 
-Supply your router's link via the `linkComponent` prop on `SidebarProvider`. The component receives `to`, `className`, `activeClassName`, `onClick`, `external`, `target`, `dataId`, and renders children.
+Supply your router's link via the `linkComponent` prop on `SidebarProvider`. The component receives `to`, `exact`, `external`, `target`, `className`, `activeClassName`, `isActive`, `onClick`, `dataId`, and renders children.
 
 ```tsx
 import { NavLink } from 'react-router-dom';
@@ -105,8 +293,7 @@ const RouterLink: React.FC<SidebarLinkProps> = ({
   <NavLink
     to={to ?? '#'}
     end={exact}
-    className={className}
-    activeClassName={activeClassName}
+    className={({ isActive }) => [className, isActive && activeClassName].filter(Boolean).join(' ')}
     data-id={dataId}
     onClick={onClick}
   >
@@ -114,48 +301,75 @@ const RouterLink: React.FC<SidebarLinkProps> = ({
   </NavLink>
 );
 
-<SidebarProvider linkComponent={RouterLink} pathname={location.pathname} ...>
+<SidebarProvider linkComponent={RouterLink} pathname={location.pathname}>
+  {/* ... */}
+</SidebarProvider>;
 ```
 
 ### Auto-expanding sections
 
-Pass `matchPaths` to `SidebarMenuCollapsible`. When the current `pathname` starts with any of the listed prefixes, the section auto-expands and stays expanded. Only one collapsible can be open at a time (Radix-style accordion), so navigating between sections collapses the others.
+Pass `matchPaths` to `SidebarMenuCollapsible`. When the current `pathname` starts with any of the listed prefixes, the section auto-expands. Only one collapsible can be open at a time, so navigating between sections collapses the others.
 
 ```tsx
+import { Wallet } from '@xsolla/xui-icons-base';
+import { SidebarMenuCollapsible, SidebarMenuSub, SidebarMenuItem } from '@xsolla/xui-b2b-sidebar';
+
 <SidebarMenuCollapsible
-  icon={<Wallet size={18} variant="line" />}
+  icon={<Wallet size={18} variant="line" aria-hidden />}
   label="Finance"
   matchPaths={['/finance', '/finance/payouts', '/finance/reports']}
 >
-  <SidebarMenuSub>{/* ... */}</SidebarMenuSub>
-</SidebarMenuCollapsible>
+  <SidebarMenuSub>
+    <SidebarMenuItem to="/finance/payouts" label="Payouts" isNested />
+    <SidebarMenuItem to="/finance/reports" label="Reports" isNested />
+  </SidebarMenuSub>
+</SidebarMenuCollapsible>;
 ```
 
-### Item flags (pin / badge / beta / external)
+### Item flags
 
 ```tsx
-<SidebarMenuItem to="/pinned" label="Pinned report" icon={<Pin size={18} />} isPinned showBadge />
-<SidebarMenuItem to="/labs" label="New analytics" icon={<Graph size={18} />} beta />
-<SidebarMenuItem
-  to="https://docs.example.com"
-  label="Documentation"
-  icon={<Layer size={18} />}
-  external
-  hasExternalIcon
-  target="_blank"
-/>
+import { Pin, Graph, Layer } from '@xsolla/xui-icons-base';
+import { SidebarMenuItem } from '@xsolla/xui-b2b-sidebar';
+
+<>
+  <SidebarMenuItem
+    to="/pinned"
+    label="Pinned report"
+    icon={<Pin size={18} aria-hidden />}
+    isPinned
+    showBadge
+  />
+  <SidebarMenuItem
+    to="/labs"
+    label="New analytics"
+    icon={<Graph size={18} aria-hidden />}
+    beta
+  />
+  <SidebarMenuItem
+    to="https://docs.example.com"
+    label="Documentation"
+    icon={<Layer size={18} aria-hidden />}
+    external
+    hasExternalIcon
+    target="_blank"
+  />
+</>;
 ```
 
 ### Collapsed icon strip
 
-Because the collapsed layout is fundamentally different (icons only, hover popovers), pass the icon-strip items separately as `collapsedItems`, `collapsedToolItems` (rendered after a spacer in the main scroll area), and `collapsedBottomItems` (rendered above the chat/toggle footer). Items with `children` open a hover popover listing the children; items without children open a single-link popover.
+Because the collapsed layout is fundamentally different (icons only, hover popovers), pass icon-strip items separately as `collapsedItems`, `collapsedToolItems` (rendered after a spacer in the main scroll area), and `collapsedBottomItems` (rendered above the chat/toggle footer). Items with `children` open a hover popover listing the children; items without children open a single-link popover.
 
 ```tsx
+import { Home, Wallet, Settings } from '@xsolla/xui-icons-base';
+import { Sidebar, type SidebarItemType } from '@xsolla/xui-b2b-sidebar';
+
 const mainNavItems: SidebarItemType[] = [
-  { to: '/dashboard', label: 'Dashboard', icon: <Home size={18} variant="line" /> },
+  { to: '/dashboard', label: 'Dashboard', icon: <Home size={18} variant="line" aria-hidden /> },
   {
     label: 'Finance',
-    icon: <Wallet size={18} variant="line" />,
+    icon: <Wallet size={18} variant="line" aria-hidden />,
     children: [
       { to: '/finance/payouts', label: 'Payouts' },
       { to: '/finance/reports', label: 'Reports' },
@@ -165,116 +379,27 @@ const mainNavItems: SidebarItemType[] = [
 
 <Sidebar
   collapsedItems={mainNavItems}
-  collapsedBottomItems={[{ to: '/settings', label: 'Settings', icon: <Settings size={18} /> }]}
+  collapsedBottomItems={[
+    { to: '/settings', label: 'Settings', icon: <Settings size={18} aria-hidden /> },
+  ]}
   onChatClick={() => openSupportChat()}
   chatBadge={hasUnreadMessages}
-/>
+>
+  {/* expanded tree */}
+</Sidebar>;
 ```
 
-## API Reference
-
-### SidebarProvider
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| `collapsed` | `boolean` | `false` | Controlled collapsed state. |
-| `onCollapsedChange` | `(collapsed: boolean) => void` | - | Called when the user toggles collapsed via the trigger button. |
-| `pathname` | `string` | `""` | Current route, used for active-state matching and auto-expand. |
-| `linkComponent` | `ComponentType<SidebarLinkProps>` | plain `<a>` | Router link component. Receives `to`, `className`, `activeClassName`, `onClick`, `external`, `target`, `dataId`, `children`. |
-| `children` | `ReactNode` | - | Sidebar tree. |
-
-### Sidebar
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| `collapsedItems` | `SidebarItemType[]` | `[]` | Top icons in the collapsed strip. |
-| `collapsedToolItems` | `SidebarItemType[]` | `[]` | Tool icons rendered after a spacer. |
-| `collapsedBottomItems` | `SidebarItemType[]` | `[]` | Bottom icons (e.g. Settings, Billing). |
-| `showChat` | `boolean` | `true` | Render the chat button in the collapsed footer. |
-| `onChatClick` | `() => void` | - | Click handler for the chat button. |
-| `chatBadge` | `boolean` | `false` | Show an unread-indicator dot on the chat button. |
-| `children` | `ReactNode` | - | The expanded tree (`SidebarContent`, `SidebarFooter`). |
-
-### SidebarMenuItem
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| `to` | `string` | - | Route URL passed through to `linkComponent`. |
-| `label` | `ReactNode` | - | Text label. |
-| `icon` | `ReactNode` | - | Leading icon (hidden when `isNested`). |
-| `exact` | `boolean` | - | Exact-match flag forwarded to the link component. |
-| `external` | `boolean` | - | Marks the link as external (sets `target`/`rel`). |
-| `hasExternalIcon` | `boolean` | - | Shows the external-link icon at the trailing edge. |
-| `target` | `string \| null` | - | Anchor target. |
-| `onClick` | `(event?) => void` | - | Click handler. |
-| `dataId` | `string` | - | `data-id` attribute for tests/analytics. |
-| `isActive` | `(match, location) => boolean` | - | Custom active-check forwarded to the link. |
-| `isPinned` | `boolean` | - | Renders the icon at 12px to indicate a pinned item. |
-| `showBadge` | `boolean` | - | Shows a small alert dot next to the label. |
-| `hasTooltip` | `boolean` | - | Truncates labels longer than 20 chars and shows the full text on hover. |
-| `beta` | `boolean` | - | Renders a "Beta" tag at the trailing edge. |
-| `multiLine` | `boolean` | - | Allows the label to wrap to multiple lines. |
-| `extra` | `ReactNode` | - | Slot rendered between the icon and the label. |
-| `isNested` | `boolean` | `false` | Set when rendered inside `SidebarMenuSub` (drops the icon, indents under the rail). |
-
-### SidebarMenuCollapsible
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| `icon` | `ReactNode` | - | Leading icon. |
-| `label` | `ReactNode` | - | Section label. |
-| `dataId` | `string` | - | `data-id` attribute. |
-| `matchPaths` | `string[]` | `[]` | Route prefixes that auto-expand this section. |
-| `children` | `ReactNode` | - | Nested items, typically a `SidebarMenuSub` containing `SidebarMenuItem isNested`. |
-
-### SidebarTrigger / SidebarChatButton / SidebarFooter / SidebarGroup / SidebarMenu / SidebarMenuSub
-
-Layout primitives:
-
-- `<SidebarTrigger />` — collapse/expand toggle button (reads state from the provider).
-- `<SidebarChatButton onClick badge />` — branded chat button for the footer.
-- `<SidebarFooter>{...}</SidebarFooter>` — bordered footer row, typically holding the chat button and trigger.
-- `<SidebarGroup label="...">` — section container with optional uppercase label.
-- `<SidebarMenu>` — flex column wrapper around items.
-- `<SidebarMenuSub>` — fragment used as a structural marker inside collapsibles.
-
-### Types
+## Accessibility
 
-```ts
-type SidebarItemType = {
-  to?: string;
-  label: ReactNode;
-  icon?: ReactNode;
-  dataId?: string;
-  exact?: boolean;
-  external?: boolean;
-  hasExternalIcon?: boolean;
-  target?: string | null;
-  onClick?: (event?: MouseEvent) => void;
-  hasTooltip?: boolean;
-  beta?: boolean;
-  multiLine?: boolean;
-  isPinned?: boolean;
-  showBadge?: boolean;
-  isActive?: (match: unknown, location: { pathname: string }) => boolean;
-  children?: SidebarItemType[];
-  privileges?: string[];
-  visibility?: string;
-  disallowedIntegrationTypes?: string[];
-};
-```
+- The root sidebar is `role="navigation"` with `aria-label="Sidebar navigation"`. The expanded and collapsed panes are toggled via `aria-hidden` so only one is announced at a time.
+- `SidebarTrigger` and the collapsed-mode toggle have `aria-pressed` and a context-aware `aria-label` (`"Expand sidebar"` / `"Collapse sidebar"`).
+- Each `SidebarMenuCollapsible` header is a `<button>` with `aria-expanded` and `aria-controls` linking to its region.
+- Collapsed icon items expose `aria-haspopup="menu"` when they have children; popovers are keyboard-reachable (focus opens, blur closes after 150ms; Escape closes immediately).
+- Truncated labels (`hasTooltip`) fall back to a Tooltip with the full text.
 
 ## Behaviour
 
-- Expanded width is 280px, collapsed width is 48px; the wrapper animates `width` over 250ms and cross-fades the two views via opacity.
-- Only one `SidebarMenuCollapsible` is open at a time; the section auto-expands when `pathname` matches one of `matchPaths`.
+- Expanded width is sourced from `theme.sizing.sidebar().widthExpanded`, collapsed from `widthCollapsed`; the wrapper animates `width` and cross-fades the two views via opacity.
+- Only one `SidebarMenuCollapsible` is open at a time; the section auto-expands when `pathname` matches one of `matchPaths` (a leading `/<merchantId>` numeric prefix is stripped before matching).
 - Hover popovers in collapsed mode are rendered into a portal on `document.body` and positioned with viewport-clamped `position: fixed` math.
-- Custom scrollbar styling on the expanded scroll area; thumb fades in on sidebar hover.
 - Active route detection lives in the consumer's `linkComponent` — apply `activeClassName` when the link matches the current route.
-
-## Accessibility
-
-- Collapse/expand button has `aria-pressed` and a context-aware `aria-label` (`"Expand sidebar"` / `"Collapse sidebar"`).
-- Each `SidebarMenuCollapsible` header is a `<button>` with `aria-expanded` and `aria-controls` linking to the region.
-- Collapsed icon items expose `aria-haspopup="menu"` when they have children; popover is keyboard-reachable and closes on Escape.
-- Truncated labels (`hasTooltip`) fall back to a Tooltip with the full text.

package/native/index.d.mts

@@ -61,6 +61,7 @@ type SidebarItemType = {
     visibility?: string;
     disallowedIntegrationTypes?: Array<string>;
     isPinned?: boolean;
+    onPinToggle?: (e: MouseEvent<HTMLButtonElement>) => void;
     showBadge?: boolean;
 };
 
@@ -119,6 +120,8 @@ declare const SidebarTrigger: React.FC;
 interface SidebarGroupProps {
     label?: string;
     dataId?: string;
+    /** Docks this group to the bottom of the expanded sidebar (e.g. Settings, Billing). */
+    pinnedToBottom?: boolean;
     children: ReactNode;
 }
 declare const SidebarGroup: React.FC<SidebarGroupProps>;
@@ -139,6 +142,10 @@ interface SidebarMenuItemProps {
     dataId?: string;
     isActive?: SidebarLinkActiveCheck;
     isPinned?: boolean;
+    /** When provided, renders a pin/unpin toggle on hover (or always, when pinned). */
+    onPinToggle?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+    /** When true on a pinned item, the leading pin glyph swaps to a drag handle on row hover (reorder affordance). */
+    dragHandle?: boolean;
     showBadge?: boolean;
     hasTooltip?: boolean;
     beta?: boolean;
@@ -185,4 +192,42 @@ interface SidebarCollapsedProps {
 }
 declare const SidebarCollapsed: React.FC<SidebarCollapsedProps>;
 
-export { Sidebar, SidebarChatButton, SidebarCollapsed, type SidebarCollapsedProps, SidebarContent, SidebarFooter, SidebarGroup, type SidebarItemType, type SidebarLinkActiveCheck, type SidebarLinkClickHandler, type SidebarLinkProps, SidebarMenu, SidebarMenuCollapsible, type SidebarMenuCollapsibleProps, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarTrigger, useSidebar };
+interface SidebarPinnedItem {
+    key: string;
+    to: string;
+    label: ReactNode;
+    exact?: boolean;
+}
+interface SidebarPinnedListProps {
+    /** Ordered list of currently-pinned items. */
+    items: SidebarPinnedItem[];
+    /** Called when the user clicks the × on a pinned shortcut. */
+    onUnpin: (key: string) => void;
+    /**
+     * Called as the user drags to reorder. Omit to disable drag-and-drop —
+     * the leading icon stays as the static pin glyph.
+     */
+    onReorder?: (fromKey: string, toKey: string) => void;
+    /** Render 8px top/bottom spacers when items are present. Default true. */
+    spacers?: boolean;
+}
+/**
+ * Renders the pinned shortcuts list with pointer-event-based drag-and-drop
+ * reorder. Drag only initiates from the leading drag-handle area on each row.
+ *
+ * Pinning is fully opt-in: consumers who don't render this component get no
+ * pin UI. Consumers without a reorder backend can omit `onReorder`; the list
+ * stays static but unpinning still works.
+ */
+declare const SidebarPinnedList: React.FC<SidebarPinnedListProps>;
+/**
+ * Helper for the collapsed sidebar: returns a single `SidebarItemType` whose
+ * popover lists every pinned shortcut. Spread it into `collapsedItems` at the
+ * position you want the Pin button to appear. Returns `null` when no items.
+ */
+declare const getPinnedCollapsedItem: (items: SidebarPinnedItem[], options?: {
+    label?: string;
+    dataId?: string;
+}) => SidebarItemType | null;
+
+export { Sidebar, SidebarChatButton, SidebarCollapsed, type SidebarCollapsedProps, SidebarContent, SidebarFooter, SidebarGroup, type SidebarItemType, type SidebarLinkActiveCheck, type SidebarLinkClickHandler, type SidebarLinkProps, SidebarMenu, SidebarMenuCollapsible, type SidebarMenuCollapsibleProps, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, type SidebarPinnedItem, SidebarPinnedList, type SidebarPinnedListProps, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarTrigger, getPinnedCollapsedItem, useSidebar };

package/native/index.d.ts

@@ -61,6 +61,7 @@ type SidebarItemType = {
     visibility?: string;
     disallowedIntegrationTypes?: Array<string>;
     isPinned?: boolean;
+    onPinToggle?: (e: MouseEvent<HTMLButtonElement>) => void;
     showBadge?: boolean;
 };
 
@@ -119,6 +120,8 @@ declare const SidebarTrigger: React.FC;
 interface SidebarGroupProps {
     label?: string;
     dataId?: string;
+    /** Docks this group to the bottom of the expanded sidebar (e.g. Settings, Billing). */
+    pinnedToBottom?: boolean;
     children: ReactNode;
 }
 declare const SidebarGroup: React.FC<SidebarGroupProps>;
@@ -139,6 +142,10 @@ interface SidebarMenuItemProps {
     dataId?: string;
     isActive?: SidebarLinkActiveCheck;
     isPinned?: boolean;
+    /** When provided, renders a pin/unpin toggle on hover (or always, when pinned). */
+    onPinToggle?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+    /** When true on a pinned item, the leading pin glyph swaps to a drag handle on row hover (reorder affordance). */
+    dragHandle?: boolean;
     showBadge?: boolean;
     hasTooltip?: boolean;
     beta?: boolean;
@@ -185,4 +192,42 @@ interface SidebarCollapsedProps {
 }
 declare const SidebarCollapsed: React.FC<SidebarCollapsedProps>;
 
-export { Sidebar, SidebarChatButton, SidebarCollapsed, type SidebarCollapsedProps, SidebarContent, SidebarFooter, SidebarGroup, type SidebarItemType, type SidebarLinkActiveCheck, type SidebarLinkClickHandler, type SidebarLinkProps, SidebarMenu, SidebarMenuCollapsible, type SidebarMenuCollapsibleProps, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarTrigger, useSidebar };
+interface SidebarPinnedItem {
+    key: string;
+    to: string;
+    label: ReactNode;
+    exact?: boolean;
+}
+interface SidebarPinnedListProps {
+    /** Ordered list of currently-pinned items. */
+    items: SidebarPinnedItem[];
+    /** Called when the user clicks the × on a pinned shortcut. */
+    onUnpin: (key: string) => void;
+    /**
+     * Called as the user drags to reorder. Omit to disable drag-and-drop —
+     * the leading icon stays as the static pin glyph.
+     */
+    onReorder?: (fromKey: string, toKey: string) => void;
+    /** Render 8px top/bottom spacers when items are present. Default true. */
+    spacers?: boolean;
+}
+/**
+ * Renders the pinned shortcuts list with pointer-event-based drag-and-drop
+ * reorder. Drag only initiates from the leading drag-handle area on each row.
+ *
+ * Pinning is fully opt-in: consumers who don't render this component get no
+ * pin UI. Consumers without a reorder backend can omit `onReorder`; the list
+ * stays static but unpinning still works.
+ */
+declare const SidebarPinnedList: React.FC<SidebarPinnedListProps>;
+/**
+ * Helper for the collapsed sidebar: returns a single `SidebarItemType` whose
+ * popover lists every pinned shortcut. Spread it into `collapsedItems` at the
+ * position you want the Pin button to appear. Returns `null` when no items.
+ */
+declare const getPinnedCollapsedItem: (items: SidebarPinnedItem[], options?: {
+    label?: string;
+    dataId?: string;
+}) => SidebarItemType | null;
+
+export { Sidebar, SidebarChatButton, SidebarCollapsed, type SidebarCollapsedProps, SidebarContent, SidebarFooter, SidebarGroup, type SidebarItemType, type SidebarLinkActiveCheck, type SidebarLinkClickHandler, type SidebarLinkProps, SidebarMenu, SidebarMenuCollapsible, type SidebarMenuCollapsibleProps, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, type SidebarPinnedItem, SidebarPinnedList, type SidebarPinnedListProps, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarTrigger, getPinnedCollapsedItem, useSidebar };