@utilitywarehouse/hearth-react-native 0.34.5 → 0.35.0

package/{src/components/Modal/Modal.docs.mdx → public/llms/components/modal.md}

@@ -1,35 +1,13 @@
-import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
-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';
-
-<Meta title="Components / Modal" />
-
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6300-2825&t=JmfcCbdIvO3jcjc3-4" />
-
-<BackToTopButton />
-
 # Modal
 
 The `Modal` component provides a versatile dialog interface that slides up from the bottom of the screen. It's built on top of
-the <StorybookLink to="components-bottom-sheet">`BottomSheetModal`</StorybookLink>
+the `BottomSheetModal`
 component and includes pre-configured layouts for common modal patterns including headers, content areas, and action buttons.
 
 The Modal component is ideal for displaying important information, collecting user input, or presenting choices that require user attention
 without navigating away from the current screen.
 
-If you need a modal layout inside a React Navigation modal screen, use <StorybookLink to="components-nav-modal">`NavModal`</StorybookLink> instead.
+If you need a modal layout inside a React Navigation modal screen, use `NavModal` instead.
 
 - [Playground](#playground)
 - [Usage](#usage)
@@ -53,21 +31,21 @@ If you need a modal layout inside a React Navigation modal screen, use <Storyboo
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
-
-## Usage
+```tsx
+// Example usage
+<View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+  <ViewWrap>
+    <Button onPress={openModal}>Open Modal</Button>
+
+    <Modal ref={modalRef} {...args} />
+  </ViewWrap>
+</View>
+```
 
 ### Basic Usage
 
-<UsageWrap>
-  <Center>
-    <Button onPress={() => {}}>Open Modal</Button>
-  </Center>
-</UsageWrap>
-
 ```tsx
+// Example usage
 import { useRef, useCallback } from 'react';
 import { Modal, Button, BottomSheetModal } from '@utilitywarehouse/hearth-react-native';
 
@@ -144,9 +122,7 @@ The `ModalImage` component can be used to display an image within the Modal. It
 | `dark`    | `ImageSourcePropType` | The source of the image to display in dark mode (use instead of source)  |
 | `...rest` | `ImageProps`          | Additional props to pass to the underlying Image component               |
 
-For more details about the ThemedImage component used internally, refer to the <StorybookLink to="utility-components-themed-image">`ThemedImage` documentation</StorybookLink>.
-
-## Features
+For more details about the ThemedImage component used internally, refer to the `ThemedImage` documentation.
 
 ### Automatic Layout Management
 
@@ -188,6 +164,7 @@ The Modal component is built with comprehensive accessibility support to ensure
 The Modal component automatically manages focus to provide a seamless experience:
 
 ```tsx
+// Example usage
 // Focus is automatically set when modal opens
 const MyModal = () => {
   const modalRef = useRef<BottomSheetModal>(null);
@@ -210,6 +187,7 @@ const MyModal = () => {
 You can enhance accessibility by providing custom labels for buttons and close actions:
 
 ```tsx
+// Example usage
 <Modal
   ref={modalRef}
   heading="Delete Item"
@@ -234,6 +212,7 @@ You can enhance accessibility by providing custom labels for buttons and close a
 Loading states are fully accessible with proper announcements:
 
 ```tsx
+// Example usage
 <Modal
   ref={modalRef}
   heading="Processing Payment"
@@ -258,6 +237,7 @@ Loading states are fully accessible with proper announcements:
 To test accessibility in your Modal implementation:
 
 ```tsx
+// Example usage
 import { AccessibilityInfo } from 'react-native';
 
 const TestableModal = () => {
@@ -294,19 +274,39 @@ The Modal component handles platform-specific accessibility differences:
 - **Android**: Implements TalkBack-specific accessibility patterns
 - **Cross-platform**: Consistent behavior across both platforms
 
-## Examples
-
 ### Basic Modal
 
-<Canvas of={Stories.Playground} />
+```tsx
+// Example usage
+<View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+  <ViewWrap>
+    <Button onPress={openModal}>Open Modal</Button>
+
+    <Modal ref={modalRef} {...args} />
+  </ViewWrap>
+</View>
+```
 
 ### Modal with Image
 
 Use the `image` prop to display an image-centric modal with centered content:
 
-<Canvas of={Stories.WithImage} />
+```tsx
+// Example usage
+<Modal
+  heading="Modal Heading"
+  description="This is a modal description"
+  showCloseButton
+  primaryButtonText="Primary"
+  secondaryButtonText="Cancel"
+  onPressCloseButton={() => null}
+  onPressPrimaryButton={() => null}
+  onPressSecondaryButton={() => null}
+/>
+```
 
 ```tsx
+// Example usage
 import { Modal, ModalImage, Button } from '@utilitywarehouse/hearth-react-native';
 
 const ImageModal = () => {
@@ -335,9 +335,34 @@ const ImageModal = () => {
 
 Create a modal that takes up the full screen height:
 
-<Canvas of={Stories.FullscreenModal} />
+```tsx
+// Example usage
+<View style={Platform.OS === 'web' ? { width: 400, height: 800 } : { flex: 1 }}>
+  <ViewWrap>
+    <Button onPress={openModal}>Open Fullscreen Modal</Button>
+
+    <Modal
+      ref={modalRef}
+      heading="Fullscreen Modal Heading"
+      description="This is a fullscreen modal description"
+      onPressCloseButton={closeModal}
+      primaryButtonText="Primary"
+      onPressPrimaryButton={closeModal}
+      secondaryButtonText="Cancel"
+      onPressSecondaryButton={closeModal}
+      fullscreen
+    >
+      <Box gap="200">
+        <BodyText>This is a fullscreen modal with content.</BodyText>
+        <BodyText>You can swipe it up and down to close.</BodyText>
+      </Box>
+    </Modal>
+  </ViewWrap>
+</View>
+```
 
 ```tsx
+// Example usage
 const FullscreenModal = () => {
   const modalRef = useRef<BottomSheetModal>(null);
 
@@ -362,9 +387,22 @@ const FullscreenModal = () => {
 
 Add custom content between the header and footer sections:
 
-<Canvas of={Stories.WithCustomContent} />
+```tsx
+// Example usage
+<Modal
+  heading="Modal Heading"
+  description="This is a modal description"
+  showCloseButton
+  primaryButtonText="Primary"
+  secondaryButtonText="Cancel"
+  onPressCloseButton={() => null}
+  onPressPrimaryButton={() => null}
+  onPressSecondaryButton={() => null}
+/>
+```
 
 ```tsx
+// Example usage
 const CustomContentModal = () => {
   const modalRef = useRef<BottomSheetModal>(null);
 
@@ -397,6 +435,7 @@ const CustomContentModal = () => {
 `description` accepts a string for the default text styling, or JSX when you need custom content such as a link:
 
 ```tsx
+// Example usage
 <Modal
   ref={modalRef}
   heading="Update available"
@@ -412,9 +451,22 @@ const CustomContentModal = () => {
 
 Replace the built-in buttons with a custom sticky footer when you need custom layouts or button arrangements:
 
-<Canvas of={Stories.StickyCustomFooter} />
+```tsx
+// Example usage
+<Modal
+  heading="Modal Heading"
+  description="This is a modal description"
+  showCloseButton
+  primaryButtonText="Primary"
+  secondaryButtonText="Cancel"
+  onPressCloseButton={() => null}
+  onPressPrimaryButton={() => null}
+  onPressSecondaryButton={() => null}
+/>
+```
 
 ```tsx
+// Example usage
 const StickyCustomFooterModal = () => {
   const modalRef = useRef<BottomSheetModal>(null);
 
@@ -458,9 +510,22 @@ const StickyCustomFooterModal = () => {
 
 Show a loading spinner while processing:
 
-<Canvas of={Stories.Loading} />
+```tsx
+// Example usage
+<Modal
+  heading="Modal Heading"
+  description="This is a modal description"
+  showCloseButton
+  primaryButtonText="Primary"
+  secondaryButtonText="Cancel"
+  onPressCloseButton={() => null}
+  onPressPrimaryButton={() => null}
+  onPressSecondaryButton={() => null}
+/>
+```
 
 ```tsx
+// Example usage
 const LoadingModal = () => {
   const modalRef = useRef<BottomSheetModal>(null);
   const [isLoading, setIsLoading] = useState(false);
@@ -496,6 +561,7 @@ const LoadingModal = () => {
 Remove the close button for critical actions:
 
 ```tsx
+// Example usage
 const CriticalModal = () => {
   const modalRef = useRef<BottomSheetModal>(null);
 
@@ -523,6 +589,7 @@ const CriticalModal = () => {
 Create a modal with only one action button:
 
 ```tsx
+// Example usage
 const AlertModal = () => {
   const modalRef = useRef<BottomSheetModal>(null);
 
@@ -544,7 +611,7 @@ const AlertModal = () => {
 
 ### Navigation Modals
 
-For React Navigation modal screens, use <StorybookLink to="components-navmodal">`NavModal`</StorybookLink>. It contains the extracted screen-based modal layout, background variants, scrollable content handling, and the Android `triggerCloseAnimation()` ref used during navigation dismissal.
+For React Navigation modal screens, use `NavModal`. It contains the extracted screen-based modal layout, background variants, scrollable content handling, and the Android `triggerCloseAnimation()` ref used during navigation dismissal.
 
 ### Close handlers and state management
 
@@ -556,6 +623,7 @@ The Modal component provides multiple ways to handle closing the modal and manag
 - Use the `onChange` prop to detect when the modal is opened or closed based on the index parameter (0 for open, -1 for closed) and manage state accordingly.
 
 ```tsx
+// Example usage
 const MyModal = () => {
   const modalRef = useRef<BottomSheetModal>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
@@ -593,13 +661,12 @@ const MyModal = () => {
 };
 ```
 
-## Integration Notes
-
 ### BottomSheetModalProvider
 
 When using the Modal component, ensure your app is wrapped with `BottomSheetModalProvider`:
 
 ```tsx
+// Example usage
 import { BottomSheetModalProvider } from '@utilitywarehouse/hearth-react-native';
 
 const App = () => {
@@ -610,6 +677,7 @@ const App = () => {
 If your app already handles safe-area padding around modal content, you can disable Hearth's bottom-sheet safe-area spacing:
 
 ```tsx
+// Example usage
 import { BottomSheetModalProvider } from '@utilitywarehouse/hearth-react-native';
 
 const App = () => {
@@ -632,6 +700,7 @@ The Modal component forwards its ref to the underlying `BottomSheetModal`, givin
 - `snapToPosition(position)` - Snap to a specific position
 
 ```tsx
+// Example usage
 const modalRef = useRef<BottomSheetModal>(null);
 
 // Open modal
@@ -647,5 +716,5 @@ modalRef.current?.snapToIndex(1);
 ## External Resources
 
 This component is built on top of [@gorhom/bottom-sheet](https://gorhom.github.io/react-native-bottom-sheet/) (v5). For more information about the
-underlying BottomSheet functionality, please refer to the <StorybookLink to="components-bottomsheet">BottomSheet documentation</StorybookLink> and
+underlying BottomSheet functionality, please refer to the BottomSheet documentation and
 the [official documentation](https://gorhom.dev/react-native-bottom-sheet/).

package/{src/components/NavModal/NavModal.docs.mdx → public/llms/components/nav-modal.md}

@@ -1,22 +1,8 @@
-import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
-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';
-import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './NavModal.stories';
-
-<Meta title="Components / Nav Modal" />
-
-<ViewFigmaButton url="https://www.figma.com/design/dLI9bmyMr42LV7dtFeW27J/Hearth-Patterns---Guides?node-id=6314-9103&t=oq3NaPLaAu3di6Db-4" />
-
-<BackToTopButton />
-
 # Nav Modal
 
 The `NavModal` component is the screen-based modal layout for navigation flows. Use it when a screen is already being presented by React Navigation with `presentation: 'modal'` or `presentation: 'fullScreenModal'` and you want Hearth's modal structure, actions, and Android close animation support.
 
-If you need a bottom-sheet modal that you present with a ref, use <StorybookLink to="components-modal">`Modal`</StorybookLink> instead.
+If you need a bottom-sheet modal that you present with a ref, use `Modal` instead.
 
 - [Playground](#playground)
 - [Usage](#usage)
@@ -27,13 +13,22 @@ If you need a bottom-sheet modal that you present with a ref, use <StorybookLink
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<View style={Platform.OS === 'web' ? { width: 400, height: 720 } : { flex: 1 }}>
+  <NavModal {...args}>
+    <Box gap="200">
+      <BodyText>This is a navigation modal with content.</BodyText>
+      <BodyText>Use it for React Navigation modal screens instead of bottom sheets.</BodyText>
+    </Box>
+  </NavModal>
+</View>
+```
 
 ## Usage
 
 ```tsx
+// Example usage
 import { useNavigation } from '@react-navigation/native';
 import type { NavigationAction } from '@react-navigation/native';
 import { useCallback, useEffect, useRef } from 'react';
@@ -171,23 +166,68 @@ When `footer` is provided, the primary and secondary button props are not availa
 
 ## Examples
 
-| ios                                                                            | android                                                                            |
-| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
-| <video src={modaliOSVideo} width={300} height="auto" controls loop autoPlay /> | <video src={modalAndroidVideo} width={300} height="auto" controls loop autoPlay /> |
+| ios | android |
+| --- | ------- |
+|     |         |
 
 ### Brand Background
 
-<Canvas of={Stories.BrandBackground} />
+```tsx
+// Example usage
+<View style={Platform.OS === 'web' ? { width: 400, height: 720 } : { flex: 1 }}>
+  <NavModal {...args}>
+    <Box gap="200">
+      <BodyText inverted>Brand background content stays readable with inverted text.</BodyText>
+      <BodyText inverted>Buttons and the close icon also invert automatically.</BodyText>
+    </Box>
+  </NavModal>
+</View>
+```
 
 ### Full-Screen Presentation
 
-<Canvas of={Stories.FullScreenPresentation} />
+```tsx
+// Example usage
+<View style={Platform.OS === 'web' ? { width: 400, height: 720 } : { flex: 1 }}>
+  <NavModal {...args}>
+    <Box gap="200">
+      <BodyText>This uses the full-screen navigation modal presentation.</BodyText>
+      <BodyText>The content switches away from the sheet-style card treatment.</BodyText>
+    </Box>
+  </NavModal>
+</View>
+```
 
 ### Sticky Custom Footer
 
-<Canvas of={Stories.StickyCustomFooter} />
+```tsx
+// Example usage
+<View style={Platform.OS === 'web' ? { width: 400, height: 720 } : { flex: 1 }}>
+  <NavModal
+    heading="Confirm changes"
+    description="This example replaces the default buttons with a custom sticky footer."
+    footer={
+      <Flex direction="row" spacing="md">
+        <Button variant="outline" colorScheme="functional" style={{ flex: 1 }}>
+          Back
+        </Button>
+        <Button style={{ flex: 1 }}>Continue</Button>
+      </Flex>
+    }
+    footerStyle={{
+      boxShadow: '0px -6px 12px rgba(16, 24, 40, 0.12)',
+    }}
+  >
+    <Box gap="200">
+      <BodyText>This sticky footer stays pinned while the body content scrolls.</BodyText>
+      <BodyText>Use the footer prop when you need custom layouts or custom buttons.</BodyText>
+    </Box>
+  </NavModal>
+</View>
+```
 
 ```tsx
+// Example usage
 <NavModal
   heading="Confirm changes"
   description="Use a custom sticky footer when your actions need a custom layout."
@@ -212,6 +252,7 @@ When `footer` is provided, the primary and secondary button props are not availa
 `description` accepts a string for the default text styling, or JSX when you need custom content such as a link.
 
 ```tsx
+// Example usage
 <NavModal
   heading="Update available"
   description={

package/{src/components/Pagination/Pagination.docs.mdx → public/llms/components/pagination.md}

@@ -1,14 +1,3 @@
-import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
-import { Box, Center, Pagination } from '../..';
-import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
-import * as Stories from './Pagination.stories';
-
-<Meta title="Components / Pagination" />
-
-<BackToTopButton />
-
-<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6416-5836&t=pZwKJYFo1y1QRQD1-4" />
-
 # Pagination
 
 Pagination helps users move between pages of content while keeping the current position visible. It supports both a full page list and a condensed “Page X of Y” layout.
@@ -20,21 +9,15 @@ Pagination helps users move between pages of content while keeping the current p
 
 ## Playground
 
-<Canvas of={Stories.Playground} />
-
-<Controls of={Stories.Playground} />
+```tsx
+// Example usage
+<Pagination {...args} currentPage={currentPage} onPageChange={setCurrentPage} />
+```
 
 ## Usage
 
-<UsageWrap>
-  <Center>
-    <Box style={{ width: 520, maxWidth: '100%' }}>
-      <Pagination currentPage={3} totalPages={10} onPageChange={() => {}} />
-    </Box>
-  </Center>
-</UsageWrap>
-
 ```tsx
+// Example usage
 import { Pagination } from '@utilitywarehouse/hearth-react-native';
 import { useState } from 'react';
 
@@ -55,13 +38,15 @@ const MyComponent = () => {
 | `condensed`       | `boolean`                | Displays “Page X of Y” instead of numbered items. | `false`  |
 | `hideSkipButtons` | `boolean`                | Hides the first and last page controls.           | `false`  |
 
-## Examples
-
 ### Condensed
 
-<Canvas of={Stories.Condensed} />
+```tsx
+// Example usage
+<Pagination condensed currentPage={currentPage} onPageChange={setCurrentPage} totalPages={10} />
+```
 
 ```tsx
+// Example usage
 const [currentPage, setCurrentPage] = useState(1);
 
 <Pagination condensed currentPage={currentPage} onPageChange={setCurrentPage} totalPages={10} />;
@@ -69,9 +54,18 @@ const [currentPage, setCurrentPage] = useState(1);
 
 ### Without skip buttons
 
-<Canvas of={Stories.WithoutSkipButtons} />
+```tsx
+// Example usage
+<Pagination
+  currentPage={currentPage}
+  hideSkipButtons
+  onPageChange={setCurrentPage}
+  totalPages={10}
+/>
+```
 
 ```tsx
+// Example usage
 const [currentPage, setCurrentPage] = useState(3);
 
 <Pagination
@@ -84,9 +78,26 @@ const [currentPage, setCurrentPage] = useState(3);
 
 ### Edge cases
 
-<Canvas of={Stories.EdgeCases} />
+```tsx
+// Example usage
+<Flex direction="column" spacing="lg" style={{ width: '100%', maxWidth: 520 }}>
+  <Flex direction="column" spacing="xs">
+    <BodyText size="sm">Near start</BodyText>
+    <Pagination currentPage={nearStartPage} onPageChange={setNearStartPage} totalPages={10} />
+  </Flex>
+  <Flex direction="column" spacing="xs">
+    <BodyText size="sm">Middle</BodyText>
+    <Pagination currentPage={middlePage} onPageChange={setMiddlePage} totalPages={10} />
+  </Flex>
+  <Flex direction="column" spacing="xs">
+    <BodyText size="sm">Near end</BodyText>
+    <Pagination currentPage={nearEndPage} onPageChange={setNearEndPage} totalPages={10} />
+  </Flex>
+</Flex>
+```
 
 ```tsx
+// Example usage
 const [nearStartPage, setNearStartPage] = useState(2);
 const [middlePage, setMiddlePage] = useState(5);
 const [nearEndPage, setNearEndPage] = useState(9);