@headless-tree/core 0.0.0-20230802230636

package/src/core/create-tree.ts

@@ -0,0 +1,228 @@
+import {
+  FeatureImplementation,
+  HotkeysConfig,
+  ItemInstance,
+  TreeConfig,
+  TreeInstance,
+  TreeState,
+} from "../types/core";
+import { MainFeatureDef } from "../features/main/types";
+import { treeFeature } from "../features/tree/feature";
+import { ItemMeta } from "../features/tree/types";
+
+const buildItemInstance = (
+  features: FeatureImplementation[],
+  tree: TreeInstance<any>,
+  itemId: string
+) => {
+  const itemInstance = {} as ItemInstance<any>;
+  for (const feature of features) {
+    Object.assign(
+      itemInstance,
+      feature.createItemInstance?.(
+        { ...itemInstance },
+        itemInstance,
+        tree,
+        itemId
+      ) ?? {}
+    );
+  }
+  return itemInstance;
+};
+
+const verifyFeatures = (features: FeatureImplementation[] | undefined) => {
+  const loadedFeatures = features?.map((feature) => feature.key);
+  for (const feature of features ?? []) {
+    const missingDependency = feature.deps?.find(
+      (dep) => !loadedFeatures?.includes(dep)
+    );
+    if (missingDependency) {
+      throw new Error(`${feature.key} needs ${missingDependency}`);
+    }
+  }
+};
+
+const compareFeatures = (
+  feature1: FeatureImplementation,
+  feature2: FeatureImplementation
+) => {
+  if (feature2.key && feature1.overwrites?.includes(feature2.key)) {
+    return 1;
+  }
+  return -1;
+};
+
+const sortFeatures = (features: FeatureImplementation[] = []) =>
+  features.sort(compareFeatures);
+
+export const createTree = <T>(
+  initialConfig: TreeConfig<T>
+): TreeInstance<T> => {
+  const treeInstance: TreeInstance<T> = {} as any;
+
+  const additionalFeatures = [
+    treeFeature,
+    ...sortFeatures(initialConfig.features),
+  ];
+  verifyFeatures(additionalFeatures);
+
+  let state = additionalFeatures.reduce(
+    (acc, feature) => feature.getInitialState?.(acc, treeInstance) ?? acc,
+    initialConfig.initialState ?? initialConfig.state ?? {}
+  ) as TreeState<T>;
+  let config = additionalFeatures.reduce(
+    (acc, feature) => feature.getDefaultConfig?.(acc, treeInstance) ?? acc,
+    initialConfig
+  ) as TreeConfig<T>;
+  const stateHandlerNames = additionalFeatures.reduce(
+    (acc, feature) => ({ ...acc, ...feature.stateHandlerNames }),
+    {} as Record<string, string>
+  );
+
+  let treeElement: HTMLElement | undefined | null;
+  const treeDataRef: { current: any } = { current: {} };
+
+  const itemInstancesMap: Record<string, ItemInstance<T>> = {};
+  let itemInstances: ItemInstance<T>[] = [];
+  const itemElementsMap: Record<string, HTMLElement | undefined | null> = {};
+  const itemDataRefs: Record<string, { current: any }> = {};
+  let itemMetaMap: Record<string, ItemMeta> = {};
+
+  const hotkeyPresets = {} as HotkeysConfig<T>;
+
+  const rebuildItemMeta = (main: FeatureImplementation) => {
+    // TODO can we find a way to only run this for the changed substructure?
+    itemInstances = [];
+    itemMetaMap = {};
+
+    const rootInstance = buildItemInstance(
+      [main, ...additionalFeatures],
+      treeInstance,
+      config.rootItemId
+    );
+    itemInstancesMap[config.rootItemId] = rootInstance;
+    itemMetaMap[config.rootItemId] = {
+      itemId: config.rootItemId,
+      index: -1,
+      parentId: null!,
+      level: -1,
+      posInSet: 0,
+      setSize: 1,
+    };
+
+    for (const item of treeInstance.getItemsMeta()) {
+      itemMetaMap[item.itemId] = item;
+      if (!itemInstancesMap[item.itemId]) {
+        const instance = buildItemInstance(
+          [main, ...additionalFeatures],
+          treeInstance,
+          item.itemId
+        );
+        itemInstancesMap[item.itemId] = instance;
+        itemInstances.push(instance);
+      } else {
+        itemInstances.push(itemInstancesMap[item.itemId]);
+      }
+    }
+    console.log("REBUILT");
+  };
+
+  const eachFeature = (fn: (feature: FeatureImplementation<any>) => void) => {
+    for (const feature of additionalFeatures) {
+      fn(feature);
+    }
+  };
+
+  const mainFeature: FeatureImplementation<
+    T,
+    MainFeatureDef<T>,
+    MainFeatureDef<T>
+  > = {
+    key: "main",
+    createTreeInstance: (prev) => ({
+      ...prev,
+      getState: () => state,
+      setState: (updater) => {
+        // Not necessary, since I think the subupdate below keeps the state fresh anyways?
+        // state = typeof updater === "function" ? updater(state) : updater;
+        config.setState?.(state);
+      },
+      applySubStateUpdate: (stateName, updater) => {
+        state[stateName] =
+          typeof updater === "function" ? updater(state[stateName]) : updater;
+        config[stateHandlerNames[stateName]]!(state[stateName]);
+      },
+      rebuildTree: () => {
+        rebuildItemMeta(mainFeature);
+        config.setState?.(state);
+      },
+      getConfig: () => config,
+      setConfig: (updater) => {
+        config = typeof updater === "function" ? updater(config) : updater;
+
+        if (config.state) {
+          state = { ...state, ...config.state };
+        }
+      },
+      getItemInstance: (itemId) => itemInstancesMap[itemId],
+      getItems: () => itemInstances,
+      registerElement: (element) => {
+        if (treeElement === element) {
+          return;
+        }
+
+        if (treeElement && !element) {
+          eachFeature((feature) =>
+            feature.onTreeUnmount?.(treeInstance, treeElement!)
+          );
+        } else if (!treeElement && element) {
+          eachFeature((feature) =>
+            feature.onTreeMount?.(treeInstance, element)
+          );
+        }
+        treeElement = element;
+      },
+      getElement: () => treeElement,
+      getDataRef: () => treeDataRef,
+      getHotkeyPresets: () => hotkeyPresets,
+    }),
+    createItemInstance: (prev, instance, _, itemId) => ({
+      ...prev,
+      registerElement: (element) => {
+        if (itemElementsMap[itemId] === element) {
+          return;
+        }
+
+        const oldElement = itemElementsMap[itemId];
+        if (oldElement && !element) {
+          eachFeature((feature) =>
+            feature.onItemUnmount?.(instance, oldElement!, treeInstance)
+          );
+        } else if (!oldElement && element) {
+          eachFeature((feature) =>
+            feature.onItemMount?.(instance, element!, treeInstance)
+          );
+        }
+        itemElementsMap[itemId] = element;
+      },
+      getElement: () => itemElementsMap[itemId],
+      // eslint-disable-next-line no-return-assign
+      getDataRef: () => (itemDataRefs[itemId] ??= { current: {} }),
+      getItemMeta: () => itemMetaMap[itemId],
+    }),
+  };
+
+  const features = [mainFeature, ...additionalFeatures];
+
+  for (const feature of features) {
+    Object.assign(
+      treeInstance,
+      feature.createTreeInstance?.({ ...treeInstance }, treeInstance) ?? {}
+    );
+    Object.assign(hotkeyPresets, feature.hotkeys ?? {});
+  }
+
+  rebuildItemMeta(mainFeature);
+
+  return treeInstance;
+};

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

