@headless-tree/core 0.0.14 → 1.0.0

package/lib/esm/utilities/insert-items-at-target.d.ts

@@ -1,3 +1,3 @@
 import { ItemInstance } from "../types/core";
-import { DropTarget } from "../features/drag-and-drop/types";
-export declare const insertItemsAtTarget: <T>(itemIds: string[], target: DropTarget<T>, onChangeChildren: (item: ItemInstance<T>, newChildrenIds: string[]) => void) => void;
+import { DragTarget } from "../features/drag-and-drop/types";
+export declare const insertItemsAtTarget: <T>(itemIds: string[], target: DragTarget<T>, onChangeChildren: (item: ItemInstance<T>, newChildrenIds: string[]) => Promise<void> | void) => Promise<void>;

package/lib/esm/utilities/insert-items-at-target.js

@@ -1,11 +1,21 @@
-export const insertItemsAtTarget = (itemIds, target, onChangeChildren) => {
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+export const insertItemsAtTarget = (itemIds, target, onChangeChildren) => __awaiter(void 0, void 0, void 0, function* () {
+    yield target.item.getTree().waitForItemChildrenLoaded(target.item.getId());
+    const oldChildrenIds = target.item
+        .getTree()
+        .retrieveChildrenIds(target.item.getId());
     // add moved items to new common parent, if dropped onto parent
-    if (target.childIndex === null) {
-        const newChildren = [
-            ...target.item.getChildren().map((item) => item.getId()),
-            ...itemIds,
-        ];
-        onChangeChildren(target.item, newChildren);
+    if (!("childIndex" in target)) {
+        const newChildren = [...oldChildrenIds, ...itemIds];
+        yield onChangeChildren(target.item, newChildren);
         if (target.item && "updateCachedChildrenIds" in target.item) {
             target.item.updateCachedChildrenIds(newChildren);
         }
@@ -13,15 +23,14 @@ export const insertItemsAtTarget = (itemIds, target, onChangeChildren) => {
         return;
     }
     // add moved items to new common parent, if dropped between siblings
-    const oldChildren = target.item.getChildren();
     const newChildren = [
-        ...oldChildren.slice(0, target.insertionIndex).map((item) => item.getId()),
+        ...oldChildrenIds.slice(0, target.insertionIndex),
         ...itemIds,
-        ...oldChildren.slice(target.insertionIndex).map((item) => item.getId()),
+        ...oldChildrenIds.slice(target.insertionIndex),
     ];
-    onChangeChildren(target.item, newChildren);
+    yield onChangeChildren(target.item, newChildren);
     if (target.item && "updateCachedChildrenIds" in target.item) {
         target.item.updateCachedChildrenIds(newChildren);
     }
     target.item.getTree().rebuildTree();
-};
+});

package/lib/esm/utilities/remove-items-from-parents.d.ts

@@ -1,2 +1,2 @@
 import { ItemInstance } from "../types/core";
-export declare const removeItemsFromParents: <T>(movedItems: ItemInstance<T>[], onChangeChildren: (item: ItemInstance<T>, newChildrenIds: string[]) => void) => void;
+export declare const removeItemsFromParents: <T>(movedItems: ItemInstance<T>[], onChangeChildren: (item: ItemInstance<T>, newChildrenIds: string[]) => void | Promise<void>) => Promise<void>;

package/lib/esm/utilities/remove-items-from-parents.js

@@ -1,4 +1,13 @@
-export const removeItemsFromParents = (movedItems, onChangeChildren) => {
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+export const removeItemsFromParents = (movedItems, onChangeChildren) => __awaiter(void 0, void 0, void 0, function* () {
     const movedItemsIds = movedItems.map((item) => item.getId());
     const uniqueParents = [
         ...new Set(movedItems.map((item) => item.getParent())),
@@ -9,11 +18,11 @@ export const removeItemsFromParents = (movedItems, onChangeChildren) => {
             const newChildren = siblings
                 .filter((sibling) => !movedItemsIds.includes(sibling.getId()))
                 .map((i) => i.getId());
-            onChangeChildren(parent, newChildren);
+            yield onChangeChildren(parent, newChildren);
             if (parent && "updateCachedChildrenIds" in parent) {
                 parent === null || parent === void 0 ? void 0 : parent.updateCachedChildrenIds(newChildren);
             }
         }
     }
     movedItems[0].getTree().rebuildTree();
-};
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-tree/core",
-  "version": "0.0.14",
+  "version": "1.0.0",
   "type": "module",
   "main": "lib/cjs/index.js",
   "module": "lib/esm/index.js",
@@ -21,7 +21,7 @@
   "license": "MIT",
   "devDependencies": {
     "jsdom": "^26.0.0",
-    "typescript": "^5.7.3",
+    "typescript": "^5.7.2",
     "vitest": "^3.0.3"
   }
 }

package/src/core/core.spec.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { TestTree } from "../test-utils/test-tree";
+import { buildStaticInstance } from "./build-static-instance";
 
 declare module "../types/core" {
   export interface TreeInstance<T> {
@@ -17,6 +18,36 @@ const factory = TestTree.default({});
 
 describe("core-feature/prop-memoization", () => {
   factory.forSuits((tree) => {
+    describe("rebuilds item instance", () => {
+      it("rebuilds when explicitly invoked", async () => {
+        const instanceBuilder = vi.fn().mockImplementation(buildStaticInstance);
+        const testTree = await tree
+          .with({ instanceBuilder })
+          .createTestCaseTree();
+        expect(instanceBuilder).toBeCalled();
+        instanceBuilder.mockClear();
+        testTree.instance.rebuildTree();
+        // if tree structure doesnt mutate, only root tree item is rebuilt actually
+        expect(instanceBuilder).toBeCalled();
+      });
+
+      it("rebuilds when config changes with new expanded items", async () => {
+        const instanceBuilder = vi.fn().mockImplementation(buildStaticInstance);
+        const testTree = await tree
+          .with({ instanceBuilder })
+          .createTestCaseTree();
+        expect(instanceBuilder).toBeCalled();
+        instanceBuilder.mockClear();
+        testTree.instance.setConfig((oldCfg) => ({
+          ...oldCfg,
+          state: {
+            expandedItems: ["x4"],
+          },
+        }));
+        expect(instanceBuilder).toBeCalled();
+      });
+    });
+
     describe("calls prev in correct order", () => {
       it("tree instance with overwrite marks, order 1", async () => {
         const testTree = await tree

package/src/core/create-tree.ts

@@ -137,6 +137,7 @@ export const createTree = <T>(
         // Not necessary, since I think the subupdate below keeps the state fresh anyways?
         // state = typeof updater === "function" ? updater(state) : updater;
         config.setState?.(state); // TODO this cant be right... This doesnt allow external state updates
+        // TODO this is never used, remove
       },
       applySubStateUpdate: <K extends keyof TreeState<any>>(
         {},
@@ -157,10 +158,20 @@ export const createTree = <T>(
       },
       getConfig: () => config,
       setConfig: (_, updater) => {
-        config = typeof updater === "function" ? updater(config) : updater;
-
-        if (config.state) {
-          state = { ...state, ...config.state };
+        const newConfig =
+          typeof updater === "function" ? updater(config) : updater;
+        const hasChangedExpandedItems =
+          newConfig.state?.expandedItems &&
+          newConfig.state?.expandedItems !== state.expandedItems;
+        config = newConfig;
+
+        if (newConfig.state) {
+          state = { ...state, ...newConfig.state };
+        }
+        if (hasChangedExpandedItems) {
+          // if expanded items where changed from the outside
+          rebuildItemMeta();
+          config.setState?.(state);
         }
       },
       getItemInstance: ({}, itemId) => itemInstancesMap[itemId],
@@ -186,7 +197,6 @@ export const createTree = <T>(
       getHotkeyPresets: () => hotkeyPresets,
     },
     itemInstance: {
-      // TODO just change to a getRef method that memoizes, maybe as part of getProps
       registerElement: ({ itemId, item }, element) => {
         if (itemElementsMap[itemId] === element) {
           return;

package/src/features/async-data-loader/async-data-loader.spec.ts

@@ -41,11 +41,17 @@ describe("core-feature/selections", () => {
 
   describe("calls handlers", () => {
     it("updates setLoadingItems", async () => {
-      const setLoadingItems = tree.mockedHandler("setLoadingItems");
+      const setLoadingItemChildrens = tree.mockedHandler(
+        "setLoadingItemChildrens",
+      );
+      const setLoadingItemData = tree.mockedHandler("setLoadingItemData");
       tree.do.selectItem("x12");
-      expect(setLoadingItems).toHaveBeenCalledWith(["x12"]);
+      expect(setLoadingItemChildrens).toHaveBeenCalledWith(["x12"]);
+      expect(setLoadingItemData).not.toHaveBeenCalled();
       await tree.resolveAsyncVisibleItems();
-      expect(setLoadingItems).toHaveBeenCalledWith([]);
+      expect(setLoadingItemChildrens).toHaveBeenCalledWith([]);
+      expect(setLoadingItemData).toHaveBeenCalledWith(["x121"]);
+      expect(setLoadingItemData).toHaveBeenCalledWith([]);
     });
 
     it("calls onLoadedItem", async () => {
@@ -76,7 +82,7 @@ describe("core-feature/selections", () => {
       `${id}3`,
       `${id}4`,
     ]);
-    const suiteTree = tree.with({ asyncDataLoader: { getItem, getChildren } });
+    const suiteTree = tree.with({ dataLoader: { getItem, getChildren } });
     suiteTree.resetBeforeEach();
 
     it("invalidates item data on item instance", async () => {
@@ -119,6 +125,4 @@ describe("core-feature/selections", () => {
       expect(getChildren).toHaveBeenCalledTimes(1);
     });
   });
-
-  describe.todo("getChildrenWithData");
 });

package/src/features/async-data-loader/feature.ts

@@ -1,28 +1,57 @@
 import { FeatureImplementation } from "../../types/core";
-import { AsyncDataLoaderRef } from "./types";
+import { AsyncDataLoaderDataRef } from "./types";
 import { makeStateUpdater } from "../../utils";
 
 export const asyncDataLoaderFeature: FeatureImplementation = {
   key: "async-data-loader",
 
   getInitialState: (initialState) => ({
-    loadingItems: [],
+    loadingItemData: [],
+    loadingItemChildrens: [],
     ...initialState,
   }),
 
   getDefaultConfig: (defaultConfig, tree) => ({
-    setLoadingItems: makeStateUpdater("loadingItems", tree),
+    setLoadingItemData: makeStateUpdater("loadingItemData", tree),
+    setLoadingItemChildrens: makeStateUpdater("loadingItemChildrens", tree),
     ...defaultConfig,
   }),
 
   stateHandlerNames: {
-    loadingItems: "setLoadingItems",
+    loadingItemData: "setLoadingItemData",
+    loadingItemChildrens: "setLoadingItemChildrens",
   },
 
   treeInstance: {
+    waitForItemDataLoaded: async ({ tree }, itemId) => {
+      tree.retrieveItemData(itemId);
+      if (!tree.getState().loadingItemData.includes(itemId)) {
+        return;
+      }
+      await new Promise<void>((resolve) => {
+        const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
+        dataRef.current.awaitingItemDataLoading ??= {};
+        dataRef.current.awaitingItemDataLoading[itemId] ??= [];
+        dataRef.current.awaitingItemDataLoading[itemId].push(resolve);
+      });
+    },
+
+    waitForItemChildrenLoaded: async ({ tree }, itemId) => {
+      tree.retrieveChildrenIds(itemId);
+      if (!tree.getState().loadingItemChildrens.includes(itemId)) {
+        return;
+      }
+      await new Promise<void>((resolve) => {
+        const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
+        dataRef.current.awaitingItemChildrensLoading ??= {};
+        dataRef.current.awaitingItemChildrensLoading[itemId] ??= [];
+        dataRef.current.awaitingItemChildrensLoading[itemId].push(resolve);
+      });
+    },
+
     retrieveItemData: ({ tree }, itemId) => {
       const config = tree.getConfig();
-      const dataRef = tree.getDataRef<AsyncDataLoaderRef>();
+      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
       dataRef.current.itemData ??= {};
       dataRef.current.childrenIds ??= {};
 
@@ -30,18 +59,25 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
         return dataRef.current.itemData[itemId];
       }
 
-      if (!tree.getState().loadingItems.includes(itemId)) {
-        tree.applySubStateUpdate("loadingItems", (loadingItems) => [
-          ...loadingItems,
+      if (!tree.getState().loadingItemData.includes(itemId)) {
+        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
+          ...loadingItemData,
           itemId,
         ]);
-        config.asyncDataLoader?.getItem(itemId).then((item) => {
+
+        (async () => {
+          const item = await config.dataLoader.getItem(itemId);
           dataRef.current.itemData[itemId] = item;
           config.onLoadedItem?.(itemId, item);
-          tree.applySubStateUpdate("loadingItems", (loadingItems) =>
-            loadingItems.filter((id) => id !== itemId),
+          tree.applySubStateUpdate("loadingItemData", (loadingItemData) =>
+            loadingItemData.filter((id) => id !== itemId),
           );
-        });
+
+          dataRef.current.awaitingItemDataLoading?.[itemId].forEach((cb) =>
+            cb(),
+          );
+          delete dataRef.current.awaitingItemDataLoading?.[itemId];
+        })();
       }
 
       return config.createLoadingItemData?.() ?? null;
@@ -49,46 +85,37 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
 
     retrieveChildrenIds: ({ tree }, itemId) => {
       const config = tree.getConfig();
-      const dataRef = tree.getDataRef<AsyncDataLoaderRef>();
-      dataRef.current.itemData ??= {};
+      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
       dataRef.current.childrenIds ??= {};
       if (dataRef.current.childrenIds[itemId]) {
         return dataRef.current.childrenIds[itemId];
       }
 
-      if (tree.getState().loadingItems.includes(itemId)) {
+      if (tree.getState().loadingItemChildrens.includes(itemId)) {
         return [];
       }
 
-      tree.applySubStateUpdate("loadingItems", (loadingItems) => [
-        ...loadingItems,
-        itemId,
-      ]);
-
-      if (config.asyncDataLoader?.getChildrenWithData) {
-        config.asyncDataLoader?.getChildrenWithData(itemId).then((children) => {
-          for (const { id, data } of children) {
-            dataRef.current.itemData[id] = data;
-            config.onLoadedItem?.(id, data);
-          }
-          const childrenIds = children.map(({ id }) => id);
-          dataRef.current.childrenIds[itemId] = childrenIds;
-          config.onLoadedChildren?.(itemId, childrenIds);
-          tree.applySubStateUpdate("loadingItems", (loadingItems) =>
-            loadingItems.filter((id) => id !== itemId),
-          );
-          tree.rebuildTree();
-        });
-      } else {
-        config.asyncDataLoader?.getChildren(itemId).then((childrenIds) => {
-          dataRef.current.childrenIds[itemId] = childrenIds;
-          config.onLoadedChildren?.(itemId, childrenIds);
-          tree.applySubStateUpdate("loadingItems", (loadingItems) =>
-            loadingItems.filter((id) => id !== itemId),
-          );
-          tree.rebuildTree();
-        });
-      }
+      tree.applySubStateUpdate(
+        "loadingItemChildrens",
+        (loadingItemChildrens) => [...loadingItemChildrens, itemId],
+      );
+
+      (async () => {
+        const childrenIds = await config.dataLoader.getChildren(itemId);
+        dataRef.current.childrenIds[itemId] = childrenIds;
+        config.onLoadedChildren?.(itemId, childrenIds);
+        tree.applySubStateUpdate(
+          "loadingItemChildrens",
+          (loadingItemChildrens) =>
+            loadingItemChildrens.filter((id) => id !== itemId),
+        );
+        tree.rebuildTree();
+
+        dataRef.current.awaitingItemChildrensLoading?.[itemId]?.forEach((cb) =>
+          cb(),
+        );
+        delete dataRef.current.awaitingItemChildrensLoading?.[itemId];
+      })();
 
       return [];
     },
@@ -96,19 +123,20 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
 
   itemInstance: {
     isLoading: ({ tree, item }) =>
-      tree.getState().loadingItems.includes(item.getItemMeta().itemId),
+      tree.getState().loadingItemData.includes(item.getItemMeta().itemId) ||
+      tree.getState().loadingItemChildrens.includes(item.getItemMeta().itemId),
     invalidateItemData: ({ tree, itemId }) => {
-      const dataRef = tree.getDataRef<AsyncDataLoaderRef>();
+      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
       delete dataRef.current.itemData?.[itemId];
       tree.retrieveItemData(itemId);
     },
     invalidateChildrenIds: ({ tree, itemId }) => {
-      const dataRef = tree.getDataRef<AsyncDataLoaderRef>();
+      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
       delete dataRef.current.childrenIds?.[itemId];
       tree.retrieveChildrenIds(itemId);
     },
     updateCachedChildrenIds: ({ tree, itemId }, childrenIds) => {
-      const dataRef = tree.getDataRef<AsyncDataLoaderRef>();
+      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
       dataRef.current.childrenIds[itemId] = childrenIds;
       tree.rebuildTree();
     },

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

@@ -1,33 +1,40 @@
 import { SetStateFn } from "../../types/core";
 import { SyncDataLoaderFeatureDef } from "../sync-data-loader/types";
 
-export type AsyncTreeDataLoader<T> = {
-  getItem: (itemId: string) => Promise<T>;
-  getChildren: (itemId: string) => Promise<string[]>;
-  getChildrenWithData?: (itemId: string) => Promise<{ id: string; data: T }[]>;
-};
+type AwaitingLoaderCallbacks = Record<string, (() => void)[]>;
 
-export type AsyncDataLoaderRef<T = any> = {
+export interface AsyncDataLoaderDataRef<T = any> {
   itemData: Record<string, T>;
   childrenIds: Record<string, string[]>;
-};
+  awaitingItemDataLoading: AwaitingLoaderCallbacks;
+  awaitingItemChildrensLoading: AwaitingLoaderCallbacks;
+}
 
 /**
  * @category Async Data Loader/General
  * */
 export type AsyncDataLoaderFeatureDef<T> = {
   state: {
-    loadingItems: string[];
+    loadingItemData: string[];
+    loadingItemChildrens: string[];
   };
   config: {
     rootItemId: string;
+
+    /** Will be called when HT retrieves item data for an item whose item data is asynchronously being loaded.
+     * Can be used to create placeholder data to use for rendering the tree item while it is loaded. If not defined,
+     * the tree item data will be null. */
     createLoadingItemData?: () => T;
-    setLoadingItems?: SetStateFn<string[]>;
+
+    setLoadingItemData?: SetStateFn<string[]>;
+    setLoadingItemChildrens?: SetStateFn<string[]>;
     onLoadedItem?: (itemId: string, item: T) => void;
     onLoadedChildren?: (itemId: string, childrenIds: string[]) => void;
-    asyncDataLoader?: AsyncTreeDataLoader<T>;
   };
-  treeInstance: SyncDataLoaderFeatureDef<T>["treeInstance"];
+  treeInstance: SyncDataLoaderFeatureDef<T>["treeInstance"] & {
+    waitForItemDataLoaded: (itemId: string) => Promise<void>;
+    waitForItemChildrenLoaded: (itemId: string) => Promise<void>;
+  };
   itemInstance: SyncDataLoaderFeatureDef<T>["itemInstance"] & {
     /** Invalidate fetched data for item, and triggers a refetch and subsequent rerender if the item is visible */
     invalidateItemData: () => void;