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

package/input-range-slider/types.d.ts

@@ -1,36 +1,121 @@
+/**
+ * Shared configuration for `InputRangeSlider` covering track bounds,
+ * step interval, track colors, and label display.
+ */
 export interface BaseSliderProps {
     className?: string | undefined;
     id?: string | undefined;
     "data-testid"?: string | undefined;
+    /**
+     * The lower bound of the slider range.
+     *
+     * @default 0
+     */
     min?: number | undefined;
+    /**
+     * The upper bound of the slider range.
+     *
+     * @default 100
+     */
     max?: number | undefined;
-    /** The interval between the prev and next value */
+    /**
+     * The interval between selectable values.
+     *
+     * @default 1
+     */
     step?: number | undefined;
     disabled?: boolean | undefined;
     readOnly?: boolean | undefined;
-    /** Customise the color of each track segment. Expected length is (number of values + 1) */
+    /**
+     * Colours applied to each track segment in order. The array length should
+     * equal to `numOfThumbs + 1`.
+     */
     colors?: (string | undefined)[] | undefined;
+    /**
+     * Renders label text at the minimum and maximum ends of the track.
+     */
     showSliderLabels?: boolean | undefined;
+    /**
+     * Text prepended to each slider label value. Ignored when
+     * `renderSliderLabel` is provided.
+     */
     sliderLabelPrefix?: string | undefined;
+    /**
+     * Text appended to each slider label value. Ignored when
+     * `renderSliderLabel` is provided.
+     */
     sliderLabelSuffix?: string | undefined;
+    /**
+     * Renders a label above the slider showing the current selection.
+     */
     showIndicatorLabel?: boolean | undefined;
+    /**
+     * Text prepended to the indicator label value.
+     */
     indicatorLabelPrefix?: string | undefined;
+    /**
+     * Text appended to the indicator label value.
+     */
     indicatorLabelSuffix?: string | undefined;
+    /**
+     * Custom renderer for the slider labels shown at the min and max track
+     * ends. Takes precedence over `sliderLabelPrefix` and `sliderLabelSuffix`.
+     */
     renderSliderLabel?: ((value: number) => React.ReactNode) | undefined;
 }
+/**
+ * Props for the `InputRangeSlider` component.
+ */
 export interface InputRangeSliderProps extends BaseSliderProps {
+    /**
+     * Controlled values for each thumb, indexed by position. Must have the
+     * same length as `numOfThumbs`; when the lengths differ or `value` is
+     * omitted, each thumb defaults to `min + step * index`.
+     */
     value?: number[] | undefined;
-    /** The number of thumb controls */
+    /**
+     * The number of thumb controls rendered on the track.
+     *
+     * @default 2
+     */
     numOfThumbs?: number | undefined;
-    /** The minimum difference between values */
+    /**
+     * The minimum allowed difference between adjacent thumb values.
+     *
+     * @default 0
+     */
     minRange?: number | undefined;
+    /**
+     * Accessible labels for each thumb.
+     */
     ariaLabels?: string[] | undefined;
+    /**
+     * Accessible description text for each thumb.
+     */
     ariaDescriptions?: string[] | undefined;
+    /**
+     * Marks each thumb's native range input as invalid for assistive
+     * technologies.
+     */
     "aria-invalid"?: boolean | undefined;
+    /**
+     * ID(s) of an element(s) that labels the slider group.
+     */
     "aria-labelledby"?: string | undefined;
+    /**
+     * ID(s) of an element(s) that provides additional information of the slider group.
+     */
     "aria-describedby"?: string | undefined;
-    /** Called on every selection change */
+    /**
+     * Called on every selection change.
+     *
+     * @param value The updated array of thumb values, in thumb order.
+     */
     onChange?: ((value: number[]) => void) | undefined;
-    /** Called when a thumb is released after selection is complete */
+    /**
+     * Called when a thumb is released after selection is complete.
+     *
+     * @param value The final array of thumb values, in thumb order.
+     */
     onChangeEnd?: ((value: number[]) => void) | undefined;
 }

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

@@ -1,2 +1,7 @@
 import type { InputSelectProps } from "./types";
+/**
+ * A single-selection dropdown input.
+ *
+ * Use `InputSelect` when the user must pick exactly one item from a list.
+ */
 export declare const InputSelect: <T, V>({ selectedOption, placeholder, options, disabled, error, className, "data-testid": testId, id, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, enableSearch, searchFunction, searchPlaceholder, valueExtractor, valueToStringFunction, listExtractor, displayValueExtractor, onSelectOption, onShowOptions, onHideOptions, onRetry, optionsLoadState, optionTruncationType, renderCustomSelectedOption, renderListItem, hideNoResultsDisplay, noResultsDescription, customLabels, renderCustomCallToAction, onBlur, variant, readOnly, alignment, dropdownZIndex, dropdownRootNode, dropdownWidth, }: InputSelectProps<T, V>) => JSX.Element;

package/input-select/input-select.js.map

