@react-fabric/data 1.0.0-beta.0

package/src/tree/TreePanel.tsx

@@ -0,0 +1,157 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import {
+  Button,
+  ButtonGroup,
+  CoreIcons,
+  Header,
+  Icon,
+  Section,
+} from "@react-fabric/core";
+import { Search } from "@react-fabric/form";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useMemo, useRef } from "react";
+import { TreeNode } from "./TreeNode";
+import { iconCollapseAll, iconExpandAll, type TreePanelProps } from "./types";
+import { useTree } from "./useTree";
+
+// TODO: implement keyboard handler for navigating tree
+
+export const TreePanel = <T extends KeyValue>({
+  items,
+  selected,
+  checked,
+  checkable,
+  noLines,
+  renderer,
+  searchable,
+  selectable,
+  matcher,
+  filterPlaceholder,
+  defaultLeafIcon,
+  defaultNodeIcon,
+  expander = "box",
+  onChecked,
+  onLoad,
+  onSelect,
+  ...aria
+}: TreePanelProps<T>) => {
+  const {
+    tree,
+    toggleExpand,
+    toggleCheck,
+    expandAll,
+    collapseAll,
+    select,
+    onFilter,
+  } = useTree({
+    items,
+    checked,
+    selected,
+    matcher,
+    onSelect,
+    onChecked,
+  });
+
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  const virtualizer = useVirtualizer({
+    count: tree.length,
+    getScrollElement: () => scrollerRef.current,
+    estimateSize: () => 24,
+  });
+
+  const virtualItems = virtualizer.getVirtualItems();
+
+  const expanders = useMemo<[string, string]>(() => {
+    if (expander === "caret")
+      return [CoreIcons.caretRight, CoreIcons.caretDown];
+    if (expander === "chevron")
+      return [CoreIcons.chevronRight, CoreIcons.chevronDown];
+    if (expander === "folder")
+      return [CoreIcons.folderClosed, CoreIcons.folderOpen];
+    return [CoreIcons.expand, CoreIcons.collapse];
+  }, [expander]);
+
+  return (
+    <Section>
+      <Header
+        flex
+        className="items-center p-px justify-end overflow-hidden border-b"
+      >
+        {searchable && (
+          <Search
+            onSearch={onFilter}
+            allowClear
+            placeholder={filterPlaceholder}
+            {...{ noBorder: true }}
+            decorateStart={<Icon icon={CoreIcons.filter} className="p-1" />}
+          />
+        )}
+        <ButtonGroup variant="link" className="m-0">
+          <Button
+            size="sm"
+            aria-label="expand all"
+            icon={iconExpandAll}
+            onClick={expandAll}
+          />
+          <Button
+            size="sm"
+            aria-label="collapse all"
+            icon={iconCollapseAll}
+            onClick={collapseAll}
+          />
+        </ButtonGroup>
+      </Header>
+      <div
+        ref={scrollerRef}
+        role="tree"
+        className="area-content overflow-auto p-1"
+        {...aria}
+      >
+        <div style={{ height: virtualizer.getTotalSize() }}>
+          <div style={{ height: virtualItems[0]?.start }} />
+          {virtualItems.map(({ index, key }) => (
+            <div key={key} data-index={index} ref={virtualizer.measureElement}>
+              <TreeNode
+                node={tree[index]}
+                noLines={noLines}
+                expanders={expanders}
+                checkable={checkable}
+                selectable={selectable}
+                defaultLeafIcon={defaultLeafIcon}
+                defaultNodeIcon={defaultNodeIcon}
+                onToggle={toggleExpand}
+                onChecked={toggleCheck}
+                onSelect={select}
+              >
+                {(tree[index].data && renderer?.(tree[index].data)) ||
+                  tree[index].label}
+              </TreeNode>
+            </div>
+          ))}
+        </div>
+      </div>
+    </Section>
+  );
+};

package/src/tree/types.ts

