@utilitywarehouse/hearth-react-native 0.31.0 → 0.32.0

package/src/components/NavModal/NavModal.docs.mdx

@@ -6,13 +6,13 @@ import modaliOSVideo from '../../../docs/assets/modal-ios.mp4';
 import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
 import * as Stories from './NavModal.stories';
 
-<Meta title="Components / NavModal" />
+<Meta title="Components / Nav Modal" />
 
 <ViewFigmaButton url="https://www.figma.com/design/dLI9bmyMr42LV7dtFeW27J/Hearth-Patterns---Guides?node-id=6314-9103&t=oq3NaPLaAu3di6Db-4" />
 
 <BackToTopButton />
 
-# NavModal
+# Nav Modal
 
 The `NavModal` component is the screen-based modal layout for navigation flows. Use it when a screen is already being presented by React Navigation with `presentation: 'modal'` or `presentation: 'fullScreenModal'` and you want Hearth's modal structure, actions, and Android close animation support.
 

package/src/components/Rating/Rating.docs.mdx

@@ -0,0 +1,178 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Box, Center, Rating } from '../..';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Rating.stories';
+
+<Meta title="Components / Rating" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10620-4185" />
+
+# Rating
+
+Use Rating to collect a star-based score with an optional descriptive label.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Rating value={0} labels={{ 0: 'Not rated' }} />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { useState } from 'react';
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [rating, setRating] = useState<0 | 1 | 2 | 3 | 4 | 5>(0);
+
+  return <Rating value={rating} onChange={setRating} labels={{ 0: 'Not rated' }} />;
+};
+```
+
+## Props
+
+| Property       | Type                                   | Description                                 | Default     |
+| -------------- | -------------------------------------- | ------------------------------------------- | ----------- |
+| `value`        | `0 \| 1 \| 2 \| 3 \| 4 \| 5`           | Current rating value.                       | `0`         |
+| `defaultValue` | `0 \| 1 \| 2 \| 3 \| 4 \| 5`           | Initial rating value when uncontrolled.     | `0`         |
+| `onChange`     | `(value: RatingValue) => void`         | Called when a star is selected.             | `undefined` |
+| `disabled`     | `boolean`                              | Disables the rating input.                  | `false`     |
+| `labels`       | `Partial<Record<RatingValue, string>>` | Override labels for specific rating values. | `undefined` |
+| `hideLabel`    | `boolean`                              | Hide the label text below the stars.        | `false`     |
+
+## Examples
+
+### Default rating
+
+Use the default labels for a quick feedback prompt.
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Rating value={3} />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={3} />;
+```
+
+### Empty rating
+
+Use `value={0}` to show a zero-star state.
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Rating value={0} labels={{ 0: 'Not rated' }} />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={0} labels={{ 0: 'Not rated' }} />;
+```
+
+### Custom labels
+
+Provide custom copy for each rating value.
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Rating
+        value={5}
+        labels={{
+          0: 'Not rated',
+          1: 'Terrible',
+          2: 'Poor',
+          3: 'OK',
+          4: 'Great',
+          5: 'Outstanding',
+        }}
+      />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Rating
+    value={5}
+    labels={{
+      0: 'Not rated',
+      1: 'Terrible',
+      2: 'Poor',
+      3: 'OK',
+      4: 'Great',
+      5: 'Outstanding',
+    }}
+  />
+);
+```
+
+### Hidden label
+
+Use `hideLabel` when the context already explains the rating.
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Rating value={2} hideLabel />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={2} hideLabel />;
+```
+
+### Disabled
+
+Use `disabled` to show a read-only rating.
+
+<UsageWrap>
+  <Center>
+    <Box>
+      <Rating value={4} disabled />
+    </Box>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Rating } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Rating value={4} disabled />;
+```
+
+## Accessibility
+
+- Rating uses a `radiogroup` container with `radio` items for each star.
+- Each star announces a descriptive label (e.g., "Rate Okay"). Override labels with the `labels` prop to match your content.
+- Provide `accessibilityLabel` when the default label text is not sufficient for your screen reader context.

package/src/components/Rating/Rating.figma.tsx

@@ -0,0 +1,20 @@
+import figma from '@figma/code-connect';
+import { Rating } from '../';
+
+figma.connect(
+  Rating,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10620-4185',
+  {
+    props: {
+      value: figma.enum('Rating', {
+        '0 Star': 0,
+        '1 Star': 1,
+        '2 Star': 2,
+        '3 Star': 3,
+        '4 Star': 4,
+        '5 Star': 5,
+      }),
+    },
+    example: props => <Rating value={props.value} />,
+  }
+);

package/src/components/Rating/Rating.props.ts

@@ -0,0 +1,22 @@
+import type { ViewProps } from 'react-native';
+
+export type RatingValue = 0 | 1 | 2 | 3 | 4 | 5;
+
+export type RatingLabels = Partial<Record<RatingValue, string>>;
+
+export interface RatingProps extends Omit<ViewProps, 'children'> {
+  /** Current rating value. */
+  value?: RatingValue;
+  /** Initial rating value when uncontrolled. */
+  defaultValue?: RatingValue;
+  /** Called when a star is selected. */
+  onChange?: (value: RatingValue) => void;
+  /** Disables the rating input. */
+  disabled?: boolean;
+  /** Override labels for specific rating values. */
+  labels?: RatingLabels;
+  /** Hide the label text below the stars. */
+  hideLabel?: boolean;
+}
+
+export default RatingProps;

package/src/components/Rating/Rating.stories.tsx

@@ -0,0 +1,95 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import type { ComponentProps } from 'react';
+import { useEffect, useState } from 'react';
+import { Rating } from '.';
+import { VariantTitle } from '../../../docs/components';
+import { Box } from '../Box';
+
+type RatingStoryProps = ComponentProps<typeof Rating>;
+
+const meta = {
+  title: 'Stories / Rating',
+  component: Rating,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    value: {
+      control: { type: 'number', min: 0, max: 5, step: 1 },
+    },
+    defaultValue: {
+      control: { type: 'number', min: 0, max: 5, step: 1 },
+    },
+    labels: {
+      control: 'object',
+    },
+    hideLabel: {
+      control: 'boolean',
+    },
+    disabled: {
+      control: 'boolean',
+    },
+  },
+  args: {
+    value: 3,
+    hideLabel: false,
+    disabled: false,
+  },
+} satisfies Meta<typeof Rating>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: ({ value: initialValue, onChange, ...args }: RatingStoryProps) => {
+    const [value, setValue] = useState(initialValue ?? 0);
+
+    useEffect(() => {
+      setValue(initialValue ?? 0);
+    }, [initialValue]);
+
+    return (
+      <Rating
+        {...args}
+        value={value}
+        onChange={nextValue => {
+          setValue(nextValue);
+          onChange?.(nextValue);
+        }}
+      />
+    );
+  },
+};
+
+export const Variants: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => (
+    <Box gap="300">
+      <VariantTitle title="Default">
+        <Rating value={3} />
+      </VariantTitle>
+      <VariantTitle title="Custom Labels">
+        <Rating
+          value={4}
+          labels={{
+            0: 'Not rated',
+            1: 'Terrible',
+            2: 'Poor',
+            3: 'OK',
+            4: 'Great',
+            5: 'Outstanding',
+          }}
+        />
+      </VariantTitle>
+      <VariantTitle title="Hidden Label">
+        <Rating value={2} hideLabel />
+      </VariantTitle>
+      <VariantTitle title="Disabled">
+        <Rating value={5} disabled />
+      </VariantTitle>
+    </Box>
+  ),
+};

package/src/components/Rating/Rating.tsx