@@ -1 +1 @@
-{"version":3,"file":"input-select.js","sources":["../../src/input-select/input-select.tsx"],"sourcesContent":["import type { OpenChangeReason } from \"@floating-ui/react\";\nimport type React from \"react\";\nimport { useEffect, useRef, useState } from \"react\";\n\nimport {\n    DropdownList,\n    DropdownListState,\n    ExpandableElement,\n} from \"../shared/dropdown-list\";\nimport { ElementWithDropdown } from \"../shared/dropdown-wrapper\";\nimport {\n    LabelContainer,\n    PlaceholderLabel,\n    ValueLabel,\n} from \"../shared/dropdown-wrapper/dropdown-wrapper\";\nimport { InputBox } from \"../shared/input-wrapper/input-wrapper\";\nimport { useId } from \"../util\";\nimport { StringHelper } from \"../util/string-helper\";\nimport type { InputSelectProps } from \"./types\";\n\nexport const InputSelect = <T, V>({\n    selectedOption,\n    placeholder = \"Select\",\n    options,\n    disabled,\n    error,\n    className,\n    \"data-testid\": testId,\n    id,\n    \"aria-labelledby\": ariaLabelledBy,\n    \"aria-describedby\": ariaDescribedBy,\n    \"aria-invalid\": ariaInvalid,\n    enableSearch = false,\n    searchFunction,\n    searchPlaceholder,\n    valueExtractor,\n    valueToStringFunction,\n    listExtractor,\n    displayValueExtractor,\n    onSelectOption,\n    onShowOptions,\n    onHideOptions,\n    onRetry,\n    optionsLoadState = \"success\",\n    optionTruncationType = \"end\",\n    renderCustomSelectedOption,\n    renderListItem,\n    hideNoResultsDisplay,\n    noResultsDescription,\n    customLabels,\n    renderCustomCallToAction,\n    onBlur,\n    variant = \"default\",\n    readOnly,\n    alignment,\n    dropdownZIndex,\n    dropdownRootNode,\n    dropdownWidth,\n}: InputSelectProps<T, V>): JSX.Element => {\n    // =============================================================================\n    // CONST, STATE\n    // =============================================================================\n    const [selected, setSelected] = useState<T | undefined>(selectedOption);\n    const [showOptions, setShowOptions] = useState<boolean>(false);\n    const [focused, setFocused] = useState<boolean>(false);\n    const internalId = useId();\n\n    const nodeRef = useRef<HTMLDivElement>(null);\n    const selectorRef = useRef<HTMLButtonElement>(null);\n    const labelContainerRef = useRef<HTMLDivElement>(null);\n\n    // =============================================================================\n    // EFFECTS\n    // =============================================================================\n    useEffect(() => {\n        setSelected(selectedOption);\n    }, [selectedOption]);\n\n    // =============================================================================\n    // EVENT HANDLERS\n    // =============================================================================\n    const handleListItemClick = (item: T, extractedValue: V) => {\n        selectorRef.current?.focus();\n        setSelected(item);\n        setShowOptions(false);\n        triggerOptionDisplayCallback(false);\n\n        onSelectOption?.(item, extractedValue);\n    };\n\n    const handleListDismiss = () => {\n        if (showOptions) {\n            setShowOptions(false);\n            triggerOptionDisplayCallback(false);\n        }\n    };\n\n    const handleNodeFocus = () => {\n        if (!focused && !showOptions) {\n            setFocused(true);\n        }\n    };\n\n    const handleNodeBlur = (e: React.FocusEvent) => {\n        if (\n            focused &&\n            !showOptions &&\n            nodeRef.current &&\n            !nodeRef.current.contains(e.relatedTarget as Node)\n        ) {\n            setFocused(false);\n            onBlur?.();\n        }\n    };\n\n    const handleOpen = () => {\n        setShowOptions(true);\n        triggerOptionDisplayCallback(true);\n        setFocused(true);\n    };\n\n    const handleClose = (reason: OpenChangeReason | undefined) => {\n        setShowOptions(false);\n        triggerOptionDisplayCallback(false);\n\n        // click to toggle should not blur the input\n        if (reason !== \"click\") {\n            setFocused(false);\n            onBlur?.();\n        }\n    };\n\n    const handleDismiss = () => {\n        selectorRef.current?.focus();\n        setShowOptions(false);\n        triggerOptionDisplayCallback(false);\n    };\n\n    // =============================================================================\n    // HELPER FUNCTION\n    // =============================================================================\n    const getDisplayValue = (): string => {\n        if (!selected) return \"\";\n\n        if (displayValueExtractor) {\n            return displayValueExtractor(selected);\n        }\n\n        if (valueExtractor) {\n            const value = valueExtractor(selected);\n            return valueToStringFunction\n                ? valueToStringFunction(value)\n                : value?.toString() ?? \"\";\n        }\n\n        return selected.toString();\n    };\n\n    const truncateValue = (value: string) => {\n        if (optionTruncationType === \"middle\") {\n            let widthOfElement = 0;\n            if (labelContainerRef && labelContainerRef.current) {\n                widthOfElement =\n                    labelContainerRef.current.getBoundingClientRect().width;\n            }\n\n            return StringHelper.truncateOneLine(value, widthOfElement, 120, 8);\n        }\n        return value;\n    };\n\n    const triggerOptionDisplayCallback = (show: boolean) => {\n        if (show) {\n            onShowOptions?.();\n        } else {\n            onHideOptions?.();\n        }\n    };\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    const renderLabel = () => {\n        if (!selected) {\n            return (\n                <PlaceholderLabel\n                    variant={variant}\n                    truncateType={optionTruncationType}\n                >\n                    {placeholder}\n                </PlaceholderLabel>\n            );\n        } else if (renderCustomSelectedOption) {\n            return renderCustomSelectedOption(selected);\n        } else {\n            return (\n                <ValueLabel\n                    variant={variant}\n                    truncateType={optionTruncationType}\n                >\n                    {truncateValue(getDisplayValue())}\n                </ValueLabel>\n            );\n        }\n    };\n\n    const renderSelectorContent = () => (\n        <LabelContainer ref={labelContainerRef} disabled={disabled}>\n            {renderLabel()}\n        </LabelContainer>\n    );\n\n    const renderElement = () => {\n        return (\n            <InputBox\n                className={className}\n                data-testid={testId}\n                id={id}\n                ref={nodeRef}\n                tabIndex={-1}\n                onFocus={handleNodeFocus}\n                onBlur={handleNodeBlur}\n                focused={focused}\n                disabled={disabled}\n                readOnly={readOnly}\n                error={error}\n            >\n                <ExpandableElement\n                    ref={selectorRef}\n                    disabled={disabled}\n                    expanded={showOptions}\n                    listboxId={internalId}\n                    popupRole=\"listbox\"\n                    readOnly={readOnly}\n                    variant={variant}\n                    aria-labelledby={ariaLabelledBy}\n                    aria-describedby={ariaDescribedBy}\n                    aria-invalid={ariaInvalid}\n                >\n                    {renderSelectorContent()}\n                </ExpandableElement>\n            </InputBox>\n        );\n    };\n\n    const renderDropdown = () => {\n        return (\n            <DropdownList\n                listboxId={internalId}\n                listItems={options}\n                onSelectItem={handleListItemClick}\n                onDismiss={handleListDismiss}\n                valueExtractor={valueExtractor}\n                listExtractor={listExtractor}\n                enableSearch={enableSearch}\n                searchPlaceholder={searchPlaceholder}\n                searchFunction={searchFunction}\n                selectedItems={selected ? [selected] : []}\n                onRetry={onRetry}\n                itemsLoadState={optionsLoadState}\n                itemTruncationType={optionTruncationType}\n                renderListItem={renderListItem}\n                hideNoResultsDisplay={hideNoResultsDisplay}\n                noResultsDescription={noResultsDescription}\n                customLabels={customLabels}\n                renderCustomCallToAction={renderCustomCallToAction}\n                variant={variant}\n                width={dropdownWidth}\n                matchElementWidth\n            />\n        );\n    };\n\n    return (\n        <DropdownListState>\n            <ElementWithDropdown\n                enabled={!readOnly && !disabled}\n                isOpen={showOptions}\n                renderElement={renderElement}\n                renderDropdown={renderDropdown}\n                onOpen={handleOpen}\n                onClose={handleClose}\n                onDismiss={handleDismiss}\n                clickToToggle\n                offset={8}\n                alignment={alignment}\n                fitAvailableHeight\n                customZIndex={dropdownZIndex}\n                rootNode={dropdownRootNode}\n            />\n        </DropdownListState>\n    );\n};\n"],"names":["InputSelect","selectedOption","placeholder","options","disabled","error","className","testId","id","ariaLabelledBy","ariaDescribedBy","ariaInvalid","enableSearch","searchFunction","searchPlaceholder","valueExtractor","valueToStringFunction","listExtractor","displayValueExtractor","onSelectOption","onShowOptions","onHideOptions","onRetry","optionsLoadState","optionTruncationType","renderCustomSelectedOption","renderListItem","hideNoResultsDisplay","noResultsDescription","customLabels","renderCustomCallToAction","onBlur","variant","readOnly","alignment","dropdownZIndex","dropdownRootNode","dropdownWidth","selected","setSelected","useState","showOptions","setShowOptions","focused","setFocused","internalId","useId","nodeRef","useRef","selectorRef","labelContainerRef","useEffect","handleListItemClick","item","extractedValue","_a","current","focus","triggerOptionDisplayCallback","handleListDismiss","handleNodeFocus","handleNodeBlur","e","contains","relatedTarget","getDisplayValue","value","toString","truncateValue","widthOfElement","getBoundingClientRect","width","StringHelper","truncateOneLine","show","_jsx","DropdownListState","children","ElementWithDropdown","enabled","isOpen","renderElement","InputBox","ref","tabIndex","onFocus","ExpandableElement","expanded","listboxId","popupRole","LabelContainer","ValueLabel","truncateType","PlaceholderLabel","renderDropdown","DropdownList","listItems","onSelectItem","onDismiss","selectedItems","itemsLoadState","itemTruncationType","matchElementWidth","onOpen","onClose","reason","clickToToggle","offset","fitAvailableHeight","customZIndex","rootNode"],"mappings":"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"}
+{"version":3,"file":"input-select.js","sources":["../../src/input-select/input-select.tsx"],"sourcesContent":["import type { OpenChangeReason } from \"@floating-ui/react\";\nimport type React from \"react\";\nimport { useEffect, useRef, useState } from \"react\";\n\nimport {\n    DropdownList,\n    DropdownListState,\n    ExpandableElement,\n} from \"../shared/dropdown-list\";\nimport { ElementWithDropdown } from \"../shared/dropdown-wrapper\";\nimport {\n    LabelContainer,\n    PlaceholderLabel,\n    ValueLabel,\n} from \"../shared/dropdown-wrapper/dropdown-wrapper\";\nimport { InputBox } from \"../shared/input-wrapper/input-wrapper\";\nimport { useId } from \"../util\";\nimport { StringHelper } from \"../util/string-helper\";\nimport type { InputSelectProps } from \"./types\";\n\n/**\n * A single-selection dropdown input.\n *\n * Use `InputSelect` when the user must pick exactly one item from a list.\n */\nexport const InputSelect = <T, V>({\n    selectedOption,\n    placeholder = \"Select\",\n    options,\n    disabled,\n    error,\n    className,\n    \"data-testid\": testId,\n    id,\n    \"aria-labelledby\": ariaLabelledBy,\n    \"aria-describedby\": ariaDescribedBy,\n    \"aria-invalid\": ariaInvalid,\n    enableSearch = false,\n    searchFunction,\n    searchPlaceholder,\n    valueExtractor,\n    valueToStringFunction,\n    listExtractor,\n    displayValueExtractor,\n    onSelectOption,\n    onShowOptions,\n    onHideOptions,\n    onRetry,\n    optionsLoadState = \"success\",\n    optionTruncationType = \"end\",\n    renderCustomSelectedOption,\n    renderListItem,\n    hideNoResultsDisplay,\n    noResultsDescription,\n    customLabels,\n    renderCustomCallToAction,\n    onBlur,\n    variant = \"default\",\n    readOnly,\n    alignment,\n    dropdownZIndex,\n    dropdownRootNode,\n    dropdownWidth,\n}: InputSelectProps<T, V>): JSX.Element => {\n    // =============================================================================\n    // CONST, STATE\n    // =============================================================================\n    const [selected, setSelected] = useState<T | undefined>(selectedOption);\n    const [showOptions, setShowOptions] = useState<boolean>(false);\n    const [focused, setFocused] = useState<boolean>(false);\n    const internalId = useId();\n\n    const nodeRef = useRef<HTMLDivElement>(null);\n    const selectorRef = useRef<HTMLButtonElement>(null);\n    const labelContainerRef = useRef<HTMLDivElement>(null);\n\n    // =============================================================================\n    // EFFECTS\n    // =============================================================================\n    useEffect(() => {\n        setSelected(selectedOption);\n    }, [selectedOption]);\n\n    // =============================================================================\n    // EVENT HANDLERS\n    // =============================================================================\n    const handleListItemClick = (item: T, extractedValue: V) => {\n        selectorRef.current?.focus();\n        setSelected(item);\n        setShowOptions(false);\n        triggerOptionDisplayCallback(false);\n\n        onSelectOption?.(item, extractedValue);\n    };\n\n    const handleListDismiss = () => {\n        if (showOptions) {\n            setShowOptions(false);\n            triggerOptionDisplayCallback(false);\n        }\n    };\n\n    const handleNodeFocus = () => {\n        if (!focused && !showOptions) {\n            setFocused(true);\n        }\n    };\n\n    const handleNodeBlur = (e: React.FocusEvent) => {\n        if (\n            focused &&\n            !showOptions &&\n            nodeRef.current &&\n            !nodeRef.current.contains(e.relatedTarget as Node)\n        ) {\n            setFocused(false);\n            onBlur?.();\n        }\n    };\n\n    const handleOpen = () => {\n        setShowOptions(true);\n        triggerOptionDisplayCallback(true);\n        setFocused(true);\n    };\n\n    const handleClose = (reason: OpenChangeReason | undefined) => {\n        setShowOptions(false);\n        triggerOptionDisplayCallback(false);\n\n        // click to toggle should not blur the input\n        if (reason !== \"click\") {\n            setFocused(false);\n            onBlur?.();\n        }\n    };\n\n    const handleDismiss = () => {\n        selectorRef.current?.focus();\n        setShowOptions(false);\n        triggerOptionDisplayCallback(false);\n    };\n\n    // =============================================================================\n    // HELPER FUNCTION\n    // =============================================================================\n    const getDisplayValue = (): string => {\n        if (!selected) return \"\";\n\n        if (displayValueExtractor) {\n            return displayValueExtractor(selected);\n        }\n\n        if (valueExtractor) {\n            const value = valueExtractor(selected);\n            return valueToStringFunction\n                ? valueToStringFunction(value)\n                : value?.toString() ?? \"\";\n        }\n\n        return selected.toString();\n    };\n\n    const truncateValue = (value: string) => {\n        if (optionTruncationType === \"middle\") {\n            let widthOfElement = 0;\n            if (labelContainerRef && labelContainerRef.current) {\n                widthOfElement =\n                    labelContainerRef.current.getBoundingClientRect().width;\n            }\n\n            return StringHelper.truncateOneLine(value, widthOfElement, 120, 8);\n        }\n        return value;\n    };\n\n    const triggerOptionDisplayCallback = (show: boolean) => {\n        if (show) {\n            onShowOptions?.();\n        } else {\n            onHideOptions?.();\n        }\n    };\n\n    // =============================================================================\n    // RENDER FUNCTIONS\n    // =============================================================================\n    const renderLabel = () => {\n        if (!selected) {\n            return (\n                <PlaceholderLabel\n                    variant={variant}\n                    truncateType={optionTruncationType}\n                >\n                    {placeholder}\n                </PlaceholderLabel>\n            );\n        } else if (renderCustomSelectedOption) {\n            return renderCustomSelectedOption(selected);\n        } else {\n            return (\n                <ValueLabel\n                    variant={variant}\n                    truncateType={optionTruncationType}\n                >\n                    {truncateValue(getDisplayValue())}\n                </ValueLabel>\n            );\n        }\n    };\n\n    const renderSelectorContent = () => (\n        <LabelContainer ref={labelContainerRef} disabled={disabled}>\n            {renderLabel()}\n        </LabelContainer>\n    );\n\n    const renderElement = () => {\n        return (\n            <InputBox\n                className={className}\n                data-testid={testId}\n                id={id}\n                ref={nodeRef}\n                tabIndex={-1}\n                onFocus={handleNodeFocus}\n                onBlur={handleNodeBlur}\n                focused={focused}\n                disabled={disabled}\n                readOnly={readOnly}\n                error={error}\n            >\n                <ExpandableElement\n                    ref={selectorRef}\n                    disabled={disabled}\n                    expanded={showOptions}\n                    listboxId={internalId}\n                    popupRole=\"listbox\"\n                    readOnly={readOnly}\n                    variant={variant}\n                    aria-labelledby={ariaLabelledBy}\n                    aria-describedby={ariaDescribedBy}\n                    aria-invalid={ariaInvalid}\n                >\n                    {renderSelectorContent()}\n                </ExpandableElement>\n            </InputBox>\n        );\n    };\n\n    const renderDropdown = () => {\n        return (\n            <DropdownList\n                listboxId={internalId}\n                listItems={options}\n                onSelectItem={handleListItemClick}\n                onDismiss={handleListDismiss}\n                valueExtractor={valueExtractor}\n                listExtractor={listExtractor}\n                enableSearch={enableSearch}\n                searchPlaceholder={searchPlaceholder}\n                searchFunction={searchFunction}\n                selectedItems={selected ? [selected] : []}\n                onRetry={onRetry}\n                itemsLoadState={optionsLoadState}\n                itemTruncationType={optionTruncationType}\n                renderListItem={renderListItem}\n                hideNoResultsDisplay={hideNoResultsDisplay}\n                noResultsDescription={noResultsDescription}\n                customLabels={customLabels}\n                renderCustomCallToAction={renderCustomCallToAction}\n                variant={variant}\n                width={dropdownWidth}\n                matchElementWidth\n            />\n        );\n    };\n\n    return (\n        <DropdownListState>\n            <ElementWithDropdown\n                enabled={!readOnly && !disabled}\n                isOpen={showOptions}\n                renderElement={renderElement}\n                renderDropdown={renderDropdown}\n                onOpen={handleOpen}\n                onClose={handleClose}\n                onDismiss={handleDismiss}\n                clickToToggle\n                offset={8}\n                alignment={alignment}\n                fitAvailableHeight\n                customZIndex={dropdownZIndex}\n                rootNode={dropdownRootNode}\n            />\n        </DropdownListState>\n    );\n};\n"],"names":["InputSelect","selectedOption","placeholder","options","disabled","error","className","testId","id","ariaLabelledBy","ariaDescribedBy","ariaInvalid","enableSearch","searchFunction","searchPlaceholder","valueExtractor","valueToStringFunction","listExtractor","displayValueExtractor","onSelectOption","onShowOptions","onHideOptions","onRetry","optionsLoadState","optionTruncationType","renderCustomSelectedOption","renderListItem","hideNoResultsDisplay","noResultsDescription","customLabels","renderCustomCallToAction","onBlur","variant","readOnly","alignment","dropdownZIndex","dropdownRootNode","dropdownWidth","selected","setSelected","useState","showOptions","setShowOptions","focused","setFocused","internalId","useId","nodeRef","useRef","selectorRef","labelContainerRef","useEffect","handleListItemClick","item","extractedValue","_a","current","focus","triggerOptionDisplayCallback","handleListDismiss","handleNodeFocus","handleNodeBlur","e","contains","relatedTarget","getDisplayValue","value","toString","truncateValue","widthOfElement","getBoundingClientRect","width","StringHelper","truncateOneLine","show","_jsx","DropdownListState","children","ElementWithDropdown","enabled","isOpen","renderElement","InputBox","ref","tabIndex","onFocus","ExpandableElement","expanded","listboxId","popupRole","LabelContainer","ValueLabel","truncateType","PlaceholderLabel","renderDropdown","DropdownList","listItems","onSelectItem","onDismiss","selectedItems","itemsLoadState","itemTruncationType","matchElementWidth","onOpen","onClose","reason","clickToToggle","offset","fitAvailableHeight","customZIndex","rootNode"],"mappings":"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"}

