uikit-react-public 0.30.1 → 0.32.4

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

@@ -518,6 +518,76 @@ describe('Select', () => {
     );
   });
 
+  test('selectionBehaviour=commit returns focus to the combobox on Enter (filterable)', async () => {
+    const user = userEvent.setup();
+
+    const ControlledSelect = () => {
+      const [value, setValue] = useState('');
+      return (
+        <Select
+          filterable
+          options={defaultOptions}
+          value={value}
+          selectionBehaviour='commit'
+          onValueChange={(next) => setValue(next as string)}
+        />
+      );
+    };
+
+    const result = render(
+      <ThemeContextProvider>
+        <ControlledSelect />
+      </ThemeContextProvider>
+    );
+
+    await user.click(result.getByTestId('ucl-uikit-select'));
+    // Filter input has focus while the panel is open
+    expect(result.getByRole('searchbox')).toHaveFocus();
+
+    await user.keyboard('{ArrowDown}');
+    await user.keyboard('{Enter}');
+
+    // Panel (and its filter input) has closed, and focus is back on the
+    // combobox rather than lost to the document body.
+    expect(
+      result.queryByTestId('ucl-uikit-select__panel')
+    ).not.toBeInTheDocument();
+    expect(result.getByRole('combobox')).toHaveFocus();
+  });
+
+  test('selectionBehaviour=commit announces the committed option via a live region', async () => {
+    const user = userEvent.setup();
+
+    const ControlledSelect = () => {
+      const [value, setValue] = useState('');
+      return (
+        <Select
+          filterable
+          options={defaultOptions}
+          value={value}
+          selectionBehaviour='commit'
+          onValueChange={(next) => setValue(next as string)}
+        />
+      );
+    };
+
+    const result = render(
+      <ThemeContextProvider>
+        <ControlledSelect />
+      </ThemeContextProvider>
+    );
+
+    const status = result.getByRole('status');
+    expect(status).toHaveTextContent('');
+
+    await user.click(result.getByTestId('ucl-uikit-select'));
+    await user.keyboard('{ArrowDown}');
+    await user.keyboard('{ArrowDown}');
+    await user.keyboard('{Enter}');
+
+    expect(status).toHaveTextContent('Option 2 selected');
+  });
+
   test('keyboard navigation does not get stuck on duplicate values', async () => {
     const user = userEvent.setup();
     const options = [
@@ -969,6 +1039,48 @@ describe('Select', () => {
     ).not.toBeInTheDocument();
   });
 
+  test('aria-activedescendant is absent immediately after opening with a preselected value', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <Select
+          options={defaultOptions}
+          value='2'
+          onValueChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    const combobox = result.getByRole('combobox');
+    await user.click(combobox);
+
+    expect(combobox).not.toHaveAttribute('aria-activedescendant');
+
+    await user.keyboard('{ArrowDown}');
+    expect(combobox).toHaveAttribute('aria-activedescendant');
+  });
+
+  test('filterable: aria-activedescendant is absent immediately after opening with a preselected value', async () => {
+    const user = userEvent.setup();
+    const result = render(
+      <ThemeContextProvider>
+        <Select
+          filterable
+          options={defaultOptions}
+          value='2'
+          onValueChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    await user.click(result.getByRole('combobox'));
+    const filterInput = result.getByRole('searchbox');
+    expect(filterInput).not.toHaveAttribute('aria-activedescendant');
+
+    await user.keyboard('{ArrowDown}');
+    expect(filterInput).toHaveAttribute('aria-activedescendant');
+  });
+
   test('disabled clearable select does not show clear button', () => {
     const result = render(
       <ThemeContextProvider>

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

@@ -35,5 +35,10 @@ exports[`Select > Snapshot: default 1`] = `
       />
     </svg>
   </div>
+  <span
+    aria-live="polite"
+    class="css-fj1rnv"
+    role="status"
+  />
 </div>
 `;

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

@@ -122,11 +122,15 @@ const CustomSelect = <T extends string | number>({
     null
   );
   const [overlaySize, setOverlaySize] = useState<OverlaySize | null>(null);
+  // Message announced via an aria-live region when a selection is committed,
+  // so screen reader users hear confirmation even after the panel/filter closes.
+  const [selectionAnnouncement, setSelectionAnnouncement] = useState('');
   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`;
+  const selectionStatusId = `${idBase}-selection-status`;
   const overlayViewportPadding = parseFloat(String(theme.margin.m32));
 
   // Returns a list of indexes of options that are currently visible based on the filter text
@@ -150,6 +154,12 @@ const CustomSelect = <T extends string | number>({
     if (!isOpen && filterText) setFilterText('');
   }, [isOpen, filterText]);
 
+  // Reset the live-region text when the panel opens so committing the same
+  // option again produces a changed value that screen readers will re-announce.
+  useEffect(() => {
+    if (isOpen && selectionAnnouncement) setSelectionAnnouncement('');
+  }, [isOpen, selectionAnnouncement]);
+
   useEffect(() => {
     const matchingIndexes = options.reduce<number[]>(
       (matches, option, index) => {
@@ -410,7 +420,9 @@ const CustomSelect = <T extends string | number>({
       ? visibleOptionIndexes[highlightedVisibleIndex]
       : null;
   const activeDescendantId =
-    isOpen && highlightedOptionSourceIndex !== null
+    isOpen &&
+    effectiveActiveOptionIndex !== null &&
+    highlightedOptionSourceIndex !== null
       ? `${idBase}-option-${highlightedOptionSourceIndex}`
       : undefined;
 
@@ -457,12 +469,21 @@ const CustomSelect = <T extends string | number>({
       if (selectionBehaviour === 'commit' && visibleOptions.length > 0) {
         const currentOptionIndex = getCurrentOptionIndex();
         if (currentOptionIndex !== null) {
+          const committedOption = visibleOptions[currentOptionIndex];
           const currentSourceIndex = visibleOptionIndexes[currentOptionIndex];
           setSelectedOptionIndex(currentSourceIndex);
-          onValueChange?.(visibleOptions[currentOptionIndex].value, event);
+          onValueChange?.(committedOption.value, event);
           setFilterText('');
+          // Announce the committed selection; the filter input (which carried the
+          // description) unmounts when the panel closes, so this live region is
+          // what confirms the choice to assistive tech.
+          setSelectionAnnouncement(`${committedOption.label} selected`);
         }
         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;
       }
 
@@ -581,8 +602,39 @@ const CustomSelect = <T extends string | number>({
     color: ${theme.color.text.secondary};
   `;
 
+  // Visually hidden but available to assistive technology
+  const visuallyHiddenStyle = css`
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  `;
+
   const style = cx(NAME, baseStyle, disabled && disabledStyle, className);
 
+  // Forward the combobox's accessible name/description onto the filter input so
+  // assistive tech announces the field label (and current selection) while filtering.
+  const filterInputA11yProps = {
+    ...(props['aria-label'] !== undefined
+      ? { 'aria-label': props['aria-label'] }
+      : {}),
+    ...(props['aria-labelledby'] !== undefined
+      ? { 'aria-labelledby': props['aria-labelledby'] }
+      : {}),
+    'aria-describedby':
+      [
+        props['aria-describedby'],
+        selectedOption ? selectionStatusId : undefined,
+      ]
+        .filter(Boolean)
+        .join(' ') || undefined,
+  };
+
   return (
     <div
       onClick={handleClick}
@@ -622,10 +674,26 @@ const CustomSelect = <T extends string | number>({
             ariaControls={listboxId}
             ariaExpanded={isOpen}
             ariaActiveDescendant={activeDescendantId}
+            {...filterInputA11yProps}
             {...filterInputProps}
           />
         )}
       </VisibleField>
+      {filterable && selectedOption && (
+        <span
+          id={selectionStatusId}
+          className={visuallyHiddenStyle}
+        >
+          {`${selectedOption.label} selected`}
+        </span>
+      )}
+      <span
+        role='status'
+        aria-live='polite'
+        className={visuallyHiddenStyle}
+      >
+        {selectionAnnouncement}
+      </span>
       {isOpen && (
         <Overlay
           reference={effectiveRef}
@@ -663,7 +731,11 @@ const CustomSelect = <T extends string | number>({
                 onSelect={handleSelect}
                 lineBreak={lineBreak}
                 role='option'
-                aria-selected={highlightedVisibleIndex === index}
+                aria-selected={
+                  effectiveActiveOptionIndex !== null
+                    ? highlightedVisibleIndex === index
+                    : undefined
+                }
                 aria-posinset={index + 1}
                 aria-setsize={visibleOptions.length}
                 {...option.optionProps}

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

@@ -75,13 +75,13 @@ const FilterInput = ({
       onBlur={onBlur}
       onClick={(e) => e.stopPropagation()}
       onKeyDown={(e) => handleOnKeyDown(e)}
-      aria-label='Filter options'
       aria-autocomplete='list'
       role='searchbox'
       aria-haspopup='listbox'
       aria-controls={ariaControls}
       aria-expanded={ariaExpanded}
       aria-activedescendant={ariaActiveDescendant}
+      aria-label='Filter options'
       {...rest}
     />
   );

package/lib/components/Sidebar/Sidebar.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { css } from '@emotion/css';
+import Sidebar from './Sidebar';
+import Icon from '../Icon';
+import Menu from '../MenuNew';
+
+const meta = {
+  title: 'Components/Sidebar',
+  component: Sidebar,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  argTypes: {
+    collapsed: { control: 'boolean' },
+    defaultCollapsed: { control: 'boolean' },
+    onCollapsedChange: { action: 'collapsed changed' },
+    testId: { control: { type: 'text' } },
+    className: { control: false },
+    children: { control: false },
+  },
+  args: {
+    defaultCollapsed: false,
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Sidebar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const pageStyle = css`
+  min-height: 100vh;
+  margin-left: 254px;
+  padding: 32px;
+  font-family: sans-serif;
+  background: #f5f7fa;
+`;
+
+const storyContent = (
+  <Menu>
+    <Menu.Section>
+      <Menu.Heading>Application</Menu.Heading>
+      <Menu.PrimaryItem
+        icon={<Icon.Home size={20} />}
+        active
+      >
+        Home
+      </Menu.PrimaryItem>
+      <Menu.PrimaryItem icon={<Icon.Search size={20} />}>
+        Search
+      </Menu.PrimaryItem>
+      <Menu.PrimaryItem icon={<Icon.Calendar size={20} />}>
+        Calendar
+      </Menu.PrimaryItem>
+      <Menu.PrimaryItem icon={<Icon.Settings size={20} />}>
+        Settings
+      </Menu.PrimaryItem>
+    </Menu.Section>
+    <Menu.Divider />
+    <Menu.Section>
+      <Menu.PrimaryItem icon={<Icon.HelpCircle size={20} />}>
+        Support
+      </Menu.PrimaryItem>
+    </Menu.Section>
+  </Menu>
+);
+
+export const Default: Story = {
+  render: (args) => (
+    <>
+      <Sidebar {...args}>{storyContent}</Sidebar>
+      <main className={pageStyle}>
+        <h1>Sidebar example</h1>
+        <p>
+          The sidebar stays fixed to the left and remains visible when
+          collapsed.
+        </p>
+      </main>
+    </>
+  ),
+};
+
+export const Collapsed: Story = {
+  args: {
+    defaultCollapsed: true,
+  },
+  render: (args) => (
+    <>
+      <Sidebar {...args}>{storyContent}</Sidebar>
+      <main className={pageStyle}>
+        <h1>Collapsed sidebar example</h1>
+      </main>
+    </>
+  ),
+};

package/lib/components/Sidebar/Sidebar.tsx

@@ -0,0 +1,208 @@
+import {
+  Children,
+  HTMLAttributes,
+  ReactElement,
+  cloneElement,
+  memo,
+  useId,
+  useState,
+} from 'react';
+import { css, cx } from '@emotion/css';
+import Icon from '../Icon';
+import IconButton from '../IconButton';
+import { useTheme } from '../../theme';
+import {
+  DEFAULT_Z_INDEX as HEADER_Z_INDEX,
+  HEADER_MOBILE_HEIGHT_PX,
+  HEADER_TABLET_HEIGHT_PX,
+} from '../HeaderNew';
+
+export const NAME = 'ucl-uikit-sidebar';
+
+export interface SidebarProps extends HTMLAttributes<HTMLElement> {
+  collapsed?: boolean;
+  defaultCollapsed?: boolean;
+  onCollapsedChange?: (collapsed: boolean) => void;
+  testId?: string;
+  collapseButtonAriaLabel?: string;
+  expandButtonAriaLabel?: string;
+}
+
+const Sidebar = ({
+  collapsed,
+  defaultCollapsed = false,
+  onCollapsedChange,
+  testId = NAME,
+  collapseButtonAriaLabel = 'Collapse sidebar',
+  expandButtonAriaLabel = 'Expand sidebar',
+  className,
+  children,
+  ...props
+}: SidebarProps) => {
+  const [theme] = useTheme();
+  const sidebarId = useId();
+  const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed);
+  const isCollapsed = collapsed ?? internalCollapsed;
+
+  const handleToggle = () => {
+    const nextCollapsed = !isCollapsed;
+
+    if (collapsed === undefined) {
+      setInternalCollapsed(nextCollapsed);
+    }
+
+    onCollapsedChange?.(nextCollapsed);
+  };
+
+  const baseStyle = css`
+    position: fixed;
+    inset: ${HEADER_MOBILE_HEIGHT_PX}px auto 0 0;
+    z-index: ${HEADER_Z_INDEX - 1};
+    box-sizing: border-box;
+    width: min(254px, 100vw);
+    padding: ${theme.padding.p24} ${theme.padding.p12};
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    background-color: ${theme.colour.surface.primary};
+    border-right: ${theme.border.b1} solid ${theme.colour.border.subtle};
+    color: ${theme.colour.text.default};
+    font-family: ${theme.font.family.primary};
+    transition:
+      width 160ms ease,
+      padding 160ms ease;
+
+    @media screen and (min-width: ${theme.breakpoints.tablet}px) {
+      width: 254px;
+    }
+
+    @media screen and (min-width: ${theme.breakpoints.desktop}px) {
+      inset: ${HEADER_TABLET_HEIGHT_PX}px auto 0 0;
+    }
+  `;
+
+  const collapsedStyle = css`
+    width: 64px;
+    padding: ${theme.padding.p16} ${theme.padding.p8};
+
+    @media screen and (min-width: ${theme.breakpoints.tablet}px) {
+      width: 64px;
+    }
+  `;
+
+  const menuBaseStyle = css`
+    width: calc(100% + ${theme.padding.p24});
+    margin-left: -${theme.padding.p12};
+    box-sizing: border-box;
+    flex: 1 1 auto;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    overflow-x: hidden;
+    overflow-y: auto;
+    background-color: transparent;
+    padding: 0 ${theme.padding.p12} !important;
+  `;
+
+  const menuCollapsedStyle = css`
+    width: calc(100% + ${theme.padding.p16});
+    margin-left: -${theme.padding.p8};
+    padding: 4px ${theme.padding.p8} 0 !important;
+  `;
+
+  const footerBaseStyle = css`
+    flex: 0 0 auto;
+    margin-top: auto;
+    padding-top: ${theme.padding.p16};
+    background-color: ${theme.colour.surface.primary};
+    display: flex;
+    justify-content: flex-end;
+  `;
+
+  const footerCollapsedStyle = css`
+    justify-content: center;
+  `;
+
+  const toggleStyle = css`
+    width: 32px;
+    height: 32px;
+    border-radius: 4px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: ${theme.colour.icon.default};
+
+    &:hover {
+      background-color: ${theme.colour.fill.brandSubtleHover};
+      color: ${theme.colour.icon.brandHover};
+    }
+  `;
+
+  const style = cx(NAME, baseStyle, isCollapsed && collapsedStyle, className);
+  const menuStyle = cx(menuBaseStyle, isCollapsed && menuCollapsedStyle);
+  const footerStyle = cx(footerBaseStyle, isCollapsed && footerCollapsedStyle);
+  const menu = cloneSidebarMenu(
+    Children.only(children) as ReactElement<SidebarChildProps>,
+    {
+      collapsed: isCollapsed,
+      className: menuStyle,
+      id: sidebarId,
+    }
+  );
+
+  return (
+    <aside
+      className={style}
+      data-testid={testId}
+      data-collapsed={isCollapsed}
+      {...props}
+    >
+      {menu}
+      <div className={footerStyle}>
+        <IconButton
+          type='button'
+          className={toggleStyle}
+          aria-controls={sidebarId}
+          aria-expanded={!isCollapsed}
+          aria-label={
+            isCollapsed ? expandButtonAriaLabel : collapseButtonAriaLabel
+          }
+          onClick={handleToggle}
+        >
+          {isCollapsed ? (
+            <Icon.ChevronsRight
+              size={20}
+              aria-hidden='true'
+              focusable='false'
+            />
+          ) : (
+            <Icon.ChevronsLeft
+              size={20}
+              aria-hidden='true'
+              focusable='false'
+            />
+          )}
+        </IconButton>
+      </div>
+    </aside>
+  );
+};
+
+interface SidebarChildProps {
+  collapsed?: boolean;
+  className?: string;
+  id?: string;
+}
+
+const cloneSidebarMenu = (
+  child: ReactElement<SidebarChildProps>,
+  props: Required<SidebarChildProps>
+) =>
+  cloneElement(child, {
+    id: props.id,
+    collapsed: props.collapsed,
+    className: cx(props.className, child.props.className),
+  });
+
+export default memo(Sidebar);

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

@@ -0,0 +1,96 @@
+import { describe, expect, test, vitest } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import Sidebar from '../Sidebar';
+import Icon from '../../Icon';
+import Menu from '../../MenuNew';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+
+const renderSidebar = (props = {}) =>
+  render(
+    <ThemeContextProvider>
+      <Sidebar {...props}>
+        <Menu>
+          <Menu.Section>
+            <Menu.Heading>Application</Menu.Heading>
+            <Menu.PrimaryItem
+              icon={<Icon.Home />}
+              active
+            >
+              Home
+            </Menu.PrimaryItem>
+            <Menu.PrimaryItem icon={<Icon.Search />}>Search</Menu.PrimaryItem>
+          </Menu.Section>
+        </Menu>
+      </Sidebar>
+    </ThemeContextProvider>
+  );
+
+describe('Sidebar', () => {
+  test('snapshot: no props', () => {
+    const renderResult = renderSidebar();
+    expect(renderResult.container.firstChild).toMatchSnapshot();
+  });
+
+  test('snapshot: defaultCollapsed prop true', () => {
+    const renderResult = renderSidebar({ defaultCollapsed: true });
+    expect(renderResult.container.firstChild).toMatchSnapshot();
+  });
+
+  test('Can find by default testId', () => {
+    renderSidebar();
+    const sidebar = screen.getByTestId('ucl-uikit-sidebar');
+    expect(sidebar).toBeInTheDocument();
+  });
+
+  test('Can find by custom testId', () => {
+    renderSidebar({ testId: 'custom-sidebar' });
+    const sidebar = screen.getByTestId('custom-sidebar');
+    expect(sidebar).toBeInTheDocument();
+  });
+
+  test('Toggles collapsed state', async () => {
+    const user = userEvent.setup();
+    renderSidebar();
+
+    const sidebar = screen.getByTestId('ucl-uikit-sidebar');
+    const toggle = screen.getByRole('button', { name: 'Collapse sidebar' });
+
+    expect(sidebar).toHaveAttribute('data-collapsed', 'false');
+    await user.click(toggle);
+    expect(sidebar).toHaveAttribute('data-collapsed', 'true');
+    expect(
+      screen.getByRole('button', { name: 'Expand sidebar' })
+    ).toBeInTheDocument();
+  });
+
+  test('Calls onCollapsedChange', async () => {
+    const user = userEvent.setup();
+    const onCollapsedChange = vitest.fn();
+    renderSidebar({ onCollapsedChange });
+
+    await user.click(screen.getByRole('button', { name: 'Collapse sidebar' }));
+    expect(onCollapsedChange).toHaveBeenCalledWith(true);
+  });
+
+  test('Supports controlled collapsed state', async () => {
+    const user = userEvent.setup();
+    const onCollapsedChange = vitest.fn();
+    renderSidebar({
+      collapsed: false,
+      onCollapsedChange,
+    });
+
+    const sidebar = screen.getByTestId('ucl-uikit-sidebar');
+    await user.click(screen.getByRole('button', { name: 'Collapse sidebar' }));
+
+    expect(onCollapsedChange).toHaveBeenCalledWith(true);
+    expect(sidebar).toHaveAttribute('data-collapsed', 'false');
+  });
+
+  test('Marks the active item as the current page', () => {
+    renderSidebar();
+    const activeItem = screen.getByText('Home').closest('[aria-current]');
+    expect(activeItem).toHaveAttribute('aria-current', 'page');
+  });
+});