@xsolla/xui-counter 0.200.0

package/native/index.d.mts

@@ -0,0 +1,130 @@
+import React from 'react';
+import { ThemeOverrideProps, ComponentSize } from '@xsolla/xui-core';
+
+/**
+ * How the Counter renders the value between the − and + buttons.
+ *
+ * - `"input"` — an editable text field. Supports Hover and Focus because it is
+ *   a real input target.
+ * - `"readOnly"` — plain text changed only by the buttons. Has no Hover or
+ *   Focus state of its own; the buttons carry their own hover states.
+ *
+ * `"readOnly"` renders the value as plain text, **not** as a disabled or
+ * `readonly` input — both would tell assistive technology the value cannot
+ * change, which is false.
+ */
+type CounterType = "input" | "readOnly";
+interface CounterProps extends ThemeOverrideProps {
+    /**
+     * Current value (controlled). Pass `null` for a genuinely empty counter —
+     * the Figma `Filled=False` state. An empty counter is unusual; most counters
+     * start at a defined value such as `0` or `1`.
+     */
+    value?: number | null;
+    /**
+     * Initial value when the component is uncontrolled. Ignored when `value` is
+     * provided.
+     *
+     * @default null
+     */
+    defaultValue?: number | null;
+    /**
+     * Fired when the value is committed — on button press, on blur, or on Enter.
+     * Never fired on every keystroke, and never fired with an out-of-range or
+     * empty value: the committed number is always clamped into
+     * `[min, max]`.
+     */
+    onChange?: (value: number) => void;
+    /**
+     * Lowest allowed value. When reached, the − button becomes unavailable.
+     * Values below it are rounded up to it on commit.
+     */
+    min?: number;
+    /**
+     * Highest allowed value. When reached, the + button becomes unavailable.
+     * Values above it are rounded down to it on commit.
+     */
+    max?: number;
+    /**
+     * How much one − / + press changes the value by. Define a larger step when
+     * the domain requires it (for example steps of 5 for bulk items).
+     *
+     * @default 1
+     */
+    step?: number;
+    /**
+     * Size of the counter. Drives the button box, the field height, the type
+     * scale, and the gap between the three elements.
+     *
+     * @default "md"
+     */
+    size?: ComponentSize;
+    /**
+     * Whether the value is an editable field (`"input"`) or plain text driven
+     * only by the buttons (`"readOnly"`).
+     *
+     * @default "input"
+     */
+    type?: CounterType;
+    /**
+     * Disables the whole control — both buttons and, for `type="input"`, the
+     * field. The current value stays visible; always explain nearby why the
+     * quantity cannot be changed if the reason is not obvious.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Visible label rendered above the whole control (buttons + value), not
+     * between the buttons. Prefer FieldGroup or adjacent text in product UI;
+     * this prop is a convenience for the same layout. `type="input"` only —
+     * use `aria-label` for `type="readOnly"`. The − / + buttons alone do not
+     * name what is being counted.
+     */
+    label?: string;
+    /**
+     * Accessible name for the control when no visible `label` is present, e.g.
+     * `"Quantity"`, `"Number of guests"`, `"Quantity of Dragon Scale skin"`.
+     */
+    "aria-label"?: string;
+    /**
+     * Accessible name for the decrement button. Include the subject where
+     * possible so multiple counters on one page stay distinguishable.
+     *
+     * @default "Decrease quantity"
+     */
+    decrementLabel?: string;
+    /**
+     * Accessible name for the increment button.
+     *
+     * @default "Increase quantity"
+     */
+    incrementLabel?: string;
+    /**
+     * `name` attribute forwarded to the underlying field. Only used for
+     * `type="input"`.
+     */
+    name?: string;
+    /**
+     * Unique identifier for the field element. Used for accessibility linking.
+     */
+    id?: string;
+    /**
+     * Test ID for testing frameworks. On web this renders as `data-testid`; on
+     * React Native it renders as `testID`. Sub-elements append `__decrement`,
+     * `__increment`, `__input`, and `__value`.
+     */
+    testID?: string;
+}
+
+/**
+ * A numeric stepper that lets the user increase or decrease a value using
+ * dedicated − and + buttons.
+ *
+ * Counter has no error state: values outside the allowed range are never
+ * rejected, they are silently clamped to the nearest bound on commit, so the
+ * component is always in a valid state.
+ */
+declare const Counter: React.ForwardRefExoticComponent<CounterProps & React.RefAttributes<HTMLInputElement>>;
+
+export { Counter, type CounterProps, type CounterType };

