@utilitywarehouse/hearth-react-native 0.4.2 → 0.6.0

package/src/components/List/ListAction/index.ts

@@ -0,0 +1,6 @@
+export { default as ListAction } from './ListAction';
+export type { default as ListActionProps } from './ListAction.props';
+export { default as ListActionContent } from './ListActionContent';
+export { default as ListActionText } from './ListActionText';
+export { default as ListActionTrailingContent } from './ListActionTrailingContent';
+export { default as ListActionTrailingIcon } from './ListActionTrailingIcon';

package/src/components/List/ListItem/ListItem.context.ts

@@ -1,7 +1,7 @@
 import { createContext, useContext } from 'react';
 import ListItemProps from './ListItem.props';
 
-export interface IListItemContext extends Pick<ListItemProps, 'divider' | 'loading' | 'disabled'> {
+export interface IListItemContext extends Pick<ListItemProps, 'loading' | 'disabled'> {
   showPressed?: boolean;
   active?: boolean;
 }

package/src/components/List/ListItem/ListItem.props.ts

@@ -1,9 +1,7 @@
 import type { PressableProps, ViewProps } from 'react-native';
-import type { ColorValue } from '../../../types';
+import BadgeProps from '../../Badge/Badge.props';
 
 interface ListItemBaseProps extends Omit<PressableProps, 'children'> {
-  divider?: boolean;
-  dividerColor?: ColorValue;
   loading?: boolean;
   disabled?: boolean;
   variant?: 'subtle' | 'emphasis';
@@ -12,18 +10,24 @@ interface ListItemBaseProps extends Omit<PressableProps, 'children'> {
 
 export interface ListItemWithChildren extends ListItemBaseProps {
   children: ViewProps['children'];
-  text?: never;
+  heading?: never;
   helperText?: never;
   leadingContent?: never;
   trailingContent?: never;
+  numericValue?: never;
+  badge?: never;
+  badgePosition?: never;
 }
 
 export interface ListItemWithoutChildren extends ListItemBaseProps {
   children?: never;
-  text: string;
+  heading: string;
   helperText?: string;
   leadingContent?: ViewProps['children'];
   trailingContent?: ViewProps['children'];
+  numericValue?: string | number;
+  badge?: BadgeProps;
+  badgePosition?: 'top' | 'bottom';
 }
 
 type ListItemProps = ListItemWithChildren | ListItemWithoutChildren;

package/src/components/List/ListItem/ListItemRoot.tsx

@@ -2,6 +2,8 @@ import { ChevronRightSmallIcon } from '@utilitywarehouse/hearth-react-native-ico
 import { useMemo } from 'react';
 import { Pressable, ViewStyle } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
+import { Badge } from '../../Badge';
+import { DetailText } from '../../DetailText';
 import { Skeleton } from '../../Skeleton';
 import { useListContext } from '../List.context';
 import { IListItemContext, ListItemContext } from './ListItem.context';
@@ -14,16 +16,18 @@ import ListItemTrailingContent from './ListItemTrailingContent';
 import ListItemTrailingIcon from './ListItemTrailingIcon';
 
 const ListItemRoot = ({
-  text,
+  heading,
   helperText,
   leadingContent,
   trailingContent,
   disabled,
-  divider,
   loading,
   children,
   states,
   variant = 'subtle',
+  badge,
+  badgePosition = 'bottom',
+  numericValue,
   ...props
 }: ListItemProps & { states?: { active?: boolean; disabled?: boolean } }) => {
   const { onPress } = props;
@@ -42,7 +46,6 @@ const ListItemRoot = ({
 
   const isLoading = loading || listContext?.loading;
   const showPressed = isLoading ? false : !!onPress;
-  const showDivider = listContext?.divider ?? divider;
   const isDisabled = disabled || listContext?.disabled || false;
   const listItemVariant = getListContainer() || variant;
 
@@ -50,7 +53,6 @@ const ListItemRoot = ({
   const loadingTestID = isLoading ? `${testID}-loading` : testID;
 
   styles.useVariants({
-    divider: showDivider,
     variant: listItemVariant,
     showPressed,
     active,
@@ -63,12 +65,11 @@ const ListItemRoot = ({
   const value: IListItemContext = useMemo(() => {
     return {
       showPressed,
-      divider: showDivider,
       active,
       loading: isLoading,
       disabled: isDisabled,
     };
-  }, [active, showPressed, showDivider, isLoading, isDisabled]);
+  }, [active, showPressed, isLoading, isDisabled]);
 
   if (loading || listContext?.loading) {
     return (
@@ -95,6 +96,7 @@ const ListItemRoot = ({
         testID={testID}
         style={[styles.container, props.style as ViewStyle]}
         disabled={isDisabled}
+        accessibilityRole={onPress ? 'button' : undefined}
       >
         {children ? (
           children
@@ -104,13 +106,16 @@ const ListItemRoot = ({
               <ListItemLeadingContent>{leadingContent}</ListItemLeadingContent>
             ) : null}
             <ListItemContent>
-              <ListItemText>{text}</ListItemText>
+              {badgePosition === 'top' && badge ? <Badge {...badge} /> : null}
+              <ListItemText>{heading}</ListItemText>
               {helperText ? <ListItemHelperText>{helperText}</ListItemHelperText> : null}
+              {badgePosition === 'bottom' && badge ? <Badge {...badge} /> : null}
             </ListItemContent>
+            {!!numericValue && <DetailText size="lg">{numericValue}</DetailText>}
             {trailingContent ? (
               <ListItemTrailingContent>{trailingContent}</ListItemTrailingContent>
             ) : onPress ? (
-              <ListItemTrailingContent>
+              <ListItemTrailingContent style={styles.centeredTrailingIcon}>
                 <ListItemTrailingIcon as={ChevronRightSmallIcon} />
               </ListItemTrailingContent>
             ) : null}
@@ -129,13 +134,9 @@ const styles = StyleSheet.create(theme => ({
     paddingHorizontal: theme.components.list.item.functional.padding,
     flexDirection: 'row',
     gap: theme.components.list.item.gap,
+    borderTopWidth: theme.borderWidth['1'],
+    borderStyle: 'solid',
     variants: {
-      divider: {
-        true: {
-          borderTopWidth: theme.borderWidth['1'],
-          borderStyle: 'solid',
-        },
-      },
       isFirstChild: {
         true: {
           borderTopWidth: 0,
@@ -197,6 +198,9 @@ const styles = StyleSheet.create(theme => ({
       },
     ],
   },
+  centeredTrailingIcon: {
+    justifyContent: 'center',
+  },
 }));
 
 export default ListItemRoot;

package/src/components/List/ListItem/index.ts

@@ -1,9 +1,9 @@
 export { default as ListItem } from './ListItem';
-export { default as ListItemIcon } from './ListItemIcon';
-export { default as ListItemContent } from './ListItemContent';
 export type { default as ListItemProps } from './ListItem.props';
+export { default as ListItemContent } from './ListItemContent';
+export { default as ListItemHelperText } from './ListItemHelperText';
+export { default as ListItemIcon } from './ListItemIcon';
 export { default as ListItemLeadingContent } from './ListItemLeadingContent';
+export { default as ListItemText } from './ListItemText';
 export { default as ListItemTrailingContent } from './ListItemTrailingContent';
 export { default as ListItemTrailingIcon } from './ListItemTrailingIcon';
-export { default as ListItemHelperText } from './ListItemHelperText';
-export { default as ListItemText } from './ListItemText';

package/src/components/List/index.ts

@@ -1,3 +1,4 @@
 export { default as List } from './List';
 export { useListContext } from './List.context';
+export * from './ListAction';
 export * from './ListItem';

package/src/components/ProgressStepper/ProgressStep.tsx

@@ -0,0 +1,134 @@
+import React from 'react';
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { Icon } from '../Icon';
+import { BodyText } from '../BodyText';
+import { ProgressStepProps } from './ProgressStepper.props';
+
+interface ProgressStepInternalProps extends ProgressStepProps {
+  index?: number;
+  isLast?: boolean;
+}
+
+const ProgressStep = ({ status, index = 0, isLast = false, ...rest }: ProgressStepInternalProps) => {
+  styles.useVariants({ status, isLast });
+
+  const renderStepNumber = () => {
+    return (
+      <BodyText size="md" weight="semibold" style={styles.text}>
+        {index + 1}
+      </BodyText>
+    );
+  };
+
+  return (
+    <View
+      style={styles.container}
+      accessible
+      aria-label={`Step ${index + 1}, ${rest.id}, ${status}`}
+      {...rest}
+    >
+      <View style={styles.step}>
+        {status === 'complete' ? (
+          <Icon as={TickSmallIcon} width={20} height={20} style={styles.text} />
+        ) : status === 'active' ? (
+          <View style={styles.inner}>{renderStepNumber()}</View>
+        ) : (
+          renderStepNumber()
+        )}
+      </View>
+      {!isLast && <View style={styles.connector} />}
+    </View>
+  );
+};
+
+ProgressStep.displayName = 'ProgressStep';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    variants: {
+      isLast: {
+        true: {
+          flex: 0,
+          _web: {
+            flex: 'none',
+          },
+        },
+        false: {
+          flex: 1,
+        },
+      },
+    },
+  },
+  step: {
+    width: theme.components.progressStepper.indicator.width,
+    height: theme.components.progressStepper.indicator.height,
+    borderRadius: theme.borderRadius.full,
+    alignItems: 'center',
+    justifyContent: 'center',
+    variants: {
+      status: {
+        complete: {
+          backgroundColor: theme.color.surface.brand.default,
+        },
+        active: {
+          backgroundColor: theme.color.surface.brand.default,
+          padding: theme.borderWidth[2],
+        },
+        incomplete: {
+          borderWidth: theme.components.progressStepper.indicator.future.borderWidth,
+          borderColor: theme.color.border.subtle,
+        },
+      },
+    },
+  },
+  inner: {
+    width: theme.components.progressStepper.indicator.width - theme.borderWidth[2] * 2,
+    height: theme.components.progressStepper.indicator.height - theme.borderWidth[2] * 2,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.color.surface.brand.default,
+    borderWidth: theme.borderWidth[2],
+    borderColor: theme.color.surface.neutral.subtle,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  text: {
+    variants: {
+      status: {
+        complete: {
+          color: theme.color.text.inverted,
+        },
+        active: {
+          color: theme.color.text.inverted,
+          // NOTE: Adjust lineHeight to vertically center the text within the smaller inner circle
+          lineHeight: theme.lineHeight[500] - theme.borderWidth[2] * 2,
+        },
+        incomplete: {
+          color: theme.color.text.primary,
+        },
+      },
+    },
+  },
+  connector: {
+    flex: 1,
+    height: theme.components.progressStepper.bar.height,
+    variants: {
+      status: {
+        complete: {
+          backgroundColor: theme.components.progressStepper.bar.complete.backgroundColor,
+        },
+        active: {
+          backgroundColor: theme.color.border.subtle,
+        },
+        incomplete: {
+          backgroundColor: theme.color.border.subtle,
+        },
+      },
+    },
+  },
+}));
+
+export default ProgressStep;

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

@@ -0,0 +1,87 @@
+import { Canvas, Meta } from '@storybook/addon-docs/blocks';
+import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
+import * as ProgressStepperStories from './ProgressStepper.stories';
+
+<Meta title="Components / Progress Stepper" />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6056-1987" />
+
+<BackToTopButton />
+
+# Progress Stepper
+
+A form helper component that displays a series of dots connected by lines, showing the progress through a multi-step process. Each step can be marked as completed, active, or uncompleted.
+
+- [Usage](#usage)
+- [Examples](#examples)
+- [API](#api)
+- [Step Statuses](#step-statuses-1)
+- [Accessibility](#accessibility)
+- [Best Practices](#best-practices)
+
+## Usage
+
+The `ProgressStepper` component uses a compound component pattern, making it easy to define steps declaratively. It provides visual feedback about complete steps, the current active step, and remaining incomplete steps.
+
+### Basic Usage
+
+```tsx
+import { ProgressStepper, ProgressStep } from '@hearth/react-native';
+
+<ProgressStepper>
+  <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>
+```
+
+## Examples
+
+### Default Layout
+
+<Canvas of={ProgressStepperStories.Playground} />
+
+### Step Statuses
+
+See how different step statuses are visualized:
+
+<Canvas of={ProgressStepperStories.StepStatuses} />
+
+### Basic
+
+<Canvas of={ProgressStepperStories.BasicExample} />
+
+## API
+
+### Progress Stepper Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | Required | `ProgressStep` components |
+
+### Progress Step Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | Required | Unique identifier for the step |
+| `status` | `'complete' \| 'active' \| 'incomplete'` | Required | Current status of the step |
+
+## Step Statuses
+
+- **complete**: Step has been finished, shows a checkmark icon
+- **active**: Current step, shows a number with highlighted background
+- **incomplete**: Future step, shows a number with muted styling
+
+## Accessibility
+
+- Each step is properly labeled for screen readers
+- The component follows WCAG guidelines for color contrast
+- Progress indication is communicated through both visual and textual means
+
+## Best Practices
+
+1. **Keep it simple** - The stepper focuses on essential functionality without complexity
+1. **Indicate progress clearly** - Make sure users understand how many steps remain
+1. **Use meaningful IDs** - Choose IDs that make sense for your specific use case (numbers, step names, etc.)

package/src/components/ProgressStepper/ProgressStepper.props.ts

@@ -0,0 +1,27 @@
+import { ViewProps } from 'react-native';
+
+export type StepStatus = 'complete' | 'active' | 'incomplete';
+
+export interface ProgressStepperProps extends ViewProps {
+  /**
+   * Child ProgressStep components
+   */
+  children: React.ReactNode;
+}
+
+export interface ProgressStepProps extends ViewProps {
+  /**
+   * Unique identifier for the step
+   */
+  id: string;
+  /**
+   * Current status of the step
+   */
+  status: StepStatus;
+}
+
+export interface ProgressStepperRootProps extends ViewProps {
+  children: React.ReactNode;
+}
+
+export default ProgressStepperProps;

package/src/components/ProgressStepper/ProgressStepper.stories.tsx

@@ -0,0 +1,108 @@
+import React from 'react';
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { ProgressStepper, ProgressStep } from '.';
+import { VariantTitle } from '../../../docs/components';
+import { BodyText } from '../BodyText';
+import { Flex } from '../Flex';
+import { Heading } from '../Heading';
+
+const meta = {
+  title: 'Stories / ProgressStepper',
+  component: ProgressStepper,
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof ProgressStepper>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    children: (
+      <Flex space="xl" direction="column" align="center" style={{ flex: 1, minWidth: 200 }}>
+        <ProgressStepper>
+          <ProgressStep id={'1'} status="complete" />
+          <ProgressStep id={'2'} status="complete" />
+          <ProgressStep id={'3'} status="active" />
+          <ProgressStep id={'4'} status="incomplete" />
+        </ProgressStepper>
+        <Flex direction="row" space="lg" style={{ width: '100%' }}>
+          <ProgressStep id={'1'} status="complete" />
+        </Flex>
+        <Flex direction="row" space="lg" style={{ width: '100%' }}>
+          <ProgressStep id={'3'} status="active" />
+        </Flex>
+        <Flex direction="row" space="lg" style={{ width: '100%' }}>
+          <ProgressStep id={'5'} status="incomplete" />
+        </Flex>
+      </Flex>
+    ),
+  },
+};
+
+export const StepStatuses: Story = {
+  args: {
+    children: <></>,
+  },
+  parameters: {
+    controls: { exclude: ['space'] },
+  },
+  render: props => {
+    return (
+      <Flex space="xl" direction="column" align="center">
+        <VariantTitle title="All Uncompleted Steps">
+          <ProgressStepper {...props}>
+            <ProgressStep id={'1'} status="incomplete" />
+            <ProgressStep id={'2'} status="incomplete" />
+            <ProgressStep id={'3'} status="incomplete" />
+          </ProgressStepper>
+        </VariantTitle>
+        <VariantTitle title="One Active Step">
+          <ProgressStepper {...props}>
+            <ProgressStep id={'1'} status="active" />
+            <ProgressStep id={'2'} status="incomplete" />
+            <ProgressStep id={'3'} status="incomplete" />
+          </ProgressStepper>
+        </VariantTitle>
+        <VariantTitle title="Mixed Statuses">
+          <ProgressStepper {...props}>
+            <ProgressStep id={'1'} status="complete" />
+            <ProgressStep id={'2'} status="complete" />
+            <ProgressStep id={'3'} status="active" />
+            <ProgressStep id={'4'} status="incomplete" />
+          </ProgressStepper>
+        </VariantTitle>
+        <VariantTitle title="All Completed">
+          <ProgressStepper {...props}>
+            <ProgressStep id={'1'} status="complete" />
+            <ProgressStep id={'2'} status="complete" />
+            <ProgressStep id={'3'} status="complete" />
+          </ProgressStepper>
+        </VariantTitle>
+      </Flex>
+    );
+  },
+};
+
+export const BasicExample: Story = {
+  args: {
+    children: <></>,
+  },
+  render: props => {
+    return (
+      <Flex space="lg" direction="column" align="center">
+        <Heading size="md">Progress Stepper</Heading>
+        <BodyText>Shows progress through multi-step processes</BodyText>
+        <ProgressStepper {...props}>
+          <ProgressStep id="services-data" status="complete" />
+          <ProgressStep id="customer-data" status="complete" />
+          <ProgressStep id="shipping-data" status="active" />
+          <ProgressStep id="payment-data" status="incomplete" />
+          <ProgressStep id="summary" status="incomplete" />
+        </ProgressStepper>
+        <BodyText>Step 3 of 5</BodyText>
+      </Flex>
+    );
+  },
+};

package/src/components/ProgressStepper/ProgressStepper.tsx

@@ -0,0 +1,26 @@
+import React, { useMemo, Children, cloneElement, isValidElement } from 'react';
+import ProgressStepperProps from './ProgressStepper.props';
+import ProgressStepperRoot from './ProgressStepperRoot';
+
+const ProgressStepper = ({ children, ...rest }: ProgressStepperProps) => {
+  // Process children to add index and isLast props
+  const processedChildren = useMemo(() => {
+    const childrenArray = Children.toArray(children);
+    return childrenArray.map((child, index) => {
+      if (isValidElement(child)) {
+        return cloneElement(child, {
+          ...(child.props as any),
+          index,
+          isLast: index === childrenArray.length - 1,
+        });
+      }
+      return child;
+    });
+  }, [children]);
+
+  return <ProgressStepperRoot {...rest}>{processedChildren}</ProgressStepperRoot>;
+};
+
+ProgressStepper.displayName = 'ProgressStepper';
+
+export default ProgressStepper;

package/src/components/ProgressStepper/ProgressStepperRoot.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { View, ViewStyle } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { ProgressStepperRootProps } from './ProgressStepper.props';
+
+const ProgressStepperRoot = ({
+  children,
+  style,
+  ...rest
+}: ProgressStepperRootProps) => {
+  return (
+    <View
+      style={[styles.root, style as ViewStyle]}
+      {...rest}
+    >
+      {children}
+    </View>
+  );
+};
+
+ProgressStepperRoot.displayName = 'ProgressStepperRoot';
+
+const styles = StyleSheet.create(() => ({
+  root: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    width: '100%',
+  },
+}));
+
+export default ProgressStepperRoot;

package/src/components/ProgressStepper/index.ts

@@ -0,0 +1,3 @@
+export { default as ProgressStepper } from './ProgressStepper';
+export { default as ProgressStep } from './ProgressStep';
+export type { ProgressStepperProps, ProgressStepProps, StepStatus } from './ProgressStepper.props';

package/src/components/SectionHeader/SectionHeader.props.ts

@@ -1,5 +1,6 @@
-import { ComponentType, Ref } from 'react';
-import type { ViewProps, View } from 'react-native';
+import { Ref } from 'react';
+import type { View, ViewProps } from 'react-native';
+import BadgeProps from '../Badge/Badge.props';
 
 interface SectionHeaderBaseProps extends Omit<ViewProps, 'children'> {
   ref?: Ref<View>;
@@ -9,26 +10,18 @@ export interface SectionHeaderWithChildren extends SectionHeaderBaseProps {
   children: ViewProps['children'];
   heading?: never;
   helperText?: never;
-  linkText?: never;
-  linkHref?: never;
-  linkOnPress?: never;
-  linkTarget?: never;
-  linkIcon?: never;
-  linkIconPosition?: never;
-  linkShowIcon?: never;
+  trailingContent?: never;
+  badge?: never;
+  invalidText?: never;
 }
 
 export interface SectionHeaderWithoutChildren extends SectionHeaderBaseProps {
   children?: never;
   heading: string;
   helperText?: string;
-  linkText?: string;
-  linkHref?: string;
-  linkOnPress?: () => void;
-  linkTarget?: '_blank' | '_self' | '_parent' | '_top';
-  linkIcon?: ComponentType;
-  linkIconPosition?: 'left' | 'right';
-  linkShowIcon?: boolean;
+  trailingContent?: React.ReactNode;
+  badge?: BadgeProps;
+  invalidText?: string;
 }
 
 type SectionHeaderProps = SectionHeaderWithChildren | SectionHeaderWithoutChildren;