@dxos/react-ui-mosaic 0.3.3-main.3ce60d4

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@dxos/react-ui-mosaic",
+  "version": "0.3.3-main.3ce60d4",
+  "description": "An intermediate interface for drag-and-drop interactions.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "exports": {
+    ".": "./dist/lib/browser/index.mjs"
+  },
+  "types": "./dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@dnd-kit/core": "^6.0.5",
+    "@dnd-kit/modifiers": "^6.0.0",
+    "@dnd-kit/sortable": "^7.0.1",
+    "@dnd-kit/utilities": "^3.2.0",
+    "@preact/signals-core": "^1.5.0",
+    "@radix-ui/react-compose-refs": "^1.0.0",
+    "@tldraw/indices": "2.0.0-alpha.14",
+    "deepsignal": "^1.3.6",
+    "lodash.defaultsdeep": "^4.6.1",
+    "lodash.pick": "^4.4.0",
+    "react-resize-detector": "^7.1.2",
+    "@dxos/debug": "0.3.3-main.3ce60d4",
+    "@dxos/invariant": "0.3.3-main.3ce60d4",
+    "@dxos/keys": "0.3.3-main.3ce60d4",
+    "@dxos/react-ui": "0.3.3-main.3ce60d4",
+    "@dxos/react-ui-theme": "0.3.3-main.3ce60d4",
+    "@dxos/react-ui-types": "0.3.3-main.3ce60d4",
+    "@dxos/util": "0.3.3-main.3ce60d4"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^8.0.2",
+    "@phosphor-icons/react": "^2.0.5",
+    "@types/d3": "^7.1.0",
+    "@types/lodash.defaultsdeep": "^4.6.6",
+    "@types/lodash.pick": "^4.4.7",
+    "@types/react": "^18.0.21",
+    "@types/react-dom": "^18.0.6",
+    "chromatic": "^6.17.0",
+    "d3": "^7.4.4",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "vite": "^4.3.9",
+    "vite-plugin-turbosnap": "^1.0.2",
+    "@braneframe/plugin-graph": "0.3.3-main.3ce60d4",
+    "@dxos/echo-schema": "0.3.3-main.3ce60d4",
+    "@dxos/gem-core": "0.3.3-main.3ce60d4",
+    "@dxos/react-client": "0.3.3-main.3ce60d4"
+  },
+  "peerDependencies": {
+    "@phosphor-icons/react": "^2.0.5",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "chromatic": "true"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './mosaic';

package/src/mosaic/Container.tsx

@@ -0,0 +1,137 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Modifier } from '@dnd-kit/core';
+import React, {
+  createContext,
+  useEffect,
+  type CSSProperties,
+  type HTMLAttributes,
+  type PropsWithChildren,
+} from 'react';
+
+import { type MosaicTileComponent } from './Tile';
+import { useMosaic } from './hooks';
+import { type MosaicDataItem, type MosaicDraggedItem } from './types';
+
+export const DEFAULT_TRANSITION = 200;
+
+export type MosaicTileOverlayProps = {
+  grow?: boolean;
+  debug?: boolean;
+};
+
+// TODO(wittjosiah): Add delete.
+export type MosaicOperation = 'adopt' | 'copy' | 'rearrange' | 'reject';
+
+export type MosaicMoveEvent<TPosition = unknown> = {
+  active: MosaicDraggedItem<TPosition>;
+  over: MosaicDraggedItem<TPosition>;
+};
+
+export type MosaicDropEvent<TPosition = unknown> = MosaicMoveEvent<TPosition> & {
+  operation: MosaicOperation;
+};
+
+export type MosaicCompareDataItem = Parameters<typeof Array.prototype.sort>[0];
+
+export type MosaicContainerProps<TData extends MosaicDataItem = MosaicDataItem, TPosition = unknown> = Pick<
+  HTMLAttributes<HTMLDivElement>,
+  'className'
+> &
+  PropsWithChildren<{
+    id: string;
+
+    // TODO(wittjosiah): Don't expose externally.
+    debug?: boolean;
+
+    /**
+     * Default component used to render tiles.
+     */
+    Component?: MosaicTileComponent<TData, any>;
+
+    /**
+     * Length of transition when moving tiles in milliseconds.
+     *
+     * @default 200
+     */
+    transitionDuration?: number;
+
+    /**
+     * Adapter to transform properties while dragging (e.g., constraint axes).
+     * https://github.com/clauderic/dnd-kit/blob/master/packages/core/src/modifiers/types.ts
+     */
+    modifier?: (activeItem: MosaicDraggedItem, ...modifierArgs: Parameters<Modifier>) => ReturnType<Modifier>;
+
+    /**
+     * Property overrides for the default overlay.
+     */
+    getOverlayProps?: () => MosaicTileOverlayProps;
+
+    /**
+     * Style property overrides for the default overlay.
+     */
+    getOverlayStyle?: () => CSSProperties;
+
+    /**
+     * Called when a tile is dragged over the container.
+     * Returns true if the tile can be dropped.
+     */
+    onOver?: (event: MosaicMoveEvent<TPosition>) => MosaicOperation;
+
+    /**
+     * Called when a tile is dropped on the container.
+     */
+    onDrop?: (event: MosaicDropEvent<TPosition>) => void;
+
+    /**
+     * Used to sort items within the container.
+     */
+    compare?: MosaicCompareDataItem;
+  }>;
+
+export type MosaicContainerContextType = Omit<MosaicContainerProps<any>, 'children'>;
+
+export const MosaicContainerContext = createContext<MosaicContainerContextType | undefined>(undefined);
+
+/**
+ * Root Container that manages the layout of tiles.
+ */
+export const MosaicContainer = ({
+  children,
+  id,
+  debug,
+  Component,
+  transitionDuration = DEFAULT_TRANSITION,
+  modifier,
+  getOverlayProps,
+  getOverlayStyle,
+  onOver,
+  onDrop,
+  compare,
+}: MosaicContainerProps) => {
+  const mosaic = useMosaic();
+  const container = {
+    id,
+    debug,
+    Component,
+    transitionDuration,
+    modifier,
+    getOverlayProps,
+    getOverlayStyle,
+    onOver,
+    onDrop,
+    compare,
+  };
+
+  useEffect(() => {
+    mosaic.setContainer(container.id, container);
+    return () => {
+      // TODO(burdon): The overlay unregisters the container after the tile has re-rendered (removing it).
+      // mosaic.setContainer(container.id);
+    };
+  }, Object.values(container));
+
+  return <MosaicContainerContext.Provider value={container}>{children}</MosaicContainerContext.Provider>;
+};

