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

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @headless-tree/core
 
-## 0.0.0-20250509160455
+## 0.0.0-20250509212452
 
 ### Minor Changes
 

package/lib/cjs/core/create-tree.js

@@ -100,6 +100,15 @@ const createTree = (initialConfig) => {
                 const externalStateSetter = config[stateHandlerNames[stateName]];
                 externalStateSetter === null || externalStateSetter === void 0 ? void 0 : externalStateSetter(state[stateName]);
             },
+            buildItemInstance: ({}, itemId) => {
+                const [instance, finalizeInstance] = buildInstance(features, "itemInstance", (instance) => ({
+                    item: instance,
+                    tree: treeInstance,
+                    itemId,
+                }));
+                finalizeInstance();
+                return instance;
+            },
             // TODO rebuildSubTree: (itemId: string) => void;
             rebuildTree: () => {
                 var _a;

package/lib/cjs/features/async-data-loader/feature.js

@@ -29,14 +29,17 @@ const loadItemData = (tree, itemId) => __awaiter(void 0, void 0, void 0, functio
     tree.applySubStateUpdate("loadingItemData", (loadingItemData) => loadingItemData.filter((id) => id !== itemId));
     (_b = dataRef.current.awaitingItemDataLoading) === null || _b === void 0 ? void 0 : _b[itemId].forEach((cb) => cb());
     (_c = dataRef.current.awaitingItemDataLoading) === null || _c === void 0 ? true : delete _c[itemId];
+    return item;
 });
 const loadChildrenIds = (tree, itemId) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c, _d, _e;
     const config = tree.getConfig();
     const dataRef = getDataRef(tree);
