@headless-tree/core 0.0.0-20250224204705 → 0.0.0-20250322153940

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-tree/core",
-  "version": "0.0.0-20250224204705",
+  "version": "0.0.0-20250322153940",
   "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;