@dxos/react-ui-mosaic 0.3.3-main.006ca4d

package/src/mosaic/Root.tsx

@@ -0,0 +1,255 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import {
+  type CollisionDetection,
+  DndContext,
+  type DragCancelEvent,
+  type DragEndEvent,
+  type DragMoveEvent,
+  type DragOverEvent,
+  type DragStartEvent,
+  KeyboardSensor,
+  type Modifier,
+  MouseSensor,
+  pointerWithin,
+  rectIntersection,
+  TouchSensor,
+  useSensor,
+  useSensors,
+} from '@dnd-kit/core';
+import { sortableKeyboardCoordinates } from '@dnd-kit/sortable';
+import pick from 'lodash.pick';
+import React, { createContext, type FC, type PropsWithChildren, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import { DEFAULT_TRANSITION, type MosaicContainerProps, type MosaicMoveEvent, type MosaicOperation } from './Container';
+import { Debug } from './Debug';
+import { DefaultComponent } from './DefaultComponent';
+import { type MosaicTileComponent } from './Tile';
+import { type MosaicDraggedItem } from './types';
+import { Path } from './util';
+
+const DEFAULT_COMPONENT_ID = '__default';
+
+export type MosaicContextType = {
+  containers: Record<string, MosaicContainerProps<any> | undefined>;
+  setContainer: (id: string, container?: MosaicContainerProps<any>) => void;
+  activeItem: MosaicDraggedItem | undefined;
+  overItem: MosaicDraggedItem | undefined;
+  operation: MosaicOperation;
+};
+
+export const MosaicContext = createContext<MosaicContextType | undefined>(undefined);
+
+export type MosaicRootProps = PropsWithChildren<{
+  /**
+   * Default component.
+   */
+  Component?: MosaicTileComponent<any>;
+  debug?: boolean;
+}>;
+
+/**
+ * Root context provider.
+ */
+export const MosaicRoot: FC<MosaicRootProps> = ({ Component = DefaultComponent, debug, children }) => {
+  const [containers, setContainers] = useState<MosaicContextType['containers']>({
+    [DEFAULT_COMPONENT_ID]: { id: DEFAULT_COMPONENT_ID, Component },
+  });
+
+  const handleSetContainer = (id: string, container?: MosaicContainerProps<any>) => {
+    setContainers((containers) => {
+      if (container) {
+        return { ...containers, [id]: container };
+      } else {
+        const { [id]: _, ...rest } = containers;
+        return rest;
+      }
+    });
+  };
+
+  const [activeItem, setActiveItem] = useState<MosaicDraggedItem>();
+  const [overItem, setOverItem] = useState<MosaicDraggedItem>();
+  const [operation, setOperation] = useState<MosaicOperation>('reject');
+
+  //
+  // DndKit Defaults
+  //
+
+  /**
+   * See: https://docs.dndkit.com/api-documentation/context-provider/collision-detection-algorithms#custom-collision-detection-algorithms
+   * See: https://github.com/clauderic/dnd-kit/tree/master/packages/core/src/utilities/algorithms
+   */
+  // TODO(burdon): Flickering: should not change while animation is happening.
+  const collisionDetection: CollisionDetection = (args) => {
+    // pointerWithin is the most accurate (since we're using drag handles), but only works with pointer sensors.
+    const pointerCollisions = pointerWithin(args);
+    if (pointerCollisions.length > 0) {
+      return pointerCollisions;
+    }
+
+    // If there are no collisions with the pointer, return rectangle intersections.
+    return rectIntersection(args);
+  };
+
+  /**
+   * Dragging transformation modifiers adaptable by container.
+   * See: https://github.com/clauderic/dnd-kit/tree/master/packages/core/src/modifiers
+   */
+  const modifiers: Modifier = (props) => {
+    const { transform } = props;
+    if (activeItem) {
+      const container = containers[Path.first(activeItem.path)];
+      return container?.modifier?.(activeItem, props) ?? transform;
+    } else {
+      return transform;
+    }
+  };
+
+  /**
+   * See: https://github.com/clauderic/dnd-kit/tree/master/packages/core/src/sensors
+   */
+  const sensors = useSensors(
+    useSensor(MouseSensor, {
+      activationConstraint: {
+        distance: 10,
+      },
+    }),
+    useSensor(TouchSensor, {
+      activationConstraint: {
+        delay: 200,
+        tolerance: 5,
+      },
+    }),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    }),
+  );
+
+  //
+  // Events
+  //
+
+  const handleDragStart = (event: DragStartEvent) => {
+    setActiveItem(pick(event.active.data.current as MosaicDraggedItem, 'path', 'item', 'position'));
+  };
+
+  const handleDragMove = (event: DragMoveEvent) => {};
+
+  const handleDragOver = (event: DragOverEvent) => {
+    const overItem = pick(event.over?.data.current as MosaicDraggedItem, 'path', 'item', 'position');
+
+    // If the over item is the same as the active item, do nothing.
+    // This happens when moving between containers where a placeholder of itself is rendered where it will be dropped.
+    if (overItem?.item?.id === activeItem?.item.id) {
+      return;
+    }
+
+    const activeContainer = activeItem && containers[Path.first(activeItem.path)];
+    const overContainer = overItem?.path && containers[Path.first(overItem.path)];
+    if (!event.over || !overItem || !overContainer || !activeItem || !activeContainer) {
+      setOperation('reject');
+      setOverItem(undefined);
+      return;
+    }
+
+    const onOver = ({ active, over }: MosaicMoveEvent) => {
+      if (Path.parent(active.path) === Path.parent(over.path)) {
+        return 'rearrange';
+      } else if (overContainer.onOver) {
+        return overContainer.onOver({ active, over });
+      } else {
+        // TODO(wittjosiah): Default to reject.
+        return 'adopt';
+      }
+    };
+
+    setOperation(onOver({ active: activeItem, over: overItem }));
+    setOverItem(overItem);
+  };
+
+  const handleDragCancel = (event: DragCancelEvent) => {
+    setOperation('reject');
+    setActiveItem(undefined);
+    setOverItem(undefined);
+  };
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    const overContainer = overItem && containers[Path.first(overItem.path)];
+
+    if (
+      operation !== 'reject' &&
+      activeItem &&
+      overItem &&
+      (activeItem.path !== overItem.path || activeItem.position !== overItem.position)
+    ) {
+      const activeContainer = containers[Path.first(activeItem.path)];
+      if (activeContainer) {
+        activeContainer.onDrop?.({ operation, active: activeItem, over: overItem });
+
+        if (overContainer && overContainer !== activeContainer) {
+          overContainer.onDrop?.({ operation, active: activeItem, over: overItem });
+        }
+      }
+    }
+
+    setTimeout(() => {
+      setOperation('reject');
+      setOverItem(undefined);
+      setActiveItem(undefined);
+    }, overContainer?.transitionDuration ?? DEFAULT_TRANSITION);
+  };
+
+  return (
+    <MosaicContext.Provider value={{ containers, setContainer: handleSetContainer, activeItem, overItem, operation }}>
+      <DndContext
+        collisionDetection={collisionDetection}
+        modifiers={[modifiers]}
+        sensors={sensors}
+        // TODO(burdon): Allow container to veto drop.
+        cancelDrop={(event) => false}
+        onDragStart={handleDragStart}
+        onDragMove={handleDragMove}
+        onDragOver={handleDragOver}
+        onDragCancel={handleDragCancel}
+        onDragEnd={handleDragEnd}
+      >
+        {children}
+        {debug &&
+          createPortal(
+            <MosaicDebug containers={containers} operation={operation} activeItem={activeItem} overItem={overItem} />,
+            document.body,
+          )}
+      </DndContext>
+    </MosaicContext.Provider>
+  );
+};
+
+const MosaicDebug: FC<{
+  containers: MosaicContextType['containers'];
+  operation: MosaicOperation;
+  activeItem?: MosaicDraggedItem;
+  overItem?: MosaicDraggedItem;
+}> = ({ containers, operation, activeItem, overItem }) => {
+  return (
+    <Debug
+      position='bottom-right'
+      data={{
+        containers: Object.keys(containers).map((id) => id),
+        operation,
+        active: {
+          id: activeItem?.item?.id.slice(0, 16),
+          path: activeItem?.path && Path.create(...Path.parts(activeItem.path).map((part) => part.slice(0, 16))),
+          position: activeItem?.position,
+        },
+        over: {
+          id: overItem?.item?.id.slice(0, 16),
+          path: overItem?.path && Path.create(...Path.parts(overItem.path).map((part) => part.slice(0, 16))),
+          position: overItem?.position,
+        },
+      }}
+    />
+  );
+};

