@xsolla/xui-b2b-drawer 0.150.0 → 0.152.0

package/README.md

@@ -1,32 +1,42 @@
-# B2B Drawer
+# Drawer
 
-A slide-in panel that opens from the right edge of the screen, designed for B2B settings panels, multi-step flows, and auxiliary content that should not disrupt the main interface. Supports an optional stepper sidebar for multi-step workflows.
+A slide-in panel that opens from the right edge of the screen for B2B settings, multi-step flows, and auxiliary content. Supports an optional stepper sidebar for guided wizards.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-b2b-drawer
-# or
-yarn add @xsolla/xui-b2b-drawer
 ```
 
-## Demo
+## Imports
 
-### Basic Drawer
+```tsx
+import {
+  Drawer,
+  useDrawer,
+  type DrawerProps,
+  type DrawerSize,
+  type DrawerFooterAlign,
+  type UseDrawerOptions,
+  type UseDrawerReturn,
+} from '@xsolla/xui-b2b-drawer';
+```
+
+## Quick start
 
 ```tsx
-import React, { useState } from 'react';
+import { useState } from 'react';
 import { Drawer } from '@xsolla/xui-b2b-drawer';
 import { Button } from '@xsolla/xui-button';
 import { Typography } from '@xsolla/xui-typography';
 
