@xsolla/xui-gradient-picker 0.204.0

package/README.md

@@ -0,0 +1,280 @@
+# Gradient Picker
+
+A cross-platform React gradient picker: a live preview track with draggable colour stops, per-stop colour and opacity editing via ColorPicker, and CSS-compatible gradient output.
+
+<!-- BEGIN:xui-mcp-instructions:gradient-picker -->
+
+A compound component for defining a CSS-style colour gradient. Combines a visual gradient preview track with draggable stop markers and integrates with ColorPicker to edit the colour and opacity of each stop individually. Supports three gradient types and up to five colour stops.
+
+### When to use
+
+- When a user needs to define a multi-colour gradient — background fills, banner overlays, avatar tints, UI theme customisation
+- In design tool contexts, theme editors, or advanced colour configuration panels where fine-grained gradient control is required
+- When the product supports gradient fills as a first-class input (e.g. a game customisation screen, a chart background picker)
+
+### When not to use
+
+- When a solid colour is sufficient — use ColorPicker instead
+- When only a simple two-colour linear gradient with fixed endpoints is needed and the user doesn't need to adjust stops — consider a simpler two-swatch input
+- In contexts where gradient complexity would overwhelm the user — hide behind an "Advanced" toggle
+
+### Content guidelines
+
+- Gradient type labels — use the standard CSS-adjacent names: "Linear", "Radial", "Angular" (or "Conic" if the product uses that term). Do not use internal technical names.
+- Stop position display — when a stop is active, show its position as a percentage (e.g. 0%, 50%, 100%) in a read-only or editable label near the marker or in the ColorPicker header. This helps users set precise positions numerically.
+- Minimum stops warning — if the user tries to remove the last stop, show a tooltip or brief inline message: "A gradient requires at least one stop" rather than silently blocking the action.
+
+### Behaviour guidelines
+
+- Adding stops — clicking on an empty area of the stop track adds a new stop at that position, interpolating its initial colour from the gradient at that point. The new stop immediately becomes Active. Adding is only permitted up to the product-defined maximum (5 in Figma).
+- Removing stops — a stop can be removed by dragging it off the track (up or down beyond a threshold) or via a delete action (e.g. pressing Delete / Backspace when the stop is active). A minimum of 1 stop must always remain; do not allow removing the last stop.
+- Dragging stops — a stop is dragged horizontally along the track. Position is expressed as a percentage (0%–100%). Stops cannot be dragged past each other — they swap order when they cross. Provide a smooth position update with no snap unless the product explicitly requires snapping to percentage increments.
+- Active stop ColorPicker — the ColorPicker panel opens below the component when a stop is activated. If the panel would push the component out of the viewport, position it above the track instead. Closing the ColorPicker (clicking outside, pressing Escape) deactivates the stop.
+- Gradient type change — switching Gradient type via the Select applies immediately to the preview without resetting stop positions or colours.
+- Angle / centre point — for Linear, the gradient angle should be adjustable (e.g. via a degree input or a rotation handle on the preview). For Radial, the centre point should be configurable. For Angular, the rotation angle and start point should be configurable. These controls are not shown in the Figma component directly but are part of the full implementation.
+- Real-time preview — every interaction (dragging a stop, changing a colour, switching gradient type, adjusting angle) must update the gradient preview in real time without requiring a confirm action.
+- Output format — the component outputs a CSS-compatible gradient string that can be applied directly as a background or background-image value. Provide a copy action to let the user copy the gradient string.
+
+### Accessibility
+
+- The stop track must be operable by keyboard. When a stop has focus, ← / → arrows move it by 1% increments; Shift+← / Shift+→ move it by 10% increments.
+- Each .GradientStop must have role=*"slider"* with aria-label identifying the stop (e.g. aria-label=*"Stop 1 position"*) and aria-valuenow / aria-valuemin=*"0"* / aria-valuemax=*"100"*.
+- The gradient type selector must have aria-label=*"Gradient type"*.
+- When a stop is activated and the ColorPicker opens, focus must move into the ColorPicker. When the ColorPicker closes, focus must return to the stop marker.
+- The gradient preview is decorative — it must have aria-hidden=*"true"* and not receive focus.
+- Adding a stop via keyboard: provide a button (e.g. *"+ Add stop"*) as a keyboard-accessible alternative to clicking on the track.
+- Removing a stop via keyboard: when a stop is active, Delete / Backspace removes it and focus moves to the adjacent stop or the track.
+- Do not rely on the visual gradient colour alone to communicate stop positions — always show numeric position values for screen reader users and users who cannot perceive colour differences in the gradient.
+
+### Gradient types
+
+The angle can only be controlled for linear gradients and angular gradients.
+
+### Stop hover
+
+While dragging a gradient stop, the row of the corresponding stop transitions into the active state.
+
+<!-- END:xui-mcp-instructions:gradient-picker -->
+
+## Installation
+
+```bash
+npm install @xsolla/xui-gradient-picker
+```
+
+## Demo
+
+### Basic Gradient Picker
+
+```tsx
+import * as React from "react";
+import { GradientPicker } from "@xsolla/xui-gradient-picker";
+
+export default function BasicGradientPicker() {
+  return <GradientPicker onChange={({ css }) => console.log(css)} />;
+}
+```
+
+### Controlled Gradient Picker
+
+```tsx
+import * as React from "react";
+import {
+  GradientPicker,
+  DEFAULT_GRADIENT,
+  toCssGradient,
+  type GradientValue,
+} from "@xsolla/xui-gradient-picker";
+
+export default function ControlledGradientPicker() {
+  const [gradient, setGradient] = React.useState<GradientValue>(
+    DEFAULT_GRADIENT
+  );
+
+  return (
+    <>
+      <GradientPicker
+        value={gradient}
+        onChange={({ value }) => setGradient(value)}
+      />
+      <div style={{ backgroundImage: toCssGradient(gradient) }} />
+    </>
+  );
+}
+```
+
+### Radial Gradient
+
+```tsx
+import * as React from "react";
+import { GradientPicker } from "@xsolla/xui-gradient-picker";
+
+export default function RadialGradient() {
+  return (
+    <GradientPicker
+      defaultValue={{
+        type: "radial",
+        angle: 0,
+        stops: [
+          { id: "stop-1", color: "#D9D9D9", position: 0, opacity: 100 },
+          { id: "stop-2", color: "#22A8C3", position: 100, opacity: 100 },
+        ],
+      }}
+    />
+  );
+}
+```
+
+Radial gradients have no rotation, so the angle field is hidden for them.
+
+### Angular ("Conic") Gradient
+
+```tsx
+import * as React from "react";
+import { GradientPicker } from "@xsolla/xui-gradient-picker";
+
+export default function AngularGradient() {
+  return (
+    <GradientPicker
+      typeLabels={{ angular: "Conic gradient" }}
+      onChange={({ css }) => console.log(css)}
+    />
+  );
+}
+```
+
+## Anatomy
+
+```jsx
+import { GradientPicker } from "@xsolla/xui-gradient-picker";
+
+<GradientPicker
+  value={gradient} // Controlled gradient value
+  defaultValue={initial} // Initial value for uncontrolled usage
+  onChange={handleChange} // ({ value, css }) => void
+  gradientTypes={["linear", "radial", "angular"]} // Types offered in the selector
+  typeLabels={{ angular: "Conic gradient" }} // Option label overrides
+  minStops={1} // Floor for removal
+  maxStops={5} // Ceiling for adding
+  disabled={false} // Disable every control
+  stopsLabel="Stops" // Heading above the stop list
+/>;
+```
+
+## API Reference
+
+### GradientPicker
+
+**GradientPickerProps:**
+
+| Prop           | Type                                            | Default                              | Description                                                                                                   |
+| :------------- | :---------------------------------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------ |
+| `testID`       | `string`                                        | —                                    | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |
+| value          | `GradientValue`                                 | —                                    | Controlled gradient value. Pair with `onChange`.                                                              |
+| defaultValue   | `GradientValue`                                 | `DEFAULT_GRADIENT`                   | Initial gradient value for uncontrolled usage.                                                                |
+| onChange       | `(event: GradientPickerChangeEvent) => void`    | —                                    | Fired on every interaction. Receives the new value and its CSS string.                                        |
+| gradientTypes  | `GradientType[]`                                | `["linear", "radial", "angular"]`    | Gradient types offered in the selector, in display order.                                                     |
+| typeLabels     | `Partial<Record<GradientType, string>>`         | —                                    | Overrides for the gradient-type option labels.                                                                |
+| minStops       | `number`                                        | `1`                                  | Smallest number of stops the user may reduce the gradient to.                                                 |
+| maxStops       | `number`                                        | `5`                                  | Largest number of stops the user may add.                                                                     |
+| disabled       | `boolean`                                       | `false`                              | Disables every control and blocks track interaction.                                                          |
+| typeAriaLabel  | `string`                                        | `"Gradient type"`                    | Accessible name for the gradient-type selector.                                                               |
+| angleAriaLabel | `string`                                        | `"Gradient angle"`                   | Accessible name for the angle field.                                                                          |
+| stopsLabel     | `string`                                        | `"Stops"`                            | Heading rendered above the stop list.                                                                         |
+
+### Types
+
+```typescript
+type GradientType = "linear" | "radial" | "angular";
+
+interface GradientStop {
+  id: string; // Stable identity, survives reordering
+  color: string; // "#RRGGBB"
+  position: number; // 0–100 (percent)
+  opacity: number; // 0–100 (percent)
+}
+
+interface GradientValue {
+  type: GradientType;
+  angle: number; // Degrees; ignored for "radial"
+  stops: GradientStop[];
+}
+
+interface GradientPickerChangeEvent {
+  value: GradientValue;
+  css: string; // e.g. "linear-gradient(0deg, #D9D9D9 0%, #22A8C3 100%)"
+}
+```
+
+### Exported helpers
+
+Every gradient operation is a pure function, so a consuming surface can render
+or transform a gradient without mounting the component.
+
+| Helper                                | Signature                                                        | Description                                                                       |
+| :------------------------------------ | :--------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
+| `toCssGradient(value)`                | `(value: GradientValue) => string`                               | Serialises to `linear-gradient()` / `radial-gradient()` / `conic-gradient()`.     |
+| `toPreviewCssGradient(value)`         | `(value: GradientValue) => string`                               | Left-to-right ramp used by the preview track, regardless of gradient type.        |
+| `interpolateColorAt(stops, position)` | `(stops: GradientStop[], position: number) => { color, opacity }` | Samples the gradient — the colour a stop added at `position` inherits.            |
+| `addStopAt(stops, position, max)`     | `(…) => GradientStop[]`                                          | Adds an interpolated stop; returns the input array unchanged at `max`.            |
+| `removeStop(stops, id, min)`          | `(…) => GradientStop[]`                                          | Removes by id; returns the input array unchanged at `min`.                        |
+| `updateStop(stops, id, patch)`        | `(…) => GradientStop[]`                                          | Applies a clamped, normalised patch to one stop.                                  |
+| `sortStops(stops)`                    | `(stops: GradientStop[]) => GradientStop[]`                      | Position order, stable on ties, non-mutating.                                     |
+| `supportsAngle(type)`                 | `(type: GradientType) => boolean`                                | `false` for `radial` — the angle field is hidden for it.                          |
+| `DEFAULT_GRADIENT`                    | `GradientValue`                                                  | The two-stop `#D9D9D9 → #22A8C3` linear ramp from the Figma component.            |
+
+## CSS output
+
+| Type      | Output                                                          |
+| :-------- | :-------------------------------------------------------------- |
+| `linear`  | `linear-gradient(<angle>deg, <stops>)`                          |
+| `radial`  | `radial-gradient(circle, <stops>)`                              |
+| `angular` | `conic-gradient(from <angle>deg, <stops>)`                      |
+
+A fully opaque stop serialises to its hex value; a partially transparent stop
+serialises to `rgba()`. A gradient with a single stop is emitted twice (`0%` and
+`100%`) because CSS gradients require at least two colour stops.
+
+## Keyboard navigation
+
+| Key                       | Action                                            |
+| :------------------------ | :------------------------------------------------ |
+| Tab / Shift+Tab           | Move focus between markers, fields and buttons    |
+| ← / → (marker focused)    | Move the stop by 1%                               |
+| Shift+← / Shift+→         | Move the stop by 10%                              |
+| Home / End                | Jump the stop to 0% / 100%                        |
+| Enter / Space             | Activate the stop and open its ColorPicker        |
+| Delete / Backspace        | Remove the stop (blocked at `minStops`)           |
+| Escape                    | Close the ColorPicker; focus returns to the marker |
+
+## Theme
+
+- The panel background comes from the `layer/float` colour token (`theme.colors.layer.float`) so it reads as a floating surface in both light and dark mode, matching ColorPicker.
+- Corner radius comes from `theme.shape.contextMenu.lg.borderRadius`.
+- Stop markers use `theme.colors.background.primary` for their ring so the stop colour stays legible against any track fill.
+
+## Accessibility
+
+- Each stop marker is a `role="slider"` with `aria-label="Stop N position"`, `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax="100"` and `aria-valuetext="N%"`.
+- The preview track is `aria-hidden="true"` and is not focusable — position is always available numerically from the per-stop position field and the marker's `aria-valuetext`.
+- The **+** button is the keyboard-accessible alternative to clicking the track; it drops the new stop in the widest gap.
+- Closing the ColorPicker (Escape) returns focus to the marker that opened it.
+- The angle field and every per-stop field carry an explicit `aria-label`.
+
+## Known gaps
+
+These are deliberate v1 boundaries, tracked as follow-ups:
+
+- **Type selector naming** — `SelectProps` has no `aria-label`, so the accessible
+  name for the gradient-type selector is carried by a wrapping
+  `role="group"` element. Once Select accepts `aria-label`, move it onto the
+  combobox itself.
+- **ColorPicker placement** — the active-stop ColorPicker renders inline below
+  the stop list. The spec's "flip above the track when the panel would leave the
+  viewport" behaviour needs a floating-popover layer.
+- **Pointer drag is web-only** — keyboard operation works everywhere; marker
+  dragging uses web mouse events. React Native `PanResponder` parity is a
+  follow-up, matching the approach `Slider` takes.
+- **Radial centre point / angular start point** are not exposed. They are not in
+  the Figma component; the behaviour spec lists them as part of a fuller
+  implementation.

