@dxos/react-ui-list 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/components/Tree/Tree.tsx

@@ -1,68 +1,71 @@
 //
 // Copyright 2024 DXOS.org
-//
 
+import { useAtomValue } from '@effect-atom/atom-react';
 import React, { useMemo } from 'react';
 
-import { type HasId } from '@dxos/echo-schema';
 import { Treegrid, type TreegridRootProps } from '@dxos/react-ui';
 
-import { type TreeContextType, TreeProvider } from './TreeContext';
-import { TreeItem, type TreeItemProps } from './TreeItem';
+import { type TreeModel, TreeProvider } from './TreeContext';
+import { TreeItemById, type TreeItemByIdProps, type TreeItemProps } from './TreeItem';
 
-export type TreeProps<T extends HasId = any, O = any> = {
-  root?: T;
+export type TreeProps<T extends { id: string } = any> = {
+  model: TreeModel<T>;
+  rootId?: string;
   path?: string[];
   id: string;
-} & TreeContextType<T, O> &
-  Partial<Pick<TreegridRootProps, 'gridTemplateColumns' | 'classNames'>> &
-  Pick<TreeItemProps<T>, 'draggable' | 'renderColumns' | 'canDrop' | 'onOpenChange' | 'onSelect' | 'levelOffset'>;
+} & Partial<Pick<TreegridRootProps, 'gridTemplateColumns' | 'classNames'>> &
+  Pick<
+    TreeItemProps<T>,
+    | 'draggable'
+    | 'renderColumns'
+    | 'blockInstruction'
+    | 'canDrop'
+    | 'canSelect'
+    | 'onOpenChange'
+    | 'onSelect'
+    | 'onItemHover'
+    | 'levelOffset'
+  >;
 
