uikit-react-public 0.45.5 → 0.47.0

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

@@ -0,0 +1,378 @@
+import { ReactElement } from 'react';
+import { afterEach, describe, expect, test, vitest } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import DropZone from '../DropZone';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+import { useDraggable, useDropZone } from '../../../hooks';
+import {
+  clearActiveKeyboardDrag,
+  getActiveKeyboardDrag,
+} from '../../../hooks/useDropZone';
+
+const TABLE_CELL_TYPE = 'application/x-ucl-uikit-table-cell';
+
+const wrap = (ui: ReactElement) =>
+  render(<ThemeContextProvider>{ui}</ThemeContextProvider>);
+
+const createDataTransfer = (data: Record<string, string>) =>
+  ({
+    dropEffect: 'none',
+    files: [],
+    getData: vitest.fn((type: string) => data[type] ?? ''),
+    setData: vitest.fn(),
+    types: Object.keys(data),
+  }) as unknown as DataTransfer;
+
+describe('DropZone', () => {
+  afterEach(() => {
+    clearActiveKeyboardDrag();
+  });
+
+  test('snapshot: no props', () => {
+    const renderResult = wrap(<DropZone />);
+
+    expect(renderResult.container.firstChild).toMatchSnapshot();
+  });
+
+  test('renders with default test id and labelled group role', () => {
+    wrap(<DropZone />);
+
+    expect(screen.getByTestId('ucl-uikit-drop-zone')).toBeInTheDocument();
+    expect(
+      screen.getByRole('group', { name: 'Drop zone' })
+    ).toBeInTheDocument();
+  });
+
+  test('falls back to generic copy when accepted types are empty', () => {
+    wrap(<DropZone acceptedTypes={[]} />);
+
+    expect(screen.getByText('Drop an item here')).toBeInTheDocument();
+  });
+
+  test('does not add a role when using the hook directly', () => {
+    const HookDropZone = () => {
+      const { getRootProps } = useDropZone();
+
+      return (
+        <section
+          data-testid='hook-drop-zone'
+          {...getRootProps()}
+        />
+      );
+    };
+
+    render(<HookDropZone />);
+
+    expect(screen.getByTestId('hook-drop-zone')).not.toHaveAttribute('role');
+  });
+
+  test('sets drag state data attributes during an accepted drag', () => {
+    wrap(<DropZone acceptedTypes={TABLE_CELL_TYPE} />);
+
+    const dropZone = screen.getByTestId('ucl-uikit-drop-zone');
+
+    fireEvent.dragEnter(dropZone, {
+      dataTransfer: createDataTransfer({
+        [TABLE_CELL_TYPE]: JSON.stringify({
+          column: 'Status',
+          row: 'Research proposal',
+          value: 'Approved',
+        }),
+      }),
+    });
+
+    expect(dropZone).toHaveAttribute('data-drag-active', 'true');
+    expect(dropZone).toHaveAttribute('data-drag-accept', 'true');
+    expect(dropZone).toHaveAttribute('data-drag-reject', 'false');
+  });
+
+  test('calls onDrop with parsed app data when a matching type is dropped', () => {
+    const onDrop = vitest.fn();
+    const dataTransfer = createDataTransfer({
+      [TABLE_CELL_TYPE]: JSON.stringify({
+        column: 'Status',
+        row: 'Research proposal',
+        value: 'Approved',
+      }),
+    });
+
+    wrap(
+      <DropZone
+        acceptedTypes={TABLE_CELL_TYPE}
+        onDrop={onDrop}
+      />
+    );
+
+    fireEvent.drop(screen.getByTestId('ucl-uikit-drop-zone'), {
+      dataTransfer,
+    });
+
+    expect(onDrop).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: {
+          column: 'Status',
+          row: 'Research proposal',
+          value: 'Approved',
+        },
+        dataTransfer,
+        rawData: JSON.stringify({
+          column: 'Status',
+          row: 'Research proposal',
+          value: 'Approved',
+        }),
+        type: TABLE_CELL_TYPE,
+      }),
+      expect.any(Object)
+    );
+  });
+
+  test('calls onReject when a dropped type is not accepted', () => {
+    const onDrop = vitest.fn();
+    const onReject = vitest.fn();
+
+    wrap(
+      <DropZone
+        acceptedTypes={TABLE_CELL_TYPE}
+        onDrop={onDrop}
+        onReject={onReject}
+      />
+    );
+
+    fireEvent.drop(screen.getByTestId('ucl-uikit-drop-zone'), {
+      dataTransfer: createDataTransfer({
+        'text/plain': 'Approved',
+      }),
+    });
+
+    expect(onDrop).not.toHaveBeenCalled();
+    expect(onReject).toHaveBeenCalledWith(
+      {
+        drop: null,
+        reason: 'invalid-type',
+      },
+      expect.any(Object)
+    );
+  });
+
+  test('shows rejection copy before release copy for rejected drags', () => {
+    wrap(<DropZone acceptedTypes={TABLE_CELL_TYPE} />);
+
+    fireEvent.dragEnter(screen.getByTestId('ucl-uikit-drop-zone'), {
+      dataTransfer: createDataTransfer({
+        'text/plain': 'Approved',
+      }),
+    });
+
+    expect(
+      screen.getByText('This item cannot be dropped here')
+    ).toBeInTheDocument();
+    expect(screen.queryByText('Release to drop')).not.toBeInTheDocument();
+  });
+
+  test('calls onReject when canDrop returns false', () => {
+    const onReject = vitest.fn();
+
+    wrap(
+      <DropZone<{ locked: boolean }>
+        acceptedTypes={TABLE_CELL_TYPE}
+        canDrop={(drop) => !drop.data.locked}
+        onReject={onReject}
+      />
+    );
+
+    fireEvent.drop(screen.getByTestId('ucl-uikit-drop-zone'), {
+      dataTransfer: createDataTransfer({
+        [TABLE_CELL_TYPE]: JSON.stringify({ locked: true }),
+      }),
+    });
+
+    expect(onReject).toHaveBeenCalledWith(
+      {
+        drop: expect.objectContaining({
+          data: { locked: true },
+          type: TABLE_CELL_TYPE,
+        }),
+        reason: 'cannot-drop',
+      },
+      expect.any(Object)
+    );
+  });
+
+  test('does not call onDrop when disabled', () => {
+    const onDrop = vitest.fn();
+
+    wrap(
+      <DropZone
+        acceptedTypes={TABLE_CELL_TYPE}
+        disabled
+        onDrop={onDrop}
+      />
+    );
+
+    fireEvent.drop(screen.getByTestId('ucl-uikit-drop-zone'), {
+      dataTransfer: createDataTransfer({
+        [TABLE_CELL_TYPE]: 'Approved',
+      }),
+    });
+
+    expect(onDrop).not.toHaveBeenCalled();
+  });
+
+  test('passes drag state to render-prop children', () => {
+    wrap(
+      <DropZone acceptedTypes={TABLE_CELL_TYPE}>
+        {({ isDragActive }) => (
+          <span>{isDragActive ? 'Release to drop' : 'Drop a table cell'}</span>
+        )}
+      </DropZone>
+    );
+
+    const dropZone = screen.getByTestId('ucl-uikit-drop-zone');
+
+    expect(screen.getByText('Drop a table cell')).toBeInTheDocument();
+
+    fireEvent.dragEnter(dropZone, {
+      dataTransfer: createDataTransfer({
+        [TABLE_CELL_TYPE]: 'Approved',
+      }),
+    });
+
+    expect(screen.getByText('Release to drop')).toBeInTheDocument();
+  });
+
+  test('supports keyboard drag and drop between UIKit hooks', () => {
+    const onDrop = vitest.fn();
+
+    const KeyboardDndDemo = () => {
+      const { getDragProps } = useDraggable({
+        data: { value: 'Approved' },
+        type: TABLE_CELL_TYPE,
+      });
+      const { getRootProps } = useDropZone<{ value: string }>({
+        acceptedTypes: TABLE_CELL_TYPE,
+        onDrop,
+      });
+
+      return (
+        <>
+          <button
+            data-testid='drag-source'
+            type='button'
+            {...getDragProps()}
+          >
+            Approved
+          </button>
+          <div
+            data-testid='drop-target'
+            {...getRootProps()}
+          />
+        </>
+      );
+    };
+
+    render(<KeyboardDndDemo />);
+
+    fireEvent.keyDown(screen.getByTestId('drag-source'), { key: ' ' });
+    fireEvent.keyDown(screen.getByTestId('drop-target'), { key: 'Enter' });
+
+    expect(onDrop).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: { value: 'Approved' },
+        dataTransfer: null,
+        files: [],
+        rawData: JSON.stringify({ value: 'Approved' }),
+        type: TABLE_CELL_TYPE,
+      }),
+      expect.any(Object)
+    );
+  });
+
+  test('honours keyboardDrop false on the DropZone component', () => {
+    const onDrop = vitest.fn();
+
+    const KeyboardDndDemo = () => {
+      const { getDragProps } = useDraggable({
+        data: { value: 'Approved' },
+        type: TABLE_CELL_TYPE,
+      });
+
+      return (
+        <>
+          <button
+            data-testid='drag-source'
+            type='button'
+            {...getDragProps()}
+          >
+            Approved
+          </button>
+          <DropZone
+            acceptedTypes={TABLE_CELL_TYPE}
+            keyboardDrop={false}
+            onDrop={onDrop}
+            testId='drop-target'
+          />
+        </>
+      );
+    };
+
+    wrap(<KeyboardDndDemo />);
+
+    fireEvent.keyDown(screen.getByTestId('drag-source'), { key: 'Enter' });
+    fireEvent.keyDown(screen.getByTestId('drop-target'), { key: 'Enter' });
+
+    expect(onDrop).not.toHaveBeenCalled();
+    expect(screen.getByTestId('drop-target')).not.toHaveAttribute(
+      'keyboardDrop'
+    );
+  });
+
+  test('supports keyboard drop when drag and drop props are composed on one item', () => {
+    const onDrop = vitest.fn();
+    const onReject = vitest.fn();
+
+    const ReorderItem = ({ id }: { id: string }) => {
+      const { getDragProps } = useDraggable({
+        data: { id },
+        type: TABLE_CELL_TYPE,
+      });
+      const { getRootProps } = useDropZone<{ id: string }>({
+        acceptedTypes: TABLE_CELL_TYPE,
+        canDrop: (drop) => drop.data.id !== id,
+        onDrop,
+        onReject,
+      });
+
+      return (
+        <li
+          data-testid={`item-${id}`}
+          {...getRootProps<HTMLLIElement>(getDragProps<HTMLLIElement>())}
+        >
+          {id}
+        </li>
+      );
+    };
+
+    render(
+      <ul>
+        <ReorderItem id='first' />
+        <ReorderItem id='second' />
+      </ul>
+    );
+
+    fireEvent.keyDown(screen.getByTestId('item-first'), { key: 'Enter' });
+
+    expect(onDrop).not.toHaveBeenCalled();
+    expect(onReject).not.toHaveBeenCalled();
+    expect(getActiveKeyboardDrag()?.data).toEqual({ id: 'first' });
+
+    fireEvent.keyDown(screen.getByTestId('item-second'), { key: 'Enter' });
+
+    expect(onDrop).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: { id: 'first' },
+        type: TABLE_CELL_TYPE,
+      }),
+      expect.any(Object)
+    );
+  });
+});

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

@@ -0,0 +1,46 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`DropZone > snapshot: no props 1`] = `
+<div
+  aria-label="Drop zone"
+  class="ucl-uikit-drop-zone css-vpriu7"
+  data-drag-accept="false"
+  data-drag-active="false"
+  data-drag-reject="false"
+  data-testid="ucl-uikit-drop-zone"
+  role="group"
+  tabindex="0"
+>
+  <svg
+    aria-hidden="true"
+    class="ucl-uikit-icon css-17h2vfb"
+    data-testid="ucl-uikit-icon"
+    fill="none"
+    focusable="false"
+    height="24"
+    stroke="currentColor"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    stroke-width="2"
+    viewBox="0 0 24 24"
+    width="24"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="m5 9-3 3 3 3M9 5l3-3 3 3m0 14-3 3-3-3M19 9l3 3-3 3M2 12h20M12 2v20"
+    />
+  </svg>
+  <div
+    class="ucl-uikit-paragraph css-12ufxmf"
+    data-testid="ucl-uikit-paragraph"
+  >
+    Drop an item here
+  </div>
+  <span
+    class="ucl-uikit-text css-v0obke"
+    data-testid="ucl-uikit-text"
+  >
+    Drag a compatible item into this area
+  </span>
+</div>
+`;

package/lib/components/DropZone/index.ts

@@ -0,0 +1,2 @@
+export { default } from './DropZone';
+export type { DropZoneProps, DropZoneRenderProps } from './DropZone';

package/lib/components/Skeleton/Skeleton.mdx

@@ -0,0 +1,34 @@
+import * as SkeletonStories from "./Skeleton.stories";
+import { Meta, Title, Subtitle, Canvas, Controls } from "@storybook/addon-docs/blocks";
+
+<Meta of={SkeletonStories} />
+<Title />
+<Subtitle>A placeholder that mirrors the shape of content while it loads.</Subtitle>
+
+Use `<Skeleton>` when a region's layout is known but its data is still loading. Numeric `width` and `height` values are treated as pixels; CSS strings such as `40%` are passed through.
+
+## Variants
+
+### Circle
+The default 72px circle matches the Figma avatar placeholder.
+
+<Canvas of={SkeletonStories.Circle} />
+
+### Rectangle
+Use explicit dimensions to reserve the final content's space. Rectangles have square corners by default; pass a `radius` token when the content will be rounded.
+
+<Canvas of={SkeletonStories.Landscape} />
+
+### Text
+Text placeholders are 8px high with a 16px gap. With multiple lines, the final line is 61.8% wide.
+
+<Canvas of={SkeletonStories.TextLines} />
+
+## Accessibility
+
+Skeleton shapes are decorative and hidden from assistive technology. Set `aria-busy="true"` on the region whose content is loading and provide one visually hidden loading message for that region. The shimmer is removed when the user prefers reduced motion.
+
+## Props
+
+<Canvas of={SkeletonStories.Default} sourceState="hidden" />
+<Controls of={SkeletonStories.Default} />

