@instructure/ui-tree-browser 11.6.0 → 11.6.1-snapshot-129

package/src/TreeBrowser/v2/TreeNode/index.tsx

@@ -0,0 +1,158 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2021 - present Instructure, Inc.
+ *
+ * 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 { Component, ContextType } from 'react'
+
+import { Img } from '@instructure/ui-img/latest'
+import { withStyle } from '@instructure/emotion'
+import { renderIconWithProps } from '@instructure/ui-icons'
+
+import generateStyles from '../TreeButton/styles'
+import type { TreeBrowserNodeProps } from './props'
+import { allowedProps } from './props'
+import TreeBrowserContext from '../TreeBrowserContext'
+
+// Map TreeBrowser size tokens to icon size tokens
+const treeBrowserSizeToIconSize = {
+  small: 'md',
+  medium: 'lg',
+  large: 'xl'
+} as const
+
+// Todo: merge TreeButton and TreeNode: TreeButton should be a special type of TreeNode
+
+/**
+---
+parent: TreeBrowser
+id: TreeBrowser.Node
+---
+A helper class used to render the :renderBeforeItems and :renderAfterItems
+in the TreeBrowser.
+**/
+@withStyle(generateStyles, 'TreeBrowserTreeButton')
+class TreeNode extends Component<TreeBrowserNodeProps, { isHovered: boolean }> {
+  static readonly componentId = 'TreeBrowser.Node'
+
+  static allowedProps = allowedProps
+
+  static contextType = TreeBrowserContext
+  declare context: ContextType<typeof TreeBrowserContext>
+
+  static defaultProps = {
+    size: 'medium',
+    variant: 'folderTree',
+    selected: false,
+    focused: false,
+    hoverable: true
+  }
+
+  ref: Element | null = null
+
+  state = {
+    isHovered: false
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.({
+      animation: this.context?.animation,
+      hoverable: this.props.hoverable
+    })
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.({
+      animation: this.context?.animation,
+      hoverable: this.props.hoverable
+    })
+  }
+
+  handleRef = (el: HTMLDivElement) => {
+    if (el && typeof this.props.containerRef === 'function') {
+      this.props.containerRef(el.parentElement)
+    }
+    this.ref = el
+  }
+
+  handleMouseEnter = () => {
+    if (this.props.hoverable) {
+      this.setState({ isHovered: true })
+    }
+  }
+
+  handleMouseLeave = () => {
+    if (this.props.hoverable) {
+      this.setState({ isHovered: false })
+    }
+  }
+  getIconColor(): 'baseColor' | 'onColor' | 'inverseColor' {
+    const { selected } = this.props
+    const { isHovered } = this.state
+
+    // Priority: selected > hover > default
+    if (selected) return 'onColor'
+    if (isHovered) return 'inverseColor'
+    return 'baseColor'
+  }
+  renderItemImage() {
+    const { thumbnail, itemIcon, styles, size } = this.props
+
+    if (thumbnail) {
+      return (
+        <div css={styles?.thumbnail}>
+          <Img src={thumbnail} constrain="cover" alt="" />
+        </div>
+      )
+    }
+    if (itemIcon) {
+      const iconSize = treeBrowserSizeToIconSize[size!]
+      const iconColor = this.getIconColor()
+      const iconElement = renderIconWithProps(itemIcon, iconSize, iconColor)
+
+      return <div css={styles?.icon}>{iconElement}</div>
+    }
+    return undefined
+  }
+
+  render() {
+    const { children, styles } = this.props
+    return (
+      <div
+        ref={this.handleRef}
+        tabIndex={-1}
+        css={styles?.treeButton}
+        data-cid="TreeNode"
+        onMouseEnter={this.handleMouseEnter}
+        onMouseLeave={this.handleMouseLeave}
+      >
+        <span css={styles?.layout}>
+          {this.renderItemImage()}
+          <span css={styles?.node}>{children}</span>
+        </span>
+      </div>
+    )
+  }
+}
+
+export default TreeNode
+export { TreeNode }

package/src/TreeBrowser/v2/TreeNode/props.ts

