@dxos/react-ui-list 0.9.1-main.c7dcc2e112 → 0.10.0

package/src/components/OrderedList/OrderedListRoot.tsx

@@ -17,13 +17,16 @@ import { mx } from '@dxos/ui-theme';
 import {
   type ReorderActive,
   type ReorderListController,
-  type UseListNavigationReturn,
   type UseListDisclosureReturn,
+  type UseListNavigationReturn,
   useListDisclosure,
   useListNavigation,
   useReorderAutoScroll,
   useReorderList,
 } from '../../aspects';
+import { listTheme } from '../List.theme';
+
+const styles = listTheme.styles();
 
 export type ListItemRecord = any;
 
@@ -132,7 +135,7 @@ export const OrderedListRoot = <T extends ListItemRecord>({
 export const OrderedListContent = ({ classNames, children }: ThemedClassName<PropsWithChildren>) => {
   const { navigation } = useOrderedListContext('OrderedList.Content');
   return (
-    <div {...navigation.containerProps} className={mx('flex flex-col', classNames)}>
+    <div {...navigation.containerProps} className={styles.orderedListContent({ class: mx(classNames) })}>
       {children}
     </div>
   );
@@ -158,7 +161,7 @@ export const OrderedListViewport = composable<HTMLDivElement, OrderedListViewpor
   const autoScrollRef = useReorderAutoScroll();
   return (
     <ScrollArea.Root
-      {...composableProps<HTMLDivElement>(rest, { classNames: 'dx-container' })}
+      {...composableProps<HTMLDivElement>(rest, { classNames: styles.orderedListViewport() })}
       {...{ thin, padding, centered }}
       orientation='vertical'
       ref={forwardedRef}

package/src/components/Picker/Picker.tsx

@@ -15,8 +15,8 @@ import React, {
   type ComponentPropsWithRef,
   type ElementType,
   type KeyboardEvent,
-  type MouseEvent as ReactMouseEvent,
   type PropsWithChildren,
+  type MouseEvent as ReactMouseEvent,
   type ReactNode,
   forwardRef,
   useCallback,
@@ -29,6 +29,7 @@ import React, {
 import { type Density, type Elevation, Input, type ThemedClassName, useThemeContext } from '@dxos/react-ui';
 import { mx } from '@dxos/ui-theme';
 
+import { listTheme } from '../List.theme';
 import {
   PickerInputContextProvider,
   PickerItemContextProvider,
@@ -36,6 +37,8 @@ import {
   usePickerItemContext,
 } from './context';
 
+const styles = listTheme.styles();
+
 type ItemData = {
   element: HTMLElement;
   disabled?: boolean;
@@ -46,20 +49,33 @@ type ItemData = {
 // Root
 //
 
-type PickerRootProps = PropsWithChildren<{}>;
+type PickerRootProps = PropsWithChildren<{
+  /**
+   * When the item set changes, snap the highlight back to the first item (command-palette behavior),
+   * instead of only re-selecting when the current selection disappears. Use for type-to-filter lists so
+   * the top result stays highlighted as results update. Does not fire on keyboard navigation (which
+   * changes the selection, not the item set). Defaults to false.
+   */
+  resetSelectionOnChange?: boolean;
+}>;
 
-const PickerRoot = ({ children }: PickerRootProps) => {
+const PickerRoot = ({ children, resetSelectionOnChange = false }: PickerRootProps) => {
   const [selectedValue, setSelectedValue] = useState<string | undefined>(undefined);
   const itemsRef = useRef<Map<string, ItemData>>(new Map());
   // Bumped on every (un)register to retrigger auto-select.
   const [itemVersion, setItemVersion] = useState(0);
+  // Tracks the last-seen item set so a reset fires only when items change, not on selection change.
+  const prevItemVersionRef = useRef(itemVersion);
 
-  // Auto-select first non-disabled item when the current selection is
-  // gone or disabled.
+  // Auto-select the first non-disabled item when the current selection is gone or disabled — or, when
+  // `resetSelectionOnChange`, whenever the item set itself changes.
   useEffect(() => {
+    const itemsChanged = prevItemVersionRef.current !== itemVersion;
+    prevItemVersionRef.current = itemVersion;
+
     const current = selectedValue !== undefined ? itemsRef.current.get(selectedValue) : undefined;
     const isValid = current !== undefined && !current.disabled;
-    if (!isValid && itemsRef.current.size > 0) {
+    if ((!isValid || (resetSelectionOnChange && itemsChanged)) && itemsRef.current.size > 0) {
       const entries = Array.from(itemsRef.current.entries()).filter(([, data]) => !data.disabled);
       if (entries.length > 0) {
         entries.sort(([, a], [, b]) => {
@@ -80,7 +96,7 @@ const PickerRoot = ({ children }: PickerRootProps) => {
         setSelectedValue(undefined);
       }
     }
-  }, [itemVersion, selectedValue]);
+  }, [itemVersion, selectedValue, resetSelectionOnChange]);
 
   const registerItem = useCallback(
     (value: string, element: HTMLElement | null, onSelect: (() => void) | undefined, disabled?: boolean) => {
@@ -321,8 +337,6 @@ const PickerItem = forwardRef<HTMLDivElement, PickerItemProps>(
 
     const Comp: ElementType = asChild ? Slot : 'div';
 
-    // Padding follows `--gutter` to align with sibling `Column.Center`
-    // content; falls back to `0.75rem` when not nested under `Column.Root`.
     return (
       <Comp
         {...props}
@@ -342,11 +356,7 @@ const PickerItem = forwardRef<HTMLDivElement, PickerItemProps>(
         data-value={value}
         // Browser focus stays on the input; highlight is via `aria-selected`.
         tabIndex={-1}
-        className={mx(
-          'dx-hover dx-selected px-[var(--gutter,0.75rem)] py-1 cursor-pointer select-none',
-          disabled && 'opacity-50 cursor-not-allowed',
-          classNames,
-        )}
+        className={styles.pickerItem({ class: mx(disabled && 'opacity-50 cursor-not-allowed', classNames) })}
         onMouseDown={handleMouseDown}
         onClick={handleClick}
       >
@@ -364,6 +374,6 @@ export const Picker = {
   Item: PickerItem,
 };
 
-export type { PickerRootProps, PickerInputProps, PickerItemProps };
+export type { PickerInputProps, PickerItemProps, PickerRootProps };
 
 export { usePickerInputContext, usePickerItemContext } from './context';

package/src/components/Picker/index.ts

@@ -3,4 +3,4 @@
 //
 
 export { Picker, usePickerInputContext, usePickerItemContext } from './Picker';
-export type { PickerRootProps, PickerInputProps, PickerItemProps } from './Picker';
+export type { PickerInputProps, PickerItemProps, PickerRootProps } from './Picker';

package/src/components/Tree/Tree.stories.tsx

@@ -21,9 +21,11 @@ import { type TreeData } from './TreeItem';
 
 random.seed(1234);
 
-const tree = createTree() as TestItem;
+const tree = createTree();
+const groupsTree = createTree(4, 4, { groups: true });
 
-const DefaultStory = ({ draggable }: { draggable?: boolean }) => {
+const DefaultStory = ({ draggable, groups }: { draggable?: boolean; groups?: boolean }) => {
+  const rootTree = groups ? groupsTree : tree;
   const registry = useContext(RegistryContext);
   const stateAtomsRef = useRef(new Map<string, Atom.Writable<{ open: boolean; current: boolean }>>());
 
@@ -43,9 +45,9 @@ const DefaultStory = ({ draggable }: { draggable?: boolean }) => {
       map.set(item.id, item);
       item.items?.forEach(walk);
     };
-    walk(tree);
+    walk(rootTree);
     return map;
-  }, []);
+  }, [rootTree]);
 
   // Build a child IDs map keyed by parent ID.
   const childIdsMap = useMemo(() => {
@@ -61,15 +63,17 @@ const DefaultStory = ({ draggable }: { draggable?: boolean }) => {
     };
     // Root children.
     map.set(
-      tree.id,
-      (tree.items ?? []).map((child) => child.id),
+      rootTree.id,
+      (rootTree.items ?? []).map((child) => child.id),
     );
-    walk(tree);
+    walk(rootTree);
     return map;
-  }, []);
+  }, [rootTree]);
 
+  // Writable so drops can push new child orderings (a derived `Atom.make(() => …)` would snapshot
+  // the initial map and never reflect the reorder).
   const childIdsFamily = useMemo(
-    () => Atom.family((id: string) => Atom.make(() => childIdsMap.get(id) ?? []).pipe(Atom.keepAlive)),
+    () => Atom.family((id: string) => Atom.make<string[]>(childIdsMap.get(id) ?? []).pipe(Atom.keepAlive)),
     [childIdsMap],
   );
 
@@ -91,6 +95,7 @@ const DefaultStory = ({ draggable }: { draggable?: boolean }) => {
             id: parent.id,
             label: parent.name,
             icon: parent.icon,
+            disposition: parent.disposition,
             ...((parent.items?.length ?? 0) > 0 && {
               parentOf: parent.items!.map(({ id }) => id),
               count: parent.items!.length,
@@ -123,13 +128,13 @@ const DefaultStory = ({ draggable }: { draggable?: boolean }) => {
 
   const model: TreeModel<TestItem> = useMemo(
     () => ({
-      childIds: (parentId?: string) => childIdsFamily(parentId ?? tree.id),
+      childIds: (parentId?: string) => childIdsFamily(parentId ?? rootTree.id),
       item: (id: string) => itemFamily(id),
       itemProps: (path: string[]) => itemPropsFamily(path.join('~')),
       itemOpen: (path: string[]) => itemOpenFamily(Path.create(...path)),
       itemCurrent: (path: string[]) => itemCurrentFamily(Path.create(...path)),
     }),
-    [childIdsFamily, itemFamily, itemPropsFamily, itemOpenFamily, itemCurrentFamily],
+    [childIdsFamily, itemFamily, itemPropsFamily, itemOpenFamily, itemCurrentFamily, rootTree.id],
   );
 
   const handleOpenChange = useCallback(
@@ -164,21 +169,36 @@ const DefaultStory = ({ draggable }: { draggable?: boolean }) => {
         const instruction: Instruction | null = extractInstruction(target.data);
         if (instruction !== null) {
           updateState({
-            state: tree,
+            state: rootTree,
             instruction,
             source: source.data as TreeData,
             target: target.data as TreeData,
           });
+
+          // `updateState` mutates the tree in place; push the new child orderings into the
+          // (writable) childIds atoms so the affected branches re-render.
+          const refresh = (item: TestItem) => {
+            registry.set(
+              childIdsFamily(item.id),
+              (item.items ?? []).map((child) => child.id),
+            );
+            item.items?.forEach(refresh);
+          };
+          registry.set(
+            childIdsFamily(rootTree.id),
+            (rootTree.items ?? []).map((child) => child.id),
+          );
+          rootTree.items?.forEach(refresh);
         }
       },
     });
-  }, []);
+  }, [rootTree, childIdsFamily, registry]);
 
   return (
     <Tree
       model={model}
-      id={tree.id}
-      rootId={tree.id}
+      id={rootTree.id}
+      rootId={rootTree.id}
       draggable={draggable}
       renderColumns={() => (
         <div className='flex items-center'>
@@ -210,3 +230,7 @@ export const Draggable: Story = {
     draggable: true,
   },
 };
+
+export const WithGroups: Story = {
+  args: { groups: true },
+};

package/src/components/Tree/Tree.tsx

@@ -1,11 +1,11 @@
 //
 // Copyright 2024 DXOS.org
+//
 
 import { useAtomValue } from '@effect-atom/atom-react';
 import React, { useMemo } from 'react';
 
-import { Treegrid, type TreegridRootProps } from '@dxos/react-ui';
-
+import { Treegrid, type TreegridRootProps } from '../Treegrid';
 import { type TreeModel, TreeProvider } from './TreeContext';
 import { TreeItemById, type TreeItemByIdProps, type TreeItemProps } from './TreeItem';
 
@@ -28,6 +28,16 @@ export type TreeProps<T extends { id: string } = any> = {
     | 'levelOffset'
   >;
 
+/** Renders a single root-level child. */
+const TreeChild = <T extends { id: string } = any>({
+  id,
+  path: parentPath,
+  last,
+  ...childProps
+}: TreeItemByIdProps & { last: boolean }) => {
+  return <TreeItemById id={id} path={parentPath} last={last} {...childProps} />;
+};
+
 export const Tree = <T extends { id: string } = any>({
   classNames,
   model,
@@ -65,7 +75,7 @@ export const Tree = <T extends { id: string } = any>({
     <Treegrid.Root gridTemplateColumns={gridTemplateColumns} classNames={classNames}>
       <TreeProvider value={model}>
         {childIds.map((childId, index) => (
-          <TreeItemById key={childId} id={childId} last={index === childIds.length - 1} {...childProps} />
+          <TreeChild key={childId} id={childId} last={index === childIds.length - 1} {...childProps} />
         ))}
       </TreeProvider>
     </Treegrid.Root>

package/src/components/Tree/TreeContext.tsx

@@ -12,6 +12,8 @@ export type TreeItemDataProps = {
   id: string;
   label: Label;
   parentOf?: string[];
+  /** Pass-through of the node's disposition; the tree uses this to branch render mode (e.g. `'group'` → section header). */
+  disposition?: string;
   /** When `false`, the item cannot be dragged (overrides tree-level `draggable`). */
   draggable?: boolean;
   /** When `false`, the item does not participate as a drop target. */

package/src/components/Tree/TreeDropIndicator.tsx

@@ -0,0 +1,72 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Instruction } from '@atlaskit/pragmatic-drag-and-drop-hitbox/tree-item';
+import React, { type CSSProperties, type HTMLAttributes } from 'react';
+
+// Tree-item instruction indicator. Atlaskit's `react-drop-indicator` ships `box`/`list-item`
+// renderers but no `tree-item` one, so this stays a small Tailwind port (theme-aware via
+// `bg-accent-bg`). See `react-ui-list/AUDIT.md` D4.
+// https://github.com/atlassian/pragmatic-drag-and-drop/blob/main/packages/hitbox/constellation/index/about.mdx#tree-item
+
+type InstructionType = Exclude<Instruction, { type: 'instruction-blocked' }>['type'];
+type Orientation = 'sibling' | 'child';
+
+const edgeToOrientationMap: Record<InstructionType, Orientation> = {
+  'reorder-above': 'sibling',
+  'reorder-below': 'sibling',
+  'make-child': 'child',
+  'reparent': 'child',
+};
+
+const orientationStyles: Record<Orientation, HTMLAttributes<HTMLElement>['className']> = {
+  sibling:
+    'h-(--line-thickness) left-(--horizontal-indent) right-0 bg-accent-bg before:left-(--negative-terminal-size)',
+  child: 'inset-0 border-[length:var(--line-thickness)] before:invisible',
+};
+
+const instructionStyles: Record<InstructionType, HTMLAttributes<HTMLElement>['className']> = {
+  'reorder-above': 'top-(--line-offset) before:top-(--offset-terminal)',
+  'reorder-below': 'bottom-(--line-offset) before:bottom-(--offset-terminal)',
+  'make-child': 'border-accent-bg',
+  'reparent': '',
+};
+
+const strokeSize = 2;
+const terminalSize = 8;
+const offsetToAlignTerminalWithLine = (strokeSize - terminalSize) / 2;
+
+/** Props for {@link TreeDropIndicator}. */
+export type TreeDropIndicatorProps = {
+  instruction: Instruction;
+  gap?: number;
+};
+
+/** Themed drop indicator for a tree-item pragmatic-dnd `Instruction` (sibling reorder / make-child). */
+export const TreeDropIndicator = ({ instruction, gap = 0 }: TreeDropIndicatorProps) => {
+  const lineOffset = `calc(-0.5 * (${gap}px + ${strokeSize}px))`;
+  const isBlocked = instruction.type === 'instruction-blocked';
+  const desiredInstruction = isBlocked ? instruction.desired : instruction;
+  const orientation = edgeToOrientationMap[desiredInstruction.type];
+  if (isBlocked) {
+    return null;
+  }
+
+  return (
+    <div
+      style={
+        {
+          '--line-thickness': `${strokeSize}px`,
+          '--line-offset': `${lineOffset}`,
+          '--terminal-size': `${terminalSize}px`,
+          '--terminal-radius': `${terminalSize / 2}px`,
+          '--negative-terminal-size': `-${terminalSize}px`,
+          '--offset-terminal': `${offsetToAlignTerminalWithLine}px`,
+          '--horizontal-indent': `${desiredInstruction.currentLevel * desiredInstruction.indentPerLevel + 4}px`,
+        } as CSSProperties
+      }
+      className={`absolute z-10 pointer-events-none before:w-(--terminal-size) before:h-(--terminal-size) box-border before:absolute before:border-[length:--line-thickness] before:border-solid before:border-accent-bg before:rounded-full ${orientationStyles[orientation]} ${instructionStyles[desiredInstruction.type]}`}
+    ></div>
+  );
+};

package/src/components/Tree/TreeItem.tsx

@@ -25,7 +25,7 @@ import React, {
 } from 'react';
 
 import { invariant } from '@dxos/invariant';
-import { TreeItem as NaturalTreeItem, Treegrid, TREEGRID_PARENT_OF_SEPARATOR } from '@dxos/react-ui';
+import { type Label, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import {
   ghostFocusWithin,
   ghostHover,
@@ -35,14 +35,30 @@ import {
   mx,
 } from '@dxos/ui-theme';
 
+import { Treegrid, TREEGRID_PARENT_OF_SEPARATOR } from '../Treegrid';
 import { DEFAULT_INDENTATION, paddingIndentation } from './helpers';
 import { useTree } from './TreeContext';
+import { TreeDropIndicator } from './TreeDropIndicator';
 import { TreeItemHeading } from './TreeItemHeading';
 import { TreeItemToggle } from './TreeItemToggle';
 
 const hoverableDescriptionIcons =
   '[--icons-color:inherit] hover-hover:[--icons-color:var(--description-text)] hover-hover:hover:[--icons-color:inherit] focus-within:[--icons-color:inherit]';
 
+/** Renders a section-group label spanning the full tree row. Used when a node has `disposition === 'group'`. */
+const NavTreeSectionHeader = ({ label }: { label: Label }) => {
+  const { t } = useTranslation();
+  return (
+    <div
+      role='heading'
+      aria-level={2}
+      className='col-[tree-row] pl-7 pt-3 pb-0.5 text-xs uppercase tracking-widest text-subdued hover:text-description select-none'
+    >
+      {toLocalizedString(label, t)}
+    </div>
+  );
+};
+
 type TreeItemDragState = 'idle' | 'dragging' | 'preview' | 'parent-of-instruction';
 
 export const TreeDataSchema = Schema.Struct({
@@ -110,6 +126,7 @@ const RawTreeItem = <T extends { id: string } = any>({
   const {
     id,
     parentOf,
+    disposition,
     draggable: itemDraggable,
     droppable: itemDroppable,
     label,
@@ -145,7 +162,7 @@ const RawTreeItem = <T extends { id: string } = any>({
   const nativeDragText = id;
 
   useEffect(() => {
-    if (!draggableProp) {
+    if (!draggableProp || (!isItemDraggable && !isItemDroppable)) {
       return;
     }
 
@@ -300,6 +317,29 @@ const RawTreeItem = <T extends { id: string } = any>({
     onSelect,
   };
 
+  // Group nodes render as a flat section header with their children always expanded at the same visual level.
+  // Suppress the header entirely when there are no children to avoid orphaned section labels.
+  if (disposition === 'group') {
+    if (childIds.length === 0) {
+      return null;
+    }
+    return (
+      <>
+        <NavTreeSectionHeader label={label} />
+        {childIds.map((childId, index) => (
+          <TreeItemById
+            key={childId}
+            id={childId}
+            path={path}
+            last={index === childIds.length - 1}
+            levelOffset={levelOffset + 1}
+            {...childProps}
+          />
+        ))}
+      </>
+    );
+  }
+
   return (
     <>
       <Treegrid.Row
@@ -347,7 +387,7 @@ const RawTreeItem = <T extends { id: string } = any>({
             />
           </Treegrid.Cell>
           {Columns && <Columns item={item} path={path} open={open} menuOpen={menuOpen} setMenuOpen={setMenuOpen} />}
-          {instruction && <NaturalTreeItem.DropIndicator instruction={instruction} gap={2} />}
+          {instruction && <TreeDropIndicator instruction={instruction} gap={2} />}
         </div>
       </Treegrid.Row>
       {open &&

package/src/components/Tree/TreeItemHeading.tsx

@@ -88,7 +88,7 @@ export const TreeItemHeading = memo(
 const CountBadge = ({ count, modifiedCount }: Pick<TreeItemHeadingProps, 'count' | 'modifiedCount'>) => {
   if (typeof modifiedCount === 'number' && modifiedCount > 0) {
     return (
-      <Tag palette='rose' classNames='shrink-0 text-center [min-inline-size:1.5rem] tabular-nums'>
+      <Tag hue='rose' classNames='shrink-0 text-center [min-inline-size:1.5rem] tabular-nums'>
         {modifiedCount}
       </Tag>
     );
@@ -96,7 +96,7 @@ const CountBadge = ({ count, modifiedCount }: Pick<TreeItemHeadingProps, 'count'
 
   if (typeof count === 'number') {
     return (
-      <Tag palette='neutral' classNames='shrink-0 text-center [min-inline-size:1.5rem] tabular-nums'>
+      <Tag hue='neutral' classNames='shrink-0 text-center [min-inline-size:1.5rem] tabular-nums'>
         {count}
       </Tag>
     );

package/src/components/Tree/testing.ts

@@ -15,6 +15,7 @@ export type TestItem = {
   id: string;
   name: string;
   icon?: string;
+  disposition?: string;
   items: TestItem[];
 };
 
@@ -25,20 +26,24 @@ export const TestItemSchema = Schema.Struct({
   items: Schema.mutable(Schema.Array(Schema.suspend((): Schema.Schema<TestItem> => TestItemSchema))),
 });
 
-export const createTree = (n = 4, d = 4): TestItem => ({
-  id: random.string.uuid(),
-  name: random.commerce.productName(),
-  icon:
-    d === 3
-      ? undefined
-      : random.helpers.arrayElement([
-          'ph--planet--regular',
-          'ph--sailboat--regular',
-          'ph--house--regular',
-          'ph--gear--regular',
-        ]),
-  items: d > 0 ? random.helpers.multiple(() => createTree(n, d - 1), { count: n }) : [],
-});
+export const createTree = (n = 4, d = 4, { groups = false }: { groups?: boolean } = {}): TestItem => {
+  const children = d > 0 ? random.helpers.multiple(() => createTree(n, d - 1), { count: n }) : [];
+  return {
+    id: random.string.uuid(),
+    name: random.commerce.productName(),
+    icon:
+      d === 3
+        ? undefined
+        : random.helpers.arrayElement([
+            'ph--planet--regular',
+            'ph--sailboat--regular',
+            'ph--house--regular',
+            'ph--gear--regular',
+          ]),
+    // When groups is true, mark every direct child as a group section header (no icon).
+    items: groups ? children.map((child) => ({ ...child, disposition: 'group', icon: undefined })) : children,
+  };
+};
 
 const removeItem = (tree: TestItem, source: TreeData) => {
   const parent = getTestItem(tree, source.path.slice(1, -1));