@xsolla/xui-modal 0.148.0 → 0.148.2

package/README.md

@@ -0,0 +1,599 @@
+# Modal
+
+A cross-platform React modal dialog system for displaying focused overlay content. Built on a provider/context architecture with a hook-based API, the Modal package supports three presentation types (`popup`, `bottom-sheet`, `full-screen`), structured headers with back/close controls, content alignment, custom header/footer slots, focus trapping, and programmatic open/close — on both React (web) and React Native.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-modal @xsolla/xui-core
+# or
+yarn add @xsolla/xui-modal @xsolla/xui-core
+```
+
+**Peer dependencies:** `react >= 16.8.0`, `react-dom >= 16`, `styled-components >= 4`
+
+## Architecture
+
+The modal system uses a **Provider → Context → Hook** pattern:
+
+```
+┌──────────────────────────────────────────────────────┐
+│  ModalProvider                                        │
+│  ┌──────────────┐   ┌────────────────────────────┐   │
+│  │ ModalContext  │   │ ModalRoot (portal / stub)  │   │
+│  │  - openModal │   │  ┌───────────────────────┐ │   │
+│  │  - closeModal│──▶│  │ Overlay + Modal        │ │   │
+│  └──────────────┘   │  └───────────────────────┘ │   │
+│        ▲            └────────────────────────────┘   │
+│        │  useModal(renderFn)                          │
+│  ┌─────┴──────┐                                       │
+│  │  Your App  │                                       │
+│  └────────────┘                                       │
+└──────────────────────────────────────────────────────┘
+```
+
+1. **`ModalProvider`** — Wraps your application. Manages a record of open modals (keyed by random ID), and renders `ModalRoot` as a sibling inside the provider.
+2. **`ModalContext`** — React context that exposes `onOpenModal(key, renderFn)` and `onCloseModal(key)` to descendants.
+3. **`useModal(renderFn)`** — Consumer hook that returns `[open, close]` functions for programmatic control of a single modal.
+4. **`ModalRoot`** — Renders the top-most modal from the stack. On web, uses `ReactDOM.createPortal` into `document.body` with a fixed overlay. On React Native, this is a no-op stub (native modal rendering is not yet supported via the provider flow).
+5. **`Modal`** — The dialog component with built-in header (back/close buttons), scrollable body, and optional footer. Supports three presentation types.
+6. **`WorkArea`** — Internal chrome component that handles border-radius, box-shadow, background color, and alignment based on modal type.
+
+## Quick Start
+
+### 1. Wrap your app with `ModalProvider`
+
+```tsx
+import { XUIProvider } from '@xsolla/xui-core';
+import { ModalProvider } from '@xsolla/xui-modal';
+
+export default function App() {
+  return (
+    <XUIProvider initialMode="dark">
+      <ModalProvider>
+        <YourApp />
+      </ModalProvider>
+    </XUIProvider>
+  );
+}
+```
+
+### 2. Open modals with `useModal`
+
+```tsx
+import { Modal, useModal } from '@xsolla/xui-modal';
+import { Button } from '@xsolla/xui-button';
+
+function OpenModalButton() {
+  const [openModal, closeModal] = useModal(() => (
+    <Modal onClose={closeModal} title="Confirm Action">
+      <p>Are you sure you want to proceed?</p>
+      <Button onPress={closeModal}>Close</Button>
+    </Modal>
+  ));
+
+  return <Button onPress={openModal}>Open Modal</Button>;
+}
+```
+
+## Demo
+
+### Basic Modal with Hook
+
+```tsx
+import { Modal, ModalProvider, useModal } from '@xsolla/xui-modal';
+import { Button } from '@xsolla/xui-button';
+
+function ModalContent({ onClose }: { onClose: () => void }) {
+  return (
+    <Modal onClose={onClose} title="Withdrawal dialog">
+      <h2>Modal Title</h2>
+      <p>This is the modal content. You can put any content here.</p>
+      <Button onPress={onClose}>Close</Button>
+    </Modal>
+  );
+}
+
+function App() {
+  const [openModal, closeModal] = useModal(() => (
+    <ModalContent onClose={closeModal} />
+  ));
+
+  return <Button onPress={openModal}>Open Modal</Button>;
+}
+
+export default function Example() {
+  return (
+    <ModalProvider>
+      <App />
+    </ModalProvider>
+  );
+}
+```
+
+### Modal Types
+
+Each type controls how the dialog is positioned and styled:
+
+```tsx
+import { Modal, useModal } from '@xsolla/xui-modal';
+import { Button } from '@xsolla/xui-button';
+
+function ModalTypesDemo() {
+  const [openPopup, closePopup] = useModal(() => (
+    <Modal type="popup" onClose={closePopup} title="Popup">
+      <p>Centered with border-radius and shadow. Max-width constrained (680px default).</p>
+    </Modal>
+  ));
+
+  const [openSheet, closeSheet] = useModal(() => (
+    <Modal type="bottom-sheet" onClose={closeSheet} title="Bottom Sheet">
+      <p>Anchored to the bottom. Full width with rounded top corners only.</p>
+    </Modal>
+  ));
+
+  const [openFull, closeFull] = useModal(() => (
+    <Modal type="full-screen" onClose={closeFull} title="Full Screen">
+      <p>Fills the entire viewport. No border-radius, no shadow.</p>
+    </Modal>
+  ));
+
+  return (
+    <div style={{ display: 'flex', gap: 12 }}>
+      <Button onPress={openPopup}>Popup</Button>
+      <Button onPress={openSheet}>Bottom Sheet</Button>
+      <Button onPress={openFull}>Full Screen</Button>
+    </div>
+  );
+}
+```
+
+### Back and Close Buttons
+
+The header renders automatically when `onBack` or `onClose` are provided. `onBack` places a ChevronLeft button on the left; `onClose` places an X button on the right:
+
+```tsx
+import { Modal, useModal } from '@xsolla/xui-modal';
+import { Button } from '@xsolla/xui-button';
+
+function BackAndCloseDemo() {
+  const [open, close] = useModal(() => (
+    <Modal
+      onBack={() => console.log('Back pressed')}
+      onClose={close}
+      title="Dialog with navigation"
+    >
+      <p>This modal has both back and close buttons.</p>
+    </Modal>
+  ));
+
+  return <Button onPress={open}>Open</Button>;
+}
+```
+
+### Content Alignment
+
+Control whether content is left-aligned (default) or centered:
+
+```tsx
+<Modal align="center" onClose={close} title="Centered content">
+  <h2>Welcome</h2>
+  <p>This text is centered within the modal.</p>
+</Modal>
+```
+
+### Custom Header
+
+Pass a `header` prop to replace the default back/close button row entirely:
+
+```tsx
+import { FlexButton } from '@xsolla/xui-button';
+
+<Modal
+  header={
+    <div style={{ display: 'flex', justifyContent: 'space-between', width: '100%' }}>
+      <span>Custom Header</span>
+      <FlexButton variant="brand" size="xs">Done</FlexButton>
+    </div>
+  }
+  title="Custom header modal"
+>
+  <p>Content below the custom header.</p>
+</Modal>
+```
+
+### Footer
+
+Pass a `footer` prop to render action buttons or other content below the body:
+
+```tsx
+import { Button, ButtonGroup } from '@xsolla/xui-button';
+
+<Modal onClose={close} onBack={close} footer={
+  <ButtonGroup orientation="horizontal" size="xl">
+    <Button variant="secondary" tone="mono" onPress={close}>Cancel</Button>
+    <Button variant="primary" tone="brand" onPress={handleConfirm}>Confirm</Button>
+  </ButtonGroup>
+} title="Confirmation">
+  <p>Do you want to save your changes?</p>
+</Modal>
+```
+
+### Open Content (Edge-to-Edge)
+
+Set `openContent` to remove inner padding so children fill the modal edge-to-edge. Useful for images, maps, or custom backgrounds:
+
+```tsx
+<Modal openContent onClose={close} title="Gallery">
+  <img
+    src="/hero-image.jpg"
+    alt="Hero"
+    style={{ width: '100%', display: 'block' }}
+  />
+</Modal>
+```
+
+### Custom Width
+
+```tsx
+<Modal onClose={close} maxWidth={900} title="Wide modal">
+  <p>This modal has a custom max width of 900px.</p>
+</Modal>
+```
+
+### Prevent Close on Outside Click
+
+```tsx
+<Modal onClose={close} closeOutside={false} title="Required action">
+  <p>You must click a button to close this modal. Clicking outside will not dismiss it.</p>
+  <Button onPress={close}>Confirm and Close</Button>
+</Modal>
+```
+
+### Confirmation Dialog
+
+```tsx
+import { Modal, useModal } from '@xsolla/xui-modal';
+import { Button, ButtonGroup } from '@xsolla/xui-button';
+
+function DeleteConfirmation() {
+  const [open, close] = useModal(() => (
+    <Modal
+      onClose={close}
+      closeOutside={false}
+      maxWidth={400}
+      title="Delete Item?"
+      footer={
+        <ButtonGroup orientation="horizontal" size="xl">
+          <Button variant="secondary" tone="mono" onPress={close}>Cancel</Button>
+          <Button tone="alert" onPress={() => { deleteItem(); close(); }}>Delete</Button>
+        </ButtonGroup>
+      }
+    >
+      <p>This action cannot be undone. Are you sure you want to delete this item?</p>
+    </Modal>
+  ));
+
+  return <Button tone="alert" onPress={open}>Delete Item</Button>;
+}
+```
+
+### Form Modal
+
+```tsx
+import { Modal, useModal } from '@xsolla/xui-modal';
+import { Button, ButtonGroup } from '@xsolla/xui-button';
+import { Input } from '@xsolla/xui-input';
+
+function CreateUserModal() {
+  const [open, close] = useModal(() => (
+    <Modal
+      onClose={close}
+      closeOutside={false}
+      maxWidth={500}
+      title="Create User"
+      footer={
+        <ButtonGroup orientation="horizontal" size="xl">
+          <Button variant="secondary" onPress={close}>Cancel</Button>
+          <Button variant="primary" tone="brand" onPress={handleSubmit}>Create</Button>
+        </ButtonGroup>
+      }
+    >
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+        <Input label="Name" placeholder="Enter name" />
+        <Input label="Email" placeholder="Enter email" />
+      </div>
+    </Modal>
+  ));
+
+  return <Button onPress={open}>Add User</Button>;
+}
+```
+
+### Multi-Step Modal
+
+Use `onBack` to navigate between steps within a single modal:
+
+```tsx
+import { Modal, useModal } from '@xsolla/xui-modal';
+import { Button } from '@xsolla/xui-button';
+import { useState } from 'react';
+
+function MultiStepContent({ onClose }: { onClose: () => void }) {
+  const [step, setStep] = useState(1);
+
+  return (
+    <Modal
+      onClose={onClose}
+      onBack={step > 1 ? () => setStep((s) => s - 1) : undefined}
+      title={`Step ${step} of 3`}
+    >
+      <p>Content for step {step}</p>
+      {step < 3 ? (
+        <Button onPress={() => setStep((s) => s + 1)}>Next</Button>
+      ) : (
+        <Button onPress={onClose}>Finish</Button>
+      )}
+    </Modal>
+  );
+}
+```
+
+### Multiple Modals
+
+Each `useModal` call manages an independent modal. Only the most recently opened modal is visible (stack behavior):
+
+```tsx
+function App() {
+  const [openFirst, closeFirst] = useModal(() => (
+    <Modal onClose={closeFirst} maxWidth={400} title="First Modal">
+      <p>This is the first modal.</p>
+    </Modal>
+  ));
+
+  const [openSecond, closeSecond] = useModal(() => (
+    <Modal onClose={closeSecond} maxWidth={400} title="Second Modal">
+      <p>This is the second modal.</p>
+    </Modal>
+  ));
+
+  return (
+    <div style={{ display: 'flex', gap: 16 }}>
+      <Button onPress={openFirst}>Open Modal 1</Button>
+      <Button onPress={openSecond}>Open Modal 2</Button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ModalProvider
+
+The root provider component that manages modal state and renders `ModalRoot`.
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| `children` | `ReactNode` | — | Application content (required). |
+
+### useModal
+
+A hook that returns `[open, close]` functions for a single modal. Must be called within a `ModalProvider`.
+
+**Signature:**
+
+```typescript
+function useModal(
+  modal: (props: any) => ReactNode
+): [() => void, () => void]
+```
+
+| Parameter | Type | Description |
+| :-------- | :--- | :---------- |
+| `modal` | `(props: any) => ReactNode` | Render function that returns the modal content (typically a `<Modal>` component). |
+
+**Returns:**
+
+| Index | Type | Description |
+| :---- | :--- | :---------- |
+| `[0]` | `() => void` | `open` — Opens the modal. |
+| `[1]` | `() => void` | `close` — Closes the modal. |
+
+The hook generates a stable random key per component instance and keeps a ref to the latest render function, so the render function always uses current closure values without needing a dependency array.
+
+### Modal
+
+The dialog component with built-in header, body, and footer zones. Accepts a `ref` that is forwarded to the inner `WorkArea`.
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| `children` | `ReactNode` | — | Modal body content (required). |
+| `type` | `"popup" \| "bottom-sheet" \| "full-screen"` | `"popup"` | Modal presentation type. Controls positioning, border-radius, and shadow. |
+| `align` | `"left" \| "center"` | `"left"` | Content alignment within the modal body. |
+| `onClose` | `() => void` | — | Close callback. When provided, renders a close (X) `FlexButton` in the header and enables Escape key and click-outside dismissal. |
+| `onBack` | `() => void` | — | Back callback. When provided, renders a back (ChevronLeft) `FlexButton` in the header. |
+| `header` | `ReactNode` | — | Custom header content that replaces the default back/close button row entirely. |
+| `footer` | `ReactNode` | — | Footer content rendered below children (e.g. `ButtonGroup`). |
+| `openContent` | `boolean` | `false` | Removes inner padding so children fill the modal edge-to-edge. |
+| `closeOutside` | `boolean` | `true` | Whether clicking outside the modal closes it (requires `onClose`). |
+| `maxWidth` | `string \| number` | `680` | Maximum width. Ignored for `bottom-sheet` and `full-screen` types (forced to `100%`). |
+| `minHeight` | `string \| number` | — | Minimum height of the modal. |
+| `styled` | `CSSProperties` | — | Additional CSS styles applied to the modal container. |
+| `title` | `string` | — | Accessible title — creates a visually hidden element with `aria-labelledby`. |
+| `aria-label` | `string` | — | Alternative accessible name when `title` is not used. |
+| `aria-describedby` | `string` | — | ID of element describing the modal content. |
+| `initialFocusRef` | `RefObject<HTMLElement>` | — | Ref to the element that should receive focus when the modal opens. Defaults to the close button, then the first focusable element. |
+| `size` | `"sm" \| "md" \| "lg"` | — | Size hint (passed through to the root `Box` via rest props). |
+
+### Modal Types
+
+| Type | Positioning | Border Radius | Shadow | Max Width |
+| :--- | :---------- | :------------ | :----- | :-------- |
+| `popup` (default) | Centered in viewport overlay | `12px` all corners | Dual-layer box shadow | `680px` (or custom) |
+| `bottom-sheet` | Fixed to bottom of viewport | `12px` top corners only | Dual-layer box shadow | `100%` (forced) |
+| `full-screen` | Fixed, fills entire viewport | `0` | None | `100%` (forced) |
+
+### WorkArea
+
+Internal chrome component used by `Modal`. Can be used standalone for custom modal layouts.
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| `children` | `ReactNode` | — | Content to display (required). |
+| `type` | `"popup" \| "bottom-sheet" \| "full-screen"` | `"popup"` | Affects border-radius and shadow. |
+| `align` | `"left" \| "center"` | — | Content alignment. |
+| `stretched` | `boolean` | `false` | Whether to stretch to full height. |
+| `fetching` | `boolean` | `false` | Shows a loading indicator when `true`. |
+
+### ModalContext
+
+The React context object. Typically consumed via `useModal`, but available for advanced use cases:
+
+```tsx
+import { useContext } from 'react';
+import { ModalContext } from '@xsolla/xui-modal';
+
+function CustomModalTrigger() {
+  const { onOpenModal, onCloseModal } = useContext(ModalContext);
+  const key = 'my-custom-modal';
+
+  const open = () => onOpenModal(key, () => (
+    <Modal onClose={() => onCloseModal(key)}>
+      <p>Custom modal</p>
+    </Modal>
+  ));
+
+  return <button onClick={open}>Open</button>;
+}
+```
+
+### Exported Types
+
+| Type | Description |
+| :--- | :---------- |
+| `ModalProps` | Props for the `Modal` component. |
+| `ModalSize` | `"sm" \| "md" \| "lg"` |
+| `ModalVariant` | `"popup" \| "bottom-sheet" \| "full-screen"` |
+| `ModalType` | `(props: any) => ReactNode` — the render function signature. |
+| `ModalContextType` | `{ onOpenModal, onCloseModal }` context shape. |
+| `ModalProviderProps` | Props for `ModalProvider`. |
+| `ModalRootProps` | Props for `ModalRoot` (internal). |
+| `WorkAreaProps` | Props for `WorkArea`. |
+| `WorkAreaSize` | `"sm" \| "md" \| "lg"` |
+
+## Theming
+
+Modal uses the design system theme for all visual properties.
+
+### Colors
+
+```typescript
+theme.colors.background.primary  // Modal background
+theme.colors.content.primary     // Modal text and icon color
+```
+
+The overlay backdrop uses `rgba(0, 0, 0, 0.5)`.
+
+### Sizing
+
+Modal dimensions come from `theme.sizing.modal()`:
+
+| Token | Value | Description |
+| :---- | :---- | :---------- |
+| `borderRadius` | `12` | Corner radius (0 for full-screen, top-only for bottom-sheet) |
+| `headerPadding` | `8` | Padding around the header row |
+| `contentPadding` | `40` | Padding around the body and footer (0 when `openContent`) |
+| `headerButtonSize` | `"xl"` | Size passed to back/close `FlexButton` components |
+| `headerGap` | `8` | Gap between header elements |
+| `shadow` | `"0px 8px 12px 6px rgba(7,7,8,0.1), 0px 4px 4px rgba(7,7,8,0.2)"` | Box shadow (none for full-screen) |
+| `maxWidth` | `680` | Default maximum width for popup type |
+| `overlayColor` | `"rgba(0, 0, 0, 0.5)"` | Backdrop overlay color |
+| `portalPadding` | `20` | Padding between the portal container and viewport edges |
+| `zIndex` | `1000` | z-index of the portal overlay |
+
+## Platform Support
+
+This package supports both React (web) and React Native with an identical component API.
+
+### React (Web)
+
+- `ModalRoot` uses `ReactDOM.createPortal` to render into `document.body`
+- The overlay is fixed-positioned with `z-index: 1000`, covering the entire viewport
+- Escape key closes the modal, click-outside dismissal is supported
+- Focus is trapped within the modal dialog
+- Works with any React web framework (Next.js, Vite, Create React App, Remix, etc.)
+
+### React Native
+
+- `ModalRoot` is a no-op stub — the provider-based modal stack does not render on native
+- The `Modal` component itself can be rendered directly (without the provider flow) for static display
+- Uses `@xsolla/xui-primitives-native` primitives resolved at build time via `tsup`
+- Full interactive modal support on native requires wrapping with a native modal solution
+
+### Cross-Platform Comparison
+
+| Feature | Web | React Native |
+| :------ | :-- | :----------- |
+| Provider setup | `ModalProvider` | `ModalProvider` (root renders nothing) |
+| Hook API | `useModal()` → `[open, close]` | Same signature (but root is no-op) |
+| Portal | `ReactDOM.createPortal` into `document.body` | No portal (stub) |
+| Overlay | Fixed-positioned dark backdrop | N/A |
+| Focus trapping | Keyboard Tab trapping | N/A |
+| Escape key | Closes modal | N/A |
+| Click outside | Dismisses when `closeOutside={true}` | N/A |
+
+## Keyboard Interaction
+
+| Key | Action |
+| :-- | :----- |
+| `Escape` | Closes the modal (when `onClose` is provided) |
+| `Tab` | Moves focus to next focusable element within the modal (trapped) |
+| `Shift + Tab` | Moves focus to previous focusable element (trapped) |
+| `Enter` | Activates the focused button |
+
+## Accessibility
+
+- Modal renders with `role="dialog"` and `aria-modal="true"`
+- When `title` is provided, a visually hidden element is created with `aria-labelledby`
+- When `title` is not provided, `aria-label` is used as the accessible name
+- Focus is trapped within the modal — Tab and Shift+Tab cycle through focusable elements
+- On open, focus moves to `initialFocusRef`, the close button, or the first focusable element
+- On close, focus returns to the element that was focused before the modal opened
+- The close button has `aria-label="Close modal"` and the back button has `aria-label="Go back"`
+- The overlay backdrop has `aria-hidden="true"`
+- `data-modal-id` attribute enables click-outside detection to ignore portaled content belonging to the modal
+
+## Troubleshooting
+
+### "useModal must be used within a ModalProvider"
+
+The `useModal` hook (or direct `ModalContext` access) was called outside a `ModalProvider`. Ensure your component tree has a `ModalProvider` ancestor:
+
+```tsx
+// Correct — hook is inside the provider tree
+<ModalProvider>
+  <ComponentThatCallsUseModal />
+</ModalProvider>
+
+// Wrong — hook is outside the provider
+<ComponentThatCallsUseModal />
+<ModalProvider>
+  <OtherContent />
+</ModalProvider>
+```
+
+### Modal appears behind other content
+
+`ModalRoot` uses `z-index: 1000` via portal into `document.body`. If your content uses a higher z-index, the modal may be hidden. Ensure `ModalProvider` is placed high in the component tree. Toast notifications use `z-index: 9999` and will appear above modals by default.
+
+### Click-outside not working for portaled dropdowns
+
+If your modal contains components that render into portals (like `Select` or `Dropdown`), those portaled elements are outside the modal DOM tree. The modal uses `data-modal-id` to detect these cases — ensure portaled content inside the modal uses `useModalId` from `@xsolla/xui-core` and sets `data-modal-id` on its root element.
+
+### Bottom-sheet or full-screen modal not filling width
+
+`maxWidth` is forced to `100%` for `bottom-sheet` and `full-screen` types. If you're seeing constrained width, ensure no parent container is restricting width.
+
+### Focus not returning after close
+
+The modal saves `document.activeElement` on mount and restores focus on unmount. If the trigger element is removed from the DOM between open and close, focus cannot be restored. Ensure the trigger element persists in the DOM while the modal is open.

package/package.json

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