Merge branch 'main' into mayank/displaycontents-voiceover

apps/website/src/content/docs/middletexttruncation.mdx

@@ -0,0 +1,44 @@
+---
+title: MiddleTextTruncation
+description: A utility component for truncating long texts in the middle.
+thumbnail: #TODO
+group: utilities
+---
+
+<p>{frontmatter.description}</p>
+
+## Usage
+
+When displaying texts with constrains on its width, the `MiddleTextTruncation` component can help by truncating long texts in the middle with an ellipsis (`"…"`). This ensures that the beginning and the end of the text remain visible.
+
+<LiveExample src='MiddleTextTruncation.main.jsx' truncated={false}>
+  <AllExamples.MiddleTextTruncationMainExample client:load />
+</LiveExample>
+
+For more examples, see [truncation in Select](/docs/select#truncation).
+
+### Number of end characters
+
+By default, six characters are left visible at the end of the truncated text. This ensures that important suffixes, such as file extensions or identifiers, remain visible. This number can be modified through the `endCharsCount` prop to suit user's specific needs.
+
+<LiveExample src='MiddleTextTruncation.endCharsCount.jsx'>
+  <AllExamples.MiddleTextTruncationEndCharsCountExample client:load />
+</LiveExample>
+
+### Customization
+
+For further control over the rendering of the content, the `textRenderer` prop allows users to provide a custom rendering function. This function takes `originalText` and `truncatedText` as parameters and returns a `ReactNode`.
+
+<LiveExample src='MiddleTextTruncation.customizeTruncation.jsx'>
+  <AllExamples.MiddleTextTruncationCustomizationExample client:load />
+</LiveExample>
+
+## Accessibility
+
+This component only truncates the content visually but leaves the full content in the accessibility tree. That way, users using assistive technologies can still have access to the full content. This is also consistent with the browser's default `text-overflow` behavior.
+
+However, this behavior may cause some inconvenience for screen-reader users, as the accessible text can become overly verbose. Thus, we recommend taking this into consideration when planning the UX.
+
+## Props
+
+<PropsTable path='@itwin/itwinui-react/esm/utils/components/MiddleTextTruncation.d.ts' />

examples/MiddleTextTruncation.customizeTruncation.css

@@ -0,0 +1,3 @@
+.demo-container {
+  width: 300px;
+}

examples/MiddleTextTruncation.customizeTruncation.jsx

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { MiddleTextTruncation } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <MiddleTextTruncation
+      className='demo-container'
+      text='MyTitleWithAReallyLongNameThatWillBeTruncatedWithCustomizedStylingBecauseItIsReallyThatLongSoHardToBelieve'
+      textRenderer={(truncatedText) => <b>{truncatedText}</b>}
+    />
+  );
+};

examples/MiddleTextTruncation.endCharsCount.css

@@ -0,0 +1,3 @@
+.demo-container {
+  width: 300px;
+}

examples/MiddleTextTruncation.endCharsCount.jsx

@@ -0,0 +1,18 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { MiddleTextTruncation } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <MiddleTextTruncation
+      className='demo-container'
+      endCharsCount={15}
+      text={
+        'ThisIsMyVeryLongFileNameWithImportantExtension_FinalVersion_V2.docx'
+      }
+    />
+  );
+};

examples/MiddleTextTruncation.main.css

@@ -0,0 +1,3 @@
+.demo-container {
+  width: 300px;
+}

examples/MiddleTextTruncation.main.jsx

@@ -0,0 +1,15 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { MiddleTextTruncation } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <MiddleTextTruncation
+      className='demo-container'
+      text='MyTitleWithAReallyLongNameThatWillBeTruncatedBecauseItIsReallyThatLongSoHardToBelieve'
+    />
+  );
+};

examples/index.tsx

@@ -807,6 +807,26 @@ export { ListComboboxExample };
 
 // ----------------------------------------------------------------------------
 
+import { default as MiddleTextTruncationMainExampleRaw } from './MiddleTextTruncation.main';
+const MiddleTextTruncationMainExample = withThemeProvider(
+  MiddleTextTruncationMainExampleRaw,
+);
+export { MiddleTextTruncationMainExample };
+
+import { default as MiddleTextTruncationEndCharsCountExampleRaw } from './MiddleTextTruncation.endCharsCount';
+const MiddleTextTruncationEndCharsCountExample = withThemeProvider(
+  MiddleTextTruncationEndCharsCountExampleRaw,
+);
+export { MiddleTextTruncationEndCharsCountExample };
+
+import { default as MiddleTextTruncationCustomizationExampleRaw } from './MiddleTextTruncation.customizeTruncation';
+const MiddleTextTruncationCustomizationExample = withThemeProvider(
+  MiddleTextTruncationCustomizationExampleRaw,
+);
+export { MiddleTextTruncationCustomizationExample };
+
+// ----------------------------------------------------------------------------
+
 import { default as NonIdealStateBadgatewayExampleRaw } from './NonIdealState.badgateway';
 const NonIdealStateBadgatewayExample = withThemeProvider(
   NonIdealStateBadgatewayExampleRaw,