package/input-select/types.d.ts

@@ -1,56 +1,112 @@
 import type { RefObject } from "react";
 import type { DropdownCustomLabelProps, DropdownDisplayProps, DropdownSearchProps, DropdownVariantType, ItemsLoadStateType, TruncateType } from "../shared/dropdown-list/types";
 import type { DropdownAlignmentType } from "../shared/dropdown-wrapper";
+/**
+ * Options configuration for `InputSelect`.
+ */
 export interface InputSelectOptionsProps<T> {
+    /** The list of selectable options rendered in the dropdown. */
     options: T[];
     /**
-     * Used when options are loaded from an api call.
-     * Values: "loading" | "fail" | "success"
+     * Indicates the load state of options fetched asynchronously.
+     * Renders a loading spinner, error retry, or the list depending on the state.
+     *
+     * @default "success"
      */
     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.
+     *
+     * @default "end"
+     */
     optionTruncationType?: TruncateType | undefined;
+    /** Called when the dropdown list becomes visible. */
     onShowOptions?: (() => void) | undefined;
+    /** Called when the dropdown list is hidden. */
     onHideOptions?: (() => void) | undefined;
+    /** Called when the user activates the retry action after a load failure. */
     onRetry?: (() => void) | undefined;
 }
+/** Common presentation and state props shared across select components. */
 export interface InputSelectSharedProps<T> {
-    /** HTML button props */
+    /** Name attribute forwarded to the underlying button element. */
     name?: string | undefined;
-    /** Component specific props */
+    /** The list of selectable options. */
     options: T[];
+    /** Placeholder text shown when no option is selected. */
     placeholder?: string | undefined;
     disabled?: boolean | undefined;
+    /** Renders the trigger in an error state. */
     error?: boolean | undefined;
     "data-testid"?: string | undefined;
 }
