uikit-react-public 0.40.5 → 0.42.0

package/lib/components/Callout/Callout.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { css } from '@emotion/css';
+import Callout from './Callout';
+import Icon from '../Icon';
+
+const meta = {
+  title: 'Components/Callout',
+  component: Callout,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    heading: { control: { type: 'text' } },
+    children: { control: { type: 'text' } },
+    showIcon: { control: { type: 'boolean' } },
+    icon: { control: false },
+    testId: { control: { type: 'text' } },
+    className: { control: false },
+  },
+  args: {
+    heading: 'Nobody at UCL will ever ask you for your password',
+    children:
+      "If you're unsure a request is genuine, contact OneDesk IT before entering anything.",
+    showIcon: true,
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Callout>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithoutIcon: Story = {
+  args: {
+    showIcon: false,
+  },
+};
+
+export const CustomIcon: Story = {
+  args: {
+    icon: <Icon.Info size={24} />,
+  },
+};
+
+export const ConstrainedWidth: Story = {
+  render: (args) => (
+    <div
+      className={css`
+        width: 420px;
+      `}
+    >
+      <Callout {...args} />
+    </div>
+  ),
+};

package/lib/components/Callout/Callout.tsx

@@ -0,0 +1,109 @@
+import { HTMLAttributes, ReactNode, Ref, memo } from 'react';
+import { css, cx } from '@emotion/css';
+import useTheme from '../../theme/useTheme';
+import marginsStyle, { MarginProps } from '../common/marginsStyle';
+import Heading from '../Heading';
+import Icon from '../Icon';
+import Paragraph from '../Paragraph';
+
+export const NAME = 'ucl-uikit-callout';
+
+export interface CalloutBaseProps extends HTMLAttributes<HTMLDivElement> {
+  heading?: ReactNode;
+  icon?: ReactNode;
+  showIcon?: boolean;
+  testId?: string;
+  ref?: Ref<HTMLDivElement>;
+}
+
+export type CalloutProps = CalloutBaseProps & MarginProps;
+
+const Callout = ({
+  heading,
+  icon,
+  showIcon = true,
+  testId = NAME,
+  className,
+  children,
+  ref,
+  ...props
+}: CalloutProps) => {
+  const [theme] = useTheme();
+
+  const baseStyle = css`
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 30px;
+    width: 100%;
+    padding: ${theme.padding.p24};
+    background-color: ${theme.colour.surface.brand};
+    border: 1px solid ${theme.colour.border.brand};
+  `;
+
+  const rowStyle = css`
+    display: flex;
+    align-items: flex-start;
+    gap: ${theme.padding.p16};
+    width: 100%;
+  `;
+
+  const iconStyle = css`
+    flex: 0 0 auto;
+    color: ${theme.colour.icon.brand};
+  `;
+
+  const contentStyle = css`
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    justify-content: center;
+    align-items: flex-start;
+    gap: ${theme.padding.p8};
+    min-width: 0;
+  `;
+
+  const style = cx(NAME, baseStyle, marginsStyle(props, theme), className);
+
+  return (
+    <div
+      className={style}
+      data-testid={testId}
+      ref={ref}
+      {...props}
+    >
+      <div className={rowStyle}>
+        {showIcon && (
+          <span
+            className={iconStyle}
+            aria-hidden='true'
+          >
+            {icon ?? <Icon.Info size={24} />}
+          </span>
+        )}
+        <div className={contentStyle}>
+          {heading && (
+            <Heading
+              level='xs'
+              as='h3'
+              noMargins
+            >
+              {heading}
+            </Heading>
+          )}
+          {children && (
+            <Paragraph
+              level='md'
+              noMargins
+            >
+              {children}
+            </Paragraph>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default memo(Callout);

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

@@ -0,0 +1,59 @@
+import { describe, expect, test } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+import Callout from '../Callout';
+
+const wrap = (ui: React.ReactElement) =>
+  render(<ThemeContextProvider>{ui}</ThemeContextProvider>);
+
+describe('Callout', () => {
+  test('renders with default test id', () => {
+    const { getByTestId } = wrap(<Callout />);
+
+    expect(getByTestId('ucl-uikit-callout')).toBeInTheDocument();
+  });
+
+  test('renders heading and children', () => {
+    wrap(
+      <Callout heading='Nobody at UCL will ever ask you for your password'>
+        If you're unsure a request is genuine, contact OneDesk IT before
+        entering anything.
+      </Callout>
+    );
+
+    expect(
+      screen.getByRole('heading', {
+        name: 'Nobody at UCL will ever ask you for your password',
+      })
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        /If you're unsure a request is genuine, contact OneDesk IT/
+      )
+    ).toBeInTheDocument();
+  });
+
+  test('applies custom test id and className', () => {
+    const { getByTestId } = wrap(
+      <Callout
+        testId='custom-callout'
+        className='custom-class'
+      />
+    );
+
+    expect(getByTestId('custom-callout')).toBeInTheDocument();
+    expect(getByTestId('custom-callout').classList).toContain('custom-class');
+  });
+
+  test('renders an icon by default', () => {
+    const { container } = wrap(<Callout />);
+
+    expect(container.querySelector('svg')).toBeInTheDocument();
+  });
+
+  test('can hide the icon', () => {
+    const { container } = wrap(<Callout showIcon={false} />);
+
+    expect(container.querySelector('svg')).not.toBeInTheDocument();
+  });
+});

package/lib/components/Callout/index.ts

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

package/lib/components/ProgressBar/ProgressBar.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { css } from '@emotion/css';
+import ProgressBar, {
+  type ProgressBarSize,
+  type ProgressBarVariant,
+} from './ProgressBar';
+
+const VARIANTS: ProgressBarVariant[] = [
+  'info',
+  'success',
+  'critical',
+  'warning',
+];
+
+const SIZES: ProgressBarSize[] = ['small', 'large'];
+
+const meta = {
+  title: 'Components/ProgressBar',
+  component: ProgressBar,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    value: { control: { type: 'number', min: 0, max: 100 } },
+    max: { control: { type: 'number', min: 1 } },
+    variant: {
+      options: VARIANTS,
+      control: { type: 'radio' },
+    },
+    size: {
+      options: SIZES,
+      control: { type: 'radio' },
+    },
+    title: { control: { type: 'text' } },
+    label: { control: { type: 'text' } },
+    valueLabel: { control: { type: 'text' } },
+    testId: { control: { type: 'text' } },
+    className: { control: false },
+  },
+  args: {
+    value: 50,
+    max: 100,
+    variant: 'info',
+    size: 'small',
+    title: 'Uploading file',
+    valueLabel: '50%',
+    label: 'Uploading... 50%',
+    'aria-label': 'Uploading file',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ProgressBar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Large: Story = {
+  args: {
+    size: 'large',
+  },
+};
+
+export const Indeterminate: Story = {
+  args: {
+    value: undefined,
+    valueLabel: undefined,
+    label: 'Loading...',
+    'aria-label': 'Loading',
+  },
+};
+
+const stackStyle = css`
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  width: 360px;
+`;
+
+const rowStyle = css`
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+`;
+
+const labelStyle = css`
+  font-family: sans-serif;
+  font-size: 12px;
+`;
+
+export const Variants: Story = {
+  parameters: { layout: 'padded' },
+  render: () => (
+    <div className={stackStyle}>
+      {VARIANTS.map((variant) => (
+        <div
+          key={variant}
+          className={rowStyle}
+        >
+          <span className={labelStyle}>{variant}</span>
+          <ProgressBar
+            value={50}
+            variant={variant}
+            aria-label={`${variant} progress`}
+          />
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  parameters: { layout: 'padded' },
+  render: () => (
+    <div className={stackStyle}>
+      {SIZES.map((size) => (
+        <div
+          key={size}
+          className={rowStyle}
+        >
+          <span className={labelStyle}>{size}</span>
+          <ProgressBar
+            value={70}
+            size={size}
+            aria-label={`${size} progress`}
+          />
+        </div>
+      ))}
+    </div>
+  ),
+};

package/lib/components/ProgressBar/ProgressBar.tsx

@@ -0,0 +1,220 @@
+import { HTMLAttributes, ReactNode, Ref, memo, useId } from 'react';
+import { css, cx } from '@emotion/css';
+import useTheme from '../../theme/useTheme';
+import type { ThemeType } from '../../theme';
+import marginsStyle, { MarginProps } from '../common/marginsStyle';
+import Text from '../Text';
+
+export const NAME = 'ucl-uikit-progress-bar';
+
+export type ProgressBarVariant = 'info' | 'success' | 'critical' | 'warning';
+
+export type ProgressBarSize = 'small' | 'large';
+
+export interface ProgressBarBaseProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  | 'children'
+  | 'title'
+  | 'aria-label'
+  | 'aria-labelledby'
+  | 'aria-describedby'
+  | 'role'
+> {
+  value?: number | null;
+  max?: number;
+  variant?: ProgressBarVariant;
+  size?: ProgressBarSize;
+  title?: ReactNode;
+  label?: ReactNode;
+  valueLabel?: ReactNode;
+  testId?: string;
+  ref?: Ref<HTMLDivElement>;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
+}
+
+export type ProgressBarProps = ProgressBarBaseProps & MarginProps;
+
+export const getProgressBarVariantColour = (
+  theme: ThemeType,
+  variant: ProgressBarVariant
+) =>
+  ({
+    info: theme.colour.fill.brand,
+    success: theme.colour.fill.success,
+    critical: theme.colour.fill.critical,
+    warning: theme.colour.fill.warning,
+  })[variant];
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), max);
+
+const ProgressBar = ({
+  value,
+  max = 100,
+  variant = 'info',
+  size = 'small',
+  title,
+  label,
+  valueLabel,
+  testId = NAME,
+  className,
+  ref,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
+  ...props
+}: ProgressBarProps) => {
+  const [theme] = useTheme();
+  const generatedId = useId();
+
+  const isIndeterminate = value === undefined || value === null;
+  const normalizedMax = max > 0 ? max : 100;
+  const normalizedValue = isIndeterminate
+    ? undefined
+    : clamp(value, 0, normalizedMax);
+  const percentage =
+    normalizedValue === undefined ? 0 : (normalizedValue / normalizedMax) * 100;
+  const barHeight = size === 'large' ? 8 : 4;
+  const fillColour = getProgressBarVariantColour(theme, variant);
+  const titleId = `${generatedId}-title`;
+  const labelId = `${generatedId}-label`;
+  const progressBarLabelledBy =
+    ariaLabelledBy ??
+    (ariaLabel ? undefined : label ? labelId : title ? titleId : undefined);
+
+  const rootStyle = css`
+    display: flex;
+    flex-direction: column;
+    gap: ${theme.padding.p8};
+    width: 100%;
+  `;
+
+  const labelRowStyle = css`
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: ${theme.padding.p16};
+  `;
+
+  const titleStyle = css`
+    color: ${theme.colour.text.default};
+  `;
+
+  const valueLabelStyle = css`
+    color: ${theme.colour.text.secondary};
+    white-space: nowrap;
+  `;
+
+  const trackStyle = css`
+    position: relative;
+    width: 100%;
+    height: ${barHeight}px;
+    overflow: hidden;
+    background-color: ${theme.colour.fill.subtle};
+    border-radius: 100px;
+  `;
+
+  const fillStyle = cx(
+    css`
+      display: block;
+      height: 100%;
+      background-color: ${fillColour};
+      border-radius: 100px;
+    `,
+    isIndeterminate
+      ? css`
+          position: absolute;
+          inset-block: 0;
+          inline-size: 40%;
+          animation: progress-bar-indeterminate 1.6s ease-in-out infinite;
+
+          @keyframes progress-bar-indeterminate {
+            0% {
+              transform: translateX(-100%);
+            }
+
+            100% {
+              transform: translateX(250%);
+            }
+          }
+
+          @media (prefers-reduced-motion: reduce) {
+            animation: none;
+            transform: translateX(75%);
+          }
+        `
+      : css`
+          width: ${percentage}%;
+          transition: width 160ms ease-out;
+
+          @media (prefers-reduced-motion: reduce) {
+            transition: none;
+          }
+        `
+  );
+
+  const labelStyle = css`
+    color: ${fillColour};
+  `;
+
+  const style = cx(NAME, rootStyle, marginsStyle(props, theme), className);
+
+  return (
+    <div
+      className={style}
+      data-testid={testId}
+      ref={ref}
+      {...props}
+    >
+      {(title || valueLabel) && (
+        <div className={labelRowStyle}>
+          {title && (
+            <Text
+              id={titleId}
+              level='sm'
+              className={titleStyle}
+            >
+              {title}
+            </Text>
+          )}
+          {valueLabel && (
+            <Text
+              level='xs'
+              className={valueLabelStyle}
+            >
+              {valueLabel}
+            </Text>
+          )}
+        </div>
+      )}
+      <div
+        className={trackStyle}
+        role='progressbar'
+        aria-label={ariaLabel}
+        aria-labelledby={progressBarLabelledBy}
+        aria-describedby={ariaDescribedBy}
+        aria-valuemin={isIndeterminate ? undefined : 0}
+        aria-valuemax={isIndeterminate ? undefined : normalizedMax}
+        aria-valuenow={normalizedValue}
+      >
+        <span
+          className={fillStyle}
+          aria-hidden='true'
+        />
+      </div>
+      {label && (
+        <Text
+          id={labelId}
+          level='xs'
+          className={labelStyle}
+        >
+          {label}
+        </Text>
+      )}
+    </div>
+  );
+};
+
+export default memo(ProgressBar);

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

@@ -0,0 +1,120 @@
+import { describe, expect, test } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+import ProgressBar, { getProgressBarVariantColour } from '../ProgressBar';
+import lightTheme from '../../../theme/light/lightTheme';
+import darkTheme from '../../../theme/dark/darkTheme';
+
+const wrap = (ui: React.ReactElement) =>
+  render(<ThemeContextProvider>{ui}</ThemeContextProvider>);
+
+describe('ProgressBar', () => {
+  test('renders with default test id', () => {
+    const { getByTestId } = wrap(<ProgressBar value={50} />);
+
+    expect(getByTestId('ucl-uikit-progress-bar')).toBeInTheDocument();
+  });
+
+  test('renders custom title, value label, and label', () => {
+    wrap(
+      <ProgressBar
+        value={50}
+        title='coverletter.pdf'
+        valueLabel='2.4 MB'
+        label='Uploading... 50%'
+      />
+    );
+
+    expect(screen.getByText('coverletter.pdf')).toBeInTheDocument();
+    expect(screen.getByText('2.4 MB')).toBeInTheDocument();
+    expect(screen.getByText('Uploading... 50%')).toBeInTheDocument();
+  });
+
+  test('sets determinate progressbar aria attributes', () => {
+    wrap(
+      <ProgressBar
+        value={25}
+        max={50}
+        aria-label='Upload progress'
+      />
+    );
+
+    const progressbar = screen.getByRole('progressbar', {
+      name: 'Upload progress',
+    });
+
+    expect(progressbar).toHaveAttribute('aria-valuemin', '0');
+    expect(progressbar).toHaveAttribute('aria-valuemax', '50');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '25');
+  });
+
+  test('omits value aria attributes for indeterminate progress', () => {
+    wrap(<ProgressBar aria-label='Loading' />);
+
+    const progressbar = screen.getByRole('progressbar', {
+      name: 'Loading',
+    });
+
+    expect(progressbar).not.toHaveAttribute('aria-valuemin');
+    expect(progressbar).not.toHaveAttribute('aria-valuemax');
+    expect(progressbar).not.toHaveAttribute('aria-valuenow');
+  });
+
+  test('clamps aria-valuenow to the allowed range', () => {
+    wrap(
+      <ProgressBar
+        value={120}
+        max={100}
+        aria-label='Clamped progress'
+      />
+    );
+
+    expect(screen.getByRole('progressbar')).toHaveAttribute(
+      'aria-valuenow',
+      '100'
+    );
+  });
+
+  test('applies custom className', () => {
+    const { getByTestId } = wrap(
+      <ProgressBar
+        value={50}
+        className='custom-class'
+      />
+    );
+
+    expect(getByTestId('ucl-uikit-progress-bar').classList).toContain(
+      'custom-class'
+    );
+  });
+
+  test('uses semantic variant colours in light theme', () => {
+    expect(getProgressBarVariantColour(lightTheme, 'info')).toBe(
+      lightTheme.colour.fill.brand
+    );
+    expect(getProgressBarVariantColour(lightTheme, 'success')).toBe(
+      lightTheme.colour.fill.success
+    );
+    expect(getProgressBarVariantColour(lightTheme, 'critical')).toBe(
+      lightTheme.colour.fill.critical
+    );
+    expect(getProgressBarVariantColour(lightTheme, 'warning')).toBe(
+      lightTheme.colour.fill.warning
+    );
+  });
+
+  test('uses semantic variant colours in dark theme', () => {
+    expect(getProgressBarVariantColour(darkTheme, 'info')).toBe(
+      darkTheme.colour.fill.brand
+    );
+    expect(getProgressBarVariantColour(darkTheme, 'success')).toBe(
+      darkTheme.colour.fill.success
+    );
+    expect(getProgressBarVariantColour(darkTheme, 'critical')).toBe(
+      darkTheme.colour.fill.critical
+    );
+    expect(getProgressBarVariantColour(darkTheme, 'warning')).toBe(
+      darkTheme.colour.fill.warning
+    );
+  });
+});

package/lib/components/ProgressBar/index.ts

@@ -0,0 +1,6 @@
+export { default } from './ProgressBar';
+export type {
+  ProgressBarProps,
+  ProgressBarSize,
+  ProgressBarVariant,
+} from './ProgressBar';