@xsolla/xui-gdpr-banner 0.206.0

package/README.md

@@ -0,0 +1,50 @@
+# @xsolla/xui-gdpr-banner
+
+The Xsolla cookie-consent (GDPR) banner. Implements the Figma `GDPR-banner`
+component set. Also re-exported from `@xsolla/xui-feedback`.
+
+Full API reference: [`docs/api/components/gdpr-banner.md`](../../../docs/api/components/gdpr-banner.md)
+
+## Installation
+
+```bash
+yarn add @xsolla/xui-gdpr-banner
+```
+
+## Usage
+
+```tsx
+import { GdprBanner } from "@xsolla/xui-gdpr-banner";
+
+<GdprBanner
+  cookiePolicyUrl="https://xsolla.com/cookie-policy"
+  privacyPolicyUrl="https://xsolla.com/privacy-policy"
+  onAcceptAll={() => consent.acceptAll()}
+  onRejectAll={() => consent.rejectAll()}
+  onConfirmSelection={(ids) => consent.save(ids)}
+  onClose={() => setVisible(false)}
+/>;
+```
+
+## Figma variant mapping
+
+| Figma variant | Prop | Values |
+| --- | --- | --- |
+| `Type` | `type` | `"complex"` (default) \| `"simple"` |
+| `Fold` | `expanded` | `false` (runtime default) \| `true` |
+| `Buttons row` | `buttonsRow` | `"single"` (default) \| `"double"` |
+| `Viewport` | `viewport` | `"desktop"` (default) \| `"mobile"` |
+
+## Layout
+
+| State | Behaviour |
+| --- | --- |
+| Desktop, collapsed | 400px card pinned to a bottom corner with a 20px inset |
+| Desktop, expanded | Full-bleed bottom bar with the two-column Privacy settings panel |
+| Mobile | Bottom-anchored, full width, stacked actions |
+
+## Accessibility
+
+`role="dialog"` labelled by the visible heading, focus pulled in on mount and on
+expand, Tab/Shift+Tab cycling inside the banner, Escape fires `onClose`, and an
+explicit `aria-label` on the close control.

package/native/index.d.mts