-export const Tree = <T extends HasId = any, O = any>({
-  root,
+export const Tree = <T extends { id: string } = any>({
+  model,
+  rootId,
   path,
   id,
-  useItems,
-  getProps,
-  isOpen,
-  isCurrent,
   draggable = false,
   gridTemplateColumns = '[tree-row-start] 1fr min-content [tree-row-end]',
   classNames,
   levelOffset,
   renderColumns,
+  blockInstruction,
   canDrop,
+  canSelect,
   onOpenChange,
   onSelect,
-}: TreeProps<T, O>) => {
-  const context = useMemo(
-    () => ({
-      useItems,
-      getProps,
-      isOpen,
-      isCurrent,
-    }),
-    [useItems, getProps, isOpen, isCurrent],
-  );
-  const items = useItems(root);
+  onItemHover,
+}: TreeProps<T>) => {
+  const childIds = useAtomValue(model.childIds(rootId));
   const treePath = useMemo(() => (path ? [...path, id] : [id]), [id, path]);
 
+  const childProps: Omit<TreeItemByIdProps, 'id' | 'last'> = {
+    path: treePath,
+    levelOffset,
+    draggable,
+    renderColumns,
+    blockInstruction,
+    canDrop,
+    canSelect,
+    onOpenChange,
+    onSelect,
+    onItemHover,
+  };
+
   return (
     <Treegrid.Root gridTemplateColumns={gridTemplateColumns} classNames={classNames}>
-      <TreeProvider value={context}>
-        {items.map((item, index) => (
-          <TreeItem
-            key={item.id}
-            item={item}
-            last={index === items.length - 1}
-            path={treePath}
-            levelOffset={levelOffset}
-            draggable={draggable}
-            renderColumns={renderColumns}
-            canDrop={canDrop}
-            onOpenChange={onOpenChange}
-            onSelect={onSelect}
-          />
+      <TreeProvider value={model}>
+        {childIds.map((childId, index) => (
+          <TreeItemById key={childId} id={childId} last={index === childIds.length - 1} {...childProps} />
         ))}
       </TreeProvider>
     </Treegrid.Root>

package/src/components/Tree/TreeContext.tsx

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+import { type Atom } from '@effect-atom/atom-react';
 import { createContext, useContext } from 'react';
 
 import { raise } from '@dxos/debug';
@@ -11,21 +12,32 @@ export type TreeItemDataProps = {
   id: string;
   label: Label;
   parentOf?: string[];
-  icon?: string;
-  disabled?: boolean;
+  /** When `false`, the item cannot be dragged (overrides tree-level `draggable`). */
+  draggable?: boolean;
+  /** When `false`, the item does not participate as a drop target. */
+  droppable?: boolean;
   className?: string;
   headingClassName?: string;
+  icon?: string;
+  iconHue?: string;
+  disabled?: boolean;
   testId?: string;
 };
 
-export type TreeContextType<T = any, O = any> = {
-  useItems: (parent?: T, options?: O) => T[];
-  getProps: (item: T, parent: string[]) => TreeItemDataProps;
-  isOpen: (path: string[], item: T) => boolean;
-  isCurrent: (path: string[], item: T) => boolean;
-};
+export interface TreeModel<T extends { id: string } = any> {
+  /** Atom family: resolve item by ID (content). */
+  item: (id: string) => Atom.Atom<T | undefined>;
+  /** Atom family: open state keyed by path. */
+  itemOpen: (path: string[]) => Atom.Atom<boolean>;
+  /** Atom family: current (selected) state keyed by path. */
+  itemCurrent: (path: string[]) => Atom.Atom<boolean>;
+  /** Atom family: display props for an item at a given path (path includes item's own ID at end). */
+  itemProps: (path: string[]) => Atom.Atom<TreeItemDataProps>;
+  /** Atom family: outbound child IDs for a parent ID (topology). Undefined = root. */
+  childIds: (parentId?: string) => Atom.Atom<string[]>;
+}
 
-const TreeContext = createContext<null | TreeContextType>(null);
+const TreeContext = createContext<TreeModel | null>(null);
 
 export const TreeProvider = TreeContext.Provider;
 

package/src/components/Tree/TreeItem.tsx

@@ -2,37 +2,49 @@
 // Copyright 2024 DXOS.org
 //
 
-import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
-import { draggable, dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
 import {
   type Instruction,
   type ItemMode,
   attachInstruction,
   extractInstruction,
 } from '@atlaskit/pragmatic-drag-and-drop-hitbox/tree-item';
-import { Schema } from 'effect';
-import React, { type FC, type KeyboardEvent, memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
+import { draggable, dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Schema from 'effect/Schema';
+import React, {
+  type FC,
+  type KeyboardEvent,
+  type MouseEvent,
+  memo,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 
-import { type HasId } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
-import { TreeItem as NaturalTreeItem, Treegrid } from '@dxos/react-ui';
+import { TreeItem as NaturalTreeItem, Treegrid, TREEGRID_PARENT_OF_SEPARATOR } from '@dxos/react-ui';
 import {
+  ghostFocusWithin,
   ghostHover,
   hoverableControls,
   hoverableFocusedKeyboardControls,
   hoverableFocusedWithinControls,
-} from '@dxos/react-ui-theme';
+  mx,
+} from '@dxos/ui-theme';
 
 import { DEFAULT_INDENTATION, paddingIndentation } from './helpers';
 import { useTree } from './TreeContext';
 import { TreeItemHeading } from './TreeItemHeading';
 import { TreeItemToggle } from './TreeItemToggle';
 
-type TreeItemState = 'idle' | 'dragging' | 'preview' | 'parent-of-instruction';
-
 const hoverableDescriptionIcons =
   '[--icons-color:inherit] hover-hover:[--icons-color:var(--description-text)] hover-hover:hover:[--icons-color:inherit] focus-within:[--icons-color:inherit]';
 
+type TreeItemDragState = 'idle' | 'dragging' | 'preview' | 'parent-of-instruction';
+
 export const TreeDataSchema = Schema.Struct({
   id: Schema.String,
   path: Schema.Array(Schema.String),
@@ -42,7 +54,7 @@ export const TreeDataSchema = Schema.Struct({
 export type TreeData = Schema.Schema.Type<typeof TreeDataSchema>;
 export const isTreeData = (data: unknown): data is TreeData => Schema.is(TreeDataSchema)(data);
 
-export type ColumnRenderer<T extends HasId = any> = FC<{
+export type ColumnRenderer<T extends { id: string } = any> = FC<{
   item: T;
   path: string[];
   open: boolean;
@@ -50,46 +62,74 @@ export type ColumnRenderer<T extends HasId = any> = FC<{
   setMenuOpen: (open: boolean) => void;
 }>;
 
-export type TreeItemProps<T extends HasId = any> = {
+export type TreeItemProps<T extends { id: string } = any> = {
   item: T;
   path: string[];
   levelOffset?: number;
   last: boolean;
   draggable?: boolean;
   renderColumns?: ColumnRenderer<T>;
+  blockInstruction?: (params: { instruction: Instruction; source: TreeData; target: TreeData }) => boolean;
   canDrop?: (params: { source: TreeData; target: TreeData }) => boolean;
+  canSelect?: (params: { item: T; path: string[] }) => boolean;
   onOpenChange?: (params: { item: T; path: string[]; open: boolean }) => void;
   onSelect?: (params: { item: T; path: string[]; current: boolean; option: boolean }) => void;
+  onItemHover?: (params: { item: T }) => void;
 };
 
-const RawTreeItem = <T extends HasId = any>({
+const RawTreeItem = <T extends { id: string } = any>({
   item,
-  path: _path,
+  path: pathProp,
+  levelOffset = 2,
   last,
-  draggable: _draggable,
+  draggable: draggableProp,
   renderColumns: Columns,
+  blockInstruction,
   canDrop,
+  canSelect,
   onOpenChange,
   onSelect,
-  levelOffset = 2,
+  onItemHover,
 }: TreeItemProps<T>) => {
   const rowRef = useRef<HTMLDivElement | null>(null);
   const buttonRef = useRef<HTMLButtonElement | null>(null);
   const openRef = useRef(false);
   const cancelExpandRef = useRef<NodeJS.Timeout | null>(null);
-  const [_state, setState] = useState<TreeItemState>('idle');
+  const [_state, setState] = useState<TreeItemDragState>('idle');
   const [instruction, setInstruction] = useState<Instruction | null>(null);
   const [menuOpen, setMenuOpen] = useState(false);
 
-  const { useItems, getProps, isOpen, isCurrent } = useTree();
-  const items = useItems(item);
-  const { id, label, parentOf, icon, disabled, className, headingClassName, testId } = getProps(item, _path);
-  const path = useMemo(() => [..._path, id], [_path, id]);
-  const open = isOpen(path, item);
-  const current = isCurrent(path, item);
+  const {
+    itemProps: itemPropsAtom,
+    childIds: childIdsAtom,
+    itemOpen: itemOpenAtom,
+    itemCurrent: itemCurrentAtom,
+  } = useTree();
+  const path = useMemo(() => [...pathProp, item.id], [pathProp, item.id]);
+
+  const {
+    id,
+    parentOf,
+    draggable: itemDraggable,
+    droppable: itemDroppable,
+    label,
+    className,
+    headingClassName,
+    icon,
+    iconHue,
+    disabled,
+    testId,
+  } = useAtomValue(itemPropsAtom(path));
+  const childIds = useAtomValue(childIdsAtom(item.id));
+  const open = useAtomValue(itemOpenAtom(path));
+  const current = useAtomValue(itemCurrentAtom(path));
+
   const level = path.length - levelOffset;
   const isBranch = !!parentOf;
   const mode: ItemMode = last ? 'last-in-group' : open ? 'expanded' : 'standard';
+  const canSelectItem = canSelect?.({ item, path }) ?? true;
+  const data = { id, path, item } satisfies TreeData;
+  const shouldSeedNativeDragData = typeof document !== 'undefined' && document.body.hasAttribute('data-platform');
 
   const cancelExpand = useCallback(() => {
     if (cancelExpandRef.current) {
@@ -98,20 +138,27 @@ const RawTreeItem = <T extends HasId = any>({
     }
   }, []);
 
+  const isItemDraggable = draggableProp && itemDraggable !== false;
+  const isItemDroppable = itemDroppable !== false;
+  const nativeDragText = id;
+
   useEffect(() => {
-    if (!_draggable) {
+    if (!draggableProp) {
       return;
     }
 
     invariant(buttonRef.current);
 
-    const data = { id, path, item } satisfies TreeData;
-
-    // https://atlassian.design/components/pragmatic-drag-and-drop/core-package/adapters/element/about
-    return combine(
+    const makeDraggable = () =>
       draggable({
-        element: buttonRef.current,
+        element: buttonRef.current!,
         getInitialData: () => data,
+        getInitialDataForExternal: () => {
+          if (!shouldSeedNativeDragData) {
+            return {};
+          }
+          return { 'text/plain': nativeDragText };
+        },
         onDragStart: () => {
           setState('dragging');
           if (open) {
@@ -125,96 +172,132 @@ const RawTreeItem = <T extends HasId = any>({
             onOpenChange?.({ item, path, open: true });
           }
         },
-      }),
-      // https://github.com/atlassian/pragmatic-drag-and-drop/blob/main/packages/hitbox/constellation/index/about.mdx
-      dropTargetForElements({
-        element: buttonRef.current,
-        getData: ({ input, element }) => {
-          return attachInstruction(data, {
-            input,
-            element,
-            indentPerLevel: DEFAULT_INDENTATION,
-            currentLevel: level,
-            mode,
-            block: isBranch ? [] : ['make-child'],
-          });
-        },
-        canDrop: ({ source }) => {
-          const _canDrop = canDrop ?? (() => true);
-          return source.element !== buttonRef.current && _canDrop({ source: source.data as TreeData, target: data });
-        },
-        getIsSticky: () => true,
-        onDrag: ({ self, source }) => {
-          const instruction = extractInstruction(self.data);
-
-          if (source.data.id !== id) {
-            if (instruction?.type === 'make-child' && isBranch && !open && !cancelExpandRef.current) {
-              cancelExpandRef.current = setTimeout(() => {
-                onOpenChange?.({ item, path, open: true });
-              }, 500);
-            }
-
-            if (instruction?.type !== 'make-child') {
-              cancelExpand();
-            }
-
-            setInstruction(instruction);
-          } else if (instruction?.type === 'reparent') {
-            // TODO(wittjosiah): This is not occurring in the current implementation.
-            setInstruction(instruction);
-          } else {
-            setInstruction(null);
+      });
+
+    if (!isItemDroppable) {
+      return isItemDraggable ? makeDraggable() : undefined;
+    }
+
+    const dropTarget = dropTargetForElements({
+      element: buttonRef.current,
+      getData: ({ input, element }) => {
+        return attachInstruction(data, {
+          input,
+          element,
+          indentPerLevel: DEFAULT_INDENTATION,
+          currentLevel: level,
+          mode,
+          block: isBranch ? [] : ['make-child'],
+        });
+      },
+      canDrop: ({ source }) => {
+        const _canDrop = canDrop ?? (() => true);
+        return source.element !== buttonRef.current && _canDrop({ source: source.data as TreeData, target: data });
+      },
+      getIsSticky: () => true,
+      onDrag: ({ self, source }) => {
+        const desired = extractInstruction(self.data);
+        const block =
+          desired && blockInstruction?.({ instruction: desired, source: source.data as TreeData, target: data });
+        const instruction: Instruction | null =
+          block && desired.type !== 'instruction-blocked' ? { type: 'instruction-blocked', desired } : desired;
+
+        if (source.data.id !== id) {
+          if (instruction?.type === 'make-child' && isBranch && !open && !cancelExpandRef.current) {
+            cancelExpandRef.current = setTimeout(() => {
+              onOpenChange?.({ item, path, open: true });
+            }, 500);
           }
-        },
-        onDragLeave: () => {
-          cancelExpand();
-          setInstruction(null);
-        },
-        onDrop: () => {
-          cancelExpand();
+
+          if (instruction?.type !== 'make-child') {
+            cancelExpand();
+          }
+
+          setInstruction(instruction);
+        } else if (instruction?.type === 'reparent') {
+          // TODO(wittjosiah): This is not occurring in the current implementation.
+          setInstruction(instruction);
+        } else {
           setInstruction(null);
-        },
-      }),
-    );
-  }, [_draggable, item, id, mode, path, open, canDrop]);
+        }
+      },
+      onDragLeave: () => {
+        cancelExpand();
+        setInstruction(null);
+      },
+      onDrop: () => {
+        cancelExpand();
+        setInstruction(null);
+      },
+    });
+
+    if (!isItemDraggable) {
+      return dropTarget;
+    }
+
+    // https://atlassian.design/components/pragmatic-drag-and-drop/core-package/adapters/element/about
+    return combine(makeDraggable(), dropTarget);
+  }, [draggableProp, isItemDraggable, isItemDroppable, item, id, mode, path, open, blockInstruction, canDrop]);
 
   // Cancel expand on unmount.
   useEffect(() => () => cancelExpand(), [cancelExpand]);
 
-  const handleOpenChange = useCallback(
+  const handleOpenToggle = useCallback(
     () => onOpenChange?.({ item, path, open: !open }),
     [onOpenChange, item, path, open],
   );
 
   const handleSelect = useCallback(
     (option = false) => {
-      if (isBranch) {
-        handleOpenChange();
-      } else {
+      // If the item is a branch, toggle it if:
+      //   - also holding down the option key
+      //   - or the item is currently selected
+      if (isBranch && (option || current)) {
+        handleOpenToggle();
+      } else if (canSelectItem) {
+        canSelect?.({ item, path });
         rowRef.current?.focus();
         onSelect?.({ item, path, current: !current, option });
       }
     },
-    [item, path, current, isBranch, handleOpenChange, onSelect],
+    [item, path, current, isBranch, canSelectItem, handleOpenToggle, onSelect],
   );
 
   const handleKeyDown = useCallback(
     (event: KeyboardEvent) => {
       switch (event.key) {
         case 'ArrowRight':
-          isBranch && !open && handleOpenChange();
-          break;
         case 'ArrowLeft':
-          isBranch && open && handleOpenChange();
-          break;
-        case ' ':
-          handleSelect(event.altKey);
+          isBranch && handleOpenToggle();
           break;
       }
     },
-    [isBranch, open, handleOpenChange, handleSelect],
+    [isBranch, open, handleOpenToggle, handleSelect],
+  );
+
+  const handleItemHover = useCallback(() => {
+    onItemHover?.({ item });
+  }, [onItemHover, item]);
+
+  const handleContextMenu = useCallback(
+    (event: MouseEvent) => {
+      event.preventDefault();
+      setMenuOpen(true);
+    },
+    [setMenuOpen],
   );
 
+  const childProps = {
+    draggable: draggableProp,
+    renderColumns: Columns,
+    blockInstruction,
+    canDrop,
+    canSelect,
+    onItemHover,
+    onOpenChange,
+    onSelect,
+  };
+
   return (
     <>
       <Treegrid.Row
@@ -222,65 +305,69 @@ const RawTreeItem = <T extends HasId = any>({
         key={id}
         id={id}
         aria-labelledby={`${id}__label`}
-        parentOf={parentOf?.join(Treegrid.PARENT_OF_SEPARATOR)}
-        classNames={[
-          'grid grid-cols-subgrid col-[tree-row] mbs-0.5 aria-[current]:bg-activeSurface',
+        parentOf={parentOf?.join(TREEGRID_PARENT_OF_SEPARATOR)}
+        data-object-id={id}
+        data-testid={testId}
+        // NOTE(thure): This is intentionally an empty string to for descendents to select by in the CSS
+        //   without alerting the user (except for in the correct link element). See also:
+        //   https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current#description
+        aria-current={current ? ('' as 'page') : undefined}
+        classNames={mx(
+          'grid grid-cols-subgrid col-[tree-row] mt-0.5 is-current:bg-active-surface',
           hoverableControls,
           hoverableFocusedKeyboardControls,
           hoverableFocusedWithinControls,
           hoverableDescriptionIcons,
+          ghostFocusWithin,
           ghostHover,
           className,
-        ]}
-        data-itemid={id}
-        data-testid={testId}
-        // NOTE(thure): This is intentionally an empty string to for descendents to select by in the CSS
-        //   without alerting the user (except for in the correct link element). See also:
-        //   https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current#description
-        aria-current={current ? ('' as 'page') : undefined}
+        )}
         onKeyDown={handleKeyDown}
-        onContextMenu={(event) => {
-          event.preventDefault();
-          setMenuOpen(true);
-        }}
+        onMouseEnter={handleItemHover}
+        onContextMenu={handleContextMenu}
       >
-        <Treegrid.Cell
-          indent
-          classNames='relative grid grid-cols-subgrid col-[tree-row]'
+        <div
+          role='none'
+          className='indent relative grid grid-cols-subgrid col-[tree-row]'
           style={paddingIndentation(level)}
         >
-          <div role='none' className='flex items-center'>
-            <TreeItemToggle isBranch={isBranch} open={open} onToggle={handleOpenChange} />
+          <Treegrid.Cell classNames='flex items-center'>
+            <TreeItemToggle isBranch={isBranch} open={open} onClick={handleOpenToggle} />
             <TreeItemHeading
-              ref={buttonRef}
-              label={label}
-              icon={icon}
-              className={headingClassName}
               disabled={disabled}
               current={current}
+              label={label}
+              className={headingClassName}
+              icon={icon}
+              iconHue={iconHue}
               onSelect={handleSelect}
+              ref={buttonRef}
             />
-          </div>
+          </Treegrid.Cell>
           {Columns && <Columns item={item} path={path} open={open} menuOpen={menuOpen} setMenuOpen={setMenuOpen} />}
           {instruction && <NaturalTreeItem.DropIndicator instruction={instruction} gap={2} />}
-        </Treegrid.Cell>
+        </div>
       </Treegrid.Row>
       {open &&
-        items.map((item, index) => (
-          <TreeItem
-            key={item.id}
-            item={item}
-            path={path}
-            last={index === items.length - 1}
-            draggable={_draggable}
-            renderColumns={Columns}
-            canDrop={canDrop}
-            onOpenChange={onOpenChange}
-            onSelect={onSelect}
-          />
+        childIds.map((childId, index) => (
+          <TreeItemById key={childId} id={childId} path={path} last={index === childIds.length - 1} {...childProps} />
         ))}
     </>
   );
 };
 
 export const TreeItem = memo(RawTreeItem) as FC<TreeItemProps>;
+
+/** Resolves a child ID to an item via the `item` atom and renders a TreeItem. */
+export type TreeItemByIdProps = Omit<TreeItemProps, 'item'> & { id: string };
+
+const RawTreeItemById = <T extends { id: string } = any>({ id, ...props }: TreeItemByIdProps) => {
+  const { item: itemAtom } = useTree();
+  const item = useAtomValue(itemAtom(id)) as T | undefined;
+  if (!item) {
+    return null;
+  }
+  return <TreeItem item={item} {...props} />;
+};
+
+export const TreeItemById = memo(RawTreeItemById) as FC<TreeItemByIdProps>;