@@ -0,0 +1,126 @@
+import { FeatureImplementation } from "../../types/core";
+import { AsyncDataLoaderFeatureDef, AsyncDataLoaderRef } from "./types";
+import { MainFeatureDef } from "../main/types";
+import { makeStateUpdater } from "../../utils";
+import { TreeFeatureDef } from "../tree/types";
+
+export const asyncDataLoaderFeature: FeatureImplementation<
+  any,
+  AsyncDataLoaderFeatureDef<any>,
+  MainFeatureDef | TreeFeatureDef<any> | AsyncDataLoaderFeatureDef<any>
+> = {
+  key: "async-data-loader",
+
+  getInitialState: (initialState) => ({
+    loadingItems: [],
+    ...initialState,
+  }),
+
+  getDefaultConfig: (defaultConfig, tree) => ({
+    setLoadingItems: makeStateUpdater("loadingItems", tree),
+    ...defaultConfig,
+  }),
+
+  stateHandlerNames: {
+    loadingItems: "setLoadingItems",
+  },
+
+  createTreeInstance: (prev, instance) => ({
+    ...prev,
+
+    retrieveItemData: (itemId) => {
+      const config = instance.getConfig();
+      const dataRef = instance.getDataRef<AsyncDataLoaderRef>();
+      dataRef.current.itemData ??= {};
+      dataRef.current.childrenIds ??= {};
+
+      if (dataRef.current.itemData[itemId]) {
+        return dataRef.current.itemData[itemId];
+      }
+
+      if (!instance.getState().loadingItems.includes(itemId)) {
+        instance.applySubStateUpdate("loadingItems", (loadingItems) => [
+          ...loadingItems,
+          itemId,
+        ]);
+        config.asyncDataLoader?.getItem(itemId).then((item) => {
+          dataRef.current.itemData[itemId] = item;
+          config.onLoadedItem?.(itemId, item);
+          instance.applySubStateUpdate("loadingItems", (loadingItems) =>
+            loadingItems.filter((id) => id !== itemId)
+          );
+        });
+      }
+
+      return config.createLoadingItemData?.() ?? null;
+    },
+
+    retrieveChildrenIds: (itemId) => {
+      const config = instance.getConfig();
+      const dataRef = instance.getDataRef<AsyncDataLoaderRef>();
+      dataRef.current.itemData ??= {};
+      dataRef.current.childrenIds ??= {};
+      if (dataRef.current.childrenIds[itemId]) {
+        return dataRef.current.childrenIds[itemId];
+      }
+
+      if (instance.getState().loadingItems.includes(itemId)) {
+        return [];
+      }
+
+      instance.applySubStateUpdate("loadingItems", (loadingItems) => [
+        ...loadingItems,
+        itemId,
+      ]);
+
+      if (config.asyncDataLoader?.getChildrenWithData) {
+        config.asyncDataLoader?.getChildrenWithData(itemId).then((children) => {
+          for (const { id, data } of children) {
+            dataRef.current.itemData[id] = data;
+            config.onLoadedItem?.(id, data);
+          }
+          const childrenIds = children.map(({ id }) => id);
+          dataRef.current.childrenIds[itemId] = childrenIds;
+          config.onLoadedChildren?.(itemId, childrenIds);
+          instance.applySubStateUpdate("loadingItems", (loadingItems) =>
+            loadingItems.filter((id) => id !== itemId)
+          );
+          instance.rebuildTree();
+        });
+      } else {
+        config.asyncDataLoader?.getChildren(itemId).then((childrenIds) => {
+          dataRef.current.childrenIds[itemId] = childrenIds;
+          config.onLoadedChildren?.(itemId, childrenIds);
+          instance.applySubStateUpdate("loadingItems", (loadingItems) =>
+            loadingItems.filter((id) => id !== itemId)
+          );
+          instance.rebuildTree();
+        });
+      }
+
+      return [];
+    },
+
+    invalidateItemData: (itemId) => {
+      const dataRef = instance.getDataRef<AsyncDataLoaderRef>();
+      delete dataRef.current.itemData?.[itemId];
+      instance.retrieveItemData(itemId);
+    },
+
+    invalidateChildrenIds: (itemId) => {
+      const dataRef = instance.getDataRef<AsyncDataLoaderRef>();
+      delete dataRef.current.childrenIds?.[itemId];
+      instance.retrieveChildrenIds(itemId);
+    },
+  }),
+
+  createItemInstance: (prev, item, tree) => ({
+    ...prev,
+    isLoading: () =>
+      tree.getState().loadingItems.includes(item.getItemMeta().itemId),
+    invalidateItemData: () =>
+      tree.invalidateItemData(item.getItemMeta().itemId),
+    invalidateChildrenIds: () =>
+      tree.invalidateChildrenIds(item.getItemMeta().itemId),
+  }),
+};

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

