@xsolla/xui-button 0.191.0 → 0.193.0

package/README.md

@@ -476,11 +476,13 @@ A button variant that displays only an icon. Requires `aria-label` for accessibi
 
 A flexible button with more granular control over background, hover fills, and styling.
 
+Forwards a `ref` to the underlying `<button>` element, and inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
+
 **FlexButton Props:**
 
 | Prop            | Type                                                                             | Default    | Description                                                    |
 | :-------------- | :------------------------------------------------------------------------------- | :--------- | :------------------------------------------------------------- |
-| children        | `ReactNode`                                                                      | -          | The button label content.                                      |
+| children        | `ReactNode`                                                                      | -          | The button label content. Optional — omit for an icon-only button, which renders no text slot so the icon stays centred in the hit area. |
 | variant         | `"brand" \| "primary" \| "secondary" \| "tertiary" \| "brandExtra" \| "inverse"` | `"brand"`  | The visual style variant.                                      |
 | size            | `"xl" \| "lg" \| "md" \| "sm" \| "xs"`                                           | `"md"`     | The size of the button.                                        |
 | background      | `boolean`                                                                        | `false`    | Whether to show background fill.                               |
@@ -492,6 +494,16 @@ A flexible button with more granular control over background, hover fills, and s
 | onPress         | `() => void`                                                                     | -          | Callback fired when button is pressed.                         |
 | type            | `"button" \| "submit" \| "reset"`                                                | `"button"` | The HTML button type attribute.                                |
 
