@utilitywarehouse/hearth-react-native 0.23.0 → 0.25.0

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;

package/src/components/ProgressBar/ProgressBarCircular.tsx

@@ -0,0 +1,181 @@
+import React, { useEffect, useRef } from 'react';
+import { Text, View } from 'react-native';
+import Animated, {
+  Easing,
+  useAnimatedProps,
+  useReducedMotion,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { Circle, G, Svg } from 'react-native-svg';
+import { StyleSheet } from 'react-native-unistyles';
+import useTheme from '../../hooks/useTheme';
+import { BodyText } from '../BodyText';
+import type { ProgressBarInternalProps } from './ProgressBar.props';
+
+const AnimatedCircle = Animated.createAnimatedComponent(Circle as React.ComponentType<any>);
+
+const ProgressBarCircular = ({
+  percent,
+  label,
+  valueText,
+  hideLabel,
+  colorScheme,
+  size,
+}: ProgressBarInternalProps) => {
+  const { components } = useTheme();
+  const isReducedMotion = useReducedMotion();
+  const progress = useSharedValue(0);
+  const hasMountedRef = useRef(false);
+
+  useEffect(() => {
+    const target = Math.max(0, Math.min(100, percent)) / 100;
+    if (isReducedMotion) {
+      progress.value = target;
+      hasMountedRef.current = true;
+      return;
+    }
+
+    if (!hasMountedRef.current) {
+      progress.value = target;
+      hasMountedRef.current = true;
+      return;
+    }
+
+    progress.value = withTiming(target, { duration: 300, easing: Easing.out(Easing.ease) });
+  }, [percent, isReducedMotion, progress]);
+
+  const circularTokens = components.progressBar.circular[size];
+  const barWidth = 'bar' in circularTokens ? circularTokens.bar.width : circularTokens.barWidth;
+  const diameter = circularTokens.height;
+  const radius = (diameter - barWidth) / 2;
+  const circumference = 2 * Math.PI * radius;
+
+  const animatedCircleProps = useAnimatedProps(() => ({
+    strokeDashoffset: circumference * (1 - progress.value),
+  }));
+
+  const indicatorColor =
+    colorScheme === 'success'
+      ? components.progressBar.progress.successColor
+      : colorScheme === 'danger'
+        ? components.progressBar.progress.dangerColor
+        : components.progressBar.progress.defaultColor;
+
+  styles.useVariants({ size });
+
+  return (
+    <View style={styles.container}>
+      <Svg
+        width={diameter}
+        height={diameter}
+        viewBox={`0 0 ${diameter} ${diameter}`}
+        style={styles.svg}
+      >
+        <G origin={`${diameter / 2}, ${diameter / 2}`} rotation={-90}>
+          <Circle
+            cx="50%"
+            cy="50%"
+            r={radius}
+            stroke={components.progressBar.barColor}
+            strokeWidth={barWidth}
+            fill="transparent"
+          />
+          <AnimatedCircle
+            cx="50%"
+            cy="50%"
+            r={radius}
+            stroke={indicatorColor}
+            strokeWidth={barWidth}
+            fill="transparent"
+            strokeLinecap="round"
+            strokeDasharray={circumference}
+            animatedProps={animatedCircleProps}
+          />
+        </G>
+      </Svg>
+      <View style={styles.content}>
+        <Text style={styles.valueText}>{valueText}</Text>
+        {!hideLabel && size === 'md' ? (
+          <BodyText style={styles.label} size="md" weight="semibold">
+            {label}
+          </BodyText>
+        ) : null}
+      </View>
+    </View>
+  );
+};
+
+ProgressBarCircular.displayName = 'ProgressBarCircular';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    position: 'relative',
+    variants: {
+      size: {
+        md: {
+          width: theme.components.progressBar.circular.md.height,
+          height: theme.components.progressBar.circular.md.height,
+        },
+        sm: {
+          width: theme.components.progressBar.circular.sm.height,
+          height: theme.components.progressBar.circular.sm.height,
+        },
+      },
+    },
+  },
+  svg: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+  },
+  content: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    _web: {
+      position: 'absolute',
+      top: 0,
+      left: 0,
+      width: '100%',
+      height: '100%',
+    },
+    variants: {
+      size: {
+        md: {
+          gap: theme.components.progressBar.circular.md.gap,
+        },
+        sm: {
+          gap: 0,
+        },
+      },
+    },
+  },
+  valueText: {
+    color: theme.color.text.primary,
+    textAlign: 'center',
+    variants: {
+      size: {
+        md: {
+          fontFamily: theme.components.progressBar.circular.md.label.fontFamily,
+          fontSize: theme.components.progressBar.circular.md.label.fontSize,
+          lineHeight: theme.components.progressBar.circular.md.label.lineHeight,
+          fontWeight: theme.components.progressBar.circular.md.label.fontWeight,
+        },
+        sm: {
+          fontFamily: theme.typography.mobile.bodyText.fontFamily,
+          fontSize: theme.typography.mobile.bodyText.md.fontSize,
+          lineHeight: theme.typography.mobile.bodyText.md.lineHeight,
+          fontWeight: theme.fontWeight.semibold,
+        },
+      },
+    },
+  },
+  label: {
+    textAlign: 'center',
+    maxWidth: 90,
+  },
+}));
+
+export default ProgressBarCircular;

