@xsolla/xui-modal 0.150.0 → 0.151.0

package/README.md

@@ -1,599 +1,342 @@
 # 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.
+A cross-platform React modal dialog system. A provider/context/hook trio drives a stack of dialogs supporting three presentation types (`popup`, `bottom-sheet`, `full-screen`), structured headers, focus trapping, and programmatic open/close on both web and React Native.
 
 ## Installation
 
 ```bash
-npm install @xsolla/xui-modal @xsolla/xui-core
-# or
-yarn add @xsolla/xui-modal @xsolla/xui-core
+npm install @xsolla/xui-modal
 ```
 
-**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`
+## Imports
 
 ```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>;
-}
+import {
+  Modal,
+  ModalProvider,
+  ModalContext,
+  WorkArea,
+  useModal,
+  useModalId,
+  type ModalProps,
+  type ModalSize,
+  type ModalVariant,
+  type WorkAreaProps,
+  type WorkAreaSize,
+} from '@xsolla/xui-modal';
 ```
 
-## Demo
+`useModalId` is re-exported from `@xsolla/xui-core` and is consumed by portaled descendants (e.g. `Select`, `Dropdown`) so click-outside detection ignores content that logically belongs to the modal.
 
-### Basic Modal with Hook
+## Quick start
 
 ```tsx
+import * as React from 'react';
 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>
+function Trigger() {
+  const [open, close] = useModal(() => (
+    <Modal onClose={close} title="Confirm action">
+      <p>Are you sure you want to proceed?</p>
+      <Button onPress={close}>Close</Button>
     </Modal>
-  );
-}
-
-function App() {
-  const [openModal, closeModal] = useModal(() => (
-    <ModalContent onClose={closeModal} />
   ));
-
-  return <Button onPress={openModal}>Open Modal</Button>;
+  return <Button onPress={open}>Open modal</Button>;
 }
 
-export default function Example() {
+export default function QuickStart() {
   return (
     <ModalProvider>
-      <App />
+      <Trigger />
     </ModalProvider>
   );
 }
 ```
 
-### Modal Types
-
-Each type controls how the dialog is positioned and styled:
+## API Reference
 
-```tsx
-import { Modal, useModal } from '@xsolla/xui-modal';
-import { Button } from '@xsolla/xui-button';
+### `<Modal>`
 
-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>
-  ));
+The dialog component with header, body, and footer zones. Accepts a `ref` forwarded to the inner `WorkArea`. Unknown props are spread onto the root `Box`. `size` is a typed `ModalProps` field but is never consumed by `Modal`'s internal layout; it passes through via `...rest` to the root `Box` with no built-in styling effect.
 
-  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>
-  ));
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | **Required.** Modal body content. |
+| `type` | `"popup" \| "bottom-sheet" \| "full-screen"` | `"popup"` | Presentation type. Drives positioning, border-radius, and shadow. |
+| `align` | `"left" \| "center"` | `"left"` | Content alignment within the body. |
+| `onClose` | `() => void` | — | Close callback. When provided, renders a close (X) button and enables Escape and click-outside dismissal. |
+| `onBack` | `() => void` | — | Back callback. Renders a chevron-left button on the left of the header. |
+| `header` | `ReactNode` | — | Custom header — replaces the default back/close row. |
+| `footer` | `ReactNode` | — | Footer content rendered below children. |
+| `openContent` | `boolean` | `false` | Removes inner padding so children fill edge-to-edge. |
+| `closeOutside` | `boolean` | `true` | Whether clicking outside closes the modal (requires `onClose`). |
+| `maxWidth` | `string \| number` | `680` | Forced to `100%` for `bottom-sheet` and `full-screen`. |
+| `minHeight` | `string \| number` | — | Minimum height of the modal. |
+| `styled` | `CSSProperties` | — | Inline overrides on the modal container. |
+| `title` | `string` | — | Visually hidden accessible title — drives `aria-labelledby`. For a visible heading, render it inside `children` or pass a custom `header`. |
+| `aria-label` | `string` | — | Alternative accessible name when `title` is not used. |
+| `aria-describedby` | `string` | — | ID of an element describing modal content. |
+| `initialFocusRef` | `RefObject<HTMLElement>` | — | Element to focus on open. Falls back to the close button, then the first focusable child. |
 
