@dxos/react-ui-mosaic 0.8.4-main.fcfe5033a5 → 0.9.0

package/src/components/SearchStack/SearchStack.stories.tsx

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+
+import { withAttention } from '@dxos/react-ui-attention/testing';
+import { withMosaic } from '@dxos/react-ui-mosaic/testing';
+import { type SearchResult } from '@dxos/react-ui-search';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { SearchStack, type SearchStackProps } from './SearchStack';
+
+const createMockResults = (count: number): SearchResult[] => {
+  return Array.from({ length: count }, (_, index) => ({
+    id: `result-${index}`,
+    label: `Search Result ${index + 1}`,
+    snippet: index % 2 === 0 ? `This is a preview snippet for result ${index + 1}.` : undefined,
+    type: index % 3 === 0 ? 'document' : index % 3 === 1 ? 'contact' : 'project',
+  }));
+};
+
+const SearchStackStory = (props: Omit<SearchStackProps, 'id' | 'results'>) => {
+  const results = useMemo(() => createMockResults(50), []);
+  return <SearchStack id='story' results={results} {...props} />;
+};
+
+const meta: Meta<typeof SearchStackStory> = {
+  title: 'ui/react-ui-search/SearchStack',
+  component: SearchStackStory,
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  decorators: [withTheme(), withLayout({ layout: 'column' }), withAttention(), withMosaic()],
+};
+
+export const Responsive: Story = {
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-[30rem]' }), withAttention(), withMosaic()],
+};

package/src/components/SearchStack/SearchStack.tsx

@@ -0,0 +1,135 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type KeyboardEvent, forwardRef, useCallback, useMemo, useState } from 'react';
+
+import { Card, ScrollArea } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/react-ui';
+import { type SearchResult } from '@dxos/react-ui-search';
+
+import { Focus, Mosaic, type MosaicTileProps, useMosaicContainer } from '../..';
+
+export type SearchStackAction = {
+  type: 'select';
+  resultId: string;
+};
+
+export type SearchStackActionHandler = (action: SearchStackAction) => void;
+
+//
+// SearchStack
+//
+
+export type SearchStackProps = {
+  id: string;
+  results?: SearchResult[];
+  currentId?: string;
+  onAction?: SearchStackActionHandler;
+};
+
+/**
+ * Card-based search result stack component using mosaic layout.
+ */
+export const SearchStack = composable<HTMLDivElement, SearchStackProps>(
+  ({ results = [], currentId, onAction, ...props }, forwardedRef) => {
+    const [viewport, setViewport] = useState<HTMLElement | null>(null);
+    const items = useMemo(() => results.map((result) => ({ result, onAction })), [results, onAction]);
+
+    const handleCurrentChange = useCallback(
+      (id: string | undefined) => {
+        if (id) {
+          onAction?.({ type: 'select', resultId: id });
+        }
+      },
+      [onAction],
+    );
+
+    const handleKeyDown = useCallback((event: KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === 'Enter') {
+        event.preventDefault();
+        (document.activeElement as HTMLElement | null)?.click();
+      }
+    }, []);
+
+    return (
+      <Focus.Group asChild {...composableProps(props)} onKeyDown={handleKeyDown} ref={forwardedRef}>
+        <Mosaic.Container asChild withFocus currentId={currentId} onCurrentChange={handleCurrentChange}>
+          <ScrollArea.Root orientation='vertical' padding centered thin>
+            <ScrollArea.Viewport ref={setViewport}>
+              <Mosaic.VirtualStack
+                Tile={SearchTile}
+                classNames='my-2'
+                gap={8}
+                items={items}
+                draggable={false}
+                getId={(item) => item.result.id}
+                getScrollElement={() => viewport}
+                estimateSize={() => 100}
+              />
+            </ScrollArea.Viewport>
+          </ScrollArea.Root>
+        </Mosaic.Container>
+      </Focus.Group>
+    );
+  },
+);
+
+SearchStack.displayName = 'SearchStack';
+
+//
+// SearchTile
+//
+
+type SearchTileData = {
+  result: SearchResult;
+  onAction?: SearchStackActionHandler;
+};
+
+type SearchTileProps = Pick<MosaicTileProps<SearchTileData>, 'location' | 'data' | 'current'>;
+
+/**
+ * Default search result tile with a simple Card header.
+ */
+const SearchTile = forwardRef<HTMLDivElement, SearchTileProps>(({ data, location, current }, forwardedRef) => {
+  const { result } = data;
+  const { setCurrentId } = useMosaicContainer('SearchTile');
+
+  const handleCurrentChange = useCallback(() => {
+    setCurrentId(result.id);
+  }, [result.id, setCurrentId]);
+
+  // Navigation / current pattern: clicking a result navigates to its
+  // detail. `dx-current` pairs with the `aria-current` attribute that
+  // `Mosaic.Tile` now sets from the `current` prop. `dx-selected`
+  // (master/detail option pattern) would be the wrong grammar here.
+  // See `ui-theme/src/css/components/selected.md`.
+  return (
+    <Mosaic.Tile
+      asChild
+      classNames='dx-hover dx-current'
+      id={result.id}
+      data={data}
+      location={location}
+      current={current}
+    >
+      <Focus.Item asChild current={current} onCurrentChange={handleCurrentChange}>
+        <Card.Root fullWidth ref={forwardedRef}>
+          <Card.Header>
+            <Card.IconBlock />
+            <Card.Title>{result.label}</Card.Title>
+          </Card.Header>
+          {result.snippet && (
+            <Card.Body>
+              <Card.Row>
+                <Card.Text variant='description'>{result.snippet}</Card.Text>
+              </Card.Row>
+            </Card.Body>
+          )}
+        </Card.Root>
+      </Focus.Item>
+    </Mosaic.Tile>
+  );
+});
+
+SearchTile.displayName = 'SearchTile';