@@ -0,0 +1,84 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * 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 React from 'react'
+import type { TreeBrowserButtonTheme } from '@instructure/shared-types'
+import type { WithStyleProps } from '@instructure/emotion'
+
+import type {
+  TreeBrowserButtonProps,
+  TreeBrowserButtonStyle
+} from '../TreeButton/props'
+import { CollectionData } from '../props'
+
+type TreeBrowserNodeOwnProps = Pick<
+  TreeBrowserButtonProps,
+  | 'id'
+  | 'size'
+  | 'variant'
+  | 'selected'
+  | 'focused'
+  | 'itemIcon'
+  | 'thumbnail'
+  | 'level'
+  | 'containerRef'
+  | 'onClick'
+> & {
+  onKeyDown?: (e: React.KeyboardEvent, data: CollectionData) => void
+  /**
+   * The children to be rendered within the `<TreeNode />`
+   */
+  children?: React.ReactNode
+  /**
+   * Whether the node should show hover effects.
+   * Set to false to disable hover styling when the node contains custom interactive content.
+   * @default true
+   */
+  hoverable?: boolean
+}
+
+type PropKeys = keyof TreeBrowserNodeOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type TreeBrowserNodeProps = TreeBrowserNodeOwnProps &
+  WithStyleProps<TreeBrowserButtonTheme, TreeBrowserButtonStyle>
+const allowedProps: AllowedPropKeys = [
+  'id',
+  'size',
+  'variant',
+  'selected',
+  'focused',
+  'itemIcon',
+  'thumbnail',
+  'level',
+  'children',
+  'containerRef',
+  'onKeyDown',
+  'onClick',
+  'hoverable'
+]
+
+export type { TreeBrowserNodeProps }
+export { allowedProps }

package/src/TreeBrowser/v2/index.tsx

