@utilitywarehouse/hearth-react-native 0.27.3 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.27.3",
+  "version": "0.28.0",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -58,8 +58,8 @@
     "vitest": "^3.2.4",
     "@utilitywarehouse/hearth-fonts": "^0.0.4",
     "@utilitywarehouse/hearth-react-icons": "^0.8.0",
-    "@utilitywarehouse/hearth-react-native-icons": "^0.8.0",
     "@utilitywarehouse/hearth-svg-assets": "^0.5.0",
+    "@utilitywarehouse/hearth-react-native-icons": "^0.8.0",
     "@utilitywarehouse/hearth-tokens": "^0.2.4"
   },
   "peerDependencies": {

package/src/components/Combobox/Combobox.context.ts

@@ -0,0 +1,26 @@
+import { createContext, useContext } from 'react';
+
+export interface ComboboxSelection {
+  label: string;
+  value: string;
+}
+
+export interface ComboboxContextValue {
+  close: () => void;
+  search: string;
+  selectedValue?: string | null;
+  selectOption: (option: ComboboxSelection) => void;
+  setSearch: (value: string) => void;
+}
+
+export const ComboboxContext = createContext<ComboboxContextValue | undefined>(undefined);
+
+export const useComboboxContext = () => {
+  const context = useContext(ComboboxContext);
+
+  if (!context) {
+    throw new Error('useComboboxContext must be used within a Combobox');
+  }
+
+  return context;
+};

package/src/components/Combobox/Combobox.docs.mdx

@@ -0,0 +1,277 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { BottomSheetFlatList, Box, Center, Combobox, ComboboxOption } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Combobox.stories';
+
+<Meta title="Forms / Combobox" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=9359-2923&t=c7xg5X0N2EL0t87h-4" />
+
+# Combobox
+
+The `Combobox` component lets people search and select from a list inside a bottom sheet. It keeps the trigger text and the bottom sheet search input in sync, and can render either the built-in options list or fully custom sheet content.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Center>
+    <Combobox
+      label="Country"
+      placeholder="Search for a country"
+      searchPlaceholder="Search for a country"
+      options={[
+        { label: 'United Kingdom', value: 'uk' },
+        { label: 'United States', value: 'us' },
+        { label: 'Canada', value: 'ca' },
+      ]}
+      value="uk"
+    />
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Combobox } from '@utilitywarehouse/hearth-react-native';
+import { useState } from 'react';
+
+const countries = [
+  { label: 'United Kingdom', value: 'uk' },
+  { label: 'United States', value: 'us' },
+  { label: 'Canada', value: 'ca' },
+];
+
+const MyComponent = () => {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <Combobox
+      label="Country"
+      placeholder="Search for a country"
+      searchPlaceholder="Search for a country"
+      options={countries}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+};
+```
+
+## Props
+
+The `Combobox` component inherits all of the React Native [`View` props](https://reactnative.dev/docs/view).
+
+| Prop                 | Type                                | Default              | Description                                                                  |
+| -------------------- | ----------------------------------- | -------------------- | ---------------------------------------------------------------------------- |
+| `options`            | `ComboboxOptionItemProps[]`         | `[]`                 | Array of options for the built-in bottom sheet list.                         |
+| `value`              | `string \| null`                    | `-`                  | Currently selected value.                                                    |
+| `onValueChange`      | `(value: string \| null) => void`   | `-`                  | Callback when the selected value changes.                                    |
+| `inputValue`         | `string`                            | `-`                  | Controlled search value for the trigger and bottom sheet input.              |
+| `onInputValueChange` | `(value: string) => void`           | `-`                  | Callback when the search value changes.                                      |
+| `placeholder`        | `string`                            | `'Search'`           | Placeholder shown in the trigger when empty.                                 |
+| `searchPlaceholder`  | `string`                            | `'Search'`           | Placeholder shown in the bottom sheet search input.                          |
+| `menuHeading`        | `string`                            | `-`                  | Optional heading shown at the top of the bottom sheet.                       |
+| `children`           | `ReactNode \| (props) => ReactNode` | `-`                  | Custom bottom sheet content, or a render function for custom list rendering. |
+| `loading`            | `boolean`                           | `false`              | Displays a loading spinner in the trigger and sheet input.                   |
+| `noOptionsFoundText` | `string`                            | `'No options found'` | Empty state text for the built-in options list.                              |
+| `getValueLabel`      | `(value) => string`                 | `-`                  | Resolve a label for selected values that are not present in `options`.       |
+| `filterOption`       | `(option, search) => boolean`       | `-`                  | Override the default label and keyword filtering logic.                      |
+
+## Examples
+
+### Static Searchable List
+
+<Canvas of={Stories.StaticSearchableList} />
+
+```tsx
+import { Combobox } from '@utilitywarehouse/hearth-react-native';
+import { useState } from 'react';
+
+const countries = [
+  { label: 'United Kingdom', value: 'uk', keywords: ['britain', 'england'] },
+  { label: 'United States', value: 'us', keywords: ['america', 'usa'] },
+  { label: 'Canada', value: 'ca' },
+  { label: 'Australia', value: 'au' },
+  { label: 'France', value: 'fr' },
+];
+
+const MyComponent = () => {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <Combobox
+      label="Country"
+      helperText="Search a fixed list of countries"
+      placeholder="Search for a country"
+      searchPlaceholder="Search for a country"
+      menuHeading="Choose a country"
+      options={countries}
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+};
+```
+
+### Dynamic Items
+
+<Canvas of={Stories.DynamicItems} />
+
+```tsx
+import { Combobox } from '@utilitywarehouse/hearth-react-native';
+import { useEffect, useState } from 'react';
+
+const allProducts = [
+  { label: 'Broadband', value: 'broadband' },
+  { label: 'Energy', value: 'energy' },
+  { label: 'Mobile', value: 'mobile' },
+];
+
+const MyComponent = () => {
+  const [value, setValue] = useState<string | null>(null);
+  const [inputValue, setInputValue] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [options, setOptions] = useState(allProducts);
+
+  useEffect(() => {
+    setLoading(true);
+
+    const timeout = setTimeout(() => {
+      const query = inputValue.trim().toLowerCase();
+      setOptions(allProducts.filter(option => option.label.toLowerCase().includes(query)));
+      setLoading(false);
+    }, 300);
+
+    return () => clearTimeout(timeout);
+  }, [inputValue]);
+
+  return (
+    <Combobox
+      label="Products"
+      options={options}
+      value={value}
+      onValueChange={setValue}
+      inputValue={inputValue}
+      onInputValueChange={setInputValue}
+      loading={loading}
+      getValueLabel={selectedValue =>
+        allProducts.find(option => option.value === selectedValue)?.label ?? ''
+      }
+    />
+  );
+};
+```
+
+### Custom Bottom Sheet Flat List
+
+<Canvas of={Stories.CustomFlatList} />
+
+```tsx
+import {
+  BottomSheetFlatList,
+  Combobox,
+  ComboboxOption,
+} from '@utilitywarehouse/hearth-react-native';
+
+const cities = [
+  { label: 'London', value: 'london' },
+  { label: 'Liverpool', value: 'liverpool' },
+  { label: 'Leeds', value: 'leeds' },
+];
+
+const MyComponent = () => {
+  return (
+    <Combobox label="Cities" placeholder="Search a city">
+      {({ search }) => {
+        const query = search.trim().toLowerCase();
+        const filteredCities = cities.filter(option => option.label.toLowerCase().includes(query));
+
+        return (
+          <BottomSheetFlatList
+            data={filteredCities}
+            keyExtractor={item => item.value}
+            renderItem={({ item }) => <ComboboxOption label={item.label} value={item.value} />}
+          />
+        );
+      }}
+    </Combobox>
+  );
+};
+```
+
+### Inline Custom Content
+
+<UsageWrap>
+  <Center>
+    <Combobox label="Inline options" placeholder="Search for a country">
+      <Box>
+        <ComboboxOption label="United Kingdom" value="uk" />
+        <ComboboxOption label="United States" value="us" />
+        <ComboboxOption label="Canada" value="ca" />
+      </Box>
+    </Combobox>
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Box, Combobox, ComboboxOption } from '@utilitywarehouse/hearth-react-native';
+import { useState } from 'react';
+
+const countries = [
+  { label: 'United Kingdom', value: 'uk' },
+  { label: 'United States', value: 'us' },
+  { label: 'Canada', value: 'ca' },
+];
+
+const MyComponent = () => {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <Combobox
+      label="Inline options"
+      helperText="Compose your own sheet content using ComboboxOption"
+      placeholder="Search a country"
+      searchPlaceholder="Search a country"
+      value={value}
+      onValueChange={setValue}
+    >
+      <Box>
+        {countries.map(option => (
+          <ComboboxOption key={option.value} label={option.label} value={option.value} />
+        ))}
+      </Box>
+    </Combobox>
+  );
+};
+```
+
+## Accessibility
+
+The `Combobox` is implemented as a button that opens a bottom sheet. By default:
+
+- The trigger uses an accessible label derived from the `label` prop (and, where appropriate, the current value or `placeholder`) and is exposed with `accessibilityRole="button"`.
+- When the bottom sheet is open, the trigger reflects its state via `accessibilityState={{ expanded: true }}`; when the sheet is closed, it reports `expanded: false`. Screen readers should announce this state change as “expanded” / “collapsed”.
+- The clear control (shown when a value is selected and clearing is allowed) is exposed as a separate button with an accessibility label such as “Clear selection”, so that screen reader users understand its purpose.
+
+When you rely on the built‑in options list via the `options` prop, each option is rendered with appropriate roles and labels so that it can be discovered and activated with assistive technology.
+
+When you provide fully custom sheet content instead of using `ComboboxOption`:
+
+- Make sure interactive elements inside the sheet have the correct `accessibilityRole` (for example, `button` or `checkbox`) and meaningful `accessibilityLabel`s.
+- Ensure that the primary search field inside the sheet remains focusable and clearly labelled with `searchPlaceholder` or a custom accessible label.
+- Provide clear labelling or headings for grouped content, and ensure focus order inside the sheet is logical.
+- Keep a visible and accessible way to dismiss the sheet (for example, a close button with an appropriate accessibility label).
+
+These practices help ensure that the combobox remains understandable and operable for screen reader and keyboard users, regardless of whether you use the built‑in options list or custom content.

