@galaxy-io/dls 1.6.1 → 2.0.0

package/dist/inputs/SliderInput.d.ts

@@ -1,39 +1,159 @@
-import { InputSize, InputVariant } from "./Input";
-export interface SliderInputProps {
+import { type AriaAttributes, type CSSProperties } from "react";
+/** Canonical rungs; SliderInput supports all five. The track area is the rung height. */
+export declare enum SliderInputSize {
+    /** 20px track area, 2px rail, 10px thumb. */
+    X_SMALL = "X_SMALL",
+    /** 24px track area, 2px rail, 12px thumb. */
+    SMALL = "SMALL",
+    /** 32px track area, 4px rail, 14px thumb. The default. */
+    MEDIUM = "MEDIUM",
+    /** 36px track area, 4px rail, 16px thumb. */
+    LARGE = "LARGE",
+    /** 40px track area, 4px rail, 18px thumb. */
+    X_LARGE = "X_LARGE"
+}
+/** Fill of the unfilled rail (Constitution V-A surface set; 1.x InputVariant unchanged). */
+export declare enum SliderInputVariant {
+    /** `background.base` fill. */
+    BASE = "BASE",
+    /** `background.primary` fill. The default. */
+    PRIMARY = "PRIMARY",
+    /** `background.secondary` fill. */
+    SECONDARY = "SECONDARY",
+    /** `background.tertiary` fill. */
+    TERTIARY = "TERTIARY"
+}
+/** A `[low, high]` pair; `low <= high`. */
+export type SliderInputRange = [low: number, high: number];
+/** A tick on the rail. */
+export interface SliderInputMark {
+    /** Position on the rail, in value units. */
+    value: number;
+    /** Text under the tick. Omit for an unlabeled tick. */
+    label?: string;
+}
+/** Every prop except the value quartet; exported as a helper type. */
+export interface SliderInputBaseProps extends AriaAttributes {
     /**
-     * Track color. The filled portion and the handle are state colors and stay
-     * `icon.primary`. @default InputVariant.PRIMARY
+     * Lowest value.
+     * @default 0
      */
-    variant?: InputVariant;
-    /** Rail and handle size — 2/6, 3/8 or 4/10px. @default InputSize.MEDIUM */
-    size?: InputSize;
-    label?: string;
-    /** Adds an info icon beside the label with this content on hover. */
-    labelTooltip?: string | React.ReactNode;
-    /** Controlled value. Clamped into `[min, max]`. */
-    value: number;
-    /** Fires continuously while dragging, not just on release. */
-    onChange: (value: number) => void;
-    /** Drag started — useful for pausing an expensive live preview. */
-    onInteractionStart?: () => void;
-    /** Drag finished — commit the value here if `onChange` is too chatty. */
-    onInteractionEnd?: () => void;
-    /** @default 0 */
     min?: number;
-    /** @default 100 */
+    /**
+     * Highest value. Values below `min` are raised to `min`.
+     * @default 100
+     */
     max?: number;
-    /** Increment the thumb snaps to. @default 1 */
+    /**
+     * Increment the value snaps to, counted from `min`. Values ≤ 0 mean `1`.
+     * @default 1
+     */
     step?: number;
+    /** Ticks on the rail at these values, each with an optional label under it. Marks outside `[min, max]` are ignored. */
+    marks?: SliderInputMark[];
+    /**
+     * Text for a value: the tooltip and the screen-reader value (`aria-valuetext`). Use it for units ("40%", "120 ms").
+     * @default String
+     */
+    formatValue?: (value: number) => string;
+    /**
+     * Shows the formatted value in a `Tooltip` above a thumb while it is hovered, focused or dragged.
+     * @default false
+     */
+    hasValueTooltip?: boolean;
+    /**
+     * Control rung: the track area is 20 / 24 / 32 / 36 / 40px tall; the rail and thumb scale with it.
+     * @default SliderInputSize.MEDIUM
+     */
+    size?: SliderInputSize;
+    /**
+     * Fill of the unfilled rail, from the surface set. Ignored with `isGhost`.
+     * @default SliderInputVariant.PRIMARY
+     */
+    variant?: SliderInputVariant;
+    /**
+     * Ghost rail: the unfilled rail has no fill and keeps its hairline (1.x `TRANSPARENT`). For a
+     * slider on a surface whose own fill should show through.
+     * @default false
+     */
+    isGhost?: boolean;
+    /** Label above the slider, rendered through `Field`. For a description or a horizontal layout, wrap it in `Field` instead. */
+    label?: string;
+    /** Message from the app, shown under the slider through `Field`. Also turns the rail's hairline red and sets `aria-invalid`. */
+    error?: string;
+    /**
+     * Error hairline and `aria-invalid` without a message. `error` implies it.
+     * @default false
+     */
+    isError?: boolean;
+    /**
+     * Thumbs are not focusable and nothing moves. Shows the disabled look.
+     * @default false
+     */
     isDisabled?: boolean;
-    /** A number is px. */
-    width?: number | string;
+    /**
+     * Thumbs are focusable and announce the value, but pointer and keys change nothing.
+     * @default false
+     */
+    isReadOnly?: boolean;
+    /**
+     * Required marker on the `label` (via `Field`). It does no validation.
+     * @default false
+     */
+    isRequired?: boolean;
+    /**
+     * Stretch to the parent's width. Without it, the slider is 200px wide.
+     * @default false
+     */
     fillWidth?: boolean;
+    /** Accessible name when there is no visible label (no `label` and no wrapping `Field`). */
+    ariaLabel?: string;
+    /** DOM id of the thumb (single) or of the group (range). A wrapping `Field`'s id wins. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the root `Slider` element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root: the `Field` wrapper when SliderInput renders one, otherwise the slider. */
+    className?: string;
+    /** Inline style on the root; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** One thumb: the value is a number. */
+interface SliderInputSingleProps {
+    /**
+     * Two thumbs: the value is a `[low, high]` tuple and the fill runs between them.
+     * @default false
+     */
+    isRange?: false;
+    /** Controlled value. Drawn clamped to `[min, max]` and snapped to `step`. Pass it with `onChange`. */
+    value?: number;
+    /**
+     * Initial value while uncontrolled.
+     * @default min
+     */
+    defaultValue?: number;
+    /** Called with the snapped value on every pointer move and key press that changes it. */
+    onChange?: (value: number) => void;
+    /** Called with the final value when a drag ends and after each keyboard change. Commit expensive work here. */
+    onChangeEnd?: (value: number) => void;
+}
+/** Two thumbs: the value is a `[low, high]` tuple. */
+interface SliderInputRangeProps {
+    /** Two thumbs: the value is a `[low, high]` tuple and the fill runs between them. */
+    isRange: true;
+    /** Controlled `[low, high]` value. Drawn clamped to `[min, max]` and snapped to `step`. Pass it with `onChange`. */
+    value?: SliderInputRange;
+    /**
+     * Initial `[low, high]` value while uncontrolled.
+     * @default [min, max]
+     */
+    defaultValue?: SliderInputRange;
+    /** Called with the snapped `[low, high]` value on every pointer move and key press that changes it. */
+    onChange?: (value: SliderInputRange) => void;
+    /** Called with the final `[low, high]` value when a drag ends and after each keyboard change. */
+    onChangeEnd?: (value: SliderInputRange) => void;
 }
-/**
- * A drag-to-set numeric slider. Fully controlled.
- *
- * `onChange` fires on every pointer move. When each change is expensive, drive
- * a preview from it and commit on `onInteractionEnd`.
- */
-declare const SliderInput: ({ variant, size, label, labelTooltip, value, onChange, onInteractionStart, onInteractionEnd, min, max, step, isDisabled, width, fillWidth, }: SliderInputProps) => import("react").JSX.Element;
+/** SliderInput props: `isRange` fixes the type of the value quartet. */
+export type SliderInputProps = SliderInputBaseProps & (SliderInputSingleProps | SliderInputRangeProps);
+/** A number, or a `[low, high]` range, set by dragging thumbs along a rail. */
+declare const SliderInput: import("react").ForwardRefExoticComponent<SliderInputProps & import("react").RefAttributes<HTMLDivElement>>;
 export default SliderInput;