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

package/histogram-slider/histogram-slider.js.map

@@ -1 +1 @@
-{"version":3,"file":"histogram-slider.js","sources":["../../src/histogram-slider/histogram-slider.tsx"],"sourcesContent":["import { announce, clearAnnouncer } from \"@react-aria/live-announcer\";\nimport clsx from \"clsx\";\nimport { useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { InputRangeSlider } from \"../input-range-slider\";\nimport { concatIds } from \"../shared/accessibility\";\nimport { useApplyStyle } from \"../theme\";\nimport { Typography } from \"../typography\";\nimport { useId } from \"../util\";\nimport * as styles from \"./histogram-slider.styles\";\nimport type { HistogramBinProps, HistogramSliderProps } from \"./types\";\n\nconst ANNOUNCEMENT_DEBOUNCE_MS = 500;\n\nexport const HistogramSlider = ({\n    bins = [],\n    interval,\n    disabled,\n    readOnly,\n    value,\n    showRangeLabels,\n    rangeLabelPrefix,\n    rangeLabelSuffix,\n    ariaLabels,\n    \"aria-labelledby\": ariaLabelledBy,\n    \"aria-describedby\": ariaDescribedBy,\n    onChange,\n    onChangeEnd,\n    renderEmptyView,\n    renderRangeLabel,\n    className,\n    ...otherProps\n}: HistogramSliderProps) => {\n    // =========================================================================\n    // CONST, STATE, REF\n    // =========================================================================\n    const counts = bins.map((item) => item.count);\n    const maxCount = Math.max(...counts);\n\n    const values = bins.map((item) => item.minValue);\n    const maxValue = Math.max(...values);\n    const minValue = Math.min(...values);\n\n    const [selection, setSelection] = useState<[number, number]>(\n        initSelection()\n    );\n    const internalId = useId();\n    const announcementTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(\n        null\n    );\n    const rangeLabelId = `${internalId}-range-label`;\n    const sliderDescribedBy = concatIds(\n        ariaDescribedBy,\n        showRangeLabels ? rangeLabelId : undefined\n    );\n\n    const items = useMemo(() => {\n        const sorted = [...bins].sort((a, b) => a.minValue - b.minValue);\n        const numCols = (maxValue - minValue) / interval + 1;\n\n        const items: typeof sorted = [];\n        for (let i = 0; i < numCols; i++) {\n            const bin = sorted.find(\n                (b) => b.minValue === minValue + interval * i\n            );\n            if (bin) {\n                items.push(bin);\n            } else {\n                items.push({ count: 0, minValue: minValue + interval * i });\n            }\n        }\n        return items;\n    }, [bins, interval]);\n\n    // =========================================================================\n    // EFFECTS\n    // =========================================================================\n    useEffect(() => {\n        if (value !== selection) {\n            setSelection(initSelection());\n        }\n    }, [value]);\n\n    useEffect(() => {\n        return () => {\n            clearPendingAnnouncement();\n        };\n    }, []);\n\n    // =========================================================================\n    // EVENT HANDLERS\n    // =========================================================================\n    const handleChange = (values: number[]) => {\n        const [val1, val2] = values;\n        const newSelection: [number, number] = [val1, val2];\n        setSelection(newSelection);\n        scheduleRangePercentageAnnouncement(newSelection);\n        onChange?.(newSelection);\n    };\n\n    const handleChangeEnd = (values: number[]) => {\n        const [val1, val2] = values;\n        const newSelection: [number, number] = [val1, val2];\n        setSelection(newSelection);\n        scheduleRangePercentageAnnouncement(newSelection);\n        onChangeEnd?.(newSelection);\n    };\n\n    // =========================================================================\n    // HELPER FUNCTIONS\n    // =========================================================================\n    function initSelection(): [number, number] {\n        return value ?? [minValue, minValue + interval];\n    }\n\n    function clearPendingAnnouncement() {\n        if (announcementTimeoutRef.current) {\n            clearTimeout(announcementTimeoutRef.current);\n            announcementTimeoutRef.current = null;\n        }\n    }\n\n    function getRangePercentageDescription(currentSelection: [number, number]) {\n        const totalCount = items.reduce((sum, item) => sum + item.count, 0);\n\n        if (totalCount === 0) {\n            return \"0% of results available in the range you specified.\";\n        }\n\n        const selectedCount = items.reduce((sum, item) => {\n            const isSelected =\n                item.minValue >= currentSelection[0] &&\n                item.minValue < currentSelection[1];\n\n            return isSelected ? sum + item.count : sum;\n        }, 0);\n\n        const percentage = Math.round((selectedCount / totalCount) * 100);\n\n        return `${percentage}% of results available in the range you specified.`;\n    }\n\n    function scheduleRangePercentageAnnouncement(\n        currentSelection: [number, number]\n    ) {\n        if (disabled || readOnly) {\n            return;\n        }\n\n        const announcement = getRangePercentageDescription(currentSelection);\n\n        clearPendingAnnouncement();\n\n        announcementTimeoutRef.current = setTimeout(() => {\n            clearAnnouncer(\"polite\");\n            announce(announcement, \"polite\");\n        }, ANNOUNCEMENT_DEBOUNCE_MS);\n    }\n\n    // =========================================================================\n    // RENDER FUNCTIONS\n    // =========================================================================\n    const renderRangeItem = (value: number) => {\n        if (renderRangeLabel) {\n            return renderRangeLabel(value);\n        }\n        return (\n            <Typography.BodyBL>\n                {rangeLabelPrefix}\n                {value}\n                {rangeLabelSuffix}\n            </Typography.BodyBL>\n        );\n    };\n\n    const renderHistogramSlider = () => {\n        const selectionDescription = getRangePercentageDescription(selection);\n\n        return (\n            <>\n                <div className={styles.histogram}>\n                    {items.map((item, i) => (\n                        <HistogramBar\n                            key={i}\n                            item={item}\n                            maxCount={maxCount}\n                            isSelected={\n                                item.minValue >= selection[0] &&\n                                item.minValue < selection[1]\n                            }\n                            isDisabled={disabled || readOnly}\n                        />\n                    ))}\n                </div>\n                <InputRangeSlider\n                    min={minValue}\n                    max={maxValue + interval}\n                    step={interval}\n                    minRange={interval}\n                    numOfThumbs={2}\n                    value={selection}\n                    disabled={disabled}\n                    readOnly={readOnly}\n                    ariaLabels={ariaLabels}\n                    ariaDescriptions={[\n                        selectionDescription,\n                        selectionDescription,\n                    ]}\n                    aria-describedby={sliderDescribedBy}\n                    aria-labelledby={ariaLabelledBy}\n                    onChange={handleChange}\n                    onChangeEnd={handleChangeEnd}\n                    className={styles.slider}\n                />\n            </>\n        );\n    };\n\n    return (\n        <div role=\"group\" {...otherProps} className={className}>\n            {showRangeLabels && (\n                <div id={rangeLabelId} className={styles.label}>\n                    {renderRangeItem(selection[0])}\n                    <div className={styles.separator}>-</div>\n                    {renderRangeItem(selection[1])}\n                </div>\n            )}\n            {items.every((item) => item.count === 0) && renderEmptyView\n                ? renderEmptyView()\n                : renderHistogramSlider()}\n        </div>\n    );\n};\n\n// =============================================================================\n// SUB COMPONENT\n// =============================================================================\ninterface HistogramBarProps {\n    item: HistogramBinProps;\n    maxCount: number;\n    isSelected: boolean;\n    isDisabled: boolean | undefined;\n}\n\nconst HistogramBar = ({\n    item,\n    maxCount,\n    isSelected,\n    isDisabled,\n}: HistogramBarProps) => {\n    const ratio = item.count / maxCount;\n    const barRef = useRef<HTMLDivElement>(null);\n\n    useApplyStyle(barRef, {\n        height: ratio ? `calc(calc(100% - 0.25rem) * ${ratio} + 0.25rem)` : \"0\",\n    });\n\n    return (\n        <div\n            data-testid=\"histogram-bar\"\n            className={clsx(\n                styles.bar,\n                isDisabled && isSelected && styles.barSelectedDisabled,\n                isDisabled && styles.barDisabled,\n                isSelected && styles.barSelected\n            )}\n            ref={barRef}\n        />\n    );\n};\n"],"names":["HistogramSlider","_a","bins","interval","disabled","readOnly","value","showRangeLabels","rangeLabelPrefix","rangeLabelSuffix","ariaLabels","ariaLabelledBy","ariaDescribedBy","onChange","onChangeEnd","renderEmptyView","renderRangeLabel","className","otherProps","__rest","counts","map","item","count","maxCount","Math","max","values","minValue","maxValue","min","selection","setSelection","useState","initSelection","internalId","useId","announcementTimeoutRef","useRef","rangeLabelId","sliderDescribedBy","concatIds","undefined","items","useMemo","sorted","sort","a","b","numCols","i","bin","find","push","useEffect","clearPendingAnnouncement","handleChange","val1","val2","newSelection","scheduleRangePercentageAnnouncement","handleChangeEnd","current","clearTimeout","getRangePercentageDescription","currentSelection","totalCount","reduce","sum","selectedCount","round","announcement","setTimeout","clearAnnouncer","announce","renderRangeItem","_jsxs","Typography","BodyBL","children","Object","assign","role","id","styles.label","_jsx","styles.separator","every","selectionDescription","_Fragment","styles.histogram","HistogramBar","isSelected","isDisabled","InputRangeSlider","step","minRange","numOfThumbs","ariaDescriptions","styles.slider","renderHistogramSlider","ratio","barRef","useApplyStyle","height","clsx","styles.bar","styles.barSelectedDisabled","styles.barDisabled","styles.barSelected","ref"],"mappings":"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"}
+{"version":3,"file":"histogram-slider.js","sources":["../../src/histogram-slider/histogram-slider.tsx"],"sourcesContent":["import { announce, clearAnnouncer } from \"@react-aria/live-announcer\";\nimport clsx from \"clsx\";\nimport { useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { InputRangeSlider } from \"../input-range-slider\";\nimport { concatIds } from \"../shared/accessibility\";\nimport { useApplyStyle } from \"../theme\";\nimport { Typography } from \"../typography\";\nimport { useId } from \"../util\";\nimport * as styles from \"./histogram-slider.styles\";\nimport type { HistogramBinProps, HistogramSliderProps } from \"./types\";\n\nconst ANNOUNCEMENT_DEBOUNCE_MS = 500;\n\n// @catalog\n/**\n * A histogram with an overlaid two-thumb range slider for numeric filtering.\n *\n * Use `HistogramSlider` to let users narrow a dataset by selecting a numeric\n * range while seeing how values are distributed across bins.\n */\nexport const HistogramSlider = ({\n    bins = [],\n    interval,\n    disabled,\n    readOnly,\n    value,\n    showRangeLabels,\n    rangeLabelPrefix,\n    rangeLabelSuffix,\n    ariaLabels,\n    \"aria-labelledby\": ariaLabelledBy,\n    \"aria-describedby\": ariaDescribedBy,\n    onChange,\n    onChangeEnd,\n    renderEmptyView,\n    renderRangeLabel,\n    className,\n    ...otherProps\n}: HistogramSliderProps) => {\n    // =========================================================================\n    // CONST, STATE, REF\n    // =========================================================================\n    const counts = bins.map((item) => item.count);\n    const maxCount = Math.max(...counts);\n\n    const values = bins.map((item) => item.minValue);\n    const maxValue = Math.max(...values);\n    const minValue = Math.min(...values);\n\n    const [selection, setSelection] = useState<[number, number]>(\n        initSelection()\n    );\n    const internalId = useId();\n    const announcementTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(\n        null\n    );\n    const rangeLabelId = `${internalId}-range-label`;\n    const sliderDescribedBy = concatIds(\n        ariaDescribedBy,\n        showRangeLabels ? rangeLabelId : undefined\n    );\n\n    const items = useMemo(() => {\n        const sorted = [...bins].sort((a, b) => a.minValue - b.minValue);\n        const numCols = (maxValue - minValue) / interval + 1;\n\n        const items: typeof sorted = [];\n        for (let i = 0; i < numCols; i++) {\n            const bin = sorted.find(\n                (b) => b.minValue === minValue + interval * i\n            );\n            if (bin) {\n                items.push(bin);\n            } else {\n                items.push({ count: 0, minValue: minValue + interval * i });\n            }\n        }\n        return items;\n    }, [bins, interval]);\n\n    // =========================================================================\n    // EFFECTS\n    // =========================================================================\n    useEffect(() => {\n        if (value !== selection) {\n            setSelection(initSelection());\n        }\n    }, [value]);\n\n    useEffect(() => {\n        return () => {\n            clearPendingAnnouncement();\n        };\n    }, []);\n\n    // =========================================================================\n    // EVENT HANDLERS\n    // =========================================================================\n    const handleChange = (values: number[]) => {\n        const [val1, val2] = values;\n        const newSelection: [number, number] = [val1, val2];\n        setSelection(newSelection);\n        scheduleRangePercentageAnnouncement(newSelection);\n        onChange?.(newSelection);\n    };\n\n    const handleChangeEnd = (values: number[]) => {\n        const [val1, val2] = values;\n        const newSelection: [number, number] = [val1, val2];\n        setSelection(newSelection);\n        scheduleRangePercentageAnnouncement(newSelection);\n        onChangeEnd?.(newSelection);\n    };\n\n    // =========================================================================\n    // HELPER FUNCTIONS\n    // =========================================================================\n    function initSelection(): [number, number] {\n        return value ?? [minValue, minValue + interval];\n    }\n\n    function clearPendingAnnouncement() {\n        if (announcementTimeoutRef.current) {\n            clearTimeout(announcementTimeoutRef.current);\n            announcementTimeoutRef.current = null;\n        }\n    }\n\n    function getRangePercentageDescription(currentSelection: [number, number]) {\n        const totalCount = items.reduce((sum, item) => sum + item.count, 0);\n\n        if (totalCount === 0) {\n            return \"0% of results available in the range you specified.\";\n        }\n\n        const selectedCount = items.reduce((sum, item) => {\n            const isSelected =\n                item.minValue >= currentSelection[0] &&\n                item.minValue < currentSelection[1];\n\n            return isSelected ? sum + item.count : sum;\n        }, 0);\n\n        const percentage = Math.round((selectedCount / totalCount) * 100);\n\n        return `${percentage}% of results available in the range you specified.`;\n    }\n\n    function scheduleRangePercentageAnnouncement(\n        currentSelection: [number, number]\n    ) {\n        if (disabled || readOnly) {\n            return;\n        }\n\n        const announcement = getRangePercentageDescription(currentSelection);\n\n        clearPendingAnnouncement();\n\n        announcementTimeoutRef.current = setTimeout(() => {\n            clearAnnouncer(\"polite\");\n            announce(announcement, \"polite\");\n        }, ANNOUNCEMENT_DEBOUNCE_MS);\n    }\n\n    // =========================================================================\n    // RENDER FUNCTIONS\n    // =========================================================================\n    const renderRangeItem = (value: number) => {\n        if (renderRangeLabel) {\n            return renderRangeLabel(value);\n        }\n        return (\n            <Typography.BodyBL>\n                {rangeLabelPrefix}\n                {value}\n                {rangeLabelSuffix}\n            </Typography.BodyBL>\n        );\n    };\n\n    const renderHistogramSlider = () => {\n        const selectionDescription = getRangePercentageDescription(selection);\n\n        return (\n            <>\n                <div className={styles.histogram}>\n                    {items.map((item, i) => (\n                        <HistogramBar\n                            key={i}\n                            item={item}\n                            maxCount={maxCount}\n                            isSelected={\n                                item.minValue >= selection[0] &&\n                                item.minValue < selection[1]\n                            }\n                            isDisabled={disabled || readOnly}\n                        />\n                    ))}\n                </div>\n                <InputRangeSlider\n                    min={minValue}\n                    max={maxValue + interval}\n                    step={interval}\n                    minRange={interval}\n                    numOfThumbs={2}\n                    value={selection}\n                    disabled={disabled}\n                    readOnly={readOnly}\n                    ariaLabels={ariaLabels}\n                    ariaDescriptions={[\n                        selectionDescription,\n                        selectionDescription,\n                    ]}\n                    aria-describedby={sliderDescribedBy}\n                    aria-labelledby={ariaLabelledBy}\n                    onChange={handleChange}\n                    onChangeEnd={handleChangeEnd}\n                    className={styles.slider}\n                />\n            </>\n        );\n    };\n\n    return (\n        <div role=\"group\" {...otherProps} className={className}>\n            {showRangeLabels && (\n                <div id={rangeLabelId} className={styles.label}>\n                    {renderRangeItem(selection[0])}\n                    <div className={styles.separator}>-</div>\n                    {renderRangeItem(selection[1])}\n                </div>\n            )}\n            {items.every((item) => item.count === 0) && renderEmptyView\n                ? renderEmptyView()\n                : renderHistogramSlider()}\n        </div>\n    );\n};\n\n// =============================================================================\n// SUB COMPONENT\n// =============================================================================\ninterface HistogramBarProps {\n    item: HistogramBinProps;\n    maxCount: number;\n    isSelected: boolean;\n    isDisabled: boolean | undefined;\n}\n\nconst HistogramBar = ({\n    item,\n    maxCount,\n    isSelected,\n    isDisabled,\n}: HistogramBarProps) => {\n    const ratio = item.count / maxCount;\n    const barRef = useRef<HTMLDivElement>(null);\n\n    useApplyStyle(barRef, {\n        height: ratio ? `calc(calc(100% - 0.25rem) * ${ratio} + 0.25rem)` : \"0\",\n    });\n\n    return (\n        <div\n            data-testid=\"histogram-bar\"\n            className={clsx(\n                styles.bar,\n                isDisabled && isSelected && styles.barSelectedDisabled,\n                isDisabled && styles.barDisabled,\n                isSelected && styles.barSelected\n            )}\n            ref={barRef}\n        />\n    );\n};\n"],"names":["HistogramSlider","_a","bins","interval","disabled","readOnly","value","showRangeLabels","rangeLabelPrefix","rangeLabelSuffix","ariaLabels","ariaLabelledBy","ariaDescribedBy","onChange","onChangeEnd","renderEmptyView","renderRangeLabel","className","otherProps","__rest","counts","map","item","count","maxCount","Math","max","values","minValue","maxValue","min","selection","setSelection","useState","initSelection","internalId","useId","announcementTimeoutRef","useRef","rangeLabelId","sliderDescribedBy","concatIds","undefined","items","useMemo","sorted","sort","a","b","numCols","i","bin","find","push","useEffect","clearPendingAnnouncement","handleChange","val1","val2","newSelection","scheduleRangePercentageAnnouncement","handleChangeEnd","current","clearTimeout","getRangePercentageDescription","currentSelection","totalCount","reduce","sum","selectedCount","round","announcement","setTimeout","clearAnnouncer","announce","renderRangeItem","_jsxs","Typography","BodyBL","children","Object","assign","role","id","styles.label","_jsx","styles.separator","every","selectionDescription","_Fragment","styles.histogram","HistogramBar","isSelected","isDisabled","InputRangeSlider","step","minRange","numOfThumbs","ariaDescriptions","styles.slider","renderHistogramSlider","ratio","barRef","useApplyStyle","height","clsx","styles.bar","styles.barSelectedDisabled","styles.barDisabled","styles.barSelected","ref"],"mappings":"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"}

