@bspk/ui 1.1.33 → 1.2.0

package/src/components/Slider/Slider.tsx

@@ -0,0 +1,281 @@
+import { useEffect, useRef } from 'react';
+
+import './slider.scss';
+import { SliderIntervalDots } from './SliderIntervalDots';
+import { useNormalizeSliderValue } from './useNormalizeSliderValue';
+import { Txt } from '-/components/Txt';
+import { CommonPropsLibrary } from '-/types/common';
+
+export type SliderValue = number | [number, number];
+
+export type SliderProps<Value> = Pick<CommonPropsLibrary, 'disabled' | 'readOnly'> & {
+    /**
+     * The label of the slider.
+     *
+     * @required
+     */
+    label: string;
+    /**
+     * The numerical value of the slider.
+     *
+     * Providing an array of two numbers will create a **range slider**.
+     *
+     * @required
+     */
+    value: Value;
+    /**
+     * Invoked with the new value when value changes.
+     *
+     * @required
+     */
+    onChange: (newValue: Value) => void;
+    /**
+     * The minimum value of the slider.
+     *
+     * @required
+     */
+    min: number;
+    /**
+     * The maximum value of the slider.;
+     *
+     * @required
+     */
+    max: number;
+    /**
+     * Indicates if marks should be displayed on the slider.
+     *
+     * @default false
+     */
+    marks?: boolean;
+    /**
+     * The number that specifies the granularity that the value must adhere to
+     *
+     * @default 1
+     */
+    step?: number;
+    /**
+     * Optional function to format the display of each number.
+     *
+     * Useful for currency, percentages, etc.
+     */
+    formatNumber?: (value: number, context?: 'max' | 'min' | 'rangeEnd' | 'rangeStart') => string;
+    /**
+     * The name of the slider input, useful for form submissions.
+     *
+     * @required
+     */
+    name: string;
+};
+
+/**
+ * A control element that allows customers to select a value or adjust a setting by moving the handle along a horizontal
+ * track.
+ *
+ * @example
+ *     import { Slider } from '@bspk/ui/Slider';
+ *     import { useState } from 'react';
+ *
+ *     function Example() {
+ *         const [value, setValue] = useState(50);
+ *
+ *         return <Slider value={value} min={0} max={100} label="Slider Example" onChange={setValue} />;
+ *     }
+ *
+ * @name Slider
+ * @phase UXReview
+ */
+export function Slider<V = SliderValue>({
+    value: valueProp,
+    onChange,
+    min,
+    max,
+    label,
+    marks = false,
+    step = 1,
+    disabled = false,
+    readOnly = false,
+    name,
+    formatNumber: formatNumberProp,
+}: SliderProps<V>) {
+    const value = (valueProp as V) || min;
+    const formatNumber: SliderProps<V>['formatNumber'] = (rawValue, context) =>
+        formatNumberProp?.(rawValue, context) || rawValue.toString();
+    const sliderRef = useRef<HTMLDivElement>(null);
+    const isDraggingRef = useRef<0 | 1 | null>(null);
+    const { normalizeSliderValue } = useNormalizeSliderValue({ min, max, step });
+
+    const isRange = Array.isArray(value);
+    let val0: number = isRange ? value[0] : value;
+    let val1: number = isRange ? value[1] : value;
+
+    // Always show the lower value first
+    if (isRange && val0 > val1) {
+        [val0, val1] = [val1, val0];
+    }
+
+    const displayValue = isRange
+        ? [formatNumber(val0, 'rangeStart'), formatNumber(val1, 'rangeEnd')].join(' - ')
+        : formatNumber(val0, 'rangeStart');
+
+    const percent0 = Math.min(Math.max(((val0 - min) / (max - min)) * 100, 0), 100);
+    const percent1 = Math.min(Math.max(((val1 - min) / (max - min)) * 100, 0), 100);
+
+    const getValueFromPosition = (clientX: number) => {
+        const slider = sliderRef.current;
+        if (!slider) return min;
+        const { left, width } = slider.getBoundingClientRect();
+        let percent = (clientX - left) / width;
+        percent = Math.max(0, Math.min(1, percent));
+        return normalizeSliderValue(min + percent * (max - min));
+    };
+
+    const handleMouseMove = (e: MouseEvent) => {
+        if (isDraggingRef.current === null || disabled || readOnly) return;
+        const newValue = getValueFromPosition(e.clientX);
+        const normalValue = normalizeSliderValue(newValue);
+        let nextValue: number | [number, number] = normalValue;
+        if (isRange) nextValue = isDraggingRef.current === 0 ? [normalValue, val1] : [val0, normalValue];
+        onChange(nextValue as V);
+    };
+
+    const handleMouseUp = () => {
+        isDraggingRef.current = null;
+        window.removeEventListener('mousemove', handleMouseMove);
+        window.removeEventListener('mouseup', handleMouseUp);
+    };
+
+    const handleTrackClick = (e: React.MouseEvent<HTMLDivElement>) => {
+        if (disabled || readOnly) return;
+        const clickValue = getValueFromPosition(e.clientX);
+        let nextValue: number | [number, number] = normalizeSliderValue(clickValue);
+
+        if (isRange) {
+            if (Math.abs(clickValue - val0) < Math.abs(clickValue - val1)) {
+                nextValue = [clickValue, val1];
+                isDraggingRef.current = 0;
+            } else {
+                nextValue = [val0, clickValue];
+                isDraggingRef.current = 1;
+            }
+        }
+
+        onChange(nextValue as V);
+    };
+
+    const handleKnobMouseDown = (knobIndex: 0 | 1) => (e: React.MouseEvent<HTMLDivElement>) => {
+        if (disabled || readOnly) return;
+        e.stopPropagation();
+        isDraggingRef.current = knobIndex;
+        window.addEventListener('mousemove', handleMouseMove);
+        window.addEventListener('mouseup', handleMouseUp);
+    };
+
+    const handleKnobKeyDown = (knobIndex: 0 | 1) => (e: React.KeyboardEvent<HTMLDivElement>) => {
+        if (disabled || readOnly) return;
+        let newValue = knobIndex === 0 ? val0 : val1;
+        if (e.key === 'ArrowLeft') newValue -= step;
+        else if (e.key === 'ArrowRight') newValue += step;
+        else return;
+        newValue = normalizeSliderValue(newValue);
+
+        let nextValue: number | [number, number] = newValue;
+        if (isRange) {
+            if (knobIndex === 0) nextValue = [newValue, val1];
+            else nextValue = [val0, newValue];
+        }
+
+        onChange(nextValue as V);
+    };
+
+    useEffect(() => {
+        return () => {
+            window.removeEventListener('mousemove', handleMouseMove);
+            window.removeEventListener('mouseup', handleMouseUp);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    return (
+        <div data-bspk="slider" data-disabled={disabled || undefined} data-readonly={readOnly || undefined}>
+            <input name={name} type="hidden" value={isRange ? `${val0},${val1}` : val0} />
+            <div data-top-labels>
+                <Txt variant="labels-small">{label}</Txt>
+                <Txt data-value-label>{displayValue}</Txt>
+            </div>
+            <div data-slider-parent>
+                <div
+                    aria-disabled={disabled || undefined}
+                    aria-label={label}
+                    aria-readonly={readOnly || undefined}
+                    aria-valuemax={max}
+                    aria-valuemin={min}
+                    aria-valuenow={val0}
+                    aria-valuetext={displayValue}
+                    data-slider-body
+                    onClick={handleTrackClick}
+                    onKeyDown={(e) => {
+                        if (disabled || readOnly) return;
+                        if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
+                            if (!isRange) {
+                                handleKnobKeyDown(0)(e as React.KeyboardEvent<HTMLDivElement>);
+                            }
+                        }
+                    }}
+                    ref={sliderRef}
+                    role="slider"
+                    tabIndex={disabled ? -1 : 0}
+                >
+                    <div data-slider-background />
+                    <div
+                        data-slider-fill
+                        style={{
+                            left: isRange ? `${percent0}%` : '0%',
+                            width: isRange ? `${percent1 - percent0}%` : `${percent0}%`,
+                        }}
+                    />
+                    {marks && (
+                        <SliderIntervalDots max={max} min={min} step={step} value={isRange ? [val0, val1] : val0} />
+                    )}
+                </div>
+                {isRange && (
+                    <div
+                        aria-label={`${label} start`}
+                        aria-valuemax={max}
+                        aria-valuemin={min}
+                        aria-valuenow={val0}
+                        aria-valuetext={val0.toString()}
+                        data-slider-knob
+                        onKeyDown={handleKnobKeyDown(0)}
+                        onMouseDown={handleKnobMouseDown(0)}
+                        role="slider"
+                        style={{ left: `calc(${percent0}% - 8px)` }}
+                        tabIndex={disabled ? -1 : 0}
+                    />
+                )}
+                <div
+                    aria-label={isRange ? `${label} end` : label}
+                    aria-valuemax={max}
+                    aria-valuemin={min}
+                    aria-valuenow={val1}
+                    aria-valuetext={val1?.toString()}
+                    data-slider-knob
+                    onKeyDown={handleKnobKeyDown(isRange ? 1 : 0)}
+                    onMouseDown={handleKnobMouseDown(isRange ? 1 : 0)}
+                    role="slider"
+                    style={{ left: `calc(${percent1}% - 8px)` }}
+                    tabIndex={disabled ? -1 : 0}
+                />
+            </div>
+            <div data-bottom-labels>
+                <Txt data-min-label variant="body-small">
+                    {formatNumber(min, 'min')}
+                </Txt>
+                <Txt data-max-label variant="body-small">
+                    {formatNumber(max, 'max')}
+                </Txt>
+            </div>
+        </div>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Slider/SliderExample.tsx

@@ -0,0 +1,63 @@
+import { useState } from 'react';
+
+import { SliderProps } from './Slider';
+import { ComponentExample } from '-/utils/demo';
+
+export const SliderExample: ComponentExample<SliderProps<number | [number, number]>> = {
+    // containerStyle: { width: '100%' },
+    render: ({ props, Component }) => {
+        const SliderDemo = (sliderProps: SliderProps<number | [number, number]>) => {
+            const initialValue = Array.isArray(sliderProps.value)
+                ? sliderProps.value
+                : typeof sliderProps.value === 'number'
+                  ? sliderProps.value
+                  : 0;
+
+            const [value, setValue] = useState(initialValue);
+
+            return <Component {...sliderProps} onChange={setValue} value={value} />;
+        };
+
+        return <SliderDemo {...props} max={props.max || 100} min={props.min || 0} value={props.value || 50} />;
+    },
+    presets: [
+        {
+            label: 'Basic Slider',
+            propState: {
+                label: 'Basic option',
+                min: 20,
+                max: 80,
+                step: 1,
+                value: 30,
+                formatNumber: (num) => `$${num}`,
+            },
+        },
+        {
+            label: 'Range Slider',
+            propState: {
+                label: 'Range option',
+                min: 0,
+                max: 100,
+                step: 1,
+                value: [70, 80],
+                formatNumber: (num) => {
+                    return `${num}%`;
+                },
+            },
+        },
+        {
+            label: 'Undefined Value',
+            propState: {
+                label: 'undefined',
+                min: 50,
+                max: 150,
+                step: 1,
+                value: null as unknown as [number, number],
+                formatNumber: (num, context) => {
+                    if (context === 'max') return `${num}% Passing`;
+                    return `${num}%`;
+                },
+            },
+        },
+    ],
+};

package/src/components/Slider/SliderIntervalDots.tsx

@@ -0,0 +1,35 @@
+import { SliderProps, SliderValue } from './Slider';
+
+type IntervalDotProps = Pick<SliderProps<SliderValue>, 'max' | 'min' | 'value'> & {
+    step: number;
+};
+
+export function SliderIntervalDots({ step, max, min, value }: IntervalDotProps) {
+    if (step <= 0) return null;
+
+    const count = Math.floor((max - min) / step);
+    const dots = [];
+
+    for (let i = 1; i < count; i++) {
+        const pointValue = i * step;
+        const percent = (pointValue / (max - min)) * 100;
+        dots.push(
+            <div
+                data-filled-section={
+                    typeof value === 'number'
+                        ? pointValue < value
+                            ? ''
+                            : undefined
+                        : pointValue < value[0]
+                          ? ''
+                          : undefined
+                }
+                data-interval-dot
+                key={i}
+                style={{ left: `${percent}%` }}
+            />,
+        );
+    }
+
+    return dots;
+}

package/src/components/Slider/index.tsx

@@ -0,0 +1 @@
+export * from './Slider';

package/src/components/Slider/slider.scss

@@ -0,0 +1,121 @@
+[data-bspk='slider'],
+[data-bspk='range-slider'] {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    width: 100%;
+    gap: 10px;
+
+    [data-top-labels],
+    [data-bottom-labels] {
+        display: flex;
+        flex-direction: row;
+        justify-content: space-between;
+        user-select: none;
+    }
+
+    [data-top-labels] {
+        color: var(--foreground-neutral-on-surface-variant-01);
+    }
+
+    [data-bottom-labels] {
+        color: var(--foreground-neutral-on-surface-variant-02);
+    }
+
+    [data-slider-parent] {
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+    }
+
+    [data-slider-body] {
+        position: relative;
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+    }
+
+    [data-slider-background] {
+        position: absolute;
+        background: var(--surface-neutral-t3-low);
+        height: var(--spacing-sizing-01);
+        border-radius: 2px;
+        left: 0;
+        right: 0;
+        cursor: pointer;
+    }
+
+    [data-slider-fill] {
+        position: absolute;
+        height: var(--spacing-sizing-01);
+        background-color: var(--foreground-brand-primary);
+        border-radius: 2px;
+        left: 0;
+        cursor: pointer;
+    }
+
+    [data-slider-knob] {
+        position: absolute;
+        border: 1px solid var(--stroke-neutral-low);
+        border-radius: 50%;
+        width: var(--spacing-sizing-04);
+        height: var(--spacing-sizing-04);
+        background-color: white;
+        box-sizing: border-box;
+        box-shadow: 0 0 3px 0 rgba(0 0 0 / 32%);
+        cursor: pointer;
+    }
+
+    [data-slider-knob]:focus-visible {
+        outline: 2px solid var(--stroke-neutral-focus);
+    }
+
+    [data-interval-dot] {
+        position: absolute;
+        width: 2px;
+        height: 2px;
+        background-color: var(--foreground-neutral-on-surface-variant-01);
+        transform: translate(-50%) rotate(45deg);
+    }
+
+    [data-interval-dot][data-filled-section] {
+        background-color: var(--foreground-brand-on-primary);
+    }
+
+    &[data-disabled],
+    &[data-readonly] {
+        [data-slider-knob] {
+            cursor: default;
+        }
+
+        [data-interval-dot] {
+            background-color: var(--foreground-neutral-disabled-on-surface);
+        }
+
+        [data-interval-dot][data-filled-section] {
+            background-color: var(--foreground-brand-on-primary);
+        }
+
+        [data-slider-fill] {
+            background-color: var(--foreground-neutral-disabled-on-surface);
+            cursor: default;
+        }
+
+        [data-slider-background] {
+            background: var(--interactions-disabled-opacity);
+            cursor: default;
+        }
+    }
+
+    &[data-disabled] {
+        [data-bottom-labels] {
+            color: var(--foreground-neutral-disabled-on-surface);
+        }
+
+        [data-value-label] {
+            color: var(--foreground-neutral-disabled-on-surface);
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Slider/useNormalizeSliderValue.ts

@@ -0,0 +1,16 @@
+export const useNormalizeSliderValue = ({ min, max, step }: { min: number; max: number; step: number }) => {
+    const clamp = (val: number) => Math.min(Math.max(val, min), max);
+
+    const normalizeSliderValue = (val: number) => {
+        let newValue = clamp(val);
+
+        newValue = Math.round(newValue / step) * step;
+
+        // Fix floating-point precision issues
+        newValue = parseFloat(newValue.toFixed(10));
+
+        return clamp(newValue);
+    };
+
+    return { normalizeSliderValue };
+};

package/src/components/StylesProviderAnywhere/StylesProviderAnywhere.tsx

@@ -1,17 +1,15 @@
 import '@bspk/styles/anywhere.css';
-import '../../base.scss';
+import '-/styles/base.scss';
 
 /**
  * Utility to provide the Anywhere styles to the application.
  *
  * @name StylesProviderAnywhere
+ * @phase Utility
+ * @generated
  */
-function StylesProviderAnywhere(): JSX.Element | null {
+export function StylesProviderAnywhere(): JSX.Element | null {
     return null;
 }
 
-StylesProviderAnywhere.bspkName = 'StylesProviderAnywhere';
-
-export { StylesProviderAnywhere };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/StylesProviderBetterHomesGardens/StylesProviderBetterHomesGardens.tsx

@@ -1,17 +1,15 @@
 import '@bspk/styles/better-homes-gardens.css';
-import '../../base.scss';
+import '-/styles/base.scss';
 
 /**
  * Utility to provide the Better Homes & Gardens styles to the application.
  *
  * @name StylesProviderBetterHomesGardens
+ * @phase Utility
+ * @generated
  */
-function StylesProviderBetterHomesGardens(): JSX.Element | null {
+export function StylesProviderBetterHomesGardens(): JSX.Element | null {
     return null;
 }
 
-StylesProviderBetterHomesGardens.bspkName = 'StylesProviderBetterHomesGardens';
-
-export { StylesProviderBetterHomesGardens };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/StylesProviderCartus/StylesProviderCartus.tsx

@@ -1,17 +1,15 @@
 import '@bspk/styles/cartus.css';
-import '../../base.scss';
+import '-/styles/base.scss';
 
 /**
  * Utility to provide the Cartus styles to the application.
  *
  * @name StylesProviderCartus
+ * @phase Utility
+ * @generated
  */
-function StylesProviderCartus(): JSX.Element | null {
+export function StylesProviderCartus(): JSX.Element | null {
     return null;
 }
 
-StylesProviderCartus.bspkName = 'StylesProviderCartus';
-
-export { StylesProviderCartus };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/StylesProviderCentury21/StylesProviderCentury21.tsx

@@ -1,17 +1,15 @@
 import '@bspk/styles/century-21.css';
-import '../../base.scss';
+import '-/styles/base.scss';
 
 /**
  * Utility to provide the Century 21 styles to the application.
  *
  * @name StylesProviderCentury21
+ * @phase Utility
+ * @generated
  */
-function StylesProviderCentury21(): JSX.Element | null {
+export function StylesProviderCentury21(): JSX.Element | null {
     return null;
 }
 
-StylesProviderCentury21.bspkName = 'StylesProviderCentury21';
-
-export { StylesProviderCentury21 };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/StylesProviderColdwellBanker/StylesProviderColdwellBanker.tsx

@@ -1,17 +1,15 @@
 import '@bspk/styles/coldwell-banker.css';
-import '../../base.scss';
+import '-/styles/base.scss';
 
 /**
  * Utility to provide the Coldwell Banker styles to the application.
  *
  * @name StylesProviderColdwellBanker
+ * @phase Utility
+ * @generated
  */
-function StylesProviderColdwellBanker(): JSX.Element | null {
+export function StylesProviderColdwellBanker(): JSX.Element | null {
     return null;
 }
 
-StylesProviderColdwellBanker.bspkName = 'StylesProviderColdwellBanker';
-
-export { StylesProviderColdwellBanker };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/StylesProviderCorcoran/StylesProviderCorcoran.tsx

@@ -1,17 +1,15 @@
 import '@bspk/styles/corcoran.css';
-import '../../base.scss';
+import '-/styles/base.scss';
 
 /**
  * Utility to provide the Corcoran styles to the application.
  *
  * @name StylesProviderCorcoran
+ * @phase Utility
+ * @generated
  */
-function StylesProviderCorcoran(): JSX.Element | null {
+export function StylesProviderCorcoran(): JSX.Element | null {
     return null;
 }
 
-StylesProviderCorcoran.bspkName = 'StylesProviderCorcoran';
-
-export { StylesProviderCorcoran };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */