@mui/x-tree-view 6.0.0-alpha.0

package/TreeView/TreeView.types.d.ts

@@ -0,0 +1,170 @@
+import * as React from 'react';
+import { Theme } from '@mui/material/styles';
+import { SxProps } from '@mui/system';
+import { DefaultizedProps } from '../internals/models';
+import { TreeViewClasses } from './treeViewClasses';
+export interface TreeViewPropsBase extends React.HTMLAttributes<HTMLUListElement> {
+    /**
+     * The content of the component.
+     */
+    children?: React.ReactNode;
+    /**
+     * className applied to the root element.
+     */
+    className?: string;
+    /**
+     * Override or extend the styles applied to the component.
+     */
+    classes?: Partial<TreeViewClasses>;
+    /**
+     * The default icon used to collapse the node.
+     */
+    defaultCollapseIcon?: React.ReactNode;
+    /**
+     * The default icon displayed next to a end node. This is applied to all
+     * tree nodes and can be overridden by the TreeItem `icon` prop.
+     */
+    defaultEndIcon?: React.ReactNode;
+    /**
+     * Expanded node ids.
+     * Used when the item's expansion are not controlled.
+     * @default []
+     */
+    defaultExpanded?: string[];
+    /**
+     * The default icon used to expand the node.
+     */
+    defaultExpandIcon?: React.ReactNode;
+    /**
+     * The default icon displayed next to a parent node. This is applied to all
+     * parent nodes and can be overridden by the TreeItem `icon` prop.
+     */
+    defaultParentIcon?: React.ReactNode;
+    /**
+     * If `true`, will allow focus on disabled items.
+     * @default false
+     */
+    disabledItemsFocusable?: boolean;
+    /**
+     * If `true` selection is disabled.
+     * @default false
+     */
+    disableSelection?: boolean;
+    /**
+     * Expanded node ids.
+     * Used when the item's expansion are controlled.
+     */
+    expanded?: string[];
+    /**
+     * This prop is used to help implement the accessibility logic.
+     * If you don't provide this prop. It falls back to a randomly generated id.
+     */
+    id?: string;
+    /**
+     * Callback fired when tree items are focused.
+     * @param {React.SyntheticEvent} event The event source of the callback **Warning**: This is a generic event not a focus event.
+     * @param {string} nodeId The id of the node focused.
+     * @param {string} value of the focused node.
+     */
+    onNodeFocus?: (event: React.SyntheticEvent, nodeId: string) => void;
+    /**
+     * Callback fired when tree items are expanded/collapsed.
+     * @param {React.SyntheticEvent} event The event source of the callback.
+     * @param {array} nodeIds The ids of the expanded nodes.
+     */
+    onNodeToggle?: (event: React.SyntheticEvent, nodeIds: string[]) => void;
+    /**
+     * The system prop that allows defining system overrides as well as additional CSS styles.
+     */
+    sx?: SxProps<Theme>;
+}
+export interface MultiSelectTreeViewProps extends TreeViewPropsBase {
+    /**
+     * Selected node ids. (Uncontrolled)
+     * When `multiSelect` is true this takes an array of strings; when false (default) a string.
+     * @default []
+     */
+    defaultSelected?: string[];
+    /**
+     * Selected node ids. (Controlled)
+     * When `multiSelect` is true this takes an array of strings; when false (default) a string.
+     */
+    selected?: string[];
+    /**
+     * If true `ctrl` and `shift` will trigger multiselect.
+     * @default false
+     */
+    multiSelect?: true;
+    /**
+     * Callback fired when tree items are selected/unselected.
+     * @param {React.SyntheticEvent} event The event source of the callback
+     * @param {string[] | string} nodeIds Ids of the selected nodes. When `multiSelect` is true
+     * this is an array of strings; when false (default) a string.
+     */
+    onNodeSelect?: (event: React.SyntheticEvent, nodeIds: string[]) => void;
+}
+export interface SingleSelectTreeViewProps extends TreeViewPropsBase {
+    /**
+     * Selected node ids. (Uncontrolled)
+     * When `multiSelect` is true this takes an array of strings; when false (default) a string.
+     * @default []
+     */
+    defaultSelected?: string | null;
+    /**
+     * Selected node ids. (Controlled)
+     * When `multiSelect` is true this takes an array of strings; when false (default) a string.
+     */
+    selected?: string | null;
+    /**
+     * If true `ctrl` and `shift` will trigger multiselect.
+     * @default false
+     */
+    multiSelect?: false;
+    /**
+     * Callback fired when tree items are selected/unselected.
+     * @param {React.SyntheticEvent} event The event source of the callback
+     * @param {string[] | string} nodeIds Ids of the selected nodes. When `multiSelect` is true
+     * this is an array of strings; when false (default) a string.
+     */
+    onNodeSelect?: (event: React.SyntheticEvent, nodeIds: string) => void;
+}
+export type TreeViewProps = SingleSelectTreeViewProps | MultiSelectTreeViewProps;
+export type TreeViewDefaultizedProps = DefaultizedProps<TreeViewProps, 'defaultExpanded' | 'defaultSelected' | 'disabledItemsFocusable' | 'disableSelection' | 'multiSelect'>;
+export interface TreeViewNode {
+    id: string;
+    idAttribute: string | undefined;
+    index: number;
+    parentId: string | null;
+    expandable: boolean;
+    disabled: boolean | undefined;
+}
+export interface TreeViewItemRange {
+    start?: string | null;
+    end?: string | null;
+    next?: string | null;
+    current?: string;
+}
+export interface TreeViewContextValue {
+    registerNode: (node: TreeViewNode) => void;
+    unregisterNode: (nodeId: string) => void;
+    isFocused: (nodeId: string) => boolean;
+    isSelected: (nodeId: string) => boolean;
+    isExpanded: (nodeId: string) => boolean;
+    isExpandable: (nodeId: string) => boolean;
+    isDisabled: (nodeId: string) => boolean;
+    mapFirstChar: (nodeId: string, firstChar: string) => void;
+    unMapFirstChar: (nodeId: string) => void;
+    focus: (event: React.SyntheticEvent, nodeId: string) => void;
+    toggleExpansion: (event: React.SyntheticEvent, value?: string) => void;
+    selectNode: (event: React.SyntheticEvent, nodeId: string, multiple?: boolean) => void;
+    selectRange: (event: React.SyntheticEvent, nodes: TreeViewItemRange, stacked?: boolean) => void;
+    multiSelect: boolean;
+    disabledItemsFocusable: boolean;
+    treeId: string | undefined;
+    icons: {
+        defaultCollapseIcon: React.ReactNode;
+        defaultExpandIcon: React.ReactNode;
+        defaultParentIcon: React.ReactNode;
+        defaultEndIcon: React.ReactNode;
+    };
+}

