uikit-react-public 0.29.6 → 0.30.0

package/lib/components/Tabs/Tabs.tsx

@@ -1,34 +1,91 @@
-import { memo, HTMLAttributes } from 'react';
-import { css, cx } from '@emotion/css';
+import {
+  Children,
+  HTMLAttributes,
+  NamedExoticComponent,
+  ReactNode,
+  isValidElement,
+  memo,
+  useId,
+  useState,
+} from 'react';
+import { cx } from '@emotion/css';
 import { useTheme } from '../../theme';
-import TabContext from './TabContext';
-import Tab from './Tab';
+import TabContext, { TabsActivationMode, TabsOrientation } from './TabContext';
+import Tab, { TabProps } from './Tab';
+import TabsList, { TabsListProps } from './TabsList';
+import TabsPanel, { TabsPanelProps } from './TabsPanel';
 import marginsStyle, { MarginProps } from '../common/marginsStyle';
 
 export const NAME = 'ucl-uikit-tabs';
 
 export interface TabsBaseProps extends Omit<
   HTMLAttributes<HTMLDivElement>,
-  'onChange'
+  'defaultValue' | 'onChange'
 > {
-  activeTab: string;
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  activationMode?: TabsActivationMode;
+  orientation?: TabsOrientation;
+  testId?: string;
+  ref?: React.Ref<HTMLDivElement>;
+  /** @deprecated Use value instead. */
+  activeTab?: string;
+  /** @deprecated Use onValueChange instead. */
   onChange?: (value: string) => void;
+  /** @deprecated Prefer setting fullWidth on Tabs.List. */
   fullWidth?: boolean;
-  testId?: string;
+  /** @deprecated Tabs now uses theme.colour.border.brand by default. */
   color?: string;
-  ref?: React.RefObject<HTMLDivElement>;
 }
 
 export type TabsProps = TabsBaseProps & MarginProps;
 
