@utilitywarehouse/hearth-react-native 0.36.1 → 0.36.3

package/build/components/Card/CardAction/CardAction.props.d.ts

@@ -2,20 +2,37 @@ import { ComponentType, ReactNode } from 'react';
 import type { PressableProps, ViewProps } from 'react-native';
 import { IconContainerProps } from '../../IconContainer';
 export interface CardActionBaseProps extends Omit<PressableProps, 'children'> {
+    /** Shows a loading skeleton in place of the content. */
     loading?: boolean;
+    /** Disables interaction with the action. */
     disabled?: boolean;
+    /** Size of the heading text.
+     * @default 'md'
+     */
     size?: 'md' | 'lg';
 }
 export interface CardActionContentProps {
+    /** Main heading text; required unless `children` is used. */
     heading: string;
+    /** Secondary text shown below the heading. */
     helperText?: string;
+    /** Badge rendered alongside the action. */
     badge?: ReactNode;
+    /** Position of the badge relative to the heading and helper text.
+     * @default 'bottom'
+     */
     badgePosition?: 'bottom' | 'middle' | 'right' | 'top';
+    /** Wraps the leading icon in a styled container.
+     * @default true
+     */
     iconContainer?: boolean;
+    /** Visual variant of the icon container. */
     iconContainerVariant?: IconContainerProps['variant'];
+    /** Semantic colour family used for the icon container's surface. */
     iconContainerColor?: IconContainerProps['color'];
 }
 export interface CardActionWithChildren extends CardActionBaseProps {
+    /** Custom content rendered in place of the built-in heading, helper text, and icon slots. */
     children: ViewProps['children'];
     heading?: never;
     helperText?: never;
@@ -31,12 +48,14 @@ export interface CardActionWithChildren extends CardActionBaseProps {
 }
 type CardActionWithLeadingContent = CardActionBaseProps & CardActionContentProps & {
     children?: never;
+    /** Custom content displayed at the start of the action, typically an icon. */
     leadingContent: ViewProps['children'];
     leadingIcon?: never;
 };
 type CardActionWithLeadingIcon = CardActionBaseProps & CardActionContentProps & {
     children?: never;
     leadingContent?: never;
+    /** Icon displayed at the start of the action. */
     leadingIcon: ComponentType;
 };
 type CardActionWithNoLeading = CardActionBaseProps & CardActionContentProps & {
@@ -46,11 +65,15 @@ type CardActionWithNoLeading = CardActionBaseProps & CardActionContentProps & {
 };
 type CardActionLeadingVariants = CardActionWithLeadingContent | CardActionWithLeadingIcon | CardActionWithNoLeading;
 type CardActionWithTrailingContent = CardActionLeadingVariants & {
+    /** Custom content displayed at the end of the action, typically an icon. */
     trailingContent: ViewProps['children'];
     trailingIcon?: never;
 };
 type CardActionWithTrailingIcon = CardActionLeadingVariants & {
     trailingContent?: never;
+    /** Icon displayed at the end of the action.
+     * @default ChevronRightSmallIcon
+     */
     trailingIcon: ComponentType;
 };
 type CardActionWithNoTrailing = CardActionLeadingVariants & {

package/build/components/Card/CardPressHandler.d.ts

@@ -1,8 +1,13 @@
 import { PropsWithChildren } from 'react';
+interface CardPressHandlerOwnProps {
+    /** The handler to inherit from the child component when the `Card` is pressed. */
+    handlerToInherit?: string;
+}
+/**
+ * Wraps a child component so it inherits the `Card`'s pressed state, letting the child show an active appearance when the `Card` is pressed.
+ */
 declare const CardPressHandler: {
-    ({ children }: PropsWithChildren<{
-        handlerToInherit?: string;
-    }>): import("react").JSX.Element;
+    ({ children }: PropsWithChildren<CardPressHandlerOwnProps>): import("react").JSX.Element;
     displayName: string;
 };
 export default CardPressHandler;

package/build/components/Card/CardPressHandler.js

@@ -2,6 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from 'react';
 import { useCardContext } from './Card.context';
 import { CardPressHandlerContext } from './CardPressHandler.context';
+/**
+ * Wraps a child component so it inherits the `Card`'s pressed state, letting the child show an active appearance when the `Card` is pressed.
+ */
 const CardPressHandler = ({ children }) => {
     const { pressed } = useCardContext();
     const context = useMemo(() => ({

package/build/components/Carousel/Carousel.d.ts

@@ -1,4 +1,7 @@
 import { CarouselProps } from './Carousel.props';
+/**
+ * Displays a horizontally scrollable series of `CarouselItem`s, such as images, articles, or products, with built-in pagination controls.
+ */
 declare const Carousel: {
     ({ centered, children, disabled, inactiveItemOpacity, itemWidth, onSnapToItem, showOverflow, style, width, itemsStyle, activeIndex: initialActiveIndex, showControls, showNavigation, controlsStyle, controlsItemStyle, controlsActiveItemStyle, controlsAccessibilityHidden, inverted, ref, ...props }: CarouselProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Carousel/Carousel.js

@@ -5,6 +5,9 @@ import { StyleSheet } from 'react-native-unistyles';
 import CarouselContext from './Carousel.context';
 import { CarouselControls } from './CarouselControls';
 import { CarouselItem } from './CarouselItem';
+/**
+ * Displays a horizontally scrollable series of `CarouselItem`s, such as images, articles, or products, with built-in pagination controls.
+ */
 const Carousel = ({ centered = false, children, disabled = false, inactiveItemOpacity = 1, itemWidth, onSnapToItem, showOverflow = false, style, width, itemsStyle, activeIndex: initialActiveIndex = 0, showControls = true, showNavigation = false, controlsStyle, controlsItemStyle, controlsActiveItemStyle, controlsAccessibilityHidden = true, inverted = false, ref, ...props }) => {
     const [activeIndex, setActiveIndex] = useState(initialActiveIndex);
     const [, setNumItems] = useState(0);

package/build/components/Carousel/Carousel.props.d.ts

@@ -26,24 +26,61 @@ export interface CarouselItemProps extends ViewProps {
     width?: number;
 }
 export interface CarouselProps extends Omit<FlatListProps<ReactElement<CarouselItemProps>>, 'accessibilityActions' | 'accessibilityLabel' | 'accessibilityRole' | 'accessible' | 'bounces' | 'children' | 'data' | 'decelerationRate' | 'getItemLayout' | 'horizontal' | 'pagingEnabled' | 'onAccessibilityAction' | 'onViewableItemsChanged' | 'overScrollMode' | 'renderItem' | 'showsHorizontalScrollIndicator' | 'snapToInterval' | 'snapToAlignment' | 'viewabilityConfig' | 'style'> {
+    /** Sets the initial active item index.
+     * @default 0
+     */
     activeIndex?: number;
+    /** Centers items within the viewport, revealing partial adjacent items when used with `itemWidth`.
+     * @default false
+     */
     centered?: boolean;
+    /** Disables scrolling and interaction with the carousel.
+     * @default false
+     */
     disabled?: boolean;
+    /** Opacity applied to items outside the active viewport, for use with `showOverflow`.
+     * @default 1
+     */
     inactiveItemOpacity?: number;
+    /** Width of each carousel item, if different from `width`. */
     itemWidth?: number;
+    /** Called each time a new item becomes active in the viewport. */
     onSnapToItem?: (index: number) => void;
+    /** Reveals items that sit outside the carousel viewport.
+     * @default false
+     */
     showOverflow?: boolean;
+    /** Width of the carousel viewport. */
     width: number;
+    /** The `CarouselItem` elements to render. */
     children?: ViewProps['children'];
+    /** Style applied to the scrollable list of items. */
     itemsStyle?: FlatListProps<ReactElement<CarouselItemProps>>['style'];
+    /** Style applied to the carousel's outer container. */
     style?: ViewStyle;
+    /** Shows the built-in pagination controls.
+     * @default true
+     */
     showControls?: boolean;
+    /** Shows previous/next navigation buttons in the controls.
+     * @default false
+     */
     showNavigation?: boolean;
+    /** Style applied to the pagination controls container. */
     controlsStyle?: ViewProps['style'];
+    /** Style applied to each pagination dot. */
     controlsItemStyle?: ViewProps['style'];
+    /** Style applied to the active pagination dot. */
     controlsActiveItemStyle?: ViewProps['style'];
+    /** Hides the pagination controls from screen readers.
+     * @default true
+     */
     controlsAccessibilityHidden?: boolean;
+    /** Forwarded ref exposing `scrollToIndex` and `scrollToOffset` methods. */
     ref?: React.Ref<CarouselRef>;
+    /** Inverts the carousel control colours, for use on brand-coloured backgrounds.
+     * @default false
+     */
     inverted?: boolean;
 }
 export interface CarouselProviderProps {

package/build/components/Center/Center.d.ts

@@ -1,4 +1,7 @@
 import BoxProps from '../Box/Box.props';
+/**
+ * Centers its children both horizontally and vertically, for building simple centered layouts.
+ */
 declare const Center: {
     ({ children, ...props }: BoxProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Center/Center.js

@@ -1,5 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Box } from '../Box';
+/**
+ * Centers its children both horizontally and vertically, for building simple centered layouts.
+ */
 const Center = ({ children, ...props }) => (_jsx(Box, { alignItems: "center", justifyContent: "center", ...props, children: children }));
 Center.displayName = 'Center';
 export default Center;

package/build/components/Checkbox/Checkbox.d.ts

@@ -9,6 +9,9 @@ declare const CheckboxIcon: import("react").ForwardRefExoticComponent<import("re
     forceMount?: boolean;
 }>;
 declare const CheckboxLabel: import("react").ForwardRefExoticComponent<import("react").RefAttributes<import("../Label/Label.props").default> & Omit<import("../Label/Label.props").default, "ref">>;
+/**
+ * Lets a user select one or more options from a list, with an optional label, helper text, and validation state.
+ */
 declare const Checkbox: {
     ({ children, label, disabled, checked, helperIcon, helperText, badge, invalidText, validText, validationStatus: validation, showValidationIcon, type, image, value, ...props }: CheckboxProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Checkbox/Checkbox.js

@@ -25,6 +25,9 @@ CheckboxGroup.displayName = 'CheckboxGroup';
 CheckboxIndicator.displayName = 'CheckboxIndicator';
 CheckboxIcon.displayName = 'CheckboxIcon';
 CheckboxLabel.displayName = 'CheckboxLabel';
+/**
+ * Lets a user select one or more options from a list, with an optional label, helper text, and validation state.
+ */
 const Checkbox = ({ children, label, disabled, checked, helperIcon, helperText, badge, invalidText, validText, validationStatus: validation, showValidationIcon, type = 'default', image, value, ...props }) => {
     const { validationStatus: fieldValidationStatus } = useFormFieldContext();
     const { validationStatus: groupValidationStatus, type: groupType } = useCheckboxGroupContext();

package/build/components/Checkbox/Checkbox.props.d.ts

@@ -1,18 +1,28 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { PressableProps, ViewProps } from 'react-native';
 type CheckboxBaseProps = {
+    /** Called with the new checked state when the checkbox is toggled. */
     onChange?: (isSelected: boolean) => void;
     disabled?: boolean;
+    /** The validation status of the checkbox. */
     validationStatus?: 'valid' | 'invalid' | 'initial';
+    /** The visual style of the checkbox.
+     * @default 'default'
+     */
     type?: 'default' | 'tile';
 } & ({
+    /** The value returned on form submission when the checkbox is checked. */
     value?: string | number | boolean;
+    /** Whether the checkbox is checked. */
     checked: boolean;
 } | {
+    /** The value returned on form submission when the checkbox is checked. */
     value: string | number | boolean;
+    /** Whether the checkbox is checked. */
     checked?: boolean;
 }) & Omit<PressableProps, 'children'>;
 type CheckboxWithChildrenProps = {
+    /** Custom content to render in place of the default label, helper text, and validation content. */
     children: ViewProps['children'];
     label?: never;
     helperText?: never;
@@ -25,13 +35,23 @@ type CheckboxWithChildrenProps = {
 } & CheckboxBaseProps;
 type CheckboxWithoutChildrenProps = {
     children?: never;
+    /** The label to display next to the checkbox. */
     label?: string;
+    /** The helper text to display below the checkbox. */
     helperText?: string;
+    /** The icon to display next to the helper text. */
     helperIcon?: ComponentType;
+    /** The badge to display below the helper text. */
     badge?: ReactNode;
+    /** The text to display below the checkbox when `validationStatus` is `'invalid'`. */
     invalidText?: string;
+    /** The text to display below the checkbox when `validationStatus` is `'valid'`. */
     validText?: string;
+    /** Whether to show the validation icon.
+     * @default true
+     */
     showValidationIcon?: boolean;
+    /** The image to display next to the label. */
     image?: ReactNode;
 } & CheckboxBaseProps;
 type CheckboxProps = CheckboxWithChildrenProps | CheckboxWithoutChildrenProps;

package/build/components/Checkbox/CheckboxGroup.d.ts

@@ -1,5 +1,8 @@
 import React from 'react';
 import CheckboxGroupProps from './CheckboxGroup.props';
+/**
+ * Groups multiple `Checkbox` components together, sharing a common label, helper text, and validation state.
+ */
 declare const CheckboxGroup: {
     ({ children, disabled, readonly, onChange, onValueChange, validationStatus, label, labelVariant, helperText, invalidText, validText, showValidationIcon, helperIcon, type, direction, gap, ...props }: CheckboxGroupProps): React.JSX.Element;
     displayName: string;

package/build/components/Checkbox/CheckboxGroup.js

@@ -7,6 +7,9 @@ import { Label } from '../Label';
 import { CheckboxGroup as CheckboxGroupComponent } from './Checkbox';
 import { CheckboxGroupContext } from './CheckboxGroup.context';
 import CheckboxGroupTextContent from './CheckboxGroupTextContent';
+/**
+ * Groups multiple `Checkbox` components together, sharing a common label, helper text, and validation state.
+ */
 const CheckboxGroup = ({ children, disabled, readonly, onChange, onValueChange, validationStatus, label, labelVariant = 'body', helperText, invalidText, validText, showValidationIcon = true, helperIcon, type, direction = 'column', gap, ...props }) => {
     const value = useMemo(() => ({ disabled, validationStatus, type, direction }), [disabled, validationStatus, type, direction]);
     const showHeader = !!label || !!helperText || !!invalidText || !!validText;

package/build/components/Checkbox/CheckboxGroup.props.d.ts

@@ -2,24 +2,48 @@ import { ComponentType } from 'react';
 import { ViewProps } from 'react-native';
 import { space } from '../../tokens';
 interface CheckboxGroupProps extends ViewProps {
+    /** Disables every checkbox in the group. */
     disabled?: boolean;
+    /** The selected values in the group. */
     value?: Array<string>;
+    /** Called with the full array of selected values when any checkbox in the group is checked or unchecked. */
     onValueChange?: (value: Array<string>) => void;
     /**
+     * Called with the full array of selected values when any checkbox in the group is checked or unchecked.
      * @deprecated Use `onValueChange` instead.
      */
     onChange?: (value: Array<string>) => void;
+    /** Marks every checkbox in the group as read-only. */
     readonly?: boolean;
+    /** The validation status of the checkbox group. */
     validationStatus?: 'valid' | 'invalid' | 'initial';
+    /** The label to display above the checkbox group. */
     label?: string;
+    /** The variant of the label text.
+     * @default 'body'
+     */
     labelVariant?: 'heading' | 'body';
+    /** The helper text to display below the checkbox group. */
     helperText?: string;
+    /** Whether to show the validation icon.
+     * @default true
+     */
     showValidationIcon?: boolean;
+    /** The text to display below the checkbox group when `validationStatus` is `'invalid'`. */
     invalidText?: string;
+    /** The text to display below the checkbox group when `validationStatus` is `'valid'`. */
     validText?: string;
+    /** The icon to display next to the helper text. */
     helperIcon?: ComponentType;
+    /** The type of checkbox rendered by the group's children.
+     * @default 'default'
+     */
     type?: 'default' | 'tile';
+    /** The layout direction of the checkboxes in the group.
+     * @default 'column'
+     */
     direction?: 'row' | 'column';
+    /** The gap between the checkbox group items. */
     gap?: keyof typeof space;
 }
 export default CheckboxGroupProps;

package/build/components/Combobox/Combobox.d.ts

@@ -1,5 +1,8 @@
 import React from 'react';
 import ComboboxProps from './Combobox.props';
+/**
+ * A searchable select field that opens a bottom sheet for choosing a single option from a list.
+ */
 declare const Combobox: {
     ({ options, value, onValueChange, inputValue, onInputValueChange, label, labelVariant, placeholder, searchPlaceholder, disabled, validationStatus, helperText, helperIcon, invalidText, validText, required, children, bottomSheetProps, menuHeading, noOptionsFoundText, listProps, loading, readonly, getValueLabel, filterOption, ...rest }: ComboboxProps): React.JSX.Element;
     displayName: string;

package/build/components/Combobox/Combobox.js

@@ -18,6 +18,9 @@ import { ComboboxContext } from './Combobox.context';
 import { defaultFilterOption } from './Combobox.utils';
 import ComboboxOption from './ComboboxOption';
 const DEFAULT_SNAP_POINTS = ['25%', '40%', '80%'];
+/**
+ * A searchable select field that opens a bottom sheet for choosing a single option from a list.
+ */
 const Combobox = ({ options = [], value, onValueChange, inputValue, onInputValueChange, label, labelVariant = 'body', placeholder = 'Search', searchPlaceholder = 'Search', disabled = false, validationStatus = 'initial', helperText, helperIcon, invalidText, validText, required = true, children, bottomSheetProps, menuHeading, noOptionsFoundText = 'No options found', listProps, loading = false, readonly = false, getValueLabel, filterOption, ...rest }) => {
     const formFieldContext = useFormFieldContext();
     const validationStatusFromContext = formFieldContext?.validationStatus ?? validationStatus;

package/build/components/Container/Container.d.ts

@@ -1,4 +1,7 @@
 import type ContainerProps from './Container.props';
+/**
+ * Applies the design system's responsive layout margin, padding, and spacing tokens to its content.
+ */
 declare const Container: {
     ({ style, children, spacing, space, ...props }: ContainerProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Container/Container.js

@@ -2,6 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { useStyleProps } from '../../hooks';
+/**
+ * Applies the design system's responsive layout margin, padding, and spacing tokens to its content.
+ */
 const Container = ({ style, children, spacing = 'md', space, ...props }) => {
     const { computedStyles, remainingProps } = useStyleProps(props);
     styles.useVariants({ spacing: space ?? spacing });

package/build/components/CurrencyInput/CurrencyInput.d.ts

@@ -1,4 +1,7 @@
 import type CurrencyInputProps from './CurrencyInput.props';
+/**
+ * An input specialised for entering monetary amounts, showing a currency symbol prefix and a decimal keypad where supported.
+ */
 declare const CurrencyInput: {
     ({ validationStatus, disabled, focused, readonly, placeholder, inBottomSheet, required, disableGroupSeparator, value, onChangeText, label, labelVariant, helperText, helperIcon, validText, invalidText, ref, ...rest }: CurrencyInputProps): import("react").JSX.Element;
     displayName: string;

package/build/components/CurrencyInput/CurrencyInput.js

@@ -4,6 +4,9 @@ import { StyleSheet } from 'react-native-unistyles';
 import { formatThousands } from '../../utils';
 import { DetailText } from '../DetailText';
 import { Input, InputField, InputSlot } from '../Input';
+/**
+ * An input specialised for entering monetary amounts, showing a currency symbol prefix and a decimal keypad where supported.
+ */
 const CurrencyInput = ({ validationStatus = 'initial', disabled, focused, readonly, placeholder, inBottomSheet = false, required = true, disableGroupSeparator = false, value, onChangeText, label, labelVariant = 'body', helperText, helperIcon, validText, invalidText, ref, ...rest }) => {
     const defaultFormat = '0.00';
     const getPlaceholder = placeholder ?? defaultFormat;

package/build/components/CurrencyInput/CurrencyInput.props.d.ts

@@ -1,21 +1,46 @@
 import type { Ref } from 'react';
 import type { TextInput, TextInputProps, ViewProps } from 'react-native';
 export interface CurrencyInputBaseProps {
+    /** Ref to the underlying text input. */
     ref?: Ref<TextInput>;
+    /** Disables the input.
+     * @default false
+     */
     disabled?: boolean;
+    /** Validation styling state.
+     * @default 'initial'
+     */
     validationStatus?: 'initial' | 'valid' | 'invalid';
+    /** Makes the input read-only.
+     * @default false
+     */
     readonly?: boolean;
+    /** Forces the focused visual state.
+     * @default false
+     */
     focused?: boolean;
     placeholder?: string;
+    /** Renders using `BottomSheetTextInput` for use inside a bottom sheet.
+     * @default false
+     */
     inBottomSheet?: boolean;
+    /** Whether the input is required. */
     required?: boolean;
     /** When not specifically disabled, the numeric value is automatically formatted with thousand separators (e.g. 1234 -> 1,234). */
     disableGroupSeparator?: boolean;
+    /** The label for the input. */
     label?: string;
+    /** The variant of the label text.
+     * @default 'body'
+     */
     labelVariant?: 'heading' | 'body';
+    /** Helper text to display below the input. */
     helperText?: string;
+    /** Icon to display alongside the helper text. */
     helperIcon?: React.ComponentType;
+    /** Text to display below the input when `validationStatus` is `'valid'`. */
     validText?: string;
+    /** Text to display below the input when `validationStatus` is `'invalid'`. */
     invalidText?: string;
 }
 export type CurrencyInputProps = CurrencyInputBaseProps & Omit<TextInputProps, 'children'> & ViewProps;

package/build/components/DateInput/DateInput.d.ts

@@ -1,4 +1,8 @@
 import type { DateInputProps } from './DateInput.props';
+/**
+ * Lets users enter a date manually across separate day, month, and year segments, with the option to show only the segments needed.
+ * Integrates with the design system's form field styling, validation states, and helper text.
+ */
 declare const DateInput: {
     ({ label, helperText, helperIcon, validationStatus, validText, invalidText, disabled, readonly, required, hideDay, hideMonth, hideYear, dayPlaceholder, monthPlaceholder, yearPlaceholder, dayValue, monthValue, yearValue, dayRef, monthRef, yearRef, onDayChange, onMonthChange, onYearChange, onDayFocus, onMonthFocus, onYearFocus, onDayBlur, onMonthBlur, onYearBlur, inputLabelStyle, inputContainerStyle, inputStyle, ...props }: DateInputProps): import("react").JSX.Element;
     displayName: string;

package/build/components/DateInput/DateInput.js

@@ -3,6 +3,10 @@ import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { FormField } from '../FormField';
 import DateInputSegment from './DateInputSegment';
+/**
+ * Lets users enter a date manually across separate day, month, and year segments, with the option to show only the segments needed.
+ * Integrates with the design system's form field styling, validation states, and helper text.
+ */
 const DateInput = ({ label, helperText, helperIcon, validationStatus = 'initial', validText, invalidText, disabled, readonly, required, hideDay = false, hideMonth = false, hideYear = false, dayPlaceholder = 'DD', monthPlaceholder = 'MM', yearPlaceholder = 'YYYY', dayValue, monthValue, yearValue, dayRef, monthRef, yearRef, onDayChange, onMonthChange, onYearChange, onDayFocus, onMonthFocus, onYearFocus, onDayBlur, onMonthBlur, onYearBlur, inputLabelStyle, inputContainerStyle, inputStyle, ...props }) => {
     return (_jsx(FormField, { label: label, helperText: helperText, helperIcon: helperIcon, validationStatus: validationStatus, validText: validText, invalidText: invalidText, disabled: disabled, readonly: readonly, required: required, style: styles.wrap, ...props, children: _jsxs(View, { style: styles.container, children: [!hideDay && (_jsx(DateInputSegment, { label: "Day", placeholder: dayPlaceholder, value: dayValue, inputRef: dayRef, onChange: onDayChange, onFocus: onDayFocus, onBlur: onDayBlur, disabled: disabled, required: required, readonly: readonly, validationStatus: validationStatus, maxLength: 2, testID: "date-input-day", inputContainerStyle: inputContainerStyle, inputStyle: inputStyle, inputLabelStyle: inputLabelStyle })), !hideMonth && (_jsx(DateInputSegment, { label: "Month", placeholder: monthPlaceholder, value: monthValue, inputRef: monthRef, onChange: onMonthChange, onFocus: onMonthFocus, onBlur: onMonthBlur, disabled: disabled, required: required, readonly: readonly, validationStatus: validationStatus, maxLength: 2, testID: "date-input-month", inputContainerStyle: inputContainerStyle, inputStyle: inputStyle, inputLabelStyle: inputLabelStyle })), !hideYear && (_jsx(DateInputSegment, { label: "Year", placeholder: yearPlaceholder, value: yearValue, inputRef: yearRef, onChange: onYearChange, onFocus: onYearFocus, onBlur: onYearBlur, disabled: disabled, required: required, readonly: readonly, validationStatus: validationStatus, maxLength: 4, testID: "date-input-year", inputContainerStyle: inputContainerStyle, inputStyle: inputStyle, inputLabelStyle: inputLabelStyle }))] }) }));
 };

package/build/components/DateInput/DateInput.props.d.ts

@@ -90,8 +90,11 @@ export interface DateInputProps extends FormFieldBaseProps {
      * Callback fired when the year segment loses focus.
      */
     onYearBlur?: TextInputProps['onBlur'];
+    /** Custom style for each input segment's container. */
     inputContainerStyle?: ViewProps['style'];
+    /** Custom style for each input segment's text input. */
     inputStyle?: ViewProps['style'];
+    /** Custom style for each input segment's label. */
     inputLabelStyle?: LabelProps['style'];
 }
 export interface DateInputSegmentProps {

package/build/components/DatePicker/DatePicker.context.d.ts

@@ -13,6 +13,7 @@ export interface DatePickerContextType extends DatePickerBaseProps {
     onSelectYear: (year: number) => void;
     onChangeMonth: (value: number) => void;
     onChangeYear: (value: number) => void;
+    onConfirm: () => void;
     closeDatePicker: () => void;
 }
 export declare const DatePickerContext: import("react").Context<DatePickerContextType>;

package/build/components/DatePicker/DatePicker.d.ts

@@ -1,19 +1,33 @@
 import type { DatePickerBaseProps, DateType, MultiChange, RangeChange, SingleChange } from './DatePicker.props';
 export interface DatePickerSingleProps extends DatePickerBaseProps {
+    /** Controls whether the picker returns a single date, a date range, or multiple dates. */
     mode: 'single';
+    /** The selected date, used in single mode. */
     date?: DateType;
+    /** Called after a selection changes. */
     onChange?: SingleChange;
 }
 export interface DatePickerRangeProps extends DatePickerBaseProps {
+    /** Controls whether the picker returns a single date, a date range, or multiple dates. */
     mode: 'range';
+    /** Start of the selected range, used in range mode. */
     startDate?: DateType;
+    /** End of the selected range, used in range mode. */
     endDate?: DateType;
+    /** Called after a selection changes. */
     onChange?: RangeChange;
 }
 export interface DatePickerMultipleProps extends DatePickerBaseProps {
+    /** Controls whether the picker returns a single date, a date range, or multiple dates. */
     mode: 'multiple';
+    /** The selected dates, used in multiple mode. */
     dates?: DateType[];
+    /** Called after a selection changes. */
     onChange?: MultiChange;
 }
+/**
+ * Presents a calendar in a bottom sheet so people can choose a single date, a date range, or multiple dates without leaving the current screen.
+ * Supports locale, time zone, and availability rules such as enabled, disabled, minimum, and maximum dates.
+ */
 declare const DateTimePicker: (props: DatePickerSingleProps | DatePickerRangeProps | DatePickerMultipleProps) => import("react").JSX.Element;
 export default DateTimePicker;

package/build/components/DatePicker/DatePicker.js

@@ -20,6 +20,10 @@ dayjs.extend(localizedFormat);
 dayjs.extend(utc);
 dayjs.extend(timezone);
 dayjs.extend(duration);
+/**
+ * Presents a calendar in a bottom sheet so people can choose a single date, a date range, or multiple dates without leaving the current screen.
+ * Supports locale, time zone, and availability rules such as enabled, disabled, minimum, and maximum dates.
+ */
 const DateTimePicker = (props) => {
     // eslint-disable-next-line @typescript-eslint/prefer-as-const
     const numerals = 'latn';
@@ -151,6 +155,9 @@ const DateTimePicker = (props) => {
     }, initialState);
     const stateRef = useRef(state);
     stateRef.current = state;
+    // Tracks whether a selection was made since the sheet last opened, so Ok doesn't
+    // re-emit onChange for a value it already just committed via onSelectDate.
+    const hasChangedRef = useRef(false);
     useEffect(() => {
         const newState = {
             ...initialState,
@@ -234,6 +241,7 @@ const DateTimePicker = (props) => {
         dispatch({ type: CalendarActionKind.SET_CALENDAR_VIEW, payload: view });
     }, []);
     const onSelectDate = useCallback((selectedDate) => {
+        hasChangedRef.current = true;
         if (onChange) {
             if (mode === 'single') {
                 const newDate = timePicker
@@ -332,6 +340,26 @@ const DateTimePicker = (props) => {
             }
         }
     }, [mode, timePicker, min, max, timeZone]);
+    const onConfirm = useCallback(() => {
+        if (!onChange || hasChangedRef.current)
+            return;
+        const current = stateRef.current;
+        if (mode === 'single' && current.date) {
+            onChange({ date: dayjs(current.date).toDate() });
+        }
+        else if (mode === 'range' && current.startDate) {
+            onChange({
+                startDate: dayjs(current.startDate).toDate(),
+                endDate: current.endDate ? dayjs(current.endDate).toDate() : current.endDate,
+            });
+        }
+        else if (mode === 'multiple' && current.dates?.length) {
+            onChange({
+                dates: current.dates.map(item => dayjs(item).toDate()),
+                change: 'updated',
+            });
+        }
+    }, [mode, onChange]);
     // set the active displayed month
     const onSelectMonth = useCallback((value) => {
         const currentMonth = dayjs(stateRef.current.currentDate).month();
@@ -445,6 +473,7 @@ const DateTimePicker = (props) => {
         onSelectYear,
         onChangeMonth,
         onChangeYear,
+        onConfirm,
         onCancel,
     }), [
         setCalendarView,
@@ -453,6 +482,7 @@ const DateTimePicker = (props) => {
         onSelectYear,
         onChangeMonth,
         onChangeYear,
+        onConfirm,
         onCancel,
     ]);
     const memoizedValue = useMemo(() => ({
@@ -462,6 +492,7 @@ const DateTimePicker = (props) => {
     }), [state, baseContextValue, handlerContextValue]);
     const handleChange = useCallback((index) => {
         if (index > -1) {
+            hasChangedRef.current = false;
             // Add a small delay to ensure the bottom sheet is fully rendered
             setTimeout(() => {
                 // Announce to screen readers