@utilitywarehouse/hearth-react-native 0.7.0 → 0.8.1

package/src/components/ExpandableCard/ExpandableCardTrailingContent.tsx

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

package/src/components/ExpandableCard/ExpandableCardTrailingIcon.tsx

@@ -0,0 +1,30 @@
+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 ExpandableCardTrailingIcon = ({ 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>
+  );
+};
+
+ExpandableCardTrailingIcon.displayName = 'ExpandableCardTrailingIcon';
+
+const styles = StyleSheet.create(theme => ({
+  icon: {
+    color: theme.color.icon.primary,
+  },
+}));
+
+export default ExpandableCardTrailingIcon;

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

@@ -0,0 +1,47 @@
+import type { ComponentType } from 'react';
+import type { PressableProps } from 'react-native';
+import type BadgeProps from '../Badge/Badge.props';
+
+export interface ExpandableCardTriggerProps extends Omit<PressableProps, 'children'> {
+  /**
+   * The main heading text
+   */
+  heading?: string;
+  /**
+   * Optional helper text displayed below the heading
+   */
+  helperText?: string;
+  /**
+   * Leading icon component
+   */
+  leadingIcon?: ComponentType;
+  /**
+   * Content to display on the left side (e.g., icon, avatar)
+   */
+  leadingContent?: React.ReactNode;
+  /**
+   * Optional badge to display
+   */
+  badge?: BadgeProps;
+  /**
+   * Position of the badge relative to the heading
+   * @default 'bottom'
+   */
+  badgePosition?: 'top' | 'bottom';
+  /**
+   * Optional numeric value to display
+   */
+  numericValue?: string | number;
+  /**
+   * Whether the expandable card is expanded
+   */
+  isExpanded: boolean;
+  /**
+   * Whether the trigger is disabled
+   */
+  disabled?: boolean;
+  /* Optional children */
+  children?: React.ReactNode;
+}
+
+export default ExpandableCardTriggerProps;

package/src/components/ExpandableCard/ExpandableCardTrigger.tsx

@@ -0,0 +1,10 @@
+import { createPressable } from '@gluestack-ui/pressable';
+import ExpandableCardTriggerRoot from './ExpandableCardTriggerRoot';
+
+const ExpandableCardTrigger = createPressable({
+  Root: ExpandableCardTriggerRoot,
+});
+
+ExpandableCardTrigger.displayName = 'ExpandableCardTrigger';
+
+export default ExpandableCardTrigger;

package/src/components/ExpandableCard/ExpandableCardTriggerRoot.tsx