@@ -0,0 +1,438 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * 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 { Component, SyntheticEvent } from 'react'
+import keycode from 'keycode'
+
+import {
+  FolderClosedInstUIIcon,
+  FileTextInstUIIcon
+} from '@instructure/ui-icons'
+
+import { omitProps, pickProps } from '@instructure/ui-react-utils'
+import { withStyle } from '@instructure/emotion'
+
+import { TreeCollection } from './TreeCollection'
+import { TreeButton } from './TreeButton'
+import { TreeNode } from './TreeNode'
+
+import generateStyles from './styles'
+import type {
+  Collection,
+  CollectionData,
+  CollectionProps,
+  TreeBrowserProps,
+  TreeBrowserState
+} from './props'
+import { allowedProps } from './props'
+import TreeBrowserContext from './TreeBrowserContext'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyles)
+class TreeBrowser extends Component<TreeBrowserProps, TreeBrowserState> {
+  static readonly componentId = 'TreeBrowser'
+
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    size: 'medium',
+    variant: 'folderTree',
+    showRootCollection: true,
+    collectionIcon: FolderClosedInstUIIcon,
+    collectionIconExpanded: FolderClosedInstUIIcon,
+    itemIcon: FileTextInstUIIcon,
+    getItemProps: (props: unknown) => props,
+    getCollectionProps: (props: unknown) => props,
+    defaultExpanded: [],
+    selectionType: 'none',
+    sortOrder: function () {
+      return 0
+    },
+    animation: true
+  }
+
+  static Node = TreeNode
+  static Collection = TreeCollection
+  static Button = TreeButton
+
+  ref: Element | null = null
+
+  constructor(props: TreeBrowserProps) {
+    super(props)
+    const initialState: TreeBrowserState = {
+      selection: ''
+    }
+
+    // Handle expanded state (controlled vs uncontrolled)
+    if (typeof this.props.expanded === 'undefined') {
+      initialState.expanded = this.props.defaultExpanded
+    }
+
+    // Handle selection state (controlled vs uncontrolled)
+    if (typeof this.props.selection === 'undefined') {
+      initialState.selection = this.props.defaultSelection || ''
+    }
+
+    this.state = initialState
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  get _root() {
+    console.warn(
+      '_root property is deprecated and will be removed in v9, please use ref instead'
+    )
+    return this.ref
+  }
+
+  handleCollectionClick = (
+    e: SyntheticEvent,
+    collection: CollectionData,
+    expand = true
+  ) => {
+    e.stopPropagation()
+    const { onCollectionClick } = this.props
+
+    if (expand) this.expandOrCollapseNode(collection)
+    onCollectionClick?.(collection.id as any, collection) // TODO: this should pass the event as the first arg
+    this.handleSelection(collection.id, 'collection')
+  }
+
+  handleItemClick = (e: SyntheticEvent, item: CollectionData) => {
+    e.stopPropagation()
+    this.props.onItemClick?.(item)
+    this.handleSelection(item.id, 'item')
+  }
+
+  handleKeyDown = (event: React.KeyboardEvent, node?: CollectionData) => {
+    switch (event.keyCode) {
+      case keycode.codes.down:
+      case keycode.codes.j:
+        event.stopPropagation()
+        this.moveFocus(1)
+        break
+      case keycode.codes.up:
+      case keycode.codes.k:
+        event.stopPropagation()
+        this.moveFocus(-1)
+        break
+      case keycode.codes.home:
+      case keycode.codes.end:
+        event.stopPropagation()
+        this.homeOrEnd(event.keyCode)
+        break
+      case keycode.codes.left:
+      case keycode.codes.right:
+        event.stopPropagation()
+        this.handleLeftOrRightArrow(event.keyCode, node)
+        break
+      case keycode.codes.enter:
+      case keycode.codes.space:
+        event.stopPropagation()
+        this.handleActivation(event, node)
+        break
+      default:
+        return
+    }
+    event.preventDefault()
+  }
+
+  get collections() {
+    const { collections, rootId } = this.props
+    if (typeof rootId !== 'undefined') {
+      return [collections[rootId]]
+    } else {
+      return Object.keys(collections)
+        .map((id) => collections[id])
+        .filter((collection) => collection != null)
+    }
+  }
+
+  get expanded() {
+    return this.getExpanded(this.state, this.props)
+  }
+
+  getExpanded(state: TreeBrowserState, props: TreeBrowserProps) {
+    return typeof props.expanded === 'undefined'
+      ? state.expanded!
+      : props.expanded
+  }
+
+  get selection() {
+    return this.getSelection(this.state, this.props)
+  }
+
+  getSelection(state: TreeBrowserState, props: TreeBrowserProps) {
+    return typeof props.selection === 'undefined'
+      ? state.selection
+      : props.selection
+  }
+
+  expandOrCollapseNode(collection: CollectionData) {
+    this.props.onCollectionToggle?.(collection)
+    if (typeof this.props.expanded === 'undefined') {
+      this.setState((state, props) => {
+        const expanded = [...this.getExpanded(state, props)]
+        const expandedIndex = this.getExpandedIndex(expanded, collection.id)
+        if (collection.expanded && expandedIndex < 0) {
+          expanded.push(collection.id)
+        } else if (expandedIndex >= 0) {
+          expanded.splice(expandedIndex, 1)
+        }
+        return { expanded }
+      })
+    }
+  }
+
+  handleSelection(id: string | number | undefined, type: string) {
+    const { selectionType, onSelectionChange } = this.props
+
+    if (selectionType !== 'single') return
+
+    const selection = `${type}_${id}`
+
+    // Call the callback if provided (for controlled selection)
+    if (onSelectionChange) {
+      onSelectionChange(selection, type as 'item' | 'collection', id)
+    }
+
+    // Update internal state only if uncontrolled
+    if (typeof this.props.selection === 'undefined') {
+      this.setState((state) => {
+        if (state.selection !== selection) {
+          return { selection }
+        } else {
+          return state
+        }
+      })
+    }
+  }
+
+  clearSelection = () => {
+    const { onSelectionChange } = this.props
+
+    // Call the callback if provided (for controlled selection)
+    if (onSelectionChange) {
+      onSelectionChange('', 'item', undefined)
+    }
+
+    // Update internal state only if uncontrolled
+    if (typeof this.props.selection === 'undefined') {
+      this.setState({ selection: '' })
+    }
+  }
+
+  getNavigableNodes() {
+    return Array.from(this.ref!.querySelectorAll('[role="treeitem"]'))
+  }
+
+  moveFocus(delta: number) {
+    const nodes = this.getNavigableNodes()
+    const closest = window.document.activeElement!.closest('[role="treeitem"]')!
+    const active = nodes.indexOf(closest)
+    let next = active + delta
+    if (next < 0) {
+      next = 0
+    } else if (next >= nodes.length) {
+      next = nodes.length - 1
+    }
+    nodes.forEach((n) => {
+      n.setAttribute('tabindex', '-1')
+    })
+    nodes[next].setAttribute('tabindex', '0')
+    ;(nodes[next] as any).focus()
+  }
+
+  homeOrEnd(keyCode: number) {
+    const length = this.getNavigableNodes().length
+    if (keyCode === keycode.codes.home) {
+      this.moveFocus(1 - length)
+    } else {
+      this.moveFocus(length - 1)
+    }
+  }
+
+  handleLeftOrRightArrow(keyCode: number, node?: CollectionData) {
+    const ltr = !(
+      this.ref!.parentElement!.dir === 'rtl' || document.dir === 'rtl'
+    )
+    if (
+      (ltr && keyCode === keycode.codes.left) ||
+      (!ltr && keyCode == keycode.codes.right)
+    ) {
+      this.handleCloseOrPrevious(node)
+    } else {
+      this.handleOpenOrNext(node)
+    }
+  }
+
+  handleOpenOrNext(node?: CollectionData) {
+    if (
+      node &&
+      !this.expanded.includes(node.id) &&
+      node.type === 'collection'
+    ) {
+      this.expandOrCollapseNode(node)
+    } else {
+      this.moveFocus(1)
+    }
+  }
+
+  handleCloseOrPrevious(node?: CollectionData) {
+    if (node && this.expanded.includes(node.id) && node.type === 'collection') {
+      this.expandOrCollapseNode(node)
+    } else {
+      this.moveFocus(-1)
+    }
+  }
+
+  handleActivation(event: React.KeyboardEvent, node?: CollectionData) {
+    if (node == null) return
+    if (node.type === 'collection') {
+      this.handleCollectionClick(
+        event,
+        node,
+        this.props.selectionType === 'none'
+      )
+    } else {
+      this.handleItemClick(event, node)
+    }
+  }
+
+  getSubCollections(collection: Collection) {
+    const collections = collection.collections
+      ? [...collection.collections]
+      : []
+    return collections
+      .map((id) => this.getCollectionProps(this.props.collections[id]))
+      .filter((collection) => collection != null)
+      .sort(this.props.sortOrder)
+  }
+
+  getItems(collection: Collection) {
+    if (collection.items) {
+      const items = collection.items ? [...collection.items] : []
+      return items
+        .map((id) => {
+          return { ...this.props.items[id] }
+        })
+        .filter((item) => item != null)
+        .sort(this.props.sortOrder)
+    } else {
+      return []
+    }
+  }
+
+  getIsFlattened = (collection: Collection) => {
+    const { rootId, showRootCollection } = this.props
+    return (
+      !showRootCollection &&
+      typeof rootId !== 'undefined' &&
+      collection.id === rootId
+    )
+  }
+
+  getCollectionProps(collection: Collection): CollectionProps {
+    return {
+      id: collection.id,
+      name: collection.name,
+      collections: this.getSubCollections(collection),
+      items: this.getItems(collection),
+      descriptor: collection.descriptor,
+      containerRef: collection.containerRef,
+      renderBeforeItems: collection.renderBeforeItems,
+      renderAfterItems: collection.renderAfterItems,
+      expanded: this.getExpandedIndex(this.expanded, collection.id) >= 0,
+      isCollectionFlattened: this.getIsFlattened(collection),
+      compareFunc: collection.compareFunc
+    }
+  }
+
+  getExpandedIndex(
+    expanded: (string | number | undefined)[],
+    id?: string | number
+  ) {
+    return expanded.findIndex((expanded) => String(expanded) === String(id))
+  }
+
+  renderRoot() {
+    return this.collections
+      .sort(this.props.sortOrder)
+      .map((collection, i) => (
+        <TreeCollection
+          key={i}
+          {...pickProps(omitProps(this.props), TreeCollection.allowedProps)}
+          {...this.getCollectionProps(collection)}
+          selection={this.selection}
+          onItemClick={this.handleItemClick}
+          onCollectionClick={this.handleCollectionClick}
+          onKeyDown={this.handleKeyDown}
+          numChildren={this.collections.length}
+          level={1}
+          position={1}
+          renderContent={this.props.renderContent}
+        />
+      ))
+  }
+
+  render() {
+    const { styles } = this.props
+
+    return (
+      <TreeBrowserContext.Provider
+        value={{
+          animation: this.props.animation,
+          clearSelection: this.clearSelection
+        }}
+      >
+        <ul
+          css={styles?.treeBrowser}
+          tabIndex={0}
+          role="tree"
+          onKeyDown={this.handleKeyDown}
+          ref={(el) => {
+            this.ref = el
+          }}
+          aria-label={this.props.treeLabel}
+          data-cid="TreeBrowser"
+        >
+          {this.renderRoot()}
+        </ul>
+      </TreeBrowserContext.Provider>
+    )
+  }
+}
+
+export default TreeBrowser
+export { TreeBrowser }