-  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>
-  );
-}
-```
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
-### Back and Close Buttons
+### Modal types
 
-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:
+| Type | Positioning | Border radius | Shadow | Max width |
+| --- | --- | --- | --- | --- |
+| `popup` (default) | Centred in the overlay | All corners | Yes | `680px` (or custom) |
+| `bottom-sheet` | Anchored to the bottom | Top corners only | Yes | `100%` (forced) |
+| `full-screen` | Fills the viewport | `0` | None | `100%` (forced) |
 
-```tsx
-import { Modal, useModal } from '@xsolla/xui-modal';
-import { Button } from '@xsolla/xui-button';
+### `<ModalProvider>`
 
-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>
-  ));
+Wraps your app, manages the open-modal stack, and renders `ModalRoot`.
 
-  return <Button onPress={open}>Open</Button>;
-}
-```
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `ReactNode` | **Required.** Application content. |
 
-### Content Alignment
+### `<WorkArea>`
 
-Control whether content is left-aligned (default) or centered:
+Internal chrome used by `Modal`. Can be rendered standalone for custom layouts.
 
-```tsx
-<Modal align="center" onClose={close} title="Centered content">
-  <h2>Welcome</h2>
-  <p>This text is centered within the modal.</p>
-</Modal>
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | **Required.** Content. |
+| `type` | `"popup" \| "bottom-sheet" \| "full-screen"` | `"popup"` | Affects border-radius and shadow. |
+| `align` | `"left" \| "center"` | — | Content alignment. |
+| `indent` | `"sm" \| "md" \| "lg"` | — | Padding hint passed alongside the work-area sizing. |
+| `stretched` | `boolean` | `false` | Stretch to full height. |
+| `openContent` | `boolean` | `false` | Edge-to-edge mode. |
+| `fetching` | `boolean` | `false` | Renders a loading placeholder when `true`. |
 
-### Custom Header
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
-Pass a `header` prop to replace the default back/close button row entirely:
+### `useModal(renderFn)`
 
-```tsx
-import { FlexButton } from '@xsolla/xui-button';
+Returns `[open, close]` for a single modal. Must be called inside a `ModalProvider`.
 
-<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>
+```typescript
+function useModal(modal: (props: any) => ReactNode): [() => void, () => void];
 ```
 
-### Footer
-
-Pass a `footer` prop to render action buttons or other content below the body:
-
-```tsx
-import { Button, ButtonGroup } from '@xsolla/xui-button';
+The hook generates a stable random key per component instance and keeps a ref to the latest render function — your closure values stay current without a dependency array.
 
-<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>
-```
+### `useModalId()`
 
-### Open Content (Edge-to-Edge)
+Returns the current modal's `data-modal-id`. Portaled descendants should set this attribute on their root so the modal recognises them as in-tree for click-outside checks.
 
-Set `openContent` to remove inner padding so children fill the modal edge-to-edge. Useful for images, maps, or custom backgrounds:
+### `ModalContext`
 
-```tsx
-<Modal openContent onClose={close} title="Gallery">
-  <img
-    src="/hero-image.jpg"
-    alt="Hero"
-    style={{ width: '100%', display: 'block' }}
-  />
-</Modal>
-```
+The raw React context. Most apps consume `useModal`, but advanced cases can call `onOpenModal(key, renderFn)` and `onCloseModal(key)` directly.
 
-### Custom Width
+### Exported types
 
-```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
+| Type | Members |
+| --- | --- |
+| `ModalProps` | Props for `<Modal>`. |
+| `ModalSize` | `"sm" \| "md" \| "lg"` |
+| `ModalVariant` | `"popup" \| "bottom-sheet" \| "full-screen"` |
+| `ModalType` | `(props: any) => ReactNode` — the render function signature. |
+| `ModalContextType` | `{ onOpenModal, onCloseModal }` |
+| `ModalProviderProps` | Props for `<ModalProvider>`. |
+| `ModalRootProps` | Props for the internal root. |
+| `WorkAreaProps` | Props for `<WorkArea>`. |
+| `WorkAreaSize` | `"sm" \| "md" \| "lg"` |
 
