@utilitywarehouse/hearth-react-native 0.5.0 → 0.6.0

package/src/components/Container/Container.docs.mdx

@@ -0,0 +1,168 @@
+import { Canvas, Controls, Meta, Primary, Story } from '@storybook/addon-docs/blocks';
+import { BodyText, Box, Container } from '../..';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Container.stories';
+
+<Meta title="Primitives / Container" />
+
+<BackToTopButton />
+
+# Container
+
+The Container component is a layout primitive that provides consistent spacing and structure using the design system's layout tokens. It automatically applies responsive margin and padding based on the current breakpoint, and supports additional customization through spacing props.
+
+- [Playground](#playground)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [With Custom Padding](#with-custom-padding)
+  - [With Custom Margin](#with-custom-margin)
+  - [With Custom Spacing](#with-custom-spacing)
+- [Props](#props)
+- [Design Tokens](#design-tokens)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+### Basic Usage
+
+The Container component uses layout tokens automatically for responsive spacing:
+
+<UsageWrap>
+  <Container backgroundColor="backgroundSecondary">
+    <Box bg="blue400" p="200" borderRadius="md">
+      <BodyText>Container content</BodyText>
+    </Box>
+  </Container>
+</UsageWrap>
+
+```jsx
+import { Container, Box, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Container>
+    <Box bg="cyan400" p="200" borderRadius="md">
+      <BodyText>Container content</BodyText>
+    </Box>
+  </Container>
+);
+```
+
+### With Custom Padding
+
+You can override the default padding with custom values using space tokens:
+
+<Canvas of={Stories.WithPadding} />
+
+```jsx
+import { Container, Box, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Container padding="300">
+    <Box bg="cyan400" p="200" borderRadius="md">
+      <BodyText>Container with padding</BodyText>
+    </Box>
+  </Container>
+);
+```
+
+### With Custom Margin
+
+You can override the default margin with custom values using space tokens:
+
+<Canvas of={Stories.WithMargin} />
+
+```jsx
+import { Container, Box, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Container margin="300">
+    <Box bg="cyan400" p="200" borderRadius="md">
+      <BodyText>Container with margin</BodyText>
+    </Box>
+  </Container>
+);
+```
+
+### With Custom Spacing
+
+The Container component supports a `space` prop for controlling gap between child elements, as well as directional padding and margin props:
+
+<Canvas of={Stories.WithCustomSpacing} />
+
+```jsx
+import { Container, Box, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Container space="xl" paddingHorizontal="200" paddingVertical="300">
+    <Box bg="cyan400" p="200" borderRadius="md">
+      <BodyText>Item 1</BodyText>
+    </Box>
+    <Box bg="purple400" p="200" borderRadius="md">
+      <BodyText>Item 2</BodyText>
+    </Box>
+    <Box bg="pink400" p="200" borderRadius="md">
+      <BodyText>Item 3</BodyText>
+    </Box>
+  </Container>
+);
+```
+
+## Props
+
+The Container component supports spacing props similar to the Box component, with both long-form and shorthand syntax:
+
+### Spacing Props
+
+| Name                | Shorthand | Type         | Default | Description                              |
+| ------------------- | --------- | ------------ | ------- | ---------------------------------------- |
+| `padding`           | `p`       | `SpaceValue` | -       | The padding of the container.            |
+| `paddingHorizontal` | `px`      | `SpaceValue` | -       | The horizontal padding of the container. |
+| `paddingVertical`   | `py`      | `SpaceValue` | -       | The vertical padding of the container.   |
+| `paddingTop`        | `pt`      | `SpaceValue` | -       | The top padding of the container.        |
+| `paddingBottom`     | `pb`      | `SpaceValue` | -       | The bottom padding of the container.     |
+| `paddingLeft`       | `pl`      | `SpaceValue` | -       | The left padding of the container.       |
+| `paddingRight`      | `pr`      | `SpaceValue` | -       | The right padding of the container.      |
+| `margin`            | `m`       | `SpaceValue` | -       | The margin of the container.             |
+| `marginHorizontal`  | `mx`      | `SpaceValue` | -       | The horizontal margin of the container.  |
+| `marginVertical`    | `my`      | `SpaceValue` | -       | The vertical margin of the container.    |
+| `marginTop`         | `mt`      | `SpaceValue` | -       | The top margin of the container.         |
+| `marginBottom`      | `mb`      | `SpaceValue` | -       | The bottom margin of the container.      |
+| `marginLeft`        | `ml`      | `SpaceValue` | -       | The left margin of the container.        |
+| `marginRight`       | `mr`      | `SpaceValue` | -       | The right margin of the container.       |
+
+## Design Tokens
+
+The Container component uses the following layout tokens from the design system:
+
+### Mobile (320px - 740px)
+
+- **Margin Horizontal**: 16px
+- **Padding Top**: 24px
+- **Padding Bottom**: 32px
+
+### Tablet (740px - 992px)
+
+- **Margin Horizontal**: 32px
+- **Padding Top**: 24px
+- **Padding Bottom**: 32px
+
+### Desktop (992px+)
+
+- **Margin Horizontal**: 32px
+- **Padding Top**: 32px
+- **Padding Bottom**: 48px
+
+These values are automatically applied based on the current breakpoint. You can override them using the padding and margin props.
+
+### Space Tokens
+
+For the `padding`, `margin`, and directional spacing props, you can use any of the following space token values:
+
+`'0'`, `'25'`, `'50'`, `'75'`, `'100'`, `'150'`, `'175'`, `'200'`, `'250'`, `'300'`, `'350'`, `'400'`, `'500'`, `'600'`, `'700'`, `'800'`, `'900'`, `'1000'`
+
+These correspond to pixel values: 0px, 2px, 4px, 6px, 8px, 12px, 14px, 16px, 20px, 24px, 28px, 32px, 40px, 48px, 56px, 64px, 72px, 80px respectively.

package/src/components/Container/Container.props.ts

@@ -0,0 +1,89 @@
+import type { ViewProps } from 'react-native';
+import { SpaceValue, SpacingValues } from '../../types';
+
+interface ContainerProps extends ViewProps {
+  /**
+   * The padding of the container.
+   */
+  padding?: SpaceValue;
+  /**
+   * The horizontal padding of the container.
+   */
+  paddingHorizontal?: SpaceValue;
+  /**
+   * The vertical padding of the container.
+   */
+  paddingVertical?: SpaceValue;
+  /**
+   * The top padding of the container.
+   */
+  paddingTop?: SpaceValue;
+  /**
+   * The bottom padding of the container.
+   */
+  paddingBottom?: SpaceValue;
+  /**
+   * The left padding of the container.
+   */
+  paddingLeft?: SpaceValue;
+  /**
+   * The right padding of the container.
+   */
+  paddingRight?: SpaceValue;
+  /**
+   * The margin of the container.
+   */
+  margin?: SpaceValue;
+  /**
+   * The horizontal margin of the container.
+   */
+  marginHorizontal?: SpaceValue;
+  /**
+   * The vertical margin of the container.
+   */
+  marginVertical?: SpaceValue;
+  /**
+   * The top margin of the container.
+   */
+  marginTop?: SpaceValue;
+  /**
+   * The bottom margin of the container.
+   */
+  marginBottom?: SpaceValue;
+  /**
+   * The left margin of the container.
+   */
+  marginLeft?: SpaceValue;
+  /**
+   * The right margin of the container.
+   */
+  marginRight?: SpaceValue;
+  // Padding
+  p?: SpaceValue;
+  px?: SpaceValue;
+  py?: SpaceValue;
+  pt?: SpaceValue;
+  pb?: SpaceValue;
+  pl?: SpaceValue;
+  pr?: SpaceValue;
+  // Margin
+  m?: SpaceValue;
+  mx?: SpaceValue;
+  my?: SpaceValue;
+  mt?: SpaceValue;
+  mb?: SpaceValue;
+  ml?: SpaceValue;
+  mr?: SpaceValue;
+  /**
+   * The space between child elements (gap).
+   */
+  space?: SpacingValues;
+  /**
+   * The space between child elements.
+   */
+  gap?: SpaceValue;
+  backgroundColor?: 'backgroundBrand' | 'backgroundPrimary' | 'backgroundSecondary' | 'transparent';
+  bg?: 'backgroundBrand' | 'backgroundPrimary' | 'backgroundSecondary' | 'transparent';
+}
+
+export default ContainerProps;

package/src/components/Container/Container.stories.tsx

@@ -0,0 +1,274 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { Container } from '.';
+import { lightTheme } from '../../core/themes';
+import { BodyText } from '../BodyText';
+import { Box } from '../Box';
+
+// More on how to set up stories at: https://storybook.js.org/docs/writing-stories#default-export
+const meta = {
+  title: 'Stories / Container',
+  component: Container,
+  parameters: {
+    // Optional parameter to center the component in the Canvas. More info: https://storybook.js.org/docs/configure/story-layout
+    layout: 'fullscreen',
+  },
+  // More on argTypes: https://storybook.js.org/docs/api/argtypes
+  argTypes: {
+    padding: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The padding of the container.',
+    },
+    p: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The padding of the container.',
+    },
+    paddingHorizontal: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The horizontal padding of the container.',
+    },
+    px: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The horizontal padding of the container.',
+    },
+    paddingVertical: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The vertical padding of the container.',
+    },
+    py: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The vertical padding of the container.',
+    },
+    paddingTop: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The top padding of the container.',
+    },
+    pt: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The top padding of the container.',
+    },
+    paddingBottom: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The bottom padding of the container.',
+    },
+    pb: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The bottom padding of the container.',
+    },
+    paddingLeft: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The left padding of the container.',
+    },
+    pl: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The left padding of the container.',
+    },
+    paddingRight: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The right padding of the container.',
+    },
+    pr: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The right padding of the container.',
+    },
+    margin: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The margin of the container.',
+    },
+    m: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The margin of the container.',
+    },
+    marginHorizontal: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The horizontal margin of the container.',
+    },
+    mx: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The horizontal margin of the container.',
+    },
+    marginVertical: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The vertical margin of the container.',
+    },
+    my: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The vertical margin of the container.',
+    },
+    marginTop: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The top margin of the container.',
+    },
+    mt: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The top margin of the container.',
+    },
+    marginBottom: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The bottom margin of the container.',
+    },
+    mb: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The bottom margin of the container.',
+    },
+    marginLeft: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The left margin of the container.',
+    },
+    ml: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The left margin of the container.',
+    },
+    marginRight: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The right margin of the container.',
+    },
+    mr: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The right margin of the container.',
+    },
+    space: {
+      options: ['none', '2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'],
+      control: 'radio',
+      description: 'The space between child elements (gap).',
+    },
+    gap: {
+      options: Object.keys(lightTheme.space),
+      control: 'select',
+      description: 'The space between child elements.',
+    },
+    backgroundColor: {
+      options: ['backgroundBrand', 'backgroundPrimary', 'backgroundSecondary', 'transparent'],
+      control: 'select',
+      description: 'The background color of the container.',
+    },
+    bg: {
+      options: ['backgroundBrand', 'backgroundPrimary', 'backgroundSecondary', 'transparent'],
+      control: 'select',
+      description: 'The background color of the container.',
+    },
+  },
+  // Use `fn` to spy on the onClick arg, which will appear in the actions panel once invoked: https://storybook.js.org/docs/essentials/actions#action-args
+  args: {
+    space: 'md',
+  },
+} satisfies Meta<typeof Container>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: args => (
+    <Box backgroundColor="red100">
+      <Container {...args} backgroundColor="backgroundSecondary">
+        <Box bg="blue400" p="200" borderRadius="md">
+          <BodyText>Container content 1</BodyText>
+        </Box>
+        <Box bg="purple400" p="200" borderRadius="md">
+          <BodyText>Container content 2</BodyText>
+        </Box>
+        <Box bg="piggyPink400" p="200" borderRadius="md">
+          <BodyText>Container content 3</BodyText>
+        </Box>
+      </Container>
+    </Box>
+  ),
+};
+
+export const WithPadding: Story = {
+  args: {
+    padding: '300',
+  },
+  render: args => (
+    <Box backgroundColor="red100">
+      <Container {...args} backgroundColor="backgroundSecondary">
+        <Box bg="blue400" p="200" borderRadius="md">
+          <BodyText>Container with padding</BodyText>
+        </Box>
+      </Container>
+    </Box>
+  ),
+};
+
+export const WithMargin: Story = {
+  args: {
+    margin: '300',
+  },
+  render: args => (
+    <Box backgroundColor="red100">
+      <Container {...args} backgroundColor="backgroundSecondary">
+        <Box bg="blue400" p="200" borderRadius="md">
+          <BodyText>Container with margin</BodyText>
+        </Box>
+      </Container>
+    </Box>
+  ),
+};
+
+export const WithCustomSpacing: Story = {
+  args: {
+    space: 'xl',
+    paddingHorizontal: '200',
+    paddingVertical: '300',
+  },
+  render: args => (
+    <Box backgroundColor="red100">
+      <Container {...args} backgroundColor="backgroundSecondary">
+        <Box bg="blue400" p="200" borderRadius="md">
+          <BodyText>Item 1</BodyText>
+        </Box>
+        <Box bg="purple400" p="200" borderRadius="md">
+          <BodyText>Item 2</BodyText>
+        </Box>
+        <Box bg="piggyPink400" p="200" borderRadius="md">
+          <BodyText>Item 3</BodyText>
+        </Box>
+        <Box bg="orange400" p="200" borderRadius="md">
+          <BodyText>Item 4</BodyText>
+        </Box>
+      </Container>
+    </Box>
+  ),
+};
+
+export const LayoutTokens: Story = {
+  render: () => (
+    <Box backgroundColor="red100">
+      <Container backgroundColor="backgroundSecondary">
+        <Box bg="blue100" p="200" borderRadius="md">
+          <BodyText>
+            This Container uses the responsive layout tokens from the design system. It will
+            automatically adjust margin and padding based on the current breakpoint.
+          </BodyText>
+        </Box>
+      </Container>
+    </Box>
+  ),
+};

