uikit-react-public 0.45.4 → 0.47.0

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;

package/lib/components/Skeleton/SkeletonAvatar.tsx

@@ -0,0 +1,20 @@
+import { Skeleton, SkeletonProps } from './Skeleton';
+
+export interface SkeletonAvatarProps extends Omit<
+  SkeletonProps,
+  'variant' | 'width' | 'height' | 'count'
+> {
+  /** Matches the `Avatar` size options. @default 72 */
+  size?: 32 | 48 | 56 | 72 | 80;
+}
+
+const SkeletonAvatar = ({ size = 72, ...props }: SkeletonAvatarProps) => (
+  <Skeleton
+    variant='circle'
+    width={size}
+    height={size}
+    {...props}
+  />
+);
+
+export default SkeletonAvatar;

package/lib/components/Skeleton/SkeletonInput.tsx

@@ -0,0 +1,13 @@
+import { Skeleton, SkeletonProps } from './Skeleton';
+
+export type SkeletonInputProps = Omit<SkeletonProps, 'variant' | 'count'>;
+
+const SkeletonInput = ({ height = 48, ...props }: SkeletonInputProps) => (
+  <Skeleton
+    variant='rect'
+    height={height}
+    {...props}
+  />
+);
+
+export default SkeletonInput;

package/lib/components/Skeleton/SkeletonTableRow.tsx

@@ -0,0 +1,44 @@
+import { HTMLAttributes } from 'react';
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../theme';
+import { Skeleton } from './Skeleton';
+
+export const NAME = 'ucl-uikit-skeleton__table-row';
+
+export interface SkeletonTableRowProps extends HTMLAttributes<HTMLTableRowElement> {
+  /** Number of cells to render. @default 4 */
+  columns?: number;
+  testId?: string;
+}
+
+const SkeletonTableRow = ({
+  columns = 4,
+  testId = NAME,
+  className,
+  ...props
+}: SkeletonTableRowProps) => {
+  const [theme] = useTheme();
+
+  const cellStyle = css`
+    padding: ${theme.padding.p12} ${theme.padding.p16};
+  `;
+
+  return (
+    <tr
+      className={cx(NAME, className)}
+      data-testid={testId}
+      {...props}
+    >
+      {Array.from({ length: columns }, (_, index) => (
+        <td
+          key={index}
+          className={cellStyle}
+        >
+          <Skeleton variant='text' />
+        </td>
+      ))}
+    </tr>
+  );
+};
+
+export default SkeletonTableRow;

package/lib/components/Skeleton/SkeletonText.tsx

@@ -0,0 +1,13 @@
+import { Skeleton, SkeletonProps } from './Skeleton';
+
+export type SkeletonTextProps = Omit<SkeletonProps, 'variant'>;
+
+const SkeletonText = ({ count = 4, ...props }: SkeletonTextProps) => (
+  <Skeleton
+    variant='text'
+    count={count}
+    {...props}
+  />
+);
+
+export default SkeletonText;

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

@@ -0,0 +1,86 @@
+import { describe, expect, test } from 'vitest';
+import { render } from '@testing-library/react';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+import darkTheme from '../../../theme/dark/darkTheme';
+import lightTheme from '../../../theme/light/lightTheme';
+import Skeleton, { getSkeletonShimmerBackground } from '../Skeleton';
+
+const wrap = (ui: React.ReactElement) =>
+  render(<ThemeContextProvider>{ui}</ThemeContextProvider>);
+
+describe('Skeleton', () => {
+  test('renders one bar per count', () => {
+    const { getByTestId } = wrap(
+      <Skeleton
+        count={4}
+        testId='skeleton'
+      />
+    );
+
+    expect(getByTestId('skeleton').childElementCount).toBe(4);
+  });
+
+  test('is hidden from assistive technology', () => {
+    const { getByTestId } = wrap(<Skeleton testId='skeleton' />);
+
+    expect(getByTestId('skeleton')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  test('applies a custom class name', () => {
+    const { getByTestId } = wrap(
+      <Skeleton
+        className='custom-class'
+        testId='skeleton'
+      />
+    );
+
+    expect(getByTestId('skeleton')).toHaveClass('custom-class');
+  });
+
+  test('renders a 61.8% final line for multiline text', () => {
+    const { getByTestId } = wrap(
+      <Skeleton
+        count={4}
+        testId='skeleton'
+      />
+    );
+
+    expect(getByTestId('skeleton').lastElementChild).toHaveStyle({
+      width: '61.8%',
+    });
+  });
+
+  test('does not shorten a single text line', () => {
+    const { getByTestId } = wrap(<Skeleton testId='skeleton' />);
+
+    expect(getByTestId('skeleton').firstElementChild).not.toHaveAttribute(
+      'style'
+    );
+  });
+
+  test('Skeleton.TableRow renders one cell per column', () => {
+    const { getByTestId } = wrap(
+      <table>
+        <tbody>
+          <Skeleton.TableRow
+            columns={4}
+            testId='skeleton-row'
+          />
+        </tbody>
+      </table>
+    );
+
+    expect(getByTestId('skeleton-row').querySelectorAll('td')).toHaveLength(4);
+  });
+
+  test.each([
+    ['light', lightTheme],
+    ['dark', darkTheme],
+  ])('uses semantic theme colours for the %s shimmer', (_, theme) => {
+    const shimmer = getSkeletonShimmerBackground(theme);
+
+    expect(shimmer).toContain(theme.colour.bg.default);
+    expect(shimmer).toContain(theme.colour.surface.secondary);
+    expect(shimmer).toContain(theme.colour.fill.subtle);
+  });
+});

package/lib/components/Skeleton/index.ts

@@ -0,0 +1,6 @@
+export { default } from './Skeleton';
+export type { SkeletonProps, SkeletonVariant } from './Skeleton';
+export type { SkeletonAvatarProps } from './SkeletonAvatar';
+export type { SkeletonInputProps } from './SkeletonInput';
+export type { SkeletonTableRowProps } from './SkeletonTableRow';
+export type { SkeletonTextProps } from './SkeletonText';

package/lib/components/index.ts

@@ -56,6 +56,16 @@ export type {
   ProgressBarVariant,
 } from './ProgressBar';
 
+export { default as Skeleton } from './Skeleton';
+export type {
+  SkeletonProps,
+  SkeletonVariant,
+  SkeletonTextProps,
+  SkeletonAvatarProps,
+  SkeletonInputProps,
+  SkeletonTableRowProps,
+} from './Skeleton';
+
 export { default as Textarea } from './Textarea';
 export type { TextareaProps } from './Textarea';
 
@@ -215,6 +225,9 @@ export type { CalendarProps, CalendarStatuses } from './Calendar';
 
 export { default as WeekPicker } from './WeekPicker';
 
+export { default as DropZone } from './DropZone';
+export type { DropZoneProps, DropZoneRenderProps } from './DropZone';
+
 export { default as FileInput } from './FileInput';
 export type { FileInputProps } from './FileInput';
 

package/lib/hooks/__tests__/useDraggable.test.tsx

@@ -0,0 +1,184 @@
+import { afterEach, describe, expect, test, vitest } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { UIKIT_DND_DATA_TYPE, useDraggable } from '..';
+import { clearActiveKeyboardDrag, getActiveKeyboardDrag } from '../useDropZone';
+
+const TABLE_CELL_TYPE = 'application/x-ucl-uikit-table-cell';
+
+const createDataTransfer = () =>
+  ({
+    effectAllowed: 'all',
+    setData: vitest.fn(),
+    setDragImage: vitest.fn(),
+  }) as unknown as DataTransfer;
+
+const DraggableDemo = () => {
+  const { getDragProps, isDragging } = useDraggable({
+    data: {
+      column: 'Status',
+      row: 'Research proposal',
+      value: 'Approved',
+    },
+    type: TABLE_CELL_TYPE,
+  });
+
+  return (
+    <div
+      data-testid='drag-source'
+      {...getDragProps()}
+    >
+      {isDragging ? 'Dragging' : 'Ready'}
+    </div>
+  );
+};
+
+const StringDraggableDemo = () => {
+  const { getDragProps } = useDraggable({
+    data: '123',
+    type: TABLE_CELL_TYPE,
+  });
+
+  return (
+    <div
+      data-testid='string-drag-source'
+      {...getDragProps()}
+    />
+  );
+};
+
+const DisabledDraggableDemo = ({ disabled }: { disabled: boolean }) => {
+  const { getDragProps } = useDraggable({
+    data: 'Approved',
+    disabled,
+    type: TABLE_CELL_TYPE,
+  });
+
+  return (
+    <div
+      data-testid='disabled-drag-source'
+      {...getDragProps()}
+    />
+  );
+};
+
+describe('useDraggable', () => {
+  afterEach(() => {
+    clearActiveKeyboardDrag();
+  });
+
+  test('sets draggable data on drag start', () => {
+    const dataTransfer = createDataTransfer();
+
+    render(<DraggableDemo />);
+
+    fireEvent.dragStart(screen.getByTestId('drag-source'), {
+      dataTransfer,
+    });
+
+    expect(dataTransfer.effectAllowed).toBe('move');
+    expect(dataTransfer.setData).toHaveBeenCalledWith(
+      TABLE_CELL_TYPE,
+      JSON.stringify({
+        column: 'Status',
+        row: 'Research proposal',
+        value: 'Approved',
+      })
+    );
+    expect(dataTransfer.setData).toHaveBeenCalledWith(
+      UIKIT_DND_DATA_TYPE,
+      JSON.stringify({
+        data: JSON.stringify({
+          column: 'Status',
+          row: 'Research proposal',
+          value: 'Approved',
+        }),
+        type: TABLE_CELL_TYPE,
+      })
+    );
+    expect(screen.getByText('Dragging')).toBeInTheDocument();
+  });
+
+  test('clears dragging state on drag end', () => {
+    render(<DraggableDemo />);
+
+    fireEvent.dragStart(screen.getByTestId('drag-source'), {
+      dataTransfer: createDataTransfer(),
+    });
+    fireEvent.dragEnd(screen.getByTestId('drag-source'));
+
+    expect(screen.getByText('Ready')).toBeInTheDocument();
+  });
+
+  test('serializes strings as JSON strings', () => {
+    const dataTransfer = createDataTransfer();
+
+    render(<StringDraggableDemo />);
+
+    fireEvent.dragStart(screen.getByTestId('string-drag-source'), {
+      dataTransfer,
+    });
+
+    expect(dataTransfer.setData).toHaveBeenCalledWith(
+      TABLE_CELL_TYPE,
+      JSON.stringify('123')
+    );
+  });
+
+  test('supports keyboard drag start and cancel', () => {
+    render(<DraggableDemo />);
+
+    fireEvent.keyDown(screen.getByTestId('drag-source'), { key: 'Enter' });
+
+    expect(screen.getByText('Dragging')).toBeInTheDocument();
+
+    fireEvent.keyDown(screen.getByTestId('drag-source'), { key: 'Escape' });
+
+    expect(screen.getByText('Ready')).toBeInTheDocument();
+  });
+
+  test('does not replace an active keyboard drag', () => {
+    render(
+      <>
+        <DraggableDemo />
+        <StringDraggableDemo />
+      </>
+    );
+
+    fireEvent.keyDown(screen.getByTestId('drag-source'), { key: 'Enter' });
+    fireEvent.keyDown(screen.getByTestId('string-drag-source'), {
+      key: 'Enter',
+    });
+
+    expect(getActiveKeyboardDrag()?.data).toEqual({
+      column: 'Status',
+      row: 'Research proposal',
+      value: 'Approved',
+    });
+  });
+
+  test('clears an owned keyboard drag on unmount', () => {
+    const { unmount } = render(<DraggableDemo />);
+
+    fireEvent.keyDown(screen.getByTestId('drag-source'), { key: 'Enter' });
+
+    expect(getActiveKeyboardDrag()).not.toBeNull();
+
+    unmount();
+
+    expect(getActiveKeyboardDrag()).toBeNull();
+  });
+
+  test('clears an owned keyboard drag when disabled', () => {
+    const { rerender } = render(<DisabledDraggableDemo disabled={false} />);
+
+    fireEvent.keyDown(screen.getByTestId('disabled-drag-source'), {
+      key: 'Enter',
+    });
+
+    expect(getActiveKeyboardDrag()).not.toBeNull();
+
+    rerender(<DisabledDraggableDemo disabled />);
+
+    expect(getActiveKeyboardDrag()).toBeNull();
+  });
+});

package/lib/hooks/index.ts

@@ -1,2 +1,21 @@
 export { useFocusTrap } from './useFocusTrap';
+export { default as useDraggable } from './useDraggable';
+export type {
+  DraggableProps,
+  UseDraggableOptions,
+  UseDraggableReturn,
+} from './useDraggable';
+export { default as useDropZone, UIKIT_DND_DATA_TYPE } from './useDropZone';
+export type {
+  DragData,
+  DropZoneAcceptedTypes,
+  DropZoneDrop,
+  DropZoneEvent,
+  DropZoneRejection,
+  DropZoneRejectionReason,
+  DropZoneRootProps,
+  KeyboardDragData,
+  UseDropZoneOptions,
+  UseDropZoneReturn,
+} from './useDropZone';
 export { default as useMediaQuery } from './useMediaQuery';