Skip to content

Commit 9cde46b

Browse files
cdransfrise-erpelding
cdransf
authored and
rise-erpelding
committed
chore(docs): barebones analysis for Field label, Help text, Picker button, In-field button and In-field progress circle (#5738)
* chore(docs): barebones analysis for SWC-1218 * chore(docs): address feedback * chore(docs): address feedback
1 parent d69fdff commit 9cde46b

File tree

5 files changed

+987
-0
lines changed

5 files changed

+987
-0
lines changed

‎migration-roadmap/field-label.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Field label migration roadmap
2+
3+
## Component specifications
4+
5+
### CSS
6+
7+
<details>
8+
<summary>CSS selectors</summary>
9+
10+
- `.spectrum-FieldLabel`
11+
- `.spectrum-FieldLabel--left`
12+
- `.spectrum-FieldLabel--right`
13+
- `.spectrum-FieldLabel--sizeL`
14+
- `.spectrum-FieldLabel--sizeS`
15+
- `.spectrum-FieldLabel--sizeXL`
16+
- `.spectrum-FieldLabel--staticBlack`
17+
- `.spectrum-FieldLabel--staticWhite`
18+
- `.spectrum-FieldLabel-requiredIcon`
19+
- `.spectrum-FieldLabel.is-disabled`
20+
- `.spectrum-FieldLabel:lang(ja)`
21+
- `.spectrum-FieldLabel:lang(ko)`
22+
- `.spectrum-FieldLabel:lang(zh)`
23+
24+
</details>
25+
26+
<details>
27+
<summary>Passthroughs</summary>
28+
29+
None found for this component.
30+
31+
</details>
32+
33+
<details>
34+
<summary>Modifiers</summary>
35+
36+
- `--mod-fieldlabel-asterisk-vertical-align`
37+
- `--mod-fieldlabel-bottom-to-text`
38+
- `--mod-fieldlabel-font-size`
39+
- `--mod-fieldlabel-font-weight`
40+
- `--mod-fieldlabel-line-height`
41+
- `--mod-fieldlabel-line-height-cjk`
42+
- `--mod-fieldlabel-min-height`
43+
- `--mod-fieldlabel-padding-inline`
44+
- `--mod-fieldlabel-side-margin-block-start`
45+
- `--mod-fieldlabel-side-padding-right`
46+
- `--mod-fieldlabel-text-to-asterisk`
47+
- `--mod-fieldlabel-top-to-text`
48+
49+
</details>
50+
51+
### SWC
52+
53+
<details>
54+
<summary>Attributes</summary>
55+
56+
- `disabled` (Boolean) - Whether the field label is disabled
57+
- `id` (String) - Unique identifier for the field label
58+
- `for` (String) - ID of the form control the label is associated with
59+
- `required` (Boolean) - Whether the field is required
60+
- `side-aligned` (String) - Alignment of the label: 'start' or 'end'
61+
62+
</details>
63+
64+
<details>
65+
<summary>Slots</summary>
66+
67+
- Default slot - Text content of the label
68+
69+
</details>
70+
71+
## Comparison
72+
73+
### DOM Structure changes
74+
75+
<details>
76+
<summary>Spectrum Web Components:</summary>
77+
78+
```html
79+
<label>
80+
<slot></slot>
81+
<sp-icon-asterisk100
82+
class="required-icon spectrum-UIIcon-Asterisk100"
83+
></sp-icon-asterisk100>
84+
</label>
85+
```
86+
87+
</details>
88+
89+
<details>
90+
<summary>Legacy (CSS main branch):</summary>
91+
92+
```html
93+
<label class="spectrum-FieldLabel spectrum-FieldLabel--sizeM">
94+
Label text
95+
<svg
96+
class="spectrum-FieldLabel-UIIcon spectrum-FieldLabel-requiredIcon"
97+
focusable="false"
98+
aria-hidden="true"
99+
>
100+
<path
101+
d="M10 2L13.09 8.26L20 9L14 14.74L15.18 22L10 18.77L4.82 22L6 14.74L0 9L6.91 8.26L10 2Z"
102+
></path>
103+
</svg>
104+
</label>
105+
```
106+
107+
</details>
108+
109+
<details>
110+
<summary>Spectrum 2 (CSS spectrum-two branch):</summary>
111+
112+
```html
113+
<label class="spectrum-FieldLabel spectrum-FieldLabel--sizeM">
114+
Label text&#8288;
115+
<svg
116+
class="spectrum-FieldLabel-UIIcon spectrum-FieldLabel-requiredIcon"
117+
focusable="false"
118+
aria-hidden="true"
119+
>
120+
<path
121+
d="M10 2L13.09 8.26L20 9L14 14.74L15.18 22L10 18.77L4.82 22L6 14.74L0 9L6.91 8.26L10 2Z"
122+
></path>
123+
</svg>
124+
</label>
125+
```
126+
127+
</details>
128+
129+
<details>
130+
<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>
131+
132+
### HTML Output Diff
133+
134+
```diff
135+
<label class="spectrum-FieldLabel spectrum-FieldLabel--sizeM">
136+
- Label text
137+
+ Label text&#8288;
138+
<svg
139+
class="spectrum-FieldLabel-UIIcon spectrum-FieldLabel-requiredIcon"
140+
focusable="false"
141+
aria-hidden="true"
142+
>
143+
<path
144+
d="M10 2L13.09 8.26L20 9L14 14.74L15.18 22L10 18.77L4.82 22L6 14.74L0 9L6.91 8.26L10 2Z"
145+
></path>
146+
</svg>
147+
</label>
148+
```
149+
150+
</details>
151+
152+
### Key Changes in HTML Structure
153+
154+
1. **Text processing enhancement**: Added `?.trim()` to remove whitespace from label text
155+
2. **Zero-width non-joiner**: Added `&#8288;` (zero-width non-joiner) between label text and required asterisk icon to prevent text wrapping issues in internationalized content
156+
3. **Static color support**: Added support for `--staticBlack` and `--staticWhite` variants through the `staticColor` parameter
157+
158+
</details>
159+
160+
### CSS => SWC mapping
161+
162+
| CSS selector | Attribute or slot | Status |
163+
| --------------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------- |
164+
| `.spectrum-FieldLabel` | `:host` | Implemented |
165+
| `.spectrum-FieldLabel--left` | `side-aligned="start"` | Implemented |
166+
| `.spectrum-FieldLabel--right` | `side-aligned="end"` | Implemented |
167+
| `.spectrum-FieldLabel--sizeL` | `size="l"` | Implemented |
168+
| `.spectrum-FieldLabel--sizeS` | `size="s"` | Implemented |
169+
| `.spectrum-FieldLabel--sizeXL` | `size="xl"` | Implemented |
170+
| `.spectrum-FieldLabel--staticBlack` | `static-color="black"` | Missing from WC (new for S2) |
171+
| `.spectrum-FieldLabel--staticWhite` | `static-color="white"` | Missing from WC (new for S2) |
172+
| `.spectrum-FieldLabel-requiredIcon` | Required icon element; `.required-icon` | Implemented |
173+
| `.spectrum-FieldLabel.is-disabled` | `disabled` attribute | Implemented |
174+
| `.spectrum-FieldLabel:lang(ja), .spectrum-FieldLabel:lang(ko), .spectrum-FieldLabel:lang(zh)` | Language-specific styling | Implemented |
175+
176+
## Summary of changes
177+
178+
### CSS => SWC implementation gaps
179+
180+
- **Static color variants**: The web component is missing support for static color variants (`--staticBlack` and `--staticWhite`). These are commonly used for overlays and high-contrast scenarios where labels need to maintain visibility over varying backgrounds.
181+
182+
### CSS Spectrum 2 changes
183+
184+
- **Improved text handling**: Enhanced label text processing with `?.trim()` to remove whitespace and added a zero-width non-joiner (`&#8288;`) between label text and the required asterisk icon. This ensures proper spacing and prevents text wrapping issues in internationalized content.
185+
186+
## Resources
187+
188+
- [CSS migration](https://github.com/adobe/spectrum-css/pull/2569)
189+
- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-field-label--docs)

‎migration-roadmap/help-text.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# Help text migration roadmap
2+
3+
## Component specifications
4+
5+
### CSS
6+
7+
<details>
8+
<summary>CSS selectors</summary>
9+
10+
- `.spectrum-HelpText`
11+
- `.spectrum-HelpText .spectrum-HelpText-text`
12+
- `.spectrum-HelpText .spectrum-HelpText-validationIcon`
13+
- `.spectrum-HelpText.is-disabled`
14+
- `.spectrum-HelpText.is-disabled .spectrum-HelpText-text`
15+
- `.spectrum-HelpText.is-disabled .spectrum-HelpText-validationIcon`
16+
- `.spectrum-HelpText.spectrum-HelpText--negative`
17+
- `.spectrum-HelpText.spectrum-HelpText--negative .spectrum-HelpText-text`
18+
- `.spectrum-HelpText.spectrum-HelpText--negative .spectrum-HelpText-validationIcon`
19+
- `.spectrum-HelpText.spectrum-HelpText--neutral`
20+
- `.spectrum-HelpText.spectrum-HelpText--neutral .spectrum-HelpText-text`
21+
- `.spectrum-HelpText.spectrum-HelpText--neutral .spectrum-HelpText-validationIcon`
22+
- `.spectrum-HelpText.spectrum-HelpText--sizeL`
23+
- `.spectrum-HelpText.spectrum-HelpText--sizeS`
24+
- `.spectrum-HelpText.spectrum-HelpText--sizeXL`
25+
- `.spectrum-HelpText:lang(ja)`
26+
- `.spectrum-HelpText:lang(ko)`
27+
- `.spectrum-HelpText:lang(zh)`
28+
29+
</details>
30+
31+
<details>
32+
<summary>Passthroughs</summary>
33+
34+
None found for this component.
35+
36+
</details>
37+
38+
<details>
39+
<summary>Modifiers</summary>
40+
41+
- `--mod-helptext-bottom-edge-to-workflow-icon`
42+
- `--mod-helptext-bottom-to-text`
43+
- `--mod-helptext-content-color-default`
44+
- `--mod-helptext-font-family`
45+
- `--mod-helptext-font-size`
46+
- `--mod-helptext-font-style`
47+
- `--mod-helptext-font-weight`
48+
- `--mod-helptext-icon-color-default`
49+
- `--mod-helptext-icon-size`
50+
- `--mod-helptext-line-height`
51+
- `--mod-helptext-line-height-cjk`
52+
- `--mod-helptext-min-height`
53+
- `--mod-helptext-text-to-visual`
54+
- `--mod-helptext-top-edge-to-workflow-icon`
55+
- `--mod-helptext-top-to-text`
56+
57+
</details>
58+
59+
### SWC
60+
61+
<details>
62+
<summary>Attributes</summary>
63+
64+
- `disabled` (Boolean) - Whether the help text is disabled
65+
- `icon` (Boolean) - Whether to show the validation icon
66+
- `variant` (String) - Visual variant: 'neutral' or 'negative'
67+
68+
</details>
69+
70+
<details>
71+
<summary>Slots</summary>
72+
73+
- Default slot - Text content of the help text
74+
75+
</details>
76+
77+
## Comparison
78+
79+
### DOM Structure changes
80+
81+
<details>
82+
<summary>Spectrum Web Components:</summary>
83+
84+
```html
85+
<sp-icon-alert class="icon"></sp-icon-alert>
86+
<div class="text"><slot></slot></div>
87+
```
88+
89+
</details>
90+
91+
<details>
92+
<summary>Legacy (CSS main branch):</summary>
93+
94+
```html
95+
<div class="spectrum-HelpText spectrum-HelpText--sizeM">
96+
<svg
97+
class="spectrum-HelpText-validationIcon"
98+
focusable="false"
99+
aria-hidden="true"
100+
role="img"
101+
>
102+
<path
103+
d="M10 2L13.09 8.26L20 9L14 14.74L15.18 22L10 18.77L4.82 22L6 14.74L0 9L6.91 8.26L10 2Z"
104+
></path>
105+
</svg>
106+
<div class="spectrum-HelpText-text">Help text content</div>
107+
</div>
108+
```
109+
110+
</details>
111+
112+
<details>
113+
<summary>Spectrum 2 (CSS spectrum-two branch):</summary>
114+
115+
```html
116+
<div class="spectrum-HelpText spectrum-HelpText--sizeM">
117+
<svg
118+
class="spectrum-Icon spectrum-HelpText-validationIcon"
119+
focusable="false"
120+
aria-hidden="true"
121+
role="img"
122+
>
123+
<path
124+
d="M10 2L13.09 8.26L20 9L14 14.74L15.18 22L10 18.77L4.82 22L6 14.74L0 9L6.91 8.26L10 2Z"
125+
></path>
126+
</svg>
127+
<div class="spectrum-HelpText-text">Help text content</div>
128+
</div>
129+
```
130+
131+
</details>
132+
133+
<details>
134+
<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>
135+
136+
No significant structural changes.
137+
138+
</details>
139+
140+
### CSS => SWC mapping
141+
142+
| CSS selector | Attribute or slot | Status |
143+
| --------------------------------------------------------------------------------------- | ------------------------- | ----------- |
144+
| `.spectrum-HelpText` | `:host` | Implemented |
145+
| `.spectrum-HelpText-text` | Text slot | Implemented |
146+
| `.spectrum-HelpText-validationIcon` | Icon element | Implemented |
147+
| `.spectrum-HelpText.is-disabled` | `disabled` attribute | Implemented |
148+
| `.spectrum-HelpText--negative` | `variant="negative"` | Implemented |
149+
| `.spectrum-HelpText--neutral` | `variant="neutral"` | Implemented |
150+
| `.spectrum-HelpText--sizeL` | `size="l"` | Implemented |
151+
| `.spectrum-HelpText--sizeS` | `size="s"` | Implemented |
152+
| `.spectrum-HelpText--sizeXL` | `size="xl"` | Implemented |
153+
| `.spectrum-HelpText:lang(ja), .spectrum-HelpText:lang(ko), .spectrum-HelpText:lang(zh)` | Language-specific styling | Implemented |
154+
155+
## Summary of changes
156+
157+
### CSS => SWC implementation gaps
158+
159+
No implementation gaps found. All CSS functionality is properly mapped to web component attributes and slots.
160+
161+
### CSS Spectrum 2 changes
162+
163+
- **Updated validation icon**: Changed the validation icon from `"Alert"` to `"AlertTriangle"` for better visual consistency with other form validation elements. This provides a more recognizable warning indicator for negative validation states.
164+
165+
## Resources
166+
167+
- [CSS migration](https://github.com/adobe/spectrum-css/pull/3628)
168+
- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-help-text--docs)

0 commit comments

Comments
 (0)