@xsolla/xui-color-picker 0.99.0 → 0.100.0

package/README.md

@@ -1,36 +1,210 @@
-# @xsolla/xui-color-picker
+---
+title: Color Picker
+subtitle: Color selection with multiple formats.
+description: A cross-platform React color picker with support for hex, RGB, HSL, and HSB formats, alpha channel, and eyedropper tool.
+---
 
-HSB colour picker with hue/alpha sliders, format switching, and optional eyedropper.
+# Color Picker
+
+A cross-platform React color picker component with a visual selection area, format switching, and color value controls.
 
 ## Installation
 
 ```bash
+npm install @xsolla/xui-color-picker
+# or
 yarn add @xsolla/xui-color-picker
 ```
 
-## Usage
+## Demo
+
+### Basic Color Picker
+
+```tsx
+import * as React from 'react';
+import { ColorPicker } from '@xsolla/xui-color-picker';
+
+export default function BasicColorPicker() {
+  const [color, setColor] = React.useState('#66E6FFFF');
+
+  return (
+    <ColorPicker
+      value={color}
+      onChange={({ valueInInitialFormat }) => setColor(valueInInitialFormat)}
+    />
+  );
+}
+```
+
+### Without Alpha Channel
+
+```tsx
+import * as React from 'react';
+import { ColorPicker } from '@xsolla/xui-color-picker';
+
+export default function NoAlpha() {
+  return (
+    <ColorPicker
+      value="#FF5733"
+      alpha={false}
+      onChange={console.log}
+    />
+  );
+}
+```
+
+### With Eyedropper
 
 ```tsx
+import * as React from 'react';
+import { ColorPicker } from '@xsolla/xui-color-picker';
+
+export default function WithEyedropper() {
+  return (
+    <ColorPicker
+      value="#3498DB"
+      eyedropper
+      onChange={console.log}
+    />
+  );
+}
+```
+
+## Anatomy
+
+```jsx
 import { ColorPicker } from '@xsolla/xui-color-picker';
 
 <ColorPicker
-  value="#66E6FF"
-  colorFormat="hex"
-  onChange={({ valueInInitialFormat }) => console.log(valueInInitialFormat)}
+  value="#66E6FFFF"           // Initial color value
+  colorFormat="hex"           // Default format (hex, rgb, hsl, hsb)
+  alpha={true}                // Show alpha slider
+  eyedropper={false}          // Show eyedropper button
+  selectableFormats={['hex', 'hsl', 'rgb', 'hsb']} // Available formats
+  onChange={handleChange}     // Change callback
+  bottomContent={<Custom />}  // Custom content below controls
 />
 ```
 
-## Props
+## Examples
+
+### Custom Format Selection
+
+```tsx
+import * as React from 'react';
+import { ColorPicker } from '@xsolla/xui-color-picker';
+
+export default function CustomFormats() {
+  return (
+    <ColorPicker
+      value="#FF0000"
+      colorFormat="rgb"
+      selectableFormats={['rgb', 'hex']}
+      onChange={({ valueInCurrentFormat, currentColorFormat }) => {
+        console.log(`${currentColorFormat}: ${valueInCurrentFormat}`);
+      }}
+    />
+  );
+}
+```
+
+### With Bottom Content
+
+```tsx
+import * as React from 'react';
+import { ColorPicker } from '@xsolla/xui-color-picker';
+import { Button } from '@xsolla/xui-button';
+
+export default function WithBottomContent() {
+  const [color, setColor] = React.useState('#66E6FFFF');
+
+  return (
+    <ColorPicker
+      value={color}
+      onChange={({ valueInInitialFormat }) => setColor(valueInInitialFormat)}
+      bottomContent={
+        <Button size="sm" onPress={() => console.log('Applied:', color)}>
+          Apply Color
+        </Button>
+      }
+    />
+  );
+}
+```
+
+### Controlled Color Picker
+
+```tsx
+import * as React from 'react';
+import { ColorPicker } from '@xsolla/xui-color-picker';
+
+export default function ControlledPicker() {
+  const [color, setColor] = React.useState('#9B59B6FF');
+
+  const handleChange = ({ valueInInitialFormat, valueInCurrentFormat, currentColorFormat }) => {
+    console.log('Format:', currentColorFormat);
+    console.log('Current format value:', valueInCurrentFormat);
+    console.log('Initial format value:', valueInInitialFormat);
+    setColor(valueInInitialFormat);
+  };
+
+  return (
+    <div>
+      <p>Selected: {color}</p>
+      <ColorPicker value={color} onChange={handleChange} />
+    </div>
+  );
+}
+```
+
+## API Reference
 
 ### ColorPicker
 
