@utilitywarehouse/hearth-react-native 0.31.1 → 0.32.1

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>
+  ),
+};

package/src/components/Roundel/Roundel.tsx

@@ -0,0 +1,51 @@
+import { CloseSmallIcon, TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { Icon } from '../Icon';
+import type RoundelProps from './Roundel.props';
+
+const Roundel = ({ variant = 'success', style, ...props }: RoundelProps) => {
+  styles.useVariants({ variant });
+
+  const icon =
+    variant === 'error' ? CloseSmallIcon : variant === 'success' ? TickSmallIcon : undefined;
+
+  return (
+    <View {...props} style={[styles.container, style]}>
+      {icon ? <Icon as={icon} size="sm" /> : null}
+    </View>
+  );
+};
+
+Roundel.displayName = 'Roundel';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    width: theme.space[300],
+    height: theme.space[300],
+    borderRadius: theme.components.parts.roundel.borderRadius,
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+    backgroundColor: 'transparent',
+    borderWidth: 0,
+    borderStyle: 'solid',
+    variants: {
+      variant: {
+        success: {
+          backgroundColor: theme.color.feedback.positive.surface.default,
+        },
+        error: {
+          backgroundColor: theme.color.feedback.danger.surface.default,
+        },
+        pending: {
+          borderWidth: theme.components.parts.roundel.pending.borderWidth,
+          borderStyle: 'dashed',
+          borderColor: theme.color.border.strong,
+        },
+      },
+    },
+  },
+}));
+
+export default Roundel;

package/src/components/Roundel/index.ts

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

package/src/components/StepperInput/StepperButton.tsx

@@ -0,0 +1,83 @@
+import { createPressable } from '@gluestack-ui/pressable';
+import type { ComponentType } from 'react';
+import type { PressableProps, ViewStyle } from 'react-native';
+import { Pressable } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { Icon } from '../Icon';
+
+type StepperButtonProps = {
+  icon: ComponentType;
+  disabled?: boolean;
+} & Omit<PressableProps, 'children'>;
+
+const StepperButtonRoot = ({
+  icon,
+  disabled,
+  states,
+  ...props
+}: StepperButtonProps & { states?: { active?: boolean; disabled?: boolean } }) => {
+  const isDisabled = disabled ?? states?.disabled ?? false;
+  const isActive = states?.active ?? false;
+
+  styles.useVariants({ active: isActive, disabled: isDisabled });
+
+  return (
+    <Pressable
+      {...props}
+      accessibilityRole="button"
+      accessibilityState={{ disabled: isDisabled, ...props.accessibilityState }}
+      disabled={isDisabled}
+      style={[styles.button, props.style as ViewStyle]}
+    >
+      <Icon as={icon} size="sm" style={styles.icon} />
+    </Pressable>
+  );
+};
+
+const StepperButton = createPressable({ Root: StepperButtonRoot });
+
+StepperButton.displayName = 'StepperButton';
+
+const styles = StyleSheet.create(theme => ({
+  button: {
+    width: theme.components.iconButton.md.width,
+    height: theme.components.iconButton.md.height,
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: theme.components.input.borderRadius,
+    borderWidth: theme.components.input.borderWidth,
+    borderColor: theme.color.border.strong,
+    backgroundColor: theme.color.surface.neutral.strong,
+    _web: {
+      _hover: {
+        backgroundColor: theme.color.interactive.neutral.surface.subtle.hover,
+      },
+      _active: {
+        backgroundColor: theme.color.interactive.neutral.surface.subtle.active,
+      },
+      '_focus-visible': {
+        outlineStyle: 'solid',
+        outlineWidth: 2,
+        outlineColor: theme.color.focus.primary,
+        outlineOffset: 2,
+      },
+    },
+    variants: {
+      active: {
+        true: {
+          backgroundColor: theme.color.interactive.neutral.surface.subtle.active,
+        },
+      },
+      disabled: {
+        true: {
+          opacity: theme.opacity.disabled,
+        },
+      },
+    },
+  },
+  icon: {
+    color: theme.color.icon.primary,
+  },
+}));
+
+export default StepperButton;

package/src/components/StepperInput/StepperInput.docs.mdx

