jfs-components 0.0.71 → 0.0.73

package/src/components/OTP/OTP.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useRef, useCallback, useEffect } from 'react'
+import React, { useState, useRef, useCallback, useEffect, useMemo } from 'react'
 import {
     View,
     Text,
@@ -12,8 +12,310 @@ import {
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import SupportText, { type SupportTextProps } from '../SupportText/SupportText'
+import Button from '../Button/Button'
 import { cloneChildrenWithModes, EMPTY_MODES } from '../../utils/react-utils'
 
+// Default mode overrides for the resend Button. Per design: a small,
+// low-emphasis, neutral-appearance button. Consumers can override any of
+// these via OTPResendConfig.resendButtonModes.
+const DEFAULT_RESEND_BUTTON_MODES = {
+    AppearanceBrand: 'Neutral',
+    'Button / Size': 'S',
+    Emphasis: 'Low',
+} as const
+
+// ---------------------------------------------------------------------------
+// useOtpResend — headless state machine for the resend countdown.
+//
+// State machine: counting -> ready -> sending -> counting -> ...
+//
+//   counting  : timer is ticking down; resend button disabled.
+//   ready     : timer elapsed; resend button enabled.
+//   sending   : an in-flight onResend() promise is pending; button shows
+//               a transient "sending" label, prevents double-fire, and
+//               restarts the countdown only on resolve.
+//
+// Designed as a hook so consumers can render any UI they want and still
+// reuse the timing/lifecycle logic. The OTPResend component below is the
+// opinionated default.
+// ---------------------------------------------------------------------------
+
+export type OtpResendState = 'counting' | 'ready' | 'sending'
+
+export type UseOtpResendOptions = {
+    /** Countdown length in seconds. Defaults to 30. */
+    durationSeconds?: number | undefined
+    /** Called when the user requests a resend. May return a Promise; while pending, state is 'sending'. */
+    onResend?: (() => void | Promise<void>) | undefined
+    /** Whether the countdown should auto-start on mount. Defaults to true. */
+    autoStart?: boolean | undefined
+}
+
+export type UseOtpResendReturn = {
+    state: OtpResendState
+    /** Seconds remaining in the current countdown (0 when not counting). */
+    secondsLeft: number
+    /** True while state === 'ready'. */
+    canResend: boolean
+    /** True while state === 'sending'. */
+    isSending: boolean
+    /**
+     * Trigger a resend. No-op unless state === 'ready'. Awaits onResend()
+     * before restarting the countdown. Re-throws any onResend rejection
+     * so callers can surface the failure (state returns to 'ready').
+     */
+    resend: () => Promise<void>
+    /** Manually start (or restart) the countdown. */
+    restart: (durationSeconds?: number) => void
+    /** Stop the countdown and move to 'ready' (without invoking onResend). */
+    skip: () => void
+}
+
+/**
+ * Headless hook that drives an OTP resend countdown.
+ *
+ * The hook is intentionally UI-agnostic: it returns just enough state
+ * (`state`, `secondsLeft`, plus `resend()` / `restart()` / `skip()`) so
+ * consumers can render their own button, support text, etc. The bundled
+ * `OTPResend` component is the canonical UI on top of this hook.
+ */
+export function useOtpResend({
+    durationSeconds = 30,
+    onResend,
+    autoStart = true,
+}: UseOtpResendOptions = {}): UseOtpResendReturn {
+    // Initial state: if we're auto-starting, we begin in 'counting' with
+    // the full duration; otherwise we go straight to 'ready' (handy for
+    // flows where a previous screen already triggered the SMS and we
+    // mount with the timer already elapsed).
+    const [state, setState] = useState<OtpResendState>(autoStart ? 'counting' : 'ready')
+    const [secondsLeft, setSecondsLeft] = useState<number>(autoStart ? durationSeconds : 0)
+
+    // Keep a ref to the latest onResend so the resend() callback is stable
+    // even if consumers pass an inline arrow function on every render.
+    const onResendRef = useRef(onResend)
+    useEffect(() => {
+        onResendRef.current = onResend
+    }, [onResend])
+
+    const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+    const stopTicker = useCallback(() => {
+        if (intervalRef.current !== null) {
+            clearInterval(intervalRef.current)
+            intervalRef.current = null
+        }
+    }, [])
+
+    const startTicker = useCallback(
+        (seconds: number) => {
+            stopTicker()
+            const initial = Math.max(0, Math.floor(seconds))
+            if (initial === 0) {
+                setState('ready')
+                setSecondsLeft(0)
+                return
+            }
+            setState('counting')
+            setSecondsLeft(initial)
+            intervalRef.current = setInterval(() => {
+                setSecondsLeft((prev) => {
+                    if (prev <= 1) {
+                        stopTicker()
+                        setState('ready')
+                        return 0
+                    }
+                    return prev - 1
+                })
+            }, 1000)
+        },
+        [stopTicker],
+    )
+
+    // Auto-start once on mount if requested. We deliberately omit
+    // `durationSeconds` from the dependency array so changing the prop
+    // mid-flight does not silently reset the countdown — consumers should
+    // call `restart()` explicitly when they want a new duration.
+    useEffect(() => {
+        if (autoStart) startTicker(durationSeconds)
+        return stopTicker
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    const resend = useCallback(async () => {
+        // Guard against double-fire and out-of-state taps (e.g. an
+        // accessibility re-tap while we're already in 'sending').
+        if (state !== 'ready') return
+        try {
+            setState('sending')
+            const result = onResendRef.current?.()
+            if (result && typeof (result as Promise<void>).then === 'function') {
+                await result
+            }
+            startTicker(durationSeconds)
+        } catch (e) {
+            // Surface the failure — the consumer can decide whether to
+            // show a toast, retry, etc. We move back to 'ready' so the
+            // user can try again immediately.
+            setState('ready')
+            throw e
+        }
+    }, [state, durationSeconds, startTicker])
+
+    const restart = useCallback(
+        (next?: number) => {
+            startTicker(next ?? durationSeconds)
+        },
+        [durationSeconds, startTicker],
+    )
+
+    const skip = useCallback(() => {
+        stopTicker()
+        setState('ready')
+        setSecondsLeft(0)
+    }, [stopTicker])
+
+    return {
+        state,
+        secondsLeft,
+        canResend: state === 'ready',
+        isSending: state === 'sending',
+        resend,
+        restart,
+        skip,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// OTPResend — opinionated UI built on useOtpResend.
+//
+// Renders a SupportText line that shows "Resend OTP in {n}s" while the
+// countdown is active, and turns into a tappable "Resend" button once the
+// countdown elapses. Re-tapping is debounced via the hook's state machine.
+//
+// Exported as a standalone so consumers can position it anywhere in their
+// layout (it does not need to live inside <OTP />). When passed via
+// <OTP resend={...} />, OTP renders this internally in the support area.
+// ---------------------------------------------------------------------------
+
+export type OTPResendConfig = {
+    /** Countdown length in seconds. Defaults to 30. */
+    durationSeconds?: number
+    /** Called when the user taps the resend button. May return a Promise. */
+    onResend?: () => void | Promise<void>
+    /** Whether the countdown should auto-start on mount. Defaults to true. */
+    autoStart?: boolean
+    /** Format the countdown line. Defaults to (s) => `Resend OTP in ${s}s`. */
+    formatCountdown?: (secondsLeft: number) => string
+    /** Label shown in the 'sending' state. Defaults to "Sending…". */
+    sendingLabel?: string
+    /** Label shown when ready to resend. Defaults to "Resend". */
+    resendLabel?: string
+    /** SupportText status applied while counting. Defaults to "Loading" (clock icon). */
+    countdownStatus?: SupportTextProps['status']
+    /**
+     * Mode overrides for the resend Button (in the 'ready' state). Merged
+     * on top of the component default of `{ AppearanceBrand: 'Neutral',
+     * 'Button / Size': 'S', Emphasis: 'Low' }`. Use this to swap to a
+     * different brand/size/emphasis without touching the rest of the UI.
+     */
+    resendButtonModes?: Record<string, any>
+}
+
+export type OTPResendProps = OTPResendConfig & {
+    modes?: Record<string, any>
+    style?: StyleProp<ViewStyle>
+}
+
+const defaultFormatCountdown = (s: number) => `Resend OTP in ${s}s`
+
+export function OTPResend({
+    durationSeconds = 30,
+    onResend,
+    autoStart = true,
+    formatCountdown,
+    sendingLabel = 'Sending…',
+    resendLabel = 'Resend',
+    countdownStatus = 'Loading',
+    resendButtonModes,
+    modes: propModes = EMPTY_MODES,
+    style,
+}: OTPResendProps) {
+    const { modes: globalModes } = useTokens()
+    const modes = useMemo(() => ({ ...globalModes, ...propModes }), [globalModes, propModes])
+
+    // The Button gets the consumer's modes layered first, then the
+    // component-default brand/size/emphasis trio, and finally any caller
+    // overrides via `resendButtonModes`. Spreading in this order lets
+    // consumers (a) keep theming like Color Mode propagating through,
+    // (b) rely on the small/low/neutral defaults out of the box, and
+    // (c) selectively override e.g. `Button / Size: 'M'` without losing
+    // the other defaults.
+    const resolvedButtonModes = useMemo(
+        () => ({ ...modes, ...DEFAULT_RESEND_BUTTON_MODES, ...resendButtonModes }),
+        [modes, resendButtonModes],
+    )
+
+    const { state, secondsLeft, canResend, resend } = useOtpResend({
+        durationSeconds,
+        onResend,
+        autoStart,
+    })
+
+    const formatter = formatCountdown ?? defaultFormatCountdown
+
+    // counting → static SupportText. Not a Pressable: tapping the
+    // countdown should not do anything (it's an inert status line).
+    if (state === 'counting') {
+        return (
+            <SupportText
+                label={formatter(secondsLeft)}
+                status={countdownStatus}
+                modes={modes}
+                style={style}
+            />
+        )
+    }
+
+    // sending → static SupportText with a transient "Sending…" label so
+    // the user has clear feedback that their tap was received and we
+    // don't accept another tap until the resend completes.
+    if (state === 'sending') {
+        return (
+            <SupportText
+                label={sendingLabel}
+                status={countdownStatus}
+                modes={modes}
+                style={style}
+            />
+        )
+    }
+
+    // ready → render a real Button (no leading/trailing icon — design
+    // calls for a clean text-only pill once the countdown elapses). The
+    // Button handles its own pressed/hover states from tokens, so we
+    // don't need to layer extra opacity etc. on top.
+    return (
+        <Button
+            label={resendLabel}
+            modes={resolvedButtonModes}
+            disabled={!canResend}
+            onPress={() => {
+                // Swallow rejections here — the hook re-throws so callers
+                // wiring useOtpResend directly can react, but at the
+                // component boundary we never want an unhandled promise.
+                resend().catch(() => {})
+            }}
+            accessibilityLabel={resendLabel}
+            style={style}
+        />
+    )
+}
+
+// ---------------------------------------------------------------------------
+// OTP
+// ---------------------------------------------------------------------------
+
 export type OTPProps = {
     /** Number of OTP digits. Defaults to 6. */
     length?: number
@@ -29,7 +331,7 @@ export type OTPProps = {
     onComplete?: (value: string) => void
     /** Whether the OTP input is disabled. */
     isDisabled?: boolean
-    /** Whether the OTP input is in an invalid/error state. */
+    /** Whether the OTP input is in an invalid/error state. Drives underline colour and (optionally) the error message. */
     isInvalid?: boolean
     /** Regex pattern to filter allowed characters. Defaults to digits only. */
     allowedPattern?: RegExp
@@ -43,10 +345,38 @@ export type OTPProps = {
     supportText?: React.ReactNode
     /** SupportText status when using the string shorthand. */
     supportTextStatus?: SupportTextProps['status']
+    /**
+     * Convenience: shown beneath the slots **only** while `isInvalid` is true.
+     * Renders with status="Error" automatically. When omitted, the regular
+     * `supportText` is shown instead (with status promoted to Error).
+     */
+    errorMessage?: string
+    /**
+     * When provided, replaces the support area with a managed countdown that
+     * decays into a "Resend" button. Hidden while `isInvalid` is true so the
+     * error message can take precedence.
+     */
+    resend?: OTPResendConfig
+    /**
+     * Enable native one-time-code auto-fill on the underlying TextInput.
+     * On iOS this surfaces the SMS code in the QuickType bar above the
+     * keyboard (system-managed; no library required). On Android this sets
+     * `autoComplete="one-time-code"`, which the OS can auto-fill from
+     * notifications when the host app is wired up to the SMS Retriever or
+     * SMS User Consent APIs. Defaults to true.
+     */
+    enableSmsAutofill?: boolean
 }
 
 const DIGITS_ONLY = /^\d*$/
 
+// How long the underline takes to fade in when a slot becomes
+// "highlighted" (filled or actively focused), and to fade out when a slot
+// reverts to idle (e.g. on backspace). The asymmetric durations make the
+// "fades back" cue intentional without being sluggish.
+const SLOT_FADE_IN_MS = 120
+const SLOT_FADE_OUT_MS = 220
+
 function OTP({
     length = 6,
     value: controlledValue,
@@ -62,9 +392,12 @@ function OTP({
     style,
     supportText,
     supportTextStatus,
+    errorMessage,
+    resend,
+    enableSmsAutofill = true,
 }: OTPProps) {
     const { modes: globalModes } = useTokens()
-    const modes = { ...globalModes, ...propModes }
+    const modes = useMemo(() => ({ ...globalModes, ...propModes }), [globalModes, propModes])
 
     const isControlled = controlledValue !== undefined
     const [internalValue, setInternalValue] = useState(defaultValue)
@@ -73,8 +406,8 @@ function OTP({
     const inputRef = useRef<RNTextInput>(null)
     const [isFocused, setIsFocused] = useState(false)
 
+    // --- Caret blink (unchanged) ---
     const caretAnim = useRef(new Animated.Value(1)).current
-
     useEffect(() => {
         if (!isFocused) return
         const blink = Animated.loop(
@@ -128,7 +461,6 @@ function OTP({
 
     const slotWidth = Number(getVariableByName('pinSlot/width', modes)) || 48
     const slotGap = Number(getVariableByName('pinSlot/gap', modes)) || 8
-    // digit/color has no state variants in Figma — resolved once from the Output collection
     const digitColor = (getVariableByName('pinSlot/digit/color', modes) as string) || '#000000'
     const digitFontSize = Number(getVariableByName('pinSlot/digit/fontSize', modes)) || 24
     const digitFontFamily = (getVariableByName('pinSlot/digit/fontFamily', modes) as string) || 'JioType Var'
@@ -137,17 +469,82 @@ function OTP({
     const underlineHeight = Number(getVariableByName('pinSlot/underline/height', modes)) || 2
     const underlineRadius = Number(getVariableByName('pinSlot/underline/radius', modes)) || 1
 
-    // --- State-driven slot modes ---
-    // Collection name in Figma is "Input/PINSlot  States" (double space before States).
-    // Only PinSlot/underline/color (capital P/S) lives in this collection with Idle/Active/Error modes.
-    // isInvalid takes priority over active focus; the component maps semantic state → token mode
-    // internally so consumers never need to know the collection key name.
-    const getSlotModes = (isActiveSlot: boolean): Record<string, any> => {
-        if (isInvalid) return { ...modes, 'Input/PINSlot  States': 'Error' }
-        if (isActiveSlot && isFocused) return { ...modes, 'Input/PINSlot  States': 'Active' }
-        return { ...modes, 'Input/PINSlot  States': 'Idle' }
+    // --- Resolve the three underline colors ONCE per render. We then
+    // animate between idle ↔ active per-slot using interpolation; the
+    // error color is applied directly (no animation) when isInvalid.
+    const idleUnderlineColor = useMemo(
+        () =>
+            (getVariableByName('PinSlot/underline/color', {
+                ...modes,
+                'Input/PINSlot  States': 'Idle',
+            }) as string) || '#303338',
+        [modes],
+    )
+    const activeUnderlineColor = useMemo(
+        () =>
+            (getVariableByName('PinSlot/underline/color', {
+                ...modes,
+                'Input/PINSlot  States': 'Active',
+            }) as string) || '#5d00b5',
+        [modes],
+    )
+    const errorUnderlineColor = useMemo(
+        () =>
+            (getVariableByName('PinSlot/underline/color', {
+                ...modes,
+                'Input/PINSlot  States': 'Error',
+            }) as string) || '#d92d20',
+        [modes],
+    )
+
+    // --- Per-slot underline highlight animations ---
+    //
+    // Each slot owns one Animated.Value in [0, 1]. 0 = Idle color, 1 =
+    // Active color. We re-target on every value/focus change:
+    //
+    //   highlighted = isFilled || (isActiveSlot && isFocused)
+    //
+    // Filled slots stay lit, so adding a digit instantly recruits its
+    // slot into the lit cohort. Deleting a digit transitions that slot
+    // (which is no longer the active slot — the cursor moved back) from
+    // 1 → 0, producing the "fades back" cue the design calls for.
+    //
+    // We use useNativeDriver:false because backgroundColor cannot run on
+    // the native driver (it's a JS-thread layout property). The overhead
+    // is fine here: at most `length` (≤ ~8) values transitioning briefly
+    // on each keystroke.
+    const slotAnimsRef = useRef<Animated.Value[]>([])
+    if (slotAnimsRef.current.length !== length) {
+        const next: Animated.Value[] = []
+        for (let i = 0; i < length; i++) {
+            const existing = slotAnimsRef.current[i]
+            // Initialize fresh slots to match their *current* highlight
+            // target. This avoids a flash on first mount when consumers
+            // pass a non-empty defaultValue (slots would otherwise fade
+            // in from 0 even though they're already filled).
+            const initial = i < currentValue.length ? 1 : 0
+            next.push(existing ?? new Animated.Value(initial))
+        }
+        slotAnimsRef.current = next
     }
 
+    useEffect(() => {
+        const anims = slotAnimsRef.current
+        const filledLen = currentValue.length
+        for (let i = 0; i < length; i++) {
+            const slotAnim = anims[i]
+            if (!slotAnim) continue
+            const isFilled = i < filledLen
+            const isActiveSlot = i === filledLen && filledLen < length && isFocused
+            const target = isFilled || isActiveSlot ? 1 : 0
+            Animated.timing(slotAnim, {
+                toValue: target,
+                duration: target === 1 ? SLOT_FADE_IN_MS : SLOT_FADE_OUT_MS,
+                useNativeDriver: false,
+            }).start()
+        }
+    }, [currentValue, isFocused, length])
+
     // --- Styles ---
     const containerStyle: ViewStyle = {
         flexDirection: 'column',
@@ -169,12 +566,6 @@ function OTP({
         const isActiveSlot = index === currentValue.length && currentValue.length < length
         const isFilled = char !== undefined
 
-        // Underline color is the only state-sensitive token (lives in "Input/PINSlot  States" collection).
-        // Note: token name is "PinSlot/underline/color" (capital P/S) — different from the static
-        // "pinSlot/underline/color" in the Output collection.
-        const slotModes = getSlotModes(isActiveSlot)
-        const underlineColor = (getVariableByName('PinSlot/underline/color', slotModes) as string) || '#303338'
-
         const slotStyle: ViewStyle = {
             width: slotWidth,
             flexDirection: 'column',
@@ -193,12 +584,23 @@ function OTP({
             minWidth: '100%' as any,
         }
 
-        const underlineStyle: ViewStyle = {
+        // Pull the per-slot animated value (always exists by this point —
+        // we resync the ref array above before render).
+        const slotAnim = slotAnimsRef.current[index] ?? new Animated.Value(0)
+        const interpolatedColor = slotAnim.interpolate({
+            inputRange: [0, 1],
+            outputRange: [idleUnderlineColor, activeUnderlineColor],
+        })
+
+        const underlineStyle = {
             width: slotWidth,
             height: underlineHeight,
             borderRadius: underlineRadius,
-            backgroundColor: underlineColor,
-        }
+            // Error state takes precedence and snaps directly to the
+            // error color — animating *to* an error feels less urgent
+            // than the snap, and the design uses an instant transition.
+            backgroundColor: isInvalid ? errorUnderlineColor : interpolatedColor,
+        } as Animated.WithAnimatedObject<ViewStyle>
 
         return (
             <View key={index} style={slotStyle}>
@@ -218,23 +620,60 @@ function OTP({
                         <Text style={[digitStyle, { color: 'transparent' }]}>{'\u00A0'}</Text>
                     )}
                 </View>
-                <View style={underlineStyle} />
+                <Animated.View style={underlineStyle} />
             </View>
         )
     }
 
-    const renderSupportText = () => {
+    // --- Support area rendering ---
+    //
+    // Priority:
+    //   1. isInvalid → errorMessage (with Error status). Falls back to
+    //      `supportText` if errorMessage isn't provided, promoting its
+    //      status to Error.
+    //   2. resend (and !isInvalid) → managed countdown / button.
+    //   3. supportText → user's static support text.
+    //   4. nothing.
+    //
+    // This split keeps validation a parent concern (the component never
+    // tries to "know" what valid means) while still giving consumers a
+    // turnkey error UI when they flip `isInvalid`.
+    //
+    // While `isInvalid` is true we also inject `Status: 'Error'` into the
+    // mode set forwarded to the support area. This lets the SupportText
+    // (and any nested icon) resolve error-themed Figma tokens — foreground
+    // color, icon color, etc. — without consumers having to thread the
+    // collection mode in by hand.
+    const supportModes = useMemo(
+        () => (isInvalid ? { ...modes, Status: 'Error' } : modes),
+        [modes, isInvalid],
+    )
+
+    const renderStaticSupportText = (overrideStatus?: SupportTextProps['status']) => {
         if (!supportText) return null
         if (typeof supportText === 'string') {
             return (
                 <SupportText
                     label={supportText}
-                    status={supportTextStatus ?? (isInvalid ? 'Error' : 'Neutral')}
-                    modes={modes}
+                    status={overrideStatus ?? supportTextStatus ?? 'Neutral'}
+                    modes={supportModes}
                 />
             )
         }
-        return <>{cloneChildrenWithModes(React.Children.toArray(supportText), modes)}</>
+        return <>{cloneChildrenWithModes(React.Children.toArray(supportText), supportModes)}</>
+    }
+
+    const renderSupportArea = () => {
+        if (isInvalid) {
+            if (errorMessage) {
+                return <SupportText label={errorMessage} status="Error" modes={supportModes} />
+            }
+            return renderStaticSupportText('Error')
+        }
+        if (resend) {
+            return <OTPResend {...resend} modes={supportModes} />
+        }
+        return renderStaticSupportText()
     }
 
     return (
@@ -255,6 +694,14 @@ function OTP({
                 onFocus={() => setIsFocused(true)}
                 onBlur={() => setIsFocused(false)}
                 caretHidden
+                // Cross-platform native one-time-code autofill. iOS reads
+                // `textContentType="oneTimeCode"` to surface SMS codes in
+                // the QuickType bar (no library needed). Android reads
+                // `autoComplete="one-time-code"` (the canonical RN value;
+                // also accepted as a hint by the SMS Retriever / SMS User
+                // Consent APIs that the host app wires up natively).
+                textContentType={enableSmsAutofill ? 'oneTimeCode' : 'none'}
+                autoComplete={enableSmsAutofill ? 'one-time-code' : 'off'}
                 style={{
                     position: 'absolute',
                     width: 1,
@@ -267,7 +714,7 @@ function OTP({
             <View style={slotWrapStyle}>
                 {Array.from({ length }, (_, i) => renderSlot(i))}
             </View>
-            {renderSupportText()}
+            {renderSupportArea()}
         </Pressable>
     )
 }