-type TabsComponent = React.FC<TabsProps> & {
+export interface TabsComponent extends NamedExoticComponent<TabsProps> {
+  List: typeof TabsList;
   Tab: typeof Tab;
+  Panel: typeof TabsPanel;
+  /** @deprecated Use Tabs.Tab instead. */
+  Trigger: typeof Tab;
+}
+
+const hasTabsList = (children: React.ReactNode) =>
+  Children.toArray(children).some(
+    (child) => isValidElement(child) && child.type === TabsList
+  );
+
+const getPanelValues = (children: ReactNode): Set<string> => {
+  const values = new Set<string>();
+
+  Children.toArray(children).forEach((child) => {
+    if (!isValidElement<{ value?: string; children?: ReactNode }>(child)) {
+      return;
+    }
+
+    if (child.type === TabsPanel && child.props.value) {
+      values.add(child.props.value);
+      return;
+    }
+
+    if (child.props.children) {
+      getPanelValues(child.props.children).forEach((panelValue) => {
+        values.add(panelValue);
+      });
+    }
+  });
+
+  return values;
 };
 
 const TabsBase = ({
+  value,
+  defaultValue,
+  onValueChange,
+  activationMode = 'automatic',
+  orientation = 'horizontal',
   activeTab,
   onChange,
-  fullWidth = true,
+  fullWidth,
   color,
   testId = NAME,
   className,
@@ -37,42 +94,77 @@ const TabsBase = ({
   ...props
 }: TabsProps) => {
   const [theme] = useTheme();
+  void color;
+  const generatedId = useId();
+  const [uncontrolledValue, setUncontrolledValue] = useState(
+    defaultValue ?? activeTab
+  );
+  const containsList = hasTabsList(children);
+  const panelValues = getPanelValues(children);
+  const isControlled = value !== undefined || activeTab !== undefined;
+  const selectedValue = value ?? activeTab ?? uncontrolledValue;
+  const shouldFill = fullWidth ?? !containsList;
+
+  const handleValueChange = (nextValue: string) => {
+    if (!isControlled) {
+      setUncontrolledValue(nextValue);
+    }
 
-  const handleTabChange = (value: string) => {
-    if (onChange) onChange(value);
+    onValueChange?.(nextValue);
+    onChange?.(nextValue);
   };
 
-  const baseStyle = css`
-    display: flex;
-    border-bottom: 1px solid ${theme.colour.border.subtle};
-  `;
+  const style = cx(NAME, marginsStyle(props, theme), className);
 
-  const style = cx(NAME, baseStyle, marginsStyle(props, theme), className);
+  const contextValue = {
+    value: selectedValue,
+    setValue: handleValueChange,
+    baseId: `ucl-uikit-tabs-${generatedId}`,
+    activationMode,
+    orientation,
+    fullWidth: shouldFill,
+    panelValues,
+  };
 
   return (
-    <TabContext.Provider
-      value={{
-        activeTab,
-        setActiveTab: handleTabChange,
-        onChange,
-        fullWidth,
-        color,
-      }}
-    >
-      <div
-        ref={ref}
-        className={style}
-        data-testid={testId}
-        role='tablist'
-        {...props}
-      >
-        {children}
-      </div>
+    <TabContext.Provider value={contextValue}>
+      {containsList ? (
+        <div
+          ref={ref}
+          className={style}
+          data-testid={testId}
+          {...props}
+        >
+          {children}
+        </div>
+      ) : (
+        <TabsList
+          ref={ref}
+          className={style}
+          data-testid={testId}
+          fullWidth={shouldFill}
+          {...props}
+        >
+          {children}
+        </TabsList>
+      )}
     </TabContext.Provider>
   );
 };
 
-const Tabs = memo(TabsBase) as unknown as TabsComponent;
-Tabs.Tab = Tab;
+const Tabs = Object.assign(memo(TabsBase), {
+  List: TabsList,
+  Tab,
+  Panel: TabsPanel,
+  Trigger: Tab,
+}) as TabsComponent;
+
+export type {
+  TabProps,
+  TabsActivationMode,
+  TabsListProps,
+  TabsOrientation,
+  TabsPanelProps,
+};
 
 export default Tabs;

package/lib/components/Tabs/TabsList.tsx

@@ -0,0 +1,134 @@
+import { HTMLAttributes, KeyboardEvent, memo } from 'react';
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../theme';
+import { useTabContext } from './TabContext';
+
+export const NAME = 'ucl-uikit-tabs__list';
+
+export interface TabsListProps extends HTMLAttributes<HTMLDivElement> {
+  fullWidth?: boolean;
+  testId?: string;
+  ref?: React.Ref<HTMLDivElement>;
+}
+
+const getEnabledTabs = (list: HTMLElement) =>
+  Array.from(
+    list.querySelectorAll<HTMLElement>(
+      '[role="tab"]:not([aria-disabled="true"])'
+    )
+  );
+
+const TabsList = ({
+  fullWidth,
+  testId = NAME,
+  className,
+  children,
+  onKeyDown,
+  ref,
+  ...props
+}: TabsListProps) => {
+  const [theme] = useTheme();
+  const {
+    orientation,
+    activationMode,
+    fullWidth: contextFullWidth,
+    setValue,
+  } = useTabContext();
+  const shouldFill = fullWidth ?? contextFullWidth;
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event);
+
+    if (event.defaultPrevented) {
+      return;
+    }
+
+    const keyMap =
+      orientation === 'vertical'
+        ? { next: 'ArrowDown', previous: 'ArrowUp' }
+        : { next: 'ArrowRight', previous: 'ArrowLeft' };
+
+    const isNavigationKey = [
+      keyMap.next,
+      keyMap.previous,
+      'Home',
+      'End',
+    ].includes(event.key);
+
+    if (!isNavigationKey) {
+      return;
+    }
+
+    const tabs = getEnabledTabs(event.currentTarget);
+    const currentIndex = tabs.indexOf(document.activeElement as HTMLElement);
+
+    if (currentIndex === -1) {
+      return;
+    }
+
+    event.preventDefault();
+
+    const nextIndex =
+      {
+        [keyMap.next]: (currentIndex + 1) % tabs.length,
+        [keyMap.previous]: (currentIndex - 1 + tabs.length) % tabs.length,
+        Home: 0,
+        End: tabs.length - 1,
+      }[event.key] ?? currentIndex;
+
+    const nextTab = tabs[nextIndex];
+    nextTab.focus();
+
+    if (activationMode === 'automatic') {
+      const nextValue = nextTab.dataset.uclTabsValue;
+
+      if (nextValue) {
+        setValue(nextValue);
+      }
+    }
+  };
+
+  const baseStyle = css`
+    display: flex;
+    align-items: stretch;
+    overflow-x: auto;
+    padding: 4px;
+    border-bottom: ${theme.border.b1} solid ${theme.colour.border.subtle};
+    background-color: transparent;
+  `;
+
+  const verticalStyle = css`
+    flex-direction: column;
+    overflow: visible;
+    border-bottom: 0;
+    border-right: ${theme.border.b1} solid ${theme.colour.border.subtle};
+  `;
+
+  const fullWidthStyle = css`
+    width: 100%;
+  `;
+
+  const style = cx(
+    NAME,
+    baseStyle,
+    orientation === 'vertical' && verticalStyle,
+    shouldFill && fullWidthStyle,
+    className
+  );
+
+  return (
+    <div
+      ref={ref}
+      className={style}
+      data-testid={testId}
+      role='tablist'
+      aria-orientation={orientation}
+      onKeyDown={handleKeyDown}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+export default memo(TabsList);

package/lib/components/Tabs/TabsPanel.tsx

@@ -0,0 +1,55 @@
+import { HTMLAttributes, memo } from 'react';
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../theme';
+import { getTabId, getTabPanelId, useTabContext } from './TabContext';
+
+export const NAME = 'ucl-uikit-tabs__panel';
+
+export interface TabsPanelProps extends HTMLAttributes<HTMLDivElement> {
+  value: string;
+  forceMount?: boolean;
+  testId?: string;
+  ref?: React.Ref<HTMLDivElement>;
+}
+
+const TabsPanel = ({
+  value,
+  forceMount = false,
+  testId = NAME,
+  className,
+  children,
+  ref,
+  ...props
+}: TabsPanelProps) => {
+  const [theme] = useTheme();
+  const { value: selectedValue, baseId } = useTabContext();
+  const isSelected = selectedValue === value;
+
+  if (!forceMount && !isSelected) {
+    return null;
+  }
+
+  const baseStyle = css`
+    color: ${theme.colour.text.default};
+    outline: none;
+  `;
+
+  const style = cx(NAME, baseStyle, className);
+
+  return (
+    <div
+      ref={ref}
+      className={style}
+      data-testid={testId}
+      role='tabpanel'
+      id={getTabPanelId(baseId, value)}
+      aria-labelledby={getTabId(baseId, value)}
+      hidden={!isSelected}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+export default memo(TabsPanel);

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

@@ -1,122 +1,190 @@
-import { describe, expect, test } from 'vitest';
-import { render } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
 import Tabs from '../Tabs';
 import { ThemeContextProvider } from '../../../theme/useTheme';
 
+const wrap = (ui: React.ReactElement) =>
+  render(<ThemeContextProvider>{ui}</ThemeContextProvider>);
+
 describe('Tabs', () => {
-  // Snapshot tests
+  test('renders a tablist with selectable button tabs', () => {
+    const onValueChange = vi.fn();
 
-  test('snapshot: Minimal props', () => {
-    const renderResult = render(
-      <ThemeContextProvider>
-        <Tabs activeTab='1'>
-          <Tabs.Tab
-            label='Tab Item 1'
-            value='1'
-          />
-          <Tabs.Tab
-            label='Tab Item 2'
-            value='2'
-          />
-          <Tabs.Tab
-            label='Tab Item 3'
-            value='3'
-          />
-          <Tabs.Tab
-            label='Tab Item 4'
-            value='4'
-          />
-        </Tabs>
-      </ThemeContextProvider>
+    wrap(
+      <Tabs
+        defaultValue='overview'
+        onValueChange={onValueChange}
+      >
+        <Tabs.List aria-label='Course sections'>
+          <Tabs.Tab value='overview'>Overview</Tabs.Tab>
+          <Tabs.Tab value='modules'>Modules</Tabs.Tab>
+        </Tabs.List>
+      </Tabs>
+    );
+
+    expect(
+      screen.getByRole('tablist', { name: 'Course sections' })
+    ).toBeInTheDocument();
+    expect(screen.getByRole('tab', { name: 'Overview' })).toHaveAttribute(
+      'aria-selected',
+      'true'
+    );
+    expect(screen.getByRole('tab', { name: 'Overview' })).not.toHaveAttribute(
+      'aria-controls'
+    );
+
+    fireEvent.click(screen.getByRole('tab', { name: 'Modules' }));
+
+    expect(onValueChange).toHaveBeenCalledWith('modules');
+    expect(screen.getByRole('tab', { name: 'Modules' })).toHaveAttribute(
+      'aria-selected',
+      'true'
     );
-    expect(renderResult.container.firstChild).toMatchSnapshot();
   });
 
-  test('snapshot: Custom test id', () => {
-    const renderResult = render(
-      <ThemeContextProvider>
-        <Tabs
-          activeTab='1'
-          data-testid='custom-test-id'
-        >
-          <Tabs.Tab
-            label='Tab Item 1'
-            value='1'
-          />
-          <Tabs.Tab
-            label='Tab Item 2'
-            value='2'
-          />
-          <Tabs.Tab
-            label='Tab Item 3'
-            value='3'
-          />
-          <Tabs.Tab
-            label='Tab Item 4'
-            value='4'
-          />
-        </Tabs>
-      </ThemeContextProvider>
+  test('supports panels linked to their tabs', () => {
+    wrap(
+      <Tabs defaultValue='overview'>
+        <Tabs.List>
+          <Tabs.Tab value='overview'>Overview</Tabs.Tab>
+          <Tabs.Tab value='modules'>Modules</Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value='overview'>Overview content</Tabs.Panel>
+        <Tabs.Panel value='modules'>Modules content</Tabs.Panel>
+      </Tabs>
+    );
+
+    const overviewTab = screen.getByRole('tab', { name: 'Overview' });
+    const overviewPanel = screen.getByRole('tabpanel', {
+      name: 'Overview',
+    });
+
+    expect(overviewTab).toHaveAttribute(
+      'aria-controls',
+      overviewPanel.getAttribute('id')
     );
-    expect(renderResult.container.firstChild).toMatchSnapshot();
+    expect(screen.queryByText('Modules content')).not.toBeInTheDocument();
   });
 
-  test('snapshot: Auto width', () => {
-    const renderResult = render(
-      <ThemeContextProvider>
-        <Tabs
-          activeTab='1'
-          fullWidth={false}
-        >
-          <Tabs.Tab
-            label='Tab Item 1'
-            value='1'
-          />
-          <Tabs.Tab
-            label='Tab Item 2'
-            value='2'
-          />
-          <Tabs.Tab
-            label='Tab Item 3'
-            value='3'
-          />
-          <Tabs.Tab
-            label='A longer tab item showing auto width'
-            value='4'
-          />
-        </Tabs>
-      </ThemeContextProvider>
+  test('supports asChild link tabs', () => {
+    wrap(
+      <Tabs value='overview'>
+        <Tabs.List>
+          <Tabs.Tab
+            value='overview'
+            asChild
+          >
+            <a href='/overview'>Overview</a>
+          </Tabs.Tab>
+          <Tabs.Tab
+            value='modules'
+            asChild
+          >
+            <a href='/modules'>Modules</a>
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs>
     );
-    expect(renderResult.container.firstChild).toMatchSnapshot();
+
+    const overview = screen.getByRole('tab', { name: 'Overview' });
+
+    expect(overview.tagName).toBe('A');
+    expect(overview).toHaveAttribute('href', '/overview');
+    expect(overview).toHaveAttribute('aria-selected', 'true');
   });
 
-  test('snapshot: Counter', () => {
-    const renderResult = render(
-      <ThemeContextProvider>
-        <Tabs activeTab='1'>
-          <Tabs.Tab
-            counter={12}
-            label='Tab Item 1'
-            value='1'
-          />
-          <Tabs.Tab
-            counter={6}
-            label='Tab Item 2'
-            value='2'
-          />
-          <Tabs.Tab
-            counter={9}
-            label='Tab Item 3'
-            value='3'
-          />
-          <Tabs.Tab
-            counter={0}
-            label='Tab Item 4'
-            value='4'
-          />
-        </Tabs>
-      </ThemeContextProvider>
+  test('renders counts as plain tab text', () => {
+    wrap(
+      <Tabs defaultValue='overview'>
+        <Tabs.List>
+          <Tabs.Tab
+            count={12}
+            value='overview'
+          >
+            Overview
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs>
+    );
+
+    expect(screen.getByRole('tab', { name: 'Overview 12' })).toHaveTextContent(
+      'Overview 12'
+    );
+    expect(screen.queryByRole('tab', { name: 'Overview (12)' })).toBe(null);
+  });
+
+  test('moves focus with arrow keys and activates automatically', () => {
+    wrap(
+      <Tabs defaultValue='overview'>
+        <Tabs.List>
+          <Tabs.Tab value='overview'>Overview</Tabs.Tab>
+          <Tabs.Tab value='modules'>Modules</Tabs.Tab>
+          <Tabs.Tab value='people'>People</Tabs.Tab>
+        </Tabs.List>
+      </Tabs>
+    );
+
+    const overview = screen.getByRole('tab', { name: 'Overview' });
+    const modules = screen.getByRole('tab', { name: 'Modules' });
+
+    overview.focus();
+    fireEvent.keyDown(screen.getByRole('tablist'), { key: 'ArrowRight' });
+
+    expect(modules).toHaveFocus();
+    expect(modules).toHaveAttribute('aria-selected', 'true');
+  });
+
+  test('keeps deprecated activeTab/onChange/label props working', () => {
+    const onChange = vi.fn();
+
+    wrap(
+      <Tabs
+        activeTab='overview'
+        onChange={onChange}
+      >
+        <Tabs.Tab
+          label='Overview'
+          value='overview'
+        />
+        <Tabs.Tab
+          label='Modules'
+          value='modules'
+        />
+      </Tabs>
+    );
+
+    fireEvent.click(screen.getByRole('tab', { name: 'Modules' }));
+
+    expect(screen.getByRole('tablist')).toHaveClass('ucl-uikit-tabs__list');
+    expect(onChange).toHaveBeenCalledWith('modules');
+  });
+
+  test('does not activate disabled tabs', () => {
+    const onValueChange = vi.fn();
+
+    wrap(
+      <Tabs
+        defaultValue='overview'
+        onValueChange={onValueChange}
+      >
+        <Tabs.List>
+          <Tabs.Tab value='overview'>Overview</Tabs.Tab>
+          <Tabs.Tab
+            value='modules'
+            disabled
+          >
+            Modules
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs>
+    );
+
+    fireEvent.click(screen.getByRole('tab', { name: 'Modules' }));
+
+    expect(onValueChange).not.toHaveBeenCalled();
+    expect(screen.getByRole('tab', { name: 'Overview' })).toHaveAttribute(
+      'aria-selected',
+      'true'
     );
-    expect(renderResult.container.firstChild).toMatchSnapshot();
   });
 });