-```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>
-```
+## Examples
 
-### Confirmation Dialog
+### Modal types
 
 ```tsx
-import { Modal, useModal } from '@xsolla/xui-modal';
-import { Button, ButtonGroup } from '@xsolla/xui-button';
+import * as React from 'react';
+import { Modal, ModalProvider, useModal } from '@xsolla/xui-modal';
+import { Button } 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>
+function Demo() {
+  const [openPopup, closePopup] = useModal(() => (
+    <Modal type="popup" onClose={closePopup} title="Popup">
+      <p>Centred with border-radius and shadow.</p>
+    </Modal>
+  ));
+  const [openSheet, closeSheet] = useModal(() => (
+    <Modal type="bottom-sheet" onClose={closeSheet} title="Bottom sheet">
+      <p>Anchored to the bottom.</p>
+    </Modal>
+  ));
+  const [openFull, closeFull] = useModal(() => (
+    <Modal type="full-screen" onClose={closeFull} title="Full screen">
+      <p>Fills the viewport.</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>
+  );
+}
 
-  return <Button tone="alert" onPress={open}>Delete Item</Button>;
+export default function Example() {
+  return (
+    <ModalProvider>
+      <Demo />
+    </ModalProvider>
+  );
 }
 ```
 
-### Form Modal
+### Confirmation dialog
 
 ```tsx
-import { Modal, useModal } from '@xsolla/xui-modal';
+import * as React from 'react';
+import { Modal, ModalProvider, useModal } from '@xsolla/xui-modal';
 import { Button, ButtonGroup } from '@xsolla/xui-button';
-import { Input } from '@xsolla/xui-input';
 
-function CreateUserModal() {
+function ConfirmTrigger() {
+  const [confirmed, setConfirmed] = React.useState(false);
   const [open, close] = useModal(() => (
     <Modal
       onClose={close}
       closeOutside={false}
-      maxWidth={500}
-      title="Create User"
+      maxWidth={400}
+      title="Delete item?"
       footer={
         <ButtonGroup orientation="horizontal" size="xl">
-          <Button variant="secondary" onPress={close}>Cancel</Button>
-          <Button variant="primary" tone="brand" onPress={handleSubmit}>Create</Button>
+          <Button variant="secondary" tone="mono" onPress={close}>Cancel</Button>
+          <Button tone="alert" onPress={() => { setConfirmed(true); close(); }}>Delete</Button>
         </ButtonGroup>
       }
     >
-      <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
-        <Input label="Name" placeholder="Enter name" />
-        <Input label="Email" placeholder="Enter email" />
-      </div>
+      <p>This action cannot be undone.</p>
     </Modal>
   ));
 
-  return <Button onPress={open}>Add User</Button>;
+  return (
+    <div>
+      <Button tone="alert" onPress={open}>Delete</Button>
+      {confirmed && <p>Deleted.</p>}
+    </div>
+  );
 }
-```
 
-### Multi-Step Modal
+export default function ConfirmDialog() {
+  return (
+    <ModalProvider>
+      <ConfirmTrigger />
+    </ModalProvider>
+  );
+}
+```
 
-Use `onBack` to navigate between steps within a single modal:
+### Multi-step modal
 
 ```tsx