+    let childrenIds;
+    // TODO is folder check?
     if ("getChildrenWithData" in config.dataLoader) {
         const children = yield config.dataLoader.getChildrenWithData(itemId);
-        const childrenIds = children.map((c) => c.id);
+        childrenIds = children.map((c) => c.id);
         dataRef.current.childrenIds[itemId] = childrenIds;
         children.forEach(({ id, data }) => {
             var _a, _b, _c;
@@ -50,7 +53,7 @@ const loadChildrenIds = (tree, itemId) => __awaiter(void 0, void 0, void 0, func
         tree.applySubStateUpdate("loadingItemData", (loadingItemData) => loadingItemData.filter((id) => !childrenIds.includes(id)));
     }
     else {
-        const childrenIds = yield config.dataLoader.getChildren(itemId);
+        childrenIds = yield config.dataLoader.getChildren(itemId);
         dataRef.current.childrenIds[itemId] = childrenIds;
         (_b = config.onLoadedChildren) === null || _b === void 0 ? void 0 : _b.call(config, itemId, childrenIds);
         tree.rebuildTree();
@@ -58,6 +61,7 @@ const loadChildrenIds = (tree, itemId) => __awaiter(void 0, void 0, void 0, func
     tree.applySubStateUpdate("loadingItemChildrens", (loadingItemChildrens) => loadingItemChildrens.filter((id) => id !== itemId));
     (_d = (_c = dataRef.current.awaitingItemChildrensLoading) === null || _c === void 0 ? void 0 : _c[itemId]) === null || _d === void 0 ? void 0 : _d.forEach((cb) => cb());
     (_e = dataRef.current.awaitingItemChildrensLoading) === null || _e === void 0 ? true : delete _e[itemId];
+    return childrenIds;
 });
 exports.asyncDataLoaderFeature = {
     key: "async-data-loader",
@@ -83,6 +87,7 @@ exports.asyncDataLoaderFeature = {
             });
         }),
         waitForItemChildrenLoaded: (_a, itemId_1) => __awaiter(void 0, [_a, itemId_1], void 0, function* ({ tree }, itemId) {
+            // TODO replace inner implementation with load() fns
             tree.retrieveChildrenIds(itemId);
             if (!tree.getState().loadingItemChildrens.includes(itemId)) {
                 return;
@@ -96,14 +101,22 @@ exports.asyncDataLoaderFeature = {
                 dataRef.current.awaitingItemChildrensLoading[itemId].push(resolve);
             });
         }),
-        retrieveItemData: ({ tree }, itemId) => {
+        loadItemData: (_a, itemId_1) => __awaiter(void 0, [_a, itemId_1], void 0, function* ({ tree }, itemId) {
+            var _b;
+            return ((_b = getDataRef(tree).current.itemData[itemId]) !== null && _b !== void 0 ? _b : (yield loadItemData(tree, itemId)));
+        }),
+        loadChildrenIds: (_a, itemId_1) => __awaiter(void 0, [_a, itemId_1], void 0, function* ({ tree }, itemId) {
+            var _b;
+            return ((_b = getDataRef(tree).current.childrenIds[itemId]) !== null && _b !== void 0 ? _b : (yield loadChildrenIds(tree, itemId)));
+        }),
+        retrieveItemData: ({ tree }, itemId, skipFetch = false) => {
             var _a, _b;
             const config = tree.getConfig();
             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,
@@ -112,12 +125,12 @@ exports.asyncDataLoaderFeature = {
             }
             return (_b = (_a = config.createLoadingItemData) === null || _a === void 0 ? void 0 : _a.call(config)) !== null && _b !== void 0 ? _b : null;
         },
-        retrieveChildrenIds: ({ tree }, itemId) => {
+        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 [];
             }
             tree.applySubStateUpdate("loadingItemChildrens", (loadingItemChildrens) => [...loadingItemChildrens, itemId]);

package/lib/cjs/features/async-data-loader/types.d.ts

@@ -27,8 +27,12 @@ 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

package/lib/cjs/features/checkboxes/feature.d.ts

@@ -0,0 +1,2 @@
+import { FeatureImplementation } from "../../types/core";
+export declare const checkboxesFeature: FeatureImplementation;

package/lib/cjs/features/checkboxes/feature.js

@@ -0,0 +1,128 @@
+"use strict";
+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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkboxesFeature = void 0;
+const utils_1 = require("../../utils");
+const types_1 = require("./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 = (tree, itemId) => __awaiter(void 0, void 0, void 0, function* () {
+    const children = yield tree.loadChildrenIds(itemId);
+    return [
+        itemId,
+        ...(yield Promise.all(children.map((child) => fetchAllDescendants(tree, child)))).flat(),
+    ];
+});
+const getAllLoadedDescendants = (tree, itemId) => {
+    const children = tree.retrieveChildrenIds(itemId, true);
+    return [
+        itemId,
+        ...children.map((child) => getAllLoadedDescendants(tree, child)).flat(),
+    ];
+};
+exports.checkboxesFeature = {
+    key: "checkboxes",
+    overwrites: ["selection"],
+    getInitialState: (initialState) => (Object.assign({ checkedItems: [] }, initialState)),
+    getDefaultConfig: (defaultConfig, tree) => (Object.assign({ setCheckedItems: (0, utils_1.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 === types_1.CheckedState.Checked,
+                ref: (r) => {
+                    if (r) {
+                        // console.log("ref", itemId, checkedState);
+                        r.indeterminate = checkedState === types_1.CheckedState.Indeterminate;
+                    }
+                },
+            };
+        },
+        toggleCheckedState: (_a) => __awaiter(void 0, [_a], void 0, function* ({ item }) {
+            if (item.getCheckedState() === types_1.CheckedState.Checked) {
+                yield item.setUnchecked();
+            }
+            else {
+                yield item.setChecked();
+            }
+        }),
+        getCheckedState: ({ item, tree, itemId }) => {
+            // TODO checkedcache
+            const { checkedItems } = tree.getState();
+            if (checkedItems.includes(itemId)) {
+                return types_1.CheckedState.Checked;
+            }
+            if (item.isFolder()) {
+                const descendants = getAllLoadedDescendants(tree, itemId);
+                console.log("descendants of ", itemId, descendants);
+                if (descendants.every((d) => checkedItems.includes(d))) {
+                    return types_1.CheckedState.Checked;
+                }
+                if (descendants.some((d) => checkedItems.includes(d))) {
+                    return types_1.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 types_1.CheckedState.Unchecked;
+        },
+        setChecked: (_a) => __awaiter(void 0, [_a], void 0, function* ({ item, tree, itemId }) {
+            if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+                tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
+            }
+            else {
+                const descendants = yield fetchAllDescendants(tree, itemId);
+                tree.applySubStateUpdate("checkedItems", (items) => [
+                    ...items,
+                    ...descendants,
+                ]);
+            }
+        }),
+        setUnchecked: (_a) => __awaiter(void 0, [_a], void 0, function* ({ item, tree, itemId }) {
+            if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+                tree.applySubStateUpdate("checkedItems", (items) => items.filter((id) => id !== itemId));
+            }
+            else {
+                yield tree.loadChildrenIds(itemId);
+                item.getChildren().forEach((item) => item.setUnchecked());
+            }
+        }),
+    },
+};

package/lib/cjs/features/checkboxes/types.d.ts

@@ -0,0 +1,26 @@
+import { SetStateFn } from "../../types/core";
+export declare 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/lib/cjs/features/checkboxes/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckedState = void 0;
+var CheckedState;
+(function (CheckedState) {
+    CheckedState["Checked"] = "checked";
+    CheckedState["Unchecked"] = "unchecked";
+    CheckedState["Indeterminate"] = "indeterminate";
+})(CheckedState || (exports.CheckedState = CheckedState = {}));

package/lib/cjs/features/main/types.d.ts

@@ -17,6 +17,8 @@ export type MainFeatureDef<T = any> = {
     treeInstance: {
         /** @internal */
         applySubStateUpdate: <K extends keyof TreeState<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/lib/cjs/features/sync-data-loader/feature.js

@@ -40,6 +40,8 @@ exports.syncDataLoaderFeature = {
             }
             return unpromise(dataLoader.getChildrenWithData(itemId)).map((c) => c.data);
         },
+        loadItemData: ({ tree }, itemId) => tree.retrieveItemData(itemId),
+        loadChildrenIds: ({ tree }, itemId) => tree.retrieveChildrenIds(itemId),
     },
     itemInstance: {
         isLoading: () => false,

package/lib/cjs/features/sync-data-loader/types.d.ts

@@ -18,8 +18,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/lib/cjs/index.d.ts

@@ -5,6 +5,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";
@@ -13,6 +14,7 @@ export * from "./features/renaming/types";
 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/lib/cjs/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./features/tree/types"), exports);
 __exportStar(require("./features/drag-and-drop/types"), exports);
 __exportStar(require("./features/keyboard-drag-and-drop/types"), exports);
 __exportStar(require("./features/selection/types"), exports);
+__exportStar(require("./features/checkboxes/types"), exports);
 __exportStar(require("./features/async-data-loader/types"), exports);
 __exportStar(require("./features/sync-data-loader/types"), exports);
 __exportStar(require("./features/hotkeys-core/types"), exports);
@@ -28,6 +29,7 @@ __exportStar(require("./features/renaming/types"), exports);
 __exportStar(require("./features/expand-all/types"), exports);
 __exportStar(require("./features/prop-memoization/types"), exports);
 __exportStar(require("./features/selection/feature"), exports);
+__exportStar(require("./features/checkboxes/feature"), exports);
 __exportStar(require("./features/hotkeys-core/feature"), exports);
 __exportStar(require("./features/async-data-loader/feature"), exports);
 __exportStar(require("./features/sync-data-loader/feature"), exports);

package/lib/cjs/types/core.d.ts

@@ -10,6 +10,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;
 export type FeatureDef = {
@@ -34,7 +35,7 @@ type MergedFeatures<F extends FeatureDef> = {
     itemInstance: UnionToIntersection<F["itemInstance"]>;
     hotkeys: F["hotkeys"];
 };
-export type RegisteredFeatures<T> = MainFeatureDef<T> | TreeFeatureDef<T> | SelectionFeatureDef<T> | DragAndDropFeatureDef<T> | KeyboardDragAndDropFeatureDef<T> | HotkeysCoreFeatureDef<T> | SyncDataLoaderFeatureDef<T> | AsyncDataLoaderFeatureDef<T> | SearchFeatureDef<T> | RenamingFeatureDef<T> | ExpandAllFeatureDef | PropMemoizationFeatureDef;
+export type RegisteredFeatures<T> = MainFeatureDef<T> | TreeFeatureDef<T> | SelectionFeatureDef<T> | CheckboxesFeatureDef<T> | DragAndDropFeatureDef<T> | KeyboardDragAndDropFeatureDef<T> | HotkeysCoreFeatureDef<T> | SyncDataLoaderFeatureDef<T> | AsyncDataLoaderFeatureDef<T> | SearchFeatureDef<T> | RenamingFeatureDef<T> | ExpandAllFeatureDef | PropMemoizationFeatureDef;
 type TreeStateType<T> = MergedFeatures<RegisteredFeatures<T>>["state"];
 export interface TreeState<T> extends TreeStateType<T> {
 }

package/lib/esm/core/create-tree.js

@@ -97,6 +97,15 @@ export const createTree = (initialConfig) => {
                 const externalStateSetter = config[stateHandlerNames[stateName]];
                 externalStateSetter === null || externalStateSetter === void 0 ? void 0 : externalStateSetter(state[stateName]);
             },
+            buildItemInstance: ({}, itemId) => {
+                const [instance, finalizeInstance] = buildInstance(features, "itemInstance", (instance) => ({
+                    item: instance,
+                    tree: treeInstance,
+                    itemId,
+                }));
+                finalizeInstance();
+                return instance;
+            },
             // TODO rebuildSubTree: (itemId: string) => void;
             rebuildTree: () => {
                 var _a;

package/lib/esm/features/async-data-loader/feature.js

@@ -26,14 +26,17 @@ const loadItemData = (tree, itemId) => __awaiter(void 0, void 0, void 0, functio
     tree.applySubStateUpdate("loadingItemData", (loadingItemData) => loadingItemData.filter((id) => id !== itemId));
     (_b = dataRef.current.awaitingItemDataLoading) === null || _b === void 0 ? void 0 : _b[itemId].forEach((cb) => cb());
     (_c = dataRef.current.awaitingItemDataLoading) === null || _c === void 0 ? true : delete _c[itemId];
+    return item;
 });
 const loadChildrenIds = (tree, itemId) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c, _d, _e;
     const config = tree.getConfig();
     const dataRef = getDataRef(tree);
+    let childrenIds;
+    // TODO is folder check?
     if ("getChildrenWithData" in config.dataLoader) {
         const children = yield config.dataLoader.getChildrenWithData(itemId);
-        const childrenIds = children.map((c) => c.id);
+        childrenIds = children.map((c) => c.id);
         dataRef.current.childrenIds[itemId] = childrenIds;
         children.forEach(({ id, data }) => {
             var _a, _b, _c;
@@ -47,7 +50,7 @@ const loadChildrenIds = (tree, itemId) => __awaiter(void 0, void 0, void 0, func
         tree.applySubStateUpdate("loadingItemData", (loadingItemData) => loadingItemData.filter((id) => !childrenIds.includes(id)));
     }
     else {
-        const childrenIds = yield config.dataLoader.getChildren(itemId);
+        childrenIds = yield config.dataLoader.getChildren(itemId);
         dataRef.current.childrenIds[itemId] = childrenIds;
         (_b = config.onLoadedChildren) === null || _b === void 0 ? void 0 : _b.call(config, itemId, childrenIds);
         tree.rebuildTree();
@@ -55,6 +58,7 @@ const loadChildrenIds = (tree, itemId) => __awaiter(void 0, void 0, void 0, func
     tree.applySubStateUpdate("loadingItemChildrens", (loadingItemChildrens) => loadingItemChildrens.filter((id) => id !== itemId));
     (_d = (_c = dataRef.current.awaitingItemChildrensLoading) === null || _c === void 0 ? void 0 : _c[itemId]) === null || _d === void 0 ? void 0 : _d.forEach((cb) => cb());
     (_e = dataRef.current.awaitingItemChildrensLoading) === null || _e === void 0 ? true : delete _e[itemId];
+    return childrenIds;
 });
 export const asyncDataLoaderFeature = {
     key: "async-data-loader",
@@ -80,6 +84,7 @@ export const asyncDataLoaderFeature = {
             });
         }),
         waitForItemChildrenLoaded: (_a, itemId_1) => __awaiter(void 0, [_a, itemId_1], void 0, function* ({ tree }, itemId) {
+            // TODO replace inner implementation with load() fns
             tree.retrieveChildrenIds(itemId);
             if (!tree.getState().loadingItemChildrens.includes(itemId)) {
                 return;
@@ -93,14 +98,22 @@ export const asyncDataLoaderFeature = {
                 dataRef.current.awaitingItemChildrensLoading[itemId].push(resolve);
             });
         }),
-        retrieveItemData: ({ tree }, itemId) => {
+        loadItemData: (_a, itemId_1) => __awaiter(void 0, [_a, itemId_1], void 0, function* ({ tree }, itemId) {
+            var _b;
+            return ((_b = getDataRef(tree).current.itemData[itemId]) !== null && _b !== void 0 ? _b : (yield loadItemData(tree, itemId)));
+        }),
+        loadChildrenIds: (_a, itemId_1) => __awaiter(void 0, [_a, itemId_1], void 0, function* ({ tree }, itemId) {
+            var _b;
+            return ((_b = getDataRef(tree).current.childrenIds[itemId]) !== null && _b !== void 0 ? _b : (yield loadChildrenIds(tree, itemId)));
+        }),
+        retrieveItemData: ({ tree }, itemId, skipFetch = false) => {
             var _a, _b;
             const config = tree.getConfig();
             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,
@@ -109,12 +122,12 @@ export const asyncDataLoaderFeature = {
             }
             return (_b = (_a = config.createLoadingItemData) === null || _a === void 0 ? void 0 : _a.call(config)) !== null && _b !== void 0 ? _b : null;
         },
-        retrieveChildrenIds: ({ tree }, itemId) => {
+        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 [];
             }
             tree.applySubStateUpdate("loadingItemChildrens", (loadingItemChildrens) => [...loadingItemChildrens, itemId]);

package/lib/esm/features/async-data-loader/types.d.ts

@@ -27,8 +27,12 @@ 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

package/lib/esm/features/checkboxes/feature.d.ts

@@ -0,0 +1,2 @@
+import { FeatureImplementation } from "../../types/core";
+export declare const checkboxesFeature: FeatureImplementation;

package/lib/esm/features/checkboxes/feature.js

@@ -0,0 +1,125 @@
+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());
+    });
+};
+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 = (tree, itemId) => __awaiter(void 0, void 0, void 0, function* () {
+    const children = yield tree.loadChildrenIds(itemId);
+    return [
+        itemId,
+        ...(yield Promise.all(children.map((child) => fetchAllDescendants(tree, child)))).flat(),
+    ];
+});
+const getAllLoadedDescendants = (tree, itemId) => {
+    const children = tree.retrieveChildrenIds(itemId, true);
+    return [
+        itemId,
+        ...children.map((child) => getAllLoadedDescendants(tree, child)).flat(),
+    ];
+};
+export const checkboxesFeature = {
+    key: "checkboxes",
+    overwrites: ["selection"],
+    getInitialState: (initialState) => (Object.assign({ checkedItems: [] }, initialState)),
+    getDefaultConfig: (defaultConfig, tree) => (Object.assign({ 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) => {
+                    if (r) {
+                        // console.log("ref", itemId, checkedState);
+                        r.indeterminate = checkedState === CheckedState.Indeterminate;
+                    }
+                },
+            };
+        },
+        toggleCheckedState: (_a) => __awaiter(void 0, [_a], void 0, function* ({ item }) {
+            if (item.getCheckedState() === CheckedState.Checked) {
+                yield item.setUnchecked();
+            }
+            else {
+                yield 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: (_a) => __awaiter(void 0, [_a], void 0, function* ({ item, tree, itemId }) {
+            if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+                tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
+            }
+            else {
+                const descendants = yield fetchAllDescendants(tree, itemId);
+                tree.applySubStateUpdate("checkedItems", (items) => [
+                    ...items,
+                    ...descendants,
+                ]);
+            }
+        }),
+        setUnchecked: (_a) => __awaiter(void 0, [_a], void 0, function* ({ item, tree, itemId }) {
+            if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+                tree.applySubStateUpdate("checkedItems", (items) => items.filter((id) => id !== itemId));
+            }
+            else {
+                yield tree.loadChildrenIds(itemId);
+                item.getChildren().forEach((item) => item.setUnchecked());
+            }
+        }),
+    },
+};

package/lib/esm/features/checkboxes/types.d.ts

@@ -0,0 +1,26 @@
+import { SetStateFn } from "../../types/core";
+export declare 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/lib/esm/features/checkboxes/types.js

@@ -0,0 +1,6 @@
+export var CheckedState;
+(function (CheckedState) {
+    CheckedState["Checked"] = "checked";
+    CheckedState["Unchecked"] = "unchecked";
+    CheckedState["Indeterminate"] = "indeterminate";
+})(CheckedState || (CheckedState = {}));

package/lib/esm/features/main/types.d.ts

@@ -17,6 +17,8 @@ export type MainFeatureDef<T = any> = {
     treeInstance: {
         /** @internal */
         applySubStateUpdate: <K extends keyof TreeState<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/lib/esm/features/sync-data-loader/feature.js

@@ -37,6 +37,8 @@ export const syncDataLoaderFeature = {
             }
             return unpromise(dataLoader.getChildrenWithData(itemId)).map((c) => c.data);
         },
+        loadItemData: ({ tree }, itemId) => tree.retrieveItemData(itemId),
+        loadChildrenIds: ({ tree }, itemId) => tree.retrieveChildrenIds(itemId),
     },
     itemInstance: {
         isLoading: () => false,

package/lib/esm/features/sync-data-loader/types.d.ts

@@ -18,8 +18,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/lib/esm/index.d.ts

@@ -5,6 +5,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";
@@ -13,6 +14,7 @@ export * from "./features/renaming/types";
 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/lib/esm/index.js

@@ -4,6 +4,7 @@ export * from "./features/tree/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";
@@ -12,6 +13,7 @@ export * from "./features/renaming/types";
 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/lib/esm/types/core.d.ts

@@ -10,6 +10,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;
 export type FeatureDef = {
@@ -34,7 +35,7 @@ type MergedFeatures<F extends FeatureDef> = {
     itemInstance: UnionToIntersection<F["itemInstance"]>;
     hotkeys: F["hotkeys"];
 };
-export type RegisteredFeatures<T> = MainFeatureDef<T> | TreeFeatureDef<T> | SelectionFeatureDef<T> | DragAndDropFeatureDef<T> | KeyboardDragAndDropFeatureDef<T> | HotkeysCoreFeatureDef<T> | SyncDataLoaderFeatureDef<T> | AsyncDataLoaderFeatureDef<T> | SearchFeatureDef<T> | RenamingFeatureDef<T> | ExpandAllFeatureDef | PropMemoizationFeatureDef;
+export type RegisteredFeatures<T> = MainFeatureDef<T> | TreeFeatureDef<T> | SelectionFeatureDef<T> | CheckboxesFeatureDef<T> | DragAndDropFeatureDef<T> | KeyboardDragAndDropFeatureDef<T> | HotkeysCoreFeatureDef<T> | SyncDataLoaderFeatureDef<T> | AsyncDataLoaderFeatureDef<T> | SearchFeatureDef<T> | RenamingFeatureDef<T> | ExpandAllFeatureDef | PropMemoizationFeatureDef;
 type TreeStateType<T> = MergedFeatures<RegisteredFeatures<T>>["state"];
 export interface TreeState<T> extends TreeStateType<T> {
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headless-tree/core",
-  "version": "0.0.0-20250509160455",
+  "version": "0.0.0-20250509212452",
   "type": "module",
   "main": "lib/cjs/index.js",
   "module": "lib/esm/index.js",

package/src/core/create-tree.ts

@@ -151,6 +151,19 @@ export const createTree = <T>(
         ] as Function;
         externalStateSetter?.(state[stateName]);
       },
+      buildItemInstance: ({}, itemId) => {
+        const [instance, finalizeInstance] = buildInstance(
+          features,
+          "itemInstance",
+          (instance) => ({
+            item: instance,
+            tree: treeInstance,
+            itemId,
+          }),
+        );
+        finalizeInstance();
+        return instance;
+      },
       // TODO rebuildSubTree: (itemId: string) => void;
       rebuildTree: () => {
         rebuildItemMeta();

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

@@ -22,15 +22,19 @@ const loadItemData = async <T>(tree: TreeInstance<T>, itemId: string) => {
 
   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);
-    const childrenIds = children.map((c) => c.id);
+    childrenIds = children.map((c) => c.id);
     dataRef.current.childrenIds[itemId] = childrenIds;
     children.forEach(({ id, data }) => {
       dataRef.current.itemData[id] = data;
@@ -45,7 +49,7 @@ const loadChildrenIds = async <T>(tree: TreeInstance<T>, itemId: string) => {
       loadingItemData.filter((id) => !childrenIds.includes(id)),
     );
   } else {
-    const childrenIds = await config.dataLoader.getChildren(itemId);
+    childrenIds = await config.dataLoader.getChildren(itemId);
     dataRef.current.childrenIds[itemId] = childrenIds;
     config.onLoadedChildren?.(itemId, childrenIds);
     tree.rebuildTree();
@@ -57,6 +61,7 @@ const loadChildrenIds = async <T>(tree: TreeInstance<T>, itemId: string) => {
 
   dataRef.current.awaitingItemChildrensLoading?.[itemId]?.forEach((cb) => cb());
   delete dataRef.current.awaitingItemChildrensLoading?.[itemId];
+  return childrenIds;
 };
 
 export const asyncDataLoaderFeature: FeatureImplementation = {
@@ -94,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;
@@ -106,7 +112,20 @@ 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 = getDataRef(tree);
 
@@ -114,7 +133,7 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
         return dataRef.current.itemData[itemId];
       }
 
-      if (!tree.getState().loadingItemData.includes(itemId)) {
+      if (!tree.getState().loadingItemData.includes(itemId) && !skipFetch) {
         tree.applySubStateUpdate("loadingItemData", (loadingItemData) => [
           ...loadingItemData,
           itemId,
@@ -126,13 +145,13 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
       return config.createLoadingItemData?.() ?? null;
     },
 
-    retrieveChildrenIds: ({ tree }, itemId) => {
+    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 [];
       }
 

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

@@ -32,8 +32,12 @@ 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

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>