@utilitywarehouse/hearth-react-native 0.1.0

package/src/components/Radio/Radio.docs.mdx

@@ -0,0 +1,366 @@
+import { Meta, Canvas, Story, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './Radio.stories';
+import {
+  Radio,
+  RadioGroup,
+  RadioIndicator,
+  RadioIcon,
+  RadioLabel,
+  Center,
+  Box,
+  RadioTile,
+} from '../../';
+import { TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import {
+  ViewFigmaButton,
+  BackToTopButton,
+  UsageWrap,
+  AdvancedRadioExample,
+} from '../../../docs/components';
+
+<Meta title="Forms / Radio" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/3RY3OvLA88yZksRjOfjQJm/UW-App-UI?node-id=4454-2232" />
+
+# Radio
+
+The Radio component presents users with predefined choices and enables them to select only one option. It is commonly used for providing a single-choice selection in forms or surveys.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Components](#components)
+  - [`Radio`](#radio)
+  - [`RadioTile`](#radiotile)
+  - [`RadioIndicator`](#radioindicator)
+  - [`RadioIcon`](#radioicon)
+  - [`RadioLabel`](#radiolabel)
+  - [`RadioGroup`](#radiogroup)
+- [Variants](#variants)
+- [Advanced Usage](#advanced-usage)
+- [Examples](#examples)
+  - [`RadioTile` component](#radiotile-component)
+  - [`RadioGroup` component](#radiogroup-component)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+- A `Radio` component is composed of a `RadioGroup`, `RadioIndicator`, `RadioLabel`.
+- `Radio` is used for a single selection
+- `RadioGroup` is the building block for `Radio`
+
+<UsageWrap>
+  <Center>
+    <RadioGroup aria-label="Radio Group" nativeID="Radio-group">
+      <Radio
+        value="Label 1"
+        aria-label="Label 1"
+        label="Option 1"
+      />
+      <Radio
+        value="Label 2"
+        aria-label="Label 2"
+        label="Option 2"
+      />
+    </RadioGroup>
+
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Radio, RadioGroup, RadioLabel, RadioIndicator } from '@utilitywarehouse/native-ui';
+
+const MyComponent = () => {
+  const [value, setValue] = React.useState('Option 1');
+  return (
+    <RadioGroup aria-label="Radio Group" value={value} onChange={setValue} nativeID="Radio-group">
+      <Radio value="Option 1" aria-label="Option 1" label="Option 1" />
+      <Radio value="Option 2" aria-label="Option 2" label="Option 2" />
+    </RadioGroup>
+  );
+};
+```
+
+## Props
+
+| Property             | Type                                | Default   | Description                                                                                          |
+| -------------------- | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `value`              | string                              | -         | The value to be used in the radio input. This is the value that will be returned on form submission. |
+| `onChange`           | function                            | -         | Function called when the state of the radio changes.                                                 |
+| `disabled`           | bool                                | false     | To manually set disable to the radio.                                                                |
+| `validationStatus`   | `'valid' \| 'invalid' \| 'initial'` | -         | The validation status of the radio.                                                                  |
+| `disabled`           | `bool`                              | `false`   | To manually set disable to the radio.                                                                |
+| `label`              | `string`                            | -         | The label to be displayed next to the radio.                                                         |
+| `helperText`         | `string`                            | -         | The helper text to be displayed below the radio.                                                     |
+| `helperIcon`         | `React.ComponentType`               | -         | The icon to be displayed next to the helper text.                                                    |
+| `invalidText`        | `string`                            | -         | The invalid text to be displayed below the radio.                                                    |
+| `validText`          | `string`                            | -         | The valid text to be displayed below the radio.                                                      |
+| `showValidationIcon` | `boolean`                           | `true`    | Whether to show the validation icon.                                                                 |
+| `type`               | `'default' \| 'tile'`               | `default` | The type of the radio.                                                                               |
+
+## Components
+
+### `Radio`
+
+Contains all Radio related layout style props and actions. It inherits all the properties of React Native's [View component](https://reactnative.dev/docs/view).
+
+### `RadioTile`
+
+Contains all Radio related layout style props and actions. It inherits all the properties of React Native's [View component](https://reactnative.dev/docs/view).
+
+### `RadioIndicator`
+
+Contains all Indicator related layout style props and actions. It inherits all the properties of React Native's [View component](https://reactnative.dev/docs/view).
+
+### `RadioIcon`
+
+Contains all Icon related layout style props and actions.
+
+### `RadioLabel`
+
+Contains all Label related layout style props and actions. It inherits all the properties of React Native's [Text component](https://reactnative.dev/docs/text).
+
+### `RadioGroup`
+
+Contains all Group related layout style props and actions. It inherits all the properties of React Native's [View component](https://reactnative.dev/docs/view).
+
+| Property             | Type                                | Default   | Description                                                         |
+| -------------------- | ----------------------------------- | --------- | ------------------------------------------------------------------- |
+| `value`              | string                              | -         | The value of the radio group.                                       |
+| `onChange`           | function                            | -         | The callback fired when any children Radio is checked or unchecked. |
+| `disabled`           | bool                                | -         | To manually set disable to the radio group.                         |
+| `validationStatus`   | `'valid' \| 'invalid' \| 'initial'` | -         | The validation status of the radio group.                           |
+| `label`              | `string`                            | -         | The label to be displayed above the radio group.                    |
+| `helperText`         | `string`                            | -         | The helper text to be displayed below the radio group.              |
+| `helperIcon`         | `React.ComponentType`               | -         | The icon to be displayed next to the helper text.                   |
+| `invalidText`        | `string`                            | -         | The invalid text to be displayed below the radio group.             |
+| `validText`          | `string`                            | -         | The valid text to be displayed below the radio group.               |
+| `showValidationIcon` | `boolean`                           | `true`    | Whether to show the validation icon.                                |
+| `type`               | `'default' \| 'tile'`               | `default` | The type of the radio group.                                        |
+| `direction`          | `'row' \| 'column'`                 | `column`  | The direction of the radio group.                                   |
+| `gap`                | `string`                            | -         | The gap between the radio group items.                              |
+
+## Variants
+
+<Canvas of={Stories.Variants} />
+
+## Advanced Usage
+
+There may be cases where you need to customise the Radio component to fit your design requirements.
+In this example, we will create a custom Radio component with a badge and bullet list.
+
+<UsageWrap>
+  <Center>
+    <AdvancedRadioExample />
+  </Center>
+</UsageWrap>
+
+```tsx
+import {
+  Badge,
+  Heading,
+  Radio,
+  RadioGroup,
+  RadioIcon,
+  RadioIndicator,
+  BodyText,
+  Box,
+  type RadioProps as NativeUIRadioProps,
+} from '../../src';
+import { TickSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+import { StyleSheet } from 'react-native-unistyles';
+
+interface RadioProps {
+  currentValue: string;
+}
+
+const styles = StyleSheet.create(({ colorMode, color, borderRadius, borderWidth, space }) => ({
+  radio: {
+    borderWidth: borderWidth[2],
+    borderColor: colorMode === 'light' ? color.grey[500] : color.grey[700],
+    borderRadius: borderRadius.xl,
+    padding: space[200],
+    variants: {
+      checked: {
+        true: {
+          borderColor: colorMode === 'light' ? color.green[500] : color.green[700],
+        },
+      },
+    },
+  },
+  indicator: {
+    variants: {
+      checked: {
+        true: {
+          backgroundColor: colorMode === 'light' ? color.green[500] : color.green[700],
+          borderColor: colorMode === 'light' ? color.green[500] : color.green[700],
+        },
+      },
+    },
+  },
+  heading: {
+    marginBottom: space[100],
+  },
+  badge: {
+    marginRight: space[200],
+    alignSelf: 'flex-end',
+  },
+}));
+
+const CustomRadio: React.FC<
+  RadioProps &
+    Omit<
+      NativeUIRadioProps,
+      'label' | 'helperText' | 'helperIcon' | 'invalidText' | 'validText' | 'showValidationIcon'
+    >
+> = ({ children, currentValue, ...props }) => {
+  styles.useVariants({ checked: currentValue === props.value });
+  return (
+    <Radio style={styles.radio} {...props}>
+      <Box flexDirection="row" flex={1}>
+        <Box pr="200" flex={1}>
+          {children}
+        </Box>
+        <RadioIndicator style={styles.indicator}>
+          <RadioIcon as={TickSmallIcon} color="white" />
+        </RadioIndicator>
+      </Box>
+    </Radio>
+  );
+};
+
+const BulletListItem = ({ children }: { children: React.ReactNode }) => (
+  <BodyText>
+    {'\u2022'} {children}
+  </BodyText>
+);
+
+const BulletList = ({ children }: { children: React.ReactNode }) => (
+  <Box pl="200" gap="100">
+    {children}
+  </Box>
+);
+
+const AdvancedRadioExample: React.FC = () => {
+  const [value, setValue] = React.useState('Option 1');
+
+  const handleChange = (val: string) => setValue(val);
+
+  return (
+    <RadioGroup onChange={handleChange} value={value} gap="200">
+      <Box>
+        <Badge colorScheme={value === 'Option 1' ? 'green' : 'grey'} flatBase style={styles.badge}>
+          Recommended
+        </Badge>
+        <CustomRadio value="Option 1" currentValue={value}>
+          <Heading size="md" style={styles.heading}>
+            Instant bank transfer
+          </Heading>
+          <BulletList>
+            <BulletListItem>Receive your money instantly</BulletListItem>
+            <BulletListItem>No fees</BulletListItem>
+            <BulletListItem>Available 24/7</BulletListItem>
+          </BulletList>
+        </CustomRadio>
+      </Box>
+      <CustomRadio value="Option 2" currentValue={value}>
+        <Heading size="md" style={styles.heading}>
+          Debit card payment
+        </Heading>
+        <BulletList>
+          <BulletListItem>£0.35 fee</BulletListItem>
+          <BulletListItem>Available 24/7</BulletListItem>
+        </BulletList>
+      </CustomRadio>
+    </RadioGroup>
+  );
+};
+
+export default AdvancedRadioExample;
+```
+
+## Examples
+
+### `RadioTile` component
+
+The `RadioTile` component is a variant of the `Radio` component that displays the radio button as a card.
+It is used to present options in a more visually appealing way.
+
+<UsageWrap>
+  <Center>
+    <RadioGroup>
+      <RadioTile value="option-1" aria-label="Label 1" label="Option 1" />
+      <RadioTile value="option-2" aria-label="Label 2" label="Option 2" />
+    </RadioGroup>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { RadioTile, RadioGroup } from '@utilitywarehouse/native-ui';
+
+const MyComponent = () => {
+  const [value, setValue] = React.useState('option-1');
+  return (
+    <RadioGroup value={value} onChange={setValue}>
+      <RadioTile value="option-1" aria-label="Label 1" label="Option 1" />
+      <RadioTile value="option-2" aria-label="Label 2" label="Option 2" />
+    </RadioGroup>
+  );
+};
+```
+
+### `RadioGroup` component
+
+The `RadioGroup` component is used to group multiple `Radio` components together.
+You can pass props like `label` and `helperText` to the `RadioGroup` component to provide context for the group of radios.
+
+<UsageWrap>
+  <Center>
+    <RadioGroup
+      aria-label="Radio Group"
+      label="Radio Group Label"
+      helperText="This is the supporting text"
+      invalidText="This is an invalid text"
+      validText="This is a valid text"
+      validationStatus="invalid"
+    >
+      <Radio value="option-1" aria-label="Label 1" label="Option 1" />
+      <Radio value="option-2" aria-label="Label 2" label="Option 2" />
+      <Radio value="option-3" aria-label="Label 3" label="Option 3" />
+      <Radio value="option-4" aria-label="Label 4" label="Option 4" />
+    </RadioGroup>
+
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Radio, RadioGroup } from '@utilitywarehouse/native-ui';
+
+const MyComponent = () => {
+  const [value, setValue] = React.useState('option-1');
+  return (
+    <RadioGroup
+      aria-label="Radio Group"
+      value={value}
+      onChange={setValue}
+      label="Radio Group Label"
+      helperText="This is the supporting text"
+      invalidText="This is an invalid text"
+      validText="This is a valid text"
+    >
+      <Radio value="option-1" aria-label="Label 1" label="Option 1" />
+      <Radio value="option-2" aria-label="Label 2" label="Option 2" />
+      <Radio value="option-3" aria-label="Label 3" label="Option 3" />
+      <Radio value="option-4" aria-label="Label 4" label="Option 4" />
+    </RadioGroup>
+  );
+};
+```

package/src/components/Radio/Radio.figma.tsx

@@ -0,0 +1,45 @@
+import figma from '@figma/code-connect';
+import { Radio, RadioGroup } from './';
+
+const value = 'some-value';
+const setValue = (value: string) => console.log(value);
+
+figma.connect(
+  Radio,
+  'https://www.figma.com/design/3RY3OvLA88yZksRjOfjQJm/UW-App-UI?node-id=5626-1463&m=dev',
+  {
+    props: {
+      disabled: figma.boolean('disabled'),
+      label: figma.nestedProps('Label', {
+        text: figma.string('Label Text'),
+      }),
+      helperText: figma.nestedProps('Helper Text', {
+        text: figma.string('Text'),
+      }),
+      invalidText: figma.boolean('invalid', {
+        true: figma.nestedProps('Helper Text', {
+          text: figma.string('Text'),
+          showIcon: figma.boolean('showIcon?'),
+        }),
+        false: {
+          text: undefined,
+          showIcon: undefined,
+        },
+      }),
+    },
+    example: ({ disabled, label, helperText, invalidText }) => (
+      <RadioGroup value={value} onChange={setValue}>
+        <Radio
+          value="someValue"
+          disabled={disabled}
+          label={label.text}
+          helperText={helperText.text}
+          invalidText={invalidText.text}
+          showValidationIcon={invalidText.showIcon}
+        />
+      </RadioGroup>
+    ),
+  }
+);
+
+// TODO: Add variants with helperText when it's implemented

package/src/components/Radio/Radio.props.ts

@@ -0,0 +1,34 @@
+import type { ComponentType } from 'react';
+import type { PressableProps, ViewProps } from 'react-native';
+
+interface RadioBaseProps extends Omit<PressableProps, 'children'> {
+  value: string;
+  onChange?: (isSelected: boolean) => void;
+  disabled?: boolean;
+  validationStatus?: 'valid' | 'invalid' | 'initial';
+  type?: 'default' | 'tile';
+}
+
+interface RadioWithChildrenProps extends RadioBaseProps {
+  children: ViewProps['children'];
+  label?: never;
+  helperText?: never;
+  helperIcon?: never;
+  invalidText?: never;
+  validText?: never;
+  showValidationIcon?: never;
+}
+
+interface RadioWithoutChildrenProps extends RadioBaseProps {
+  children?: never;
+  label?: string;
+  helperText?: string;
+  helperIcon?: ComponentType;
+  invalidText?: string;
+  validText?: string;
+  showValidationIcon?: boolean;
+}
+
+type RadioProps = RadioWithChildrenProps | RadioWithoutChildrenProps;
+
+export default RadioProps;

package/src/components/Radio/Radio.stories.tsx

@@ -0,0 +1,157 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { Radio, RadioGroup } from '.';
+import { VariantTitle } from '../../../docs/components';
+import { Flex } from '../Flex';
+
+const meta = {
+  title: 'Stories / Radio',
+  component: Radio,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    disabled: {
+      type: 'boolean',
+      control: 'boolean',
+      description: 'To manually set disable to the radio.',
+    },
+    label: {
+      type: 'string',
+      control: 'text',
+      description: 'The label component for the radio.',
+    },
+    helperText: {
+      type: 'string',
+      control: 'text',
+      description: 'The helper text of the radio component',
+      defaultValue: 'Helper text',
+    },
+    validationStatus: {
+      control: 'select',
+      options: ['initial', 'valid', 'invalid'],
+      description: 'The validation status of the radio component',
+      defaultValue: 'initial',
+    },
+    showValidationIcon: {
+      control: 'boolean',
+      description: 'Show the validation icon.',
+      defaultValue: true,
+    },
+    invalidText: {
+      control: 'text',
+      description: 'The invalid text of the radio component',
+      defaultValue: 'Invalid text',
+    },
+    type: {
+      control: 'select',
+      options: ['default', 'tile'],
+      description: 'The type of the radio component',
+      defaultValue: 'default',
+    },
+  },
+  args: {
+    disabled: false,
+    label: '',
+    helperText: '',
+    validationStatus: 'initial',
+    showValidationIcon: true,
+    invalidText: 'Invalid text',
+    validText: 'Valid text',
+    type: 'default',
+  },
+} satisfies Meta<typeof Radio>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    value: 'Option 1',
+    label: 'Label',
+  },
+  render: args => (
+    <RadioGroup>
+      <Radio
+        aria-label="Label 1"
+        onChange={(checked: boolean) => {
+          console.log(checked, '###');
+        }}
+        nativeID="Radio-1"
+        {...args}
+      />
+    </RadioGroup>
+  ),
+};
+
+export const Variants: Story = {
+  parameters: {
+    controls: { exclude: ['value', 'label', 'disabled'] },
+  },
+  args: {
+    value: 'Option 1',
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ value: _, children: __, label: ___, disabled: _____, onChange: ______, ...args }) => {
+    const [value, setValue] = useState('Option 1');
+    return (
+      <Flex space="lg">
+        <VariantTitle title="Default">
+          <RadioGroup
+            aria-label="Radio Group"
+            value={value}
+            onChange={setValue}
+            nativeID="Radio-group"
+          >
+            <Radio
+              value="Option 1"
+              aria-label="Option 1"
+              onChange={(checked: boolean) => {
+                console.log(checked, '###');
+              }}
+              nativeID="Radio-1"
+              label="Option 1"
+              {...args}
+            />
+            <Radio
+              value="Option 2"
+              aria-label="Option 2"
+              onChange={(checked: boolean) => {
+                console.log(checked, '###');
+              }}
+              nativeID="Radio-2"
+              label="Option 2"
+              {...args}
+            />
+          </RadioGroup>
+        </VariantTitle>
+        <VariantTitle title="Disabled">
+          <RadioGroup
+            aria-label="Radio Group"
+            value={value}
+            onChange={setValue}
+            nativeID="Radio-group"
+            disabled
+          >
+            <Radio
+              aria-label="Option 3"
+              value="Option 1"
+              onChange={(checked: boolean) => console.log(checked, '###')}
+              nativeID="Radio-3"
+              label="Option 1"
+              {...args}
+            />
+            <Radio
+              aria-label="Option 4"
+              value="Option 2"
+              onChange={(checked: boolean) => console.log(checked, '###')}
+              nativeID="Radio-4"
+              label="Option 2"
+              {...args}
+            />
+          </RadioGroup>
+        </VariantTitle>
+      </Flex>
+    );
+  },
+};

package/src/components/Radio/Radio.tsx

@@ -0,0 +1,94 @@
+import { createRadio } from '@gluestack-ui/radio';
+import StyledRadio from './RadioRoot';
+import StyledRadioIndicator from './RadioIndicator';
+import StyledRadioIcon from './RadioIcon';
+import StyledRadioLabel from './RadioLabel';
+import StyledRadioGroup from './RadioGroupRoot';
+import RadioProps from './Radio.props';
+
+import { Helper } from '../Helper';
+import { useRadioGroupContext } from './RadioGroup.context';
+import { useFormFieldContext } from '../FormField';
+import RadioTileRoot from './RadioTileRoot';
+import RadioTextContent from './RadioTextContent';
+
+const RadioComponent = createRadio({
+  Root: StyledRadio,
+  Group: StyledRadioGroup,
+  Indicator: StyledRadioIndicator,
+  Icon: StyledRadioIcon,
+  Label: StyledRadioLabel,
+});
+
+const RadioGroup = RadioComponent.Group;
+const RadioIndicator = RadioComponent.Indicator;
+const RadioIcon = RadioComponent.Icon;
+const RadioLabel = RadioComponent.Label;
+
+RadioGroup.displayName = 'RadioGroup';
+RadioIndicator.displayName = 'RadioIndicator';
+RadioIcon.displayName = 'RadioIcon';
+RadioLabel.displayName = 'RadioLabel';
+
+const Radio = ({
+  children,
+  label,
+  disabled,
+  helperIcon,
+  helperText,
+  invalidText,
+  validText,
+  validationStatus: validation,
+  showValidationIcon,
+  type = 'default',
+  ...props
+}: RadioProps) => {
+  const { validationStatus: fieldValidationStatus } = useFormFieldContext();
+  const { validationStatus: groupValidationStatus, type: groupType } = useRadioGroupContext();
+  const validationStatus =
+    fieldValidationStatus ?? groupValidationStatus ?? validation ?? 'initial';
+  const radioType = groupType ?? type;
+  const radioChildren = children ? (
+    children
+  ) : (
+    <>
+      <RadioIndicator>
+        <RadioIcon />
+      </RadioIndicator>
+      <RadioTextContent>
+        {!!label && <RadioLabel>{label}</RadioLabel>}
+        {!!helperText && <Helper disabled={disabled} icon={helperIcon} text={helperText} />}
+        {validationStatus === 'invalid' && !!invalidText && (
+          <Helper
+            showIcon={showValidationIcon}
+            disabled={disabled}
+            validationStatus="invalid"
+            text={invalidText}
+          />
+        )}
+        {validationStatus === 'valid' && !!validText && (
+          <Helper
+            disabled={disabled}
+            showIcon={showValidationIcon}
+            validationStatus="valid"
+            text={validText}
+          />
+        )}
+      </RadioTextContent>
+    </>
+  );
+  return (
+    <RadioComponent {...props} isDisabled={disabled}>
+      {radioType === 'tile' ? <RadioTileRoot>{radioChildren}</RadioTileRoot> : radioChildren}
+    </RadioComponent>
+  );
+};
+
+const RadioTile = ({ type = 'tile', ...props }: RadioProps) => <Radio {...props} type={type} />;
+
+RadioTile.displayName = 'RadioTile';
+Radio.displayName = 'Radio';
+
+export { Radio, RadioGroup, RadioIndicator, RadioIcon, RadioLabel, RadioTile };
+
+export default Radio;