-export default function BasicDrawer() {
+function BasicDrawer() {
   const [open, setOpen] = useState(false);
 
   return (
     <>
       <Button variant="primary" tone="brand" size="sm" onPress={() => setOpen(true)}>
-        Open Drawer
+        Open drawer
       </Button>
       <Drawer
         open={open}
@@ -50,37 +60,106 @@ export default function BasicDrawer() {
 }
 ```
 
-### Size Variants
+## API Reference
+
+### `<Drawer>`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | `false` | Whether the drawer is visible. |
+| `onClose` | `() => void` | — | Called when the drawer should close (Escape, overlay click, close button). |
+| `size` | `DrawerSize` | `"md"` | Width preset: `sm` 480px, `md` 620px, `lg` 1056px. |
+| `title` | `ReactNode` | — | Title displayed in the header. |
+| `onBack` | `() => void` | — | When provided, renders a back arrow button in the header. |
+| `headerAction` | `ReactNode` | — | Element rendered between the title and the close button. |
+| `closeOnOverlayClick` | `boolean` | `true` | Whether clicking the backdrop closes the drawer. |
+| `closeOnEscape` | `boolean` | `true` | Whether pressing Escape closes the drawer. |
+| `footer` | `ReactNode` | — | Footer content (typically action buttons). |
+| `footerAlign` | `DrawerFooterAlign` | `"right"` | Alignment of footer content. |
+| `footerShadow` | `boolean` | `false` | Show a drop shadow above the footer (useful with scrollable content). |
+| `footerFullWidth` | `boolean` | `true` | Whether footer buttons stretch to full width. |
+| `stepper` | `ReactNode` | — | Stepper sidebar rendered to the left of the content panel. |
+| `children` | `ReactNode` | — | **Required.** Main scrollable body content. |
+| `initialFocusRef` | `RefObject<HTMLElement>` | — | Ref to the element that should receive focus when the drawer opens. |
+
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
+
+#### Deprecated props
+
+| Prop | Replacement |
+| --- | --- |
+| `isOpen` | `open` |
+| `header` (`{ title, onBack }`) | `title` + `onBack` |
+| `bottom` | `footer` |
+
+### `useDrawer(options?)`
+
+Convenience hook that owns local open/close state for a drawer.
+
+```ts
+function useDrawer(options?: UseDrawerOptions): UseDrawerReturn;
+
+interface UseDrawerOptions {
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+
+interface UseDrawerReturn {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+}
+```
+
+`onOpen` / `onClose` fire after the internal state flips — use them to coordinate analytics or external state.
+
+### Type exports
+
+```ts
+type DrawerSize = 'sm' | 'md' | 'lg';
+type DrawerFooterAlign = 'center' | 'right';
+```
+
+## Examples
+
+### Size variants
 
 ```tsx
-// sm = 480px, md = 620px (default), lg = 1056px
-<Drawer open={open} onClose={onClose} title="Small" size="sm">{...}</Drawer>
-<Drawer open={open} onClose={onClose} title="Medium" size="md">{...}</Drawer>
-<Drawer open={open} onClose={onClose} title="Large"  size="lg">{...}</Drawer>
+import { Drawer } from '@xsolla/xui-b2b-drawer';
+
+<>
+  {/* sm = 480px, md = 620px (default), lg = 1056px */}
+  <Drawer open={open} onClose={onClose} title="Small" size="sm">{...}</Drawer>
+  <Drawer open={open} onClose={onClose} title="Medium" size="md">{...}</Drawer>
+  <Drawer open={open} onClose={onClose} title="Large" size="lg">{...}</Drawer>
+</>;
 ```
 
-### With Back Button
+### With back button
 
 ```tsx
+import { Drawer } from '@xsolla/xui-b2b-drawer';
+
 <Drawer
   open={open}
   onClose={onClose}
-  title="Step Details"
+  title="Step details"
   onBack={() => goToPreviousStep()}
 >
   {/* back arrow appears in the header */}
-</Drawer>
+</Drawer>;
 ```
 
-### With Header Action
+### With header action
 
 ```tsx
+import { Drawer } from '@xsolla/xui-b2b-drawer';
 import { Button } from '@xsolla/xui-button';
 
 <Drawer
   open={open}
   onClose={onClose}
-  title="User Profile"
+  title="User profile"
   headerAction={
     <Button variant="ghost" tone="brand" size="sm">
       View history
@@ -88,15 +167,35 @@ import { Button } from '@xsolla/xui-button';
   }
 >
   {/* action renders between the title and the close button */}
-</Drawer>
+</Drawer>;
 ```
 
-### With Stepper Sidebar
+### `useDrawer` hook
+
+```tsx
+import { Drawer, useDrawer } from '@xsolla/xui-b2b-drawer';
+import { Button } from '@xsolla/xui-button';
+import { Typography } from '@xsolla/xui-typography';
+
+function HookExample() {
+  const drawer = useDrawer({ onOpen: () => console.log('opened') });
+  return (
+    <>
+      <Button variant="primary" tone="brand" size="sm" onPress={drawer.open}>
+        Open
+      </Button>
+      <Drawer open={drawer.isOpen} onClose={drawer.close} title="Hello">
+        <Typography variant="bodyMd">Driven by useDrawer.</Typography>
+      </Drawer>
+    </>
+  );
+}
+```
 
-Use the `stepper` prop to render a `@xsolla/xui-b2b-stepper` alongside the content panel, creating a guided multi-step flow.
+### With stepper sidebar
 
 ```tsx
-import React, { useState } from 'react';
+import { useState } from 'react';
 import { Drawer } from '@xsolla/xui-b2b-drawer';
 import { Stepper } from '@xsolla/xui-b2b-stepper';
 import { Button } from '@xsolla/xui-button';
@@ -108,13 +207,15 @@ const STEPS = [
   { title: 'Confirm', description: 'Review and submit' },
 ];
 
-export default function StepperDrawer() {
+function StepperDrawer() {
   const [open, setOpen] = useState(false);
   const [active, setActive] = useState(0);
 
   const steps = STEPS.map((s, i) => ({
     ...s,
-    state: i < active ? 'complete' as const : i === active ? 'current' as const : 'incomplete' as const,
+    state:
+      i < active ? ('complete' as const) :
+      i === active ? ('current' as const) : ('incomplete' as const),
   }));
 
   const isLast = active === steps.length - 1;
@@ -122,13 +223,13 @@ export default function StepperDrawer() {
   return (
     <>
       <Button variant="primary" tone="brand" size="sm" onPress={() => { setActive(0); setOpen(true); }}>
-        Open Wizard
+        Open wizard
       </Button>
       <Drawer
         open={open}
         onClose={() => setOpen(false)}
         title={STEPS[active].title}
-        onBack={active > 0 ? () => setActive(a => a - 1) : undefined}
+        onBack={active > 0 ? () => setActive((a) => a - 1) : undefined}
         stepper={
           <Stepper
             steps={steps}
@@ -146,7 +247,7 @@ export default function StepperDrawer() {
               variant="primary"
               tone="brand"
               size="sm"
-              onPress={() => isLast ? setOpen(false) : setActive(a => a + 1)}
+              onPress={() => (isLast ? setOpen(false) : setActive((a) => a + 1))}
             >
               {isLast ? 'Submit' : 'Next'}
             </Button>
@@ -160,13 +261,17 @@ export default function StepperDrawer() {
 }
 ```
 
-### Scrollable Content with Footer Shadow
+### Scrollable content with footer shadow
 
 ```tsx
+import { Drawer } from '@xsolla/xui-b2b-drawer';
+import { Button } from '@xsolla/xui-button';
+import { Typography } from '@xsolla/xui-typography';
+
 <Drawer
   open={open}
   onClose={onClose}
-  title="Long Content"
+  title="Long content"
   footerShadow
   footer={<Button variant="primary" tone="brand" size="sm">Done</Button>}
 >
@@ -175,53 +280,20 @@ export default function StepperDrawer() {
       <Typography key={i} variant="bodyMd">Item {i + 1}</Typography>
     ))}
   </div>
-</Drawer>
+</Drawer>;
 ```
 
-## API Reference
-
-### Drawer
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| `open` | `boolean` | `false` | Whether the drawer is visible. |
-| `onClose` | `() => void` | - | Called when the drawer should close (Escape key, overlay click, close button). |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Width preset: sm=480px, md=620px, lg=1056px. |
-| `title` | `ReactNode` | - | Title displayed in the header. |
-| `onBack` | `() => void` | - | When provided, renders a back arrow button in the header. |
-| `headerAction` | `ReactNode` | - | Optional element rendered between the title and the close button. |
-| `closeOnOverlayClick` | `boolean` | `true` | Whether clicking the backdrop closes the drawer. |
-| `closeOnEscape` | `boolean` | `true` | Whether pressing Escape closes the drawer. |
-| `footer` | `ReactNode` | - | Footer content (typically action buttons). |
-| `footerAlign` | `"center" \| "right"` | `"right"` | Alignment of footer content. |
-| `footerShadow` | `boolean` | `false` | Show a drop shadow above the footer (useful with scrollable content). |
-| `footerFullWidth` | `boolean` | `true` | Whether footer buttons stretch to full width. |
-| `stepper` | `ReactNode` | - | Optional stepper sidebar rendered to the left of the content panel. |
-| `children` | `ReactNode` | - | Main scrollable body content. |
-| `initialFocusRef` | `RefObject<HTMLElement>` | - | Ref to the element that should receive focus when the drawer opens. |
-| `themeMode` | `string` | - | Override the global theme mode for this component. |
-| `themeProductContext` | `string` | - | Override the global product context for this component. |
-
-**Deprecated props** (still accepted for backwards compatibility):
+## Accessibility
 
-| Prop | Replacement |
-| :--- | :---------- |
-| `isOpen` | `open` |
-| `header` | `title` + `onBack` |
-| `bottom` | `footer` |
+- Drawer panel is `role="dialog"` with `aria-modal="true"`.
+- `aria-label` is set to the `title` when it is a string. If you pass a non-string `title` and need a label, supply your own labelling via the surrounding markup or wrap the title text in a string node.
+- Focus is moved to `initialFocusRef` (or the close button, or the first focusable element) on open, and restored to the previously active element after the exit animation completes.
+- Tab is trapped inside the drawer; Shift+Tab wraps to the last focusable element, Tab wraps back to the first.
+- Escape closes the drawer unless `closeOnEscape={false}`.
+- Close and back buttons in the header have accessible labels.
 
 ## Behaviour
 
 - Slides in from the right with an animated transition.
-- Renders in a portal (z-index controlled by `theme.sizing.drawer().zIndex`) so it always appears above page content.
-- Traps keyboard focus inside the drawer while open; restores focus to the previously active element on close.
-- Body scroll is locked while the drawer is open on web.
-- When `stepper` is provided, the panel widens to accommodate the sidebar to the left of the content area.
-
-## Accessibility
-
-- `role="dialog"` and `aria-modal="true"` on the drawer panel.
-- Header title is linked via `aria-labelledby`.
-- Focus trap keeps Tab and Shift+Tab within the drawer.
-- Escape key closes the drawer (unless `closeOnEscape={false}`).
-- Close and back buttons have accessible labels.
+- Renders in a portal layer (z-index from `theme.sizing.drawer().zIndex`) so it appears above page content.
+- When `stepper` is provided, the panel widens to render the sidebar to the left of the content area inside the same surface.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-b2b-drawer",
-  "version": "0.150.0",
+  "version": "0.152.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,12 +13,12 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-b2b-stepper": "0.150.0",
-    "@xsolla/xui-button": "0.150.0",
-    "@xsolla/xui-core": "0.150.0",
-    "@xsolla/xui-icons-base": "0.150.0",
-    "@xsolla/xui-primitives-core": "0.150.0",
-    "@xsolla/xui-typography": "0.150.0"
+    "@xsolla/xui-b2b-stepper": "0.152.0",
+    "@xsolla/xui-button": "0.152.0",
+    "@xsolla/xui-core": "0.152.0",
+    "@xsolla/xui-icons-base": "0.152.0",
+    "@xsolla/xui-primitives-core": "0.152.0",
+    "@xsolla/xui-typography": "0.152.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",