package/src/components/Combobox/Combobox.figma.tsx

@@ -0,0 +1,60 @@
+import figma from '@figma/code-connect';
+import { useState } from 'react';
+import { Combobox } from '../';
+
+figma.connect(
+  Combobox,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=9359%3A2923',
+  {
+    props: {
+      label: figma.string('Label'),
+      placeholder: figma.enum('Value type', {
+        Empty: figma.string('Value'),
+      }),
+      disabled: figma.enum('Variant', {
+        Disabled: true,
+      }),
+      validationStatus: figma.enum('Variant', {
+        Invalid: 'invalid',
+      }),
+      invalidText: figma.enum('Variant', {
+        Invalid: figma.string('Validation'),
+      }),
+      helperText: figma.boolean('Helper text?', {
+        true: figma.string('Helper text'),
+      }),
+      required: figma.boolean('Optional?', {
+        true: false,
+      }),
+      loading: figma.enum('Variant', {
+        Loading: true,
+      }),
+      value: figma.enum('Value type', {
+        Filled: figma.string('Value'),
+      }),
+    },
+    example: props => {
+      const [value, setValue] = useState<string | null>(props.value ? '1' : null);
+
+      return (
+        <Combobox
+          label={props.label}
+          placeholder={props.placeholder}
+          disabled={props.disabled}
+          validationStatus={props.validationStatus}
+          invalidText={props.invalidText}
+          helperText={props.helperText}
+          required={props.required}
+          loading={props.loading}
+          options={[
+            { label: 'Option 1', value: '1' },
+            { label: 'Option 2', value: '2' },
+            { label: 'Option 3', value: '3' },
+          ]}
+          value={value}
+          onValueChange={setValue}
+        />
+      );
+    },
+  }
+);