package/src/components/SearchStack/index.ts

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

package/src/components/index.ts

@@ -5,3 +5,4 @@
 export * from './Board';
 export * from './Focus';
 export * from './Mosaic';
+export * from './SearchStack';

package/src/hooks/useContainerDebug.tsx

@@ -6,7 +6,7 @@ import React, { type FC, type ReactNode, forwardRef, useMemo, useRef } from 'rea
 import { createPortal } from 'react-dom';
 
 import { type ThemedClassName } from '@dxos/react-ui';
-import { Json } from '@dxos/react-ui-syntax-highlighter';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
 import { mx } from '@dxos/ui-theme';
 
 import { useMosaicContainer } from '../components';
@@ -25,7 +25,7 @@ export const useContainerDebug = (debug?: boolean): UseContainerDebug => {
     }
 
     return [
-      ({ classNames }) => <div role='none' className={mx('overflow-hidden', classNames)} ref={debugRef} />,
+      ({ classNames }) => <div className={mx('overflow-hidden', classNames)} ref={debugRef} />,
       () => debugRef.current && createPortal(<ContainerInfo />, debugRef.current),
     ];
   }, [debug, debugRef]);
@@ -37,7 +37,7 @@ const ContainerInfo = forwardRef<HTMLDivElement, ThemedClassName>(({ classNames
   const { id, state, activeLocation, scrolling } = useMosaicContainer(CONTAINER_INFO_NAME);
   const counter = useRef(0);
   return (
-    <Json.Data
+    <JsonHighlighter
       data={{ id, activeLocation, scrolling, state, count: counter.current++ }}
       classNames={mx('text-xs', classNames)}
       ref={forwardedRef}

package/src/hooks/useEventHandlerAdapter.ts

@@ -35,7 +35,7 @@ export type UseEventHandlerProps<TItem = any, TObject extends Obj.Unknown = Obj.
   make: (object: TObject) => TItem;
 
   /**
-   * Optional change callback for wrapping mutations in Obj.change style.
+   * Optional change callback for wrapping mutations in Obj.update style.
    * When provided, all array mutations will be wrapped in this callback.
    * When not provided, mutations happen directly on the items array.
    */

package/src/playwright/board-manager.ts

@@ -2,7 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import type { Locator, Page } from '@playwright/test';
+import { type Locator, type Page, expect } from '@playwright/test';
+
+/**
+ * Edge of the target tile to drop on. Pragmatic-dnd assigns the closest edge
+ * based on cursor position; a stale (pre-layout-shift) cursor can land in the
+ * wrong half. When `dragTo` is called with an `edge`, the helper waits for the
+ * target tile to register the drag, re-measures the target after the
+ * placeholder has expanded, repositions the cursor near the requested edge,
+ * and confirms via `data-mosaic-tile-edge` before releasing.
+ */
+export type DragEdge = 'top' | 'bottom' | 'left' | 'right';
 
 export class BoardManager {
   private readonly _page: Page;
@@ -84,27 +94,150 @@ export class ItemManager {
     return this.locator.getByTestId('mosaicBoard.cardTitle');
   }
 
-  async dragTo(target: Locator, offset = { x: 0, y: 0 }): Promise<void> {
+  async dragTo(target: Locator, offset: { x: number; y: number } = { x: 0, y: 0 }, edge?: DragEdge): Promise<void> {
     const handle = this.locator.getByTestId('mosaicBoard.cardDragHandle');
-    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);
+    const handleBox = await handle.boundingBox();
+    if (!handleBox) {
+      return;
+    }
+
+    // Capture stable ElementHandles to source and target before the drag
+    // begins. Both `nth(N)` locators shift when `useVisibleItems` filters the
+    // source out of its column, so we need raw DOM references that survive
+    // the reconciliation.
+    const targetHandle = await target.elementHandle();
+    const box = targetHandle ? await targetHandle.boundingBox() : null;
+    if (!targetHandle || !box) {
+      return;
+    }
+    const sourceHandle = await this.locator.elementHandle();
+
+    await handle.hover();
+    await this._page.mouse.down();
+    // Allow the drag monitor to register the grab before moving.
+    await this._page.waitForTimeout(100);
+
+    if (edge) {
+      // Stage 1: trigger the dragstart. A 1-pixel nudge near the press
+      // point primes pragmatic-dnd's HTML5 dragstart, then a long move
+      // over the target tile commits the drag past every browser's
+      // "click vs drag" threshold.
+      await this._page.mouse.move(handleBox.x + handleBox.width / 2 + 1, handleBox.y + handleBox.height / 2, {
+        steps: 1,
+      });
+      await this._page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 4 });
+
+      // Wait for `data-mosaic-container-state="active"` so we know the
+      // dragstart has been processed. This alone is *not* enough: pragmatic-
+      // dnd's `monitorForElements.onDragStart` (Root.tsx) and the
+      // `dropTargetForElements.onDragStart` (Container.tsx) write into
+      // independent React state, and only the latter drives the attribute.
+      // The former drives `useVisibleItems` filtering, which is what
+      // physically reflows the column. So we ALSO wait for the source tile
+      // to detach from the DOM — that's the unambiguous signal that the
+      // reflow has happened and any cached bbox is stale.
+      await expect
+        .poll(() => this._page.locator('[data-mosaic-container-state="active"]').count(), { timeout: 2000 })
+        .toBeGreaterThan(0);
+      if (sourceHandle) {
+        await this._page.waitForFunction((el) => !el || !el.isConnected, sourceHandle, { timeout: 2000 });
+      }
+
+      // Stage 2: walk siblings on the (now reflowed) drag-time DOM and aim
+      // at the placeholder representing the requested edge. The Fragment
+      // keying on item id keeps the target tile's adjacent placeholder DOM
+      // node stable across reconciliation, but its `location` prop and bbox
+      // both change once the source is filtered out — measure after the
+      // reflow, never before.
+      const placeholderHandle = await this._adjacentPlaceholder(targetHandle, edge);
+      if (placeholderHandle) {
+        const phBox = await placeholderHandle.boundingBox();
+        if (phBox) {
+          const aimX = phBox.x + phBox.width / 2;
+          const aimY = phBox.y + Math.max(phBox.height / 2, 1);
+          await this._page.mouse.move(aimX, aimY, { steps: 4 });
+
+          // Some browser/CDP combinations need a follow-up nudge to push
+          // the dragOver event through — re-aim with a 1px offset and poll.
+          const isActive = () =>
+            placeholderHandle.evaluate((el) => el.getAttribute('data-mosaic-placeholder-state') === 'active');
+          if (!(await isActive())) {
+            const start = Date.now();
+            let nudge = 0;
+            while (Date.now() - start < 3000) {
+              await this._page.waitForTimeout(100);
+              nudge = (nudge + 1) % 4;
+              const dx = nudge === 0 || nudge === 2 ? 1 : -1;
+              const dy = nudge === 1 || nudge === 2 ? 1 : -1;
+              await this._page.mouse.move(aimX + dx, aimY + dy, { steps: 1 });
+              if (await isActive()) {
+                break;
+              }
+            }
+            await expect
+              .poll(() => placeholderHandle.evaluate((el) => el.getAttribute('data-mosaic-placeholder-state')), {
+                timeout: 1000,
+              })
+              .toBe('active');
+          }
+
+          // Re-centre on the now-expanded placeholder so the drop lands
+          // solidly inside it.
+          const expanded = await placeholderHandle.boundingBox();
+          if (expanded) {
+            await this._page.mouse.move(expanded.x + expanded.width / 2, expanded.y + expanded.height / 2, {
+              steps: 2,
+            });
+          }
+        }
+      }
+    } else {
+      // Legacy path: no explicit edge — rely on the offset placement and a
+      // small settle delay before releasing.
       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();
     }
+    await this._page.mouse.up();
+  }
+
+  /**
+   * Find the placeholder element adjacent to `target` on the requested
+   * side via DOM walk. Returns `null` if the target has no matching
+   * sibling (e.g. when the caller passes a non-tile target).
+   */
+  private async _adjacentPlaceholder(
+    targetHandle: import('@playwright/test').ElementHandle<Element | SVGElement | HTMLElement>,
+    edge: DragEdge,
+  ): Promise<import('@playwright/test').ElementHandle<HTMLElement> | null> {
+    const before = edge === 'top' || edge === 'left';
+    const result = await targetHandle.evaluateHandle((el, beforeArg) => {
+      let sibling: Element | null = beforeArg ? el.previousElementSibling : el.nextElementSibling;
+      while (sibling && !sibling.hasAttribute('data-mosaic-placeholder-location')) {
+        sibling = beforeArg ? sibling.previousElementSibling : sibling.nextElementSibling;
+      }
+      return sibling as HTMLElement | null;
+    }, before);
+    const handle = result.asElement() as import('@playwright/test').ElementHandle<HTMLElement> | null;
+    if (!handle) {
+      return null;
+    }
+    // `evaluateHandle` returning `null` still produces a non-null JSHandle —
+    // verify the underlying element actually exists.
+    const exists = await handle.evaluate((el) => el !== null);
+    return exists ? handle : null;
   }
 
   /**
-   * 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.
+   * Drag this item to a column's scroll bottom, using auto-scroll when needed,
+   * then drop on the target item.
+   *
+   * When the target is already visible in the viewport (no scrolling needed), the
+   * item is dragged directly to the target. When the target is below the viewport,
+   * the mouse is held near the footer to trigger pragmatic auto-scroll until the
+   * target scrolls into view.
    *
    * @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 dropTarget - The element to drop on.
    * @param dropOffset - Offset from the drop target center.
    */
   async dragToEndWithAutoScroll(holdTarget: Locator, dropTarget: Locator, dropOffset = { x: 0, y: 0 }): Promise<void> {
@@ -118,11 +251,33 @@ export class ItemManager {
     const holdX = holdBox.x + holdBox.width / 2;
     const holdY = holdBox.y - 20;
 
+    // Check if drop target is already visible before starting the drag.
+    // Items may fit in the viewport without scrolling, in which case auto-scroll
+    // is not needed and the loop's exit condition would never be satisfied.
+    const preDropBox = await dropTarget.boundingBox();
+    const needsScroll = !preDropBox || preDropBox.y >= holdBox.y;
+
     await handle.hover();
     await this._page.mouse.down();
     // Allow the drag monitor to register the grab before moving.
     await this._page.waitForTimeout(100);
 
+    if (!needsScroll) {
+      // Target is already visible — drag directly without auto-scroll.
+      await this._page.mouse.move(holdX, holdY, { steps: 4 });
+      const dropBox = await dropTarget.boundingBox();
+      if (dropBox) {
+        const dropX = dropOffset.x + dropBox.x + dropBox.width / 2;
+        const dropY = dropOffset.y + dropBox.y + dropBox.height / 2;
+        await this._page.mouse.move(dropX, dropY, { steps: 8 });
+        await this._page.waitForTimeout(200);
+        await this._page.mouse.up();
+        return;
+      }
+      await this._page.mouse.up();
+      return;
+    }
+
     // Move to hold position above the footer to trigger auto-scroll.
     await this._page.mouse.move(holdX, holdY, { steps: 4 });
 

package/src/playwright/smoke.spec.ts

@@ -52,7 +52,7 @@ test.describe('Board', () => {
     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: BELOW_OFFSET });
+    await column.item(0).dragTo(column.item(1).locator, { x: 0, y: BELOW_OFFSET }, 'bottom');
 
     // Item count should stay the same.
     await expect(column.items()).toHaveCount(countBefore);
@@ -73,7 +73,7 @@ test.describe('Board', () => {
     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: ABOVE_OFFSET });
+    await col0.item(0).dragTo(col1.item(0).locator, { x: 0, y: ABOVE_OFFSET }, 'top');
 
     await expect(col0.items()).toHaveCount(col0CountBefore - 1);
     await expect(col1.items()).toHaveCount(col1CountBefore + 1);
@@ -89,7 +89,7 @@ test.describe('Board', () => {
     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: BELOW_OFFSET });
+    await col0.item(0).dragTo(col1.item(0).locator, { x: 0, y: BELOW_OFFSET }, 'bottom');
 
     await expect(col0.items()).toHaveCount(col0CountBefore - 1);
     await expect(col1.items()).toHaveCount(col1CountBefore + 1);

package/src/testing/CardContainer.tsx

@@ -21,7 +21,7 @@ export const CardContainer = ({ children, role, icon = 'ph--arrow-line-down--reg
   switch (role) {
     case 'popover':
       return (
-        <div role='none' className='flex justify-center'>
+        <div className='flex justify-center'>
           <PopoverCardContainer icon={icon}>{children}</PopoverCardContainer>
         </div>
       );
@@ -80,14 +80,11 @@ export const IntrinsicCardContainer = ({
 
   return (
     <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='dx-container flex flex-col'>
-        {children}
-      </div>
+      <div className='dx-container flex flex-col'>{children}</div>
       <ResizeHandle
         side='inline-end'
         fallbackSize={DEFAULT_BLOCK_SIZE}

package/src/testing/DefaultStackTile.tsx

@@ -7,7 +7,7 @@ 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 { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
 
 import { Focus, Mosaic, type MosaicStackTileComponent } from '../components';
 
@@ -18,7 +18,7 @@ export const DefaultStackTile: MosaicStackTileComponent<Obj.Any> = (props) => {
     () => [
       createMenuAction('toggle-details', () => setOpen((prev) => !prev), {
         label: open ? 'Hide details' : 'Show details',
-        icon: 'ph--placeholder--regular',
+        icon: 'ph--circle-dashed--regular',
       }),
     ],
     [open],
@@ -26,20 +26,26 @@ export const DefaultStackTile: MosaicStackTileComponent<Obj.Any> = (props) => {
 
   return (
     <Menu.Root>
+      {/*
+       * `Mosaic.Tile` sets `aria-current` from `props.current`, which the
+       * Slot composition propagates down to `Card.Root`'s div. That's what
+       * makes `dx-current` (an `aria-[current=true]:` utility) actually
+       * fire here. See `ui-theme/src/css/components/selected.md`.
+       */}
       <Mosaic.Tile {...props} asChild>
         <Focus.Item asChild>
           <Card.Root className='dx-current dx-hover'>
-            <Card.Toolbar>
+            <Card.Header>
               <Card.DragHandle ref={dragHandleRef} />
               <Card.Title>{Obj.getLabel(props.data) ?? props.data.id}</Card.Title>
               <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>
+            </Card.Header>
             {open && (
               <Card.Row>
-                <Json.Data data={props.data} classNames='text-xs' />
+                <JsonHighlighter data={props.data} classNames='text-xs' />
               </Card.Row>
             )}
           </Card.Root>

package/src/testing/types.ts

@@ -4,8 +4,8 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Ref, Type } from '@dxos/echo';
-import { ObjectId } from '@dxos/keys';
+import { DXN, Ref, Type } from '@dxos/echo';
+import { EntityId } from '@dxos/keys';
 
 //
 // Test Data
@@ -15,24 +15,14 @@ export const TestItem = Schema.Struct({
   name: Schema.String,
   description: Schema.optional(Schema.String),
   label: Schema.optional(Schema.String),
-}).pipe(
-  Type.object({
-    typename: 'com.example.type.item',
-    version: '0.1.0',
-  }),
-);
+}).pipe(Type.makeObject(DXN.make('com.example.type.item', '0.1.0')));
 
-export interface TestItem extends Schema.Schema.Type<typeof TestItem> {}
+export type TestItem = Type.InstanceType<typeof TestItem>;
 
 export const TestColumn = Schema.Struct({
-  id: ObjectId,
+  id: EntityId,
   name: Schema.String,
   items: Schema.mutable(Schema.Array(Ref.Ref(TestItem))),
-}).pipe(
-  Type.object({
-    typename: 'com.example.type.column',
-    version: '0.1.0',
-  }),
-);
+}).pipe(Type.makeObject(DXN.make('com.example.type.column', '0.1.0')));
 
-export interface TestColumn extends Schema.Schema.Type<typeof TestColumn> {}
+export type TestColumn = Type.InstanceType<typeof TestColumn>;