package/TreeView/TreeView.types.js

@@ -0,0 +1 @@
+export {};

package/TreeView/TreeViewContext.d.ts

@@ -0,0 +1,6 @@
+import * as React from 'react';
+import { TreeViewContextValue } from './TreeView.types';
+/**
+ * @ignore - internal component.
+ */
+export declare const TreeViewContext: React.Context<TreeViewContextValue>;

package/TreeView/TreeViewContext.js

@@ -0,0 +1,31 @@
+import * as React from 'react';
+/**
+ * @ignore - internal component.
+ */
+export const TreeViewContext = /*#__PURE__*/React.createContext({
+  registerNode: () => {},
+  unregisterNode: () => {},
+  isFocused: () => false,
+  isSelected: () => false,
+  isExpanded: () => false,
+  isExpandable: () => false,
+  isDisabled: () => false,
+  mapFirstChar: () => {},
+  unMapFirstChar: () => {},
+  focus: () => {},
+  toggleExpansion: () => {},
+  selectNode: () => {},
+  selectRange: () => {},
+  multiSelect: false,
+  disabledItemsFocusable: false,
+  treeId: undefined,
+  icons: {
+    defaultCollapseIcon: null,
+    defaultExpandIcon: null,
+    defaultParentIcon: null,
+    defaultEndIcon: null
+  }
+});
+if (process.env.NODE_ENV !== 'production') {
+  TreeViewContext.displayName = 'TreeViewContext';
+}

package/TreeView/descendants.d.ts

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import PropTypes from 'prop-types';
+/**
+ * This hook registers our descendant by passing it into an array. We can then
+ * search that array by to find its index when registering it in the component.
+ * We use this for focus management, keyboard navigation, and typeahead
+ * functionality for some components.
+ *
+ * The hook accepts the element node
+ *
+ * Our main goals with this are:
+ *   1) maximum composability,
+ *   2) minimal API friction
+ *   3) SSR compatibility*
+ *   4) concurrent safe
+ *   5) index always up-to-date with the tree despite changes
+ *   6) works with memoization of any component in the tree (hopefully)
+ *
+ * * As for SSR, the good news is that we don't actually need the index on the
+ * server for most use-cases, as we are only using it to determine the order of
+ * composed descendants for keyboard navigation.
+ */
+export declare function useDescendant(descendant: TreeItemDescendant): {
+    parentId: string | null;
+    index: number;
+};
+interface DescendantProviderProps {
+    id?: string;
+    children: React.ReactNode;
+}
+export declare function DescendantProvider(props: DescendantProviderProps): React.JSX.Element;
+export declare namespace DescendantProvider {
+    var propTypes: {
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        id: PropTypes.Requireable<string>;
+    };
+}
+export interface TreeItemDescendant {
+    element: HTMLLIElement;
+    id: string;
+}
+export {};