@@ -0,0 +1,199 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Banner density.
+ *
+ * - `complex` - full consent banner with `Customize` / `Reject All` /
+ *   `Accept All` and an expandable Privacy settings panel.
+ * - `simple` - essential-cookies-only notice with a single `Dismiss` action.
+ *
+ * Maps to the Figma `Type` variant (`Complex` | `Simple`).
+ */
+type GdprBannerType = "complex" | "simple";
+/** Layout target. Maps to the Figma `Viewport` variant. */
+type GdprBannerViewport = "desktop" | "mobile";
+/**
+ * How the action buttons wrap.
+ *
+ * - `single` - `Customize` / `Reject All` / `Accept All` on one row.
+ * - `double` - `Customize` moves onto its own row above the other two, which
+ *   keeps long translations from overflowing the card.
+ *
+ * Maps to the Figma `Buttons row` variant.
+ */
+type GdprBannerButtonsRow = "single" | "double";
+/**
+ * Which bottom corner the collapsed desktop card is pinned to. Ignored when
+ * the banner is expanded (the Privacy settings panel always spans full width)
+ * or when `viewport` is `mobile`.
+ */
+type GdprBannerAnchor = "bottom-left" | "bottom-right";
+/** A single consent category rendered inside the Privacy settings panel. */
+interface GdprCookieCategory {
+    /** Stable identifier reported through `onSelectionChange` / `onConfirmSelection`. */
+    id: string;
+    /** Visible category name. */
+    label: string;
+    /** Long-form explanation shown in the description pane when selected. */
+    description?: string;
+    /**
+     * Always-on category (e.g. essential cookies). Rendered checked and
+     * disabled, and can never be removed from the selection.
+     */
+    locked?: boolean;
+}
+/** Every user-facing string, so consumers can localize the banner. */
+interface GdprBannerLabels {
+    /** Banner heading. Default: `"How we use cookies"`. */
+    title?: string;
+    /** Body copy for `type="complex"`. */
+    description?: string;
+    /** Body copy for `type="simple"`. */
+    simpleDescription?: string;
+    /** Heading of the expanded Privacy settings panel. */
+    privacySettingsTitle?: string;
+    /** Label of the non-toggleable introductory row in the category list. */
+    generalInformation?: string;
+    /** Copy shown in the description pane while `General information` is selected. */
+    generalInformationDescription?: string;
+    customize?: string;
+    rejectAll?: string;
+    acceptAll?: string;
+    confirmSelection?: string;
+    dismiss?: string;
+    close?: string;
+    cookiePolicy?: string;
+    privacyPolicy?: string;
+    /** Accessible name of the icon-only close control. */
+    closeButtonAriaLabel?: string;
+}
+interface GdprBannerProps extends ThemeOverrideProps {
+    /** Banner density. @default "complex" */
+    type?: GdprBannerType;
+    /** Layout target. @default "desktop" */
+    viewport?: GdprBannerViewport;
+    /** Action-button wrapping. @default "single" */
+    buttonsRow?: GdprBannerButtonsRow;
+    /** Bottom corner for the collapsed desktop card. @default "bottom-left" */
+    anchor?: GdprBannerAnchor;
+    /**
+     * Whether the Privacy settings panel is open (the Figma `Fold` variant).
+     * Omit to let the banner manage the state itself; `Customize` opens it and
+     * `Close` collapses it back to the compact card.
+     *
+     * Note: the Figma component set defaults this variant to `On` for review
+     * convenience. At runtime the banner starts collapsed, which is the correct
+     * first-visit behaviour.
+     */
+    expanded?: boolean;
+    /** Initial open state when `expanded` is not supplied. @default false */
+    defaultExpanded?: boolean;
+    /** Fired whenever the panel opens or closes. */
+    onExpandedChange?: (expanded: boolean) => void;
+    /** Consent categories. Defaults to the four Xsolla categories from Figma. */
+    categories?: GdprCookieCategory[];
+    /** Controlled set of accepted category ids. */
+    selectedCategoryIds?: string[];
+    /** Initial accepted category ids when uncontrolled. Defaults to all of them. */
+    defaultSelectedCategoryIds?: string[];
+    /** Fired on every checkbox toggle with the next full selection. */
+    onSelectionChange?: (selectedCategoryIds: string[]) => void;
+    /** Overrides for any user-facing string. */
+    labels?: GdprBannerLabels;
+    /** Destination of the `Cookie Policy` footer link. */
+    cookiePolicyUrl?: string;
+    /** Destination of the `Privacy Policy` footer link. */
+    privacyPolicyUrl?: string;
+    /** `Accept All` pressed - every category consented. */
+    onAcceptAll?: () => void;
+    /** `Reject All` pressed - only locked categories remain consented. */
+    onRejectAll?: () => void;
+    /**
+     * `Customize` pressed. Fired in addition to the internal expand, so a
+     * consumer can log the interaction without taking over the state.
+     */
+    onCustomize?: () => void;
+    /** `Confirm Selection` pressed, with the accepted category ids. */
+    onConfirmSelection?: (selectedCategoryIds: string[]) => void;
+    /** `Dismiss` pressed on a `simple` banner. */
+    onDismiss?: () => void;
+    /** Close (X) pressed, or Escape. */
+    onClose?: () => void;
+    /** Render the close (X) control. @default true */
+    showCloseButton?: boolean;
+    /**
+     * `fixed` pins the banner to the bottom of the viewport (production usage).
+     * `static` renders it in normal flow, which is what stories and tests want.
+     * @default "fixed"
+     */
+    position?: "fixed" | "static";
+    /**
+     * Distance in px from the bottom / left / right edges while collapsed.
+     * Expanded panels always sit flush against the edges. @default 20
+     */
+    offset?: number;
+    testID?: string;
+}
+interface PrivacySettingsProps extends ThemeOverrideProps {
+    categories: GdprCookieCategory[];
+    selectedCategoryIds: string[];
+    onToggleCategory: (id: string) => void;
+    /** Id of the category whose description is shown, or `null` for General information. */
+    activeCategoryId: string | null;
+    onActiveCategoryChange: (id: string | null) => void;
+    viewport: GdprBannerViewport;
+    labels: Required<Pick<GdprBannerLabels, "generalInformation" | "generalInformationDescription" | "cookiePolicy" | "privacyPolicy">>;
+    cookiePolicyUrl?: string;
+    privacyPolicyUrl?: string;
+    testID?: string;
+}
+
+/**
+ * GdprBanner - the Xsolla cookie-consent banner.
+ *
+ * Implements the Figma `GDPR-banner` component set. The four Figma variant
+ * axes map to props: `Type` -> {@link GdprBannerProps.type}, `Fold` ->
+ * {@link GdprBannerProps.expanded} (inverted - Figma's `Fold=On` is the
+ * collapsed card), `Buttons row` -> {@link GdprBannerProps.buttonsRow},
+ * `Viewport` -> {@link GdprBannerProps.viewport}.
+ *
+ * ## Layout
+ *
+ * - Desktop, collapsed - a card pinned to the bottom of the viewport with a
+ *   20px inset, at either bottom corner (`anchor`).
+ * - Desktop, expanded - a wider panel hosting the two-column Privacy settings.
+ * - Mobile - always bottom-anchored and full width; actions stack.
+ *
+ * `Customize` and `Close` are borderless brand-tone text actions, matching the
+ * Figma `Flex Button` with `Background=False`.
+ *
+ * ## Accessibility
+ *
+ * - `role="dialog"` labelled by the visible heading.
+ * - Focus moves into the banner when it mounts and when the panel expands.
+ * - Tab and Shift+Tab cycle within the banner; Escape fires `onClose`.
+ * - The close control carries an explicit `aria-label`.
+ */
+declare const GdprBanner: React.FC<GdprBannerProps>;
+
+/**
+ * The expanded half of the GDPR banner: a category list on the left and the
+ * selected category's explanation on the right (stacked on mobile, where the
+ * explanation renders directly beneath the row it belongs to).
+ *
+ * Rendered by `GdprBanner` when the Privacy settings panel is open; exported
+ * so consumers can embed the same panel inside their own settings screen.
+ */
+declare const PrivacySettings: React.FC<PrivacySettingsProps>;
+
+/**
+ * The five categories shown in the Figma Privacy settings panel.
+ *
+ * `essential` is `locked`: it renders checked + disabled and is always part of
+ * the reported selection, including after `Reject All`.
+ */
+declare const DEFAULT_CATEGORIES: GdprCookieCategory[];
+declare const DEFAULT_LABELS: Required<GdprBannerLabels>;
+
+export { DEFAULT_CATEGORIES, DEFAULT_LABELS, GdprBanner, type GdprBannerAnchor, type GdprBannerButtonsRow, type GdprBannerLabels, type GdprBannerProps, type GdprBannerType, type GdprBannerViewport, type GdprCookieCategory, PrivacySettings, type PrivacySettingsProps };