package/src/mosaic/SortableContext.tsx

@@ -0,0 +1,60 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { SortableContext, horizontalListSortingStrategy, verticalListSortingStrategy } from '@dnd-kit/sortable';
+import React, { type PropsWithChildren } from 'react';
+
+import { useContainer, useMosaic } from './hooks';
+import { type MosaicDataItem } from './types';
+import { Path } from './util';
+
+type Direction = 'horizontal' | 'vertical';
+
+export type MosaicSortableProps<TData extends MosaicDataItem = MosaicDataItem> = PropsWithChildren<{
+  id?: string;
+  items?: TData[];
+  direction?: Direction;
+}>;
+
+/**
+ * Mosaic convenience wrapper for dnd-kit SortableContext.
+ */
+// TODO(burdon): Remove since just obfuscates SortableContext unless more deeply integrated with useSortableItem.
+//  Otherwise accept same props as SortableContext (e.g., verticalListSortingStrategy).
+export const MosaicSortableContext = ({ id, items = [], direction = 'vertical', children }: MosaicSortableProps) => {
+  const { operation, activeItem, overItem } = useMosaic();
+  const container = useContainer();
+  const contextId = id ?? container.id;
+  const Sortable = direction === 'vertical' ? Column : Row;
+
+  const ids = items.map((item) => {
+    const path = Path.create(contextId, item.id);
+    // TODO(wittjosiah): Copied from Tile.tsx. Consider factoring out to ensure logic is consistent.
+    const isPreview =
+      activeItem &&
+      activeItem.item.id === item.id &&
+      overItem &&
+      (Path.siblings(overItem.path, path) || Path.hasChild(overItem.path, path)) &&
+      operation !== 'reject';
+    return isPreview ? activeItem.path : path;
+  });
+
+  return (
+    <Sortable id={contextId} items={ids}>
+      {children}
+    </Sortable>
+  );
+};
+
+const Column = ({ children, id, items }: PropsWithChildren<{ id: string; items: string[] }>) => (
+  <SortableContext id={id} items={items} strategy={verticalListSortingStrategy}>
+    {children}
+  </SortableContext>
+);
+
+const Row = ({ children, id, items }: PropsWithChildren<{ id: string; items: string[] }>) => (
+  <SortableContext id={id} items={items} strategy={horizontalListSortingStrategy}>
+    {children}
+  </SortableContext>
+);

