@utilitywarehouse/hearth-react-native 0.2.0 → 0.3.1

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

package/src/components/DescriptionList/DescriptionList.tsx

@@ -0,0 +1,64 @@
+import { useMemo } from 'react';
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { SectionHeader } from '../SectionHeader';
+import { DescriptionListContext } from './DescriptionList.context';
+import type DescriptionListProps from './DescriptionList.props';
+
+const DescriptionList = ({
+  direction = 'column',
+  itemHeadingWidth,
+  heading,
+  helperText,
+  linkText,
+  linkHref,
+  linkIcon,
+  linkIconPosition,
+  linkOnPress,
+  linkTarget,
+  linkShowIcon,
+  children,
+  style,
+  ...props
+}: DescriptionListProps) => {
+  styles.useVariants({ direction });
+  const value = useMemo(() => ({ direction, itemHeadingWidth }), [direction, itemHeadingWidth]);
+
+  return (
+    <DescriptionListContext.Provider value={value}>
+      <View accessibilityRole="list" {...props} style={[styles.container, style]}>
+        {heading ? (
+          <SectionHeader
+            heading={heading}
+            helperText={helperText}
+            linkText={linkText}
+            linkHref={linkHref}
+            linkIcon={linkIcon}
+            linkIconPosition={linkIconPosition}
+            linkOnPress={linkOnPress}
+            linkTarget={linkTarget}
+            linkShowIcon={linkShowIcon}
+          />
+        ) : null}
+        {children}
+      </View>
+    </DescriptionListContext.Provider>
+  );
+};
+
+DescriptionList.displayName = 'DescriptionList';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    width: theme.space.full,
+    gap: theme.components.descriptionList.gap,
+    variants: {
+      direction: {
+        row: {},
+        column: {},
+      },
+    },
+  },
+}));
+
+export default DescriptionList;

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

@@ -0,0 +1,19 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+
+export interface DescriptionListItemProps extends ViewProps {
+  /** Heading / label part */
+  heading: ReactNode;
+  /** Description / value part */
+  description: ReactNode;
+  headingWidth?: number;
+  linkText?: string;
+  linkHref?: string;
+  linkIcon?: ComponentType;
+  linkIconPosition?: 'left' | 'right';
+  linkOnPress?: () => void;
+  linkTarget?: '_blank' | '_self' | '_parent' | '_top';
+  linkShowIcon?: boolean;
+}
+
+export default DescriptionListItemProps;

package/src/components/DescriptionList/DescriptionListItem.tsx

@@ -0,0 +1,101 @@
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { useTheme } from '../../hooks';
+import { BodyText } from '../BodyText';
+import { Link } from '../Link';
+import { useDescriptionListContext } from './DescriptionList.context';
+import type DescriptionListItemProps from './DescriptionListItem.props';
+
+const DescriptionListItem = ({
+  heading,
+  description,
+  headingWidth,
+  linkText,
+  linkHref,
+  linkIcon,
+  linkIconPosition,
+  linkOnPress,
+  linkTarget,
+  linkShowIcon,
+  style,
+  ...props
+}: DescriptionListItemProps) => {
+  const { components } = useTheme();
+  const { direction, itemHeadingWidth = components.descriptionList.item.row.headingWidth } =
+    useDescriptionListContext();
+  styles.useVariants({ direction });
+  const headingIsText = typeof heading === 'string' || typeof heading === 'number';
+  const descIsText = typeof description === 'string' || typeof description === 'number';
+  const combinedLabel = headingIsText && descIsText ? `${heading}: ${description}` : undefined;
+  const hideDescendants = !!combinedLabel;
+  return (
+    <View
+      accessibilityRole="text"
+      accessible={!!combinedLabel}
+      accessibilityLabel={combinedLabel}
+      {...props}
+      style={[styles.item, style]}
+    >
+      <View
+        style={styles.textWrap}
+        importantForAccessibility={hideDescendants ? 'no-hide-descendants' : undefined}
+        accessibilityElementsHidden={hideDescendants || undefined}
+      >
+        <View style={[direction === 'row' && { width: headingWidth || itemHeadingWidth }]}>
+          {headingIsText ? <BodyText style={styles.headingText}>{heading}</BodyText> : heading}
+        </View>
+        <View style={styles.descriptionWrapper}>
+          {descIsText ? <BodyText>{description}</BodyText> : description}
+        </View>
+      </View>
+      {linkText ? (
+        <Link
+          href={linkHref}
+          onPress={linkOnPress}
+          target={linkTarget}
+          showIcon={linkShowIcon}
+          icon={linkIcon}
+          iconPosition={linkIconPosition}
+          accessibilityRole="link"
+        >
+          {linkText}
+        </Link>
+      ) : null}
+    </View>
+  );
+};
+
+DescriptionListItem.displayName = 'DescriptionListItem';
+
+const styles = StyleSheet.create(theme => ({
+  item: {
+    width: theme.space.full,
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: theme.components.descriptionList.item.gap,
+  },
+  textWrap: {
+    flex: 1,
+    variants: {
+      direction: {
+        row: {
+          flexDirection: 'row',
+          alignItems: 'flex-start',
+          gap: theme.components.descriptionList.item.row.gap,
+        },
+        column: {
+          flexDirection: 'column',
+          gap: theme.components.descriptionList.item.column.gap,
+        },
+      },
+    },
+  },
+  headingText: {
+    color: theme.color.text.secondary,
+  },
+  descriptionWrapper: {
+    flex: 1,
+  },
+}));
+
+export default DescriptionListItem;