Skip to content

Commit 8516c0b

Browse files
RajdeepcRajdeepc
authored
Merge 1fa7876 into 6c97dd7 
2 parents 6c97dd7 + 1fa7876 commit 8516c0b

File tree

2 files changed

+211
-18
lines changed

2 files changed

+211
-18
lines changed

‎tools/bundle/elements.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,4 +98,5 @@ import '@spectrum-web-components/tooltip/sp-tooltip.js';
9898
import '@spectrum-web-components/top-nav/sp-top-nav.js';
9999
import '@spectrum-web-components/top-nav/sp-top-nav-item.js';
100100
import '@spectrum-web-components/tray/sp-tray.js';
101+
import '@spectrum-web-components/truncated/sp-truncated.js';
101102
import '@spectrum-web-components/underlay/sp-underlay.js';

‎tools/truncated/README.md‎

Lines changed: 210 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,241 @@
1-
## Description
1+
## Overview
22

3-
`<sp-truncated>` renders a line of text, truncating it if it overflows its container. When overflowing, a tooltip is automatically created
4-
that renders the entire non-truncated content.
3+
`<sp-truncated>` 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.
54

6-
It is used like a `<span>` to contain potentially-long strings that are important for users to see, even when in small containers, like full
7-
names and email addresses.
5+
This component is designed like a `<span>` 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.
86

97
### Usage
108

