@xsolla/xui-b2b-chip-stepper 0.195.0

package/README.md

@@ -0,0 +1,16 @@
+# @xsolla/xui-b2b-chip-stepper
+
+The full API reference lives at
+[`docs/api/components/b2b-chip-stepper.md`](../../../docs/api/components/b2b-chip-stepper.md).
+
+> **Maintainer note.** Sibling packages keep this file as a **symlink** to the
+> docs page (`README.md -> ../../../docs/api/components/b2b-chip-stepper.md`) so
+> npm publishes the real reference. This copy is a plain file because the commit
+> that created it went through the GitLab API, which cannot create symlinks.
+> Please convert it before merge:
+>
+> ```bash
+> cd packages/b2b/chip-stepper
+> rm README.md
+> ln -s ../../../docs/api/components/b2b-chip-stepper.md README.md
+> ```

package/native/index.d.mts

@@ -0,0 +1,137 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { BoxProps } from '@xsolla/xui-primitives-core';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Visual state of a single chip step.
+ *
+ * | Value      | Appearance                                                        |
+ * | ---------- | ----------------------------------------------------------------- |
+ * | `active`   | Current step — `overlay/brand` fill, `border/brand`, primary text. |
+ * | `next`     | Upcoming — `background/primary` fill, `border/secondary`, tertiary text. |
+ * | `done`     | Completed — same neutral chip as `next`, but `content/primary` text. |
+ * | `error`    | `overlay/alert` fill, `border/alert`, alert text; leading icon swaps to a warning glyph. |
+ * | `disabled` | `background/neutral-secondary` fill, disabled text colour.        |
+ */
+type ChipStepStatus = "active" | "next" | "done" | "error" | "disabled";
+/**
+ * Chip size. Maps to the Figma `Size` variant: `sm` = S (22px tall),
+ * `md` = M (28px tall). Named with the toolkit's `ComponentSize` vocabulary
+ * rather than Figma's single letters.
+ */
+type ChipStepSize = "sm" | "md";
+/** Payload handed to {@link ChipStepperProps.onStepClick}. */
+type ChipStepClickType = (args: {
+    /** 1-based position of the clicked step. */
+    number: number;
+    step: ChipStepType;
+}) => void;
+type ChipStepType = {
+    /**
+     * Step label. The leading ordinal (`"1."`, `"2."`, …) is computed by the
+     * component from the step's position — do NOT bake it into this string.
+     */
+    label: ReactNode;
+    /** Visual state. Defaults to `"next"`. */
+    status?: ChipStepStatus;
+    /**
+     * Per-step click handler. Runs in addition to the container-level
+     * {@link ChipStepperProps.onStepClick}. Ignored when `status` is
+     * `"disabled"`.
+     */
+    onClick?: () => void;
+    /**
+     * Optional leading icon rendered before the ordinal. Overridden by the
+     * warning glyph when `status` is `"error"`.
+     */
+    leftIcon?: ReactNode;
+    /**
+     * Adds one extra gap unit of leading inset. Use when the step has no
+     * `leftIcon` but must optically align with sibling steps that do.
+     * Defaults to `false`.
+     */
+    showLeftExtraPadding?: boolean;
+    /** Stable React key override. Defaults to the step index. */
+    key?: string;
+};
+interface ChipStepperProps extends Omit<BoxProps, "onClick">, ThemeOverrideProps {
+    /** Ordered list of steps. Ordinals are derived from array position. */
+    steps: ChipStepType[];
+    /** Chip size. Defaults to `"sm"`, matching the Figma default variant. */
+    size?: ChipStepSize;
+    /**
+     * Called when any step is clicked. When provided (or when a step carries its
+     * own `onClick`), non-disabled steps render as real `<button>` elements and
+     * are keyboard-operable.
+     */
+    onStepClick?: ChipStepClickType;
+    /**
+     * Render the computed ordinal (`"1."`) before each label. Defaults to `true`.
+     */
+    showStepNumbers?: boolean;
+    /**
+     * Render the chevron glyph between steps. Defaults to `true`. Set to `false`
+     * for a separator-less row where the chips sit side by side.
+     */
+    showSeparators?: boolean;
+    className?: string;
+    "aria-label"?: string;
+    testID?: string;
+}
+
+/**
+ * A horizontal, pill-per-step progress indicator for B2B surfaces.
+ *
+ * Each step renders as a small chip (`"1. Label"`, optionally with a leading
+ * icon) and steps are separated by chevron glyphs. Step numbers are derived
+ * from array position — callers pass labels only.
+ *
+ * Distinct from `@xsolla/xui-b2b-stepper`, which renders numbered circles with
+ * title/description blocks and supports a vertical layout. Reach for this one
+ * in tight horizontal spaces such as form and drawer headers.
+ *
+ * ```tsx
+ * <ChipStepper
+ *   steps={[
+ *     { label: "Details", status: "done" },
+ *     { label: "Billing", status: "active" },
+ *     { label: "Confirm" },
+ *   ]}
+ *   onStepClick={({ number }) => goTo(number)}
+ * />
+ * ```
+ */
+declare const ChipStepper: react.ForwardRefExoticComponent<ChipStepperProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Chip-stepper metrics, measured from the Figma `.Step-item` component set
+ * (file `fGm4yji206wAW2ZU7hhRRV`, node `15643:9363`) rather than derived from
+ * prose. Read via the Figma API on 2026-07-30.
+ *
+ * Kept local to the package rather than added to `theme.sizing` (where the
+ * circle-based `stepperB2b()` lives) because these values are specific to the
+ * pill layout and are not shared with any other component. If a second
+ * consumer appears, promote this into `theme.sizing.chipStepperB2b()`.
+ *
+ * Colours are NOT defined here — every colour is read from the active theme so
+ * the component follows all theme modes.
+ */
+type ChipStepperSizing = {
+    /** Auto-layout gap between chip children, and between chip and separator. */
+    itemGap: number;
+    chipPaddingTop: number;
+    chipPaddingBottom: number;
+    /** Leading inset. Measured smaller than the trailing inset in both sizes. */
+    chipPaddingLeft: number;
+    chipPaddingRight: number;
+    chipRadius: number;
+    chipBorderWidth: number;
+    chipIconSize: number;
+    separatorIconSize: number;
+    labelFontSize: number;
+    labelLineHeight: number;
+};
+declare const chipStepperSizing: Record<ChipStepSize, ChipStepperSizing>;
+
+export { type ChipStepClickType, type ChipStepSize, type ChipStepStatus, type ChipStepType, ChipStepper, type ChipStepperProps, type ChipStepperSizing, chipStepperSizing };