package/native/index.d.ts

@@ -0,0 +1,199 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Banner density.
+ *
+ * - `complex` - full consent banner with `Customize` / `Reject All` /
+ *   `Accept All` and an expandable Privacy settings panel.
+ * - `simple` - essential-cookies-only notice with a single `Dismiss` action.
+ *
+ * Maps to the Figma `Type` variant (`Complex` | `Simple`).
+ */
+type GdprBannerType = "complex" | "simple";
+/** Layout target. Maps to the Figma `Viewport` variant. */
+type GdprBannerViewport = "desktop" | "mobile";
+/**
+ * How the action buttons wrap.
+ *
+ * - `single` - `Customize` / `Reject All` / `Accept All` on one row.
+ * - `double` - `Customize` moves onto its own row above the other two, which
+ *   keeps long translations from overflowing the card.
+ *
+ * Maps to the Figma `Buttons row` variant.
+ */
+type GdprBannerButtonsRow = "single" | "double";
+/**
+ * Which bottom corner the collapsed desktop card is pinned to. Ignored when
+ * the banner is expanded (the Privacy settings panel always spans full width)
+ * or when `viewport` is `mobile`.
+ */
+type GdprBannerAnchor = "bottom-left" | "bottom-right";
+/** A single consent category rendered inside the Privacy settings panel. */
+interface GdprCookieCategory {
+    /** Stable identifier reported through `onSelectionChange` / `onConfirmSelection`. */
+    id: string;
+    /** Visible category name. */
+    label: string;
+    /** Long-form explanation shown in the description pane when selected. */
+    description?: string;
+    /**
+     * Always-on category (e.g. essential cookies). Rendered checked and
+     * disabled, and can never be removed from the selection.
+     */
+    locked?: boolean;
+}
+/** Every user-facing string, so consumers can localize the banner. */
+interface GdprBannerLabels {
+    /** Banner heading. Default: `"How we use cookies"`. */
+    title?: string;
+    /** Body copy for `type="complex"`. */
+    description?: string;
+    /** Body copy for `type="simple"`. */
+    simpleDescription?: string;
+    /** Heading of the expanded Privacy settings panel. */
+    privacySettingsTitle?: string;
+    /** Label of the non-toggleable introductory row in the category list. */
+    generalInformation?: string;
+    /** Copy shown in the description pane while `General information` is selected. */
+    generalInformationDescription?: string;
+    customize?: string;
+    rejectAll?: string;
+    acceptAll?: string;
+    confirmSelection?: string;
+    dismiss?: string;
+    close?: string;
+    cookiePolicy?: string;
+    privacyPolicy?: string;
+    /** Accessible name of the icon-only close control. */
+    closeButtonAriaLabel?: string;
+}
+interface GdprBannerProps extends ThemeOverrideProps {
+    /** Banner density. @default "complex" */
+    type?: GdprBannerType;
+    /** Layout target. @default "desktop" */
+    viewport?: GdprBannerViewport;
+    /** Action-button wrapping. @default "single" */
+    buttonsRow?: GdprBannerButtonsRow;
+    /** Bottom corner for the collapsed desktop card. @default "bottom-left" */
+    anchor?: GdprBannerAnchor;
+    /**
+     * Whether the Privacy settings panel is open (the Figma `Fold` variant).
+     * Omit to let the banner manage the state itself; `Customize` opens it and
+     * `Close` collapses it back to the compact card.
+     *
+     * Note: the Figma component set defaults this variant to `On` for review
+     * convenience. At runtime the banner starts collapsed, which is the correct
+     * first-visit behaviour.
+     */
+    expanded?: boolean;
+    /** Initial open state when `expanded` is not supplied. @default false */
+    defaultExpanded?: boolean;
+    /** Fired whenever the panel opens or closes. */
+    onExpandedChange?: (expanded: boolean) => void;
+    /** Consent categories. Defaults to the four Xsolla categories from Figma. */
+    categories?: GdprCookieCategory[];
+    /** Controlled set of accepted category ids. */
+    selectedCategoryIds?: string[];
+    /** Initial accepted category ids when uncontrolled. Defaults to all of them. */
+    defaultSelectedCategoryIds?: string[];
+    /** Fired on every checkbox toggle with the next full selection. */
+    onSelectionChange?: (selectedCategoryIds: string[]) => void;
+    /** Overrides for any user-facing string. */
+    labels?: GdprBannerLabels;
+    /** Destination of the `Cookie Policy` footer link. */
+    cookiePolicyUrl?: string;
+    /** Destination of the `Privacy Policy` footer link. */
+    privacyPolicyUrl?: string;
+    /** `Accept All` pressed - every category consented. */
+    onAcceptAll?: () => void;
+    /** `Reject All` pressed - only locked categories remain consented. */
+    onRejectAll?: () => void;
+    /**
+     * `Customize` pressed. Fired in addition to the internal expand, so a
+     * consumer can log the interaction without taking over the state.
+     */
+    onCustomize?: () => void;
+    /** `Confirm Selection` pressed, with the accepted category ids. */
+    onConfirmSelection?: (selectedCategoryIds: string[]) => void;
+    /** `Dismiss` pressed on a `simple` banner. */
+    onDismiss?: () => void;
+    /** Close (X) pressed, or Escape. */
+    onClose?: () => void;
+    /** Render the close (X) control. @default true */
+    showCloseButton?: boolean;
+    /**
+     * `fixed` pins the banner to the bottom of the viewport (production usage).
+     * `static` renders it in normal flow, which is what stories and tests want.
+     * @default "fixed"
+     */
+    position?: "fixed" | "static";
+    /**
+     * Distance in px from the bottom / left / right edges while collapsed.
+     * Expanded panels always sit flush against the edges. @default 20
+     */
+    offset?: number;
+    testID?: string;
+}
+interface PrivacySettingsProps extends ThemeOverrideProps {
+    categories: GdprCookieCategory[];
+    selectedCategoryIds: string[];
+    onToggleCategory: (id: string) => void;
+    /** Id of the category whose description is shown, or `null` for General information. */
+    activeCategoryId: string | null;
+    onActiveCategoryChange: (id: string | null) => void;
+    viewport: GdprBannerViewport;
+    labels: Required<Pick<GdprBannerLabels, "generalInformation" | "generalInformationDescription" | "cookiePolicy" | "privacyPolicy">>;
+    cookiePolicyUrl?: string;
+    privacyPolicyUrl?: string;
+    testID?: string;
+}
+
+/**
+ * GdprBanner - the Xsolla cookie-consent banner.
+ *
+ * Implements the Figma `GDPR-banner` component set. The four Figma variant
+ * axes map to props: `Type` -> {@link GdprBannerProps.type}, `Fold` ->
+ * {@link GdprBannerProps.expanded} (inverted - Figma's `Fold=On` is the
+ * collapsed card), `Buttons row` -> {@link GdprBannerProps.buttonsRow},
+ * `Viewport` -> {@link GdprBannerProps.viewport}.
+ *
+ * ## Layout
+ *
+ * - Desktop, collapsed - a card pinned to the bottom of the viewport with a
+ *   20px inset, at either bottom corner (`anchor`).
+ * - Desktop, expanded - a wider panel hosting the two-column Privacy settings.
+ * - Mobile - always bottom-anchored and full width; actions stack.
+ *
+ * `Customize` and `Close` are borderless brand-tone text actions, matching the
+ * Figma `Flex Button` with `Background=False`.
+ *
+ * ## Accessibility
+ *
+ * - `role="dialog"` labelled by the visible heading.
+ * - Focus moves into the banner when it mounts and when the panel expands.
+ * - Tab and Shift+Tab cycle within the banner; Escape fires `onClose`.
+ * - The close control carries an explicit `aria-label`.
+ */
+declare const GdprBanner: React.FC<GdprBannerProps>;
+
+/**
+ * The expanded half of the GDPR banner: a category list on the left and the
+ * selected category's explanation on the right (stacked on mobile, where the
+ * explanation renders directly beneath the row it belongs to).
+ *
+ * Rendered by `GdprBanner` when the Privacy settings panel is open; exported
+ * so consumers can embed the same panel inside their own settings screen.
+ */
+declare const PrivacySettings: React.FC<PrivacySettingsProps>;
+
+/**
+ * The five categories shown in the Figma Privacy settings panel.
+ *
+ * `essential` is `locked`: it renders checked + disabled and is always part of
+ * the reported selection, including after `Reject All`.
+ */
+declare const DEFAULT_CATEGORIES: GdprCookieCategory[];
+declare const DEFAULT_LABELS: Required<GdprBannerLabels>;
+
+export { DEFAULT_CATEGORIES, DEFAULT_LABELS, GdprBanner, type GdprBannerAnchor, type GdprBannerButtonsRow, type GdprBannerLabels, type GdprBannerProps, type GdprBannerType, type GdprBannerViewport, type GdprCookieCategory, PrivacySettings, type PrivacySettingsProps };