@headless-tree/core 0.0.0-20250508233916 → 0.0.0-20250509212452

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

@@ -1,7 +1,69 @@
-import { FeatureImplementation } from "../../types/core";
+import { FeatureImplementation, TreeInstance } from "../../types/core";
 import { AsyncDataLoaderDataRef } from "./types";
 import { makeStateUpdater } from "../../utils";
 
+const getDataRef = <T>(tree: TreeInstance<T>) => {
+  const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
+  dataRef.current.itemData ??= {};
+  dataRef.current.childrenIds ??= {};
+  return dataRef;
+};
+
+const loadItemData = async <T>(tree: TreeInstance<T>, itemId: string) => {
+  const config = tree.getConfig();
+  const dataRef = getDataRef(tree);
+
+  const item = await config.dataLoader.getItem(itemId);
+  dataRef.current.itemData[itemId] = item;
+  config.onLoadedItem?.(itemId, item);
+  tree.applySubStateUpdate("loadingItemData", (loadingItemData) =>
+    loadingItemData.filter((id) => id !== itemId),
+  );
+
+  dataRef.current.awaitingItemDataLoading?.[itemId].forEach((cb) => cb());
+  delete dataRef.current.awaitingItemDataLoading?.[itemId];
+  return item;
+};
+
+const loadChildrenIds = async <T>(tree: TreeInstance<T>, itemId: string) => {
+  const config = tree.getConfig();
+  const dataRef = getDataRef(tree);
+  let childrenIds: string[];
+
+  // TODO is folder check?
+
+  if ("getChildrenWithData" in config.dataLoader) {
+    const children = await config.dataLoader.getChildrenWithData(itemId);
+    childrenIds = children.map((c) => c.id);
+    dataRef.current.childrenIds[itemId] = childrenIds;
+    children.forEach(({ id, data }) => {
+      dataRef.current.itemData[id] = data;
+      config.onLoadedItem?.(id, data);
+      dataRef.current.awaitingItemDataLoading?.[id].forEach((cb) => cb());
+      delete dataRef.current.awaitingItemDataLoading?.[id];
+    });
+
+    config.onLoadedChildren?.(itemId, childrenIds);
+    tree.rebuildTree();
+    tree.applySubStateUpdate("loadingItemData", (loadingItemData) =>
+      loadingItemData.filter((id) => !childrenIds.includes(id)),
+    );
+  } else {
+    childrenIds = await config.dataLoader.getChildren(itemId);
+    dataRef.current.childrenIds[itemId] = childrenIds;
+    config.onLoadedChildren?.(itemId, childrenIds);
+    tree.rebuildTree();
+  }
+
+  tree.applySubStateUpdate("loadingItemChildrens", (loadingItemChildrens) =>
+    loadingItemChildrens.filter((id) => id !== itemId),
+  );
+
+  dataRef.current.awaitingItemChildrensLoading?.[itemId]?.forEach((cb) => cb());
+  delete dataRef.current.awaitingItemChildrensLoading?.[itemId];
+  return childrenIds;
+};
+
 export const asyncDataLoaderFeature: FeatureImplementation = {
   key: "async-data-loader",
 
@@ -37,6 +99,7 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
     },
 
     waitForItemChildrenLoaded: async ({ tree }, itemId) => {
+      // TODO replace inner implementation with load() fns
       tree.retrieveChildrenIds(itemId);
       if (!tree.getState().loadingItemChildrens.includes(itemId)) {
         return;
@@ -49,50 +112,46 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
       });
     },
 