package/histogram-slider/types.d.ts

@@ -1,27 +1,87 @@
+/**
+ * A single bin (bar) in the histogram, representing a value range and its
+ * item count.
+ *
+ * The upper bound of the bin's range is `minValue + interval`, where
+ * `interval` is provided separately via `HistogramSliderProps`.
+ */
 export interface HistogramBinProps {
+    /**
+     * Number of items that fall within this bin's value range.
+     */
     count: number;
+    /** Lower bound of this bin's value range. */
     minValue: number;
 }
+/** Props for the `HistogramSlider` component. */
 export interface HistogramSliderProps {
     className?: string | undefined;
     id?: string | undefined;
     "data-testid"?: string | undefined;
+    /**
+     * The set of bins to render as bars.
+     */
     bins: HistogramBinProps[];
+    /**
+     * Controls the slider's step increment and minimum selectable range.
+     */
     interval: number;
     disabled?: boolean | undefined;
     readOnly?: boolean | undefined;
-    /** The selected range, in the format `[start, end]` */
+    /**
+     * The selected range as `[start, end]`.
+     *
+     * When omitted, the selection is initialised to
+     * `[minValue, minValue + interval]` derived from the provided `bins`.
+     */
     value?: [number, number] | undefined;
+    /**
+     * When `true`, displays the current start and end values above the
+     * histogram.
+     */
     showRangeLabels?: boolean | undefined;
+    /**
+     * Text prepended to each range label value.
+     * Has no effect when `renderRangeLabel` is provided.
+     */
     rangeLabelPrefix?: string | undefined;
+    /**
+     * Text appended to each range label value.
+     * Has no effect when `renderRangeLabel` is provided.
+     */
     rangeLabelSuffix?: string | undefined;
+    /**
+     * Accessible labels for the two slider thumbs, as `[startLabel, endLabel]`.
+     */
     ariaLabels?: [string, string] | undefined;
+    /**
+     * ID of an element that labels the slider group.
+     */
     "aria-labelledby"?: string | undefined;
+    /**
+     * ID of an element that describes the slider group.
+     */
     "aria-describedby"?: string | undefined;
+    /**
+     * Custom renderer for each range label value. When provided, overrides the
+     * `rangeLabelPrefix` and `rangeLabelSuffix` combination.
+     */
     renderRangeLabel?: ((value: number) => React.ReactNode) | undefined;
-    /** Called on every selection change. Returns the value in the format `[start, end]` */
+    /**
+     * Called on every selection change.
+     *
+     * @param value The current selection as `[start, end]`.
+     */
     onChange?: ((value: [number, number]) => void) | undefined;
-    /** Called when a thumb is released after selection is complete. Returns the value in the format `[start, end]` */
+    /**
+     * Called when a thumb is released after selection is complete.
+     *
+     * @param value The settled selection as `[start, end]`.
+     */
     onChangeEnd?: ((value: [number, number]) => void) | undefined;
+    /**
+     * Rendered in place of the histogram and slider when all bins have a count
+     * of zero.
+     */
     renderEmptyView?: (() => React.ReactNode) | undefined;
 }

package/image-button/image-button.d.ts

@@ -1,3 +1,9 @@
 import React from "react";
 import type { ImageButtonProps } from "./types";
