@utilitywarehouse/hearth-react-native 0.7.0 → 0.8.0

package/src/components/Expandable/Expandable.stories.tsx

@@ -0,0 +1,284 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import {
+  ChevronDownMediumIcon,
+  ChevronUpMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { useState } from 'react';
+import { View } from 'react-native';
+import { BodyText, Button, Card } from '../../components';
+import Expandable from './Expandable';
+
+const meta = {
+  title: 'Stories / Expandable',
+  component: Expandable,
+  parameters: {
+    // layout: 'centered',
+  },
+  argTypes: {
+    expanded: {
+      control: 'boolean',
+      description: 'Whether the content is expanded',
+    },
+    duration: {
+      control: { type: 'number', min: 100, max: 1000, step: 50 },
+      description: 'Animation duration in milliseconds',
+    },
+    accessibilityLabel: {
+      control: 'text',
+      description: 'Accessibility label for screen readers',
+    },
+  },
+  args: {
+    expanded: false,
+    duration: 300,
+  },
+} satisfies Meta<typeof Expandable>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: (args: typeof meta.args) => {
+    const [expanded, setExpanded] = useState(args.expanded ?? false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          {expanded ? 'Collapse' : 'Expand'}
+        </Button>
+        <Expandable {...args} expanded={expanded}>
+          <Card>
+            <BodyText>
+              This is expandable content. It animates smoothly when toggled. You can put any content
+              here, and it will expand and collapse with animation.
+            </BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const BasicExample: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Toggle Content
+        </Button>
+        <Expandable expanded={expanded}>
+          <Card>
+            <BodyText>This content expands and collapses with a smooth animation.</BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const FastAnimation: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Fast Toggle
+        </Button>
+        <Expandable expanded={expanded} duration={150}>
+          <Card>
+            <BodyText>This expands and collapses quickly with a 150ms duration.</BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const SlowAnimation: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Slow Toggle
+        </Button>
+        <Expandable expanded={expanded} duration={600}>
+          <Card>
+            <BodyText>This expands and collapses slowly with a 600ms duration.</BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const LongContent: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          {expanded ? 'Hide Details' : 'Show Details'}
+        </Button>
+        <Expandable expanded={expanded}>
+          <Card>
+            <BodyText>
+              This is a longer piece of content that demonstrates how the Expandable component
+              handles larger amounts of text. The animation smoothly transitions regardless of
+              content length.
+            </BodyText>
+            <BodyText style={{ marginTop: 12 }}>
+              You can include multiple paragraphs, and the component will measure the full height
+              and animate accordingly.
+            </BodyText>
+            <BodyText style={{ marginTop: 12 }}>
+              The animation uses Reanimated for optimal performance and smooth transitions.
+            </BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const MultipleExpandables: Story = {
+  render: () => {
+    const [expanded1, setExpanded1] = useState(false);
+    const [expanded2, setExpanded2] = useState(false);
+    const [expanded3, setExpanded3] = useState(false);
+
+    return (
+      <View style={{ width: 300, gap: 16 }}>
+        <View>
+          <Button
+            onPress={() => setExpanded1(!expanded1)}
+            style={{ marginBottom: 8 }}
+            iconPosition="right"
+            icon={expanded1 ? ChevronUpMediumIcon : ChevronDownMediumIcon}
+          >
+            Section 1
+          </Button>
+          <Expandable expanded={expanded1}>
+            <Card>
+              <BodyText>Content for section 1</BodyText>
+            </Card>
+          </Expandable>
+        </View>
+
+        <View>
+          <Button
+            onPress={() => setExpanded2(!expanded2)}
+            style={{ marginBottom: 8 }}
+            iconPosition="right"
+            icon={expanded2 ? ChevronUpMediumIcon : ChevronDownMediumIcon}
+          >
+            Section 2
+          </Button>
+          <Expandable expanded={expanded2}>
+            <Card>
+              <BodyText>Content for section 2 with more detailed information.</BodyText>
+            </Card>
+          </Expandable>
+        </View>
+
+        <View>
+          <Button
+            onPress={() => setExpanded3(!expanded3)}
+            style={{ marginBottom: 8 }}
+            iconPosition="right"
+            icon={expanded3 ? ChevronUpMediumIcon : ChevronDownMediumIcon}
+          >
+            Section 3
+          </Button>
+          <Expandable expanded={expanded3}>
+            <Card>
+              <BodyText>
+                Content for section 3 with even more information that spans multiple lines.
+              </BodyText>
+            </Card>
+          </Expandable>
+        </View>
+      </View>
+    );
+  },
+};
+
+export const ControlledExample: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <View style={{ width: 300 }}>
+        <View style={{ flexDirection: 'row', gap: 8, marginBottom: 16 }}>
+          <Button onPress={() => setExpanded(true)} style={{ flex: 1 }}>
+            Expand
+          </Button>
+          <Button onPress={() => setExpanded(false)} style={{ flex: 1 }}>
+            Collapse
+          </Button>
+        </View>
+        <Expandable
+          expanded={expanded}
+          onExpandedChange={setExpanded}
+          accessibilityLabel="Expandable content section"
+        >
+          <Card>
+            <BodyText>
+              This is a controlled expandable with separate expand and collapse buttons.
+            </BodyText>
+          </Card>
+        </Expandable>
+      </View>
+    );
+  },
+};
+
+export const DefaultExpanded: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(true);
+
+    return (
+      <View style={{ width: 300 }}>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Toggle
+        </Button>
+        <Expandable expanded={expanded}>
+          <Card>
+            <BodyText>This content starts expanded by default.</BodyText>
+          </Card>
+        </Expandable>
+      </View>
+    );
+  },
+};
+
+export const WithCallback: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+    const [message, setMessage] = useState('Content is collapsed');
+
+    const handleExpandedChange = (newExpanded: boolean) => {
+      console.log(newExpanded);
+      setMessage(newExpanded ? 'Content is expanded' : 'Content is collapsed');
+    };
+
+    return (
+      <View style={{ width: 300 }}>
+        <BodyText style={{ marginBottom: 8 }}>{message}</BodyText>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Toggle
+        </Button>
+        <Expandable expanded={expanded} onExpandedChange={handleExpandedChange}>
+          <Card>
+            <BodyText>This example demonstrates the onExpandedChange callback.</BodyText>
+          </Card>
+        </Expandable>
+      </View>
+    );
+  },
+};