package/src/mosaic/Debug.tsx

@@ -0,0 +1,24 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { type FC } from 'react';
+
+import { mx } from '@dxos/react-ui-theme';
+
+type Position = 'bottom-left' | 'bottom-right';
+
+export type DebugProps = { data: any; position?: Position };
+
+export const Debug: FC<DebugProps> = ({ data, position }) => (
+  <pre
+    className={mx(
+      'font-mono text-xs overflow-hidden m-2 p-1 z-[100]',
+      'bg-neutral-50 dark:bg-neutral-700 border border-neutral-300 rounded',
+      position === 'bottom-left' && 'fixed left-0 bottom-0',
+      position === 'bottom-right' && 'fixed right-0 bottom-0',
+    )}
+  >
+    {JSON.stringify(data, undefined, 1)}
+  </pre>
+);

package/src/mosaic/DefaultComponent.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { forwardRef } from 'react';
+
+import { Card } from '@dxos/react-ui';
+
+import { type MosaicTileComponent } from './Tile';
+import { type MosaicDataItem } from './types';
+import { Path } from './util';
+
+export const DefaultComponent: MosaicTileComponent<MosaicDataItem> = forwardRef(
+  ({ draggableStyle, draggableProps, item: { id }, path }, forwardRef) => {
+    return (
+      <Card.Root ref={forwardRef} style={draggableStyle}>
+        <Card.Header>
+          <Card.DragHandle {...draggableProps} />
+          <Card.Title title={Path.create(path, id)} classNames='truncate font-mono text-xs' />
+        </Card.Header>
+      </Card.Root>
+    );
+  },
+);
+
+DefaultComponent.displayName = 'DefaultComponent';

package/src/mosaic/DragOverlay.tsx