+/**
+ * A button that displays an image alongside optional label content.
+ *
+ * Use `ImageButton` for selectable image-based choices such as theme pickers or avatar
+ * selectors, where each option is represented visually.
+ */
 export declare const ImageButton: (props: ImageButtonProps & React.RefAttributes<HTMLButtonElement>) => React.ReactElement | null;

package/image-button/image-button.js.map

@@ -1 +1 @@
-{"version":3,"file":"image-button.js","sources":["../../src/image-button/image-button.tsx"],"sourcesContent":["import clsx from \"clsx\";\nimport React from \"react\";\n\nimport type { ButtonRef } from \"../button/types\";\nimport { ImageWithFallback } from \"../shared/image-with-fallback/image-with-fallback\";\nimport * as styles from \"./image-button.styles\";\nimport type { ImageButtonProps } from \"./types\";\n\nconst Component = (\n    {\n        children,\n        className,\n        imgSrc,\n        selected,\n        error,\n        type = \"button\",\n        disabled = false,\n        focusableWhenDisabled = false,\n        onClick,\n        ...otherProps\n    }: ImageButtonProps,\n    ref: ButtonRef\n) => {\n    const isNativeDisabled = !!disabled && !focusableWhenDisabled;\n\n    return (\n        <button\n            ref={ref}\n            type={type}\n            aria-disabled={disabled}\n            disabled={isNativeDisabled}\n            onClick={disabled ? undefined : onClick}\n            className={clsx(\n                styles.main,\n                selected && styles.mainSelectedText,\n                selected && styles.mainSelected,\n                error && styles.mainError,\n                disabled && styles.mainDisabled,\n                className\n            )}\n            {...otherProps}\n        >\n            <ImageWithFallback src={imgSrc} />\n            {children}\n        </button>\n    );\n};\n\nexport const ImageButton = React.forwardRef(Component);\n"],"names":["ImageButton","React","forwardRef","_a","ref","children","className","imgSrc","selected","error","type","disabled","focusableWhenDisabled","onClick","otherProps","__rest","isNativeDisabled","_jsxs","Object","assign","undefined","clsx","styles.main","styles.mainSelectedText","styles.mainSelected","styles.mainError","styles.mainDisabled","_jsx","ImageWithFallback","src"],"mappings":"4VAQA,MAwCaA,EAAcC,EAAMC,YAxCf,CACdC,EAYAC,KAZA,IAAAC,SACIA,EAAQC,UACRA,EAASC,OACTA,EAAMC,SACNA,EAAQC,MACRA,EAAKC,KACLA,EAAO,SAAQC,SACfA,GAAW,EAAKC,sBAChBA,GAAwB,EAAKC,QAC7BA,GAAOV,EACJW,EAAUC,EAAAZ,EAVjB,CAAA,WAAA,YAAA,SAAA,WAAA,QAAA,OAAA,WAAA,wBAAA,YAcA,MAAMa,IAAqBL,IAAaC,EAExC,OACIK,EAAA,SAAAC,OAAAC,OAAA,CACIf,IAAKA,EACLM,KAAMA,EAAI,gBACKC,EACfA,SAAUK,EACVH,QAASF,OAAWS,EAAYP,EAChCP,UAAWe,EACPC,EACAd,GAAYe,EACZf,GAAYgB,EACZf,GAASgB,EACTd,GAAYe,EACZpB,IAEAQ,EAAU,CAAAT,SAAA,CAEdsB,EAACC,EAAiB,CAACC,IAAKtB,IACvBF,KACI"}
+{"version":3,"file":"image-button.js","sources":["../../src/image-button/image-button.tsx"],"sourcesContent":["import clsx from \"clsx\";\nimport React from \"react\";\n\nimport type { ButtonRef } from \"../button/types\";\nimport { ImageWithFallback } from \"../shared/image-with-fallback/image-with-fallback\";\nimport * as styles from \"./image-button.styles\";\nimport type { ImageButtonProps } from \"./types\";\n\nconst Component = (\n    {\n        children,\n        className,\n        imgSrc,\n        selected,\n        error,\n        type = \"button\",\n        disabled = false,\n        focusableWhenDisabled = false,\n        onClick,\n        ...otherProps\n    }: ImageButtonProps,\n    ref: ButtonRef\n) => {\n    const isNativeDisabled = !!disabled && !focusableWhenDisabled;\n\n    return (\n        <button\n            ref={ref}\n            type={type}\n            aria-disabled={disabled}\n            disabled={isNativeDisabled}\n            onClick={disabled ? undefined : onClick}\n            className={clsx(\n                styles.main,\n                selected && styles.mainSelectedText,\n                selected && styles.mainSelected,\n                error && styles.mainError,\n                disabled && styles.mainDisabled,\n                className\n            )}\n            {...otherProps}\n        >\n            <ImageWithFallback src={imgSrc} />\n            {children}\n        </button>\n    );\n};\n\n// @catalog\n/**\n * A button that displays an image alongside optional label content.\n *\n * Use `ImageButton` for selectable image-based choices such as theme pickers or avatar\n * selectors, where each option is represented visually.\n */\nexport const ImageButton = React.forwardRef(Component);\n"],"names":["ImageButton","React","forwardRef","_a","ref","children","className","imgSrc","selected","error","type","disabled","focusableWhenDisabled","onClick","otherProps","__rest","isNativeDisabled","_jsxs","Object","assign","undefined","clsx","styles.main","styles.mainSelectedText","styles.mainSelected","styles.mainError","styles.mainDisabled","_jsx","ImageWithFallback","src"],"mappings":"4VAQA,MA+CaA,EAAcC,EAAMC,YA/Cf,CACdC,EAYAC,KAZA,IAAAC,SACIA,EAAQC,UACRA,EAASC,OACTA,EAAMC,SACNA,EAAQC,MACRA,EAAKC,KACLA,EAAO,SAAQC,SACfA,GAAW,EAAKC,sBAChBA,GAAwB,EAAKC,QAC7BA,GAAOV,EACJW,EAAUC,EAAAZ,EAVjB,CAAA,WAAA,YAAA,SAAA,WAAA,QAAA,OAAA,WAAA,wBAAA,YAcA,MAAMa,IAAqBL,IAAaC,EAExC,OACIK,EAAA,SAAAC,OAAAC,OAAA,CACIf,IAAKA,EACLM,KAAMA,EAAI,gBACKC,EACfA,SAAUK,EACVH,QAASF,OAAWS,EAAYP,EAChCP,UAAWe,EACPC,EACAd,GAAYe,EACZf,GAAYgB,EACZf,GAASgB,EACTd,GAAYe,EACZpB,IAEAQ,EAAU,CAAAT,SAAA,CAEdsB,EAACC,EAAiB,CAACC,IAAKtB,IACvBF,KACI"}

package/image-button/types.d.ts

@@ -1,8 +1,18 @@
+/**
+ * Props for the `ImageButton` component.
+ */
 export interface ImageButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     "data-testid"?: string | undefined;
-    /** The image source to be rendered */
+    /** URL of the image to display inside the button. */
     imgSrc: string;
+    /** Applies a selected visual style to indicate the button is the active choice. */
     selected?: boolean | undefined;
+    /** Applies an error visual style to indicate a validation or selection error. */
     error?: boolean | undefined;
+    /**
+     * Keeps the button reachable via keyboard focus when `disabled` is `true`.
+     *
+     * @default false
+     */
     focusableWhenDisabled?: boolean | undefined;
 }

package/index.js

