@utilitywarehouse/hearth-react-native 0.36.0 → 0.36.2

package/build/components/NavModal/NavModal.js

@@ -11,6 +11,14 @@ import { Button } from '../Button';
 import { Heading } from '../Heading';
 import { Spinner } from '../Spinner';
 import { UnstyledIconButton } from '../UnstyledIconButton';
+/**
+ * Use NavModal for the screen-based modal layout for React Navigation flows, when a screen
+ * is already presented with `presentation: 'modal'` or `presentation: 'fullScreenModal'`.
+ * Provides Hearth's modal structure and action buttons plus the Android close animation, but
+ * does not manage its own dismissal: your screen or navigator owns closing behavior. Use
+ * `Modal` instead for a bottom-sheet modal presented via a ref.
+ * @summary The screen-based modal layout for navigation flows.
+ */
 const NavModal = ({ ref, children, heading, description, showCloseButton = true, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, loading, loadingHeading = 'Loading...', loadingDescription, image, footer, footerStyle, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter = true, background = 'default', scrollable = true, presentation = 'modal', scrollViewProps, useSafeAreaInsets = true, ...props }) => {
     const theme = useTheme();
     const backgroundOpacity = useSharedValue(0);

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

@@ -5,11 +5,21 @@ export interface NavModalRef {
     triggerCloseAnimation?: () => void;
 }
 type NavModalBaseProps = ModalCommonBaseProps & {
+    /** Ref exposing `triggerCloseAnimation`, used to play the Android close animation before dismissal. */
     ref?: Ref<NavModalRef>;
+    /** Switches between the default surface background, the brand background, and the primary background treatment.
+     * @default 'default' */
     background?: 'default' | 'brand' | 'primary';
+    /** Wraps the content area in a `ScrollView`; set to `false` for custom layouts that should not scroll.
+     * @default true */
     scrollable?: boolean;
+    /** Matches the React Navigation screen presentation; `fullScreenModal` uses the full-screen layout, the other values use the sheet-style layout.
+     * @default 'modal' */
     presentation?: 'fullScreenModal' | 'modal' | 'transparentModal' | 'containedModal' | 'containedTransparentModal';
+    /** Whether to apply safe area insets as padding within the component.
+     * @default true */
     useSafeAreaInsets?: boolean;
+    /** Extra props forwarded to the `ScrollView` wrapping the modal content when `scrollable` is true. */
     scrollViewProps?: Omit<ScrollViewProps, 'children'>;
 };
 type NavModalProps = (NavModalBaseProps & ModalButtonFooterProps) | (NavModalBaseProps & ModalCustomFooterProps);

package/build/components/Pagination/Pagination.d.ts

@@ -1,4 +1,9 @@
 import type PaginationProps from './Pagination.props';
+/**
+ * Lets a user move between pages of content, rendering numbered page controls with next/previous
+ * (and optional first/last) buttons, or a condensed "Page X of Y" summary.
+ * @summary Page navigation controls for paged content.
+ */
 declare const Pagination: {
     ({ currentPage, totalPages, onPageChange, condensed, hideSkipButtons, style, ...props }: PaginationProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Pagination/Pagination.js

@@ -18,6 +18,11 @@ const PaginationItem = ({ label, selected = false, onPress }) => {
 const PaginationArrowButton = ({ accessibilityLabel, disabled, icon, onPress, }) => {
     return (_jsx(UnstyledIconButton, { accessibilityLabel: accessibilityLabel, disabled: disabled, icon: icon, onPress: onPress, size: "sm", style: styles.arrowButton }));
 };
+/**
+ * Lets a user move between pages of content, rendering numbered page controls with next/previous
+ * (and optional first/last) buttons, or a condensed "Page X of Y" summary.
+ * @summary Page navigation controls for paged content.
+ */
 const Pagination = ({ currentPage, totalPages, onPageChange, condensed = false, hideSkipButtons = false, style, ...props }) => {
     const pages = generatePageNumbers(currentPage, totalPages);
     const handleFirst = () => {

package/build/components/PillGroup/Pill.d.ts

@@ -1,4 +1,5 @@
 import type { PillProps } from './Pill.props';
+/** A selectable, pressable tag used inside a `PillGroup` for filtering or categorization. */
 export declare const Pill: import("react").ForwardRefExoticComponent<Omit<PillProps & {
     states?: {
         active?: boolean;

package/build/components/PillGroup/Pill.js

@@ -15,6 +15,7 @@ const PillRoot = ({ value, label, icon, states = {}, ...props }) => {
     };
     return (_jsxs(Pressable, { ...props, style: styles.pill, accessibilityRole: "button", accessibilityState: { selected: isSelected }, onPress: handlePress, children: [icon && _jsx(Icon, { as: icon, size: "sm", style: styles.icon }), _jsx(BodyText, { weight: "semibold", style: styles.text, children: label })] }));
 };
+/** A selectable, pressable tag used inside a `PillGroup` for filtering or categorization. */
 export const Pill = createPressable({ Root: PillRoot });
 Pill.displayName = 'Pill';
 const styles = StyleSheet.create(theme => ({

package/build/components/PillGroup/PillGroup.d.ts

@@ -1,4 +1,9 @@
 import type { PillGroupProps } from './PillGroup.props';
+/**
+ * Groups multiple `Pill` components together for filtering and categorization, controlling their
+ * layout and managing single- or multi-select state.
+ * @summary A container that groups and manages selection for `Pill` components.
+ */
 export declare const PillGroup: {
     ({ children, value, multiple, wrap, onChange, onValueChange, style, ...props }: PillGroupProps): import("react").JSX.Element;
     displayName: string;

package/build/components/PillGroup/PillGroup.js

@@ -4,6 +4,11 @@ import { ScrollView } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { Box } from '../Box';
 import { PillGroupContext } from './PillGroup.context';
+/**
+ * Groups multiple `Pill` components together for filtering and categorization, controlling their
+ * layout and managing single- or multi-select state.
+ * @summary A container that groups and manages selection for `Pill` components.
+ */
 export const PillGroup = ({ children, value, multiple = false, wrap = true, onChange, onValueChange, style, ...props }) => {
     const normalizedValue = Array.isArray(value) ? value : [value];
     const contextValue = useMemo(() => ({

package/build/components/ProgressBar/ProgressBar.d.ts

@@ -1,4 +1,9 @@
 import type ProgressBarProps from './ProgressBar.props';
+/**
+ * Communicates task completion for linear flows and bounded operations. Use the
+ * linear variant for inline layouts and the circular variant when space is tighter
+ * or when progress needs more emphasis.
+ */
 declare const ProgressBar: {
     ({ variant, colorScheme, size, value, min, max, label, hideLabel, formatValueText, "aria-valuetext": ariaValueText, accessibilityLabel, ...rest }: ProgressBarProps): import("react").JSX.Element;
     displayName: string;

package/build/components/ProgressBar/ProgressBar.js

@@ -13,6 +13,11 @@ const valueToPercent = (value, min, max) => {
         return 0;
     return ((value - min) / range) * 100;
 };
+/**
+ * Communicates task completion for linear flows and bounded operations. Use the
+ * linear variant for inline layouts and the circular variant when space is tighter
+ * or when progress needs more emphasis.
+ */
 const ProgressBar = ({ variant = 'linear', colorScheme = 'default', size = 'md', value, min = 0, max = 100, label, hideLabel, formatValueText, 'aria-valuetext': ariaValueText, accessibilityLabel, ...rest }) => {
     const effectiveValue = colorScheme === 'success' && !formatValueText ? max : clampValue(value, min, max);
     const percentValue = valueToPercent(effectiveValue, min, max);

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

@@ -3,6 +3,10 @@ export type ProgressBarVariant = 'linear' | 'circular';
 export type ProgressBarColorScheme = 'default' | 'success' | 'danger';
 export type ProgressBarSize = 'sm' | 'md';
 export interface ProgressBarProps extends ViewProps {
+    /**
+     * The progress bar variant.
+     * @default 'linear'
+     */
     variant?: ProgressBarVariant;
     /**
      * Set the visual appearance.

package/build/components/ProgressStepper/ProgressStep.d.ts

@@ -1,9 +1,22 @@
 import React from 'react';
 import { ProgressStepProps } from './ProgressStepper.props';
 interface ProgressStepInternalProps extends ProgressStepProps {
+    /**
+     * Zero-based position of the step within the sequence.
+     * @default 0
+     */
     index?: number;
+    /**
+     * Whether the step is the last one in the sequence.
+     * @default false
+     */
     isLast?: boolean;
 }
+/**
+ * Represents a single step within a ProgressStepper, showing whether it is
+ * complete, active, or incomplete. Rendered as a child of ProgressStepper
+ * rather than used on its own.
+ */
 declare const ProgressStep: {
     ({ status, index, isLast, ...rest }: ProgressStepInternalProps): React.JSX.Element;
     displayName: string;

package/build/components/ProgressStepper/ProgressStep.js

@@ -4,6 +4,11 @@ import { StyleSheet } from 'react-native-unistyles';
 import { TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
 import { Icon } from '../Icon';
 import { BodyText } from '../BodyText';
+/**
+ * Represents a single step within a ProgressStepper, showing whether it is
+ * complete, active, or incomplete. Rendered as a child of ProgressStepper
+ * rather than used on its own.
+ */
 const ProgressStep = ({ status, index = 0, isLast = false, ...rest }) => {
     styles.useVariants({ status, isLast });
     const renderStepNumber = () => {

package/build/components/ProgressStepper/ProgressStepper.d.ts

@@ -1,5 +1,10 @@
 import React from 'react';
 import ProgressStepperProps from './ProgressStepper.props';
+/**
+ * Displays a series of steps connected by lines, showing progress through a
+ * multi-step process. Use it to show which steps in a flow are complete,
+ * active, or still to come.
+ */
 declare const ProgressStepper: {
     ({ children, ...rest }: ProgressStepperProps): React.JSX.Element;
     displayName: string;

package/build/components/ProgressStepper/ProgressStepper.js

@@ -1,6 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo, Children, cloneElement, isValidElement } from 'react';
 import ProgressStepperRoot from './ProgressStepperRoot';
+/**
+ * Displays a series of steps connected by lines, showing progress through a
+ * multi-step process. Use it to show which steps in a flow are complete,
+ * active, or still to come.
+ */
 const ProgressStepper = ({ children, ...rest }) => {
     // Process children to add index and isLast props
     const processedChildren = useMemo(() => {

package/build/components/Radio/Radio.d.ts

@@ -9,6 +9,11 @@ declare const RadioIcon: import("react").ForwardRefExoticComponent<import("react
     forceMount?: boolean;
 }>;
 declare const RadioLabel: import("react").ForwardRefExoticComponent<import("react").RefAttributes<import("../Label/Label.props").default> & Omit<import("../Label/Label.props").default, "ref">>;
+/**
+ * Lets a user pick a single option from a set of mutually exclusive choices, rendered inside a
+ * `RadioGroup`. Use it for single-choice selection in forms or surveys.
+ * @summary A single-choice selection control for use inside a RadioGroup.
+ */
 declare const Radio: {
     ({ children, label, disabled, helperIcon, helperText, badge, invalidText, validText, validationStatus: validation, showValidationIcon, type, image, ...props }: RadioProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Radio/Radio.js

@@ -25,6 +25,11 @@ RadioGroup.displayName = 'RadioGroup';
 RadioIndicator.displayName = 'RadioIndicator';
 RadioIcon.displayName = 'RadioIcon';
 RadioLabel.displayName = 'RadioLabel';
+/**
+ * Lets a user pick a single option from a set of mutually exclusive choices, rendered inside a
+ * `RadioGroup`. Use it for single-choice selection in forms or surveys.
+ * @summary A single-choice selection control for use inside a RadioGroup.
+ */
 const Radio = ({ children, label, disabled, helperIcon, helperText, badge, invalidText, validText, validationStatus: validation, showValidationIcon, type = 'default', image, ...props }) => {
     const { validationStatus: fieldValidationStatus } = useFormFieldContext();
     const { validationStatus: groupValidationStatus, type: groupType } = useRadioGroupContext();

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

@@ -1,13 +1,22 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { PressableProps, ViewProps } from 'react-native';
 interface RadioBaseProps extends Omit<PressableProps, 'children'> {
+    /** The value to be used in the radio input, returned on form submission. */
     value: string;
+    /** Called when the state of the radio changes. */
     onChange?: (isSelected: boolean) => void;
+    /** Whether the radio is disabled. */
     disabled?: boolean;
+    /** The validation status of the radio. */
     validationStatus?: 'valid' | 'invalid' | 'initial';
+    /**
+     * The type of the radio.
+     * @default 'default'
+     */
     type?: 'default' | 'tile';
 }
 interface RadioWithChildrenProps extends RadioBaseProps {
+    /** Custom content rendered in place of the default label, helper text and validation content. */
     children: ViewProps['children'];
     label?: never;
     helperText?: never;
@@ -20,13 +29,21 @@ interface RadioWithChildrenProps extends RadioBaseProps {
 }
 interface RadioWithoutChildrenProps extends RadioBaseProps {
     children?: never;
+    /** The label to be displayed next to the radio. */
     label?: string;
+    /** The helper text to be displayed below the radio. */
     helperText?: string;
+    /** The icon to be displayed next to the helper text. */
     helperIcon?: ComponentType;
+    /** The badge to be displayed below the helper text. */
     badge?: ReactNode;
+    /** The invalid text to be displayed below the radio when `validationStatus` is `'invalid'`. */
     invalidText?: string;
+    /** The valid text to be displayed below the radio when `validationStatus` is `'valid'`. */
     validText?: string;
+    /** Whether to show the validation icon alongside the valid/invalid text. */
     showValidationIcon?: boolean;
+    /** The image to be displayed next to the label. */
     image?: ReactNode;
 }
 type RadioProps = RadioWithChildrenProps | RadioWithoutChildrenProps;

package/build/components/Radio/RadioGroup.d.ts

@@ -1,5 +1,10 @@
 import React from 'react';
 import RadioGroupProps from './RadioGroup.props';
+/**
+ * Groups a set of `Radio` (or `RadioTile`) options so only one can be selected at a time, and
+ * provides shared label, helper text and validation messaging for the group.
+ * @summary Groups Radio options into a single-choice set with shared validation.
+ */
 declare const RadioGroup: {
     ({ children, disabled, readonly, onChange, onValueChange, validationStatus, label, labelVariant, helperText, invalidText, validText, showValidationIcon, helperIcon, type, direction, gap, ...props }: RadioGroupProps): React.JSX.Element;
     displayName: string;

package/build/components/Radio/RadioGroup.js

@@ -7,6 +7,11 @@ import { Label } from '../Label';
 import { RadioGroup as RadioGroupComponent } from './Radio';
 import { RadioGroupContext } from './RadioGroup.context';
 import RadioGroupTextContent from './RadioGroupTextContent';
+/**
+ * Groups a set of `Radio` (or `RadioTile`) options so only one can be selected at a time, and
+ * provides shared label, helper text and validation messaging for the group.
+ * @summary Groups Radio options into a single-choice set with shared validation.
+ */
 const RadioGroup = ({ 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/Radio/RadioGroup.props.d.ts

@@ -2,24 +2,49 @@ import { ComponentType } from 'react';
 import { ViewProps } from 'react-native';
 import { space } from '../../tokens';
 interface RadioGroupProps extends ViewProps {
+    /** Whether to manually disable the radio group. */
     disabled?: boolean;
+    /** The value of the radio group. */
     value?: string;
+    /** Called when any child Radio is checked or unchecked. */
     onValueChange?: (value: string) => void;
     /**
+     * Called when any child Radio is checked or unchecked.
      * @deprecated Use `onValueChange` instead.
      */
     onChange?: (value: string) => void;
+    /** Whether the radio group is read-only. */
     readonly?: boolean;
+    /** The validation status of the radio group. */
     validationStatus?: 'valid' | 'invalid' | 'initial';
+    /** The label to be displayed above the radio group. */
     label?: string;
+    /**
+     * The variant of the label text.
+     * @default 'body'
+     */
     labelVariant?: 'heading' | 'body';
+    /** The helper text to be displayed below the radio group. */
     helperText?: string;
+    /**
+     * Whether to show the validation icon alongside the valid/invalid text.
+     * @default true
+     */
     showValidationIcon?: boolean;
+    /** The invalid text to be displayed below the radio group when `validationStatus` is `'invalid'`. */
     invalidText?: string;
+    /** The valid text to be displayed below the radio group when `validationStatus` is `'valid'`. */
     validText?: string;
+    /** The icon to be displayed next to the helper text. */
     helperIcon?: ComponentType;
+    /** The type of radio rendered by children of the group. */
     type?: 'default' | 'tile';
+    /**
+     * The layout direction of the radio group's children.
+     * @default 'column'
+     */
     direction?: 'row' | 'column';
+    /** The gap between the radio group items. */
     gap?: keyof typeof space;
 }
 export default RadioGroupProps;

package/build/components/RadioCard/RadioCard.d.ts

@@ -5,10 +5,20 @@ declare const RadioCardIcon: import("react").ForwardRefExoticComponent<import("r
     forceMount?: boolean;
 }>;
 declare const RadioCardLabel: import("react").ForwardRefExoticComponent<import("react").RefAttributes<import("../Label/Label.props").default> & Omit<import("../Label/Label.props").default, "ref">>;
+/**
+ * Groups a set of `RadioCard` options so only one can be selected at a time, laid out as a
+ * flexbox row/column or, when `columns` is set, a grid.
+ * @summary Groups RadioCard options into a single-choice set.
+ */
 declare const RadioCardGroup: {
     ({ onChange, onValueChange, disabled, ...props }: RadioCardGroupProps): import("react").JSX.Element;
     displayName: string;
 };
+/**
+ * A card-style single-choice selection control, rendered inside a `RadioCardGroup`. Use it when
+ * options need more visual weight or supporting content than a plain `Radio`.
+ * @summary A card-style single-choice selection control for use inside a RadioCardGroup.
+ */
 declare const RadioCard: {
     ({ children, label, labelVariant, contentStyle, ...props }: RadioCardProps): import("react").JSX.Element;
     displayName: string;

package/build/components/RadioCard/RadioCard.js

@@ -19,6 +19,11 @@ const RadioCardGroupComponent = RadioCardComponent.Group;
 const RadioCardIndicator = RadioCardComponent.Indicator;
 const RadioCardIcon = RadioCardComponent.Icon;
 const RadioCardLabel = RadioCardComponent.Label;
+/**
+ * Groups a set of `RadioCard` options so only one can be selected at a time, laid out as a
+ * flexbox row/column or, when `columns` is set, a grid.
+ * @summary Groups RadioCard options into a single-choice set.
+ */
 const RadioCardGroup = ({ onChange, onValueChange, disabled, ...props }) => (_jsx(RadioCardGroupComponent, { ...props, disabled: disabled, isDisabled: disabled, onChange: (value) => {
         onChange?.(value);
         onValueChange?.(value);
@@ -27,6 +32,11 @@ RadioCardGroup.displayName = 'RadioCardGroup';
 RadioCardIndicator.displayName = 'RadioCardIndicator';
 RadioCardIcon.displayName = 'RadioCardIcon';
 RadioCardLabel.displayName = 'RadioCardLabel';
+/**
+ * A card-style single-choice selection control, rendered inside a `RadioCardGroup`. Use it when
+ * options need more visual weight or supporting content than a plain `Radio`.
+ * @summary A card-style single-choice selection control for use inside a RadioCardGroup.
+ */
 const RadioCard = ({ children, label, labelVariant = 'body', contentStyle, ...props }) => {
     const { computedStyles } = useStyleProps(props);
     return (_jsxs(RadioCardComponent, { ...props, children: [_jsxs(View, { style: styles.radioContainer, children: [_jsx(RadioCardIndicator, { children: _jsx(RadioCardIcon, {}) }), !!label && _jsx(RadioCardLabel, { variant: labelVariant, children: label })] }), !!children && _jsx(View, { style: [computedStyles, contentStyle], children: children })] }));

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

@@ -2,16 +2,30 @@ import type { PressableProps, ViewStyle } from 'react-native';
 import { ViewProps } from 'react-native';
 import { SpaceValue } from '../../types';
 interface RadioCardProps extends Omit<PressableProps, 'children'> {
+    /** The value to be used in the radio card input, returned on form submission. */
     value: string;
+    /** Called when the state of the radio card changes. */
     onChange?: (isSelected: boolean) => void;
+    /** The content to be displayed inside the radio card. */
     children?: ViewProps['children'];
+    /** The label to be displayed next to the radio card. */
     label?: string;
+    /**
+     * The variant of the label text.
+     * @default 'body'
+     */
     labelVariant?: 'heading' | 'body';
+    /** Sets the direction of the flex items. */
     flexDirection?: ViewStyle['flexDirection'];
+    /** Sets whether flex items are forced onto one line or can wrap. */
     flexWrap?: ViewStyle['flexWrap'];
+    /** Sets the alignment of flex items on the cross axis. */
     alignItems?: ViewStyle['alignItems'];
+    /** Sets the alignment of flex items on the main axis. */
     justifyContent?: ViewStyle['justifyContent'];
+    /** Additional style applied to the `children` content wrapper. */
     contentStyle?: ViewStyle;
+    /** The gap between the indicator/label row and the `children` content. */
     gap?: SpaceValue;
 }
 export default RadioCardProps;

package/build/components/RadioCard/RadioCardGroup.d.ts

@@ -1,4 +1,8 @@
 import RadioCardGroupProps from './RadioCardGroup.props';
+/**
+ * Groups a set of `RadioCard` options so only one can be selected at a time, laid
+ * out as a flexbox row/column or, when `columns` is set, a grid.
+ */
 declare const RadioCardGroup: {
     ({ children, gap, style, flexDirection, flexWrap, justifyContent, alignItems, columns, disabled, isDisabled, ...props }: RadioCardGroupProps & {
         isDisabled?: boolean;

package/build/components/RadioCard/RadioCardGroup.js

@@ -4,6 +4,10 @@ import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { Grid } from '../Grid';
 import { RadioCardGroupContext } from './RadioCardGroup.context';
+/**
+ * Groups a set of `RadioCard` options so only one can be selected at a time, laid
+ * out as a flexbox row/column or, when `columns` is set, a grid.
+ */
 const RadioCardGroup = ({ children, gap = '200', style, flexDirection = 'row', flexWrap, justifyContent, alignItems, columns, disabled, 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 isDisabled, ...props }) => {

package/build/components/RadioCard/RadioCardGroup.props.d.ts

@@ -3,24 +3,41 @@ import { space } from '../../tokens';
 import { GridProps } from '../Grid';
 import { Ref } from 'react';
 type RadioCardGroupBaseProps = {
+    /** The value of the currently selected `RadioCard`. */
     value?: string;
+    /** Called when the selected `RadioCard` changes. */
     onValueChange?: (value: string) => void;
     /**
+     * Called when any child RadioCard is checked or unchecked.
      * @deprecated Use `onValueChange` instead.
      */
     onChange?: (value: string) => void;
+    /** The gap between the `RadioCard` items. */
     gap?: keyof typeof space;
+    /** If `true`, disables all `RadioCard`s in the group. */
     disabled?: boolean;
+    /** Forwarded ref to the underlying view. */
     ref?: Ref<View>;
 } & ViewProps;
 type RadioCardGroupFlexProps = {
     columns?: never;
+    /**
+     * (Flexbox only) Sets the direction of the flex items.
+     * @default 'row'
+     */
     flexDirection?: ViewStyle['flexDirection'];
+    /**
+     * (Flexbox only) Sets whether flex items are forced onto one line or can wrap.
+     * @default 'wrap'
+     */
     flexWrap?: ViewStyle['flexWrap'];
+    /** (Flexbox only) Sets the alignment of flex items on the cross axis. */
     alignItems?: ViewStyle['alignItems'];
+    /** (Flexbox only) Sets the alignment of flex items on the main axis. */
     justifyContent?: ViewStyle['justifyContent'];
 };
 type RadioCardGroupGridProps = {
+    /** If set, uses a grid layout with this many columns instead of flexbox. */
     columns: GridProps['columns'];
     flexDirection?: never;
     flexWrap?: never;

package/build/components/Rating/Rating.d.ts

@@ -1,4 +1,9 @@
 import type RatingProps from './Rating.props';
+/**
+ * Lets a user give a star or emoji rating, and shows a label describing the currently selected
+ * value. Use it to collect quick feedback such as a satisfaction or experience score.
+ * @summary A star or emoji rating input.
+ */
 declare const Rating: {
     ({ variant, value, defaultValue, onChange, onValueChange, disabled, labels, rangeLabels, hideLabel, style, accessibilityLabel, ...props }: RatingProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Rating/Rating.js

@@ -27,6 +27,11 @@ const DEFAULT_LABELS = {
     5: 'Great!',
 };
 const clampRating = (value) => Math.min(MAX_RATING, Math.max(0, Math.round(value)));
+/**
+ * Lets a user give a star or emoji rating, and shows a label describing the currently selected
+ * value. Use it to collect quick feedback such as a satisfaction or experience score.
+ * @summary A star or emoji rating input.
+ */
 const Rating = ({ variant = 'stars', value, defaultValue = 0, onChange, onValueChange, disabled = false, labels, rangeLabels = DEFAULT_RANGE_LABELS, hideLabel = false, style, accessibilityLabel, ...props }) => {
     const isControlled = value !== undefined;
     const [internalValue, setInternalValue] = useState(clampRating(defaultValue));

package/build/components/Roundel/Roundel.d.ts

@@ -1,4 +1,5 @@
 import type RoundelProps from './Roundel.props';
+/** A small status indicator icon, used to show success, pending or error state next to related content. */
 declare const Roundel: {
     ({ variant, style, ...props }: RoundelProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Roundel/Roundel.js

@@ -3,6 +3,7 @@ import { CloseSmallIcon, TickSmallIcon } from '@utilitywarehouse/hearth-react-na
 import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { Icon } from '../Icon';
+/** A small status indicator icon, used to show success, pending or error state next to related content. */
 const Roundel = ({ variant = 'success', style, ...props }) => {
     styles.useVariants({ variant });
     const icon = variant === 'error' ? CloseSmallIcon : variant === 'success' ? TickSmallIcon : undefined;

package/build/components/SectionHeader/SectionHeader.d.ts

@@ -1,4 +1,5 @@
 import SectionHeaderProps from './SectionHeader.props';
+/** A heading row for a section or list, with an optional helper text, badge and trailing content. */
 declare const SectionHeader: {
     ({ heading, helperText, children, style, trailingContent, badge, invalidText, ...props }: SectionHeaderProps): import("react").JSX.Element;
     displayName: string;

package/build/components/SectionHeader/SectionHeader.js

@@ -8,6 +8,7 @@ import SectionHeaderTitle from './SectionHeaderHeading';
 import SectionHeaderHelperText from './SectionHeaderHelperText';
 import SectionHeaderTextContent from './SectionHeaderTextContent';
 import SectionHeaderTrailingContent from './SectionHeaderTrailingContent';
+/** A heading row for a section or list, with an optional helper text, badge and trailing content. */
 const SectionHeader = ({ heading, helperText, children, style, trailingContent, badge, invalidText, ...props }) => {
     return (_jsx(View, { ...props, style: [styles.container, style], children: children ? (children) : (_jsxs(_Fragment, { children: [_jsxs(SectionHeaderTextContent, { children: [_jsx(SectionHeaderTitle, { children: heading }), !!helperText && _jsx(SectionHeaderHelperText, { children: helperText }), !!invalidText && (_jsx(Helper, { validationStatus: "invalid", showIcon: true, icon: ErrorCircleSmallIcon, text: invalidText || '' }))] }), !!badge && _jsx(Badge, { ...badge }), !!trailingContent && (_jsx(SectionHeaderTrailingContent, { children: trailingContent }))] })) }));
 };

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

@@ -2,9 +2,11 @@ import { Ref } from 'react';
 import type { View, ViewProps } from 'react-native';
 import BadgeProps from '../Badge/Badge.props';
 interface SectionHeaderBaseProps extends Omit<ViewProps, 'children'> {
+    /** Forwarded ref to the underlying view. */
     ref?: Ref<View>;
 }
 export interface SectionHeaderWithChildren extends SectionHeaderBaseProps {
+    /** Custom content rendered in place of the default heading, helper text, badge and trailing content. */
     children: ViewProps['children'];
     heading?: never;
     helperText?: never;
@@ -14,10 +16,15 @@ export interface SectionHeaderWithChildren extends SectionHeaderBaseProps {
 }
 export interface SectionHeaderWithoutChildren extends SectionHeaderBaseProps {
     children?: never;
+    /** The text to display in the heading of the section. */
     heading: string;
+    /** The helper text to display below the heading. */
     helperText?: string;
+    /** Optional content to display on the right side. */
     trailingContent?: React.ReactNode;
+    /** Optional badge to display next to the heading. */
     badge?: BadgeProps;
+    /** The invalid text to be displayed below the helper text. */
     invalidText?: string;
 }
 type SectionHeaderProps = SectionHeaderWithChildren | SectionHeaderWithoutChildren;

package/build/components/SegmentedControl/SegmentedControl.d.ts

@@ -1,4 +1,9 @@
 import type SegmentedControlProps from './SegmentedControl.props';
+/**
+ * Lets a user switch between a small set of mutually exclusive options rendered as
+ * `SegmentedControlOption` children, with an animated indicator tracking the current selection.
+ * @summary A single-choice, tab-like control for switching between a few options.
+ */
 declare const SegmentedControl: {
     ({ value: controlledValue, defaultValue, onValueChange, size, disabled, children, style, ...props }: SegmentedControlProps): import("react").JSX.Element;
     displayName: string;

package/build/components/SegmentedControl/SegmentedControl.js

@@ -7,6 +7,11 @@ import { useStyleProps } from '../../hooks';
 import { SegmentedControlContext } from './SegmentedControl.context';
 const Indicator = Animated.createAnimatedComponent(View);
 const GROUP_BORDER_WIDTH = 1;
+/**
+ * Lets a user switch between a small set of mutually exclusive options rendered as
+ * `SegmentedControlOption` children, with an animated indicator tracking the current selection.
+ * @summary A single-choice, tab-like control for switching between a few options.
+ */
 const SegmentedControl = ({ value: controlledValue, defaultValue, onValueChange, size = 'sm', disabled = false, children, style, ...props }) => {
     const { computedStyles, remainingProps } = useStyleProps(props);
     const isReducedMotion = useReducedMotion();

package/build/components/Select/Select.d.ts

@@ -1,5 +1,10 @@
 import React from 'react';
 import SelectProps from './Select.props';
+/**
+ * Lets a user pick a single value from a list of options presented in a bottom sheet. Use it in
+ * forms where the full set of options doesn't need to be visible at once, optionally with search.
+ * @summary A form field for picking one value from a bottom-sheet list of options.
+ */
 declare const Select: {
     ({ options, value, onValueChange, label, labelVariant, placeholder, disabled, leadingIcon: LeadingIcon, validationStatus, helperText, helperIcon, invalidText, validText, required, children, bottomSheetProps, menuHeading, readonly, emptyText, listProps, searchable, searchPlaceholder, testID, ...rest }: SelectProps): React.JSX.Element;
     displayName: string;

package/build/components/Select/Select.js

@@ -14,6 +14,11 @@ import { Input } from '../Input';
 import { SelectContext } from './Select.context';
 import { filterOptionsByLabel } from './Select.utils';
 import SelectOption from './SelectOption';
+/**
+ * Lets a user pick a single value from a list of options presented in a bottom sheet. Use it in
+ * forms where the full set of options doesn't need to be visible at once, optionally with search.
+ * @summary A form field for picking one value from a bottom-sheet list of options.
+ */
 const Select = ({ options = [], value, onValueChange, label, labelVariant = 'body', placeholder = 'Select an option', disabled = false, leadingIcon: LeadingIcon, validationStatus = 'initial', helperText, helperIcon, invalidText, validText, required = true, children, bottomSheetProps, menuHeading, readonly = false, emptyText = 'No options available', listProps, searchable = false, searchPlaceholder = 'Search', testID, ...rest }) => {
     const formFieldContext = useFormFieldContext();
     const validationStatusFromContext = formFieldContext?.validationStatus ?? validationStatus;