@headless-tree/core 0.0.0-20250611234714 → 0.0.0-20250615190319

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # @headless-tree/core
 
-## 0.0.0-20250611234714
+## 0.0.0-20250615190319
+
+### Minor Changes
+
+- 8dd6231: Introduced new Checkboxes feature (#88)
+
+## 1.2.0
 
 ### Minor Changes
 

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

@@ -112,6 +112,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

@@ -75,14 +75,14 @@ exports.asyncDataLoaderFeature = {
             var _b;
             return ((_b = getDataRef(tree).current.childrenIds[itemId]) !== null && _b !== void 0 ? _b : (yield loadChildrenIds(tree, itemId)));
         }),
-        retrieveItemData: ({ 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,
@@ -91,12 +91,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/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,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkboxesFeature = void 0;
+const utils_1 = require("../../utils");
+const types_1 = require("./types");
+const errors_1 = require("../../utilities/errors");
+const getAllLoadedDescendants = (tree, itemId) => {
+    if (!tree.getConfig().isItemFolder(tree.buildItemInstance(itemId))) {
+        return [itemId];
+    }
+    return tree
+        .retrieveChildrenIds(itemId)
+        .map((child) => getAllLoadedDescendants(tree, child))
+        .flat();
+};
+exports.checkboxesFeature = {
+    key: "checkboxes",
+    overwrites: ["selection"],
+    getInitialState: (initialState) => (Object.assign({ checkedItems: [] }, initialState)),
+    getDefaultConfig: (defaultConfig, tree) => {
+        var _a;
+        const hasAsyncLoader = (_a = defaultConfig.features) === null || _a === void 0 ? void 0 : _a.some((f) => f.key === "async-data-loader");
+        if (hasAsyncLoader && !defaultConfig.canCheckFolders) {
+            (0, errors_1.throwError)(`!canCheckFolders not supported with async trees`);
+        }
+        return Object.assign({ setCheckedItems: (0, utils_1.makeStateUpdater)("checkedItems", tree), canCheckFolders: hasAsyncLoader !== null && hasAsyncLoader !== void 0 ? hasAsyncLoader : false }, defaultConfig);
+    },
+    stateHandlerNames: {
+        checkedItems: "setCheckedItems",
+    },
+    treeInstance: {
+        setCheckedItems: ({ tree }, checkedItems) => {
+            tree.applySubStateUpdate("checkedItems", checkedItems);
+        },
+    },
+    itemInstance: {
+        getCheckboxProps: ({ item }) => {
+            const checkedState = item.getCheckedState();
+            return {
+                onChange: item.toggleCheckedState,
+                checked: checkedState === types_1.CheckedState.Checked,
+                ref: (r) => {
+                    if (r) {
+                        r.indeterminate = checkedState === types_1.CheckedState.Indeterminate;
+                    }
+                },
+            };
+        },
+        toggleCheckedState: ({ item }) => {
+            if (item.getCheckedState() === types_1.CheckedState.Checked) {
+                item.setUnchecked();
+            }
+            else {
+                item.setChecked();
+            }
+        },
+        getCheckedState: ({ item, tree, itemId }) => {
+            const { checkedItems } = tree.getState();
+            if (checkedItems.includes(itemId)) {
+                return types_1.CheckedState.Checked;
+            }
+            if (item.isFolder() && !tree.getConfig().canCheckFolders) {
+                const descendants = getAllLoadedDescendants(tree, itemId);
+                if (descendants.every((d) => checkedItems.includes(d))) {
+                    return types_1.CheckedState.Checked;
+                }
+                if (descendants.some((d) => checkedItems.includes(d))) {
+                    return types_1.CheckedState.Indeterminate;
+                }
+            }
+            return types_1.CheckedState.Unchecked;
+        },
+        setChecked: ({ item, tree, itemId }) => {
+            if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+                tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
+            }
+            else {
+                tree.applySubStateUpdate("checkedItems", (items) => [
+                    ...items,
+                    ...getAllLoadedDescendants(tree, itemId),
+                ]);
+            }
+        },
+        setUnchecked: ({ item, tree, itemId }) => {
+            if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+                tree.applySubStateUpdate("checkedItems", (items) => items.filter((id) => id !== itemId));
+            }
+            else {
+                const descendants = getAllLoadedDescendants(tree, itemId);
+                tree.applySubStateUpdate("checkedItems", (items) => items.filter((id) => !descendants.includes(id)));
+            }
+        },
+    },
+};

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: () => void;
+        setUnchecked: () => void;
+        toggleCheckedState: () => 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/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

@@ -21,6 +21,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);
@@ -29,6 +30,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

@@ -109,6 +109,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