@@ -1,2 +1,2 @@
-export{Accordion}from"./accordion/accordion.js";export{Alert}from"./alert/alert.js";export{LoadingDots}from"./animations/loading-dots/loading-dots.js";export{LoadingDotsSpinner}from"./animations/loading-dots-spinner/loading-dots-spinner.js";export{LoadingSpinner}from"./animations/loading-spinner/loading-spinner.js";export{ThemedLoadingSpinner}from"./animations/themed-loading-spinner/themed-loading-spinner.js";export{Avatar}from"./avatar/avatar.js";export{Badge}from"./badge/badge.js";export{BoxContainer}from"./box-container/box-container.js";export{Breadcrumb}from"./breadcrumb/breadcrumb.js";export{Button}from"./button/button.js";export{Calendar}from"./calendar/calendar.js";export{Card}from"./card/card.js";export{Checkbox}from"./checkbox/checkbox.js";export{CountdownTimer}from"./countdown-timer/countdown-timer.js";export{DashedBorder}from"./dashed-border/dashed-border.js";export{DataTable}from"./data-table/data-table.js";export{DateInput}from"./date-input/date-input.js";export{DateNavigator}from"./date-navigator/date-navigator.js";export{DateRangeInput}from"./date-range-input/date-range-input.js";export{Divider}from"./divider/divider.js";export{Drawer}from"./drawer/drawer.js";export{ESignature}from"./e-signature/e-signature.js";export{ErrorDisplay}from"./error-display/error-display.js";export{ErrorDisplayHelper}from"./error-display/helper.js";export{FeedbackRating}from"./feedback-rating/feedback-rating.js";export{FileDownload}from"./file-download/file-download.js";export{FileUpload}from"./file-upload/file-upload.js";export{Filter}from"./filter/filter.js";export{Footer}from"./footer/footer.js";export{Form}from"./form/index.js";export{Component,FullscreenImageCarousel}from"./fullscreen-image-carousel/fullscreen-image-carousel.js";export{HistogramSlider}from"./histogram-slider/histogram-slider.js";export{ImageButton}from"./image-button/image-button.js";export{Input}from"./input/input.js";export{InputGroup}from"./input-group/input-group.js";export{InputMultiSelect}from"./input-multi-select/input-multi-select.js";export{InputNestedMultiSelect}from"./input-nested-multi-select/input-nested-multi-select.js";export{InputNestedSelect}from"./input-nested-select/input-nested-select.js";export{InputRangeSelect}from"./input-range-select/input-range-select.js";export{InputRangeSlider}from"./input-range-slider/input-range-slider.js";export{InputSelect}from"./input-select/input-select.js";export{InputSlider}from"./input-slider/input-slider.js";export{Textarea}from"./input-textarea/textarea.js";export{LanguageSwitcher}from"./language-switcher/language-switcher.js";export{Layout}from"./layout/index.js";export{LinkList}from"./link-list/link-list.js";export{Markup}from"./markup/markup.js";export{MaskedInput}from"./masked-input/masked-input.js";export{Masthead}from"./masthead/masthead.js";export{Menu,MenuTrigger}from"./menu/menu.js";export{Modal}from"./modal/index.js";export{ModalV2}from"./modal-v2/index.js";export{Navbar}from"./navbar/navbar.js";export{NBComponent,NotificationBanner}from"./notification-banner/notification-banner.js";export{withNotificationBanner}from"./notification-banner/notification-banner-hoc.js";export{OtpInput}from"./otp-input/otp-input.js";export{Overlay}from"./overlay/overlay.js";export{Pagination}from"./pagination/pagination.js";export{PhoneNumberInput}from"./phone-number-input/phone-number-input.js";export{Pill}from"./pill/pill.js";export{Popover}from"./popover/popover.js";export{PopoverInline}from"./popover/popover-inline/popover-inline.js";export{PopoverTrigger}from"./popover/popover-trigger.js";export{PredictiveTextInput}from"./predictive-text-input/predictive-text-input.js";export{ProgressIndicator}from"./progress-indicator/progress-indicator.js";export{RadioButton}from"./radio-button/radio-button.js";export{SelectHistogram}from"./select-histogram/select-histogram.js";export{Sidenav}from"./sidenav/sidenav.js";export{SingpassButton}from"./singpass-button/singpass-button.js";export{SmartAppBanner}from"./smart-app-banner/smart-app-banner.js";export{Tab}from"./tab/tab.js";export{Table}from"./table/table.js";export{Tag}from"./tag/tag.js";export{TextList}from"./text-list/index.js";export{ThemeProvider}from"./theme/theme-provider/index.js";export{useInheritedThemeScope,useTheme}from"./theme/theme-provider/hooks.js";export{Border,BorderStyle,BorderThickness}from"./theme/tokens/border.js";export{Breakpoint}from"./theme/tokens/breakpoint.js";export{Colour,PrimitiveColours,SemanticColours}from"./theme/tokens/colour.js";export{ComponentToken}from"./theme/tokens/component.js";export{Font,FontSpec}from"./theme/tokens/font.js";export{MediaQuery}from"./theme/tokens/media-query.js";export{Motion}from"./theme/tokens/motion.js";export{Radius}from"./theme/tokens/radius.js";export{Shadow}from"./theme/tokens/shadow.js";export{Spacing}from"./theme/tokens/spacing.js";export{THEME_TYPES}from"./theme/types.js";export{formatUnitValue,parsePxOrRemValue}from"./theme/utils/css-variable.js";export{useApplyStyle}from"./theme/utils/use-apply-styles.js";export{useDesignToken}from"./theme/utils/use-design-token.js";export{useMaxWidthMediaQuery,useMediaQuery,useMinWidthMediaQuery,useResolvedBreakpointToken}from"./theme/utils/use-media-query.js";export{TimeRangePicker}from"./time-range-picker/time-range-picker.js";export{TimeSlotBar}from"./time-slot-bar/time-slot-bar.js";export{TimeSlotBarWeek}from"./time-slot-bar-week/time-slot-bar-week.js";export{TimeSlotWeekView}from"./time-slot-week-view/time-slot-week-view.js";export{Timeline}from"./timeline/timeline.js";export{Timepicker}from"./timepicker/timepicker.js";export{TimeTable}from"./timetable/timetable.js";export{Toast}from"./toast/toast.js";export{Toggle}from"./toggle/toggle.js";export{Typography}from"./typography/index.js";export{UneditableSection}from"./uneditable-section/index.js";export{UnitNumberInput}from"./unit-number/unit-number-input.js";
+export{Accordion}from"./accordion/accordion.js";export{Alert}from"./alert/alert.js";export{LoadingDots}from"./animations/loading-dots/loading-dots.js";export{LoadingDotsSpinner}from"./animations/loading-dots-spinner/loading-dots-spinner.js";export{LoadingSpinner}from"./animations/loading-spinner/loading-spinner.js";export{ThemedLoadingSpinner}from"./animations/themed-loading-spinner/themed-loading-spinner.js";export{Avatar}from"./avatar/avatar.js";export{Badge}from"./badge/badge.js";export{BoxContainer}from"./box-container/box-container.js";export{Breadcrumb}from"./breadcrumb/breadcrumb.js";export{Button}from"./button/button.js";export{Calendar}from"./calendar/calendar.js";export{Card}from"./card/card.js";export{Checkbox}from"./checkbox/checkbox.js";export{CountdownTimer}from"./countdown-timer/countdown-timer.js";export{DashedBorder}from"./dashed-border/dashed-border.js";export{DataTable}from"./data-table/data-table.js";export{DateInput}from"./date-input/date-input.js";export{DateNavigator}from"./date-navigator/date-navigator.js";export{DateRangeInput}from"./date-range-input/date-range-input.js";export{Divider}from"./divider/divider.js";export{Drawer}from"./drawer/drawer.js";export{ESignature}from"./e-signature/e-signature.js";export{ErrorDisplay}from"./error-display/error-display.js";export{ErrorDisplayHelper}from"./error-display/helper.js";export{FeedbackRating}from"./feedback-rating/feedback-rating.js";export{FileDownload}from"./file-download/file-download.js";export{FileUpload}from"./file-upload/file-upload.js";export{Filter}from"./filter/filter.js";export{Footer}from"./footer/footer.js";export{Form}from"./form/index.js";export{Component,FullscreenImageCarousel}from"./fullscreen-image-carousel/fullscreen-image-carousel.js";export{HistogramSlider}from"./histogram-slider/histogram-slider.js";export{ImageButton}from"./image-button/image-button.js";export{Input}from"./input/input.js";export{InputGroup}from"./input-group/input-group.js";export{InputMultiSelect}from"./input-multi-select/input-multi-select.js";export{InputNestedMultiSelect}from"./input-nested-multi-select/input-nested-multi-select.js";export{InputNestedSelect}from"./input-nested-select/input-nested-select.js";export{InputRangeSelect}from"./input-range-select/input-range-select.js";export{InputRangeSlider}from"./input-range-slider/input-range-slider.js";export{InputSelect}from"./input-select/input-select.js";export{InputSlider}from"./input-slider/input-slider.js";export{Textarea}from"./input-textarea/textarea.js";export{LanguageSwitcher}from"./language-switcher/language-switcher.js";export{Layout}from"./layout/index.js";export{LinkList}from"./link-list/link-list.js";export{Markup}from"./markup/markup.js";export{MaskedInput}from"./masked-input/masked-input.js";export{Masthead}from"./masthead/masthead.js";export{Menu,MenuTrigger}from"./menu/menu.js";export{Modal}from"./modal/index.js";export{ModalV2}from"./modal-v2/modal-v2.js";export{Navbar}from"./navbar/navbar.js";export{NBComponent,NotificationBanner}from"./notification-banner/notification-banner.js";export{withNotificationBanner}from"./notification-banner/notification-banner-hoc.js";export{OtpInput}from"./otp-input/otp-input.js";export{Overlay}from"./overlay/overlay.js";export{Pagination}from"./pagination/pagination.js";export{PhoneNumberInput}from"./phone-number-input/phone-number-input.js";export{Pill}from"./pill/pill.js";export{Popover}from"./popover/popover.js";export{PopoverInline}from"./popover/popover-inline/popover-inline.js";export{PopoverTrigger}from"./popover/popover-trigger.js";export{PredictiveTextInput}from"./predictive-text-input/predictive-text-input.js";export{ProgressIndicator}from"./progress-indicator/progress-indicator.js";export{RadioButton}from"./radio-button/radio-button.js";export{SelectHistogram}from"./select-histogram/select-histogram.js";export{Sidenav}from"./sidenav/sidenav.js";export{SingpassButton}from"./singpass-button/singpass-button.js";export{SmartAppBanner}from"./smart-app-banner/smart-app-banner.js";export{Tab}from"./tab/tab.js";export{Table}from"./table/table.js";export{Tag}from"./tag/tag.js";export{TextList}from"./text-list/index.js";export{ThemeProvider}from"./theme/theme-provider/index.js";export{useInheritedThemeScope,useTheme}from"./theme/theme-provider/hooks.js";export{Border,BorderStyle,BorderThickness}from"./theme/tokens/border.js";export{Breakpoint}from"./theme/tokens/breakpoint.js";export{Colour,PrimitiveColours,SemanticColours}from"./theme/tokens/colour.js";export{ComponentToken}from"./theme/tokens/component.js";export{Font,FontSpec}from"./theme/tokens/font.js";export{MediaQuery}from"./theme/tokens/media-query.js";export{Motion}from"./theme/tokens/motion.js";export{Radius}from"./theme/tokens/radius.js";export{Shadow}from"./theme/tokens/shadow.js";export{Spacing}from"./theme/tokens/spacing.js";export{THEME_TYPES}from"./theme/types.js";export{formatUnitValue,parsePxOrRemValue}from"./theme/utils/css-variable.js";export{useApplyStyle}from"./theme/utils/use-apply-styles.js";export{useDesignToken}from"./theme/utils/use-design-token.js";export{useMaxWidthMediaQuery,useMediaQuery,useMinWidthMediaQuery,useResolvedBreakpointToken}from"./theme/utils/use-media-query.js";export{TimeRangePicker}from"./time-range-picker/time-range-picker.js";export{TimeSlotBar}from"./time-slot-bar/time-slot-bar.js";export{TimeSlotBarWeek}from"./time-slot-bar-week/time-slot-bar-week.js";export{TimeSlotWeekView}from"./time-slot-week-view/time-slot-week-view.js";export{Timeline}from"./timeline/timeline.js";export{Timepicker}from"./timepicker/timepicker.js";export{TimeTable}from"./timetable/timetable.js";export{Toast}from"./toast/toast.js";export{Toggle}from"./toggle/toggle.js";export{Typography}from"./typography/index.js";export{UneditableSection}from"./uneditable-section/index.js";export{UnitNumberInput}from"./unit-number/unit-number-input.js";
 //# sourceMappingURL=index.js.map

package/input/input.d.ts

@@ -1,3 +1,9 @@
 import React from "react";
 import type { InputProps } from "./types";
+/**
+ * A single-line text input field.
+ *
+ * Use `Input` for free-form text entry. It supports controlled and uncontrolled
+ * usage.
+ */
 export declare const Input: (props: InputProps & React.RefAttributes<HTMLInputElement>) => React.ReactElement | null;

package/input/input.js.map