+/**
+ * Props for the `InputSelect` component.
+ *
+ * `T` is the option item type; `V` is the extracted value type returned by
+ * `valueExtractor`.
+ */
 export interface InputSelectProps<T, V> extends React.HTMLAttributes<HTMLElement>, InputSelectOptionsProps<T>, InputSelectSharedProps<T>, DropdownDisplayProps<T, V>, DropdownSearchProps<T> {
     readOnly?: boolean | undefined;
+    /** The currently selected option. The component syncs to this value on each render. */
     selectedOption?: T | undefined;
+    /**
+     * Called when the user picks an item from the dropdown.
+     *
+     * @param option The full option object that was selected.
+     * @param extractedValue The value derived from the option via `valueExtractor`.
+     */
     onSelectOption?: ((option: T, extractedValue: V) => void) | undefined;
-    /** Function to derive display value for selected option */
+    /**
+     * Derives the display string shown in the trigger for the selected option.
+     * Takes precedence over `valueExtractor` + `valueToStringFunction`.
+     */
     displayValueExtractor?: ((option: T) => string) | undefined;
-    /** Function to convert value into a string */
+    /** Function to convert selected value into a display string */
     valueToStringFunction?: ((value: V) => string) | undefined;
-    /** Function to render selected custom component */
+    /**
+     * Renders a custom element for the currently selected option.
+     */
     renderCustomSelectedOption?: ((option: T) => JSX.Element) | undefined;
+    /**
+     * Called when focus leaves both the trigger and dropdown.
+     */
     onBlur?: (() => void) | undefined;
+    /**
+     * Visual size variant of the trigger and dropdown.
+     *
+     * @default "default"
+     */
     variant?: DropdownVariantType | undefined;
+    /** Aligns the dropdown relative to the trigger element. */
     alignment?: DropdownAlignmentType | 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.
+     *
+     * Note: if a parent of the trigger has a higher `z-index` than the dropdown,
+     * the dropdown may be obscured.
      *
-     * 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
+     * @default `document.body`
      */
     dropdownRootNode?: RefObject<HTMLElement> | undefined;
     /**
-     * Custom width for the dropdown. When specified, the dropdown will use this
-     * width instead of matching the input element width.
+     * Custom width for the dropdown. When specified, the dropdown uses this
+     * width instead of matching the trigger element width.
      */
     dropdownWidth?: string | undefined;
+    /**
+     * Overrides the default labels shown inside the dropdown and on the trigger.
+     */
     customLabels?: DropdownCustomLabelProps | undefined;
 }
-/** To be exposed for Form component inheritance */
+/**
+ * A subset of `InputSelectProps` used by form components that manage
+ * the `error` state themselves.
+ */
 export type InputSelectPartialProps<T, V> = Omit<InputSelectProps<T, V>, "error">;

package/input-slider/input-slider.d.ts

@@ -1,2 +1,8 @@
 import type { InputSliderProps } from "./types";
+/**
+ * A single-thumb slider for selecting one numeric value within a range.
+ *
+ * Use `InputSlider` when a user needs to pick a single point on a continuous
+ * scale without a precise value. For selecting a range between two values, use `InputRangeSlider` instead.
+ */
 export declare const InputSlider: ({ value, ariaLabel, onChange, onChangeEnd, ...otherProps }: InputSliderProps) => import("react/jsx-runtime").JSX.Element;

package/input-slider/input-slider.js.map

