@utilitywarehouse/hearth-react-native 0.30.4 → 0.31.1

package/docs/changelog.mdx

@@ -9,6 +9,176 @@ 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.31.0
+
+### Minor Changes
+
+- [#1108](https://github.com/utilitywarehouse/hearth/pull/1108) [`8c2f3b5`](https://github.com/utilitywarehouse/hearth/commit/8c2f3b5334de83a7dd799b857394a34209b748e7) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add margin, padding, and layout utility props to `Flex`.
+
+  `Flex` now exposes the shared margin and padding utility props, along with the existing layout utility prop surface, so it can be used more like other layout primitives such as `Card`.
+
+  **Component affected**:
+  - `Flex`
+
+  **Developer changes**:
+
+  You can now apply spacing and layout utility props directly on `Flex`:
+
+  ```tsx
+  <Flex direction="row" spacing="md" padding="300" marginTop="200" flex={1}>
+    <Button>Back</Button>
+    <Button>Continue</Button>
+  </Flex>
+  ```
+
+- [#1104](https://github.com/utilitywarehouse/hearth/pull/1104) [`91feeab`](https://github.com/utilitywarehouse/hearth/commit/91feeab091ae6bf80e543f9196214066ce8b29b0) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add custom trigger content options to `ExpandableCard`.
+
+  `ExpandableCard` now supports a `triggerContent` prop for replacing the default trigger layout while keeping the chevron. `ExpandableCardTrigger` also now supports `children` with an optional `showChevron` prop, so you can fully compose the trigger content yourself and still opt in to the built-in expand/collapse chevron.
+
+  **Components affected**:
+  - `ExpandableCard`
+  - `ExpandableCardTrigger`
+
+  **Developer changes**:
+
+  Use `triggerContent` when you want a single prop on `ExpandableCard` to replace the standard trigger content:
+
+  ```tsx
+  <ExpandableCard
+    triggerContent={<BodyText weight="semibold">March bill ready</BodyText>}
+    expandedContent={<BodyText>Balance: £89.50</BodyText>}
+  />
+  ```
+
+  Use `ExpandableCardTrigger` children when you want full control over the trigger structure. Add `showChevron` if you still want the built-in chevron:
+
+  ```tsx
+  <ExpandableCardTrigger isExpanded={expanded} onPress={toggleExpanded} showChevron>
+    <ExpandableCardContent>
+      <ExpandableCardText>Custom trigger</ExpandableCardText>
+    </ExpandableCardContent>
+  </ExpandableCardTrigger>
+  ```
+
+- [#1109](https://github.com/utilitywarehouse/hearth/pull/1109) [`8215550`](https://github.com/utilitywarehouse/hearth/commit/8215550745d08a8b4c18a6902e39d3199018092a) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add `numberOfLines` support to `Badge` text.
+
+  `Badge` now renders its text content on a single line by default and supports a new `numberOfLines` prop when you want to allow more lines.
+
+  **Components affected**:
+  - `Badge`
+
+  **Developer changes**:
+
+  No changes are required unless you want a `Badge` to wrap onto more than one line. To opt in, pass `numberOfLines`:
+
+  ```tsx
+  <Badge numberOfLines={2} text="Long badge text that can wrap onto a second line" />
+  ```
+
+- [#1108](https://github.com/utilitywarehouse/hearth/pull/1108) [`8c2f3b5`](https://github.com/utilitywarehouse/hearth/commit/8c2f3b5334de83a7dd799b857394a34209b748e7) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add custom footer support to `Modal` and `NavModal`.
+
+  `Modal` and `NavModal` now support a `footer` prop for replacing the built-in primary and secondary action buttons with custom content, plus a `footerStyle` prop for styling the footer container. When `footer` is provided, the button props are now disallowed at the type level.
+
+  **Components affected**:
+  - `Modal`
+  - `NavModal`
+
+  **Developer changes**:
+
+  Use `footer` when you need a custom footer layout, such as horizontal actions or extra decoration:
+
+  ```tsx
+  <Modal
+    heading="Update billing details"
+    footer={
+      <Flex direction="row" spacing="md" pt="250">
+        <Button variant="outline" colorScheme="functional" style={{ flex: 1 }}>
+          Cancel
+        </Button>
+        <Button style={{ flex: 1 }}>Save changes</Button>
+      </Flex>
+    }
+    footerStyle={{
+      boxShadow: '0px -6px 12px rgba(16, 24, 40, 0.12)',
+    }}
+  />
+  ```
+
+- [#1103](https://github.com/utilitywarehouse/hearth/pull/1103) [`e375a44`](https://github.com/utilitywarehouse/hearth/commit/e375a442c507da1807e49f4d78e44edfff51d245) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add optional vertical resizing to `Textarea`.
+
+  `Textarea` now supports a new `resizable` prop that adds a bottom-right drag handle so people can increase the field height when they need more space for longer content.
+
+  **Components affected**:
+  - `Textarea`
+
+  **Developer changes**:
+
+  No changes are required unless you want to enable resizing for a textarea. To opt in, pass the new `resizable` prop:
+
+  ```tsx
+  <Textarea
+    label="Additional notes"
+    helperText="Drag the corner handle to resize"
+    placeholder="Enter your text here..."
+    resizable
+  />
+  ```
+
+- [#1108](https://github.com/utilitywarehouse/hearth/pull/1108) [`8c2f3b5`](https://github.com/utilitywarehouse/hearth/commit/8c2f3b5334de83a7dd799b857394a34209b748e7) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE]: Add flex utility props to `Container`.
+
+  `Container` now exposes shared flex layout utility props, allowing layout properties such as `flex`, `alignItems`, `justifyContent`, and `flexDirection` to be applied directly through its public prop API.
+
+  **Component affected**:
+  - `Container`
+
+  **Developer changes**:
+
+  You can now combine `Container`'s existing spacing props with flex layout props:
+
+  ```tsx
+  <Container flex={1} justifyContent="center" alignItems="stretch" gap="200">
+    <BodyText>Content</BodyText>
+  </Container>
+  ```
+
+### Patch Changes
+
+- [#1103](https://github.com/utilitywarehouse/hearth/pull/1103) [`e375a44`](https://github.com/utilitywarehouse/hearth/commit/e375a442c507da1807e49f4d78e44edfff51d245) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Render FormField optional text with regular weight instead of inheriting the label weight.
+
+  This fixes FormField labels that append `(Optional)` so the optional text no longer inherits the main label weight.
+
+  **Components affected**:
+  - `FormField`
+  - `Textarea`
+  - `Input`
+
+  **Developer changes**:
+
+  No changes are required.
+
+- [#1104](https://github.com/utilitywarehouse/hearth/pull/1104) [`91feeab`](https://github.com/utilitywarehouse/hearth/commit/91feeab091ae6bf80e543f9196214066ce8b29b0) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: `ExpandableCard` heading font size and weight
+
+## 0.30.4
+
+### Patch Changes
+
+- [#1096](https://github.com/utilitywarehouse/hearth/pull/1096) [`6fd9021`](https://github.com/utilitywarehouse/hearth/commit/6fd9021a91ef38b56b78755965515a0807b34fa1) Thanks [@fillyD](https://github.com/fillyD)! - 🐛 [FIX]: Restore visibility of bottom sheet content in iOS accessibility tree, enabling automated tests to interact with `Select` options
+
+## 0.30.3
+
+### Patch Changes
+
+- [#1094](https://github.com/utilitywarehouse/hearth/pull/1094) [`a9d8e66`](https://github.com/utilitywarehouse/hearth/commit/a9d8e660b7efa23c7a573af2658fc10ab6c043b9) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Make horizontal pressable `Banner` content flex correctly on native and web.
+
+  This fixes horizontal pressable `Banner` layouts where the content area did not expand consistently, which could misplace the chevron and action content.
+
+  **Components affected**:
+  - `Banner`
+
+  **Developer changes**:
+
+  No changes are required.
+
 ## 0.30.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.30.4",
+  "version": "0.31.1",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -58,10 +58,10 @@
     "vite-plugin-svgr": "^4.5.0",
     "vitest": "^3.2.4",
     "@utilitywarehouse/hearth-fonts": "^0.0.4",
-    "@utilitywarehouse/hearth-react-icons": "^0.8.0",
     "@utilitywarehouse/hearth-react-native-icons": "^0.8.0",
     "@utilitywarehouse/hearth-svg-assets": "^0.6.0",
-    "@utilitywarehouse/hearth-tokens": "^0.2.4"
+    "@utilitywarehouse/hearth-tokens": "^0.2.4",
+    "@utilitywarehouse/hearth-react-icons": "^0.8.0"
   },
   "peerDependencies": {
     "@gorhom/bottom-sheet": ">=5.0.0",

package/src/components/Badge/Badge.props.ts

@@ -20,6 +20,7 @@ interface BadgeProps extends ViewProps {
   icon?: ComponentType;
   flatBase?: boolean;
   text?: string | number;
+  numberOfLines?: number;
 }
 
 export default BadgeProps;

package/src/components/Badge/Badge.tsx

@@ -15,6 +15,7 @@ const Badge = ({ children, ...props }: BadgeProps) => {
     size = 'sm',
     style,
     text,
+    numberOfLines,
     ...rest
   } = props;
 
@@ -31,7 +32,11 @@ const Badge = ({ children, ...props }: BadgeProps) => {
     <BadgeContext.Provider value={value}>
       <View {...rest} style={[styles.container, style]}>
         {!!icon && <BadgeIcon as={icon} />}
-        {childIsText ? <BadgeText>{text ?? children}</BadgeText> : children}
+        {childIsText ? (
+          <BadgeText numberOfLines={numberOfLines}>{text ?? children}</BadgeText>
+        ) : (
+          children
+        )}
       </View>
     </BadgeContext.Provider>
   );

package/src/components/Badge/BadgeText.tsx

@@ -3,11 +3,17 @@ import { StyleSheet } from 'react-native-unistyles';
 import { BodyText } from '../BodyText';
 import { useBadgeContext } from './Badge.context';
 
-const BadgeText = ({ children, style, ...props }: TextProps) => {
+const BadgeText = ({ children, style, numberOfLines = 1, ...props }: TextProps) => {
   const { variant, colorScheme, size } = useBadgeContext();
   styles.useVariants({ variant, colorScheme });
   return (
-    <BodyText {...props} size={size} weight="semibold" style={[styles.text, style]}>
+    <BodyText
+      {...props}
+      numberOfLines={numberOfLines}
+      size={size}
+      weight="semibold"
+      style={[styles.text, style]}
+    >
       {children}
     </BodyText>
   );

package/src/components/Container/Container.props.ts

@@ -1,6 +1,8 @@
 import type { ViewProps } from 'react-native';
 import type {
   BackgroundColorProps,
+  DisplayProps,
+  FlexLayoutProps,
   GapProps,
   MarginProps,
   PaddingProps,
@@ -8,7 +10,14 @@ import type {
 } from '../../types';
 
 interface ContainerProps
-  extends ViewProps, MarginProps, PaddingProps, GapProps, BackgroundColorProps {
+  extends
+    ViewProps,
+    MarginProps,
+    PaddingProps,
+    GapProps,
+    BackgroundColorProps,
+    FlexLayoutProps,
+    DisplayProps {
   /**
    * The spacing between child elements (gap).
    */

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>
     );
   },
 };