@utilitywarehouse/hearth-react-native 0.16.2 → 0.17.0

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

@@ -172,29 +172,38 @@ You can use the `CardAction` component within a `Card` to create actionable item
 <Canvas of={Stories.WithActions} />
 
 ```jsx
-import { Card, CardAction, BodyText, Heading, Flex } from '@utilitywarehouse/hearth-react-native';
+import {
+  Card,
+  CardAction,
+  CardActions,
+  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}
-    />
+    <CardActions>
+      <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}
+      />
+    </CardActions>
   </Card>
 );
 ```
@@ -209,41 +218,47 @@ const MyComponent = () => (
 The badge can be positioned in three different locations:
 
 ```tsx
-import { Card, CardAction, Badge } from '@utilitywarehouse/hearth-react-native';
+import { Card, CardAction, CardActions, Badge } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (
   <>
     {/* Badge at bottom (default) */}
     <Card>
-      <CardAction
-        heading="Action"
-        helperText="Helper text"
-        badge={<Badge text="New" />}
-        badgePosition="bottom"
-        onPress={() => console.log('pressed')}
-      />
+      <CardActions>
+        <CardAction
+          heading="Action"
+          helperText="Helper text"
+          badge={<Badge text="New" />}
+          badgePosition="bottom"
+          onPress={() => console.log('pressed')}
+        />
+      </CardActions>
     </Card>
 
     {/* Badge in middle (between heading and helper text) */}
     <Card>
-      <CardAction
-        heading="Action"
-        helperText="Helper text"
-        badge={<Badge text="New" />}
-        badgePosition="middle"
-        onPress={() => console.log('pressed')}
-      />
+      <CardActions>
+        <CardAction
+          heading="Action"
+          helperText="Helper text"
+          badge={<Badge text="New" />}
+          badgePosition="middle"
+          onPress={() => console.log('pressed')}
+        />
+      </CardActions>
     </Card>
 
     {/* Badge on the right */}
     <Card>
-      <CardAction
-        heading="Action"
-        helperText="Helper text"
-        badge={<Badge text="New" />}
-        badgePosition="right"
-        onPress={() => console.log('pressed')}
-      />
+      <CardActions>
+        <CardAction
+          heading="Action"
+          helperText="Helper text"
+          badge={<Badge text="New" />}
+          badgePosition="right"
+          onPress={() => console.log('pressed')}
+        />
+      </CardActions>
     </Card>
   </>
 );
@@ -252,26 +267,30 @@ const MyComponent = () => (
 #### `CardAction` Size Variants
 
 ```tsx
-import { Card, CardAction } from '@utilitywarehouse/hearth-react-native';
+import { Card, CardAction, CardActions } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => (
   <>
     <Card>
-      <CardAction
-        heading="Medium heading"
-        helperText="Default md size"
-        size="md"
-        onPress={() => console.log('pressed')}
-      />
+      <CardActions>
+        <CardAction
+          heading="Medium heading"
+          helperText="Default md size"
+          size="md"
+          onPress={() => console.log('pressed')}
+        />
+      </CardActions>
     </Card>
 
     <Card>
-      <CardAction
-        heading="Large heading"
-        helperText="Larger lg size"
-        size="lg"
-        onPress={() => console.log('pressed')}
-      />
+      <CardActions>
+        <CardAction
+          heading="Large heading"
+          helperText="Larger lg size"
+          size="lg"
+          onPress={() => console.log('pressed')}
+        />
+      </CardActions>
     </Card>
   </>
 );
@@ -285,6 +304,7 @@ For more complex layouts, you can use the component parts directly:
 import {
   Card,
   CardAction,
+  CardActions,
   CardActionLeadingContent,
   CardActionContent,
   CardActionText,
@@ -300,22 +320,160 @@ import {
 
 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>
+    <CardActions>
+      <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>
+    </CardActions>
+  </Card>
+);
+```
+
+#### `CardAction` Usage Patterns and Best Practices
+
+Understanding how `Card` detects and renders `CardAction` components will help you structure your code correctly.
+
+##### Using `CardActions`
+
+`CardAction` components must be wrapped in a `CardActions` container. Place `CardActions` as a
+direct child of `Card` to give the component a clear boundary for actions and remove heuristics.
+
+```tsx
+import { Card, CardAction, CardActions, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Card>
+    <BodyText>Card content here</BodyText>
+    <CardActions>
+      <CardAction heading="First Action" onPress={() => {}} />
+      <CardAction heading="Second Action" onPress={() => {}} />
+    </CardActions>
+  </Card>
+);
+```
+
+**Using `CardContent` wrapper (For complex mixed content):**
+
+```tsx
+import {
+  Card,
+  CardContent,
+  CardAction,
+  CardActions,
+  BodyText,
+  Heading,
+} from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Card>
+    <CardContent>
+      <Heading>Title</Heading>
+      <BodyText>Complex content that shouldn't be auto-wrapped</BodyText>
+    </CardContent>
+    <CardActions>
+      <CardAction heading="Action 1" onPress={() => {}} />
+      <CardAction heading="Action 2" onPress={() => {}} />
+    </CardActions>
   </Card>
 );
 ```
 
+##### How Card Detects Actions
+
+The `Card` component determines whether it contains only actions or mixed content using the following rules:
+
+- **Type comparison**: Directly checks if children include a `CardActions` container
+- **Action boundary**: Only `CardActions` is treated as the action block
+- **Automatic wrapping**: When mixing content and actions, non-action content is automatically wrapped in `CardContent`
+
+##### When to Use `CardContent`
+
+Use the explicit `CardContent` wrapper when:
+
+1. **Complex content structure**: You have multiple components and want precise control over what gets wrapped
+2. **Avoiding auto-wrap heuristics**: The automatic detection isn't working as expected for your use case
+3. **Nested components**: You have deeply nested content structures that might confuse the detection
+
+```tsx
+// Scenario: Complex nested structure with custom wrappers
+const MyComponent = () => (
+  <Card>
+    <CardContent>
+      <CustomHeader />
+      <CustomBody />
+      <CustomFooter />
+    </CardContent>
+    <CardAction heading="Learn More" onPress={() => {}} />
+  </Card>
+);
+```
+
+##### Mapped Actions Best Practices
+
+When mapping over data to create `CardAction` components:
+
+1. **Wrap actions in `CardActions`** for better organisation:
+
+```tsx
+const ActionItem = ({ item }) => (
+  <CardAction
+    heading={item.label}
+    helperText={item.description}
+    onPress={() => handlePress(item)}
+  />
+);
+
+<Card>
+  <CardActions>
+    {actions.map(action => (
+      <ActionItem key={action.id} item={action} />
+    ))}
+  </CardActions>
+</Card>;
+```
+
+2. **Keep action items simple** - avoid adding extra content alongside `CardAction` items:
+
+```tsx
+// ✅ Good: Simple action item
+const ActionItem = ({ label }) => <CardAction heading={label} onPress={() => {}} />;
+
+// ❌ Avoid: Adding extra content inside CardActions
+const ActionItem = ({ label }) => (
+  <View>
+    <Text>Extra content</Text>
+    <CardAction heading={label} onPress={() => {}} />
+  </View>
+);
+```
+
+3. **Mix mapped actions with direct actions when needed**:
+
+```tsx
+<Card>
+  <BodyText>Content</BodyText>
+  <CardActions>
+    {dynamicActions.map(action => (
+      <CardAction key={action.id} {...action} />
+    ))}
+    <CardAction heading="Static Action" onPress={() => {}} />
+  </CardActions>
+</Card>
+```
+
+##### First Action Styling
+
+The first rendered `CardAction` in a card automatically has no top border. This applies even when actions are wrapped in custom components, and follows render order to maintain visual consistency.
+
 #### `CardAction` Component Parts
 
 - `CardAction` - Main component wrapper

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

@@ -1,6 +1,6 @@
 import { Meta, StoryObj } from '@storybook/react-vite';
 import { BellMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
-import { Card, CardAction, CardPressHandler } from '.';
+import { Card, CardAction, CardActions, CardPressHandler } from '.';
 import { VariantTitle } from '../../../docs/components';
 import { BodyText } from '../BodyText';
 import { Button } from '../Button';
@@ -79,24 +79,26 @@ export const WithActions: Story = {
     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}
-        />
+        <CardActions>
+          <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}
+          />
+        </CardActions>
       </Card>
     );
   },
@@ -109,12 +111,14 @@ export const WithOnlyAction: Story = {
   render: ({ ...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}
-        />
+        <CardActions>
+          <CardAction
+            onPress={() => console.log('Card action pressed')}
+            heading="Card Action Head"
+            helperText="Some helper text"
+            leadingIcon={BellMediumIcon}
+          />
+        </CardActions>
       </Card>
     );
   },