@@ -1 +1 @@
-{"version":3,"file":"input-slider.js","sources":["../../src/input-slider/input-slider.tsx"],"sourcesContent":["import { useEffect, useState } from \"react\";\n\nimport { InputRangeSlider } from \"../input-range-slider\";\nimport type { InputSliderProps } from \"./types\";\n\nexport const InputSlider = ({\n    value,\n    ariaLabel,\n    onChange,\n    onChangeEnd,\n    ...otherProps\n}: InputSliderProps) => {\n    // =========================================================================\n    // CONST, STATE, REF\n    // =========================================================================\n    const [selection, setSelection] = useState<number[]>(initialiseSelection());\n\n    // =========================================================================\n    // EFFECTS\n    // =========================================================================\n    useEffect(() => {\n        if (value !== selection[0]) {\n            setSelection(initialiseSelection());\n        }\n    }, [value]);\n\n    // =========================================================================\n    // EVENT HANDLERS\n    // =========================================================================\n    const handleChange = (value: number[]) => {\n        const [newVal] = value;\n        setSelection([newVal]);\n        onChange?.(newVal);\n    };\n\n    const handleChangeEnd = (value: number[]) => {\n        const [newVal] = value;\n        setSelection([newVal]);\n        onChangeEnd?.(newVal);\n    };\n\n    // =========================================================================\n    // HELPER FUNCTIONS\n    // =========================================================================\n    function initialiseSelection() {\n        return value != undefined ? [value] : [0];\n    }\n\n    return (\n        <InputRangeSlider\n            {...otherProps}\n            value={selection}\n            numOfThumbs={1}\n            onChange={handleChange}\n            onChangeEnd={handleChangeEnd}\n            ariaLabels={ariaLabel ? [ariaLabel] : undefined}\n        />\n    );\n};\n"],"names":["InputSlider","_a","value","ariaLabel","onChange","onChangeEnd","otherProps","__rest","selection","setSelection","useState","initialiseSelection","useEffect","undefined","_jsx","InputRangeSlider","Object","assign","numOfThumbs","newVal","ariaLabels"],"mappings":"sNAKO,MAAMA,EAAeC,IAAA,IAAAC,MACxBA,EAAKC,UACLA,EAASC,SACTA,EAAQC,YACRA,GAAWJ,EACRK,EAAUC,EAAAN,EALW,CAAA,QAAA,YAAA,WAAA,gBAUxB,MAAOO,EAAWC,GAAgBC,EAAmBC,KAKrDC,GAAU,KACFV,IAAUM,EAAU,IACpBC,EAAaE,IACjB,GACD,CAACT,IAoBJ,SAASS,IACL,OAAgBE,MAATX,EAAqB,CAACA,GAAS,CAAC,EAC3C,CAEA,OACIY,EAACC,EAAgBC,OAAAC,OAAA,CAAA,EACTX,GACJJ,MAAOM,EACPU,YAAa,EACbd,SAxBcF,IAClB,MAAOiB,GAAUjB,EACjBO,EAAa,CAACU,IACdf,SAAAA,EAAWe,EAAO,EAsBdd,YAnBiBH,IACrB,MAAOiB,GAAUjB,EACjBO,EAAa,CAACU,IACdd,SAAAA,EAAcc,EAAO,EAiBjBC,WAAYjB,EAAY,CAACA,QAAaU,IACxC"}
+{"version":3,"file":"input-slider.js","sources":["../../src/input-slider/input-slider.tsx"],"sourcesContent":["import { useEffect, useState } from \"react\";\n\nimport { InputRangeSlider } from \"../input-range-slider\";\nimport type { InputSliderProps } from \"./types\";\n\n/**\n * A single-thumb slider for selecting one numeric value within a range.\n *\n * Use `InputSlider` when a user needs to pick a single point on a continuous\n * scale without a precise value. For selecting a range between two values, use `InputRangeSlider` instead.\n */\nexport const InputSlider = ({\n    value,\n    ariaLabel,\n    onChange,\n    onChangeEnd,\n    ...otherProps\n}: InputSliderProps) => {\n    // =========================================================================\n    // CONST, STATE, REF\n    // =========================================================================\n    const [selection, setSelection] = useState<number[]>(initialiseSelection());\n\n    // =========================================================================\n    // EFFECTS\n    // =========================================================================\n    useEffect(() => {\n        if (value !== selection[0]) {\n            setSelection(initialiseSelection());\n        }\n    }, [value]);\n\n    // =========================================================================\n    // EVENT HANDLERS\n    // =========================================================================\n    const handleChange = (value: number[]) => {\n        const [newVal] = value;\n        setSelection([newVal]);\n        onChange?.(newVal);\n    };\n\n    const handleChangeEnd = (value: number[]) => {\n        const [newVal] = value;\n        setSelection([newVal]);\n        onChangeEnd?.(newVal);\n    };\n\n    // =========================================================================\n    // HELPER FUNCTIONS\n    // =========================================================================\n    function initialiseSelection() {\n        return value != undefined ? [value] : [0];\n    }\n\n    return (\n        <InputRangeSlider\n            {...otherProps}\n            value={selection}\n            numOfThumbs={1}\n            onChange={handleChange}\n            onChangeEnd={handleChangeEnd}\n            ariaLabels={ariaLabel ? [ariaLabel] : undefined}\n        />\n    );\n};\n"],"names":["InputSlider","_a","value","ariaLabel","onChange","onChangeEnd","otherProps","__rest","selection","setSelection","useState","initialiseSelection","useEffect","undefined","_jsx","InputRangeSlider","Object","assign","numOfThumbs","newVal","ariaLabels"],"mappings":"sNAWO,MAAMA,EAAeC,IAAA,IAAAC,MACxBA,EAAKC,UACLA,EAASC,SACTA,EAAQC,YACRA,GAAWJ,EACRK,EAAUC,EAAAN,EALW,CAAA,QAAA,YAAA,WAAA,gBAUxB,MAAOO,EAAWC,GAAgBC,EAAmBC,KAKrDC,GAAU,KACFV,IAAUM,EAAU,IACpBC,EAAaE,IACjB,GACD,CAACT,IAoBJ,SAASS,IACL,OAAgBE,MAATX,EAAqB,CAACA,GAAS,CAAC,EAC3C,CAEA,OACIY,EAACC,EAAgBC,OAAAC,OAAA,CAAA,EACTX,GACJJ,MAAOM,EACPU,YAAa,EACbd,SAxBcF,IAClB,MAAOiB,GAAUjB,EACjBO,EAAa,CAACU,IACdf,SAAAA,EAAWe,EAAO,EAsBdd,YAnBiBH,IACrB,MAAOiB,GAAUjB,EACjBO,EAAa,CAACU,IACdd,SAAAA,EAAcc,EAAO,EAiBjBC,WAAYjB,EAAY,CAACA,QAAaU,IACxC"}

package/input-slider/types.d.ts

@@ -1,9 +1,28 @@
 import type { BaseSliderProps } from "../input-range-slider/types";
+/**
+ * Props for the `InputSlider` component.
+ */
 export interface InputSliderProps extends BaseSliderProps {
+    /**
+     * The controlled value of the thumb.
+     *
+     * @default `0`
+     */
     value?: number | undefined;
+    /**
+     * Accessible label for the thumb.
+     */
     ariaLabel?: string | undefined;
-    /** Called on every selection change */
+    /**
+     * Called on every selection change.
+     *
+     * @param value The updated thumb value.
+     */
     onChange?: ((value: number) => void) | undefined;
-    /** Called when the thumb is released after selection is complete */
+    /**
+     * Called when a thumb is released after selection is complete.
+     *
+     * @param value The final thumb value.
+     */
     onChangeEnd?: ((value: number) => void) | undefined;
 }

package/input-textarea/textarea.d.ts

@@ -1,4 +1,7 @@
 import React from "react";
 import type { TextareaProps } from "./types";
 export declare const TextareaBase: (props: TextareaProps & React.RefAttributes<HTMLTextAreaElement>) => React.ReactElement | null;
+/**
+ * A multi-line text input with an optional character counter and prefix.
+ */
 export declare const Textarea: (props: TextareaProps & React.RefAttributes<HTMLTextAreaElement>) => React.ReactElement | null;

package/input-textarea/textarea.js.map