119
[![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)
1210
[![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)
1311

14-
```
12+
```bash
1513
yarn add @spectrum-web-components/truncated
1614
```
1715

18-
Import the side effectful registration of `<sp-truncated>` via:
16+
Import the side effectful registration of `<sp-truncated>` as follows:
1917

20-
```
18+
```typescript
2119
import '@spectrum-web-components/truncated/sp-truncated.js';
2220
```
2321

2422
When looking to leverage the `Truncated` base class as a type and/or for extension purposes, do so via:
2523

26-
```
24+
```typescript
2725
import { Truncated } from '@spectrum-web-components/truncated';
2826
```
2927

30-
## Example
28+
### Anatomy
29+
30+
The basic structure of the truncated component:
3131

3232
```html
3333
<sp-truncated>
3434
This will truncate into a tooltip if there isn't enough space for it.
3535
</sp-truncated>
3636
```
3737

38-
### With specific overflow content
38+
### Examples
39+
40+
#### Basic usage
41+
42+
By default, `<sp-truncated>` 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.
43+
44+
```html demo
45+
<div
46+
style="width: 200px; border: 1px solid var(--spectrum-gray-300); padding: 8px; overflow: hidden; resize: both;"
47+
>
48+
<sp-truncated>
49+
This is a very long sentence that should be truncated when there isn't
50+
enough space to display it fully.
51+
</sp-truncated>
52+
</div>
53+
```
54+
55+
#### With mixed content
56+
57+
`<sp-truncated>` supports mixed content including text formatting and inline elements:
58+
59+
```html demo
60+
<div
61+
style="width: 250px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
62+
>
63+
<sp-truncated>
64+
This is a
65+
<strong>very long</strong>
66+
sentence with
67+
<em>formatted text</em>
68+
that should be truncated.
69+
</sp-truncated>
70+
</div>
71+
```
72+
73+
#### Long words without spaces
74+
75+
The component handles long words or strings without spaces appropriately:
76+
77+
```html demo
78+
<div
79+
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
80+
>
81+
<sp-truncated>
82+
ThisIsAVeryLongWordWithoutAnySpacesThatShouldBeTruncated
83+
</sp-truncated>
84+
</div>
85+
```
86+
87+
#### Custom overflow content
88+
89+
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:
90+
91+
```html demo
92+
<div
93+
style="width: 200px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
94+
>
95+
<sp-truncated>
96+
This is the inline content that gets truncated
97+
<span slot="overflow">
98+
This custom overflow content will appear in the tooltip with any
99+
additional information or formatting you need.
100+
</span>
101+
</sp-truncated>
102+
</div>
103+
```
104+
105+
#### Tooltip placement
106+
107+
You can control the placement of the tooltip using the `placement` attribute. The default placement is `top-start`.
108+
109+
```html demo
110+
<div style="display: flex; gap: 16px; flex-wrap: wrap;">
111+
<div
112+
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
113+
>
114+
<sp-truncated placement="top">
115+
Top placement for this truncated text
116+
</sp-truncated>
117+
</div>
118+
<div
119+
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
120+
>
121+
<sp-truncated placement="bottom">
122+
Bottom placement for this truncated text
123+
</sp-truncated>
124+
</div>
125+
<div
126+
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
127+
>
128+
<sp-truncated placement="left">
129+
Left placement for this truncated text
130+
</sp-truncated>
131+
</div>
132+
<div
133+
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
134+
>
135+
<sp-truncated placement="right">
136+
Right placement for this truncated text
137+
</sp-truncated>
138+
</div>
139+
</div>
140+
```
141+
142+
#### Custom success message
143+
144+
When text is copied to the clipboard, a custom success message can be displayed:
145+
146+
```html demo
147+
<div
148+
style="width: 200px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
149+
>
150+
<sp-truncated success-message="Email copied successfully!">
151+
user.name@example.com
152+
</sp-truncated>
153+
</div>
154+
```
155+
156+
### Usage in patterns
39157

40-
By default, tooltip text will be extracted from overflowing content. To provide your own overflow content, slot it into "overflow":
158+
#### With field labels
159+
160+
`<sp-truncated>` is commonly used with form fields to display long values that might overflow:
161+
162+
```html demo
163+
<sp-field-label for="email-field">Email address</sp-field-label>
164+
<div
165+
style="width: 250px; border: 1px solid var(--spectrum-gray-300); padding: 8px; border-radius: 4px;"
166+
>
167+
<sp-truncated>very.long.email.address@subdomain.example.com</sp-truncated>
168+
</div>
169+
```
170+
171+
#### In popovers
172+
173+
For use within overlays, ensure the popover has appropriate width constraints:
41174

42175
```html
43-
<sp-truncated placement="right">
44-
This is the inline content
45-
<span slot="overflow">
46-
And this overflow content will go into the tooltip, on the right
47-
</span>
48-
</sp-truncated>
176+
<sp-button id="user-trigger">User Info</sp-button>
177+
<sp-overlay trigger="user-trigger@click" placement="bottom">
178+
<sp-popover style="width: 250px;">
179+
<div style="padding: 16px;">
180+
<sp-field-label>Username</sp-field-label>
181+
<div style="width: 200px;">
182+
<sp-truncated>
183+
very.long.username.that.exceeds.the.available.width
184+
</sp-truncated>
185+
</div>
186+
</div>
187+
</sp-popover>
188+
</sp-overlay>
49189
```
190+
191+
### Accessibility
192+
193+
#### Keyboard navigation
194+
195+
The `<sp-truncated>` 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:
196+
197+
- The tooltip appears on hover and focus
198+
- The tooltip is dismissed when the user moves away or presses the Escape key
199+
200+
#### Click to copy
201+
202+
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.
203+
204+
**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.
205+
206+
#### Screen readers
207+
208+
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.
209+
210+
For custom overflow content, ensure that the slotted content is semantically meaningful and properly structured for screen readers.
211+
212+
### Content guidelines
213+
214+
#### Do
215+
216+
- Use `<sp-truncated>` for non-critical text that users may need to see in full but can afford to be shortened in compact views
217+
- Provide meaningful text that makes sense even when truncated
218+
- Use for email addresses, file paths, long names, and similar data
219+
- Test with actual content to ensure the truncation point makes sense
220+
221+
#### Don't
222+
223+
- Don't use for critical actions or navigation labels that must always be visible
224+
- Don't use for very short text that is unlikely to overflow
225+
- Don't truncate text where the beginning or end context is essential for comprehension
226+
- Don't rely solely on truncated text for important information without providing alternative access
227+
228+
### Additional resources
229+
230+
For more information on accessibility best practices for truncated text, refer to:
231+
232+
- [Spectrum Design System - Text Overflow Guidelines](https://spectrum.adobe.com/page/text-field/#Text-overflow)
233+
- [WCAG 2.1 Success Criterion 1.4.8 - Visual Presentation](https://www.w3.org/WAI/WCAG21/Understanding/visual-presentation.html)
234+
235+
### Design reference
236+
237+
For design specifications and usage guidelines, refer to the Spectrum Design System documentation:
238+
239+
- [Spectrum Text Field Component - Text Overflow](https://spectrum.adobe.com/page/text-field/#Text-overflow)
240+
241+
**Note:** While `<sp-truncated>` is not a standalone component in the official Spectrum Design System, it implements common text truncation patterns used throughout Spectrum components.

0 commit comments

Comments
 (0)