@utilitywarehouse/hearth-react-native 0.7.0 → 0.8.1

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;

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

@@ -0,0 +1,326 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import {
+  BillMediumIcon,
+  ElectricityMediumIcon,
+  GasMediumIcon,
+  PaymentMediumIcon,
+  SettingsMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import React from 'react';
+import { BodyText, IconContainer, Link } from '../../components';
+import ExpandableCard from './ExpandableCard';
+import ExpandableCardExpandedContent from './ExpandableCardExpandedContent';
+import ExpandableCardGroup from './ExpandableCardGroup';
+import ExpandableCardIcon from './ExpandableCardIcon';
+import ExpandableCardTrigger from './ExpandableCardTrigger';
+
+const meta = {
+  title: 'Stories / ExpandableCard',
+  component: ExpandableCard,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    expanded: {
+      control: 'boolean',
+      description: 'Whether the card is expanded',
+    },
+    heading: {
+      control: 'text',
+      description: 'The heading text',
+    },
+    helperText: {
+      control: 'text',
+      description: 'Helper text below heading',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the card is disabled',
+    },
+    variant: {
+      control: 'radio',
+      description: 'The variant style of the card',
+      options: ['subtle', 'emphasis'],
+    },
+    duration: {
+      control: { type: 'number', min: 100, max: 1000, step: 50 },
+      description: 'Animation duration in milliseconds',
+    },
+    animateOpacity: {
+      control: 'boolean',
+      description: 'Whether to animate opacity',
+    },
+  },
+  args: {
+    heading: 'Expandable Card',
+    helperText: 'Click to expand',
+    expanded: false,
+    disabled: false,
+    duration: 200,
+    animateOpacity: true,
+    variant: 'subtle',
+  },
+} satisfies Meta<typeof ExpandableCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    expandedContent: (
+      <BodyText>
+        This is the expanded content. It can contain any component or content you need.
+      </BodyText>
+    ),
+  },
+};
+
+export const BasicExample: Story = {
+  render: () => (
+    <ExpandableCard
+      heading="Order Details"
+      helperText="View your order information"
+      expandedContent={
+        <>
+          <BodyText>Order #12345</BodyText>
+          <BodyText>Status: Delivered</BodyText>
+          <BodyText>Date: 10 Nov 2025</BodyText>
+        </>
+      }
+      style={{ width: 350 }}
+    />
+  ),
+};
+
+export const WithLeadingIcon: Story = {
+  render: () => (
+    <ExpandableCard
+      heading="Settings"
+      helperText="Configure your preferences"
+      leadingIcon={SettingsMediumIcon}
+      expandedContent={
+        <>
+          <BodyText>• Notifications</BodyText>
+          <BodyText>• Privacy</BodyText>
+          <BodyText>• Account</BodyText>
+        </>
+      }
+      style={{ width: 350 }}
+    />
+  ),
+};
+
+export const WithIconContainer: Story = {
+  render: () => (
+    <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>
+          <BodyText>Next Reading: 23/04/24</BodyText>
+        </>
+      }
+      style={{ width: 350 }}
+    />
+  ),
+};
+
+export const WithBadge: Story = {
+  render: () => (
+    <ExpandableCard
+      heading="New Feature"
+      helperText="Check out what's new"
+      badge={{ text: 'New', colorScheme: 'info' }}
+      expandedContent={
+        <BodyText>We've added new features to improve your experience. Explore them now!</BodyText>
+      }
+      style={{ width: 350 }}
+    />
+  ),
+};
+
+export const WithNumericValue: Story = {
+  render: () => (
+    <ExpandableCard
+      heading="Total Balance"
+      helperText="Current account balance"
+      numericValue="£123.45"
+      expandedContent={
+        <>
+          <BodyText>Available: £100.00</BodyText>
+          <BodyText>Pending: £23.45</BodyText>
+        </>
+      }
+      style={{ width: 350 }}
+    />
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <ExpandableCard
+      heading="Disabled Card"
+      helperText="This card cannot be expanded"
+      disabled
+      expandedContent={<BodyText>This content is not accessible</BodyText>}
+      style={{ width: 350 }}
+    />
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [expanded, setExpanded] = React.useState(false);
+
+    return (
+      <div style={{ width: 350 }}>
+        <BodyText style={{ marginBottom: 8 }}>
+          Status: {expanded ? 'Expanded' : 'Collapsed'}
+        </BodyText>
+        <ExpandableCard
+          heading="Controlled Card"
+          helperText="Externally controlled state"
+          expanded={expanded}
+          onExpandedChange={setExpanded}
+          expandedContent={
+            <BodyText>This card's state is controlled by the parent component.</BodyText>
+          }
+        />
+      </div>
+    );
+  },
+};
+
+export const CardGroup: Story = {
+  render: () => (
+    <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>
+  ),
+};
+
+export const GroupWithMixedContent: Story = {
+  render: () => (
+    <ExpandableCardGroup heading="Account Overview">
+      <ExpandableCard
+        heading="Bills"
+        helperText="View your recent bills"
+        leadingContent={<ExpandableCardIcon as={BillMediumIcon} />}
+        expandedContent={
+          <>
+            <BodyText>• March 2025: £89.50</BodyText>
+            <BodyText>• February 2025: £92.00</BodyText>
+            <BodyText>• January 2025: £95.30</BodyText>
+          </>
+        }
+      />
+      <ExpandableCard
+        heading="Payments"
+        helperText="Payment history"
+        leadingContent={<ExpandableCardIcon as={PaymentMediumIcon} />}
+        numericValue="3"
+        expandedContent={
+          <>
+            <BodyText>• 05/03/25: £89.50 paid</BodyText>
+            <BodyText>• 05/02/25: £92.00 paid</BodyText>
+            <BodyText>• 05/01/25: £95.30 paid</BodyText>
+          </>
+        }
+      />
+      <ExpandableCard
+        heading="Settings"
+        leadingContent={<ExpandableCardIcon as={SettingsMediumIcon} />}
+        badge={{ text: 'Updated', colorScheme: 'info', size: 'sm' }}
+        expandedContent={
+          <>
+            <BodyText>• Notification preferences</BodyText>
+            <BodyText>• Payment methods</BodyText>
+            <BodyText>• Account details</BodyText>
+          </>
+        }
+      />
+    </ExpandableCardGroup>
+  ),
+};
+
+export const ColorSchemes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 350 }}>
+      <ExpandableCard
+        heading="Default Card"
+        expandedContent={<BodyText>Default color scheme</BodyText>}
+      />
+      <ExpandableCard
+        heading="Subtle White Card"
+        colorScheme="neutralSubtle"
+        expandedContent={<BodyText>Subtle white color scheme</BodyText>}
+      />
+      <ExpandableCard
+        heading="Strong Card"
+        colorScheme="neutralStrong"
+        expandedContent={<BodyText>Strong color scheme</BodyText>}
+      />
+    </div>
+  ),
+};
+
+export const AdvancedComposition: Story = {
+  render: () => {
+    const [expanded, setExpanded] = 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" />
+          }
+          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>
+    );
+  },
+};

