uikit-react-public 0.14.21 → 0.17.4

package/lib/components/Dialog/DialogHeader.tsx

@@ -23,7 +23,7 @@ const DialogHeader = ({
   testId = NAME,
   className,
 }: DialogHeaderProps) => {
-  const { onClose } = useContext(DialogContext);
+  const { onClose, dialogHeaderId } = useContext(DialogContext);
 
   const [theme] = useTheme();
 
@@ -73,6 +73,7 @@ const DialogHeader = ({
         level={3}
         margins={false}
         {...headingProps}
+        id={dialogHeaderId}
       >
         {children}
       </Heading>

package/lib/components/Divider/Divider.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import Divider from './Divider';
 
 const meta = {
-  title: 'Components/Ready to use/Divider',
+  title: 'Components/Divider',
   component: Divider,
   parameters: {
     layout: 'padded',

package/lib/components/Field/ErrorText.tsx

@@ -45,6 +45,7 @@ const ErrorText = ({
       className={style}
       data-testid={testId}
       {...props}
+      role='alert'
     >
       <Icon.Info className={iconStyle} />
       {children}

package/lib/components/Field/Field.stories.tsx

@@ -9,7 +9,7 @@ import Input from '../Input/Input';
 import Textarea from '../Textarea/Textarea';
 
 const meta = {
-  title: 'Components/Ready to use/Field',
+  title: 'Components/Field',
   component: Field,
   parameters: { layout: 'padded' },
 } satisfies Meta<typeof Field>;

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

@@ -507,4 +507,17 @@ describe('Field', () => {
     expect(label2).not.toHaveAttribute('for', idForField2);
     expect(textarea1).not.toHaveAttribute('id', idForField1);
   });
+
+  test('Field.ErrorText has role alert', () => {
+    const testId = 'error-text-01';
+    render(
+      <ThemeContextProvider>
+        <Field error>
+          <Field.ErrorText testId={testId}> Error text </Field.ErrorText>
+        </Field>
+      </ThemeContextProvider>
+    );
+    const errorText = screen.getByTestId(testId);
+    expect(errorText).toHaveAttribute('role', 'alert');
+  });
 });

package/lib/components/FileInput/FileInput.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import FileInput from './FileInput';
 
 const meta = {
-  title: 'Components/WorkInProgress/FileInput',
+  title: 'Components/Work in progress/FileInput',
   component: FileInput,
   parameters: {
     layout: 'centered',

package/lib/components/Footer/Footer.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import Footer from './Footer';
 
 const meta = {
-  title: 'Components/Ready to use/Footer',
+  title: 'Components/Footer',
   component: Footer,
   parameters: {
     layout: 'fullscreen',

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

@@ -247,7 +247,7 @@ exports[`Footer > snapshot: footer links provided 1`] = `
         class="css-bq4k8p"
       >
         © 
-        2025
+        2026
          UCL
       </span>
     </div>
@@ -591,7 +591,7 @@ exports[`Footer > snapshot: nav links 1`] = `
         class="css-bq4k8p"
       >
         © 
-        2025
+        2026
          UCL
       </span>
     </div>
@@ -886,7 +886,7 @@ exports[`Footer > snapshot: no nav links 1`] = `
         class="css-bq4k8p"
       >
         © 
-        2025
+        2026
          UCL
       </span>
     </div>

package/lib/components/Header/Header.mdx

@@ -0,0 +1,52 @@
+import * as HeaderStories from "./Header.stories";
+import { Meta, Title, Subtitle, Canvas, Controls } from "@storybook/blocks";
+
+export const usage = {
+  default: `<Header title='App Name' />`,
+  homeLink: `<Header title='App Name' homeLinkHref='/' homeLinkAriaLabel='Go to home' />`,
+  menu: `<Header title='App Name' homeLinkHref='/'>
+  <Header.Menu>
+    <Menu title='App Name'>
+      <Menu.Section>
+        <Menu.Item icon={<Icon.Home size={20} />}>Home Page</Menu.Item>
+        <Menu.Item icon={<Icon.Tool size={20} />}>Tools</Menu.Item>
+      </Menu.Section>
+    </Menu>
+  </Header.Menu>
+</Header>`,
+};
+
+<Meta of={HeaderStories} />
+<Title />
+<Subtitle>A simple header with optional menu and home link support.</Subtitle>
+
+Use `<Header>` to display the UCL logo and app title at the top of a page. Pass
+`homeLinkHref` to make the logo/title clickable, and wrap a menu in `<Header.Menu>`
+to add a menu button on the right.
+
+<Canvas source={{ code: usage.default }} />
+
+## Home link
+
+Add `homeLinkHref` (and optionally `homeLinkAriaLabel`) to make the logo/title act as a home link.
+For client routing, pass your router link through `homeLinkProps` (e.g. `homeLinkProps={{ component: RouterLink }}`, with `import { Link as RouterLink } from 'react-router-dom'` or `'wouter'`).
+
+<Canvas of={HeaderStories.WithHomeLink} source={{ code: usage.homeLink }} />
+
+## Menu
+
+Wrap a `Menu` inside `Header.Menu` to show a menu button on the right.
+
+<Canvas of={HeaderStories.WithMenu} source={{ code: usage.menu }} />
+
+## Fixed header
+
+Use `fixed` to pin the header to the top of the viewport.
+
+<Canvas of={HeaderStories.Fixed} />
+
+## Props
+Full props specification for `<Header>` is below.
+<Canvas source={{ code: usage.default }} />
+You can use the controls below to manipulate the `<Header>` component above.
+<Controls />

package/lib/components/Header/Header.stories.tsx

@@ -0,0 +1,98 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Header from './Header';
+import Menu from '../Menu';
+import Icon from '../Icon';
+
+const storyWrapperStyle: React.CSSProperties = { minHeight: 400 };
+
+const meta = {
+  title: 'Components/Header',
+  component: Header,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  argTypes: {
+    title: { control: 'text' },
+    fixed: { control: 'boolean' },
+    homeLinkHref: { control: 'text' },
+    homeLinkAriaLabel: { control: 'text' },
+    className: { control: 'text' },
+    children: { control: false },
+  },
+  args: {
+    title: 'App Name',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Header>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div style={{ overflow: 'hidden' }}>
+      <Header {...args} />
+    </div>
+  ),
+};
+
+export const Fixed: Story = {
+  render: (args) => (
+    <div
+      style={{
+        height: '240px',
+        overflowY: 'auto',
+        position: 'relative',
+      }}
+    >
+      <Header
+        {...args}
+        fixed
+        title='App Name'
+      />
+      <div
+        style={{
+          paddingTop: '88px', // keep content below the fixed header
+          height: '600px',
+          margin: '0 16px',
+        }}
+      >
+        Scroll inside this panel; the header should stay fixed to the top of the
+        viewport.
+      </div>
+    </div>
+  ),
+};
+
+export const WithHomeLink: Story = {
+  name: 'With home link',
+  render: (args) => (
+    <div style={{ overflow: 'hidden' }}>
+      <Header {...args} />
+    </div>
+  ),
+  args: {
+    homeLinkHref: '/',
+    homeLinkAriaLabel: 'Go to home',
+  },
+};
+
+export const WithMenu: Story = {
+  render: (args) => (
+    <div style={storyWrapperStyle}>
+      <Header {...args}>
+        <Header.Menu>
+          <Menu title='App Name'>
+            <Menu.Section>
+              <Menu.Item icon={<Icon.Home size={20} />}>Home Page</Menu.Item>
+              <Menu.Item icon={<Icon.Tool size={20} />}>Tools</Menu.Item>
+            </Menu.Section>
+            <Menu.Section>
+              <Menu.Item icon={<Icon.Settings size={20} />}>Settings</Menu.Item>
+            </Menu.Section>
+          </Menu>
+        </Header.Menu>
+      </Header>
+    </div>
+  ),
+};

package/lib/components/Header/Header.tsx

@@ -3,6 +3,7 @@ import { css, cx } from '@emotion/css';
 import { useTheme } from '../..';
 import UclLogo from '../UclLogo/UclLogo';
 import HeaderMenu from './HeaderMenu';
+import Link from '../Link';
 
 export const NAME = 'ucl-uikit-header';
 export const HEADER_DESKTOP_HEIGHT_PX = 72;
@@ -15,6 +16,9 @@ export interface HeaderProps extends HTMLAttributes<HTMLElement> {
   titleAs?: React.ElementType<React.HTMLAttributes<HTMLElement>>;
   titleClassName?: string;
   titleProps?: Record<string, unknown>;
+  homeLinkHref?: string;
+  homeLinkProps?: Record<string, unknown>;
+  homeLinkAriaLabel?: string;
   testId?: string;
 }
 
@@ -24,6 +28,9 @@ const Header = ({
   titleAs = 'div',
   titleClassName,
   titleProps,
+  homeLinkHref,
+  homeLinkProps,
+  homeLinkAriaLabel = 'Go to homepage',
   testId = NAME,
   className,
   children,
@@ -86,16 +93,33 @@ const Header = ({
     }
   `;
 
+  const linkStyle = css`
+    color: inherit;
+    text-decoration: none;
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    &:visited {
+      color: inherit;
+    }
+    &:hover {
+      color: inherit;
+    }
+    &:active {
+      color: inherit;
+    }
+    &:focus-visible {
+      outline: none;
+      box-shadow: ${theme.boxShadow.focus};
+    }
+  `;
+
   const titleStyle = cx(titleBaseStyle, titleClassName);
 
   const TitleComponent = titleAs;
 
-  return (
-    <header
-      className={style}
-      data-testid={testId}
-      {...props}
-    >
+  const headerContent = (
+    <>
       <UclLogo className={uclLogoStyle} />
       {title && (
         <TitleComponent
@@ -105,6 +129,27 @@ const Header = ({
           {title}
         </TitleComponent>
       )}
+    </>
+  );
+
+  return (
+    <header
+      className={style}
+      data-testid={testId}
+      {...props}
+    >
+      {homeLinkHref ? (
+        <Link
+          href={homeLinkHref}
+          aria-label={homeLinkAriaLabel}
+          className={linkStyle}
+          {...homeLinkProps}
+        >
+          {headerContent}
+        </Link>
+      ) : (
+        headerContent
+      )}
 
       {children}
     </header>

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import { render } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import Header from '../Header';
 import { ThemeContextProvider } from '../../../theme/useTheme';
 
@@ -23,4 +23,20 @@ describe('Header', () => {
     );
     expect(renderResult.container.firstChild).toMatchSnapshot();
   });
+
+  test('wraps logo/title in a home link when homeLinkHref is provided', () => {
+    render(
+      <ThemeContextProvider>
+        <Header
+          title='LIDS'
+          homeLinkHref='/'
+          homeLinkAriaLabel='Go home'
+        />
+      </ThemeContextProvider>
+    );
+
+    const link = screen.getByLabelText('Go home');
+    expect(link).toBeInTheDocument();
+    expect(link.getAttribute('href')).toBe('/');
+  });
 });

package/lib/components/Heading/Heading.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import Heading from './Heading';
 
 const meta = {
-  title: 'Components/Ready to use/Heading',
+  title: 'Components/Heading',
   component: Heading,
   parameters: {
     layout: 'centered',

package/lib/components/Icon/Icon.stories.tsx

@@ -3,7 +3,7 @@ import Icon from './Icon';
 import { ComponentType } from 'react';
 
 const meta: Meta = {
-  title: 'Components/Ready to use/Icon',
+  title: 'Components/Icon',
   component: Icon,
   parameters: {
     // Appearing automatically, due to composition

package/lib/components/IconButton/IconButton.stories.tsx

@@ -4,7 +4,7 @@ import IconButton from './IconButton';
 import Icon from '../Icon/Icon';
 
 const meta: Meta = {
-  title: 'Components/Ready to use/IconButton',
+  title: 'Components/IconButton',
   component: IconButton,
   argTypes: {
     icon: {

package/lib/components/Input/Input.stories.tsx

@@ -3,7 +3,7 @@ import { Input } from '../../../lib';
 import { Icon } from '../../../lib';
 
 const meta: Meta<typeof Input> = {
-  title: 'Components/Ready to use/Input',
+  title: 'Components/Input',
   component: Input,
   parameters: {
     layout: 'centered',

package/lib/components/Label/Label.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import Label from './Label';
 
 const meta = {
-  title: 'Components/Ready to use/Label',
+  title: 'Components/Label',
   component: Label,
 } satisfies Meta<typeof Label>;
 

package/lib/components/Main/Main.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Main from './Main';
+
+const meta = {
+  title: 'Components/Utilities/Main',
+  component: Main,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Main>;
+
+export default meta;
+
+type Story = StoryObj<typeof Main>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const WithLayout: Story = {
+  args: {
+    layout: true,
+  },
+};
+
+export const WithChildren: Story = {
+  args: {
+    children: (
+      <>
+        <h1>Main Content</h1>
+        <p>This is some content inside the Main component.</p>
+      </>
+    ),
+  },
+};

package/lib/components/Main/Main.tsx

@@ -0,0 +1,46 @@
+import { cx } from '@emotion/css';
+import Layout from '../Layout/Layout';
+
+export interface MainProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * Determines whether to wrap children in a `<Layout>` component,
+   * to apply the grid layout from the UCL Design System.
+   */
+  layout?: boolean;
+  /**
+   * ID for testing purposes.
+   * Added to the `data-testid` attribute of top-level `<main>` element.
+   * Default is `'ucl-uikit-main'`.
+   */
+  testId?: string;
+}
+
+export const NAME = 'ucl-uikit-main';
+
+/**
+ * Semantic wrapper around HTML `<main>` element
+ *
+ * Optionally wraps children in the UCL Design System `Layout` grid when `layout` is true
+ */
+const Main = ({
+  layout = false,
+  testId = NAME,
+  className,
+  children,
+  ...props
+}: MainProps) => {
+  // No need for any additional styling -- just a semantic wrapper
+  const style = cx(NAME, className);
+
+  return (
+    <main
+      className={style}
+      data-testid={testId}
+      {...props}
+    >
+      {layout ? <Layout>{children}</Layout> : children}
+    </main>
+  );
+};
+
+export default Main;

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

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import Main from '../Main';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+
+describe('Main', () => {
+  // Snapshot tests
+
+  test('snapshot: no props', () => {
+    const renderResult = render(
+      <ThemeContextProvider>
+        <Main>Content</Main>
+      </ThemeContextProvider>
+    );
+    expect(renderResult.container.firstChild).toMatchSnapshot();
+  });
+
+  test('snapshot: layout prop true', () => {
+    const renderResult = render(
+      <ThemeContextProvider>
+        <Main layout>Content</Main>
+      </ThemeContextProvider>
+    );
+    expect(renderResult.container.firstChild).toMatchSnapshot();
+  });
+
+  test('snapshot: testId prop', () => {
+    const renderResult = render(
+      <ThemeContextProvider>
+        <Main testId='test123'>Content</Main>
+      </ThemeContextProvider>
+    );
+    expect(renderResult.container.firstChild).toMatchSnapshot();
+  });
+
+  // Interaction tests
+
+  test('Can find by default testId', () => {
+    render(
+      <ThemeContextProvider>
+        <Main>Content</Main>
+      </ThemeContextProvider>
+    );
+    const main = screen.getByTestId('ucl-uikit-main');
+    expect(main).toBeInTheDocument();
+  });
+
+  test('Can find by custom testId', () => {
+    render(
+      <ThemeContextProvider>
+        <Main testId='custom-test-id'>Content</Main>
+      </ThemeContextProvider>
+    );
+    const main = screen.getByTestId('custom-test-id');
+    expect(main).toBeInTheDocument();
+  });
+
+  test('Renders children correctly', () => {
+    render(
+      <ThemeContextProvider>
+        <Main>
+          <div data-testid='child-element'>Child Content</div>
+        </Main>
+      </ThemeContextProvider>
+    );
+    const child = screen.getByTestId('child-element');
+    expect(child).toBeInTheDocument();
+    expect(child).toHaveTextContent('Child Content');
+  });
+
+  test('Applies layout when layout prop is true', () => {
+    render(
+      <ThemeContextProvider>
+        <Main layout>Content</Main>
+      </ThemeContextProvider>
+    );
+    const layoutComponent = screen.getByTestId('ucl-uikit-layout');
+    expect(layoutComponent).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,33 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Main > snapshot: layout prop true 1`] = `
+<main
+  class="ucl-uikit-main"
+  data-testid="ucl-uikit-main"
+>
+  <div
+    class="css-3reham"
+    data-testid="ucl-uikit-layout"
+  >
+    Content
+  </div>
+</main>
+`;
+
+exports[`Main > snapshot: no props 1`] = `
+<main
+  class="ucl-uikit-main"
+  data-testid="ucl-uikit-main"
+>
+  Content
+</main>
+`;
+
+exports[`Main > snapshot: testId prop 1`] = `
+<main
+  class="ucl-uikit-main"
+  data-testid="test123"
+>
+  Content
+</main>
+`;

package/lib/components/Main/index.ts

@@ -0,0 +1,2 @@
+export { default } from './Main';
+export type { MainProps } from './Main';