feat: Add Tabs component

packages/css/src/components/index.scss

@@ -4,6 +4,7 @@
  */
 
 /* Append here */
+@import "./tabs/tabs";
 @import "./column/column";
 @import "./margin/margin";
 @import "./gap/gap";

packages/css/src/components/tabs/README.md

@@ -0,0 +1,30 @@
+# Tabs
+
+Tabs are used to bundle related content in a compact overview within a page. Each tab has a short name, and these names indicate the relationship between the information displayed in each tab.
+
+## How to Use
+
+- The content of each tab is viewable independently, not in the context of one another.
+- The content within each tab should have a similar structure.
+- Use when there is limited visual space and content needs to be divided into sections.
+
+You can navigate tabs with your keyboard:
+
+| key            | element                                        |
+| :------------- | :--------------------------------------------- |
+| Enter or Space | Open or close the tab that has the focus       |
+| Tab            | Go to the next element that can have focus     |
+| Shift + Tab    | Go to the next element that can have focus     |
+| Left arrow     | If the tabs have focus: go to the previous tab |
+| Right arrow    | If the tabs have focus: go to the next tab     |
+| Home           | If the tabs have focus: go to the first tab    |
+| End            | If the tabs have focus, go to the last tab     |
+
+### Caution
+
+Do not use tabs if the content in each tab functions just as well on separate pages.
+
+## References
+
+- [W3C - Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)
+- [MDN - Tab Aria Roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role)

packages/css/src/components/tabs/tabs.scss

@@ -0,0 +1,41 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+@import "../../common/breakpoint";
+
+.amsterdam-tabs__list {
+  border-bottom: var(--amsterdam-tabs-list-border-bottom);
+  display: flex;
+  overflow-x: auto;
+}
+
+.amsterdam-tabs__button {
+  background-color: var(--amsterdam-tabs-button-background-color);
+  border: var(--amsterdam-tabs-button-border);
+  color: var(--amsterdam-tabs-button-color);
+  cursor: var(--amsterdam-tabs-button-cursor);
+  font-family: var(--amsterdam-tabs-button-font-family);
+  font-size: var(--amsterdam-tabs-button-font-size);
+  font-weight: var(--amsterdam-tabs-button-font-weight);
+  line-height: var(--amsterdam-tabs-button-line-height);
+  outline-offset: var(--amsterdam-tabs-button-outline-offset);
+  padding-block: var(--amsterdam-tabs-button-padding-block);
+  padding-inline: var(--amsterdam-tabs-button-padding-inline);
+
+  &:disabled {
+    color: var(--amsterdam-tabs-button-disabled-color);
+    cursor: var(--amsterdam-tab-button-disabled-cursor);
+  }
+
+  &:hover:not([aria-selected="true"], [disabled]) {
+    box-shadow: var(--amsterdam-tabs-button-hover-box-shadow);
+    color: var(--amsterdam-tabs-button-hover-color);
+  }
+
+  &[aria-selected="true"] {
+    background-color: var(--amsterdam-tabs-button-selected-background-color);
+    color: var(--amsterdam-tabs-button-selected-color);
+  }
+}

packages/react/src/Tabs/README.md

@@ -0,0 +1,3 @@
+# React Tabs component
+
+[Tabs documentation](../../../css/src/components/tabs/README.md)

packages/react/src/Tabs/Tabs.test.tsx

