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

package/src/TreeBrowser/v2/TreeBrowserContext.ts

@@ -0,0 +1,53 @@
+/*
+ * 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 { createContext } from 'react'
+
+type TreeBrowserContextType = {
+  /**
+   * Whether to enable animation for the TreeBrowser
+   */
+  animation?: boolean
+  /**
+   * Function to clear the current selection
+   */
+  clearSelection?: () => void
+}
+
+/**
+ * ---
+ * category: components/contexts
+ * ---
+ * React context created by the `TreeBrowser` component to hold its data which are
+ * read by its children.
+ *
+ * @module
+ */
+const TreeBrowserContext = createContext<TreeBrowserContextType>({
+  animation: true
+})
+
+export default TreeBrowserContext
+export { TreeBrowserContext }
+export type { TreeBrowserContextType }

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

@@ -0,0 +1,210 @@
+/*
+ * 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, ContextType } from 'react'
+
+import { Img } from '@instructure/ui-img/latest'
+import { withStyle } from '@instructure/emotion'
+import { renderIconWithProps } from '@instructure/ui-icons'
+
+import generateStyles from './styles'
+import type { TreeBrowserButtonProps } from './props'
+import { allowedProps } from './props'
+import TreeBrowserContext from '../TreeBrowserContext'
+
+// Todo: merge TreeButton and TreeNode: TreeButton should be a special type of TreeNode
+
+// Map TreeBrowser size tokens to icon size tokens
+const treeBrowserSizeToIconSize = {
+  small: 'md',
+  medium: 'lg',
+  large: 'xl'
+} as const
+
+/**
+---
+parent: TreeBrowser
+id: TreeBrowser.Button
+---
+**/
+@withStyle(generateStyles, 'TreeBrowserTreeButton')
+class TreeButton extends Component<
+  TreeBrowserButtonProps,
+  { isHovered: boolean }
+> {
+  static readonly componentId = 'TreeBrowser.Button'
+
+  static allowedProps = allowedProps
+
+  static contextType = TreeBrowserContext
+  declare context: ContextType<typeof TreeBrowserContext>
+
+  static defaultProps = {
+    type: 'treeButton',
+    size: 'medium',
+    variant: 'folderTree',
+    selected: false,
+    focused: false,
+    expanded: 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
+    })
+  }
+
+  defaultContentRenderer(props: TreeBrowserButtonProps) {
+    const { name, descriptor, styles } = props
+    return (
+      <span css={styles!.layout}>
+        {this.renderImage()}
+        <span css={styles!.text}>
+          <span css={styles!.textName}>{name}</span>
+          {descriptor ? (
+            <span css={styles!.textDescriptor} title={descriptor}>
+              {descriptor}
+            </span>
+          ) : null}
+        </span>
+      </span>
+    )
+  }
+
+  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'
+  }
+
+  renderImage() {
+    const { type } = this.props
+    switch (type) {
+      case 'collection':
+        return this.renderCollectionIcon()
+      case 'item':
+        return this.renderItemImage()
+      default:
+        break
+    }
+    return undefined
+  }
+
+  renderCollectionIcon() {
+    const { expanded, collectionIcon, collectionIconExpanded, styles, size } =
+      this.props
+
+    if (collectionIcon || collectionIconExpanded) {
+      const icon = (expanded ? collectionIconExpanded : collectionIcon) as any
+      const iconSize = treeBrowserSizeToIconSize[size!]
+      const iconColor = this.getIconColor()
+      const iconElement = renderIconWithProps(icon, iconSize, iconColor)
+
+      return <div css={styles?.icon}>{iconElement}</div>
+    }
+    return undefined
+  }
+
+  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
+  }
+
+  handleRef = (el: HTMLButtonElement) => {
+    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 })
+    }
+  }
+
+  render() {
+    const { styles, renderContent } = this.props
+    const buttonContent = renderContent
+      ? renderContent(this.props)
+      : this.defaultContentRenderer(this.props)
+    // VoiceOver can't navigate without the buttons, even though they don't do anything
+    return (
+      <button
+        ref={this.handleRef}
+        tabIndex={-1}
+        type="button"
+        css={styles?.treeButton}
+        data-cid="TreeButton"
+        onMouseEnter={this.handleMouseEnter}
+        onMouseLeave={this.handleMouseLeave}
+      >
+        {buttonContent}
+      </button>
+    )
+  }
+}
+
+export default TreeButton
+export { TreeButton }

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

