uikit-react-public 0.17.4 → 0.21.8

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}

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

@@ -2,12 +2,24 @@ import { useState, useRef, useEffect, useMemo, useId } from 'react';
 import { css, cx } from '@emotion/css';
 import { VisibleField, Panel, CustomOption, FilterInput } from '.';
 import { useTheme } from '../../../theme';
-import type { SelectProps } from '../Select.types';
+import type { InternalSelectProps } from '../Select.types';
 
 const NAME = 'ucl-uikit-select';
+const FOCUSABLE_ELEMENTS = [
+  'a[href]',
+  'button:not([disabled])',
+  'textarea:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  '[contenteditable="true"]',
+  'audio[controls]',
+  'video[controls]',
+  'details > summary:first-of-type',
+].join(', ');
 
 type CustomSelectProps<T> = Omit<
-  SelectProps<T>,
+  InternalSelectProps<T>,
   'native' | 'nativeHtmlAttributes'
 >;
 
@@ -17,6 +29,7 @@ const CustomSelect = <T extends string | number>({
   options = [],
   onValueChange,
   disabled,
+  clearable = false,
   placeholder,
   lineBreak = false,
   filterInputProps,
@@ -95,6 +108,7 @@ const CustomSelect = <T extends string | number>({
     null
   );
   const filterInputRef = useRef<HTMLInputElement | null>(null);
+  const clearButtonRef = useRef<HTMLButtonElement | null>(null);
   const reactId = useId();
   const idBase = props.id ?? `${testId}-${reactId.replace(/[:]/g, '')}`;
   const listboxId = `${idBase}-listbox`;
@@ -161,6 +175,79 @@ const CustomSelect = <T extends string | number>({
     };
   }, [effectiveRef]);
 
+  const handleBlur = (event: React.FocusEvent<HTMLElement>) => {
+    const nextFocusedElement = event.relatedTarget as Node | null;
+    if (
+      effectiveRef.current &&
+      nextFocusedElement &&
+      effectiveRef.current.contains(nextFocusedElement)
+    ) {
+      return;
+    }
+    closePanel();
+  };
+
+  const isFocusableElement = (element: HTMLElement) => {
+    if (!element.isConnected) return false;
+    if (element instanceof HTMLInputElement && element.type === 'hidden') {
+      return false;
+    }
+    if (element.tabIndex < 0) return false;
+    if ('disabled' in element && element.disabled) return false;
+
+    const style = window.getComputedStyle(element);
+    if (style.display === 'none' || style.visibility === 'hidden') {
+      return false;
+    }
+
+    return true;
+  };
+
+  const moveFocusOutsideSelect = (isReverse: boolean) => {
+    if (!effectiveRef.current) return false;
+
+    const focusableElements = Array.from(
+      document.querySelectorAll<HTMLElement>(FOCUSABLE_ELEMENTS)
+    ).filter(isFocusableElement);
+
+    const currentElement = filterInputRef.current;
+    if (!currentElement) return false;
+
+    const currentIndex = focusableElements.indexOf(currentElement);
+    if (currentIndex === -1) return false;
+
+    const step = isReverse ? -1 : 1;
+    let nextIndex = currentIndex + step;
+
+    while (nextIndex >= 0 && nextIndex < focusableElements.length) {
+      const candidate = focusableElements[nextIndex];
+      if (!effectiveRef.current.contains(candidate)) {
+        candidate.focus();
+        if (document.activeElement === candidate) {
+          return true;
+        }
+      }
+      nextIndex += step;
+    }
+
+    return false;
+  };
+
+  const handleFilterTabOut = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    closePanel();
+    // If this widget gains more tabbable descendants, revisit this handoff.
+    if (!event.shiftKey && clearButtonRef.current) {
+      clearButtonRef.current.focus();
+      if (document.activeElement === clearButtonRef.current) {
+        event.preventDefault();
+        return;
+      }
+    }
+    if (moveFocusOutsideSelect(event.shiftKey)) {
+      event.preventDefault();
+    }
+  };
+
   useEffect(() => {
     // Close the dropdown if it becomes disabled
     if (disabled && isOpen) setIsOpen(false);
@@ -211,6 +298,17 @@ const CustomSelect = <T extends string | number>({
     closePanel();
   };
 
+  const handleClear = (event: React.MouseEvent | React.KeyboardEvent) => {
+    if (disabled) return;
+    event.stopPropagation();
+    setSelectedOptionIndex(null);
+    setActiveOptionIndex(null);
+    setFilterText('');
+    closePanel();
+    effectiveRef.current?.focus();
+    onValueChange?.(null, event);
+  };
+
   // Used by <CustomOption> and passed as prop
   const handleSelect = (
     event: React.MouseEvent,
@@ -393,18 +491,14 @@ const CustomSelect = <T extends string | number>({
     height: 48px;
     box-sizing: border-box;
     padding: 0 16px;
-    background-color: ${theme.color.neutral.white};
-    color: ${theme.color.text.primary};
+    background-color: ${theme.colour.fill.inverse};
+    color: ${theme.colour.text.default};
     font-family: ${theme.font.family.primary};
     font-size: ${theme.font.size.f16};
-    border: ${theme.border.b1} solid ${theme.color.neutral.grey60};
+    border: ${theme.border.b1} solid ${theme.colour.speciality.inputDefault};
     cursor: pointer;
     user-select: none;
 
-    &:hover {
-      ${!isOpen && `background-color: ${theme.color.neutral.grey5};`}
-    }
-
     &:focus-visible,
     &:focus-within {
       outline: none;
@@ -434,7 +528,8 @@ const CustomSelect = <T extends string | number>({
       onClick={handleClick}
       onKeyDown={handleKeyDown}
       onFocus={handleFocus}
-      tabIndex={disabled ? -1 : 0}
+      onBlur={handleBlur}
+      tabIndex={disabled || (filterable && isOpen) ? -1 : 0}
       className={style}
       data-testid={testId}
       ref={setRefs}
@@ -451,6 +546,9 @@ const CustomSelect = <T extends string | number>({
         placeholder={placeholder}
         disabled={disabled}
         filterable={filterable}
+        clearable={clearable}
+        onClear={handleClear}
+        clearButtonRef={clearButtonRef}
       >
         {filterable && (
           <FilterInput
@@ -459,6 +557,8 @@ const CustomSelect = <T extends string | number>({
             placeholder={placeholder}
             disabled={disabled}
             inputRef={filterInputRef}
+            onBlur={handleBlur}
+            onTabOut={handleFilterTabOut}
             ariaControls={listboxId}
             ariaExpanded={isOpen}
             ariaActiveDescendant={activeDescendantId}

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

@@ -5,6 +5,8 @@ import type { FilterInputProps } from '../Select.types';
 type FilterInputComponentProps = {
   value: string;
   onChange: (value: string) => void;
+  onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void;
+  onTabOut?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
   placeholder?: string;
   disabled?: boolean;
   inputRef?: React.RefObject<HTMLInputElement | null>;
@@ -17,6 +19,8 @@ type FilterInputComponentProps = {
 const FilterInput = ({
   value,
   onChange,
+  onBlur,
+  onTabOut,
   placeholder,
   disabled,
   inputRef,
@@ -29,6 +33,11 @@ const FilterInput = ({
   const [theme] = useTheme();
 
   const handleOnKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Tab') {
+      onTabOut?.(e);
+      return;
+    }
+
     // Let parent handle key navigation
     if (
       e.key === 'Escape' ||
@@ -46,12 +55,12 @@ const FilterInput = ({
     outline: none;
     background: transparent;
     font: inherit;
-    color: ${theme.color.text.primary};
+    color: ${theme.colour.text.default};
     &::placeholder {
-      color: ${theme.color.text.secondary};
+      color: ${theme.colour.text.tertiary};
     }
     &:disabled {
-      color: ${theme.color.text.disabled};
+      color: ${theme.colour.text.disabled};
       cursor: not-allowed;
     }
   `;
@@ -63,6 +72,7 @@ const FilterInput = ({
       placeholder={placeholder}
       disabled={disabled}
       onChange={(e) => onChange(e.target.value)}
+      onBlur={onBlur}
       onClick={(e) => e.stopPropagation()}
       onKeyDown={(e) => handleOnKeyDown(e)}
       aria-label='Filter options'