@bloomreach/react-banana-ui 1.35.1 → 1.37.0

package/dist/components/inputs/slider/internal/utils/slider.helpers.d.ts

@@ -0,0 +1,227 @@
+import { Mark, SliderProps, SliderValue } from '../../slider/slider.types';
+import type * as React from 'react';
+/**
+ * Number of pointer-move events that must fire before a drag is considered intentional.
+ * Prevents accidental drags from triggering the dragging visual state on click.
+ */
+export declare const INTENTIONAL_DRAG_COUNT_THRESHOLD = 2;
+/**
+ * CSS property mappings for each slider axis orientation.
+ * Each axis defines how to position an element (`offset`) and size the track (`leap`)
+ * using the appropriate CSS properties for that direction.
+ */
+export declare const AXIS_PROPS: {
+    readonly horizontal: {
+        readonly leap: (percent: number) => {
+            width: string;
+        };
+        readonly offset: (percent: number) => {
+            left: string;
+        };
+    };
+    readonly 'horizontal-reverse': {
+        readonly leap: (percent: number) => {
+            width: string;
+        };
+        readonly offset: (percent: number) => {
+            right: string;
+        };
+    };
+    readonly vertical: {
+        readonly leap: (percent: number) => {
+            height: string;
+        };
+        readonly offset: (percent: number) => {
+            bottom: string;
+        };
+    };
+};
+/** Identity function used as the default `scale` transform. */
+export declare const identity: (value: number) => number;
+/**
+ * Clamps a value between a minimum and maximum bound.
+ *
+ * @param value - The value to clamp.
+ * @param min - Lower bound (defaults to `Number.MIN_SAFE_INTEGER`).
+ * @param max - Upper bound (defaults to `Number.MAX_SAFE_INTEGER`).
+ * @returns The clamped value.
+ */
+export declare const clamp: (value: number, min?: number, max?: number) => number;
+/** Comparator for sorting numbers in ascending order. */
+export declare const asc: (a: number, b: number) => number;
+/**
+ * Finds the index of the value closest to `currentValue` in a sorted array.
+ * When two values are equidistant, the later index wins (useful for range sliders
+ * so that the higher thumb is preferred when clicking exactly between two thumbs).
+ *
+ * @param values - Array of numeric values to search.
+ * @param currentValue - The target value to find the closest match for.
+ * @returns The index of the closest value.
+ */
+export declare const findClosest: (values: number[], currentValue: number) => number;
+/**
+ * Normalizes the `step` prop to a safe runtime value.
+ *
+ * - `step={null}` is only valid when an explicit non-empty `marks` array is provided.
+ * - Non-positive or non-finite values fall back to `1`.
+ */
+export declare const normalizeStep: (step: null | number, marks: boolean | ReadonlyArray<Mark>) => null | number;
+/**
+ * Normalizes `shiftStep` to a positive finite number.
+ */
+export declare const normalizeShiftStep: (shiftStep: number) => number;
+/**
+ * Normalizes `minDistance` to a non-negative finite number.
+ */
+export declare const normalizeMinDistance: (minDistance: number) => number;
+/**
+ * Normalizes `snapToMarks` to a safe runtime value.
+ */
+export declare const normalizeSnapToMarks: (snapToMarks: SliderProps["snapToMarks"]) => SliderProps["snapToMarks"];
+/**
+ * Resolves track variants that are not supported for the current slider shape.
+ * Center-origin track rendering only works for single-thumb sliders.
+ */
+export declare const resolveTrackMode: (track: SliderProps["track"], range: boolean) => SliderProps["track"];
+/**
+ * Extracts the (x, y) coordinates of a pointer from a mouse or touch event.
+ * For touch events, it matches the finger by `touchId` to support multi-touch correctly.
+ *
+ * @param event - The mouse or touch event.
+ * @param touchId - Ref holding the tracked touch identifier.
+ * @returns The finger coordinates, or `false` if the tracked touch was not found.
+ */
+export declare const trackFinger: (event: MouseEvent | React.MouseEvent | TouchEvent, touchId: React.RefObject<number | undefined>) => false | {
+    x: number;
+    y: number;
+};
+/**
+ * Converts a percentage (0–1) back to an absolute value within the slider range.
+ *
+ * @param percent - A value between 0 and 1 representing position on the track.
+ * @param min - The slider minimum.
+ * @param max - The slider maximum.
+ * @returns The corresponding absolute value.
+ */
+export declare const percentToValue: (percent: number, min: number, max: number) => number;
+/**
+ * Determines the number of decimal digits needed to represent a number without
+ * floating-point rounding artifacts. Handles small numbers expressed in
+ * scientific notation (e.g. `0.001` → `1e-3` → 3 decimal places).
+ *
+ * @param num - The number to inspect.
+ * @returns The decimal precision (number of digits after the decimal point).
+ */
+export declare const getDecimalPrecision: (num: number) => number;
+/**
+ * Rounds a value to the nearest step increment relative to `min`.
+ * Uses `getDecimalPrecision` to avoid floating-point rounding errors
+ * (e.g. `0.1 + 0.2 !== 0.3`).
+ *
+ * @param value - The raw value to round.
+ * @param step - The step increment.
+ * @param min - The slider minimum (the step grid origin).
+ * @returns The value snapped to the nearest step.
+ */
+export declare const roundValueToStep: (value: number, step: number, min: number) => number;
+/**
+ * Returns a new sorted array with the value at `index` replaced by `newValue`.
+ * Used to update one thumb in a range slider while keeping the array sorted.
+ *
+ * @param values - The current thumb values.
+ * @param newValue - The new value for the thumb at `index`.
+ * @param index - The thumb index to update.
+ * @returns A new sorted array of thumb values.
+ */
+export declare const setValueIndex: (values: number[], newValue: number, index: number) => number[];
+/**
+ * Normalizes initial range values so they satisfy `minDistance` on first render.
+ * When the requested minimum gap cannot fit inside the slider range, the values
+ * are spread evenly across the available range.
+ */
+export declare const normalizeInitialRangeValues: (values: number[], { max, min, minDistance, }: {
+    max?: number;
+    min?: number;
+    minDistance?: number;
+}) => number[];
+/**
+ * Normalizes the initial slider value so the component never mounts in an
+ * invalid state. Marks-only sliders snap to the nearest mark, range values are
+ * coerced to exactly two thumbs, and initial range values are adjusted to
+ * satisfy `minDistance`.
+ */
+export declare const normalizeSliderValue: (value: SliderValue | undefined, { marks, max, min, minDistance, step, }: {
+    marks: Mark[];
+    max?: number;
+    min?: number;
+    minDistance?: number;
+    step?: null | number;
+}) => SliderValue | undefined;
+/**
+ * Logs a console warning in development if `min >= max`, which would produce
+ * a broken slider with zero or negative range.
+ */
+export declare const validateSliderRange: (min: number, max: number) => void;
+export declare const constrainRangeValue: (values: number[], newValue: number, index: number, { disableSwap, max, min, minDistance, }: {
+    disableSwap?: boolean;
+    max?: number;
+    min?: number;
+    minDistance?: number;
+}) => {
+    activeIndex: number;
+    value: number[];
+};
+/**
+ * Produces a new slider value with one thumb updated. For single-value sliders
+ * it simply returns the new number; for range sliders it returns a new array.
+ *
+ * @param currentValue - The current slider value (number or number[]).
+ * @param thumbIndex - Index of the thumb to update.
+ * @param nextValue - The new value for the thumb.
+ * @returns The updated slider value.
+ */
+export declare const updateThumbValue: (currentValue: SliderValue, thumbIndex: number, nextValue: number) => SliderValue;
+export declare const focusThumb: ({ activeIndex, setActive, sliderRef, }: {
+    activeIndex: number;
+    setActive?: (index: number) => void;
+    sliderRef: React.RefObject<HTMLSpanElement | null>;
+}) => void;
+/**
+ * Shallow-compares two arrays element by element.
+ *
+ * @param array1 - First array.
+ * @param array2 - Second array.
+ * @param itemComparer - Optional comparator (defaults to strict equality).
+ * @returns `true` if both arrays have the same length and all elements match.
+ */
+export declare const areArraysEqual: <Item>(array1: ReadonlyArray<Item>, array2: ReadonlyArray<Item>, itemComparer?: (a: Item, b: Item) => boolean) => boolean;
+/**
+ * Compares two slider values for equality. Handles both single-value (number)
+ * and range (number[]) slider variants.
+ *
+ * @param newValue - The new slider value.
+ * @param oldValue - The previous slider value.
+ * @returns `true` if the values are semantically equal.
+ */
+export declare const areValuesEqual: (newValue: number | number[], oldValue: number | ReadonlyArray<number>) => boolean;
+/**
+ * Creates a cloned native Event with a synthetic `target` containing the slider's
+ * `name` and current `value`. This mimics the behavior of native `<input>` change
+ * events so that form libraries (e.g. Formik, React Hook Form) can read the value
+ * from `event.target.value`.
+ *
+ * @param event - The original browser or React event that triggered the change.
+ * @param value - The new slider value.
+ * @param name - The slider's `name` attribute.
+ * @returns A cloned Event with `target.value` and `target.name` set.
+ */
+export declare const createChangeEvent: (event: Event | React.SyntheticEvent, value: number | number[], name?: string) => Event;
+/**
+ * Detects whether the browser supports `touch-action: none`.
+ * The result is cached after the first call for performance.
+ *
+ * When supported, touch events can use `passive: true` listeners because
+ * `touch-action: none` on the element already prevents scrolling.
+ * When not supported, touch handlers must call `preventDefault()` manually.
+ */
+export declare const doesSupportTouchActionNone: () => boolean;

