@utilitywarehouse/hearth-react-native 0.6.0 → 0.8.0

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

@@ -0,0 +1,312 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './ExpandableCard.stories';
+
+<Meta title="Components / Expandable Card" />
+
+<BackToTopButton />
+
+<ViewFigmaButton link="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7222-5934" />
+
+# Expandable Card
+
+The `ExpandableCard` component is an interactive card that expands to reveal additional content when clicked. It's a Card component with smooth expansion animations, making it perfect for displaying collapsible information sections.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+  - [`ExpandableCard`](#expandablecard)
+  - [`ExpandableCardGroup`](#expandablecardgroup)
+- [Examples](#examples)
+  - [Basic Example](#basic-example)
+  - [With Leading Icon](#with-leading-icon)
+  - [With `Badge`](#with-badge)
+  - [With Numeric Value](#with-numeric-value)
+  - [`CardGroup`](#cardgroup)
+- [Advanced Usage](#advanced-usage)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<Canvas of={Stories.BasicExample} />
+
+```tsx
+import { ExpandableCard, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <ExpandableCard
+    heading="Order Details"
+    helperText="View your order information"
+    expandedContent={
+      <>
+        <BodyText>Order #12345</BodyText>
+        <BodyText>Status: Delivered</BodyText>
+        <BodyText>Date: 10 Nov 2025</BodyText>
+      </>
+    }
+  />
+);
+```
+
+## Props
+
+### `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`            | `BadgeProps`                  | -                   | 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                              |
+
+### `ExpandableCardGroup`
+
+| Prop                    | Type        | Default                   | Description                                    |
+| ----------------------- | ----------- | ------------------------- | ---------------------------------------------- |
+| `heading`               | `string`    | -                         | Section heading                                |
+| `helperText`            | `string`    | -                         | Helper text displayed below the heading        |
+| `headerTrailingContent` | `ReactNode` | -                         | Trailing content for the header (e.g., a link) |
+| `children`              | `ReactNode` | -                         | The ExpandableCard children                    |
+| `testID`                | `string`    | `'expandable-card-group'` | Test ID for testing                            |
+
+## Examples
+
+### Basic Example
+
+<Canvas of={Stories.BasicExample} />
+
+### With Leading Icon
+
+You can add a leading icon using the `leadingIcon` prop for simple icons, or use `leadingContent` with an `IconContainer` for more customization.
+
+<Canvas of={Stories.WithLeadingIcon} />
+
+```tsx
+import { ExpandableCard, BodyText } from '@utilitywarehouse/hearth-react-native';
+import { SettingsMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => (
+  <ExpandableCard
+    heading="Settings"
+    helperText="Configure your preferences"
+    leadingIcon={SettingsMediumIcon}
+    expandedContent={
+      <>
+        <BodyText>• Notifications</BodyText>
+        <BodyText>• Privacy</BodyText>
+        <BodyText>• Account</BodyText>
+      </>
+    }
+  />
+);
+```
+
+Or use `leadingContent` with `IconContainer` for emphasis variants:
+
+<Canvas of={Stories.WithIconContainer} />
+
+```tsx
+import { ExpandableCard, IconContainer, BodyText } from '@utilitywarehouse/hearth-react-native';
+import { ElectricityMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => (
+  <ExpandableCard
+    heading="Electricity"
+    helperText="Last reading 23/03/24"
+    leadingContent={
+      <IconContainer icon={ElectricityMediumIcon} size="md" variant="emphasis" color="energy" />
+    }
+    expandedContent={
+      <>
+        <BodyText>Current Usage: 245 kWh</BodyText>
+        <BodyText>Estimated Cost: £45.50</BodyText>
+      </>
+    }
+  />
+);
+```
+
+### With `Badge`
+
+<Canvas of={Stories.WithBadge} />
+
+```tsx
+<ExpandableCard
+  heading="New Feature"
+  helperText="Check out what's new"
+  badge={{ text: 'New', colorScheme: 'cyan' }}
+  expandedContent={<BodyText>We've added new features to improve your experience.</BodyText>}
+/>
+```
+
+### With Numeric Value
+
+<Canvas of={Stories.WithNumericValue} />
+
+```tsx
+<ExpandableCard
+  heading="Total Balance"
+  helperText="Current account balance"
+  numericValue="£123.45"
+  expandedContent={
+    <>
+      <BodyText>Available: £100.00</BodyText>
+      <BodyText>Pending: £23.45</BodyText>
+    </>
+  }
+/>
+```
+
+### `CardGroup`
+
+Use `ExpandableCardGroup` to group multiple expandable cards with an optional header.
+
+<Canvas of={Stories.CardGroup} />
+
+```tsx
+import {
+  ExpandableCard,
+  ExpandableCardGroup,
+  IconContainer,
+  Link,
+  BodyText,
+} from '@utilitywarehouse/hearth-react-native';
+import { ElectricityMediumIcon, GasMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => (
+  <ExpandableCardGroup
+    heading="Your Services"
+    helperText="View details for each service"
+    headerTrailingContent={<Link href="#">View all</Link>}
+  >
+    <ExpandableCard
+      heading="Electricity"
+      helperText="Last reading 23/03/24"
+      leadingContent={
+        <IconContainer icon={ElectricityMediumIcon} size="md" variant="emphasis" color="energy" />
+      }
+      expandedContent={
+        <>
+          <BodyText>Current Usage: 245 kWh</BodyText>
+          <BodyText>Estimated Cost: £45.50</BodyText>
+        </>
+      }
+    />
+    <ExpandableCard
+      heading="Gas"
+      helperText="Last reading 23/03/24"
+      leadingContent={
+        <IconContainer icon={GasMediumIcon} size="md" variant="emphasis" color="energy" />
+      }
+      expandedContent={
+        <>
+          <BodyText>Current Usage: 180 kWh</BodyText>
+          <BodyText>Estimated Cost: £32.00</BodyText>
+        </>
+      }
+    />
+  </ExpandableCardGroup>
+);
+```
+
+## Advanced Usage
+
+If you need to use the `ExpandableCard` component in a more advanced way, you can use the child components directly for full composition control.
+
+<Canvas of={Stories.AdvancedComposition} />
+
+```tsx
+import {
+  ExpandableCard,
+  ExpandableCardTrigger,
+  ExpandableCardExpandedContent,
+  ExpandableCardContent,
+  IconContainer,
+  BodyText,
+} from '@utilitywarehouse/hearth-react-native';
+import { BillMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const [expanded, setExpanded] = 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" />
+        }
+        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>
+  );
+};
+```
+
+### Child Components
+
+When using advanced composition, you have access to these components:
+
+- **`ExpandableCardTrigger`**: The clickable header section with heading, helper text, leading/trailing content
+- **`ExpandableCardExpandedContent`**: Wrapper for the expanded content area with animation controls
+- **`ExpandableCardContent`**: Content container with proper spacing and gap
+- **`ExpandableCardIcon`**: Styled icon component for leading icons
+- **`ExpandableCardText`**: Styled text for main heading
+- **`ExpandableCardHelperText`**: Styled text for helper/secondary text
+- **`ExpandableCardLeadingContent`**: Container for leading content (icons, images, etc.)
+- **`ExpandableCardTrailingContent`**: Container for trailing content
+- **`ExpandableCardTrailingIcon`**: Styled icon for trailing position
+
+## Accessibility
+
+The ExpandableCard component includes built-in accessibility support:
+
+- Uses `accessibilityRole="button"` to indicate it's interactive
+- Sets `accessibilityState` to communicate expanded/collapsed and disabled states
+- Provides meaningful `accessibilityLabel` combining heading and helper text
+- Chevron icon changes direction to indicate current state
+- Keyboard accessible when used on web
+
+## Best Practices
+
+1. **Use descriptive headings**: Make sure your heading clearly describes what content will be revealed.
+
+2. **Keep expanded content concise**: While you can put any content inside, try to keep it focused and scannable.
+
+3. **Group related cards**: Use `ExpandableCardGroup` to organize multiple related expandable cards with a common header.
+
+4. **Consider initial state**: Most cards should start collapsed, but you can default to expanded for critical information.
+
+5. **Provide visual context**: Use leading icons or icon containers to help users quickly identify the card's purpose.
+
+6. **Use numeric values appropriately**: Display counts, amounts, or other quantitative data that adds quick context.
+
+7. **Controlled vs Uncontrolled**: Use controlled state (via `expanded` and `onExpandedChange`) when you need to manage expansion state externally, otherwise let the component handle it internally.

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

@@ -0,0 +1,85 @@
+import type { ComponentType, ReactNode } from 'react';
+import type BadgeProps from '../Badge/Badge.props';
+import type CardProps from '../Card/Card.props';
+
+export interface ExpandableCardProps extends Omit<CardProps, 'children'> {
+  /**
+   * Whether the card is expanded
+   */
+  expanded?: boolean;
+
+  /**
+   * Callback when expanded state changes
+   */
+  onExpandedChange?: (expanded: boolean) => void;
+
+  /**
+   * The heading text displayed in the trigger
+   */
+  heading?: string;
+
+  /**
+   * Optional helper text displayed below the heading
+   */
+  helperText?: string;
+
+  /**
+   * Leading icon component
+   */
+  leadingIcon?: ComponentType;
+
+  /**
+   * Leading content (icon or custom element)
+   */
+  leadingContent?: ReactNode;
+
+  /**
+   * Badge to display
+   */
+  badge?: BadgeProps;
+
+  /**
+   * Badge position
+   * @default 'bottom'
+   */
+  badgePosition?: 'top' | 'bottom';
+
+  /**
+   * Numeric value to display on the right
+   */
+  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
+   */
+  disabled?: boolean;
+
+  /**
+   * Test ID for testing
+   */
+  testID?: string;
+
+  /**
+   * Custom children for advanced composition
+   */
+  children?: ReactNode;
+}
+
+export default ExpandableCardProps;