uikit-react-public 0.45.5 → 0.47.0

package/lib/components/DropZone/DropZone.mdx

@@ -0,0 +1,72 @@
+import * as DropZoneStories from './DropZone.stories';
+import {
+  Meta,
+  Title,
+  Subtitle,
+  Description,
+  Canvas,
+  Controls,
+  ArgTypes,
+} from '@storybook/addon-docs/blocks';
+
+export const usage = {
+  default: `<DropZone
+  acceptedTypes='application/x-ucl-uikit-table-cell'
+  onDrop={(drop) => console.log(drop.data)}
+/>`,
+  sourceAndTarget: `const TABLE_CELL_TYPE = 'application/x-ucl-uikit-table-cell';
+
+const { getDragProps } = useDraggable({
+type: TABLE_CELL_TYPE,
+data: { row: 'Research proposal', column: 'Status', value: 'Approved' },
+});
+
+<Table.Cell {...getDragProps()}>Approved</Table.Cell>
+
+<DropZone
+  acceptedTypes={TABLE_CELL_TYPE}
+  onDrop={(drop) => setDroppedCell(drop.data)}
+/>`,
+};
+
+<Meta of={DropZoneStories} />
+<Title />
+<Subtitle>A themed drop target built on the public useDropZone hook</Subtitle>
+
+<Description>
+  `DropZone` accepts generic drag data. Use it with `useDraggable` for
+  UIKit-managed drag data, or pass native drag handlers when integrating with
+  another drag source. UIKit-managed draggables can be picked up with Space or
+  Enter, cancelled with Escape, and dropped on a focused drop target with Space
+  or Enter.
+</Description>
+
+<Canvas
+  of={DropZoneStories.Default}
+  source={{ code: usage.default }}
+/>
+
+## Source And Target
+
+Use `useDraggable` on a source element and `DropZone` on the target.
+
+For workflows such as list reordering, provide an equivalent button or menu
+action when the drag operation is not the only reasonable way to complete the
+task.
+
+<Canvas
+  of={DropZoneStories.WithTableCell}
+  source={{ code: usage.sourceAndTarget }}
+/>
+
+## States
+
+<Canvas of={DropZoneStories.Disabled} />
+
+## Props
+
+<ArgTypes of={DropZoneStories} />
+
+## Interactive Controls
+
+<Controls of={DropZoneStories.Default} />

package/lib/components/DropZone/DropZone.stories.tsx