@@ -0,0 +1,181 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import {
+  type BadgeType,
+  type ChildProp,
+  type CssProp,
+  type Elements,
+  type IconProps,
+  type TestProps,
+} from "@react-fabric/core/dist/types/types";
+
+interface TreeBaseNode<T> extends IconProps, CssProp, TestProps {
+  id: string;
+  /**
+   * display label
+   */
+  label: Elements<JSX.Element>;
+  /**
+   * full text to be used for querying purposes
+   */
+  queryable?: string;
+  /**
+   * element badge
+   */
+  badge?: string | number | BadgeType;
+  /**
+   * is element `node` or `leaf`
+   */
+  leaf?: boolean;
+  /**
+   * disable selection
+   */
+  disabled?: boolean;
+  data?: T;
+}
+
+export type TreeNodeType<T extends KeyValue = KeyValue> = TreeBaseNode<T> &
+  (
+    | { leaf: true; children?: never }
+    | {
+        leaf?: false;
+        children?: Array<TreeNodeType<T>>;
+        open?: boolean;
+        iconOpen?: string;
+      }
+  );
+
+export interface InternalNode extends IconProps, CssProp, TestProps {
+  id: string;
+  label: Elements<JSX.Element>;
+  queryable?: string;
+  badge?: string | number | BadgeType;
+  disabled?: boolean;
+  leaf: boolean;
+  open: boolean;
+  children?: InternalNode[];
+  level: number;
+  loading: boolean;
+  filtered: boolean;
+  childFiltered?: boolean;
+  parentFiltered?: boolean;
+  loaded: boolean;
+  parent?: string;
+  empty?: boolean;
+  errored?: string;
+  selected?: true;
+  childSelected?: true;
+  checked: 0 | 1 | 2;
+  data?: AnyObject;
+  last?: boolean;
+  lines: Array<0 | 1 | 2 | 3>;
+}
+
+export interface TreeNodeProps extends ChildProp {
+  node: InternalNode;
+  expanders: [string, string];
+  defaultNodeIcon?: string;
+  defaultLeafIcon?: string;
+  noLines?: boolean;
+  selectable?: true | "leafOnly";
+  checkable?: true | "leafOnly";
+  onToggle: (id: string) => void;
+  onSelect: (id: string) => void;
+  onChecked: (id: string) => void;
+}
+
+export interface TreePanelProps<T extends KeyValue = KeyValue>
+  extends TestProps {
+  items?: Array<TreeNodeType<T>>;
+  /**
+   * make tree searchable
+   */
+  searchable?: boolean;
+  /**
+   * filter input placeholder
+   */
+  filterPlaceholder?: string;
+  /**
+   * enable select
+   */
+  selectable?: true | "leafOnly";
+  /**
+   * enable checkable
+   */
+  checkable?: true | "leafOnly";
+  /**
+   * selected item id
+   */
+  selected?: string;
+  /**
+   * checked items
+   */
+  checked?: string[];
+  /**
+   * default node icon
+   */
+  defaultNodeIcon?: string;
+  /**
+   * default leaf icon
+   */
+  defaultLeafIcon?: string;
+  /**
+   * hide level indicator lines
+   */
+  noLines?: boolean;
+  /**
+   * expander icons
+   */
+  expander?: "box" | "caret" | "chevron" | "folder";
+  /**
+   * callback for lazy loading tree items
+   */
+  onLoad?: (
+    id: string,
+  ) =>
+    | Promise<Array<TreeNodeType<T>> | undefined>
+    | Array<TreeNodeType<T>>
+    | undefined;
+  /**
+   * callback on selection of tree node
+   */
+  onSelect?: (id: string) => void;
+  /**
+   * callback on change of checked list
+   */
+  onChecked?: (leafs: string[], nodes: string[]) => void;
+  /**
+   * item label renderer
+   */
+  renderer?: (data: T) => JSX.Element;
+  /**
+   * item filter matcher
+   */
+  matcher?: (data: T, query: string) => boolean;
+}
+
+export const iconExpandAll =
+  "M12.984 9v6h3l-3.984 3.984-3.984-3.984h3v-6h-3l3.984-3.984 3.984 3.984h-3zM3.984 2.016h16.031v1.969h-16.031v-1.969zM3.984 20.016h16.031v1.969h-16.031v-1.969z";
+export const iconCollapseAll =
+  "M3.984 11.016h16.031v1.969h-16.031v-1.969zM15.984 5.016l-3.984 3.984-3.984-3.984h3v-4.031h1.969v4.031h3zM8.016 18.984l3.984-3.984 3.984 3.984h-3v4.031h-1.969v-4.031h-3z";

package/src/tree/useTree.ts