package/src/components/Expandable/Expandable.tsx

@@ -0,0 +1,92 @@
+import { useEffect } from 'react';
+import { View } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useDerivedValue,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { StyleSheet } from 'react-native-unistyles';
+import { ExpandableProps } from './Expandable.props';
+
+const Expandable = ({
+  expanded = false,
+  onExpandedChange,
+  children,
+  duration = 200,
+  style,
+  accessibilityLabel,
+  testID,
+  animateOpacity = true,
+  ...props
+}: ExpandableProps) => {
+  const height = useSharedValue(0);
+  const open = useSharedValue(expanded);
+
+  // Update open value when expanded prop changes and call callback
+  useEffect(() => {
+    if (open.value !== expanded) {
+      open.value = expanded;
+      onExpandedChange?.(expanded);
+    }
+  }, [expanded, onExpandedChange, open]);
+
+  const derivedHeight = useDerivedValue(() =>
+    withTiming(height.value * Number(open.value), {
+      duration,
+    })
+  );
+
+  const derivedOpacity = useDerivedValue(() =>
+    animateOpacity
+      ? withTiming(Number(open.value), {
+          duration,
+        })
+      : 1
+  );
+
+  const heightStyle = useAnimatedStyle(() => ({
+    height: derivedHeight.value,
+  }));
+
+  const opacityStyle = useAnimatedStyle(() => ({
+    opacity: derivedOpacity.value,
+  }));
+
+  return (
+    <Animated.View
+      style={[styles.container, heightStyle, style]}
+      accessible={true}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole="none"
+      accessibilityState={{ expanded }}
+      testID={testID}
+      {...props}
+    >
+      <Animated.View style={opacityStyle}>
+        <View
+          onLayout={e => {
+            height.value = e.nativeEvent.layout.height;
+          }}
+          style={styles.content}
+        >
+          {children}
+        </View>
+      </Animated.View>
+    </Animated.View>
+  );
+};
+
+Expandable.displayName = 'Expandable';
+
+const styles = StyleSheet.create(() => ({
+  container: {
+    overflow: 'hidden',
+  },
+  content: {
+    position: 'absolute',
+    width: '100%',
+  },
+}));
+
+export default Expandable;

package/src/components/Expandable/index.ts

@@ -0,0 +1,2 @@
+export { default as Expandable } from './Expandable';
+export type { ExpandableProps } from './Expandable.props';

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.