@@ -72,14 +72,14 @@ export const asyncDataLoaderFeature = {
             var _b;
             return ((_b = getDataRef(tree).current.childrenIds[itemId]) !== null && _b !== void 0 ? _b : (yield loadChildrenIds(tree, itemId)));
         }),
-        retrieveItemData: ({ 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,
@@ -88,12 +88,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/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,91 @@
+import { makeStateUpdater } from "../../utils";
+import { CheckedState } from "./types";
+import { throwError } from "../../utilities/errors";
+const getAllLoadedDescendants = (tree, itemId) => {
+    if (!tree.getConfig().isItemFolder(tree.buildItemInstance(itemId))) {
+        return [itemId];
+    }
+    return tree
+        .retrieveChildrenIds(itemId)
+        .map((child) => getAllLoadedDescendants(tree, child))
+        .flat();
+};
+export const checkboxesFeature = {
+    key: "checkboxes",
+    overwrites: ["selection"],
+    getInitialState: (initialState) => (Object.assign({ checkedItems: [] }, initialState)),
+    getDefaultConfig: (defaultConfig, tree) => {
+        var _a;
+        const hasAsyncLoader = (_a = defaultConfig.features) === null || _a === void 0 ? void 0 : _a.some((f) => f.key === "async-data-loader");
+        if (hasAsyncLoader && !defaultConfig.canCheckFolders) {
+            throwError(`!canCheckFolders not supported with async trees`);
+        }
+        return Object.assign({ setCheckedItems: makeStateUpdater("checkedItems", tree), canCheckFolders: hasAsyncLoader !== null && hasAsyncLoader !== void 0 ? hasAsyncLoader : false }, defaultConfig);
+    },
+    stateHandlerNames: {
+        checkedItems: "setCheckedItems",
+    },
+    treeInstance: {
+        setCheckedItems: ({ tree }, checkedItems) => {
+            tree.applySubStateUpdate("checkedItems", checkedItems);
+        },
+    },
+    itemInstance: {
+        getCheckboxProps: ({ item }) => {
+            const checkedState = item.getCheckedState();
+            return {
+                onChange: item.toggleCheckedState,
+                checked: checkedState === CheckedState.Checked,
+                ref: (r) => {
+                    if (r) {
+                        r.indeterminate = checkedState === CheckedState.Indeterminate;
+                    }
+                },
+            };
+        },
+        toggleCheckedState: ({ item }) => {
+            if (item.getCheckedState() === CheckedState.Checked) {
+                item.setUnchecked();
+            }
+            else {
+                item.setChecked();
+            }
+        },
+        getCheckedState: ({ item, tree, itemId }) => {
+            const { checkedItems } = tree.getState();
+            if (checkedItems.includes(itemId)) {
+                return CheckedState.Checked;
+            }
+            if (item.isFolder() && !tree.getConfig().canCheckFolders) {
+                const descendants = getAllLoadedDescendants(tree, itemId);
+                if (descendants.every((d) => checkedItems.includes(d))) {
+                    return CheckedState.Checked;
+                }
+                if (descendants.some((d) => checkedItems.includes(d))) {
+                    return CheckedState.Indeterminate;
+                }
+            }
+            return CheckedState.Unchecked;
+        },
+        setChecked: ({ item, tree, itemId }) => {
+            if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+                tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
+            }
+            else {
+                tree.applySubStateUpdate("checkedItems", (items) => [
+                    ...items,
+                    ...getAllLoadedDescendants(tree, itemId),
+                ]);
+            }
+        },
+        setUnchecked: ({ item, tree, itemId }) => {
+            if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+                tree.applySubStateUpdate("checkedItems", (items) => items.filter((id) => id !== itemId));
+            }
+            else {
+                const descendants = getAllLoadedDescendants(tree, itemId);
+                tree.applySubStateUpdate("checkedItems", (items) => items.filter((id) => !descendants.includes(id)));
+            }
+        },
+    },
+};

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: () => void;
+        setUnchecked: () => void;
+        toggleCheckedState: () => 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/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-20250611234714",
+  "version": "0.0.0-20250615190319",
   "main": "lib/cjs/index.js",
   "module": "lib/esm/index.js",
   "types": "lib/esm/index.d.ts",

package/src/core/create-tree.ts

@@ -170,6 +170,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

@@ -95,7 +95,7 @@ export const asyncDataLoaderFeature: FeatureImplementation = {
       );
     },
 