@@ -0,0 +1,41 @@
+import { SetStateFn } from "../../types/core";
+import { SyncDataLoaderFeatureDef } from "../sync-data-loader/types";
+
+export type AsyncTreeDataLoader<T> = {
+  getItem: (itemId: string) => Promise<T>;
+  getChildren: (itemId: string) => Promise<string[]>;
+  getChildrenWithData?: (itemId: string) => Promise<{ id: string; data: T }[]>;
+};
+
+export type AsyncDataLoaderRef<T = any> = {
+  itemData: Record<string, T>;
+  childrenIds: Record<string, string[]>;
+};
+
+/**
+ * @category Async Data Loader/General
+ * */
+export type AsyncDataLoaderFeatureDef<T> = {
+  state: {
+    loadingItems: string[];
+  };
+  config: {
+    rootItemId: string;
+    createLoadingItemData?: () => T;
+    setLoadingItems?: SetStateFn<string[]>;
+    onLoadedItem?: (itemId: string, item: T) => void;
+    onLoadedChildren?: (itemId: string, childrenIds: string[]) => void;
+    asyncDataLoader?: AsyncTreeDataLoader<T>;
+  };
+  treeInstance: SyncDataLoaderFeatureDef<T>["treeInstance"] & {
+    /** Invalidate fetched data for item, and triggers a refetch and subsequent rerender if the item is visible */
+    invalidateItemData: (itemId: string) => void;
+    invalidateChildrenIds: (itemId: string) => void;
+  };
+  itemInstance: SyncDataLoaderFeatureDef<T>["itemInstance"] & {
+    invalidateItemData: () => void;
+    invalidateChildrenIds: () => void;
+    isLoading: () => void;
+  };
+  hotkeys: SyncDataLoaderFeatureDef<T>["hotkeys"];
+};