@@ -0,0 +1,95 @@
+/*
+ * 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 { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type { TreeBrowserButtonTheme } from '@instructure/shared-types'
+import type { TreeBrowserCommonProps } from '../props'
+
+type TreeBrowserButtonOwnProps = {
+  id?: string | number
+  name?: string
+  descriptor?: string
+  type?: 'collection' | 'item' | string // | string is for custom type
+  thumbnail?: string
+  /**
+   * Called when this button is clicked
+   */
+  onClick?: (e: React.MouseEvent) => void
+  expanded?: boolean
+  selected?: boolean
+  focused?: boolean
+  level?: number
+  /**
+   * A function that returns a reference to the parent li element
+   */
+  containerRef?: (el: HTMLElement | null) => void
+  /**
+   * Whether the button should show hover effects.
+   * Set to false to disable hover styling when the button contains custom interactive content.
+   * @default true
+   */
+  hoverable?: boolean
+} & TreeBrowserCommonProps
+
+type PropKeys = keyof TreeBrowserButtonOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type TreeBrowserButtonProps = TreeBrowserButtonOwnProps &
+  WithStyleProps<TreeBrowserButtonTheme, TreeBrowserButtonStyle>
+
+type TreeBrowserButtonStyle = ComponentStyle<
+  | 'treeButton'
+  | 'layout'
+  | 'text'
+  | 'textName'
+  | 'textDescriptor'
+  | 'icon'
+  | 'thumbnail'
+  | 'node'
+>
+const allowedProps: AllowedPropKeys = [
+  'id',
+  'name',
+  'descriptor',
+  'type',
+  'size',
+  'variant',
+  'collectionIcon',
+  'collectionIconExpanded',
+  'itemIcon',
+  'thumbnail',
+  'onClick',
+  'expanded',
+  'selected',
+  'focused',
+  'level',
+  'containerRef',
+  'renderContent',
+  'hoverable'
+]
+
+export type { TreeBrowserButtonProps, TreeBrowserButtonStyle }
+export { allowedProps }

package/src/TreeBrowser/v2/TreeButton/styles.ts

