@xsolla/xui-color-picker 0.174.3 → 0.176.0

package/README.md

@@ -1,6 +1,68 @@
 # Color Picker
 
 A cross-platform React color picker component with a visual selection area, format switching, and color value controls.
+<!-- BEGIN:xui-mcp-instructions:color-picker -->
+A compound component that lets users select a colour through a combination of a gradient canvas, hue and alpha sliders, a numeric input bar, and an optional eyedropper. Supports four colour formats and an optional alpha channel. Designed to be embedded in a popover, modal, or panel triggered by a colour swatch button.
+
+### When to use
+- When a user needs to pick an arbitrary colour — theme customisation, avatar backgrounds, design tools, data visualisation palettes
+- When the product supports branded colour selection with precise numeric input
+- When alpha (opacity) control is part of the feature requirement
+
+### When not to use
+- When the user must choose from a fixed set of colours — use a Select with colour options instead
+- When space is constrained and a full picker is not feasible — offer a hex input field paired with a colour swatch preview
+- As an inline always-visible element on a page — ColorPicker is heavy; embed it in a popover triggered by a swatch button
+
+### Content guidelines
+- Trigger button — the swatch that opens ColorPicker must show the current selected colour as its fill. Pair it with a label or tooltip (*"Choose colour"*) for clarity.
+- Format selector — no visible label is needed inside the Select; the format name itself (HEX, RGB, etc.) acts as the label.
+- Input placeholders — for HEX use #000000; for channel fields use 0. Do not use descriptive placeholder text inside narrow numeric inputs — it will be cut off.
+- Extra content heading — if the slot contains a palette or team swatches, add a short section label above the slot in the popover header, not inside the slot itself.
+
+### Behaviour guidelines
+- Canvas interaction — clicking anywhere on the colour canvas moves the handle to that position and updates all fields immediately. The handle must be draggable with both mouse and touch. Dragging outside the canvas bounds clamps the value to the nearest edge rather than throwing an error.
+- Hue slider — dragging the hue handle updates the canvas background gradient in real time. The current saturation and brightness positions on the canvas are preserved when hue changes so the colour shifts smoothly.
+- Alpha slider — the track background is a gradient from transparent to the current fully-opaque colour, overlaid on a checkerboard pattern. Moving the handle updates the A channel across all input fields.
+- Format switching — switching the format in the Select reformats the input field values to the new format. The colour itself does not change; canvas and slider positions are preserved.
+- Manual input — edits in any input field should update the canvas and sliders in real time as the user types, but commit only on blur, Enter, or Tab. Invalid entries (out-of-range values, malformed HEX strings) are silently clamped or rejected, restoring the last valid value on blur.
+- HEX normalisation — accept 3-character shorthand (#F50 → #FF5500) and 6-/8-character full form. Normalise to uppercase on commit.
+- Copy action — the copy Icon button copies the current colour value to the clipboard in the active format string (e.g. #FF5500, rgb(255, 85, 0), hsl(20, 100%, 50%)). Show a brief confirmation (tooltip or button state change) after copy.
+- Eyedropper flow — after sampling, focus returns to the ColorPicker and all fields update to the picked colour. The format selector retains its current value.
+- Magnifier — the internal .item-colorMagnifier sub-component appears during eyedropper sampling and shows a zoomed pixel grid around the cursor. It has no configurable props at the ColorPicker level.
+- Popover placement — ColorPicker is typically opened from a small colour swatch trigger button. Position the popover so it does not clip the viewport; prefer bottom-start or bottom-end, with top-start / top-end as fallback. The popover width is fixed at 380 px.
+- Closing — the picker closes on: clicking outside the popover, pressing Escape, or an explicit confirm/cancel action if the integration requires it. Live-apply vs confirm-on-close is a product decision — document the chosen behaviour per feature.
+
+### Accessibility
+- The colour canvas handle must have role=*"slider"* with aria-label=*"Colour"* and paired aria-valuenow / aria-valuemin / aria-valuemax attributes for both the horizontal (saturation) and vertical (brightness/lightness) axes. Expose both axes as separate sliders if a single 2D handle is not supported by the target assistive technology.
+- Hue and alpha sliders must each carry role=*"slider"* with aria-label=*"Hue"* / aria-label=*"Opacity"* and aria-valuetext showing the human-readable value (e.g. *"120°"*, *"75%"*).
+- Each numeric input field must have a programmatic label (aria-label) identifying the channel — *"Red"*, *"Green"*, *"Blue"*, *"Alpha"*, *"Hue"*, *"Saturation"*, *"Lightness"*, *"Hex colour"*, etc.
+- The format selector must have aria-label=*"Colour format"*.
+- The eyedropper button must have aria-label=*"Pick colour from screen"*.
+- The copy button must have aria-label=*"Copy colour value"*.
+- If the EyeDropper API is unavailable, hide the button entirely rather than disabling it without explanation.
+
+### Eyedropper
+- When Eyedropper=True, an eyedropper Icon button appears to the left of the sliders. Clicking it activates the native EyeDropper API (where supported), allowing the user to sample any pixel on screen. The picked colour immediately populates all fields and updates the canvas.
+
+Browser support for the EyeDropper API must be checked at runtime. When unsupported, hide the button entirely (Eyedropper=False) rather than showing a disabled control with no explanation.
+
+### Keyboard navigation
+- Tab / Shift+Tab
+- Move focus between canvas handle, sliders, format selector, and input fields
+- Arrow keys (canvas focused)
+- Move the colour handle 1 px in the pressed direction
+- Arrow keys (slider focused)
+- Increment / decrement hue or alpha by 1 unit
+- Enter / Space (eyedropper button)
+- Activate eyedropper
+- Enter (input focused)
+- Commit the typed value
+- Tab (input focused)
+- Commit value and move focus to the next field
+- Escape
+- Close the popover (if open) without committing uncommitted input
+<!-- END:xui-mcp-instructions:color-picker -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-color-picker",
-  "version": "0.174.3",
+  "version": "0.176.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,11 +13,11 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-button": "0.174.3",
-    "@xsolla/xui-core": "0.174.3",
-    "@xsolla/xui-input": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3",
-    "@xsolla/xui-select": "0.174.3"
+    "@xsolla/xui-button": "0.176.0",
+    "@xsolla/xui-core": "0.176.0",
+    "@xsolla/xui-input": "0.176.0",
+    "@xsolla/xui-primitives-core": "0.176.0",
+    "@xsolla/xui-select": "0.176.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0"