@instructure/ui-truncate-list 8.27.1-snapshot-13

package/src/TruncateList/TruncateListLocator.ts

@@ -0,0 +1,37 @@
+/*
+ * 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 { locator } from '@instructure/ui-test-locator'
+import { find, findAll } from '@instructure/ui-test-queries'
+
+import { TruncateList } from './index'
+
+// @ts-expect-error ts-migrate(2339) FIXME: Property 'selector' does not exist on type 'typeof... Remove this comment to see the full error message
+export const TruncateListLocator = locator(TruncateList.selector, {
+  findAllListItems: (...args: any[]) => {
+    return findAll('li', ...args)
+  },
+  findMenuTriggerItem: (...args: any[]) => {
+    return find('li[class*=-truncateList__menuTrigger]', ...args)
+  }
+})

package/src/TruncateList/index.tsx

@@ -0,0 +1,311 @@
+/*
+ * 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.
+ */
+
+/** @jsx jsx */
+import { Children, Component } from 'react'
+
+import { debounce } from '@instructure/debounce'
+import type { Debounced } from '@instructure/debounce'
+import { px } from '@instructure/ui-utils'
+import { testable } from '@instructure/ui-testable'
+import { omitProps } from '@instructure/ui-react-utils'
+import { getBoundingClientRect } from '@instructure/ui-dom-utils'
+
+import { withStyle, jsx } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import { propTypes, allowedProps } from './props'
+import type { TruncateListProps, TruncateListState } from './props'
+
+/**
+---
+category: components/utilities
+---
+@tsProps
+**/
+@withStyle(generateStyle, null)
+@testable()
+class TruncateList extends Component<TruncateListProps, TruncateListState> {
+  static readonly componentId = 'TruncateList'
+
+  static propTypes = propTypes
+  static allowedProps = allowedProps
+  static defaultProps = {
+    itemSpacing: '0',
+    debounce: 300
+  }
+
+  ref: HTMLUListElement | null = null
+
+  private _menuTriggerRef: HTMLLIElement | null = null
+
+  private _debouncedHandleResize?: Debounced
+  private _resizeListener?: ResizeObserver
+
+  handleRef = (el: HTMLUListElement | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  constructor(props: TruncateListProps) {
+    super(props)
+
+    this.state = {
+      isMeasuring: false,
+      menuTriggerWidth: undefined
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+
+    const { width: origWidth } = getBoundingClientRect(this.ref)
+
+    this._debouncedHandleResize = debounce(
+      this.handleResize,
+      this.props.debounce,
+      {
+        leading: true,
+        trailing: true
+      }
+    )
+
+    this._resizeListener = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const { width } = entry.contentRect
+
+        if (origWidth !== width) {
+          this._debouncedHandleResize?.()
+        }
+      }
+    })
+
+    // On first render we only render the trigger to measure it
+    const menuTriggerWidth = this.props.fixMenuTriggerWidth
+      ? px(this.props.fixMenuTriggerWidth)
+      : this.calcMenuTriggerWidth()
+
+    this.setState({ menuTriggerWidth }, () => {
+      this._resizeListener?.observe(this.ref!)
+
+      this._debouncedHandleResize?.()
+    })
+  }
+
+  componentDidUpdate(
+    prevProps: TruncateListProps,
+    prevState: TruncateListState
+  ) {
+    this.props.makeStyles?.()
+
+    if (
+      prevProps.fixMenuTriggerWidth !== this.props.fixMenuTriggerWidth ||
+      prevProps.itemSpacing !== this.props.itemSpacing
+    ) {
+      this._debouncedHandleResize?.()
+    }
+
+    if (
+      this.ref &&
+      prevState.isMeasuring &&
+      prevState.isMeasuring !== this.state.isMeasuring
+    ) {
+      const menuTriggerWidth = this.calcMenuTriggerWidth()
+
+      if (
+        menuTriggerWidth &&
+        this.state.menuTriggerWidth !== menuTriggerWidth
+      ) {
+        this.setState({ menuTriggerWidth }, () => {
+          this._debouncedHandleResize?.()
+        })
+      }
+    }
+  }
+
+  componentWillUnmount() {
+    if (this._resizeListener) {
+      this._resizeListener.disconnect()
+    }
+
+    if (this._debouncedHandleResize) {
+      this._debouncedHandleResize.cancel()
+    }
+  }
+
+  get childrenArray() {
+    return Children.toArray(this.props.children)
+  }
+
+  get visibleChildren() {
+    const { visibleItemsCount } = this.props
+    const { isMeasuring, menuTriggerWidth } = this.state
+
+    // for the first render we need to measure the trigger width
+    if (typeof menuTriggerWidth === 'undefined') {
+      return []
+    }
+
+    const visibleChildren =
+      typeof visibleItemsCount === 'undefined'
+        ? this.childrenArray
+        : this.childrenArray.splice(0, visibleItemsCount)
+
+    return isMeasuring ? this.childrenArray : visibleChildren
+  }
+
+  get hiddenChildren() {
+    const { isMeasuring } = this.state
+
+    return isMeasuring
+      ? []
+      : this.childrenArray.splice(
+          this.visibleChildren.length,
+          this.childrenArray.length
+        )
+  }
+
+  calcMenuTriggerWidth() {
+    const { fixMenuTriggerWidth } = this.props
+
+    if (!this._menuTriggerRef) {
+      return 0
+    }
+
+    if (fixMenuTriggerWidth) {
+      return px(fixMenuTriggerWidth)
+    }
+
+    const { children } = this._menuTriggerRef
+    let width = 0
+
+    Array.from(children).forEach((child) => {
+      width += getBoundingClientRect(child).width
+    })
+
+    return width
+  }
+
+  measureItems = () => {
+    const { fixMenuTriggerWidth, itemSpacing } = this.props
+
+    const itemSpacingPx = px(itemSpacing!)
+    const menuTriggerWidthPx = px(
+      fixMenuTriggerWidth || this.state.menuTriggerWidth!
+    )
+
+    let visibleItemsCount = 0
+
+    if (this.ref) {
+      const { width: navWidth } = getBoundingClientRect(this.ref)
+
+      const itemWidths = Array.from(this.ref.getElementsByTagName('li')).map(
+        (item) => {
+          const { width } = getBoundingClientRect(item)
+          return width
+        }
+      )
+
+      let currentWidth = 0
+
+      for (let i = 0; i < itemWidths.length; i++) {
+        currentWidth += itemWidths[i]
+
+        // for the last item we don't need to calculate with the menu trigger
+        const maxWidth =
+          i === itemWidths.length - 1
+            ? navWidth
+            : navWidth - (menuTriggerWidthPx + itemSpacingPx)
+
+        if (currentWidth <= maxWidth) {
+          visibleItemsCount++
+        } else {
+          break
+        }
+      }
+    }
+
+    return { visibleItemsCount }
+  }
+
+  handleResize = () => {
+    this.setState({ isMeasuring: true }, () => {
+      const { visibleItemsCount } = this.measureItems()
+
+      if (typeof this.props.onUpdate === 'function') {
+        this.props.onUpdate({ visibleItemsCount })
+      }
+      this.setState({ isMeasuring: false })
+    })
+  }
+
+  render() {
+    const { styles, className, style, renderHiddenItemMenu } = this.props
+    const { visibleChildren, hiddenChildren } = this
+
+    return (
+      <ul
+        ref={this.handleRef}
+        {...omitProps(this.props, allowedProps)}
+        // we have to pass style and className
+        // (e.g. if emotion style is provided, it will be passed as a className)
+        className={className}
+        style={style}
+        css={styles?.truncateList}
+      >
+        {visibleChildren.map((child, index) => {
+          return (
+            <li key={index} css={styles?.listItem}>
+              {child}
+            </li>
+          )
+        })}
+
+        {/* On first render we only render the trigger to measure it */}
+        {typeof renderHiddenItemMenu === 'function' &&
+          hiddenChildren &&
+          hiddenChildren.length > 0 && (
+            <li
+              key="menuTrigger"
+              css={[styles?.listItem, styles?.menuTrigger]}
+              ref={(e) => {
+                this._menuTriggerRef = e
+              }}
+            >
+              {renderHiddenItemMenu(hiddenChildren)}
+            </li>
+          )}
+      </ul>
+    )
+  }
+}
+
+export { TruncateList }
+export default TruncateList

package/src/TruncateList/props.ts

@@ -0,0 +1,124 @@
+/*
+ * 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 PropTypes from 'prop-types'
+
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  OtherHTMLAttributes,
+  PropValidators
+} from '@instructure/shared-types'
+
+type TruncateListOwnProps = {
+  /**
+   * List of items in the truncated list
+   */
+  children?: React.ReactNode
+
+  /**
+   * Sets the number of navigation items that are visible.
+   * If not set, the list is not truncated.
+   */
+  visibleItemsCount?: number
+
+  /**
+   * When there are list items hidden, an optional element
+   * (dropdown menu, link, etc.) can be provided to display them
+   * (renders at the end of the list).
+   */
+  renderHiddenItemMenu?: (
+    hiddenChildren: Exclude<React.ReactNode, boolean | null | undefined>[]
+  ) => React.ReactElement
+
+  /**
+   * Called whenever the navigation items are updated or the size of
+   * the navigation changes. Passes in the `visibleItemsCount` as
+   * a parameter.
+   */
+  onUpdate?: ({ visibleItemsCount }: { visibleItemsCount: number }) => void
+
+  /**
+   * The spacing between list items (in 'rem', 'em' or 'px')
+   */
+  itemSpacing?: string
+
+  /**
+   * Fix width of the Menu trigger (in 'rem', 'em' or 'px')
+   */
+  fixMenuTriggerWidth?: string
+
+  /**
+   * The rate (in ms) the component responds to container resizing or
+   * an update to one of its child items
+   */
+  debounce?: number
+
+  /**
+   * Provides a reference to the underlying ul element
+   */
+  elementRef?: (element: HTMLUListElement | null) => void
+}
+
+type PropKeys = keyof TruncateListOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type TruncateListProps = TruncateListOwnProps &
+  WithStyleProps<null, TruncateListStyle> &
+  OtherHTMLAttributes<TruncateListOwnProps>
+
+type TruncateListStyle = ComponentStyle<
+  'truncateList' | 'listItem' | 'menuTrigger'
+>
+
+type TruncateListState = {
+  isMeasuring: boolean
+  menuTriggerWidth?: number
+}
+
+const propTypes: PropValidators<PropKeys> = {
+  children: PropTypes.node,
+  visibleItemsCount: PropTypes.number,
+  onUpdate: PropTypes.func,
+  renderHiddenItemMenu: PropTypes.func,
+  itemSpacing: PropTypes.string,
+  fixMenuTriggerWidth: PropTypes.string,
+  debounce: PropTypes.number,
+  elementRef: PropTypes.func
+}
+
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'renderHiddenItemMenu',
+  'visibleItemsCount',
+  'itemSpacing',
+  'fixMenuTriggerWidth',
+  'debounce',
+  'onUpdate',
+  'elementRef'
+]
+
+export type { TruncateListProps, TruncateListStyle, TruncateListState }
+export { propTypes, allowedProps }