@@ -1 +1 @@
-{"version":3,"file":"input.js","sources":["../../src/input/input.tsx"],"sourcesContent":["import { CrossIcon } from \"@lifesg/react-icons/cross\";\nimport clsx from \"clsx\";\nimport React, { useImperativeHandle, useRef } from \"react\";\n\nimport { BasicButton, BasicInput, InputBox } from \"../shared/input-wrapper\";\nimport { StringHelper, useNextInputState } from \"../util\";\nimport * as styles from \"./input.styles\";\nimport type { InputProps, InputRef } from \"./types\";\n\nconst shouldAllowSpacing = (\n    type: string | undefined,\n    spacing: number | undefined\n): spacing is number => {\n    return type === \"tel\" && !!spacing;\n};\n\nconst Component = (\n    {\n        value,\n        spacing,\n        type,\n        error,\n        disabled,\n        readOnly,\n        onChange,\n        onClear,\n        allowClear = false,\n        className,\n        styleType = \"bordered\",\n        ...otherProps\n    }: InputProps,\n    ref: InputRef\n): JSX.Element => {\n    // =============================================================================\n    // CONST, STATE, REF\n    // =============================================================================\n    const allowSpacing = shouldAllowSpacing(type, spacing);\n    const elementRef = useRef<HTMLInputElement>(null);\n    useImperativeHandle(ref, () => elementRef.current!, []);\n\n    const getNextInputState = useNextInputState({\n        ref: elementRef,\n        formatter: (value) => {\n            return allowSpacing\n                ? StringHelper.transformWithSpaces(value, spacing)\n                : value;\n        },\n    });\n\n    // =============================================================================\n    // EVENT HANDLERS\n    // =============================================================================\n    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {\n        if (onChange) {\n            if (allowSpacing) {\n                handleSpacingAndCaretPosition(event);\n            } else {\n                onChange(event);\n            }\n        }\n    };\n\n    const handleClear = () => {\n        if (onClear) onClear();\n\n        if (elementRef && elementRef.current) {\n            elementRef.current.focus();\n        }\n    };\n\n    // =============================================================================\n    // HELPER FUNCTIONS\n    // =============================================================================\n    const convertInputString = (value: string | number | readonly string[]) => {\n        if (!value) return \"\";\n        if (allowSpacing) {\n            return StringHelper.transformWithSpaces(value, spacing);\n        }\n        return value;\n    };\n\n    const handleSpacingAndCaretPosition = (\n        event: React.ChangeEvent<HTMLInputElement>\n    ) => {\n        const nextState = getNextInputState();\n        if (!nextState) return;\n\n        const { nextValue, updateCaretPosition } = nextState;\n\n        // Send to handler unspaced value\n        const valueWithoutSpace = nextValue.replace(/\\s/g, \"\");\n        event.target.value = valueWithoutSpace;\n        onChange?.(event);\n\n        updateCaretPosition();\n    };\n\n    const shouldShowClear = () => {\n        return allowClear && !disabled && !readOnly && !!value;\n    };\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    /**\n     * To clear controlled input value, you have to pass in value as empty string,\n     * then set `updatedValue` to empty string.\n     * `updatedValue` for uncontrolled components remains as undefined such that the\n     * user is free to edit the field. (else the value of the InputElement will\n     * be set to empty string)\n     */\n    const updatedValue = value ? convertInputString(value) : value;\n    const showClear = shouldShowClear();\n\n    const renderInputElement = () => {\n        const inputClassName = clsx(styles.inputElement, {\n            [styles.inputElementDisabled]: disabled,\n            [styles.inputElementPaddingLeft]:\n                styleType !== \"no-border\" && !readOnly,\n            [styles.inputElementPaddingRight]:\n                styleType !== \"no-border\" && !readOnly && !showClear,\n        });\n\n        const clearButtonClassName = clsx(\n            styles.clearButton,\n            styleType === \"no-border\" && styles.clearButtonNoBorder\n        );\n\n        return (\n            <>\n                <BasicInput\n                    data-testid=\"input\"\n                    ref={elementRef}\n                    aria-disabled={disabled}\n                    value={updatedValue}\n                    onChange={handleChange}\n                    type={type}\n                    readOnly={readOnly || disabled}\n                    className={inputClassName}\n                    {...otherProps}\n                />\n                {showClear && (\n                    <BasicButton\n                        onClick={handleClear}\n                        type=\"button\"\n                        aria-label=\"Clear input\"\n                        className={clearButtonClassName}\n                    >\n                        <CrossIcon className={styles.clearIcon} aria-hidden />\n                    </BasicButton>\n                )}\n            </>\n        );\n    };\n\n    return (\n        <>\n            {styleType === \"no-border\" ? (\n                <div className={clsx(styles.noBorderWrapper, className)}>\n                    {renderInputElement()}\n                </div>\n            ) : (\n                <InputBox\n                    className={clsx(styles.defaultWrapper, className, {\n                        [styles.defaultWrapperDisabled]: disabled,\n                        [styles.defaultWrapperError]: error,\n                        [styles.defaultWrapperReadOnly]: readOnly,\n                    })}\n                    disabled={disabled}\n                    error={error}\n                    readOnly={readOnly}\n                >\n                    {renderInputElement()}\n                </InputBox>\n            )}\n        </>\n    );\n};\n\nexport const Input = React.forwardRef(Component);\n"],"names":["Input","React","forwardRef","_a","ref","value","spacing","type","error","disabled","readOnly","onChange","onClear","allowClear","className","styleType","otherProps","__rest","allowSpacing","shouldAllowSpacing","elementRef","useRef","useImperativeHandle","current","getNextInputState","useNextInputState","formatter","StringHelper","transformWithSpaces","handleChange","event","handleSpacingAndCaretPosition","handleClear","focus","nextState","nextValue","updateCaretPosition","valueWithoutSpace","replace","target","updatedValue","convertInputString","showClear","renderInputElement","inputClassName","clsx","styles.inputElement","inputElementDisabled","styles.inputElementDisabled","inputElementPaddingLeft","styles.inputElementPaddingLeft","inputElementPaddingRight","styles.inputElementPaddingRight","clearButtonClassName","styles.clearButton","styles.clearButtonNoBorder","_jsxs","_Fragment","children","_jsx","BasicInput","BasicButton","onClick","CrossIcon","styles.clearIcon","styles.noBorderWrapper","InputBox","styles.defaultWrapper","defaultWrapperDisabled","styles.defaultWrapperDisabled","defaultWrapperError","styles.defaultWrapperError","defaultWrapperReadOnly","styles.defaultWrapperReadOnly"],"mappings":"k6BASA,MA0KaA,EAAQC,EAAMC,YAnKT,CACdC,EAcAC,KAdA,IAAAC,MACIA,EAAKC,QACLA,EAAOC,KACPA,EAAIC,MACJA,EAAKC,SACLA,EAAQC,SACRA,EAAQC,SACRA,EAAQC,QACRA,EAAOC,WACPA,GAAa,EAAKC,UAClBA,EAASC,UACTA,EAAY,YAAUZ,EACnBa,EAAUC,EAAAd,EAZjB,oHAmBA,MAAMe,EA3BiB,EACvBX,EACAD,IAEgB,QAATC,KAAoBD,EAuBNa,CAAmBZ,EAAMD,GACxCc,EAAaC,EAAyB,MAC5CC,EAAoBlB,GAAK,IAAMgB,EAAWG,SAAU,IAEpD,MAAMC,EAAoBC,EAAkB,CACxCrB,IAAKgB,EACLM,UAAYrB,GACDa,EACDS,EAAaC,oBAAoBvB,EAAOC,GACxCD,IAORwB,EAAgBC,IACdnB,IACIO,EACAa,EAA8BD,GAE9BnB,EAASmB,GAEjB,EAGEE,EAAc,KACZpB,GAASA,IAETQ,GAAcA,EAAWG,SACzBH,EAAWG,QAAQU,OACvB,EAcEF,EACFD,IAEA,MAAMI,EAAYV,IAClB,IAAKU,EAAW,OAEhB,MAAMC,UAAEA,EAASC,oBAAEA,GAAwBF,EAGrCG,EAAoBF,EAAUG,QAAQ,MAAO,IACnDR,EAAMS,OAAOlC,MAAQgC,EACrB1B,SAAAA,EAAWmB,GAEXM,GAAqB,EAiBnBI,EAAenC,EAtCM,CAACA,GACnBA,EACDa,EACOS,EAAaC,oBAAoBvB,EAAOC,GAE5CD,EAJY,GAqCMoC,CAAmBpC,GAASA,EACnDqC,EAdK7B,IAAeJ,IAAaC,KAAcL,EAgB/CsC,EAAqB,KACvB,MAAMC,EAAiBC,EAAKC,EAAqB,CAC7CC,CAACC,GAA8BvC,EAC/BwC,CAACC,GACiB,cAAdnC,IAA8BL,EAClCyC,CAACC,GACiB,cAAdrC,IAA8BL,IAAagC,IAG7CW,EAAuBR,EACzBS,EACc,cAAdvC,GAA6BwC,GAGjC,OACIC,EAAAC,EAAA,CAAAC,SAAA,CACIC,EAACC,+BACe,QACZxD,IAAKgB,EAAU,gBACAX,EACfJ,MAAOmC,EACP7B,SAAUkB,EACVtB,KAAMA,EACNG,SAAUA,GAAYD,EACtBK,UAAW8B,GACP5B,IAEP0B,GACGiB,EAACE,EAAW,CACRC,QAAS9B,EACTzB,KAAK,sBACM,cACXO,UAAWuC,EAAoBK,SAE/BC,EAACI,GAAUjD,UAAWkD,EAAgB,eAAA,QAG/C,EAIX,OACIL,EAAAF,EAAA,CAAAC,SACmB,cAAd3C,EACG4C,EAAA,MAAA,CAAK7C,UAAW+B,EAAKoB,EAAwBnD,GAAU4C,SAClDf,MAGLgB,EAACO,GACGpD,UAAW+B,EAAKsB,EAAuBrD,EAAW,CAC9CsD,CAACC,GAAgC5D,EACjC6D,CAACC,GAA6B/D,EAC9BgE,CAACC,GAAgC/D,IAErCD,SAAUA,EACVD,MAAOA,EACPE,SAAUA,WAETiC,OAGV"}
+{"version":3,"file":"input.js","sources":["../../src/input/input.tsx"],"sourcesContent":["import { CrossIcon } from \"@lifesg/react-icons/cross\";\nimport clsx from \"clsx\";\nimport React, { useImperativeHandle, useRef } from \"react\";\n\nimport { BasicButton, BasicInput, InputBox } from \"../shared/input-wrapper\";\nimport { StringHelper, useNextInputState } from \"../util\";\nimport * as styles from \"./input.styles\";\nimport type { InputProps, InputRef } from \"./types\";\n\nconst shouldAllowSpacing = (\n    type: string | undefined,\n    spacing: number | undefined\n): spacing is number => {\n    return type === \"tel\" && !!spacing;\n};\n\nconst Component = (\n    {\n        value,\n        spacing,\n        type,\n        error,\n        disabled,\n        readOnly,\n        onChange,\n        onClear,\n        allowClear = false,\n        className,\n        styleType = \"bordered\",\n        ...otherProps\n    }: InputProps,\n    ref: InputRef\n): JSX.Element => {\n    // =============================================================================\n    // CONST, STATE, REF\n    // =============================================================================\n    const allowSpacing = shouldAllowSpacing(type, spacing);\n    const elementRef = useRef<HTMLInputElement>(null);\n    useImperativeHandle(ref, () => elementRef.current!, []);\n\n    const getNextInputState = useNextInputState({\n        ref: elementRef,\n        formatter: (value) => {\n            return allowSpacing\n                ? StringHelper.transformWithSpaces(value, spacing)\n                : value;\n        },\n    });\n\n    // =============================================================================\n    // EVENT HANDLERS\n    // =============================================================================\n    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {\n        if (onChange) {\n            if (allowSpacing) {\n                handleSpacingAndCaretPosition(event);\n            } else {\n                onChange(event);\n            }\n        }\n    };\n\n    const handleClear = () => {\n        if (onClear) onClear();\n\n        if (elementRef && elementRef.current) {\n            elementRef.current.focus();\n        }\n    };\n\n    // =============================================================================\n    // HELPER FUNCTIONS\n    // =============================================================================\n    const convertInputString = (value: string | number | readonly string[]) => {\n        if (!value) return \"\";\n        if (allowSpacing) {\n            return StringHelper.transformWithSpaces(value, spacing);\n        }\n        return value;\n    };\n\n    const handleSpacingAndCaretPosition = (\n        event: React.ChangeEvent<HTMLInputElement>\n    ) => {\n        const nextState = getNextInputState();\n        if (!nextState) return;\n\n        const { nextValue, updateCaretPosition } = nextState;\n\n        // Send to handler unspaced value\n        const valueWithoutSpace = nextValue.replace(/\\s/g, \"\");\n        event.target.value = valueWithoutSpace;\n        onChange?.(event);\n\n        updateCaretPosition();\n    };\n\n    const shouldShowClear = () => {\n        return allowClear && !disabled && !readOnly && !!value;\n    };\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    /**\n     * To clear controlled input value, you have to pass in value as empty string,\n     * then set `updatedValue` to empty string.\n     * `updatedValue` for uncontrolled components remains as undefined such that the\n     * user is free to edit the field. (else the value of the InputElement will\n     * be set to empty string)\n     */\n    const updatedValue = value ? convertInputString(value) : value;\n    const showClear = shouldShowClear();\n\n    const renderInputElement = () => {\n        const inputClassName = clsx(styles.inputElement, {\n            [styles.inputElementDisabled]: disabled,\n            [styles.inputElementPaddingLeft]:\n                styleType !== \"no-border\" && !readOnly,\n            [styles.inputElementPaddingRight]:\n                styleType !== \"no-border\" && !readOnly && !showClear,\n        });\n\n        const clearButtonClassName = clsx(\n            styles.clearButton,\n            styleType === \"no-border\" && styles.clearButtonNoBorder\n        );\n\n        return (\n            <>\n                <BasicInput\n                    data-testid=\"input\"\n                    ref={elementRef}\n                    aria-disabled={disabled}\n                    value={updatedValue}\n                    onChange={handleChange}\n                    type={type}\n                    readOnly={readOnly || disabled}\n                    className={inputClassName}\n                    {...otherProps}\n                />\n                {showClear && (\n                    <BasicButton\n                        onClick={handleClear}\n                        type=\"button\"\n                        aria-label=\"Clear input\"\n                        className={clearButtonClassName}\n                    >\n                        <CrossIcon className={styles.clearIcon} aria-hidden />\n                    </BasicButton>\n                )}\n            </>\n        );\n    };\n\n    return (\n        <>\n            {styleType === \"no-border\" ? (\n                <div className={clsx(styles.noBorderWrapper, className)}>\n                    {renderInputElement()}\n                </div>\n            ) : (\n                <InputBox\n                    className={clsx(styles.defaultWrapper, className, {\n                        [styles.defaultWrapperDisabled]: disabled,\n                        [styles.defaultWrapperError]: error,\n                        [styles.defaultWrapperReadOnly]: readOnly,\n                    })}\n                    disabled={disabled}\n                    error={error}\n                    readOnly={readOnly}\n                >\n                    {renderInputElement()}\n                </InputBox>\n            )}\n        </>\n    );\n};\n\n// @catalog\n/**\n * A single-line text input field.\n *\n * Use `Input` for free-form text entry. It supports controlled and uncontrolled\n * usage.\n */\nexport const Input = React.forwardRef(Component);\n"],"names":["Input","React","forwardRef","_a","ref","value","spacing","type","error","disabled","readOnly","onChange","onClear","allowClear","className","styleType","otherProps","__rest","allowSpacing","shouldAllowSpacing","elementRef","useRef","useImperativeHandle","current","getNextInputState","useNextInputState","formatter","StringHelper","transformWithSpaces","handleChange","event","handleSpacingAndCaretPosition","handleClear","focus","nextState","nextValue","updateCaretPosition","valueWithoutSpace","replace","target","updatedValue","convertInputString","showClear","renderInputElement","inputClassName","clsx","styles.inputElement","inputElementDisabled","styles.inputElementDisabled","inputElementPaddingLeft","styles.inputElementPaddingLeft","inputElementPaddingRight","styles.inputElementPaddingRight","clearButtonClassName","styles.clearButton","styles.clearButtonNoBorder","_jsxs","_Fragment","children","_jsx","BasicInput","BasicButton","onClick","CrossIcon","styles.clearIcon","styles.noBorderWrapper","InputBox","styles.defaultWrapper","defaultWrapperDisabled","styles.defaultWrapperDisabled","defaultWrapperError","styles.defaultWrapperError","defaultWrapperReadOnly","styles.defaultWrapperReadOnly"],"mappings":"k6BASA,MAiLaA,EAAQC,EAAMC,YA1KT,CACdC,EAcAC,KAdA,IAAAC,MACIA,EAAKC,QACLA,EAAOC,KACPA,EAAIC,MACJA,EAAKC,SACLA,EAAQC,SACRA,EAAQC,SACRA,EAAQC,QACRA,EAAOC,WACPA,GAAa,EAAKC,UAClBA,EAASC,UACTA,EAAY,YAAUZ,EACnBa,EAAUC,EAAAd,EAZjB,oHAmBA,MAAMe,EA3BiB,EACvBX,EACAD,IAEgB,QAATC,KAAoBD,EAuBNa,CAAmBZ,EAAMD,GACxCc,EAAaC,EAAyB,MAC5CC,EAAoBlB,GAAK,IAAMgB,EAAWG,SAAU,IAEpD,MAAMC,EAAoBC,EAAkB,CACxCrB,IAAKgB,EACLM,UAAYrB,GACDa,EACDS,EAAaC,oBAAoBvB,EAAOC,GACxCD,IAORwB,EAAgBC,IACdnB,IACIO,EACAa,EAA8BD,GAE9BnB,EAASmB,GAEjB,EAGEE,EAAc,KACZpB,GAASA,IAETQ,GAAcA,EAAWG,SACzBH,EAAWG,QAAQU,OACvB,EAcEF,EACFD,IAEA,MAAMI,EAAYV,IAClB,IAAKU,EAAW,OAEhB,MAAMC,UAAEA,EAASC,oBAAEA,GAAwBF,EAGrCG,EAAoBF,EAAUG,QAAQ,MAAO,IACnDR,EAAMS,OAAOlC,MAAQgC,EACrB1B,SAAAA,EAAWmB,GAEXM,GAAqB,EAiBnBI,EAAenC,EAtCM,CAACA,GACnBA,EACDa,EACOS,EAAaC,oBAAoBvB,EAAOC,GAE5CD,EAJY,GAqCMoC,CAAmBpC,GAASA,EACnDqC,EAdK7B,IAAeJ,IAAaC,KAAcL,EAgB/CsC,EAAqB,KACvB,MAAMC,EAAiBC,EAAKC,EAAqB,CAC7CC,CAACC,GAA8BvC,EAC/BwC,CAACC,GACiB,cAAdnC,IAA8BL,EAClCyC,CAACC,GACiB,cAAdrC,IAA8BL,IAAagC,IAG7CW,EAAuBR,EACzBS,EACc,cAAdvC,GAA6BwC,GAGjC,OACIC,EAAAC,EAAA,CAAAC,SAAA,CACIC,EAACC,+BACe,QACZxD,IAAKgB,EAAU,gBACAX,EACfJ,MAAOmC,EACP7B,SAAUkB,EACVtB,KAAMA,EACNG,SAAUA,GAAYD,EACtBK,UAAW8B,GACP5B,IAEP0B,GACGiB,EAACE,EAAW,CACRC,QAAS9B,EACTzB,KAAK,sBACM,cACXO,UAAWuC,EAAoBK,SAE/BC,EAACI,GAAUjD,UAAWkD,EAAgB,eAAA,QAG/C,EAIX,OACIL,EAAAF,EAAA,CAAAC,SACmB,cAAd3C,EACG4C,EAAA,MAAA,CAAK7C,UAAW+B,EAAKoB,EAAwBnD,GAAU4C,SAClDf,MAGLgB,EAACO,GACGpD,UAAW+B,EAAKsB,EAAuBrD,EAAW,CAC9CsD,CAACC,GAAgC5D,EACjC6D,CAACC,GAA6B/D,EAC9BgE,CAACC,GAAgC/D,IAErCD,SAAUA,EACVD,MAAOA,EACPE,SAAUA,WAETiC,OAGV"}