package/dist/components/inputs/slider/internal/utils/slider.utils.d.ts

@@ -0,0 +1,190 @@
+import { CSSProperties, ReactNode } from 'react';
+import { Mark, SliderProps, SliderValue } from '../../slider/slider.types';
+import { Axis } from '../types';
+/** Soft cap for decorative tickmarks to avoid rendering excessive DOM. */
+export declare const MAX_DECORATIVE_TICKMARK_COUNT = 100;
+/** A mark augmented with a stagger `level` for label collision avoidance. */
+export interface MarkLevel {
+    label?: ReactNode;
+    /** The stagger row (0 = default row, 1+ = offset rows below). */
+    level: number;
+    value: number;
+}
+/** Metadata for a single tickmark dot rendered on the slider rail. */
+export interface TickmarkMeta {
+    /** Whether this tick aligns with a user-defined mark (rendered larger). */
+    isMajor: boolean;
+    /** Position of the tick as a percentage (0–100) along the track. */
+    percent: number;
+}
+/** Computed CSS-ready metrics for the active track segment. */
+export interface TrackMetrics {
+    /** Length of the active track as a percentage of the full range. */
+    leap: number;
+    /** Start position of the active track as a percentage of the full range. */
+    offset: number;
+}
+/** Default value label formatter — returns the numeric value as-is. */
+export declare const defaultValueLabelFormat: (x: number) => number;
+/**
+ * Resolves the public `marks` prop into a concrete array of mark objects.
+ *
+ * - `marks={true}` generates marks from `min` to `max` using `step`.
+ * - custom mark arrays are normalized into a stable ascending range order.
+ * - when the generated step grid does not land exactly on `max`, the endpoint
+ *   is appended so the full range remains visibly represented.
+ */
+export declare const buildMarks: (marksProp: boolean | ReadonlyArray<Mark>, min: number, max: number, step: null | number) => Mark[];
+/**
+ * Converts an absolute slider value to a percentage (0–100) within the [min, max] range.
+ *
+ * @param value - The absolute value.
+ * @param min - The slider minimum.
+ * @param max - The slider maximum.
+ * @returns The percentage position, or 0 if range is zero/negative.
+ */
+export declare const toPercent: (value: number, min: number, max: number) => number;
+/**
+ * Computes staggered label levels to avoid overlapping mark labels.
+ * Returns marks augmented with a `level` property (0, 1, or 2).
+ */
+export declare const computeMarkLevels: <MarkEntry extends {
+    label?: ReactNode;
+    value: number;
+}>(marksList: MarkEntry[], min: number, max: number) => Array<MarkEntry & {
+    level: number;
+}>;
+/**
+ * Snaps a value to the nearest mark if within the threshold.
+ */
+/**
+ * Snaps a single value to the nearest mark if the distance is within `threshold`.
+ * If no mark is close enough the original value is returned unchanged.
+ *
+ * @param rawValue - The raw (unsnapped) slider value.
+ * @param marksArr - The array of available marks.
+ * @param threshold - Maximum distance (in slider units) for a snap to occur.
+ * @returns The snapped value, or `rawValue` if no mark is close enough.
+ */
+export declare const snapToNearestMark: (rawValue: number, marksArr: Mark[], threshold: number) => number;
+/**
+ * Applies snap-to-mark behavior to a slider value. Works with both single values
+ * and arrays (range sliders), snapping each value independently.
+ *
+ * @param value - The current slider value (number or number[]).
+ * @param marksArr - The available marks.
+ * @param threshold - Snap distance threshold in slider units.
+ * @returns The snapped slider value.
+ */
+export declare const applySnapToValue: (value: SliderValue, marksArr: Mark[], threshold: number) => SliderValue;
+export declare const resolveKeyboardSnapValue: ({ currentValue, marks, max, min, nextValue, snapThreshold, }: {
+    currentValue: number;
+    marks: Mark[];
+    max: number;
+    min: number;
+    nextValue: number;
+    snapThreshold: number;
+}) => number;
+/**
+ * Calculates the snap threshold in absolute slider units from the percentage-based
+ * `snapToMarks` prop. When `snapToMarks` is `true`, uses the default 2%.
+ * When it's a number, uses that as the percentage.
+ *
+ * @param snapEnabled - Whether snapping is active.
+ * @param snapToMarks - The `snapToMarks` prop value (`true` or a custom percentage).
+ * @param min - Slider minimum.
+ * @param max - Slider maximum.
+ * @returns The snap threshold in slider units (0 when snapping is disabled).
+ */
+export declare const getSnapThreshold: (snapEnabled: boolean, snapToMarks: SliderProps["snapToMarks"], min: number, max: number) => number;
+export declare const normalizeVisibleInputValue: ({ marks, max, min, snapThreshold, snapToMarks, step, value, }: {
+    marks: Mark[];
+    max: number;
+    min: number;
+    snapThreshold?: number;
+    snapToMarks?: boolean;
+    step: null | number;
+    value: number;
+}) => number;
+/**
+ * Computes the CSS offset and length of the colored track segment.
+ * Supports all track modes: `normal`, `inverted`, `center`, and `false`.
+ *
+ * - **normal**: track runs from `min` (or the lower thumb) to the value.
+ * - **inverted**: the track colors the *remaining* portion instead.
+ * - **center**: track runs from the midpoint of the range to the current value.
+ * - **false**: no track rendered (returns zeros).
+ *
+ * @param values - The current thumb value(s).
+ * @param range - Whether the slider is a range slider.
+ * @param min - Slider minimum.
+ * @param max - Slider maximum.
+ * @param track - The track display mode.
+ * @returns `{ offset, leap }` as percentages (0–100).
+ */
+export declare const getTrackMetrics: (values: number[], range: boolean, min: number, max: number, track?: SliderProps["track"]) => TrackMetrics;
+/**
+ * Builds metadata for evenly-spaced tickmark dots along the slider rail.
+ * Each tickmark is either a normal dot or a "major" dot (when it aligns with a
+ * user-defined mark position within `MAJOR_TICK_THRESHOLD_PERCENT`).
+ *
+ * @param tickmarks - Total number of tickmarks to render.
+ * @param marksArray - User-defined marks (used to identify major ticks).
+ * @param min - Slider minimum.
+ * @param max - Slider maximum.
+ * @returns Array of `{ percent, isMajor }` for each tickmark.
+ */
+export declare const buildTickmarkMeta: (tickmarks: number, marksArray: Mark[] | undefined, min: number, max: number) => TickmarkMeta[];
+/**
+ * Determines whether a mark at a given percentage is within the active track region.
+ * Used to style marks differently when they fall inside vs. outside the colored track.
+ *
+ * @param percent - The mark's position as a percentage (0–100).
+ * @param range - Whether the slider is a range slider.
+ * @param track - The track display mode.
+ * @param trackOffset - The start of the active track (percentage).
+ * @param trackLeap - The length of the active track (percentage).
+ * @returns `true` if the mark is within the active track region.
+ */
+export declare const isMarkActive: (percent: number, range: boolean, track: SliderProps["track"], trackOffset: number, trackLeap: number) => boolean;
+/**
+ * Generates a CSS `clip-path: inset(...)` value that clips the "active" tickmark
+ * layer to only show ticks within the colored track region. The active layer is
+ * rendered on top of the inactive layer and uses a different color.
+ *
+ * @param orientation - The slider orientation, used to choose horizontal vs. vertical clipping.
+ * @param track - The track display mode.
+ * @param range - Whether the slider is a range slider.
+ * @param trackOffset - The start of the active track (percentage).
+ * @param trackLeap - The length of the active track (percentage).
+ * @returns One or more CSS `inset(...)` strings for the `clip-path` property.
+ */
+export declare const getTickmarkClipPaths: (orientation: SliderProps["orientation"], track: SliderProps["track"], range: boolean, trackOffset: number, trackLeap: number) => string[];
+/**
+ * Backwards-compatible helper returning the first clip-path segment.
+ * Prefer `getTickmarkClipPaths()` for new code.
+ */
+export declare const getTickmarkClipPath: (track: SliderProps["track"], range: boolean, trackOffset: number, trackLeap: number) => string;
+/**
+ * Returns inline styles for the slider root element. Applies `width` for horizontal
+ * sliders and `height` for vertical sliders when a length is explicitly provided.
+ *
+ * @param length - The desired length along the main axis (number for px, or a CSS string).
+ * @param orientation - The slider orientation.
+ * @returns CSS properties object, or `undefined` if no styles are needed.
+ */
+export declare const getSliderStyle: (length: SliderProps["length"], orientation: SliderProps["orientation"]) => CSSProperties | undefined;
+/**
+ * Returns a clamped CSS offset for a mark dot so that the full circle stays
+ * within the rail bounds. Without clamping, marks at 0% and 100% would have
+ * half the dot extending beyond the rail due to `translate(-50%)`.
+ *
+ * The position is clamped between `mark-size / 2` and `100% - mark-size / 2`
+ * using the `--rbui-slider-mark-size` CSS custom property, so the dot never
+ * overflows the rounded rail ends regardless of the component size variant.
+ *
+ * @param percent - The mark's position as a percentage (0–100) along the track.
+ * @param axis - The resolved axis direction (`horizontal`, `horizontal-reverse`, or `vertical`).
+ * @returns CSS properties with the clamped positional value for the appropriate axis.
+ */
+export declare const getClampedMarkOffset: (percent: number, axis: Axis) => CSSProperties;

