@bloomreach/react-banana-ui 1.36.0 → 1.38.0

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

@@ -0,0 +1,229 @@
+import { InputHTMLAttributes, ReactNode } from 'react';
+import type * as React from 'react';
+/**
+ * Handler called when the user finishes a change (mouseup, touchend, blur, or keyboard commit).
+ * Use this for expensive side effects like API calls that should only run on "commit".
+ */
+export type SliderChangeCommittedHandler = (event: Event | React.SyntheticEvent, value: SliderValue) => void;
+/**
+ * Handler called continuously as the slider value changes (during drag, keyboard navigation, or input).
+ * Receives the active thumb index to support range sliders.
+ */
+export type SliderChangeHandler = (event: Event, value: SliderValue, activeThumb: number) => void;
+/**
+ * HTML attributes allowed on the visible number input (`withNumberInput`).
+ * Omits attributes that are managed internally by the slider.
+ */
+export type SliderNumberInputAttributes = Omit<InputHTMLAttributes<HTMLInputElement>, 'defaultValue' | 'disabled' | 'max' | 'min' | 'readOnly' | 'step' | 'type' | 'value'>;
+/** Tuple of two numbers for range sliders. */
+export type SliderRangeValue = [number, number];
+/** Single number, or a range tuple for dual-thumb sliders. */
+export type SliderValue = number | SliderRangeValue;
+/** A discrete mark position on the slider, with an optional label displayed below the track. */
+export interface Mark {
+    /**
+     * The label to display at the mark position.
+     */
+    label?: ReactNode;
+    /**
+     * The value at which the mark is placed.
+     */
+    value: number;
+}
+/** Public props for the `Slider` component. */
+export interface SliderProps {
+    /**
+     * The label of the slider.
+     */
+    'aria-label'?: string;
+    /**
+     * The id of the element containing a label for the slider.
+     */
+    'aria-labelledby'?: string;
+    /**
+     * A string value that provides a user-friendly name for the current value of the slider.
+     */
+    'aria-valuetext'?: string;
+    /**
+     * Custom class name for the container of the component.
+     */
+    className?: string;
+    /**
+     * The default value. Use when the component is not controlled.
+     * For range sliders, provide a tuple with exactly two values.
+     */
+    defaultValue?: SliderValue;
+    /**
+     * If `true`, the component is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * If `true`, the active thumb doesn't swap when moving pointer over a thumb while dragging another thumb.
+     * @default false
+     */
+    disableSwap?: boolean;
+    /**
+     * If `true`, the slider is in an error state.
+     * @default false
+     */
+    error?: boolean;
+    /**
+     * Accepts a function which returns a string value that provides a user-friendly name
+     * for the thumb labels of the slider. This is important for screen reader users.
+     * @param {number} index The thumb label's index to format.
+     * @returns {string}
+     */
+    getAriaLabel?: (index: number) => string;
+    /**
+     * Accepts a function which returns a string value that provides a user-friendly name
+     * for the current value of the slider. This is important for screen reader users.
+     * @param {number} value The thumb label's value to format.
+     * @param {number} index The thumb label's index to format.
+     * @returns {string}
+     */
+    getAriaValueText?: (value: number, index: number) => string;
+    /**
+     * Props applied to the visible number input when `withNumberInput` is enabled.
+     * Provide a function to customize the props per thumb in range sliders.
+     * Range sliders render exactly two visible inputs when `withNumberInput` is enabled.
+     * Visible inputs keep transient text while the user edits and commit normalized values on blur or Enter.
+     */
+    inputProps?: ((index: number) => SliderNumberInputAttributes) | SliderNumberInputAttributes;
+    /**
+     * The length of the slider along its main axis. Accepts any valid CSS value.
+     * Sets `width` for horizontal sliders and `height` for vertical sliders.
+     */
+    length?: number | string;
+    /**
+     * Marks indicate predetermined values to which the user can move the slider.
+     * If `true` the marks are spaced according the value of the `step` prop.
+     * If an array, it should contain objects with `value` and an optional `label` keys.
+     * @default false
+     */
+    marks?: boolean | Mark[];
+    /**
+     * The maximum allowed value of the slider.
+     * @default 100
+     */
+    max?: number;
+    /**
+     * The minimum allowed value of the slider.
+     * @default 0
+     */
+    min?: number;
+    /**
+     * The minimum allowed distance between adjacent thumbs in a range slider.
+     * The value uses the same unit as the slider itself.
+     * @default 0
+     */
+    minDistance?: number;
+    /**
+     * Name attribute of the hidden `input` element.
+     * For range sliders, native form submission uses indexed names: `${name}[0]` and `${name}[1]`.
+     */
+    name?: string;
+    /**
+     * Callback function that is fired when the slider's value changed.
+     * @param {Event} event The event source of the callback.
+     * @param {number | number[]} value The new value.
+     * @param {number} activeThumb Index of the currently moved thumb.
+     */
+    onChange?: SliderChangeHandler;
+    /**
+     * Callback function that is fired when the `mouseup` is triggered.
+     * @param {React.SyntheticEvent | Event} event The event source of the callback.
+     * @param {number | number[]} value The new value.
+     */
+    onChangeCommitted?: SliderChangeCommittedHandler;
+    /**
+     * The component orientation.
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * If `true`, the component is read only. The slider is visible but not interactive.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * A transformation function, to change the scale of the slider.
+     * The slider still stores and submits raw values. The transformed value is used for
+     * display-oriented output such as value labels and ARIA value text.
+     * @default (x) => x
+     */
+    scale?: (value: number) => number;
+    /**
+     * The granularity with which the slider can step through values
+     * when using Page Up/Page Down or Shift + Arrow Up/Arrow Down.
+     * @default 10
+     */
+    shiftStep?: number;
+    /**
+     * The size of the slider.
+     * @default 'md'
+     */
+    size?: 'md' | 'sm';
+    /**
+     * When set, the slider magnetically snaps to nearby mark positions while dragging.
+     * - `true` uses a default threshold of 2% of the total range.
+     * - A number sets a custom threshold as a percentage of the range (e.g., `5` = 5%).
+     * Only active when `marks` is an array and `step` is not `null`.
+     * @default false
+     */
+    snapToMarks?: boolean | number;
+    /**
+     * The granularity with which the slider can step through values.
+     * When step is `null`, the thumb can only be slid onto marks provided with the `marks` prop.
+     * @default 1
+     */
+    step?: null | number;
+    /**
+     * Tab index attribute of the hidden `input` element.
+     */
+    tabIndex?: number;
+    /**
+     * Number of evenly-spaced decorative tick dots to render on the slider track.
+     * When set, dots are displayed along the rail with active/inactive coloring.
+     * If marks are also provided, larger dots are shown at mark positions.
+     * Very large decorative counts may be capped to keep rendering lightweight.
+     */
+    tickmarks?: number;
+    /**
+     * The track presentation:
+     * - `normal` the track will render a bar representing the slider value.
+     * - `inverted` the track will render a bar representing the remaining slider value.
+     * - `center` the track will render a bar from the midpoint of the range to the current value.
+     * - `false` the track will render without a bar.
+     * @default 'normal'
+     */
+    track?: 'center' | 'inverted' | 'normal' | false;
+    /**
+     * The value of the slider. For ranged sliders, provide a tuple with exactly two values.
+     */
+    value?: SliderValue;
+    /**
+     * Controls when the value label is displayed:
+     * - `auto` the value label will display when the thumb is hovered or focused.
+     * - `on` will display persistently.
+     * - `off` will never display.
+     * @default 'auto'
+     */
+    valueLabelDisplay?: 'auto' | 'off' | 'on';
+    /**
+     * The format function the value label's value.
+     * @param {number} value The value label's value to format.
+     * @param {number} index The value label's index to format.
+     * @returns {React.ReactNode}
+     * @default (x) => x
+     */
+    valueLabelFormat?: (value: number, index: number) => ReactNode;
+    /**
+     * If `true`, a number input is rendered alongside the slider for direct value entry.
+     * For range sliders, two inputs are shown (one per thumb).
+     * The visible inputs respect slider constraints such as step, marks, snapping, and minimum thumb distance.
+     * Partial text entry is preserved while typing and normalized when the input is committed.
+     * @default false
+     */
+    withNumberInput?: boolean;
+}

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

