uikit-react-public 0.49.4 → 0.49.6

package/lib/components/ToggleGroup/ToggleGroup.tsx

@@ -0,0 +1,144 @@
+import type React from 'react';
+import {
+  Children,
+  isValidElement,
+  KeyboardEvent,
+  useId,
+  useState,
+} from 'react';
+
+import { css } from '@emotion/css';
+import useTheme from '../../theme/useTheme';
+import useMediaQuery from '../../hooks/useMediaQuery';
+import Select, { NonClearableSelectProps } from '../Select';
+import ToggleGroupContext from './ToggleGroupContext';
+import Item, { ItemProps } from './subcomponents/Item';
+
+export interface ToggleGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  selectProps?: Omit<
+    NonClearableSelectProps<string>,
+    'options' | 'value' | 'onValueChange'
+  >;
+}
+
+const MOBILE_SELECT_ITEM_THRESHOLD = 2;
+
+const NAVIGATION_KEYS = ['ArrowRight', 'ArrowLeft', 'Home', 'End'];
+
+const getEnabledItems = (container: HTMLElement) =>
+  Array.from(
+    container.querySelectorAll<HTMLInputElement>(
+      '[role="radio"]:not(:disabled)'
+    )
+  );
+
+const getItemsFromChildren = (
+  children: React.ReactNode
+): React.ReactElement<ItemProps>[] =>
+  Children.toArray(children).flatMap((child) => {
+    if (!isValidElement<{ children?: React.ReactNode }>(child)) {
+      return [];
+    }
+    if (child.type === Item) {
+      return [child as React.ReactElement<ItemProps>];
+    }
+    return getItemsFromChildren(child.props.children);
+  });
+
+const ToggleGroup = ({
+  children,
+  value,
+  defaultValue,
+  onValueChange,
+  selectProps,
+}: ToggleGroupProps) => {
+  const [theme] = useTheme();
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+  const isControlled = value !== undefined;
+  const selectedValue = value ?? uncontrolledValue;
+  const isMobile = !useMediaQuery(`(min-width: ${theme.breakpoints.tablet}px)`);
+  const items = getItemsFromChildren(children);
+  const name = useId();
+
+  const setValue = (nextValue: string) => {
+    if (!isControlled) {
+      setUncontrolledValue(nextValue);
+    }
+
+    onValueChange?.(nextValue);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (!NAVIGATION_KEYS.includes(event.key)) {
+      return;
+    }
+
+    const enabledItems = getEnabledItems(event.currentTarget);
+    const currentIndex = enabledItems.indexOf(
+      document.activeElement as HTMLInputElement
+    );
+
+    if (currentIndex === -1) {
+      return;
+    }
+
+    event.preventDefault();
+
+    const nextIndex =
+      {
+        ArrowRight: (currentIndex + 1) % enabledItems.length,
+        ArrowLeft:
+          (currentIndex - 1 + enabledItems.length) % enabledItems.length,
+        Home: 0,
+        End: enabledItems.length - 1,
+      }[event.key] ?? currentIndex;
+
+    const nextItem = enabledItems[nextIndex];
+    nextItem.focus();
+    setValue(nextItem.dataset.uclToggleGroupValue as string);
+  };
+
+  const toggleGroupStyle = css`
+    display: flex;
+    gap: -1px;
+    padding: ${theme.padding.p4};
+    background-color: ${theme.colour.fill.subtle};
+    border-radius: ${theme.radius.r4};
+  `;
+
+  if (isMobile && items.length > MOBILE_SELECT_ITEM_THRESHOLD) {
+    return (
+      <Select
+        {...selectProps}
+        options={items.map((item) => ({
+          label: item.props.label,
+          value: item.props.value,
+        }))}
+        value={selectedValue}
+        onValueChange={setValue}
+      />
+    );
+  }
+
+  return (
+    <ToggleGroupContext.Provider
+      value={{ value: selectedValue, setValue, name }}
+    >
+      <div
+        className={toggleGroupStyle}
+        role='radiogroup'
+        onKeyDown={handleKeyDown}
+      >
+        {children}
+      </div>
+    </ToggleGroupContext.Provider>
+  );
+};
+
+ToggleGroup.Item = Item;
+
+export default ToggleGroup;