package/TreeView/descendants.js

@@ -0,0 +1,186 @@
+import _objectWithoutPropertiesLoose from "@babel/runtime/helpers/esm/objectWithoutPropertiesLoose";
+import _extends from "@babel/runtime/helpers/esm/extends";
+const _excluded = ["element"];
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import useEnhancedEffect from '@mui/utils/useEnhancedEffect';
+
+/** Credit: https://github.com/reach/reach-ui/blob/86a046f54d53b6420e392b3fa56dd991d9d4e458/packages/descendants/README.md
+ *  Modified slightly to suit our purposes.
+ */
+
+// To replace with .findIndex() once we stop IE11 support.
+import { jsx as _jsx } from "react/jsx-runtime";
+function findIndex(array, comp) {
+  for (let i = 0; i < array.length; i += 1) {
+    if (comp(array[i])) {
+      return i;
+    }
+  }
+  return -1;
+}
+function binaryFindElement(array, element) {
+  let start = 0;
+  let end = array.length - 1;
+  while (start <= end) {
+    const middle = Math.floor((start + end) / 2);
+    if (array[middle].element === element) {
+      return middle;
+    }
+
+    // eslint-disable-next-line no-bitwise
+    if (array[middle].element.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_PRECEDING) {
+      end = middle - 1;
+    } else {
+      start = middle + 1;
+    }
+  }
+  return start;
+}
+const DescendantContext = /*#__PURE__*/React.createContext({});
+if (process.env.NODE_ENV !== 'production') {
+  DescendantContext.displayName = 'DescendantContext';
+}
+function usePrevious(value) {
+  const ref = React.useRef(null);
+  React.useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref.current;
+}
+const noop = () => {};
+
+/**
+ * This hook registers our descendant by passing it into an array. We can then
+ * search that array by to find its index when registering it in the component.
+ * We use this for focus management, keyboard navigation, and typeahead
+ * functionality for some components.
+ *
+ * The hook accepts the element node
+ *
+ * Our main goals with this are:
+ *   1) maximum composability,
+ *   2) minimal API friction
+ *   3) SSR compatibility*
+ *   4) concurrent safe
+ *   5) index always up-to-date with the tree despite changes
+ *   6) works with memoization of any component in the tree (hopefully)
+ *
+ * * As for SSR, the good news is that we don't actually need the index on the
+ * server for most use-cases, as we are only using it to determine the order of
+ * composed descendants for keyboard navigation.
+ */
+export function useDescendant(descendant) {
+  const [, forceUpdate] = React.useState();
+  const {
+    registerDescendant = noop,
+    unregisterDescendant = noop,
+    descendants = [],
+    parentId = null
+  } = React.useContext(DescendantContext);
+
+  // This will initially return -1 because we haven't registered the descendant
+  // on the first render. After we register, this will then return the correct
+  // index on the following render, and we will re-register descendants
+  // so that everything is up-to-date before the user interacts with a
+  // collection.
+  const index = findIndex(descendants, item => item.element === descendant.element);
+  const previousDescendants = usePrevious(descendants);
+
+  // We also need to re-register descendants any time ANY of the other
+  // descendants have changed. My brain was melting when I wrote this and it
+  // feels a little off, but checking in render and using the result in the
+  // effect's dependency array works well enough.
+  const someDescendantsHaveChanged = descendants.some((newDescendant, position) => {
+    return previousDescendants && previousDescendants[position] && previousDescendants[position].element !== newDescendant.element;
+  });
+
+  // Prevent any flashing
+  useEnhancedEffect(() => {
+    if (descendant.element) {
+      registerDescendant(_extends({}, descendant, {
+        index
+      }));
+      return () => {
+        unregisterDescendant(descendant.element);
+      };
+    }
+    forceUpdate({});
+    return undefined;
+  }, [registerDescendant, unregisterDescendant, index, someDescendantsHaveChanged, descendant]);
+  return {
+    parentId,
+    index
+  };
+}
+export function DescendantProvider(props) {
+  const {
+    children,
+    id
+  } = props;
+  const [items, set] = React.useState([]);
+  const registerDescendant = React.useCallback(_ref => {
+    let {
+        element
+      } = _ref,
+      other = _objectWithoutPropertiesLoose(_ref, _excluded);
+    set(oldItems => {
+      if (oldItems.length === 0) {
+        // If there are no items, register at index 0 and bail.
+        return [_extends({}, other, {
+          element,
+          index: 0
+        })];
+      }
+      const index = binaryFindElement(oldItems, element);
+      let newItems;
+      if (oldItems[index] && oldItems[index].element === element) {
+        // If the element is already registered, just use the same array
+        newItems = oldItems;
+      } else {
+        // When registering a descendant, we need to make sure we insert in
+        // into the array in the same order that it appears in the DOM. So as
+        // new descendants are added or maybe some are removed, we always know
+        // that the array is up-to-date and correct.
+        //
+        // So here we look at our registered descendants and see if the new
+        // element we are adding appears earlier than an existing descendant's
+        // DOM node via `node.compareDocumentPosition`. If it does, we insert
+        // the new element at this index. Because `registerDescendant` will be
+        // called in an effect every time the descendants state value changes,
+        // we should be sure that this index is accurate when descendent
+        // elements come or go from our component.
+
+        const newItem = _extends({}, other, {
+          element,
+          index
+        });
+
+        // If an index is not found we will push the element to the end.
+        newItems = oldItems.slice();
+        newItems.splice(index, 0, newItem);
+      }
+      newItems.forEach((item, position) => {
+        item.index = position;
+      });
+      return newItems;
+    });
+  }, []);
+  const unregisterDescendant = React.useCallback(element => {
+    set(oldItems => oldItems.filter(item => element !== item.element));
+  }, []);
+  const value = React.useMemo(() => ({
+    descendants: items,
+    registerDescendant,
+    unregisterDescendant,
+    parentId: id
+  }), [items, registerDescendant, unregisterDescendant, id]);
+  return /*#__PURE__*/_jsx(DescendantContext.Provider, {
+    value: value,
+    children: children
+  });
+}
+process.env.NODE_ENV !== "production" ? DescendantProvider.propTypes = {
+  children: PropTypes.node,
+  id: PropTypes.string
+} : void 0;