-import { Modal, useModal } from '@xsolla/xui-modal';
+import * as React from 'react';
+import { Modal, ModalProvider, 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 (
+function MultiStep() {
+  const [step, setStep] = React.useState(1);
+  const [open, close] = useModal(() => (
     <Modal
-      onClose={onClose}
+      onClose={() => { setStep(1); close(); }}
       onBack={step > 1 ? () => setStep((s) => s - 1) : undefined}
       title={`Step ${step} of 3`}
     >
-      <p>Content for step {step}</p>
+      <p>Step {step} content.</p>
       {step < 3 ? (
         <Button onPress={() => setStep((s) => s + 1)}>Next</Button>
       ) : (
-        <Button onPress={onClose}>Finish</Button>
+        <Button onPress={() => { setStep(1); close(); }}>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 <Button onPress={open}>Open multi-step</Button>;
+}
 
+export default function MultiStepExample() {
   return (
-    <div style={{ display: 'flex', gap: 16 }}>
-      <Button onPress={openFirst}>Open Modal 1</Button>
-      <Button onPress={openSecond}>Open Modal 2</Button>
-    </div>
+    <ModalProvider>
+      <MultiStep />
+    </ModalProvider>
   );
 }
 ```
 
-## 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:
+### Edge-to-edge content
 
 ```tsx
-import { useContext } from 'react';
-import { ModalContext } from '@xsolla/xui-modal';
-
-function CustomModalTrigger() {
-  const { onOpenModal, onCloseModal } = useContext(ModalContext);
-  const key = 'my-custom-modal';
+import * as React from 'react';
+import { Modal, ModalProvider, useModal } from '@xsolla/xui-modal';
+import { Button } from '@xsolla/xui-button';
 
-  const open = () => onOpenModal(key, () => (
-    <Modal onClose={() => onCloseModal(key)}>
-      <p>Custom modal</p>
+function HeroTrigger() {
+  const [open, close] = useModal(() => (
+    <Modal openContent onClose={close} title="Gallery">
+      <img src="/hero-image.jpg" alt="Hero" style={{ width: '100%', display: 'block' }} />
     </Modal>
   ));
-
-  return <button onClick={open}>Open</button>;
+  return <Button onPress={open}>Open hero</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
+export default function EdgeToEdge() {
+  return (
+    <ModalProvider>
+      <HeroTrigger />
+    </ModalProvider>
+  );
+}
 ```
 
-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 |
+| --- | --- | --- |
+| Provider | `ModalProvider` (with `ModalRoot` portal) | `ModalProvider` (root is a no-op stub) |
+| Hook | `useModal()` → `[open, close]` | Same signature; provider stack does not render |
+| Overlay | Fixed-positioned backdrop | N/A |
+| Focus trap | 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 |
+| --- | --- |
+| `Escape` | Closes the modal (when `onClose` is provided). |
+| `Tab` | Moves focus to the next focusable element (trapped). |
+| `Shift + Tab` | Moves focus to the 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
+- Renders with `role="dialog"` and `aria-modal="true"`.
+- `title` creates a visually hidden labelled element via `aria-labelledby`; otherwise `aria-label` is used.
+- Focus is trapped within the modal; on open it moves to `initialFocusRef`, the close button, or the first focusable element. On close, focus returns to the previously active element.
+- The default close button has `aria-label="Close modal"`; the back button has `aria-label="Go back"`.
+- `data-modal-id` lets click-outside detection ignore portaled content (e.g. `Select`, `Dropdown`) 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>
-```
+`useModal` (or direct `ModalContext` access) ran outside a `ModalProvider`. Ensure your component tree has a `ModalProvider` ancestor.
 
 ### 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.
+`ModalRoot` uses `z-index: 1000` via portal into `document.body`. 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.
+Portaled descendants must set `data-modal-id` (read via `useModalId`) on their root so the modal recognises them as in-tree.
 
 ### 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.
+`maxWidth` is forced to `100%` for these types — check that 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.
+The modal saves `document.activeElement` on mount. If the trigger element is removed from the DOM while the modal is open, focus cannot be restored.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-modal",
-  "version": "0.150.0",
+  "version": "0.151.0",
   "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.150.0",
-    "@xsolla/xui-core": "0.150.0",
-    "@xsolla/xui-icons-base": "0.150.0",
-    "@xsolla/xui-primitives-core": "0.150.0"
+    "@xsolla/xui-button": "0.151.0",
+    "@xsolla/xui-core": "0.151.0",
+    "@xsolla/xui-icons-base": "0.151.0",
+    "@xsolla/xui-primitives-core": "0.151.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",