uikit-react-public 0.49.5 → 0.50.0

package/lib/components/Filters/QuickFilter.tsx

@@ -0,0 +1,89 @@
+import { ButtonHTMLAttributes, memo } from 'react';
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../theme';
+import { useFiltersContext } from './Filters.context';
+
+export const NAME = 'ucl-uikit-quick-filter';
+
+export interface QuickFilterProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  selected?: boolean;
+  testId?: string;
+}
+
+const QuickFilter = ({
+  selected = false,
+  disabled = false,
+  testId = NAME,
+  className,
+  children,
+  type = 'button',
+  ...props
+}: QuickFilterProps) => {
+  const [theme] = useTheme();
+  const filtersContext = useFiltersContext();
+  const isDesktop = filtersContext?.isDesktop ?? true;
+  const typography = isDesktop
+    ? theme.typography.body.sm
+    : theme.typography.body.smSemibold;
+
+  const baseStyle = css`
+    min-height: ${isDesktop ? '28px' : '32px'};
+    padding: ${theme.padding.p4}
+      ${isDesktop ? theme.padding.p8 : theme.padding.p16};
+    border: ${theme.border.b1} solid ${theme.colour.border.brand};
+    border-radius: ${isDesktop ? theme.radius.r4 : theme.radius.r16};
+    box-sizing: border-box;
+    background-color: ${theme.colour.fill.default};
+    color: ${theme.colour.text.brand};
+    font-family: ${typography.fontFamily};
+    font-feature-settings: ${typography.fontSettings};
+    font-size: ${typography.fontSize}px;
+    font-weight: ${typography.fontWeight};
+    line-height: ${typography.lineHeight}%;
+    cursor: pointer;
+
+    &:hover {
+      background-color: ${theme.colour.fill.brandSubtleHover};
+    }
+
+    &:focus-visible {
+      outline: none;
+      box-shadow: ${theme.boxShadow.focus};
+    }
+  `;
+
+  const selectedStyle = css`
+    background-color: ${theme.colour.fill.brandSubtleSelected};
+    color: ${theme.colour.text.brandHover};
+  `;
+
+  const disabledStyle = css`
+    border-color: ${theme.colour.border.disabled};
+    background-color: ${theme.colour.fill.disabled};
+    color: ${theme.colour.text.disabled};
+    cursor: not-allowed;
+  `;
+
+  const style = cx(
+    NAME,
+    baseStyle,
+    selected && selectedStyle,
+    disabled && disabledStyle,
+    className
+  );
+
+  return (
+    <button
+      type={type}
+      className={style}
+      disabled={disabled}
+      aria-pressed={selected}
+      data-testid={testId}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+};
+
+export default memo(QuickFilter);

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

@@ -0,0 +1,230 @@
+import { useState } from 'react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ThemeContextProvider } from '../../../theme';
+import Filters from '../Filters';
+import Filter from '../Filter';
+import QuickFilter from '../QuickFilter';
+
+const setDesktopViewport = (matches: boolean) => {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation(() => ({
+      matches,
+      media: '',
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }))
+  );
+};
+
+const renderFilters = (component: React.ReactNode) =>
+  render(<ThemeContextProvider>{component}</ThemeContextProvider>);
+
+const StatefulMobileFilters = () => {
+  const [value, setValue] = useState('');
+
+  return (
+    <Filters
+      onOpenChange={() => {}}
+      onApply={() => {}}
+    >
+      <Filter
+        label='Search'
+        defaultOpen
+      >
+        <input
+          aria-label='Search records'
+          value={value}
+          onChange={(event) => setValue(event.target.value)}
+        />
+      </Filter>
+    </Filters>
+  );
+};
+
+describe('Filters', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  test('opens a desktop panel in an Overlay and closes on Apply', async () => {
+    setDesktopViewport(true);
+    const user = userEvent.setup();
+    const onApply = vi.fn();
+
+    const result = renderFilters(
+      <Filters>
+        <Filter
+          label='File type'
+          onApply={onApply}
+        >
+          Panel controls
+        </Filter>
+      </Filters>
+    );
+
+    const trigger = result.getByRole('button', { name: 'File type' });
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    await user.click(trigger);
+
+    const panel = result.getByRole('dialog', { name: 'File type filter' });
+    expect(panel.parentElement).toHaveClass('ucl-overlay');
+    expect(panel).toHaveTextContent('Panel controls');
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    await user.click(result.getByRole('button', { name: 'Apply' }));
+
+    expect(onApply).toHaveBeenCalledOnce();
+    expect(
+      result.queryByRole('dialog', { name: 'File type filter' })
+    ).not.toBeInTheDocument();
+  });
+
+  test('closes a desktop filter on Escape and restores trigger focus', async () => {
+    setDesktopViewport(true);
+    const user = userEvent.setup();
+
+    const result = renderFilters(
+      <Filters>
+        <Filter label='Status'>Panel controls</Filter>
+      </Filters>
+    );
+
+    const trigger = result.getByRole('button', { name: 'Status' });
+    await user.click(trigger);
+    await user.keyboard('{Escape}');
+
+    expect(result.queryByText('Panel controls')).not.toBeInTheDocument();
+    expect(trigger).toHaveFocus();
+  });
+
+  test('renders mobile filters in a bottom sheet and expands a filter inline', async () => {
+    setDesktopViewport(false);
+    const user = userEvent.setup();
+    const onApply = vi.fn();
+    const onReset = vi.fn();
+
+    const result = renderFilters(
+      <Filters
+        appliedCount={2}
+        onApply={onApply}
+        onReset={onReset}
+      >
+        <Filter
+          label='File type'
+          appliedCount={2}
+        >
+          Panel controls
+        </Filter>
+      </Filters>
+    );
+
+    const groupTrigger = result.getByRole('button', {
+      name: 'Filters, 2 applied',
+    });
+    expect(groupTrigger).toHaveTextContent('');
+    await user.click(groupTrigger);
+
+    expect(result.getByRole('dialog', { name: 'Filters' })).toBeInTheDocument();
+    expect(result.getByTestId('ucl-blanket')).toBeInTheDocument();
+    expect(result.queryByText('Panel controls')).not.toBeInTheDocument();
+
+    await user.click(result.getByRole('button', { name: /File type/ }));
+    expect(result.getByText('Panel controls')).toBeInTheDocument();
+
+    await user.click(result.getByRole('button', { name: 'Reset all' }));
+    expect(onReset).toHaveBeenCalledOnce();
+
+    await user.click(result.getByRole('button', { name: 'Apply filters' }));
+    expect(onApply).toHaveBeenCalledOnce();
+    expect(
+      result.queryByRole('dialog', { name: 'Filters' })
+    ).not.toBeInTheDocument();
+  });
+
+  test('preserves focus when an inline open callback changes identity', async () => {
+    setDesktopViewport(false);
+    const user = userEvent.setup();
+    const result = renderFilters(<StatefulMobileFilters />);
+
+    await user.click(result.getByRole('button', { name: 'Filters' }));
+
+    const input = result.getByRole('textbox', { name: 'Search records' });
+    await user.click(input);
+    await user.type(input, 'report');
+
+    expect(input).toHaveFocus();
+    expect(input).toHaveValue('report');
+  });
+
+  test('supports controlled open state', async () => {
+    setDesktopViewport(true);
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+
+    const result = renderFilters(
+      <Filters>
+        <Filter
+          label='Status'
+          open={false}
+          onOpenChange={onOpenChange}
+        >
+          Panel controls
+        </Filter>
+      </Filters>
+    );
+
+    await user.click(result.getByRole('button', { name: 'Status' }));
+
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    expect(result.queryByText('Panel controls')).not.toBeInTheDocument();
+  });
+
+  test('keeps only one filter open at a time', async () => {
+    setDesktopViewport(true);
+    const user = userEvent.setup();
+
+    const result = renderFilters(
+      <Filters>
+        <Filter label='File type'>File controls</Filter>
+        <Filter label='Status'>Status controls</Filter>
+      </Filters>
+    );
+
+    await user.click(result.getByRole('button', { name: 'File type' }));
+    expect(result.getByText('File controls')).toBeInTheDocument();
+
+    await user.click(result.getByRole('button', { name: 'Status' }));
+    expect(result.queryByText('File controls')).not.toBeInTheDocument();
+    expect(result.getByText('Status controls')).toBeInTheDocument();
+  });
+
+  test('QuickFilter exposes its selected state', async () => {
+    setDesktopViewport(true);
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+
+    const result = renderFilters(
+      <QuickFilter
+        selected
+        onClick={onClick}
+      >
+        Last 30 days
+      </QuickFilter>
+    );
+
+    const quickFilter = result.getByRole('button', { name: 'Last 30 days' });
+    expect(quickFilter).toHaveAttribute('aria-pressed', 'true');
+
+    await user.click(quickFilter);
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+});

package/lib/components/Filters/index.ts

@@ -0,0 +1,6 @@
+export { default } from './Filters';
+export { default as Filter } from './Filter';
+export { default as QuickFilter } from './QuickFilter';
+export type { FiltersProps, FiltersSubComponents } from './Filters';
+export type { FilterProps } from './Filter';
+export type { QuickFilterProps } from './QuickFilter';

package/lib/components/Overlay/Overlay.tsx

@@ -19,6 +19,7 @@ import {
   size as fuiSize,
   autoUpdate,
   Placement,
+  type Derivable,
   type FlipOptions,
   type ShiftOptions,
   type Strategy,
@@ -43,11 +44,12 @@ export type OverlaySize = {
 
 export interface OverlayProps extends HTMLAttributes<HTMLDivElement> {
   reference: RefObject<HTMLElement | null>;
+  positioning?: 'reference' | 'viewport';
   placement?: Placement;
   strategy?: Strategy;
   blanket?: boolean;
   flip?: boolean | FlipOptions;
-  shift?: boolean | ShiftOptions;
+  shift?: boolean | ShiftOptions | Derivable<ShiftOptions>;
   offset?: number;
   size?: boolean | OverlaySizeOptions;
   arrow?: ReactElement;
@@ -62,6 +64,7 @@ const Overlay = forwardRef<Ref, OverlayProps>(
   (
     {
       reference,
+      positioning = 'reference',
       placement = 'bottom',
       strategy = 'absolute',
       blanket = false,
@@ -99,8 +102,7 @@ const Overlay = forwardRef<Ref, OverlayProps>(
           ...(typeof flip === 'object' ? flip : {}),
         })
       );
-    if (shift)
-      fuiMiddleware.push(fuiShift(typeof shift === 'object' ? shift : {}));
+    if (shift) fuiMiddleware.push(fuiShift(shift === true ? {} : shift));
     if (size) {
       const sizeOptions = typeof size === 'object' ? size : {};
       const { padding = 0, matchReferenceWidth = false } = sizeOptions;
@@ -111,6 +113,12 @@ const Overlay = forwardRef<Ref, OverlayProps>(
           apply({ availableWidth, availableHeight, elements, rects }) {
             const { style } = elements.floating;
 
+            // CSS var applies before remeasurement; React props update too late.
+            style.setProperty(
+              '--ucl-overlay-available-height',
+              `${Math.max(0, availableHeight)}px`
+            );
+
             onSizeChange?.({
               referenceWidth: rects.reference.width,
               availableWidth: Math.max(0, availableWidth),
@@ -140,6 +148,7 @@ const Overlay = forwardRef<Ref, OverlayProps>(
 
     const overlayPlacement = currentPlacement.split('-')[0] as
       'left' | 'right' | 'top' | 'bottom';
+    const isReferencePositioned = positioning === 'reference';
 
     useLayoutEffect(() => {
       refs.setReference(reference.current);
@@ -231,11 +240,13 @@ const Overlay = forwardRef<Ref, OverlayProps>(
           className={style}
           style={{
             ...(inlineStyle as CSSProperties),
-            position: strategy,
-            left: x ?? 0,
-            top: y ?? 0,
+            ...(isReferencePositioned && {
+              position: strategy,
+              left: x ?? 0,
+              top: y ?? 0,
+            }),
             visibility:
-              x === null || y === null
+              isReferencePositioned && (x === null || y === null)
                 ? 'hidden'
                 : (inlineStyle as CSSProperties | undefined)?.visibility,
           }}

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, test, vi } from 'vitest';
 import { useRef } from 'react';
 import { render, waitFor } from '@testing-library/react';
+import { css } from '@emotion/css';
 import Overlay from '../Overlay';
 
 describe('Overlay', () => {
@@ -78,4 +79,42 @@ describe('Overlay', () => {
       });
     });
   });
+
+  test('allows viewport positioning to be defined by className', async () => {
+    const TestOverlay = () => {
+      const reference = useRef<HTMLButtonElement>(null);
+      const viewportStyle = css`
+        position: fixed;
+        inset: auto 0 0;
+      `;
+
+      return (
+        <>
+          <button
+            ref={reference}
+            type='button'
+          >
+            Anchor
+          </button>
+          <Overlay
+            reference={reference}
+            positioning='viewport'
+            className={viewportStyle}
+          >
+            Content
+          </Overlay>
+        </>
+      );
+    };
+
+    const result = render(<TestOverlay />);
+    const overlay = result.container.querySelector('.ucl-overlay');
+
+    await waitFor(() => {
+      expect(overlay).toHaveStyle({
+        position: 'fixed',
+        inset: 'auto 0 0',
+      });
+    });
+  });
 });

package/lib/components/Select/Select.mdx

@@ -172,6 +172,7 @@ For very long labels, set `lineBreak` to allow breaking the text inside options.
 - In `selectionBehaviour="commit"`, arrow keys move highlight without changing value until Enter/click.
 - Tabbing away from an open custom dropdown closes it and lets focus move normally to the next or previous control.
 - Native variant leverages built-in browser semantics.
+- Tabbing to a filterable custom Select focuses the closed combobox. Typing starts filtering immediately; Enter, Space, an arrow key, or a click also opens the panel. Focus moves to the filter input when the panel opens.
 - The filter input (when `filterable` is true) is focusable when the panel opens; Escape and arrow keys bubble to the parent so the dropdown still closes/navigates.
 - In the custom variant, `clearable` emits `null` as the cleared value.
 - `filterInputProps` lets you forward ARIA hooks like `aria-describedby` to the filter input.

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

@@ -116,11 +116,70 @@ describe('Select', () => {
     expect(overlay).toHaveClass('ucl-overlay');
     await waitFor(() => {
       expect(overlay).toHaveStyle({
-        position: 'absolute',
+        position: 'fixed',
       });
     });
   });
 
+  test.each([
+    { fieldTop: 200, menuHeight: 120, menuTop: 248 },
+    { fieldTop: 500, menuHeight: 120, menuTop: 380 },
+    { fieldTop: 280, menuHeight: 400, menuTop: 328 },
+  ])(
+    'anchors the menu without covering the input at $fieldTop with height $menuHeight',
+    async ({ fieldTop, menuHeight, menuTop }) => {
+      vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(
+        800
+      );
+      vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(
+        600
+      );
+      vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(
+        240
+      );
+      vi.spyOn(HTMLElement.prototype, 'offsetHeight', 'get').mockReturnValue(
+        menuHeight
+      );
+      vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(
+        function (this: Element) {
+          return this.getAttribute('role') === 'combobox'
+            ? new DOMRect(80, fieldTop, 240, 48)
+            : new DOMRect(0, 0, 240, menuHeight);
+        }
+      );
+
+      try {
+        const user = userEvent.setup();
+        const result = render(
+          <ThemeContextProvider>
+            <Select
+              filterable
+              options={defaultOptions}
+              value='2'
+              onValueChange={() => {}}
+            />
+          </ThemeContextProvider>
+        );
+
+        await user.click(result.getByRole('combobox'));
+
+        const expectAnchoredMenu = () => {
+          expect(result.getByRole('listbox').parentElement).toHaveStyle({
+            position: 'fixed',
+            left: '80px',
+            top: `${menuTop}px`,
+          });
+        };
+        await waitFor(expectAnchoredMenu);
+
+        await user.type(result.getByRole('searchbox'), '2');
+        await waitFor(expectAnchoredMenu);
+      } finally {
+        vi.restoreAllMocks();
+      }
+    }
+  );
+
   test('dropdownWidth defaults to content width', async () => {
     const user = userEvent.setup();
     const renderResult = render(
@@ -743,7 +802,7 @@ describe('Select', () => {
     expect(filterInput).toHaveAttribute('aria-describedby', 'filter-hint');
   });
 
-  test('opens filter input on keyboard focus', async () => {
+  test('keeps a filterable select closed on keyboard focus', async () => {
     const user = userEvent.setup();
     const result = render(
       <ThemeContextProvider>
@@ -758,11 +817,79 @@ describe('Select', () => {
 
     await user.tab();
 
-    const filterInput = await result.findByRole('searchbox');
-    expect(filterInput).toHaveFocus();
+    const combobox = result.getByRole('combobox');
+    expect(combobox).toHaveFocus();
+    expect(combobox).toHaveAttribute('aria-expanded', 'false');
+    expect(result.queryByRole('searchbox')).not.toBeInTheDocument();
+    expect(result.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
+  test('does not duplicate the selected option text while closed', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <Select
+          filterable
+          options={defaultOptions}
+          value={defaultOptions[1].value}
+          onValueChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    await user.tab();
+
+    const combobox = result.getByRole('combobox');
+    expect(combobox).toHaveTextContent(defaultOptions[1].label);
+    expect(
+      result.queryByText(`${defaultOptions[1].label} selected`)
+    ).not.toBeInTheDocument();
+  });
+
+  test('opens a focused filterable select with ArrowDown and focuses its filter', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <Select
+          filterable
+          options={defaultOptions}
+          value=''
+          onValueChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    await user.tab();
+    await user.keyboard('{ArrowDown}');
+
+    expect(result.getByRole('searchbox')).toHaveFocus();
     expect(result.getByRole('listbox')).toBeInTheDocument();
   });
 
+  test('opens and filters when typing on a focused closed filterable select', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <Select
+          filterable
+          options={defaultOptions}
+          value=''
+          onValueChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    await user.tab();
+    await user.keyboard('2');
+
+    expect(result.getByRole('searchbox')).toHaveFocus();
+    expect(result.getByRole('searchbox')).toHaveValue('2');
+    expect(result.getAllByRole('option')).toHaveLength(1);
+    expect(
+      result.getByRole('option', { name: 'Option 2' })
+    ).toBeInTheDocument();
+  });
+
   test('pressing Escape closes dropdown and clears filter', async () => {
     const user = userEvent.setup();
     const result = render(
@@ -939,6 +1066,9 @@ describe('Select', () => {
 
     await user.tab();
     await user.tab();
+    expect(result.getByRole('combobox')).toHaveFocus();
+
+    await user.keyboard('{Enter}');
     expect(result.getByRole('searchbox')).toHaveFocus();
     expect(result.getByRole('listbox')).toBeInTheDocument();
 
@@ -985,6 +1115,9 @@ describe('Select', () => {
     );
 
     await user.tab();
+    expect(result.getByRole('combobox')).toHaveFocus();
+
+    await user.keyboard('{Enter}');
     const searchbox = result.getByRole('searchbox');
     expect(searchbox).toHaveFocus();
     expect(result.getByRole('listbox')).toBeInTheDocument();