@xsolla/xui-b2b-sidebar 0.148.0 → 0.148.1

package/README.md

@@ -0,0 +1,280 @@
+# B2B 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.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-b2b-sidebar
+# or
+yarn add @xsolla/xui-b2b-sidebar
+```
+
+## Demo
+
+### Basic usage
+
+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`.
+
+```tsx
+import { useState } from 'react';
+import { Home, Wallet, Settings } from '@xsolla/xui-icons-base';
+import {
+  Sidebar,
+  SidebarProvider,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuCollapsible,
+  SidebarMenuSub,
+  SidebarTrigger,
+} from '@xsolla/xui-b2b-sidebar';
+
+export default function AppShell({ pathname }: { pathname: string }) {
+  const [collapsed, setCollapsed] = useState(false);
+
+  return (
+    <SidebarProvider
+      collapsed={collapsed}
+      onCollapsedChange={setCollapsed}
+      pathname={pathname}
+      linkComponent={MyRouterLink}
+    >
+      <Sidebar
+        collapsedItems={mainNavItems}
+        collapsedBottomItems={workspaceNavItems}
+      >
+        <SidebarContent>
+          <SidebarGroup label="Main">
+            <SidebarMenu>
+              <SidebarMenuItem
+                to="/dashboard"
+                icon={<Home size={18} variant="line" />}
+                label="Dashboard"
+              />
+              <SidebarMenuCollapsible
+                icon={<Wallet size={18} variant="line" />}
+                label="Finance"
+                matchPaths={['/finance']}
+              >
+                <SidebarMenuSub>
+                  <SidebarMenuItem to="/finance/payouts" label="Payouts" isNested />
+                  <SidebarMenuItem to="/finance/reports" label="Reports" isNested />
+                </SidebarMenuSub>
+              </SidebarMenuCollapsible>
+            </SidebarMenu>
+          </SidebarGroup>
+          <SidebarGroup label="Workspace">
+            <SidebarMenu>
+              <SidebarMenuItem
+                to="/settings"
+                icon={<Settings size={18} variant="line" />}
+                label="Settings"
+              />
+            </SidebarMenu>
+          </SidebarGroup>
+        </SidebarContent>
+        <SidebarFooter>
+          <SidebarTrigger />
+        </SidebarFooter>
+      </Sidebar>
+    </SidebarProvider>
+  );
+}
+```
+
+### 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.
+
+```tsx
+import { NavLink } from 'react-router-dom';
+import type { SidebarLinkProps } from '@xsolla/xui-b2b-sidebar';
+
+const RouterLink: React.FC<SidebarLinkProps> = ({
+  to,
+  exact,
+  className,
+  activeClassName,
+  children,
+  onClick,
+  dataId,
+}) => (
+  <NavLink
+    to={to ?? '#'}
+    end={exact}
+    className={className}
+    activeClassName={activeClassName}
+    data-id={dataId}
+    onClick={onClick}
+  >
+    {children}
+  </NavLink>
+);
+
+<SidebarProvider linkComponent={RouterLink} pathname={location.pathname} ...>
+```
+
+### 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.
+
+```tsx
+<SidebarMenuCollapsible
+  icon={<Wallet size={18} variant="line" />}
+  label="Finance"
+  matchPaths={['/finance', '/finance/payouts', '/finance/reports']}
+>
+  <SidebarMenuSub>{/* ... */}</SidebarMenuSub>
+</SidebarMenuCollapsible>
+```
+
+### Item flags (pin / badge / beta / external)
+
+```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"
+/>
+```
+
+### 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.
+
+```tsx
+const mainNavItems: SidebarItemType[] = [
+  { to: '/dashboard', label: 'Dashboard', icon: <Home size={18} variant="line" /> },
+  {
+    label: 'Finance',
+    icon: <Wallet size={18} variant="line" />,
+    children: [
+      { to: '/finance/payouts', label: 'Payouts' },
+      { to: '/finance/reports', label: 'Reports' },
+    ],
+  },
+];
+
+<Sidebar
+  collapsedItems={mainNavItems}
+  collapsedBottomItems={[{ to: '/settings', label: 'Settings', icon: <Settings size={18} /> }]}
+  onChatClick={() => openSupportChat()}
+  chatBadge={hasUnreadMessages}
+/>
+```
+
+## 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
+
+```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[];
+};
+```
+
+## 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`.
+- 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-b2b-sidebar",
-  "version": "0.148.0",
+  "version": "0.148.1",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,11 +13,11 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.148.0",
-    "@xsolla/xui-icons-base": "0.148.0",
-    "@xsolla/xui-primitives-core": "0.148.0",
-    "@xsolla/xui-tooltip": "0.148.0",
-    "@xsolla/xui-typography": "0.148.0"
+    "@xsolla/xui-core": "0.148.1",
+    "@xsolla/xui-icons-base": "0.148.1",
+    "@xsolla/xui-primitives-core": "0.148.1",
+    "@xsolla/xui-tooltip": "0.148.1",
+    "@xsolla/xui-typography": "0.148.1"
   },
   "peerDependencies": {
     "react": ">=16.8.0",