@utilitywarehouse/hearth-react-native 0.30.4 → 0.31.0

package/src/components/ExpandableCard/ExpandableCard.docs.mdx

@@ -22,6 +22,7 @@ The `ExpandableCard` component is an interactive card that expands to reveal add
   - [With Leading Icon](#with-leading-icon)
   - [With `Badge`](#with-badge)
   - [With Numeric Value](#with-numeric-value)
+  - [With Custom Trigger Content](#with-custom-trigger-content)
   - [`CardGroup`](#cardgroup)
 - [Advanced Usage](#advanced-usage)
 - [Accessibility](#accessibility)
@@ -58,24 +59,27 @@ const MyComponent = () => (
 
 ### `ExpandableCard`
 
-| Prop               | Type                          | Default             | Description                                      |
-| ------------------ | ----------------------------- | ------------------- | ------------------------------------------------ |
-| `heading`          | `string`                      | -                   | The heading text displayed in the trigger        |
-| `helperText`       | `string`                      | -                   | Optional helper text displayed below the heading |
-| `leadingIcon`      | `ComponentType`               | -                   | Leading icon component (automatically wrapped)   |
-| `leadingContent`   | `ReactNode`                   | -                   | Leading content (icon or custom element)         |
-| `badge`            | `ReactNode`                   | -                   | Badge to display                                 |
-| `badgePosition`    | `'top' \| 'bottom'`           | `'bottom'`          | Badge position                                   |
-| `numericValue`     | `string \| number`            | -                   | Numeric value to display on the right            |
-| `expandedContent`  | `ReactNode`                   | -                   | The content to show when expanded                |
-| `expanded`         | `boolean`                     | -                   | Whether the card is expanded (controlled)        |
-| `onExpandedChange` | `(expanded: boolean) => void` | -                   | Callback when expanded state changes             |
-| `duration`         | `number`                      | `200`               | Duration of expansion animation in milliseconds  |
-| `animateOpacity`   | `boolean`                     | `true`              | Whether to animate opacity during expansion      |
-| `disabled`         | `boolean`                     | `false`             | Whether the card is disabled                     |
-| `colorScheme`      | `CardColorScheme`             | -                   | Color scheme (inherits from Card component)      |
-| `variant`          | `CardVariant`                 | -                   | Variant (inherits from Card component)           |
-| `testID`           | `string`                      | `'expandable-card'` | Test ID for testing                              |
+| Prop               | Type                          | Default             | Description                                                    |
+| ------------------ | ----------------------------- | ------------------- | -------------------------------------------------------------- |
+| `heading`          | `string`                      | -                   | The heading text displayed in the trigger                      |
+| `helperText`       | `string`                      | -                   | Optional helper text displayed below the heading               |
+| `leadingIcon`      | `ComponentType`               | -                   | Leading icon component (automatically wrapped)                 |
+| `leadingContent`   | `ReactNode`                   | -                   | Leading content (icon or custom element)                       |
+| `badge`            | `ReactNode`                   | -                   | Badge to display                                               |
+| `badgePosition`    | `'top' \| 'bottom'`           | `'bottom'`          | Badge position                                                 |
+| `numericValue`     | `string \| number`            | -                   | Numeric value to display on the right                          |
+| `triggerContent`   | `ReactNode`                   | -                   | Replaces the default trigger content while keeping the chevron |
+| `expandedContent`  | `ReactNode`                   | -                   | The content to show when expanded                              |
+| `expanded`         | `boolean`                     | -                   | Whether the card is expanded (controlled)                      |
+| `onExpandedChange` | `(expanded: boolean) => void` | -                   | Callback when expanded state changes                           |
+| `duration`         | `number`                      | `200`               | Duration of expansion animation in milliseconds                |
+| `animateOpacity`   | `boolean`                     | `true`              | Whether to animate opacity during expansion                    |
+| `disabled`         | `boolean`                     | `false`             | Whether the card is disabled                                   |
+| `colorScheme`      | `CardColorScheme`             | -                   | Color scheme (inherits from Card component)                    |
+| `variant`          | `CardVariant`                 | -                   | Variant (inherits from Card component)                         |
+| `testID`           | `string`                      | `'expandable-card'` | Test ID for testing                                            |
+
+When `triggerContent` is provided, the default trigger props such as `heading`, `helperText`, `leadingIcon`, `leadingContent`, `badge`, `badgePosition`, and `numericValue` are not available.
 
 ### `ExpandableCardGroup`
 
@@ -175,6 +179,34 @@ const MyComponent = () => (
 />
 ```
 
+    ### With Custom Trigger Content
+
+    Use `triggerContent` when you need to replace the standard trigger layout entirely while keeping the expandable chevron.
+
+    <Canvas of={Stories.WithCustomTriggerContent} />
+
+    ```tsx
+    import { ExpandableCard, BodyText } from '@utilitywarehouse/hearth-react-native';
+    import { View } from 'react-native';
+
+    const MyComponent = () => (
+      <ExpandableCard
+        triggerContent={
+          <View style={{ flex: 1, gap: 4 }}>
+            <BodyText weight="semibold">March bill ready</BodyText>
+            <BodyText color="secondary">Due on 18 April 2026</BodyText>
+          </View>
+        }
+        expandedContent={
+          <>
+            <BodyText>Balance: £89.50</BodyText>
+            <BodyText>Payment method: Direct Debit</BodyText>
+          </>
+        }
+      />
+    );
+    ```
+
 ### `CardGroup`
 
 Use `ExpandableCardGroup` to group multiple expandable cards with an optional header.
@@ -239,34 +271,52 @@ import {
   ExpandableCardTrigger,
   ExpandableCardExpandedContent,
   ExpandableCardContent,
-  IconContainer,
+  ExpandableCardHelperText,
+  ExpandableCardText,
   BodyText,
 } from '@utilitywarehouse/hearth-react-native';
-import { BillMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
 import { useState } from 'react';
+import { View } from 'react-native';
 
 const MyComponent = () => {
-  const [expanded, setExpanded] = useState(false);
+  const [triggerContentExpanded, setTriggerContentExpanded] = useState(false);
+  const [customChildrenExpanded, setCustomChildrenExpanded] = useState(false);
 
   return (
-    <ExpandableCard expanded={expanded} onExpandedChange={setExpanded}>
-      <ExpandableCardTrigger
-        onPress={() => setExpanded(!expanded)}
-        heading="Custom Account Details"
-        helperText="View your detailed account information"
-        leadingContent={
-          <IconContainer icon={BillMediumIcon} size="md" variant="emphasis" color="pig" />
+    <>
+      <ExpandableCard
+        expanded={triggerContentExpanded}
+        onExpandedChange={setTriggerContentExpanded}
+        expandedContent={<BodyText>Use `triggerContent` for a full replacement.</BodyText>}
+        triggerContent={
+          <View style={{ flex: 1, gap: 4 }}>
+            <BodyText weight="semibold">Use `triggerContent`</BodyText>
+            <BodyText color="secondary">Replace the built-in trigger layout</BodyText>
+          </View>
         }
-        numericValue="£123.45"
-        isExpanded={expanded}
       />
-      <ExpandableCardExpandedContent isExpanded={expanded}>
-        <BodyText>Account Number: 1234567890</BodyText>
-        <BodyText>Sort Code: 12-34-56</BodyText>
-        <BodyText>Balance: £123.45</BodyText>
-        <BodyText>Last Updated: 12/11/25</BodyText>
-      </ExpandableCardExpandedContent>
-    </ExpandableCard>
+
+      <ExpandableCard
+        expanded={customChildrenExpanded}
+        onExpandedChange={setCustomChildrenExpanded}
+      >
+        <ExpandableCardTrigger
+          onPress={() => setCustomChildrenExpanded(!customChildrenExpanded)}
+          isExpanded={customChildrenExpanded}
+          showChevron
+        >
+          <ExpandableCardContent>
+            <ExpandableCardText>Use `children` + `showChevron`</ExpandableCardText>
+            <ExpandableCardHelperText>
+              Build the trigger yourself and keep the chevron
+            </ExpandableCardHelperText>
+          </ExpandableCardContent>
+        </ExpandableCardTrigger>
+        <ExpandableCardExpandedContent isExpanded={customChildrenExpanded}>
+          <BodyText>Use `children` when you want full trigger composition control.</BodyText>
+        </ExpandableCardExpandedContent>
+      </ExpandableCard>
+    </>
   );
 };
 ```
@@ -285,6 +335,8 @@ When using advanced composition, you have access to these components:
 - **`ExpandableCardTrailingContent`**: Container for trailing content
 - **`ExpandableCardTrailingIcon`**: Styled icon for trailing position
 
+Use `triggerContent` when you want a simpler one-prop replacement on `ExpandableCard`. Use `ExpandableCardTrigger` children when you want to compose the trigger structure yourself. The built-in chevron is shown by default, and you can set `showChevron={false}` if you want to hide it.
+
 ## Accessibility
 
 The ExpandableCard component includes built-in accessibility support:

package/src/components/ExpandableCard/ExpandableCard.props.ts

@@ -1,7 +1,7 @@
 import type { ComponentType, ReactNode } from 'react';
 import type CardProps from '../Card/Card.props';
 
-export interface ExpandableCardProps extends Omit<CardProps, 'children'> {
+interface ExpandableCardSharedProps extends Omit<CardProps, 'children'> {
   /**
    * Whether the card is expanded
    */
@@ -12,6 +12,40 @@ export interface ExpandableCardProps extends Omit<CardProps, 'children'> {
    */
   onExpandedChange?: (expanded: boolean) => void;
 
+  /**
+   * The heading text displayed in the trigger
+   */
+  expandedContent?: ReactNode;
+
+  /**
+   * Duration of the expansion animation in milliseconds
+   * @default 200
+   */
+  duration?: number;
+
+  /**
+   * Whether to animate opacity during expansion
+   * @default true
+   */
+  animateOpacity?: boolean;
+
+  /**
+   * Whether the card is disabled
+   */
+  disabled?: boolean;
+
+  /**
+   * Test ID for testing
+   */
+  testID?: string;
+
+  /**
+   * Custom children for advanced composition
+   */
+  children?: ReactNode;
+}
+
+interface ExpandableCardDefaultTriggerProps {
   /**
    * The heading text displayed in the trigger
    */
@@ -49,36 +83,26 @@ export interface ExpandableCardProps extends Omit<CardProps, 'children'> {
   numericValue?: string | number;
 
   /**
-   * The content to show when expanded
-   */
-  expandedContent?: ReactNode;
-
-  /**
-   * Duration of the expansion animation in milliseconds
-   * @default 200
-   */
-  duration?: number;
-
-  /**
-   * Whether to animate opacity during expansion
-   * @default true
-   */
-  animateOpacity?: boolean;
-
-  /**
-   * Whether the card is disabled
+   * Custom trigger content that replaces the default trigger layout.
    */
-  disabled?: boolean;
-
-  /**
-   * Test ID for testing
-   */
-  testID?: string;
+  triggerContent?: never;
+}
 
+interface ExpandableCardCustomTriggerProps {
   /**
-   * Custom children for advanced composition
+   * Custom trigger content that replaces the default trigger layout.
    */
-  children?: ReactNode;
+  triggerContent: ReactNode;
+  heading?: never;
+  helperText?: never;
+  leadingIcon?: never;
+  leadingContent?: never;
+  badge?: never;
+  badgePosition?: never;
+  numericValue?: never;
 }
 
+type ExpandableCardProps = ExpandableCardSharedProps &
+  (ExpandableCardDefaultTriggerProps | ExpandableCardCustomTriggerProps);
+
 export default ExpandableCardProps;

package/src/components/ExpandableCard/ExpandableCard.stories.tsx

@@ -7,11 +7,15 @@ import {
   SettingsMediumIcon,
 } from '@utilitywarehouse/hearth-react-native-icons';
 import React from 'react';
+import { View } from 'react-native';
 import { Badge, BodyText, IconContainer, Link } from '../../components';
 import ExpandableCard from './ExpandableCard';
+import ExpandableCardContent from './ExpandableCardContent';
 import ExpandableCardExpandedContent from './ExpandableCardExpandedContent';
 import ExpandableCardGroup from './ExpandableCardGroup';
+import ExpandableCardHelperText from './ExpandableCardHelperText';
 import ExpandableCardIcon from './ExpandableCardIcon';
+import ExpandableCardText from './ExpandableCardText';
 import ExpandableCardTrigger from './ExpandableCardTrigger';
 
 const meta = {
@@ -161,6 +165,26 @@ export const WithNumericValue: Story = {
   ),
 };
 
+export const WithCustomTriggerContent: Story = {
+  render: () => (
+    <ExpandableCard
+      triggerContent={
+        <View style={{ flex: 1, gap: 4 }}>
+          <BodyText weight="semibold">March bill ready</BodyText>
+          <BodyText color="secondary">Due on 18 April 2026</BodyText>
+        </View>
+      }
+      expandedContent={
+        <>
+          <BodyText>Balance: £89.50</BodyText>
+          <BodyText>Payment method: Direct Debit</BodyText>
+        </>
+      }
+      style={{ width: 350 }}
+    />
+  ),
+};
+
 export const Disabled: Story = {
   render: () => (
     <ExpandableCard
@@ -300,27 +324,53 @@ export const ColorSchemes: Story = {
 
 export const AdvancedComposition: Story = {
   render: () => {
-    const [expanded, setExpanded] = React.useState(false);
+    const [triggerContentExpanded, setTriggerContentExpanded] = React.useState(false);
+    const [customChildrenExpanded, setCustomChildrenExpanded] = React.useState(false);
 
     return (
-      <ExpandableCard expanded={expanded} onExpandedChange={setExpanded}>
-        <ExpandableCardTrigger
-          onPress={() => setExpanded(!expanded)}
-          heading="Custom Account Details"
-          helperText="View your detailed account information"
-          leadingContent={
-            <IconContainer icon={BillMediumIcon} size="md" variant="emphasis" color="pig" />
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 350 }}>
+        <ExpandableCard
+          expanded={triggerContentExpanded}
+          onExpandedChange={setTriggerContentExpanded}
+          expandedContent={
+            <>
+              <BodyText>Account Number: 1234567890</BodyText>
+              <BodyText>Sort Code: 12-34-56</BodyText>
+              <BodyText>Balance: £123.45</BodyText>
+            </>
+          }
+          triggerContent={
+            <View style={{ flex: 1, gap: 4 }}>
+              <BodyText weight="semibold">Use `triggerContent`</BodyText>
+              <BodyText color="secondary">Replace the built-in trigger layout</BodyText>
+            </View>
           }
-          numericValue="£123.45"
-          isExpanded={expanded}
         />
-        <ExpandableCardExpandedContent isExpanded={expanded}>
-          <BodyText>Account Number: 1234567890</BodyText>
-          <BodyText>Sort Code: 12-34-56</BodyText>
-          <BodyText>Balance: £123.45</BodyText>
-          <BodyText>Last Updated: 12/11/25</BodyText>
-        </ExpandableCardExpandedContent>
-      </ExpandableCard>
+
+        <ExpandableCard
+          expanded={customChildrenExpanded}
+          onExpandedChange={setCustomChildrenExpanded}
+        >
+          <ExpandableCardTrigger
+            onPress={() => setCustomChildrenExpanded(!customChildrenExpanded)}
+            isExpanded={customChildrenExpanded}
+            showChevron
+          >
+            <ExpandableCardContent>
+              <ExpandableCardText>Use `children` + `showChevron`</ExpandableCardText>
+              <ExpandableCardHelperText>
+                Build the trigger yourself and keep the chevron
+              </ExpandableCardHelperText>
+            </ExpandableCardContent>
+          </ExpandableCardTrigger>
+          <ExpandableCardExpandedContent isExpanded={customChildrenExpanded}>
+            <BodyText>Account Number: 1234567890</BodyText>
+            <BodyText>Sort Code: 12-34-56</BodyText>
+            <BodyText>Balance: £123.45</BodyText>
+            <BodyText>Last Updated: 12/11/25</BodyText>
+          </ExpandableCardExpandedContent>
+        </ExpandableCard>
+      </div>
     );
   },
 };

package/src/components/ExpandableCard/ExpandableCard.tsx

@@ -14,6 +14,7 @@ const ExpandableCard = ({
   badge,
   badgePosition = 'bottom',
   numericValue,
+  triggerContent,
   expandedContent,
   duration = 200,
   animateOpacity = true,
@@ -39,18 +40,25 @@ const ExpandableCard = ({
     onExpandedChange?.(newExpanded);
   };
 
+  const triggerProps =
+    triggerContent !== undefined
+      ? { triggerContent }
+      : {
+          heading,
+          helperText,
+          leadingIcon,
+          leadingContent,
+          badge,
+          badgePosition,
+          numericValue,
+        };
+
   const renderDefaultContent = () => (
     <>
       <ExpandableCardTrigger
         onPress={handlePress}
         disabled={disabled}
-        heading={heading}
-        helperText={helperText}
-        leadingIcon={leadingIcon}
-        leadingContent={leadingContent}
-        badge={badge}
-        badgePosition={badgePosition}
-        numericValue={numericValue}
+        {...triggerProps}
         isExpanded={isExpanded}
         testID={`${testID}-trigger`}
       />

package/src/components/ExpandableCard/ExpandableCardText.tsx

@@ -3,7 +3,7 @@ import { BodyText } from '../BodyText';
 
 const ExpandableCardText = ({ children, ...props }: TextProps) => {
   return (
-    <BodyText size="lg" {...props}>
+    <BodyText size="md" weight="semibold" {...props}>
       {children}
     </BodyText>
   );

package/src/components/ExpandableCard/ExpandableCardTrigger.props.ts

@@ -1,7 +1,25 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { PressableProps } from 'react-native';
 
-export interface ExpandableCardTriggerProps extends Omit<PressableProps, 'children'> {
+interface ExpandableCardTriggerSharedProps extends Omit<PressableProps, 'children'> {
+  /**
+   * Whether the expandable card is expanded
+   */
+  isExpanded: boolean;
+  /**
+   * Whether to show the chevron when providing custom children.
+   * @default true
+   */
+  showChevron?: boolean;
+  /**
+   * Whether the trigger is disabled
+   */
+  disabled?: boolean;
+  /* Optional children */
+  children?: ReactNode;
+}
+
+interface ExpandableCardTriggerDefaultContentProps {
   /**
    * The main heading text
    */
@@ -31,16 +49,28 @@ export interface ExpandableCardTriggerProps extends Omit<PressableProps, 'childr
    * Optional numeric value to display
    */
   numericValue?: string | number;
+
   /**
-   * Whether the expandable card is expanded
+   * Custom trigger content that replaces the default trigger layout.
    */
-  isExpanded: boolean;
+  triggerContent?: never;
+}
+
+interface ExpandableCardTriggerCustomContentProps {
   /**
-   * Whether the trigger is disabled
+   * Custom trigger content that replaces the default trigger layout.
    */
-  disabled?: boolean;
-  /* Optional children */
-  children?: ReactNode;
+  triggerContent: ReactNode;
+  heading?: never;
+  helperText?: never;
+  leadingIcon?: never;
+  leadingContent?: never;
+  badge?: never;
+  badgePosition?: never;
+  numericValue?: never;
 }
 
+type ExpandableCardTriggerProps = ExpandableCardTriggerSharedProps &
+  (ExpandableCardTriggerDefaultContentProps | ExpandableCardTriggerCustomContentProps);
+
 export default ExpandableCardTriggerProps;

package/src/components/ExpandableCard/ExpandableCardTriggerRoot.tsx

@@ -22,7 +22,9 @@ const ExpandableCardTriggerRoot = ({
   badge,
   badgePosition = 'bottom',
   numericValue,
+  triggerContent,
   isExpanded,
+  showChevron = true,
   disabled,
   states,
   children,
@@ -53,6 +55,8 @@ const ExpandableCardTriggerRoot = ({
     return null;
   };
 
+  const defaultAccessibilityLabel = [heading, helperText].filter(Boolean).join(', ');
+
   const renderDefaultContent = () => (
     <>
       {renderLeadingContent()}
@@ -73,6 +77,36 @@ const ExpandableCardTriggerRoot = ({
     </>
   );
 
+  const renderChevron = () => (
+    <ExpandableCardTrailingContent style={styles.chevron}>
+      <ExpandableCardTrailingIcon as={isExpanded ? ChevronUpSmallIcon : ChevronDownSmallIcon} />
+    </ExpandableCardTrailingContent>
+  );
+
+  const renderCustomTriggerContent = () => (
+    <>
+      {triggerContent}
+      {showChevron ? renderChevron() : null}
+    </>
+  );
+
+  const renderChildrenContent = () => (
+    <>
+      {children}
+      {showChevron ? renderChevron() : null}
+    </>
+  );
+
+  let triggerBody = renderDefaultContent();
+
+  if (triggerContent !== undefined) {
+    triggerBody = renderCustomTriggerContent();
+  }
+
+  if (children) {
+    triggerBody = renderChildrenContent();
+  }
+
   return (
     <Pressable
       {...props}
@@ -81,9 +115,9 @@ const ExpandableCardTriggerRoot = ({
       disabled={disabled}
       accessibilityRole="button"
       accessibilityState={{ expanded: isExpanded, disabled }}
-      accessibilityLabel={`${heading}${helperText ? `, ${helperText}` : ''}`}
+      accessibilityLabel={props.accessibilityLabel || defaultAccessibilityLabel || undefined}
     >
-      {children || renderDefaultContent()}
+      {triggerBody}
     </Pressable>
   );
 };

package/src/components/Flex/Flex.props.ts

@@ -1,7 +1,21 @@
 import type { FlexAlignType, ViewProps, ViewStyle } from 'react-native';
-import { FlexLayoutProps, GapProps, SpacingValues } from '../../types';
+import {
+  DisplayProps,
+  FlexLayoutProps,
+  GapProps,
+  MarginProps,
+  PaddingProps,
+  SpacingValues,
+} from '../../types';
 
-interface FlexProps extends ViewProps, FlexLayoutProps, GapProps {
+interface FlexProps
+  extends
+    ViewProps,
+    MarginProps,
+    PaddingProps,
+    FlexLayoutProps,
+    GapProps,
+    Omit<DisplayProps, 'direction'> {
   direction?: ViewStyle['flexDirection'];
   align?: FlexAlignType;
   justify?: ViewStyle['justifyContent'];

package/src/components/FormField/FormField.tsx

@@ -1,6 +1,7 @@
 import { createFormControl } from '@gluestack-ui/form-control';
 import { useMemo, useState } from 'react';
 import { View } from 'react-native';
+import { BodyText } from '../BodyText';
 import { HelperIcon, HelperText } from '../Helper';
 import { FormFieldContext } from './FormField.context';
 import FormFieldProps from './FormField.props';
@@ -94,7 +95,7 @@ const FormField = ({
                 accessibilityElementsHidden={shouldHandleAccessibility}
               >
                 {label}
-                {!required ? ` (Optional)` : ''}
+                {!required ? <BodyText weight="regular"> (Optional)</BodyText> : ''}
               </FormFieldLabelText>
             )}
             {!!helperText && (

package/src/components/List/List.stories.tsx

@@ -10,6 +10,7 @@ import {
   UserMediumIcon,
 } from '@utilitywarehouse/hearth-react-native-icons';
 import { useState } from 'react';
+import { FlatList } from 'react-native';
 import { List, ListAction, ListItem, ListItemIcon, ListItemTrailingIcon } from '.';
 import { VariantTitle } from '../../../docs/components';
 import { Badge } from '../Badge';
@@ -398,6 +399,40 @@ export const Loading: Story = {
   ),
 };
 
+export const WithFlatList: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => {
+    const listData = Array.from({ length: 200 }).map((_, index) => ({
+      id: index.toString(),
+      heading: `List Item ${index + 1}`,
+      helperText: `Supporting Text ${index + 1}`,
+    }));
+
+    return (
+      <List
+        container="subtleWhite"
+        heading="FlatList Example"
+        helperText="This list is rendered using FlatList for performance"
+      >
+        <FlatList
+          data={listData}
+          keyExtractor={item => item.id}
+          renderItem={({ item }) => (
+            <ListItem
+              heading={item.heading}
+              helperText={item.helperText}
+              leadingContent={<ListItemIcon as={SettingsMediumIcon} />}
+              onPress={() => console.log(`${item.heading} pressed`)}
+            />
+          )}
+        />
+      </List>
+    );
+  },
+};
+
 export const KitchenSink: Story = {
   parameters: {
     controls: { include: [] },