package/src/components/Combobox/Combobox.props.ts

@@ -0,0 +1,187 @@
+import { BottomSheetFlatListProps } from '@gorhom/bottom-sheet/lib/typescript/components/bottomSheetScrollable/types';
+import { ComponentType, ReactNode } from 'react';
+import { ViewProps } from 'react-native';
+import { BottomSheetProps } from '../BottomSheet';
+import { ComboboxSelection } from './Combobox.context';
+
+type ValidationStatus = 'initial' | 'valid' | 'invalid';
+
+export interface ComboboxOptionItemProps {
+  /**
+   * Label shown for this option.
+   */
+  label: string;
+  /**
+   * Value returned when this option is selected.
+   */
+  value: string;
+  /**
+   * Optional icon shown before the option label.
+   */
+  leadingIcon?: ComponentType;
+  /**
+   * Optional icon shown after the option label.
+   */
+  trailingIcon?: ComponentType;
+  /**
+   * Additional searchable terms for this option.
+   */
+  keywords?: string[];
+  /**
+   * Whether this option is disabled.
+   */
+  disabled?: boolean;
+}
+
+export interface ComboboxRenderContentProps {
+  /**
+   * Current search value used by both the trigger and bottom sheet input.
+   */
+  search: string;
+  /**
+   * Update the search value.
+   */
+  setSearch: (value: string) => void;
+  /**
+   * Close the bottom sheet.
+   */
+  close: () => void;
+  /**
+   * Select an option, update the trigger text and close the bottom sheet.
+   */
+  selectOption: (option: ComboboxSelection) => void;
+  /**
+   * Currently selected value.
+   */
+  selectedValue?: string | null;
+}
+
+export interface ComboboxOptionProps extends ComboboxOptionItemProps {
+  /**
+   * Whether this option is selected.
+   */
+  selected?: boolean;
+  /**
+   * Custom press handler for this option.
+   */
+  onPress?: (value: string) => void;
+}
+
+type ComboboxChildren = ReactNode | ((props: ComboboxRenderContentProps) => ReactNode);
+
+interface ComboboxProps extends Omit<ViewProps, 'children'> {
+  /**
+   * Array of options to render using the default bottom sheet list.
+   */
+  options?: ComboboxOptionItemProps[];
+  /**
+   * Currently selected value.
+   */
+  value?: string | null;
+  /**
+   * Callback fired when the selected value changes.
+   */
+  onValueChange?: (value: string | null) => void;
+  /**
+   * Controlled search value used by the trigger and bottom sheet input.
+   */
+  inputValue?: string;
+  /**
+   * Callback fired when the search value changes.
+   */
+  onInputValueChange?: (value: string) => void;
+  /**
+   * Label shown above the combobox.
+   */
+  label?: string;
+  /**
+   * The variant of the label text.
+   *
+   * @default 'body'
+   */
+  labelVariant?: 'heading' | 'body';
+  /**
+   * Helper text shown below the label.
+   */
+  helperText?: string;
+  /**
+   * Optional helper icon.
+   */
+  helperIcon?: ComponentType;
+  /**
+   * Text shown for invalid state.
+   */
+  invalidText?: string;
+  /**
+   * Text shown for valid state.
+   */
+  validText?: string;
+  /**
+   * Placeholder shown when the combobox is empty.
+   *
+   * @default 'Search'
+   */
+  placeholder?: string;
+  /**
+   * Placeholder shown in the bottom sheet search input.
+   *
+   * @default 'Search'
+   */
+  searchPlaceholder?: string;
+  /**
+   * Whether the combobox is disabled.
+   */
+  disabled?: boolean;
+  /**
+   * Validation status for the combobox.
+   *
+   * @default 'initial'
+   */
+  validationStatus?: ValidationStatus;
+  /**
+   * Whether the combobox is required.
+   *
+   * @default true
+   */
+  required?: boolean;
+  /**
+   * Heading displayed above the bottom sheet search input.
+   */
+  menuHeading?: string;
+  /**
+   * Custom bottom sheet content, or a render function for fully custom list rendering.
+   */
+  children?: ComboboxChildren;
+  /**
+   * Props passed to the BottomSheetModal.
+   */
+  bottomSheetProps?: Partial<BottomSheetProps>;
+  /**
+   * Text shown when no options match the current search.
+   *
+   * @default 'No options found'
+   */
+  noOptionsFoundText?: string;
+  /**
+   * Props passed to the default BottomSheetFlatList renderer.
+   */
+  listProps?: Partial<BottomSheetFlatListProps<ComboboxOptionItemProps>>;
+  /**
+   * Whether the combobox should show a loading spinner.
+   */
+  loading?: boolean;
+  /**
+   * Whether the combobox is readonly.
+   */
+  readonly?: boolean;
+  /**
+   * Resolve a label for a selected value when the current options array does not contain it.
+   */
+  getValueLabel?: (value: string | null | undefined) => string;
+  /**
+   * Override the default filtering behaviour for the default options list.
+   */
+  filterOption?: (option: ComboboxOptionItemProps, search: string) => boolean;
+}
+
+export default ComboboxProps;