+**ColorPickerProps:**
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | `"#66E6FFFF"` | Current colour value in any supported format |
-| `onChange` | `(event: ColorPickerChangeEvent) => void` | — | Called on every colour change with values in both initial and current formats |
-| `colorFormat` | `"hex" \| "rgb" \| "hsl" \| "hsb"` | `"hex"` | Default output format |
-| `selectableFormats` | `InputColorFormat[]` | all formats | Formats available in the format selector |
-| `alpha` | `boolean` | `true` | Enable the alpha (opacity) slider and channel input |
-| `eyedropper` | `boolean` | `false` | Show the native eyedropper tool button |
-| `bottomContent` | `ReactNode` | — | Custom content rendered at the bottom of the picker |
-| `copiedIcon` | `ReactElement` | — | Custom icon shown after copying the colour value |
+| :--- | :--- | :------ | :---------- |
+| value | `string` | `"#66E6FFFF"` | Color value in any supported format. |
+| colorFormat | `"hex" \| "rgb" \| "hsl" \| "hsb"` | `"hex"` | Default color format for output. |
+| alpha | `boolean` | `true` | Show alpha channel slider. |
+| eyedropper | `boolean` | `false` | Show eyedropper tool (web only). |
+| selectableFormats | `Array<"hex" \| "rgb" \| "hsl" \| "hsb">` | All formats | Available formats in dropdown. |
+| copiedIcon | `ReactNode` | - | Custom icon for copied state. |
+| bottomContent | `ReactNode` | - | Custom content below color controls. |
+| onChange | `(result: ColorChangeResult) => void` | - | Callback when color changes. |
+| testID | `string` | - | Test identifier. |
+
+**ColorChangeResult:**
+
+```typescript
+interface ColorChangeResult {
+  valueInInitialFormat: string;   // Color in original format
+  valueInCurrentFormat: string;   // Color in selected format
+  currentColorFormat: "hex" | "rgb" | "hsl" | "hsb";
+}
+```
+
+## Supported Formats
+
+| Format | Example | With Alpha |
+| :----- | :------ | :--------- |
+| hex | `#FF5733` | `#FF5733FF` |
+| rgb | `rgb(255, 87, 51)` | `rgba(255, 87, 51, 1)` |
+| hsl | `hsl(11, 100%, 60%)` | `hsla(11, 100%, 60%, 1)` |
+| hsb | `hsb(11, 80%, 100%)` | `hsba(11, 80%, 100%, 1)` |
+
+## Features
+
+- **Visual picker**: Click and drag on the color area to select hue/saturation
+- **Sliders**: Hue and alpha channel sliders
+- **Format switching**: Toggle between hex, RGB, HSL, HSB via dropdown
+- **Copy button**: Copy current color value to clipboard
+- **Reset button**: Reset to initial color value
+- **Eyedropper**: Pick colors from anywhere on screen (web only, requires browser support)
+
+## Accessibility
+
+- Copy and reset buttons have accessible labels
+- Keyboard navigation supported for all controls
+- Color values are displayed in text inputs for manual entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-color-picker",
-  "version": "0.99.0",
+  "version": "0.100.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -10,11 +10,11 @@
     "build:native": "PLATFORM=native tsup"
   },
   "dependencies": {
-    "@xsolla/xui-button": "0.99.0",
-    "@xsolla/xui-core": "0.99.0",
-    "@xsolla/xui-input": "0.99.0",
-    "@xsolla/xui-primitives-core": "0.99.0",
-    "@xsolla/xui-select": "0.99.0"
+    "@xsolla/xui-button": "0.100.0",
+    "@xsolla/xui-core": "0.100.0",
+    "@xsolla/xui-input": "0.100.0",
+    "@xsolla/xui-primitives-core": "0.100.0",
+    "@xsolla/xui-select": "0.100.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0"