@xsolla/xui-b2c-card-selector 0.217.0

package/README.md

@@ -0,0 +1,4 @@
+# @xsolla/xui-b2c-card-selector
+
+B2C selectable card for presenting a visual choice within a group — a media
+thumbnail with a title and a Radio or Check selection control.

package/native/index.d.mts

@@ -0,0 +1,112 @@
+import React, { ReactNode } from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Figma `CardSelector` property `Platform`. Adjusts the card's internal
+ * proportions — control size, title scale and padding.
+ */
+type CardSelectorPlatform = "mobile" | "desktop";
+/**
+ * Figma `CardSelector` property `Type`. `radio` = mutually exclusive choice
+ * within a group, `check` = independent toggle.
+ */
+type CardSelectorType = "radio" | "check";
+/**
+ * Figma `CardSelector` property `Control`.
+ *
+ * - `text` — the selection control and the label sit in a solid text bar
+ *   below the image. The control is always visible.
+ * - `onImage` — the control overlays the image and only renders when the card
+ *   is selected; the label is a caption beneath the card.
+ */
+type CardSelectorControlPlacement = "text" | "onImage";
+/** Figma `CardSelector` property `State`. `selected` is derived from `checked`. */
+type CardSelectorState = "default" | "hover" | "press" | "disabled";
+interface CardSelectorProps extends ThemeOverrideProps {
+    /**
+     * Option label. Required, single-line, truncates with an ellipsis — aim for
+     * under 24 characters.
+     */
+    title: ReactNode;
+    /**
+     * Optional single-line clarification. Use it only when the title alone is
+     * ambiguous; never repeat the title.
+     */
+    description?: ReactNode;
+    /** Media thumbnail (1:1). The image should preview the option itself. */
+    imageSrc?: string;
+    /**
+     * Alt text. Defaults to `""` because the title normally describes the
+     * option; supply a meaningful value when the image carries meaning the
+     * title does not convey.
+     */
+    imageAlt?: string;
+    /** Identifies the card inside a `CardSelectorGroup`. Required for `radio`. */
+    value?: string;
+    /** Inherited from `CardSelectorGroup` when unset. Defaults to `"radio"`. */
+    type?: CardSelectorType;
+    /** Inherited from `CardSelectorGroup` when unset. Defaults to `"text"`. */
+    control?: CardSelectorControlPlacement;
+    /** Inherited from `CardSelectorGroup` when unset. Defaults to `"mobile"`. */
+    platform?: CardSelectorPlatform;
+    /** Controlled selection state. Inside a radio group, derived from the group. */
+    checked?: boolean;
+    /** Uncontrolled initial selection state. */
+    defaultChecked?: boolean;
+    /** Fired when the card toggles. Not fired while disabled. */
+    onChange?: (checked: boolean, value?: string) => void;
+    /**
+     * Interactive state. Web applies hover and press automatically — pass this
+     * explicitly only for design review. `selected` is not a member: it is
+     * derived from `checked` and takes visual priority over hover.
+     */
+    state?: CardSelectorState;
+    /** Same effect as `state="disabled"`: 48% opacity, no interactivity, untabbable. */
+    disabled?: boolean;
+    /**
+     * Card width. Defaults to `"100%"` so the card fills the grid cell the
+     * consumer lays out.
+     */
+    width?: number | string;
+    /** Overrides the accessible name derived from the title and description. */
+    "aria-label"?: string;
+    testID?: string;
+}
+interface CardSelectorGroupProps extends ThemeOverrideProps {
+    children: ReactNode;
+    /** `radio` renders a `radiogroup`; `check` renders a plain `group`. */
+    type?: CardSelectorType;
+    /** Selected value for `type="radio"` (controlled). */
+    value?: string;
+    /** Initial selected value for `type="radio"` (uncontrolled). */
+    defaultValue?: string;
+    /** Fired with the newly selected value. `type="radio"` only. */
+    onValueChange?: (value: string) => void;
+    /** Applied to every card in the group unless the card overrides it. */
+    platform?: CardSelectorPlatform;
+    /** Applied to every card in the group unless the card overrides it. */
+    control?: CardSelectorControlPlacement;
+    /** Disables every card in the group. */
+    disabled?: boolean;
+    /** Grid gap between cards. */
+    gap?: number;
+    /** Accessible name for the group. Required unless `aria-labelledby` is set. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    testID?: string;
+}
+
+declare const CardSelector: React.FC<CardSelectorProps>;
+
+/**
+ * Wraps a set of `CardSelector` cards.
+ *
+ * For `type="radio"` it renders a `radiogroup`, keeps the cards mutually
+ * exclusive, and implements the roving-tabindex + Arrow-key behaviour the
+ * Figma spec requires (3446:1761 — "within a Radio group, Arrow keys move
+ * focus and selection between cards"). For `type="check"` the cards toggle
+ * independently and the wrapper is a plain `group`.
+ */
+declare const CardSelectorGroup: React.FC<CardSelectorGroupProps>;
+
+export { CardSelector, type CardSelectorControlPlacement, CardSelectorGroup, type CardSelectorGroupProps, type CardSelectorPlatform, type CardSelectorProps, type CardSelectorState, type CardSelectorType };

package/native/index.d.ts

@@ -0,0 +1,112 @@
+import React, { ReactNode } from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Figma `CardSelector` property `Platform`. Adjusts the card's internal
+ * proportions — control size, title scale and padding.
+ */
+type CardSelectorPlatform = "mobile" | "desktop";
+/**
+ * Figma `CardSelector` property `Type`. `radio` = mutually exclusive choice
+ * within a group, `check` = independent toggle.
+ */
+type CardSelectorType = "radio" | "check";
+/**
+ * Figma `CardSelector` property `Control`.
+ *
+ * - `text` — the selection control and the label sit in a solid text bar
+ *   below the image. The control is always visible.
+ * - `onImage` — the control overlays the image and only renders when the card
+ *   is selected; the label is a caption beneath the card.
+ */
+type CardSelectorControlPlacement = "text" | "onImage";
+/** Figma `CardSelector` property `State`. `selected` is derived from `checked`. */
+type CardSelectorState = "default" | "hover" | "press" | "disabled";
+interface CardSelectorProps extends ThemeOverrideProps {
+    /**
+     * Option label. Required, single-line, truncates with an ellipsis — aim for
+     * under 24 characters.
+     */
+    title: ReactNode;
+    /**
+     * Optional single-line clarification. Use it only when the title alone is
+     * ambiguous; never repeat the title.
+     */
+    description?: ReactNode;
+    /** Media thumbnail (1:1). The image should preview the option itself. */
+    imageSrc?: string;
+    /**
+     * Alt text. Defaults to `""` because the title normally describes the
+     * option; supply a meaningful value when the image carries meaning the
+     * title does not convey.
+     */
+    imageAlt?: string;
+    /** Identifies the card inside a `CardSelectorGroup`. Required for `radio`. */
+    value?: string;
+    /** Inherited from `CardSelectorGroup` when unset. Defaults to `"radio"`. */
+    type?: CardSelectorType;
+    /** Inherited from `CardSelectorGroup` when unset. Defaults to `"text"`. */
+    control?: CardSelectorControlPlacement;
+    /** Inherited from `CardSelectorGroup` when unset. Defaults to `"mobile"`. */
+    platform?: CardSelectorPlatform;
+    /** Controlled selection state. Inside a radio group, derived from the group. */
+    checked?: boolean;
+    /** Uncontrolled initial selection state. */
+    defaultChecked?: boolean;
+    /** Fired when the card toggles. Not fired while disabled. */
+    onChange?: (checked: boolean, value?: string) => void;
+    /**
+     * Interactive state. Web applies hover and press automatically — pass this
+     * explicitly only for design review. `selected` is not a member: it is
+     * derived from `checked` and takes visual priority over hover.
+     */
+    state?: CardSelectorState;
+    /** Same effect as `state="disabled"`: 48% opacity, no interactivity, untabbable. */
+    disabled?: boolean;
+    /**
+     * Card width. Defaults to `"100%"` so the card fills the grid cell the
+     * consumer lays out.
+     */
+    width?: number | string;
+    /** Overrides the accessible name derived from the title and description. */
+    "aria-label"?: string;
+    testID?: string;
+}
+interface CardSelectorGroupProps extends ThemeOverrideProps {
+    children: ReactNode;
+    /** `radio` renders a `radiogroup`; `check` renders a plain `group`. */
+    type?: CardSelectorType;
+    /** Selected value for `type="radio"` (controlled). */
+    value?: string;
+    /** Initial selected value for `type="radio"` (uncontrolled). */
+    defaultValue?: string;
+    /** Fired with the newly selected value. `type="radio"` only. */
+    onValueChange?: (value: string) => void;
+    /** Applied to every card in the group unless the card overrides it. */
+    platform?: CardSelectorPlatform;
+    /** Applied to every card in the group unless the card overrides it. */
+    control?: CardSelectorControlPlacement;
+    /** Disables every card in the group. */
+    disabled?: boolean;
+    /** Grid gap between cards. */
+    gap?: number;
+    /** Accessible name for the group. Required unless `aria-labelledby` is set. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    testID?: string;
+}
+
+declare const CardSelector: React.FC<CardSelectorProps>;
+
+/**
+ * Wraps a set of `CardSelector` cards.
+ *
+ * For `type="radio"` it renders a `radiogroup`, keeps the cards mutually
+ * exclusive, and implements the roving-tabindex + Arrow-key behaviour the
+ * Figma spec requires (3446:1761 — "within a Radio group, Arrow keys move
+ * focus and selection between cards"). For `type="check"` the cards toggle
+ * independently and the wrapper is a plain `group`.
+ */
+declare const CardSelectorGroup: React.FC<CardSelectorGroupProps>;
+
+export { CardSelector, type CardSelectorControlPlacement, CardSelectorGroup, type CardSelectorGroupProps, type CardSelectorPlatform, type CardSelectorProps, type CardSelectorState, type CardSelectorType };