@lifesg/react-design-system 4.0.0-alpha.5 → 4.0.0-alpha.6

package/notification-banner/types.d.ts

@@ -1,27 +1,82 @@
 import type { TypographyLinkProps, TypographyProps } from "../typography";
+/**
+ * Props for the `NotificationBanner` component.
+ *
+ * When `onClick` is provided, the entire banner becomes interactive and a
+ * visually hidden accessible button is rendered for keyboard and screen-reader
+ * users.
+ */
 export interface NotificationBannerProps extends React.HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode | undefined;
+    /**
+     * Whether the dismiss button is rendered. The caller is responsible
+     * for dismissing the banner in the callback.
+     *
+     * @default true
+     */
     dismissible?: boolean | undefined;
+    /**
+     * Controls the visibility of the banner.
+     *
+     * @default true
+     */
     visible?: boolean | undefined;
+    /**
+     * Whether the banner sticks to the top of the viewport while the page
+     * scrolls.
+     *
+     * @default true
+     */
     sticky?: boolean | undefined;
+    /**
+     * An optional icon element rendered at the leading edge of the banner.
+     */
     icon?: JSX.Element | undefined;
+    /**
+     * Called when the user activates the dismiss button and `dismissible` is `true`.
+     */
     onDismiss?: (() => void) | undefined;
     "data-testid"?: string | undefined;
-    /** Specifies the maximum height of content, after which it is collapsed */
+    /**
+     * Maximum height in pixels for the content area. When the rendered content
+     * exceeds this value, the overflow is clipped.
+     */
     maxCollapsedHeight?: number | undefined;
-    /** Action button that will be displayed */
+    /**
+     * An action button rendered inside the content area. When
+     * `actionButton.onClick` is provided it stops propagation to the banner's
+     * own `onClick` handler.
+     */
     actionButton?: React.ButtonHTMLAttributes<HTMLButtonElement> | undefined;
 }
+/**
+ * Props for the `withNotificationBanner` HOC wrapper,
+ * extending `NotificationBannerProps` with a forwarded ref.
+ */
 export interface NotificationBannerWithForwardedRefProps extends NotificationBannerProps {
     forwardedRef?: React.Ref<HTMLDivElement> | undefined;
 }
+/**
+ * Discriminant for `NotificationContentAttributes` content items.
+ *
+ * - `"text"` items are sanitized and injected as HTML paragraphs.
+ * - `"link"` items are rendered as `NotificationBanner.Link` elements.
+ */
 export type ContentType = "text" | "link";
+/** Props for a `"link"` content item inside a notification banner. */
 export interface ContentLinkAttributes extends TypographyLinkProps {
 }
+/** Props for a `"text"` content item inside a notification banner. */
 export interface ContentTextAttributes extends TypographyProps {
 }
+/**
+ * A single content item for use with `withNotificationBanner`.
+ */
 export interface NotificationContentAttributes {
+    /** Determines how `content` is rendered inside the banner. */
     type: ContentType;
+    /** The text string or link label to display. */
     content: string;
+    /** Additional props forwarded to the rendered text or link element. */
     otherAttributes?: TypographyLinkProps | TypographyProps | undefined;
 }

package/otp-input/otp-input.d.ts

@@ -1,3 +1,10 @@
 import type React from "react";
 import type { OtpInputProps, OtpInputRef } from "./types";
+/**
+ * A field composed of individual inputs for a numeric one-time password
+ * with an in-built countdown mechanism.
+ *
+ * Use `OtpInput` when users must enter the one-time password (OTP)
+ * for multi-factored authentication methods.
+ */
 export declare const OtpInput: (props: OtpInputProps & React.RefAttributes<OtpInputRef>) => React.ReactElement | null;

package/otp-input/otp-input.js.map

