uikit-react-public 0.45.5 → 0.47.0

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';

package/lib/hooks/useDraggable.ts

@@ -0,0 +1,243 @@
+import {
+  DragEvent,
+  HTMLAttributes,
+  KeyboardEvent,
+  Ref,
+  RefCallback,
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from 'react';
+import {
+  clearActiveKeyboardDrag,
+  DragData,
+  getActiveKeyboardDrag,
+  setActiveKeyboardDrag,
+  subscribeToKeyboardDrag,
+  UIKIT_DND_DATA_TYPE,
+} from './useDropZone';
+
+export interface UseDraggableOptions<TData = unknown> {
+  data: TData;
+  disabled?: boolean;
+  dragImage?: Element;
+  dragImageOffset?: {
+    x: number;
+    y: number;
+  };
+  effectAllowed?: DataTransfer['effectAllowed'];
+  keyboardDrag?: boolean;
+  onDragEnd?: (event: DragEvent<HTMLElement>) => void;
+  onKeyboardDragCancel?: (dragData: DragData<TData>) => void;
+  onDragStart?: (
+    dragData: DragData<TData>,
+    event: DragEvent<HTMLElement>
+  ) => void;
+  onKeyboardDragStart?: (dragData: DragData<TData>) => void;
+  serializeData?: (data: TData) => string;
+  type: string;
+}
+
+export interface DraggableProps<
+  TElement extends HTMLElement,
+> extends HTMLAttributes<TElement> {
+  draggable: boolean;
+  ref: RefCallback<TElement>;
+}
+
+export interface UseDraggableReturn {
+  getDragProps: <TElement extends HTMLElement = HTMLElement>(
+    props?: HTMLAttributes<TElement> & { ref?: Ref<TElement> }
+  ) => DraggableProps<TElement>;
+  isDragging: boolean;
+}
+
+const serializeDefaultData = <TData>(data: TData): string => {
+  const serializedData = JSON.stringify(data);
+
+  if (serializedData === undefined) {
+    throw new TypeError('Drag data must be JSON-serializable');
+  }
+
+  return serializedData;
+};
+
+const setRef = <TValue>(ref: Ref<TValue> | undefined, value: TValue) => {
+  if (!ref) return;
+
+  if (typeof ref === 'function') {
+    ref(value);
+    return;
+  }
+
+  ref.current = value;
+};
+
+const useDraggable = <TData = unknown>({
+  data,
+  disabled = false,
+  dragImage,
+  dragImageOffset = { x: 0, y: 0 },
+  effectAllowed = 'move',
+  keyboardDrag = true,
+  onDragEnd,
+  onKeyboardDragCancel,
+  onDragStart,
+  onKeyboardDragStart,
+  serializeData = serializeDefaultData,
+  type,
+}: UseDraggableOptions<TData>): UseDraggableReturn => {
+  const dragId = useId();
+  const dragRef = useRef<HTMLElement | null>(null);
+  const [isDragging, setIsDragging] = useState(false);
+
+  const getDragData = useCallback((): DragData<TData> => {
+    const rawData = serializeData(data);
+
+    return {
+      data,
+      rawData,
+      type,
+    };
+  }, [data, serializeData, type]);
+
+  useEffect(() => {
+    const unsubscribe = subscribeToKeyboardDrag(() => {
+      if (getActiveKeyboardDrag()?.id !== dragId) {
+        setIsDragging(false);
+      }
+    });
+
+    return () => {
+      unsubscribe();
+      if (getActiveKeyboardDrag()?.id === dragId) {
+        clearActiveKeyboardDrag();
+      }
+    };
+  }, [dragId]);
+
+  useEffect(() => {
+    if (disabled && getActiveKeyboardDrag()?.id === dragId) {
+      clearActiveKeyboardDrag();
+    }
+  }, [disabled, dragId]);
+
+  const getDragProps = useCallback(
+    <TElement extends HTMLElement = HTMLElement>({
+      onDragEnd: userOnDragEnd,
+      onDragStart: userOnDragStart,
+      onKeyDown: userOnKeyDown,
+      ref: userRef,
+      tabIndex,
+      ...props
+    }: HTMLAttributes<TElement> & { ref?: Ref<TElement> } = {}) => {
+      const ref: RefCallback<TElement> = (element) => {
+        dragRef.current = element;
+        setRef(userRef, element);
+      };
+
+      const onDragStartHandler = (event: DragEvent<TElement>) => {
+        userOnDragStart?.(event);
+        if (disabled || event.defaultPrevented) return;
+
+        const dragData = getDragData();
+
+        event.dataTransfer.effectAllowed = effectAllowed;
+        event.dataTransfer.setData(type, dragData.rawData ?? '');
+        event.dataTransfer.setData(
+          UIKIT_DND_DATA_TYPE,
+          JSON.stringify({
+            data: dragData.rawData,
+            type,
+          })
+        );
+
+        if (dragImage) {
+          event.dataTransfer.setDragImage(
+            dragImage,
+            dragImageOffset.x,
+            dragImageOffset.y
+          );
+        }
+
+        setIsDragging(true);
+        onDragStart?.(dragData, event);
+      };
+
+      const onDragEndHandler = (event: DragEvent<TElement>) => {
+        userOnDragEnd?.(event);
+        setIsDragging(false);
+        onDragEnd?.(event);
+      };
+
+      const onKeyDownHandler = (event: KeyboardEvent<TElement>) => {
+        userOnKeyDown?.(event);
+        if (disabled || !keyboardDrag || event.defaultPrevented) return;
+
+        if (event.target !== event.currentTarget) return;
+
+        if (event.key === 'Escape' && isDragging) {
+          event.preventDefault();
+          const dragData = getDragData();
+          clearActiveKeyboardDrag();
+          setIsDragging(false);
+          onKeyboardDragCancel?.(dragData);
+          return;
+        }
+
+        if (
+          (event.key !== 'Enter' && event.key !== ' ') ||
+          getActiveKeyboardDrag()
+        ) {
+          return;
+        }
+
+        event.preventDefault();
+
+        const dragData = getDragData();
+        setActiveKeyboardDrag({
+          ...dragData,
+          id: dragId,
+          rawData: dragData.rawData ?? '',
+        });
+        setIsDragging(true);
+        onKeyboardDragStart?.(dragData);
+      };
+
+      return {
+        ...props,
+        ref,
+        draggable: !disabled,
+        tabIndex: disabled ? -1 : keyboardDrag ? (tabIndex ?? 0) : tabIndex,
+        onDragEnd: onDragEndHandler,
+        onDragStart: onDragStartHandler,
+        onKeyDown: onKeyDownHandler,
+      };
+    },
+    [
+      disabled,
+      dragImage,
+      dragImageOffset.x,
+      dragImageOffset.y,
+      effectAllowed,
+      getDragData,
+      isDragging,
+      keyboardDrag,
+      onKeyboardDragCancel,
+      onDragEnd,
+      onKeyboardDragStart,
+      onDragStart,
+      type,
+      dragId,
+    ]
+  );
+
+  return {
+    getDragProps,
+    isDragging,
+  };
+};
+
+export default useDraggable;