package/src/mosaic/Tile.tsx

@@ -0,0 +1,189 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type DraggableAttributes, useDraggable, useDroppable } from '@dnd-kit/core';
+import { defaultAnimateLayoutChanges, useSortable } from '@dnd-kit/sortable';
+import React from 'react';
+import type { CSSProperties, ForwardRefExoticComponent, HTMLAttributes, RefAttributes } from 'react';
+
+import type { MosaicOperation, MosaicTileOverlayProps } from './Container';
+import { DefaultComponent } from './DefaultComponent';
+import { useContainer, useMosaic } from './hooks';
+import type { MosaicDataItem, MosaicDraggedItem } from './types';
+import { getTransformCSS, Path } from './util';
+
+export type MosaicActiveType = 'overlay' | 'rearrange' | 'origin' | 'destination';
+
+/**
+ * Props passed to mosaic tile.
+ */
+export type MosaicTileProps<TData extends MosaicDataItem = MosaicDataItem, TPosition = unknown> = Pick<
+  HTMLAttributes<HTMLDivElement>,
+  'className'
+> &
+  MosaicTileOverlayProps & {
+    path: string;
+    item: TData;
+    Component?: MosaicTileComponent<TData, any>;
+    position?: TPosition;
+    operation?: MosaicOperation;
+    active?: MosaicActiveType; // TODO(burdon): Rename state?
+
+    // DndKit props.
+    isDragging?: boolean;
+    isOver?: boolean;
+    draggableStyle?: CSSProperties;
+    draggableProps?: DraggableAttributes &
+      // TODO(wittjosiah): SyntheticListenerMap.
+      HTMLAttributes<HTMLElement>;
+
+    onSelect?: () => void;
+    onRemove?: () => void;
+  };
+
+/**
+ * Mosaic Tile component.
+ */
+export type MosaicTileComponent<
+  TData extends MosaicDataItem = MosaicDataItem,
+  TElement extends HTMLElement = HTMLDivElement,
+> = ForwardRefExoticComponent<
+  RefAttributes<TElement> & Omit<MosaicTileProps<TData>, 'Component' | 'operation'> & { operation: MosaicOperation }
+>;
+
+/**
+ * Basic draggable mosaic tile.
+ */
+export const DraggableTile = ({
+  path: parentPath,
+  item,
+  Component = DefaultComponent,
+  position,
+  draggableStyle,
+  ...props
+}: MosaicTileProps<any>) => {
+  const { operation } = useMosaic();
+  const path = Path.create(parentPath, item.id);
+  const { setNodeRef, attributes, listeners, /* transform, */ isDragging } = useDraggable({
+    id: path,
+    data: { path, item, position } satisfies MosaicDraggedItem,
+  });
+
+  return (
+    <Component
+      ref={setNodeRef}
+      item={item}
+      path={path}
+      position={position}
+      operation={operation}
+      isDragging={isDragging}
+      draggableStyle={{
+        // TODO(burdon): Override by container?
+        // transform: getTransformCSS(transform),
+        ...draggableStyle,
+      }}
+      draggableProps={{ ...attributes, ...listeners }}
+      {...props}
+    />
+  );
+};
+
+/**
+ * Basic droppable mosaic tile.
+ */
+export const DroppableTile = ({
+  path: parentPath,
+  item,
+  Component = DefaultComponent,
+  position,
+  ...props
+}: MosaicTileProps<any>) => {
+  const { operation } = useMosaic();
+  const path =
+    parentPath === item.id
+      ? parentPath // If the path is the same as the item id, then this is the root tile.
+      : Path.create(parentPath, item.id);
+  const { setNodeRef, isOver } = useDroppable({
+    id: path,
+    data: { path, item, position } satisfies MosaicDraggedItem,
+  });
+
+  return (
+    <Component
+      ref={setNodeRef}
+      item={item}
+      path={path}
+      position={position}
+      operation={operation}
+      isOver={isOver}
+      {...props}
+    />
+  );
+};
+
+/**
+ * Mosaic tile that can be sorted.
+ */
+export const SortableTile = ({
+  path: parentPath,
+  item,
+  Component: OverrideComponent,
+  position,
+  draggableStyle,
+  ...props
+}: MosaicTileProps<any, number>) => {
+  const { operation, activeItem, overItem } = useMosaic();
+  const { transitionDuration, Component: ContainerComponent } = useContainer();
+
+  const path = Path.create(parentPath, item.id);
+  // Re-use the active path if it's the same item and the item is a preview.
+  // This helps dndkit understand that the item is being moved and animate it appropriately.
+  const isPreview =
+    activeItem &&
+    activeItem.item.id === item.id &&
+    overItem &&
+    !Path.siblings(activeItem.path, overItem.path) &&
+    (Path.siblings(overItem.path, path) || Path.hasChild(overItem.path, path)) &&
+    operation !== 'reject';
+
+  const { setNodeRef, attributes, listeners, transform, isDragging, isOver } = useSortable({
+    id: isPreview ? activeItem.path : path,
+    data: { path, item, position } satisfies MosaicDraggedItem,
+    animateLayoutChanges: (args) =>
+      defaultAnimateLayoutChanges({ ...args, wasDragging: item.id !== activeItem?.item.id }),
+  });
+
+  let active: MosaicActiveType | undefined;
+  if (isDragging) {
+    if (operation === 'rearrange' || operation === 'reject') {
+      active = 'rearrange';
+    } else if (activeItem && Path.parent(activeItem.path) !== parentPath) {
+      active = 'destination';
+    } else {
+      active = 'origin';
+    }
+  }
+
+  const Component = OverrideComponent ?? ContainerComponent ?? DefaultComponent;
+
+  return (
+    <Component
+      ref={setNodeRef}
+      item={item}
+      path={path}
+      position={position}
+      operation={operation}
+      active={active}
+      isDragging={isDragging}
+      isOver={isOver}
+      draggableStyle={{
+        transform: getTransformCSS(transform),
+        transition: transform ? `transform ${transitionDuration}ms ease` : 'none',
+        ...draggableStyle,
+      }}
+      draggableProps={{ ...attributes, ...listeners }}
+      {...props}
+    />
+  );
+};