@@ -1 +1 @@
-{"version":3,"file":"otp-input.js","sources":["../../src/otp-input/otp-input.tsx"],"sourcesContent":["import clsx from \"clsx\";\nimport type React from \"react\";\nimport {\n    forwardRef,\n    useEffect,\n    useImperativeHandle,\n    useRef,\n    useState,\n} from \"react\";\n\nimport { Button } from \"../button\";\nimport { FormErrorMessage } from \"../form/form-label\";\nimport { Input } from \"../input\";\nimport { VisuallyHidden } from \"../shared/accessibility\";\nimport { Typography } from \"../typography\";\nimport { StringHelper, useId } from \"../util\";\nimport * as styles from \"./otp-input.styles\";\nimport type { OtpInputProps, OtpInputRef } from \"./types\";\nimport { stripOtpFromAutofill, validateUserInput } from \"./utils\";\n\nconst Component = (\n    {\n        id,\n        value = [],\n        \"data-testid\": dataTestId,\n        className,\n        cooldownDuration,\n        actionButtonProps,\n        errorMessage,\n        numOfInput,\n        prefix,\n        onChange,\n        onCooldownStart,\n        onCooldownEnd,\n        otpOnly,\n        onCountdownChange,\n        ...otherProps\n    }: OtpInputProps,\n    ref: React.Ref<OtpInputRef>\n) => {\n    // =============================================================================\n    // CONST, STATE, REF\n    // =============================================================================\n    const {\n        disabled,\n        onClick,\n        styleType = \"secondary\",\n        ...otherCtaProps\n    } = actionButtonProps ?? {};\n\n    const inputRefs = useRef<(HTMLInputElement | null)[]>([]);\n    const onChangeRef = useRef(onChange);\n\n    const [otpValues, setOtpValues] = useState<string[]>(\n        new Array(numOfInput).fill(\"\")\n    );\n    const [countDown, setCountDown] = useState<number>(cooldownDuration);\n    const [lastCtaTimestamp, setLastCtaTimestamp] = useState<Date>(new Date());\n    const internalId = useId();\n\n    const hasError = !!errorMessage;\n    const errorId = `${internalId}-error`;\n    const timerId = `${internalId}-timer`;\n\n    // =============================================================================\n    // EFFECTS\n    // =============================================================================\n    useEffect(() => {\n        inputRefs?.current[0]?.focus();\n        document.addEventListener(\"paste\", handlePaste);\n        return () => document.removeEventListener(\"paste\", handlePaste);\n    }, []);\n\n    useEffect(() => {\n        if (cooldownDuration !== 0) {\n            if (onCooldownStart) onCooldownStart();\n            const cleanup = beginCountdown();\n\n            return () => cleanup();\n        }\n    }, [lastCtaTimestamp]);\n\n    useImperativeHandle(ref, () => ({\n        startCooldown: () => {\n            setLastCtaTimestamp(new Date());\n            setCountDown(cooldownDuration);\n        },\n    }));\n\n    useEffect(() => {\n        onChangeRef.current = onChange;\n    }, [onChange]);\n\n    useEffect(() => {\n        if (value.length === numOfInput) {\n            setOtpValues(value);\n        }\n    }, [value]);\n\n    // =============================================================================\n    // EVENT HANDLERS\n    // =============================================================================\n    const handleInputFullValue = (incomingValue: string) => {\n        if (incomingValue && validateUserInput(incomingValue, numOfInput)) {\n            const incomingValueArr = incomingValue.split(\"\");\n            setOtpValues(incomingValueArr);\n            if (onChangeRef.current) {\n                onChangeRef.current(incomingValueArr);\n            }\n\n            return true;\n        }\n\n        return false;\n    };\n\n    const handleChange =\n        (index: number) => (event: React.ChangeEvent<HTMLInputElement>) => {\n            const eventValue = event.target.value;\n\n            /* handle autofill */\n            const fieldIsEmpty = otpValues.every((num) => num === \"\");\n            const autofillOtp = stripOtpFromAutofill(\n                eventValue,\n                numOfInput,\n                prefix\n            );\n            if (fieldIsEmpty && handleInputFullValue(autofillOtp)) {\n                return;\n            }\n\n            /* handle normal input */\n            const value = eventValue.replace(/[^0-9]/g, \"\");\n            if (validateUserInput(value)) {\n                const newOtpValues = [...otpValues];\n\n                newOtpValues[index] = value.substring(value.length - 1);\n                inputRefs.current[index + 1]?.focus();\n\n                setOtpValues(newOtpValues);\n\n                if (onChange) {\n                    onChange(newOtpValues);\n                }\n            }\n        };\n\n    const handleKeyDown =\n        (index: number) => (event: React.KeyboardEvent<HTMLInputElement>) => {\n            const { key, code } = event;\n\n            if (key === \"Backspace\" || code === \"Backspace\") {\n                const newOtpValues = [...otpValues];\n                if (newOtpValues[index] !== \"\") {\n                    newOtpValues[index] = \"\";\n                } else if (index !== 0) {\n                    newOtpValues[index - 1] = \"\";\n                    inputRefs.current[index - 1]?.focus();\n                }\n\n                setOtpValues(newOtpValues);\n\n                if (onChange) {\n                    onChange(newOtpValues);\n                }\n            } else if (event.code === \"ArrowRight\") {\n                inputRefs.current[index + 1]?.focus();\n            } else if (event.code === \"ArrowLeft\") {\n                inputRefs.current[index - 1]?.focus();\n            }\n        };\n\n    const handlePaste = (event: ClipboardEvent): void => {\n        if (!event.clipboardData) return;\n\n        const pastedValue = event.clipboardData.getData(\"text\");\n        const autofillOtp = stripOtpFromAutofill(\n            pastedValue,\n            numOfInput,\n            prefix\n        );\n        if (!handleInputFullValue(autofillOtp)) {\n            event.preventDefault();\n        }\n    };\n\n    const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {\n        setOtpValues(new Array(numOfInput).fill(\"\"));\n\n        if (!isWithinCooldown()) {\n            setLastCtaTimestamp(new Date());\n            setCountDown(cooldownDuration);\n        }\n\n        if (onClick) {\n            onClick(event);\n        }\n    };\n\n    // =========================================================================\n    // HELPER FUNCTIONS\n    // =========================================================================\n    const isWithinCooldown = (): boolean => {\n        const currentTime = Date.now();\n        const coolDownInMilliseconds = cooldownDuration * 1000;\n\n        return (\n            currentTime < lastCtaTimestamp.valueOf() + coolDownInMilliseconds\n        );\n    };\n\n    const beginCountdown = () => {\n        const interval = setInterval(() => {\n            const currentTime = Date.now();\n            const coolDownInMilliseconds = cooldownDuration * 1000;\n\n            const timer = Math.ceil(\n                (lastCtaTimestamp.valueOf() +\n                    coolDownInMilliseconds -\n                    currentTime) /\n                    1000\n            );\n            setCountDown(timer);\n            if (timer <= 0) {\n                if (onCooldownEnd) onCooldownEnd();\n                clearInterval(interval);\n            } else if (onCountdownChange) {\n                onCountdownChange(timer);\n            }\n        }, 1000);\n\n        return () => {\n            clearInterval(interval);\n        };\n    };\n\n    const generateId = (index: number, name: string, prefix?: string) => {\n        return prefix\n            ? `${prefix}-${name}-${index + 1}`\n            : `${name}-${index + 1}`;\n    };\n\n    const displaySeconds = (time: number) => {\n        return `${time} second${time === 1 ? \"\" : \"s\"}`;\n    };\n\n    const getCTALabelProps = (): Partial<\n        React.HTMLAttributes<HTMLButtonElement>\n    > => {\n        return otherCtaProps.children\n            ? { children: otherCtaProps.children }\n            : {\n                  children:\n                      countDown > 0\n                          ? `Resend OTP in ${displaySeconds(countDown)}`\n                          : \"Resend OTP\",\n                  // use a fixed label to avoid repeated screen reader updates when the button is focused\n                  \"aria-label\":\n                      countDown > 0\n                          ? `Resend OTP in ${displaySeconds(cooldownDuration)}`\n                          : \"Resend OTP\",\n                  // use a secondary element to reflect the latest countdown\n                  \"aria-describedby\": timerId,\n              };\n    };\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    return (\n        <div\n            id={id}\n            data-testid={dataTestId}\n            className={clsx(styles.wrapper, className)}\n        >\n            <div\n                className={styles.inputContainer}\n                role=\"group\"\n                aria-label={`${numOfInput}-digit OTP input field`}\n            >\n                {prefix && (\n                    <Typography.BodyBL\n                        as=\"span\"\n                        className={styles.prefix}\n                        data-testid=\"otp-prefix\"\n                        weight=\"semibold\"\n                    >\n                        <VisuallyHidden>O T P prefix</VisuallyHidden>\n                        {`${prefix.value} ${prefix.separator}`}\n                    </Typography.BodyBL>\n                )}\n                {otpValues.map((data, index) => {\n                    return (\n                        <Input\n                            className={styles.inputField}\n                            id={generateId(index, \"otp-input\", id)}\n                            data-testid={generateId(\n                                index,\n                                \"otp-input\",\n                                dataTestId\n                            )}\n                            aria-label={`${StringHelper.formatOrdinal(\n                                index + 1\n                            )} digit`}\n                            aria-invalid={hasError}\n                            aria-describedby={hasError ? errorId : undefined}\n                            key={index}\n                            ref={(el) => (inputRefs.current[index] = el)}\n                            type=\"text\"\n                            inputMode=\"numeric\"\n                            value={data}\n                            error={hasError}\n                            onChange={handleChange(index)}\n                            onKeyDown={handleKeyDown(index)}\n                            autoComplete=\"off\"\n                            {...otherProps}\n                        />\n                    );\n                })}\n            </div>\n            {errorMessage && (\n                <FormErrorMessage id={errorId} data-testid=\"otp-error-message\">\n                    {errorMessage}\n                </FormErrorMessage>\n            )}\n            {/* visually hidden elements need to be rendered before the button so that Voiceover/Chrome doesn't skip the button */}\n            <VisuallyHidden role=\"timer\" id={timerId}>\n                {displaySeconds(countDown)} remaining\n            </VisuallyHidden>\n            <VisuallyHidden aria-live=\"polite\">\n                {countDown > 0 ? \"\" : \"Ready to resend OTP\"}\n            </VisuallyHidden>\n            {!otpOnly && (\n                <Button\n                    className={styles.ctaButton}\n                    styleType={styleType}\n                    type=\"button\"\n                    sizeType=\"small\"\n                    {...otherCtaProps}\n                    onClick={handleClick}\n                    disabled={disabled || isWithinCooldown()}\n                    {...getCTALabelProps()}\n                />\n            )}\n        </div>\n    );\n};\n\nexport const OtpInput = forwardRef(Component);\n"],"names":["OtpInput","forwardRef","_a","ref","id","value","dataTestId","className","cooldownDuration","actionButtonProps","errorMessage","numOfInput","prefix","onChange","onCooldownStart","onCooldownEnd","otpOnly","onCountdownChange","otherProps","__rest","_b","disabled","onClick","styleType","otherCtaProps","inputRefs","useRef","onChangeRef","otpValues","setOtpValues","useState","Array","fill","countDown","setCountDown","lastCtaTimestamp","setLastCtaTimestamp","Date","internalId","useId","hasError","errorId","timerId","useEffect","current","focus","document","addEventListener","handlePaste","removeEventListener","cleanup","beginCountdown","useImperativeHandle","startCooldown","length","handleInputFullValue","incomingValue","validateUserInput","incomingValueArr","split","handleChange","index","event","eventValue","target","fieldIsEmpty","every","num","autofillOtp","stripOtpFromAutofill","replace","newOtpValues","substring","handleKeyDown","key","code","_c","clipboardData","pastedValue","getData","preventDefault","isWithinCooldown","currentTime","now","coolDownInMilliseconds","valueOf","interval","setInterval","timer","Math","ceil","clearInterval","generateId","name","displaySeconds","time","_jsxs","clsx","styles.wrapper","children","styles.inputContainer","role","Typography","BodyBL","as","styles.prefix","weight","_jsx","VisuallyHidden","separator","map","data","Input","Object","assign","styles.inputField","StringHelper","formatOrdinal","undefined","el","type","inputMode","error","onKeyDown","autoComplete","FormErrorMessage","Button","styles.ctaButton","sizeType"],"mappings":"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"}
+{"version":3,"file":"otp-input.js","sources":["../../src/otp-input/otp-input.tsx"],"sourcesContent":["import clsx from \"clsx\";\nimport type React from \"react\";\nimport {\n    forwardRef,\n    useEffect,\n    useImperativeHandle,\n    useRef,\n    useState,\n} from \"react\";\n\nimport { Button } from \"../button\";\nimport { FormErrorMessage } from \"../form/form-label\";\nimport { Input } from \"../input\";\nimport { VisuallyHidden } from \"../shared/accessibility\";\nimport { Typography } from \"../typography\";\nimport { StringHelper, useId } from \"../util\";\nimport * as styles from \"./otp-input.styles\";\nimport type { OtpInputProps, OtpInputRef } from \"./types\";\nimport { stripOtpFromAutofill, validateUserInput } from \"./utils\";\n\nconst Component = (\n    {\n        id,\n        value = [],\n        \"data-testid\": dataTestId,\n        className,\n        cooldownDuration,\n        actionButtonProps,\n        errorMessage,\n        numOfInput,\n        prefix,\n        onChange,\n        onCooldownStart,\n        onCooldownEnd,\n        otpOnly,\n        onCountdownChange,\n        ...otherProps\n    }: OtpInputProps,\n    ref: React.Ref<OtpInputRef>\n) => {\n    // =============================================================================\n    // CONST, STATE, REF\n    // =============================================================================\n    const {\n        disabled,\n        onClick,\n        styleType = \"secondary\",\n        ...otherCtaProps\n    } = actionButtonProps ?? {};\n\n    const inputRefs = useRef<(HTMLInputElement | null)[]>([]);\n    const onChangeRef = useRef(onChange);\n\n    const [otpValues, setOtpValues] = useState<string[]>(\n        new Array(numOfInput).fill(\"\")\n    );\n    const [countDown, setCountDown] = useState<number>(cooldownDuration);\n    const [lastCtaTimestamp, setLastCtaTimestamp] = useState<Date>(new Date());\n    const internalId = useId();\n\n    const hasError = !!errorMessage;\n    const errorId = `${internalId}-error`;\n    const timerId = `${internalId}-timer`;\n\n    // =============================================================================\n    // EFFECTS\n    // =============================================================================\n    useEffect(() => {\n        inputRefs?.current[0]?.focus();\n        document.addEventListener(\"paste\", handlePaste);\n        return () => document.removeEventListener(\"paste\", handlePaste);\n    }, []);\n\n    useEffect(() => {\n        if (cooldownDuration !== 0) {\n            if (onCooldownStart) onCooldownStart();\n            const cleanup = beginCountdown();\n\n            return () => cleanup();\n        }\n    }, [lastCtaTimestamp]);\n\n    useImperativeHandle(ref, () => ({\n        startCooldown: () => {\n            setLastCtaTimestamp(new Date());\n            setCountDown(cooldownDuration);\n        },\n    }));\n\n    useEffect(() => {\n        onChangeRef.current = onChange;\n    }, [onChange]);\n\n    useEffect(() => {\n        if (value.length === numOfInput) {\n            setOtpValues(value);\n        }\n    }, [value]);\n\n    // =============================================================================\n    // EVENT HANDLERS\n    // =============================================================================\n    const handleInputFullValue = (incomingValue: string) => {\n        if (incomingValue && validateUserInput(incomingValue, numOfInput)) {\n            const incomingValueArr = incomingValue.split(\"\");\n            setOtpValues(incomingValueArr);\n            if (onChangeRef.current) {\n                onChangeRef.current(incomingValueArr);\n            }\n\n            return true;\n        }\n\n        return false;\n    };\n\n    const handleChange =\n        (index: number) => (event: React.ChangeEvent<HTMLInputElement>) => {\n            const eventValue = event.target.value;\n\n            /* handle autofill */\n            const fieldIsEmpty = otpValues.every((num) => num === \"\");\n            const autofillOtp = stripOtpFromAutofill(\n                eventValue,\n                numOfInput,\n                prefix\n            );\n            if (fieldIsEmpty && handleInputFullValue(autofillOtp)) {\n                return;\n            }\n\n            /* handle normal input */\n            const value = eventValue.replace(/[^0-9]/g, \"\");\n            if (validateUserInput(value)) {\n                const newOtpValues = [...otpValues];\n\n                newOtpValues[index] = value.substring(value.length - 1);\n                inputRefs.current[index + 1]?.focus();\n\n                setOtpValues(newOtpValues);\n\n                if (onChange) {\n                    onChange(newOtpValues);\n                }\n            }\n        };\n\n    const handleKeyDown =\n        (index: number) => (event: React.KeyboardEvent<HTMLInputElement>) => {\n            const { key, code } = event;\n\n            if (key === \"Backspace\" || code === \"Backspace\") {\n                const newOtpValues = [...otpValues];\n                if (newOtpValues[index] !== \"\") {\n                    newOtpValues[index] = \"\";\n                } else if (index !== 0) {\n                    newOtpValues[index - 1] = \"\";\n                    inputRefs.current[index - 1]?.focus();\n                }\n\n                setOtpValues(newOtpValues);\n\n                if (onChange) {\n                    onChange(newOtpValues);\n                }\n            } else if (event.code === \"ArrowRight\") {\n                inputRefs.current[index + 1]?.focus();\n            } else if (event.code === \"ArrowLeft\") {\n                inputRefs.current[index - 1]?.focus();\n            }\n        };\n\n    const handlePaste = (event: ClipboardEvent): void => {\n        if (!event.clipboardData) return;\n\n        const pastedValue = event.clipboardData.getData(\"text\");\n        const autofillOtp = stripOtpFromAutofill(\n            pastedValue,\n            numOfInput,\n            prefix\n        );\n        if (!handleInputFullValue(autofillOtp)) {\n            event.preventDefault();\n        }\n    };\n\n    const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {\n        setOtpValues(new Array(numOfInput).fill(\"\"));\n\n        if (!isWithinCooldown()) {\n            setLastCtaTimestamp(new Date());\n            setCountDown(cooldownDuration);\n        }\n\n        if (onClick) {\n            onClick(event);\n        }\n    };\n\n    // =========================================================================\n    // HELPER FUNCTIONS\n    // =========================================================================\n    const isWithinCooldown = (): boolean => {\n        const currentTime = Date.now();\n        const coolDownInMilliseconds = cooldownDuration * 1000;\n\n        return (\n            currentTime < lastCtaTimestamp.valueOf() + coolDownInMilliseconds\n        );\n    };\n\n    const beginCountdown = () => {\n        const interval = setInterval(() => {\n            const currentTime = Date.now();\n            const coolDownInMilliseconds = cooldownDuration * 1000;\n\n            const timer = Math.ceil(\n                (lastCtaTimestamp.valueOf() +\n                    coolDownInMilliseconds -\n                    currentTime) /\n                    1000\n            );\n            setCountDown(timer);\n            if (timer <= 0) {\n                if (onCooldownEnd) onCooldownEnd();\n                clearInterval(interval);\n            } else if (onCountdownChange) {\n                onCountdownChange(timer);\n            }\n        }, 1000);\n\n        return () => {\n            clearInterval(interval);\n        };\n    };\n\n    const generateId = (index: number, name: string, prefix?: string) => {\n        return prefix\n            ? `${prefix}-${name}-${index + 1}`\n            : `${name}-${index + 1}`;\n    };\n\n    const displaySeconds = (time: number) => {\n        return `${time} second${time === 1 ? \"\" : \"s\"}`;\n    };\n\n    const getCTALabelProps = (): Partial<\n        React.HTMLAttributes<HTMLButtonElement>\n    > => {\n        return otherCtaProps.children\n            ? { children: otherCtaProps.children }\n            : {\n                  children:\n                      countDown > 0\n                          ? `Resend OTP in ${displaySeconds(countDown)}`\n                          : \"Resend OTP\",\n                  // use a fixed label to avoid repeated screen reader updates when the button is focused\n                  \"aria-label\":\n                      countDown > 0\n                          ? `Resend OTP in ${displaySeconds(cooldownDuration)}`\n                          : \"Resend OTP\",\n                  // use a secondary element to reflect the latest countdown\n                  \"aria-describedby\": timerId,\n              };\n    };\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    return (\n        <div\n            id={id}\n            data-testid={dataTestId}\n            className={clsx(styles.wrapper, className)}\n        >\n            <div\n                className={styles.inputContainer}\n                role=\"group\"\n                aria-label={`${numOfInput}-digit OTP input field`}\n            >\n                {prefix && (\n                    <Typography.BodyBL\n                        as=\"span\"\n                        className={styles.prefix}\n                        data-testid=\"otp-prefix\"\n                        weight=\"semibold\"\n                    >\n                        <VisuallyHidden>O T P prefix</VisuallyHidden>\n                        {`${prefix.value} ${prefix.separator}`}\n                    </Typography.BodyBL>\n                )}\n                {otpValues.map((data, index) => {\n                    return (\n                        <Input\n                            className={styles.inputField}\n                            id={generateId(index, \"otp-input\", id)}\n                            data-testid={generateId(\n                                index,\n                                \"otp-input\",\n                                dataTestId\n                            )}\n                            aria-label={`${StringHelper.formatOrdinal(\n                                index + 1\n                            )} digit`}\n                            aria-invalid={hasError}\n                            aria-describedby={hasError ? errorId : undefined}\n                            key={index}\n                            ref={(el) => (inputRefs.current[index] = el)}\n                            type=\"text\"\n                            inputMode=\"numeric\"\n                            value={data}\n                            error={hasError}\n                            onChange={handleChange(index)}\n                            onKeyDown={handleKeyDown(index)}\n                            autoComplete=\"off\"\n                            {...otherProps}\n                        />\n                    );\n                })}\n            </div>\n            {errorMessage && (\n                <FormErrorMessage id={errorId} data-testid=\"otp-error-message\">\n                    {errorMessage}\n                </FormErrorMessage>\n            )}\n            {/* visually hidden elements need to be rendered before the button so that Voiceover/Chrome doesn't skip the button */}\n            <VisuallyHidden role=\"timer\" id={timerId}>\n                {displaySeconds(countDown)} remaining\n            </VisuallyHidden>\n            <VisuallyHidden aria-live=\"polite\">\n                {countDown > 0 ? \"\" : \"Ready to resend OTP\"}\n            </VisuallyHidden>\n            {!otpOnly && (\n                <Button\n                    className={styles.ctaButton}\n                    styleType={styleType}\n                    type=\"button\"\n                    sizeType=\"small\"\n                    {...otherCtaProps}\n                    onClick={handleClick}\n                    disabled={disabled || isWithinCooldown()}\n                    {...getCTALabelProps()}\n                />\n            )}\n        </div>\n    );\n};\n\n/**\n * A field composed of individual inputs for a numeric one-time password\n * with an in-built countdown mechanism.\n *\n * Use `OtpInput` when users must enter the one-time password (OTP)\n * for multi-factored authentication methods.\n */\nexport const OtpInput = forwardRef(Component);\n"],"names":["OtpInput","forwardRef","_a","ref","id","value","dataTestId","className","cooldownDuration","actionButtonProps","errorMessage","numOfInput","prefix","onChange","onCooldownStart","onCooldownEnd","otpOnly","onCountdownChange","otherProps","__rest","_b","disabled","onClick","styleType","otherCtaProps","inputRefs","useRef","onChangeRef","otpValues","setOtpValues","useState","Array","fill","countDown","setCountDown","lastCtaTimestamp","setLastCtaTimestamp","Date","internalId","useId","hasError","errorId","timerId","useEffect","current","focus","document","addEventListener","handlePaste","removeEventListener","cleanup","beginCountdown","useImperativeHandle","startCooldown","length","handleInputFullValue","incomingValue","validateUserInput","incomingValueArr","split","handleChange","index","event","eventValue","target","fieldIsEmpty","every","num","autofillOtp","stripOtpFromAutofill","replace","newOtpValues","substring","handleKeyDown","key","code","_c","clipboardData","pastedValue","getData","preventDefault","isWithinCooldown","currentTime","now","coolDownInMilliseconds","valueOf","interval","setInterval","timer","Math","ceil","clearInterval","generateId","name","displaySeconds","time","_jsxs","clsx","styles.wrapper","children","styles.inputContainer","role","Typography","BodyBL","as","styles.prefix","weight","_jsx","VisuallyHidden","separator","map","data","Input","Object","assign","styles.inputField","StringHelper","formatOrdinal","undefined","el","type","inputMode","error","onKeyDown","autoComplete","FormErrorMessage","Button","styles.ctaButton","sizeType"],"mappings":"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"}