@@ -0,0 +1,154 @@
+import {
+  ChevronDownSmallIcon,
+  ChevronUpSmallIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { Pressable, ViewStyle } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { Badge } from '../Badge';
+import { DetailText } from '../DetailText';
+import ExpandableCardContent from './ExpandableCardContent';
+import ExpandableCardHelperText from './ExpandableCardHelperText';
+import ExpandableCardIcon from './ExpandableCardIcon';
+import ExpandableCardLeadingContent from './ExpandableCardLeadingContent';
+import ExpandableCardText from './ExpandableCardText';
+import ExpandableCardTrailingContent from './ExpandableCardTrailingContent';
+import ExpandableCardTrailingIcon from './ExpandableCardTrailingIcon';
+import type ExpandableCardTriggerProps from './ExpandableCardTrigger.props';
+
+const ExpandableCardTriggerRoot = ({
+  heading,
+  helperText,
+  leadingIcon,
+  leadingContent,
+  badge,
+  badgePosition = 'bottom',
+  numericValue,
+  isExpanded,
+  disabled,
+  states,
+  children,
+  ...props
+}: ExpandableCardTriggerProps & { states?: { active?: boolean; disabled?: boolean } }) => {
+  const { active } = states || { active: false };
+
+  const testID = props.testID || 'expandable-card-trigger';
+
+  styles.useVariants({
+    active,
+    disabled: !!disabled,
+  });
+
+  const renderLeadingContent = () => {
+    if (leadingIcon) {
+      return (
+        <ExpandableCardLeadingContent>
+          <ExpandableCardIcon as={leadingIcon} />
+        </ExpandableCardLeadingContent>
+      );
+    }
+
+    if (leadingContent) {
+      return <ExpandableCardLeadingContent>{leadingContent}</ExpandableCardLeadingContent>;
+    }
+
+    return null;
+  };
+
+  const renderTopBadge = () => {
+    if (badgePosition === 'top' && badge) {
+      return <Badge {...badge} />;
+    }
+    return null;
+  };
+
+  const renderBottomBadge = () => {
+    if (badgePosition === 'bottom' && badge) {
+      return <Badge {...badge} />;
+    }
+    return null;
+  };
+
+  const renderDefaultContent = () => (
+    <>
+      {renderLeadingContent()}
+      <ExpandableCardContent>
+        {renderTopBadge()}
+        <ExpandableCardText>{heading}</ExpandableCardText>
+        {helperText && <ExpandableCardHelperText>{helperText}</ExpandableCardHelperText>}
+        {renderBottomBadge()}
+      </ExpandableCardContent>
+      {numericValue && (
+        <DetailText size="lg" style={styles.numericValue}>
+          {numericValue}
+        </DetailText>
+      )}
+      <ExpandableCardTrailingContent style={styles.chevron}>
+        <ExpandableCardTrailingIcon as={isExpanded ? ChevronUpSmallIcon : ChevronDownSmallIcon} />
+      </ExpandableCardTrailingContent>
+    </>
+  );
+
+  return (
+    <Pressable
+      {...props}
+      testID={testID}
+      style={[styles.container, props.style as ViewStyle]}
+      disabled={disabled}
+      accessibilityRole="button"
+      accessibilityState={{ expanded: isExpanded, disabled }}
+      accessibilityLabel={`${heading}${helperText ? `, ${helperText}` : ''}`}
+    >
+      {children || renderDefaultContent()}
+    </Pressable>
+  );
+};
+
+ExpandableCardTriggerRoot.displayName = 'ExpandableCardTriggerRoot';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    paddingVertical: theme.components.card.mobile.padding,
+    paddingHorizontal: theme.components.card.mobile.padding,
+    flexDirection: 'row',
+    width: '100%',
+    gap: theme.components.expandableCard.gapHorizontal,
+    variants: {
+      disabled: {
+        true: {
+          cursor: 'auto',
+          opacity: theme.opacity.disabled,
+        },
+        false: {
+          _web: {
+            _hover: {
+              backgroundColor: theme.color.interactive.neutral.surface.subtle.hover,
+            },
+            _active: {
+              backgroundColor: theme.color.interactive.neutral.surface.subtle.active,
+            },
+          },
+        },
+      },
+      active: {
+        true: {},
+      },
+    },
+    compoundVariants: [
+      {
+        disabled: false,
+        active: true,
+        styles: {
+          backgroundColor: theme.color.interactive.neutral.surface.subtle.active,
+        },
+      },
+    ],
+  },
+  chevron: {
+    justifyContent: 'center',
+  },
+  numericValue: {
+    alignSelf: 'center',
+  },
+}));
+
+export default ExpandableCardTriggerRoot;

package/src/components/ExpandableCard/index.ts

@@ -0,0 +1,14 @@
+export { default as ExpandableCard } from './ExpandableCard';
+export type { default as ExpandableCardProps } from './ExpandableCard.props';
+export { default as ExpandableCardContent } from './ExpandableCardContent';
+export { default as ExpandableCardExpandedContent } from './ExpandableCardExpandedContent';
+export { default as ExpandableCardGroup } from './ExpandableCardGroup';
+export type { default as ExpandableCardGroupProps } from './ExpandableCardGroup.props';
+export { default as ExpandableCardHelperText } from './ExpandableCardHelperText';
+export { default as ExpandableCardIcon } from './ExpandableCardIcon';
+export { default as ExpandableCardLeadingContent } from './ExpandableCardLeadingContent';
+export { default as ExpandableCardText } from './ExpandableCardText';
+export { default as ExpandableCardTrailingContent } from './ExpandableCardTrailingContent';
+export { default as ExpandableCardTrailingIcon } from './ExpandableCardTrailingIcon';
+export { default as ExpandableCardTrigger } from './ExpandableCardTrigger';
+export type { default as ExpandableCardTriggerProps } from './ExpandableCardTrigger.props';

package/src/components/HighlightBanner/HighlightBanner.docs.mdx