package/src/components/ExpandableCard/ExpandableCard.tsx

@@ -0,0 +1,76 @@
+import { useState } from 'react';
+import { Card } from '../Card';
+import type ExpandableCardProps from './ExpandableCard.props';
+import ExpandableCardExpandedContent from './ExpandableCardExpandedContent';
+import ExpandableCardTrigger from './ExpandableCardTrigger';
+
+const ExpandableCard = ({
+  expanded: controlledExpanded,
+  onExpandedChange,
+  heading,
+  helperText,
+  leadingIcon,
+  leadingContent,
+  badge,
+  badgePosition = 'bottom',
+  numericValue,
+  expandedContent,
+  duration = 200,
+  animateOpacity = true,
+  disabled = false,
+  testID = 'expandable-card',
+  children,
+  ...cardProps
+}: ExpandableCardProps) => {
+  const [internalExpanded, setInternalExpanded] = useState(false);
+
+  // Use controlled or uncontrolled state
+  const isExpanded = controlledExpanded !== undefined ? controlledExpanded : internalExpanded;
+
+  const handlePress = () => {
+    if (disabled) return;
+
+    const newExpanded = !isExpanded;
+
+    if (controlledExpanded === undefined) {
+      setInternalExpanded(newExpanded);
+    }
+
+    onExpandedChange?.(newExpanded);
+  };
+
+  const renderDefaultContent = () => (
+    <>
+      <ExpandableCardTrigger
+        onPress={handlePress}
+        disabled={disabled}
+        heading={heading}
+        helperText={helperText}
+        leadingIcon={leadingIcon}
+        leadingContent={leadingContent}
+        badge={badge}
+        badgePosition={badgePosition}
+        numericValue={numericValue}
+        isExpanded={isExpanded}
+        testID={`${testID}-trigger`}
+      />
+      <ExpandableCardExpandedContent
+        isExpanded={isExpanded}
+        duration={duration}
+        animateOpacity={animateOpacity}
+      >
+        {expandedContent}
+      </ExpandableCardExpandedContent>
+    </>
+  );
+
+  return (
+    <Card noPadding {...cardProps} testID={testID}>
+      {children || renderDefaultContent()}
+    </Card>
+  );
+};
+
+ExpandableCard.displayName = 'ExpandableCard';
+
+export default ExpandableCard;

