uikit-react-public 0.17.4 → 0.21.9

package/lib/components/Select/Select.stories.tsx

@@ -25,9 +25,9 @@ const meta = {
       table: { type: { summary: 'OptionData[]' } },
     },
     value: {
-      description: 'Selected value (string | number)',
+      description: 'Selected value (string | number | null)',
       control: { type: 'text' },
-      table: { type: { summary: 'string | number' } },
+      table: { type: { summary: 'string | number | null' } },
     },
     onValueChange: {
       description:
@@ -35,7 +35,8 @@ const meta = {
       control: false,
       table: {
         type: {
-          summary: '(value: string | number, ev: React.UIEvent) => void',
+          summary:
+            '(value: string | number | null, ev: React.SyntheticEvent) => void',
         },
       },
     },
@@ -67,6 +68,12 @@ const meta = {
       control: { type: 'boolean' },
       table: { type: { summary: 'boolean' } },
     },
+    clearable: {
+      description:
+        'Show a clear action in the custom variant when a value is selected',
+      control: { type: 'boolean' },
+      table: { type: { summary: 'boolean' } },
+    },
     filterInputProps: {
       description:
         'Additional props to spread onto the filter input (when filterable)',
@@ -131,7 +138,7 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
     return (
@@ -176,7 +183,7 @@ export const Disabled: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
 
@@ -198,7 +205,7 @@ export const WithPlaceholder: Story = {
   args: { placeholder: 'Please select an option' },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
 
@@ -227,7 +234,7 @@ export const SingleLongOption: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
 
@@ -268,7 +275,7 @@ export const ManyOptions: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
     return (
@@ -289,7 +296,8 @@ export const filterable: Story = {
   args: { filterable: true },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => updateArgs({ value });
+    const onValueChange = (value: string | number | null) =>
+      updateArgs({ value });
     return (
       <div style={storyWrapperStyle}>
         <Select
@@ -305,12 +313,37 @@ export const filterable: Story = {
   },
 };
 
+export const Clearable: Story = {
+  args: {
+    clearable: true,
+    value: '2',
+    placeholder: 'Clear selection',
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onValueChange = (value: string | number | null) =>
+      updateArgs({ value });
+    return (
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+        />
+      </div>
+    );
+  },
+};
+
 export const SelectionBehaviourCommit: Story = {
   name: 'Selection behaviour: commit',
   args: { selectionBehaviour: 'commit' },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => updateArgs({ value });
+    const onValueChange = (value: string | number | null) =>
+      updateArgs({ value });
     return (
       <div style={storyWrapperStyle}>
         <Select

package/lib/components/Select/Select.tsx

@@ -1,11 +1,18 @@
 import { NativeSelect, CustomSelect } from './subcomponents';
-import { SelectProps } from './Select.types';
+import type { InternalSelectProps, SelectProps } from './Select.types';
 
-const Select = <T extends string | number = string>(props: SelectProps<T>) => {
+type SelectComponent = <T extends string | number = string>(
+  props: SelectProps<T>
+) => React.JSX.Element;
+
+const Select = (<T extends string | number = string>(
+  props: InternalSelectProps<T>
+) => {
   const {
     native,
     nativeHtmlAttributes,
     filterable,
+    clearable,
     onValueChange,
     ref,
     ...rest
@@ -15,6 +22,9 @@ const Select = <T extends string | number = string>(props: SelectProps<T>) => {
     if (filterable) {
       console.warn('filterable is not supported on native Select; ignoring.');
     }
+    if (clearable) {
+      console.warn('clearable is not supported on native Select; ignoring.');
+    }
     const { value, ...nativeRest } = rest;
     const {
       value: nativeAttrValue,
@@ -40,10 +50,11 @@ const Select = <T extends string | number = string>(props: SelectProps<T>) => {
     <CustomSelect<T>
       onValueChange={onValueChange}
       filterable={filterable}
+      clearable={clearable}
       ref={ref as React.Ref<HTMLDivElement>}
       {...rest}
     />
   );
-};
+}) as SelectComponent;
 
 export default Select;

package/lib/components/Select/Select.types.ts

@@ -37,11 +37,10 @@ export type FilterInputProps = Omit<
   | 'aria-label'
 >;
 
-/**
- * Public props for <Select>, used by both custom and native render paths.
- */
-export interface SelectProps<T = string | number>
-  extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange'> {
+type SelectBaseProps<T = string | number> = Omit<
+  React.HTMLAttributes<HTMLElement>,
+  'onChange'
+> & {
   /**
    * Controls keyboard selection behaviour in the custom select variant.
    * - `focus` (default): arrow keys move focus and commit value immediately.
@@ -84,10 +83,6 @@ export interface SelectProps<T = string | number>
    * Extra attributes forwarded to the native <select> when `native` is true
    */
   nativeHtmlAttributes?: React.SelectHTMLAttributes<HTMLSelectElement>;
-  /**
-   * Current value (controlled)
-   */
-  value?: T;
   /**
    * Disable interaction
    */
@@ -104,23 +99,65 @@ export interface SelectProps<T = string | number>
    * Custom className for the options panel
    */
   panelClassName?: string;
-  /**
-   * Change handler for the custom variant
-   */
-  onValueChange?: (value: T, ev: React.UIEvent) => void;
   /**
    * Ref forwarded to the rendered element
    * (div for custom, select for native)
    */
   ref?: React.Ref<HTMLDivElement | HTMLSelectElement | null>;
-}
+};
+
+export type NonClearableSelectProps<T = string | number> =
+  SelectBaseProps<T> & {
+    /**
+     * Current value (controlled)
+     */
+    value?: T;
+    /**
+     * Show a clear action in the custom variant when a value is selected
+     */
+    clearable?: false | undefined;
+    /**
+     * Change handler for the custom variant
+     */
+    onValueChange?: (value: T, ev: React.SyntheticEvent) => void;
+  };
+
+export type ClearableSelectProps<T = string | number> = SelectBaseProps<T> & {
+  /**
+   * Current value (controlled)
+   */
+  value?: T | null;
+  /**
+   * Show a clear action in the custom variant when a value is selected
+   */
+  clearable: true;
+  /**
+   * Change handler for the custom variant
+   */
+  onValueChange?: (value: T | null, ev: React.SyntheticEvent) => void;
+};
+
+/**
+ * Public props for <Select>, used by both custom and native render paths.
+ */
+export type SelectProps<T = string | number> =
+  | NonClearableSelectProps<T>
+  | ClearableSelectProps<T>;
+
+export type InternalSelectProps<T = string | number> = SelectBaseProps<T> & {
+  value?: T | null;
+  clearable?: boolean;
+  onValueChange?: (value: T | null, ev: React.SyntheticEvent) => void;
+};
 
 /**
  * Each option as displayed in the Panel of <CustomSelect>
  * Roughly equivalent to a custom version of <option>
  */
-export interface CustomOptionProps<T>
-  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+export interface CustomOptionProps<T> extends Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  'onSelect'
+> {
   value: T;
   optionIndex?: number;
   testId?: string;

package/lib/components/Select/__tests__/Select.test.tsx

@@ -1,6 +1,6 @@
 import { describe, expect, test, vi, beforeAll } from 'vitest';
 import { useState } from 'react';
-import { render } from '@testing-library/react';
+import { createEvent, fireEvent, render } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import Select from '../Select';
 import { ThemeContextProvider } from '../../../theme/useTheme';
@@ -418,6 +418,41 @@ describe('Select', () => {
     );
   });
 
+  test('filterable select keeps option clicks working while the filter input is focused', async () => {
+    const user = userEvent.setup();
+
+    const ControlledSelect = () => {
+      const [value, setValue] = useState('');
+      return (
+        <Select
+          filterable
+          options={defaultOptions}
+          value={value}
+          onValueChange={(next) => setValue(next as string)}
+        />
+      );
+    };
+
+    const result = render(
+      <ThemeContextProvider>
+        <ControlledSelect />
+      </ThemeContextProvider>
+    );
+
+    await user.click(result.getByTestId('ucl-uikit-select'));
+    const filterInput = result.getByRole('searchbox');
+    expect(filterInput).toHaveFocus();
+
+    await user.click(result.getByRole('option', { name: 'Option 2' }));
+
+    expect(
+      result.queryByTestId('ucl-uikit-select__panel')
+    ).not.toBeInTheDocument();
+    expect(result.getByTestId('ucl-uikit-select')).toHaveTextContent(
+      'Option 2'
+    );
+  });
+
   test('forwards id and title attributes to the combobox', () => {
     const result = render(
       <ThemeContextProvider>
@@ -557,4 +592,218 @@ describe('Select', () => {
     await user.keyboard('{ArrowDown}');
     expect(filterInput).toHaveAttribute('aria-activedescendant', options[1].id);
   });
+
+  test('open dropdown closes when tabbing to the next element', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <div>
+          <Select
+            options={defaultOptions}
+            value=''
+            onValueChange={() => {}}
+          />
+          <button type='button'>After</button>
+        </div>
+      </ThemeContextProvider>
+    );
+
+    await user.click(result.getByRole('combobox'));
+    expect(result.getByRole('listbox')).toBeInTheDocument();
+
+    await user.tab();
+
+    expect(result.queryByRole('listbox')).not.toBeInTheDocument();
+    expect(result.getByRole('button', { name: 'After' })).toHaveFocus();
+  });
+
+  test('open filterable dropdown closes when tabbing to the next element', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <div>
+          <Select
+            filterable
+            options={defaultOptions}
+            value=''
+            onValueChange={() => {}}
+          />
+          <button type='button'>After</button>
+        </div>
+      </ThemeContextProvider>
+    );
+
+    await user.click(result.getByRole('combobox'));
+    expect(result.getByRole('searchbox')).toHaveFocus();
+    expect(result.getByRole('listbox')).toBeInTheDocument();
+
+    await user.tab();
+
+    expect(result.queryByRole('listbox')).not.toBeInTheDocument();
+    expect(result.getByRole('button', { name: 'After' })).toHaveFocus();
+  });
+
+  test('open dropdown closes when shift-tabbing to the previous element', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <div>
+          <button type='button'>Before</button>
+          <Select
+            options={defaultOptions}
+            value=''
+            onValueChange={() => {}}
+          />
+        </div>
+      </ThemeContextProvider>
+    );
+
+    await user.tab();
+    await user.tab();
+    expect(result.getByRole('combobox')).toHaveFocus();
+
+    await user.keyboard('{Enter}');
+    expect(result.getByRole('listbox')).toBeInTheDocument();
+
+    await user.tab({ shift: true });
+
+    expect(result.queryByRole('listbox')).not.toBeInTheDocument();
+    expect(result.getByRole('button', { name: 'Before' })).toHaveFocus();
+  });
+
+  test('open filterable dropdown closes when shift-tabbing to the previous element', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <div>
+          <button type='button'>Before</button>
+          <Select
+            filterable
+            options={defaultOptions}
+            value=''
+            onValueChange={() => {}}
+          />
+        </div>
+      </ThemeContextProvider>
+    );
+
+    await user.tab();
+    await user.tab();
+    expect(result.getByRole('searchbox')).toHaveFocus();
+    expect(result.getByRole('listbox')).toBeInTheDocument();
+
+    await user.tab({ shift: true });
+
+    expect(result.queryByRole('listbox')).not.toBeInTheDocument();
+    expect(result.getByRole('button', { name: 'Before' })).toHaveFocus();
+  });
+
+  test('open filterable dropdown at end of tab order does not trap focus on Tab', async () => {
+    const result = render(
+      <ThemeContextProvider>
+        <Select
+          filterable
+          options={defaultOptions}
+          value=''
+          onValueChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    fireEvent.click(result.getByRole('combobox'));
+    const searchbox = result.getByRole('searchbox');
+    expect(result.getByRole('listbox')).toBeInTheDocument();
+
+    const tabEvent = createEvent.keyDown(searchbox, { key: 'Tab' });
+    const dispatchResult = fireEvent(searchbox, tabEvent);
+
+    expect(dispatchResult).toBe(true);
+    expect(result.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('open filterable dropdown at start of tab order does not trap focus on shift-tab', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <Select
+          filterable
+          options={defaultOptions}
+          value=''
+          onValueChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    await user.tab();
+    const searchbox = result.getByRole('searchbox');
+    expect(searchbox).toHaveFocus();
+    expect(result.getByRole('listbox')).toBeInTheDocument();
+
+    const shiftTabEvent = createEvent.keyDown(searchbox, {
+      key: 'Tab',
+      shiftKey: true,
+    });
+    const dispatchResult = fireEvent(searchbox, shiftTabEvent);
+
+    expect(dispatchResult).toBe(true);
+    expect(result.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('clear button appears for clearable select and clears to null', async () => {
+    const user = userEvent.setup();
+    const changeSpy = vi.fn();
+
+    const ControlledSelect = () => {
+      const [value, setValue] = useState<string | null>('2');
+      return (
+        <Select
+          clearable
+          options={defaultOptions}
+          value={value}
+          placeholder='Select an option'
+          onValueChange={(next, ev) => {
+            setValue(next as string | null);
+            changeSpy(next, ev);
+          }}
+        />
+      );
+    };
+
+    const result = render(
+      <ThemeContextProvider>
+        <ControlledSelect />
+      </ThemeContextProvider>
+    );
+
+    const clearButton = result.getByTestId(
+      'ucl-uikit-select__visible-field-clear-button'
+    );
+    expect(result.getByRole('combobox')).toHaveTextContent('Option 2');
+
+    await user.click(clearButton);
+
+    expect(changeSpy).toHaveBeenCalledWith(null, expect.any(Object));
+    expect(result.getByRole('combobox')).toHaveTextContent('Select an option');
+    expect(
+      result.queryByTestId('ucl-uikit-select__visible-field-clear-button')
+    ).not.toBeInTheDocument();
+  });
+
+  test('disabled clearable select does not show clear button', () => {
+    const result = render(
+      <ThemeContextProvider>
+        <Select
+          clearable
+          disabled
+          options={defaultOptions}
+          value='1'
+          onValueChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    expect(
+      result.queryByTestId('ucl-uikit-select__visible-field-clear-button')
+    ).not.toBeInTheDocument();
+  });
 });

package/lib/components/Select/__tests__/__snapshots__/Select.test.tsx.snap

@@ -4,7 +4,7 @@ exports[`Select > Snapshot: default 1`] = `
 <div
   aria-expanded="false"
   aria-haspopup="listbox"
-  class="ucl-uikit-select css-1kop2c3"
+  class="ucl-uikit-select css-a6n340"
   data-testid="ucl-uikit-select"
   role="combobox"
   tabindex="0"
@@ -17,9 +17,10 @@ exports[`Select > Snapshot: default 1`] = `
       class="css-16t5nns"
     />
     <svg
-      class="ucl-uikit-icon css-hseitk"
+      class="ucl-uikit-icon css-1pg9a4v"
       data-testid="ucl-uikit-icon"
       fill="none"
+      focusable="false"
       height="24"
       stroke="currentColor"
       stroke-linecap="round"
@@ -29,8 +30,8 @@ exports[`Select > Snapshot: default 1`] = `
       width="24"
       xmlns="http://www.w3.org/2000/svg"
     >
-      <polyline
-        points="6 9 12 15 18 9"
+      <path
+        d="m6 9 6 6 6-6"
       />
     </svg>
   </div>

package/lib/components/Select/subcomponents/CustomOption.tsx

@@ -34,6 +34,12 @@ const CustomOption = <T extends string | number>({
     event.stopPropagation(); // Otherwise the panel will open again instantaneously
   };
 
+  const handleMouseDown = (event: React.MouseEvent<HTMLDivElement>) => {
+    // Keep focus on the combobox/filter input so blur does not close the panel
+    // before the option click handler runs.
+    event.preventDefault();
+  };
+
   const baseStyle = css`
     gap: 16px;
     min-height: 40px;
@@ -42,11 +48,11 @@ const CustomOption = <T extends string | number>({
     font-family: ${theme.font.family.primary};
     font-size: ${theme.font.size.f16};
     line-height: ${theme.font.lineHeight.h140};
-    background-color: ${theme.color.neutral.white};
+    background-color: ${theme.colour.fill.inverse};
     overflow: hidden;
 
     &:hover {
-      background-color: ${theme.color.neutral.grey5};
+      background-color: ${theme.colour.fill.brandSubtleHover};
     }
   `;
 
@@ -60,7 +66,7 @@ const CustomOption = <T extends string | number>({
   `;
 
   const selectedStyle = css`
-    background-color: ${theme.color.neutral.grey5};
+    background-color: ${theme.colour.fill.brandSubtleSelected};
   `;
 
   const style = cx(
@@ -74,6 +80,7 @@ const CustomOption = <T extends string | number>({
 
   return (
     <div
+      onMouseDown={handleMouseDown}
       onClick={handleClick}
       className={style}
       data-testid={testId}