@@ -0,0 +1,296 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Button, Center, HighlightBanner, Link } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './HighlightBanner.stories';
+
+<Meta title="Components / Highlight Banner" />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=8306-4665&t=qkAoIRb6rKiYkSIE-4" />
+
+<BackToTopButton />
+
+# Highlight Banner
+
+A `HighlightBanner` component is a specialised card layout designed for highlighting featured content with an image. It combines a colored heading banner, an optional image, and descriptive text with optional action buttons or links. Perfect for promotional content, featured articles, or important announcements.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Variants](#variants)
+- [Examples](#examples)
+  - [With Button](#with-button)
+  - [With Link](#with-link)
+  - [Without Image](#without-image)
+  - [Color Variants](#color-variants)
+  - [Subtle Variant](#subtle-variant)
+  - [Different Images](#different-images)
+  - [Custom Image Height](#custom-image-height)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Center>
+    <HighlightBanner
+      heading="Featured Content"
+      headingColor="energy"
+      image={{
+        source: {
+          uri: 'https://images.unsplash.com/photo-1506126613408-eca07ce68773?w=800&q=80',
+        },
+      }}
+      description="This is a description of the featured content that appears below the image."
+    />
+  </Center>
+</UsageWrap>
+
+```jsx
+import { HighlightBanner } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <HighlightBanner
+    heading="Featured Content"
+    headingColor="energy"
+    image={{
+      source: {
+        uri: 'https://example.com/image.jpg',
+      },
+    }}
+    description="This is a description of the featured content."
+  />
+);
+```
+
+## Props
+
+| Property             | Type                                                                                               | Description                                                   | Default      |
+| -------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------ |
+| heading              | `string`                                                                                           | The heading text displayed at the top with colored background | `-`          |
+| headingColor         | `'pig' \| 'energy' \| 'broadband' \| 'mobile' \|` <br />`'insurance' \| 'cashback' \| 'highlight'` | The semantic color scheme for the heading background          | `-`          |
+| image                | `ImageProps`                                                                                       | React Native Image props for the featured image               | `-`          |
+| imageContainerHeight | `number`                                                                                           | Height of the image container in pixels                       | `200`        |
+| description          | `string`                                                                                           | Description text displayed below the image                    | `-`          |
+| link                 | `ReactElement`                                                                                     | Optional Link component displayed below description           | `-`          |
+| button               | `ReactElement`                                                                                     | Optional Button component displayed below description         | `-`          |
+| variant              | `'emphasis' \| 'subtle'`                                                                           | Visual style variant with strong or subtle borders            | `'emphasis'` |
+
+The component also accepts all standard Card props except `noPadding`, `space`, `gap`, `rowGap`, `columnGap`, `flexDirection`, `flexWrap`, `alignItems`, and `justifyContent`.
+
+## Variants
+
+The HighlightBanner supports two visual variants:
+
+- **emphasis** (default) - Strong borders for clear visual separation
+- **subtle** - Softer borders for a more understated appearance
+
+## Examples
+
+### With Button
+
+Add a Button component to provide a clear call-to-action:
+
+<Canvas of={Stories.WithButton} />
+
+```jsx
+import { HighlightBanner, Button } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <HighlightBanner
+    heading="New Feature"
+    headingColor="energy"
+    image={{
+      source: {
+        uri: 'https://example.com/feature.jpg',
+      },
+    }}
+    description="Check out our latest feature"
+    button={<Button onPress={() => console.log('pressed')}>Get Started</Button>}
+  />
+);
+```
+
+### With Link
+
+Use a Link component for a lighter-weight action:
+
+<Canvas of={Stories.WithLink} />
+
+```jsx
+import { HighlightBanner, Link } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <HighlightBanner
+    heading="Learn More"
+    headingColor="broadband"
+    image={{
+      source: {
+        uri: 'https://example.com/info.jpg',
+      },
+    }}
+    description="Explore our documentation"
+    link={<Link onPress={() => console.log('pressed')}>Read more</Link>}
+  />
+);
+```
+
+### Without Image
+
+Display the HighlightBanner without an image by omitting the `image` prop:
+
+<Canvas of={Stories.WithoutImage} />
+
+```jsx
+import { HighlightBanner, Button } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <HighlightBanner
+    heading="Content Without Image"
+    description="This HighlightBanner does not have an image, focusing solely on the text content."
+    button={<Button onPress={() => console.log('pressed')}>Discover More</Button>}
+  />
+);
+```
+
+### Color Variants
+
+The component supports seven semantic color schemes that automatically apply the appropriate subtle background colors:
+
+<Canvas of={Stories.ColorVariants} />
+
+```jsx
+import { HighlightBanner } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <>
+    {/* Energy Blue */}
+    <HighlightBanner
+      heading="Energy Services"
+      headingColor="energy"
+      image={{ source: { uri: 'https://example.com/energy.jpg' } }}
+      description="Discover our energy solutions"
+    />
+
+    {/* Broadband Green */}
+    <HighlightBanner
+      heading="Broadband Deals"
+      headingColor="broadband"
+      image={{ source: { uri: 'https://example.com/broadband.jpg' } }}
+      description="Fast and reliable broadband"
+    />
+
+    {/* Insurance Orange */}
+    <HighlightBanner
+      heading="Insurance Coverage"
+      headingColor="insurance"
+      image={{ source: { uri: 'https://example.com/insurance.jpg' } }}
+      description="Protect what matters most"
+    />
+
+    {/* Mobile Rose */}
+    <HighlightBanner
+      heading="Mobile Plans"
+      headingColor="mobile"
+      image={{ source: { uri: 'https://example.com/mobile.jpg' } }}
+      description="Stay connected anywhere"
+    />
+
+    {/* Cashback Lilac */}
+    <HighlightBanner
+      heading="Cashback Rewards"
+      headingColor="cashback"
+      image={{ source: { uri: 'https://example.com/cashback.jpg' } }}
+      description="Earn rewards on your bills"
+    />
+
+    {/* Pig Pink */}
+    <HighlightBanner
+      heading="Savings Account"
+      headingColor="pig"
+      image={{ source: { uri: 'https://example.com/savings.jpg' } }}
+      description="Save for your future"
+    />
+
+    {/* Highlight Yellow */}
+    <HighlightBanner
+      heading="Special Offer"
+      headingColor="highlight"
+      image={{ source: { uri: 'https://example.com/offer.jpg' } }}
+      description="Limited time promotion"
+    />
+  </>
+);
+```
+
+### Subtle Variant
+
+Use the subtle variant for a softer, less prominent appearance:
+
+<Canvas of={Stories.SubtleCard} />
+
+```jsx
+import { HighlightBanner } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <HighlightBanner
+    variant="subtle"
+    heading="Featured Content"
+    headingColor="energy"
+    image={{
+      source: {
+        uri: 'https://example.com/image.jpg',
+      },
+    }}
+    description="This banner has a subtle appearance"
+  />
+);
+```
+
+### Different Images
+
+The component works well with various types of imagery:
+
+<Canvas of={Stories.DifferentImages} />
+
+### Custom Image Height
+
+Control the image container height to suit your content needs:
+
+```jsx
+import { HighlightBanner } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <>
+    {/* Default height (200px) */}
+    <HighlightBanner
+      heading="Standard Image"
+      headingColor="energy"
+      image={{ source: { uri: 'https://example.com/image.jpg' } }}
+      description="Using default height"
+    />
+
+    {/* Custom height */}
+    <HighlightBanner
+      heading="Tall Image"
+      headingColor="broadband"
+      image={{ source: { uri: 'https://example.com/image.jpg' } }}
+      imageContainerHeight={300}
+      description="Using custom height of 300px"
+    />
+  </>
+);
+```
+
+## Best Practices
+
+- Use the **energy**, **broadband**, **mobile**, **insurance**, **cashback**, or **pig** colors to align with specific service offerings
+- Use **highlight** for time-sensitive promotions or special offers
+- Keep descriptions concise and scannable
+- Choose between link and button based on the importance of the action - use buttons for primary actions
+- Consider using the subtle variant when displaying multiple banners to reduce visual clutter
+- Ensure images are high quality and relevant to the content
+- Use appropriate image heights based on the aspect ratio of your images

package/src/components/HighlightBanner/HighlightBanner.props.ts

@@ -0,0 +1,29 @@
+import { ReactElement } from 'react';
+import { ImageProps } from 'react-native';
+import CardProps from '../Card/Card.props';
+
+interface HighlightBannerProps
+  extends Omit<
+    CardProps,
+    | 'noPadding'
+    | 'variant'
+    | 'space'
+    | 'gap'
+    | 'rowGap'
+    | 'columnGap'
+    | 'flexDirection'
+    | 'flexWrap'
+    | 'alignItems'
+    | 'justifyContent'
+  > {
+  heading?: string;
+  headingColor?: 'pig' | 'energy' | 'broadband' | 'mobile' | 'insurance' | 'cashback' | 'highlight';
+  variant?: 'emphasis' | 'subtle';
+  image?: ImageProps;
+  imageContainerHeight?: number;
+  description?: string;
+  link?: ReactElement;
+  button?: ReactElement;
+}
+
+export default HighlightBannerProps;