@@ -0,0 +1,140 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { Pressable, View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { BodyText } from '../BodyText';
+import type RatingProps from './Rating.props';
+import type { RatingLabels, RatingValue } from './Rating.props';
+import RatingStarEmpty from './RatingStarEmpty';
+import RatingStarFilled from './RatingStarFilled';
+
+const MAX_RATING: RatingValue = 5;
+const STAR_WIDTH = 32;
+const STAR_HEIGHT = 30;
+const STAR_CONTAINER_SIZE = 40;
+
+const DEFAULT_LABELS: Record<RatingValue, string> = {
+  0: 'Select a rating',
+  1: 'Awful',
+  2: 'Bad',
+  3: 'Okay',
+  4: 'Good',
+  5: 'Great!',
+};
+
+const clampRating = (value: number) =>
+  Math.min(MAX_RATING, Math.max(0, Math.round(value))) as RatingValue;
+
+const Rating = ({
+  value,
+  defaultValue = 0,
+  onChange,
+  disabled = false,
+  labels,
+  hideLabel = false,
+  style,
+  accessibilityLabel,
+  ...props
+}: RatingProps) => {
+  const isControlled = value !== undefined;
+  const [internalValue, setInternalValue] = useState<RatingValue>(clampRating(defaultValue));
+
+  useEffect(() => {
+    if (!isControlled) {
+      setInternalValue(clampRating(defaultValue));
+    }
+  }, [defaultValue, isControlled]);
+
+  const resolvedLabels = useMemo<RatingLabels>(() => ({ ...DEFAULT_LABELS, ...labels }), [labels]);
+
+  const resolvedValue = clampRating(isControlled ? value : internalValue);
+  const currentLabel = resolvedLabels[resolvedValue] ?? DEFAULT_LABELS[resolvedValue];
+  const labelColor = resolvedValue === 0 ? 'secondary' : 'primary';
+
+  const handlePress = useCallback(
+    (nextValue: RatingValue) => {
+      if (disabled) return;
+
+      if (!isControlled) {
+        setInternalValue(nextValue);
+      }
+
+      onChange?.(nextValue);
+    },
+    [disabled, isControlled, onChange]
+  );
+
+  styles.useVariants({ disabled });
+
+  return (
+    <View
+      {...props}
+      accessibilityRole="radiogroup"
+      accessibilityState={{ disabled }}
+      accessibilityLabel={accessibilityLabel ?? currentLabel}
+      style={[styles.container, style]}
+    >
+      <View style={styles.stars}>
+        {([1, 2, 3, 4, 5] as RatingValue[]).map(starValue => {
+          const isFilled = starValue <= resolvedValue;
+          const starLabel = resolvedLabels[starValue] ?? DEFAULT_LABELS[starValue];
+
+          return (
+            <Pressable
+              key={starValue}
+              accessibilityRole="radio"
+              accessibilityState={{ selected: resolvedValue === starValue, disabled }}
+              accessibilityLabel={`Rate ${starLabel}`}
+              disabled={disabled}
+              hitSlop={8}
+              onPress={() => handlePress(starValue)}
+              style={styles.star}
+            >
+              {isFilled ? (
+                <RatingStarFilled width={STAR_WIDTH} height={STAR_HEIGHT} />
+              ) : (
+                <RatingStarEmpty width={STAR_WIDTH} height={STAR_HEIGHT} />
+              )}
+            </Pressable>
+          );
+        })}
+      </View>
+      {!hideLabel ? (
+        <BodyText size="md" color={labelColor} style={styles.label}>
+          {currentLabel}
+        </BodyText>
+      ) : null}
+    </View>
+  );
+};
+
+Rating.displayName = 'Rating';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    alignItems: 'center',
+    gap: theme.components.rating.gap,
+    variants: {
+      disabled: {
+        true: {
+          opacity: theme.opacity.disabled,
+        },
+      },
+    },
+  },
+  stars: {
+    flexDirection: 'row',
+    gap: theme.components.rating.gap,
+  },
+  star: {
+    width: STAR_CONTAINER_SIZE,
+    height: STAR_CONTAINER_SIZE,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: theme.components.rating.borderWidth,
+  },
+  label: {
+    textAlign: 'center',
+  },
+}));
+
+export default Rating;

package/src/components/Rating/RatingStarEmpty.tsx

