@xsolla/xui-b2c-popover 0.209.0

package/README.md

@@ -0,0 +1,22 @@
+# @xsolla/xui-b2c-popover
+
+Responsive overlay panel for player-facing surfaces — a 400px floating panel on
+desktop and tablet, a full-screen page on mobile, optionally draggable and
+pinnable. The container behind the Xsolla ID profile popover.
+
+```bash
+yarn add @xsolla/xui-b2c-popover
+```
+
+```tsx
+import { Popover, usePopover } from "@xsolla/xui-b2c-popover";
+
+const { isOpen, open, close } = usePopover();
+
+<Popover open={isOpen} onClose={close} title="Profile">
+  {sections}
+</Popover>;
+```
+
+Full API, device buckets, layout slots, drag/pin behaviour, and accessibility
+notes: [docs/api/components/b2c-popover.md](../../../docs/api/components/b2c-popover.md).

package/native/index.d.mts

@@ -0,0 +1,255 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, RefObject, PointerEvent, KeyboardEvent } from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Device buckets from the Figma "Breakpoints" frame
+ * (file `SOOtaT80JAVJf7PKlFnt7Q`, node `6393:1137`):
+ *
+ * | Device  | Viewport      | Presentation                    |
+ * | ------- | ------------- | ------------------------------- |
+ * | Desktop | 1024px and up | 400px floating panel            |
+ * | Tablet  | 769–1023px    | 400px floating panel            |
+ * | Mobile  | 320–768px     | full-screen, reads as a page    |
+ *
+ * Mirrors the `Device` variant on the Figma `idPopover` component set
+ * (node `7394:4832`), whose options are Desktop (default), Tablet, Mobile.
+ */
+type PopoverDevice = "desktop" | "tablet" | "mobile";
+/** Viewport-relative offset of the floating panel's top-left corner. */
+interface PopoverPosition {
+    x: number;
+    y: number;
+}
+/** Handlers that turn an element into a drag grip for the floating panel. */
+interface PopoverDragHandleProps {
+    onPointerDown: (event: PointerEvent) => void;
+    onKeyDown: (event: KeyboardEvent) => void;
+}
+interface PopoverProps extends ThemeOverrideProps {
+    /** Whether the popover is open. */
+    open?: boolean;
+    /** Called when the popover should close (Escape, scrim press, close button). */
+    onClose?: () => void;
+    /**
+     * Forces a device bucket instead of measuring the viewport. Useful for
+     * Storybook, tests, and product shells that already know their layout.
+     * Omit it and `useDeviceType` resolves the bucket from `window.innerWidth`.
+     */
+    device?: PopoverDevice;
+    /**
+     * Panel width on `desktop` / `tablet`. Ignored on `mobile`, which fills the
+     * viewport.
+     * @default 400
+     */
+    width?: number | string;
+    /**
+     * Renders the grab handle in the title bar and lets the user reposition the
+     * panel. Ignored on `mobile` — per the Figma spec, "Buttons for floating […]
+     * Don't use it in other cases and on mobile."
+     * @default false
+     */
+    draggable?: boolean;
+    /**
+     * Starting viewport offset for a `draggable` panel. Omit to let the panel
+     * centre itself until the first drag.
+     */
+    initialPosition?: PopoverPosition;
+    /** Called on every drag frame with the panel's new viewport offset. */
+    onPositionChange?: (position: PopoverPosition) => void;
+    /** Title shown in the default title bar, to the right of the grab handle. */
+    title?: ReactNode;
+    /**
+     * Whether the popover is pinned. Pinning shows the pin control in its active
+     * state and suppresses scrim dismissal. Controlled — the control only renders
+     * when `onPinnedChange` is supplied.
+     */
+    pinned?: boolean;
+    /** Called with the next pinned state when the pin control is pressed. */
+    onPinnedChange?: (pinned: boolean) => void;
+    /**
+     * Renders the close (X) control in the default title bar. Set it to `false`
+     * for the Figma "No buttons" variant, which has no chrome at all — `onClose`
+     * still runs on Escape and on a scrim press, so the popover stays
+     * dismissible.
+     * @default true
+     */
+    showCloseButton?: boolean;
+    /**
+     * Replaces the whole default title bar (grab handle, title, pin, close).
+     * You own the grab handle in this case — put `data-xui-popover-drag-handle`
+     * on the element that should accept arrow-key nudges.
+     */
+    titleBar?: ReactNode;
+    /**
+     * Content pinned above the scrollable body — the logo row, hero image, and
+     * greeting in the Xsolla ID profile popover.
+     */
+    header?: ReactNode;
+    /** Scrollable body content. */
+    children: ReactNode;
+    /** Content pinned below the scrollable body — sign-out button, legal links. */
+    footer?: ReactNode;
+    /**
+     * Whether pressing the scrim closes the popover. Always disabled while
+     * `pinned`, and on `mobile`, where a full-screen page has no outside.
+     * @default true
+     */
+    closeOnOverlayClick?: boolean;
+    /** Whether pressing Escape closes the popover. @default true */
+    closeOnEscape?: boolean;
+    /**
+     * Renders the dimming scrim behind the panel. Turn it off for a floating
+     * panel that should leave the page underneath usable — that is the
+     * "Float buttons for desktop" case in the Figma spec.
+     * @default true
+     */
+    scrim?: boolean;
+    /**
+     * Surface background. Accepts any theme background token or a CSS colour.
+     * @default theme.colors.background.primary
+     */
+    backgroundColor?: string;
+    /**
+     * Applies the 24px backdrop blur from the Figma `boxShadow&BlurPopover`
+     * effect style. Ignored on `mobile`.
+     * @default true
+     */
+    blur?: boolean;
+    /** Extra styles merged onto the panel. */
+    styled?: CSSProperties;
+    /** Element focused when the popover opens. Defaults to the first focusable. */
+    initialFocusRef?: RefObject<HTMLElement>;
+    /** Accessible name for the dialog. Falls back to a string `title`. */
+    "aria-label"?: string;
+    testID?: string;
+}
+interface PopoverRootProps {
+    children: ReactNode;
+    /** Whether the popover is logically open — `false` runs the exit animation. */
+    open: boolean;
+    /** Called once the exit animation has finished so the parent can unmount. */
+    onExited: () => void;
+    /** Press handler for the scrim. Omit to make the scrim inert. */
+    onBackdropClick?: () => void;
+    /** Scrim colour, or `undefined` to render no scrim at all. */
+    scrimColor?: string;
+    /** Full-bleed layout for the `mobile` variant. */
+    fullScreen: boolean;
+    /** Absolute viewport offset — set once a draggable panel has been moved. */
+    position?: PopoverPosition;
+    animationDuration: number;
+    testID?: string;
+}
+interface PopoverTitleBarProps {
+    title?: ReactNode;
+    /** Renders the grab handle and wires it to `dragHandleProps`. */
+    draggable: boolean;
+    dragHandleProps?: PopoverDragHandleProps;
+    pinned?: boolean;
+    onPinnedChange?: (pinned: boolean) => void;
+    onClose?: () => void;
+    testID?: string;
+}
+
+/**
+ * Responsive overlay panel for player-facing surfaces — the container behind
+ * the Xsolla ID profile popover.
+ *
+ * On `desktop` and `tablet` it presents as a 400px floating panel over a
+ * scrim, optionally draggable by its title bar. On `mobile` the same content
+ * takes over the whole screen as a page. The bucket is measured from the
+ * viewport by `useDeviceType`; pass `device` only to override that.
+ *
+ * Everything inside is a slot — `titleBar`, `header`, `children`, `footer` —
+ * which is how the Figma `idPopover` composes its variants (the component set
+ * declares one property, `Device`; every other difference between the usage
+ * examples is different content in the same slots).
+ *
+ * ```tsx
+ * <Popover
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   title="Profile"
+ *   header={<Greeting />}
+ *   footer={<SignOut />}
+ * >
+ *   {sections}
+ * </Popover>
+ * ```
+ */
+declare const Popover: react.ForwardRefExoticComponent<PopoverProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * The floating title row from the Figma `idPopover` spec: grab handle, title,
+ * pin toggle, close button.
+ *
+ * `dragHandleProps` is attached to the whole row rather than just the grip, so
+ * the title text is draggable too. Presses that originate inside a `<button>`
+ * (pin, close) are filtered out by `usePopoverDrag`, and the grip stays
+ * focusable so the row can also be moved with the arrow keys.
+ */
+declare const PopoverTitleBar: react.MemoExoticComponent<({ title, draggable, dragHandleProps, pinned, onPinnedChange, onClose, testID, }: PopoverTitleBarProps) => react_jsx_runtime.JSX.Element>;
+
+interface UsePopoverOptions {
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+interface UsePopoverReturn {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+}
+/** Open/close state for a `Popover`, mirroring `useDrawer`. */
+declare function usePopover(options?: UsePopoverOptions): UsePopoverReturn;
+
+interface UsePopoverDragOptions {
+    /** Drag is a no-op while this is false (mobile, or `draggable={false}`). */
+    enabled: boolean;
+    /** Starting viewport offset. `undefined` leaves the panel centred. */
+    initialPosition?: PopoverPosition;
+    onPositionChange?: (position: PopoverPosition) => void;
+}
+interface UsePopoverDragReturn {
+    /** `undefined` until the panel has been positioned, so it stays centred. */
+    position?: PopoverPosition;
+    /** Attach to the panel so the hook can measure it for clamping. */
+    panelRef: RefObject<HTMLDivElement>;
+    /** Spread onto the element that starts a drag. */
+    dragHandleProps: PopoverDragHandleProps;
+    isDragging: boolean;
+}
+/**
+ * Pointer- and keyboard-driven repositioning for a floating popover panel.
+ *
+ * The panel stays in its centred flow position until the first drag, at which
+ * point the hook switches it to an absolute viewport offset. Positions are
+ * always clamped so at least `EDGE_MARGIN` of the panel stays on screen.
+ */
+declare const usePopoverDrag: ({ enabled, initialPosition, onPositionChange, }: UsePopoverDragOptions) => UsePopoverDragReturn;
+
+/**
+ * Viewport thresholds from the Figma "Breakpoints" frame
+ * (file `SOOtaT80JAVJf7PKlFnt7Q`, node `6393:1137`).
+ */
+declare const POPOVER_BREAKPOINTS: {
+    /** Widths at or below this are `mobile` (Figma: "Mobile: 320-768px"). */
+    readonly mobileMax: 768;
+    /** Widths at or below this, but above `mobileMax`, are `tablet` (Figma: "Tablet: 769-1023px"). */
+    readonly tabletMax: 1023;
+};
+/** Maps a viewport width in CSS pixels onto a {@link PopoverDevice} bucket. */
+declare const resolveDevice: (width: number) => PopoverDevice;
+/**
+ * Resolves the active device bucket from the viewport width, re-resolving on
+ * resize. Pass `override` to short-circuit measurement entirely — the override
+ * is returned verbatim and no listener is attached.
+ *
+ * Server-side (no `window`) the hook reports `desktop`, which matches the
+ * Figma default variant, and corrects itself on the first client effect.
+ */
+declare const useDeviceType: (override?: PopoverDevice) => PopoverDevice;
+
+export { POPOVER_BREAKPOINTS, Popover, type PopoverDevice, type PopoverDragHandleProps, type PopoverPosition, type PopoverProps, type PopoverRootProps, PopoverTitleBar, type PopoverTitleBarProps, type UsePopoverDragOptions, type UsePopoverDragReturn, type UsePopoverOptions, type UsePopoverReturn, resolveDevice, useDeviceType, usePopover, usePopoverDrag };

package/native/index.d.ts

@@ -0,0 +1,255 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, RefObject, PointerEvent, KeyboardEvent } from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Device buckets from the Figma "Breakpoints" frame
+ * (file `SOOtaT80JAVJf7PKlFnt7Q`, node `6393:1137`):
+ *
+ * | Device  | Viewport      | Presentation                    |
+ * | ------- | ------------- | ------------------------------- |
+ * | Desktop | 1024px and up | 400px floating panel            |
+ * | Tablet  | 769–1023px    | 400px floating panel            |
+ * | Mobile  | 320–768px     | full-screen, reads as a page    |
+ *
+ * Mirrors the `Device` variant on the Figma `idPopover` component set
+ * (node `7394:4832`), whose options are Desktop (default), Tablet, Mobile.
+ */
+type PopoverDevice = "desktop" | "tablet" | "mobile";
+/** Viewport-relative offset of the floating panel's top-left corner. */
+interface PopoverPosition {
+    x: number;
+    y: number;
+}
+/** Handlers that turn an element into a drag grip for the floating panel. */
+interface PopoverDragHandleProps {
+    onPointerDown: (event: PointerEvent) => void;
+    onKeyDown: (event: KeyboardEvent) => void;
+}
+interface PopoverProps extends ThemeOverrideProps {
+    /** Whether the popover is open. */
+    open?: boolean;
+    /** Called when the popover should close (Escape, scrim press, close button). */
+    onClose?: () => void;
+    /**
+     * Forces a device bucket instead of measuring the viewport. Useful for
+     * Storybook, tests, and product shells that already know their layout.
+     * Omit it and `useDeviceType` resolves the bucket from `window.innerWidth`.
+     */
+    device?: PopoverDevice;
+    /**
+     * Panel width on `desktop` / `tablet`. Ignored on `mobile`, which fills the
+     * viewport.
+     * @default 400
+     */
+    width?: number | string;
+    /**
+     * Renders the grab handle in the title bar and lets the user reposition the
+     * panel. Ignored on `mobile` — per the Figma spec, "Buttons for floating […]
+     * Don't use it in other cases and on mobile."
+     * @default false
+     */
+    draggable?: boolean;
+    /**
+     * Starting viewport offset for a `draggable` panel. Omit to let the panel
+     * centre itself until the first drag.
+     */
+    initialPosition?: PopoverPosition;
+    /** Called on every drag frame with the panel's new viewport offset. */
+    onPositionChange?: (position: PopoverPosition) => void;
+    /** Title shown in the default title bar, to the right of the grab handle. */
+    title?: ReactNode;
+    /**
+     * Whether the popover is pinned. Pinning shows the pin control in its active
+     * state and suppresses scrim dismissal. Controlled — the control only renders
+     * when `onPinnedChange` is supplied.
+     */
+    pinned?: boolean;
+    /** Called with the next pinned state when the pin control is pressed. */
+    onPinnedChange?: (pinned: boolean) => void;
+    /**
+     * Renders the close (X) control in the default title bar. Set it to `false`
+     * for the Figma "No buttons" variant, which has no chrome at all — `onClose`
+     * still runs on Escape and on a scrim press, so the popover stays
+     * dismissible.
+     * @default true
+     */
+    showCloseButton?: boolean;
+    /**
+     * Replaces the whole default title bar (grab handle, title, pin, close).
+     * You own the grab handle in this case — put `data-xui-popover-drag-handle`
+     * on the element that should accept arrow-key nudges.
+     */
+    titleBar?: ReactNode;
+    /**
+     * Content pinned above the scrollable body — the logo row, hero image, and
+     * greeting in the Xsolla ID profile popover.
+     */
+    header?: ReactNode;
+    /** Scrollable body content. */
+    children: ReactNode;
+    /** Content pinned below the scrollable body — sign-out button, legal links. */
+    footer?: ReactNode;
+    /**
+     * Whether pressing the scrim closes the popover. Always disabled while
+     * `pinned`, and on `mobile`, where a full-screen page has no outside.
+     * @default true
+     */
+    closeOnOverlayClick?: boolean;
+    /** Whether pressing Escape closes the popover. @default true */
+    closeOnEscape?: boolean;
+    /**
+     * Renders the dimming scrim behind the panel. Turn it off for a floating
+     * panel that should leave the page underneath usable — that is the
+     * "Float buttons for desktop" case in the Figma spec.
+     * @default true
+     */
+    scrim?: boolean;
+    /**
+     * Surface background. Accepts any theme background token or a CSS colour.
+     * @default theme.colors.background.primary
+     */
+    backgroundColor?: string;
+    /**
+     * Applies the 24px backdrop blur from the Figma `boxShadow&BlurPopover`
+     * effect style. Ignored on `mobile`.
+     * @default true
+     */
+    blur?: boolean;
+    /** Extra styles merged onto the panel. */
+    styled?: CSSProperties;
+    /** Element focused when the popover opens. Defaults to the first focusable. */
+    initialFocusRef?: RefObject<HTMLElement>;
+    /** Accessible name for the dialog. Falls back to a string `title`. */
+    "aria-label"?: string;
+    testID?: string;
+}
+interface PopoverRootProps {
+    children: ReactNode;
+    /** Whether the popover is logically open — `false` runs the exit animation. */
+    open: boolean;
+    /** Called once the exit animation has finished so the parent can unmount. */
+    onExited: () => void;
+    /** Press handler for the scrim. Omit to make the scrim inert. */
+    onBackdropClick?: () => void;
+    /** Scrim colour, or `undefined` to render no scrim at all. */
+    scrimColor?: string;
+    /** Full-bleed layout for the `mobile` variant. */
+    fullScreen: boolean;
+    /** Absolute viewport offset — set once a draggable panel has been moved. */
+    position?: PopoverPosition;
+    animationDuration: number;
+    testID?: string;
+}
+interface PopoverTitleBarProps {
+    title?: ReactNode;
+    /** Renders the grab handle and wires it to `dragHandleProps`. */
+    draggable: boolean;
+    dragHandleProps?: PopoverDragHandleProps;
+    pinned?: boolean;
+    onPinnedChange?: (pinned: boolean) => void;
+    onClose?: () => void;
+    testID?: string;
+}
+
+/**
+ * Responsive overlay panel for player-facing surfaces — the container behind
+ * the Xsolla ID profile popover.
+ *
+ * On `desktop` and `tablet` it presents as a 400px floating panel over a
+ * scrim, optionally draggable by its title bar. On `mobile` the same content
+ * takes over the whole screen as a page. The bucket is measured from the
+ * viewport by `useDeviceType`; pass `device` only to override that.
+ *
+ * Everything inside is a slot — `titleBar`, `header`, `children`, `footer` —
+ * which is how the Figma `idPopover` composes its variants (the component set
+ * declares one property, `Device`; every other difference between the usage
+ * examples is different content in the same slots).
+ *
+ * ```tsx
+ * <Popover
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   title="Profile"
+ *   header={<Greeting />}
+ *   footer={<SignOut />}
+ * >
+ *   {sections}
+ * </Popover>
+ * ```
+ */
+declare const Popover: react.ForwardRefExoticComponent<PopoverProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * The floating title row from the Figma `idPopover` spec: grab handle, title,
+ * pin toggle, close button.
+ *
+ * `dragHandleProps` is attached to the whole row rather than just the grip, so
+ * the title text is draggable too. Presses that originate inside a `<button>`
+ * (pin, close) are filtered out by `usePopoverDrag`, and the grip stays
+ * focusable so the row can also be moved with the arrow keys.
+ */
+declare const PopoverTitleBar: react.MemoExoticComponent<({ title, draggable, dragHandleProps, pinned, onPinnedChange, onClose, testID, }: PopoverTitleBarProps) => react_jsx_runtime.JSX.Element>;
+
+interface UsePopoverOptions {
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+interface UsePopoverReturn {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+}
+/** Open/close state for a `Popover`, mirroring `useDrawer`. */
+declare function usePopover(options?: UsePopoverOptions): UsePopoverReturn;
+
+interface UsePopoverDragOptions {
+    /** Drag is a no-op while this is false (mobile, or `draggable={false}`). */
+    enabled: boolean;
+    /** Starting viewport offset. `undefined` leaves the panel centred. */
+    initialPosition?: PopoverPosition;
+    onPositionChange?: (position: PopoverPosition) => void;
+}
+interface UsePopoverDragReturn {
+    /** `undefined` until the panel has been positioned, so it stays centred. */
+    position?: PopoverPosition;
+    /** Attach to the panel so the hook can measure it for clamping. */
+    panelRef: RefObject<HTMLDivElement>;
+    /** Spread onto the element that starts a drag. */
+    dragHandleProps: PopoverDragHandleProps;
+    isDragging: boolean;
+}
+/**
+ * Pointer- and keyboard-driven repositioning for a floating popover panel.
+ *
+ * The panel stays in its centred flow position until the first drag, at which
+ * point the hook switches it to an absolute viewport offset. Positions are
+ * always clamped so at least `EDGE_MARGIN` of the panel stays on screen.
+ */
+declare const usePopoverDrag: ({ enabled, initialPosition, onPositionChange, }: UsePopoverDragOptions) => UsePopoverDragReturn;
+
+/**
+ * Viewport thresholds from the Figma "Breakpoints" frame
+ * (file `SOOtaT80JAVJf7PKlFnt7Q`, node `6393:1137`).
+ */
+declare const POPOVER_BREAKPOINTS: {
+    /** Widths at or below this are `mobile` (Figma: "Mobile: 320-768px"). */
+    readonly mobileMax: 768;
+    /** Widths at or below this, but above `mobileMax`, are `tablet` (Figma: "Tablet: 769-1023px"). */
+    readonly tabletMax: 1023;
+};
+/** Maps a viewport width in CSS pixels onto a {@link PopoverDevice} bucket. */
+declare const resolveDevice: (width: number) => PopoverDevice;
+/**
+ * Resolves the active device bucket from the viewport width, re-resolving on
+ * resize. Pass `override` to short-circuit measurement entirely — the override
+ * is returned verbatim and no listener is attached.
+ *
+ * Server-side (no `window`) the hook reports `desktop`, which matches the
+ * Figma default variant, and corrects itself on the first client effect.
+ */
+declare const useDeviceType: (override?: PopoverDevice) => PopoverDevice;
+
+export { POPOVER_BREAKPOINTS, Popover, type PopoverDevice, type PopoverDragHandleProps, type PopoverPosition, type PopoverProps, type PopoverRootProps, PopoverTitleBar, type PopoverTitleBarProps, type UsePopoverDragOptions, type UsePopoverDragReturn, type UsePopoverOptions, type UsePopoverReturn, resolveDevice, useDeviceType, usePopover, usePopoverDrag };