@dxos/react-ui-mosaic 0.8.4-main.bc674ce → 0.8.4-main.c85a9c8dae

package/src/components/Mosaic/Placeholder.tsx

@@ -0,0 +1,133 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import {
+  DropIndicator as NaturalDropIndicator,
+  type DropIndicatorProps as NaturalDropIndicatorProps,
+} from '@atlaskit/pragmatic-drag-and-drop-react-drop-indicator/box';
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, { type PropsWithChildren, useLayoutEffect, useMemo, useRef } from 'react';
+
+import { type Axis, type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { useMosaicContainerContext } from './Container';
+import { useMosaicTileContext } from './Tile';
+import { type LocationType, type MosaicPlaceholderData, getSourceData } from './types';
+
+//
+// Placeholder
+//
+
+const MOSAIC_PLACEHOLDER_NAME = 'Mosaic.Placeholder';
+
+// Orientation: data-[mosaic-placeholder-orientation=vertical]
+const MOSAIC_PLACEHOLDER_ORIENTATION_ATTR = 'mosaic-placeholder-orientation';
+
+// State attribute: data-[mosaic-placeholder-state=active]
+const MOSAIC_PLACEHOLDER_STATE_ATTR = 'mosaic-placeholder-state';
+
+type MosaicPlaceholderProps<Location = LocationType> = ThemedClassName<
+  PropsWithChildren<{
+    asChild?: boolean;
+    orientation?: Axis;
+    location: Location;
+  }>
+>;
+
+const MosaicPlaceholder = <Location extends LocationType = LocationType>({
+  classNames,
+  children,
+  asChild,
+  orientation = 'vertical',
+  location,
+}: MosaicPlaceholderProps<Location>) => {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const Comp = asChild ? Slot : Primitive.div;
+  const {
+    id: containerId,
+    eventHandler,
+    scrolling,
+    activeLocation,
+    setActiveLocation,
+  } = useMosaicContainerContext(MOSAIC_PLACEHOLDER_NAME);
+  const data = useMemo<MosaicPlaceholderData<Location>>(
+    () =>
+      ({
+        type: 'placeholder',
+        containerId,
+        location,
+      }) satisfies MosaicPlaceholderData<Location>,
+    [containerId, location],
+  );
+
+  useLayoutEffect(() => {
+    const root = rootRef.current;
+    if (!root || scrolling) {
+      return;
+    }
+
+    return dropTargetForElements({
+      element: root,
+      getData: () => data,
+      canDrop: ({ source }) => {
+        const data = getSourceData(source);
+        return (data && eventHandler.canDrop?.({ source: data })) || false;
+      },
+      onDragEnter: () => {
+        setActiveLocation(data.location);
+      },
+      onDragLeave: () => {
+        setActiveLocation(undefined);
+      },
+      onDrop: () => {
+        setActiveLocation(undefined);
+      },
+    });
+  }, [rootRef, data, scrolling, setActiveLocation]);
+
+  return (
+    <Comp
+      {...{
+        [`data-${MOSAIC_PLACEHOLDER_ORIENTATION_ATTR}`]: orientation,
+        [`data-${MOSAIC_PLACEHOLDER_STATE_ATTR}`]: data.location === activeLocation ? 'active' : 'idle',
+      }}
+      role='none'
+      className={mx('relative', classNames)}
+      ref={rootRef}
+    >
+      {children}
+    </Comp>
+  );
+};
+
+MosaicPlaceholder.displayName = MOSAIC_PLACEHOLDER_NAME;
+
+//
+// DropIndicator
+// TODO(burdon): Support DropIndicator or Placeholder variants.
+//
+
+const DROP_INDICATOR_NAME = 'Mosaic.DropIndicator';
+
+type MosaicDropIndicatorProps = Omit<NaturalDropIndicatorProps, 'edge'>;
+
+const MosaicDropIndicator = (props: MosaicDropIndicatorProps) => {
+  const { state } = useMosaicTileContext(DROP_INDICATOR_NAME);
+  return state.type === 'target' && state.closestEdge ? (
+    <NaturalDropIndicator {...props} edge={state.closestEdge} />
+  ) : null;
+};
+
+MosaicDropIndicator.displayName = DROP_INDICATOR_NAME;
+
+//
+// Exports
+//
+
+export { MosaicPlaceholder, MosaicDropIndicator };
+
+export type { MosaicPlaceholderProps, MosaicDropIndicatorProps };

package/src/components/Mosaic/Root.tsx

@@ -0,0 +1,292 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
+import { type ElementDragPayload, monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import { type DragLocationHistory } from '@atlaskit/pragmatic-drag-and-drop/types';
+import { useComposedRefs } from '@radix-ui/react-compose-refs';
+import { createContext } from '@radix-ui/react-context';
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, { type PropsWithChildren, forwardRef, useCallback, useEffect, useRef, useState } from 'react';
+
+import { log } from '@dxos/log';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { type MosaicData, type MosaicEventHandler, type MosaicTileData } from './types';
+
+//
+// Context
+//
+
+type MosaicDraggingSource = {
+  data: MosaicTileData;
+  handler?: MosaicEventHandler;
+  container?: Element;
+};
+
+type MosaicDraggingTarget = {
+  data: MosaicData;
+  handler?: MosaicEventHandler;
+};
+
+type MosaicDraggingState = {
+  source: MosaicDraggingSource;
+  target?: MosaicDraggingTarget;
+};
+
+type MosaicRootContextValue = {
+  containers: Record<string, MosaicEventHandler>;
+  addContainer: (container: MosaicEventHandler) => void;
+  removeContainer: (id: string) => void;
+  dragging?: MosaicDraggingState;
+};
+
+const [MosaicRootContextProvider, useMosaicRootContext] = createContext<MosaicRootContextValue>('MosaicRoot');
+
+//
+// Root
+//
+
+const MOSAIC_ROOT_NAME = 'Mosaic.Root';
+
+// State attribute: [&:has(>_[data-mosaic-debug=true])]
+const MOSAIC_ROOT_DEBUG_ATTR = 'mosaic-debug';
+
+type MosaicRootProps = ThemedClassName<
+  PropsWithChildren<{
+    asChild?: boolean;
+    debug?: boolean;
+  }>
+>;
+
+const MosaicRoot = forwardRef<HTMLDivElement, MosaicRootProps>(
+  ({ classNames, children, asChild, debug }, forwardedRef) => {
+    const rootRef = useRef<HTMLDivElement>(null);
+    const composedRef = useComposedRefs<HTMLDivElement>(rootRef, forwardedRef);
+    const Comp = asChild ? Slot : Primitive.div;
+
+    const [handlers, setHandlers] = useState<Record<string, MosaicEventHandler>>({});
+    const [dragging, setDragging] = useState<MosaicDraggingState | undefined>();
+
+    const getSourceHandler = useCallback(
+      (source: ElementDragPayload): { data: MosaicTileData; handler?: MosaicEventHandler } => {
+        const data = source.data as MosaicTileData;
+        return { data, handler: handlers[data.containerId] };
+      },
+      [handlers],
+    );
+
+    const getTargetHandler = useCallback(
+      (location: DragLocationHistory): { data?: MosaicData; handler?: MosaicEventHandler } => {
+        for (const target of location.current.dropTargets) {
+          const data = target.data as MosaicData;
+          let containerId: string;
+          switch (data.type) {
+            case 'tile':
+            case 'placeholder':
+              containerId = data.containerId;
+              break;
+            case 'container':
+              containerId = data.id;
+              break;
+          }
+
+          const handler = handlers[containerId];
+          if (handler) {
+            return { data, handler };
+          }
+        }
+
+        return {};
+      },
+      [handlers],
+    );
+
+    useEffect(() => {
+      const handleChange = ({ source, location }: { source: ElementDragPayload; location: DragLocationHistory }) => {
+        const { data: sourceData } = getSourceHandler(source);
+        const { data: targetData, handler } = getTargetHandler(location);
+        setDragging((dragging) => {
+          dragging?.target?.handler?.onCancel?.();
+          return {
+            source: {
+              data: sourceData,
+              handler: handlers[sourceData.containerId],
+              // TOOD(burdon): Check id matches.
+              container: location.initial.dropTargets.find((target) => target.data.type === 'container')?.element,
+            },
+            target: targetData && {
+              data: targetData,
+              handler,
+            },
+          };
+        });
+      };
+
+      const handleCancel = () => {
+        setDragging((dragging) => {
+          requestAnimationFrame(() => {
+            dragging?.target?.handler?.onCancel?.();
+            dragging?.source?.container?.dispatchEvent(new CustomEvent('dnd:cancel', { bubbles: true }));
+          });
+
+          return undefined;
+        });
+      };
+
+      let noTargetTimeout: NodeJS.Timeout;
+
+      // Main controller.
+      return combine(
+        monitorForElements({
+          /**
+           * Dragging started within any container.
+           */
+          onDragStart: ({ source, location }) => {
+            log('Root.onDragStart', {
+              source: source.data,
+              location: location.current.dropTargets.map((target) => target.data),
+            });
+
+            handleChange({ source, location });
+          },
+
+          /**
+           * Dragging entered a new container.
+           */
+          onDropTargetChange: ({ source, location }) => {
+            clearTimeout(noTargetTimeout);
+            log('Root.onDropTargetChange', {
+              source: source.data,
+              location: location.current.dropTargets.map((target) => target.data),
+            });
+
+            // Stop dragging if there are no drop targets (or we are cancelling).
+            if (location.current.dropTargets.length === 0) {
+              noTargetTimeout = setTimeout(() => setDragging(undefined), 1_000);
+            } else {
+              handleChange({ source, location });
+            }
+          },
+
+          /**
+           * Dragging within any container.
+           */
+          onDrag: ({ source, location }) => {
+            const { data } = getSourceHandler(source);
+            const { handler } = getTargetHandler(location);
+            if (handler) {
+              const { clientX: x, clientY: y } = location.current.input;
+              handler.onDrag?.({ source: data, position: { x, y } });
+            }
+          },
+
+          /**
+           * Dragging ended.
+           */
+          onDrop: ({ source, location }) => {
+            log.info('Root.onDrop', {
+              source: source.data,
+              location: location.current.dropTargets.map((target) => target.data),
+            });
+
+            // Get the source container.
+            const { data: sourceData, handler: sourceHandler } = getSourceHandler(source);
+            if (!sourceHandler) {
+              log.warn('invalid source', {
+                source: sourceData,
+                handlers: Object.keys(handlers),
+              });
+              return;
+            }
+
+            // NOTE: When dragging is cancelled (e.g., user presses ESC) onDrop is only called after a subsequent event.
+            // NOTE: pDND blocks ESC event propagation while dragging.
+            // - ESC only flips internal state.
+            // - Completion happens on the next processed input event.
+            // - This avoids reentrancy and keeps pointer/keyboard behavior consistent.
+            // - We set dragging to undefined in onDropTargetChange after a delay if there are no drop targets.
+            try {
+              if (location.current.dropTargets.length === 0) {
+                log.info('cancelled');
+              } else {
+                // Get the target container.
+                const { data: targetData, handler: targetHandler } = getTargetHandler(location);
+                if (!targetHandler) {
+                  log.warn('invalid target', {
+                    source: sourceData,
+                    location,
+                    handlers: Object.keys(handlers),
+                  });
+                  return;
+                }
+
+                // TODO(burdon): Check object doesn't already exist in the collection.
+                if (sourceHandler === targetHandler) {
+                  targetHandler.onDrop?.({
+                    source: sourceData,
+                    target: targetData,
+                  });
+                } else {
+                  if (!sourceHandler.onTake) {
+                    log.warn('invalid source', { source: sourceData });
+                    return;
+                  }
+
+                  sourceHandler.onTake?.({ source: sourceData }, async (object) => {
+                    targetHandler.onDrop?.({
+                      source: { ...sourceData, data: object },
+                      target: targetData,
+                    });
+
+                    return true;
+                  });
+                }
+              }
+            } finally {
+              handleCancel();
+            }
+          },
+        }),
+      );
+    }, [handlers, getSourceHandler, getTargetHandler]);
+
+    return (
+      <MosaicRootContextProvider
+        containers={handlers}
+        addContainer={(container) =>
+          setHandlers((containers) => ({
+            ...containers,
+            [container.id]: container,
+          }))
+        }
+        removeContainer={(id) =>
+          setHandlers((containers) => {
+            delete containers[id];
+            return { ...containers };
+          })
+        }
+        dragging={dragging}
+      >
+        <Comp
+          className={mx('group', classNames)}
+          {...{
+            [`data-${MOSAIC_ROOT_DEBUG_ATTR}`]: debug,
+          }}
+          ref={composedRef}
+        >
+          {children}
+        </Comp>
+      </MosaicRootContextProvider>
+    );
+  },
+);
+
+MosaicRoot.displayName = MOSAIC_ROOT_NAME;
+
+export { MosaicRoot, useMosaicRootContext };
+
+export type { MosaicRootProps, MosaicDraggingState };

package/src/components/{Stack → Mosaic}/Stack.stories.tsx

@@ -8,14 +8,14 @@ import { useMemo } from 'react';
 
 import { Obj } from '@dxos/echo';
 import { faker } from '@dxos/random';
-import { Toolbar } from '@dxos/react-ui';
+import { ScrollArea, Toolbar } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
 import { useContainerDebug } from '../../hooks';
 import { DefaultStackTile, TestItem } from '../../testing';
-import { Mosaic } from '../Mosaic';
 
-import { Stack } from './Stack';
+import { Mosaic } from './Mosaic';
+import { MosaicStack } from './Stack';
 
 faker.seed(999);
 
@@ -30,15 +30,15 @@ const createTestItems = (n: number) =>
     }),
   );
 