-    retrieveItemData: ({ tree }, itemId) => {
+    loadItemData: async ({ tree }, itemId) => {
+      return (
+        getDataRef(tree).current.itemData[itemId] ??
+        (await loadItemData(tree, itemId))
+      );
+    },
+    loadChildrenIds: async ({ tree }, itemId) => {
+      return (
+        getDataRef(tree).current.childrenIds[itemId] ??
+        (await loadChildrenIds(tree, itemId))
+      );
+    },
+
+    retrieveItemData: ({ tree }, itemId, skipFetch = false) => {
       const config = tree.getConfig();
-      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
-      dataRef.current.itemData ??= {};
-      dataRef.current.childrenIds ??= {};
+      const dataRef = getDataRef(tree);
 
       if (dataRef.current.itemData[itemId]) {
         return dataRef.current.itemData[itemId];
       }
 
-      if (!tree.getState().loadingItemData.includes(itemId)) {
+      if (!tree.getState().loadingItemData.includes(itemId) && !skipFetch) {
         tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
           ...loadingItemData,
           itemId,
         ]);
 
-        (async () => {
-          const item = await config.dataLoader.getItem(itemId);
-          dataRef.current.itemData[itemId] = item;
-          config.onLoadedItem?.(itemId, item);
-          tree.applySubStateUpdate("loadingItemData", (loadingItemData) =>
-            loadingItemData.filter((id) => id !== itemId),
-          );
-
-          dataRef.current.awaitingItemDataLoading?.[itemId].forEach((cb) =>
-            cb(),
-          );
-          delete dataRef.current.awaitingItemDataLoading?.[itemId];
-        })();
+        loadItemData(tree, itemId);
       }
 
       return config.createLoadingItemData?.() ?? null;
     },
 
-    retrieveChildrenIds: ({ tree }, itemId) => {
-      const config = tree.getConfig();
-      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
-      dataRef.current.itemData ??= {};
-      dataRef.current.childrenIds ??= {};
+    retrieveChildrenIds: ({ tree }, itemId, skipFetch = false) => {
+      const dataRef = getDataRef(tree);
       if (dataRef.current.childrenIds[itemId]) {
         return dataRef.current.childrenIds[itemId];
       }
 
-      if (tree.getState().loadingItemChildrens.includes(itemId)) {
+      if (tree.getState().loadingItemChildrens.includes(itemId) || skipFetch) {
         return [];
       }
 
@@ -101,41 +160,7 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
         (loadingItemChildrens) => [...loadingItemChildrens, itemId],
       );
 
-      (async () => {
-        if ("getChildrenWithData" in config.dataLoader) {
-          const children = await config.dataLoader.getChildrenWithData(itemId);
-          const childrenIds = children.map((c) => c.id);
-          dataRef.current.childrenIds[itemId] = childrenIds;
-          children.forEach(({ id, data }) => {
-            dataRef.current.itemData[id] = data;
-            config.onLoadedItem?.(id, data);
-            dataRef.current.awaitingItemDataLoading?.[id].forEach((cb) => cb());
-            delete dataRef.current.awaitingItemDataLoading?.[id];
-          });
-
-          config.onLoadedChildren?.(itemId, childrenIds);
-          tree.rebuildTree();
-          tree.applySubStateUpdate("loadingItemData", (loadingItemData) =>
-            loadingItemData.filter((id) => !childrenIds.includes(id)),
-          );
-        } else {
-          const childrenIds = await config.dataLoader.getChildren(itemId);
-          dataRef.current.childrenIds[itemId] = childrenIds;
-          config.onLoadedChildren?.(itemId, childrenIds);
-          tree.rebuildTree();
-        }
-
-        tree.applySubStateUpdate(
-          "loadingItemChildrens",
-          (loadingItemChildrens) =>
-            loadingItemChildrens.filter((id) => id !== itemId),
-        );
-
-        dataRef.current.awaitingItemChildrensLoading?.[itemId]?.forEach((cb) =>
-          cb(),
-        );
-        delete dataRef.current.awaitingItemChildrensLoading?.[itemId];
-      })();
+      loadChildrenIds(tree, itemId);
 
       return [];
     },
@@ -145,15 +170,25 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
     isLoading: ({ tree, item }) =>
       tree.getState().loadingItemData.includes(item.getItemMeta().itemId) ||
       tree.getState().loadingItemChildrens.includes(item.getItemMeta().itemId),
-    invalidateItemData: ({ tree, itemId }) => {
-      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
-      delete dataRef.current.itemData?.[itemId];
-      tree.retrieveItemData(itemId);
+    invalidateItemData: async ({ tree, itemId }, optimistic) => {
+      if (!optimistic) {
+        delete getDataRef(tree).current.itemData?.[itemId];
+        tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
+          ...loadingItemData,
+          itemId,
+        ]);
+      }
+      await loadItemData(tree, itemId);
     },