@@ -0,0 +1,139 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { css } from '@emotion/css';
+import DropZone from './DropZone';
+import Text from '../Text';
+import { useDraggable } from '../../hooks';
+
+const TABLE_CELL_TYPE = 'application/x-ucl-uikit-table-cell';
+
+interface TableCellDragData {
+  column: string;
+  row: string;
+  value: string;
+}
+
+const meta = {
+  title: 'Components/DropZone',
+  component: DropZone,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    acceptedTypes: {
+      control: { type: 'object' },
+    },
+    disabled: {
+      control: { type: 'boolean' },
+    },
+    dropEffect: {
+      options: ['copy', 'move', 'link'],
+      control: { type: 'select' },
+    },
+    testId: {
+      control: { type: 'text' },
+    },
+    className: {
+      control: false,
+    },
+    children: {
+      control: false,
+    },
+    onDrop: {
+      action: 'drop',
+    },
+    onReject: {
+      action: 'reject',
+    },
+  },
+  args: {
+    acceptedTypes: TABLE_CELL_TYPE,
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof DropZone>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const storyContainerStyle = css`
+  display: grid;
+  grid-template-columns: minmax(180px, 1fr) minmax(260px, 1.5fr);
+  gap: 24px;
+  width: min(720px, 90vw);
+`;
+
+const draggableCellStyle = css`
+  display: inline-flex;
+  align-items: center;
+  min-height: 40px;
+  padding: 0 12px;
+  border: 1px solid #d8dde8;
+  border-radius: 4px;
+  cursor: grab;
+  user-select: none;
+`;
+
+const DraggableCell = ({ data }: { data: TableCellDragData }) => {
+  const { getDragProps, isDragging } = useDraggable({
+    data,
+    type: TABLE_CELL_TYPE,
+  });
+
+  return (
+    <span
+      {...getDragProps({
+        className: draggableCellStyle,
+      })}
+      aria-label={`Drag ${data.value}`}
+    >
+      {isDragging ? 'Dragging...' : data.value}
+    </span>
+  );
+};
+
+const TableCellDropExample = () => {
+  const [droppedCell, setDroppedCell] = useState<TableCellDragData | null>(
+    null
+  );
+
+  return (
+    <div className={storyContainerStyle}>
+      <DraggableCell
+        data={{
+          column: 'Status',
+          row: 'Research proposal',
+          value: 'Approved',
+        }}
+      />
+      <DropZone<TableCellDragData>
+        acceptedTypes={TABLE_CELL_TYPE}
+        onDrop={(drop) => setDroppedCell(drop.data)}
+      >
+        {({ isDragActive }) => (
+          <Text level='md-semibold'>
+            {droppedCell
+              ? `${droppedCell.row}: ${droppedCell.value}`
+              : isDragActive
+                ? 'Release to drop the table cell'
+                : 'Drop a table cell here'}
+          </Text>
+        )}
+      </DropZone>
+    </div>
+  );
+};
+
+export const Default: Story = {
+  render: (args) => <DropZone {...args} />,
+};
+
+export const WithTableCell: Story = {
+  render: () => <TableCellDropExample />,
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+  render: (args) => <DropZone {...args} />,
+};

package/lib/components/DropZone/DropZone.tsx

@@ -0,0 +1,213 @@
+import { HTMLAttributes, ReactNode, Ref, memo } from 'react';
+import { css, cx } from '@emotion/css';
+import useTheme from '../../theme/useTheme';
+import useDropZone, {
+  DropZoneAcceptedTypes,
+  DropZoneDrop,
+  DropZoneRejection,
+  UseDropZoneOptions,
+} from '../../hooks/useDropZone';
+import marginsStyle, { MarginProps } from '../common/marginsStyle';
+import Icon from '../Icon';
+import Paragraph from '../Paragraph';
+import Text from '../Text';
+
+export const NAME = 'ucl-uikit-drop-zone';
+
+export interface DropZoneRenderProps<TData = unknown> {
+  activeTypes: string[];
+  isDragAccept: boolean;
+  isDragActive: boolean;
+  isDragReject: boolean;
+  lastDrop: DropZoneDrop<TData> | null;
+  lastRejection: DropZoneRejection<TData> | null;
+}
+
+export interface DropZoneBaseProps<TData = unknown>
+  extends
+    Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'onDrop'>,
+    UseDropZoneOptions<TData> {
+  children?: ReactNode | ((props: DropZoneRenderProps<TData>) => ReactNode);
+  ref?: Ref<HTMLDivElement>;
+  testId?: string;
+}
+
+export type DropZoneProps<TData = unknown> = DropZoneBaseProps<TData> &
+  MarginProps;
+
+const getDefaultDescription = (acceptedTypes?: DropZoneAcceptedTypes) => {
+  if (!acceptedTypes) return 'Drop an item here';
+
+  const values =
+    typeof acceptedTypes === 'string'
+      ? acceptedTypes.split(',')
+      : Array.from(acceptedTypes);
+  const normalizedValues = values.map((value) => value.trim()).filter(Boolean);
+
+  return normalizedValues.length > 0
+    ? `Drop ${normalizedValues.join(', ')} here`
+    : 'Drop an item here';
+};
+
+const DropZone = <TData = unknown,>({
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  acceptedTypes,
+  canDrop,
+  children,
+  className,
+  disabled = false,
+  dropEffect = 'move',
+  keyboardDrop,
+  onDrop,
+  onReject,
+  parseData,
+  ref,
+  role,
+  testId = NAME,
+  ...props
+}: DropZoneProps<TData>) => {
+  const [theme] = useTheme();
+  const {
+    activeTypes,
+    getRootProps,
+    isDragAccept,
+    isDragActive,
+    isDragReject,
+    lastDrop,
+    lastRejection,
+  } = useDropZone<TData>({
+    acceptedTypes,
+    canDrop,
+    disabled,
+    dropEffect,
+    keyboardDrop,
+    onDrop,
+    onReject,
+    parseData,
+  });
+
+  const baseStyle = css`
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: ${theme.padding.p8};
+    width: 100%;
+    min-height: 160px;
+    padding: ${theme.padding.p24};
+    color: ${theme.colour.text.default};
+    background-color: ${theme.colour.surface.default};
+    border: ${theme.border.b2} dashed ${theme.colour.border.default};
+    border-radius: ${theme.radius.r4};
+    outline: none;
+    text-align: center;
+
+    &:focus-visible {
+      box-shadow: ${theme.boxShadow.focus};
+    }
+  `;
+
+  const activeStyle = css`
+    background-color: ${theme.colour.surface.brand};
+    border-color: ${theme.colour.border.brand};
+  `;
+
+  const acceptStyle = css`
+    border-color: ${theme.colour.border.success};
+  `;
+
+  const rejectStyle = css`
+    background-color: ${theme.colour.surface.critical};
+    border-color: ${theme.colour.border.critical};
+  `;
+
+  const disabledStyle = css`
+    color: ${theme.colour.text.disabled};
+    background-color: ${theme.colour.fill.disabled};
+    border-color: ${theme.colour.border.disabled};
+    cursor: not-allowed;
+  `;
+
+  const iconStyle = css`
+    color: ${
+      disabled
+        ? theme.colour.icon.disabled
+        : isDragReject
+          ? theme.colour.icon.critical
+          : isDragAccept
+            ? theme.colour.icon.success
+            : theme.colour.icon.brand
+    };
+  `;
+
+  const style = cx(
+    NAME,
+    baseStyle,
+    marginsStyle(props, theme),
+    isDragActive && activeStyle,
+    isDragAccept && acceptStyle,
+    isDragReject && rejectStyle,
+    disabled && disabledStyle,
+    className
+  );
+
+  const renderProps: DropZoneRenderProps<TData> = {
+    activeTypes,
+    isDragAccept,
+    isDragActive,
+    isDragReject,
+    lastDrop,
+    lastRejection,
+  };
+
+  return (
+    <div
+      data-testid={testId}
+      {...getRootProps({
+        ...props,
+        'aria-label': ariaLabel ?? (ariaLabelledBy ? undefined : 'Drop zone'),
+        'aria-labelledby': ariaLabelledBy,
+        ref,
+        role: role ?? 'group',
+        className: style,
+      })}
+    >
+      {typeof children === 'function' ? (
+        children(renderProps)
+      ) : (
+        <>
+          <Icon.Move
+            aria-hidden='true'
+            className={iconStyle}
+          />
+          {children ?? (
+            <>
+              <Paragraph
+                as='div'
+                level='md-semibold'
+                noMargins
+              >
+                {isDragReject
+                  ? 'This item cannot be dropped here'
+                  : isDragActive
+                    ? 'Release to drop'
+                    : getDefaultDescription(acceptedTypes)}
+              </Paragraph>
+              <Text level='sm'>
+                {isDragReject
+                  ? 'This drop target does not accept that item'
+                  : 'Drag a compatible item into this area'}
+              </Text>
+            </>
+          )}
+        </>
+      )}
+    </div>
+  );
+};
+
+const MemoizedDropZone = memo(DropZone) as typeof DropZone;
+
+export default MemoizedDropZone;