@@ -0,0 +1,121 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { StepperInput } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './StepperInput.stories';
+
+<Meta title="Forms / Stepper Input" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10612-1860&t=aFS22MoPV7Y08jdq-4" />
+
+# Stepper Input
+
+The Stepper Input combines a numeric text input with decrement and increment controls. Use it when the value should stay within a defined range but still needs direct text entry.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <StepperInput
+    label="Guests"
+    helperText="Choose between 1 and 10"
+    value="2"
+    onChangeText={() => undefined}
+  />
+</UsageWrap>
+
+```tsx
+import { useState } from 'react';
+import { StepperInput } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [value, setValue] = useState('2');
+
+  return (
+    <StepperInput
+      label="Guests"
+      helperText="Choose between 1 and 10"
+      min={1}
+      max={10}
+      value={value}
+      onChangeText={setValue}
+    />
+  );
+};
+```
+
+## Props
+
+The Stepper Input inherits React Native `TextInput` props except `children`, `value`, `defaultValue`, `onChangeText`, `editable`, and `keyboardType`. It also supports the following props:
+
+| Prop                          | Type                                | Default            | Description                                                                                 |
+| ----------------------------- | ----------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| `value`                       | `string \| number`                  | -                  | Controlled value displayed in the input.                                                    |
+| `defaultValue`                | `number`                            | -                  | Initial value for uncontrolled usage.                                                       |
+| `onChangeText`                | `(text: string) => void`            | -                  | Called whenever the displayed string changes.                                               |
+| `onChangeValue`               | `(value: number) => void`           | -                  | Called whenever the current text can be parsed as a number.                                 |
+| `min`                         | `number`                            | -                  | Minimum allowed numeric value.                                                              |
+| `max`                         | `number`                            | -                  | Maximum allowed numeric value.                                                              |
+| `step`                        | `number`                            | `1`                | Amount added or removed when the side buttons are pressed. Fractional values are supported. |
+| `focusInputOnStepPress`       | `boolean`                           | `false`            | When `true`, pressing a step button moves focus to the text input after updating the value. |
+| `validationStatus`            | `'initial' \| 'valid' \| 'invalid'` | `'initial'`        | Validation styling for the center input.                                                    |
+| `label`                       | `string`                            | -                  | Label shown above the stepper.                                                              |
+| `labelVariant`                | `'heading' \| 'body'`               | `'body'`           | Typography variant used for the label.                                                      |
+| `helperText`                  | `string`                            | -                  | Helper text shown below the label.                                                          |
+| `helperIcon`                  | `ComponentType`                     | -                  | Optional helper icon shown next to helper text.                                             |
+| `invalidText`                 | `string`                            | -                  | Validation text shown when `validationStatus="invalid"`.                                    |
+| `validText`                   | `string`                            | -                  | Validation text shown when `validationStatus="valid"`.                                      |
+| `disabled`                    | `boolean`                           | `false`            | Disables the input and both stepper buttons.                                                |
+| `readonly`                    | `boolean`                           | `false`            | Prevents editing and disables both buttons.                                                 |
+| `focused`                     | `boolean`                           | `false`            | Forces the focused visual state on the center input.                                        |
+| `decrementAccessibilityLabel` | `string`                            | `'Decrease value'` | Accessibility label for the decrement button.                                               |
+| `incrementAccessibilityLabel` | `string`                            | `'Increase value'` | Accessibility label for the increment button.                                               |
+
+## Examples
+
+### States
+
+<Canvas of={Stories.States} />
+
+### Bounds
+
+<Canvas of={Stories.Bounds} />
+
+### Fractional Values
+
+`StepperInput` supports fractional steps and negative ranges. When `step`, `min`, `max`, or the current value uses decimals, the input switches to a numeric keyboard path that preserves decimal editing.
+
+<Canvas of={Stories.DecimalStep} />
+
+```tsx
+<StepperInput label="Weight" min={-2} max={2} step={0.5} value={value} onChangeText={setValue} />
+```
+
+### Opt-In Focus On Step Press
+
+By default, the increment and decrement buttons update the value without moving focus into the text field. Enable `focusInputOnStepPress` when keyboard-first flows need the caret to stay in the input after a button press.
+
+<Canvas of={Stories.FocusOnStepPress} />
+
+```tsx
+<StepperInput label="Guests" value={value} onChangeText={setValue} focusInputOnStepPress />
+```
+
+## Accessibility
+
+- The center field remains a standard text input, so screen readers can edit the value directly.
+- The side controls expose button semantics with separate accessibility labels for increment and decrement.
+- Button presses do not move focus into the text field unless `focusInputOnStepPress` is enabled.
+- Validation, helper text, and disabled state follow the same `FormField` treatment as other input components.