package/otp-input/types.d.ts

@@ -1,34 +1,77 @@
 import type { ButtonProps } from "../button";
+/**
+ * Props for the `OtpInput` component.
+ */
 export interface OtpInputProps extends React.AriaAttributes {
     id?: string | undefined;
     "data-testid"?: string | undefined;
     className?: string | undefined;
-    /** The array of input values */
+    /**
+     * Controlled array of digit strings, one entry per input cell.
+     * Only applied when the array length equals `numOfInput`.
+     */
     value?: string[] | undefined;
+    /**
+     * Error text displayed below the input cells.
+     */
     errorMessage?: string | React.ReactNode | undefined;
-    /** The duration (in seconds) to disable the submit button after a click is made */
+    /**
+     * Duration in seconds to disable the action button after it is clicked.
+     * Pass `0` to skip the cooldown entirely.
+     */
     cooldownDuration: number;
-    /** The props for the submit button */
+    /**
+     * Props forwarded to the action button. When `children` is not provided,
+     * the button label defaults to `"Resend OTP"`, or `"Resend OTP in X seconds"`
+     * while a cooldown is active.
+     *
+     * @default styleType: "secondary"
+     */
     actionButtonProps?: ButtonProps | undefined;
-    /** Flag to indicate if only OTP inputs should be rendered without the action button */
+    /**
+     * When `true`, renders only the OTP input cells without the action button.
+     */
     otpOnly?: boolean | undefined;
-    /** The number of characters for the Otp */
+    /**
+     * Number of single-digit input cells to render.
+     */
     numOfInput: number;
+    /**
+     * Optional prefix label rendered before the input cells.
+     */
     prefix?: {
-        /** Optional OTP prefix, usually consisting of a few alphabetic characters */
+        /** Prefix text, usually a few alphabetic characters. */
         value: string;
-        /** separator between prefix and otp digits. Only "-" supported for now */
+        /**
+         * Separator between the prefix and the OTP input.
+         * Only `"-"` is supported.
+         */
         separator: "-";
     } | undefined;
-    /** Called when one of the input is changed. Returns an array of all the input values */
+    /**
+     * Called when any input cell changes.
+     *
+     * @param value Array of all input cell values, one string per cell.
+     */
     onChange?: ((value: string[]) => void) | undefined;
-    /** Called when the countdown changes. Returns the remaining time in seconds */
+    /**
+     * Called each second while a cooldown countdown is active.
+     *
+     * @param remaining Seconds remaining in the current cooldown.
+     */
     onCountdownChange?: ((remaining: number) => void) | undefined;
-    /** Called when the cooldown begins */
+    /** Called when a cooldown period begins. */
     onCooldownStart?: (() => void) | undefined;
-    /** Called when the cooldown ends */
+    /** Called when a cooldown period ends. */
     onCooldownEnd?: (() => void) | undefined;
 }
