@utilitywarehouse/hearth-react-native 0.6.0 → 0.7.0

package/src/components/Card/Card.docs.mdx

@@ -2,6 +2,7 @@ import { Canvas, Controls, Meta, Primary, Story } from '@storybook/addon-docs/bl
 import { BodyText, Card, Center, DetailText } from '../../';
 import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
 import * as Stories from './Card.stories';
+import * as ActionStories from './CardAction/CardAction.stories';
 
 <Meta title="Components / Card" />
 
@@ -17,7 +18,9 @@ A Card component serves as a visual container that groups related content and ac
 - [Usage](#usage)
 - [Props](#props)
 - [Variants](#variants)
-- [Interactive](#interactive)
+- [Examples](#examples)
+  - [Interactive](#interactive)
+  - [With `CardAction`](#with-cardaction)
 
 ## Playground
 
@@ -55,7 +58,7 @@ const MyComponent = () => (
 | colorScheme    | `'neutralStrong' \| 'neutralSubtle' \| 'purple' \| 'energy'` <br /> `'broadband' \| 'mobile' \| 'insurance' \| 'cashback' \|` <br /> `'pig'` | The color scheme of the card.              | `'neutralStrong'` |
 | noPadding      | `boolean`                                                                                                                                    | Wether or not the card has padding.        | `false`           |
 | selected       | `boolean`                                                                                                                                    | Whether the card is selected.              | `false`           |
-| onPress        | `() => void`                                                                                                                                 | Callback function to be called.            | -                 |
+| onPress        | `() => void`                                                                                                                                 | Callback function to be called.            | `-`               |
 | disabled       | `boolean`                                                                                                                                    | Whether the card is disabled.              | `false`           |
 | space          | `'none' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                                                                           | The space between the content.             | `none`            |
 | alignItems     | `'flex-start' \| 'flex-end' \| `<br />`'center' \| 'stretch' \| 'baseline'`                                                                  | The align items of the flex container.     | `flex-start`      |
@@ -66,42 +69,237 @@ const MyComponent = () => (
 | rowGap         | `number`                                                                                                                                     | The row gap between the content.           | `0`               |
 | columnGap      | `number`                                                                                                                                     | The column gap between the content.        | `0`               |
 
+### `CardPressHandler`
+
+| Property         | Type     | Description                                                                 | Default   |
+| ---------------- | -------- | --------------------------------------------------------------------------- | --------- |
+| handlerToInherit | `string` | The handler to inherit from the child component when the `Card` is pressed. | `onPress` |
+
 ### `CardAction`
 
-| Property        | Type     | Description                                                                | Default   |
-| --------------- | -------- | -------------------------------------------------------------------------- | --------- |
-| actionToInherit | `string` | The action to inherit from the child component when the `Card` is pressed. | `onPress` |
+| Property             | Type                                                                                               | Description                                              | Default    |
+| -------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------- |
+| loading              | `boolean`                                                                                          | Show loading skeleton state                              | `false`    |
+| disabled             | `boolean`                                                                                          | Disable interactions                                     | `false`    |
+| size                 | `'md' \| 'lg'`                                                                                     | Size of the heading text                                 | `'md'`     |
+| onPress              | `() => void`                                                                                       | Callback when the action is pressed                      | `-`        |
+| heading              | `string`                                                                                           | The main heading text (required when not using children) | `-`        |
+| helperText           | `string`                                                                                           | Optional secondary text below the heading                | `-`        |
+| leadingIcon          | `ReactNode`                                                                                        | The leading icon.                                        | `-`        |
+| trailingIcon         | `ReactNode`                                                                                        | The trailing icon.                                       | `-`        |
+| leadingContent       | `ReactNode`                                                                                        | Content to display on the left (typically an icon)       | `-`        |
+| trailingContent      | `ReactNode`                                                                                        | Content to display on the right (typically an icon)      | `-`        |
+| iconContainer        | `boolean`                                                                                          | Whether to show the icon container                       | `false`    |
+| iconContainerVariant | `'subtle' \| 'emphasis'`                                                                           | Variant of the icon container                            | `'subtle'` |
+| iconContainerColor   | `'pig' \| 'energy' \| 'broadband' \| 'mobile' \|` <br />`'insurance' \| 'cashback' \| 'highlight'` | Semantic colour family for surface tokens                | `pig`      |
+| badge                | `BadgeProps`                                                                                       | Badge configuration object                               |            |
+| badgePosition        | `'bottom' \| 'middle' \| 'right' \| 'top'`                                                         | Position of the badge                                    | `'bottom'` |
 
 ## Variants
 
 <Canvas of={Stories.Variants} />
 
-## Interactive
+## Examples
+
+### Interactive
 
 You can make the card interactive by adding an `onPress` prop. You can also toggle the `selected` prop
 to change the card's appearance.
 
-Alternatively to make the card inherit an action from a child component, you can use the `CardAction` component.
-This will by default inherit the `onPress` action from the child component. You can specify a different action
-by passing the `actionToInherit` prop e.g `onChange`. Wrapping a component in a `CardAction` component will
+Alternatively to make the card inherit an event handler from a child component, you can use the `CardPressHandler` component.
+This will by default inherit the `onPress` handler from the child component. You can specify a different action
+by passing the `handlerToInherit` prop e.g `onChange`. Wrapping a component in a `CardPressHandler` component will
 make the card interactive and also show the `active` state of the child component when the `Card` is pressed.
 
 <Canvas of={Stories.Interactive} />
 
-See example below for how to use the `CardAction` component:
+See example below for how to use the `CardPressHandler` component:
 
 ```jsx
-import { Card, CardAction, BodyText, Heading, Felx, Button } from '@utilitywarehouse/hearth-react-native';
+import {
+  Card,
+  CardPressHandler,
+  BodyText,
+  Heading,
+  Flex,
+  Button,
+} from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (
   <Card variant="emphasis" colorScheme="neutralSubtle">
     <Flex space="md" direction="column" align="stretch">
       <Heading size="md">Heading</Heading>
-      <BodyText>{children as string}</BodyText>
-      <CardAction>
+      <BodyText>Content</BodyText>
+      <CardPressHandler>
         <Button onPress={() => console.log('pressed')}>Press me</Button>
-      </CardAction>
+      </CardPressHandler>
     </Flex>
   </Card>
 );
 ```
+
+### With `CardAction`
+
+You can use the `CardAction` component within a `Card` to create actionable items with consistent styling.
+
+<Canvas of={Stories.WithActions} />
+
+```jsx
+import { Card, CardAction, BodyText, Heading, Flex } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Card variant="emphasis">
+    <BodyText>Content</BodyText>
+    <CardAction
+      onPress={() => console.log('Card action pressed')}
+      heading="Card Action Head"
+      helperText="Some helper text"
+      leadingIcon={BellMediumIcon}
+    />
+    <CardAction
+      onPress={() => console.log('Card action pressed')}
+      heading="Card Action Head"
+      leadingIcon={BellMediumIcon}
+    />
+    <CardAction
+      onPress={() => console.log('Card action pressed')}
+      heading="Card Action Head"
+      helperText="Testing"
+      leadingIcon={BellMediumIcon}
+      iconContainer={false}
+    />
+  </Card>
+);
+```
+
+#### `CardAction` Playground
+
+<Canvas of={ActionStories.Playground} />
+<Controls of={ActionStories.Playground} />
+
+#### `CardAction` With Badge
+
+The badge can be positioned in three different locations:
+
+```tsx
+import { Card, CardAction } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <>
+    {/* Badge at bottom (default) */}
+    <Card>
+      <CardAction
+        heading="Action"
+        helperText="Helper text"
+        badge={{ text: 'New' }}
+        badgePosition="bottom"
+        onPress={() => console.log('pressed')}
+      />
+    </Card>
+
+    {/* Badge in middle (between heading and helper text) */}
+    <Card>
+      <CardAction
+        heading="Action"
+        helperText="Helper text"
+        badge={{ text: 'New' }}
+        badgePosition="middle"
+        onPress={() => console.log('pressed')}
+      />
+    </Card>
+
+    {/* Badge on the right */}
+    <Card>
+      <CardAction
+        heading="Action"
+        helperText="Helper text"
+        badge={{ text: 'New' }}
+        badgePosition="right"
+        onPress={() => console.log('pressed')}
+      />
+    </Card>
+  </>
+);
+```
+
+#### `CardAction` Size Variants
+
+```tsx
+import { Card, CardAction } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <>
+    <Card>
+      <CardAction
+        heading="Medium heading"
+        helperText="Default md size"
+        size="md"
+        onPress={() => console.log('pressed')}
+      />
+    </Card>
+
+    <Card>
+      <CardAction
+        heading="Large heading"
+        helperText="Larger lg size"
+        size="lg"
+        onPress={() => console.log('pressed')}
+      />
+    </Card>
+  </>
+);
+```
+
+#### `CardAction` Advanced Usage with Children
+
+For more complex layouts, you can use the component parts directly:
+
+```tsx
+import {
+  Card,
+  CardAction,
+  CardActionLeadingContent,
+  CardActionContent,
+  CardActionText,
+  CardActionHelperText,
+  CardActionTrailingContent,
+  CardActionIcon,
+  CardActionTrailingIcon,
+} from '@utilitywarehouse/hearth-react-native';
+import {
+  ElectricityMediumIcon,
+  ChevronRightSmallIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => (
+  <Card>
+    <CardAction onPress={() => console.log('pressed')}>
+      <CardActionLeadingContent>
+        <CardActionIcon as={ElectricityMediumIcon} />
+      </CardActionLeadingContent>
+      <CardActionContent>
+        <CardActionText>Custom Layout</CardActionText>
+        <CardActionHelperText>With complete control</CardActionHelperText>
+      </CardActionContent>
+      <CardActionTrailingContent>
+        <CardActionTrailingIcon as={ChevronRightSmallIcon} />
+      </CardActionTrailingContent>
+    </CardAction>
+  </Card>
+);
+```
+
+#### `CardAction` Component Parts
+
+- `CardAction` - Main component wrapper
+- `CardActionContent` - Container for text content
+- `CardActionText` - Heading text
+- `CardActionHelperText` - Secondary helper text
+- `CardActionLeadingContent` - Container for leading content
+- `CardActionTrailingContent` - Container for trailing content
+- `CardActionIcon` - Styled icon for leading content
+- `CardActionTrailingIcon` - Styled icon for trailing content
+
+#### `CardAction` Accessibility
+
+The component automatically sets `accessibilityRole="button"` when an `onPress` handler is provided, ensuring proper screen reader announcements.

package/src/components/Card/Card.stories.tsx

@@ -1,5 +1,6 @@
 import { Meta, StoryObj } from '@storybook/react-vite';
-import { Card, CardAction } from '.';
+import { BellMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { Card, CardAction, CardPressHandler } from '.';
 import { VariantTitle } from '../../../docs/components';
 import { BodyText } from '../BodyText';
 import { Button } from '../Button';
@@ -59,6 +60,52 @@ export const Playground: Story = {
   },
 };
 
+export const WithActions: Story = {
+  render: ({ children, ...props }) => {
+    return (
+      <Card {...props} flexDirection="column" alignItems="stretch" space="md" variant="emphasis">
+        <BodyText>{children as string}</BodyText>
+        <CardAction
+          onPress={() => console.log('Card action pressed')}
+          heading="Card Action Head"
+          helperText="Some helper text"
+          leadingIcon={BellMediumIcon}
+        />
+        <CardAction
+          onPress={() => console.log('Card action pressed')}
+          heading="Card Action Head"
+          leadingIcon={BellMediumIcon}
+        />
+        <CardAction
+          onPress={() => console.log('Card action pressed')}
+          heading="Card Action Head"
+          helperText="Testing"
+          leadingIcon={BellMediumIcon}
+          iconContainer={false}
+        />
+      </Card>
+    );
+  },
+};
+
+export const WithOnlyAction: Story = {
+  args: {
+    variant: 'emphasis',
+  },
+  render: ({ children, ...props }) => {
+    return (
+      <Card {...props} flexDirection="column" alignItems="stretch" space="md">
+        <CardAction
+          onPress={() => console.log('Card action pressed')}
+          heading="Card Action Head"
+          helperText="Some helper text"
+          leadingIcon={BellMediumIcon}
+        />
+      </Card>
+    );
+  },
+};
+
 export const Variants: Story = {
   parameters: {
     controls: { exclude: ['variant', 'colorScheme'] },
@@ -224,9 +271,9 @@ export const Interactive: Story = {
           >
             <Heading size="md">Heading</Heading>
             <BodyText>{children as string}</BodyText>
-            <CardAction>
+            <CardPressHandler>
               <Button onPress={() => console.log('pressed')}>Press me</Button>
-            </CardAction>
+            </CardPressHandler>
           </Card>
         </VariantTitle>
       </Flex>

package/src/components/Card/CardAction/CardAction.context.ts

@@ -0,0 +1,22 @@
+import { createContext, useContext } from 'react';
+
+export interface ICardActionContext {
+  showPressed: boolean;
+  active?: boolean;
+  loading: boolean;
+  disabled: boolean;
+  size: 'md' | 'lg';
+}
+
+export const CardActionContext = createContext<ICardActionContext>({
+  showPressed: false,
+  active: false,
+  loading: false,
+  disabled: false,
+  size: 'md',
+});
+
+export const useCardActionContext = () => {
+  const context = useContext(CardActionContext);
+  return context;
+};

package/src/components/Card/CardAction/CardAction.props.ts

@@ -0,0 +1,87 @@
+import { ComponentType } from 'react';
+import type { PressableProps, ViewProps } from 'react-native';
+import BadgeProps from '../../Badge/Badge.props';
+import { IconContainerProps } from '../../IconContainer';
+
+interface CardActionBaseProps extends Omit<PressableProps, 'children'> {
+  loading?: boolean;
+  disabled?: boolean;
+  size?: 'md' | 'lg';
+}
+
+interface CardActionContentProps {
+  heading: string;
+  helperText?: string;
+  badge?: BadgeProps;
+  badgePosition?: 'bottom' | 'middle' | 'right' | 'top';
+  iconContainer?: boolean;
+  iconContainerVariant?: IconContainerProps['variant'];
+  iconContainerColor?: IconContainerProps['color'];
+}
+
+export interface CardActionWithChildren extends CardActionBaseProps {
+  children: ViewProps['children'];
+  heading?: never;
+  helperText?: never;
+  leadingContent?: never;
+  leadingIcon?: never;
+  trailingContent?: never;
+  trailingIcon?: never;
+  badge?: never;
+  badgePosition?: never;
+  iconContainer?: never;
+  iconContainerVariant?: never;
+  iconContainerColor?: never;
+}
+
+// Leading content variants
+type CardActionWithLeadingContent = CardActionBaseProps &
+  CardActionContentProps & {
+    children?: never;
+    leadingContent: ViewProps['children'];
+    leadingIcon?: never;
+  };
+
+type CardActionWithLeadingIcon = CardActionBaseProps &
+  CardActionContentProps & {
+    children?: never;
+    leadingContent?: never;
+    leadingIcon: ComponentType;
+  };
+
+type CardActionWithNoLeading = CardActionBaseProps &
+  CardActionContentProps & {
+    children?: never;
+    leadingContent?: never;
+    leadingIcon?: never;
+  };
+
+type CardActionLeadingVariants =
+  | CardActionWithLeadingContent
+  | CardActionWithLeadingIcon
+  | CardActionWithNoLeading;
+
+// Trailing content combined with leading variants
+type CardActionWithTrailingContent = CardActionLeadingVariants & {
+  trailingContent: ViewProps['children'];
+  trailingIcon?: never;
+};
+
+type CardActionWithTrailingIcon = CardActionLeadingVariants & {
+  trailingContent?: never;
+  trailingIcon: ComponentType;
+};
+
+type CardActionWithNoTrailing = CardActionLeadingVariants & {
+  trailingContent?: never;
+  trailingIcon?: never;
+};
+
+type CardActionWithoutChildren =
+  | CardActionWithTrailingContent
+  | CardActionWithTrailingIcon
+  | CardActionWithNoTrailing;
+
+type CardActionProps = CardActionWithChildren | CardActionWithoutChildren;
+
+export default CardActionProps;