uikit-react-public 0.49.4 → 0.49.6

package/lib/components/Icon/svgImports.ts

@@ -321,7 +321,9 @@ interface SVGRProps {
 
 type IconComponent = (props: SVGProps<SVGSVGElement> & SVGRProps) => ReactNode;
 
-const iconSvgs: Record<string, IconComponent> = {
+// `satisfies` keeps literal key names (needed for icon name autocomplete/type-checking)
+// while still validating every value matches IconComponent.
+const iconSvgs = {
   Activity,
   Airplay,
   AlertCircle,
@@ -618,6 +620,6 @@ const iconSvgs: Record<string, IconComponent> = {
   Zap,
   ZoomIn,
   ZoomOut,
-};
+} satisfies Record<string, IconComponent>;
 
 export default iconSvgs;

package/lib/components/Overlay/Overlay.tsx

@@ -19,6 +19,7 @@ import {
   size as fuiSize,
   autoUpdate,
   Placement,
+  type Derivable,
   type FlipOptions,
   type ShiftOptions,
   type Strategy,
@@ -47,7 +48,7 @@ export interface OverlayProps extends HTMLAttributes<HTMLDivElement> {
   strategy?: Strategy;
   blanket?: boolean;
   flip?: boolean | FlipOptions;
-  shift?: boolean | ShiftOptions;
+  shift?: boolean | ShiftOptions | Derivable<ShiftOptions>;
   offset?: number;
   size?: boolean | OverlaySizeOptions;
   arrow?: ReactElement;
@@ -99,8 +100,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 +111,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),

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();

package/lib/components/Select/index.ts

@@ -1,2 +1,6 @@
 export { default } from './Select';
-export type { SelectProps, OptionData } from './Select.types';
+export type {
+  SelectProps,
+  NonClearableSelectProps,
+  OptionData,
+} from './Select.types';

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

@@ -5,6 +5,7 @@ import {
   useLayoutEffect,
   useMemo,
   useId,
+  useCallback,
 } from 'react';
 import { css, cx } from '@emotion/css';
 import { VisibleField, Panel, CustomOption, FilterInput } from '.';
@@ -93,23 +94,25 @@ const CustomSelect = <T extends string | number>({
 
   const internalRef = useRef<HTMLDivElement>(null);
   const effectiveRef = internalRef;
-  const openedViaFocusRef = useRef(false);
-  const skipOpenOnFocusRef = useRef(false);
-
-  const setRefs = (node: HTMLDivElement | null) => {
-    internalRef.current = node;
-    if (typeof ref === 'function') {
-      ref(node);
-    } else if (
-      ref &&
-      'current' in
-        (ref as React.RefObject<HTMLDivElement | HTMLSelectElement | null>)
-    ) {
-      (
-        ref as React.RefObject<HTMLDivElement | HTMLSelectElement | null>
-      ).current = node;
-    }
-  };
+
+  // Keep the anchor attached while the newly opened Overlay reads its ref.
+  const setRefs = useCallback(
+    (node: HTMLDivElement | null) => {
+      internalRef.current = node;
+      if (typeof ref === 'function') {
+        ref(node);
+      } else if (
+        ref &&
+        'current' in
+          (ref as React.RefObject<HTMLDivElement | HTMLSelectElement | null>)
+      ) {
+        (
+          ref as React.RefObject<HTMLDivElement | HTMLSelectElement | null>
+        ).current = node;
+      }
+    },
+    [ref]
+  );
 
   const [theme] = useTheme();
   const [isOpen, setIsOpen] = useState(false);
@@ -371,10 +374,6 @@ const CustomSelect = <T extends string | number>({
 
   const handleClick = (event: React.MouseEvent) => {
     if (disabled) return;
-    if (openedViaFocusRef.current) {
-      openedViaFocusRef.current = false;
-      return;
-    }
     if (!isOpen) {
       openPanel();
       if (filterable && filterInputRef.current) {
@@ -485,6 +484,20 @@ const CustomSelect = <T extends string | number>({
 
     if (disabled) return;
 
+    const isAltGraph = event.getModifierState('AltGraph');
+    const isPrintableCharacter =
+      event.key.length === 1 &&
+      event.key !== ' ' &&
+      !event.metaKey &&
+      ((!event.altKey && !event.ctrlKey) || isAltGraph);
+
+    if (filterable && !isOpen && isPrintableCharacter) {
+      event.preventDefault();
+      setFilterText(event.key);
+      openPanel();
+      return;
+    }
+
     if (event.key === 'Enter') {
       if (!isOpen) {
         openPanel();
@@ -507,7 +520,6 @@ const CustomSelect = <T extends string | number>({
         closePanel();
         // Return focus to the combobox so the screen reader stays on the control
         // instead of falling back to the document/page title.
-        skipOpenOnFocusRef.current = true;
         effectiveRef.current?.focus();
         return;
       }
@@ -521,7 +533,6 @@ const CustomSelect = <T extends string | number>({
     }
     if (isOpen && event.key === 'Escape') {
       closePanel();
-      skipOpenOnFocusRef.current = true;
       event.currentTarget.focus();
       return;
     }
@@ -572,19 +583,6 @@ const CustomSelect = <T extends string | number>({
     }
   };
 
-  const handleFocus = (event: React.FocusEvent<HTMLDivElement>) => {
-    if (disabled) return;
-    if (skipOpenOnFocusRef.current) {
-      skipOpenOnFocusRef.current = false;
-      return;
-    }
-    const isKeyboardFocus = event.currentTarget.matches(':focus-visible');
-    if (filterable && isKeyboardFocus) {
-      openedViaFocusRef.current = true;
-      openPanel();
-      if (filterInputRef.current) filterInputRef.current.focus();
-    }
-  };
   const { md } = theme.typography.body;
 
   const baseStyle = css`
@@ -668,7 +666,6 @@ const CustomSelect = <T extends string | number>({
     <div
       onClick={handleClick}
       onKeyDown={handleKeyDown}
-      onFocus={handleFocus}
       onBlur={handleBlur}
       tabIndex={disabled || (filterable && isOpen) ? -1 : 0}
       className={style}
@@ -710,7 +707,7 @@ const CustomSelect = <T extends string | number>({
           />
         )}
       </VisibleField>
-      {filterable && selectedOption && (
+      {filterable && isOpen && selectedOption && (
         <span
           id={selectionStatusId}
           className={visuallyHiddenStyle}
@@ -729,12 +726,15 @@ const CustomSelect = <T extends string | number>({
         <Overlay
           reference={effectiveRef}
           placement='bottom-start'
+          strategy='fixed'
           flip={{ padding: overlayViewportPadding }}
-          shift={{
+          shift={({ rects }) => ({
             padding: overlayViewportPadding,
-            mainAxis: false,
-            crossAxis: true,
-          }}
+            mainAxis:
+              dropdownWidth === 'content' &&
+              rects.floating.width > rects.reference.width,
+            crossAxis: false,
+          })}
           size={{
             matchReferenceWidth: true,
             padding: overlayViewportPadding,
@@ -747,7 +747,6 @@ const CustomSelect = <T extends string | number>({
             referenceWidth={
               overlaySize?.referenceWidth ?? panelReferenceWidth ?? undefined
             }
-            availableHeight={overlaySize?.availableHeight}
             maxWidth={panelMaxWidth ?? undefined}
             id={listboxId}
             role='listbox'

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

@@ -7,7 +7,6 @@ const NAME = 'ucl-uikit-select__panel';
 type PanelProps = React.ComponentPropsWithoutRef<'div'> & {
   dropdownWidth?: SelectDropdownWidth;
   referenceWidth?: number;
-  availableHeight?: number;
   maxWidth?: number;
 };
 
@@ -15,7 +14,6 @@ const Panel = ({
   className,
   dropdownWidth = 'content',
   referenceWidth,
-  availableHeight,
   maxWidth,
   ...props
 }: PanelProps) => {
@@ -32,19 +30,15 @@ const Panel = ({
     typeof maxWidth === 'number'
       ? `min(${maxWidth}px, calc(100vw - (${theme.margin.m32} * 2)))`
       : `calc(100vw - (${theme.margin.m32} * 2))`;
-  const maxHeightValue =
-    typeof availableHeight === 'number'
-      ? `min(400px, ${availableHeight}px)`
-      : '400px';
 
   const baseStyle = css`
     min-width: ${referenceWidthValue};
     width: fit-content;
     max-width: ${maxWidthValue};
-    max-height: ${maxHeightValue};
+    max-height: min(400px, var(--ucl-overlay-available-height, 400px));
     overflow-y: auto;
     overflow-x: hidden;
-    box-sizing: content-box;
+    box-sizing: border-box;
     padding: ${theme.padding.p8} 0;
     border: ${theme.border.b1} solid ${theme.colour.border.subtle};
     background-color: ${theme.colour.fill.inverse};

package/lib/components/ToggleGroup/ToggleGroup.mdx

@@ -0,0 +1,31 @@
+import * as ToggleGroupStories from "./ToggleGroup.stories";
+import { Meta, Title, Subtitle, Canvas, Controls } from "@storybook/addon-docs/blocks";
+
+<Meta of={ToggleGroupStories} />
+<Title />
+<Subtitle>A mutually-exclusive horizontal bar of radio buttons.</Subtitle>
+
+Use a `<ToggleGroup>` when you want the user to switch between two or more views, modes, or states that sit side by side (e.g. list / grid, day / week / month).
+
+<Canvas of={ToggleGroupStories.Default} sourceState="hidden" />
+
+## ToggleGroup.Item components
+
+### Icons
+Add any `<Icon>` to the left of the `<Item>`.
+
+<Canvas of={ToggleGroupStories.WithIcons} />
+
+### Sublabels
+Add a `sublabel` to the `<Item>`.
+
+<Canvas of={ToggleGroupStories.WithSublabels} />
+
+### Disabled
+Disable a given `<Item>`.
+
+<Canvas of={ToggleGroupStories.Disabled} />
+
+## Props
+
+<Controls of={ToggleGroupStories.Default} />

package/lib/components/ToggleGroup/ToggleGroup.stories.tsx

@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import ToggleGroup from './ToggleGroup';
+
+const meta = {
+  title: 'Components/ToggleGroup',
+  component: ToggleGroup,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ToggleGroup>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    defaultValue: 'option-1',
+    children: (
+      <>
+        <ToggleGroup.Item
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroup.Item
+          value='option-2'
+          label='Option 2'
+        />
+        <ToggleGroup.Item
+          value='option-3'
+          label='Option 3'
+        />
+      </>
+    ),
+  },
+};
+
+export const WithIcons: Story = {
+  args: {
+    defaultValue: 'option-1',
+    children: (
+      <>
+        <ToggleGroup.Item
+          value='option-1'
+          label='Option 1'
+          icon='BookOpen'
+        />
+        <ToggleGroup.Item
+          value='option-2'
+          label='Option 2'
+          icon='Calendar'
+        />
+        <ToggleGroup.Item
+          value='option-3'
+          label='Option 3'
+          icon='Star'
+        />
+        <ToggleGroup.Item
+          value='option-4'
+          label='Option 4'
+          icon='User'
+        />
+      </>
+    ),
+  },
+};
+
+export const WithSublabels: Story = {
+  args: {
+    defaultValue: 'option-1',
+    children: (
+      <>
+        <ToggleGroup.Item
+          value='option-1'
+          label='Option 1'
+          sublabel='Sublabel 1'
+        />
+        <ToggleGroup.Item
+          value='option-2'
+          label='Option 2'
+          sublabel='Sublabel 2'
+          icon='User'
+        />
+        <ToggleGroup.Item
+          value='option-3'
+          label='Option 3'
+          sublabel='Sublabel 3'
+        />
+      </>
+    ),
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    defaultValue: 'option-1',
+    children: (
+      <>
+        <ToggleGroup.Item
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroup.Item
+          value='option-2'
+          label='Option 2'
+          icon='Calendar'
+          disabled
+        />
+        <ToggleGroup.Item
+          value='option-3'
+          label='Option 3'
+          sublabel='Sublabel 3'
+          disabled
+        />
+      </>
+    ),
+  },
+};