@headless-tree/core 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @headless-tree/core
 
+## 1.5.0
+
+### Minor Changes
+
+- cbeaba6: all state updates (like setSelectedItems) will not propagate while the component is unmounted. This happened before for `tree.setState()` calls directly, but not individual state atoms like `setSelectedItems`. When calling `createTree()` directly (instead of `useTree()`), `tree.setMounted(true)` needs to be called once after mount. No changes are necessary when using the React-based `useTree()` integration. (#158)
+
+### Patch Changes
+
+- 72e714b: all NPM deployments will now publish with provenance
+- 6693986: fixed an issue where async data loaders cause calling `item.getItemData()` outside of the component calling `useTree()` to cause a React warning log (#158)
+- 7a7424f: fixed incorrect exports definition in package.json for require/cjs imports (#161)
+- 215ab4b: add a new symbol that can be used in hotkey configurations "metaorcontrol" that will trigger if either any windows control key or mac meta key is pressed (#141)
+- 51b0dea: Added `isUnorderedDragTarget` as alternative to `isDragTarget` for easier detection of drag type
+- cf845d7: Added new state variable `loadingCheckPropagationItems` to indicate if, in async trees with checkboxes and state propagation enabled, data loading operations are currently loading due to a checkbox propagation taking place
+- 597faad: Checkbox propagation is now supported for trees with async data loaders!
+- b0ee382: triggering a data refetch will now always set the loadingItemData/loadingItemChildrens state variable to the associated items if they where not apart of the cache before
+
+## 1.4.0
+
+### Minor Changes
+
+- 7ef4864: added feature where closed items are auto-expanded briefly after dragging onto them. set config option `openOnDropDelay` to zero to disable.
+
+### Patch Changes
+
+- 8d53b4f: fixed a bug where external changes to focused or selected items don't trigger a rerender (#150)
+- 1cee368: fixed a bug where the drag line is not cleared after drop (#149)
+- 1e833bb: drag-and-drop feature is no longer dependent on selection feature, and fill default to focused item if selection feature is missing (#143)
+
 ## 1.3.0
 
 ### Minor Changes

package/dist/index.d.mts

@@ -2,6 +2,7 @@ interface DndDataRef {
     lastDragCode?: string;
     lastAllowDrop?: boolean;
     lastDragEnter?: number;
+    autoExpandTimeout?: any;
     windowDragEndListener?: () => void;
 }
 interface DndState<T> {
@@ -65,6 +66,8 @@ type DragAndDropFeatureDef<T> = {
         onDrop?: (items: ItemInstance<T>[], target: DragTarget<T>) => void | Promise<void>;
         onDropForeignDragObject?: (dataTransfer: DataTransfer, target: DragTarget<T>) => void | Promise<void>;
         onCompleteForeignDrop?: (items: ItemInstance<T>[]) => void;
+        /** When dragging for this many ms on a closed folder, the folder will automatically open. Set to zero to disable. */
+        openOnDropDelay?: number;
     };
     treeInstance: {
         getDragTarget: () => DragTarget<T> | null;
@@ -72,7 +75,12 @@ type DragAndDropFeatureDef<T> = {
         getDragLineStyle: (topOffset?: number, leftOffset?: number) => Record<string, any>;
     };
     itemInstance: {
+        /** Checks if the user is dragging in a way which makes this the new parent of the dragged items, either by dragging on top of
+         * this item, or by dragging inbetween children of this item. See @{isUnorderedDragTarget} if the latter is undesirable. */
         isDragTarget: () => boolean;
+        /** As opposed to @{isDragTarget}, this will not be true if the target is inbetween children of this item. This returns only true
+         * if the user is dragging directly on top of this item. */
+        isUnorderedDragTarget: () => boolean;
         isDragTargetAbove: () => boolean;
         isDragTargetBelow: () => boolean;
         isDraggingOver: () => boolean;
@@ -174,6 +182,10 @@ type MainFeatureDef<T = any> = {
         };
         getHotkeyPresets: () => HotkeysConfig<T>;
         rebuildTree: () => void;
+        /** @deprecated Experimental feature, might get removed or changed in the future. */
+        scheduleRebuildTree: () => void;
+        /** @internal */
+        setMounted: (isMounted: boolean) => void;
     };
     itemInstance: {
         registerElement: (element: HTMLElement | null) => void;
@@ -256,7 +268,12 @@ type SyncDataLoaderFeatureDef<T> = {
     };
     treeInstance: {
         retrieveItemData: (itemId: string) => T;
-        retrieveChildrenIds: (itemId: string) => string[];
+        /** Retrieve children Ids. If an async data loader is used, skipFetch is set to true, and children have not been retrieved
+         * yet for this item, this will initiate fetching the children, and return an empty array. Once the children have loaded,
+         * a rerender will be triggered.
+         * @param skipFetch - Defaults to false.
+         */
+        retrieveChildrenIds: (itemId: string, skipFetch?: boolean) => string[];
     };
     itemInstance: {
         isLoading: () => boolean;
@@ -304,7 +321,8 @@ type AsyncDataLoaderFeatureDef<T> = {
          * @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>;
-        updateCachedData: (data: T) => void;
+        /** Set to undefined to clear cache without triggering automatic refetch. Use @invalidateItemData to clear and triggering refetch. */
+        updateCachedData: (data: T | undefined) => void;
         updateCachedChildrenIds: (childrenIds: string[]) => void;
         isLoading: () => boolean;
     };
@@ -440,9 +458,11 @@ declare enum CheckedState {
 type CheckboxesFeatureDef<T> = {
     state: {
         checkedItems: string[];
+        loadingCheckPropagationItems: string[];
     };
     config: {
         setCheckedItems?: SetStateFn<string[]>;
+        setLoadingCheckPropagationItems?: SetStateFn<string[]>;
         canCheckFolders?: boolean;
         propagateCheckedState?: boolean;
     };
@@ -450,11 +470,18 @@ type CheckboxesFeatureDef<T> = {
         setCheckedItems: (checkedItems: string[]) => void;
     };
     itemInstance: {
-        setChecked: () => void;
-        setUnchecked: () => void;
-        toggleCheckedState: () => void;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        setChecked: () => Promise<void>;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        setUnchecked: () => Promise<void>;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        toggleCheckedState: () => Promise<void>;
         getCheckedState: () => CheckedState;
         getCheckboxProps: () => Record<string, any>;
+        isLoadingCheckPropagation: () => boolean;
     };
     hotkeys: never;
 };
@@ -500,11 +527,11 @@ type HotkeyName = MergedFeatures<RegisteredFeatures<any>>["hotkeys"];
 type HotkeysConfig<T> = Record<HotkeyName, HotkeyConfig<T>>;
 type CustomHotkeysConfig<T> = Partial<Record<HotkeyName | `custom${string}`, Partial<HotkeyConfig<T>>>>;
 type MayReturnNull<T extends (...x: any[]) => any> = (...args: Parameters<T>) => ReturnType<T> | null;
-type ItemInstanceOpts<Key extends keyof ItemInstance<any>> = {
-    item: ItemInstance<any>;
-    tree: TreeInstance<any>;
+type ItemInstanceOpts<T, Key extends keyof ItemInstance<any>> = {
+    item: ItemInstance<T>;
+    tree: TreeInstance<T>;
     itemId: string;
-    prev?: MayReturnNull<ItemInstance<any>[Key]>;
+    prev?: MayReturnNull<ItemInstance<T>[Key]>;
 };
 type TreeInstanceOpts<Key extends keyof TreeInstance<any>> = {
     tree: TreeInstance<any>;
@@ -521,7 +548,7 @@ type FeatureImplementation<T = any> = {
         [key in keyof TreeInstance<T>]?: (opts: TreeInstanceOpts<key>, ...args: Parameters<TreeInstance<T>[key]>) => void;
     };
     itemInstance?: {
-        [key in keyof ItemInstance<T>]?: (opts: ItemInstanceOpts<key>, ...args: Parameters<ItemInstance<T>[key]>) => void;
+        [key in keyof ItemInstance<T>]?: (opts: ItemInstanceOpts<T, key>, ...args: Parameters<ItemInstance<T>[key]>) => void;
     };
     onTreeMount?: (instance: TreeInstance<T>, treeElement: HTMLElement) => void;
     onTreeUnmount?: (instance: TreeInstance<T>, treeElement: HTMLElement) => void;

package/dist/index.d.ts

@@ -2,6 +2,7 @@ interface DndDataRef {
     lastDragCode?: string;
     lastAllowDrop?: boolean;
     lastDragEnter?: number;
+    autoExpandTimeout?: any;
     windowDragEndListener?: () => void;
 }
 interface DndState<T> {
@@ -65,6 +66,8 @@ type DragAndDropFeatureDef<T> = {
         onDrop?: (items: ItemInstance<T>[], target: DragTarget<T>) => void | Promise<void>;
         onDropForeignDragObject?: (dataTransfer: DataTransfer, target: DragTarget<T>) => void | Promise<void>;
         onCompleteForeignDrop?: (items: ItemInstance<T>[]) => void;
+        /** When dragging for this many ms on a closed folder, the folder will automatically open. Set to zero to disable. */
+        openOnDropDelay?: number;
     };
     treeInstance: {
         getDragTarget: () => DragTarget<T> | null;
@@ -72,7 +75,12 @@ type DragAndDropFeatureDef<T> = {
         getDragLineStyle: (topOffset?: number, leftOffset?: number) => Record<string, any>;
     };
     itemInstance: {
+        /** Checks if the user is dragging in a way which makes this the new parent of the dragged items, either by dragging on top of
+         * this item, or by dragging inbetween children of this item. See @{isUnorderedDragTarget} if the latter is undesirable. */
         isDragTarget: () => boolean;
+        /** As opposed to @{isDragTarget}, this will not be true if the target is inbetween children of this item. This returns only true
+         * if the user is dragging directly on top of this item. */
+        isUnorderedDragTarget: () => boolean;
         isDragTargetAbove: () => boolean;
         isDragTargetBelow: () => boolean;
         isDraggingOver: () => boolean;
@@ -174,6 +182,10 @@ type MainFeatureDef<T = any> = {
         };
         getHotkeyPresets: () => HotkeysConfig<T>;
         rebuildTree: () => void;
+        /** @deprecated Experimental feature, might get removed or changed in the future. */
+        scheduleRebuildTree: () => void;
+        /** @internal */
+        setMounted: (isMounted: boolean) => void;
     };
     itemInstance: {
         registerElement: (element: HTMLElement | null) => void;
@@ -256,7 +268,12 @@ type SyncDataLoaderFeatureDef<T> = {
     };
     treeInstance: {
         retrieveItemData: (itemId: string) => T;
-        retrieveChildrenIds: (itemId: string) => string[];
+        /** Retrieve children Ids. If an async data loader is used, skipFetch is set to true, and children have not been retrieved
+         * yet for this item, this will initiate fetching the children, and return an empty array. Once the children have loaded,
+         * a rerender will be triggered.
+         * @param skipFetch - Defaults to false.
+         */
+        retrieveChildrenIds: (itemId: string, skipFetch?: boolean) => string[];
     };
     itemInstance: {
         isLoading: () => boolean;
@@ -304,7 +321,8 @@ type AsyncDataLoaderFeatureDef<T> = {
          * @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>;
-        updateCachedData: (data: T) => void;
+        /** Set to undefined to clear cache without triggering automatic refetch. Use @invalidateItemData to clear and triggering refetch. */
+        updateCachedData: (data: T | undefined) => void;
         updateCachedChildrenIds: (childrenIds: string[]) => void;
         isLoading: () => boolean;
     };
@@ -440,9 +458,11 @@ declare enum CheckedState {
 type CheckboxesFeatureDef<T> = {
     state: {
         checkedItems: string[];
+        loadingCheckPropagationItems: string[];
     };
     config: {
         setCheckedItems?: SetStateFn<string[]>;
+        setLoadingCheckPropagationItems?: SetStateFn<string[]>;
         canCheckFolders?: boolean;
         propagateCheckedState?: boolean;
     };
@@ -450,11 +470,18 @@ type CheckboxesFeatureDef<T> = {
         setCheckedItems: (checkedItems: string[]) => void;
     };
     itemInstance: {
-        setChecked: () => void;
-        setUnchecked: () => void;
-        toggleCheckedState: () => void;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        setChecked: () => Promise<void>;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        setUnchecked: () => Promise<void>;
+        /** Will recursively load descendants if propagateCheckedState=true and async data loader is used. If not,
+         * this will return immediately. */
+        toggleCheckedState: () => Promise<void>;
         getCheckedState: () => CheckedState;
         getCheckboxProps: () => Record<string, any>;
+        isLoadingCheckPropagation: () => boolean;
     };
     hotkeys: never;
 };
@@ -500,11 +527,11 @@ type HotkeyName = MergedFeatures<RegisteredFeatures<any>>["hotkeys"];
 type HotkeysConfig<T> = Record<HotkeyName, HotkeyConfig<T>>;
 type CustomHotkeysConfig<T> = Partial<Record<HotkeyName | `custom${string}`, Partial<HotkeyConfig<T>>>>;
 type MayReturnNull<T extends (...x: any[]) => any> = (...args: Parameters<T>) => ReturnType<T> | null;
-type ItemInstanceOpts<Key extends keyof ItemInstance<any>> = {
-    item: ItemInstance<any>;
-    tree: TreeInstance<any>;
+type ItemInstanceOpts<T, Key extends keyof ItemInstance<any>> = {
+    item: ItemInstance<T>;
+    tree: TreeInstance<T>;
     itemId: string;
-    prev?: MayReturnNull<ItemInstance<any>[Key]>;
+    prev?: MayReturnNull<ItemInstance<T>[Key]>;
 };
 type TreeInstanceOpts<Key extends keyof TreeInstance<any>> = {
     tree: TreeInstance<any>;
@@ -521,7 +548,7 @@ type FeatureImplementation<T = any> = {
         [key in keyof TreeInstance<T>]?: (opts: TreeInstanceOpts<key>, ...args: Parameters<TreeInstance<T>[key]>) => void;
     };
     itemInstance?: {
-        [key in keyof ItemInstance<T>]?: (opts: ItemInstanceOpts<key>, ...args: Parameters<ItemInstance<T>[key]>) => void;
+        [key in keyof ItemInstance<T>]?: (opts: ItemInstanceOpts<T, key>, ...args: Parameters<ItemInstance<T>[key]>) => void;
     };
     onTreeMount?: (instance: TreeInstance<T>, treeElement: HTMLElement) => void;
     onTreeUnmount?: (instance: TreeInstance<T>, treeElement: HTMLElement) => void;