+**`getFlexButtonBoxSize(size?)`**
+
+Returns the square side, in px, of an icon-only `FlexButton` — `20 | 22 | 28 | 32 | 36` for `xs`–`xl`, defaulting to `md`. Use it when a layout has to reserve a matching column for a button it does not render itself (as `Modal`'s header does), instead of hardcoding the number. `noPadding` does not change it; only the inner padding is removed.
+
+```tsx
+import { getFlexButtonBoxSize } from "@xsolla/xui-button";
+
+<Box style={{ minWidth: getFlexButtonBoxSize("xl") }} />; // 36
+```
+
 ---
 
 ### ButtonGroup

package/native/index.d.mts

@@ -169,8 +169,15 @@ interface IconButtonProps extends ThemeOverrideProps {
  */
 declare const IconButton: React.FC<IconButtonProps>;
 
-interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
-    /** Button label. Omit for icon-only buttons (provide `aria-label`). */
+interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type">, ThemeOverrideProps {
+    /**
+     * Button label. Omit for icon-only buttons (provide `aria-label`).
+     *
+     * An icon may also be passed directly as `children` instead of via
+     * `iconLeft`/`iconRight`. When `children` carries no text, the button is
+     * treated as icon-only and renders as a square sized from the design-system
+     * height token for `size`.
+     */
     children?: ReactNode;
     /** Visual variant of the button */
     variant?: "brand" | "primary" | "secondary" | "tertiary" | "brandExtra" | "inverse";
@@ -190,6 +197,9 @@ interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElem
      * The component applies padding via an inline style, which overrides any CSS
      * class or `style` prop a consumer passes, so this prop is the supported way
      * to render a zero-padding FlexButton (e.g. an inline text action).
+     *
+     * Icon-only buttons keep their square dimensions when `noPadding` is set —
+     * only the inner padding is removed.
      * @default false
      */
     noPadding?: boolean;
@@ -219,11 +229,29 @@ interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElem
     "aria-controls"?: string;
     testID?: string;
 }
+/**
+ * Total hit-area size of an icon-only `FlexButton`, in px. `noPadding` does not
+ * change it — only the inner padding is removed.
+ */
+declare const getFlexButtonBoxSize: (size?: NonNullable<FlexButtonProps["size"]>) => number;
 /**
  * FlexButton - A compact button component designed for use in modals and popups.
  *
  * Renders as a semantic `<button>` element with full ARIA support.
  *
+ * ## Icon-only buttons
+ *
+ * A FlexButton is icon-only when it has no text label and an icon is supplied
+ * either as `children` or via `iconLeft`/`iconRight`. Icon-only buttons render
+ * as a square whose side equals `theme.sizing.flexButton(size).height`, so they
+ * line up with the Modal header icon slots (36x36 at `size="xl"`).
+ *
+ * ```tsx
+ * <FlexButton variant="secondary" size="xl" aria-label="Go back">
+ *   <BackwardAlt variant="line" />
+ * </FlexButton>
+ * ```
+ *
  * ## Accessibility Features
  *
  * - **Semantic HTML**: Renders as a native `<button>` element
@@ -232,7 +260,7 @@ interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElem
  * - **Focus Indicator**: Visible focus ring for keyboard navigation
  * - **Screen Reader Support**: Announces button label, state, and any associated descriptions
  */
-declare const FlexButton: React.FC<FlexButtonProps>;
+declare const FlexButton: React.ForwardRefExoticComponent<FlexButtonProps & React.RefAttributes<HTMLButtonElement>>;
 
 interface AppButtonProps extends ThemeOverrideProps {
     /** Size of the button */
@@ -341,4 +369,4 @@ interface ButtonGroupProps extends ThemeOverrideProps {
  */
 declare const ButtonGroup: React.FC<ButtonGroupProps>;
 
-export { AppButton, type AppButtonProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, FlexButton, type FlexButtonProps, IconButton, type IconButtonProps };
+export { AppButton, type AppButtonProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, FlexButton, type FlexButtonProps, IconButton, type IconButtonProps, getFlexButtonBoxSize };

package/native/index.d.ts

@@ -169,8 +169,15 @@ interface IconButtonProps extends ThemeOverrideProps {
  */
 declare const IconButton: React.FC<IconButtonProps>;
 
-interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
-    /** Button label. Omit for icon-only buttons (provide `aria-label`). */
+interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type">, ThemeOverrideProps {
+    /**
+     * Button label. Omit for icon-only buttons (provide `aria-label`).
+     *
+     * An icon may also be passed directly as `children` instead of via
+     * `iconLeft`/`iconRight`. When `children` carries no text, the button is
+     * treated as icon-only and renders as a square sized from the design-system
+     * height token for `size`.
+     */
     children?: ReactNode;
     /** Visual variant of the button */
     variant?: "brand" | "primary" | "secondary" | "tertiary" | "brandExtra" | "inverse";
@@ -190,6 +197,9 @@ interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElem
      * The component applies padding via an inline style, which overrides any CSS
      * class or `style` prop a consumer passes, so this prop is the supported way
      * to render a zero-padding FlexButton (e.g. an inline text action).
+     *
+     * Icon-only buttons keep their square dimensions when `noPadding` is set —
+     * only the inner padding is removed.
      * @default false
      */
     noPadding?: boolean;
@@ -219,11 +229,29 @@ interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElem
     "aria-controls"?: string;
     testID?: string;
 }
+/**
+ * Total hit-area size of an icon-only `FlexButton`, in px. `noPadding` does not
+ * change it — only the inner padding is removed.
+ */
+declare const getFlexButtonBoxSize: (size?: NonNullable<FlexButtonProps["size"]>) => number;
 /**
  * FlexButton - A compact button component designed for use in modals and popups.
  *
  * Renders as a semantic `<button>` element with full ARIA support.
  *
+ * ## Icon-only buttons
+ *
+ * A FlexButton is icon-only when it has no text label and an icon is supplied
+ * either as `children` or via `iconLeft`/`iconRight`. Icon-only buttons render
+ * as a square whose side equals `theme.sizing.flexButton(size).height`, so they
+ * line up with the Modal header icon slots (36x36 at `size="xl"`).
+ *
+ * ```tsx
+ * <FlexButton variant="secondary" size="xl" aria-label="Go back">
+ *   <BackwardAlt variant="line" />
+ * </FlexButton>
+ * ```
+ *
  * ## Accessibility Features
  *
  * - **Semantic HTML**: Renders as a native `<button>` element
@@ -232,7 +260,7 @@ interface FlexButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElem
  * - **Focus Indicator**: Visible focus ring for keyboard navigation
  * - **Screen Reader Support**: Announces button label, state, and any associated descriptions
  */
-declare const FlexButton: React.FC<FlexButtonProps>;
+declare const FlexButton: React.ForwardRefExoticComponent<FlexButtonProps & React.RefAttributes<HTMLButtonElement>>;
 
 interface AppButtonProps extends ThemeOverrideProps {
     /** Size of the button */
@@ -341,4 +369,4 @@ interface ButtonGroupProps extends ThemeOverrideProps {
  */
 declare const ButtonGroup: React.FC<ButtonGroupProps>;
 
-export { AppButton, type AppButtonProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, FlexButton, type FlexButtonProps, IconButton, type IconButtonProps };
+export { AppButton, type AppButtonProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, FlexButton, type FlexButtonProps, IconButton, type IconButtonProps, getFlexButtonBoxSize };