-    retrieveItemData: ({ tree }, itemId) => {
+    retrieveItemData: ({ tree }, itemId, skipFetch = false) => {
       const config = tree.getConfig();
       const dataRef = getDataRef(tree);
 
@@ -103,7 +103,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,
@@ -115,13 +115,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/checkboxes/checkboxes.spec.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import { TestTree } from "../../test-utils/test-tree";
+import { checkboxesFeature } from "./feature";
+import { CheckedState } from "./types";
+
+const factory = TestTree.default({})
+  .withFeatures(checkboxesFeature)
+  .suits.sync().tree;
+
+describe("core-feature/checkboxes", () => {
+  it("should initialize with no checked items", async () => {
+    const tree = await factory.createTestCaseTree();
+    expect(tree.instance.getState().checkedItems).toEqual([]);
+  });
+
+  it("should check items", async () => {
+    const tree = await factory.createTestCaseTree();
+    tree.item("x111").setChecked();
+    tree.item("x112").setChecked();
+    expect(tree.instance.getState().checkedItems).toEqual(["x111", "x112"]);
+  });
+
+  it("should uncheck an item", async () => {
+    const tree = await factory
+      .with({ state: { checkedItems: ["x111"] } })
+      .createTestCaseTree();
+    tree.item("x111").setUnchecked();
+    expect(tree.instance.getState().checkedItems).not.toContain("x111");
+  });
+
+  it("should toggle checked state", async () => {
+    const tree = await factory.createTestCaseTree();
+    const item = tree.item("x111");
+
+    item.toggleCheckedState();
+    expect(tree.instance.getState().checkedItems).toContain("x111");
+
+    item.toggleCheckedState();
+    expect(tree.instance.getState().checkedItems).not.toContain("x111");
+  });
+
+  describe("props", () => {
+    it("should toggle checked state", async () => {
+      const tree = await factory.createTestCaseTree();
+      const item = tree.item("x111");
+
+      item.getCheckboxProps().onChange();
+      expect(tree.instance.getState().checkedItems).toContain("x111");
+
+      item.getCheckboxProps().onChange();
+      expect(tree.instance.getState().checkedItems).not.toContain("x111");
+    });
+
+    it("should return checked state in props", async () => {
+      const tree = await factory.createTestCaseTree();
+      tree.item("x111").setChecked();
+      expect(tree.item("x111").getCheckboxProps().checked).toBe(true);
+      expect(tree.item("x112").getCheckboxProps().checked).toBe(false);
+    });
+
+    it("should create indeterminate state", async () => {
+      const tree = await factory.createTestCaseTree();
+      tree.item("x111").setChecked();
+      const refObject = { indeterminate: undefined };
+      tree.item("x11").getCheckboxProps().ref(refObject);
+      expect(refObject.indeterminate).toBe(true);
+    });
+
+    it("should not create indeterminate state", async () => {
+      const tree = await factory.createTestCaseTree();
+      const refObject = { indeterminate: undefined };
+      tree.item("x11").getCheckboxProps().ref(refObject);
+      expect(refObject.indeterminate).toBe(false);
+    });
+  });
+
+  it("should handle folder checking when canCheckFolders is true", async () => {
+    const tree = await factory
+      .with({ canCheckFolders: true })
+      .createTestCaseTree();
+
+    tree.item("x11").setChecked();
+    expect(tree.instance.getState().checkedItems).toContain("x11");
+  });
+
+  it("should handle folder checking when canCheckFolders is false", async () => {
+    const tree = await factory.createTestCaseTree();
+
+    tree.item("x11").setChecked();
+    expect(tree.instance.getState().checkedItems).toEqual(
+      expect.arrayContaining(["x111", "x112", "x113", "x114"]),
+    );
+  });
+
+  it("should turn folder indeterminate", async () => {
+    const tree = await factory.createTestCaseTree();
+
+    tree.item("x111").setChecked();
+    expect(tree.item("x11").getCheckedState()).toBe(CheckedState.Indeterminate);
+  });
+
+  it("should turn folder checked if all children are checked", async () => {
+    const tree = await factory
+      .with({
+        isItemFolder: (item) => item.getItemData().length < 4,
+      })
+      .createTestCaseTree();
+
+    tree.item("x11").setChecked();
+    tree.item("x12").setChecked();
+    tree.item("x13").setChecked();
+    expect(tree.item("x1").getCheckedState()).toBe(CheckedState.Indeterminate);
+    tree.do.selectItem("x14");
+    tree.item("x141").setChecked();
+    tree.item("x142").setChecked();
+    tree.item("x143").setChecked();
+    expect(tree.item("x1").getCheckedState()).toBe(CheckedState.Indeterminate);
+    tree.item("x144").setChecked();
+    expect(tree.item("x1").getCheckedState()).toBe(CheckedState.Checked);
+  });
+
+  it("should return correct checked state for items", async () => {
+    const tree = await factory.createTestCaseTree();
+    const item = tree.instance.getItemInstance("x111");
+
+    expect(item.getCheckedState()).toBe(CheckedState.Unchecked);
+
+    item.setChecked();
+    expect(item.getCheckedState()).toBe(CheckedState.Checked);
+
+    item.setUnchecked();
+    expect(item.getCheckedState()).toBe(CheckedState.Unchecked);
+  });
+});

package/src/features/checkboxes/feature.ts

@@ -0,0 +1,119 @@
+import { FeatureImplementation, TreeInstance } from "../../types/core";
+import { makeStateUpdater } from "../../utils";
+import { CheckedState } from "./types";
+import { throwError } from "../../utilities/errors";
+
+const getAllLoadedDescendants = <T>(
+  tree: TreeInstance<T>,
+  itemId: string,
+): string[] => {
+  if (!tree.getConfig().isItemFolder(tree.buildItemInstance(itemId))) {
+    return [itemId];
+  }
+  return tree
+    .retrieveChildrenIds(itemId)
+    .map((child) => getAllLoadedDescendants(tree, child))
+    .flat();
+};
+
+export const checkboxesFeature: FeatureImplementation = {
+  key: "checkboxes",
+
+  overwrites: ["selection"],
+
+  getInitialState: (initialState) => ({
+    checkedItems: [],
+    ...initialState,
+  }),
+
+  getDefaultConfig: (defaultConfig, tree) => {
+    const hasAsyncLoader = defaultConfig.features?.some(
+      (f) => f.key === "async-data-loader",
+    );
+    if (hasAsyncLoader && !defaultConfig.canCheckFolders) {
+      throwError(`!canCheckFolders not supported with async trees`);
+    }
+    return {
+      setCheckedItems: makeStateUpdater("checkedItems", tree),
+      canCheckFolders: hasAsyncLoader ?? false,
+      ...defaultConfig,
+    };
+  },
+
+  stateHandlerNames: {
+    checkedItems: "setCheckedItems",
+  },
+
+  treeInstance: {
+    setCheckedItems: ({ tree }, checkedItems) => {
+      tree.applySubStateUpdate("checkedItems", checkedItems);
+    },
+  },
+
+  itemInstance: {
+    getCheckboxProps: ({ item }) => {
+      const checkedState = item.getCheckedState();
+      return {
+        onChange: item.toggleCheckedState,
+        checked: checkedState === CheckedState.Checked,
+        ref: (r: any) => {
+          if (r) {
+            r.indeterminate = checkedState === CheckedState.Indeterminate;
+          }
+        },
+      };
+    },
+
+    toggleCheckedState: ({ item }) => {
+      if (item.getCheckedState() === CheckedState.Checked) {
+        item.setUnchecked();
+      } else {
+        item.setChecked();
+      }
+    },
+
+    getCheckedState: ({ item, tree, itemId }) => {
+      const { checkedItems } = tree.getState();
+
+      if (checkedItems.includes(itemId)) {
+        return CheckedState.Checked;
+      }
+
+      if (item.isFolder() && !tree.getConfig().canCheckFolders) {
+        const descendants = getAllLoadedDescendants(tree, itemId);
+        if (descendants.every((d) => checkedItems.includes(d))) {
+          return CheckedState.Checked;
+        }
+        if (descendants.some((d) => checkedItems.includes(d))) {
+          return CheckedState.Indeterminate;
+        }
+      }
+
+      return CheckedState.Unchecked;
+    },
+
+    setChecked: ({ item, tree, itemId }) => {
+      if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+        tree.applySubStateUpdate("checkedItems", (items) => [...items, itemId]);
+      } else {
+        tree.applySubStateUpdate("checkedItems", (items) => [
+          ...items,
+          ...getAllLoadedDescendants(tree, itemId),
+        ]);
+      }
+    },
+
+    setUnchecked: ({ item, tree, itemId }) => {
+      if (!item.isFolder() || tree.getConfig().canCheckFolders) {
+        tree.applySubStateUpdate("checkedItems", (items) =>
+          items.filter((id) => id !== itemId),
+        );
+      } else {
+        const descendants = getAllLoadedDescendants(tree, itemId);
+        tree.applySubStateUpdate("checkedItems", (items) =>
+          items.filter((id) => !descendants.includes(id)),
+        );
+      }
+    },
+  },
+};

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: () => void;
+    setUnchecked: () => void;
+    toggleCheckedState: () => 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/tree/types.ts

@@ -20,7 +20,7 @@ export type TreeFeatureDef<T> = {
     focusedItem: string | null;
   };
   config: {
-    isItemFolder: (item: ItemInstance<T>) => boolean;
+    isItemFolder: (item: ItemInstance<T>) => boolean; // TODO:breaking use item data as payload
     getItemName: (item: ItemInstance<T>) => string;
 
     onPrimaryAction?: (item: ItemInstance<T>) => void;

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>