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

package/src/components/Mosaic/Stack.tsx

@@ -0,0 +1,246 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type ReactVirtualizerOptions, useVirtualizer } from '@tanstack/react-virtual';
+import React, { type FC, Fragment, type ReactElement, type Ref, forwardRef } from 'react';
+
+import { invariant } from '@dxos/invariant';
+import { type Axis, type ComposableProps } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { useVisibleItems } from '../../hooks';
+
+import { useMosaicContainerContext } from './Container';
+import { MosaicPlaceholder, type MosaicPlaceholderProps } from './Placeholder';
+import { styles } from './styles';
+import { type MosaicTileProps } from './Tile';
+import { type GetId } from './types';
+
+//
+// Mosaic Drag-and-drop
+//
+// Drop targets:
+// - Placeholders exist to allow gaps but prevent deadspace when dragging within a container.
+// - When dragging over a Tile, the placeholder next to the closest edge is activated.
+// - Placeholders expand when active; event handlers are disabled while the container is scrolling.
+//
+// [Container]
+// - [Placeholder 0.5]
+// - [Tile        1  ]
+// - [Placeholder 1.5]
+// - [Tile        2  ]
+// - [Placeholder 2.5]
+// - [Tile        3  ]
+// - [Placeholder 3.5]
+//
+// Implementation Notes
+// - We use [Radix composition](https://www.radix-ui.com/primitives/docs/guides/composition) to factor out composible aspects (e.g., Focus, Mosaic, etc.)
+// - NOTE: Use Slottable only if needed to disambiguate; otherwise a suspected Radix bug causes compositional problems.
+
+const MOSAIC_STACK_NAME = 'MosaicStack';
+
+type MosaicStackTileComponent<TData = any> = FC<MosaicTileProps<TData>>;
+
+type MosaicStackProps<TData = any> = ComposableProps<
+  {
+    Tile: MosaicStackTileComponent<TData>;
+    getId: GetId<TData>;
+    role?: string;
+    orientation?: Axis;
+    items?: readonly TData[];
+  } & Pick<MosaicTileProps<TData>, 'draggable' | 'debug'>
+>;
+
+/**
+ * Linear layout of Mosaic tiles.
+ * NOTE: This is a low-level component and should be wrapped by a scrollable container.
+ */
+const MosaicStackInner = forwardRef<HTMLDivElement, MosaicStackProps>(
+  (
+    {
+      classNames,
+      className,
+      role = 'list',
+      orientation: orientationProp = 'vertical',
+      draggable = true,
+      items,
+      getId,
+      Tile,
+      debug,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    invariant(Tile);
+    const { id, orientation = orientationProp, dragging } = useMosaicContainerContext(MOSAIC_STACK_NAME);
+    const visibleItems = useVisibleItems({ id, items, dragging: dragging?.source.data, getId });
+    invariant(orientation === 'vertical' || orientation === 'horizontal', `Invalid orientation: ${orientation}`);
+
+    return (
+      <div
+        {...props}
+        role={role}
+        className={mx(
+          'flex',
+          orientation === 'horizontal' && 'h-full [&>*]:shrink-0',
+          orientation === 'vertical' && 'flex-col',
+          classNames,
+          className,
+        )}
+        ref={forwardedRef}
+      >
+        <InternalPlaceholder orientation={orientation} location={0.5} />
+        {visibleItems?.map((item, index) => (
+          <Fragment key={getId(item)}>
+            <Tile id={getId(item)} data={item} location={index + 1} draggable={draggable} debug={debug} />
+            <InternalPlaceholder orientation={orientation} location={index + 1.5} />
+          </Fragment>
+        ))}
+      </div>
+    );
+  },
+);
+
+MosaicStackInner.displayName = MOSAIC_STACK_NAME;
+
+const MosaicStack = MosaicStackInner as <TData = any>(
+  props: MosaicStackProps<TData> & { ref?: Ref<HTMLDivElement> },
+) => ReactElement;
+
+//
+// VirtualStack
+//
+
+const MOSAIC_VIRTUAL_STACK_NAME = 'MosaicVirtualStack';
+
+type MosaicVirtualStackProps<TData = any> = MosaicStackProps<TData> &
+  Pick<
+    ReactVirtualizerOptions<HTMLElement, HTMLDivElement>,
+    'estimateSize' | 'getScrollElement' | 'overscan' | 'onChange'
+  >;
+
+const MosaicVirtualStackInner = forwardRef<HTMLDivElement, MosaicVirtualStackProps>(
+  (
+    {
+      classNames,
+      className,
+      role = 'list',
+      orientation = 'vertical',
+      items,
+      getId,
+      Tile,
+      estimateSize,
+      getScrollElement,
+      overscan = 8,
+      onChange,
+      debug,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    invariant(Tile);
+    const { id, dragging } = useMosaicContainerContext(MOSAIC_VIRTUAL_STACK_NAME);
+    const visibleItems = useVisibleItems({ id, items, dragging: dragging?.source.data, getId });
+    const virtualizer = useVirtualizer({
+      count: visibleItems.length * 2 + 1,
+      estimateSize,
+      getScrollElement,
+      overscan,
+      onChange,
+    });
+
+    const virtualItems = virtualizer.getVirtualItems();
+
+    return (
+      <div
+        {...props}
+        role={role}
+        className={mx(
+          'flex',
+          orientation === 'horizontal' && 'h-full [&>*]:shrink-0',
+          orientation === 'vertical' && 'flex-col',
+          classNames,
+          className,
+        )}
+        style={{
+          position: 'relative',
+          ...(orientation === 'vertical'
+            ? {
+                width: '100%',
+                height: virtualizer.getTotalSize(),
+              }
+            : {
+                width: virtualizer.getTotalSize(),
+                height: '100%',
+              }),
+        }}
+        ref={forwardedRef}
+      >
+        {virtualItems.map((virtualItem) => {
+          const data = visibleItems![Math.floor(virtualItem.index / 2)];
+          return (
+            <div
+              key={virtualItem.key}
+              data-index={virtualItem.index}
+              style={{
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                ...(orientation === 'vertical'
+                  ? {
+                      width: '100%',
+                      transform: `translateY(${virtualItem.start}px)`,
+                    }
+                  : {
+                      height: '100%',
+                      transform: `translateX(${virtualItem.start}px)`,
+                    }),
+              }}
+              ref={virtualizer.measureElement}
+            >
+              {virtualItem.index % 2 === 0 ? (
+                <InternalPlaceholder orientation={orientation} location={Math.floor(virtualItem.index / 2) + 0.5} />
+              ) : (
+                <Tile id={getId(data)} data={data} location={Math.floor(virtualItem.index / 2) + 1} debug={debug} />
+              )}
+            </div>
+          );
+        })}
+      </div>
+    );
+  },
+);
+
+MosaicVirtualStackInner.displayName = MOSAIC_VIRTUAL_STACK_NAME;
+
+const MosaicVirtualStack = MosaicVirtualStackInner as <TData = any>(
+  props: MosaicVirtualStackProps<TData> & { ref?: Ref<HTMLDivElement> },
+) => ReactElement;
+
+//
+// InternalPlaceholder
+//
+
+const InternalPlaceholder = (props: MosaicPlaceholderProps<number>) => {
+  return (
+    <MosaicPlaceholder {...props} classNames={styles.placeholder.root}>
+      <div
+        className={mx(
+          'flex h-full bg-base-surface border border-dashed border-separator rounded-xs',
+          styles.placeholder.content,
+        )}
+      />
+    </MosaicPlaceholder>
+  );
+};
+
+InternalPlaceholder.displayName = 'InternalPlaceholder';
+
+//
+// Exports
+//
+
+export { MosaicStack, MosaicVirtualStack };
+
+export type { MosaicStackTileComponent, MosaicStackProps, MosaicVirtualStackProps };

package/src/components/Mosaic/Tile.tsx

@@ -0,0 +1,242 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
+import {
+  type ElementDragPayload,
+  draggable,
+  dropTargetForElements,
+} from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import { preserveOffsetOnSource } from '@atlaskit/pragmatic-drag-and-drop/element/preserve-offset-on-source';
+import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
+import { type DropTargetRecord } from '@atlaskit/pragmatic-drag-and-drop/types';
+import {
+  type Edge,
+  attachClosestEdge,
+  extractClosestEdge,
+} from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
+import { composeRefs } 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 CSSProperties,
+  type PropsWithChildren,
+  forwardRef,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import { type ComposableProps } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { useMosaicContainerContext } from './Container';
+import { type LocationType, type MosaicTileData, getSourceData } from './types';
+
+//
+// Tile
+//
+
+const MOSAIC_TILE_NAME = 'Mosaic.Tile';
+
+type MosaicTileState =
+  | { type: 'idle' }
+  | { type: 'preview'; container: HTMLElement; rect: DOMRect }
+  | { type: 'dragging' }
+  | { type: 'target'; closestEdge: Edge | null };
+
+type MosaicTileContextValue = {
+  state: MosaicTileState;
+};
+
+const [MosaicTileContextProvider, useMosaicTileContext] = createContext<MosaicTileContextValue>('MosaicTile');
+
+// State attribute: data-[mosaic-tile-state=dragging]
+const MOSAIC_TILE_STATE_ATTR = 'mosaic-tile-state';
+
+type MosaicTileProps<TData = any, TLocation = LocationType> = ComposableProps<
+  PropsWithChildren<{
+    asChild?: boolean;
+    dragHandle?: HTMLElement | null;
+    allowedEdges?: Edge[];
+    id: string;
+    data: TData;
+    location: TLocation;
+    draggable?: boolean; // TODO(burdon): Not currently implemented.
+    debug?: boolean;
+  }>
+>;
+
+const MosaicTile = forwardRef<HTMLDivElement, MosaicTileProps>(
+  (
+    {
+      classNames,
+      className,
+      children,
+      asChild,
+      dragHandle,
+      allowedEdges: allowedEdgesProp,
+      location,
+      id,
+      data: dataProp,
+      debug: _,
+      ...props
+    }: MosaicTileProps,
+    forwardedRef,
+  ) => {
+    const rootRef = useRef<HTMLDivElement>(null);
+    const composedRef = composeRefs<HTMLDivElement>(rootRef, forwardedRef);
+    const Comp = asChild ? Slot : Primitive.div;
+
+    // State.
+    const {
+      id: containerId,
+      eventHandler,
+      orientation,
+      scrolling,
+      setActiveLocation,
+    } = useMosaicContainerContext(MOSAIC_TILE_NAME);
+    const [state, setState] = useState<MosaicTileState>({ type: 'idle' });
+
+    const allowedEdges = useMemo<Edge[]>(
+      () => allowedEdgesProp || (orientation === 'vertical' ? ['top', 'bottom'] : ['left', 'right']),
+      [allowedEdgesProp, orientation],
+    );
+
+    const data = useMemo<MosaicTileData>(
+      () =>
+        ({
+          type: 'tile',
+          id,
+          containerId,
+          data: dataProp,
+          location,
+        }) satisfies MosaicTileData,
+      [containerId, location, dataProp],
+    );
+
+    useLayoutEffect(() => {
+      const root = rootRef.current;
+      if (!root || !containerId || scrolling) {
+        return;
+      }
+
+      const handleChange = ({ self, source }: { self: DropTargetRecord; source: ElementDragPayload }) => {
+        if (source.data.id !== dataProp.id) {
+          const closestEdge = extractClosestEdge(self.data);
+          const location = data.location + (closestEdge === 'top' || closestEdge === 'left' ? -0.5 : 0.5);
+          setActiveLocation(location);
+          setState({ type: 'target', closestEdge });
+        }
+      };
+
+      return combine(
+        // Source.
+        draggable({
+          element: root,
+          dragHandle: dragHandle && state.type !== 'preview' ? dragHandle : undefined,
+          canDrag: () => true,
+          getInitialData: () => data,
+          onGenerateDragPreview: ({ location, nativeSetDragImage }) => {
+            setCustomNativeDragPreview({
+              nativeSetDragImage,
+              getOffset: preserveOffsetOnSource({
+                element: root,
+                input: location.current.input,
+              }),
+              render: ({ container }) => {
+                data.bounds = root.getBoundingClientRect();
+                setState({
+                  type: 'preview',
+                  container,
+                  rect: root.getBoundingClientRect(),
+                });
+                return () => setState({ type: 'dragging' });
+              },
+            });
+          },
+
+          onDragStart: () => {
+            setState({ type: 'dragging' });
+          },
+          onDrop: () => {
+            setState({ type: 'idle' });
+          },
+        }),
+
+        // Target.
+        dropTargetForElements({
+          element: root,
+          getData: ({ input, element }) => attachClosestEdge(data, { input, element, allowedEdges }),
+          canDrop: ({ source }) => {
+            const data = getSourceData(source);
+            return (data && eventHandler.canDrop?.({ source: data })) || false;
+          },
+          onDragEnter: ({ self, source }) => {
+            handleChange({ self, source });
+          },
+          onDragLeave: () => {
+            setState({ type: 'idle' });
+            setActiveLocation(undefined);
+          },
+          onDrag: ({ self, source }) => {
+            handleChange({ self, source });
+          },
+          onDrop: () => {
+            setState({ type: 'idle' });
+            setActiveLocation(undefined);
+          },
+        }),
+      );
+    }, [rootRef, dragHandle, eventHandler, data, scrolling, allowedEdges, setActiveLocation]);
+
+    // NOTE: Ensure no gaps between cells (prevent drop indicators flickering).
+    // NOTE: Ensure padding doesn't change position of cursor when dragging (no margins).
+    return (
+      <MosaicTileContextProvider state={state}>
+        <Comp
+          {...props}
+          {...{
+            [`data-${MOSAIC_TILE_STATE_ATTR}`]: state.type,
+          }}
+          role='listitem'
+          className={mx('relative', className, classNames)}
+          ref={composedRef}
+        >
+          {children}
+        </Comp>
+
+        {state.type === 'preview' &&
+          createPortal(
+            <Comp
+              {...{
+                // NOTE: Use to control appearance while dragging.
+                [`data-${MOSAIC_TILE_STATE_ATTR}`]: state.type,
+              }}
+              // TODO(burdon): Configure drop animation.
+              className={mx('relative', className, classNames)}
+              style={
+                {
+                  width: `${state.rect.width}px`,
+                  height: `${state.rect.height}px`,
+                } as CSSProperties
+              }
+            >
+              {children}
+            </Comp>,
+            state.container,
+          )}
+      </MosaicTileContextProvider>
+    );
+  },
+);
+
+MosaicTile.displayName = MOSAIC_TILE_NAME;
+
+export { MosaicTile, useMosaicTileContext };
+
+export type { MosaicTileProps, MosaicTileState };

package/src/components/Mosaic/extension.ts

@@ -123,7 +123,7 @@ const dropField = StateField.define<DecorationSet>({
               toDOM() {
                 const dom = document.createElement('span');
                 dom.className = 'cm-drop-cursor';
-                dom.style.borderLeft = '2px solid var(--dx-accentSurface)';
+                dom.style.borderLeft = '2px solid var(--color-accent-surface)';
                 dom.style.display = 'inline-block';
                 dom.style.height = '1em';
                 dom.style.verticalAlign = 'middle';

package/src/components/Mosaic/styles.ts

@@ -11,10 +11,11 @@ export const styles = {
       'group-data-[mosaic-debug="true"]:opacity-100',
       'group-data-[mosaic-debug="true"]:bg-orange-500',
       'data-[mosaic-placeholder-state=active]:opacity-100',
-      'data-[mosaic-placeholder-axis=vertical]:plb-1',
-      'data-[mosaic-placeholder-axis=vertical]:data-[mosaic-placeholder-state=active]:plb-2.5',
-      'data-[mosaic-placeholder-axis=horizontal]:pli-1',
-      'data-[mosaic-placeholder-axis=horizontal]:data-[mosaic-placeholder-state=active]:pli-2.5',
+      'data-[mosaic-placeholder-orientation=vertical]:snap-start', // TODO(burdon): Option.
+      'data-[mosaic-placeholder-orientation=vertical]:py-1',
+      'data-[mosaic-placeholder-orientation=vertical]:data-[mosaic-placeholder-state=active]:py-2.5',
+      'data-[mosaic-placeholder-orientation=horizontal]:px-1',
+      'data-[mosaic-placeholder-orientation=horizontal]:data-[mosaic-placeholder-state=active]:px-2.5',
     ],
     content: [
       'transition-all duration-0',
@@ -22,10 +23,10 @@ export const styles = {
       // TODO(burdon): Flickers when start to drag since source is removed and then the placeholder shows up.
       //  - Use absolute positioning?
       // 'group-data-[mosaic-placeholder-state=active]:duration-200',
-      'group-data-[mosaic-placeholder-axis=vertical]:bs-0',
-      'group-data-[mosaic-placeholder-axis=horizontal]:is-0',
-      'group-data-[mosaic-placeholder-axis=vertical]:group-data-[mosaic-placeholder-state=active]:bs-[var(--mosaic-placeholder-height)]',
-      'group-data-[mosaic-placeholder-axis=horizontal]:group-data-[mosaic-placeholder-state=active]:is-[var(--mosaic-placeholder-width)]',
+      'group-data-[mosaic-placeholder-orientation=vertical]:h-0',
+      'group-data-[mosaic-placeholder-orientation=vertical]:group-data-[mosaic-placeholder-state=active]:h-[var(--mosaic-placeholder-height)]',
+      'group-data-[mosaic-placeholder-orientation=horizontal]:w-0',
+      'group-data-[mosaic-placeholder-orientation=horizontal]:group-data-[mosaic-placeholder-state=active]:w-[var(--mosaic-placeholder-width)]',
     ],
   },
 } satisfies Record<string, Record<string, ClassNameValue>>;

package/src/components/Mosaic/types.ts

@@ -2,12 +2,24 @@
 // Copyright 2025 DXOS.org
 //
 
-// These are not exported from the pragmatic-drag-and-drop-auto-scroll package.
-export type Axis = 'vertical' | 'horizontal';
-export type AllowedAxis = Axis | 'all';
+import { type ElementDragPayload } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
 
 export type GetId<TData = any> = (data: TData) => string;
 
+/**
+ * NOTE: Must implement value equivalence.
+ */
+export type LocationType = string | number;
+
+/**
+ * Get the source data from the drag payload.
+ */
+export const getSourceData = <TData = any, TLocation = any>(
+  source: ElementDragPayload,
+): MosaicTileData<TData, TLocation> | null => {
+  return source.data.type === 'tile' ? (source.data as MosaicTileData<TData, TLocation>) : null;
+};
+
 /**
  * Draggable item.
  * Tiles may contain arbitrary data (which may not be an ECHO object; e.g., search result).

package/src/components/index.ts

@@ -2,9 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './Card';
+export * from './Board';
 export * from './Focus';
-export * from './Image';
-export * from './Layout';
 export * from './Mosaic';
-export * from './Stack';

package/src/hooks/index.ts

@@ -3,5 +3,6 @@
 //
 
 export * from './useContainerDebug';
+export * from './useDefaultColumnEventHandler';
 export * from './useEventHandlerAdapter';
 export * from './useVisibleItems';

package/src/hooks/useContainerDebug.tsx

@@ -31,8 +31,10 @@ export const useContainerDebug = (debug?: boolean): UseContainerDebug => {
   }, [debug, debugRef]);
 };
 
+const CONTAINER_INFO_NAME = 'ContainerInfo';
+
 const ContainerInfo = forwardRef<HTMLDivElement, ThemedClassName>(({ classNames }, forwardedRef) => {
-  const { id, state, activeLocation, scrolling } = useMosaicContainer(ContainerInfo.displayName!);
+  const { id, state, activeLocation, scrolling } = useMosaicContainer(CONTAINER_INFO_NAME);
   const counter = useRef(0);
   return (
     <Json
@@ -43,4 +45,4 @@ const ContainerInfo = forwardRef<HTMLDivElement, ThemedClassName>(({ classNames
   );
 });
 
-ContainerInfo.displayName = 'ContainerInfo';
+ContainerInfo.displayName = CONTAINER_INFO_NAME;

package/src/hooks/useDefaultColumnEventHandler.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Obj } from '@dxos/echo';
+
+import { type GetId, type MosaicEventHandler } from '../components';
+
+import { useEventHandlerAdapter } from './useEventHandlerAdapter';
+
+/**
+ * Minimal model shape needed to build the default column handler.
+ */
+export type DefaultColumnEventHandlerModel<TColumn = unknown> = {
+  getColumnId: GetId<TColumn>;
+  isColumn: (obj: unknown) => obj is TColumn;
+};
+
+/**
+ * Returns the default column drag/drop handler (no persistence).
+ * Use this when no custom eventHandler is passed to Board.Content.
+ */
+export const useDefaultColumnEventHandler = <TColumn extends Obj.Unknown = Obj.Unknown>(
+  id: string,
+  model: DefaultColumnEventHandlerModel<TColumn>,
+  items: TColumn[],
+): MosaicEventHandler<TColumn> =>
+  useEventHandlerAdapter<TColumn, TColumn>({
+    id,
+    items,
+    getId: model.getColumnId,
+    get: (data) => data,
+    make: (object) => object,
+    canDrop: ({ source }) => model.isColumn(source.data),
+  });

package/src/hooks/useEventHandlerAdapter.ts

@@ -10,7 +10,10 @@ import { arrayMove } from '@dxos/util';
 
 import { type GetId, type MosaicEventHandler } from '../components';
 
-export type UseEventHandlerProps<TItem = any, TObject = any> = Pick<MosaicEventHandler<TItem>, 'id' | 'canDrop'> & {
+export type UseEventHandlerProps<TItem = any, TObject extends Obj.Unknown = Obj.Unknown> = Pick<
+  MosaicEventHandler<TItem>,
+  'id' | 'canDrop'
+> & {
   /**
    * The items to manage.
    */
@@ -72,17 +75,23 @@ export const useEventHandlerAdapter = <TItem = any, TObject extends Obj.Unknown
         void cb(source.data);
       },
       onDrop: ({ source, target }) => {
-        const to = target?.type === 'tile' || target?.type === 'placeholder' ? target.location : -1;
-        log.info('onDrop', { source, target, to });
+        log.info('onDrop', { source, target });
 
         const mutate = (items: TItem[]) => {
+          const to =
+            target?.type === 'tile' || target?.type === 'placeholder'
+              ? target.location
+              : target?.type === 'container'
+                ? items.length
+                : -1;
           const from = items.findIndex((item) => getId(item) === source.id);
-          if (to !== -1) {
+          const insertIndex = typeof to === 'number' && to >= 0 ? Math.floor(to) : -1;
+          if (insertIndex !== -1) {
             if (from !== -1) {
-              arrayMove(items, from, to);
+              arrayMove(items, from, insertIndex);
             } else {
               // TODO(burdon): This should be the responsibility of the source container.
-              items.splice(to, 0, make(get(source.data)));
+              items.splice(insertIndex, 0, make(get(source.data)));
             }
           }
         };