feat: tree component #566

maxinteger · 2024-08-05T15:46:59Z

Description

Add new Tree and TreeBaseNode components

Links

https://jira-eng-gpk2.cisco.com/jira/browse/SPARK-548345

nataliadelmar · 2024-08-14T16:01:02Z

src/components/TreeNodeBase/TreeNodeBase.types.ts

+  shouldItemFocusBeInset?: boolean;
+
+  /**
+   * Determines if the tree node is interactive (usually used as a header when false)


What do you mean with '(usually used as a header when false)' ? If the node is not interactive, it is probably a leaf node right?

good point. This was a leftover from the ListItemBase, but we do not really need this

I removed the interactive and isDisabled props for now because if we can disable nodes then it will effect on the navigation.

Let's postpone this functionality until we really need it

nataliadelmar · 2024-08-14T16:12:41Z

src/components/TreeNodeBase/TreeNodeBase.tsx

+    ...rest
+  } = props;
+  if (!nodeId) {
+    throw new Error('TreeNodeBase: nodeId prop is required.');


I think we do not throw error in Tree components. We normally console.warn(message), like we do here

nataliadelmar · 2024-08-14T16:15:45Z

src/components/TreeNodeBase/TreeNodeBase.tsx

+  // ref directly because we want it to be a useRef style ref
+  // We useLayoutEffect so that it happens in time for tippy
+  // to use the ref when adding event handlers
+  useLayoutEffect(() => {


Is this for the case of having a tree component inside a popover? Do we have a use case for that? I can only think of calendar item popover, but curious if there is any other

Since this solution works in list and you already mentioned a possible use case, I keep this code

nataliadelmar · 2024-08-14T16:17:54Z

src/components/TreeNodeBase/TreeNodeBase.tsx

+        content = children;
+      } else {
+        console.warn(
+          'TreeNodeBase: this component can only receive ListItemBaseSection as children.'


can only receive ListItemBaseSection or Text as children

nataliadelmar · 2024-08-14T16:22:31Z

src/components/TreeNodeBase/TreeNodeBase.tsx

+      } else {
+        console.warn(
+          'TreeNodeBase: this component can only receive ListItemBaseSection as children.'
+        );


So, if children is an array, the only permitted cases are:
[<ListItemBaseSection />, <ListItemBaseSection/ >, <ListItemBaseSection>]
[<ListItemBaseSection />, <ListItemBaseSection/ >]
[<Text />, <Text/ >, <Text>]
[<Text />, <Text/ >]

Why do we want to make this that restrictive? why not simply rendering the children inside the node?

I re-phrased the warning.

Valid children are:

Single, eg.: <div/>, </> (React.Frament)

Multiple eg: `[, <Text/ >]

The message is misleading, [<ListItemBaseSection />, <ListItemBaseSection/ >] is not allowed, instead you have to use: [<ListItemBaseSection />] and put the multiple child into ListItemBaseSection

nataliadelmar · 2024-08-14T16:29:54Z

src/components/TreeNodeBase/TreeNodeBase.tsx

+   */
+  const shouldFocusOnPress = treeContext?.shouldFocusOnPress || false;
+  const shouldItemFocusBeInset =
+    treeContext?.shouldItemFocusBeInset || DEFAULTS.SHOULD_ITEM_FOCUS_BE_INSET;


On TreeNodeBase.tsx I see there is a prop called shouldItemFocusBeInset. Why are we not using this for this line too?