package/input/types.d.ts

@@ -1,14 +1,50 @@
 import type React from "react";
+/**
+ * Visual style variant for the `Input` component.
+ *
+ * - `"bordered"` wraps the input in a styled border container.
+ * - `"no-border"` omits the border wrapper.
+ */
 export type InputStyleType = "no-border" | "bordered";
+/**
+ * Props for the `Input` component.
+ */
 export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
-    /** Sets the number of characters before a space is added (works only with type `tel` input) */
+    /**
+     * Inserts a space after every `spacing` characters in the displayed value.
+     * Only applies when `type` is `"tel"`.
+     */
     spacing?: number | undefined;
+    /**
+     * Marks the input wrapper in an error state.
+     */
     error?: boolean | undefined;
+    /**
+     * Shows a clear button when the field has a value and is neither disabled
+     * nor read-only.
+     *
+     * @default false
+     */
     allowClear?: boolean | undefined;
+    /**
+     * Called when the user activates the clear button. Use this to clear the
+     * controlled value.
+     */
     onClear?: () => void | undefined;
     "data-testid"?: string | undefined;
+    /**
+     * Visual style variant.
+     *
+     * @default "bordered"
+     */
     styleType?: InputStyleType | undefined;
 }
-/** To be exposed for Form component inheritance */
+/**
+ * A subset of `InputProps` for use by form components that manage the `error`
+ * state themselves.
+ */
 export type InputPartialProps = Omit<InputProps, "error">;
+/**
+ * Ref type for programmatic access to the underlying `HTMLInputElement`.
+ */
 export type InputRef = React.Ref<HTMLInputElement>;

package/input-group/input-group.d.ts

@@ -1,3 +1,10 @@
 import React from "react";
 import type { InputGroupProps } from "./types";
+/**
+ * A single-line text input optionally paired with a static label, a custom element, or a
+ * dropdown list selector.
+ *
+ * Use `InputGroup` when the input needs contextual decoration such as a unit label,
+ * a country-code dropdown, or a fully custom slot.
+ */
 export declare const InputGroup: <T, V>(props: InputGroupProps<T, V> & React.RefAttributes<HTMLInputElement>) => React.ReactElement | null;

package/input-group/input-group.js.map