@@ -1 +1 @@
-{"version":3,"file":"textarea.js","sources":["../../src/input-textarea/textarea.tsx"],"sourcesContent":["import clsx from \"clsx\";\nimport React, { useEffect, useState } from \"react\";\n\nimport * as styles from \"./textarea.styles\";\nimport { TextareaCounter } from \"./textarea-counter\";\nimport type { TextareaProps, TextareaRef } from \"./types\";\n\n// =============================================================================\n// BASE COMPONENT\n// =============================================================================\nconst TextareaBaseComponent = (\n    {\n        className,\n        disabled,\n        error,\n        maxLength,\n        onChange,\n        prefix,\n        readOnly,\n        rows = 5,\n        transformValue,\n        value,\n        ...otherProps\n    }: TextareaProps,\n    ref: TextareaRef\n) => {\n    const [stateValue, setStateValue] = useState(value);\n\n    useEffect(() => {\n        setStateValue(value);\n    }, [value]);\n\n    const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {\n        let newValue = event.target.value;\n        if (prefix) {\n            // Ensure prefix is always present\n            if (!newValue.startsWith(prefix)) {\n                newValue = prefix + newValue.trimStart();\n            }\n\n            // Prevent deleting the prefix\n            if (newValue.length < prefix.length) {\n                newValue = prefix;\n            }\n\n            const cursorPosition = event.target.selectionStart || 0;\n\n            // Ensure backspace does not delete the prefix\n            if (cursorPosition < prefix.length) {\n                event.preventDefault();\n                return;\n            }\n\n            // Extract user input\n            const userInput = newValue.slice(prefix.length);\n\n            // Transform the input if needed\n            const transformedValue = transformValue\n                ? transformValue(userInput)\n                : userInput;\n\n            // Update state and input field\n            setStateValue(transformedValue);\n            event.target.value = prefix + transformedValue;\n\n            // Pass only the user input (without prefix) to `onChange`\n            if (onChange) {\n                const syntheticEvent = {\n                    ...event,\n                    target: { ...event.target, value: transformedValue },\n                };\n                onChange(\n                    syntheticEvent as React.ChangeEvent<HTMLTextAreaElement>\n                );\n            }\n        } else {\n            const transformedValue = transformValue\n                ? transformValue(newValue ?? \"\")\n                : newValue;\n\n            setStateValue(transformedValue);\n            event.target.value = transformedValue;\n            if (onChange) onChange(event);\n        }\n    };\n\n    const getDisplayValue = () => {\n        return prefix ? prefix + (stateValue ?? \"\") : stateValue;\n    };\n\n    const handleKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {\n        if (!prefix) return;\n\n        const { selectionStart } = event.currentTarget;\n\n        // Prevent backspace in prefix\n        if (event.key === \"Backspace\" && selectionStart <= prefix.length) {\n            event.preventDefault();\n        }\n\n        // Prevent left arrow from moving into prefix\n        if (event.key === \"ArrowLeft\" && selectionStart <= prefix.length) {\n            event.preventDefault();\n        }\n\n        // Prevent \"Home\" key from moving cursor to beginning\n        if (event.key === \"Home\") {\n            event.preventDefault();\n            requestAnimationFrame(() => {\n                event.currentTarget.setSelectionRange(\n                    prefix.length,\n                    prefix.length\n                );\n            });\n        }\n    };\n\n    return (\n        <textarea\n            ref={ref}\n            disabled={disabled}\n            value={getDisplayValue()}\n            onChange={handleChange}\n            onKeyDown={handleKeyDown}\n            readOnly={readOnly}\n            className={clsx(\n                styles.element,\n                (readOnly && styles.elementReadOnly) ||\n                    (disabled && styles.elementDisabled) ||\n                    (error && styles.elementError),\n                className\n            )}\n            rows={rows}\n            maxLength={\n                prefix && maxLength ? prefix.length + maxLength : maxLength\n            }\n            {...otherProps}\n        />\n    );\n};\n\nexport const TextareaBase = React.forwardRef(TextareaBaseComponent);\n\n// =============================================================================\n// MODULE COMPONENT (comes with the counter)\n// =============================================================================\n\nconst TextareaComponent = (\n    {\n        value,\n        disabled,\n        rows = 5,\n        onChange,\n        transformValue,\n        prefix,\n        maxLength,\n        renderCustomCounter,\n        ...otherProps\n    }: TextareaProps,\n    ref: TextareaRef\n) => {\n    // -------------------------------------------------------------------------\n    // CONST, STATE, REF\n    // -------------------------------------------------------------------------\n    const [stateValue, setStateValue] = useState<\n        string | number | readonly string[] | undefined\n    >(value);\n\n    // -------------------------------------------------------------------------\n    // EFFECTS\n    // -------------------------------------------------------------------------\n    useEffect(() => {\n        setStateValue(value);\n    }, [value]);\n\n    // -------------------------------------------------------------------------\n    // EVENT HANDLER\n    // -------------------------------------------------------------------------\n    const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {\n        const newValue = event.target.value;\n        setStateValue(newValue);\n        if (onChange) onChange(event);\n    };\n\n    // -------------------------------------------------------------------------\n    // RENDER FUNCTIONS\n    // -------------------------------------------------------------------------\n    return (\n        <div className={styles.wrapper}>\n            <TextareaBase\n                ref={ref}\n                disabled={disabled}\n                value={stateValue}\n                rows={rows || 5}\n                onChange={handleChange}\n                prefix={prefix}\n                transformValue={transformValue}\n                maxLength={maxLength}\n                {...otherProps}\n            />\n            {maxLength && (\n                <TextareaCounter\n                    value={stateValue}\n                    maxLength={maxLength}\n                    renderCustomCounter={renderCustomCounter}\n                />\n            )}\n        </div>\n    );\n};\n\nexport const Textarea = React.forwardRef(TextareaComponent);\n"],"names":["TextareaBase","React","forwardRef","_a","ref","className","disabled","error","maxLength","onChange","prefix","readOnly","rows","transformValue","value","otherProps","__rest","stateValue","setStateValue","useState","useEffect","_jsx","Object","assign","event","newValue","target","startsWith","trimStart","length","selectionStart","preventDefault","userInput","slice","transformedValue","syntheticEvent","onKeyDown","currentTarget","key","requestAnimationFrame","setSelectionRange","clsx","styles.element","styles.elementReadOnly","styles.elementDisabled","styles.elementError","Textarea","renderCustomCounter","_jsxs","styles.wrapper","children","TextareaCounter"],"mappings":"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"}
+{"version":3,"file":"textarea.js","sources":["../../src/input-textarea/textarea.tsx"],"sourcesContent":["import clsx from \"clsx\";\nimport React, { useEffect, useState } from \"react\";\n\nimport * as styles from \"./textarea.styles\";\nimport { TextareaCounter } from \"./textarea-counter\";\nimport type { TextareaProps, TextareaRef } from \"./types\";\n\n// =============================================================================\n// BASE COMPONENT\n// =============================================================================\nconst TextareaBaseComponent = (\n    {\n        className,\n        disabled,\n        error,\n        maxLength,\n        onChange,\n        prefix,\n        readOnly,\n        rows = 5,\n        transformValue,\n        value,\n        ...otherProps\n    }: TextareaProps,\n    ref: TextareaRef\n) => {\n    const [stateValue, setStateValue] = useState(value);\n\n    useEffect(() => {\n        setStateValue(value);\n    }, [value]);\n\n    const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {\n        let newValue = event.target.value;\n        if (prefix) {\n            // Ensure prefix is always present\n            if (!newValue.startsWith(prefix)) {\n                newValue = prefix + newValue.trimStart();\n            }\n\n            // Prevent deleting the prefix\n            if (newValue.length < prefix.length) {\n                newValue = prefix;\n            }\n\n            const cursorPosition = event.target.selectionStart || 0;\n\n            // Ensure backspace does not delete the prefix\n            if (cursorPosition < prefix.length) {\n                event.preventDefault();\n                return;\n            }\n\n            // Extract user input\n            const userInput = newValue.slice(prefix.length);\n\n            // Transform the input if needed\n            const transformedValue = transformValue\n                ? transformValue(userInput)\n                : userInput;\n\n            // Update state and input field\n            setStateValue(transformedValue);\n            event.target.value = prefix + transformedValue;\n\n            // Pass only the user input (without prefix) to `onChange`\n            if (onChange) {\n                const syntheticEvent = {\n                    ...event,\n                    target: { ...event.target, value: transformedValue },\n                };\n                onChange(\n                    syntheticEvent as React.ChangeEvent<HTMLTextAreaElement>\n                );\n            }\n        } else {\n            const transformedValue = transformValue\n                ? transformValue(newValue ?? \"\")\n                : newValue;\n\n            setStateValue(transformedValue);\n            event.target.value = transformedValue;\n            if (onChange) onChange(event);\n        }\n    };\n\n    const getDisplayValue = () => {\n        return prefix ? prefix + (stateValue ?? \"\") : stateValue;\n    };\n\n    const handleKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {\n        if (!prefix) return;\n\n        const { selectionStart } = event.currentTarget;\n\n        // Prevent backspace in prefix\n        if (event.key === \"Backspace\" && selectionStart <= prefix.length) {\n            event.preventDefault();\n        }\n\n        // Prevent left arrow from moving into prefix\n        if (event.key === \"ArrowLeft\" && selectionStart <= prefix.length) {\n            event.preventDefault();\n        }\n\n        // Prevent \"Home\" key from moving cursor to beginning\n        if (event.key === \"Home\") {\n            event.preventDefault();\n            requestAnimationFrame(() => {\n                event.currentTarget.setSelectionRange(\n                    prefix.length,\n                    prefix.length\n                );\n            });\n        }\n    };\n\n    return (\n        <textarea\n            ref={ref}\n            disabled={disabled}\n            value={getDisplayValue()}\n            onChange={handleChange}\n            onKeyDown={handleKeyDown}\n            readOnly={readOnly}\n            className={clsx(\n                styles.element,\n                (readOnly && styles.elementReadOnly) ||\n                    (disabled && styles.elementDisabled) ||\n                    (error && styles.elementError),\n                className\n            )}\n            rows={rows}\n            maxLength={\n                prefix && maxLength ? prefix.length + maxLength : maxLength\n            }\n            {...otherProps}\n        />\n    );\n};\n\nexport const TextareaBase = React.forwardRef(TextareaBaseComponent);\n\n// =============================================================================\n// MODULE COMPONENT (comes with the counter)\n// =============================================================================\n\nconst TextareaComponent = (\n    {\n        value,\n        disabled,\n        rows = 5,\n        onChange,\n        transformValue,\n        prefix,\n        maxLength,\n        renderCustomCounter,\n        ...otherProps\n    }: TextareaProps,\n    ref: TextareaRef\n) => {\n    // -------------------------------------------------------------------------\n    // CONST, STATE, REF\n    // -------------------------------------------------------------------------\n    const [stateValue, setStateValue] = useState<\n        string | number | readonly string[] | undefined\n    >(value);\n\n    // -------------------------------------------------------------------------\n    // EFFECTS\n    // -------------------------------------------------------------------------\n    useEffect(() => {\n        setStateValue(value);\n    }, [value]);\n\n    // -------------------------------------------------------------------------\n    // EVENT HANDLER\n    // -------------------------------------------------------------------------\n    const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {\n        const newValue = event.target.value;\n        setStateValue(newValue);\n        if (onChange) onChange(event);\n    };\n\n    // -------------------------------------------------------------------------\n    // RENDER FUNCTIONS\n    // -------------------------------------------------------------------------\n    return (\n        <div className={styles.wrapper}>\n            <TextareaBase\n                ref={ref}\n                disabled={disabled}\n                value={stateValue}\n                rows={rows || 5}\n                onChange={handleChange}\n                prefix={prefix}\n                transformValue={transformValue}\n                maxLength={maxLength}\n                {...otherProps}\n            />\n            {maxLength && (\n                <TextareaCounter\n                    value={stateValue}\n                    maxLength={maxLength}\n                    renderCustomCounter={renderCustomCounter}\n                />\n            )}\n        </div>\n    );\n};\n\n/**\n * A multi-line text input with an optional character counter and prefix.\n */\nexport const Textarea = React.forwardRef(TextareaComponent);\n"],"names":["TextareaBase","React","forwardRef","_a","ref","className","disabled","error","maxLength","onChange","prefix","readOnly","rows","transformValue","value","otherProps","__rest","stateValue","setStateValue","useState","useEffect","_jsx","Object","assign","event","newValue","target","startsWith","trimStart","length","selectionStart","preventDefault","userInput","slice","transformedValue","syntheticEvent","onKeyDown","currentTarget","key","requestAnimationFrame","setSelectionRange","clsx","styles.element","styles.elementReadOnly","styles.elementDisabled","styles.elementError","Textarea","renderCustomCounter","_jsxs","styles.wrapper","children","TextareaCounter"],"mappings":"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"}

