@utilitywarehouse/hearth-react-native 0.36.0 → 0.36.2

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

@@ -1,13 +1,27 @@
 import { ReactElement, ReactNode } from 'react';
 import CardProps from '../Card/Card.props';
 interface HighlightBannerProps extends Omit<CardProps, 'noPadding' | 'variant' | 'space' | 'gap' | 'rowGap' | 'columnGap' | 'flexDirection' | 'flexWrap' | 'alignItems' | 'justifyContent' | 'colorScheme'> {
+    /** The heading text displayed at the top with a coloured background. */
     heading?: string;
+    /** The semantic colour scheme for the heading background. */
     headingColor?: 'pig' | 'energy' | 'broadband' | 'mobile' | 'insurance' | 'cashback' | 'highlight';
+    /**
+     * Visual style variant with strong or subtle borders.
+     * @default 'emphasis'
+     */
     variant?: 'emphasis' | 'subtle';
+    /** The image component to be displayed in the banner. */
     image?: ReactNode;
+    /**
+     * Height of the image container in pixels.
+     * @default 200
+     */
     imageContainerHeight?: number;
+    /** Description text displayed below the image. */
     description?: string;
+    /** Optional Link component displayed below the description. */
     link?: ReactElement;
+    /** Optional Button component displayed below the description. */
     button?: ReactElement;
 }
 export default HighlightBannerProps;

package/build/components/HighlightBanner/HighlightBannerImage.d.ts

@@ -1,4 +1,8 @@
 import { ImageProps } from 'react-native';
 import { ThemedImageProps } from '../ThemedImage';
+/**
+ * Use HighlightBannerImage to render the image inside a HighlightBanner. Pass either standard
+ * `Image` props, or `light`/`dark` sources to render a theme-aware image.
+ */
 declare const HighlightBannerImage: (props: ImageProps | ThemedImageProps) => import("react").JSX.Element;
 export default HighlightBannerImage;

package/build/components/HighlightBanner/HighlightBannerImage.js

@@ -3,6 +3,10 @@ import { Image } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { isThemedImageProps } from '../../utils';
 import { ThemedImage } from '../ThemedImage';