package/src/features/drag-and-drop/feature.ts

@@ -0,0 +1,214 @@
+import { FeatureDefs, FeatureImplementation } from "../../types/core";
+import { DndDataRef, DragAndDropFeatureDef, DragLineData } from "./types";
+import { canDrop, getDragCode, getDropTarget } from "./utils";
+import { makeStateUpdater } from "../../utils";
+
+export const dragAndDropFeature: FeatureImplementation<
+  any,
+  DragAndDropFeatureDef<any>,
+  FeatureDefs<any>
+> = {
+  key: "dragAndDrop",
+  deps: ["selection"],
+
+  getDefaultConfig: (defaultConfig, tree) => ({
+    canDrop: (_, target) => target.item.isFolder(),
+    canDropForeignDragObject: () => false,
+    setDndState: makeStateUpdater("dnd", tree),
+    ...defaultConfig,
+  }),
+
+  stateHandlerNames: {
+    dnd: "setDndState",
+  },
+
+  createTreeInstance: (prev, tree) => ({
+    ...prev,
+
+    getDropTarget: () => {
+      return tree.getState().dnd?.dragTarget ?? null;
+    },
+
+    getDragLineData: (): DragLineData | null => {
+      const target = tree.getDropTarget();
+      const intend = (target?.item.getItemMeta().level ?? 0) + 1;
+
+      if (!target || target.childIndex === null) return null;
+
+      const children = target.item.getChildren();
+
+      if (target.childIndex === children.length) {
+        const bb = children[target.childIndex - 1]
+          ?.getElement()
+          ?.getBoundingClientRect();
+
+        if (bb) {
+          return {
+            intend,
+            top: bb.bottom,
+            left: bb.left,
+            right: bb.right,
+          };
+        }
+      }
+
+      const bb = children[target.childIndex]
+        ?.getElement()
+        ?.getBoundingClientRect();
+
+      if (bb) {
+        return {
+          intend,
+          top: bb.top,
+          left: bb.left,
+          right: bb.right,
+        };
+      }
+
+      return null;
+    },
+  }),
+
+  createItemInstance: (prev, item, tree) => ({
+    ...prev,
+
+    getProps: () => ({
+      ...prev.getProps(),
+
+      draggable: tree.getConfig().isItemDraggable?.(item) ?? true,
+
+      onDragStart: item.getMemoizedProp("dnd/onDragStart", () => (e) => {
+        const selectedItems = tree.getSelectedItems();
+        const items = selectedItems.includes(item) ? selectedItems : [item];
+        const config = tree.getConfig();
+
+        if (!selectedItems.includes(item)) {
+          tree.setSelectedItems([item.getItemMeta().itemId]);
+        }
+
+        if (!(config.canDrag?.(items) ?? true)) {
+          e.preventDefault();
+          return;
+        }
+
+        if (config.createForeignDragObject) {
+          const { format, data } = config.createForeignDragObject(items);
+          e.dataTransfer?.setData(format, data);
+        }
+
+        tree.applySubStateUpdate("dnd", {
+          draggedItems: items,
+          draggingOverItem: tree.getFocusedItem(),
+        });
+      }),
+
+      onDragOver: item.getMemoizedProp("dnd/onDragOver", () => (e) => {
+        const target = getDropTarget(e, item, tree);
+        const dataRef = tree.getDataRef<DndDataRef>();
+
+        if (
+          !tree.getState().dnd?.draggedItems &&
+          !tree.getConfig().canDropForeignDragObject?.(e.dataTransfer, target)
+        ) {
+          return;
+        }
+
+        if (!canDrop(e.dataTransfer, target, tree)) {
+          return;
+        }
+
+        e.preventDefault();
+        const nextDragCode = getDragCode(target);
+
+        if (nextDragCode === dataRef.current.lastDragCode) {
+          return;
+        }
+
+        dataRef.current.lastDragCode = nextDragCode;
+
+        tree.applySubStateUpdate("dnd", (state) => ({
+          ...state,
+          dragTarget: target,
+          draggingOverItem: item,
+        }));
+      }),
+
+      onDragLeave: item.getMemoizedProp("dnd/onDragLeave", () => () => {
+        const dataRef = tree.getDataRef<DndDataRef>();
+        dataRef.current.lastDragCode = "no-drag";
+        tree.applySubStateUpdate("dnd", (state) => ({
+          ...state,
+          draggingOverItem: undefined,
+          dragTarget: undefined,
+        }));
+      }),
+
+      onDragEnd: item.getMemoizedProp("dnd/onDragEnd", () => (e) => {
+        const draggedItems = tree.getState().dnd?.draggedItems;
+        tree.applySubStateUpdate("dnd", null);
+
+        if (e.dataTransfer.dropEffect === "none" || !draggedItems) {
+          return;
+        }
+
+        tree.getConfig().onCompleteForeignDrop?.(draggedItems);
+      }),
+
+      onDrop: item.getMemoizedProp("dnd/onDrop", () => (e) => {
+        const dataRef = tree.getDataRef<DndDataRef>();
+        const target = getDropTarget(e, item, tree);
+
+        if (!canDrop(e.dataTransfer, target, tree)) {
+          return;
+        }
+
+        e.preventDefault();
+        const config = tree.getConfig();
+        const draggedItems = tree.getState().dnd?.draggedItems;
+
+        dataRef.current.lastDragCode = undefined;
+        tree.applySubStateUpdate("dnd", null);
+
+        if (draggedItems) {
+          config.onDrop?.(draggedItems, target);
+        } else {
+          config.onDropForeignDragObject?.(e.dataTransfer, target);
+        }
+        // TODO rebuild tree?
+      }),
+    }),
+
+    isDropTarget: () => {
+      const target = tree.getDropTarget();
+      return target ? target.item.getId() === item.getId() : false;
+    },
+
+    isDropTargetAbove: () => {
+      const target = tree.getDropTarget();
+
+      if (
+        !target ||
+        target.childIndex === null ||
+        target.item !== item.getParent()
+      )
+        return false;
+      return target.childIndex === item.getItemMeta().posInSet;
+    },
+
+    isDropTargetBelow: () => {
+      const target = tree.getDropTarget();
+
+      if (
+        !target ||
+        target.childIndex === null ||
+        target.item !== item.getParent()
+      )
+        return false;
+      return target.childIndex - 1 === item.getItemMeta().posInSet;
+    },
+
+    isDraggingOver: () => {
+      return tree.getState().dnd?.draggingOverItem?.getId() === item.getId();
+    },
+  }),
+};