package/input-textarea/types.d.ts

@@ -1,11 +1,34 @@
 import type React from "react";
+/**
+ * Props for the `Textarea` component.
+ */
 export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Renders the input in an error state. */
     error?: boolean | undefined;
     "data-testid"?: string | undefined;
+    /**
+     * Transforms user input on every change event.
+     */
     transformValue?: ((value: string) => string) | undefined;
+    /**
+     * A read-only string permanently displayed at the start of the textarea.
+     */
     prefix?: string | undefined;
+    /**
+     * Replaces the built-in character counter displayed below the textarea.
+     * Called only when `maxLength` is provided.
+     *
+     * @param maxLength The maximum number of user-input characters allowed.
+     * @param currentValueLength The current length of the user's input.
+     */
     renderCustomCounter?: ((maxLength: number, currentValueLength: number) => JSX.Element) | undefined;
 }
-/** To be exposed for Form component inheritance */
+/**
+ * A subset of `TextareaProps` used by form components that manage
+ * the `error` state themselves.
+ */
 export type TextareaPartialProps = Omit<TextareaProps, "error">;
+/**
+ * Ref type for programmatic access to the underlying `HTMLTextAreaElement`.
+ */
 export type TextareaRef = React.Ref<HTMLTextAreaElement>;

package/language-switcher/language-switcher.d.ts

@@ -1,2 +1,8 @@
 import type { LanguageSwitcherProps } from "./types";
+/**
+ * A locale-switching control that lets users change the active display language.
+ *
+ * Use `LanguageSwitcher` to surface supported languages as either
+ * a compact dropdown or a set of inline links.
+ */
 export declare const LanguageSwitcher: ({ variant, selectedLanguage, onSelectLanguage, "data-testid": testId, ...otherProps }: LanguageSwitcherProps) => JSX.Element;

package/language-switcher/language-switcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"language-switcher.js","sources":["../../src/language-switcher/language-switcher.tsx"],"sourcesContent":["import { announce } from \"@react-aria/live-announcer\";\n\nimport { LANGUAGE_DISPLAY_MAP } from \"./data\";\nimport { DropdownVariant } from \"./dropdown-variant\";\nimport { LinkContainerVariant } from \"./link-container-variant\";\nimport type { LanguageSwitcherCode, LanguageSwitcherProps } from \"./types\";\n\nexport const LanguageSwitcher = ({\n    variant = \"dropdown\",\n    selectedLanguage = \"en\",\n    onSelectLanguage,\n    \"data-testid\": testId = \"language-switcher\",\n    ...otherProps\n}: LanguageSwitcherProps): JSX.Element => {\n    // =========================================================================\n    // EVENT HANDLERS\n    // =========================================================================\n    const handleSelectLanguage = (code: LanguageSwitcherCode) => {\n        if (code !== selectedLanguage && onSelectLanguage) {\n            onSelectLanguage(code);\n            announce(`${LANGUAGE_DISPLAY_MAP[code]} selected`, \"polite\");\n        }\n    };\n\n    // =========================================================================\n    // RENDER\n    // =========================================================================\n    switch (variant) {\n        case \"dropdown\":\n            return (\n                <DropdownVariant\n                    selectedLanguage={selectedLanguage}\n                    onSelectLanguage={handleSelectLanguage}\n                    testId={testId}\n                    {...otherProps}\n                />\n            );\n        case \"link-container\":\n            return (\n                <LinkContainerVariant\n                    selectedLanguage={selectedLanguage}\n                    onSelectLanguage={handleSelectLanguage}\n                    testId={testId}\n                    {...otherProps}\n                />\n            );\n    }\n};\n"],"names":["LanguageSwitcher","_a","variant","selectedLanguage","onSelectLanguage","testId","otherProps","__rest","handleSelectLanguage","code","announce","LANGUAGE_DISPLAY_MAP","_jsx","DropdownVariant","LinkContainerVariant"],"mappings":"yTAOO,MAAMA,EAAoBC,QAAAC,QAC7BA,EAAU,WAAUC,iBACpBA,EAAmB,KAAIC,iBACvBA,EACA,cAAeC,EAAS,qBAAmBJ,EACxCK,EAAUC,EAAAN,EALgB,iEAU7B,MAAMO,EAAwBC,IACtBA,IAASN,GAAoBC,IAC7BA,EAAiBK,GACjBC,EAAS,GAAGC,EAAqBF,cAAkB,UACvD,EAMJ,OAAQP,GACJ,IAAK,WACD,OACIU,EAACC,iBACGV,iBAAkBA,EAClBC,iBAAkBI,EAClBH,OAAQA,GACJC,IAGhB,IAAK,iBACD,OACIM,EAACE,iBACGX,iBAAkBA,EAClBC,iBAAkBI,EAClBH,OAAQA,GACJC"}
+{"version":3,"file":"language-switcher.js","sources":["../../src/language-switcher/language-switcher.tsx"],"sourcesContent":["import { announce } from \"@react-aria/live-announcer\";\n\nimport { LANGUAGE_DISPLAY_MAP } from \"./data\";\nimport { DropdownVariant } from \"./dropdown-variant\";\nimport { LinkContainerVariant } from \"./link-container-variant\";\nimport type { LanguageSwitcherCode, LanguageSwitcherProps } from \"./types\";\n\n/**\n * A locale-switching control that lets users change the active display language.\n *\n * Use `LanguageSwitcher` to surface supported languages as either\n * a compact dropdown or a set of inline links.\n */\nexport const LanguageSwitcher = ({\n    variant = \"dropdown\",\n    selectedLanguage = \"en\",\n    onSelectLanguage,\n    \"data-testid\": testId = \"language-switcher\",\n    ...otherProps\n}: LanguageSwitcherProps): JSX.Element => {\n    // =========================================================================\n    // EVENT HANDLERS\n    // =========================================================================\n    const handleSelectLanguage = (code: LanguageSwitcherCode) => {\n        if (code !== selectedLanguage && onSelectLanguage) {\n            onSelectLanguage(code);\n            announce(`${LANGUAGE_DISPLAY_MAP[code]} selected`, \"polite\");\n        }\n    };\n\n    // =========================================================================\n    // RENDER\n    // =========================================================================\n    switch (variant) {\n        case \"dropdown\":\n            return (\n                <DropdownVariant\n                    selectedLanguage={selectedLanguage}\n                    onSelectLanguage={handleSelectLanguage}\n                    testId={testId}\n                    {...otherProps}\n                />\n            );\n        case \"link-container\":\n            return (\n                <LinkContainerVariant\n                    selectedLanguage={selectedLanguage}\n                    onSelectLanguage={handleSelectLanguage}\n                    testId={testId}\n                    {...otherProps}\n                />\n            );\n    }\n};\n"],"names":["LanguageSwitcher","_a","variant","selectedLanguage","onSelectLanguage","testId","otherProps","__rest","handleSelectLanguage","code","announce","LANGUAGE_DISPLAY_MAP","_jsx","DropdownVariant","LinkContainerVariant"],"mappings":"yTAaO,MAAMA,EAAoBC,QAAAC,QAC7BA,EAAU,WAAUC,iBACpBA,EAAmB,KAAIC,iBACvBA,EACA,cAAeC,EAAS,qBAAmBJ,EACxCK,EAAUC,EAAAN,EALgB,iEAU7B,MAAMO,EAAwBC,IACtBA,IAASN,GAAoBC,IAC7BA,EAAiBK,GACjBC,EAAS,GAAGC,EAAqBF,cAAkB,UACvD,EAMJ,OAAQP,GACJ,IAAK,WACD,OACIU,EAACC,iBACGV,iBAAkBA,EAClBC,iBAAkBI,EAClBH,OAAQA,GACJC,IAGhB,IAAK,iBACD,OACIM,EAACE,iBACGX,iBAAkBA,EAClBC,iBAAkBI,EAClBH,OAAQA,GACJC"}

