From 78be3f6573cfacb6d949ca323276c3bfeb5a896f Mon Sep 17 00:00:00 2001 From: Rajdeep Chandra Date: Tue, 28 Oct 2025 18:26:51 +0530 Subject: [PATCH 1/4] docs: updated sp-truncated pattern --- tools/bundle/elements.ts | 1 + tools/truncated/README.md | 333 +++++++++++++++++++++++++++++++++++--- 2 files changed, 316 insertions(+), 18 deletions(-) diff --git a/tools/bundle/elements.ts b/tools/bundle/elements.ts index 0eafb05ce15..68f6de5e6ff 100644 --- a/tools/bundle/elements.ts +++ b/tools/bundle/elements.ts @@ -98,4 +98,5 @@ import '@spectrum-web-components/tooltip/sp-tooltip.js'; import '@spectrum-web-components/top-nav/sp-top-nav.js'; import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; import '@spectrum-web-components/tray/sp-tray.js'; +import '@spectrum-web-components/truncated/sp-truncated.js'; import '@spectrum-web-components/underlay/sp-underlay.js'; diff --git a/tools/truncated/README.md b/tools/truncated/README.md index 1725a244b66..6396f58796d 100644 --- a/tools/truncated/README.md +++ b/tools/truncated/README.md @@ -1,33 +1,33 @@ -## Description +## Overview -`` renders a line of text, truncating it if it overflows its container. When overflowing, a tooltip is automatically created -that renders the entire non-truncated content. +`` renders a line of text, truncating it if it overflows its container. When overflowing, a tooltip is automatically created that renders the entire non-truncated content. Additionally, clicking on overflowing text copies the full content to the clipboard and displays a success message. -It is used like a `` to contain potentially-long strings that are important for users to see, even when in small containers, like full -names and email addresses. +This component is designed like a `` to contain potentially-long strings that are important for users to see, even when in small containers, such as full names, email addresses, file paths, and other text data that may exceed the available space. ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/truncated?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/truncated) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/truncated?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/truncated) -``` +```bash yarn add @spectrum-web-components/truncated ``` -Import the side effectful registration of `` via: +Import the side effectful registration of `` as follows: -``` +```typescript import '@spectrum-web-components/truncated/sp-truncated.js'; ``` When looking to leverage the `Truncated` base class as a type and/or for extension purposes, do so via: -``` +```typescript import { Truncated } from '@spectrum-web-components/truncated'; ``` -## Example +### Anatomy + +The basic structure of the truncated component: ```html @@ -35,15 +35,312 @@ import { Truncated } from '@spectrum-web-components/truncated'; ``` -### With specific overflow content +### Examples + +#### Basic usage + +By default, `` will automatically detect when text overflows its container and display a tooltip with the full content on hover. When the truncated text is clicked, it copies the full text to the clipboard. + +```html demo +
+ + This is a very long sentence that should be truncated when there isn't + enough space to display it fully. + +
+``` + +#### With mixed content + +`` supports mixed content including text formatting and inline elements: + +```html demo +
+ + This is a + very long + sentence with + formatted text + that should be truncated. + +
+``` + +#### Long words without spaces + +The component handles long words or strings without spaces appropriately: + +```html demo +
+ + ThisIsAVeryLongWordWithoutAnySpacesThatShouldBeTruncated + +
+``` + +#### Custom overflow content -By default, tooltip text will be extracted from overflowing content. To provide your own overflow content, slot it into "overflow": +By default, tooltip text will be extracted from the overflowing content. To provide your own custom overflow content for the tooltip, slot it into the `overflow` slot: + +```html demo +
+ + This is the inline content that gets truncated + + This custom overflow content will appear in the tooltip with any + additional information or formatting you need. + + +
+``` + +#### Tooltip placement + +You can control the placement of the tooltip using the `placement` attribute. The default placement is `top-start`. + +```html demo +
+
+ + Top placement for this truncated text + +
+
+ + Bottom placement for this truncated text + +
+
+ + Left placement for this truncated text + +
+
+ + Right placement for this truncated text + +
+
+``` + +#### Custom success message + +When text is copied to the clipboard, a custom success message can be displayed: + +```html demo +
+ + user.name@example.com + +
+``` + +### Usage in patterns + +#### With field labels + +`` is commonly used with form fields to display long values that might overflow: + +```html demo +Email address +
+ very.long.email.address@subdomain.example.com +
+``` + +#### In tables + +Display truncated content in table cells to maintain consistent row heights: + +```html demo + + + Name + Email + + + + + John Smith + + + + john.smith@verylongdomainname.example.com + + + + + + Jane Doe + + + + jane.doe@anotherverylongdomainname.example.com + + + + + +``` + +#### With breadcrumbs + +Truncate long breadcrumb items to maintain navigation clarity: + +```html demo + + Home + Documents + + + Very Long Project Name That Needs Truncation + + + + Another Very Long Folder Name + + +``` + +#### In popovers + +For use within overlays, ensure the popover has appropriate width constraints: ```html - - This is the inline content - - And this overflow content will go into the tooltip, on the right - - +User Info + + +
+ Username +
+ + very.long.username.that.exceeds.the.available.width + +
+
+ + ``` + +### Accessibility + +#### Keyboard navigation + +The `` component does not receive keyboard focus by itself, as it functions as inline content. However, the tooltip that appears on hover follows standard Spectrum tooltip accessibility patterns: + +- The tooltip appears on hover and focus +- The tooltip is dismissed when the user moves away or presses the Escape key + +#### Click to copy + +When truncated text is clicked, the full text content is copied to the clipboard. This interaction provides a quick way for users to access the complete content. + +**Important accessibility note:** The click handler on the truncated text does not include keyboard event handlers (`/* eslint-disable lit-a11y/click-events-have-key-events */`). This is a known limitation. Users who rely on keyboard navigation will need to use the tooltip hover interaction to view the full content, but cannot copy it via keyboard alone. + +#### Screen readers + +Screen readers will announce the visible truncated text. When the tooltip appears on hover, screen readers will announce the full content if it differs from the visible text. + +For custom overflow content, ensure that the slotted content is semantically meaningful and properly structured for screen readers. + +### Content guidelines + +#### Do + +- Use `` for non-critical text that users may need to see in full but can afford to be shortened in compact views +- Provide meaningful text that makes sense even when truncated +- Use for email addresses, file paths, long names, and similar data +- Test with actual content to ensure the truncation point makes sense + +#### Don't + +- Don't use for critical actions or navigation labels that must always be visible +- Don't use for very short text that is unlikely to overflow +- Don't truncate text where the beginning or end context is essential for comprehension +- Don't rely solely on truncated text for important information without providing alternative access + +### Additional resources + +For more information on accessibility best practices for truncated text, refer to: + +- [Spectrum Design System - Text Overflow Guidelines](https://spectrum.adobe.com/page/text-field/#Text-overflow) +- [WCAG 2.1 Success Criterion 1.4.8 - Visual Presentation](https://www.w3.org/WAI/WCAG21/Understanding/visual-presentation.html) + +### Behaviors + +#### Overflow detection + +The component uses a `ResizeObserver` to automatically detect when content overflows its container. When overflow is detected: + +1. The visible text is truncated with an ellipsis (`…`) +2. A tooltip is created containing the full content +3. The tooltip appears on hover +4. Clicking the truncated text copies the full content to the clipboard + +When content does not overflow, no tooltip is created and clicking has no effect. + +#### Copy to clipboard + +When truncated (overflowing) text is clicked: + +1. The full text content is copied to the clipboard using the Clipboard API (`navigator.clipboard.writeText()`) +2. The tooltip immediately displays the success message (default: "Copied to clipboard") +3. After 6 seconds, the tooltip reverts to showing the full text content + +#### Content observation + +The component uses a `MutationObserver` to watch for changes to the default slot content. When content changes, the component automatically updates the tooltip text to reflect the new content. + +This observation is disabled when custom overflow content is provided via the `overflow` slot, as the custom content takes precedence. + +### Technical notes + +#### Browser compatibility + +The component requires support for: + +- **Clipboard API**: Modern browsers support `navigator.clipboard.writeText()` +- **ResizeObserver**: Widely supported in modern browsers +- **MutationObserver**: Standard in all modern browsers + +For older browsers that don't support the Clipboard API, the copy functionality will not work, but the tooltip will still display correctly. + +#### Performance considerations + +The component is optimized for performance: + +- ResizeObserver efficiently detects layout changes without constant polling +- MutationObserver is only active when using automatic overflow content +- The component avoids duplicating DOM content by using textContent for tooltips + +#### Safari rendering note + +The overflow detection adds 1px to the comparison calculation to account for Safari's sub-pixel rounding differences. This ensures consistent behavior across browsers. + +### Design reference + +For design specifications and usage guidelines, refer to the Spectrum Design System documentation: + +- [Spectrum Text Field Component - Text Overflow](https://spectrum.adobe.com/page/text-field/#Text-overflow) + +**Note:** While `` is not a standalone component in the official Spectrum Design System, it implements common text truncation patterns used throughout Spectrum components. From 69e086b3a9fea7a2b69ebf66abcaae5e541c0a90 Mon Sep 17 00:00:00 2001 From: Rajdeep Chandra Date: Thu, 30 Oct 2025 17:19:40 +0530 Subject: [PATCH 2/4] chore: updated guidelines text --- tools/truncated/README.md | 105 -------------------------------------- 1 file changed, 105 deletions(-) diff --git a/tools/truncated/README.md b/tools/truncated/README.md index 6396f58796d..5cb46cfc452 100644 --- a/tools/truncated/README.md +++ b/tools/truncated/README.md @@ -168,60 +168,6 @@ When text is copied to the clipboard, a custom success message can be displayed: ``` -#### In tables - -Display truncated content in table cells to maintain consistent row heights: - -```html demo - - - Name - Email - - - - - John Smith - - - - john.smith@verylongdomainname.example.com - - - - - - Jane Doe - - - - jane.doe@anotherverylongdomainname.example.com - - - - - -``` - -#### With breadcrumbs - -Truncate long breadcrumb items to maintain navigation clarity: - -```html demo - - Home - Documents - - - Very Long Project Name That Needs Truncation - - - - Another Very Long Folder Name - - -``` - #### In popovers For use within overlays, ensure the popover has appropriate width constraints: @@ -286,57 +232,6 @@ For more information on accessibility best practices for truncated text, refer t - [Spectrum Design System - Text Overflow Guidelines](https://spectrum.adobe.com/page/text-field/#Text-overflow) - [WCAG 2.1 Success Criterion 1.4.8 - Visual Presentation](https://www.w3.org/WAI/WCAG21/Understanding/visual-presentation.html) -### Behaviors - -#### Overflow detection - -The component uses a `ResizeObserver` to automatically detect when content overflows its container. When overflow is detected: - -1. The visible text is truncated with an ellipsis (`…`) -2. A tooltip is created containing the full content -3. The tooltip appears on hover -4. Clicking the truncated text copies the full content to the clipboard - -When content does not overflow, no tooltip is created and clicking has no effect. - -#### Copy to clipboard - -When truncated (overflowing) text is clicked: - -1. The full text content is copied to the clipboard using the Clipboard API (`navigator.clipboard.writeText()`) -2. The tooltip immediately displays the success message (default: "Copied to clipboard") -3. After 6 seconds, the tooltip reverts to showing the full text content - -#### Content observation - -The component uses a `MutationObserver` to watch for changes to the default slot content. When content changes, the component automatically updates the tooltip text to reflect the new content. - -This observation is disabled when custom overflow content is provided via the `overflow` slot, as the custom content takes precedence. - -### Technical notes - -#### Browser compatibility - -The component requires support for: - -- **Clipboard API**: Modern browsers support `navigator.clipboard.writeText()` -- **ResizeObserver**: Widely supported in modern browsers -- **MutationObserver**: Standard in all modern browsers - -For older browsers that don't support the Clipboard API, the copy functionality will not work, but the tooltip will still display correctly. - -#### Performance considerations - -The component is optimized for performance: - -- ResizeObserver efficiently detects layout changes without constant polling -- MutationObserver is only active when using automatic overflow content -- The component avoids duplicating DOM content by using textContent for tooltips - -#### Safari rendering note - -The overflow detection adds 1px to the comparison calculation to account for Safari's sub-pixel rounding differences. This ensures consistent behavior across browsers. - ### Design reference For design specifications and usage guidelines, refer to the Spectrum Design System documentation: From 096681da03c4d3c06dd411b08885650828e1ce9b Mon Sep 17 00:00:00 2001 From: Rajdeep Chandra Date: Mon, 10 Nov 2025 12:33:07 +0530 Subject: [PATCH 3/4] chore: updated text to show custom message --- 1st-gen/tools/truncated/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1st-gen/tools/truncated/README.md b/1st-gen/tools/truncated/README.md index 5cb46cfc452..980481e516f 100644 --- a/1st-gen/tools/truncated/README.md +++ b/1st-gen/tools/truncated/README.md @@ -148,7 +148,7 @@ When text is copied to the clipboard, a custom success message can be displayed: style="width: 200px; border: 1px solid var(--spectrum-gray-300); padding: 8px;" > - user.name@example.com + iamaverylongusernametoshowthecustom.message.text@example.com ``` From 018f3a8872f2a641e46b2387fae2a2b4938035b0 Mon Sep 17 00:00:00 2001 From: Rajdeep Chandra Date: Wed, 26 Nov 2025 16:19:24 +0530 Subject: [PATCH 4/4] chore: updated patterns in a11y screen readers and field element support for interactivity --- 1st-gen/tools/truncated/README.md | 33 ++++++++++++++++++------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/1st-gen/tools/truncated/README.md b/1st-gen/tools/truncated/README.md index 980481e516f..6066509fd7c 100644 --- a/1st-gen/tools/truncated/README.md +++ b/1st-gen/tools/truncated/README.md @@ -155,16 +155,24 @@ When text is copied to the clipboard, a custom success message can be displayed: ### Usage in patterns -#### With field labels +#### Displaying form values -`` is commonly used with form fields to display long values that might overflow: +`` is commonly used to display long values that might overflow, such as saved form data: ```html demo -Email address -
- very.long.email.address@subdomain.example.com +
+