package/src/components/ProgressBar/ProgressBarLinear.tsx

@@ -0,0 +1,127 @@
+import { useEffect, useRef, useState } from 'react';
+import { LayoutChangeEvent, Platform, View } from 'react-native';
+import Animated, {
+  Easing,
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { StyleSheet } from 'react-native-unistyles';
+import useTheme from '../../hooks/useTheme';
+import { BodyText } from '../BodyText';
+import type { ProgressBarInternalProps } from './ProgressBar.props';
+
+const ProgressBarLinear = ({
+  percent,
+  label,
+  valueText,
+  hideLabel,
+  colorScheme,
+}: ProgressBarInternalProps) => {
+  const { components } = useTheme();
+  const isReducedMotion = useReducedMotion();
+  const progress = useSharedValue(0);
+  const hasMountedRef = useRef(false);
+  const [trackWidth, setTrackWidth] = useState(0);
+
+  useEffect(() => {
+    const target = Math.max(0, Math.min(100, percent)) / 100;
+    if (isReducedMotion) {
+      progress.value = target;
+      hasMountedRef.current = true;
+      return;
+    }
+
+    if (!hasMountedRef.current) {
+      progress.value = target;
+      hasMountedRef.current = true;
+      return;
+    }
+
+    progress.value = withTiming(target, { duration: 300, easing: Easing.out(Easing.ease) });
+  }, [percent, isReducedMotion, progress]);
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    width: trackWidth * progress.value,
+  }));
+
+  const indicatorColor =
+    colorScheme === 'success'
+      ? components.progressBar.progress.successColor
+      : colorScheme === 'danger'
+        ? components.progressBar.progress.dangerColor
+        : components.progressBar.progress.defaultColor;
+
+  const handleTrackLayout = (event: LayoutChangeEvent) => {
+    setTrackWidth(event.nativeEvent.layout.width);
+  };
+
+  return (
+    <View style={styles.container}>
+      {!hideLabel && (
+        <View style={styles.header}>
+          <BodyText size="md" weight="semibold" style={styles.label}>
+            {label}
+          </BodyText>
+          <BodyText size="md" style={styles.value}>
+            {valueText}
+          </BodyText>
+        </View>
+      )}
+      <View style={styles.track} onLayout={handleTrackLayout}>
+        {Platform.OS === 'web' ? (
+          <View
+            style={[
+              styles.indicator,
+              { width: `${Math.max(0, Math.min(100, percent))}%` },
+              { backgroundColor: indicatorColor },
+            ]}
+          />
+        ) : (
+          <Animated.View
+            style={[styles.indicator, animatedStyle, { backgroundColor: indicatorColor }]}
+          />
+        )}
+      </View>
+    </View>
+  );
+};
+
+ProgressBarLinear.displayName = 'ProgressBarLinear';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    width: '100%',
+    gap: theme.components.progressBar.linear.gap,
+  },
+  header: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: theme.components.progressBar.linear.label.gap,
+  },
+  label: {
+    flex: 1,
+  },
+  value: {
+    flexShrink: 0,
+    textAlign: 'right',
+  },
+  track: {
+    width: '100%',
+    height: theme.components.progressBar.linear.bar.height,
+    backgroundColor: theme.components.progressBar.barColor,
+    borderRadius: theme.components.progressBar.linear.bar.borderRadius,
+    overflow: 'hidden',
+  },
+  indicator: {
+    height: '100%',
+    borderRadius: theme.components.progressBar.linear.bar.borderRadius,
+    _web: {
+      height: '100%',
+    },
+  },
+}));
+
+export default ProgressBarLinear;

package/src/components/ProgressBar/index.ts

@@ -0,0 +1,7 @@
+export { default as ProgressBar } from './ProgressBar';
+export type {
+  ProgressBarColorScheme,
+  ProgressBarProps,
+  ProgressBarSize,
+  ProgressBarVariant,
+} from './ProgressBar.props';

package/src/components/TimePicker/TimePicker.docs.mdx