@@ -0,0 +1,136 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { DragOverlay } from '@dnd-kit/core';
+import React, { Component, type PropsWithChildren, useEffect, useRef, useState } from 'react';
+
+import { DensityProvider } from '@dxos/react-ui';
+
+import { type MosaicContainerProps } from './Container';
+import { DefaultComponent } from './DefaultComponent';
+import { type MosaicTileComponent } from './Tile';
+import { useMosaic } from './hooks';
+import { Path } from './util';
+
+export type MosaicDragOverlayProps = { delay?: number; debug?: boolean } & Omit<
+  React.ComponentProps<typeof DragOverlay>,
+  'children'
+>;
+
+/**
+ * Render the currently dragged item of the Mosaic.
+ */
+export const MosaicDragOverlay = ({ delay = 200, debug = false, ...overlayProps }: MosaicDragOverlayProps) => {
+  const { containers, operation, activeItem, overItem } = useMosaic();
+
+  // Get the overlay component from the over container, otherwise default to the original.
+  const [state, setState] = useState<{
+    container?: MosaicContainerProps<any>;
+    OverlayComponent?: MosaicTileComponent<any>;
+  }>({});
+
+  const timer = useRef<ReturnType<typeof setTimeout>>();
+
+  useEffect(() => {
+    if (activeItem) {
+      let container: MosaicContainerProps<any> | undefined;
+      let OverlayComponent: MosaicTileComponent<any> | undefined;
+      if (overItem?.path) {
+        container = containers[Path.first(overItem.path)];
+        OverlayComponent = container?.Component;
+      }
+
+      if (!OverlayComponent) {
+        container = containers[Path.first(activeItem.path)];
+        OverlayComponent = container?.Component ?? DefaultComponent;
+      }
+
+      // Prevent jitter when transitioning across containers.
+      clearTimeout(timer.current);
+      timer.current = setTimeout(() => setState({ container, OverlayComponent }), timer.current ? delay : 0);
+    } else {
+      setState({});
+    }
+  }, [activeItem, overItem]);
+
+  // Ensure the overlay is rendered as soon as there's an active item, then use local state.
+  const container = state.container ?? (activeItem && containers[Path.first(activeItem.path)]);
+  const OverlayComponent = state.OverlayComponent ?? container?.Component;
+  // Fallback is always to the active (origin) container.
+  const FallbackComponent = (activeItem && containers[Path.first(activeItem.path)])?.Component ?? DefaultComponent;
+
+  // NOTE: The DragOverlay wrapper element must always be mounted to support animations. Conditionally render the content.
+  return (
+    // TODO(burdon): Set custom animations (e.g., in/out/around).
+    <DragOverlay adjustScale={false} {...overlayProps} style={{ ...container?.getOverlayStyle?.() }}>
+      {/* TODO(burdon): Configure density via getOverlayProps. */}
+      {activeItem?.path && container && OverlayComponent && (
+        <DensityProvider density='fine'>
+          <OverlayErrorBoundary
+            fallback={
+              <FallbackComponent
+                {...container.getOverlayProps?.()}
+                item={activeItem.item}
+                path={activeItem.path}
+                operation={operation}
+                active='overlay'
+              />
+            }
+          >
+            <OverlayComponent
+              {...container.getOverlayProps?.()}
+              item={activeItem.item}
+              path={activeItem.path}
+              operation={operation}
+              active='overlay'
+            />
+            {debug && (
+              <div className='flex flex-wrap mt-1 p-1 bg-neutral-50 dark:bg-neutral-700 text-xs border rounded overflow-hidden gap-1'>
+                <span className='truncate'>
+                  <span className='text-neutral-400'>container </span>
+                  {container.id}
+                </span>
+                <span className='truncate'>
+                  <span className='text-neutral-400'>item </span>
+                  {activeItem.item.id.slice(0, 8)}
+                </span>
+              </div>
+            )}
+          </OverlayErrorBoundary>
+        </DensityProvider>
+      )}
+    </DragOverlay>
+  );
+};
+
+type OverlayErrorBoundaryProps = PropsWithChildren<{ fallback?: React.ReactNode }>;
+
+class OverlayErrorBoundary extends Component<OverlayErrorBoundaryProps> {
+  private readonly fallback: React.ReactNode;
+
+  constructor(props: OverlayErrorBoundaryProps) {
+    super(props);
+    this.fallback = props.fallback ?? <p>ERROR: ${String(this.state.error)}</p>;
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  override state = {
+    error: null,
+  };
+
+  override componentDidCatch(error: any, info: any) {
+    console.warn(error, info);
+  }
+
+  override render() {
+    if (this.state.error) {
+      return this.fallback;
+    }
+
+    return this.props.children;
+  }
+}

package/src/mosaic/Mosaic.ts

@@ -0,0 +1,84 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type FC } from 'react';
+
+import {
+  MosaicContainer,
+  type MosaicContainerProps as NaturalMosaicContainerProps,
+  type MosaicMoveEvent as NaturalMosaicMoveEvent,
+  type MosaicDropEvent as NaturalMosaicDropEvent,
+  type MosaicOperation as NaturalMosaicOperation,
+  type MosaicCompareDataItem as NaturalMosaicCompareDataItem,
+} from './Container';
+import { Debug, type DebugProps } from './Debug';
+import { DefaultComponent } from './DefaultComponent';
+import { MosaicDragOverlay, type MosaicDragOverlayProps } from './DragOverlay';
+import { MosaicRoot, type MosaicRootProps as NaturalMosaicRootProps } from './Root';
+import { MosaicSortableContext, type MosaicSortableProps as NaturalMosaicSortableProps } from './SortableContext';
+import {
+  DraggableTile,
+  DroppableTile,
+  SortableTile,
+  type MosaicTileProps as NaturalMosaicTileProps,
+  type MosaicTileComponent as NaturalMosaicTileComponent,
+  type MosaicActiveType as NaturalMosaicActiveType,
+} from './Tile';
+import { type MosaicDataItem } from './types';
+
+export const Mosaic = {
+  Root: MosaicRoot,
+  Container: MosaicContainer,
+  DragOverlay: MosaicDragOverlay,
+  SortableContext: MosaicSortableContext,
+  DraggableTile,
+  DroppableTile,
+  SortableTile,
+
+  // TODO(wittjosiah): Consider factoring out or using inline styles instead depending on DXOS UI theme/tailwind.
+  DefaultComponent,
+  // TODO(burdon): Don't export; move to util.
+  Debug,
+} as {
+  Root: FC<MosaicRootProps>;
+  Container: FC<MosaicContainerProps<any, any>>;
+  DragOverlay: FC<MosaicOverlayProps>;
+  SortableContext: FC<MosaicSortableProps>;
+  DraggableTile: FC<MosaicTileProps<any, any>>;
+  DroppableTile: FC<MosaicTileProps<any, any>>;
+  SortableTile: FC<MosaicTileProps<any, number>>;
+
+  DefaultComponent: MosaicTileComponent;
+  Debug: FC<MosaicDebugProps>;
+};
+
+export type MosaicRootProps = NaturalMosaicRootProps;
+
+export type MosaicContainerProps<
+  TData extends MosaicDataItem = MosaicDataItem,
+  TPosition = unknown,
+> = NaturalMosaicContainerProps<TData, TPosition>;
+
+export type MosaicOverlayProps = MosaicDragOverlayProps;
+
+export type MosaicSortableProps = NaturalMosaicSortableProps;
+
+export type MosaicTileProps<
+  TData extends MosaicDataItem = MosaicDataItem,
+  TPosition = unknown,
+> = NaturalMosaicTileProps<TData, TPosition>;
+
+export type MosaicTileComponent<
+  TData extends MosaicDataItem = MosaicDataItem,
+  TElement extends HTMLElement = HTMLDivElement,
+> = NaturalMosaicTileComponent<TData, TElement>;
+
+export type MosaicDebugProps = DebugProps;
+
+export type MosaicMoveEvent<TPosition = unknown> = NaturalMosaicMoveEvent<TPosition>;
+export type MosaicDropEvent<TPosition = unknown> = NaturalMosaicDropEvent<TPosition>;
+export type MosaicOperation = NaturalMosaicOperation;
+export type MosaicActiveType = NaturalMosaicActiveType;
+
+export type MosaicCompareDataItem = NaturalMosaicCompareDataItem;