package/src/components/Container/Container.tsx

@@ -0,0 +1,52 @@
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { useStyleProps } from '../../hooks';
+import type ContainerProps from './Container.props';
+
+const Container = ({ style, children, space = 'md', ...props }: ContainerProps) => {
+  const { computedStyles, remainingProps } = useStyleProps(props);
+
+  styles.useVariants({ space });
+  return (
+    <View style={[styles.container(computedStyles), style]} {...remainingProps}>
+      {children}
+    </View>
+  );
+};
+
+Container.displayName = 'Container';
+
+const styles = StyleSheet.create(theme => ({
+  container: extra => ({
+    paddingTop:
+      typeof extra.padding === 'undefined' && typeof extra.paddingVertical === 'undefined'
+        ? {
+            base: theme.layout.mobile.container.paddingTop,
+            md: theme.layout.tablet.container.paddingTop,
+            lg: theme.layout.desktop.container.paddingTop,
+          }
+        : undefined,
+    paddingBottom:
+      typeof extra.padding === 'undefined' && typeof extra.paddingVertical === 'undefined'
+        ? {
+            base: theme.layout.mobile.container.paddingBottom,
+            md: theme.layout.tablet.container.paddingBottom,
+            lg: theme.layout.desktop.container.paddingBottom,
+          }
+        : undefined,
+    marginHorizontal:
+      typeof extra.margin === 'undefined' && typeof extra.marginHorizontal === 'undefined'
+        ? {
+            base: theme.layout.mobile.container.margin,
+            md: theme.layout.tablet.container.margin,
+            lg: theme.layout.desktop.container.margin,
+          }
+        : undefined,
+    ...extra,
+    variants: {
+      space: theme.globalStyle.variants.space,
+    },
+  }),
+}));
+
+export default Container;