@@ -1 +1 @@
-{"version":3,"file":"input-group.js","sources":["../../src/input-group/input-group.tsx"],"sourcesContent":["import clsx from \"clsx\";\nimport React from \"react\";\n\nimport { Input } from \"../input\";\nimport { concatIds, VisuallyHidden } from \"../shared/accessibility\";\nimport { InputBox } from \"../shared/input-wrapper\";\nimport { useId } from \"../util\";\nimport * as styles from \"./input-group.styles\";\nimport { InputGroupListAddon } from \"./input-group-list-addon\";\nimport type {\n    CustomAddon,\n    InputGroupProps,\n    LabelAddon,\n    ListAddon,\n} from \"./types\";\n\nconst Component = <T, V>(\n    {\n        addon,\n        error,\n        className,\n        noBorder,\n        \"aria-label\": ariaLabel,\n        \"aria-labelledby\": ariaLabelledBy,\n        ...otherProps\n    }: InputGroupProps<T, V>,\n    ref: React.Ref<HTMLInputElement>\n) => {\n    // =============================================================================\n    // CONST, STATE, REF\n    // =============================================================================\n    const internalId = useId();\n    const addonId = `${internalId}-addon`;\n    const ariaLabelId = `${internalId}-ariaLabelId`;\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    const renderNoAddons = () => (\n        <InputBox\n            disabled={otherProps.disabled}\n            error={error}\n            readOnly={otherProps.readOnly}\n            noBorder={noBorder}\n            data-testid={otherProps[\"data-testid\"]}\n            className={clsx(styles.noAddonWrapper, className)}\n            data-read-only={otherProps.readOnly}\n            data-no-border={noBorder}\n        >\n            <VisuallyHidden aria-hidden id={ariaLabelId}>\n                {ariaLabel}\n            </VisuallyHidden>\n            <Input\n                ref={ref}\n                {...otherProps}\n                data-testid=\"input\"\n                styleType=\"no-border\"\n                aria-labelledby={concatIds(ariaLabelId, ariaLabelledBy)}\n            />\n        </InputBox>\n    );\n\n    const renderWithAddon = (\n        addonContent: React.ReactNode,\n        position: \"left\" | \"right\",\n        allowClear?: boolean\n    ) => (\n        <InputBox\n            disabled={otherProps.disabled}\n            error={error}\n            readOnly={otherProps.readOnly}\n            noBorder={noBorder}\n            data-testid={otherProps[\"data-testid\"]}\n            className={clsx(styles.addonWrapper, className)}\n            data-read-only={otherProps.readOnly}\n            data-no-border={noBorder}\n            data-position={position}\n        >\n            <div\n                data-testid=\"addon\"\n                id={addonId}\n                className={styles.labelAddonContainer}\n                data-disabled={otherProps.disabled}\n                data-read-only={otherProps.readOnly}\n                data-position={position}\n            >\n                {addonContent}\n            </div>\n            <VisuallyHidden aria-hidden id={ariaLabelId}>\n                {ariaLabel}\n            </VisuallyHidden>\n            <Input\n                ref={ref}\n                {...otherProps}\n                aria-labelledby={concatIds(\n                    ariaLabelId,\n                    ariaLabelledBy,\n                    addonId\n                )}\n                allowClear={allowClear && position !== \"right\"}\n                error={error}\n                data-testid=\"input\"\n                styleType=\"no-border\"\n            />\n        </InputBox>\n    );\n\n    if (addon) {\n        const { type = \"label\", position = \"left\" } = addon;\n        const { allowClear } = otherProps;\n\n        switch (type) {\n            case \"list\": {\n                const listAddon = addon.attributes as ListAddon<T, V>;\n                if (listAddon.options && listAddon.options.length > 0) {\n                    return (\n                        <InputGroupListAddon\n                            ref={ref}\n                            addon={addon}\n                            error={error}\n                            className={className}\n                            noBorder={noBorder}\n                            aria-label={ariaLabel}\n                            aria-labelledby={ariaLabelledBy}\n                            {...otherProps}\n                        />\n                    );\n                } else {\n                    return renderNoAddons();\n                }\n            }\n\n            case \"custom\": {\n                const customAddon = addon.attributes as CustomAddon;\n                if (customAddon.children) {\n                    return renderWithAddon(\n                        customAddon.children,\n                        position,\n                        allowClear\n                    );\n                } else {\n                    return renderNoAddons();\n                }\n            }\n            default: {\n                const labelAddon = addon.attributes as LabelAddon;\n                if (labelAddon.value) {\n                    return renderWithAddon(\n                        labelAddon.value,\n                        position,\n                        allowClear\n                    );\n                } else {\n                    return renderNoAddons();\n                }\n            }\n        }\n    } else {\n        return renderNoAddons();\n    }\n};\n\nexport const InputGroup = React.forwardRef(Component);\n"],"names":["InputGroup","React","forwardRef","_a","ref","addon","error","className","noBorder","ariaLabel","ariaLabelledBy","otherProps","__rest","internalId","useId","addonId","ariaLabelId","renderNoAddons","_jsxs","InputBox","disabled","readOnly","clsx","styles.noAddonWrapper","_jsx","VisuallyHidden","id","children","Input","Object","assign","styleType","concatIds","renderWithAddon","addonContent","position","allowClear","styles.addonWrapper","styles.labelAddonContainer","type","listAddon","attributes","options","length","InputGroupListAddon","customAddon","labelAddon","value"],"mappings":"orBAgBA,MAkJaA,EAAaC,EAAMC,YAlJd,CACdC,EASAC,SATAC,MACIA,EAAKC,MACLA,EAAKC,UACLA,EAASC,SACTA,EACA,aAAcC,EACd,kBAAmBC,GAAcP,EAC9BQ,EAAUC,EAAAT,EAPjB,yEAcA,MAAMU,EAAaC,IACbC,EAAU,GAAGF,UACbG,EAAc,GAAGH,gBAKjBI,EAAiB,IACnBC,EAACC,EAAQ,CACLC,SAAUT,EAAWS,SACrBd,MAAOA,EACPe,SAAUV,EAAWU,SACrBb,SAAUA,gBACGG,EAAW,eACxBJ,UAAWe,EAAKC,EAAuBhB,oBACvBI,EAAWU,SAAQ,iBACnBb,YAEhBgB,EAACC,EAAc,CAAA,eAAA,EAAaC,GAAIV,EAAWW,SACtClB,IAELe,EAACI,EAAKC,OAAAC,OAAA,CACF1B,IAAKA,GACDO,iBACQ,QACZoB,UAAU,8BACOC,EAAUhB,EAAaN,SAK9CuB,EAAkB,CACpBC,EACAC,EACAC,IAEAlB,EAACC,EAAQ,CACLC,SAAUT,EAAWS,SACrBd,MAAOA,EACPe,SAAUV,EAAWU,SACrBb,SAAUA,EAAQ,cACLG,EAAW,eACxBJ,UAAWe,EAAKe,EAAqB9B,GAAU,iBAC/BI,EAAWU,SAAQ,iBACnBb,EAAQ,gBACT2B,EAAQR,SAAA,CAEvBH,EAAA,MAAA,CAAA,cACgB,QACZE,GAAIX,EACJR,UAAW+B,EAA0B,gBACtB3B,EAAWS,SAAQ,iBAClBT,EAAWU,SAAQ,gBACpBc,EAAQR,SAEtBO,IAELV,EAACC,EAAc,CAAA,eAAA,EAAaC,GAAIV,EAAWW,SACtClB,IAELe,EAACI,iBACGxB,IAAKA,GACDO,EAAU,CAAA,kBACGqB,EACbhB,EACAN,EACAK,GAEJqB,WAAYA,GAA2B,UAAbD,EAC1B7B,MAAOA,EAAK,cACA,QACZyB,UAAU,kBAKtB,IAAI1B,EAmDA,OAAOY,IAnDA,CACP,MAAMsB,KAAEA,EAAO,QAAOJ,SAAEA,EAAW,QAAW9B,GACxC+B,WAAEA,GAAezB,EAEvB,OAAQ4B,GACJ,IAAK,OAAQ,CACT,MAAMC,EAAYnC,EAAMoC,WACxB,OAAID,EAAUE,SAAWF,EAAUE,QAAQC,OAAS,EAE5CnB,EAACoB,EAAmBf,OAAAC,OAAA,CAChB1B,IAAKA,EACLC,MAAOA,EACPC,MAAOA,EACPC,UAAWA,EACXC,SAAUA,EAAQ,aACNC,EAAS,kBACJC,GACbC,IAILM,GAEf,CAEA,IAAK,SAAU,CACX,MAAM4B,EAAcxC,EAAMoC,WAC1B,OAAII,EAAYlB,SACLM,EACHY,EAAYlB,SACZQ,EACAC,GAGGnB,GAEf,CACA,QAAS,CACL,MAAM6B,EAAazC,EAAMoC,WACzB,OAAIK,EAAWC,MACJd,EACHa,EAAWC,MACXZ,EACAC,GAGGnB,GAEf,EAER,CAEA"}
+{"version":3,"file":"input-group.js","sources":["../../src/input-group/input-group.tsx"],"sourcesContent":["import clsx from \"clsx\";\nimport React from \"react\";\n\nimport { Input } from \"../input\";\nimport { concatIds, VisuallyHidden } from \"../shared/accessibility\";\nimport { InputBox } from \"../shared/input-wrapper\";\nimport { useId } from \"../util\";\nimport * as styles from \"./input-group.styles\";\nimport { InputGroupListAddon } from \"./input-group-list-addon\";\nimport type {\n    CustomAddon,\n    InputGroupProps,\n    LabelAddon,\n    ListAddon,\n} from \"./types\";\n\nconst Component = <T, V>(\n    {\n        addon,\n        error,\n        className,\n        noBorder,\n        \"aria-label\": ariaLabel,\n        \"aria-labelledby\": ariaLabelledBy,\n        ...otherProps\n    }: InputGroupProps<T, V>,\n    ref: React.Ref<HTMLInputElement>\n) => {\n    // =============================================================================\n    // CONST, STATE, REF\n    // =============================================================================\n    const internalId = useId();\n    const addonId = `${internalId}-addon`;\n    const ariaLabelId = `${internalId}-ariaLabelId`;\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    const renderNoAddons = () => (\n        <InputBox\n            disabled={otherProps.disabled}\n            error={error}\n            readOnly={otherProps.readOnly}\n            noBorder={noBorder}\n            data-testid={otherProps[\"data-testid\"]}\n            className={clsx(styles.noAddonWrapper, className)}\n            data-read-only={otherProps.readOnly}\n            data-no-border={noBorder}\n        >\n            <VisuallyHidden aria-hidden id={ariaLabelId}>\n                {ariaLabel}\n            </VisuallyHidden>\n            <Input\n                ref={ref}\n                {...otherProps}\n                data-testid=\"input\"\n                styleType=\"no-border\"\n                aria-labelledby={concatIds(ariaLabelId, ariaLabelledBy)}\n            />\n        </InputBox>\n    );\n\n    const renderWithAddon = (\n        addonContent: React.ReactNode,\n        position: \"left\" | \"right\",\n        allowClear?: boolean\n    ) => (\n        <InputBox\n            disabled={otherProps.disabled}\n            error={error}\n            readOnly={otherProps.readOnly}\n            noBorder={noBorder}\n            data-testid={otherProps[\"data-testid\"]}\n            className={clsx(styles.addonWrapper, className)}\n            data-read-only={otherProps.readOnly}\n            data-no-border={noBorder}\n            data-position={position}\n        >\n            <div\n                data-testid=\"addon\"\n                id={addonId}\n                className={styles.labelAddonContainer}\n                data-disabled={otherProps.disabled}\n                data-read-only={otherProps.readOnly}\n                data-position={position}\n            >\n                {addonContent}\n            </div>\n            <VisuallyHidden aria-hidden id={ariaLabelId}>\n                {ariaLabel}\n            </VisuallyHidden>\n            <Input\n                ref={ref}\n                {...otherProps}\n                aria-labelledby={concatIds(\n                    ariaLabelId,\n                    ariaLabelledBy,\n                    addonId\n                )}\n                allowClear={allowClear && position !== \"right\"}\n                error={error}\n                data-testid=\"input\"\n                styleType=\"no-border\"\n            />\n        </InputBox>\n    );\n\n    if (addon) {\n        const { type = \"label\", position = \"left\" } = addon;\n        const { allowClear } = otherProps;\n\n        switch (type) {\n            case \"list\": {\n                const listAddon = addon.attributes as ListAddon<T, V>;\n                if (listAddon.options && listAddon.options.length > 0) {\n                    return (\n                        <InputGroupListAddon\n                            ref={ref}\n                            addon={addon}\n                            error={error}\n                            className={className}\n                            noBorder={noBorder}\n                            aria-label={ariaLabel}\n                            aria-labelledby={ariaLabelledBy}\n                            {...otherProps}\n                        />\n                    );\n                } else {\n                    return renderNoAddons();\n                }\n            }\n\n            case \"custom\": {\n                const customAddon = addon.attributes as CustomAddon;\n                if (customAddon.children) {\n                    return renderWithAddon(\n                        customAddon.children,\n                        position,\n                        allowClear\n                    );\n                } else {\n                    return renderNoAddons();\n                }\n            }\n            default: {\n                const labelAddon = addon.attributes as LabelAddon;\n                if (labelAddon.value) {\n                    return renderWithAddon(\n                        labelAddon.value,\n                        position,\n                        allowClear\n                    );\n                } else {\n                    return renderNoAddons();\n                }\n            }\n        }\n    } else {\n        return renderNoAddons();\n    }\n};\n\n// @catalog\n/**\n * A single-line text input optionally paired with a static label, a custom element, or a\n * dropdown list selector.\n *\n * Use `InputGroup` when the input needs contextual decoration such as a unit label,\n * a country-code dropdown, or a fully custom slot.\n */\nexport const InputGroup = React.forwardRef(Component);\n"],"names":["InputGroup","React","forwardRef","_a","ref","addon","error","className","noBorder","ariaLabel","ariaLabelledBy","otherProps","__rest","internalId","useId","addonId","ariaLabelId","renderNoAddons","_jsxs","InputBox","disabled","readOnly","clsx","styles.noAddonWrapper","_jsx","VisuallyHidden","id","children","Input","Object","assign","styleType","concatIds","renderWithAddon","addonContent","position","allowClear","styles.addonWrapper","styles.labelAddonContainer","type","listAddon","attributes","options","length","InputGroupListAddon","customAddon","labelAddon","value"],"mappings":"orBAgBA,MA0JaA,EAAaC,EAAMC,YA1Jd,CACdC,EASAC,SATAC,MACIA,EAAKC,MACLA,EAAKC,UACLA,EAASC,SACTA,EACA,aAAcC,EACd,kBAAmBC,GAAcP,EAC9BQ,EAAUC,EAAAT,EAPjB,yEAcA,MAAMU,EAAaC,IACbC,EAAU,GAAGF,UACbG,EAAc,GAAGH,gBAKjBI,EAAiB,IACnBC,EAACC,EAAQ,CACLC,SAAUT,EAAWS,SACrBd,MAAOA,EACPe,SAAUV,EAAWU,SACrBb,SAAUA,gBACGG,EAAW,eACxBJ,UAAWe,EAAKC,EAAuBhB,oBACvBI,EAAWU,SAAQ,iBACnBb,YAEhBgB,EAACC,EAAc,CAAA,eAAA,EAAaC,GAAIV,EAAWW,SACtClB,IAELe,EAACI,EAAKC,OAAAC,OAAA,CACF1B,IAAKA,GACDO,iBACQ,QACZoB,UAAU,8BACOC,EAAUhB,EAAaN,SAK9CuB,EAAkB,CACpBC,EACAC,EACAC,IAEAlB,EAACC,EAAQ,CACLC,SAAUT,EAAWS,SACrBd,MAAOA,EACPe,SAAUV,EAAWU,SACrBb,SAAUA,EAAQ,cACLG,EAAW,eACxBJ,UAAWe,EAAKe,EAAqB9B,GAAU,iBAC/BI,EAAWU,SAAQ,iBACnBb,EAAQ,gBACT2B,EAAQR,SAAA,CAEvBH,EAAA,MAAA,CAAA,cACgB,QACZE,GAAIX,EACJR,UAAW+B,EAA0B,gBACtB3B,EAAWS,SAAQ,iBAClBT,EAAWU,SAAQ,gBACpBc,EAAQR,SAEtBO,IAELV,EAACC,EAAc,CAAA,eAAA,EAAaC,GAAIV,EAAWW,SACtClB,IAELe,EAACI,iBACGxB,IAAKA,GACDO,EAAU,CAAA,kBACGqB,EACbhB,EACAN,EACAK,GAEJqB,WAAYA,GAA2B,UAAbD,EAC1B7B,MAAOA,EAAK,cACA,QACZyB,UAAU,kBAKtB,IAAI1B,EAmDA,OAAOY,IAnDA,CACP,MAAMsB,KAAEA,EAAO,QAAOJ,SAAEA,EAAW,QAAW9B,GACxC+B,WAAEA,GAAezB,EAEvB,OAAQ4B,GACJ,IAAK,OAAQ,CACT,MAAMC,EAAYnC,EAAMoC,WACxB,OAAID,EAAUE,SAAWF,EAAUE,QAAQC,OAAS,EAE5CnB,EAACoB,EAAmBf,OAAAC,OAAA,CAChB1B,IAAKA,EACLC,MAAOA,EACPC,MAAOA,EACPC,UAAWA,EACXC,SAAUA,EAAQ,aACNC,EAAS,kBACJC,GACbC,IAILM,GAEf,CAEA,IAAK,SAAU,CACX,MAAM4B,EAAcxC,EAAMoC,WAC1B,OAAII,EAAYlB,SACLM,EACHY,EAAYlB,SACZQ,EACAC,GAGGnB,GAEf,CACA,QAAS,CACL,MAAM6B,EAAazC,EAAMoC,WACzB,OAAIK,EAAWC,MACJd,EACHa,EAAWC,MACXZ,EACAC,GAGGnB,GAEf,EAER,CAEA"}