package/native/index.d.ts

@@ -0,0 +1,137 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { BoxProps } from '@xsolla/xui-primitives-core';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Visual state of a single chip step.
+ *
+ * | Value      | Appearance                                                        |
+ * | ---------- | ----------------------------------------------------------------- |
+ * | `active`   | Current step — `overlay/brand` fill, `border/brand`, primary text. |
+ * | `next`     | Upcoming — `background/primary` fill, `border/secondary`, tertiary text. |
+ * | `done`     | Completed — same neutral chip as `next`, but `content/primary` text. |
+ * | `error`    | `overlay/alert` fill, `border/alert`, alert text; leading icon swaps to a warning glyph. |
+ * | `disabled` | `background/neutral-secondary` fill, disabled text colour.        |
+ */
+type ChipStepStatus = "active" | "next" | "done" | "error" | "disabled";
+/**
+ * Chip size. Maps to the Figma `Size` variant: `sm` = S (22px tall),
+ * `md` = M (28px tall). Named with the toolkit's `ComponentSize` vocabulary
+ * rather than Figma's single letters.
+ */
+type ChipStepSize = "sm" | "md";
+/** Payload handed to {@link ChipStepperProps.onStepClick}. */
+type ChipStepClickType = (args: {
+    /** 1-based position of the clicked step. */
+    number: number;
+    step: ChipStepType;
+}) => void;
+type ChipStepType = {
+    /**
+     * Step label. The leading ordinal (`"1."`, `"2."`, …) is computed by the
+     * component from the step's position — do NOT bake it into this string.
+     */
+    label: ReactNode;
+    /** Visual state. Defaults to `"next"`. */
+    status?: ChipStepStatus;
+    /**
+     * Per-step click handler. Runs in addition to the container-level
+     * {@link ChipStepperProps.onStepClick}. Ignored when `status` is
+     * `"disabled"`.
+     */
+    onClick?: () => void;
+    /**
+     * Optional leading icon rendered before the ordinal. Overridden by the
+     * warning glyph when `status` is `"error"`.
+     */
+    leftIcon?: ReactNode;
+    /**
+     * Adds one extra gap unit of leading inset. Use when the step has no
+     * `leftIcon` but must optically align with sibling steps that do.
+     * Defaults to `false`.
+     */
+    showLeftExtraPadding?: boolean;
+    /** Stable React key override. Defaults to the step index. */
+    key?: string;
+};
+interface ChipStepperProps extends Omit<BoxProps, "onClick">, ThemeOverrideProps {
+    /** Ordered list of steps. Ordinals are derived from array position. */
+    steps: ChipStepType[];
+    /** Chip size. Defaults to `"sm"`, matching the Figma default variant. */
+    size?: ChipStepSize;
+    /**
+     * Called when any step is clicked. When provided (or when a step carries its
+     * own `onClick`), non-disabled steps render as real `<button>` elements and
+     * are keyboard-operable.
+     */
+    onStepClick?: ChipStepClickType;
+    /**
+     * Render the computed ordinal (`"1."`) before each label. Defaults to `true`.
+     */
+    showStepNumbers?: boolean;
+    /**
+     * Render the chevron glyph between steps. Defaults to `true`. Set to `false`
+     * for a separator-less row where the chips sit side by side.
+     */
+    showSeparators?: boolean;
+    className?: string;
+    "aria-label"?: string;
+    testID?: string;
+}
+
+/**
+ * A horizontal, pill-per-step progress indicator for B2B surfaces.
+ *
+ * Each step renders as a small chip (`"1. Label"`, optionally with a leading
+ * icon) and steps are separated by chevron glyphs. Step numbers are derived
+ * from array position — callers pass labels only.
+ *
+ * Distinct from `@xsolla/xui-b2b-stepper`, which renders numbered circles with
+ * title/description blocks and supports a vertical layout. Reach for this one
+ * in tight horizontal spaces such as form and drawer headers.
+ *
+ * ```tsx
+ * <ChipStepper
+ *   steps={[
+ *     { label: "Details", status: "done" },
+ *     { label: "Billing", status: "active" },
+ *     { label: "Confirm" },
+ *   ]}
+ *   onStepClick={({ number }) => goTo(number)}
+ * />
+ * ```
+ */
+declare const ChipStepper: react.ForwardRefExoticComponent<ChipStepperProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Chip-stepper metrics, measured from the Figma `.Step-item` component set
+ * (file `fGm4yji206wAW2ZU7hhRRV`, node `15643:9363`) rather than derived from
+ * prose. Read via the Figma API on 2026-07-30.
+ *
+ * Kept local to the package rather than added to `theme.sizing` (where the
+ * circle-based `stepperB2b()` lives) because these values are specific to the
+ * pill layout and are not shared with any other component. If a second
+ * consumer appears, promote this into `theme.sizing.chipStepperB2b()`.
+ *
+ * Colours are NOT defined here — every colour is read from the active theme so
+ * the component follows all theme modes.
+ */
+type ChipStepperSizing = {
+    /** Auto-layout gap between chip children, and between chip and separator. */
+    itemGap: number;
+    chipPaddingTop: number;
+    chipPaddingBottom: number;
+    /** Leading inset. Measured smaller than the trailing inset in both sizes. */
+    chipPaddingLeft: number;
+    chipPaddingRight: number;
+    chipRadius: number;
+    chipBorderWidth: number;
+    chipIconSize: number;
+    separatorIconSize: number;
+    labelFontSize: number;
+    labelLineHeight: number;
+};
+declare const chipStepperSizing: Record<ChipStepSize, ChipStepperSizing>;
+
+export { type ChipStepClickType, type ChipStepSize, type ChipStepStatus, type ChipStepType, ChipStepper, type ChipStepperProps, type ChipStepperSizing, chipStepperSizing };