package/src/features/drag-and-drop/types.ts

@@ -0,0 +1,89 @@
+import { ItemInstance, SetStateFn } from "../../types/core";
+
+export type DndDataRef = {
+  lastDragCode?: string;
+};
+
+export type DndState<T> = {
+  draggedItems?: ItemInstance<T>[]; // TODO not used anymore?
+  draggingOverItem?: ItemInstance<T>;
+  dragTarget?: DropTarget<T>;
+};
+
+export type DragLineData = {
+  intend: number;
+  top: number;
+  left: number;
+  right: number;
+};
+
+export type DropTarget<T> =
+  | {
+      item: ItemInstance<T>;
+      childIndex: number;
+      insertionIndex: number;
+    }
+  | {
+      item: ItemInstance<T>;
+      childIndex: null;
+      insertionIndex: null;
+    };
+
+export enum DropTargetPosition {
+  Top = "top",
+  Bottom = "bottom",
+  Item = "item",
+}
+
+export type DragAndDropFeatureDef<T> = {
+  state: {
+    dnd?: DndState<T> | null;
+  };
+  config: {
+    setDndState?: SetStateFn<DndState<T> | null>;
+
+    topLinePercentage?: number;
+    bottomLinePercentage?: number;
+    canDropInbetween?: boolean;
+
+    isItemDraggable?: (item: ItemInstance<T>) => boolean;
+    canDrag?: (items: ItemInstance<T>[]) => boolean;
+    canDrop?: (items: ItemInstance<T>[], target: DropTarget<T>) => boolean;
+
+    createForeignDragObject?: (items: ItemInstance<T>[]) => {
+      format: string;
+      data: any;
+    };
+    canDropForeignDragObject?: (
+      dataTransfer: DataTransfer,
+      target: DropTarget<T>
+    ) => boolean;
+    onDrop?: (items: ItemInstance<T>[], target: DropTarget<T>) => void;
+    onDropForeignDragObject?: (
+      dataTransfer: DataTransfer,
+      target: DropTarget<T>
+    ) => void;
+
+    /** Runs in the onDragEnd event, if `ev.dataTransfer.dropEffect` is not `none`, i.e. the drop
+     * was not aborted. No target is provided as parameter since the target may be a foreign drop target.
+     * This is useful to seperate out the logic to move dragged items out of their previous parents.
+     * Use `onDrop` to handle drop-related logic.
+     *
+     * This ignores the `canDrop` handler, since the drop target is unknown in this handler.
+     */
+    // onSuccessfulDragEnd?: (items: ItemInstance<T>[]) => void;
+
+    onCompleteForeignDrop?: (items: ItemInstance<T>[]) => void;
+  };
+  treeInstance: {
+    getDropTarget: () => DropTarget<T> | null;
+    getDragLineData: () => DragLineData | null;
+  };
+  itemInstance: {
+    isDropTarget: () => boolean;
+    isDropTargetAbove: () => boolean;
+    isDropTargetBelow: () => boolean;
+    isDraggingOver: () => boolean;
+  };
+  hotkeys: never;
+};