@@ -0,0 +1,84 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Button, Center } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './TimePicker.stories';
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10334-16770&t=Jg2fPJPQNzOyspmQ-4" />
+
+<Meta title="Components / Time Picker" />
+
+<BackToTopButton />
+
+# Time Picker
+
+`TimePicker` presents a wheel-based time selector inside a bottom sheet, letting people pick hours and minutes without leaving the current context. It supports 12-hour and 24-hour clocks and returns a JavaScript `Date` whenever the selection changes.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+Use the `TimePicker` with a ref to present the bottom sheet when people tap a trigger button.
+
+<UsageWrap>
+  <Center>
+    <Button onPress={() => {}}>Pick a time</Button>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { useRef, useState } from 'react';
+import {
+  BottomSheetModalProvider,
+  Button,
+  TimePicker,
+  type DateType,
+} from '@utilitywarehouse/hearth-react-native';
+
+const BookingTime = () => {
+  const pickerRef = useRef(null);
+  const [time, setTime] = useState<DateType>();
+
+  return (
+    <BottomSheetModalProvider>
+      <Button onPress={() => pickerRef.current?.present()}>Choose time</Button>
+
+      <TimePicker
+        ref={pickerRef}
+        date={time}
+        onChange={({ date }) => setTime(date)}
+        onCancel={() => setTime(undefined)}
+        use12Hours={false}
+      />
+    </BottomSheetModalProvider>
+  );
+};
+```
+
+## Props
+
+`TimePicker` extends the `BottomSheetModal` component. The table below highlights the main props.
+
+| Prop             | Type                                    | Default    | Description                                                     |
+| ---------------- | --------------------------------------- | ---------- | --------------------------------------------------------------- |
+| `date`           | `DateType`                              | `-`        | Selected time value.                                            |
+| `timeZone`       | `string`                                | `-`        | IANA time zone identifier applied to the selected time.         |
+| `use12Hours`     | `boolean`                               | `false`    | Displays an AM/PM selector and formats hours from 1 to 12.      |
+| `minuteInterval` | `number`                                | `1`        | Step interval for minutes shown in the picker.                  |
+| `hideFooter`     | `boolean`                               | `false`    | Hides the Cancel/Ok actions.                                    |
+| `onChange`       | `(payload: { date: DateType }) => void` | `-`        | Fired whenever the selected time changes.                       |
+| `onCancel`       | `() => void`                            | `() => {}` | Fired when the cancel action is triggered.                      |
+| `ref`            | `Ref<BottomSheetModalMethods>`          | `-`        | Gives imperative access to present or dismiss the bottom sheet. |
+
+## Accessibility
+
+- Screen readers announce the picker when the sheet opens and focus the wheel area on Android.
+- Action buttons are exposed as standard buttons with clear labels.

package/src/components/TimePicker/TimePicker.figma.tsx

@@ -0,0 +1,29 @@
+import figma from '@figma/code-connect';
+import { useRef, useState } from 'react';
+import { BottomSheetModalProvider, Button, DateType, TimePicker } from '../';
+
+figma.connect(
+  TimePicker,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10334-16770&t=Jg2fPJPQNzOyspmQ-4',
+  {
+    props: {},
+    example: props => {
+      const pickerRef = useRef(null);
+      const [time, setTime] = useState<DateType>();
+
+      return (
+        <BottomSheetModalProvider>
+          <Button onPress={() => pickerRef.current?.present()}>Choose time</Button>
+
+          <TimePicker
+            ref={pickerRef}
+            date={time}
+            onChange={({ date }) => setTime(date)}
+            onCancel={() => setTime(undefined)}
+            use12Hours={false}
+          />
+        </BottomSheetModalProvider>
+      );
+    },
+  }
+);

package/src/components/TimePicker/TimePicker.props.ts

@@ -0,0 +1,45 @@
+import type { BottomSheetModalMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+import type { Ref } from 'react';
+import type { ViewStyle } from 'react-native';
+import type { DateType, PickerOption } from '../DatePicker/DatePicker.props';
+
+export interface TimePickerProps {
+  /**
+   * IANA time zone identifier applied when normalising and comparing times.
+   */
+  timeZone?: string;
+  /**
+   * Controlled time value.
+   */
+  date?: DateType;
+  /**
+   * Fired whenever a time is picked.
+   */
+  onChange?: (params: { date: DateType }) => void;
+  /**
+   * Display a 12-hour clock with AM/PM selector.
+   */
+  use12Hours?: boolean;
+  /**
+   * Step interval for minutes shown in the picker.
+   */
+  minuteInterval?: number;
+  /**
+   * Hide the footer actions.
+   */
+  hideFooter?: boolean;
+  /**
+   * Custom container styling for the time picker surface.
+   */
+  style?: ViewStyle;
+  /**
+   * Gives imperative access to the bottom sheet instance.
+   */
+  ref?: Ref<BottomSheetModalMethods<any>>;
+  /**
+   * Fired when the cancel action is triggered.
+   */
+  onCancel?: () => void;
+}
+
+export type { DateType, PickerOption };