jfs-components 0.1.2 → 0.1.12

package/src/components/Slider/Slider.tsx

@@ -0,0 +1,635 @@
+import React, {
+    forwardRef,
+    useCallback,
+    useImperativeHandle,
+    useMemo,
+    useRef,
+    useState,
+} from 'react'
+import {
+    View,
+    Text,
+    PanResponder,
+    Platform,
+    type LayoutChangeEvent,
+    type GestureResponderEvent,
+    type StyleProp,
+    type ViewStyle,
+    type TextStyle,
+} from 'react-native'
+import Svg, { Path } from 'react-native-svg'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { EMPTY_MODES, resolveTruncation } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
+
+/**
+ * Imperative handle exposed via `ref`. The primary way to read a slider's value
+ * is still the controlled `value` + `onChange` pair (each `<Slider />` reports
+ * its own value, so multiple sliders are disambiguated by their own handlers).
+ * The ref is a convenience for reading the latest value on demand (e.g. on a
+ * button press) or imperatively nudging an uncontrolled slider.
+ *
+ * @example
+ * const slider = useRef<SliderHandle>(null)
+ * slider.current?.setValue(50)
+ * const v = slider.current?.getValue()
+ */
+export interface SliderHandle {
+    /** Returns the slider's current (clamped, step-snapped) value. */
+    getValue: () => number
+    /** Sets the value. Fires `onChange` + `onChangeEnd`. */
+    setValue: (value: number) => void
+    /** Steps the value up by one `step` (or `by`, snapped to `step`). */
+    increment: (by?: number) => void
+    /** Steps the value down by one `step` (or `by`, snapped to `step`). */
+    decrement: (by?: number) => void
+}
+
+export interface SliderProps {
+    /** Current value (controlled). Pair with `onChange`. */
+    value?: number
+    /** Initial value (uncontrolled). Defaults to `minValue`. */
+    defaultValue?: number
+    /** Called continuously while the value changes (drag / keypress / track press). */
+    onChange?: (value: number) => void
+    /** Called once when the interaction ends (drag release / keypress). */
+    onChangeEnd?: (value: number) => void
+    /** Minimum selectable value. Defaults to `0`. */
+    minValue?: number
+    /** Maximum selectable value. Defaults to `100`. */
+    maxValue?: number
+    /** Snap increment. Defaults to `1`. Use a smaller value for finer control. */
+    step?: number
+    /** Disables interaction and dims the control. */
+    isDisabled?: boolean
+    /**
+     * `Intl.NumberFormat` options used to format the value bubble and the
+     * min/max labels (e.g. `{ style: 'currency', currency: 'USD' }`).
+     */
+    formatOptions?: Intl.NumberFormatOptions
+    /** BCP-47 locale used with `formatOptions`. Defaults to the runtime locale. */
+    locale?: string
+    /**
+     * Full override for value formatting. Takes precedence over `formatOptions`.
+     * Receives the raw numeric value, returns the string to display.
+     */
+    formatValue?: (value: number) => string
+    /** Renders fully custom value-bubble content. Takes precedence over `formatValue`. */
+    renderTooltip?: (value: number) => React.ReactNode
+    /**
+     * When `true` (default, matches the Figma design) the value bubble is
+     * always visible. When `false` it behaves like a normal tooltip — hidden at
+     * rest and revealed only while the user interacts (dragging on touch, or
+     * hovering/dragging on web), then dismissed as soon as the finger lifts.
+     *
+     * Either way the bubble floats above the track and never occupies layout
+     * space, so it will overlap content above the slider — leave room for it.
+     */
+    alwaysShowTooltip?: boolean
+    /** Toggles the min/max labels below the track. Defaults to `true`. */
+    showLabels?: boolean
+    /** Override for the left (min) label. Defaults to the formatted `minValue`. */
+    minLabel?: React.ReactNode
+    /** Override for the right (max) label. Defaults to the formatted `maxValue`. */
+    maxLabel?: React.ReactNode
+    /** Slider width. Defaults to `'100%'` so it fills its parent. */
+    width?: number | `${number}%`
+    /** Design-token modes for theming. */
+    modes?: Modes
+    /** Style override for the outer container. */
+    style?: StyleProp<ViewStyle>
+    /** Accessibility label for screen readers. */
+    accessibilityLabel?: string
+    /**
+     * When `true`, disables text truncation: the trailing ellipsis (`…`) is never
+     * shown and any `numberOfLines` clamp is ignored, so the text wraps to as many
+     * lines as it needs even when horizontal space is tight.
+     */
+    disableTruncation?: boolean
+}
+
+const clamp = (n: number, min: number, max: number) => Math.min(Math.max(n, min), max)
+
+const asNum = (raw: unknown, fallback: number): number => {
+    const n = typeof raw === 'number' ? raw : parseFloat(raw as string)
+    return Number.isFinite(n) ? n : fallback
+}
+
+const asStr = (raw: unknown, fallback: string): string => (raw != null ? String(raw) : fallback)
+
+// The unfilled track is rendered at a lighter emphasis in the design.
+const TRACK_EMPHASIS: Modes = { Emphasis: 'Low' }
+
+/**
+ * Slider — Figma node 5373:446 ("Slider").
+ *
+ * A horizontal, single-thumb slider driven entirely by design tokens. It maps a
+ * numeric range (`minValue`–`maxValue`) onto a track with a filled indicator, a
+ * draggable handle, a value bubble pinned above the handle, and optional min/max
+ * labels beneath the track. Built on `PanResponder` so the one code path works
+ * on iOS, Android and the web.
+ *
+ * The design only labels the range bounds, but a slider's purpose is to bind a
+ * value — so the live value is surfaced through the bubble (formatted via
+ * `formatOptions` / `formatValue`) and reported through `onChange` /
+ * `onChangeEnd`. Supports controlled and uncontrolled usage, web keyboard
+ * control, and an imperative {@link SliderHandle} `ref` for on-demand reads.
+ */
+const Slider = forwardRef<SliderHandle, SliderProps>(function Slider(
+    {
+        value: controlledValue,
+        defaultValue,
+        onChange,
+        onChangeEnd,
+        minValue = 0,
+        maxValue = 100,
+        step = 1,
+        isDisabled = false,
+        formatOptions,
+        locale,
+        formatValue,
+        renderTooltip,
+        alwaysShowTooltip = true,
+        showLabels = true,
+        minLabel,
+        maxLabel,
+        width = '100%',
+        modes = EMPTY_MODES,
+        style,
+        accessibilityLabel,
+        disableTruncation,
+    },
+    ref
+) {
+    const tokens = useMemo(() => resolveTokens(modes), [modes])
+
+    const isControlled = controlledValue !== undefined
+    const [internalValue, setInternalValue] = useState(() =>
+        clamp(defaultValue ?? minValue, minValue, maxValue)
+    )
+    const rawValue = isControlled ? (controlledValue as number) : internalValue
+    const currentValue = clamp(rawValue, minValue, maxValue)
+
+    const [trackWidth, setTrackWidth] = useState(0)
+    const [tooltipWidth, setTooltipWidth] = useState(0)
+    const [isDragging, setIsDragging] = useState(false)
+    const [isHovered, setIsHovered] = useState(false)
+
+    const quantize = useCallback(
+        (v: number) => {
+            if (!step || step <= 0) return clamp(v, minValue, maxValue)
+            const stepped = Math.round((v - minValue) / step) * step + minValue
+            // Round away float dust introduced by the division (e.g. 0.30000000000004).
+            const decimals = (String(step).split('.')[1] || '').length
+            const fixed = decimals > 0 ? Number(stepped.toFixed(decimals)) : stepped
+            return clamp(fixed, minValue, maxValue)
+        },
+        [minValue, maxValue, step]
+    )
+
+    // Keep the latest interactive config in a ref so the PanResponder (created
+    // once) always reads fresh values without being recreated mid-gesture.
+    const interaction = useRef({
+        trackWidth,
+        minValue,
+        maxValue,
+        isDisabled,
+        isControlled,
+        quantize,
+        onChange,
+        onChangeEnd,
+    })
+    interaction.current = {
+        trackWidth,
+        minValue,
+        maxValue,
+        isDisabled,
+        isControlled,
+        quantize,
+        onChange,
+        onChangeEnd,
+    }
+
+    const lastValueRef = useRef(currentValue)
+    lastValueRef.current = currentValue
+
+    const commit = useCallback((next: number, isFinal: boolean) => {
+        const { isControlled: ctrl, onChange: change, onChangeEnd: changeEnd } = interaction.current
+        const changed = next !== lastValueRef.current
+        lastValueRef.current = next
+        if (changed) {
+            if (!ctrl) setInternalValue(next)
+            change?.(next)
+        }
+        if (isFinal) changeEnd?.(next)
+    }, [])
+
+    const valueFromX = useCallback((x: number): number => {
+        const { trackWidth: w, minValue: min, maxValue: max, quantize: q } = interaction.current
+        if (w <= 0) return lastValueRef.current
+        const ratio = clamp(x / w, 0, 1)
+        return q(min + ratio * (max - min))
+    }, [])
+
+    const panResponder = useRef(
+        PanResponder.create({
+            onStartShouldSetPanResponder: () => !interaction.current.isDisabled,
+            onMoveShouldSetPanResponder: () => !interaction.current.isDisabled,
+            onPanResponderGrant: (e: GestureResponderEvent) => {
+                if (interaction.current.isDisabled) return
+                setIsDragging(true)
+                commit(valueFromX(e.nativeEvent.locationX), false)
+            },
+            onPanResponderMove: (e: GestureResponderEvent) => {
+                if (interaction.current.isDisabled) return
+                commit(valueFromX(e.nativeEvent.locationX), false)
+            },
+            onPanResponderRelease: (e: GestureResponderEvent) => {
+                setIsDragging(false)
+                if (interaction.current.isDisabled) return
+                commit(valueFromX(e.nativeEvent.locationX), true)
+            },
+            onPanResponderTerminate: () => {
+                setIsDragging(false)
+                if (interaction.current.isDisabled) return
+                commit(lastValueRef.current, true)
+            },
+        })
+    ).current
+
+    // Keyboard support (web). Arrow/Page keys nudge, Home/End jump to bounds.
+    const handleKeyDown = useCallback(
+        (e: any) => {
+            if (isDisabled) return
+            const big = Math.max(step, (maxValue - minValue) / 10)
+            let next: number | null = null
+            switch (e.key) {
+                case 'ArrowRight':
+                case 'ArrowUp':
+                    next = quantize(currentValue + step)
+                    break
+                case 'ArrowLeft':
+                case 'ArrowDown':
+                    next = quantize(currentValue - step)
+                    break
+                case 'PageUp':
+                    next = quantize(currentValue + big)
+                    break
+                case 'PageDown':
+                    next = quantize(currentValue - big)
+                    break
+                case 'Home':
+                    next = minValue
+                    break
+                case 'End':
+                    next = maxValue
+                    break
+                default:
+                    return
+            }
+            e.preventDefault?.()
+            commit(next, true)
+        },
+        [isDisabled, step, minValue, maxValue, currentValue, quantize, commit]
+    )
+
+    const handleAccessibilityAction = useCallback(
+        (event: { nativeEvent: { actionName: string } }) => {
+            if (isDisabled) return
+            const name = event.nativeEvent.actionName
+            if (name === 'increment') commit(quantize(currentValue + step), true)
+            else if (name === 'decrement') commit(quantize(currentValue - step), true)
+        },
+        [isDisabled, step, currentValue, quantize, commit]
+    )
+
+    useImperativeHandle(
+        ref,
+        (): SliderHandle => ({
+            getValue: () => lastValueRef.current,
+            setValue: (v: number) => commit(quantize(v), true),
+            increment: (by?: number) => commit(quantize(lastValueRef.current + (by ?? step)), true),
+            decrement: (by?: number) => commit(quantize(lastValueRef.current - (by ?? step)), true),
+        }),
+        [quantize, commit, step]
+    )
+
+    const defaultFormat = useCallback(
+        (v: number) => {
+            try {
+                return new Intl.NumberFormat(locale, formatOptions).format(v)
+            } catch {
+                return String(v)
+            }
+        },
+        [locale, formatOptions]
+    )
+    const format = formatValue ?? defaultFormat
+
+    const ratio = maxValue > minValue ? (currentValue - minValue) / (maxValue - minValue) : 0
+    const percent = clamp(ratio, 0, 1) * 100
+
+    const handleSize = tokens.handleSize
+    // The bubble floats (absolutely positioned, no reserved layout space). When
+    // `alwaysShowTooltip` is false it only appears while interacting: dragging on
+    // any platform, or hovering on web. Lifting the finger clears `isDragging`,
+    // so the bubble disappears immediately on touch release.
+    const showTooltip = alwaysShowTooltip || isDragging || isHovered
+
+    const onTrackLayout = useCallback((e: LayoutChangeEvent) => {
+        setTrackWidth(e.nativeEvent.layout.width)
+    }, [])
+
+    const onTooltipLayout = useCallback((e: LayoutChangeEvent) => {
+        setTooltipWidth(e.nativeEvent.layout.width)
+    }, [])
+
+    const valueText = format(currentValue)
+
+    const tooltipNode = showTooltip ? (
+        <View
+            onLayout={onTooltipLayout}
+            style={[
+                styles.tooltip,
+                {
+                    backgroundColor: tokens.tooltipBackground,
+                    paddingHorizontal: tokens.tooltipPaddingH,
+                    paddingVertical: tokens.tooltipPaddingV,
+                    borderRadius: tokens.tooltipRadius,
+                    maxWidth: tokens.tooltipMaxWidth,
+                    bottom: handleSize + tokens.tooltipWrapGap,
+                    // Pinned to the value point on the full-width track area (not
+                    // the tiny handle-width thumb). An absolute child with only
+                    // `left` set is clamped by Yoga to `parentWidth - left`, so
+                    // parenting it to the 20px thumb collapsed the text to ~0px
+                    // and rendered an empty bubble on device. Centre via translate.
+                    left: `${percent}%`,
+                    transform: [{ translateX: -tooltipWidth / 2 }],
+                },
+            ]}
+            pointerEvents="none"
+        >
+            {renderTooltip ? (
+                renderTooltip(currentValue)
+            ) : (
+                <Text style={tokens.tooltipLabel} {...resolveTruncation(disableTruncation, 1)}>
+                    {valueText}
+                </Text>
+            )}
+            <View style={[styles.tip, { bottom: -tokens.tipHeight }]} pointerEvents="none">
+                <Svg
+                    width={tokens.tipWidth}
+                    height={tokens.tipHeight}
+                    viewBox={`0 0 ${tokens.tipWidth} ${tokens.tipHeight}`}
+                >
+                    <Path
+                        d={`M0 0 L${tokens.tipWidth / 2} ${tokens.tipHeight} L${tokens.tipWidth} 0 Z`}
+                        fill={tokens.tooltipBackground}
+                    />
+                </Svg>
+            </View>
+        </View>
+    ) : null
+
+    return (
+        <View
+            style={[
+                {
+                    width,
+                    gap: tokens.gap,
+                    paddingTop: tokens.paddingTop,
+                    paddingBottom: tokens.paddingBottom,
+                    paddingLeft: tokens.paddingLeft,
+                    paddingRight: tokens.paddingRight,
+                    opacity: isDisabled ? 0.5 : 1,
+                },
+                style,
+            ]}
+            accessibilityLabel={accessibilityLabel}
+        >
+            {/* Track area — the PanResponder target spans the full track width. */}
+            <View
+                {...panResponder.panHandlers}
+                onLayout={onTrackLayout}
+                style={[styles.trackArea, { height: handleSize }]}
+                accessible
+                accessibilityRole="adjustable"
+                accessibilityLabel={accessibilityLabel}
+                accessibilityValue={{ min: minValue, max: maxValue, now: currentValue, text: valueText }}
+                accessibilityState={{ disabled: isDisabled }}
+                accessibilityActions={[{ name: 'increment' }, { name: 'decrement' }]}
+                onAccessibilityAction={handleAccessibilityAction}
+                focusable={!isDisabled}
+                {...(Platform.OS === 'web'
+                    ? {
+                          onKeyDown: handleKeyDown,
+                          tabIndex: isDisabled ? -1 : 0,
+                          onMouseEnter: () => !isDisabled && setIsHovered(true),
+                          onMouseLeave: () => setIsHovered(false),
+                      }
+                    : {})}
+            >
+                {/* Track */}
+                <View
+                    style={{
+                        height: tokens.trackHeight,
+                        borderRadius: tokens.trackRadius,
+                        backgroundColor: tokens.trackBackground,
+                    }}
+                />
+                {/* Filled indicator */}
+                <View
+                    pointerEvents="none"
+                    style={{
+                        position: 'absolute',
+                        left: 0,
+                        top: (handleSize - tokens.indicatorHeight) / 2,
+                        height: tokens.indicatorHeight,
+                        width: `${percent}%`,
+                        borderRadius: tokens.indicatorRadius,
+                        backgroundColor: tokens.indicatorBackground,
+                    }}
+                />
+                {/* Thumb (handle), centred on the value point */}
+                <View
+                    pointerEvents="none"
+                    style={{
+                        position: 'absolute',
+                        top: 0,
+                        left: `${percent}%`,
+                        width: handleSize,
+                        height: handleSize,
+                        transform: [{ translateX: -handleSize / 2 }],
+                    }}
+                >
+                    <View
+                        style={{
+                            width: handleSize,
+                            height: handleSize,
+                            borderRadius: tokens.handleRadius,
+                            backgroundColor: tokens.handleBackground,
+                        }}
+                    />
+                </View>
+                {/* Value bubble — parented to the full-width track area so it can
+                    size to its content (see the note on the tooltip's `left`). */}
+                {tooltipNode}
+            </View>
+
+            {/* Min / max labels */}
+            {showLabels ? (
+                <View style={styles.labelWrap}>
+                    <Text style={tokens.label}>{minLabel ?? format(minValue)}</Text>
+                    <Text style={tokens.label}>{maxLabel ?? format(maxValue)}</Text>
+                </View>
+            ) : null}
+        </View>
+    )
+})
+
+interface ResolvedTokens {
+    gap: number
+    paddingTop: number
+    paddingBottom: number
+    paddingLeft: number
+    paddingRight: number
+    trackHeight: number
+    trackRadius: number
+    trackBackground: string
+    indicatorHeight: number
+    indicatorRadius: number
+    indicatorBackground: string
+    handleSize: number
+    handleRadius: number
+    handleBackground: string
+    tooltipWrapGap: number
+    tooltipBackground: string
+    tooltipPaddingH: number
+    tooltipPaddingV: number
+    tooltipRadius: number
+    tooltipMaxWidth: number
+    tooltipLineHeight: number
+    tipWidth: number
+    tipHeight: number
+    tooltipLabel: TextStyle
+    label: TextStyle
+}
+
+function resolveTokens(modes: Modes): ResolvedTokens {
+    // NOTE: token names are passed as string literals DIRECTLY to
+    // getVariableByName so the `extract-component-tokens` script can statically
+    // collect them for the generated docs. Do not refactor into a helper that
+    // receives the name as a variable.
+    const gap = asNum(getVariableByName('slider/gap', modes), 16)
+    const paddingTop = asNum(getVariableByName('slider/padding/top', modes), 8)
+    const paddingBottom = asNum(getVariableByName('slider/padding/bottom', modes), 0)
+    const paddingLeft = asNum(getVariableByName('slider/padding/left', modes), 0)
+    const paddingRight = asNum(getVariableByName('slider/padding/right', modes), 0)
+
+    const trackHeight = asNum(getVariableByName('slider/track/height', modes), 4)
+    const trackRadius = asNum(getVariableByName('slider/track/radius', modes), 999)
+    // The unfilled track uses a lighter emphasis in the design; consumer modes
+    // still win over the baked-in `Emphasis: Low`.
+    const trackBackground = asStr(
+        getVariableByName('slider/track/background', { ...TRACK_EMPHASIS, ...modes }),
+        '#fde8c9'
+    )
+
+    const indicatorHeight = asNum(getVariableByName('slider/indicator/height', modes), 4)
+    const indicatorRadius = asNum(getVariableByName('slider/indicator/radius', modes), 999)
+    const indicatorBackground = asStr(getVariableByName('slider/indicator/background', modes), '#f7ab21')
+
+    const handleSize = asNum(getVariableByName('slider/handle/size', modes), 20)
+    const handleRadius = asNum(getVariableByName('slider/handle/radius', modes), 999999)
+    const handleBackground = asStr(getVariableByName('slider/handle/background', modes), '#f7ab21')
+
+    const tooltipWrapGap = asNum(getVariableByName('slider/tooltipWrap/gap', modes), 12)
+    const tooltipBackground = asStr(getVariableByName('tooltip/background', modes), '#0f0d0a')
+    const tooltipPaddingH = asNum(getVariableByName('tooltip/padding/horizontal', modes), 12)
+    const tooltipPaddingV = asNum(getVariableByName('tooltip/padding/vertical', modes), 8)
+    const tooltipRadius = asNum(getVariableByName('radius', modes), 8)
+    const tooltipMaxWidth = asNum(getVariableByName('maxWidth', modes), 280)
+    const tipWidth = asNum(getVariableByName('tooltip/tipItem/width', modes), 16)
+    const tipHeight = asNum(getVariableByName('tooltip/tipItem/height', modes), 8)
+
+    const tooltipLabelColor = asStr(getVariableByName('tooltip/label/color', modes), '#ffffff')
+    const tooltipLabelSize = asNum(getVariableByName('tooltip/label/fontSize', modes), 14)
+    const tooltipLabelFamily = asStr(getVariableByName('tooltip/lable/fontFamily', modes), 'JioType Var')
+    const tooltipLabelLineHeight = asNum(getVariableByName('tooltip/label/lineHeight', modes), 18)
+    const tooltipLabelWeight = asStr(getVariableByName('tooltip/label/fontWeight', modes), '500')
+
+    const labelColor = asStr(getVariableByName('text/foreground', modes), '#000000')
+    const labelSize = asNum(getVariableByName('text/fontSize', modes), 14)
+    const labelFamily = asStr(getVariableByName('text/fontFamily', modes), 'JioType Var')
+    const labelLineHeight = asNum(getVariableByName('text/lineHeight', modes), 20)
+    const labelWeight = asStr(getVariableByName('text/fontWeight', modes), '500')
+    const labelLetterSpacing = asNum(getVariableByName('text/letterSpacing', modes), -0.5)
+
+    return {
+        gap,
+        paddingTop,
+        paddingBottom,
+        paddingLeft,
+        paddingRight,
+        trackHeight,
+        trackRadius,
+        trackBackground,
+        indicatorHeight,
+        indicatorRadius,
+        indicatorBackground,
+        handleSize,
+        handleRadius,
+        handleBackground,
+        tooltipWrapGap,
+        tooltipBackground,
+        tooltipPaddingH,
+        tooltipPaddingV,
+        tooltipRadius,
+        tooltipMaxWidth,
+        tooltipLineHeight: tooltipLabelLineHeight,
+        tipWidth,
+        tipHeight,
+        tooltipLabel: {
+            color: tooltipLabelColor,
+            fontSize: tooltipLabelSize,
+            fontFamily: tooltipLabelFamily,
+            lineHeight: tooltipLabelLineHeight,
+            fontWeight: tooltipLabelWeight as TextStyle['fontWeight'],
+            includeFontPadding: false as any,
+        },
+        label: {
+            color: labelColor,
+            fontSize: labelSize,
+            fontFamily: labelFamily,
+            lineHeight: labelLineHeight,
+            fontWeight: labelWeight as TextStyle['fontWeight'],
+            letterSpacing: labelLetterSpacing,
+            includeFontPadding: false as any,
+        },
+    }
+}
+
+const styles = {
+    trackArea: {
+        width: '100%',
+        justifyContent: 'center',
+        position: 'relative',
+    } as ViewStyle,
+    labelWrap: {
+        flexDirection: 'row',
+        justifyContent: 'space-between',
+        alignItems: 'flex-start',
+        width: '100%',
+    } as ViewStyle,
+    tooltip: {
+        position: 'absolute',
+        alignItems: 'center',
+        justifyContent: 'center',
+    } as ViewStyle,
+    tip: {
+        position: 'absolute',
+        alignSelf: 'center',
+    } as ViewStyle,
+}
+
+export default Slider