@utilitywarehouse/hearth-react-native 0.23.0 → 0.24.0

package/src/components/Modal/Modal.tsx

@@ -59,6 +59,7 @@ const Modal = ({
   const theme = useTheme();
   const backgroundOpacity = useSharedValue(0);
   const pretendContentTranslateY = useSharedValue(20);
+  const isBrandBackground = background === 'brand';
 
   const triggerCloseAnimation = useCallback(() => {
     if (Platform.OS === 'android' && inNavModal) {
@@ -171,7 +172,7 @@ const Modal = ({
     noButtons,
     stickyFooter,
     showHandle: props.showHandle,
-    background: background === 'brand' ? 'brand' : 'primary',
+    background: isBrandBackground ? 'brand' : 'primary',
   });
 
   const footer = (
@@ -180,7 +181,7 @@ const Modal = ({
         <Button
           onPress={handlePrimaryButtonPress}
           text={primaryButtonText}
-          inverted={background === 'brand' && inNavModal}
+          inverted={isBrandBackground && inNavModal}
           {...primaryButtonProps}
           variant={(primaryButtonProps?.variant as 'solid') ?? 'solid'}
           colorScheme={(primaryButtonProps?.colorScheme as 'highlight') ?? 'highlight'}
@@ -190,7 +191,7 @@ const Modal = ({
         <Button
           onPress={handleSecondaryButtonPress}
           text={secondaryButtonText}
-          inverted={background === 'brand' && inNavModal}
+          inverted={isBrandBackground && inNavModal}
           {...secondaryButtonProps}
           variant={(secondaryButtonProps?.variant as 'outline') ?? 'outline'}
           colorScheme={(secondaryButtonProps?.colorScheme as 'functional') ?? 'functional'}
@@ -209,8 +210,11 @@ const Modal = ({
           screenReaderFocusable
           ref={viewRef}
         >
-          <Spinner size="lg" />
-          <Heading size="lg" textAlign="center">
+          <Spinner
+            size="lg"
+            color={isBrandBackground && inNavModal ? theme.color.icon.inverted : undefined}
+          />
+          <Heading size="lg" textAlign="center" inverted={isBrandBackground && inNavModal}>
             {loadingHeading}
           </Heading>
         </View>
@@ -225,18 +229,22 @@ const Modal = ({
           <View style={styles.header}>
             <View style={styles.headerTextContent}>
               {heading && !image ? (
-                <Heading size="lg" accessible>
+                <Heading size="lg" accessible inverted={isBrandBackground && inNavModal}>
                   {heading}
                 </Heading>
               ) : null}
-              {description && !image ? <BodyText accessible>{description}</BodyText> : null}
+              {description && !image ? (
+                <BodyText accessible inverted={isBrandBackground && inNavModal}>
+                  {description}
+                </BodyText>
+              ) : null}
             </View>
             {showCloseButton ? (
               <UnstyledIconButton
                 icon={CloseMediumIcon}
                 onPress={handleCloseButtonPress}
                 accessibilityLabel="Close modal"
-                inverted={background === 'brand' && inNavModal}
+                inverted={isBrandBackground && inNavModal}
                 {...closeButtonProps}
               />
             ) : null}
@@ -246,12 +254,21 @@ const Modal = ({
               {image}
               <View style={styles.textContent}>
                 {heading ? (
-                  <Heading size="lg" textAlign="center" accessible>
+                  <Heading
+                    size="lg"
+                    textAlign="center"
+                    accessible
+                    inverted={isBrandBackground && inNavModal}
+                  >
                     {heading}
                   </Heading>
                 ) : null}
                 {description ? (
-                  <BodyText textAlign="center" accessible>
+                  <BodyText
+                    textAlign="center"
+                    accessible
+                    inverted={isBrandBackground && inNavModal}
+                  >
                     {description}
                   </BodyText>
                 ) : null}
@@ -285,7 +302,7 @@ const Modal = ({
     <View
       style={{
         flex: 1,
-        backgroundColor: theme.color.background[background === 'brand' ? 'brand' : 'primary'],
+        backgroundColor: theme.color.background[isBrandBackground ? 'brand' : 'primary'],
       }}
     >
       {Platform.OS === 'android' ? (

package/src/components/ProgressBar/ProgressBar.docs.mdx

@@ -0,0 +1,90 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Box, Center, ProgressBar } from '../..';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './ProgressBar.stories';
+
+<Meta title="Components / Progress Bar" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7849-5704&t=Jg2fPJPQNzOyspmQ-4" />
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7863-3977&t=Jg2fPJPQNzOyspmQ-4" />
+
+# Progress Bar
+
+Progress bars communicate task completion for linear flows and bounded operations. Use the linear variant for
+inline layouts and the circular variant when space is tighter or when progress needs more emphasis.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Variants](#variants)
+- [Circular Sizes](#circular-sizes)
+- [Examples](#examples)
+  - [Custom Value Labels](#custom-value-labels)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Center>
+    <Box style={{ width: 260 }}>
+      <ProgressBar value={42} label="Uploading documents" />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { ProgressBar } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <ProgressBar value={42} label="Uploading documents" />;
+```
+
+## Props
+
+| Property          | Type                                                                                      | Description                                              | Default   |
+| ----------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------- | --------- |
+| `variant`         | `'linear' \| 'circular'`                                                                  | The progress bar variant.                                | `linear`  |
+| `colorScheme`     | `'default' \| 'success' \| 'danger'`                                                      | The color scheme for the progress indicator.             | `default` |
+| `size`            | `'sm' \| 'md'`                                                                            | Circular size. Only applies to the circular variant.     | `md`      |
+| `value`           | `number`                                                                                  | Current progress value.                                  |           |
+| `min`             | `number`                                                                                  | Minimum value.                                           | `0`       |
+| `max`             | `number`                                                                                  | Maximum value.                                           | `100`     |
+| `label`           | `string`                                                                                  | Accessible label for the progress bar.                   |           |
+| `hideLabel`       | `boolean`                                                                                 | Visually hide the label and value text.                  | `false`   |
+| `formatValueText` | `(value: number, meta: { min: number; `<br />` max: number; percent: number }) => string` | Override the default percentage label.                   |           |
+| `aria-valuetext`  | `string`                                                                                  | A human-readable text alternative for the current value. |           |
+
+## Variants
+
+<Canvas of={Stories.Variants} />
+
+## Circular Sizes
+
+<Canvas of={Stories.CircularSizes} />
+
+## Examples
+
+### Custom Value Labels
+
+Use `formatValueText` to show values that are not percentages, such as remaining data allowance.
+
+<Canvas of={Stories.CustomValueLabels} />
+
+```tsx
+import { ProgressBar } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <ProgressBar
+    value={68}
+    max={100}
+    label="Data allowance"
+    formatValueText={(value, { max }) => `${max - value}GB remaining`}
+  />
+);
+```

package/src/components/ProgressBar/ProgressBar.figma.tsx

@@ -0,0 +1,79 @@
+import figma from '@figma/code-connect';
+import { ProgressBar } from '../';
+
+figma.connect(
+  ProgressBar,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7849-5704',
+  {
+    props: {
+      value: figma.enum('Progress', {
+        '0%': 0,
+        '10%': 10,
+        '20%': 20,
+        '30%': 30,
+        '40%': 40,
+        '50%': 50,
+        '60%': 60,
+        '70%': 70,
+        '80%': 80,
+        '90%': 90,
+        '100%': 100,
+      }),
+      colorScheme: figma.enum('Color Scheme', {
+        Default: 'default',
+        Success: 'success',
+        Danger: 'danger',
+      }),
+      label: figma.boolean('Label?', { true: figma.string('Label') }),
+    },
+    example: props => (
+      <ProgressBar
+        variant="linear"
+        value={props.value}
+        colorScheme={props.colorScheme}
+        label={props.label}
+      />
+    ),
+  }
+);
+
+figma.connect(
+  ProgressBar,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=7863-3977',
+  {
+    props: {
+      value: figma.enum('Progress', {
+        '0%': 0,
+        '10%': 10,
+        '20%': 20,
+        '30%': 30,
+        '40%': 40,
+        '50%': 50,
+        '60%': 60,
+        '70%': 70,
+        '80%': 80,
+        '90%': 90,
+        '100%': 100,
+      }),
+      colorScheme: figma.enum('Color Scheme', {
+        Default: 'default',
+        Success: 'success',
+        Danger: 'danger',
+      }),
+      size: figma.enum('Size', {
+        'SM-80': 'sm',
+        'MD-140': 'md',
+      }),
+      label: figma.boolean('Label?', { true: figma.string('Label') }),
+    },
+    example: props => (
+      <ProgressBar
+        variant="circular"
+        value={props.value}
+        colorScheme={props.colorScheme}
+        size={props.size}
+        label={props.label}
+      />
+    ),
+  }
+);

package/src/components/ProgressBar/ProgressBar.props.ts

@@ -0,0 +1,60 @@
+import { ViewProps } from 'react-native';
+
+export type ProgressBarVariant = 'linear' | 'circular';
+export type ProgressBarColorScheme = 'default' | 'success' | 'danger';
+export type ProgressBarSize = 'sm' | 'md';
+
+export interface ProgressBarProps extends ViewProps {
+  variant?: ProgressBarVariant;
+  /**
+   * Set the visual appearance.
+   * @default 'default'
+   */
+  colorScheme?: ProgressBarColorScheme;
+  /**
+   * Sets the circular variant size. Does not affect the appearance of the linear variant.
+   * @default 'md'
+   */
+  size?: ProgressBarSize;
+  /**
+   * The current progress value.
+   */
+  value: number;
+  /**
+   * The minimum value.
+   * @default 0
+   */
+  min?: number;
+  /**
+   * The maximum value.
+   * @default 100
+   */
+  max?: number;
+  /**
+   * Required text label for the progress bar.
+   */
+  label: string;
+  /**
+   * Visually hide the label and value text.
+   */
+  hideLabel?: boolean;
+  /**
+   * Override the default percentage value label formatting.
+   */
+  formatValueText?: (value: number, meta: { min: number; max: number; percent: number }) => string;
+  /**
+   * A human-readable text alternative for the current value.
+   */
+  'aria-valuetext'?: string;
+}
+
+export interface ProgressBarInternalProps {
+  percent: number;
+  label: string;
+  valueText: string;
+  hideLabel?: boolean;
+  colorScheme: ProgressBarColorScheme;
+  size: ProgressBarSize;
+}
+
+export default ProgressBarProps;

package/src/components/ProgressBar/ProgressBar.stories.tsx

@@ -0,0 +1,117 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import type { ComponentProps } from 'react';
+import { ProgressBar } from '.';
+import { VariantTitle } from '../../../docs/components';
+import { Box } from '../Box';
+
+const meta = {
+  title: 'Stories / ProgressBar',
+  component: ProgressBar,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      options: ['linear', 'circular'],
+      control: 'select',
+      description: 'The progress bar variant.',
+    },
+    colorScheme: {
+      options: ['default', 'success', 'danger'],
+      control: 'select',
+      description: 'The color scheme for the progress indicator.',
+    },
+    size: {
+      options: ['sm', 'md'],
+      control: 'select',
+      description: 'The circular size. Only applies to the circular variant.',
+    },
+  },
+  args: {
+    variant: 'linear',
+    colorScheme: 'default',
+    size: 'md',
+    value: 35,
+    min: 0,
+    max: 100,
+    label: 'Progress',
+  },
+} satisfies Meta<typeof ProgressBar>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+type ProgressBarStoryArgs = ComponentProps<typeof ProgressBar>;
+
+export const Playground: Story = {};
+
+export const Variants: Story = {
+  args: {
+    value: 55,
+    label: 'Downloads',
+  },
+  render: (args: ProgressBarStoryArgs) => (
+    <Box gap="300" style={{ width: 260 }}>
+      <VariantTitle title="Linear">
+        <ProgressBar {...args} variant="linear" />
+      </VariantTitle>
+      <VariantTitle title="Circular">
+        <ProgressBar {...args} variant="circular" />
+      </VariantTitle>
+    </Box>
+  ),
+};
+
+export const ColorSchemes: Story = {
+  args: {
+    value: 72,
+    label: 'Storage',
+    variant: 'linear',
+  },
+  render: (args: ProgressBarStoryArgs) => (
+    <Box gap="300" style={{ width: 260 }}>
+      <VariantTitle title="Default">
+        <ProgressBar {...args} colorScheme="default" />
+      </VariantTitle>
+      <VariantTitle title="Success">
+        <ProgressBar {...args} colorScheme="success" />
+      </VariantTitle>
+      <VariantTitle title="Danger">
+        <ProgressBar {...args} colorScheme="danger" />
+      </VariantTitle>
+    </Box>
+  ),
+};
+
+export const CircularSizes: Story = {
+  args: {
+    value: 65,
+    label: 'Usage',
+    variant: 'circular',
+  },
+  render: (args: ProgressBarStoryArgs) => (
+    <Box gap="300">
+      <VariantTitle title="Small">
+        <ProgressBar {...args} size="sm" />
+      </VariantTitle>
+      <VariantTitle title="Medium">
+        <ProgressBar {...args} size="md" />
+      </VariantTitle>
+    </Box>
+  ),
+};
+
+export const CustomValueLabels: Story = {
+  args: {
+    value: 68,
+    max: 100,
+    label: 'Data allowance',
+    variant: 'linear',
+    formatValueText: (value: number, { max }: { max: number }) => `${max - value}GB remaining`,
+  },
+  render: (args: ProgressBarStoryArgs) => (
+    <Box style={{ width: 260 }}>
+      <ProgressBar {...args} />
+    </Box>
+  ),
+};

package/src/components/ProgressBar/ProgressBar.tsx

@@ -0,0 +1,74 @@
+import { View } from 'react-native';
+import type ProgressBarProps from './ProgressBar.props';
+import ProgressBarCircular from './ProgressBarCircular';
+import ProgressBarLinear from './ProgressBarLinear';
+
+const clampValue = (value: number, min: number, max: number) => {
+  if (max <= min) return min;
+  return Math.min(Math.max(value, min), max);
+};
+
+const valueToPercent = (value: number, min: number, max: number) => {
+  const range = max - min;
+  if (range <= 0) return 0;
+  return ((value - min) / range) * 100;
+};
+
+const ProgressBar = ({
+  variant = 'linear',
+  colorScheme = 'default',
+  size = 'md',
+  value,
+  min = 0,
+  max = 100,
+  label,
+  hideLabel,
+  formatValueText,
+  'aria-valuetext': ariaValueText,
+  accessibilityLabel,
+  ...rest
+}: ProgressBarProps) => {
+  const effectiveValue =
+    colorScheme === 'success' && !formatValueText ? max : clampValue(value, min, max);
+  const percentValue = valueToPercent(effectiveValue, min, max);
+  const clampedPercent = Math.max(0, Math.min(100, percentValue));
+  const valueText = formatValueText
+    ? formatValueText(effectiveValue, { min, max, percent: clampedPercent })
+    : `${Math.round(clampedPercent)}%`;
+  const valueTextForAria = ariaValueText ?? valueText;
+
+  const internalProps = {
+    percent: clampedPercent,
+    label,
+    valueText,
+    hideLabel,
+    colorScheme,
+    size,
+  };
+
+  return (
+    <View
+      {...rest}
+      accessible
+      role="progressbar"
+      accessibilityRole="progressbar"
+      accessibilityLabel={accessibilityLabel ?? label}
+      accessibilityValue={{ min, max, now: effectiveValue, text: valueTextForAria }}
+      aria-valuenow={effectiveValue}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-valuetext={valueTextForAria}
+      data-colorscheme={colorScheme}
+    >
+      {variant === 'circular' ? (
+        <ProgressBarCircular {...internalProps} />
+      ) : (
+        <ProgressBarLinear {...internalProps} />
+      )}
+    </View>
+  );
+};
+
+ProgressBar.displayName = 'ProgressBar';
+
+export default ProgressBar;