@utilitywarehouse/hearth-react-native 0.31.0 → 0.32.0

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.

package/src/components/StepperInput/StepperInput.figma.tsx

@@ -0,0 +1,45 @@
+import figma from '@figma/code-connect';
+import { StepperInput } from '../';
+
+const props = {
+  value: figma.string('Value'),
+  label: figma.string('Label'),
+  labelVariant: figma.enum('Label variant', {
+    Body: 'body',
+    Heading: 'heading',
+  }),
+  helperText: figma.boolean('Helper text?', {
+    true: figma.string('Helper text'),
+    false: undefined,
+  }),
+  validationStatus: figma.enum('State', {
+    Default: 'initial',
+    Invalid: 'invalid',
+  }),
+  invalidText: figma.enum('State', {
+    Invalid: figma.string('Validation'),
+  }),
+};
+
+const handleChangeText = () => {
+  // Placeholder for Code Connect examples.
+};
+
+figma.connect(
+  StepperInput,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=10612%3A1860&m=dev',
+  {
+    props,
+    example: props => (
+      <StepperInput
+        value={props.value}
+        label={props.label}
+        labelVariant={props.labelVariant}
+        helperText={props.helperText}
+        validationStatus={props.validationStatus}
+        invalidText={props.invalidText}
+        onChangeText={handleChangeText}
+      />
+    ),
+  }
+);

package/src/components/StepperInput/StepperInput.props.ts

@@ -0,0 +1,39 @@
+import type { ComponentType, Ref } from 'react';
+import type { TextInput, TextInputProps, ViewProps } from 'react-native';
+
+export interface StepperBaseProps {
+  ref?: Ref<TextInput>;
+  disabled?: boolean;
+  validationStatus?: 'initial' | 'valid' | 'invalid';
+  readonly?: boolean;
+  focused?: boolean;
+  placeholder?: string;
+  inBottomSheet?: boolean;
+  required?: boolean;
+  label?: string;
+  labelVariant?: 'heading' | 'body';
+  helperText?: string;
+  helperIcon?: ComponentType;
+  validText?: string;
+  invalidText?: string;
+  value?: number | string;
+  defaultValue?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  onChangeValue?: (value: number) => void;
+  focusInputOnStepPress?: boolean;
+  decrementAccessibilityLabel?: string;
+  incrementAccessibilityLabel?: string;
+}
+
+export type StepperInputProps = StepperBaseProps &
+  Omit<
+    TextInputProps,
+    'children' | 'value' | 'defaultValue' | 'onChangeText' | 'editable' | 'keyboardType'
+  > &
+  ViewProps & {
+    onChangeText?: (text: string) => void;
+  };
+
+export default StepperInputProps;

package/src/components/StepperInput/StepperInput.stories.tsx