package/TreeView/index.d.ts

@@ -0,0 +1,3 @@
+export * from './TreeView';
+export * from './treeViewClasses';
+export type { TreeViewProps, SingleSelectTreeViewProps, MultiSelectTreeViewProps, TreeViewPropsBase, } from './TreeView.types';

package/TreeView/index.js

@@ -0,0 +1,3 @@
+export * from './TreeView';
+export * from './treeViewClasses';
+export {};

package/TreeView/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": false,
+  "module": "./index.js",
+  "main": "../node/TreeView/index.js",
+  "types": "./index.d.ts"
+}

package/TreeView/treeViewClasses.d.ts

@@ -0,0 +1,7 @@
+export interface TreeViewClasses {
+    /** Styles applied to the root element. */
+    root: string;
+}
+export type TreeViewClassKey = keyof TreeViewClasses;
+export declare function getTreeViewUtilityClass(slot: string): string;
+export declare const treeViewClasses: TreeViewClasses;

package/TreeView/treeViewClasses.js

@@ -0,0 +1,6 @@
+import generateUtilityClass from '@mui/utils/generateUtilityClass';
+import generateUtilityClasses from '@mui/utils/generateUtilityClasses';
+export function getTreeViewUtilityClass(slot) {
+  return generateUtilityClass('MuiTreeView', slot);
+}
+export const treeViewClasses = generateUtilityClasses('MuiTreeView', ['root']);

package/index.d.ts

@@ -0,0 +1,2 @@
+export * from './TreeItem';
+export * from './TreeView';

package/index.js

@@ -0,0 +1,9 @@
+/**
+ * @mui/x-tree-view v6.0.0-alpha.0
+ *
+ * @license MIT
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export * from './TreeItem';
+export * from './TreeView';

package/internals/models.d.ts

@@ -0,0 +1 @@
+export type DefaultizedProps<P extends {}, RequiredProps extends keyof P, AdditionalProps extends {} = {}> = Omit<P, RequiredProps | keyof AdditionalProps> & Required<Pick<P, RequiredProps>> & AdditionalProps;

package/internals/models.js

@@ -0,0 +1 @@
+export {};