@headless-tree/core 1.3.0 → 1.5.0

package/src/features/drag-and-drop/feature.ts

@@ -1,17 +1,51 @@
-import { FeatureImplementation } from "../../types/core";
+import {
+  FeatureImplementation,
+  type ItemInstance,
+  type TreeInstance,
+} from "../../types/core";
 import { DndDataRef, DragLineData, DragTarget } from "./types";
 import {
+  PlacementType,
+  type TargetPlacement,
   canDrop,
   getDragCode,
   getDragTarget,
+  getTargetPlacement,
   isOrderedDragTarget,
 } from "./utils";
 import { makeStateUpdater } from "../../utils";
 
+const handleAutoOpenFolder = (
+  dataRef: { current: DndDataRef },
+  tree: TreeInstance<any>,
+  item: ItemInstance<any>,
+  placement: TargetPlacement,
+) => {
+  const { openOnDropDelay } = tree.getConfig();
+  const dragCode = dataRef.current.lastDragCode;
+
+  if (
+    !openOnDropDelay ||
+    !item.isFolder() ||
+    item.isExpanded() ||
+    placement.type !== PlacementType.MakeChild
+  ) {
+    return;
+  }
+  clearTimeout(dataRef.current.autoExpandTimeout);
+  dataRef.current.autoExpandTimeout = setTimeout(() => {
+    if (
+      dragCode !== dataRef.current.lastDragCode ||
+      !dataRef.current.lastAllowDrop
+    )
+      return;
+    item.expand();
+  }, openOnDropDelay);
+};
+
 const defaultCanDropForeignDragObject = () => false;
 export const dragAndDropFeature: FeatureImplementation = {
   key: "drag-and-drop",
-  deps: ["selection"],
 
   getDefaultConfig: (defaultConfig, tree) => ({
     canDrop: (_, target) => target.item.isFolder(),
@@ -22,6 +56,7 @@ export const dragAndDropFeature: FeatureImplementation = {
         : () => false,
     setDndState: makeStateUpdater("dnd", tree),
     canReorder: true,
+    openOnDropDelay: 800,
     ...defaultConfig,
   }),
 
@@ -74,7 +109,7 @@ export const dragAndDropFeature: FeatureImplementation = {
         }
       }
 
-      const bb = targetItem.getElement()?.getBoundingClientRect();
+      const bb = targetItem?.getElement()?.getBoundingClientRect();
 
       if (bb) {
         return {
@@ -149,12 +184,14 @@ export const dragAndDropFeature: FeatureImplementation = {
       onDragEnter: (e: DragEvent) => e.preventDefault(),
 
       onDragStart: (e: DragEvent) => {
-        const selectedItems = tree.getSelectedItems();
+        const selectedItems = tree.getSelectedItems
+          ? tree.getSelectedItems()
+          : [tree.getFocusedItem()];
         const items = selectedItems.includes(item) ? selectedItems : [item];
         const config = tree.getConfig();
 
         if (!selectedItems.includes(item)) {
-          tree.setSelectedItems([item.getItemMeta().itemId]);
+          tree.setSelectedItems?.([item.getItemMeta().itemId]);
         }
 
         if (!(config.canDrag?.(items) ?? true)) {
@@ -185,7 +222,9 @@ export const dragAndDropFeature: FeatureImplementation = {
       onDragOver: (e: DragEvent) => {
         e.stopPropagation(); // don't bubble up to container dragover
         const dataRef = tree.getDataRef<DndDataRef>();
-        const nextDragCode = getDragCode(e, item, tree);
+        const placement = getTargetPlacement(e, item, tree, true);
+        const nextDragCode = getDragCode(item, placement);
+
         if (nextDragCode === dataRef.current.lastDragCode) {
           if (dataRef.current.lastAllowDrop) {
             e.preventDefault();
@@ -195,6 +234,8 @@ export const dragAndDropFeature: FeatureImplementation = {
         dataRef.current.lastDragCode = nextDragCode;
         dataRef.current.lastDragEnter = Date.now();
 
+        handleAutoOpenFolder(dataRef, tree, item, placement);
+
         const target = getDragTarget(e, item, tree);
 
         if (
@@ -260,14 +301,21 @@ export const dragAndDropFeature: FeatureImplementation = {
         e.stopPropagation();
         const dataRef = tree.getDataRef<DndDataRef>();
         const target = getDragTarget(e, item, tree);
+        const draggedItems = tree.getState().dnd?.draggedItems;
+        const isValidDrop = canDrop(e.dataTransfer, target, tree);
 
-        if (!canDrop(e.dataTransfer, target, tree)) {
+        tree.applySubStateUpdate("dnd", {
+          draggedItems: undefined,
+          draggingOverItem: undefined,
+          dragTarget: undefined,
+        });
+
+        if (!isValidDrop) {
           return;
         }
 
         e.preventDefault();
         const config = tree.getConfig();
-        const draggedItems = tree.getState().dnd?.draggedItems;
 
         dataRef.current.lastDragCode = undefined;
 
@@ -284,6 +332,13 @@ export const dragAndDropFeature: FeatureImplementation = {
       return target ? target.item.getId() === item.getId() : false;
     },
 
+    isUnorderedDragTarget: ({ tree, item }) => {
+      const target = tree.getDragTarget();
+      return target
+        ? !isOrderedDragTarget(target) && target.item.getId() === item.getId()
+        : false;
+    },
+
     isDragTargetAbove: ({ tree, item }) => {
       const target = tree.getDragTarget();
 

package/src/features/drag-and-drop/types.ts

@@ -4,6 +4,7 @@ export interface DndDataRef {
   lastDragCode?: string;
   lastAllowDrop?: boolean;
   lastDragEnter?: number;
+  autoExpandTimeout?: any;
   windowDragEndListener?: () => void;
 }
 
@@ -93,6 +94,9 @@ export type DragAndDropFeatureDef<T> = {
       target: DragTarget<T>,
     ) => void | Promise<void>;
     onCompleteForeignDrop?: (items: ItemInstance<T>[]) => void;
+
+    /** When dragging for this many ms on a closed folder, the folder will automatically open. Set to zero to disable. */
+    openOnDropDelay?: number;
   };
   treeInstance: {
     getDragTarget: () => DragTarget<T> | null;
@@ -104,7 +108,13 @@ export type DragAndDropFeatureDef<T> = {
     ) => Record<string, any>;
   };
   itemInstance: {
+    /** Checks if the user is dragging in a way which makes this the new parent of the dragged items, either by dragging on top of
+     * this item, or by dragging inbetween children of this item. See @{isUnorderedDragTarget} if the latter is undesirable. */
     isDragTarget: () => boolean;
+
+    /** As opposed to @{isDragTarget}, this will not be true if the target is inbetween children of this item. This returns only true
+     * if the user is dragging directly on top of this item. */
+    isUnorderedDragTarget: () => boolean;
     isDragTargetAbove: () => boolean;
     isDragTargetBelow: () => boolean;
     isDraggingOver: () => boolean;

package/src/features/drag-and-drop/utils.ts

@@ -7,14 +7,14 @@ export enum ItemDropCategory {
   LastInGroup,
 }
 
-enum PlacementType {
+export enum PlacementType {
   ReorderAbove,
   ReorderBelow,
   MakeChild,
   Reparent,
 }
 
-type TargetPlacement =
+export type TargetPlacement =
   | {
       type:
         | PlacementType.ReorderAbove
@@ -95,7 +95,7 @@ export const getInsertionIndex = <T>(
   return childIndex - numberOfDragItemsBeforeTarget;
 };
 
-const getTargetPlacement = (
+export const getTargetPlacement = (
   e: any,
   item: ItemInstance<any>,
   tree: TreeInstance<any>,
@@ -153,11 +153,9 @@ const getTargetPlacement = (
 };
 
 export const getDragCode = (
-  e: any,
   item: ItemInstance<any>,
-  tree: TreeInstance<any>,
+  placement: TargetPlacement,
 ) => {
-  const placement = getTargetPlacement(e, item, tree, true);
   return [
     item.getId(),
     placement.type,
@@ -222,6 +220,10 @@ export const getDragTarget = (
     canBecomeSibling &&
     placement.type !== PlacementType.MakeChild
   ) {
+    if (draggedItems?.some((item) => item.isDescendentOf(parent.getId()))) {
+      // dropping on itself should be illegal, return item, canDrop will then return false
+      return itemTarget;
+    }
     return parentTarget;
   }
 

package/src/features/hotkeys-core/feature.ts

@@ -13,6 +13,7 @@ const specialKeys: Record<string, RegExp> = {
   minus: /^(NumpadSubtract|Minus)$/,
   control: /^(ControlLeft|ControlRight)$/,
   shift: /^(ShiftLeft|ShiftRight)$/,
+  metaorcontrol: /^(MetaLeft|MetaRight|ControlLeft|ControlRight)$/,
 };
 
 const testHotkeyMatch = (

package/src/features/keyboard-drag-and-drop/feature.ts

@@ -191,7 +191,9 @@ export const keyboardDragAndDropFeature: FeatureImplementation = {
       preventDefault: true,
       isEnabled: (tree) => !tree.getState().dnd,
       handler: (_, tree) => {
-        const selectedItems = tree.getSelectedItems();
+        const selectedItems = tree.getSelectedItems?.() ?? [
+          tree.getFocusedItem(),
+        ];
         const focusedItem = tree.getFocusedItem();
 
         tree.startKeyboardDrag(

package/src/features/main/types.ts

@@ -10,6 +10,11 @@ import {
 } from "../../types/core";
 import { ItemMeta } from "../tree/types";
 
+export interface TreeDataRef {
+  isMounted?: boolean;
+  waitingForMount?: (() => void)[];
+}
+
 export type InstanceTypeMap = {
   itemInstance: ItemInstance<any>;
   treeInstance: TreeInstance<any>;
@@ -49,6 +54,10 @@ export type MainFeatureDef<T = any> = {
     /* @internal */
     getHotkeyPresets: () => HotkeysConfig<T>;
     rebuildTree: () => void;
+    /** @deprecated Experimental feature, might get removed or changed in the future. */
+    scheduleRebuildTree: () => void;
+    /** @internal */
+    setMounted: (isMounted: boolean) => void;
   };
   itemInstance: {
     registerElement: (element: HTMLElement | null) => void;

package/src/features/sync-data-loader/types.ts

@@ -18,7 +18,13 @@ export type SyncDataLoaderFeatureDef<T> = {
   };
   treeInstance: {
     retrieveItemData: (itemId: string) => T;
-    retrieveChildrenIds: (itemId: string) => string[];
+
+    /** Retrieve children Ids. If an async data loader is used, skipFetch is set to true, and children have not been retrieved
+     * yet for this item, this will initiate fetching the children, and return an empty array. Once the children have loaded,
+     * a rerender will be triggered.
+     * @param skipFetch - Defaults to false.
+     */
+    retrieveChildrenIds: (itemId: string, skipFetch?: boolean) => string[];
   };
   itemInstance: {
     isLoading: () => boolean;

package/src/mddocs-entry.ts

@@ -10,6 +10,7 @@ import { SyncDataLoaderFeatureDef } from "./features/sync-data-loader/types";
 import { TreeFeatureDef } from "./features/tree/types";
 import { PropMemoizationFeatureDef } from "./features/prop-memoization/types";
 import { KeyboardDragAndDropFeatureDef } from "./features/keyboard-drag-and-drop/types";
+import type { CheckboxesFeatureDef } from "./features/checkboxes/types";
 
 export * from ".";
 
@@ -167,3 +168,15 @@ export type TreeFeatureTreeInstance<T> = TreeFeatureDef<T>["treeInstance"];
 /** @interface */
 export type TreeFeatureItemInstance<T> = TreeFeatureDef<T>["itemInstance"];
 export type TreeFeatureHotkeys<T> = TreeFeatureDef<T>["hotkeys"];
+
+/** @interface */
+export type CheckboxesFeatureConfig<T> = CheckboxesFeatureDef<T>["config"];
+/** @interface */
+export type CheckboxesFeatureState<T> = CheckboxesFeatureDef<T>["state"];
+/** @interface */
+export type CheckboxesFeatureTreeInstance<T> =
+  CheckboxesFeatureDef<T>["treeInstance"];
+/** @interface */
+export type CheckboxesFeatureItemInstance<T> =
+  CheckboxesFeatureDef<T>["itemInstance"];
+export type CheckboxesFeatureHotkeys<T> = CheckboxesFeatureDef<T>["hotkeys"];

package/src/test-utils/test-tree-do.ts

@@ -135,4 +135,10 @@ export class TestTreeDo<T> {
       "function called with inconsistent parameters",
     ).toBeOneOf([0, 1]);
   }
+
+  async awaitNextTick() {
+    await new Promise((r) => {
+      setTimeout(r);
+    });
+  }
 }

package/src/test-utils/test-tree.ts

@@ -78,6 +78,7 @@ export class TestTree<T = string> {
   get instance() {
     if (!this.treeInstance) {
       this.treeInstance = createTree(this.config);
+      this.treeInstance.setMounted(true);
       this.treeInstance.rebuildTree();
     }
     return this.treeInstance;
@@ -87,10 +88,9 @@ export class TestTree<T = string> {
 
   static async resolveAsyncLoaders() {
     do {
+      await vi.advanceTimersToNextTimerAsync();
       TestTree.asyncLoaderResolvers.shift()?.();
-      await new Promise<void>((r) => {
-        setTimeout(r);
-      });
+      await vi.advanceTimersToNextTimerAsync();
     } while (TestTree.asyncLoaderResolvers.length);
   }
 
@@ -101,6 +101,17 @@ export class TestTree<T = string> {
     await TestTree.resolveAsyncLoaders();
   }
 
+  async runWhileResolvingItems(cb: () => Promise<void>) {
+    const interval = setInterval(() => {
+      TestTree.resolveAsyncLoaders();
+    }, 5);
+    try {
+      await cb();
+    } finally {
+      clearInterval(interval);
+    }
+  }
+
   static default(config: Partial<TreeConfig<string>>) {
     return new TestTree({
       rootItemId: "x",

package/src/types/core.ts

@@ -93,11 +93,11 @@ type MayReturnNull<T extends (...x: any[]) => any> = (
   ...args: Parameters<T>
 ) => ReturnType<T> | null;
 
-export type ItemInstanceOpts<Key extends keyof ItemInstance<any>> = {
-  item: ItemInstance<any>;
-  tree: TreeInstance<any>;
+export type ItemInstanceOpts<T, Key extends keyof ItemInstance<any>> = {
+  item: ItemInstance<T>;
+  tree: TreeInstance<T>;
   itemId: string;
-  prev?: MayReturnNull<ItemInstance<any>[Key]>;
+  prev?: MayReturnNull<ItemInstance<T>[Key]>;
 };
 
 export type TreeInstanceOpts<Key extends keyof TreeInstance<any>> = {
@@ -131,7 +131,7 @@ export type FeatureImplementation<T = any> = {
 
   itemInstance?: {
     [key in keyof ItemInstance<T>]?: (
-      opts: ItemInstanceOpts<key>,
+      opts: ItemInstanceOpts<T, key>,
       ...args: Parameters<ItemInstance<T>[key]>
     ) => void;
   };