@utilitywarehouse/hearth-react-native 0.1.0

package/src/components/Select/Select.docs.mdx

@@ -0,0 +1,218 @@
+import { Meta, Controls, Story, Canvas } from '@storybook/addon-docs/blocks';
+import * as Stories from './Select.stories';
+import { Select, SelectOption, FormField, Center } from '../../';
+import { UserSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { ViewFigmaButton, BackToTopButton, UsageWrap } from '../../../docs/components';
+
+<Meta title="Forms / Select" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=3224-12" />
+
+# Select
+
+The `Select` component creates a dropdown menu that allows users to choose from a list of options. It's commonly used in forms for selecting one option from many.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+  - [`Select`](#select)
+  - [`SelectOption`](#selectoption)
+- [Examples](#examples)
+  - [With `FormField`](#with-formfield)
+  - [Searchable `Select`](#searchable-select)
+  - [Inline `SelectOption`](#inline-selectoption)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Center>
+    <Select
+      label="Choose an option"
+      placeholder="Select an option"
+      options={[
+        { label: 'Option 1', value: '1' },
+        { label: 'Option 2', value: '2' },
+        { label: 'Option 3', value: '3' },
+      ]}
+      value="1"
+      onValueChange={value => console.log('Selected:', value)}
+    />
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Select } from '@utilitywarehouse/hearth-react-native';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const [value, setValue] = useState('1');
+
+  return (
+    <Select
+      label="Choose an option"
+      placeholder="Select an option"
+      options={[
+        { label: 'Option 1', value: '1' },
+        { label: 'Option 2', value: '2' },
+        { label: 'Option 3', value: '3' },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+};
+```
+
+## Props
+
+### `Select`
+
+The `Select` component inherits all of the React Native [`View` props](https://reactnative.dev/docs/view).
+
+| Prop              | Type                                | Default                  | Description                                                |
+| ----------------- | ----------------------------------- | ------------------------ | ---------------------------------------------------------- |
+| options           | SelectOptionProps[]                 | `[]`                     | Array of options to display in the select.                 |
+| value             | string \| null                      | `-`                      | Currently selected value.                                  |
+| onValueChange     | (value: string) => void             | `-`                      | Callback when value changes.                               |
+| label             | string                              | `-`                      | Label for the select.                                      |
+| placeholder       | string                              | `'Select an option'`     | Placeholder text to show when no value is selected.        |
+| disabled          | boolean                             | `false`                  | Whether the select is disabled.                            |
+| readonly          | boolean                             | `false`                  | Whether the select is readonly.                            |
+| leadingIcon       | React.ComponentType                 | `-`                      | Icon to display before the select text.                    |
+| validationStatus  | `'initial' \| 'valid' \| 'invalid'` | `'initial'`              | The validation status of the select.                       |
+| required          | boolean                             | `true`                   | Indicates that the select is required.                     |
+| menuHeading       | string                              | `-`                      | Heading to display at the top of the menu.                 |
+| children          | ReactNode                           | `-`                      | Children to render inside the select (for custom options). |
+| bottomSheetProps  | `BottomSheetProps`                  | `-`                      | Props passed to the BottomSheetModal.                      |
+| emptyText         | string                              | `'No options available'` | Text to display when no options are available.             |
+| listProps         | object                              | `-`                      | Props to be passed to the bottom sheet flat list.          |
+| searchable        | boolean                             | `false`                  | Optional search functionality for the select.              |
+| searchPlaceholder | string                              | `'Search'`               | Search placeholder.                                        |
+
+### `SelectOption`
+
+The `SelectOption` component is used to create individual options within the `Select` component. It can be used inline or as part of the `options` prop.
+
+| Prop         | Type                    | Default | Description                            |
+| ------------ | ----------------------- | ------- | -------------------------------------- |
+| label        | string                  | `-`     | Label to display for this option.      |
+| value        | string                  | `-`     | Value for this option.                 |
+| leadingIcon  | React.ComponentType     | `-`     | Optional left icon for this option.    |
+| trailingIcon | React.ComponentType     | `-`     | Optional right icon for this option.   |
+| selected     | boolean                 | `-`     | Whether this option is selected.       |
+| disabled     | boolean                 | `false` | Whether this option is disabled.       |
+| onPress      | (value: string) => void | `-`     | Callback when this option is selected. |
+
+## Examples
+
+### With `FormField`
+
+The `Select` component can be used with the `FormField` component for additional functionality like validation messages and helper text.
+For more information on the `FormField` component, view the [docs here](/docs/components-form-field--docs).
+
+<Canvas of={Stories.WithValidationStatus} />
+
+```tsx
+import { FormField, Select } from '@utilitywarehouse/hearth-react-native';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const [value, setValue] = useState(null);
+
+  return (
+    <FormField
+      validationStatus="invalid"
+      label="Invalid select"
+      invalidText="Please select a value"
+    >
+      <Select
+        placeholder="Select an option"
+        options={[
+          { label: 'Option 1', value: '1' },
+          { label: 'Option 2', value: '2' },
+          { label: 'Option 3', value: '3' },
+        ]}
+        value={value}
+        onValueChange={setValue}
+      />
+    </FormField>
+  );
+};
+```
+
+### Searchable `Select`
+
+<Canvas of={Stories.Searchable} />
+
+```tsx
+import { Select } from '@utilitywarehouse/hearth-react-native';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const [value, setValue] = useState(null);
+
+  return (
+    <Select
+      label="Searchable select"
+      placeholder="Select a country"
+      searchable
+      searchPlaceholder="Search countries..."
+      options={[
+        { label: 'United Kingdom', value: 'uk' },
+        { label: 'United States', value: 'us' },
+        { label: 'Canada', value: 'ca' },
+        { label: 'Australia', value: 'au' },
+        { label: 'France', value: 'fr' },
+        { label: 'Germany', value: 'de' },
+        { label: 'Japan', value: 'jp' },
+        { label: 'Brazil', value: 'br' },
+        { label: 'India', value: 'in' },
+        { label: 'South Africa', value: 'za' },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+};
+```
+
+### Inline `SelectOption`
+
+The `SelectOption` component can be used inline instead of the options prop. This allows for more flexibility in how the options are displayed.
+
+<Canvas of={Stories.WithInlineOptions} />
+
+```tsx
+import { Select, SelectOption } from '@utilitywarehouse/hearth-react-native';
+import {
+  UserSmallIcon,
+  HeartSmallIcon,
+  StarSmallIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const [value, setValue] = useState(null);
+
+  return (
+    <Select
+      label="Custom options"
+      placeholder="Select an option"
+      value={value}
+      onValueChange={setValue}
+    >
+      <SelectOption label="Home option" value="home" leadingIcon={UserSmallIcon} />
+      <SelectOption label="Car option" value="car" leadingIcon={HeartSmallIcon} />
+      <SelectOption label="World option" value="world" leadingIcon={StarSmallIcon} />
+    </Select>
+  );
+};
+```

package/src/components/Select/Select.props.ts

@@ -0,0 +1,131 @@
+import { ViewProps } from 'react-native';
+import { BottomSheetProps } from '../BottomSheet';
+
+type ValidationStatus = 'initial' | 'valid' | 'invalid';
+
+export interface SelectOptionItemProps {
+  /**
+   * Label to display for this option
+   */
+  label: string;
+  /**
+   * Value for this option
+   */
+  value: string;
+  /**
+   * Optional left icon for this option
+   */
+  leadingIcon?: React.ComponentType;
+  /**
+   * Optional right icon for this option
+   */
+  trailingIcon?: React.ComponentType;
+  /**
+   * Whether this option is disabled
+   */
+  disabled?: boolean;
+}
+
+interface SelectProps extends ViewProps {
+  /**
+   * Array of options to display in the select
+   */
+  options?: SelectOptionProps[];
+  /**
+   * Currently selected value
+   */
+  value?: string | null;
+  /**
+   * Callback when value changes
+   */
+  onValueChange?: (value: string) => void;
+  /**
+   * Label for the select
+   */
+  label?: string;
+  /**
+   * Placeholder text to show when no value is selected
+   */
+  placeholder?: string;
+  /**
+   * Whether the select is disabled
+   */
+  disabled?: boolean;
+  /**
+   * Leading icon for the select
+   */
+  leadingIcon?: React.ComponentType;
+  /**
+   * Validation status
+   */
+  validationStatus?: ValidationStatus;
+  /**
+   * Whether the select is required
+   */
+  required?: boolean;
+  /**
+   * The heading to display in the bottom sheet
+   */
+  menuHeading?: string;
+  /**
+   * Children to render inside the select (for custom options)
+   */
+  children?: ViewProps['children'];
+  /**
+   * Props passed to the BottomSheetModal
+   */
+  bottomSheetProps?: Partial<BottomSheetProps>;
+  /**
+   * Text to display when no options are available
+   */
+  emptyText?: string;
+  /**
+   * Props to be passed to the bottom sheet flat list
+   */
+  listProps?: any;
+  /**
+   * Optional search functionality for the select
+   */
+  searchable?: boolean;
+  /**
+   * Search placeholder
+   */
+  searchPlaceholder?: string;
+  /**
+   * Whether the select is readonly
+   */
+  readonly?: boolean;
+}
+
+export interface SelectOptionProps {
+  /**
+   * Label to display for this option
+   */
+  label: string;
+  /**
+   * Value for this option
+   */
+  value: string;
+  /**
+   * Optional left icon
+   */
+  leadingIcon?: React.ComponentType;
+  /**
+   * Optional right icon
+   */
+  trailingIcon?: React.ComponentType;
+  /**
+   * Whether this option is selected
+   */
+  selected?: boolean;
+  /**
+   * Whether this option is disabled
+   */
+  disabled?: boolean;
+  /**
+   * Callback when this option is selected
+   */
+  onPress?: (value: string) => void;
+}
+
+export default SelectProps;

package/src/components/Select/Select.stories.tsx

@@ -0,0 +1,290 @@
+import type { Meta } from '@storybook/react-vite';
+import React, { useState } from 'react';
+import Select from './Select';
+import SelectOption from './SelectOption';
+import { FormField } from '../FormField';
+import {
+  UserSmallIcon,
+  HeartSmallIcon,
+  StarSmallIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { Box } from '../Box';
+import { Button } from '../Button';
+
+const meta = {
+  title: 'Stories / Select',
+  component: Select,
+  parameters: {
+    status: {
+      type: 'stable',
+    },
+  },
+  argTypes: {
+    label: {
+      control: 'text',
+      description: 'Label for the select',
+      defaultValue: 'Choose an option',
+    },
+    placeholder: {
+      control: 'text',
+      description: 'Placeholder text to show when no value is selected',
+      defaultValue: 'Select an option',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the select is disabled',
+      defaultValue: false,
+    },
+    readonly: {
+      control: 'boolean',
+      description: 'Whether the select is readonly',
+      defaultValue: false,
+    },
+    validationStatus: {
+      control: 'select',
+      options: ['initial', 'valid', 'invalid'],
+      description: 'The validation status of the select',
+      defaultValue: 'initial',
+    },
+    required: {
+      control: 'boolean',
+      description: 'Whether the select is required',
+      defaultValue: true,
+    },
+    menuHeading: {
+      control: 'text',
+      description: 'The heading to display in the bottom sheet',
+    },
+    emptyText: {
+      control: 'text',
+      description: 'Text to display when no options are available',
+      defaultValue: 'No options available',
+    },
+    searchable: {
+      control: 'boolean',
+      description: 'Whether to enable search functionality',
+      defaultValue: false,
+    },
+    searchPlaceholder: {
+      control: 'text',
+      description: 'Search placeholder text',
+      defaultValue: 'Search',
+    },
+  },
+  args: {
+    label: 'Choose an option',
+    placeholder: 'Select an option',
+    disabled: false,
+    readonly: false,
+    validationStatus: 'initial',
+    required: true,
+    emptyText: 'No options available',
+    searchable: false,
+    searchPlaceholder: 'Search',
+    options: [
+      { label: 'Option 1', value: '1' },
+      { label: 'Option 2', value: '2' },
+      { label: 'Option 3', value: '3' },
+    ],
+  },
+} satisfies Meta<typeof Select>;
+
+export default meta;
+
+export const Playground = ({ ...args }) => {
+  const [value, setValue] = useState<string | null>(null);
+  const handleValueChange = (newValue: string | null) => {
+    setValue(newValue);
+    console.log('Selected value:', newValue);
+  };
+  return (
+    <Select
+      value={value}
+      onValueChange={handleValueChange}
+      {...args}
+      options={Array.from({ length: 100 }, (_, i) => ({
+        label: `Option ${i + 1}`,
+        value: `${i + 1}`,
+      }))}
+    />
+  );
+};
+
+export const WithMenuHeading = () => {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <Select
+      label="Choose an option"
+      placeholder="Select an option"
+      menuHeading="This is a menu heading"
+      options={[
+        { label: 'Option 1', value: '1' },
+        { label: 'Option 2', value: '2' },
+        { label: 'Option 3', value: '3' },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+};
+
+export const Disabled = () => {
+  const [value, setValue] = useState<string | null>('2');
+
+  return (
+    <Select
+      label="Choose an option"
+      placeholder="Select an option"
+      disabled
+      options={[
+        { label: 'Option 1', value: '1' },
+        { label: 'Option 2', value: '2' },
+        { label: 'Option 3', value: '3' },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+};
+
+export const WithValidationStatus = () => {
+  const [value, setValue] = useState<string | null>(null);
+  const [value2, setValue2] = useState<string | null>('2');
+
+  return (
+    <Box gap="200">
+      <FormField
+        validationStatus={value ? 'initial' : 'invalid'}
+        label="Invalid select"
+        invalidText="Please select a value"
+      >
+        <Select
+          placeholder="Select an option"
+          options={[
+            { label: 'Option 1', value: '1' },
+            { label: 'Option 2', value: '2' },
+            { label: 'Option 3', value: '3' },
+          ]}
+          value={value}
+          onValueChange={setValue}
+        />
+      </FormField>
+      {!!value && <Button text="Clear value" onPress={() => setValue(null)} />}
+      <FormField validationStatus="valid" label="Valid select">
+        <Select
+          placeholder="Select an option"
+          options={[
+            { label: 'Option 1', value: '1' },
+            { label: 'Option 2', value: '2' },
+            { label: 'Option 3', value: '3' },
+          ]}
+          value={value2}
+          onValueChange={setValue2}
+        />
+      </FormField>
+    </Box>
+  );
+};
+
+export const Optional = () => {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <FormField label="Field label" required={false}>
+      <Select
+        placeholder="Select an option"
+        menuHeading="Optionally select an option"
+        options={[
+          { label: 'Option 1', value: '1' },
+          { label: 'Option 2', value: '2' },
+          { label: 'Option 3', value: '3' },
+        ]}
+        value={value}
+        onValueChange={setValue}
+      />
+    </FormField>
+  );
+};
+
+export const WithDisabledOption = () => {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <FormField label="Field label">
+      <Select
+        placeholder="Select an option"
+        options={[
+          { label: 'Option 1', value: '1', disabled: true },
+          { label: 'Option 2', value: '2' },
+          { label: 'Option 3', value: '3' },
+        ]}
+        value={value}
+        onValueChange={setValue}
+      />
+    </FormField>
+  );
+};
+
+export const Searchable = () => {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <Select
+      label="Searchable select"
+      placeholder="Select a country"
+      menuHeading="Searchable countries"
+      searchable
+      searchPlaceholder="Search countries..."
+      options={[
+        { label: 'United Kingdom', value: 'uk' },
+        { label: 'United States', value: 'us' },
+        { label: 'Canada', value: 'ca' },
+        { label: 'Australia', value: 'au' },
+        { label: 'France', value: 'fr' },
+        { label: 'Germany', value: 'de' },
+        { label: 'Japan', value: 'jp' },
+        { label: 'Brazil', value: 'br' },
+        { label: 'India', value: 'in' },
+        { label: 'South Africa', value: 'za' },
+      ]}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+};
+
+export const WithInlineOptions = () => {
+  const [value, setValue] = useState<string | null>(null);
+  const handleValueChange = (newValue: string | null) => {
+    setValue(newValue);
+    console.log('Selected value:', newValue);
+  };
+  return (
+    <Select
+      label="Custom options"
+      placeholder="Select an option"
+      value={value}
+      onValueChange={handleValueChange}
+    >
+      <SelectOption label="Home option" value="home" leadingIcon={UserSmallIcon} />
+      <SelectOption label="Car option" value="car" leadingIcon={HeartSmallIcon} />
+      <SelectOption label="World option" value="world" leadingIcon={StarSmallIcon} />
+    </Select>
+  );
+};
+
+export const Empty = () => {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <Select
+      label="Empty select"
+      placeholder="No options available"
+      options={[]}
+      value={value}
+      onValueChange={setValue}
+      emptyText="No options available at the moment"
+    />
+  );
+};