@@ -0,0 +1,331 @@
+/*
+ * 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 { keyframes, calcFocusOutlineStyles } from '@instructure/emotion'
+
+import type { NewComponentTypes, SharedTokens } from '@instructure/ui-themes'
+import type { TreeBrowserButtonProps, TreeBrowserButtonStyle } from './props'
+
+const transform = keyframes`
+  50% {
+    opacity: 0.5;
+    transform: translate3d(2%, 0, 0);
+  }
+
+  100% {
+    opacity: 1;
+    transform: translate3d(0, 0, 0);
+  }`
+/**
+ *
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @param  {Object} state the state of the component, the style is applied to
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyles = (
+  componentTheme: NewComponentTypes['TreeBrowserTreeButton'],
+  props: TreeBrowserButtonProps,
+  sharedTokens: SharedTokens,
+  state: { animation?: boolean; hoverable?: boolean }
+): TreeBrowserButtonStyle => {
+  const { size, variant, selected, level } = props
+
+  const isRootButton = level && level === 1
+
+  const sizeMap = {
+    small: {
+      folderTree: {
+        before: {
+          width: componentTheme.baseSpacingSmall
+        },
+        icon: {
+          marginInlineEnd: componentTheme.iconsMarginRightSmall,
+          marginInlineStart: '0'
+        },
+        thumbnail: {
+          height: `calc(${componentTheme.baseSpacingSmall} * 2)`,
+          width: `calc(${componentTheme.baseSpacingSmall}* 2)`,
+          marginInlineEnd: componentTheme.iconsMarginRightSmall,
+          marginInlineStart: '0'
+        }
+      },
+      indent: {
+        icon: {
+          marginInlineEnd: componentTheme.iconsMarginRightSmall,
+          marginInlineStart: '0'
+        },
+        thumbnail: {
+          height: `calc(${componentTheme.baseSpacingSmall} * 2)`,
+          width: `calc(${componentTheme.baseSpacingSmall} * 2)`,
+          marginInlineEnd: componentTheme.iconsMarginRightSmall,
+          marginInlineStart: '0'
+        }
+      },
+      textName: {
+        fontSize: componentTheme.nameFontSizeSmall
+      },
+      textDescriptor: {
+        fontSize: componentTheme.descriptorFontSizeSmall
+      }
+    },
+    medium: {
+      folderTree: {
+        before: {
+          width: componentTheme.baseSpacingMedium
+        },
+        icon: {
+          marginInlineEnd: componentTheme.iconsMarginRightMedium,
+          marginInlineStart: '0'
+        },
+        thumbnail: {
+          height: `calc(${componentTheme.baseSpacingMedium} * 2)`,
+          width: `calc(${componentTheme.baseSpacingMedium} * 2)`,
+          marginInlineEnd: componentTheme.iconsMarginRightMedium,
+          marginInlineStart: '0'
+        }
+      },
+      indent: {
+        icon: {
+          marginInlineEnd: componentTheme.iconsMarginRightMedium,
+          marginInlineStart: '0'
+        },
+        thumbnail: {
+          height: `calc(${componentTheme.baseSpacingMedium} * 2)`,
+          width: `calc(${componentTheme.baseSpacingMedium} * 2)`,
+          marginInlineEnd: componentTheme.iconsMarginRightMedium,
+          marginInlineStart: '0'
+        }
+      },
+      textName: {
+        fontSize: componentTheme.nameFontSizeMedium
+      },
+      textDescriptor: {
+        fontSize: componentTheme.descriptorFontSizeMedium
+      }
+    },
+    large: {
+      folderTree: {
+        before: {
+          width: componentTheme.baseSpacingLarge
+        },
+        icon: {
+          marginInlineEnd: componentTheme.iconsMarginRightLarge,
+          marginInlineStart: '0'
+        },
+        thumbnail: {
+          height: `calc(${componentTheme.baseSpacingLarge} * 2)`,
+          width: `calc(${componentTheme.baseSpacingLarge} * 2)`,
+          marginInlineEnd: componentTheme.iconsMarginRightLarge,
+          marginInlineStart: '0'
+        }
+      },
+      indent: {
+        icon: {
+          marginInlineEnd: componentTheme.iconsMarginRightLarge,
+          marginInlineStart: '0'
+        },
+        thumbnail: {
+          height: `calc(${componentTheme.baseSpacingLarge} * 2)`,
+          width: `calc(${componentTheme.baseSpacingLarge}* 2)`,
+          marginInlineEnd: componentTheme.iconsMarginRightLarge,
+          marginInlineStart: '0'
+        }
+      },
+      textName: {
+        fontSize: componentTheme.nameFontSizeLarge
+      },
+      textDescriptor: {
+        fontSize: componentTheme.descriptorFontSizeLarge
+      }
+    }
+  }
+
+  const textStyle = {
+    minWidth: '0.0625rem',
+    lineHeight: componentTheme.textLineHeight,
+    flex: 1
+  }
+
+  const textNameStyle = {
+    display: 'block',
+    overflow: 'hidden',
+    whiteSpace: 'nowrap',
+    textOverflow: 'ellipsis',
+    ...sizeMap[size!].textName
+  }
+
+  const layoutPadding = {
+    small: {
+      folderTree: {
+        padding: `calc(${componentTheme.baseSpacingSmall} / 3) ${componentTheme.baseSpacingSmall}`
+      },
+      indent: {
+        padding: `calc(${componentTheme.baseSpacingSmall} / 3) calc(${componentTheme.baseSpacingSmall} / 2)`
+      }
+    },
+    medium: {
+      folderTree: {
+        padding: `calc(${componentTheme.baseSpacingMedium} / 3) ${componentTheme.baseSpacingMedium}`
+      },
+      indent: {
+        padding: `calc(${componentTheme.baseSpacingMedium} / 3) calc(${componentTheme.baseSpacingMedium} / 2)`
+      }
+    },
+    large: {
+      folderTree: {
+        padding: `calc(${componentTheme.baseSpacingLarge} / 3) ${componentTheme.baseSpacingLarge}`
+      },
+      indent: {
+        padding: `calc(${componentTheme.baseSpacingLarge} / 3) calc(${componentTheme.baseSpacingLarge} / 2)`
+      }
+    }
+  }
+
+  return {
+    treeButton: {
+      label: 'treeButton',
+      boxSizing: 'border-box',
+      display: 'block',
+      width: '100%',
+      margin: '0',
+      backgroundColor: 'transparent',
+      textAlign: 'start',
+      fontFamily: 'inherit',
+      userSelect: 'none',
+      cursor: 'pointer',
+      border: 'none',
+      borderRadius: componentTheme.borderRadius,
+      position: 'relative',
+      zIndex: 1,
+      ...(state?.animation
+        ? {
+            transform: 'translate3d(-2%, 0, 0)',
+            opacity: 0.01,
+            transformOrigin: 'left center',
+            animationName: transform,
+            animationDuration: '0.2s',
+            animationFillMode: 'forwards',
+            animationTimingFunction: 'ease-out',
+            animationDelay: '0.2s'
+          }
+        : {}),
+      outline: '0',
+      padding: '0',
+      ...(sharedTokens?.focusOutline
+        ? calcFocusOutlineStyles(sharedTokens.focusOutline)
+        : {}),
+      ...(variant === 'folderTree' &&
+        !isRootButton && {
+          '&::before': {
+            content: '""',
+            height: componentTheme.borderWidth,
+            background: componentTheme.borderColor, // Tree horizontal lines
+            position: 'absolute',
+            insetInlineStart: '0',
+            insetInlineEnd: 'auto',
+            top: '50%',
+            ...(selected && { visibility: 'hidden' }),
+            ...sizeMap[size!][variant!].before
+          },
+          '&:hover::before': {
+            visibility: state?.hoverable ? 'hidden' : 'visible'
+          }
+        }),
+      ...(state?.hoverable !== false && {
+        '&:hover': {
+          backgroundColor: selected
+            ? componentTheme.selectedBackgroundColor
+            : componentTheme.hoverBackgroundColor,
+
+          '[class$=-treeButton__textName], [class$=-treeButton__textDescriptor], [class$=-treeButton__node]':
+            {
+              color: selected
+                ? componentTheme.selectedTextColor
+                : componentTheme.hoverTextColor
+            }
+        }
+      }),
+      ...(selected && {
+        backgroundColor: componentTheme.selectedBackgroundColor
+      })
+    },
+    layout: {
+      label: 'treeButton__layout',
+      display: 'flex',
+      alignItems: 'center',
+      lineHeight: 1,
+      minHeight: '2rem',
+      ...layoutPadding[size!][variant!]
+    },
+    text: {
+      label: 'treeButton__text',
+      ...textStyle
+    },
+    textName: {
+      label: 'treeButton__textName',
+      ...textNameStyle,
+      color: selected
+        ? componentTheme.selectedTextColor
+        : componentTheme.nameTextColor
+    },
+    textDescriptor: {
+      label: 'treeButton__textDescriptor',
+      display: 'block',
+      overflow: 'hidden',
+      whiteSpace: 'nowrap',
+      textOverflow: 'ellipsis',
+      marginTop: componentTheme.descriptorMarginTop,
+      color: selected
+        ? componentTheme.selectedTextColor
+        : componentTheme.descriptorTextColor,
+      ...sizeMap[size!].textDescriptor
+    },
+    icon: {
+      label: 'treeButton__icon',
+      minWidth: '0.0625rem',
+      position: 'relative',
+      zIndex: 1,
+      alignItems: 'center',
+      justifyContent: 'center',
+      ...sizeMap[size!][variant!].icon
+    },
+    thumbnail: {
+      label: 'treeButton__thumbnail',
+      ...sizeMap[size!][variant!].thumbnail
+    },
+    node: {
+      label: 'treeButton__node',
+      ...textStyle,
+      ...textNameStyle,
+      color: componentTheme.descriptorTextColor
+    }
+  }
+}
+
+export default generateStyles