package/src/components/Container/index.tsx

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

package/src/components/ProgressStepper/ProgressStep.tsx

@@ -11,8 +11,8 @@ interface ProgressStepInternalProps extends ProgressStepProps {
   isLast?: boolean;
 }
 
-const ProgressStep = ({ state, index = 0, isLast = false, ...rest }: ProgressStepInternalProps) => {
-  styles.useVariants({ state, isLast });
+const ProgressStep = ({ status, index = 0, isLast = false, ...rest }: ProgressStepInternalProps) => {
+  styles.useVariants({ status, isLast });
 
   const renderStepNumber = () => {
     return (
@@ -26,13 +26,13 @@ const ProgressStep = ({ state, index = 0, isLast = false, ...rest }: ProgressSte
     <View
       style={styles.container}
       accessible
-      aria-label={`Step ${index + 1}, ${rest.id}, ${state}`}
+      aria-label={`Step ${index + 1}, ${rest.id}, ${status}`}
       {...rest}
     >
       <View style={styles.step}>
-        {state === 'complete' ? (
+        {status === 'complete' ? (
           <Icon as={TickSmallIcon} width={20} height={20} style={styles.text} />
-        ) : state === 'active' ? (
+        ) : status === 'active' ? (
           <View style={styles.inner}>{renderStepNumber()}</View>
         ) : (
           renderStepNumber()
@@ -70,7 +70,7 @@ const styles = StyleSheet.create(theme => ({
     alignItems: 'center',
     justifyContent: 'center',
     variants: {
-      state: {
+      status: {
         complete: {
           backgroundColor: theme.color.surface.brand.default,
         },
@@ -97,7 +97,7 @@ const styles = StyleSheet.create(theme => ({
   },
   text: {
     variants: {
-      state: {
+      status: {
         complete: {
           color: theme.color.text.inverted,
         },
@@ -116,7 +116,7 @@ const styles = StyleSheet.create(theme => ({
     flex: 1,
     height: theme.components.progressStepper.bar.height,
     variants: {
-      state: {
+      status: {
         complete: {
           backgroundColor: theme.components.progressStepper.bar.complete.backgroundColor,
         },

package/src/components/ProgressStepper/ProgressStepper.docs.mdx

@@ -15,7 +15,7 @@ A form helper component that displays a series of dots connected by lines, showi
 - [Usage](#usage)
 - [Examples](#examples)
 - [API](#api)
-- [Step States](#step-states-1)
+- [Step Statuses](#step-statuses-1)
 - [Accessibility](#accessibility)
 - [Best Practices](#best-practices)
 
@@ -29,11 +29,11 @@ The `ProgressStepper` component uses a compound component pattern, making it eas
 import { ProgressStepper, ProgressStep } from '@hearth/react-native';
 
 <ProgressStepper>
-  <ProgressStep id={"1"} state="complete" />
-  <ProgressStep id={"2"} state="complete" />
-  <ProgressStep id={"3"} state="active" />
-  <ProgressStep id={"4"} state="incomplete" />
-  <ProgressStep id={"5"} state="incomplete" />
+  <ProgressStep id={"1"} status="complete" />
+  <ProgressStep id={"2"} status="complete" />
+  <ProgressStep id={"3"} status="active" />
+  <ProgressStep id={"4"} status="incomplete" />
+  <ProgressStep id={"5"} status="incomplete" />
 </ProgressStepper>
 ```
 
@@ -43,11 +43,11 @@ import { ProgressStepper, ProgressStep } from '@hearth/react-native';
 
 <Canvas of={ProgressStepperStories.Playground} />
 
-### Step States
+### Step Statuses
 
-See how different step states are visualized:
+See how different step statuses are visualized:
 
-<Canvas of={ProgressStepperStories.StepStates} />
+<Canvas of={ProgressStepperStories.StepStatuses} />
 
 ### Basic
 
@@ -66,9 +66,9 @@ See how different step states are visualized:
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `id` | `string` | Required | Unique identifier for the step |
-| `state` | `'complete' \| 'active' \| 'incomplete'` | Required | Current state of the step |
+| `status` | `'complete' \| 'active' \| 'incomplete'` | Required | Current status of the step |
 
-## Step States
+## Step Statuses
 
 - **complete**: Step has been finished, shows a checkmark icon
 - **active**: Current step, shows a number with highlighted background