package/dist/components/inputs/slider/slider/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './slider';
+export type { Mark, SliderChangeCommittedHandler, SliderChangeHandler, SliderNumberInputAttributes, SliderProps, SliderValue, } from './slider.types';

package/dist/components/inputs/slider/slider/slider.d.ts

@@ -0,0 +1,17 @@
+import { SliderProps } from './slider.types';
+/**
+ * Slider allows users to select a value or range from a continuous or discrete set of values
+ * by moving a thumb along a track.
+ *
+ * ### Usage
+ *
+ * ```tsx
+ * import { Slider } from '@bloomreach/react-banana-ui';
+ *
+ * export default function MySlider() {
+ *   return <Slider defaultValue={50} />;
+ * }
+ * ```
+ */
+declare const Slider: import('react').ForwardRefExoticComponent<SliderProps & import('react').RefAttributes<HTMLSpanElement>>;
+export default Slider;

package/dist/components/inputs/slider/slider/slider.qa.stories.d.ts

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/react-vite';
+import { Story } from './slider.stories';
+declare const meta: Meta;
+export default meta;
+export declare const AllStates: Story;
+export declare const TrackVariants: Story;
+export declare const WithMarks: Story;
+export declare const WithTickmarks: Story;
+export declare const TickmarksWithMarks: Story;
+export declare const StaggeredLabels: Story;
+export declare const Vertical: Story;
+export declare const VerticalTickmarks: Story;
+export declare const WithValueLabelOn: Story;
+export declare const RangeSlider: Story;
+export declare const DisableSwap: Story;
+export declare const MinDistanceRange: Story;
+export declare const WithInput: Story;
+export declare const RangeWithInput: Story;
+export declare const KeyboardInteraction: Story;
+export declare const RangeKeyboardInteraction: Story;
+export declare const ValueLabelAutoInteraction: Story;
+export declare const ControlledWithInput: Story;
+export declare const RangeWithInputControlled: Story;
+export declare const SnapToMarksInteraction: Story;
+export declare const DisabledInteraction: Story;
+export declare const ReadOnlyInteraction: Story;
+export declare const ShiftStepInteraction: Story;

