@xsolla/xui-input-color 0.184.0

package/README.md

@@ -0,0 +1,130 @@
+# Input Color
+
+A compact inline control for previewing and editing a colour value — a colour swatch alongside an editable hex or RGB field, with optional transparency (alpha). Use it on its own, or as the inline trigger that opens a `ColorPicker`. Works on web and React Native via `XUIProvider` themed contexts.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-input-color
+```
+
+## Imports
+
+```tsx
+import { InputColor } from '@xsolla/xui-input-color';
+import type {
+  InputColorProps,
+  InputColorType,
+  InputColorSize,
+} from '@xsolla/xui-input-color';
+```
+
+## Quick start
+
+```tsx
+const [color, setColor] = useState('#22A8C3');
+
+<InputColor value={color} onChange={setColor} />;
+```
+
+## API Reference
+
+### `<InputColor>`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Controlled colour as a hex string (e.g. `#22A8C3`; `#RRGGBBAA` when `transparency` is on). |
+| `defaultValue` | `string` | `'#000000'` | Initial value for uncontrolled usage. |
+| `onChange` | `(value: string) => void` | — | Change handler; always receives a hex string (8-digit when `transparency` is on). |
+| `onSwatchClick` | `() => void` | — | Fired when the swatch is activated. The swatch is interactive **only** when `type="color"` — use it to open a parent `ColorPicker`. Never called for other types. |
+| `type` | `'color' \| 'color-hex' \| 'color-rgb' \| 'hex' \| 'rgb'` | `'color-hex'` | Which controls render (see [Types](#types)). |
+| `transparency` | `boolean` | `false` | Add an alpha (`%`) field and a transparency-aware swatch. |
+| `size` | `'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs'` | `'md'` | Control size. |
+| `label` | `string` | — | Visible label shown above the control. |
+| `id` | `string` | `auto` | HTML id used for accessibility linking. |
+| `aria-label` | `string` | — | Accessible name when no visible label is present. |
+| `testID` | `string` | — | Test identifier. |
+
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
+
+The canonical value is always a hex string, regardless of `type`. The hex and RGB fields are alternate editable representations of the same colour; editing either emits an updated hex through `onChange`.
+
+## Types
+
+| `type` | Shows |
+| --- | --- |
+| `color` | Swatch only — acts as a trigger (`onSwatchClick`). |
+| `color-hex` | Swatch + hex field. |
+| `color-rgb` | Swatch + R / G / B fields. |
+| `hex` | Hex field only. |
+| `rgb` | R / G / B fields only. |
+
+When `transparency` is on, an alpha (`%`) field is appended to every type and `color` gains it too.
+
+## Examples
+
+### Hex field (default)
+
+```tsx
+const [color, setColor] = useState('#22A8C3');
+
+<InputColor value={color} onChange={setColor} />;
+```
+
+### RGB channels
+
+```tsx
+const [color, setColor] = useState('#22A8C3');
+
+<InputColor type="color-rgb" value={color} onChange={setColor} />;
+```
+
+### Transparency (alpha)
+
+```tsx
+const [color, setColor] = useState('#22A8C380');
+
+<InputColor type="color-rgb" transparency value={color} onChange={setColor} />;
+```
+
+### Sizes
+
+```tsx
+<InputColor size="xl" defaultValue="#22A8C3" />
+<InputColor size="md" defaultValue="#22A8C3" />
+<InputColor size="xs" defaultValue="#22A8C3" />
+```
+
+### Swatch as a ColorPicker trigger
+
+`type="color"` renders the swatch alone; wire `onSwatchClick` to open a parent `ColorPicker`.
+
+```tsx
+const [color, setColor] = useState('#22A8C3');
+const [open, setOpen] = useState(false);
+
+<InputColor
+  type="color"
+  value={color}
+  onChange={setColor}
+  onSwatchClick={() => setOpen(true)}
+/>;
+```
+
+### With a label
+
+```tsx
+const [color, setColor] = useState('#22A8C3');
+
+<InputColor value={color} onChange={setColor} label="Brand color" />;
+```
+
+## Accessibility
+
+- The control is a `role="group"`; label it with `label`, `aria-label`, or an external `aria-labelledby` target.
+- Each editable field has an `aria-label` — `"Hex color value"`, `"Red channel"`, `"Green channel"`, `"Blue channel"`, `"Opacity percentage"`.
+- For `type="color"` the swatch is a `<button aria-label="Open color picker">`; for every other type it is a decorative preview marked `aria-hidden` (not focusable, not clickable).
+- Numeric fields (R / G / B, alpha) step by ±1 with the `ArrowUp` / `ArrowDown` keys, clamped to their range (0–255, or 0–100 for alpha).
+- A visually hidden `role="status"` / `aria-live="polite"` region announces colour changes to screen readers (e.g. "Color updated to #FF0000").
+- Editing updates the swatch live as you type; the value commits (and normalizes — shorthand expand, uppercase, clamp) on blur, `Enter`, or `Tab`.
+- The transparency checkerboard behind a translucent colour is rendered with CSS and is web only; the solid swatch and alpha split render on native.

package/native/index.d.mts

@@ -0,0 +1,66 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Display variant of the InputColor control. Maps 1:1 to the Figma `Type` prop:
+ * - `color`      → "Color only"          (swatch preview only, no editable field)
+ * - `color-hex`  → "Color + HEX"         (swatch + editable hex field)
+ * - `color-rgb`  → "Color + HSL/HSB/RGB" (swatch + editable R/G/B channels)
+ * - `hex`        → "HEX"                  (editable hex field only)
+ * - `rgb`        → "HSL/HSB/RGB"          (editable R/G/B channels only)
+ */
+type InputColorType = "color" | "color-hex" | "color-rgb" | "hex" | "rgb";
+type InputColorSize = "xl" | "lg" | "md" | "sm" | "xs";
+interface InputColorProps extends ThemeOverrideProps {
+    /**
+     * The current color value as a hex string (controlled mode), e.g. `#22A8C3`.
+     * When `transparency` is enabled an 8-digit hex (`#RRGGBBAA`) is accepted.
+     */
+    value?: string;
+    /**
+     * The initial color value for uncontrolled usage. Defaults to `#000000`.
+     */
+    defaultValue?: string;
+    /**
+     * Event handler fired when the color changes. Always receives a hex string.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * Fired when the swatch is activated. The swatch is only interactive when
+     * `type="color"` — its role is to open the parent ColorPicker panel. For all
+     * other types the swatch is a decorative preview and this is never called.
+     */
+    onSwatchClick?: () => void;
+    /**
+     * Display variant of the control. Defaults to `color-hex`.
+     */
+    type?: InputColorType;
+    /**
+     * Enables the alpha channel. Adds an alpha field and splits the swatch to
+     * preview the transparency against a checkerboard.
+     */
+    transparency?: boolean;
+    /**
+     * Property for changing the size of the control.
+     */
+    size?: InputColorSize;
+    /**
+     * Property for displaying a label above the control.
+     */
+    label?: string;
+    /**
+     * Unique identifier for the control. Used for accessibility linking.
+     */
+    id?: string;
+    /**
+     * Accessible label for screen readers when no visible label is present.
+     */
+    "aria-label"?: string;
+    /**
+     * Test identifier for the component.
+     */
+    testID?: string;
+}
+declare const InputColor: React.ForwardRefExoticComponent<InputColorProps & React.RefAttributes<HTMLDivElement>>;
+
+export { InputColor, type InputColorProps, type InputColorSize, type InputColorType };

package/native/index.d.ts

@@ -0,0 +1,66 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Display variant of the InputColor control. Maps 1:1 to the Figma `Type` prop:
+ * - `color`      → "Color only"          (swatch preview only, no editable field)
+ * - `color-hex`  → "Color + HEX"         (swatch + editable hex field)
+ * - `color-rgb`  → "Color + HSL/HSB/RGB" (swatch + editable R/G/B channels)
+ * - `hex`        → "HEX"                  (editable hex field only)
+ * - `rgb`        → "HSL/HSB/RGB"          (editable R/G/B channels only)
+ */
+type InputColorType = "color" | "color-hex" | "color-rgb" | "hex" | "rgb";
+type InputColorSize = "xl" | "lg" | "md" | "sm" | "xs";
+interface InputColorProps extends ThemeOverrideProps {
+    /**
+     * The current color value as a hex string (controlled mode), e.g. `#22A8C3`.
+     * When `transparency` is enabled an 8-digit hex (`#RRGGBBAA`) is accepted.
+     */
+    value?: string;
+    /**
+     * The initial color value for uncontrolled usage. Defaults to `#000000`.
+     */
+    defaultValue?: string;
+    /**
+     * Event handler fired when the color changes. Always receives a hex string.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * Fired when the swatch is activated. The swatch is only interactive when
+     * `type="color"` — its role is to open the parent ColorPicker panel. For all
+     * other types the swatch is a decorative preview and this is never called.
+     */
+    onSwatchClick?: () => void;
+    /**
+     * Display variant of the control. Defaults to `color-hex`.
+     */
+    type?: InputColorType;
+    /**
+     * Enables the alpha channel. Adds an alpha field and splits the swatch to
+     * preview the transparency against a checkerboard.
+     */
+    transparency?: boolean;
+    /**
+     * Property for changing the size of the control.
+     */
+    size?: InputColorSize;
+    /**
+     * Property for displaying a label above the control.
+     */
+    label?: string;
+    /**
+     * Unique identifier for the control. Used for accessibility linking.
+     */
+    id?: string;
+    /**
+     * Accessible label for screen readers when no visible label is present.
+     */
+    "aria-label"?: string;
+    /**
+     * Test identifier for the component.
+     */
+    testID?: string;
+}
+declare const InputColor: React.ForwardRefExoticComponent<InputColorProps & React.RefAttributes<HTMLDivElement>>;
+
+export { InputColor, type InputColorProps, type InputColorSize, type InputColorType };