@@ -0,0 +1,270 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import type { ComponentProps } from 'react';
+import { useEffect, useState } from 'react';
+import { StepperInput } from '.';
+import { VariantTitle } from '../../../docs/components';
+import { Flex } from '../Flex';
+
+type StepperInputStoryProps = ComponentProps<typeof StepperInput>;
+
+const meta = {
+  title: 'Stories / StepperInput',
+  component: StepperInput,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    value: {
+      control: 'text',
+    },
+    label: {
+      control: 'text',
+    },
+    helperText: {
+      control: 'text',
+    },
+    labelVariant: {
+      control: 'radio',
+      options: ['body', 'heading'],
+    },
+    validationStatus: {
+      control: 'select',
+      options: ['initial', 'valid', 'invalid'],
+    },
+    validText: {
+      control: 'text',
+    },
+    invalidText: {
+      control: 'text',
+    },
+    disabled: {
+      control: 'boolean',
+    },
+    readonly: {
+      control: 'boolean',
+    },
+    focused: {
+      control: 'boolean',
+    },
+    min: {
+      control: 'number',
+    },
+    max: {
+      control: 'number',
+    },
+    step: {
+      control: 'number',
+    },
+    focusInputOnStepPress: {
+      control: 'boolean',
+    },
+  },
+  args: {
+    label: 'Label',
+    helperText: 'Helper text',
+    value: '10',
+    validationStatus: 'initial',
+    disabled: false,
+    readonly: false,
+    focused: false,
+    step: 1,
+    min: 0,
+    focusInputOnStepPress: false,
+  },
+} satisfies Meta<typeof StepperInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: ({
+    value: initialValue,
+    onChangeText: handleChangeText,
+    onChangeValue: handleChangeValue,
+    ...args
+  }: StepperInputStoryProps) => {
+    const [value, setValue] = useState(initialValue ?? '10');
+
+    useEffect(() => {
+      setValue(initialValue ?? '');
+    }, [initialValue]);
+
+    return (
+      <StepperInput
+        {...args}
+        value={value}
+        onChangeText={text => {
+          setValue(text);
+          handleChangeText?.(text);
+        }}
+        onChangeValue={nextValue => {
+          setValue(`${nextValue}`);
+          handleChangeValue?.(nextValue);
+        }}
+      />
+    );
+  },
+};
+
+export const States: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => {
+    const [values, setValues] = useState({
+      default: '10',
+      focused: '10',
+      invalid: '10',
+      invalidFocused: '10',
+      heading: '10',
+      headingInvalid: '10',
+      disabled: '10',
+    });
+
+    const updateValue = (key: keyof typeof values) => (text: string) => {
+      setValues(currentValues => ({ ...currentValues, [key]: text }));
+    };
+
+    return (
+      <Flex direction="column" spacing="lg" style={{ width: 420 }}>
+        <VariantTitle title="Default">
+          <StepperInput
+            label="Label"
+            helperText="Helper text"
+            value={values.default}
+            onChangeText={updateValue('default')}
+          />
+        </VariantTitle>
+        <VariantTitle title="Focused">
+          <StepperInput
+            label="Label"
+            helperText="Helper text"
+            focused
+            value={values.focused}
+            onChangeText={updateValue('focused')}
+          />
+        </VariantTitle>
+        <VariantTitle title="Invalid">
+          <StepperInput
+            label="Label"
+            helperText="Helper text"
+            validationStatus="invalid"
+            invalidText="Validation text"
+            value={values.invalid}
+            onChangeText={updateValue('invalid')}
+          />
+        </VariantTitle>
+        <VariantTitle title="Invalid Focused">
+          <StepperInput
+            label="Label"
+            helperText="Helper text"
+            focused
+            validationStatus="invalid"
+            invalidText="Validation text"
+            value={values.invalidFocused}
+            onChangeText={updateValue('invalidFocused')}
+          />
+        </VariantTitle>
+        <VariantTitle title="Heading Label">
+          <StepperInput
+            label="Label"
+            helperText="Helper text"
+            labelVariant="heading"
+            value={values.heading}
+            onChangeText={updateValue('heading')}
+          />
+        </VariantTitle>
+        <VariantTitle title="Heading Invalid">
+          <StepperInput
+            label="Label"
+            helperText="Helper text"
+            labelVariant="heading"
+            validationStatus="invalid"
+            invalidText="Validation text"
+            value={values.headingInvalid}
+            onChangeText={updateValue('headingInvalid')}
+          />
+        </VariantTitle>
+        <VariantTitle title="Disabled">
+          <StepperInput
+            label="Label"
+            helperText="Helper text"
+            disabled
+            value={values.disabled}
+            onChangeText={updateValue('disabled')}
+          />
+        </VariantTitle>
+      </Flex>
+    );
+  },
+};
+
+export const Bounds: Story = {
+  parameters: {
+    controls: { include: ['min', 'max', 'step', 'focusInputOnStepPress'] },
+  },
+  args: {
+    min: 0,
+    max: 12,
+    step: 2,
+  },
+  render: (args: StepperInputStoryProps) => {
+    const [value, setValue] = useState('10');
+
+    return <StepperInput {...args} value={value} onChangeText={setValue} />;
+  },
+};
+
+export const FocusOnStepPress: Story = {
+  parameters: {
+    controls: { include: ['focusInputOnStepPress'] },
+  },
+  args: {
+    focusInputOnStepPress: true,
+    label: 'Guests',
+    helperText: 'Button presses will keep focus in the input',
+    min: 1,
+    max: 10,
+  },
+  render: (args: StepperInputStoryProps) => {
+    const [value, setValue] = useState('2');
+
+    return <StepperInput {...args} value={value} onChangeText={setValue} />;
+  },
+};
+
+export const LargeStep: Story = {
+  parameters: {
+    controls: { include: ['step'] },
+  },
+  args: {
+    step: 10,
+    label: 'Large Step',
+    helperText: 'Step value of 10',
+    min: 0,
+    max: 100,
+  },
+  render: (args: StepperInputStoryProps) => {
+    const [value, setValue] = useState('20');
+
+    return <StepperInput {...args} value={value} onChangeText={setValue} />;
+  },
+};
+
+export const DecimalStep: Story = {
+  parameters: {
+    controls: { include: ['min', 'max', 'step'] },
+  },
+  args: {
+    step: 0.5,
+    label: 'Weight',
+    helperText: 'Supports fractional values',
+    min: -2,
+    max: 2,
+  },
+  render: (args: StepperInputStoryProps) => {
+    const [value, setValue] = useState('0.5');
+
+    return <StepperInput {...args} value={value} onChangeText={setValue} />;
+  },
+};