package/src/mosaic/hooks/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './useContainer';
+export * from './useItemsWithPreview';
+export * from './useMosaic';
+export * from './useSortedItems';

package/src/mosaic/hooks/useContainer.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { MosaicContainerContext, type MosaicContainerProps } from '../Container';
+import { type MosaicDataItem } from '../types';
+
+export const useContainer = <
+  TData extends MosaicDataItem = MosaicDataItem,
+  TPosition = unknown,
+>(): MosaicContainerProps<TData, TPosition> =>
+  useContext(MosaicContainerContext) ?? raise(new Error('Missing MosaicContainerContext'));

package/src/mosaic/hooks/useItemsWithPreview.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { useMosaic } from './useMosaic';
+import { type MosaicDataItem } from '../types';
+import { Path } from '../util';
+
+/**
+ * Returns a spliced collection of items including a placeholder if items that could drop,
+ * and removing any item that is currently being dragged out.
+ */
+export const useItemsWithPreview = <T extends MosaicDataItem>({ path, items }: { path: string; items: T[] }): T[] => {
+  const { operation, activeItem, overItem } = useMosaic();
+  const [itemsWithPreview, setItemsWithPreview] = useState(items);
+  const overParent =
+    // If over the sortable context itself & active item is foreign, then treat self as the parent.
+    // This allows items to be appended to the end of the sortable.
+    overItem?.path === path && activeItem && Path.parent(activeItem.path) !== overItem.path
+      ? path
+      : overItem && Path.parent(overItem.path);
+  const [lastOverParent, setLastOverParent] = useState(overParent);
+
+  useEffect(() => {
+    if (operation === 'reject' || operation === 'rearrange' || !activeItem || !overItem) {
+      setLastOverParent(undefined);
+      setItemsWithPreview(items);
+      return;
+    }
+
+    if (lastOverParent === overParent) {
+      return;
+    }
+
+    setLastOverParent(overParent);
+
+    const activeIsChild = Path.hasChild(path, activeItem.path);
+    const overIsChild = Path.hasChild(path, overItem.path);
+    const overSelf = overItem.path === path;
+
+    if (!activeIsChild && overIsChild) {
+      // Insert item into sortable.
+      setItemsWithPreview((items) => {
+        const position = overItem.position as number;
+        return [...items.slice(0, position), activeItem.item as T, ...items.slice(position)];
+      });
+    } else if (!activeIsChild && overSelf) {
+      // Append item to end of sortable.
+      setItemsWithPreview((items) => [...items, activeItem.item as T]);
+    } else if (activeIsChild && !overIsChild) {
+      // Remove item being dragged out.
+      setItemsWithPreview((items) => items.filter((item) => item.id !== activeItem.item.id));
+    } else {
+      // Reset items.
+      setItemsWithPreview(items);
+    }
+  }, [operation, activeItem, overItem, overParent, lastOverParent, path, items]);
+
+  // In order to avoid render glitching, rather than waiting for the effect to run,
+  // immediately return the new items after dropping an item into a new path.
+  return items.length === itemsWithPreview.length ? items : itemsWithPreview;
+};