@@ -0,0 +1,227 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import { useDebounce } from "@react-fabric/core";
+import { EMPTY_ARRAY } from "@react-fabric/utilities";
+import memoizeOne from "memoize-one";
+import { useCallback, useEffect, useReducer, useRef } from "react";
+import { type InternalNode, type TreeNodeType } from "./types";
+import {
+  filterTree,
+  flattenTree,
+  makeTreeMap,
+  refactorTree,
+  updateChecked,
+  updateSelection,
+} from "./utils";
+
+type TreeActions =
+  /**
+   * load tree items
+   */
+  | { type: "load"; items: TreeNodeType[] }
+  /**
+   * filter tree nodes
+   */
+  | { type: "filter"; query?: string }
+  /**
+   * update selected item
+   */
+  | { type: "select"; id: string }
+  /**
+   * update item check state
+   */
+  | { type: "checked"; id: string[] }
+  /**
+   * toggle item check, used as action handler
+   */
+  | { type: "toggleCheck"; id: string }
+  /**
+   * expand single item
+   */
+  | { type: "expand"; id: string }
+  /**
+   * collapse single item
+   */
+  | { type: "toggleExpand"; id: string }
+  /**
+   * expand all nodes
+   */
+  | { type: "expandAll" }
+  /**
+   * collapse all nodes
+   */
+  | { type: "collapseAll" };
+
+interface TreeState {
+  items: InternalNode[];
+  itemMap: Map<string, InternalNode>;
+  tree: InternalNode[];
+  selected?: string;
+  checked?: string[];
+}
+
+const createItemList = memoizeOne((items) => items);
+
+export const useTree = <T extends KeyValue>({
+  items = EMPTY_ARRAY,
+  checked = EMPTY_ARRAY,
+  selected,
+  matcher,
+  onSelect,
+  onChecked,
+}: {
+  items?: Array<TreeNodeType<T>>;
+  selected?: string;
+  checked?: string[];
+  onSelect?: (id: string) => void;
+  onChecked?: (leafs: string[], nodes: string[]) => void;
+  matcher?: (data: T, query: string) => boolean;
+}) => {
+  const componentEvents = useRef({ onSelect, onChecked });
+
+  const itemList = createItemList(items);
+
+  const [state, dispatch] = useReducer(
+    (state: TreeState, action: TreeActions) => {
+      if (action.type === "load") {
+        state.items = refactorTree(action.items);
+        state.itemMap = makeTreeMap(state.items);
+        state.tree = flattenTree(state.items);
+        return { ...state };
+      }
+      if (action.type === "toggleExpand") {
+        const node = state.itemMap.get(action.id);
+        node && (node.open = !node.open);
+        state.tree = flattenTree(state.items);
+        return { ...state };
+      }
+      if (action.type === "expand") {
+        // TODO: check if children available, if not call onLoad to fetch node children
+        const node = state.itemMap.get(action.id);
+        node && (node.open = true);
+        state.tree = flattenTree(state.items);
+        return { ...state };
+      }
+      if (action.type === "expandAll") {
+        // TODO: prevent opening dynamic nodes that dont have children
+        state.itemMap.forEach((node) => {
+          !node.leaf && (node.open = true);
+        });
+        state.tree = flattenTree(state.items);
+        return { ...state };
+      }
+      if (action.type === "collapseAll") {
+        state.itemMap.forEach((node) => {
+          !node.leaf && (node.open = false);
+        });
+        state.tree = flattenTree(state.items);
+        return { ...state };
+      }
+      if (action.type === "filter") {
+        filterTree(state.itemMap, action.query, matcher);
+        state.tree = flattenTree(state.items);
+        return { ...state };
+      }
+      if (action.type === "select") {
+        if (state.selected) {
+          updateSelection(state.itemMap, state.selected);
+        }
+        updateSelection(state.itemMap, action.id, true);
+        state.tree = flattenTree(state.items);
+        componentEvents.current.onSelect?.(action.id);
+        return { ...state, selected: action.id };
+      }
+      if (action.type === "toggleCheck") {
+        updateChecked(state.itemMap, action.id);
+        const checkList: string[][] = [[], []];
+        Array.from(state.itemMap.values())
+          .filter((node) => node.checked === 1)
+          .forEach((node) => checkList[node.leaf ? 0 : 1].push(node.id));
+        componentEvents.current.onChecked?.(checkList[0], checkList[1]);
+        return { ...state };
+      }
+      if (action.type === "checked") {
+        action.id.forEach((id) => updateChecked(state.itemMap, id));
+        return { ...state, checked: action.id };
+      }
+      return state;
+    },
+    {
+      itemMap: new Map(),
+      items: [],
+      tree: [],
+      checked: [],
+    },
+  );
+
+  useEffect(() => {
+    componentEvents.current = { onSelect, onChecked };
+  }, [onSelect, onChecked]);
+
+  useEffect(() => {
+    dispatch({ type: "load", items: itemList });
+  }, [itemList]);
+
+  useEffect(() => {
+    selected && dispatch({ type: "select", id: selected });
+  }, [selected]);
+
+  useEffect(() => {
+    checked && dispatch({ type: "checked", id: checked });
+  }, [checked]);
+
+  const toggleExpand = useCallback((id: string) => {
+    dispatch({ type: "toggleExpand", id });
+  }, []);
+
+  const toggleCheck = useCallback((id: string) => {
+    dispatch({ type: "toggleCheck", id });
+  }, []);
+
+  const select = useCallback((id: string) => {
+    dispatch({ type: "select", id });
+  }, []);
+
+  const expandAll = useCallback(() => {
+    dispatch({ type: "expandAll" });
+  }, []);
+
+  const collapseAll = useCallback(() => {
+    dispatch({ type: "collapseAll" });
+  }, []);
+
+  const onFilter = useDebounce((query: string) => {
+    dispatch({ type: "filter", query });
+  }, []);
+
+  return {
+    tree: state.tree,
+    toggleExpand,
+    expandAll,
+    collapseAll,
+    toggleCheck,
+    select,
+    onFilter,
+  };
+};