-const meta: Meta<typeof Stack<Obj.Any>> = {
+const meta: Meta<typeof MosaicStack<Obj.Any>> = {
   title: 'ui/react-ui-mosaic/Stack',
-  component: Stack,
-  decorators: [withLayout({ layout: 'column' }), withTheme],
+  component: MosaicStack,
+  decorators: [withLayout({ layout: 'column' }), withTheme()],
   parameters: {
     layout: 'fullscreen',
   },
   args: {
-    axis: 'vertical',
+    orientation: 'vertical',
     getId: (item) => item.id,
     Tile: DefaultStackTile,
     // debug: true,
@@ -56,22 +56,24 @@ export const Default: Story = {
     const [DebugInfo, debugHandler] = useContainerDebug(props.debug);
     const [viewport, setViewport] = useState<HTMLElement | null>(null);
     return (
-      <Mosaic.Root debug={props.debug} classNames='bs-full grid grid-rows-[min-content_1fr_min-content]'>
-        <Toolbar.Root classNames='border-be border-separator'>
+      <Mosaic.Root debug={props.debug} classNames='h-full grid grid-rows-[min-content_1fr_min-content]'>
+        <Toolbar.Root classNames='border-b border-separator'>
           <div className='flex grow justify-center'>Items: {items.length}</div>
         </Toolbar.Root>
         <Mosaic.Container
           asChild
-          axis='vertical'
+          orientation='vertical'
           autoScroll={viewport}
           eventHandler={{ id: 'test', canDrop: () => true }}
           debug={debugHandler}
         >
-          <Mosaic.Viewport axis='vertical' padding viewportRef={setViewport}>
-            <Mosaic.Stack {...props} items={items} />
-          </Mosaic.Viewport>
+          <ScrollArea.Root orientation='vertical'>
+            <ScrollArea.Viewport classNames='p-2' ref={setViewport}>
+              <Mosaic.Stack {...props} items={items} />
+            </ScrollArea.Viewport>
+          </ScrollArea.Root>
         </Mosaic.Container>
-        <DebugInfo classNames='border-bs border-separator' />
+        <DebugInfo classNames='border-t border-separator' />
       </Mosaic.Root>
     );
   },
@@ -91,22 +93,24 @@ export const Virtual: Story = {
         </Toolbar.Root>
         <Mosaic.Container
           asChild
-          axis='vertical'
+          orientation='vertical'
           autoScroll={viewport}
           eventHandler={{ id: 'test', canDrop: () => true }}
           debug={debugHandler}
         >
-          <Mosaic.Viewport axis='vertical' padding viewportRef={setViewport}>
-            <Mosaic.VirtualStack
-              {...props}
-              items={items}
-              getScrollElement={() => viewport}
-              estimateSize={() => 40}
-              onChange={(virtualizer) => {
-                setInfo({ range: virtualizer.range });
-              }}
-            />
-          </Mosaic.Viewport>
+          <ScrollArea.Root orientation='vertical'>
+            <ScrollArea.Viewport classNames='p-2' ref={setViewport}>
+              <Mosaic.VirtualStack
+                {...props}
+                items={items}
+                getScrollElement={() => viewport}
+                estimateSize={() => 40}
+                onChange={(virtualizer) => {
+                  setInfo({ range: virtualizer.range });
+                }}
+              />
+            </ScrollArea.Viewport>
+          </ScrollArea.Root>
         </Mosaic.Container>
         <DebugInfo />
       </Mosaic.Root>