package/src/mosaic/hooks/useMosaic.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { MosaicContext } from '../Root';
+
+export const useMosaic = () => useContext(MosaicContext) ?? raise(new Error('Missing MosaicContext'));

package/src/mosaic/hooks/useSortedItems.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useContainer } from './useContainer';
+import { type MosaicDataItem } from '../types';
+
+/**
+ * Returns a sorted collection of items if a compare function is provided.
+ */
+export const useSortedItems = <T extends MosaicDataItem>(items: T[]): T[] => {
+  const { compare } = useContainer();
+  return compare ? [...items].sort(compare) : items;
+};

package/src/mosaic/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './hooks';
+export * from './types';
+export * from './util';
+
+export * from './Mosaic';

package/src/mosaic/types.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export type MosaicDataItem = { id: string };
+
+export type MosaicDraggedItem<TPosition = unknown> = {
+  path: string;
+  // TODO(wittjosiah): Rename data? Otherwise item within item.
+  item: MosaicDataItem;
+  // Index or layout-specific positional information (stored separately from the item).
+  position?: TPosition;
+};

package/src/mosaic/util/data.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { arrayMove } from '@dxos/util';
+
+import { type MosaicDataItem } from '../types';
+
+// TODO(wittjosiah): Generalize and expand rearrange utilities.
+
+export const swapItems = <TItem extends MosaicDataItem, TValue extends MosaicDataItem>(
+  items: TItem[],
+  from: TValue,
+  to: TValue,
+): TItem[] => {
+  const fromIndex = items.findIndex((item) => item.id === from.id);
+  const toIndex = items.findIndex((item) => item.id === to.id);
+  return fromIndex !== -1 && toIndex !== -1 ? arrayMove(items, fromIndex, toIndex) : items;
+};

package/src/mosaic/util/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './data';
+export * from './path';
+export * from './styles';