@@ -0,0 +1,22 @@
+import { Path, Svg } from 'react-native-svg';
+import { useTheme } from '../../hooks';
+
+type RatingStarProps = {
+  width?: number;
+  height?: number;
+};
+
+const STAR_PATH =
+  'M16 1C16.0831 1 16.1883 1.02107 16.3262 1.09766C16.3896 1.13286 16.4424 1.183 16.4902 1.28711H16.4912L20.1777 9.8916L20.4141 10.4424L21.0117 10.4941L30.5107 11.3096C30.7062 11.3326 30.8 11.3864 30.8467 11.4238C30.915 11.4787 30.9492 11.5325 30.9707 11.6035C31.0029 11.71 31.0094 11.8192 30.9844 11.9463V11.9482C30.98 11.9702 30.9618 12.0389 30.832 12.1514L23.6338 18.2939L23.1689 18.6904L23.3096 19.2852L25.458 28.3926H25.459C25.4832 28.5045 25.4775 28.5714 25.4658 28.6133L25.4531 28.6475C25.4155 28.7291 25.3682 28.7951 25.3076 28.8516L25.2432 28.9043C25.172 28.9558 25.0868 28.9907 24.96 28.999C24.8763 29.0045 24.793 28.9887 24.6865 28.9229L24.6787 28.918L24.6699 28.9131L16.5088 24.0898L16 23.7891L15.4912 24.0898L7.33008 28.9131L7.32129 28.918L7.31348 28.9229C7.20704 28.9887 7.12371 29.0045 7.04004 28.999C6.94495 28.9928 6.87333 28.9713 6.81348 28.9395L6.75684 28.9043C6.68716 28.8537 6.63221 28.7954 6.58789 28.7236L6.54688 28.6475C6.53436 28.6202 6.51869 28.5743 6.52539 28.4902L6.54102 28.3926L8.69043 19.2852L8.83105 18.6904L8.36621 18.2939L1.16699 12.1514C1.03725 12.0389 1.01999 11.9702 1.01563 11.9482V11.9463L1.00195 11.8545C0.994777 11.765 1.00514 11.6834 1.0293 11.6035C1.05077 11.5325 1.08501 11.4787 1.15332 11.4238C1.19992 11.3864 1.2935 11.3327 1.48828 11.3096L10.9883 10.4941L11.5859 10.4424L11.8223 9.8916L15.5088 1.28711C15.5567 1.18274 15.6103 1.1329 15.6738 1.09766C15.8117 1.02107 15.9169 1 16 1Z';
+
+const RatingStarEmpty = ({ width = 32, height = 30 }: RatingStarProps) => {
+  const theme = useTheme();
+
+  return (
+    <Svg width={width} height={height} viewBox="0 0 32 30" preserveAspectRatio="none">
+      <Path d={STAR_PATH} strokeWidth={2} fill="none" stroke={theme.color.border.subtle} />
+    </Svg>
+  );
+};
+
+export default RatingStarEmpty;

package/src/components/Rating/RatingStarFilled.tsx

@@ -0,0 +1,27 @@
+import { Path, Svg } from 'react-native-svg';
+import { useTheme } from '../../hooks';
+
+type RatingStarProps = {
+  width?: number;
+  height?: number;
+};
+
+const STAR_PATH =
+  'M16 1C16.0831 1 16.1883 1.02107 16.3262 1.09766C16.3896 1.13286 16.4424 1.183 16.4902 1.28711H16.4912L20.1777 9.8916L20.4141 10.4424L21.0117 10.4941L30.5107 11.3096C30.7062 11.3326 30.8 11.3864 30.8467 11.4238C30.915 11.4787 30.9492 11.5325 30.9707 11.6035C31.0029 11.71 31.0094 11.8192 30.9844 11.9463V11.9482C30.98 11.9702 30.9618 12.0389 30.832 12.1514L23.6338 18.2939L23.1689 18.6904L23.3096 19.2852L25.458 28.3926H25.459C25.4832 28.5045 25.4775 28.5714 25.4658 28.6133L25.4531 28.6475C25.4155 28.7291 25.3682 28.7951 25.3076 28.8516L25.2432 28.9043C25.172 28.9558 25.0868 28.9907 24.96 28.999C24.8763 29.0045 24.793 28.9887 24.6865 28.9229L24.6787 28.918L24.6699 28.9131L16.5088 24.0898L16 23.7891L15.4912 24.0898L7.33008 28.9131L7.32129 28.918L7.31348 28.9229C7.20704 28.9887 7.12371 29.0045 7.04004 28.999C6.94495 28.9928 6.87333 28.9713 6.81348 28.9395L6.75684 28.9043C6.68716 28.8537 6.63221 28.7954 6.58789 28.7236L6.54688 28.6475C6.53436 28.6202 6.51869 28.5743 6.52539 28.4902L6.54102 28.3926L8.69043 19.2852L8.83105 18.6904L8.36621 18.2939L1.16699 12.1514C1.03725 12.0389 1.01999 11.9702 1.01563 11.9482V11.9463L1.00195 11.8545C0.994777 11.765 1.00514 11.6834 1.0293 11.6035C1.05077 11.5325 1.08501 11.4787 1.15332 11.4238C1.19992 11.3864 1.2935 11.3327 1.48828 11.3096L10.9883 10.4941L11.5859 10.4424L11.8223 9.8916L15.5088 1.28711C15.5567 1.18274 15.6103 1.1329 15.6738 1.09766C15.8117 1.02107 15.9169 1 16 1Z';
+
+const RatingStarFilled = ({ width = 32, height = 30 }: RatingStarProps) => {
+  const theme = useTheme();
+
+  return (
+    <Svg width={width} height={height} viewBox="0 0 32 30" preserveAspectRatio="none">
+      <Path
+        d={STAR_PATH}
+        strokeWidth={2}
+        fill={theme.color.surface.highlight.default}
+        stroke={theme.color.border.strong}
+      />
+    </Svg>
+  );
+};
+
+export default RatingStarFilled;

