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

package/src/hooks/useVisibleItems.ts

@@ -11,7 +11,7 @@ export type UseVisibleItemsProps<TItem = any> = {
   id: string;
 
   /** Current items. */
-  items?: TItem[];
+  items?: readonly TItem[] | TItem[];
 
   /** Currently dragging item. */
   dragging: MosaicTileData<TItem> | undefined;
@@ -23,7 +23,12 @@ export type UseVisibleItemsProps<TItem = any> = {
 /**
  * Returns items with the dragging item removed.
  */
-export const useVisibleItems = <TItem = any>({ id, items, dragging, getId }: UseVisibleItemsProps<TItem>): TItem[] => {
+export const useVisibleItems = <TItem = any>({
+  id,
+  items,
+  dragging,
+  getId,
+}: UseVisibleItemsProps<TItem>): readonly TItem[] | TItem[] => {
   const visibleItems = useMemo(() => {
     if (!items || !dragging || id !== dragging.containerId) {
       return items ?? [];

package/src/playwright/board-manager.ts

@@ -0,0 +1,154 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Locator, Page } from '@playwright/test';
+
+export class BoardManager {
+  private readonly _page: Page;
+
+  constructor(readonly locator: Locator) {
+    this._page = locator.page();
+  }
+
+  columns(): Locator {
+    return this.locator.getByTestId('board-column');
+  }
+
+  column(index: number): ColumnManager {
+    return new ColumnManager(this.locator.getByTestId('board-column').nth(index));
+  }
+}
+
+export class ColumnManager {
+  private readonly _page: Page;
+
+  constructor(readonly locator: Locator) {
+    this._page = locator.page();
+  }
+
+  items(): Locator {
+    return this.locator.getByTestId('board-item');
+  }
+
+  item(index: number): ItemManager {
+    return new ItemManager(this.locator.getByTestId('board-item').nth(index));
+  }
+
+  async addItem(): Promise<void> {
+    await this.locator.getByTestId('board-column-add-item').click();
+  }
+
+  header(): Locator {
+    return this.locator.getByTestId('board-column-header');
+  }
+
+  title(): Locator {
+    return this.header().getByRole('heading');
+  }
+
+  async dragTo(target: Locator, offset = { x: 0, y: 0 }): Promise<void> {
+    const handle = this.header().getByTestId('card-drag-handle');
+    const handleBox = await handle.boundingBox();
+    if (!handleBox) {
+      return;
+    }
+
+    await handle.hover();
+    await this._page.mouse.down();
+    // Small initial movement to trigger the native drag start.
+    await this._page.mouse.move(handleBox.x + handleBox.width / 2 + 1, handleBox.y + handleBox.height / 2, {
+      steps: 1,
+    });
+    // Allow the drag monitor to register and the DOM to settle
+    // (the dragged column is removed from visible items, shifting remaining columns).
+    await this._page.waitForTimeout(200);
+    const box = await target.boundingBox();
+    if (box) {
+      await this._page.mouse.move(offset.x + box.x + box.width / 2, offset.y + box.y + box.height / 2, { steps: 4 });
+      // Allow the drop target to process the hover before releasing.
+      await this._page.waitForTimeout(100);
+      await this._page.mouse.up();
+    }
+  }
+}
+
+export class ItemManager {
+  private readonly _page: Page;
+
+  constructor(readonly locator: Locator) {
+    this._page = locator.page();
+  }
+
+  title(): Locator {
+    return this.locator.getByRole('heading').first();
+  }
+
+  async dragTo(target: Locator, offset = { x: 0, y: 0 }): Promise<void> {
+    const handle = this.locator.getByTestId('card-drag-handle');
+    const box = await target.boundingBox();
+    if (box) {
+      await handle.hover();
+      await this._page.mouse.down();
+      // Allow the drag monitor to register the grab before moving.
+      await this._page.waitForTimeout(100);
+      await this._page.mouse.move(offset.x + box.x + box.width / 2, offset.y + box.y + box.height / 2, { steps: 4 });
+      // Allow the drop target to process the hover before releasing.
+      await this._page.waitForTimeout(100);
+      await this._page.mouse.up();
+    }
+  }
+
+  /**
+   * Drag this item to a column's scroll bottom, hold to trigger auto-scroll,
+   * then wait for the drop target to become visible and drop on it.
+   *
+   * @param holdTarget - The footer element; mouse is held ~20px above it to trigger auto-scroll.
+   * @param dropTarget - The element to drop on once it scrolls into view.
+   * @param dropOffset - Offset from the drop target center.
+   */
+  async dragToEndWithAutoScroll(holdTarget: Locator, dropTarget: Locator, dropOffset = { x: 0, y: 0 }): Promise<void> {
+    const handle = this.locator.getByTestId('card-drag-handle');
+    const holdBox = await holdTarget.boundingBox();
+    if (!holdBox) {
+      return;
+    }
+
+    // The hold position is ~20px above the footer to trigger pragmatic auto-scroll.
+    const holdX = holdBox.x + holdBox.width / 2;
+    const holdY = holdBox.y - 20;
+
+    await handle.hover();
+    await this._page.mouse.down();
+    // Allow the drag monitor to register the grab before moving.
+    await this._page.waitForTimeout(100);
+
+    // Move to hold position above the footer to trigger auto-scroll.
+    await this._page.mouse.move(holdX, holdY, { steps: 4 });
+
+    // Hold and nudge mouse periodically to keep auto-scroll active until drop target is visible.
+    for (let i = 0; i < 40; i++) {
+      // Wait between nudges to give auto-scroll time to advance.
+      await this._page.waitForTimeout(200);
+      // Small nudge to keep drag events firing (auto-scroll stalls without movement).
+      await this._page.mouse.move(holdX + (i % 2), holdY, { steps: 1 });
+
+      const dropBox = await dropTarget.boundingBox();
+      if (dropBox && dropBox.y + dropBox.height < holdY) {
+        // Drop target has scrolled into view, move to it and drop.
+        await this._page.mouse.move(
+          dropOffset.x + dropBox.x + dropBox.width / 2,
+          dropOffset.y + dropBox.y + dropBox.height / 2,
+          { steps: 4 },
+        );
+        // Allow the drop target to process the hover before releasing.
+        await this._page.waitForTimeout(100);
+        await this._page.mouse.up();
+        return;
+      }
+    }
+
+    // Fallback: drop wherever we are.
+    await this._page.mouse.up();
+  }
+}

package/src/playwright/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Playwright-only entry point for e2e helpers (e.g. BoardManager).
+ * Kept separate from the ./testing entry point so that Node can load this
+ * without pulling in the testing bundle and its browser-only dependencies
+ * (e.g. @atlaskit/pragmatic-drag-and-drop). Use ./playwright from Playwright
+ * specs; use ./testing for in-browser test helpers.
+ */
+
+export * from './board-manager';

package/src/playwright/playwright.config.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { defineConfig } from '@playwright/test';
+
+import { e2ePreset } from '@dxos/test-utils/playwright';
+
+export default defineConfig({
+  ...e2ePreset(import.meta.dirname),
+  // TODO(wittjosiah): Avoid hard-coding ports.
+  webServer: {
+    command: 'pnpm storybook dev --ci --quiet --port=9008 --config-dir=.storybook',
+    port: 9008,
+    reuseExistingServer: false,
+  },
+});

package/src/playwright/smoke.spec.ts

@@ -0,0 +1,138 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Page, expect, test } from '@playwright/test';
+
+import { setupPage, storybookUrl } from '@dxos/test-utils/playwright';
+
+import { BoardManager } from './board-manager';
+
+const PORT = 9008;
+const STORY_URL = storybookUrl('ui-react-ui-mosaic-board--spec', PORT);
+
+test.describe('Board', () => {
+  let page: Page;
+  let board: BoardManager;
+
+  test.beforeEach(async ({ browser }) => {
+    ({ page } = await setupPage(browser, { url: STORY_URL }));
+    await page.getByTestId('board-column').first().waitFor({ state: 'visible' });
+    board = new BoardManager(page.locator('body'));
+  });
+
+  test.afterEach(async () => {
+    await page.close();
+  });
+
+  test('rearrange columns', async () => {
+    const col0Label = await board.column(0).title().textContent();
+    const col1Label = await board.column(1).title().textContent();
+
+    // Drag column 0 to the right of column 1.
+    await board.column(0).dragTo(board.column(1).header());
+
+    await expect(board.column(0).title()).toHaveText(col1Label!);
+    await expect(board.column(1).title()).toHaveText(col0Label!);
+  });
+
+  test('rearrange within column', async () => {
+    // Pick whichever column has more items for a reliable test.
+    const col0Count = await board.column(0).items().count();
+    const col1Count = await board.column(1).items().count();
+    const colIndex = col0Count >= col1Count ? 0 : 1;
+    const column = board.column(colIndex);
+    const countBefore = Math.max(col0Count, col1Count);
+    expect(countBefore).toBeGreaterThanOrEqual(2);
+
+    const firstLabel = await column.item(0).title().textContent();
+    const secondLabel = await column.item(1).title().textContent();
+
+    // Drag first item below the second item.
+    await column.item(0).dragTo(column.item(1).locator, { x: 0, y: 20 });
+
+    // Item count should stay the same.
+    await expect(column.items()).toHaveCount(countBefore);
+
+    // The first item should now be what was previously the second item.
+    await expect(column.item(0).title()).toHaveText(secondLabel!);
+
+    // The original first item should now be at index 1.
+    await expect(column.item(1).title()).toHaveText(firstLabel!);
+  });
+
+  test('drag to beginning of another column', async () => {
+    const col0 = board.column(0);
+    const col1 = board.column(1);
+
+    const col0CountBefore = await col0.items().count();
+    const col1CountBefore = await col1.items().count();
+    const draggedLabel = await col0.item(0).title().textContent();
+
+    // Drag above the first item in the target column.
+    await col0.item(0).dragTo(col1.item(0).locator, { x: 0, y: -10 });
+
+    await expect(col0.items()).toHaveCount(col0CountBefore - 1);
+    await expect(col1.items()).toHaveCount(col1CountBefore + 1);
+    await expect(col1.item(0).title()).toHaveText(draggedLabel!);
+  });
+
+  test('drag to middle of another column', async () => {
+    const col0 = board.column(0);
+    const col1 = board.column(1);
+
+    const col0CountBefore = await col0.items().count();
+    const col1CountBefore = await col1.items().count();
+    const draggedLabel = await col0.item(0).title().textContent();
+
+    // Drag to below the first item in the target column.
+    await col0.item(0).dragTo(col1.item(0).locator, { x: 0, y: 10 });
+
+    await expect(col0.items()).toHaveCount(col0CountBefore - 1);
+    await expect(col1.items()).toHaveCount(col1CountBefore + 1);
+    await expect(col1.items().getByRole('heading', { name: draggedLabel! })).toBeVisible();
+  });
+
+  test('drag to end of another column', async () => {
+    const col0 = board.column(0);
+    const col1 = board.column(1);
+
+    const col0CountBefore = await col0.items().count();
+    const col1CountBefore = await col1.items().count();
+    const draggedLabel = await col0.item(0).title().textContent();
+
+    // Hold ~20px above the footer to trigger pragmatic auto-scroll,
+    // then drop on the last item once it scrolls into view.
+    const footer = col1.locator.getByTestId('board-column-add-item');
+    await col0.item(0).dragToEndWithAutoScroll(footer, col1.item(col1CountBefore - 1).locator, { x: 0, y: 20 });
+
+    await expect(col0.items()).toHaveCount(col0CountBefore - 1);
+    await expect(col1.items()).toHaveCount(col1CountBefore + 1);
+    await expect(col1.items().getByRole('heading', { name: draggedLabel! })).toBeVisible();
+  });
+
+  test('drag into empty column', async () => {
+    const col0 = board.column(0);
+    const col2 = board.column(2);
+
+    const col0CountBefore = await col0.items().count();
+    await expect(col2.items()).toHaveCount(0);
+    const draggedLabel = await col0.item(0).title().textContent();
+
+    // Drag into the empty column body area.
+    await col0.item(0).dragTo(col2.header(), { x: 0, y: 40 });
+
+    await expect(col0.items()).toHaveCount(col0CountBefore - 1);
+    await expect(col2.items()).toHaveCount(1);
+    await expect(col2.item(0).title()).toHaveText(draggedLabel!);
+  });
+
+  test('create new item', async () => {
+    const column = board.column(0);
+    const countBefore = await column.items().count();
+
+    await column.addItem();
+
+    await expect(column.items()).toHaveCount(countBefore + 1);
+  });
+});

package/src/testing/CardContainer.tsx

@@ -15,44 +15,49 @@ const MIN_BLOCK_SIZE = 8;
 // Card container.
 //
 
-export const CardContainer = ({
-  children,
-  icon = 'ph--placeholder--regular',
-  role,
-}: PropsWithChildren<{ icon?: string; role?: string }>) => {
+export type CardContainerProps = PropsWithChildren<{ role?: 'popover' | 'intrinsic'; icon?: string }>;
+
+export const CardContainer = ({ children, role, icon = 'ph--arrow-line-down--regular' }: CardContainerProps) => {
   switch (role) {
-    case 'card--popover':
-      return <PopoverCardContainer icon={icon}>{children}</PopoverCardContainer>;
-    case 'card--intrinsic':
+    case 'popover':
+      return (
+        <div role='none' className='flex justify-center'>
+          <PopoverCardContainer icon={icon}>{children}</PopoverCardContainer>
+        </div>
+      );
+    case 'intrinsic':
     default:
       return <IntrinsicCardContainer>{children}</IntrinsicCardContainer>;
   }
 };
 
-const border = 'relative border border-dashed border-subduedSeparator p-4 rounded-lg overflow-x-auto';
-
 //
 // Popover
 //
 
 export type PopoverCardContainerProps = PropsWithChildren<{ icon?: string }>;
 
-export const PopoverCardContainer = ({ children, icon = 'ph--placeholder--regular' }: PopoverCardContainerProps) => {
+export const PopoverCardContainer = ({
+  children,
+  icon = 'ph--arrow-line-down--regular',
+}: PopoverCardContainerProps) => {
   return (
     <Popover.Root open>
-      <Popover.Content onOpenAutoFocus={(event) => event.preventDefault()}>
-        <Popover.Viewport classNames='popover-card-width'>{children}</Popover.Viewport>
-        <Popover.Arrow />
-      </Popover.Content>
       <Popover.Trigger asChild>
         <Icon icon={icon} size={5} />
       </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Content onOpenAutoFocus={(event: Event) => event.preventDefault()}>
+          <Popover.Viewport classNames='dx-card-popover'>{children}</Popover.Viewport>
+          <Popover.Arrow />
+        </Popover.Content>
+      </Popover.Portal>
     </Popover.Root>
   );
 };
 
 //
-// Intrinsic card container (size constrained by card).
+// Intrinsic card container (size constrained by card itself).
 //
 
 export type IntrinsicCardContainerProps = PropsWithChildren<{
@@ -74,8 +79,15 @@ export const IntrinsicCardContainer = ({
   });
 
   return (
-    <div className={border} style={sizeStyle(size, 'horizontal')} {...resizeAttributes}>
-      {children}
+    <div
+      role='none'
+      className='relative p-2 grid overflow-hidden border-2 border-dashed border-green-500 rounded-lg'
+      style={sizeStyle(size, 'horizontal')}
+      {...resizeAttributes}
+    >
+      <div role='none' className='flex flex-col w-full h-full overflow-hidden'>
+        {children}
+      </div>
       <ResizeHandle
         side='inline-end'
         fallbackSize={DEFAULT_BLOCK_SIZE}

package/src/testing/DefaultStackTile.tsx

@@ -2,30 +2,41 @@
 // Copyright 2026 DXOS.org
 //
 
-import React, { useRef, useState } from 'react';
+import React, { useMemo, useRef, useState } from 'react';
 
 import { Obj } from '@dxos/echo';
+import { Card, Toolbar } from '@dxos/react-ui';
+import { Menu, createMenuAction } from '@dxos/react-ui-menu';
 import { Json } from '@dxos/react-ui-syntax-highlighter';
 
-import { Card, Mosaic, type StackTileComponent } from '../components';
+import { Mosaic, type MosaicStackTileComponent } from '../components';
 
-export const DefaultStackTile: StackTileComponent<Obj.Any> = (props) => {
+export const DefaultStackTile: MosaicStackTileComponent<Obj.Any> = (props) => {
   const dragHandleRef = useRef<HTMLButtonElement>(null);
   const [open, setOpen] = useState(false);
+  const menuItems = useMemo(
+    () => [
+      createMenuAction('toggle-details', () => setOpen((prev) => !prev), {
+        label: open ? 'Hide details' : 'Show details',
+        icon: 'ph--placeholder--regular',
+      }),
+    ],
+    [open],
+  );
+
   return (
-    <Mosaic.Tile {...props} className='border border-separator rounded-sm font-mono'>
-      <Card.Toolbar>
-        <Card.DragHandle ref={dragHandleRef} />
-        <Card.Title>{Obj.getLabel(props.data) ?? props.data.id}</Card.Title>
-        <Card.Menu
-          items={[
-            {
-              label: open ? 'Hide details' : 'Show details',
-              onClick: () => setOpen((open) => !open),
-            },
-          ]}
-        />
-      </Card.Toolbar>
+    <Mosaic.Tile {...props} className='border border-separator rounded-xs font-mono'>
+      <Menu.Root>
+        <Card.Toolbar>
+          <Card.DragHandle ref={dragHandleRef} />
+          <Card.Title>{Obj.getLabel(props.data) ?? props.data.id}</Card.Title>
+          {/* TODO(wittjosiah): Reconcile with Card.Menu. */}
+          <Menu.Trigger asChild disabled={!menuItems?.length}>
+            <Toolbar.IconButton iconOnly variant='ghost' icon='ph--dots-three-vertical--regular' label='Menu' />
+          </Menu.Trigger>
+          <Menu.Content items={menuItems} />
+        </Card.Toolbar>
+      </Menu.Root>
       {open && (
         <Card.Row>
           <Json data={props.data} classNames='text-xs' />

package/src/testing/index.ts

@@ -3,7 +3,7 @@
 //
 
 export * from './decorator';
+export * from './types';
 
-export * from './Board';
 export * from './CardContainer';
 export * from './DefaultStackTile';

package/src/testing/types.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Ref, Type } from '@dxos/echo';
+import { ObjectId } from '@dxos/keys';
+
+//
+// Test Data
+//
+
+export const TestItem = Schema.Struct({
+  name: Schema.String,
+  description: Schema.optional(Schema.String),
+  label: Schema.optional(Schema.String),
+}).pipe(
+  Type.object({
+    typename: 'example.com/type/Item',
+    version: '0.1.0',
+  }),
+);
+
+export interface TestItem extends Schema.Schema.Type<typeof TestItem> {}
+
+export const TestColumn = Schema.Struct({
+  id: ObjectId,
+  name: Schema.String,
+  items: Schema.mutable(Schema.Array(Ref.Ref(TestItem))),
+}).pipe(
+  Type.object({
+    typename: 'example.com/type/Column',
+    version: '0.1.0',
+  }),
+);
+
+export interface TestColumn extends Schema.Schema.Type<typeof TestColumn> {}

package/src/translations.ts

@@ -9,7 +9,11 @@ export const translationKey = '@dxos/react-ui-mosaic';
 export const translations = [
   {
     'en-US': {
-      [translationKey]: {},
+      [translationKey]: {
+        'action menu label': 'Actions',
+        'add item label': 'Add item',
+        'delete menu label': 'Delete',
+      },
     },
   },
 ] as const satisfies Resource[];