package/dist/components/inputs/slider/slider/slider.stories.d.ts

@@ -0,0 +1,33 @@
+import { default as Slider } from '.';
+import { Meta, StoryObj } from '@storybook/react-vite';
+declare const meta: Meta<typeof Slider>;
+export default meta;
+export type Story = StoryObj<typeof Slider>;
+export declare const Basic: Story;
+export declare const Controlled: Story;
+export declare const ReadOnly: Story;
+export declare const Disabled: Story;
+export declare const Error: Story;
+export declare const RangeSlider: Story;
+export declare const WithValueLabel: Story;
+export declare const CustomValueFormat: Story;
+export declare const Steps: Story;
+export declare const SmallSize: Story;
+export declare const Vertical: Story;
+export declare const CustomRange: Story;
+export declare const CenteredTrack: Story;
+export declare const TrackInverted: Story;
+export declare const TrackFalse: Story;
+export declare const LogarithmicScale: Story;
+export declare const WithMarks: Story;
+export declare const SnapToMarks: Story;
+export declare const MagneticSnapToMarks: Story;
+export declare const WithTickmarks: Story;
+export declare const TickmarksWithMarks: Story;
+export declare const StaggeredLabels: Story;
+export declare const VerticalTickmarks: Story;
+export declare const DisableSwap: Story;
+export declare const MinDistance: Story;
+export declare const WithInput: Story;
+export declare const RangeWithInput: Story;
+export declare const ShiftStep: Story;