package/src/components/Rating/index.ts

@@ -0,0 +1,2 @@
+export { default as Rating } from './Rating';
+export type { RatingLabels, RatingProps, RatingValue } from './Rating.props';

package/src/components/Roundel/Roundel.docs.mdx

@@ -0,0 +1,48 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Roundel } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Roundel.stories';
+
+<Meta title="Components / Roundel" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6414-8697&t=aFS22MoPV7Y08jdq-4" />
+
+# Roundel
+
+The `Roundel` component is a compact status indicator with success, pending, and error variants.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Roundel variant="success" />
+</UsageWrap>
+
+```tsx
+import { Roundel } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => <Roundel variant="success" />;
+```
+
+## Props
+
+| Prop      | Type                                | Default     | Description                              |
+| --------- | ----------------------------------- | ----------- | ---------------------------------------- |
+| `variant` | `'success' \| 'pending' \| 'error'` | `'success'` | Sets the status styling for the roundel. |
+| `...View` | React Native `ViewProps`            | -           | Any additional View props.               |
+
+## Examples
+
+<Canvas of={Stories.Variants} />

package/src/components/Roundel/Roundel.figma.tsx

@@ -0,0 +1,17 @@
+import figma from '@figma/code-connect';
+import { Roundel } from '..';
+
+figma.connect(
+  Roundel,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6414%3A8697&m=dev',
+  {
+    props: {
+      variant: figma.enum('Variant', {
+        Success: 'success',
+        Pending: 'pending',
+        Error: 'error',
+      }),
+    },
+    example: props => <Roundel variant={props.variant} />,
+  }
+);

package/src/components/Roundel/Roundel.props.ts

@@ -0,0 +1,8 @@
+import type { ViewProps } from 'react-native';
+
+export interface RoundelProps extends Omit<ViewProps, 'children'> {
+  /** Visual variant for the roundel status. */
+  variant?: 'success' | 'pending' | 'error';
+}
+
+export default RoundelProps;

package/src/components/Roundel/Roundel.stories.tsx

@@ -0,0 +1,49 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import { ComponentProps } from 'react';
+import { VariantTitle } from '../../../docs/components';
+import { Flex } from '../Flex';
+import { Roundel } from './';
+
+const meta: Meta<typeof Roundel> = {
+  title: 'Stories / Roundel',
+  component: Roundel,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      control: 'radio',
+      options: ['success', 'pending', 'error'],
+    },
+  },
+  args: {
+    variant: 'success',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: (args: ComponentProps<typeof Roundel>) => <Roundel {...args} />,
+};
+
+export const Variants: Story = {
+  parameters: {
+    controls: { exclude: ['variant'] },
+  },
+  render: () => (
+    <Flex direction="column" spacing="md" alignItems="center">
+      <VariantTitle title="Success">
+        <Roundel variant="success" />
+      </VariantTitle>
+      <VariantTitle title="Pending">
+        <Roundel variant="pending" />
+      </VariantTitle>
+      <VariantTitle title="Error">
+        <Roundel variant="error" />
+      </VariantTitle>
+    </Flex>
+  ),
+};