package/lib/components/Skeleton/Skeleton.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { css } from '@emotion/css';
+import Skeleton from './Skeleton';
+
+const meta = {
+  title: 'Components/Skeleton',
+  component: Skeleton,
+  parameters: { layout: 'padded' },
+  args: {
+    variant: 'text',
+  },
+  argTypes: {
+    variant: {
+      options: ['text', 'circle', 'rect'],
+      control: { type: 'radio' },
+    },
+  },
+} satisfies Meta<typeof Skeleton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Circle: Story = {
+  args: { variant: 'circle', width: 72, height: 72 },
+};
+
+export const Landscape: Story = {
+  args: { variant: 'rect', width: 637, height: 359 },
+};
+
+export const Portrait: Story = {
+  args: { variant: 'rect', width: 358, height: 620.69 },
+};
+
+export const TextLines: Story = {
+  args: { variant: 'text', width: 461, count: 4 },
+};
+
+export const FigmaExamples: Story = {
+  parameters: { layout: 'padded' },
+  render: () => (
+    <div
+      className={css`
+        position: relative;
+        width: 677px;
+        height: 1504px;
+      `}
+    >
+      <Skeleton
+        variant='circle'
+        width={72}
+        height={72}
+        style={{ position: 'absolute', top: 20, left: 20 }}
+      />
+      <Skeleton
+        variant='rect'
+        width={637}
+        height={359}
+        style={{ position: 'absolute', top: 139, left: 20 }}
+      />
+      <Skeleton
+        variant='rect'
+        width={358}
+        height={620.69}
+        style={{ position: 'absolute', top: 545, left: 20 }}
+      />
+      <Skeleton
+        variant='text'
+        width={461}
+        count={4}
+        style={{ position: 'absolute', top: 1246, left: 20 }}
+      />
+    </div>
+  ),
+};

package/lib/components/Skeleton/Skeleton.tsx