package/language-switcher/types.d.ts

@@ -1,9 +1,32 @@
 import type React from "react";
+/** Code identifying a supported display language. */
 export type LanguageSwitcherCode = "en" | "zh" | "ms" | "ta";
+/**
+ * Presentation mode for the language switcher control.
+ *
+ * - `"dropdown"` renders a compact select control.
+ * - `"link-container"` renders languages as inline links.
+ */
 export type LanguageSwitcherVariant = "dropdown" | "link-container";
+/** Props for the `LanguageSwitcher` component. */
 export interface LanguageSwitcherProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Presentation mode.
+     *
+     * @default "dropdown"
+     */
     variant?: LanguageSwitcherVariant | undefined;
+    /**
+     * The currently active language code.
+     *
+     * @default "en"
+     */
     selectedLanguage?: LanguageSwitcherCode | undefined;
+    /**
+     * Called when the user selects a language different from `selectedLanguage`.
+     *
+     * @param language The newly selected language code.
+     */
     onSelectLanguage?: ((language: LanguageSwitcherCode) => void) | undefined;
     "data-testid"?: string | undefined;
 }

package/layout/index.d.ts

@@ -1,7 +1,21 @@
+/**
+ * A set of structural layout primitives for composing page regions.
+ *
+ * Use `Layout` sub-components to establish full-width page sections, centred
+ * content areas, and responsive grid columns. Sub-components:
+ * - `Layout.ColDiv` — a `<div>` that occupies a responsive column span within a grid `Container`.
+ * - `Layout.Container` — a flex or grid layout wrapper constrained to the content width.
+ * - `Layout.Content` — the primary content block, composes of `Section` + `Container`. Use `Section` and `Container` directly for more granular control.
+ * - `Layout.Section` — a full-width semantic `<section>` page region.
+ */
 export declare const Layout: {
+    /** Renders a `<div>` that occupies a responsive column span within a grid `Container`. */
+    ColDiv: (props: import("./types").ColDivProps & import("react").RefAttributes<HTMLDivElement>) => React.ReactElement | null;
+    /** Renders a flex or grid layout wrapper constrained to the content width. */
     Container: (props: import("./types").ContainerProps & import("react").RefAttributes<HTMLDivElement>) => React.ReactElement | null;
-    Section: (props: import("./types").SectionProps & import("react").RefAttributes<HTMLDivElement>) => React.ReactElement | null;
+    /** The primary content block — composes a `Section` with an inner `Container`. */
     Content: (props: import("./types").ContentProps & import("react").RefAttributes<HTMLDivElement>) => React.ReactElement | null;
-    ColDiv: (props: import("./types").ColDivProps & import("react").RefAttributes<HTMLDivElement>) => React.ReactElement | null;
+    /** Renders a full-width semantic `<section>` page region. */
+    Section: (props: import("./types").SectionProps & import("react").RefAttributes<HTMLDivElement>) => React.ReactElement | null;
 };
 export * from "./types";

package/layout/index.js

@@ -1,2 +1,2 @@
-import{ColDiv as o}from"./col-div.js";import{Container as t}from"./container.js";import{Content as n}from"./content.js";import{Section as r}from"./section.js";const i={Container:t,Section:r,Content:n,ColDiv:o};export{i as Layout};
+import{ColDiv as o}from"./col-div.js";import{Container as t}from"./container.js";import{Content as n}from"./content.js";import{Section as r}from"./section.js";const i={ColDiv:o,Container:t,Content:n,Section:r};export{i as Layout};
 //# sourceMappingURL=index.js.map

package/layout/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/layout/index.ts"],"sourcesContent":["import { ColDiv } from \"./col-div\";\nimport { Container } from \"./container\";\nimport { Content } from \"./content\";\nimport { Section } from \"./section\";\n\nexport const Layout = {\n    Container,\n    Section,\n    Content,\n    ColDiv,\n};\n\nexport * from \"./types\";\n"],"names":["Layout","Container","Section","Content","ColDiv"],"mappings":"+JAKO,MAAMA,EAAS,CAClBC,YACAC,UACAC,UACAC"}
+{"version":3,"file":"index.js","sources":["../../src/layout/index.ts"],"sourcesContent":["import { ColDiv } from \"./col-div\";\nimport { Container } from \"./container\";\nimport { Content } from \"./content\";\nimport { Section } from \"./section\";\n\n/**\n * A set of structural layout primitives for composing page regions.\n *\n * Use `Layout` sub-components to establish full-width page sections, centred\n * content areas, and responsive grid columns. Sub-components:\n * - `Layout.ColDiv` — a `<div>` that occupies a responsive column span within a grid `Container`.\n * - `Layout.Container` — a flex or grid layout wrapper constrained to the content width.\n * - `Layout.Content` — the primary content block, composes of `Section` + `Container`. Use `Section` and `Container` directly for more granular control.\n * - `Layout.Section` — a full-width semantic `<section>` page region.\n */\nexport const Layout = {\n    /** Renders a `<div>` that occupies a responsive column span within a grid `Container`. */\n    ColDiv,\n    /** Renders a flex or grid layout wrapper constrained to the content width. */\n    Container,\n    /** The primary content block — composes a `Section` with an inner `Container`. */\n    Content,\n    /** Renders a full-width semantic `<section>` page region. */\n    Section,\n};\n\nexport * from \"./types\";\n"],"names":["Layout","ColDiv","Container","Content","Section"],"mappings":"+JAeO,MAAMA,EAAS,CAElBC,SAEAC,YAEAC,UAEAC"}