package/src/components/ExpandableCard/ExpandableCardContent.tsx

@@ -0,0 +1,21 @@
+import { View, type ViewProps } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+
+const ExpandableCardContent = ({ children, ...props }: ViewProps) => {
+  return (
+    <View {...props} style={[styles.container, props.style]}>
+      {children}
+    </View>
+  );
+};
+
+ExpandableCardContent.displayName = 'ExpandableCardContent';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    gap: theme.components.expandableCard.gapVertical,
+    flex: 1,
+  },
+}));
+
+export default ExpandableCardContent;

package/src/components/ExpandableCard/ExpandableCardExpandedContent.tsx

@@ -0,0 +1,42 @@
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { Divider } from '../Divider';
+import { Expandable } from '../Expandable';
+
+interface ExpandableCardExpandedContentProps {
+  children: React.ReactNode;
+  isExpanded: boolean;
+  duration?: number;
+  animateOpacity?: boolean;
+}
+
+const ExpandableCardExpandedContent = ({
+  children,
+  isExpanded,
+  duration = 200,
+  animateOpacity = true,
+}: ExpandableCardExpandedContentProps) => {
+  return (
+    <View style={styles.container}>
+      <Expandable expanded={isExpanded} duration={duration} animateOpacity={animateOpacity}>
+        <View>
+          <Divider space="none" />
+          <View style={styles.content}>{children}</View>
+        </View>
+      </Expandable>
+    </View>
+  );
+};
+
+ExpandableCardExpandedContent.displayName = 'ExpandableCardExpandedContent';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    width: '100%',
+  },
+  content: {
+    padding: theme.components.card.mobile.padding,
+  },
+}));
+
+export default ExpandableCardExpandedContent;

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

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+
+export interface ExpandableCardGroupProps extends ViewProps {
+  /**
+   * Section heading
+   */
+  heading?: string;
+
+  /**
+   * Helper text displayed below the heading
+   */
+  helperText?: string;
+
+  /**
+   * Trailing content for the header (e.g., a link)
+   */
+  headerTrailingContent?: ReactNode;
+
+  /**
+   * The ExpandableCard children
+   */
+  children: ReactNode;
+
+  /**
+   * Test ID for testing
+   */
+  testID?: string;
+}
+
+export default ExpandableCardGroupProps;