package/native/index.d.mts

@@ -0,0 +1,243 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+/**
+ * Supported gradient geometries.
+ *
+ * `angular` maps to the CSS `conic-gradient()` function. Some products call
+ * this "Conic" — use `typeLabels` to relabel it without changing the value.
+ */
+type GradientType = "linear" | "radial" | "angular";
+/**
+ * A single colour stop on the gradient track.
+ */
+interface GradientStop {
+    /**
+     * Stable identity for the stop. Used as the React key and as the handle for
+     * update / remove operations, so it must survive reordering.
+     */
+    id: string;
+    /**
+     * Stop colour as a `#RRGGBB` hex string. Opacity is tracked separately in
+     * `opacity` so the hex field stays human-editable.
+     */
+    color: string;
+    /**
+     * Position along the track, `0`–`100` (percent).
+     */
+    position: number;
+    /**
+     * Stop opacity, `0`–`100` (percent).
+     */
+    opacity: number;
+}
+/**
+ * The full gradient definition rendered by the picker.
+ */
+interface GradientValue {
+    /**
+     * Gradient geometry.
+     */
+    type: GradientType;
+    /**
+     * Rotation in degrees. Only meaningful for `linear` and `angular` — a radial
+     * gradient has no angle, so the angle field is hidden for it.
+     */
+    angle: number;
+    /**
+     * Colour stops. Order is not significant: the component sorts by `position`
+     * when serialising, so stops may swap as the user drags them past each other.
+     */
+    stops: GradientStop[];
+}
+/**
+ * Payload emitted on every gradient change.
+ */
+interface GradientPickerChangeEvent {
+    /**
+     * The new gradient definition.
+     */
+    value: GradientValue;
+    /**
+     * The same gradient serialised as a CSS-compatible string, ready to drop into
+     * a `background` / `background-image` declaration.
+     */
+    css: string;
+}
+interface GradientPickerProps extends ThemeOverrideProps {
+    /**
+     * Controlled gradient value. Pair with `onChange`.
+     */
+    value?: GradientValue;
+    /**
+     * Initial gradient value for uncontrolled usage.
+     */
+    defaultValue?: GradientValue;
+    /**
+     * Called on every interaction — stop drag, colour edit, opacity edit,
+     * gradient-type switch, angle change, add / remove stop.
+     */
+    onChange?: (event: GradientPickerChangeEvent) => void;
+    /**
+     * Gradient types offered in the type selector, in display order.
+     * @default ["linear", "radial", "angular"]
+     */
+    gradientTypes?: GradientType[];
+    /**
+     * Overrides for the gradient-type option labels — e.g. `{ angular: "Conic gradient" }`
+     * when the product uses the CSS term.
+     */
+    typeLabels?: Partial<Record<GradientType, string>>;
+    /**
+     * Smallest number of stops the user may reduce the gradient to. The remove
+     * control is disabled once this floor is reached.
+     * @default 1
+     */
+    minStops?: number;
+    /**
+     * Largest number of stops the user may add. The add control is disabled once
+     * this ceiling is reached.
+     * @default 5
+     */
+    maxStops?: number;
+    /**
+     * Disables every control and blocks track interaction.
+     */
+    disabled?: boolean;
+    /**
+     * Accessible label for the gradient-type selector.
+     * @default "Gradient type"
+     */
+    typeAriaLabel?: string;
+    /**
+     * Accessible label for the angle field.
+     * @default "Gradient angle"
+     */
+    angleAriaLabel?: string;
+    /**
+     * Heading rendered above the stop list.
+     * @default "Stops"
+     */
+    stopsLabel?: string;
+    testID?: string;
+}
+
+/**
+ * A compound control for defining a CSS gradient.
+ *
+ * Combines a live preview track carrying draggable stop markers with a per-stop
+ * row editor (position, colour, opacity) and an integrated `ColorPicker` for
+ * the active stop. Supports linear, radial and angular (CSS `conic`) gradients
+ * and 1–5 colour stops.
+ *
+ * Every interaction updates the preview immediately — there is no confirm step —
+ * and the gradient is emitted both as structured data and as a ready-to-apply
+ * CSS string.
+ *
+ * @example
+ * ```tsx
+ * const [gradient, setGradient] = useState<GradientValue>();
+ *
+ * <GradientPicker
+ *   value={gradient}
+ *   onChange={({ value, css }) => {
+ *     setGradient(value);
+ *     setBackground(css); // e.g. "linear-gradient(0deg, #D9D9D9 0%, #22A8C3 100%)"
+ *   }}
+ * />
+ * ```
+ */
+declare const GradientPicker: React.FC<GradientPickerProps>;
+
+interface GradientStopMarkerProps extends ThemeOverrideProps {
+    /**
+     * The stop this marker represents.
+     */
+    stop: GradientStop;
+    /**
+     * 1-based index used to build the accessible name (`"Stop 2 position"`).
+     */
+    index: number;
+    /**
+     * Whether this stop is the one currently being edited in the ColorPicker.
+     */
+    active?: boolean;
+    /**
+     * Whether the whole picker is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Pointer-down on the marker — the parent owns the drag because it owns the
+     * track geometry.
+     */
+    onDragStart?: (event: React.MouseEvent) => void;
+    /**
+     * Keyboard interaction on the marker. Handled by the parent so that arrow
+     * keys, Home/End, Enter/Space and Delete/Backspace share one implementation.
+     */
+    onKeyDown?: (event: React.KeyboardEvent) => void;
+}
+/**
+ * A single draggable handle on the gradient preview track.
+ *
+ * Exposed as `role="slider"` over the `0`–`100` position range so the stop can
+ * be moved with the keyboard alone, and so its numeric position is announced —
+ * the visual gradient must never be the only carrier of that information.
+ */
+declare const GradientStopMarker: React.FC<GradientStopMarkerProps>;
+
+/**
+ * Returns the stops ordered by position without mutating the input array.
+ * Ties keep their original relative order, so two stops parked on the same
+ * percent do not flicker while one of them is being dragged.
+ */
+declare const sortStops: (stops: GradientStop[]) => GradientStop[];
+/**
+ * Serialises the gradient to a CSS-compatible string usable as a `background`
+ * or `background-image` value.
+ */
+declare const toCssGradient: (value: GradientValue) => string;
+/**
+ * The gradient rendered inside the horizontal preview track. The track always
+ * reads left-to-right regardless of gradient type, so the user can see stop
+ * ordering while dragging — the type-specific rendering is what `toCssGradient`
+ * produces for the consuming surface.
+ */
+declare const toPreviewCssGradient: (value: GradientValue) => string;
+/**
+ * Whether the given gradient type exposes an angle control. Radial gradients
+ * have no rotation, so the angle field is hidden for them.
+ */
+declare const supportsAngle: (value: GradientValue["type"]) => boolean;
+/**
+ * Samples the gradient at `position` (`0`–`100`) and returns the interpolated
+ * colour + opacity. Used to give a newly added stop the colour the gradient
+ * already had at that point, so adding a stop never visibly changes the ramp.
+ */
+declare const interpolateColorAt: (stops: GradientStop[], position: number) => {
+    color: string;
+    opacity: number;
+};
+/**
+ * Adds a stop at `position`, taking its colour from the gradient at that point.
+ * Returns the original array untouched when `maxStops` is already reached, so
+ * callers can compare by reference to detect a no-op.
+ */
+declare const addStopAt: (stops: GradientStop[], position: number, maxStops: number) => GradientStop[];
+/**
+ * Removes a stop by id. Returns the original array when the removal would drop
+ * below `minStops`, or when the id is unknown.
+ */
+declare const removeStop: (stops: GradientStop[], id: string, minStops: number) => GradientStop[];
+/**
+ * Applies a partial update to a single stop, clamping position and opacity and
+ * normalising the hex colour.
+ */
+declare const updateStop: (stops: GradientStop[], id: string, patch: Partial<Omit<GradientStop, "id">>) => GradientStop[];
+/**
+ * The default gradient — the two-stop `#D9D9D9 → #22A8C3` linear ramp from the
+ * Figma component.
+ */
+declare const DEFAULT_GRADIENT: GradientValue;
+
+export { DEFAULT_GRADIENT, GradientPicker, type GradientPickerChangeEvent, type GradientPickerProps, type GradientStop, GradientStopMarker, type GradientStopMarkerProps, type GradientType, type GradientValue, addStopAt, interpolateColorAt, removeStop, sortStops, supportsAngle, toCssGradient, toPreviewCssGradient, updateStop };