-    invalidateChildrenIds: ({ tree, itemId }) => {
-      const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();
-      delete dataRef.current.childrenIds?.[itemId];
-      tree.retrieveChildrenIds(itemId);
+    invalidateChildrenIds: async ({ tree, itemId }, optimistic) => {
+      if (!optimistic) {
+        delete getDataRef(tree).current.childrenIds?.[itemId];
+        tree.applySubStateUpdate(
+          "loadingItemChildrens",
+          (loadingItemChildrens) => [...loadingItemChildrens, itemId],
+        );
+      }
+      await loadChildrenIds(tree, itemId);
     },
     updateCachedChildrenIds: ({ tree, itemId }, childrenIds) => {
       const dataRef = tree.getDataRef<AsyncDataLoaderDataRef>();

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

@@ -32,13 +32,24 @@ export type AsyncDataLoaderFeatureDef<T> = {
     onLoadedChildren?: (itemId: string, childrenIds: string[]) => void;
   };
   treeInstance: SyncDataLoaderFeatureDef<T>["treeInstance"] & {
+    /** @deprecated use loadItemData instead */
     waitForItemDataLoaded: (itemId: string) => Promise<void>;
+    /** @deprecated use loadChildrenIds instead */
     waitForItemChildrenLoaded: (itemId: string) => Promise<void>;
+    loadItemData: (itemId: string) => Promise<T>;
+    loadChildrenIds: (itemId: string) => Promise<string[]>;
   };
   itemInstance: SyncDataLoaderFeatureDef<T>["itemInstance"] & {
-    /** Invalidate fetched data for item, and triggers a refetch and subsequent rerender if the item is visible */
-    invalidateItemData: () => void;
-    invalidateChildrenIds: () => void;
+    /** Invalidate fetched data for item, and triggers a refetch and subsequent rerender if the item is visible
+     * @param optimistic If true, the item will not trigger a state update on `loadingItemData`, and
+     * the tree will continue to display the old data until the new data has loaded. */
+    invalidateItemData: (optimistic?: boolean) => Promise<void>;
+
+    /** Invalidate fetched children ids for item, and triggers a refetch and subsequent rerender if the item is visible
+     * @param optimistic If true, the item will not trigger a state update on `loadingItemChildrens`, and
+     * the tree will continue to display the old data until the new data has loaded. */
+    invalidateChildrenIds: (optimistic?: boolean) => Promise<void>;
+
     updateCachedChildrenIds: (childrenIds: string[]) => void;
     isLoading: () => boolean;
   };

package/src/features/checkboxes/feature.ts

@@ -0,0 +1,150 @@
+import { FeatureImplementation, TreeInstance } from "../../types/core";
+import { makeStateUpdater } from "../../utils";
+import { CheckedState } from "./types";
+
+/*
+ * Cases for checking:
+ * - Check an unchecked item in an unchecked or indeterminate folder
+ * - Check an explicitly unchecked item in a checked folder
+ * - Check an unchecked folder in an unchecked or indeterminate folder
+ *
+ * Cases for unchecking:
+ * - Uncheck a checked item in an indeterminate folder
+ * - Uncheck an explicitly unchecked item in an checked folder
+ */
+
+const fetchAllDescendants = async <T>(
+  tree: TreeInstance<T>,
+  itemId: string,
+): Promise<string[]> => {
+  const children = await tree.loadChildrenIds(itemId);
+  return [
+    itemId,
+    ...(
+      await Promise.all(
+        children.map((child) => fetchAllDescendants(tree, child)),
+      )
+    ).flat(),
+  ];
+};
+
+const getAllLoadedDescendants = <T>(
+  tree: TreeInstance<T>,
+  itemId: string,
+): string[] => {
+  const children = tree.retrieveChildrenIds(itemId, true);
+  return [
+    itemId,
+    ...children.map((child) => getAllLoadedDescendants(tree, child)).flat(),
+  ];
+};
+
+export const checkboxesFeature: FeatureImplementation = {
+  key: "checkboxes",
+
+  overwrites: ["selection"],
+
+  getInitialState: (initialState) => ({
+    checkedItems: [],
+    ...initialState,
+  }),
+
+  getDefaultConfig: (defaultConfig, tree) => ({
+    setCheckedItems: makeStateUpdater("checkedItems", tree),
+    ...defaultConfig,
+  }),
+
+  stateHandlerNames: {
+    checkedItems: "setCheckedItems",
+  },
+
+  treeInstance: {
+    setCheckedItems: ({ tree }, checkedItems) => {
+      tree.applySubStateUpdate("checkedItems", checkedItems);
+    },
+  },
+
+  itemInstance: {
+    getCheckboxProps: ({ item, itemId }) => {
+      const checkedState = item.getCheckedState();
+      // console.log("prop", itemId, checkedState);
+      return {
+        onChange: item.toggleCheckedState,
+        checked: checkedState === CheckedState.Checked,
+        ref: (r: any) => {
+          if (r) {
+            // console.log("ref", itemId, checkedState);
+            r.indeterminate = checkedState === CheckedState.Indeterminate;
+          }
+        },
+      };
+    },
+
+    toggleCheckedState: async ({ item }) => {
+      if (item.getCheckedState() === CheckedState.Checked) {
+        await item.setUnchecked();
+      } else {
+        await item.setChecked();
+      }
+    },
+
+    getCheckedState: ({ item, tree, itemId }) => {
+      // TODO checkedcache
+      const { checkedItems } = tree.getState();
+
+      if (checkedItems.includes(itemId)) {
+        return CheckedState.Checked;
+      }
+
+      if (item.isFolder()) {
+        const descendants = getAllLoadedDescendants(tree, itemId);
+        console.log("descendants of ", itemId, descendants);
+        if (descendants.every((d) => checkedItems.includes(d))) {
+          return CheckedState.Checked;
+        }
+        if (descendants.some((d) => checkedItems.includes(d))) {
+          return CheckedState.Indeterminate;
+        }
+      }
+
+      // if (
+      //   item.isFolder() &&
+      //   checkedItems.some((checkedItem) =>
+      //     tree.getItemInstance(checkedItem)?.isDescendentOf(itemId),
+      //   )
+      // ) {
+      //   // TODO for every descendent, not every checked item
+      //   return checkedItems.every((checkedItem) =>
+      //     tree.getItemInstance(checkedItem)?.isDescendentOf(itemId),
+      //   )
+      //     ? CheckedState.Checked
+      //     : CheckedState.Indeterminate;
+      // }
+
+      return CheckedState.Unchecked;
+    },
+
+    setChecked: async ({ item, tree, itemId }) => {
+      if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+        tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
+      } else {
+        const descendants = await fetchAllDescendants(tree, itemId);
+        tree.applySubStateUpdate("checkedItems", (items) => [
+          ...items,
+          ...descendants,
+        ]);
+      }
+    },
+
+    setUnchecked: async ({ item, tree, itemId }) => {
+      if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+        tree.applySubStateUpdate("checkedItems", (items) =>
+          items.filter((id) => id !== itemId),
+        );
+      } else {
+        await tree.loadChildrenIds(itemId);
+        item.getChildren().forEach((item) => item.setUnchecked());
+      }
+    },
+  },
+};