+ Email address +

+
+ + very.long.email.address@subdomain.example.com + +
``` @@ -192,20 +200,17 @@ For use within overlays, ensure the popover has appropriate width constraints: #### Keyboard navigation -The `` component does not receive keyboard focus by itself, as it functions as inline content. However, the tooltip that appears on hover follows standard Spectrum tooltip accessibility patterns: +The `` component does not receive keyboard focus by itself, as it functions as inline content. The tooltip only appears on mouse hover, not on keyboard focus. This means keyboard-only users (who are not using screen readers) cannot access the tooltip to view the full content. -- The tooltip appears on hover and focus -- The tooltip is dismissed when the user moves away or presses the Escape key +**Important accessibility limitation:** Since `` does not receive keyboard focus, keyboard-only users cannot trigger the tooltip hover interaction. Additionally, the click handler does not include keyboard event handlers (`/* eslint-disable lit-a11y/click-events-have-key-events */`), so keyboard users cannot copy the full content via keyboard alone. This is a known accessibility limitation. #### Click to copy -When truncated text is clicked, the full text content is copied to the clipboard. This interaction provides a quick way for users to access the complete content. - -**Important accessibility note:** The click handler on the truncated text does not include keyboard event handlers (`/* eslint-disable lit-a11y/click-events-have-key-events */`). This is a known limitation. Users who rely on keyboard navigation will need to use the tooltip hover interaction to view the full content, but cannot copy it via keyboard alone. +When truncated text is clicked, the full text content is copied to the clipboard. This interaction provides a quick way for mouse users to access the complete content. Keyboard users cannot trigger this interaction. #### Screen readers -Screen readers will announce the visible truncated text. When the tooltip appears on hover, screen readers will announce the full content if it differs from the visible text. +Screen readers will announce the full text content directly from the DOM, so screen reader users do not need the tooltip to access the complete content. Note that screen reader users are often but not always keyboard users, and keyboard-only users who are not using screen readers will not be able to access the tooltip content. For custom overflow content, ensure that the slotted content is semantically meaningful and properly structured for screen readers.