@fluentui/react-tree - npm Package Compare versions

Comparing version 9.0.0-beta.1 to 9.0.0-beta.2

CHANGELOG.json

@@ -5,3 +5,18 @@ {
     {
-      "date": "Fri, 10 Mar 2023 07:11:10 GMT",
+      "date": "Fri, 10 Mar 2023 13:28:18 GMT",
+      "tag": "@fluentui/react-tree_v9.0.0-beta.2",
+      "version": "9.0.0-beta.2",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "[e-mail]",
+            "package": "@fluentui/react-tree",
+            "commit": "4e092355bfa9457409d7fc3b4e617681bc9d3c85",
+            "comment": "feat: creates useFlatTree hook to improve API"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Fri, 10 Mar 2023 07:14:01 GMT",
       "tag": "@fluentui/react-tree_v9.0.0-beta.1",
@@ -8,0 +23,0 @@ "version": "9.0.0-beta.1",

CHANGELOG.md

 # Change Log - @fluentui/react-tree
 
-This log was last generated on Fri, 10 Mar 2023 07:11:10 GMT and should not be manually modified.
+This log was last generated on Fri, 10 Mar 2023 13:28:18 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## [9.0.0-beta.2](https://github.com/microsoft/fluentui/tree/@fluentui/react-tree_v9.0.0-beta.2)
+
+Fri, 10 Mar 2023 13:28:18 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-tree_v9.0.0-beta.1..@fluentui/react-tree_v9.0.0-beta.2)
+
+### Changes
+
+- feat: creates useFlatTree hook to improve API ([PR #27146](https://github.com/microsoft/fluentui/pull/27146) by [e-mail])
+
 ## [9.0.0-beta.1](https://github.com/microsoft/fluentui/tree/@fluentui/react-tree_v9.0.0-beta.1)
 
-Fri, 10 Mar 2023 07:11:10 GMT
+Fri, 10 Mar 2023 07:14:01 GMT
 
@@ -11,0 +20,0 @@ ### Changes

dist/index.d.ts

@@ -28,9 +28,73 @@ /// <reference types="react" />
  */
-export declare const flattenTree_unstable: (items: NestedTreeItem[]) => FlatTreeItem[];
+export declare const flattenTree_unstable: (items: NestedTreeItem[]) => FlatTreeItemProps[];
 
-export declare type FlatTreeItem = Required<Pick<TreeItemProps, 'id'>> & TreeItemProps & {
+/**
+ * FlatTree API to manage all required mechanisms to convert a list of items into renderable TreeItems
+ * in multiple scenarios including virtualization.
+ *
+ * !!A flat tree is an unofficial spec for tree!!
+ *
+ * It should be used on cases where more complex interactions with a Tree is required.
+ *
+ * On simple scenarios it is advised to simply use a nested structure instead.
+ */
+export declare type FlatTree = {
+    /**
+     * returns the properties required for the Tree component to work properly.
+     * That includes:
+     * `openItems`, `onOpenChange`, `onNavigation_unstable` and `ref`
+     */
+    getTreeProps(): FlatTreeProps;
+    /**
+     * internal method used to react to an `onNavigation` event.
+     * This method ensures proper navigation on keyboard and mouse interaction.
+     * In case of virtualization it might be required to cancel default provided `onNavigation`
+     * event and then call this method manually.
+     *
+     * @example
+     * ```ts
+     * // react-window
+     * const handleNavigation = (event, data) => {
+     *   event.preventDefault();
+     *   const nextItem = tree.getNextNavigableItem(data);
+     *   // scroll to item using virtualization scroll mechanism
+     *   if (nextItem && !targetDocument.getElementById(nextItem.id)) {
+     *     listRef.current.scrollToItem(nextItem.index);
+     *   }
+     *   // wait for scrolling to happen and then invoke navigate method
+     *   requestAnimationFrame(() => {
+     *     tree.navigate(data);
+     *   });
+     * };
+     *```
+     */
+    navigate(data: TreeNavigationData_unstable): void;
+    /**
+     * returns next item to be focused on a navigation.
+     * This method is provided to decouple the element that needs to be focused from
+     *  the action of focusing it itself.
+     */
+    getNextNavigableItem(data: TreeNavigationData_unstable): FlatTreeItem | null;
+    /**
+     * returns a single flat tree item by id without iterating over the whole collection
+     */
+    getItem(id: string): FlatTreeItem | null;
+    /**
+     * returns an iterable containing all visually available flat tree items
+     */
+    items(): Iterable<FlatTreeItem>;
+};
+
+export declare type FlatTreeItem = {
+    getTreeItemProps(): Required<Pick<TreeItemProps, 'id' | 'aria-setsize' | 'aria-level' | 'aria-posinset' | 'leaf'>> & TreeItemProps;
     parentId?: string;
+    childrenSize: number;
+    index: number;
+    id: string;
+    level: number;
 };
 
-export declare type FlatTreeItemProps = Required<Pick<TreeItemProps, 'id' | 'aria-level' | 'aria-posinset' | 'leaf' | 'aria-setsize'>> & TreeItemProps;
+export declare type FlatTreeItemProps = Required<Pick<TreeItemProps, 'id'>> & TreeItemProps & {
+    parentId?: string;
+};
 
@@ -67,11 +131,2 @@ export declare type FlatTreeProps = Required<Pick<TreeProps, 'openItems' | 'onOpenChange' | 'onNavigation_unstable'> & {
 
-declare type LazyArray<Value> = {
-    map<NextValue>(fn: (child: Value) => NextValue): NextValue[];
-    toArray(): Value[];
-};
-
-export declare type LazyFlatTreeItems = LazyArray<FlatTreeItemProps> & {
-    get(id: string): TreeItemPropsReference | null;
-};
-
 export declare type NestedTreeItem = Omit<TreeItemProps, 'subtree'> & {
@@ -239,9 +294,2 @@ subtree?: NestedTreeItem[];
 
-declare type TreeItemPropsReference = {
-    props: Required<Pick<TreeItemProps, 'id' | 'aria-level' | 'aria-posinset' | 'leaf'>> & TreeItemProps;
-    parentId?: string;
-    childrenSize: number;
-    index: number;
-};
-
 export declare const TreeItemProvider: React_2.Provider<TreeItemContextValue | undefined>;
@@ -401,6 +449,16 @@
 
-export declare function useFlatTreeItems_unstable(items: FlatTreeItem[], options?: UseFlatTreeItemsOptions): readonly [FlatTreeProps, LazyFlatTreeItems];
+/**
+ * this hook provides FlatTree API to manage all required mechanisms to convert a list of items into renderable TreeItems
+ * in multiple scenarios including virtualization.
+ *
+ * !!A flat tree is an unofficial spec for tree!!
+ *
+ * It should be used on cases where more complex interactions with a Tree is required.
+ * On simple scenarios it is advised to simply use a nested structure instead.
+ *
+ * @param items - a list of tree items
+ * @param options - in case control over the internal openItems is required
+ */
+export declare function useFlatTree_unstable(items: FlatTreeItemProps[], options?: Pick<TreeProps, 'openItems' | 'defaultOpenItems'>): FlatTree;
 
-export declare type UseFlatTreeItemsOptions = Pick<TreeProps, 'openItems' | 'defaultOpenItems'>;
-
 /**
@@ -407,0 +465,0 @@ * Create the state required to render Tree.

lib-commonjs/hooks/index.js

@@ -7,5 +7,5 @@ "use strict";
 const tslib_1 = /*#__PURE__*/require("tslib");
-tslib_1.__exportStar(require("./useFlatTreeItems"), exports);
+tslib_1.__exportStar(require("./useFlatTree"), exports);
 tslib_1.__exportStar(require("./useNestedTreeNavigation"), exports);
 tslib_1.__exportStar(require("./useOpenItemsState"), exports);
 //# sourceMappingURL=index.js.map

lib-commonjs/hooks/useFlatTreeNavigation.js

@@ -8,8 +8,8 @@ "use strict";
 const react_shared_contexts_1 = /*#__PURE__*/require("@fluentui/react-shared-contexts");
+const react_utilities_1 = /*#__PURE__*/require("@fluentui/react-utilities");
 const nextTypeAheadElement_1 = /*#__PURE__*/require("../utils/nextTypeAheadElement");
-const useHTMLElementWalker_1 = /*#__PURE__*/require("./useHTMLElementWalker");
 const tokens_1 = /*#__PURE__*/require("../utils/tokens");
 const treeItemFilter_1 = /*#__PURE__*/require("../utils/treeItemFilter");
+const useHTMLElementWalker_1 = /*#__PURE__*/require("./useHTMLElementWalker");
 const useRovingTabIndexes_1 = /*#__PURE__*/require("./useRovingTabIndexes");
-const react_utilities_1 = /*#__PURE__*/require("@fluentui/react-utilities");
 function useFlatTreeNavigation(flatTree) {
@@ -75,6 +75,6 @@ const {
 }
-function parentElement(flatTree, target, targetDocument) {
-  const item = flatTree.get(target.id);
-  if (item && item.parentId) {
-    return targetDocument.getElementById(item.parentId);
+function parentElement(flatTree, target, document) {
+  const flatTreeItem = flatTree.itemsPerId.get(target.id);
+  if (flatTreeItem && flatTreeItem.parentId) {
+    return document.getElementById(flatTreeItem.parentId);
   }
@@ -81,0 +81,0 @@ return null;

lib-commonjs/index.js

@@ -6,3 +6,3 @@ "use strict";
 });
-exports.flattenTree_unstable = exports.useFlatTreeItems_unstable = exports.useTreeItemPersonaLayout_unstable = exports.useTreeItemPersonaLayoutStyles_unstable = exports.renderTreeItemPersonaLayout_unstable = exports.treeItemPersonaLayoutClassNames = exports.TreeItemPersonaLayout = exports.useTreeItemLayout_unstable = exports.useTreeItemLayoutStyles_unstable = exports.renderTreeItemLayout_unstable = exports.treeItemLayoutClassNames = exports.TreeItemLayout = exports.useTreeItem_unstable = exports.useTreeItemStyles_unstable = exports.renderTreeItem_unstable = exports.treeItemClassNames = exports.TreeItem = exports.treeItemLevelToken = exports.TreeItemProvider = exports.useTreeItemContext_unstable = exports.useTreeContext_unstable = exports.TreeProvider = exports.useTreeContextValues_unstable = exports.useTree_unstable = exports.useTreeStyles_unstable = exports.renderTree_unstable = exports.treeClassNames = exports.Tree = void 0;
+exports.flattenTree_unstable = exports.useFlatTree_unstable = exports.useTreeItemPersonaLayout_unstable = exports.useTreeItemPersonaLayoutStyles_unstable = exports.renderTreeItemPersonaLayout_unstable = exports.treeItemPersonaLayoutClassNames = exports.TreeItemPersonaLayout = exports.useTreeItemLayout_unstable = exports.useTreeItemLayoutStyles_unstable = exports.renderTreeItemLayout_unstable = exports.treeItemLayoutClassNames = exports.TreeItemLayout = exports.useTreeItem_unstable = exports.useTreeItemStyles_unstable = exports.renderTreeItem_unstable = exports.treeItemClassNames = exports.TreeItem = exports.treeItemLevelToken = exports.TreeItemProvider = exports.useTreeItemContext_unstable = exports.useTreeContext_unstable = exports.TreeProvider = exports.useTreeContextValues_unstable = exports.useTree_unstable = exports.useTreeStyles_unstable = exports.renderTree_unstable = exports.treeClassNames = exports.Tree = void 0;
 var Tree_1 = /*#__PURE__*/require("./Tree");
@@ -171,6 +171,6 @@ Object.defineProperty(exports, "Tree", {
 var index_1 = /*#__PURE__*/require("./hooks/index");
-Object.defineProperty(exports, "useFlatTreeItems_unstable", {
+Object.defineProperty(exports, "useFlatTree_unstable", {
   enumerable: true,
   get: function () {
-    return index_1.useFlatTreeItems_unstable;
+    return index_1.useFlatTree_unstable;
   }
@@ -177,0 +177,0 @@ });

lib/hooks/index.js

@@ -1,4 +0,4 @@
-export * from './useFlatTreeItems';
+export * from './useFlatTree';
 export * from './useNestedTreeNavigation';
 export * from './useOpenItemsState';
 //# sourceMappingURL=index.js.map

lib/hooks/useFlatTreeNavigation.js

 import { useFluent_unstable } from '@fluentui/react-shared-contexts';
+import { useMergedRefs } from '@fluentui/react-utilities';
 import { nextTypeAheadElement } from '../utils/nextTypeAheadElement';
-import { useHTMLElementWalkerRef } from './useHTMLElementWalker';
 import { treeDataTypes } from '../utils/tokens';
 import { treeItemFilter } from '../utils/treeItemFilter';
+import { useHTMLElementWalkerRef } from './useHTMLElementWalker';
 import { useRovingTabIndex } from './useRovingTabIndexes';
-import { useMergedRefs } from '@fluentui/react-utilities';
 export function useFlatTreeNavigation(flatTree) {
@@ -67,6 +67,6 @@ const {
 }
-function parentElement(flatTree, target, targetDocument) {
-  const item = flatTree.get(target.id);
-  if (item && item.parentId) {
-    return targetDocument.getElementById(item.parentId);
+function parentElement(flatTree, target, document) {
+  const flatTreeItem = flatTree.itemsPerId.get(target.id);
+  if (flatTreeItem && flatTreeItem.parentId) {
+    return document.getElementById(flatTreeItem.parentId);
   }
@@ -73,0 +73,0 @@ return null;

lib/index.js

@@ -7,4 +7,4 @@ export { Tree, treeClassNames, renderTree_unstable, useTreeStyles_unstable, useTree_unstable, useTreeContextValues_unstable } from './Tree';
 export { TreeItemPersonaLayout, treeItemPersonaLayoutClassNames, renderTreeItemPersonaLayout_unstable, useTreeItemPersonaLayoutStyles_unstable, useTreeItemPersonaLayout_unstable } from './TreeItemPersonaLayout';
-export { useFlatTreeItems_unstable } from './hooks/index';
+export { useFlatTree_unstable } from './hooks/index';
 export { flattenTree_unstable } from './utils/flattenTree';
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "@fluentui/react-tree",
-  "version": "9.0.0-beta.1",
+  "version": "9.0.0-beta.2",
   "description": "React components for building web experiences",
@@ -5,0 +5,0 @@ "main": "lib-commonjs/index.js",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

481538

increased by5.15%

Number of package files

210

increased by3.96%

Lines of code

4614

increased by5.2%

No dependency changes