+/**
+ * Imperative handle returned by `OtpInput` via `ref`.
+ */
 export type OtpInputRef = {
+    /**
+     * Starts a new cooldown countdown without clearing the input cells.
+     * Fires `onCooldownStart` and begins the countdown timer.
+     */
     startCooldown: () => void;
 };

package/otp-verification/internal-types.d.ts

@@ -25,16 +25,33 @@ export interface ContactInputSectionProps {
 export interface VerificationSectionProps {
     id?: string | undefined;
     "data-testid"?: string | undefined;
+    countdown: ReturnType<typeof useCountdown>;
+    isVerifyLoading: boolean;
+    otpCode?: string | undefined;
+    otpPrefix?: string | undefined;
+    otpSeparator?: string | undefined;
     type: "email" | "phone-number";
+    /**
+     * Whether to display the thumbnail image in the OTP verification section,
+     * visible in the `"sent"` state.
+     */
     showVerifyOtpThumbnail?: boolean | undefined;
+    /**
+     * Custom icon in the OTP verification section, visible in the `"sent"` state.
+     */
+    verifyOtpIcon?: React.ReactNode | undefined;
+    /**
+     * Custom heading in the OTP verification section, visible in the `"sent"` state.
+     */
     verifyOtpTitle?: string | undefined;
+    /**
+     * Custom body text in the OTP verification section, visible in the `"sent"` state.
+     */
     verifyOtpMessage?: string | undefined;
+    /**
+     * Error message displayed below the OTP input after a failed verification attempt.
+     */
     verifyOtpError?: string | undefined;
-    otpCode?: string | undefined;
     setOtpCode?: (value: string) => void;
-    isVerifyLoading: boolean;
-    countdown: ReturnType<typeof useCountdown>;
     onVerifyOtp: () => void;
-    otpPrefix?: string | undefined;
-    otpSeparator?: string | undefined;
 }

package/otp-verification/otp-verification.d.ts

@@ -1,2 +1,8 @@
 import type { OtpVerificationProps } from "./types";
+/**
+ * A multi-step form component that guides users through OTP-based verification.
+ *
+ * Use `OtpVerification` when you need to verify a user's identity through
+ * email address or phone number.
+ */
 export declare const OtpVerification: (props: OtpVerificationProps) => import("react/jsx-runtime").JSX.Element;

package/otp-verification/otp-verification.js.map

@@ -1 +1 @@
-{"version":3,"file":"otp-verification.js","sources":["../../src/otp-verification/otp-verification.tsx"],"sourcesContent":["import { announce, clearAnnouncer } from \"@react-aria/live-announcer\";\nimport clsx from \"clsx\";\nimport { useState } from \"react\";\n\nimport { useCountdown } from \"../util\";\nimport { ContactInputSection } from \"./contact-input-section\";\nimport * as styles from \"./otp-verification.styles\";\nimport type { OtpVerificationProps } from \"./types\";\nimport { VerificationSection } from \"./verification-section\";\n\nexport const OtpVerification = (props: OtpVerificationProps) => {\n    // =============================================================================\n    // CONST, STATE, REF\n    // =============================================================================\n    const {\n        id,\n        \"data-testid\": dataTestId,\n        className,\n        inputId,\n        onSendOtp,\n        onVerifyOtp,\n        verifyOtpCountdownTimer = 60,\n        sendOtpError,\n        verifyOtpError,\n        otpValue,\n        onOtpChange,\n        otpState,\n        onOtpStateChange,\n        otpReminderInterval = 120,\n    } = props;\n\n    const [isLoading, setIsLoading] = useState(false);\n    const [isVerifyLoading, setIsVerifyLoading] = useState(false);\n\n    const countdown = useCountdown({\n        duration: verifyOtpCountdownTimer,\n        reminderInterval: otpReminderInterval,\n        getStartMessage: (duration) =>\n            `You can resend the OTP in ${duration} seconds`,\n        getIntervalMessage: (remaining) => `${remaining} seconds remaining`,\n        getCompletionMessage: () => \"You can now resend the OTP\",\n    });\n\n    // =============================================================================\n    // EVENT HANDLERS\n    // =============================================================================\n    // Send OTP\n    const handleSendOtp = async () => {\n        if (!onSendOtp || isLoading) return;\n\n        try {\n            setIsLoading(true);\n            await onSendOtp();\n            onOtpStateChange(\"sent\");\n            countdown.reset();\n            countdown.start();\n        } catch {\n            // do nothing\n        } finally {\n            setIsLoading(false);\n        }\n    };\n\n    // Verify OTP\n    const handleVerifyOtp = async () => {\n        if (!onVerifyOtp || isVerifyLoading || !otpValue?.value) return;\n\n        try {\n            setIsVerifyLoading(true);\n            await onVerifyOtp(otpValue.value);\n\n            onOtpStateChange(\"verified\");\n\n            clearAnnouncer(\"polite\");\n            announce(\n                \"Success. Your email or mobile number has been verified.\",\n                \"polite\"\n            );\n\n            // Reset the countdown and clear the OTP code in case user enter new OTP later\n            countdown.reset();\n            onOtpChange?.(\"\");\n        } catch {\n            // do nothing\n        } finally {\n            setIsVerifyLoading(false);\n        }\n    };\n\n    // =============================================================================\n    // HELPER FUNCTIONS\n    // =============================================================================\n    const resetToDefault = () => {\n        if (otpState === \"verified\") {\n            onOtpStateChange(\"default\");\n        }\n    };\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    return (\n        <div\n            id={id}\n            data-testid={dataTestId}\n            className={clsx(styles.otpInputWrapper, className)}\n        >\n            <ContactInputSection\n                {...props}\n                inputId={inputId}\n                data-testid={dataTestId ? `${dataTestId}-contact` : undefined}\n                isLoading={isLoading}\n                isVerified={otpState === \"verified\"}\n                countdown={countdown}\n                onSendOtp={handleSendOtp}\n                onStateReset={resetToDefault}\n                sendOtpError={sendOtpError}\n                fixedCountry={\n                    props.type === \"phone-number\" ? props.fixedCountry : true\n                }\n            />\n\n            {otpState === \"sent\" && (\n                <VerificationSection\n                    {...props}\n                    data-testid={\n                        dataTestId ? `${dataTestId}-verification` : undefined\n                    }\n                    otpCode={otpValue?.value}\n                    otpPrefix={otpValue?.prefix}\n                    otpSeparator={otpValue?.separator}\n                    setOtpCode={onOtpChange}\n                    isVerifyLoading={isVerifyLoading}\n                    countdown={countdown}\n                    onVerifyOtp={handleVerifyOtp}\n                    verifyOtpError={verifyOtpError}\n                />\n            )}\n        </div>\n    );\n};\n"],"names":["OtpVerification","props","id","dataTestId","className","inputId","onSendOtp","onVerifyOtp","verifyOtpCountdownTimer","sendOtpError","verifyOtpError","otpValue","onOtpChange","otpState","onOtpStateChange","otpReminderInterval","isLoading","setIsLoading","useState","isVerifyLoading","setIsVerifyLoading","countdown","useCountdown","duration","reminderInterval","getStartMessage","getIntervalMessage","remaining","getCompletionMessage","_jsxs","clsx","styles.otpInputWrapper","children","_jsx","ContactInputSection","Object","assign","undefined","isVerified","__awaiter","reset","start","_a","onStateReset","fixedCountry","type","VerificationSection","otpCode","value","otpPrefix","prefix","otpSeparator","separator","setOtpCode","clearAnnouncer","announce"],"mappings":"6mBAUO,MAAMA,EAAmBC,IAI5B,MAAMC,GACFA,EACA,cAAeC,EAAUC,UACzBA,EAASC,QACTA,EAAOC,UACPA,EAASC,YACTA,EAAWC,wBACXA,EAA0B,GAAEC,aAC5BA,EAAYC,eACZA,EAAcC,SACdA,EAAQC,YACRA,EAAWC,SACXA,EAAQC,iBACRA,EAAgBC,oBAChBA,EAAsB,KACtBd,GAEGe,EAAWC,GAAgBC,GAAS,IACpCC,EAAiBC,GAAsBF,GAAS,GAEjDG,EAAYC,EAAa,CAC3BC,SAAUf,EACVgB,iBAAkBT,EAClBU,gBAAkBF,GACd,6BAA6BA,YACjCG,mBAAqBC,GAAc,GAAGA,sBACtCC,qBAAsB,IAAM,+BA6DhC,OACIC,EAAA,MAAA,CACI3B,GAAIA,gBACSC,EACbC,UAAW0B,EAAKC,EAAwB3B,GAAU4B,SAAA,CAElDC,EAACC,EAAmBC,OAAAC,OAAA,CAAA,EACZnC,EAAK,CACTI,QAASA,EAAO,cACHF,EAAa,GAAGA,iBAAuBkC,EACpDrB,UAAWA,EACXsB,WAAyB,aAAbzB,EACZQ,UAAWA,EACXf,UAnEU,IAAWiC,OAAA,OAAA,OAAA,GAAA,YAC7B,GAAKjC,IAAaU,EAElB,IACIC,GAAa,SACPX,IACNQ,EAAiB,QACjBO,EAAUmB,QACVnB,EAAUoB,OACd,CAAE,MAAAC,GAEF,SACIzB,GAAa,EACjB,CACJ,IAsDY0B,aAvBW,KACF,aAAb9B,GACAC,EAAiB,UACrB,EAqBQL,aAAcA,EACdmC,aACmB,iBAAf3C,EAAM4C,MAA0B5C,EAAM2C,gBAIhC,SAAb/B,GACGoB,EAACa,mBACO7C,EAAK,CAAA,cAELE,EAAa,GAAGA,sBAA4BkC,EAEhDU,QAASpC,eAAAA,EAAUqC,MACnBC,UAAWtC,aAAQ,EAARA,EAAUuC,OACrBC,aAAcxC,aAAQ,EAARA,EAAUyC,UACxBC,WAAYzC,EACZO,gBAAiBA,EACjBE,UAAWA,EACXd,YAtEQ,IAAWgC,OAAA,OAAA,OAAA,GAAA,YAC/B,GAAKhC,IAAeY,IAAoBR,aAAQ,EAARA,EAAUqC,OAElD,IACI5B,GAAmB,SACbb,EAAYI,EAASqC,OAE3BlC,EAAiB,YAEjBwC,EAAe,UACfC,EACI,0DACA,UAIJlC,EAAUmB,QACV5B,SAAAA,EAAc,GAClB,CAAE,MAAA8B,GAEF,SACItB,GAAmB,EACvB,CACJ,IAgDgBV,eAAgBA,OAGtB"}
+{"version":3,"file":"otp-verification.js","sources":["../../src/otp-verification/otp-verification.tsx"],"sourcesContent":["import { announce, clearAnnouncer } from \"@react-aria/live-announcer\";\nimport clsx from \"clsx\";\nimport { useState } from \"react\";\n\nimport { useCountdown } from \"../util\";\nimport { ContactInputSection } from \"./contact-input-section\";\nimport * as styles from \"./otp-verification.styles\";\nimport type { OtpVerificationProps } from \"./types\";\nimport { VerificationSection } from \"./verification-section\";\n\n/**\n * A multi-step form component that guides users through OTP-based verification.\n *\n * Use `OtpVerification` when you need to verify a user's identity through\n * email address or phone number.\n */\nexport const OtpVerification = (props: OtpVerificationProps) => {\n    // =============================================================================\n    // CONST, STATE, REF\n    // =============================================================================\n    const {\n        id,\n        \"data-testid\": dataTestId,\n        className,\n        inputId,\n        onSendOtp,\n        onVerifyOtp,\n        verifyOtpCountdownTimer = 60,\n        sendOtpError,\n        verifyOtpError,\n        otpValue,\n        onOtpChange,\n        otpState,\n        onOtpStateChange,\n        otpReminderInterval = 120,\n    } = props;\n\n    const [isLoading, setIsLoading] = useState(false);\n    const [isVerifyLoading, setIsVerifyLoading] = useState(false);\n\n    const countdown = useCountdown({\n        duration: verifyOtpCountdownTimer,\n        reminderInterval: otpReminderInterval,\n        getStartMessage: (duration) =>\n            `You can resend the OTP in ${duration} seconds`,\n        getIntervalMessage: (remaining) => `${remaining} seconds remaining`,\n        getCompletionMessage: () => \"You can now resend the OTP\",\n    });\n\n    // =============================================================================\n    // EVENT HANDLERS\n    // =============================================================================\n    // Send OTP\n    const handleSendOtp = async () => {\n        if (!onSendOtp || isLoading) return;\n\n        try {\n            setIsLoading(true);\n            await onSendOtp();\n            onOtpStateChange(\"sent\");\n            countdown.reset();\n            countdown.start();\n        } catch {\n            // do nothing\n        } finally {\n            setIsLoading(false);\n        }\n    };\n\n    // Verify OTP\n    const handleVerifyOtp = async () => {\n        if (!onVerifyOtp || isVerifyLoading || !otpValue?.value) return;\n\n        try {\n            setIsVerifyLoading(true);\n            await onVerifyOtp(otpValue.value);\n\n            onOtpStateChange(\"verified\");\n\n            clearAnnouncer(\"polite\");\n            announce(\n                \"Success. Your email or mobile number has been verified.\",\n                \"polite\"\n            );\n\n            // Reset the countdown and clear the OTP code in case user enter new OTP later\n            countdown.reset();\n            onOtpChange?.(\"\");\n        } catch {\n            // do nothing\n        } finally {\n            setIsVerifyLoading(false);\n        }\n    };\n\n    // =============================================================================\n    // HELPER FUNCTIONS\n    // =============================================================================\n    const resetToDefault = () => {\n        if (otpState === \"verified\") {\n            onOtpStateChange(\"default\");\n        }\n    };\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    return (\n        <div\n            id={id}\n            data-testid={dataTestId}\n            className={clsx(styles.otpInputWrapper, className)}\n        >\n            <ContactInputSection\n                {...props}\n                inputId={inputId}\n                data-testid={dataTestId ? `${dataTestId}-contact` : undefined}\n                isLoading={isLoading}\n                isVerified={otpState === \"verified\"}\n                countdown={countdown}\n                onSendOtp={handleSendOtp}\n                onStateReset={resetToDefault}\n                sendOtpError={sendOtpError}\n                fixedCountry={\n                    props.type === \"phone-number\" ? props.fixedCountry : true\n                }\n            />\n\n            {otpState === \"sent\" && (\n                <VerificationSection\n                    {...props}\n                    data-testid={\n                        dataTestId ? `${dataTestId}-verification` : undefined\n                    }\n                    otpCode={otpValue?.value}\n                    otpPrefix={otpValue?.prefix}\n                    otpSeparator={otpValue?.separator}\n                    setOtpCode={onOtpChange}\n                    isVerifyLoading={isVerifyLoading}\n                    countdown={countdown}\n                    onVerifyOtp={handleVerifyOtp}\n                    verifyOtpError={verifyOtpError}\n                />\n            )}\n        </div>\n    );\n};\n"],"names":["OtpVerification","props","id","dataTestId","className","inputId","onSendOtp","onVerifyOtp","verifyOtpCountdownTimer","sendOtpError","verifyOtpError","otpValue","onOtpChange","otpState","onOtpStateChange","otpReminderInterval","isLoading","setIsLoading","useState","isVerifyLoading","setIsVerifyLoading","countdown","useCountdown","duration","reminderInterval","getStartMessage","getIntervalMessage","remaining","getCompletionMessage","_jsxs","clsx","styles.otpInputWrapper","children","_jsx","ContactInputSection","Object","assign","undefined","isVerified","__awaiter","reset","start","_a","onStateReset","fixedCountry","type","VerificationSection","otpCode","value","otpPrefix","prefix","otpSeparator","separator","setOtpCode","clearAnnouncer","announce"],"mappings":"6mBAgBO,MAAMA,EAAmBC,IAI5B,MAAMC,GACFA,EACA,cAAeC,EAAUC,UACzBA,EAASC,QACTA,EAAOC,UACPA,EAASC,YACTA,EAAWC,wBACXA,EAA0B,GAAEC,aAC5BA,EAAYC,eACZA,EAAcC,SACdA,EAAQC,YACRA,EAAWC,SACXA,EAAQC,iBACRA,EAAgBC,oBAChBA,EAAsB,KACtBd,GAEGe,EAAWC,GAAgBC,GAAS,IACpCC,EAAiBC,GAAsBF,GAAS,GAEjDG,EAAYC,EAAa,CAC3BC,SAAUf,EACVgB,iBAAkBT,EAClBU,gBAAkBF,GACd,6BAA6BA,YACjCG,mBAAqBC,GAAc,GAAGA,sBACtCC,qBAAsB,IAAM,+BA6DhC,OACIC,EAAA,MAAA,CACI3B,GAAIA,gBACSC,EACbC,UAAW0B,EAAKC,EAAwB3B,GAAU4B,SAAA,CAElDC,EAACC,EAAmBC,OAAAC,OAAA,CAAA,EACZnC,EAAK,CACTI,QAASA,EAAO,cACHF,EAAa,GAAGA,iBAAuBkC,EACpDrB,UAAWA,EACXsB,WAAyB,aAAbzB,EACZQ,UAAWA,EACXf,UAnEU,IAAWiC,OAAA,OAAA,OAAA,GAAA,YAC7B,GAAKjC,IAAaU,EAElB,IACIC,GAAa,SACPX,IACNQ,EAAiB,QACjBO,EAAUmB,QACVnB,EAAUoB,OACd,CAAE,MAAAC,GAEF,SACIzB,GAAa,EACjB,CACJ,IAsDY0B,aAvBW,KACF,aAAb9B,GACAC,EAAiB,UACrB,EAqBQL,aAAcA,EACdmC,aACmB,iBAAf3C,EAAM4C,MAA0B5C,EAAM2C,gBAIhC,SAAb/B,GACGoB,EAACa,mBACO7C,EAAK,CAAA,cAELE,EAAa,GAAGA,sBAA4BkC,EAEhDU,QAASpC,eAAAA,EAAUqC,MACnBC,UAAWtC,aAAQ,EAARA,EAAUuC,OACrBC,aAAcxC,aAAQ,EAARA,EAAUyC,UACxBC,WAAYzC,EACZO,gBAAiBA,EACjBE,UAAWA,EACXd,YAtEQ,IAAWgC,OAAA,OAAA,OAAA,GAAA,YAC/B,GAAKhC,IAAeY,IAAoBR,aAAQ,EAARA,EAAUqC,OAElD,IACI5B,GAAmB,SACbb,EAAYI,EAASqC,OAE3BlC,EAAiB,YAEjBwC,EAAe,UACfC,EACI,0DACA,UAIJlC,EAAUmB,QACV5B,SAAAA,EAAc,GAClB,CAAE,MAAA8B,GAEF,SACItB,GAAmB,EACvB,CACJ,IAgDgBV,eAAgBA,OAGtB"}

package/otp-verification/types.d.ts

@@ -1,52 +1,171 @@
 import type { BaseFormElementProps } from "../form/types";
 import type { PhoneNumberInputValue } from "../phone-number-input";
+import type { VerificationSectionProps } from "./internal-types";
+/**
+ * Lifecycle state of the OTP verification flow.
+ *
+ * - `"default"` — initial state; the contact input is displayed.
+ * - `"sent"` — OTP has been dispatched; the OTP entry and verification section appears.
+ * - `"verified"` — OTP was successfully verified; the success confirmation is displayed.
+ */
 export type OtpVerificationState = "default" | "sent" | "verified";
+/**
+ * Base props shared by all variants of the `OtpVerification` component.
+ */
 export interface BaseOtpVerificationProps {
     id?: string | undefined;
     "data-testid"?: string | undefined;
     disabled?: boolean | undefined;
     readOnly?: boolean | undefined;
     className?: string | undefined;
+    /**
+     * The `id` attribute applied to the contact input field.
+     */
     inputId?: string | undefined;
+    /**
+     * The current step in the OTP verification flow.
+     * Controls which sections are rendered.
+     */
     otpState: OtpVerificationState;
+    /**
+     * Called when the component transition to a new `otpState`.
+     */
     onOtpStateChange: (state: OtpVerificationState) => void;
+    /**
+     * Called when the user initiates sending the OTP.
+     * On resolution, the component transitions to `"sent"`.
+     *
+     * @remarks a rejection is silently swallowed. The consumer must use `sendOtpError` to show feedback
+     */
     onSendOtp?: (() => Promise<void>) | undefined;
+    /**
+     * Error message displayed below the contact input after a failed attempt.
+     */
     sendOtpError?: string | undefined;
+    /**
+     * Placeholder text for the contact input field.
+     */
     sendOtpPlaceholder?: string | undefined;
+    /**
+     * Interval in seconds at which an accessibility announcement is made,
+     * reminding the user how many seconds remain before they can resend the OTP.
+     *
+     * @default 120
+     */
     otpReminderInterval?: number | undefined;
 }
+/**
+ * Email-specific props for `OtpVerification`.
+ */
 export interface OtpVerificationEmailInputProps {
+    /**
+     * Discriminant that sets the contact input to email mode.
+     */
     type: "email";
+    /**
+     * Controlled value of the email input.
+     */
     emailValue?: string | undefined;
+    /**
+     * Called when the email input value changes.
+     */
     onEmailChange?: ((input: string) => void) | undefined;
 }
+/**
+ * Phone-number-specific props for `OtpVerification`.
+ */
 export interface OtpVerificationPhoneNumberInputProps {
+    /**
+     * Discriminant that sets the contact input to phone number mode.
+     */
     type: "phone-number";
+    /**
+     * Controlled value of the phone number input.
+     */
     phoneNumberValue?: PhoneNumberInputValue | undefined;
+    /**
+     * Called when the phone number input value changes.
+     */
     onPhoneNumberChange?: ((value: PhoneNumberInputValue) => void) | undefined;
+    /**
+     * Always `true`; the country selector is locked and cannot be changed by the user.
+     */
     fixedCountry: true;
 }
-export interface OtpVerificationInputProps {
+/**
+ * Props for controlling the OTP input field and verification step.
+ */
+export interface OtpVerificationInputProps extends Pick<VerificationSectionProps, "showVerifyOtpThumbnail" | "verifyOtpIcon" | "verifyOtpTitle" | "verifyOtpMessage" | "verifyOtpError"> {
+    /**
+     * Controlled state of the OTP input field.
+     */
     otpValue?: {
+        /**
+         * Static text displayed before the OTP input.
+         */
         prefix?: string | undefined;
+        /**
+         * Character displayed between the `prefix` and OTP input..
+         */
         separator?: string | undefined;
+        /**
+         * The current OTP string entered by the user.
+         */
         value?: string | undefined;
     } | undefined;
+    /**
+     * Called when the OTP input value changes.
+     *
+     * @param value The full OTP string without prefix or separators.
+     */
     onOtpChange?: ((value: string) => void) | undefined;
+    /**
+     * Called when the user submits the OTP for verification.
+     * On resolution the component transitions to `"verified"`.
+     *
+     * @param input The current OTP string.
+     *
+     * @remarks a rejection is silently swallowed. The consumer must use `verifyOtpError` to show feedback
+     */
     onVerifyOtp?: ((input: string) => Promise<void>) | undefined;
+    /**
+     * Duration in seconds of the resend cooldown after an OTP is sent.
+     *
+     * @default 60
+     */
     verifyOtpCountdownTimer?: number | undefined;
+    /**
+     * Called when the user requests to resend the OTP from the verification step.
+     */
     onResendOtp?: (() => Promise<void>) | undefined;
-    verifyOtpError?: string | undefined;
-    showVerifyOtpThumbnail?: boolean | undefined;
-    verifyOtpIcon?: React.ReactNode | undefined;
-    verifyOtpTitle?: string | undefined;
-    verifyOtpMessage?: string | undefined;
 }
+/**
+ * Combined props for email-based OTP verification.
+ */
 export type EmailOtpVerificationProps = BaseOtpVerificationProps & OtpVerificationEmailInputProps & OtpVerificationInputProps;
+/**
+ * Combined props for phone-number-based OTP verification.
+ */
 export type PhoneOtpVerificationProps = BaseOtpVerificationProps & OtpVerificationPhoneNumberInputProps & OtpVerificationInputProps;
+/**
+ * Props for the `OtpVerification` component.
+ */
 export type OtpVerificationProps = EmailOtpVerificationProps | PhoneOtpVerificationProps;
+/**
+ * Props for the `Form.OtpVerification` email variant, extending
+ * `EmailOtpVerificationProps` with form field layout metadata such as label
+ * and hint text.
+ */
 export interface FormEmailOtpVerificationProps extends EmailOtpVerificationProps, Omit<BaseFormElementProps, "errorMessage"> {
 }
+/**
+ * Props for the `Form.OtpVerification` phone-number variant, extending
+ * `PhoneOtpVerificationProps` with form field layout metadata such as label
+ * and hint text.
+ */
 export interface FormPhoneOtpVerificationProps extends PhoneOtpVerificationProps, Omit<BaseFormElementProps, "errorMessage"> {
 }
+/**
+ * Props for the `Form.OtpVerification` component.
+ */
 export type FormOtpVerificationProps = FormEmailOtpVerificationProps | FormPhoneOtpVerificationProps;

package/overlay/overlay.d.ts

@@ -1,2 +1,9 @@
 import type { OverlayProps } from "./types";
+/**
+ * A full-screen dimmed overlay backdrop.
+ *
+ * Use `Overlay` as the backdrop for modal dialogs, drawers, and similar
+ * blocking UI patterns. It manages body scroll-lock automatically and stacks
+ * correctly when multiple overlays are open at once.
+ */
 export declare const Overlay: (props: OverlayProps) => import("react/jsx-runtime").JSX.Element;