+/**
+ * Use HighlightBannerImage to render the image inside a HighlightBanner. Pass either standard
+ * `Image` props, or `light`/`dark` sources to render a theme-aware image.
+ */
 const HighlightBannerImage = (props) => {
     if (isThemedImageProps(props)) {
         return _jsx(ThemedImage, { ...props, style: [styles.image, props.style] });

package/build/components/Icon/Icon.d.ts

@@ -1,4 +1,8 @@
 import type React from 'react';
 import type IconProps from './Icon.props';
+/**
+ * Use Icon to render an SVG icon component (from `@utilitywarehouse/hearth-react-native-icons`
+ * or a custom SVG) with consistent sizing and theme-aware colouring.
+ */
 export declare const Icon: React.ForwardRefExoticComponent<IconProps>;
 export default Icon;

package/build/components/Icon/Icon.js

@@ -38,6 +38,10 @@ const PrimitiveIcon = withUnistyles(({ height, width, fill, color, size, stroke,
     return _jsx(Svg, { height: height, width: width, strokeWidth: 0, ...colorProps, ...props });
 });
 PrimitiveIcon.displayName = 'PrimitiveIcon';
+/**
+ * Use Icon to render an SVG icon component (from `@utilitywarehouse/hearth-react-native-icons`
+ * or a custom SVG) with consistent sizing and theme-aware colouring.
+ */
 export const Icon = createIcon({
     Root: PrimitiveIcon,
 });

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

@@ -3,13 +3,21 @@ import type { SvgProps } from 'react-native-svg';
 import type { ColorValue } from '../../types';
 import { ComponentType } from 'react';
 interface IconProps extends SvgProps {
+    /** The height of the icon. */
     height?: number | string;
+    /** The width of the icon. */
     width?: number | string;
+    /** The fill color applied to the icon's SVG paths. */
     fill?: string;
+    /** The color of the icon. */
     color?: ColorValue;
+    /** Sets both the height and width of the icon. */
     size?: number | string;
+    /** The stroke color applied to the icon's SVG paths. */
     stroke?: string;
+    /** The icon component to render. */
     as?: ComponentType;
+    /** Style applied to the icon's root SVG element. */
     style?: SvgProps['style'] & {
         color?: RNColorValue;
     };

package/build/components/IconButton/IconButton.d.ts

@@ -1,4 +1,9 @@
 import { IconButtonProps } from './IconButton.props';
+/**
+ * Use IconButton to trigger an action or event, such as opening a dialog, cancelling an
+ * action, or performing a delete operation, when only an icon is needed rather than a
+ * labelled button.
+ */
 declare const IconButton: {
     ({ icon, disabled, pressed, ...props }: IconButtonProps): import("react").JSX.Element;
     displayName: string;

package/build/components/IconButton/IconButton.js

@@ -15,6 +15,11 @@ const IconButtonSpinner = IconButtonComponent.Spinner;
 const IconButtonIcon = IconButtonComponent.Icon;
 IconButtonSpinner.displayName = 'IconButtonSpinner';
 IconButtonIcon.displayName = 'IconButtonIcon';
+/**
+ * Use IconButton to trigger an action or event, such as opening a dialog, cancelling an
+ * action, or performing a delete operation, when only an icon is needed rather than a
+ * labelled button.
+ */
 const IconButton = ({ icon, disabled = false, pressed, ...props }) => {
     const { disabled: groupDisabled, loading: groupLoading } = useButtonGroupContext();
     const { loading } = props;

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

@@ -4,11 +4,20 @@ import { ViewProps } from 'react-native-svg/lib/typescript/fabric/utils';
 import { ColorValue } from '../../types';
 import { ButtonVariants } from '../Button/Button.props';
 export type IconButtonProps = {
+    /**
+     * Disables the button.
+     * @default false
+     */
     disabled?: boolean;
+    /** The size of the button. */
     size?: 'sm' | 'md';
+    /** Changes the button to a pressed state. */
     pressed?: boolean;
+    /** The icon component to display on the button. */
     icon: ComponentType;
+    /** Changes the button to a loading state. */
     loading?: boolean;
+    /** Content rendered inside the button. */
     children?: ViewProps['children'];
     /**
      * Custom background color override.

package/build/components/IconContainer/IconContainer.d.ts

@@ -1,4 +1,8 @@
 import type IconContainerProps from './IconContainer.props';
+/**
+ * Use IconContainer to give a standalone icon a consistent background and sizing, with
+ * semantic colour families and subtle/emphasis variants.
+ */
 declare const IconContainer: {
     ({ icon: IconComp, size, radiusNone, variant, color, style, ...props }: IconContainerProps): import("react").JSX.Element;
     displayName: string;

package/build/components/IconContainer/IconContainer.js

@@ -2,6 +2,10 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { Icon } from '../Icon';
+/**
+ * Use IconContainer to give a standalone icon a consistent background and sizing, with
+ * semantic colour families and subtle/emphasis variants.
+ */
 const IconContainer = ({ icon: IconComp, size = 'md', radiusNone = false, variant = 'subtle', color = 'pig', style, ...props }) => {
     styles.useVariants({ size, radiusNone, variant, color });
     return (_jsx(View, { style: [styles.container, style], ...props, children: IconComp ? _jsx(Icon, { as: IconComp, style: styles.icon }) : null }));

package/build/components/IndicatorIconButton/IndicatorIconButton.d.ts

@@ -1,5 +1,11 @@
 import React from 'react';
 import { IndicatorIconButtonProps } from './IndicatorIconButton.props';
+/**
+ * Triggers an action or event, such as opening a dialog or navigating to another screen. Extends
+ * `UnstyledIconButton` with an optional red dot indicator in the top-right corner, for showing
+ * notifications or unread status.
+ * @summary An icon button with an optional notification indicator.
+ */
 declare const IndicatorIconButton: {
     ({ indicator, ...props }: IndicatorIconButtonProps): React.JSX.Element;
     displayName: string;

package/build/components/IndicatorIconButton/IndicatorIconButton.js

@@ -2,6 +2,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { UnstyledIconButton } from '../UnstyledIconButton';
+/**
+ * Triggers an action or event, such as opening a dialog or navigating to another screen. Extends
+ * `UnstyledIconButton` with an optional red dot indicator in the top-right corner, for showing
+ * notifications or unread status.
+ * @summary An icon button with an optional notification indicator.
+ */
 const IndicatorIconButton = ({ indicator = false, ...props }) => {
     return (_jsxs(View, { style: styles.container, children: [_jsx(UnstyledIconButton, { size: "md", ...props }), indicator && _jsx(View, { style: styles.indicator })] }));
 };

package/build/components/InlineLink/InlineLink.d.ts

@@ -1,4 +1,5 @@
 import type { InlineLinkProps } from './InlineLink.props';
+/** Use InlineLink to embed a hyperlink within a sentence or paragraph of body text, inheriting the surrounding typography style. */
 declare const InlineLink: {
     ({ children, disabled, target, rel, ...props }: InlineLinkProps): import("react").JSX.Element;
     displayName: string;

package/build/components/InlineLink/InlineLink.js

@@ -5,6 +5,7 @@ const InlineLinkComponent = createLink({
     Root: InlineLinkRoot,
     Text: () => null,
 });
+/** Use InlineLink to embed a hyperlink within a sentence or paragraph of body text, inheriting the surrounding typography style. */
 const InlineLink = ({ children, disabled = false, target = '_self', rel, ...props }) => {
     const InlineLinkAny = InlineLinkComponent;
     // `@gluestack-ui/link`'s `useLink` only ever applies `target`/`rel` via a ref

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

@@ -1,9 +1,13 @@
 import { TextProps } from 'react-native';
 export interface InlineLinkProps extends TextProps {
+    /** The URL to navigate to. */
     href?: string;
+    /** The target of the link.
+     * @default '_self' */
     target?: '_blank' | '_self' | '_parent' | '_top';
     /** Defaults to `noopener noreferrer` when `target` is `_blank`. */
     rel?: string;
+    /** Invert the link colours for purple backgrounds. */
     inverted?: boolean;
     disabled?: boolean;
 }

package/build/components/Input/Input.d.ts

@@ -23,5 +23,10 @@ export declare const InputIcon: import("react").ForwardRefExoticComponent<import
 }> & import("..").IconProps & {
     as?: ComponentType;
 }>;
+/**
+ * Use Input for a text field that lets users enter text, numbers, or other data, commonly in forms and search fields.
+ * Renders as a plain, password, or search field, or accepts children for a fully custom layout built from `InputField`, `InputSlot`, and `InputIcon`.
+ * @summary A configurable text field for forms and search.
+ */
 declare const Input: import("react").ForwardRefExoticComponent<InputProps & import("react").RefAttributes<TextInput>>;
 export default Input;

package/build/components/Input/Input.js

@@ -20,6 +20,11 @@ export const InputComponent = createInput({
 export const InputSlot = InputComponent.Slot;
 export const InputField = InputComponent.Input;
 export const InputIcon = InputComponent.Icon;
+/**
+ * Use Input for a text field that lets users enter text, numbers, or other data, commonly in forms and search fields.
+ * Renders as a plain, password, or search field, or accepts children for a fully custom layout built from `InputField`, `InputSlot`, and `InputIcon`.
+ * @summary A configurable text field for forms and search.
+ */
 const Input = forwardRef(({ validationStatus = 'initial', children, disabled, focused, readonly, leadingIcon, trailingIcon, type, showPasswordToggle = true, onClear, loading, clearable = false, required = true, inBottomSheet = false, style, label, labelVariant, helperText, helperIcon, validText, invalidText, prefix, suffix, ...props }, ref) => {
     const formFieldContext = useFormFieldContext();
     const inputLabel = label ?? formFieldContext?.label;

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

@@ -22,65 +22,119 @@ export interface InputBaseProps {
      * ```
      */
     validationStatus?: 'initial' | 'valid' | 'invalid';
+    /** Makes the input read-only. */
     readonly?: boolean;
+    /** Sets focus on the input. */
     focused?: boolean;
+    /** The placeholder text for the input. */
     placeholder?: string;
+    /** Indicates the input is rendered inside a bottom sheet.
+     * @default false */
     inBottomSheet?: boolean;
+    /** The label for the input; only used when the input has no children. */
     label?: string;
+    /** The text variant used for the label; only used when the input has no children. */
     labelVariant?: 'heading' | 'body';
+    /** Helper text displayed below the input; only used when the input has no children. */
     helperText?: string;
+    /** Icon displayed alongside the helper text; only used when the input has no children. */
     helperIcon?: ComponentType;
+    /** Text shown when the validation status is `valid`. */
     validText?: string;
+    /** Text shown when the validation status is `invalid`. */
     invalidText?: string;
+    /** Indicates the input is required.
+     * @default true */
     required?: boolean;
 }
 export interface InputWithChildrenProps extends InputBaseProps, ViewProps {
+    /** Custom content rendered inside the input, in place of the built-in field and icon slots. */
     children: ViewProps['children'];
+    /** Not applicable when the input has children. */
     type?: undefined;
+    /** Not applicable when the input has children. */
     showPasswordToggle?: never;
+    /** Reserved for future use; not currently used by any input type. */
     format?: never;
+    /** Not applicable when the input has children. */
     loading?: never;
+    /** Not applicable when the input has children. */
     clearable?: never;
+    /** Not applicable when the input has children. */
     onClear?: never;
+    /** Not applicable when the input has children. */
     leadingIcon?: never;
+    /** Not applicable when the input has children. */
     trailingIcon?: never;
+    /** Not applicable when the input has children. */
     prefix?: never;
+    /** Not applicable when the input has children. */
     suffix?: never;
 }
 interface InputWithoutChildrenBaseProps extends InputBaseProps, Omit<TextInputProps, 'children'> {
     children?: never;
+    /** Icon displayed at the start of the input. */
     leadingIcon?: ComponentType;
+    /** Icon displayed at the end of the input. */
     trailingIcon?: ComponentType;
+    /** Indicates the input is required.
+     * @default true */
     required?: boolean;
+    /** Content displayed before the input field. */
     prefix?: string | number | React.ReactNode;
+    /** Content displayed after the input field. */
     suffix?: string | number | React.ReactNode;
 }
 interface TextInputSpecificProps extends InputWithoutChildrenBaseProps {
+    /** The input type; renders as plain text. */
     type?: 'text';
+    /** Not applicable to the text input type. */
     showPasswordToggle?: never;
+    /** Reserved for future use; not currently used by any input type. */
     format?: never;
+    /** Not applicable to the text input type. */
     loading?: never;
+    /** Not applicable to the text input type. */
     clearable?: never;
+    /** Not applicable to the text input type. */
     onClear?: never;
 }
 interface PasswordInputSpecificProps extends InputWithoutChildrenBaseProps {
+    /** The input type; renders as a password field with masked text. */
     type: 'password';
+    /** Shows a toggle to reveal or hide the password text.
+     * @default true */
     showPasswordToggle?: boolean;
+    /** Reserved for future use; not currently used by any input type. */
     format?: never;
+    /** Not applicable to the password input type. */
     loading?: never;
+    /** Not applicable to the password input type. */
     clearable?: never;
+    /** Not applicable to the password input type. */
     onClear?: never;
+    /** Not applicable to the password input type. */
     prefix?: never;
+    /** Not applicable to the password input type. */
     suffix?: never;
 }
 interface SearchInputSpecificProps extends InputWithoutChildrenBaseProps {
+    /** The input type; renders as a search field with a search icon. */
     type: 'search';
+    /** Shows a loading spinner in the search input. */
     loading?: boolean;
+    /** Shows a clear button that empties the search input.
+     * @default false */
     clearable?: boolean;
+    /** Called when the clear button is pressed. */
     onClear?: () => void;
+    /** Not applicable to the search input type. */
     showPasswordToggle?: never;
+    /** Reserved for future use; not currently used by any input type. */
     format?: never;
+    /** Not applicable to the search input type. */
     prefix?: never;
+    /** Not applicable to the search input type. */
     suffix?: never;
 }
 export type InputWithoutChildrenProps = TextInputSpecificProps | PasswordInputSpecificProps | SearchInputSpecificProps;

package/build/components/Link/Link.d.ts

@@ -1,5 +1,10 @@
 import type { LinkProps } from './Link.props';
 export declare const LinkText: import("react").ForwardRefExoticComponent<import("react-native").TextProps & import("react").RefAttributes<import("react-native").TextProps>>;
+/**
+ * Navigates a user to another screen or website, another place on the same page, or opens a link
+ * in a new tab.
+ * @summary A navigational link with an optional icon.
+ */
 declare const Link: {
     ({ children, icon, disabled, target, rel, iconPosition, showIcon, textStyle, iconStyle, ...props }: LinkProps): import("react").JSX.Element;
     displayName: string;

package/build/components/Link/Link.js

@@ -10,6 +10,11 @@ const LinkComponent = createLink({
 });
 export const LinkText = LinkComponent.Text;
 LinkText.displayName = 'LinkText';
+/**
+ * Navigates a user to another screen or website, another place on the same page, or opens a link
+ * in a new tab.
+ * @summary A navigational link with an optional icon.
+ */
 const Link = ({ children, icon = ChevronRightSmallIcon, disabled = false, target = '_self', rel, iconPosition = 'right', showIcon = true, textStyle, iconStyle, ...props }) => {
     const LinkAny = LinkComponent;
     // `@gluestack-ui/link`'s `useLink` only ever applies `target`/`rel` via a ref

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

@@ -2,17 +2,32 @@ import { ComponentType } from 'react';
 import { PressableProps, TextProps } from 'react-native';
 import { IconProps } from '../Icon';
 export interface LinkProps extends Omit<PressableProps, 'children'> {
+    /** The text or content rendered inside the link. */
     children: TextProps['children'];
+    /** The URL to navigate to. */
     href?: string;
+    /** The target of the link.
+     * @default '_self' */
     target?: '_blank' | '_self' | '_parent' | '_top';
     /** Defaults to `noopener noreferrer` when `target` is `_blank`. */
     rel?: string;
+    /** Invert the link colours for purple backgrounds. */
     inverted?: boolean;
+    /** Disable the link.
+     * @default false */
     disabled?: boolean;
+    /** Icon displayed next to the link text.
+     * @default ChevronRightSmallIcon */
     icon?: ComponentType;
+    /** Position of the icon relative to the link text.
+     * @default 'right' */
     iconPosition?: 'left' | 'right';
+    /** Shows the icon next to the link text.
+     * @default true */
     showIcon?: boolean;
+    /** Additional style applied to the link text. */
     textStyle?: TextProps['style'];
+    /** Additional style applied to the icon. */
     iconStyle?: IconProps['style'];
 }
 export default LinkProps;

package/build/components/List/List.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
 import type ListProps from './List.props';
+/** Use List to group `ListItem` and `ListAction` components under an optional heading, with a shared container style and disabled/loading state. */
 declare const List: {
     ({ children, heading, helperText, headerTrailingContent, invalidText, ...props }: ListProps): React.JSX.Element;
     displayName: string;

package/build/components/List/List.js

@@ -5,6 +5,7 @@ import { StyleSheet } from 'react-native-unistyles';
 import { Card } from '../Card';
 import { SectionHeader } from '../SectionHeader';
 import { ListContext } from './List.context';
+/** Use List to group `ListItem` and `ListAction` components under an optional heading, with a shared container style and disabled/loading state. */
 const List = ({ children, heading, helperText, headerTrailingContent, invalidText, ...props }) => {
     const { loading, disabled, container = 'none', testID, style, accessibilityRole, ...rest } = props;
     const orderRef = useRef([]);

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

@@ -1,11 +1,19 @@
 import type { ViewProps } from 'react-native';
 interface ListProps extends ViewProps {
+    /** The container style of the list.
+     * @default 'none' */
     container?: 'none' | 'subtleWhite' | 'emphasisWhite' | 'subtleWarmWhite' | 'emphasisWarmWhite';
+    /** The text to display in the heading of the list. */
     heading?: string;
+    /** The supporting text to display in the heading of the list. */
     helperText?: string;
+    /** Optional content to display on the right side of the header. */
     headerTrailingContent?: React.ReactNode;
+    /** Whether to disable the list. */
     disabled?: boolean;
+    /** Whether to show the list items in loading state. */
     loading?: boolean;
+    /** Validation error text to display in the heading of the list. */
     invalidText?: string;
 }
 export default ListProps;

package/build/components/Menu/Menu.d.ts

@@ -1,4 +1,5 @@
 import type MenuProps from './Menu.props';
 import type { MenuMethods } from './Menu.props';
+/** Use Menu to show a bottom sheet of contextual actions or options, built from `MenuItem` children and opened via `MenuTrigger`. */
 declare const Menu: import("react").ForwardRefExoticComponent<Omit<MenuProps, "ref"> & import("react").RefAttributes<MenuMethods>>;
 export default Menu;

package/build/components/Menu/Menu.js

@@ -4,6 +4,7 @@ import { StyleSheet } from 'react-native-unistyles';
 import { BodyText } from '../BodyText';
 import { BottomSheetModal, BottomSheetScrollView } from '../BottomSheet';
 import { MenuContext } from './Menu.context';
+/** Use Menu to show a bottom sheet of contextual actions or options, built from `MenuItem` children and opened via `MenuTrigger`. */
 const Menu = forwardRef(({ heading, children, ...props }, ref) => {
     const bottomSheetModalRef = useRef(null);
     useImperativeHandle(ref, () => ({

package/build/components/Modal/Modal.d.ts

@@ -3,5 +3,10 @@ import ModalProps from './Modal.props';
 type Modal<T = any> = BottomSheetModalMethods<T> & {
     triggerCloseAnimation?: () => void;
 };
+/**
+ * Use Modal for a dialog that slides up from the bottom of the screen, with pre-configured layouts for headers, content, and action buttons.
+ * Built on `BottomSheetModal`; use it to display important information, collect input, or present choices without navigating away from the current screen. Use `NavModal` instead inside a React Navigation modal screen.
+ * @summary A bottom-sheet dialog for confirmations, input, and choices.
+ */
 declare const Modal: ({ ref, children, heading, description, showCloseButton, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, closeOnPrimaryButtonPress, closeOnSecondaryButtonPress, loading, loadingHeading, loadingDescription, fullscreen, image, footer, footerStyle, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter, testID, ...props }: ModalProps) => import("react").JSX.Element;
 export default Modal;

package/build/components/Modal/Modal.js

@@ -12,6 +12,11 @@ import { Button } from '../Button';
 import { Heading } from '../Heading';
 import { Spinner } from '../Spinner';
 import { UnstyledIconButton } from '../UnstyledIconButton';
+/**
+ * Use Modal for a dialog that slides up from the bottom of the screen, with pre-configured layouts for headers, content, and action buttons.
+ * Built on `BottomSheetModal`; use it to display important information, collect input, or present choices without navigating away from the current screen. Use `NavModal` instead inside a React Navigation modal screen.
+ * @summary A bottom-sheet dialog for confirmations, input, and choices.
+ */
 const Modal = ({ ref, children, heading, description, showCloseButton = true, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, closeOnPrimaryButtonPress = true, closeOnSecondaryButtonPress = true, loading, loadingHeading = 'Loading...', loadingDescription, fullscreen = false, image, footer, footerStyle, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter = true, testID, ...props }) => {
     const theme = useTheme();
     const bottomSheetModalRef = useRef(null);
@@ -137,7 +142,6 @@ const styles = StyleSheet.create((theme, rt) => ({
             {
                 noButtons: true,
                 useSafeAreaInsets: true,
-                stickyFooter: false,
                 styles: {
                     paddingBottom: rt.insets.bottom +
                         theme.components.modal.padding +

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

@@ -1,10 +1,16 @@
 import { BottomSheetProps } from '../BottomSheet';
 import { ModalButtonFooterProps, ModalCommonBaseProps, ModalCustomFooterProps } from './Modal.shared.types';
 type ModalBaseProps = Omit<BottomSheetProps, 'children'> & ModalCommonBaseProps & {
+    /** Whether the modal should take up the full screen height.
+     * @default false */
     fullscreen?: boolean;
 };
 type ModalProps = (ModalBaseProps & ModalButtonFooterProps & {
+    /** Whether to automatically close the modal when the primary button is pressed.
+     * @default true */
     closeOnPrimaryButtonPress?: boolean;
+    /** Whether to automatically close the modal when the secondary button is pressed.
+     * @default true */
     closeOnSecondaryButtonPress?: boolean;
 }) | (ModalBaseProps & ModalCustomFooterProps & {
     closeOnPrimaryButtonPress?: never;

package/build/components/Modal/Modal.shared.types.d.ts

@@ -3,37 +3,69 @@ import { StyleProp, ViewProps, ViewStyle } from 'react-native';
 import { ButtonWithoutChildrenProps } from '../Button/Button.props';
 import { UnstyledIconButtonProps } from '../UnstyledIconButton';
 export interface ModalCommonBaseProps {
+    /** Applied to the modal content container, useful for locating the modal in e2e tests. */
     testID?: string;
+    /** Whether to show a loading state with a spinner.
+     * @default false */
     loading?: boolean;
+    /** Image to display in the modal, shown as centered content with text below. */
     image?: ReactNode;
+    /** Whether to show the close button in the top-right corner.
+     * @default true */
     showCloseButton?: boolean;
+    /** The heading text displayed at the top of the modal. */
     heading?: string;
+    /** The heading text shown while `loading` is true, instead of the regular heading.
+     * @default 'Loading...' */
     loadingHeading?: string;
+    /** The description text shown while `loading` is true, instead of the regular description. */
     loadingDescription?: string;
+    /** The description content displayed below the heading; pass a string for the default styling, or JSX for custom content. */
     description?: ReactNode;
+    /** Whether the footer stays fixed to the bottom of the modal while content scrolls.
+     * @default true */
     stickyFooter?: boolean;
+    /** Custom content to display in the modal body. */
     children?: ViewProps['children'];
+    /** Called when the close button is pressed. */
     onPressCloseButton?: () => void;
+    /** Additional props passed to the close button. */
     closeButtonProps?: Omit<UnstyledIconButtonProps, 'children'>;
 }
 export interface ModalButtonFooterProps {
+    /** Called when the primary button is pressed. */
     onPressPrimaryButton?: () => void;
+    /** Text for the primary action button. */
     primaryButtonText?: string;
+    /** Called when the secondary button is pressed. */
     onPressSecondaryButton?: () => void;
+    /** Text for the secondary action button. */
     secondaryButtonText?: string;
+    /** Additional props passed to the primary button; `colorScheme` defaults to `highlight`, `variant` to `solid`. */
     primaryButtonProps?: Omit<ButtonWithoutChildrenProps, 'children'>;
+    /** Additional props passed to the secondary button; `colorScheme` defaults to `functional`, `variant` to `outline`. */
     secondaryButtonProps?: Omit<ButtonWithoutChildrenProps, 'children'>;
+    /** Not applicable when using the built-in primary/secondary action buttons. */
     footer?: never;
+    /** Styles applied to the footer container, useful for sticky footer shadows or custom spacing. */
     footerStyle?: StyleProp<ViewStyle>;
 }
 export interface ModalCustomFooterProps {
+    /** Custom footer content that replaces the built-in action buttons. */
     footer: ReactNode;
+    /** Styles applied to the footer container, useful for sticky footer shadows or custom spacing. */
     footerStyle?: StyleProp<ViewStyle>;
+    /** Not applicable when a custom `footer` is provided. */
     onPressPrimaryButton?: never;
+    /** Not applicable when a custom `footer` is provided. */
     primaryButtonText?: never;
+    /** Not applicable when a custom `footer` is provided. */
     onPressSecondaryButton?: never;
+    /** Not applicable when a custom `footer` is provided. */
     secondaryButtonText?: never;
+    /** Not applicable when a custom `footer` is provided. */
     primaryButtonProps?: never;
+    /** Not applicable when a custom `footer` is provided. */
     secondaryButtonProps?: never;
 }
 export type ModalCommonProps = ModalCommonBaseProps & (ModalButtonFooterProps | ModalCustomFooterProps);

package/build/components/Modal/ModalImage.d.ts

@@ -1,4 +1,5 @@
 import { ImageProps } from 'react-native';
 import { ThemedImageProps } from '../ThemedImage';
+/** Use ModalImage to display an image within a `Modal`, with support for separate light and dark mode sources via `ThemedImage`. */
 declare const ModalImage: (props: ImageProps | ThemedImageProps) => import("react").JSX.Element;
 export default ModalImage;

package/build/components/Modal/ModalImage.js

@@ -3,6 +3,7 @@ import { Image } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { isThemedImageProps } from '../../utils';
 import { ThemedImage } from '../ThemedImage';
+/** Use ModalImage to display an image within a `Modal`, with support for separate light and dark mode sources via `ThemedImage`. */
 const ModalImage = (props) => {
     if (isThemedImageProps(props)) {
         return _jsx(ThemedImage, { ...props, style: [styles.image, props.style] });

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

@@ -1,3 +1,11 @@
 import NavModalProps from './NavModal.props';
+/**
+ * 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.
+ */
 declare const NavModal: ({ ref, children, heading, description, showCloseButton, primaryButtonText, secondaryButtonText, onPressPrimaryButton, onPressCloseButton, onPressSecondaryButton, loading, loadingHeading, loadingDescription, image, footer, footerStyle, primaryButtonProps, secondaryButtonProps, closeButtonProps, stickyFooter, background, scrollable, presentation, scrollViewProps, useSafeAreaInsets, ...props }: NavModalProps) => import("react").JSX.Element;
 export default NavModal;