Good point, we do not need the shouldItemFocusBeInset on the TreeNodeBase, removed
(also renamed it in the Tree component's porps)

nataliadelmar · 2024-08-14T16:31:08Z

src/components/TreeNodeBase/TreeNodeBase.tsx

+  const shouldItemFocusBeInset =
+    treeContext?.shouldItemFocusBeInset || DEFAULTS.SHOULD_ITEM_FOCUS_BE_INSET;
+
+  const treeNodeTabIndex = getTreeNodeBaseTabIndex(nodeId, treeContext.activeNodeId, interactive);


shouldnt this const be called treeNodeBaseTabIndex?

Since it is a private variable of the component, the prefix is not needed. I reduced the name to tabIndex only

gabrielchl · 2024-08-14T15:27:35Z

src/utils/navigation.ts

+const FOCUSABLE_ELEMENT_SELECTORS =
+  'a[href], button, input, textarea, select, details, [tabindex]:not([tabindex=""]';
+const FOCUSABLE_AND_TABBABLE_ONLY_ELEMENT_SELECTORS =
+  'a[href], button, input, textarea, select, details, [tabindex]:not([tabindex="-1"]';


Suggested change

const FOCUSABLE_ELEMENT_SELECTORS =

'a[href], button, input, textarea, select, details, [tabindex]:not([tabindex=""]';

const FOCUSABLE_AND_TABBABLE_ONLY_ELEMENT_SELECTORS =

'a[href], button, input, textarea, select, details, [tabindex]:not([tabindex="-1"]';

const FOCUSABLE_ELEMENT_SELECTORS =

'a[href], button, input, textarea, select, details, [tabindex]:not([tabindex=""])';

const FOCUSABLE_AND_TABBABLE_ONLY_ELEMENT_SELECTORS =

'a[href], button, input, textarea, select, details, [tabindex]:not([tabindex="-1"])';

Nice catch!

nataliadelmar · 2024-08-15T09:10:52Z

src/components/Tree/test.utils.ts

+ */
+export const createTreeNode = (
+  id: TreeNodeId,
+  isOpenByDefault: boolean = undefined,


isn't this the same as to say isOpenByDefault?: boolean

do we need the default to undefined?

it is the same as isOpenByDefault?: boolean but it is more explicit this way, and following the patter in the next line children: Array<TreeNode> = []

nataliadelmar · 2024-08-15T09:13:02Z

src/components/Tree/Tree.utils.ts

+  return value;
+};
+
+const TREE_NAVIGATION_ITERATION_LIMIT = 1_024;


this should be in constants file

nataliadelmar · 2024-08-15T09:14:50Z

src/components/Tree/Tree.utils.ts

+ * @param tree
+ * @param nodeId
+ */
+export const toggleActiveNode = (tree: FlatTree, nodeId: TreeNodeId): TreeNodeId => {


the name of this util is confusing, it doesn't get the active node, it uses the passed nodeid and toggles it. So maybe a name like toggleNode would be better

Actually we do not event need this function

nataliadelmar · 2024-08-15T09:15:38Z

src/components/Tree/Tree.utils.ts

+ */
+export const toggleActiveNode = (tree: FlatTree, nodeId: TreeNodeId): TreeNodeId => {
+  const node = tree.get(nodeId);
+  if (node) {


should we log any warning if the node doesn't exist?

I added a check to getNextActiveNode, not sure about the rest of the case. Some time is valid to have an undefined result for example when we reach the root which has not parent

nataliadelmar · 2024-08-15T13:10:12Z

src/components/TreeNodeBase/TreeNodeBase.stories.docs.mdx

+If the `<TreeNodeBase />` can not access ot the context, it will throw an error.
+
+`<TreeNodeBase />` allows to navigate into the node itself when there are interactive elements inside it.
+After the node selected the user can use the `Tab` key to select the first, second, etc. interactive element.


'After the node is focused (not selected), the user can ...'

nataliadelmar · 2024-08-15T13:10:43Z

src/components/TreeNodeBase/TreeNodeBase.stories.docs.mdx

+
+`<TreeNodeBase />` allows to navigate into the node itself when there are interactive elements inside it.
+After the node selected the user can use the `Tab` key to select the first, second, etc. interactive element.
+When the last interactable element is selected, the next tab will move the focus to the next interactable


'When the last interactable element is focused, the next tab will move the focus to the next interactable...'

nataliadelmar · 2024-08-15T13:11:30Z

src/components/Tree/Tree.tsx

+        'aria-setsize': isRoot ? 1 : parent.children.length,
+        'aria-level': node.level + 1,
+        'aria-posinset': node.index + 1,
+        'aria-selected': isSelected,


We shouldn't set aria-selected if activeNode === node.id (that is, if the node is simply focused).

src/components/ListItemBase/ListItemBase.types.ts

src/components/Tree/Tree.stories.args.ts

src/components/Tree/Tree.style.scss

src/components/Tree/Tree.tsx

src/components/Tree/Tree.utils.ts

torgeadelin · 2024-08-15T15:12:10Z

src/components/Tree/Tree.utils.ts

+
+  // Otherwise, find the next sibling
+  for (let counter = 0; ; counter++) {
+    if (counter > TREE_NAVIGATION_ITERATION_LIMIT) {


question: we do support 1K participants, and if we're gonna use this in the participants list, we might reach the limit.. but not sure how realistic that is.

Any particular reason you added it or?

it does not limit the size of the tree, it is to detect loops in the tree.

I will write some test cases.
Also I refactored it :)

src/components/Tree/Tree.utils.ts

torgeadelin · 2024-08-15T15:19:53Z

src/components/Tree/Tree.utils.ts

+ * @param excludeRoot
+ * @param toggleTreeNode
+ */
+export const getNextActiveNode = (


suggestion: maybe rename this func, there's another function above findNextTreeNode , and in the comment it says * Find the next active tree node based on the current active node. I can see that the imlpementation of this one is actually different, it actually handles the keyboard nav.

findNextTreeNode is just a utility function which is not exported and used only in the getNextActiveNode function. I can update the docs to make it more descriptive, but I am also open for name suggestions

gabrielchl · 2024-08-16T00:07:24Z

src/components/Tree/Tree.utils.ts

+};
+
+/**
+ * Travers the tree and convert it to a map between the node id and the node


Suggested change

* Travers the tree and convert it to a map between the node id and the node

* Traverse the tree and convert it to a map between the node id and the node

nataliadelmar · 2024-08-20T11:26:53Z

src/components/Tree/Tree.types.ts

+   *
+   * It is used to build an internal tree for navigation and follow open/close states.
+   */
+  treeStructure: TreeRoot;


TreeRoot is of type TreeNode, which does not have a flat structure. What is we want a flat structure?

flat tree is the internal representation of the tree inside the Tree component, it is more efficient to use the flattened tree for navigation then the normal nested tree.

Please note, it is independent from the isRenderedFlat because it is about how the consumer built the tree in the DOM

The consumer should not know about this internal representation.

nataliadelmar · 2024-08-20T11:35:38Z

src/components/Tree/Tree.types.ts

+  /**
+   * Toggle open/close state of the tree node.
+   */
+  setVirtualTreeNodeOpenState?: (id: TreeNodeId, isOpen: boolean) => void;


you have a type set for this called ToggleTreeNode

Unfortunately there are different. The isOpen parameter is option in the ToggleTreeNode and required in setVirtualTreeNodeOpenState

nataliadelmar · 2024-08-20T11:37:02Z

src/components/Tree/Tree.types.ts

+   * Toggle the isOpen state of the tree node.
+   * @param id unique identifier of the tree node
+   */
+  toggleTreeNode: (id: TreeNodeId) => void;


we have a type called ToggleTreeNode that is a function with id and isOpen as params. It is confusing that one toggleTreeNode only needs id and the other needs both id and isOpen stated, don't you think?

torgeadelin

some small issues still, but looking great otherwise

torgeadelin · 2024-08-20T16:27:59Z

src/components/Tree/Tree.types.ts

+   *    we need to provide additional aria attributes to re-build it for the accessibility tree.
+   *    Virtualized trees are usually rendered flat.
+   *
+   * @see {@link https://codepen.io/maxinteger/pen/zYVNabV Example of a nested and flat tree}


We're still using codepen, but I'm not going to block it for that.

torgeadelin · 2024-08-20T16:28:41Z

src/components/Tree/Tree.utils.ts

+  const loopCheck = new Set<TreeNodeId>();
+
+  // Otherwise, find the next sibling
+  for (;;) {


suggestion: while (true) {}

ESLint does not like it, no-constant-condition, I do it anyway, while(true) is more readable then for(;;)

torgeadelin · 2024-08-20T16:29:36Z

src/components/Tree/Tree.utils.ts

+  if (!current.isLeaf) {
+    if (!current.isOpen) {
+      // Open it if it's closed
+


nitpick: unnecessary new line

torgeadelin · 2024-08-20T16:32:21Z

src/components/Tree/Tree.utils.ts

+ * @param prevTree
+ * @param isOpen
+ */
+export const toggleTreeNodeRecord = (


question: what is the difference between this and toggleTreeNode from

momentum-react-v2/src/components/Tree/Tree.tsx

Line 38 in 44edce1

const toggleTreeNode = useCallback(

in toggleTreeNodeRecord the isOpen parameter required while in the toggleTreeNode is optional. Also, toggleTreeNodeRecord is used internally meantime toggleTreeNode is part of the Tree context API.

I flagged toggleTreeNodeRecord as @internal

torgeadelin · 2024-08-20T16:49:39Z

src/components/TreeNodeBase/TreeNodeBase.style.scss

+  box-sizing: border-box;
+  outline: none;
+
+  &[data-interactive='true'] {


issue: you're missing interactive prop on the tree node base (you need to follow similar approach as we do in list item base), OR just remove it? Not sure we need interactive for tree node... but you never know..

Nice catch, Tree node is interactive by default, at least for now. I removed the &[data-interactive='true'] {, but kept the rest.

torgeadelin · 2024-08-20T16:50:13Z

src/components/TreeNodeBase/TreeNodeBase.style.scss

+  box-sizing: border-box;
+  outline: none;
+
+  &[data-interactive='true'] {


issue: I don't see any disabled state

I've identified both of this issue from the storybook page of this component. I noticed you've used the template for pseudo states (praise!), and they're broken. The reason they are broken are because of the 2 issues abvove.

yes, there is no disabled state fro the tree node at the moment. We can add it when it is needed.

torgeadelin · 2024-08-20T16:53:15Z

src/components/TreeNodeBase/TreeNodeBase.tsx

+        data-shape={shape}
+        className={classnames(className, STYLE.wrapper, { active: isPressed || isSelected })}
+        lang={lang}
+        {...treeNodePressProps}


suggestion: we should allow the pass in the ..rest props to this as long as they're valid tags. Not sure what the best approach for this is.. We normally just pass in ...rest BUT I've noticed a lot in Cantina and mrv2 that a lot of times we pass in invalid DOM attributes to the HMTL elements, which result in warnings in unit test output and console.logs in browser.

This is helpful if we need to pass any aria attributes from the consumer side.

torgeadelin

some small issues still, but looking great otherwise

issue: https://jira-eng-gpk2.cisco.com/jira/browse/SPARK-548345

github-actions · 2024-08-22T11:32:08Z

🎉 This PR is included in version 26.143.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

maxinteger force-pushed the feat/SPARK-548345-tree-component branch from 42a48d3 to 77c23dd Compare August 7, 2024 15:47

maxinteger marked this pull request as ready for review August 14, 2024 08:12

maxinteger added the validated If the pull request is validated automation. label Aug 14, 2024

nataliadelmar reviewed Aug 14, 2024

View reviewed changes

gabrielchl reviewed Aug 14, 2024

View reviewed changes

nataliadelmar reviewed Aug 15, 2024

View reviewed changes

torgeadelin reviewed Aug 15, 2024

View reviewed changes

gabrielchl reviewed Aug 16, 2024

View reviewed changes

nataliadelmar approved these changes Aug 20, 2024

View reviewed changes

torgeadelin reviewed Aug 20, 2024

View reviewed changes

torgeadelin requested changes Aug 20, 2024

View reviewed changes

torgeadelin approved these changes Aug 22, 2024

View reviewed changes

feat: tree component

0023a27

issue: https://jira-eng-gpk2.cisco.com/jira/browse/SPARK-548345

maxinteger force-pushed the feat/SPARK-548345-tree-component branch from f25a2bd to 0023a27 Compare August 22, 2024 11:13

maxinteger merged commit b51b782 into momentum-design:master Aug 22, 2024
5 checks passed

github-actions bot added the released label Aug 22, 2024

	* Travers the tree and convert it to a map between the node id and the node
	* Traverse the tree and convert it to a map between the node id and the node

feat: tree component #566

feat: tree component #566

Conversation

maxinteger commented Aug 5, 2024

Description

Links

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maxinteger Aug 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

torgeadelin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maxinteger Aug 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

torgeadelin left a comment

Choose a reason for hiding this comment

github-actions bot commented Aug 22, 2024

maxinteger Aug 16, 2024 •

edited

Loading

maxinteger Aug 22, 2024 •

edited

Loading