@utilitywarehouse/hearth-react-native 0.34.4 → 0.34.5

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @utilitywarehouse/hearth-react-native
 
+## 0.34.5
+
+### Patch Changes
+
+- [#1384](https://github.com/utilitywarehouse/hearth/pull/1384) [`be839e2`](https://github.com/utilitywarehouse/hearth/commit/be839e2ca46f079a0fe867f976044f4f31cca551) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: `NavModal` and `Modal` `description` prop accepts JSX
+
+  `description` now accepts `ReactNode` in addition to a string, so you can pass
+  custom content such as links or styled text alongside the default text
+  styling.
+
+  **Components affected**:
+
+  - `NavModal`
+  - `Modal`
+
+  **Developer changes**:
+
+  No changes required for existing usage. To pass custom content, provide JSX
+  instead of a string:
+
+  ```tsx
+  <Modal
+    heading="Update available"
+    description={
+      <BodyText>
+        Read the <InlineLink onPress={() => {}}>release notes</InlineLink> before updating.
+      </BodyText>
+    }
+  />
+  ```
+
 ## 0.34.4
 
 ### Patch Changes

package/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+This file covers `packages/react-native` — `@utilitywarehouse/hearth-react-native`, the React Native
+component library. See the [repo-root CLAUDE.md](../../CLAUDE.md) for monorepo-wide setup and commands.
+
+## Commands
+
+Run from this directory (`packages/react-native`), or via the root scripts shown for Turbo-filtered variants.
+
+```sh
+pnpm dev                    # Storybook (React Native Web) on :6006 — primary dev loop for this package
+pnpm dev:docs               # Storybook docs-only mode on :6002
+
+pnpm build                  # tsc — compiles src/ to build/
+pnpm watch                  # tsc --watch
+
+pnpm test                   # vitest run --config vitest.unit.config.ts — unit tests (src/**/*.test.{ts,tsx})
+pnpm test:storybook         # vitest run --project storybook — runs stories as browser tests via Playwright
+
+pnpm lint                   # eslint .
+pnpm lint:fix               # eslint --fix .
+
+pnpm copyTokens             # vendors CSS tokens from packages/tokens into src/tokens — run after changing hearth-tokens
+pnpm generateColours        # regenerates legacy colour token files
+
+pnpm figma:create           # scaffold a Code Connect entry
+pnpm figma:publish          # publish Code Connect mappings
+```
+
+Run a single unit test file: `pnpm test src/hooks/useFormFieldAccessibility.test.tsx`.
+
+Root-level equivalents (from repo root):
+```sh
+pnpm dev:react-native                # turbo run @utilitywarehouse/hearth-react-native#dev
+pnpm test:react-native               # unit tests + storybook tests for this package
+pnpm build:react-native              # turbo run build:storybook, filtered to this package
+```
+
+## Architecture
+
+### Styling: Unistyles, not StyleSheet-from-react-native
+
+Every component is styled with `react-native-unistyles`'s `StyleSheet.create(theme => ({...}))`, re-exported
+from `src/core`. Styles are defined as **variants** (e.g. `size`, `colorScheme`, `variant`, `disabled`) plus
+`compoundVariants` for combinations that need distinct treatment, and applied at render time via
+`styles.useVariants({...})`. See [`Button/ButtonRoot.tsx`](src/components/Button/ButtonRoot.tsx) for the
+canonical example — colour/variant/state combinations are resolved entirely through compound variants rather
+than conditional logic in the component body. `_web` blocks inside a style object hold web-only pseudo-class
+styles (`_hover`, `_focus-visible`, `_active`) since Unistyles targets both native and `react-native-web`.
+
+Unistyles is configured once in `src/core/index.ts` (`StyleSheet.configure({ breakpoints, themes, settings })`),
+which is why components never configure themes themselves — they just consume `theme` inside `StyleSheet.create`.
+
+### Token pipeline: tokens package → legacy + generated → theme
+
+- `src/tokens/` is **generated, not hand-edited** ("Do not edit directly" — see file headers). It's populated
+  by `pnpm copyTokens` from `@utilitywarehouse/hearth-tokens` (see root CLAUDE.md: tokens are vendored, not a
+  runtime dependency).
+- `src/legacyTokens/` holds older colour tokens (`colors`, `colorsCommon`, `colorsDark`) still consumed by
+  `src/core/themes.ts` alongside the generated tokens — check both when tracing a colour value.
+- `src/core/themes.ts` assembles the final `light`/`dark` theme objects consumed via `theme.*` inside
+  components, merging `tokens/*` (space, color, typography, shadow, border, `components.*` for
+  per-component tokens) with responsive breakpoint-aware values (`base`/`md`/`lg` per breakpoint).
+- Component-specific tokens live under `theme.components.<componentName>` (e.g. `theme.components.button.md.paddingVertical`)
+  — check `src/tokens/components/{light,dark}` before hardcoding a dimension in a component.
+
+### Component folder convention
+
+Each component under `src/components/<Component>/` follows a fixed file set (see the
+`react-native-component-addition` skill for full detail when adding a new one):
+
+```
+<Component>.tsx / <Component>Root.tsx / <Component>Xyz.tsx   # implementation, split by subcomponent
+<Component>.props.ts    # public prop types
+<Component>.context.ts  # React context for compound components (e.g. ButtonContext shares state with ButtonIcon/ButtonText)
+<Component>.stories.tsx # Storybook stories
+<Component>.docs.mdx    # Storybook docs page
+<Component>.figma.tsx   # Figma Code Connect mapping (excluded from eslint and turbo build inputs)
+index.ts                # public exports for the folder
+```
+
+Compound components (Button, Accordion, Card, etc.) share state via a `<Component>Context` rather than prop
+drilling — check for a `.context.ts` file before assuming a subcomponent is standalone.
+
+`src/index.ts` re-exports only `core`, `hooks`, and `components` — anything not re-exported there (e.g.
+internal `utils/`) is not part of the public API.
+
+### Storybook / testing split
+
+There are two distinct test configs, and they check different things:
+- `vitest.unit.config.ts` — plain unit tests (`src/**/*.test.ts(x)`), Node environment, e.g.
+  [`useFormFieldAccessibility.test.tsx`](src/hooks/useFormFieldAccessibility.test.tsx).
+- `vitest.config.js` — runs `*.stories.tsx` themselves as browser tests via `@storybook/addon-vitest` +
+  Playwright/Chromium, driven by `.storybook/` config. This is how story-level interaction tests are verified,
+  not a separate manual QA step.
+
+Storybook itself targets `@storybook/react-native-web-vite`, so stories run against `react-native-web`, not a
+native simulator — this is also why `_web`-scoped Unistyles blocks matter for how components look in Storybook.
+
+### Peer dependency surface
+
+This package is built on and requires consumers to install `react-native-unistyles`, `react-native-svg`,
+`react-native-reanimated` (+ `react-native-worklets`), `react-native-gesture-handler`,
+`react-native-safe-area-context`, `@gorhom/bottom-sheet`, and `@utilitywarehouse/hearth-react-native-icons`
+(see `docs/introduction.mdx` for consumer-side setup — Babel plugin, font linking, Jest mocks). When changing a
+component's animation or gesture behaviour, assume these are the only native modules available; don't add a new
+native dependency without checking the peerDependencies list in `package.json`.

package/build/components/Modal/Modal.js

@@ -70,6 +70,8 @@ const Modal = ({ ref, children, heading, description, showCloseButton = true, pr
     const hasSecondaryButton = !!(onPressSecondaryButton && secondaryButtonText);
     const hasFooter = !!footer || hasPrimaryButton || hasSecondaryButton;
     const shouldShowFooter = !loading && hasFooter;
+    const descriptionIsText = typeof description === 'string' || typeof description === 'number';
+    const hasDescription = description !== undefined && description !== null;
     styles.useVariants({
         loading,
         noButtons: !shouldShowFooter,
@@ -88,7 +90,7 @@ const Modal = ({ ref, children, heading, description, showCloseButton = true, pr
         secondaryButtonProps,
         secondaryButtonText,
     ]);
-    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? (loadingHeading ?? 'Loading') : undefined, accessibilityHint: Platform.OS === 'android' && loadingDescription ? loadingDescription : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsx(Spinner, { size: "lg" }), _jsx(Heading, { size: "lg", textAlign: "center", children: loadingHeading }), loadingDescription ? _jsx(BodyText, { textAlign: "center", children: loadingDescription }) : null] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, children: heading })) : null, description && !image ? _jsx(BodyText, { accessible: true, children: description }) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, children: heading })) : null, description ? (_jsx(BodyText, { textAlign: "center", accessible: true, children: description })) : null] })] })) : null, children, !stickyFooter && shouldShowFooter ? (_jsx(View, { style: footerStyle, children: footerContent })) : null] })) }));
+    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? (loadingHeading ?? 'Loading') : undefined, accessibilityHint: Platform.OS === 'android' && loadingDescription ? loadingDescription : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsx(Spinner, { size: "lg" }), _jsx(Heading, { size: "lg", textAlign: "center", children: loadingHeading }), loadingDescription ? _jsx(BodyText, { textAlign: "center", children: loadingDescription }) : null] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, children: heading })) : null, hasDescription && !image ? (descriptionIsText ? (_jsx(BodyText, { accessible: true, children: description })) : (description)) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, children: heading })) : null, hasDescription ? (descriptionIsText ? (_jsx(BodyText, { textAlign: "center", accessible: true, children: description })) : (description)) : null] })] })) : null, children, !stickyFooter && shouldShowFooter ? (_jsx(View, { style: footerStyle, children: footerContent })) : null] })) }));
     const renderFooter = useCallback((bottomSheetFooterProps) => (_jsx(BottomSheetFooter, { ...bottomSheetFooterProps, children: _jsx(View, { onLayout: handleStickyFooterLayout, style: [styles.footerWrap, footerStyle], children: footerContent }) })), [footerContent, footerStyle, handleStickyFooterLayout]);
     return (_jsxs(_Fragment, { children: [stickyFooter && shouldShowFooter && stickyFooterHeight === 0 ? (_jsx(View, { accessible: false, importantForAccessibility: "no-hide-descendants", pointerEvents: "none", style: styles.footerMeasurementContainer, children: _jsx(View, { onLayout: handleStickyFooterLayout, style: [styles.footerWrap, footerStyle], children: footerContent }) })) : null, _jsxs(BottomSheetModal, { ref: bottomSheetModalRef, enableDynamicSizing: true, snapPoints: image || fullscreen ? ['90%'] : props.snapPoints, showHandle: typeof loading !== 'undefined' && loading ? false : props.showHandle, accessible: false, style: styles.modal, footerComponent: stickyFooter && shouldShowFooter ? renderFooter : undefined, ...props, onChange: handleChange, children: [loading ? _jsx(View, { style: styles.loadingTop }) : null, _jsx(BottomSheetScrollView, { contentContainerStyle: [
                             styles.scrollView,

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

@@ -9,7 +9,7 @@ export interface ModalCommonBaseProps {
     heading?: string;
     loadingHeading?: string;
     loadingDescription?: string;
-    description?: string;
+    description?: ReactNode;
     stickyFooter?: boolean;
     children?: ViewProps['children'];
     onPressCloseButton?: () => void;

package/build/components/Modal/Modal.web.js

@@ -59,8 +59,10 @@ const Modal = ({ ref, children, heading, description, showCloseButton = true, pr
     const hasPrimaryButton = !!(onPressPrimaryButton && primaryButtonText);
     const hasSecondaryButton = !!(onPressSecondaryButton && secondaryButtonText);
     const hasFooter = !!footer || hasPrimaryButton || hasSecondaryButton;
+    const descriptionIsText = typeof description === 'string' || typeof description === 'number';
+    const hasDescription = description !== undefined && description !== null;
     const footerContent = footer ?? (_jsxs(View, { style: styles.footer, children: [hasPrimaryButton ? (_jsx(Button, { onPress: handlePrimaryButtonPress, text: primaryButtonText, ...primaryButtonProps, variant: primaryButtonProps?.variant ?? 'solid', colorScheme: primaryButtonProps?.colorScheme ?? 'highlight' })) : null, hasSecondaryButton ? (_jsx(Button, { onPress: handleSecondaryButtonPress, text: secondaryButtonText, ...secondaryButtonProps, variant: secondaryButtonProps?.variant ?? 'outline', colorScheme: secondaryButtonProps?.colorScheme ?? 'functional' })) : null] }));
-    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Loading' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsx(Spinner, { size: "lg" }), _jsx(Heading, { size: "lg", textAlign: "center", children: loadingHeading })] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, children: heading })) : null, description && !image ? _jsx(BodyText, { accessible: true, children: description }) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, children: heading })) : null, description ? (_jsx(BodyText, { textAlign: "center", accessible: true, children: description })) : null] })] })) : null, children, hasFooter ? _jsx(View, { style: footerStyle, children: footerContent }) : null] })) }));
+    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Loading' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsx(Spinner, { size: "lg" }), _jsx(Heading, { size: "lg", textAlign: "center", children: loadingHeading })] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, ref: viewRef, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, children: heading })) : null, hasDescription && !image ? (descriptionIsText ? (_jsx(BodyText, { accessible: true, children: description })) : (description)) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, children: heading })) : null, hasDescription ? (descriptionIsText ? (_jsx(BodyText, { textAlign: "center", accessible: true, children: description })) : (description)) : null] })] })) : null, children, hasFooter ? _jsx(View, { style: footerStyle, children: footerContent }) : null] })) }));
     return (_jsx(BottomSheetModal, { ref: bottomSheetModalRef, enableDynamicSizing: true, snapPoints: image || fullscreen ? ['90%'] : props.snapPoints, showHandle: typeof loading !== 'undefined' && loading ? false : props.showHandle, accessible: false, ...props, onChange: handleChange, children: _jsx(BottomSheetScrollView, { contentContainerStyle: styles.container, ref: scrollViewRef, children: content }) }));
 };
 const styles = StyleSheet.create(theme => ({

package/build/components/NavModal/NavModal.js

@@ -63,6 +63,8 @@ const NavModal = ({ ref, children, heading, description, showCloseButton = true,
     const hasPrimaryButton = !!(onPressPrimaryButton && primaryButtonText);
     const hasSecondaryButton = !!(onPressSecondaryButton && secondaryButtonText);
     const hasFooter = !!footer || hasPrimaryButton || hasSecondaryButton;
+    const descriptionIsText = typeof description === 'string' || typeof description === 'number';
+    const hasDescription = description !== undefined && description !== null;
     styles.useVariants({
         loading,
         background: isBrandBackground ? 'brand' : 'primary',
@@ -83,7 +85,7 @@ const NavModal = ({ ref, children, heading, description, showCloseButton = true,
         secondaryButtonProps,
         secondaryButtonText,
     ]);
-    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? (loadingHeading ?? 'Loading') : undefined, accessibilityHint: Platform.OS === 'android' && loadingDescription ? loadingDescription : undefined, screenReaderFocusable: true, children: [_jsx(Spinner, { size: "lg", color: isBrandBackground ? theme.color.icon.inverted : undefined }), _jsx(Heading, { size: "lg", textAlign: "center", inverted: isBrandBackground, children: loadingHeading }), loadingDescription ? (_jsx(BodyText, { size: "md", textAlign: "center", inverted: isBrandBackground, children: loadingDescription })) : null] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, inverted: isBrandBackground, children: heading })) : null, description && !image ? (_jsx(BodyText, { accessible: true, inverted: isBrandBackground, children: description })) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", inverted: isBrandBackground, ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, inverted: isBrandBackground, children: heading })) : null, description ? (_jsx(BodyText, { textAlign: "center", accessible: true, inverted: isBrandBackground, children: description })) : null] })] })) : null, scrollable ? (_jsxs(ScrollView, { style: {
+    const content = (_jsx(_Fragment, { children: loading ? (_jsxs(View, { style: styles.loadingContainer, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? (loadingHeading ?? 'Loading') : undefined, accessibilityHint: Platform.OS === 'android' && loadingDescription ? loadingDescription : undefined, screenReaderFocusable: true, children: [_jsx(Spinner, { size: "lg", color: isBrandBackground ? theme.color.icon.inverted : undefined }), _jsx(Heading, { size: "lg", textAlign: "center", inverted: isBrandBackground, children: loadingHeading }), loadingDescription ? (_jsx(BodyText, { size: "md", textAlign: "center", inverted: isBrandBackground, children: loadingDescription })) : null] })) : (_jsxs(View, { style: styles.container, accessible: Platform.OS === 'android' ? true : undefined, accessibilityLabel: Platform.OS === 'android' ? 'Modal content' : undefined, screenReaderFocusable: true, children: [_jsxs(View, { style: styles.header, children: [_jsxs(View, { style: styles.headerTextContent, children: [heading && !image ? (_jsx(Heading, { size: "lg", accessible: true, inverted: isBrandBackground, children: heading })) : null, hasDescription && !image ? (descriptionIsText ? (_jsx(BodyText, { accessible: true, inverted: isBrandBackground, children: description })) : (description)) : null] }), showCloseButton ? (_jsx(UnstyledIconButton, { icon: CloseMediumIcon, onPress: handleCloseButtonPress, accessibilityLabel: "Close modal", inverted: isBrandBackground, ...closeButtonProps })) : null] }), image ? (_jsxs(View, { style: styles.imageContainer, children: [image, _jsxs(View, { style: styles.textContent, children: [heading ? (_jsx(Heading, { size: "lg", textAlign: "center", accessible: true, inverted: isBrandBackground, children: heading })) : null, hasDescription ? (descriptionIsText ? (_jsx(BodyText, { textAlign: "center", accessible: true, inverted: isBrandBackground, children: description })) : (description)) : null] })] })) : null, scrollable ? (_jsxs(ScrollView, { style: {
                         flex: stickyFooter ? 1 : 0,
                         marginHorizontal: -4,
                     }, contentContainerStyle: { paddingHorizontal: 4 }, ...scrollViewProps, children: [children, !stickyFooter && hasFooter ? (_jsx(View, { style: [styles.inNavModalFooterContainer, footerStyle], children: footerContent })) : null] })) : (_jsxs(View, { style: {

package/docs/changelog.mdx

@@ -9,6 +9,37 @@ import { BackToTopButton, NextPrevPage } from './components';
 The changelog for the Hearth React Native library. Here you can find all the changes, improvements, and bug fixes for each version.
 
 
+## 0.34.5
+
+### Patch Changes
+
+- [#1384](https://github.com/utilitywarehouse/hearth/pull/1384) [`be839e2`](https://github.com/utilitywarehouse/hearth/commit/be839e2ca46f079a0fe867f976044f4f31cca551) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: `NavModal` and `Modal` `description` prop accepts JSX
+
+  `description` now accepts `ReactNode` in addition to a string, so you can pass
+  custom content such as links or styled text alongside the default text
+  styling.
+
+  **Components affected**:
+
+  - `NavModal`
+  - `Modal`
+
+  **Developer changes**:
+
+  No changes required for existing usage. To pass custom content, provide JSX
+  instead of a string:
+
+  ```tsx
+  <Modal
+    heading="Update available"
+    description={
+      <BodyText>
+        Read the <InlineLink onPress={() => {}}>release notes</InlineLink> before updating.
+      </BodyText>
+    }
+  />
+  ```
+
 ## 0.34.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.34.4",
+  "version": "0.34.5",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -60,9 +60,9 @@
     "vite-plugin-svgr": "^4.5.0",
     "vitest": "^4.1.7",
     "@utilitywarehouse/hearth-storybook-utils": "0.0.0",
+    "@utilitywarehouse/hearth-react-icons": "^0.8.6",
+    "@utilitywarehouse/hearth-react-native-icons": "^0.8.5",
     "@utilitywarehouse/hearth-fonts": "^0.1.1",
-    "@utilitywarehouse/hearth-react-icons": "^0.8.5",
-    "@utilitywarehouse/hearth-react-native-icons": "^0.8.4",
     "@utilitywarehouse/hearth-svg-assets": "^0.6.4",
     "@utilitywarehouse/hearth-tokens": "^0.4.1"
   },

package/src/components/Modal/Modal.docs.mdx

@@ -1,5 +1,15 @@
 import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
-import { BodyText, BottomSheetModal, Box, Button, Center, Flex, Heading, Modal } from '../../';
+import {
+  BodyText,
+  BottomSheetModal,
+  Box,
+  Button,
+  Center,
+  Flex,
+  Heading,
+  InlineLink,
+  Modal,
+} from '../../';
 import StorybookLink from '../../../../../shared/storybook/StorybookLink';
 import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
 import * as Stories from './Modal.stories';
@@ -31,6 +41,7 @@ If you need a modal layout inside a React Navigation modal screen, use <Storyboo
   - [Modal with Image](#modal-with-image)
   - [Fullscreen Modal](#fullscreen-modal)
   - [Modal with Custom Content](#modal-with-custom-content)
+  - [JSX Description](#jsx-description)
   - [Sticky Custom Footer](#sticky-custom-footer)
   - [Loading State](#loading-state)
   - [Without Close Button](#without-close-button)
@@ -93,30 +104,30 @@ const MyComponent = () => {
 
 The Modal component extends the `BottomSheetModal` component and accepts all of its props, plus the following additional props:
 
-| Property                      | Type                                                               | Description                                                                                                        | Default        |
-| ----------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------- |
-| `heading`                     | `string`                                                           | The heading text displayed at the top of the modal                                                                 | -              |
-| `description`                 | `string`                                                           | The description text displayed below the heading                                                                   | -              |
-| `showCloseButton`             | `boolean`                                                          | Whether to show the close button in the top-right corner                                                           | `true`         |
-| `primaryButtonText`           | `string`                                                           | Text for the primary action button                                                                                 | -              |
-| `secondaryButtonText`         | `string`                                                           | Text for the secondary action button                                                                               | -              |
-| `onPressPrimaryButton`        | `() => void`                                                       | Callback function called when the primary button is pressed                                                        | -              |
-| `onPressSecondaryButton`      | `() => void`                                                       | Callback function called when the secondary button is pressed                                                      | -              |
-| `onPressCloseButton`          | `() => void`                                                       | Callback function called when the close button is pressed                                                          | -              |
-| `closeOnPrimaryButtonPress`   | `boolean`                                                          | Whether to automatically close the modal when the primary button is pressed                                        | `true`         |
-| `closeOnSecondaryButtonPress` | `boolean`                                                          | Whether to automatically close the modal when the secondary button is pressed                                      | `true`         |
-| `onChange`                    | `(index: number, position: number, `<br />` type: number) => void` | Callback function called when the modal's position changes \*                                                      | -              |
-| `loading`                     | `boolean`                                                          | Whether to show a loading state with spinner                                                                       | `false`        |
-| `loadingHeading`              | `string`                                                           | The heading text to be displayed when loading is true. If not provided, the regular heading will be shown.         | `'Loading...'` |
-| `loadingDescription`          | `string`                                                           | The description text to be displayed when loading is true. If not provided, the regular description will be shown. | -              |
-| `image`                       | `ImageProps`                                                       | Image to display in the modal (shows as centered content with text below)                                          | -              |
-| `children`                    | `ReactNode`                                                        | Custom content to display in the modal body                                                                        | -              |
-| `primaryButtonProps`          | `Omit<ButtonWithoutChildrenProps, 'children'>`                     | Additional props to pass to the primary button (colorScheme defaults to 'highlight', variant to 'solid')           | -              |
-| `secondaryButtonProps`        | `Omit<ButtonWithoutChildrenProps, 'children'>`                     | Additional props to pass to the secondary button (colorScheme defaults to 'functional', variant to 'outline')      | -              |
-| `footer`                      | `ReactNode`                                                        | Custom footer content that replaces the built-in action buttons                                                    | -              |
-| `footerStyle`                 | `StyleProp<ViewStyle>`                                             | Styles applied to the footer container, useful for sticky footer shadows or custom spacing                         | -              |
-| `closeButtonProps`            | `Omit<UnstyledIconButtonProps, 'children'>`                        | Additional props to pass to the close button                                                                       | -              |
-| `fullscreen`                  | `boolean`                                                          | Whether the modal should take up the full screen height                                                            | `false`        |
+| Property                      | Type                                                               | Description                                                                                                            | Default        |
+| ----------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `heading`                     | `string`                                                           | The heading text displayed at the top of the modal                                                                     | -              |
+| `description`                 | `ReactNode`                                                        | The description content displayed below the heading. Pass a string for the default styling, or JSX for custom content. | -              |
+| `showCloseButton`             | `boolean`                                                          | Whether to show the close button in the top-right corner                                                               | `true`         |
+| `primaryButtonText`           | `string`                                                           | Text for the primary action button                                                                                     | -              |
+| `secondaryButtonText`         | `string`                                                           | Text for the secondary action button                                                                                   | -              |
+| `onPressPrimaryButton`        | `() => void`                                                       | Callback function called when the primary button is pressed                                                            | -              |
+| `onPressSecondaryButton`      | `() => void`                                                       | Callback function called when the secondary button is pressed                                                          | -              |
+| `onPressCloseButton`          | `() => void`                                                       | Callback function called when the close button is pressed                                                              | -              |
+| `closeOnPrimaryButtonPress`   | `boolean`                                                          | Whether to automatically close the modal when the primary button is pressed                                            | `true`         |
+| `closeOnSecondaryButtonPress` | `boolean`                                                          | Whether to automatically close the modal when the secondary button is pressed                                          | `true`         |
+| `onChange`                    | `(index: number, position: number, `<br />` type: number) => void` | Callback function called when the modal's position changes \*                                                          | -              |
+| `loading`                     | `boolean`                                                          | Whether to show a loading state with spinner                                                                           | `false`        |
+| `loadingHeading`              | `string`                                                           | The heading text to be displayed when loading is true. If not provided, the regular heading will be shown.             | `'Loading...'` |
+| `loadingDescription`          | `string`                                                           | The description text to be displayed when loading is true. If not provided, the regular description will be shown.     | -              |
+| `image`                       | `ImageProps`                                                       | Image to display in the modal (shows as centered content with text below)                                              | -              |
+| `children`                    | `ReactNode`                                                        | Custom content to display in the modal body                                                                            | -              |
+| `primaryButtonProps`          | `Omit<ButtonWithoutChildrenProps, 'children'>`                     | Additional props to pass to the primary button (colorScheme defaults to 'highlight', variant to 'solid')               | -              |
+| `secondaryButtonProps`        | `Omit<ButtonWithoutChildrenProps, 'children'>`                     | Additional props to pass to the secondary button (colorScheme defaults to 'functional', variant to 'outline')          | -              |
+| `footer`                      | `ReactNode`                                                        | Custom footer content that replaces the built-in action buttons                                                        | -              |
+| `footerStyle`                 | `StyleProp<ViewStyle>`                                             | Styles applied to the footer container, useful for sticky footer shadows or custom spacing                             | -              |
+| `closeButtonProps`            | `Omit<UnstyledIconButtonProps, 'children'>`                        | Additional props to pass to the close button                                                                           | -              |
+| `fullscreen`                  | `boolean`                                                          | Whether the modal should take up the full screen height                                                                | `false`        |
 
 When `footer` is provided, the primary and secondary button props are not available. Build your footer actions directly inside the custom footer content instead.
 
@@ -381,6 +392,22 @@ const CustomContentModal = () => {
 };
 ```
 
+### JSX Description
+
+`description` accepts a string for the default text styling, or JSX when you need custom content such as a link:
+
+```tsx
+<Modal
+  ref={modalRef}
+  heading="Update available"
+  description={
+    <BodyText>
+      Read the <InlineLink onPress={() => {}}>release notes</InlineLink> before updating.
+    </BodyText>
+  }
+/>
+```
+
 ### Sticky Custom Footer
 
 Replace the built-in buttons with a custom sticky footer when you need custom layouts or button arrangements:

package/src/components/Modal/Modal.shared.types.ts

@@ -10,7 +10,7 @@ export interface ModalCommonBaseProps {
   heading?: string;
   loadingHeading?: string;
   loadingDescription?: string;
-  description?: string;
+  description?: ReactNode;
   stickyFooter?: boolean;
   children?: ViewProps['children'];
   onPressCloseButton?: () => void;

package/src/components/Modal/Modal.tsx

@@ -117,6 +117,8 @@ const Modal = ({
   const hasSecondaryButton = !!(onPressSecondaryButton && secondaryButtonText);
   const hasFooter = !!footer || hasPrimaryButton || hasSecondaryButton;
   const shouldShowFooter = !loading && hasFooter;
+  const descriptionIsText = typeof description === 'string' || typeof description === 'number';
+  const hasDescription = description !== undefined && description !== null;
 
   styles.useVariants({
     loading,
@@ -197,7 +199,13 @@ const Modal = ({
                   {heading}
                 </Heading>
               ) : null}
-              {description && !image ? <BodyText accessible>{description}</BodyText> : null}
+              {hasDescription && !image ? (
+                descriptionIsText ? (
+                  <BodyText accessible>{description}</BodyText>
+                ) : (
+                  description
+                )
+              ) : null}
             </View>
             {showCloseButton ? (
               <UnstyledIconButton
@@ -217,10 +225,14 @@ const Modal = ({
                     {heading}
                   </Heading>
                 ) : null}
-                {description ? (
-                  <BodyText textAlign="center" accessible>
-                    {description}
-                  </BodyText>
+                {hasDescription ? (
+                  descriptionIsText ? (
+                    <BodyText textAlign="center" accessible>
+                      {description}
+                    </BodyText>
+                  ) : (
+                    description
+                  )
                 ) : null}
               </View>
             </View>

package/src/components/Modal/Modal.web.tsx

@@ -96,6 +96,8 @@ const Modal = ({
   const hasPrimaryButton = !!(onPressPrimaryButton && primaryButtonText);
   const hasSecondaryButton = !!(onPressSecondaryButton && secondaryButtonText);
   const hasFooter = !!footer || hasPrimaryButton || hasSecondaryButton;
+  const descriptionIsText = typeof description === 'string' || typeof description === 'number';
+  const hasDescription = description !== undefined && description !== null;
 
   const footerContent = footer ?? (
     <View style={styles.footer}>
@@ -150,7 +152,13 @@ const Modal = ({
                   {heading}
                 </Heading>
               ) : null}
-              {description && !image ? <BodyText accessible>{description}</BodyText> : null}
+              {hasDescription && !image ? (
+                descriptionIsText ? (
+                  <BodyText accessible>{description}</BodyText>
+                ) : (
+                  description
+                )
+              ) : null}
             </View>
             {showCloseButton ? (
               <UnstyledIconButton
@@ -170,10 +178,14 @@ const Modal = ({
                     {heading}
                   </Heading>
                 ) : null}
-                {description ? (
-                  <BodyText textAlign="center" accessible>
-                    {description}
-                  </BodyText>
+                {hasDescription ? (
+                  descriptionIsText ? (
+                    <BodyText textAlign="center" accessible>
+                      {description}
+                    </BodyText>
+                  ) : (
+                    description
+                  )
                 ) : null}
               </View>
             </View>

package/src/components/NavModal/NavModal.docs.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
-import { BodyText, Button, Flex } from '../../';
+import { BodyText, Button, Flex, InlineLink } from '../../';
 import StorybookLink from '../../../../../shared/storybook/StorybookLink';
 import modalAndroidVideo from '../../../docs/assets/modal-android.mp4';
 import modaliOSVideo from '../../../docs/assets/modal-ios.mp4';
@@ -139,7 +139,7 @@ const styles = StyleSheet.create({
 | Property                 | Type                                                                                                             | Description                                                                                                                                                                                      | Default        |
 | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
 | `heading`                | `string`                                                                                                         | Heading text shown at the top of the modal when no `image` is provided.                                                                                                                          | -              |
-| `description`            | `string`                                                                                                         | Supporting text shown below the heading when no `image` is provided.                                                                                                                             | -              |
+| `description`            | `ReactNode`                                                                                                      | Supporting text shown below the heading when no `image` is provided. Pass a string for the default styling, or JSX for custom content.                                                           | -              |
 | `showCloseButton`        | `boolean`                                                                                                        | Whether to render the close button in the top-right corner.                                                                                                                                      | `true`         |
 | `primaryButtonText`      | `string`                                                                                                         | Label for the primary action button.                                                                                                                                                             | -              |
 | `secondaryButtonText`    | `string`                                                                                                         | Label for the secondary action button.                                                                                                                                                           | -              |
@@ -206,3 +206,18 @@ When `footer` is provided, the primary and secondary button props are not availa
   <BodyText>This sticky footer stays pinned while the content scrolls.</BodyText>
 </NavModal>
 ```
+
+### JSX Description
+
+`description` accepts a string for the default text styling, or JSX when you need custom content such as a link.
+
+```tsx
+<NavModal
+  heading="Update available"
+  description={
+    <BodyText>
+      Read the <InlineLink onPress={() => {}}>release notes</InlineLink> before updating.
+    </BodyText>
+  }
+/>
+```

package/src/components/NavModal/NavModal.stories.tsx

@@ -4,6 +4,7 @@ import { BodyText } from '../BodyText';
 import { Box } from '../Box';
 import { Button } from '../Button';
 import { Flex } from '../Flex';
+import { LI, UL } from '../HTMLElements';
 import NavModal from './NavModal';
 
 const meta = {
@@ -158,3 +159,42 @@ export const StickyCustomFooter: Story = {
     </View>
   ),
 };
+
+export const WithJSXDescription: Story = {
+  render: () => (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 720 } : { flex: 1 }}>
+      <NavModal
+        heading="Confirm changes"
+        description={
+          <>
+            <BodyText>
+              This example uses a JSX element for the description prop. You can use any React
+              component here, including links, lists, and other text components.
+            </BodyText>
+            <UL>
+              <LI>
+                <BodyText>Item 1</BodyText>
+              </LI>
+            </UL>
+            <UL>
+              <LI>
+                <BodyText>Item 2</BodyText>
+              </LI>
+            </UL>
+            <UL>
+              <LI>
+                <BodyText>Item 3</BodyText>
+              </LI>
+            </UL>
+          </>
+        }
+      >
+        <Box gap="200">
+          <BodyText>
+            Use the description prop to provide additional context or instructions.
+          </BodyText>
+        </Box>
+      </NavModal>
+    </View>
+  ),
+};

package/src/components/NavModal/NavModal.tsx

@@ -115,6 +115,8 @@ const NavModal = ({
   const hasPrimaryButton = !!(onPressPrimaryButton && primaryButtonText);
   const hasSecondaryButton = !!(onPressSecondaryButton && secondaryButtonText);
   const hasFooter = !!footer || hasPrimaryButton || hasSecondaryButton;
+  const descriptionIsText = typeof description === 'string' || typeof description === 'number';
+  const hasDescription = description !== undefined && description !== null;
 
   styles.useVariants({
     loading,
@@ -201,10 +203,14 @@ const NavModal = ({
                   {heading}
                 </Heading>
               ) : null}
-              {description && !image ? (
-                <BodyText accessible inverted={isBrandBackground}>
-                  {description}
-                </BodyText>
+              {hasDescription && !image ? (
+                descriptionIsText ? (
+                  <BodyText accessible inverted={isBrandBackground}>
+                    {description}
+                  </BodyText>
+                ) : (
+                  description
+                )
               ) : null}
             </View>
             {showCloseButton ? (
@@ -226,10 +232,14 @@ const NavModal = ({
                     {heading}
                   </Heading>
                 ) : null}
-                {description ? (
-                  <BodyText textAlign="center" accessible inverted={isBrandBackground}>
-                    {description}
-                  </BodyText>
+                {hasDescription ? (
+                  descriptionIsText ? (
+                    <BodyText textAlign="center" accessible inverted={isBrandBackground}>
+                      {description}
+                    </BodyText>
+                  ) : (
+                    description
+                  )
                 ) : null}
               </View>
             </View>