@@ -0,0 +1,2 @@
+export { default } from './slider-field';
+export type { SliderFieldProps } from './slider-field.types';

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

@@ -0,0 +1,27 @@
+import { SliderFieldProps } from './slider-field.types';
+/**
+ * SliderField wraps a Slider with a label, helper text, and optional tooltip.
+ * Use this component when the slider needs to appear within a form with consistent field layout.
+ *
+ * ### Usage
+ *
+ * ```tsx
+ * import { SliderField } from '@bloomreach/react-banana-ui';
+ * import { useState } from 'react';
+ *
+ * export default function VolumeControl() {
+ *   const [volume, setVolume] = useState(50);
+ *
+ *   return (
+ *     <SliderField
+ *       label="Volume"
+ *       withNumberInput
+ *       value={volume}
+ *       onChange={(_, value) => setVolume(value as number)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare const SliderField: import('react').ForwardRefExoticComponent<SliderFieldProps & import('react').RefAttributes<HTMLSpanElement>>;
+export default SliderField;

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

@@ -0,0 +1,18 @@
+import { Meta } from '@storybook/react-vite';
+import { Story } from './slider-field.stories';
+declare const meta: Meta;
+export default meta;
+export declare const AllFieldStates: Story;
+export declare const WithInput: Story;
+export declare const WithInputRange: Story;
+export declare const WithInputDisabled: Story;
+export declare const WithInputReadOnly: Story;
+export declare const WithInputError: Story;
+export declare const WithoutNumberInput: Story;
+export declare const Required: Story;
+export declare const FullWidth: Story;
+export declare const WithMarks: Story;
+export declare const VerticalField: Story;
+export declare const WithTooltip: Story;
+export declare const ControlledFieldWithInput: Story;
+export declare const ControlledRangeField: Story;

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

@@ -0,0 +1,15 @@
+import { default as SliderField } from '.';
+import { Meta, StoryObj } from '@storybook/react-vite';
+declare const meta: Meta<typeof SliderField>;
+export default meta;
+export type Story = StoryObj<typeof SliderField>;
+export declare const WithInput: Story;
+export declare const WithInputRange: Story;
+export declare const WithInputDisabled: Story;
+export declare const WithInputReadOnly: Story;
+export declare const WithInputError: Story;
+export declare const WithoutNumberInput: Story;
+export declare const Required: Story;
+export declare const FullWidth: Story;
+export declare const WithMarks: Story;
+export declare const Vertical: Story;

package/dist/components/inputs/slider/slider-field/slider-field.types.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode } from 'react';
+import { SliderProps } from '../slider/slider.types';
+export interface SliderFieldProps extends SliderProps {
+    /**
+     * If `true`, the field will take up the full width of its container.
+     */
+    fullWidth?: boolean;
+    /**
+     * The helper text content.
+     */
+    helperText?: ReactNode;
+    /**
+     * The label content.
+     */
+    label?: ReactNode;
+    /**
+     * If `true`, the field will display a red asterisk next to the label to indicate it is required.
+     */
+    required?: boolean;
+    /**
+     * Tooltip to display when the field has a label.
+     */
+    tooltip?: ReactNode;
+}