@xsolla/xui-gradient-picker 0.204.0

package/web/index.d.ts

@@ -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 };