package/src/features/checkboxes/types.ts

@@ -0,0 +1,28 @@
+import { SetStateFn } from "../../types/core";
+
+export enum CheckedState {
+  Checked = "checked",
+  Unchecked = "unchecked",
+  Indeterminate = "indeterminate",
+}
+
+export type CheckboxesFeatureDef<T> = {
+  state: {
+    checkedItems: string[];
+  };
+  config: {
+    setCheckedItems?: SetStateFn<string[]>;
+    canCheckFolders?: boolean;
+  };
+  treeInstance: {
+    setCheckedItems: (checkedItems: string[]) => void;
+  };
+  itemInstance: {
+    setChecked: () => Promise<void>;
+    setUnchecked: () => Promise<void>;
+    toggleCheckedState: () => Promise<void>;
+    getCheckedState: () => CheckedState;
+    getCheckboxProps: () => Record<string, any>;
+  };
+  hotkeys: never;
+};

package/src/features/main/types.ts

@@ -36,6 +36,8 @@ export type MainFeatureDef<T = any> = {
       stateName: K,
       updater: Updater<TreeState<T>[K]>,
     ) => void;
+    /** @internal */
+    buildItemInstance: (itemId: string) => ItemInstance<T>;
     setState: SetStateFn<TreeState<T>>;
     getState: () => TreeState<T>;
     setConfig: SetStateFn<TreeConfig<T>>;

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