package/lib/components/ToggleGroup/ToggleGroupContext.tsx

@@ -0,0 +1,25 @@
+import { createContext, use } from 'react';
+
+export interface ToggleGroupContextType {
+  value: string | undefined;
+  setValue: (value: string) => void;
+  name: string;
+}
+
+const ToggleGroupContext = createContext<ToggleGroupContextType | undefined>(
+  undefined
+);
+
+export const useToggleGroupContext = () => {
+  const context = use(ToggleGroupContext);
+
+  if (!context) {
+    throw new Error(
+      'ToggleGroupItem must be used within a ToggleGroup component'
+    );
+  }
+
+  return context;
+};
+
+export default ToggleGroupContext;

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

@@ -0,0 +1,468 @@
+import { beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import ToggleGroup from '../ToggleGroup';
+import ToggleGroupItem from '../subcomponents/Item';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+
+const mockMatchMedia = (matchesDesktop: boolean) => {
+  globalThis.matchMedia = vi.fn().mockImplementation((query) => ({
+    matches: query.includes('min-width') ? matchesDesktop : false,
+    media: query,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));
+};
+
+const wrap = (ui: React.ReactElement) =>
+  render(<ThemeContextProvider>{ui}</ThemeContextProvider>);
+
+describe('ToggleGroup', () => {
+  beforeEach(() => {
+    mockMatchMedia(true);
+  });
+
+  test('renders a radiogroup with selectable radio items', () => {
+    const onValueChange = vi.fn();
+
+    wrap(
+      <ToggleGroup
+        defaultValue='option-1'
+        onValueChange={onValueChange}
+      >
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+      </ToggleGroup>
+    );
+
+    expect(screen.getByRole('radiogroup')).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: 'Option 1' })).toHaveAttribute(
+      'aria-checked',
+      'true'
+    );
+
+    fireEvent.click(screen.getByRole('radio', { name: 'Option 2' }));
+
+    expect(onValueChange).toHaveBeenCalledWith('option-2');
+    expect(screen.getByRole('radio', { name: 'Option 2' })).toHaveAttribute(
+      'aria-checked',
+      'true'
+    );
+    expect(screen.getByRole('radio', { name: 'Option 1' })).toHaveAttribute(
+      'aria-checked',
+      'false'
+    );
+  });
+
+  test('only ever has one selected item at a time', () => {
+    wrap(
+      <ToggleGroup defaultValue='option-1'>
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    fireEvent.click(screen.getByRole('radio', { name: 'Option 3' }));
+
+    const checked = screen
+      .getAllByRole('radio')
+      .filter((item) => item.getAttribute('aria-checked') === 'true');
+
+    expect(checked).toHaveLength(1);
+    expect(checked[0]).toHaveAccessibleName('Option 3');
+  });
+
+  test('behaves as a controlled component when value is provided', () => {
+    const onValueChange = vi.fn();
+
+    const { rerender } = wrap(
+      <ToggleGroup
+        value='option-1'
+        onValueChange={onValueChange}
+      >
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+      </ToggleGroup>
+    );
+
+    fireEvent.click(screen.getByRole('radio', { name: 'Option 2' }));
+
+    expect(onValueChange).toHaveBeenCalledWith('option-2');
+    // Selection does not change without the caller updating the value prop
+    expect(screen.getByRole('radio', { name: 'Option 1' })).toHaveAttribute(
+      'aria-checked',
+      'true'
+    );
+
+    rerender(
+      <ThemeContextProvider>
+        <ToggleGroup
+          value='option-2'
+          onValueChange={onValueChange}
+        >
+          <ToggleGroupItem
+            value='option-1'
+            label='Option 1'
+          />
+          <ToggleGroupItem
+            value='option-2'
+            label='Option 2'
+          />
+        </ToggleGroup>
+      </ThemeContextProvider>
+    );
+
+    expect(screen.getByRole('radio', { name: 'Option 2' })).toHaveAttribute(
+      'aria-checked',
+      'true'
+    );
+  });
+
+  test('moves focus and selection with arrow keys', () => {
+    wrap(
+      <ToggleGroup defaultValue='option-1'>
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    const option1 = screen.getByRole('radio', { name: 'Option 1' });
+    const option2 = screen.getByRole('radio', { name: 'Option 2' });
+    const option3 = screen.getByRole('radio', { name: 'Option 3' });
+
+    option1.focus();
+    fireEvent.keyDown(screen.getByRole('radiogroup'), { key: 'ArrowRight' });
+
+    expect(option2).toHaveFocus();
+    expect(option2).toHaveAttribute('aria-checked', 'true');
+
+    fireEvent.keyDown(screen.getByRole('radiogroup'), { key: 'End' });
+
+    expect(option3).toHaveFocus();
+    expect(option3).toHaveAttribute('aria-checked', 'true');
+
+    fireEvent.keyDown(screen.getByRole('radiogroup'), { key: 'Home' });
+
+    expect(option1).toHaveFocus();
+    expect(option1).toHaveAttribute('aria-checked', 'true');
+
+    fireEvent.keyDown(screen.getByRole('radiogroup'), { key: 'ArrowLeft' });
+
+    expect(option3).toHaveFocus();
+    expect(option3).toHaveAttribute('aria-checked', 'true');
+  });
+
+  test('skips disabled items when navigating with arrow keys', () => {
+    wrap(
+      <ToggleGroup defaultValue='option-1'>
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+          disabled
+        />
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    const option1 = screen.getByRole('radio', { name: 'Option 1' });
+    const option3 = screen.getByRole('radio', { name: 'Option 3' });
+
+    option1.focus();
+    fireEvent.keyDown(screen.getByRole('radiogroup'), { key: 'ArrowRight' });
+
+    expect(option3).toHaveFocus();
+  });
+
+  test('ignores non-navigation keys', () => {
+    wrap(
+      <ToggleGroup defaultValue='option-1'>
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+      </ToggleGroup>
+    );
+
+    const option1 = screen.getByRole('radio', { name: 'Option 1' });
+
+    option1.focus();
+    fireEvent.keyDown(screen.getByRole('radiogroup'), { key: 'a' });
+
+    expect(option1).toHaveFocus();
+    expect(option1).toHaveAttribute('aria-checked', 'true');
+  });
+});
+
+describe('ToggleGroup mobile select fallback', () => {
+  beforeAll(() => {
+    // CustomOption scrolls the selected option into view; jsdom has no layout engine.
+    Object.defineProperty(Element.prototype, 'scrollIntoView', {
+      value: vi.fn(),
+      writable: true,
+    });
+  });
+
+  beforeEach(() => {
+    mockMatchMedia(false);
+  });
+
+  test('renders the radiogroup on mobile when item count is at or below the threshold', () => {
+    wrap(
+      <ToggleGroup defaultValue='option-1'>
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+      </ToggleGroup>
+    );
+
+    expect(screen.getByRole('radiogroup')).toBeInTheDocument();
+    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+  });
+
+  test('renders a Select instead of the radiogroup once item count exceeds the threshold', () => {
+    wrap(
+      <ToggleGroup defaultValue='option-1'>
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    expect(screen.queryByRole('radiogroup')).not.toBeInTheDocument();
+    expect(screen.getByRole('combobox')).toBeInTheDocument();
+  });
+
+  test('counts items nested in fragments toward the mobile select threshold', async () => {
+    const user = userEvent.setup();
+
+    wrap(
+      <ToggleGroup defaultValue='option-1'>
+        <>
+          <ToggleGroupItem
+            value='option-1'
+            label='Option 1'
+          />
+          <ToggleGroupItem
+            value='option-2'
+            label='Option 2'
+          />
+        </>
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    expect(screen.getByRole('combobox')).toBeInTheDocument();
+
+    await user.click(screen.getByRole('combobox'));
+
+    expect(
+      screen.getByRole('option', { name: 'Option 1' })
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('option', { name: 'Option 2' })
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('option', { name: 'Option 3' })
+    ).toBeInTheDocument();
+  });
+
+  test('updates the selected value when an option is chosen from the mobile select', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    wrap(
+      <ToggleGroup
+        defaultValue='option-1'
+        onValueChange={onValueChange}
+      >
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    await user.click(screen.getByRole('combobox'));
+    await user.click(screen.getByRole('option', { name: 'Option 2' }));
+
+    expect(onValueChange).toHaveBeenCalledWith('option-2');
+    expect(screen.getByRole('combobox')).toHaveTextContent('Option 2');
+  });
+
+  // The Select fallback only forwards `label`/`value` for each item, so a disabled
+  // ToggleGroupItem's disabled state is not carried over to the mobile Select option.
+  test('does not prevent selection of a disabled item in the mobile select', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    wrap(
+      <ToggleGroup
+        defaultValue='option-1'
+        onValueChange={onValueChange}
+      >
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+          disabled
+        />
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    await user.click(screen.getByRole('combobox'));
+    await user.click(screen.getByRole('option', { name: 'Option 2' }));
+
+    expect(onValueChange).toHaveBeenCalledWith('option-2');
+  });
+
+  test('renders a native <select> with matching options when selectProps requests the native variant', () => {
+    wrap(
+      <ToggleGroup
+        defaultValue='option-1'
+        selectProps={{
+          native: true,
+          nativeHtmlAttributes: { onChange: vi.fn() },
+        }}
+      >
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    const select = screen.getByTestId(
+      'ucl-uikit-select--native'
+    ) as HTMLSelectElement;
+
+    expect(select.tagName).toBe('SELECT');
+    expect(select.value).toBe('option-1');
+    expect(
+      Array.from(select.querySelectorAll('option')).map(
+        (option) => option.textContent
+      )
+    ).toEqual(['Option 1', 'Option 2', 'Option 3']);
+  });
+
+  test('relies on the caller-supplied nativeHtmlAttributes.onChange rather than onValueChange for native selects', () => {
+    const onValueChange = vi.fn();
+    const nativeOnChange = vi.fn();
+
+    wrap(
+      <ToggleGroup
+        defaultValue='option-1'
+        onValueChange={onValueChange}
+        selectProps={{
+          native: true,
+          nativeHtmlAttributes: { onChange: nativeOnChange },
+        }}
+      >
+        <ToggleGroupItem
+          value='option-1'
+          label='Option 1'
+        />
+        <ToggleGroupItem
+          value='option-2'
+          label='Option 2'
+        />
+        <ToggleGroupItem
+          value='option-3'
+          label='Option 3'
+        />
+      </ToggleGroup>
+    );
+
+    fireEvent.change(screen.getByTestId('ucl-uikit-select--native'), {
+      target: { value: 'option-2' },
+    });
+
+    expect(nativeOnChange).toHaveBeenCalled();
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+});

package/lib/components/ToggleGroup/index.ts

@@ -0,0 +1,4 @@
+export { default } from './ToggleGroup';
+export type { ToggleGroupProps } from './ToggleGroup';
+export { default as Item } from './subcomponents/Item';
+export type { ItemProps } from './subcomponents/Item';

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

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import ToggleGroup from '../ToggleGroup';
+import Item from './Item';
+
+const meta = {
+  title: 'Components/ToggleGroup/Item',
+  component: Item,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ToggleGroup defaultValue='option-1'>
+        <Story />
+      </ToggleGroup>
+    ),
+  ],
+} satisfies Meta<typeof Item>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Selected: Story = {
+  args: {
+    value: 'option-1',
+    label: 'Selected',
+  },
+};
+
+export const Unselected: Story = {
+  args: {
+    value: 'option-2',
+    label: 'Unselected',
+  },
+};
+
+export const WithIcon: Story = {
+  args: {
+    value: 'option-2',
+    label: 'With icon',
+    icon: 'Calendar',
+  },
+};
+
+export const WithSublabel: Story = {
+  args: {
+    value: 'option-2',
+    label: 'With sublabel',
+    sublabel: 'Sublabel text',
+    icon: 'User',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    value: 'option-2',
+    label: 'Disabled',
+    disabled: true,
+  },
+};