@utilitywarehouse/hearth-react-native 0.1.0 → 0.3.0

package/src/components/CurrencyInput/CurrencyInput.docs.mdx

@@ -0,0 +1,120 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Center, CurrencyInput, FormField } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './CurrencyInput.stories';
+
+<Meta title="Forms / Currency Input" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/pjuYVErQWaAvs8rCAVgPKX/Motion-Tokens?node-id=2161-1336" />
+
+# Currency Input
+
+An input specialised for monetary amounts. It shows a currency symbol prefix and uses a decimal keypad where supported.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [States](#states)
+- [Formatting](#formatting)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Center>
+    <CurrencyInput placeholder="0.00" />
+  </Center>
+</UsageWrap>
+
+```tsx
+import { CurrencyInput } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [value, setValue] = useState('');
+  return (
+    <CurrencyInput value={value} onChange={e => setValue(e.nativeEvent.text)} placeholder="0.00" />
+  );
+};
+```
+
+## Props
+
+When using `CurrencyInput`, the component inherits React Native TextInput props (except `children`). In addition, it supports:
+
+| Prop                | Type                                | Default     | Description                                                                                                               |
+| ------------------- | ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
+| validationStatus    | `'initial' \| 'valid' \| 'invalid'` | `'initial'` | Validation styling state                                                                                                  |
+| disabled            | boolean                             | `false`     | Disables the input                                                                                                        |
+| readonly            | boolean                             | `false`     | Makes the input read-only                                                                                                 |
+| focused             | boolean                             | `false`     | Forces the focused visual state                                                                                           |
+| inBottomSheet       | boolean                             | `false`     | Use BottomSheetTextInput when true                                                                                        |
+| placeholder         | string                              | `'0.00'`    | Placeholder text                                                                                                          |
+| autoFormatThousands | boolean                             | `false`     | Automatically inserts thousand separators while the user types _(Only works with controlled components via onTextChange)_ |
+
+Note: When used inside `FormField`, `validationStatus` and `disabled` are read from the context unless explicitly overridden.
+
+## Examples
+
+### With `FormField`
+
+The `CurrencyInput` component can be used with the `FormField` component to create a custom input field.
+For more information on the `FormField` component view the [docs here](/docs/components-form-field--docs).
+
+<UsageWrap>
+  <Center>
+    <FormField label="Label" helperText="Helper text" helperPosition="bottom">
+      <CurrencyInput onChange={() => console.log('###')} />
+    </FormField>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { FormField, CurrencyInput } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [value, setValue] = useState('');
+  const handleChange = e => {
+    setValue(e.target.value);
+  };
+  return (
+    <FormField label="Label" helperText="Helper text" helperPosition="bottom">
+      <CurrencyInput onChange={handleChange} value={value} />
+    </FormField>
+  );
+};
+```
+
+## States
+
+<Canvas of={Stories.States} />
+
+## Formatting
+
+Enable automatic thousand separator formatting by setting `autoFormatThousands`.
+
+<Canvas of={Stories.AutoFormatThousands} />
+
+```tsx
+<CurrencyInput autoFormatThousands value="1234567.89" /> // displays 1,234,567.89
+```
+
+Notes:
+
+- Only digits, an optional leading minus and a single decimal point are formatted.
+- Formatting is applied as you type; caret will move to the end (standard RN behaviour when programmatically updating value).
+- Provide a controlled `value` if you need to manipulate or strip commas before persisting.
+
+## Accessibility
+
+The component uses a standard TextInput field and supports:
+
+- Screen readers (VoiceOver/TalkBack)
+- `aria-disabled`, `aria-required`, `aria-invalid` via underlying Input
+- Decimal keypad and selection/cursor colors aligned with theme

package/src/components/CurrencyInput/CurrencyInput.props.ts

@@ -0,0 +1,19 @@
+import type { TextInputProps, ViewProps } from 'react-native';
+
+export interface CurrencyInputBaseProps {
+  disabled?: boolean;
+  validationStatus?: 'initial' | 'valid' | 'invalid';
+  readonly?: boolean;
+  focused?: boolean;
+  placeholder?: string;
+  inBottomSheet?: boolean;
+  required?: boolean;
+  /** When true, automatically formats the numeric value with thousand separators (e.g. 1234 -> 1,234). */
+  autoFormatThousands?: boolean;
+}
+
+export type CurrencyInputProps = CurrencyInputBaseProps &
+  Omit<TextInputProps, 'children'> &
+  ViewProps;
+
+export default CurrencyInputProps;

package/src/components/CurrencyInput/CurrencyInput.stories.tsx

@@ -0,0 +1,116 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { CurrencyInput } from '..';
+import { VariantTitle } from '../../../docs/components';
+import { Flex } from '../Flex';
+
+const meta = {
+  title: 'Stories / CurrencyInput',
+  component: CurrencyInput,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    placeholder: {
+      control: 'text',
+      description: 'The CurrencyInput field placeholder',
+      defaultValue: '0.00',
+    },
+    validationStatus: {
+      control: 'select',
+      options: ['initial', 'valid', 'invalid'],
+      description: 'The validation status',
+      defaultValue: 'initial',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disable the input',
+      defaultValue: false,
+    },
+    readonly: {
+      control: 'boolean',
+      description: 'Read only',
+      defaultValue: false,
+    },
+    focused: {
+      control: 'boolean',
+      description: 'Focused',
+      defaultValue: false,
+    },
+    autoFormatThousands: {
+      control: 'boolean',
+      description:
+        'Automatically add thousand separators while typing _(Only works with controlled components via onTextChange)_',
+      defaultValue: false,
+    },
+  },
+  args: {
+    placeholder: '0.00',
+    validationStatus: 'initial',
+    disabled: false,
+    readonly: false,
+    focused: false,
+    autoFormatThousands: false,
+  },
+} satisfies Meta<typeof CurrencyInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {};
+
+export const AutoFormatThousands: Story = {
+  parameters: {
+    controls: { include: ['autoFormatThousands'] },
+  },
+  args: { autoFormatThousands: true },
+  render: args => {
+    const [value, setValue] = useState('1234.56');
+    const handleChange = (val: string) => {
+      setValue(val);
+    };
+    return <CurrencyInput {...args} value={value} onChangeText={handleChange} />;
+  },
+};
+
+export const States: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => {
+    return (
+      <Flex direction="column" space="lg">
+        <VariantTitle title="Default">
+          <CurrencyInput />
+        </VariantTitle>
+        <VariantTitle title="With placeholder">
+          <CurrencyInput placeholder="0.00" />
+        </VariantTitle>
+        <VariantTitle title="Focused">
+          <CurrencyInput focused value="12.34" />
+        </VariantTitle>
+        <VariantTitle title="Valid">
+          <CurrencyInput validationStatus="valid" />
+        </VariantTitle>
+        <VariantTitle title="Invalid">
+          <CurrencyInput validationStatus="invalid" />
+        </VariantTitle>
+        <VariantTitle title="Valid - Focused">
+          <CurrencyInput validationStatus="valid" focused />
+        </VariantTitle>
+        <VariantTitle title="Invalid - Focused">
+          <CurrencyInput validationStatus="invalid" focused />
+        </VariantTitle>
+        <VariantTitle title="Disabled">
+          <CurrencyInput disabled />
+        </VariantTitle>
+        <VariantTitle title="Readonly">
+          <CurrencyInput readonly />
+        </VariantTitle>
+        <VariantTitle title="Auto format thousands">
+          <CurrencyInput autoFormatThousands value="1234.56" />
+        </VariantTitle>
+      </Flex>
+    );
+  },
+};

package/src/components/CurrencyInput/CurrencyInput.tsx

@@ -0,0 +1,91 @@
+import { Platform } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { formatThousands } from '../../utils';
+import { DetailText } from '../DetailText';
+import { useFormFieldContext } from '../FormField';
+import { Input, InputField, InputSlot } from '../Input';
+import type CurrencyInputProps from './CurrencyInput.props';
+
+const CurrencyInput = ({
+  validationStatus = 'initial',
+  disabled,
+  focused,
+  readonly,
+  placeholder,
+  inBottomSheet = false,
+  required,
+  autoFormatThousands = false,
+  value,
+  onChangeText,
+  ...rest
+}: CurrencyInputProps) => {
+  const formFieldContext = useFormFieldContext();
+  const { disabled: formFieldDisabled } = formFieldContext;
+  const validationStatusFromContext = formFieldContext?.validationStatus ?? validationStatus;
+
+  const defaultFormat = '0.00';
+  const getPlaceholder = placeholder ?? defaultFormat;
+
+  const handleChangeText = (text: string) => {
+    if (autoFormatThousands) {
+      const formatted = formatThousands(text);
+      onChangeText?.(formatted);
+    } else {
+      onChangeText?.(text);
+    }
+  };
+
+  const displayValue =
+    autoFormatThousands && typeof value === 'string' ? formatThousands(value) : value;
+
+  return (
+    <Input
+      validationStatus={validationStatusFromContext}
+      disabled={formFieldDisabled ?? disabled}
+      readonly={readonly}
+      focused={focused}
+      style={styles.wrap}
+    >
+      <InputSlot>
+        <DetailText size="4xl" style={styles.text}>
+          £
+        </DetailText>
+      </InputSlot>
+      <InputField
+        inputMode="decimal"
+        inBottomSheet={inBottomSheet}
+        {...rest}
+        placeholder={getPlaceholder}
+        keyboardType="decimal-pad"
+        style={styles.input}
+        value={displayValue as any}
+        onChangeText={handleChangeText}
+      />
+    </Input>
+  );
+};
+
+CurrencyInput.displayName = 'CurrencyInput';
+
+const styles = StyleSheet.create(theme => ({
+  wrap: {
+    height: theme.components.input.currency.height,
+    gap: theme.components.input.currency.gap,
+  },
+  text: {
+    ...(Platform.OS === 'ios' && { lineHeight: 46 }),
+    _web: {
+      marginTop: 1,
+    },
+  },
+  input: {
+    fontSize: theme.typography.mobile.detailText['4xl'].fontSize,
+    fontFamily: theme.typography.mobile.detailText.fontFamily,
+    fontWeight: theme.typography.mobile.detailText.fontWeight,
+    paddingTop: 0,
+    paddingBottom: 0,
+    paddingLeft: 0,
+  },
+}));
+
+export default CurrencyInput;

package/src/components/CurrencyInput/index.ts

@@ -0,0 +1 @@
+export { default as CurrencyInput } from './CurrencyInput';

package/src/components/DescriptionList/DescriptionList.context.ts

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react';
+
+export interface DescriptionListContextValue {
+  direction: 'row' | 'column';
+  itemHeadingWidth?: number;
+}
+
+export const DescriptionListContext = createContext<DescriptionListContextValue | undefined>(
+  undefined
+);
+
+export const useDescriptionListContext = () => {
+  const ctx = useContext(DescriptionListContext);
+  if (!ctx) {
+    throw new Error('DescriptionListItem must be used within a DescriptionList');
+  }
+  return ctx;
+};

package/src/components/DescriptionList/DescriptionList.docs.mdx

@@ -0,0 +1,98 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { DescriptionList, DescriptionListItem } from '../../';
+import { BackToTopButton, UsageWrap } from '../../../docs/components';
+import * as Stories from './DescriptionList.stories';
+
+<BackToTopButton />
+
+<Meta title="Components / Description List" />
+
+# Description List
+
+Display pairs of related metadata (heading + description). Supports column (stacked) and row (two-column) layouts, optional SectionHeader (heading + helper text), and per-item action links.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Variants](#variants)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <DescriptionList
+    direction="column"
+    heading="Account details"
+    helperText="Static account metadata"
+  >
+    <DescriptionListItem heading="Account Number" description="123456789" />
+    <DescriptionListItem heading="Sort Code" description="12-34-56" />
+    <DescriptionListItem heading="Status" description="Active" />
+  </DescriptionList>
+</UsageWrap>
+
+```tsx
+import { DescriptionList, DescriptionListItem } from '@utilitywarehouse/hearth-react-native';
+
+<DescriptionList direction="column" heading="Account details" helperText="Static account metadata">
+  <DescriptionListItem heading="Account Number" description="123456789" />
+  <DescriptionListItem heading="Sort Code" description="12-34-56" />
+  <DescriptionListItem heading="Status" description="Active" />
+</DescriptionList>;
+```
+
+## Props
+
+### DescriptionList
+
+| Prop               | Type                                         | Description                                      | Default     |
+| ------------------ | -------------------------------------------- | ------------------------------------------------ | ----------- |
+| `direction`        | `'row' \| 'column'`                          | Layout orientation                               | `column`    |
+| `itemHeadingWidth` | `number`                                     | Override heading column width in row layout      | token value |
+| `heading`          | `string`                                     | Optional overall heading (renders SectionHeader) | -           |
+| `helperText`       | `string`                                     | Supporting text under heading                    | -           |
+| `linkText`         | `string`                                     | Section header link text                         | -           |
+| `linkHref`         | `string`                                     | Header link URL (web)                            | -           |
+| `linkIcon`         | `ComponentType`                              | Header link icon                                 | -           |
+| `linkIconPosition` | `'left' \| 'right'`                          | Header link icon position                        | `right`     |
+| `linkOnPress`      | `() => void`                                 | Header link press handler                        | -           |
+| `linkTarget`       | `'_blank' \| '_self' \| '_parent' \| '_top'` | Header link target                               | `_self`     |
+| `linkShowIcon`     | `boolean`                                    | Whether header link icon is shown                | `false`     |
+
+### DescriptionListItem
+
+| Prop               | Type                                         | Description                                  | Default    |
+| ------------------ | -------------------------------------------- | -------------------------------------------- | ---------- |
+| `heading`          | `ReactNode`                                  | Heading (label) content                      | (required) |
+| `description`      | `ReactNode`                                  | Description (value) content                  | (required) |
+| `headingWidth`     | `number`                                     | Per-item heading width override (row layout) | inherits   |
+| `linkText`         | `string`                                     | Inline action link text                      | -          |
+| `linkHref`         | `string`                                     | Inline action link URL (web)                 | -          |
+| `linkIcon`         | `ComponentType`                              | Inline action link icon                      | -          |
+| `linkIconPosition` | `'left' \| 'right'`                          | Inline link icon position                    | `right`    |
+| `linkOnPress`      | `() => void`                                 | Inline link press handler                    | -          |
+| `linkTarget`       | `'_blank' \| '_self' \| '_parent' \| '_top'` | Inline link target                           | `_self`    |
+| `linkShowIcon`     | `boolean`                                    | Show inline link icon                        | `false`    |
+
+> Uses `theme.components.descriptionList` tokens for spacing & column width.
+
+## Variants
+
+<Canvas of={Stories.KitchenSink} />
+<Canvas of={Stories.WithLinks} />
+
+## Accessibility
+
+The component applies the following roles:
+
+| Element                       | Role                                  |
+| ----------------------------- | ------------------------------------- |
+| `DescriptionList` root        | `list`                                |
+| `DescriptionListItem` wrapper | `text` (combined label when possible) |
+
+When both heading and description are plain text they are merged into one accessibility node (e.g. “Account Number: 123456789”) and the child elements are hidden from the a11y tree to avoid duplicate reading (TalkBack / VoiceOver). If either part is non‑text the children remain individually exposed.

package/src/components/DescriptionList/DescriptionList.props.ts

@@ -0,0 +1,20 @@
+import { ComponentType } from 'react';
+import type { ViewProps } from 'react-native';
+
+export interface DescriptionListProps extends ViewProps {
+  /** Direction orientation for items */
+  direction?: 'row' | 'column';
+  /** Override heading/term column width when layout is row (defaults to token) */
+  itemHeadingWidth?: number;
+  heading?: string;
+  helperText?: string;
+  linkText?: string;
+  linkHref?: string;
+  linkIcon?: ComponentType;
+  linkIconPosition?: 'left' | 'right';
+  linkOnPress?: () => void;
+  linkTarget?: '_blank' | '_self' | '_parent' | '_top';
+  linkShowIcon?: boolean;
+}
+
+export default DescriptionListProps;

package/src/components/DescriptionList/DescriptionList.stories.tsx

@@ -0,0 +1,154 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { DescriptionList, DescriptionListItem } from '.';
+import { VariantTitle } from '../../../docs/components';
+import { Flex } from '../Flex';
+
+const meta: Meta<typeof DescriptionList> = {
+  title: 'Stories / DescriptionList',
+  component: DescriptionList,
+  parameters: { layout: 'centered' },
+  argTypes: {
+    direction: {
+      control: 'select',
+      options: ['row', 'column'],
+      description: 'Orientation of heading & description pairs',
+    },
+    itemHeadingWidth: {
+      control: 'number',
+      description: 'Override width (px) for heading column when direction is row',
+    },
+    heading: {
+      control: 'text',
+      description:
+        'Optional overall heading (renders a SectionHeader). Playground only – prefer SectionHeader directly when composing.',
+    },
+    helperText: {
+      control: 'text',
+      description: 'Supporting text shown under heading (Playground only).',
+    },
+    linkText: { control: 'text', description: 'Header link text (Playground only).' },
+    linkHref: { control: 'text', description: 'Header link href (web).' },
+    linkIconPosition: {
+      control: 'select',
+      options: ['left', 'right'],
+      description: 'Header link icon position.',
+    },
+    linkShowIcon: { control: 'boolean', description: 'Show header link icon.' },
+    linkTarget: {
+      control: 'select',
+      options: ['_blank', '_self', '_parent', '_top'],
+      description: 'Header link target (web).',
+    },
+  },
+  args: {
+    direction: 'column',
+    heading: 'Account details',
+    helperText: 'Static account metadata',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const sampleData = [
+  { heading: 'Account Number', description: '123456789' },
+  { heading: 'Sort Code', description: '12-34-56' },
+  { heading: 'Status', description: 'Active' },
+];
+
+export const Playground: Story = {
+  render: args => (
+    <DescriptionList {...args}>
+      {sampleData.map(item => (
+        <DescriptionListItem
+          key={item.heading}
+          heading={item.heading}
+          description={item.description}
+        />
+      ))}
+    </DescriptionList>
+  ),
+};
+
+export const Row: Story = {
+  args: { direction: 'row' },
+  render: args => (
+    <DescriptionList {...args}>
+      {sampleData.map(item => (
+        <DescriptionListItem
+          key={item.heading}
+          heading={item.heading}
+          description={item.description}
+        />
+      ))}
+    </DescriptionList>
+  ),
+};
+
+export const Column: Story = {
+  args: { direction: 'column' },
+  render: args => (
+    <DescriptionList {...args}>
+      {sampleData.map(item => (
+        <DescriptionListItem
+          key={item.heading}
+          heading={item.heading}
+          description={item.description}
+        />
+      ))}
+    </DescriptionList>
+  ),
+};
+
+export const KitchenSink: Story = {
+  parameters: { controls: { include: [] } },
+  render: () => (
+    <Flex direction="column" space="lg" style={{ width: '100%' }}>
+      <VariantTitle title="Row direction">
+        <DescriptionList direction="row">
+          {sampleData.map(item => (
+            <DescriptionListItem
+              key={item.heading}
+              heading={item.heading}
+              description={item.description}
+            />
+          ))}
+        </DescriptionList>
+      </VariantTitle>
+      <VariantTitle title="Column direction">
+        <DescriptionList direction="column">
+          {sampleData.map(item => (
+            <DescriptionListItem
+              key={item.heading}
+              heading={item.heading}
+              description={item.description}
+            />
+          ))}
+        </DescriptionList>
+      </VariantTitle>
+    </Flex>
+  ),
+};
+
+export const WithLinks: Story = {
+  parameters: { controls: { include: ['direction', 'itemHeadingWidth'] } },
+  args: { direction: 'row' },
+  render: args => (
+    <DescriptionList {...args}>
+      <DescriptionListItem
+        heading="Account Number"
+        description="123456789"
+        linkText="Manage"
+        linkHref="https://example.com/account"
+        linkShowIcon
+      />
+      <DescriptionListItem
+        heading="Status"
+        description="Active"
+        linkText="Change"
+        linkHref="https://example.com/status"
+      />
+      <DescriptionListItem heading="Region" description="United Kingdom" />
+    </DescriptionList>
+  ),
+};