@@ -47,6 +47,9 @@ export const syncDataLoaderFeature: FeatureImplementation = {
         (c) => c.data,
       );
     },
+
+    loadItemData: ({ tree }, itemId) => tree.retrieveItemData(itemId),
+    loadChildrenIds: ({ tree }, itemId) => tree.retrieveChildrenIds(itemId),
   },
 
   itemInstance: {

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

@@ -17,8 +17,8 @@ export type SyncDataLoaderFeatureDef<T> = {
     dataLoader: TreeDataLoader<T>;
   };
   treeInstance: {
-    retrieveItemData: (itemId: string) => T;
-    retrieveChildrenIds: (itemId: string) => string[];
+    retrieveItemData: (itemId: string, skipFetch?: boolean) => T;
+    retrieveChildrenIds: (itemId: string, skipFetch?: boolean) => string[];
   };
   itemInstance: {
     isLoading: () => boolean;

package/src/index.ts

@@ -6,6 +6,7 @@ export { MainFeatureDef, InstanceBuilder } from "./features/main/types";
 export * from "./features/drag-and-drop/types";
 export * from "./features/keyboard-drag-and-drop/types";
 export * from "./features/selection/types";
+export * from "./features/checkboxes/types";
 export * from "./features/async-data-loader/types";
 export * from "./features/sync-data-loader/types";
 export * from "./features/hotkeys-core/types";
@@ -15,6 +16,7 @@ export * from "./features/expand-all/types";
 export * from "./features/prop-memoization/types";
 
 export * from "./features/selection/feature";
+export * from "./features/checkboxes/feature";
 export * from "./features/hotkeys-core/feature";
 export * from "./features/async-data-loader/feature";
 export * from "./features/sync-data-loader/feature";

package/src/types/core.ts

@@ -13,6 +13,7 @@ import { RenamingFeatureDef } from "../features/renaming/types";
 import { ExpandAllFeatureDef } from "../features/expand-all/types";
 import { PropMemoizationFeatureDef } from "../features/prop-memoization/types";
 import { KeyboardDragAndDropFeatureDef } from "../features/keyboard-drag-and-drop/types";
+import { CheckboxesFeatureDef } from "../features/checkboxes/types";
 
 export type Updater<T> = T | ((old: T) => T);
 export type SetStateFn<T> = (updaterOrValue: Updater<T>) => void;
@@ -53,6 +54,7 @@ export type RegisteredFeatures<T> =
   | MainFeatureDef<T>
   | TreeFeatureDef<T>
   | SelectionFeatureDef<T>
+  | CheckboxesFeatureDef<T>
   | DragAndDropFeatureDef<T>
   | KeyboardDragAndDropFeatureDef<T>
   | HotkeysCoreFeatureDef<T>