feat(Truncate): added logic to truncate based on max characters (#11742)

* feat(Truncate): added logic to truncate based on max characters

* Converted existing examples to TS

* Wrote tests for max chars logic

* Wrapped visible content in classless spans

* Updated classes based on core updates

Author: thatblindgeye

packages/react-core/src/components/Truncate/Truncate.tsx

@@ -22,8 +22,18 @@ export interface TruncateProps extends React.HTMLProps<HTMLSpanElement> {
   className?: string;
   /** Text to truncate */
   content: string;
-  /** The number of characters displayed in the second half of the truncation */
+  /** The number of characters displayed in the second half of a middle truncation. This will be overridden by
+   * the maxCharsDisplayed prop.
+   */
   trailingNumChars?: number;
+  /** The maximum number of characters to display before truncating. This will always truncate content
+   * when its length exceeds the value passed to this prop, and container width/resizing will not affect truncation.
+   */
+  maxCharsDisplayed?: number;
+  /** The content to use to signify omission of characters when using the maxCharsDisplayed prop.
+   * By default this will render an ellipsis.
+   */
+  omissionContent?: string;
   /** Where the text will be truncated */
   position?: 'start' | 'middle' | 'end';
   /** Tooltip position */
@@ -49,25 +59,33 @@ export interface TruncateProps extends React.HTMLProps<HTMLSpanElement> {
   refToGetParent?: React.RefObject<any>;
 }
 
-const sliceContent = (str: string, slice: number) => [str.slice(0, str.length - slice), str.slice(-slice)];
+const sliceTrailingContent = (str: string, slice: number) => [str.slice(0, str.length - slice), str.slice(-slice)];
 
 export const Truncate: React.FunctionComponent<TruncateProps> = ({
   className,
   position = 'end',
   tooltipPosition = 'top',
   trailingNumChars = 7,
+  maxCharsDisplayed,
+  omissionContent = '\u2026',
   content,
   refToGetParent,
   ...props
 }: TruncateProps) => {
   const [isTruncated, setIsTruncated] = useState(true);
   const [parentElement, setParentElement] = useState<HTMLElement>(null);
   const [textElement, setTextElement] = useState<HTMLElement>(null);
+  const [shouldRenderByMaxChars, setShouldRenderByMaxChars] = useState(maxCharsDisplayed > 0);
 
   const textRef = useRef<HTMLElement>(null);
   const subParentRef = useRef<HTMLDivElement>(null);
   const observer = useRef(null);
 
+  if (maxCharsDisplayed <= 0) {
+    // eslint-disable-next-line no-console
+    console.warn('Truncate: the maxCharsDisplayed must be greater than 0, otherwise no content will be visible.');
+  }
+
   const getActualWidth = (element: Element) => {
     const computedStyle = getComputedStyle(element);
 
@@ -100,7 +118,7 @@ export const Truncate: React.FunctionComponent<TruncateProps> = ({
   }, [textRef, subParentRef, textElement, parentElement]);
 
   useEffect(() => {
-    if (textElement && parentElement && !observer.current) {
+    if (textElement && parentElement && !observer.current && !shouldRenderByMaxChars) {
       const totalTextWidth = calculateTotalTextWidth(textElement, trailingNumChars, content);
       const textWidth = position === 'middle' ? totalTextWidth : textElement.scrollWidth;
 
@@ -115,31 +133,100 @@ export const Truncate: React.FunctionComponent<TruncateProps> = ({
         observer();
       };
     }
-  }, [textElement, parentElement, trailingNumChars, content, position]);
+  }, [textElement, parentElement, trailingNumChars, content, position, shouldRenderByMaxChars]);
 
-  const truncateBody = (
-    <span ref={subParentRef} className={css(styles.truncate, className)} {...props}>
-      {(position === TruncatePosition.end || position === TruncatePosition.start) && (
-        <span ref={textRef} className={truncateStyles[position]}>
-          {content}
-          {position === TruncatePosition.start && <Fragment>&lrm;</Fragment>}
-        </span>
-      )}
-      {position === TruncatePosition.middle && content.length - trailingNumChars > minWidthCharacters && (
-        <Fragment>
-          <span ref={textRef} className={styles.truncateStart}>
-            {sliceContent(content, trailingNumChars)[0]}
+  useEffect(() => {
+    if (shouldRenderByMaxChars) {
+      setIsTruncated(content.length > maxCharsDisplayed);
+    }
+  }, [shouldRenderByMaxChars]);
+
+  useEffect(() => {
+    setShouldRenderByMaxChars(maxCharsDisplayed > 0);
+  }, [maxCharsDisplayed]);
+
+  const renderResizeObserverContent = () => {
+    if (position === TruncatePosition.end || position === TruncatePosition.start) {
+      return (
+        <>
+          <span ref={textRef} className={truncateStyles[position]}>
+            {content}
+            {position === TruncatePosition.start && <Fragment>&lrm;</Fragment>}
           </span>
-          <span className={styles.truncateEnd}>{sliceContent(content, trailingNumChars)[1]}</span>
-        </Fragment>
-      )}
-      {position === TruncatePosition.middle && content.length - trailingNumChars <= minWidthCharacters && (
+        </>
+      );
+    }
+
+    const shouldSliceContent = content.length - trailingNumChars > minWidthCharacters;
+    return (
+      <>
         <Fragment>
           <span ref={textRef} className={styles.truncateStart}>
-            {content}
+            {shouldSliceContent ? sliceTrailingContent(content, trailingNumChars)[0] : content}
           </span>
+          {shouldSliceContent && (
+            <span className={styles.truncateEnd}>{sliceTrailingContent(content, trailingNumChars)[1]}</span>
+          )}
         </Fragment>
-      )}
+      </>
+    );
+  };
+
+  const renderMaxDisplayContent = () => {
+    const renderVisibleContent = (contentToRender: string) => (
+      <span className={`${styles.truncate}__text`}>{contentToRender}</span>
+    );
+    if (!isTruncated) {
+      return renderVisibleContent(content);
+    }
+
+    const omissionElement = (
+      <span className={`${styles.truncate}__omission`} aria-hidden="true">
+        {omissionContent}
+      </span>
+    );
+    const renderVisuallyHiddenContent = (contentToHide: string) => (
+      <span className="pf-v6-screen-reader">{contentToHide}</span>
+    );
+
+    if (position === TruncatePosition.start) {
+      return (
+        <>
+          {renderVisuallyHiddenContent(content.slice(0, maxCharsDisplayed * -1))}
+          {omissionElement}
+          {renderVisibleContent(content.slice(maxCharsDisplayed * -1))}
+        </>
+      );
+    }
+    if (position === TruncatePosition.end) {
+      return (
+        <>
+          {renderVisibleContent(content.slice(0, maxCharsDisplayed))}
+          {omissionElement}
+          {renderVisuallyHiddenContent(content.slice(maxCharsDisplayed))}
+        </>
+      );
+    }
+
+    const trueMiddleStart = Math.floor(maxCharsDisplayed / 2);
+    const trueMiddleEnd = Math.ceil(maxCharsDisplayed / 2) * -1;
+    return (
+      <>
+        {renderVisibleContent(content.slice(0, trueMiddleStart))}
+        {omissionElement}
+        {renderVisuallyHiddenContent(content.slice(trueMiddleStart, trueMiddleEnd))}
+        {renderVisibleContent(content.slice(trueMiddleEnd))}
+      </>
+    );
+  };
+
+  const truncateBody = (
+    <span
+      ref={subParentRef}
+      className={css(styles.truncate, shouldRenderByMaxChars && styles.modifiers.fixed, className)}
+      {...props}
+    >
+      {!shouldRenderByMaxChars ? renderResizeObserverContent() : renderMaxDisplayContent()}
     </span>
   );
 

packages/react-core/src/components/Truncate/__tests__/Truncate.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, within } from '@testing-library/react';
 import { Truncate } from '../Truncate';
 import styles from '@patternfly/react-styles/css/components/Truncate/truncate';
 import '@testing-library/jest-dom';
@@ -24,7 +24,7 @@ test(`renders with class ${styles.truncate}`, () => {
 
   const test = screen.getByLabelText('test-id');
 
-  expect(test).toHaveClass(styles.truncate);
+  expect(test).toHaveClass(styles.truncate, { exact: true });
 });
 
 test('renders with custom class name passed via prop', () => {
@@ -148,3 +148,71 @@ test('renders with inherited element props spread to the component', () => {
 
   expect(screen.getByTestId('test-id')).toHaveAccessibleName('labelling-id');
 });
+
+describe('Truncation with maxCharsDisplayed', () => {
+  test(`Does not render with class ${styles.modifiers.fixed} when maxCharsDisplayed is 0`, () => {
+    render(<Truncate maxCharsDisplayed={0} data-testid="truncate-component" content="Test content" />);
+
+    expect(screen.getByTestId('truncate-component')).not.toHaveClass(styles.modifiers.fixed);
+  });
+
+  test(`Renders with class ${styles.modifiers.fixed} when maxCharsDisplayed is greater than 0`, () => {
+    render(<Truncate maxCharsDisplayed={1} data-testid="truncate-component" content="Test content" />);
+
+    expect(screen.getByTestId('truncate-component')).toHaveClass(styles.modifiers.fixed);
+  });
+
+  test('Renders with hidden truncated content at end by default when maxCharsDisplayed is passed', () => {
+    render(<Truncate content="Default end position content truncated" maxCharsDisplayed={6} />);
+
+    expect(screen.getByText('Defaul')).toHaveClass(`${styles.truncate}__text`, { exact: true });
+    expect(screen.getByText('t end position content truncated')).toHaveClass('pf-v6-screen-reader');
+  });
+
+  test('Renders with hidden truncated content at middle position when maxCharsDisplayed is passed and position="middle"', () => {
+    render(<Truncate position="middle" content="Middle position contents being truncated" maxCharsDisplayed={10} />);
+
+    expect(screen.getByText('Middl')).toHaveClass(`${styles.truncate}__text`, { exact: true });
+    expect(screen.getByText('e position contents being trun')).toHaveClass('pf-v6-screen-reader');
+    expect(screen.getByText('cated')).toHaveClass(`${styles.truncate}__text`, { exact: true });
+  });
+
+  test('Renders with hidden truncated content at start when maxCharsDisplayed is passed and position="start"', () => {
+    render(<Truncate position="start" content="Start position content truncated" maxCharsDisplayed={6} />);
+
+    expect(screen.getByText('Start position content tru')).toHaveClass('pf-v6-screen-reader');
+    expect(screen.getByText('ncated')).toHaveClass(`${styles.truncate}__text`, { exact: true });
+  });
+
+  test('Renders full content when maxCharsDisplayed exceeds the length of the content', () => {
+    render(<Truncate content="This full content is rendered" maxCharsDisplayed={90} />);
+
+    expect(screen.getByText('This full content is rendered')).toHaveClass(`${styles.truncate}__text`, { exact: true });
+  });
+
+  test('Renders ellipsis as omission content by default', () => {
+    render(<Truncate content="Test truncation content" maxCharsDisplayed={5} />);
+
+    expect(screen.getByText('\u2026')).toHaveClass(`${styles.truncate}__omission`, { exact: true });
+    expect(screen.getByText('\u2026')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  test('Renders custom omission content when omissionContent is passed', () => {
+    render(<Truncate omissionContent="---" content="Test truncation content" maxCharsDisplayed={5} />);
+
+    expect(screen.getByText('---')).toHaveClass(`${styles.truncate}__omission`, { exact: true });
+    expect(screen.getByText('---')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  test('Does not render omission content when maxCharsDisplayed exceeds the length of the content ', () => {
+    render(<Truncate content="Test truncation content" maxCharsDisplayed={99} />);
+
+    expect(screen.queryByText('\u2026')).not.toBeInTheDocument();
+  });
+
+  test('Matches snapshot with default position', () => {
+    const { asFragment } = render(<Truncate content="Test truncation content" maxCharsDisplayed={3} />);
+
+    expect(asFragment()).toMatchSnapshot();
+  });
+});

packages/react-core/src/components/Truncate/__tests__/__snapshots__/Truncate.test.tsx.snap

@@ -1,5 +1,42 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`Truncation with maxCharsDisplayed Matches snapshot with default position 1`] = `
+<DocumentFragment>
+  <div
+    data-testid="Tooltip-mock"
+  >
+    <div
+      data-testid="Tooltip-mock-content-container"
+    >
+      Test Test truncation content
+    </div>
+    <p>
+      position: top
+    </p>
+    <span
+      class="pf-v6-c-truncate pf-m-fixed"
+    >
+      <span
+        class="pf-v6-c-truncate__text"
+      >
+        Tes
+      </span>
+      <span
+        aria-hidden="true"
+        class="pf-v6-c-truncate__omission"
+      >
+        …
+      </span>
+      <span
+        class="pf-v6-screen-reader"
+      >
+        t truncation content
+      </span>
+    </span>
+  </div>
+</DocumentFragment>
+`;
+
 exports[`renders default truncation 1`] = `
 <DocumentFragment>
   <div

packages/react-core/src/components/Truncate/examples/Truncate.md

@@ -9,50 +9,46 @@ import './TruncateExamples.css';
 
 ## Examples
 
+The default behavior of the `Truncate` component is to truncate based on whether the content can fit within the width of its parent container, and to prevent text from wrapping. The following examples that use this default behavior render the `<Truncate>` component inside a resizable container, allowing you to see how the parent container width affects the truncation.
+
 ### Default
-```js
-import { Truncate } from '@patternfly/react-core';
-
-<div className="truncate-example-resize">
-  <Truncate
-    content={'Vestibulum interdum risus et enim faucibus, sit amet molestie est accumsan.'}
-  />
-</div>
+
+By default content will be truncated at its end when it cannot fit entirely inside its parent container.
+
+```ts file="./TruncateDefault.tsx"
+
 ```
 
 ### Middle
-```js
-import { Truncate } from '@patternfly/react-core';
-
-<div className="truncate-example-resize">
-  <Truncate
-    content={'redhat_logo_black_and_white_reversed_simple_with_fedora_container.zip'}
-    trailingNumChars={10}
-    position={'middle'}
-  />
-</div>
+
+When passing a `position` property with a value of "middle", the position of the truncation will change based on the parent container's width and the amount of `trailingNumChars` passed in. The `trailingNumChars` will always be displayed, while the rest of the content will be truncated based on the parent container width.
+
+```ts file="./TruncateMiddle.tsx"
+
 ```
 
 ### Start
-```js
-import { Truncate } from '@patternfly/react-core';
-
-<div className="truncate-example-resize">
-  <Truncate
-    content={'Vestibulum interdum risus et enim faucibus, sit amet molestie est accumsan.'}
-    position={'start'}
-  />
-</div>
+
+You can truncate content at its start by passing the `position` property with a value of "start". This can be useful if you have several strings to truncate that have similar text at the start, but unique text at the end that you want to have visible.
+
+```ts file="./TruncateStart.tsx"
+
 ```
 
-### Default with tooltip at the bottom
-```js
-import { Truncate } from '@patternfly/react-core';
+### With custom tooltip position
+
+You can customize the position of the `<Tooltip>` that is rendered by passing in the `tooltipPosition` property. The following example overrides the default "top" position with a "bottom" position.
+
+```ts file="./TruncateCustomTooltipPosition.tsx"
+
+```
+
+### Based on max characters
+
+Rather than observing container width, you can have truncation be based on a maximum amount of characters that should always be displayed via the `maxCharsDisplayed` property. While the content's parent container width will not have an affect on whether truncation occurs, it will affect whether the content wraps. This property must be set to a value larger than `0`, otherwise the component will fall back to observing container width.
+
+Truncating based on a maximum amount of characters will truncate the content at the end by default. When the `position` property is set to "middle", the truncation will split the content as evenly as possible, providing a more "true middle" truncation.
+
+```ts file="./TruncateMaxChars.tsx"
 
-<div className="truncate-example-resize">
-  <Truncate
-    content={'Vestibulum interdum risus et enim faucibus, sit amet molestie est accumsan.'}
-    tooltipPosition={'bottom'}
-  />
-</div>
 ```