@@ -0,0 +1,158 @@
+import { HTMLAttributes, Ref } from 'react';
+import { css, cx } from '@emotion/css';
+import { useTheme, type ThemeType } from '../../theme';
+import marginsStyle, { MarginProps } from '../common/marginsStyle';
+import SkeletonAvatar from './SkeletonAvatar';
+import SkeletonInput from './SkeletonInput';
+import SkeletonTableRow from './SkeletonTableRow';
+import SkeletonText from './SkeletonText';
+
+export const NAME = 'ucl-uikit-skeleton';
+
+export type SkeletonVariant = 'text' | 'circle' | 'rect';
+
+export interface SkeletonBaseProps extends HTMLAttributes<HTMLDivElement> {
+  /** Placeholder shape. @default 'text' */
+  variant?: SkeletonVariant;
+  /** Overrides the bar width. Numbers are treated as pixels. */
+  width?: number | string;
+  /** Overrides the bar height. Numbers are treated as pixels. */
+  height?: number | string;
+  /** Number of bars to render. @default 1 */
+  count?: number;
+  /** Optional border-radius token. Ignored for the `circle` variant. */
+  radius?: keyof ThemeType['radius'];
+  testId?: string;
+  ref?: Ref<HTMLDivElement>;
+}
+
+export type SkeletonProps = SkeletonBaseProps & MarginProps;
+
+const toCss = (value?: number | string) =>
+  typeof value === 'number' ? `${value}px` : value;
+
+export const getSkeletonShimmerBackground = (theme: ThemeType) => {
+  return `
+    linear-gradient(
+      270deg,
+      color-mix(in srgb, ${theme.colour.bg.default} 0%, transparent) 0%,
+      color-mix(in srgb, ${theme.colour.bg.default} 55%, transparent) 50%,
+      color-mix(in srgb, ${theme.colour.bg.default} 0%, transparent) 100%
+    ),
+    linear-gradient(
+      270deg,
+      color-mix(in srgb, ${theme.colour.surface.secondary} 0%, transparent) 0%,
+      color-mix(in srgb, ${theme.colour.fill.subtle} 30%, transparent) 25%,
+      color-mix(in srgb, ${theme.colour.fill.subtle} 75%, transparent) 50%,
+      color-mix(in srgb, ${theme.colour.fill.subtle} 40%, transparent) 75%,
+      color-mix(in srgb, ${theme.colour.surface.secondary} 0%, transparent) 100%
+    )
+  `;
+};
+
+const Skeleton = ({
+  variant = 'text',
+  width,
+  height,
+  count = 1,
+  radius,
+  testId = NAME,
+  className,
+  ref,
+  ...props
+}: SkeletonProps) => {
+  const [theme] = useTheme();
+
+  const variantDefaults = {
+    text: { width: '100%', height: '8px' },
+    circle: { width: '72px', height: '72px' },
+    rect: { width: '100%', height: '96px' },
+  }[variant];
+
+  const wrapperStyle = css`
+    display: flex;
+    flex-direction: column;
+    gap: ${variant === 'text' ? theme.padding.p16 : 0};
+  `;
+
+  const barStyle = css`
+    position: relative;
+    display: block;
+    box-sizing: border-box;
+    width: ${toCss(width) ?? variantDefaults.width};
+    height: ${toCss(height) ?? variantDefaults.height};
+    overflow: hidden;
+    border-radius: ${
+      variant === 'circle' ? '9999px' : radius ? theme.radius[radius] : 0
+    };
+    background-color: ${theme.colour.surface.secondary};
+
+    &::after {
+      position: absolute;
+      top: 0;
+      left: -175px;
+      width: 175px;
+      height: 100%;
+      content: '';
+      background: ${getSkeletonShimmerBackground(theme)};
+      animation: ${NAME}-sweep 1.4s ease-in-out infinite;
+    }
+
+    @keyframes ${NAME}-sweep {
+      from {
+        left: -175px;
+      }
+
+      to {
+        left: 100%;
+      }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      &::after {
+        display: none;
+        animation: none;
+      }
+    }
+  `;
+
+  const style = cx(NAME, wrapperStyle, marginsStyle(props, theme), className);
+  const isRaggedLastLine = (index: number) =>
+    variant === 'text' && count > 1 && index === count - 1;
+
+  return (
+    <div
+      {...props}
+      ref={ref}
+      aria-hidden='true'
+      data-testid={testId}
+      className={style}
+    >
+      {Array.from({ length: count }, (_, index) => (
+        <span
+          key={index}
+          className={barStyle}
+          style={isRaggedLastLine(index) ? { width: '61.8%' } : undefined}
+        />
+      ))}
+    </div>
+  );
+};
+
+export interface SkeletonSubcomponents {
+  Text: typeof SkeletonText;
+  Avatar: typeof SkeletonAvatar;
+  Input: typeof SkeletonInput;
+  TableRow: typeof SkeletonTableRow;
+}
+
+const SkeletonWithSubcomponents = Skeleton as typeof Skeleton &
+  SkeletonSubcomponents;
+
+SkeletonWithSubcomponents.Text = SkeletonText;
+SkeletonWithSubcomponents.Avatar = SkeletonAvatar;
+SkeletonWithSubcomponents.Input = SkeletonInput;
+SkeletonWithSubcomponents.TableRow = SkeletonTableRow;
+
+export { Skeleton };
+export default SkeletonWithSubcomponents;