@react-fabric/data 1.0.0-beta.5 → 1.0.0-beta.52

package/src/table/useVirtualTable.ts

@@ -21,78 +21,200 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { useVirtualizer } from "@tanstack/react-virtual";
-import { useCallback, useReducer, useRef } from "react";
+import { compareValues, groupBy } from "@react-fabric/utilities";
+import {
+  defaultRangeExtractor,
+  type Range,
+  useVirtualizer,
+} from "@tanstack/react-virtual";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from "react";
 
-interface DataState {
-  checked: Key[];
+interface DataState<T = KeyValue> {
+  data: T[];
+  items: T[];
+  grouped: KeyValue<T[]>;
+  groups: AnyObject[];
+  expanded: AnyObject[];
+  checked: AnyObject[];
   allChecked: 0 | 1 | 2;
 }
 
-type DataAction = { type: "check"; key: Key } | { type: "checkall" };
+type DataAction =
+  | { type: "updateState"; checked: AnyObject[] }
+  | { type: "groupExpand"; key: AnyObject }
+  | { type: "reset"; key: AnyObject; data: AnyObject[] }
+  | { type: "expand"; key: AnyObject }
+  | { type: "check"; key: AnyObject }
+  | { type: "checkall" };
 
-export const useVirtualTable = (
-  data: KeyValue[],
-  keyProperty?: Key,
-  onCheckChanged?: (checked: Key[]) => void,
+export const useVirtualTable = <T extends KeyValue = KeyValue>(
+  data: T[],
+  options: {
+    checked?: AnyObject[];
+    keyProperty: keyof T;
+    groupProperty?: keyof T;
+    onCheckChanged?: (checked: AnyObject[]) => void;
+  },
 ) => {
   // TODO: refactor data into item list, apply grouping if groupColumn provided
   // TODO: when grouping maintain map of group with children, {___GROUP___:true, label, items, open}
 
-  const scrollerRef = useRef<HTMLDivElement>(null);
-  const virtualizer = useVirtualizer({
-    count: data.length,
-    getScrollElement: () => scrollerRef.current,
-    estimateSize: () => 24,
-  });
-
   const [state, dispatch] = useReducer(
-    (state: DataState, action: DataAction) => {
+    (state: DataState<T>, action: DataAction) => {
+      if (action.type === "updateState") {
+        state.checked = action.checked;
+      }
+      if (action.type === "expand") {
+        if (state.expanded.includes(action.key))
+          state.expanded.splice(state.expanded.indexOf(action.key), 1);
+        else state.expanded.push(action.key);
+      }
       if (action.type === "check") {
         if (state.checked.includes(action.key))
           state.checked.splice(state.checked.indexOf(action.key), 1);
         else state.checked.push(action.key);
+        options.onCheckChanged?.(state.checked);
       }
       if (action.type === "checkall") {
         if (state.allChecked !== 0) {
           state.checked = [];
-        } else if (keyProperty) {
-          state.checked = data.map((item) => item[keyProperty]);
+        } else if (options.keyProperty) {
+          state.checked = state.data.map((item) => item[options.keyProperty]);
+        }
+        options.onCheckChanged?.(state.checked);
+      }
+      const checkList = state.data.filter((hit) =>
+        state.checked.includes(hit[options.keyProperty]),
+      );
+      if (action.type === "groupExpand") {
+        const group = state.groups.find((group) => group.key === action.key);
+        if (group) {
+          group.open = !group.open;
+          state.groups = state.groups.slice();
+          state.items = state.groups
+            .map((group) => [
+              group,
+              group.open ? state.grouped[group.key] : undefined,
+            ])
+            .flat(2)
+            .filter(Boolean) as any;
+        }
+      }
+      if (action.type === "reset") {
+        state.data = action.data;
+        if (action.key) {
+          state.grouped = groupBy<T>(state.data, action.key);
+          state.groups = Object.keys(state.grouped)
+            .sort(compareValues("asc"))
+            .map((group) => ({
+              __GROUP__: true,
+              open: true,
+              key: group,
+              items: state.grouped[group],
+              itemCount: state.grouped[group].length,
+            }));
+          state.items = state.groups
+            .map((group) => [group, ...state.grouped[group.key]])
+            .flat() as any;
+        } else {
+          state.items = state.data;
         }
       }
-      onCheckChanged?.(state.checked);
       return {
         ...state,
         allChecked:
-          state.checked.length === data.length
+          checkList.length === state.data.length
             ? 1
             : state.checked.length
               ? 2
               : 0,
-      } as DataState;
+      } as DataState<T>;
     },
     {
+      data,
+      items: [],
+      grouped: {},
+      groups: [],
       checked: [],
+      expanded: [],
       allChecked: 0,
     },
   );
 
+  const activeStickyIndexRef = useRef(0);
+  const stickyIndexes = useMemo<number[]>(
+    () =>
+      state.items
+        .map((hit, idx) => ("__GROUP__" in hit ? idx : undefined))
+        .filter(Boolean) as number[],
+    [state.items],
+  );
+  const isActiveSticky = (index: number) =>
+    activeStickyIndexRef.current === index;
+
+  const [hasActiveSticky, setHasActiveSticky] = useState(false);
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  const virtualizer = useVirtualizer({
+    count: state.items.length,
+    getScrollElement: () => scrollerRef.current,
+    estimateSize: () => 32,
+    rangeExtractor: useCallback(
+      (range: Range) => {
+        activeStickyIndexRef.current =
+          [...stickyIndexes]
+            .reverse()
+            .find((index) => range.startIndex > index) ?? 0;
+
+        setHasActiveSticky(range.startIndex !== activeStickyIndexRef.current);
+
+        const next = new Set([
+          activeStickyIndexRef.current,
+          ...defaultRangeExtractor(range),
+        ]);
+
+        return [...next];
+      },
+      [stickyIndexes],
+    ),
+  });
+
   const virtualItems = virtualizer.getVirtualItems();
 
   const getData = useCallback(
     (index: number) => {
-      return data[index];
+      return state.items[index];
     },
-    [data],
+    [state.items],
   );
 
+  useEffect(() => {
+    dispatch({ type: "reset", key: options.groupProperty, data });
+  }, [data, options.groupProperty]);
+
+  useEffect(() => {
+    dispatch({ type: "updateState", checked: options.checked ?? [] });
+  }, [options.checked]);
+
   return {
     scrollerRef,
     items: virtualItems,
     checkState: state,
     getData,
+    virtualizer,
+    hasActiveSticky,
+    isActiveSticky,
+    top: virtualizer.range?.startIndex,
     totalSize: virtualizer.getTotalSize,
     measureElement: virtualizer.measureElement,
+    toggleGroupExpand: (key: Key) => dispatch({ type: "groupExpand", key }),
+    toggleExpand: (key: Key) => dispatch({ type: "expand", key }),
     toggleChecked: (key: Key) => dispatch({ type: "check", key }),
     toggleAllChecked: () => dispatch({ type: "checkall" }),
   };

package/src/tree/TreeNode.tsx

@@ -22,8 +22,10 @@
  */
 
 import { Badge, CoreIcons, getBadgeProps, Icon } from "@react-fabric/core";
+import { isEmpty, isString } from "@react-fabric/utilities";
 import classNames from "classnames";
-import { useMemo } from "react";
+import { isValidElement, useMemo } from "react";
+import { useTranslation } from "react-i18next";
 import { type TreeNodeProps } from "./types";
 
 export const TreeNode = ({
@@ -35,30 +37,43 @@ export const TreeNode = ({
   defaultLeafIcon,
   defaultNodeIcon,
   onToggle,
+  onClick,
   onSelect,
   onChecked,
   children,
+  leafClassName,
+  nodeClassName,
 }: TreeNodeProps) => {
+  const { t } = useTranslation("data");
   const badgeProps = useMemo(() => {
     return getBadgeProps(node.badge);
   }, [node.badge]);
 
   const filler = useMemo(() => {
-    return node.lines.slice(noLines ? 1 : 0).map((line, idx) => (
-      <svg
+    return node.lines.slice(1).map((line, idx) => (
+      <div
         key={idx}
-        viewBox="0 0 24 24"
-        className="flex-initial w-6 fill-tint-200"
-      >
-        {line === 0 && <path d="" />}
-        {!noLines && line === 1 && <path d="M7.45 26.1v-28.2h1.1v28.2h-1.1z" />}
-        {!noLines && line === 2 && (
-          <path d="M14.989 12.389l0.161-0.389-0.161-0.389-0.389-0.161h-6.050v-13.55h-1.1v14.1l0.161 0.389 0.389 0.161h6.6z" />
-        )}
-        {!noLines && line === 3 && (
-          <path d="M8.55 12.55h6.050l0.389-0.161 0.161-0.389-0.161-0.389-0.389-0.161h-6.050v-13.55h-1.1v28.2h1.1z" />
+        className={classNames(
+          "flex-initial self-stretch flex items-center w-6 relative",
+          !noLines &&
+            line > 0 &&
+            "before:absolute before:top-0 before:start-[7px] before:bg-tint-200 before:min-h-[50%] before:w-[2px] before:scale-x-[.625]",
+          !noLines && line !== 2 && "before:h-full",
         )}
-      </svg>
+      >
+        <svg viewBox="0 0 24 24" className="fill-tint-200 rtl:-scale-x-100">
+          {line === 0 && <path d="" />}
+          {!noLines && line === 1 && (
+            <path d="M7.45 26.1v-28.2h1.1v28.2h-1.1z" />
+          )}
+          {!noLines && line === 2 && (
+            <path d="M14.989 12.389l0.161-0.389-0.161-0.389-0.389-0.161h-6.050v-13.55h-1.1v14.1l0.161 0.389 0.389 0.161h6.6z" />
+          )}
+          {!noLines && line === 3 && (
+            <path d="M8.55 12.55h6.050l0.389-0.161 0.161-0.389-0.161-0.389-0.389-0.161h-6.050v-13.55h-1.1v28.2h1.1z" />
+          )}
+        </svg>
+      </div>
     ));
   }, [noLines, node.lines]);
 
@@ -82,12 +97,21 @@ export const TreeNode = ({
     <div
       role="treeitem"
       aria-selected={node.selected}
-      className="flex flex-nowrap"
+      className={classNames(
+        "flex flex-nowrap items-center",
+        node.className,
+        node.leaf ? leafClassName : nodeClassName,
+      )}
       data-testid={node["data-testid"]}
       data-test-value={node["data-test-value"]}
     >
       {filler}
-      {!node.leaf && !node.childFiltered && (
+      {node.loading && (
+        <div className="flex-initial w-6">
+          <Icon icon={CoreIcons.spinner} className="animate-spin text-muted" />
+        </div>
+      )}
+      {!node.leaf && !node.childFiltered && !node.loading && (
         <div className="flex-initial w-6">
           <Icon
             rtlFlip
@@ -116,48 +140,66 @@ export const TreeNode = ({
           />
         </div>
       )}
-      <div
-        role="none"
-        className={classNames(
-          "group data-[selected]:bg-primary-100 flex flex-nowrap flex-1 items-center overflow-hidden select-none",
-          node.childSelected && "font-medium",
-          canSelect && "hover:bg-primary-50 cursor-pointer",
-        )}
-        data-selected={node.selected}
-        onClick={() =>
-          canSelect
-            ? onSelect(node.id)
-            : canCheck
-              ? onChecked(node.id)
-              : onToggle(node.id)
-        }
-      >
-        {nodeIcon && (
-          <div className="flex-content w-6">
-            <Icon
-              icon={nodeIcon}
-              bg={node.iconBg}
-              color={node.iconColor}
-              rtlFlip={node.rtlFlip}
-            />
+      {!node.empty && (
+        <div
+          role="none"
+          className={classNames(
+            "group/tool data-[selected]:bg-primary-100 flex flex-nowrap flex-1 overflow-hidden select-none",
+            node.childSelected && "font-medium",
+            node.disabled && "text-muted opacity-65",
+            !node.disabled &&
+              (canSelect || onClick) &&
+              "hover:bg-primary-50 cursor-pointer",
+          )}
+          data-selected={node.selected}
+          onClick={
+            node.disabled
+              ? undefined
+              : () => {
+                  onClick?.(node.id, node.data);
+                  canSelect
+                    ? onSelect(node.id)
+                    : canCheck
+                      ? onChecked(node.id)
+                      : onToggle(node.id);
+                }
+          }
+        >
+          {nodeIcon && (
+            <div className="flex-content w-6 self-center leading-none">
+              {isValidElement(nodeIcon) && nodeIcon}
+              {isString(nodeIcon) && (
+                <Icon
+                  icon={nodeIcon}
+                  bg={node.iconBg}
+                  color={node.iconColor}
+                  rtlFlip={node.rtlFlip}
+                />
+              )}
+            </div>
+          )}
+          {node.childSelected && !node.open && (
+            <span className=" flex-content text-primary-500">•</span>
+          )}
+          <div role="none" className="flex-1 truncate">
+            {children}
           </div>
-        )}
-        {node.childSelected && !node.open && (
-          <span className=" flex-content text-primary-500">•</span>
-        )}
-        <div role="none" className="flex-1 truncate">
-          {children}
+          {!isEmpty(node.badge) && (
+            <Badge
+              {...badgeProps}
+              className={classNames(
+                "me-1 self-center flex-content bg-opacity-50",
+                badgeProps.className,
+              )}
+            />
+          )}
         </div>
-        {node.badge && (
-          <Badge
-            {...badgeProps}
-            className={classNames(
-              "me-1 self-center flex-content bg-opacity-50",
-              badgeProps.className,
-            )}
-          />
-        )}
-      </div>
+      )}
+      {node.empty && (
+        <div className="text-muted text-sm select-none">
+          {t("tree.noItems")}
+        </div>
+      )}
     </div>
   );
 };

package/src/tree/TreePanel.tsx

@@ -38,6 +38,47 @@ import { useTree } from "./useTree";
 
 // TODO: implement keyboard handler for navigating tree
 
+/**
+ * TreePanel component renders a virtualized tree structure with support for
+ * selection, expansion, and filtering. It allows for custom rendering of tree
+ * nodes and supports checkable nodes.
+ *
+ * @param {TreePanelProps<T>} props - The properties for the TreePanel component.
+ * @returns {JSX.Element} The rendered TreePanel component.
+ * @template T - The type of items in the tree, extending KeyValue.
+ *
+ * @example
+ * ```jsx
+ * <TreePanel
+ *   items={items}
+ *   selected={selectedItem}
+ *   checked={checkedItems}
+ *   checkable={true}
+ *   renderer={(item) => <span>{item.name}</span>}
+ *   searchable={true}
+ *   selectable={true}
+ *   matcher={(item, query) => item.name.toLowerCase().includes(query.toLowerCase())}
+ *   filterPlaceholder="Search..."
+ *   defaultLeafIcon={<Icon icon={CoreIcons.file} />}
+ *   defaultNodeIcon={<Icon icon={CoreIcons.folder} />}
+ *   expander="caret"
+ *   onChecked={(checkedItems) => console.log(checkedItems)}
+ *   onLoad={(id) => console.log(`Load children for ${id}`)}
+ *   onQuery={(query) => console.log(`Query: ${query}`)}
+ *   onSelect={(selectedItem) => console.log(selectedItem)}
+ *   onClick={(item) => console.log(`Clicked on ${item.id}`)}
+ *   sorter={(a, b) => a.label.localeCompare(b.label)}
+ *   makeLabel={(item) => item.name}
+ *   makeIcon={(item) => item.icon ? <Icon icon={item.icon} /> : null}
+ *   defaultExpanded={["root"]}
+ *   onExpandToggle={(id, expanded) => console.log(`Toggle expand for ${id}: ${expanded}`)}
+ *   leafClassName="leaf-node"
+ *   nodeClassName="tree-node"
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/data-treepanel--docs}
+ */
 export const TreePanel = <T extends KeyValue>({
   ref,
   items,
@@ -55,7 +96,16 @@ export const TreePanel = <T extends KeyValue>({
   expander = "box",
   onChecked,
   onLoad,
+  onQuery,
   onSelect,
+  onClick,
+  sorter,
+  makeLabel,
+  makeIcon,
+  defaultExpanded,
+  onExpandToggle,
+  leafClassName,
+  nodeClassName,
   ...aria
 }: TreePanelProps<T>) => {
   const {
@@ -72,8 +122,13 @@ export const TreePanel = <T extends KeyValue>({
     checked,
     selected,
     matcher,
+    sorter,
+    onLoad,
+    onQuery,
     onSelect,
     onChecked,
+    defaultExpanded,
+    onExpandToggle,
   });
 
   const scrollerRef = useRef<HTMLDivElement>(null);
@@ -99,7 +154,7 @@ export const TreePanel = <T extends KeyValue>({
     ref,
     () => ({
       open: (id: string) => expand(id),
-      select: (id: string) => expand(id),
+      select: (id: string) => select(id),
     }),
     [],
   );
@@ -151,12 +206,18 @@ export const TreePanel = <T extends KeyValue>({
                 checkable={checkable}
                 selectable={selectable}
                 defaultLeafIcon={defaultLeafIcon}
-                defaultNodeIcon={defaultNodeIcon}
+                defaultNodeIcon={
+                  makeIcon?.(tree[index].data) ?? defaultNodeIcon
+                }
                 onToggle={toggleExpand}
                 onChecked={toggleCheck}
                 onSelect={select}
+                onClick={onClick}
+                leafClassName={leafClassName}
+                nodeClassName={nodeClassName}
               >
-                {(tree[index].data && renderer?.(tree[index].data)) ||
+                {(tree[index].data && renderer?.(tree[index].data)) ??
+                  makeLabel?.(tree[index].data) ??
                   tree[index].label}
               </TreeNode>
             </div>

package/src/tree/types.ts

@@ -30,8 +30,9 @@ import {
   type RefProp,
   type TestProps,
 } from "@react-fabric/core/dist/types/types";
+import { type ElementType } from "react";
 
-interface TreeBaseNode<T> extends IconProps, CssProp, TestProps {
+interface TreeBaseNode<T> extends Omit<IconProps, "icon">, CssProp, TestProps {
   id: string;
   /**
    * display label
@@ -54,20 +55,25 @@ interface TreeBaseNode<T> extends IconProps, CssProp, TestProps {
    */
   disabled?: boolean;
   data?: T;
+
+  icon?: ElementType<IconProps> | string;
 }
 
 export type TreeNodeType<T extends KeyValue = KeyValue> = TreeBaseNode<T> &
   (
     | { leaf: true; children?: never }
     | {
-        leaf?: false;
+        leaf?: boolean;
         children?: Array<TreeNodeType<T>>;
         open?: boolean;
         iconOpen?: string;
       }
   );
 
-export interface InternalNode extends IconProps, CssProp, TestProps {
+export interface InternalNode
+  extends Omit<IconProps, "icon">,
+    CssProp,
+    TestProps {
   id: string;
   label: Elements<JSX.Element>;
   queryable?: string;
@@ -84,6 +90,7 @@ export interface InternalNode extends IconProps, CssProp, TestProps {
   loaded: boolean;
   parent?: string;
   empty?: boolean;
+  icon?: ElementType<IconProps> | string;
   errored?: string;
   selected?: true;
   childSelected?: true;
@@ -101,9 +108,12 @@ export interface TreeNodeProps extends ChildProp {
   noLines?: boolean;
   selectable?: true | "leafOnly";
   checkable?: true | "leafOnly";
+  leafClassName?: string;
+  nodeClassName?: string;
   onToggle: (id: string) => void;
   onSelect: (id: string) => void;
   onChecked: (id: string) => void;
+  onClick?: (id: string, node: any) => void;
 }
 
 export interface TreeRef {
@@ -164,10 +174,18 @@ export interface TreePanelProps<T extends KeyValue = KeyValue>
     | Promise<Array<TreeNodeType<T>> | undefined>
     | Array<TreeNodeType<T>>
     | undefined;
+  /**
+   * callback to load tree using search query
+   */
+  onQuery?: (query: string) => void;
+  /**
+   * callback on click of tree node
+   */
+  onClick?: (id: string, data: T) => void;
   /**
    * callback on selection of tree node
    */
-  onSelect?: (id: string) => void;
+  onSelect?: (id: string, data: T) => void;
   /**
    * callback on change of checked list
    */
@@ -180,6 +198,16 @@ export interface TreePanelProps<T extends KeyValue = KeyValue>
    * item filter matcher
    */
   matcher?: (data: T, query: string) => boolean;
+
+  sorter?: false | ((a: T, b: T) => number);
+  makeLabel?: (node: T) => string;
+  makeIcon?: (node: T) => string;
+
+  defaultExpanded?: string[];
+  onExpandToggle?: (id: string[]) => void;
+
+  leafClassName?: string;
+  nodeClassName?: string;
 }
 
 export const iconExpandAll =