@instructure/ui-truncate-text 11.6.0 → 11.6.1-snapshot-129

package/src/TruncateText/v2/README.md

@@ -0,0 +1,230 @@
+---
+describes: TruncateText
+---
+
+A component for truncating text content.
+
+> For best results, avoid using TruncateText inside parent containers that are inline (`display: inline/inline-block`) or that default to inline display (span, link, etc.).
+
+### Single line
+
+```javascript
+---
+type: example
+---
+
+<div>
+  <View
+    as="div"
+    padding="xx-small none"
+    maxWidth="480px"
+    withVisualDebug
+  >
+    <Heading level="h1">
+      <TruncateText>
+        {lorem.paragraph()}
+      </TruncateText>
+    </Heading>
+    <Text
+      as="p"
+      weight="bold"
+      size="large"
+      transform="uppercase"
+      letterSpacing="expanded"
+    >
+      <TruncateText>
+        {lorem.paragraph()}
+      </TruncateText>
+    </Text>
+    <Text as="p">
+      <TruncateText>
+        {lorem.paragraph()}
+      </TruncateText>
+    </Text>
+
+    <div>
+      <TruncateText
+        onUpdate={(truncated, text) => {
+          console.log(truncated, text)
+        }}
+      >
+        <span>
+          Regular sized text with <Link href="#">A Text Link </Link>and <Text weight="bold">some bold text.</Text>
+        </span>
+      </TruncateText>
+    </div>
+
+  </View>
+</div>
+```
+
+### Multiple lines
+
+You can set the number of lines to display before truncation begins with the `maxLines` prop. Setting `maxLines` to `auto` will determine the number of lines that will fit.
+
+```javascript
+---
+type: example
+---
+<div>
+  <View
+    as="div"
+    padding="small none"
+    maxWidth="480px"
+    withVisualDebug
+  >
+    <Text as="p" size="large">
+      <TruncateText
+        maxLines={2}
+        truncate="word"
+        ellipsis=" (...)"
+      >
+        {lorem.paragraph()}
+      </TruncateText>
+      <Link href="#">Read More</Link>
+    </Text>
+
+    <Text as="p" lineHeight="double">
+      <TruncateText
+        maxLines={4}
+        truncate="word"
+        ellipsis=" (...)"
+      >
+        Esse aliqua minim veniam duis consectetur non sunt ea deserunt qui cillum laboris officia. Minim nulla commodo dolore reprehenderit commodo occaecat veniam ad consectetur mollit consectetur partur consectetur eiusmod dolor incididunt incididunt.
+      </TruncateText>
+      <Link href="#">Read More</Link>
+    </Text>
+  </View>
+  <br />
+  <View
+    as="div"
+    padding="small none"
+    maxWidth="480px"
+    withVisualDebug
+  >
+    <Text as="p">
+      <TruncateText maxLines={4} ellipsis=" (...)">
+        <span>Esse aliqua minim veniam duis consectetur non sunt ea deserunt qui cillum laboris officia. <Link href="#">http://instructure.github.io/instructure-ui/#ui-elements</Link> occaecat veniam ad consectetur mollit consectetur partur consectetur eiusmod dolor incididunt incididunt.</span>
+      </TruncateText>
+    </Text>
+
+    <Text as="p">
+      <TruncateText maxLines={4} ellipsis=" (...)">
+        <span>Qui cillum laboris officia. <strong>supercalifragilisticexpialidocious</strong> occaecat veniam ad consectetur mollit consectetur partur consectetur eiusmod dolor incididunt incididunt. Esse aliqua minim veniam duis consectetur non sunt ea deserunt.</span>
+      </TruncateText>
+    </Text>
+  </View>
+  <br />
+  <div style={{height: '78px', border: 'solid 1px red'}}>
+    <Text>
+      <TruncateText maxLines="auto" ellipsis=" (...)">
+        Esse aliqua minim veniam duis consectetur non sunt ea deserunt qui cillum laboris officia. Minim nulla commodo dolore reprehenderit commodo occaecat veniam ad consectetur mollit consectetur partur consectetur eiusmod dolor incididunt incididunt.
+      </TruncateText>
+    </Text>
+  </div>
+</div>
+
+```
+
+### Truncate middle
+
+You can set the position of the truncation using the `position` prop.
+
+```javascript
+---
+type: example
+---
+<div>
+  <View
+    as="div"
+    padding="small none"
+    maxWidth="480px"
+    withVisualDebug
+  >
+    <Text as="p">
+      <TruncateText position="middle">
+        <span>This line of text should be truncated from the middle of the string <strong>instead of the end.</strong></span>
+      </TruncateText>
+    </Text>
+  </View>
+  <br />
+  <View
+    as="div"
+    padding="small none"
+    maxWidth="480px"
+    withVisualDebug
+  >
+    <Link href="#">
+      <TruncateText
+        position="middle"
+        truncate="word"
+        ellipsis=".../"
+      >
+        @instructure/ui-elements/somefakedir/tomakethislonger/lib/longer/TruncateText
+      </TruncateText>
+    </Link>
+  </View>
+</div>
+```
+
+### Using tooltips
+
+It's best practice to make the complete text of a truncated element available via a [Tooltip](Tooltip).
+
+```js
+---
+type: example
+---
+const Example = (props) => {
+  const [isTruncated, setIsTruncated] = useState(false)
+
+  const handleUpdate = (newIsTruncated) => {
+    if (isTruncated !== newIsTruncated) {
+      setIsTruncated(newIsTruncated)
+    }
+  }
+
+  const renderLink = () => (
+    <Link href="#">
+      <TruncateText onUpdate={handleUpdate}>{props.message}</TruncateText>
+    </Link>
+  )
+
+  return (
+    <View as="div" padding="xx-small none" maxWidth="230px" withVisualDebug>
+      {isTruncated ? (
+        <Tooltip
+          renderTip={props.message}
+          mountNode={() => document.getElementById('main')}
+        >
+          {renderLink()}
+        </Tooltip>
+      ) : (
+        renderLink()
+      )}
+    </View>
+  )
+}
+render(
+  <Example message="A tooltip will display only when this text is truncated" />
+)
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Use a <Link href="/#Tooltip">Tooltip</Link> for all truncated items</Figure.Item>
+    <Figure.Item>Use when trying to restrict the number of lines that are visible</Figure.Item>
+    <Figure.Item>Use end ellipsis if the unique identifier is at the beginning of the string</Figure.Item>
+    <Figure.Item>Use middle ellipsis if the unique identifier is at the end of the string</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Use in <Link href="/#Button">Buttons</Link>, <Link href="/#Navigation">Nav Items</Link>, <Link href="/#TabList">TabLists</Link></Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/TruncateText/v2/index.tsx

@@ -0,0 +1,314 @@
+/*
+ * 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 { Children, Component, type JSX } from 'react'
+
+import { debounce } from '@instructure/debounce'
+import type { Debounced } from '@instructure/debounce'
+import { canUseDOM, getBoundingClientRect } from '@instructure/ui-dom-utils'
+import {
+  safeCloneElement,
+  ensureSingleChild
+} from '@instructure/ui-react-utils'
+import { logError as error } from '@instructure/console'
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import truncate from './utils/truncate'
+import { allowedProps, TruncateTextState } from './props'
+import type { TruncateTextProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class TruncateText extends Component<TruncateTextProps, TruncateTextState> {
+  static readonly componentId = 'TruncateText'
+
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    maxLines: 1,
+    ellipsis: '\u2026',
+    truncate: 'character',
+    position: 'end',
+    ignore: [' ', '.', ','],
+    debounce: 0
+  }
+
+  ref: Element | null = null
+  private _text?: JSX.Element
+  private _debounced?: Debounced<typeof this.update>
+  private _stage: HTMLSpanElement | null = null
+  private _wasTruncated?: boolean
+  private _resizeListener?: ResizeObserver
+  private _prevWidth: number | null = null
+
+  constructor(props: TruncateTextProps) {
+    super(props)
+    this.state = this.initialState
+  }
+
+  get _ref() {
+    console.warn(
+      '_ref property is deprecated and will be removed in v9, please use ref instead'
+    )
+    return this.ref
+  }
+
+  get initialState() {
+    return {
+      isTruncated: false,
+      needsSecondRender: true,
+      truncatedElement: undefined,
+      truncatedText: undefined
+    }
+  }
+
+  componentDidMount() {
+    const { children, makeStyles } = this.props
+
+    makeStyles?.()
+
+    if (children) {
+      this.checkChildren()
+      const txt = ensureSingleChild(children)
+      this._text = txt ? txt : undefined
+
+      this.truncate()
+
+      this._debounced = debounce(this.update, this.props.debounce, {
+        leading: true,
+        trailing: true
+      })
+
+      this._prevWidth = getBoundingClientRect(this.ref)?.width
+      this._resizeListener = new ResizeObserver((entries) => {
+        // requestAnimationFrame call is needed becuase some truncatetext test cases
+        // failed due to ResizeObserver was not able to deliver all observations within a single animation frame
+        // see: https://stackoverflow.com/questions/49384120/resizeobserver-loop-limit-exceeded
+        requestAnimationFrame(() => {
+          for (const entry of entries) {
+            const { width } = entry.contentRect
+
+            if (this._prevWidth !== width) {
+              this._prevWidth = width
+              this.props.debounce === 0 ? this.update() : this._debounced!()
+            }
+          }
+        })
+      })
+      this._resizeListener.observe(this.ref!)
+    }
+  }
+
+  componentWillUnmount() {
+    if (this._resizeListener) {
+      this._resizeListener.disconnect()
+    }
+
+    if (this._debounced) {
+      this._debounced.cancel()
+    }
+  }
+
+  shallowCompare(obj1: any, obj2: any) {
+    const keys1 = Object.keys(obj1)
+    const keys2 = Object.keys(obj2)
+    if (keys1.length !== keys2.length) {
+      return false
+    }
+    for (const key of keys1) {
+      if (obj1[key] !== obj2[key]) {
+        return false
+      }
+    }
+    return true
+  }
+
+  componentDidUpdate(prevProps: TruncateTextProps) {
+    const { children, onUpdate, makeStyles } = this.props
+    makeStyles?.()
+    const { isTruncated, needsSecondRender, truncatedText } = this.state
+
+    if (children) {
+      // for some reason in React 19 prevPros and this.props are a different
+      // object even if their contents are the same, so we cannot use !==
+      if (!this.shallowCompare(prevProps, this.props)) {
+        if (prevProps.children !== this.props.children) {
+          // reset internal text variable if children change
+          this.checkChildren()
+          const txt = ensureSingleChild(children)
+          this._text = txt ? txt : undefined
+        }
+        // require the double render whenever props change
+        this.setState(this.initialState)
+        return
+      }
+
+      if (!needsSecondRender && (isTruncated || this._wasTruncated)) {
+        onUpdate?.(isTruncated, truncatedText)
+        this._wasTruncated = isTruncated
+      } else {
+        this.truncate()
+      }
+    }
+  }
+
+  checkChildren() {
+    error(
+      !(() => {
+        let isTooDeep = false
+        const text = ensureSingleChild(this.props.children)!
+        Children.forEach(text.props.children, (child) => {
+          if (child.props) {
+            Children.forEach(child.props.children, (grandChild) => {
+              // currently we don't support node trees deeper than 2 levels
+              // truncation will still occur on their text content, but their actual node structure will be lost
+              if (grandChild.props) {
+                isTooDeep = true
+              }
+            })
+          }
+        })
+        return isTooDeep
+      })(),
+      `[TruncateText] Some children are too deep in the node tree and will not render.`
+    )
+  }
+
+  update = () => {
+    if (this.ref) {
+      this.setState(this.initialState)
+    }
+  }
+
+  truncate() {
+    if (!this.state.needsSecondRender) {
+      return
+    }
+
+    if (canUseDOM) {
+      const result = truncate(this._stage!, {
+        ...this.props,
+        parent: this.ref ? this.ref : undefined,
+        lineHeight: this.props.styles?.lineHeight as number
+      })
+      if (result) {
+        const element = this.renderChildren(
+          result.isTruncated,
+          result.data,
+          result.constraints.width
+        )
+        this.setState({
+          needsSecondRender: false,
+          isTruncated: result.isTruncated,
+          truncatedElement: element,
+          truncatedText: result.text
+        })
+      }
+    } else {
+      const textContent = this.ref?.textContent
+        ? this.ref?.textContent
+        : undefined
+      // if dom isn't available, use original children
+      this.setState({
+        needsSecondRender: false,
+        isTruncated: false,
+        truncatedElement: this._text,
+        truncatedText: textContent
+      })
+    }
+  }
+
+  renderChildren(truncated: boolean, data: string[][], width: number) {
+    if (!truncated) {
+      return this._text
+    }
+
+    const childElements = []
+    // iterate over each node used in the truncated string
+    for (let i = 0; i < data.length; i++) {
+      const item = data[i]
+      const element = this._text!.props.children[i]
+      const nodeText = item.join('')
+
+      if (element && element.props) {
+        // if node is an html element and not just a string
+        childElements.push(safeCloneElement(element, element.props, nodeText))
+      } else {
+        childElements.push(nodeText)
+      }
+    }
+    // this spacer element is set to the max width the full text could
+    // potentially be without this, text in `width: auto` elements won't expand
+    // to accommodate more text, once truncated
+    // Breadcrumb is modifying this element's display to inline to prevent layout issues
+    // TODO: find a better way to handle this
+    childElements.push(
+      <span
+        css={this.props.styles?.spacer}
+        style={{ width: width || undefined }}
+        key="spacer" // TODO this is a temp solution so tests on the CI pass... for v11_rc
+      />
+    )
+
+    const children = Children.map(childElements, (child) => child)
+    return this._text!.props
+      ? safeCloneElement(this._text!, this._text!.props, children)
+      : children
+  }
+
+  render() {
+    const { truncatedElement } = this.state
+    const { children } = this.props
+    return (
+      <span
+        data-cid="TruncateText"
+        css={this.props.styles?.truncateText}
+        ref={(el) => {
+          this.ref = el
+        }}
+      >
+        {children &&
+          (truncatedElement ? null : (
+            <span
+              ref={(el) => {
+                this._stage = el
+              }}
+            >
+              {ensureSingleChild(children)}
+            </span>
+          ))}
+        {truncatedElement}
+      </span>
+    )
+  }
+}
+
+export default TruncateText
+export { TruncateText }

package/src/TruncateText/v2/props.ts

@@ -0,0 +1,113 @@
+/*
+ * 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 { ReactNode } from 'react'
+
+import type { TruncateTextTheme } from '@instructure/shared-types'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+
+type CleanDataOptions = {
+  /**
+   * Add ellipsis after words or after any character. Default is 'character'
+   */
+  truncate?: 'character' | 'word'
+  /**
+   * A string to use as the ellipsis
+   */
+  ellipsis?: string
+  /**
+   * Characters to ignore at truncated end of string. Default is ' ', '.', ','
+   */
+  ignore?: string[]
+}
+
+type TruncateTextCommonProps = {
+  /**
+   * Number of lines to allow before truncating. `auto` will fit to parent.
+   * Default is 1.
+   */
+  maxLines?: 'auto' | number
+  /**
+   * Where to place the ellipsis within the string. Default is 'end'
+   */
+  position?: 'end' | 'middle'
+  /**
+   * Force truncation of invisible elements (hack; will be removed in favor
+   * of a better fix)
+   */
+  shouldTruncateWhenInvisible?: boolean
+} & CleanDataOptions
+
+type TruncateTextOwnProps = {
+  /**
+   * The content to be truncated.
+   */
+  children: React.ReactNode
+  /**
+   * Debounce delay in milliseconds
+   */
+  debounce?: number
+  /**
+   * Callback when truncated text has changed
+   */
+  onUpdate?: (isTruncated: boolean, truncatedText?: string) => void
+} & TruncateTextCommonProps
+
+type PropKeys = keyof TruncateTextOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type TruncateTextProps = TruncateTextOwnProps &
+  WithStyleProps<TruncateTextTheme, TruncateTextStyle>
+
+type TruncateTextStyle = ComponentStyle<
+  'truncateText' | 'auto' | 'spacer' | 'lineHeight'
+>
+
+type TruncateTextState = {
+  isTruncated: boolean
+  needsSecondRender: boolean
+  truncatedElement?: ReactNode
+  truncatedText?: string
+}
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'maxLines',
+  'position',
+  'truncate',
+  'ellipsis',
+  'ignore',
+  'debounce',
+  'onUpdate',
+  'shouldTruncateWhenInvisible'
+]
+
+export type {
+  CleanDataOptions,
+  TruncateTextCommonProps,
+  TruncateTextProps,
+  TruncateTextState,
+  TruncateTextStyle
+}
+export { allowedProps }