package/src/components/ExpandableCard/ExpandableCardGroup.tsx

@@ -0,0 +1,40 @@
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { SectionHeader } from '../SectionHeader';
+import type ExpandableCardGroupProps from './ExpandableCardGroup.props';
+
+const ExpandableCardGroup = ({
+  heading,
+  helperText,
+  headerTrailingContent,
+  children,
+  style,
+  testID = 'expandable-card-group',
+  ...props
+}: ExpandableCardGroupProps) => {
+  return (
+    <View style={[styles.container, style]} testID={testID} {...props}>
+      {heading ? (
+        <SectionHeader
+          heading={heading}
+          helperText={helperText}
+          trailingContent={headerTrailingContent}
+        />
+      ) : null}
+      <View style={styles.cardsContainer}>{children}</View>
+    </View>
+  );
+};
+
+ExpandableCardGroup.displayName = 'ExpandableCardGroup';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    gap: theme.components.expandableCard.group.gap,
+  },
+  cardsContainer: {
+    gap: theme.components.expandableCard.group.gap,
+  },
+}));
+
+export default ExpandableCardGroup;

package/src/components/ExpandableCard/ExpandableCardHelperText.tsx

@@ -0,0 +1,21 @@
+import { TextProps } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { BodyText } from '../BodyText';
+
+const ExpandableCardHelperText = ({ children, ...props }: TextProps) => {
+  return (
+    <BodyText size="md" {...props} style={[styles.text, props.style]}>
+      {children}
+    </BodyText>
+  );
+};
+
+ExpandableCardHelperText.displayName = 'ExpandableCardHelperText';
+
+const styles = StyleSheet.create(theme => ({
+  text: {
+    color: theme.color.text.secondary,
+  },
+}));
+
+export default ExpandableCardHelperText;

package/src/components/ExpandableCard/ExpandableCardIcon.tsx

@@ -0,0 +1,32 @@
+import { ComponentType } from 'react';
+import { Platform, type StyleProp, type ViewStyle } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { Icon, IconProps } from '../Icon';
+
+const ExpandableCardIcon = ({ children, ...props }: IconProps & { as?: ComponentType }) => {
+  return (
+    <Icon
+      {...props}
+      style={
+        Platform.OS === 'web'
+          ? // @ts-expect-error - style prop type issue
+            { ...(styles.icon as StyleProp<ViewStyle>), ...props.style }
+          : ([styles.icon as StyleProp<ViewStyle>, props.style] as any)
+      }
+    >
+      {children}
+    </Icon>
+  );
+};
+
+ExpandableCardIcon.displayName = 'ExpandableCardIcon';
+
+const styles = StyleSheet.create(theme => ({
+  icon: {
+    color: theme.color.icon.primary,
+    width: 24,
+    height: 24,
+  },
+}));
+
+export default ExpandableCardIcon;

package/src/components/ExpandableCard/ExpandableCardLeadingContent.tsx

@@ -0,0 +1,9 @@
+import { View, type ViewProps } from 'react-native';
+
+const ExpandableCardLeadingContent = ({ children, ...props }: ViewProps) => (
+  <View {...props}>{children}</View>
+);
+
+ExpandableCardLeadingContent.displayName = 'ExpandableCardLeadingContent';
+
+export default ExpandableCardLeadingContent;

package/src/components/ExpandableCard/ExpandableCardText.tsx

@@ -0,0 +1,14 @@
+import { TextProps } from 'react-native';
+import { BodyText } from '../BodyText';
+
+const ExpandableCardText = ({ children, ...props }: TextProps) => {
+  return (
+    <BodyText size="lg" {...props}>
+      {children}
+    </BodyText>
+  );
+};
+
+ExpandableCardText.displayName = 'ExpandableCardText';
+
+export default ExpandableCardText;