package/native/index.d.ts

@@ -0,0 +1,130 @@
+import React from 'react';
+import { ThemeOverrideProps, ComponentSize } from '@xsolla/xui-core';
+
+/**
+ * How the Counter renders the value between the − and + buttons.
+ *
+ * - `"input"` — an editable text field. Supports Hover and Focus because it is
+ *   a real input target.
+ * - `"readOnly"` — plain text changed only by the buttons. Has no Hover or
+ *   Focus state of its own; the buttons carry their own hover states.
+ *
+ * `"readOnly"` renders the value as plain text, **not** as a disabled or
+ * `readonly` input — both would tell assistive technology the value cannot
+ * change, which is false.
+ */
+type CounterType = "input" | "readOnly";
+interface CounterProps extends ThemeOverrideProps {
+    /**
+     * Current value (controlled). Pass `null` for a genuinely empty counter —
+     * the Figma `Filled=False` state. An empty counter is unusual; most counters
+     * start at a defined value such as `0` or `1`.
+     */
+    value?: number | null;
+    /**
+     * Initial value when the component is uncontrolled. Ignored when `value` is
+     * provided.
+     *
+     * @default null
+     */
+    defaultValue?: number | null;
+    /**
+     * Fired when the value is committed — on button press, on blur, or on Enter.
+     * Never fired on every keystroke, and never fired with an out-of-range or
+     * empty value: the committed number is always clamped into
+     * `[min, max]`.
+     */
+    onChange?: (value: number) => void;
+    /**
+     * Lowest allowed value. When reached, the − button becomes unavailable.
+     * Values below it are rounded up to it on commit.
+     */
+    min?: number;
+    /**
+     * Highest allowed value. When reached, the + button becomes unavailable.
+     * Values above it are rounded down to it on commit.
+     */
+    max?: number;
+    /**
+     * How much one − / + press changes the value by. Define a larger step when
+     * the domain requires it (for example steps of 5 for bulk items).
+     *
+     * @default 1
+     */
+    step?: number;
+    /**
+     * Size of the counter. Drives the button box, the field height, the type
+     * scale, and the gap between the three elements.
+     *
+     * @default "md"
+     */
+    size?: ComponentSize;
+    /**
+     * Whether the value is an editable field (`"input"`) or plain text driven
+     * only by the buttons (`"readOnly"`).
+     *
+     * @default "input"
+     */
+    type?: CounterType;
+    /**
+     * Disables the whole control — both buttons and, for `type="input"`, the
+     * field. The current value stays visible; always explain nearby why the
+     * quantity cannot be changed if the reason is not obvious.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Visible label rendered above the whole control (buttons + value), not
+     * between the buttons. Prefer FieldGroup or adjacent text in product UI;
+     * this prop is a convenience for the same layout. `type="input"` only —
+     * use `aria-label` for `type="readOnly"`. The − / + buttons alone do not
+     * name what is being counted.
+     */
+    label?: string;
+    /**
+     * Accessible name for the control when no visible `label` is present, e.g.
+     * `"Quantity"`, `"Number of guests"`, `"Quantity of Dragon Scale skin"`.
+     */
+    "aria-label"?: string;
+    /**
+     * Accessible name for the decrement button. Include the subject where
+     * possible so multiple counters on one page stay distinguishable.
+     *
+     * @default "Decrease quantity"
+     */
+    decrementLabel?: string;
+    /**
+     * Accessible name for the increment button.
+     *
+     * @default "Increase quantity"
+     */
+    incrementLabel?: string;
+    /**
+     * `name` attribute forwarded to the underlying field. Only used for
+     * `type="input"`.
+     */
+    name?: string;
+    /**
+     * Unique identifier for the field element. Used for accessibility linking.
+     */
+    id?: string;
+    /**
+     * Test ID for testing frameworks. On web this renders as `data-testid`; on
+     * React Native it renders as `testID`. Sub-elements append `__decrement`,
+     * `__increment`, `__input`, and `__value`.
+     */
+    testID?: string;
+}
+
+/**
+ * A numeric stepper that lets the user increase or decrease a value using
+ * dedicated − and + buttons.
+ *
+ * Counter has no error state: values outside the allowed range are never
+ * rejected, they are silently clamped to the nearest bound on commit, so the
+ * component is always in a valid state.
+ */
+declare const Counter: React.ForwardRefExoticComponent<CounterProps & React.RefAttributes<HTMLInputElement>>;
+
+export { Counter, type CounterProps, type CounterType };