package/src/TruncateList/styles.ts

@@ -0,0 +1,81 @@
+/*
+ * 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 type { TruncateListProps, TruncateListStyle } from './props'
+
+/**
+ * ---
+ * 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 generateStyle = (
+  _componentTheme: null,
+  props: TruncateListProps
+): TruncateListStyle => {
+  const { itemSpacing, fixMenuTriggerWidth } = props
+
+  const listItemStyle = {
+    minWidth: '0.0625rem',
+    flexShrink: 0,
+    flexGrow: 0
+  }
+
+  return {
+    truncateList: {
+      label: 'truncateList',
+      boxSizing: 'border-box',
+      listStyleType: 'none',
+      margin: '0',
+      padding: '0',
+      display: 'flex',
+      justifyContent: 'flex-start',
+      alignItems: 'center'
+    },
+    listItem: {
+      label: 'truncateList__listItem',
+      ...listItemStyle,
+
+      '& + &': {
+        paddingInlineStart: itemSpacing
+      }
+    },
+    menuTrigger: {
+      label: 'truncateList__menuTrigger',
+      maxWidth: '100%',
+      ...(fixMenuTriggerWidth && { width: fixMenuTriggerWidth }),
+      paddingInlineStart: itemSpacing,
+
+      '&:first-of-type': {
+        paddingInlineStart: 0
+      }
+    }
+  }
+}
+
+export default generateStyle

package/src/index.ts

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+export { TruncateList } from './TruncateList'
+export type { TruncateListProps } from './TruncateList/props'

package/tsconfig.build.json

@@ -0,0 +1,25 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./types",
+    "composite": true
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../console/tsconfig.build.json" },
+    { "path": "../debounce/tsconfig.build.json" },
+    { "path": "../emotion/tsconfig.build.json" },
+    { "path": "../shared-types/tsconfig.build.json" },
+    { "path": "../ui-dom-utils/tsconfig.build.json" },
+    { "path": "../ui-react-utils/tsconfig.build.json" },
+    { "path": "../ui-testable/tsconfig.build.json" },
+    { "path": "../ui-utils/tsconfig.build.json" },
+    { "path": "../ui-babel-preset/tsconfig.build.json" },
+    { "path": "../ui-color-utils/tsconfig.build.json" },
+    { "path": "../ui-test-locator/tsconfig.build.json" },
+    { "path": "../ui-test-queries/tsconfig.build.json" },
+    { "path": "../ui-test-utils/tsconfig.build.json" },
+    { "path": "../ui-themes/tsconfig.build.json" }
+  ]
+}