package/input-group/types.d.ts

@@ -1,50 +1,126 @@
 import type { RefObject } from "react";
 import type { InputProps } from "../input/types";
 import type { DropdownDisplayProps, DropdownSearchProps, ItemsLoadStateType, TruncateType } from "../shared/dropdown-list";
+/** Determines which kind of addon is rendered alongside the input. */
 export type InputGroupAddonType = "label" | "list" | "custom";
+/**
+ * Placement of the addon relative to the input field.
+ */
 export type InputGroupAddonPosition = "left" | "right" | undefined;
+/** Attributes for a custom addon that renders arbitrary JSX alongside the input. */
 export interface CustomAddon {
+    /**
+     * The JSX element rendered inside the addon slot.
+     * If omitted the addon is not displayed.
+     */
     children?: JSX.Element | undefined;
 }
+/** Attributes for a static text label rendered alongside the input. */
 export interface LabelAddon {
+    /**
+     * Text displayed in the addon slot.
+     * If omitted the addon is not displayed.
+     */
     value?: string | undefined;
 }
+/**
+ * Attributes for a dropdown list addon that pairs a combobox selector with the text input.
+ */
 export interface ListAddon<T, V> extends DropdownDisplayProps<T, V>, DropdownSearchProps<T> {
+    /**
+     * Placeholder text shown in the dropdown trigger when no option is selected.
+     *
+     * @default "Select"
+     */
     placeholder?: string | undefined;
+    /**
+     * Derives the display string shown in the dropdown trigger from the selected item.
+     */
     displayValueExtractor?: ((item: T) => string) | undefined;
     "data-selector-testid"?: string | undefined;
+    /**
+     * Accessible label for the combobox trigger element.
+     */
     "aria-label"?: string | undefined;
+    /** The list of items to render in the dropdown. */
     options?: T[] | undefined;
+    /** The currently selected item. Controls the value shown in the trigger. */
     selectedOption?: T | undefined;
-    onSelectOption?: ((option: T, extractedValue: T | V) => void) | undefined;
     /**
-     * Used when items are loaded from an api call.
-     * Values: "loading" | "fail" | "success"
+     * Called when the user selects an item from the dropdown.
+     *
+     * @param option The full item object that was selected.
+     * @param extractedValue The value derived by `valueExtractor`, or the item itself when no extractor is provided.
      */
+    onSelectOption?: ((option: T, extractedValue: T | V) => void) | undefined;
+    /** Indicates the async load state of the options list. */
     optionsLoadState?: ItemsLoadStateType | undefined;
-    /** Specifies the truncation type. Truncated text will be replaced with ellipsis. Values: "middle" | "end" */
+    /** Controls how long option labels are truncated when they overflow. */
     optionTruncationType?: TruncateType | undefined;
+    /** Called when the user activates the retry action while `optionsLoadState` is `"fail"`. */
     onRetry?: (() => void) | undefined;
+    /** Called when the dropdown list is hidden. */
     onHideOptions?: (() => void) | undefined;
+    /** Called when the dropdown list is shown. */
     onShowOptions?: (() => void) | undefined;
+    /** CSS `z-index` applied to the dropdown overlay. */
     dropdownZIndex?: number | undefined;
     /**
-     * The root element that contains the dropdown element. Defaults to the document body.
+     * The root element that contains the dropdown element.
+     *
+     * @remarks Specify this if you need to change the parent of the
+     * dropdown in the HTML DOM.
+     * Possible use case: sharing a stacking context.
      *
-     * If the parent that contains the trigger element has a higher z-index than the dropdown,
-     * the dropdown may not be visible. Specify the parent element here instead
+     * Note: if a parent of the trigger has a higher `z-index` than the dropdown,
+     * the dropdown may be obscured.
+     *
+     * @default document.body
      */
     dropdownRootNode?: RefObject<HTMLElement> | undefined;
 }
+/**
+ * Configuration for the addon rendered alongside the `InputGroup` text field.
+ */
 export interface AddonProps<T, V> {
+    /**
+     * Variant of the addon to render.
+     *
+     * @default "label"
+     */
     type?: InputGroupAddonType | undefined;
+    /** Variant-specific configuration. Shape depends on `type`. */
     attributes: ListAddon<T, V> | LabelAddon | CustomAddon;
+    /**
+     * Side of the input field where the addon is placed.
+     *
+     * @default "left"
+     */
     position?: InputGroupAddonPosition;
 }
+/** Props for the `InputGroup` component. */
 export interface InputGroupProps<T, V> extends InputProps {
+    /**
+     * Optional addon rendered alongside the text field.
+     * Omitting this prop renders a plain input without any addon.
+     */
     addon?: AddonProps<T, V> | undefined;
+    /**
+     * Removes the outer border of the input box.
+     *
+     * @default false
+     */
     noBorder?: boolean | undefined;
+    /**
+     * Called when focus leaves the entire input group.
+     *
+     * @remarks The event argument is optional because the `"list"` addon type fires
+     * `onBlur` from the dropdown interaction rather than from the native input element.
+     */
     onBlur?: ((event?: React.FocusEvent<HTMLInputElement>) => void) | undefined;
 }
-/** To be exposed for Form component inheritance */
+/**
+ * A subset of `InputGroupProps` for use by form components that manage the `error`
+ * state themselves.
+ */
 export type InputGroupPartialProps<T, V> = Omit<InputGroupProps<T, V>, "error">;

package/input-multi-select/input-multi-select.d.ts

@@ -1,2 +1,8 @@
 import type { InputMultiSelectProps } from "./types";
+/**
+ * A dropdown field that lets users select multiple options from a list.
+ *
+ * Use `InputMultiSelect` when users need to pick one or more items from a
+ * predefined list.
+ */
 export declare const InputMultiSelect: <T, V>({ selectedOptions, placeholder, options, disabled, error, className, "data-testid": testId, id, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, enableSearch, searchFunction, searchPlaceholder, valueExtractor, listExtractor, onSelectOptions, onShowOptions, onHideOptions, onRetry, optionsLoadState, optionTruncationType, renderListItem, hideNoResultsDisplay, noResultsDescription, customLabels, renderCustomCallToAction, onBlur, variant, readOnly, alignment, dropdownZIndex, maxSelectable, dropdownRootNode, dropdownWidth, }: InputMultiSelectProps<T, V>) => JSX.Element;