@@ -0,0 +1,76 @@
+import { render, screen } from '@testing-library/react'
+import { createRef } from 'react'
+import { Tabs } from './Tabs'
+import '@testing-library/jest-dom'
+
+describe('Tabs', () => {
+  it('renders', () => {
+    render(<Tabs />)
+
+    const component = screen.getByRole('tabs')
+
+    expect(component).toBeInTheDocument()
+    expect(component).toBeVisible()
+  })
+
+  it('renders a design system BEM class name', () => {
+    render(<Tabs />)
+
+    const component = screen.getByRole('tabs')
+
+    expect(component).toHaveClass('amsterdam-tabs')
+  })
+
+  it('renders an additional class name', () => {
+    render(<Tabs className="extra" />)
+
+    const component = screen.getByRole('tabs')
+
+    expect(component).toHaveClass('amsterdam-tabs extra')
+  })
+
+  it('supports ForwardRef in React', () => {
+    const ref = createRef<HTMLDivElement>()
+
+    const { container } = render(<Tabs ref={ref} />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(ref.current).toBe(component)
+  })
+
+  it('supports children', () => {
+    render(
+      <Tabs>
+        <Tabs.List>
+          <Tabs.Button tab={0} label="Tab 1" />
+          <Tabs.Button tab={1} label="Tab 2" />
+        </Tabs.List>
+        <Tabs.Panel tab={0}>Content 1</Tabs.Panel>
+        <Tabs.Panel tab={2}>Content 2</Tabs.Panel>
+      </Tabs>,
+    )
+
+    expect(screen.getByRole('tabs')).toBeInTheDocument()
+    expect(screen.getByRole('tablist')).toBeInTheDocument()
+    expect(screen.getByRole('tab', { selected: true })).toBeInTheDocument()
+    expect(screen.getByRole('tabpanel')).toBeInTheDocument()
+  })
+
+  it('should render its subcomponents', () => {
+    render(
+      <Tabs>
+        <Tabs.List>
+          <Tabs.Button tab={0} label="Tab 1" />
+          <Tabs.Button tab={1} label="Tab 2" />
+        </Tabs.List>
+        <Tabs.Panel tab={0}>Content 1</Tabs.Panel>
+        <Tabs.Panel tab={1}>Content 2</Tabs.Panel>
+      </Tabs>,
+    )
+
+    expect(screen.getByRole('tab', { name: 'Tab 1', selected: true })).toBeInTheDocument()
+    expect(screen.getByRole('tab', { name: 'Tab 2', selected: false })).toBeInTheDocument()
+    expect(screen.getByRole('tabpanel')).toBeInTheDocument()
+  })
+})

packages/react/src/Tabs/Tabs.tsx

@@ -0,0 +1,65 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import clsx from 'clsx'
+import { forwardRef, useId, useImperativeHandle, useRef, useState } from 'react'
+import type { ForwardedRef, ForwardRefExoticComponent, HTMLAttributes, PropsWithChildren, RefAttributes } from 'react'
+import { TabsButton } from './TabsButton'
+import { TabsContext } from './TabsContext'
+import { TabsList } from './TabsList'
+import { TabsPanel } from './TabsPanel'
+import useFocusWithArrows from '../common/useFocusWithArrows'
+
+export type TabsProps = PropsWithChildren<HTMLAttributes<HTMLDivElement>>
+
+type TabsComponent = {
+  /** Always use a TabList to hold the Tab Buttons */
+  List: typeof TabsList
+  /** Use a TabButton for each tab */
+  Button: typeof TabsButton
+  /** A TabsPanel will only return its contents when the corresponding TabsButton is activated */
+  Panel: typeof TabsPanel
+} & ForwardRefExoticComponent<TabsProps & RefAttributes<HTMLDivElement>>
+
+export const Tabs = forwardRef(
+  ({ children, className, ...restProps }: TabsProps, ref: ForwardedRef<HTMLDivElement>) => {
+    const tabsId = useId()
+    const [activeTab, setActiveTab] = useState(0)
+    const innerRef = useRef<HTMLDivElement>(null)
+
+    const updateTab = (tab: number) => {
+      setActiveTab(tab)
+    }
+
+    // use a passed ref if it's there, otherwise use innerRef
+    useImperativeHandle(ref, () => innerRef.current as HTMLDivElement)
+
+    const { keyDown } = useFocusWithArrows({
+      ref: innerRef,
+      rotating: true,
+      directChildrenOnly: false,
+      horizontally: true,
+    })
+
+    return (
+      <TabsContext.Provider value={{ activeTab, updateTab, tabsId }}>
+        <div
+          {...restProps}
+          role="tabs"
+          ref={innerRef}
+          onKeyDown={keyDown}
+          className={clsx('amsterdam-tabs', className)}
+        >
+          {children}
+        </div>
+      </TabsContext.Provider>
+    )
+  },
+) as TabsComponent
+
+Tabs.List = TabsList
+Tabs.Button = TabsButton
+Tabs.Panel = TabsPanel
+Tabs.displayName = 'Tabs'

packages/react/src/Tabs/TabsButton.tsx

@@ -0,0 +1,42 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import clsx from 'clsx'
+import { forwardRef, startTransition, useContext } from 'react'
+import type { ButtonHTMLAttributes, ForwardedRef, PropsWithChildren } from 'react'
+import { TabsContext } from './TabsContext'
+
+export type TabsButtonProps = {
+  label: string
+  tab: number
+} & PropsWithChildren<ButtonHTMLAttributes<HTMLButtonElement>>
+
+export const TabsButton = forwardRef(
+  ({ label, tab = 0, className, ...restProps }: TabsButtonProps, ref: ForwardedRef<HTMLButtonElement>) => {
+    const { activeTab, updateTab, tabsId } = useContext(TabsContext)
+
+    return (
+      <button
+        {...restProps}
+        role="tab"
+        id={`{tabsId}-tab-${tab}`}
+        aria-controls={`${tabsId}-panel-${tab}`}
+        aria-selected={activeTab === tab}
+        tabIndex={activeTab === tab ? 0 : -1}
+        ref={ref}
+        onClick={() => {
+          startTransition(() => {
+            updateTab(tab)
+          })
+        }}
+        className={clsx('amsterdam-tabs__button', className)}
+      >
+        {label}
+      </button>
+    )
+  },
+)
+
+TabsButton.displayName = 'Tabs.Button'

packages/react/src/Tabs/TabsContext.tsx

@@ -0,0 +1,21 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import { createContext } from 'react'
+
+export type TabsContextValue = {
+  activeTab: number
+  // eslint-disable-next-line no-unused-vars
+  updateTab: (tab: number) => void
+  tabsId: string
+}
+
+const defaultValues: TabsContextValue = {
+  activeTab: 0,
+  updateTab: () => {},
+  tabsId: '',
+}
+
+export const TabsContext = createContext(defaultValues)

packages/react/src/Tabs/TabsList.tsx

@@ -0,0 +1,20 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import clsx from 'clsx'
+import { forwardRef } from 'react'
+import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
+
+export type TabsListProps = PropsWithChildren<HTMLAttributes<HTMLDivElement>>
+
+export const TabsList = forwardRef(
+  ({ children, className, ...restProps }: TabsListProps, ref: ForwardedRef<HTMLDivElement>) => (
+    <div {...restProps} role="tablist" ref={ref} className={clsx('amsterdam-tabs__list', className)}>
+      {children}
+    </div>
+  ),
+)
+
+TabsList.displayName = 'Tabs.List'

packages/react/src/Tabs/TabsPanel.tsx

@@ -0,0 +1,39 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import clsx from 'clsx'
+import { forwardRef, useContext } from 'react'
+import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
+import { TabsContext } from './TabsContext'
+
+export type TabsPanelProps = {
+  tab: number
+} & PropsWithChildren<HTMLAttributes<HTMLDivElement>>
+
+export const TabsPanel = forwardRef(
+  ({ tab, children, className, ...restProps }: TabsPanelProps, ref: ForwardedRef<HTMLDivElement>) => {
+    const { activeTab, tabsId } = useContext(TabsContext)
+
+    if (tab !== activeTab) {
+      return null
+    }
+
+    return (
+      <div
+        {...restProps}
+        role="tabpanel"
+        aria-labelledby={`${tabsId}-tab-${tab}`}
+        id={`${tabsId}-panel-${tab}`}
+        tabIndex={0}
+        ref={ref}
+        className={clsx('amsterdam-tabs__panel', className)}
+      >
+        {children}
+      </div>
+    )
+  },
+)
+
+TabsPanel.displayName = 'Tabs.Panel'

packages/react/src/Tabs/index.ts

@@ -0,0 +1,5 @@
+export { Tabs } from './Tabs'
+export type { TabsProps } from './Tabs'
+export type { TabsPanelProps } from './TabsPanel'
+export type { TabsListProps } from './TabsList'
+export type { TabsButtonProps } from './TabsButton'