Skip to content

Commit 537ce7f

Browse files
rise-erpeldingrise-erpelding
committed
docs(progresscircle): update docs
1 parent 3f0190f commit 537ce7f

File tree

1 file changed

+139
-110
lines changed

1 file changed

+139
-110
lines changed

‎migration-roadmap/progress-circle.md‎

Lines changed: 139 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Progress Circle migration roadmap
22

3-
## CSS selectors
3+
## Component specifications
4+
5+
### CSS
46

57
<details>
68
<summary>CSS selectors</summary>
@@ -18,51 +20,47 @@
1820

1921
</details>
2022

21-
## Passthroughs
22-
2323
<details>
2424
<summary>Passthroughs</summary>
2525

26-
No passthroughs found for this component.
26+
None found for this component.
2727

2828
</details>
2929

30-
## Attributes
31-
3230
<details>
33-
<summary>Attributes</summary>
31+
<summary>Modifiers</summary>
3432

35-
- `indeterminate` - Boolean attribute for indeterminate state
36-
- `label` - String attribute for accessibility label
37-
- `static-color` - String attribute for static color variants (white)
38-
- `progress` - Number attribute for progress value (0-100)
39-
- `size` - String attribute for size variants (s, m, l)
33+
- `--mod-progress-circle-fill-border-color`
34+
- `--mod-progress-circle-position`
35+
- `--mod-progress-circle-size`
36+
- `--mod-progress-circle-thickness`
37+
- `--mod-progress-circle-track-border-color`
4038

4139
</details>
4240

43-
## Slots
41+
### SWC
4442

4543
<details>
46-
<summary>Slots</summary>
44+
<summary>Attributes</summary>
4745

48-
- Default slot - Optional content for accessibility labeling
46+
- `size` (s, m, l)
47+
- `indeterminate` (boolean)
48+
- `label` (string)
49+
- `static-color` (white)
50+
- `progress` (number)
4951

5052
</details>
5153

52-
## Modifiers
53-
5454
<details>
55-
<summary>Modifiers</summary>
55+
<summary>Slots</summary>
5656

57-
- `--mod-progress-circle-fill-border-color`
58-
- `--mod-progress-circle-position`
59-
- `--mod-progress-circle-size`
60-
- `--mod-progress-circle-thickness`
61-
- `--mod-progress-circle-track-border-color`
57+
- Default slot (for label content, sets the aria label)
6258

6359
</details>
6460

65-
## Visual Comparison
61+
## Comparison
62+
63+
### Visual comparison
6664

6765
**Legacy Component:**
6866

@@ -72,13 +70,40 @@ No passthroughs found for this component.
7270

7371
<!-- Screenshot of Spectrum 2 component will be added here -->
7472

75-
## DOM Structure Changes
73+
### DOM structure changes
7674

77-
**Legacy (main branch):**
75+
<details>
76+
<summary>Spectrum Web Components:</summary>
77+
78+
```html
79+
<sp-progress-circle role="progressbar" aria-valuenow="50">
80+
<slot></slot>
81+
<div class="track"></div>
82+
<div class="fills">
83+
<div class="fillMask1">
84+
<div class="fillSubMask1" style="transform: rotate(0deg);">
85+
<div class="fill"></div>
86+
</div>
87+
</div>
88+
<div class="fillMask2">
89+
<div class="fillSubMask2" style="transform: rotate(0deg);">
90+
<div class="fill"></div>
91+
</div>
92+
</div>
93+
</div>
94+
</sp-progress-circle>
95+
```
96+
97+
</details>
98+
99+
<details>
100+
<summary>Legacy (CSS main branch):</summary>
78101

79102
```html
80103
<div
81-
class="spectrum-ProgressCircle spectrum-ProgressCircle--medium spectrum-ProgressCircle--indeterminate"
104+
class="spectrum-ProgressCircle spectrum-ProgressCircle--medium"
105+
id="progress-circle-123"
106+
data-testid="test-id"
82107
>
83108
<div class="spectrum-ProgressCircle-track"></div>
84109
<div class="spectrum-ProgressCircle-fills">
@@ -96,16 +121,23 @@ No passthroughs found for this component.
96121
</div>
97122
```
98123

99-
**Spectrum 2 (spectrum-two branch):**
124+
</details>
125+
126+
<details>
127+
<summary>Spectrum 2 (CSS spectrum-two branch):</summary>
100128

101129
```html
102-
<div class="spectrum-ProgressCircle spectrum-ProgressCircle--indeterminate">
130+
<div
131+
class="spectrum-ProgressCircle"
132+
id="progress-circle-123"
133+
data-testid="test-id"
134+
>
103135
<svg fill="none" width="100%" height="100%" class="spectrum-outerCircle">
104136
<circle
105137
class="spectrum-innerCircle"
106138
cx="50%"
107139
cy="50%"
108-
r="calc(50% - 1px)"
140+
r="calc(50% - 3px)"
109141
stroke-width="2"
110142
/>
111143
<circle
@@ -121,93 +153,90 @@ No passthroughs found for this component.
121153
class="spectrum-ProgressCircle-fill"
122154
pathLength="100"
123155
stroke-dasharray="100 200"
124-
stroke-dashoffset="0"
156+
stroke-dashoffset="50"
125157
stroke-linecap="round"
126158
/>
127159
</svg>
128160
</div>
129161
```
130162

131-
## Comparison
132-
133-
| CSS selector | Attribute or slot | Status |
134-
| --------------------------------------------------------------------------------------------- | ------------------------- | --------------- |
135-
| `.spectrum-ProgressCircle` | Base component | Implemented |
136-
| `.spectrum-ProgressCircle--indeterminate .spectrum-ProgressCircle-fill` | `indeterminate` attribute | Implemented |
137-
| `.spectrum-ProgressCircle--sizeL` | `size="l"` | Implemented |
138-
| `.spectrum-ProgressCircle--sizeS` | `size="s"` | Implemented |
139-
| `.spectrum-ProgressCircle-fill` | Progress fill element | Implemented |
140-
| `.spectrum-ProgressCircle-track` | Track element | Implemented |
141-
| `.spectrum-ProgressCircle.spectrum-ProgressCircle--staticBlack` | `static-color` attribute | Missing from WC |
142-
| `.spectrum-ProgressCircle.spectrum-ProgressCircle--staticWhite` | `static-color="white"` | Implemented |
143-
| `.spectrum-ProgressCircle:not(.spectrum-ProgressCircle--indeterminate) .spectrum-innerCircle` | Non-indeterminate state | Implemented |
144-
| `.spectrum-ProgressCircle:not(.spectrum-ProgressCircle--indeterminate) .spectrum-outerCircle` | Non-indeterminate state | Implemented |
145-
146-
## Key Structural Changes
147-
148-
**Element Hierarchy Changes:**
149-
150-
- **Major restructuring**: Legacy uses complex nested div structure with masks and submasks
151-
- **Spectrum 2**: Simplified to SVG-based approach with circles for track and fill
152-
- **Removed complexity**: Eliminated the complex mask/submask system in favor of SVG stroke-dasharray
153-
154-
**Class Name Changes:**
155-
156-
- **Size classes**: Legacy uses `--small`, `--medium`, `--large` while Spectrum 2 uses `--sizeS`, `--sizeM`, `--sizeL`
157-
- **Static color**: Legacy supports both `--staticBlack` and `--staticWhite`, Spectrum 2 only supports `--staticWhite`
158-
- **Simplified structure**: Removed complex fill mask classes in favor of SVG-based approach
159-
160-
**Attribute Changes:**
161-
162-
- **No new required attributes**
163-
- **No removed attributes**
164-
- **Size values**: Legacy uses `small/medium/large`, Spectrum 2 uses `s/m/l`
165-
166-
**Slot/Content Changes:**
167-
168-
- **No changes in slot usage**
169-
- **Content structure**: Completely different internal implementation approach
170-
171-
**Migration Impact:**
172-
173-
- **Breaking changes**: Complete restructuring of internal DOM elements
174-
- **Visual consistency**: Maintained through CSS styling but different underlying structure
175-
- **Accessibility**: Preserved through maintained attributes and ARIA support
176-
177-
## Implementation Gaps Analysis
178-
179-
### CSS Features Missing from Web Component
180-
181-
- **Static black variant**: CSS supports `--staticBlack` but web component only supports `--staticWhite`
182-
- **Complex mask system**: Legacy CSS has sophisticated mask/submask system that's not replicated in web component
183-
- **Theme imports**: Legacy includes multiple theme imports that may affect styling
184-
185-
### Web Component Features Missing from CSS
186-
187-
- **SVG-based rendering**: Web component uses modern SVG approach not present in legacy CSS
188-
- **Simplified structure**: Web component eliminates complex mask system in favor of cleaner SVG implementation
189-
190-
### Features Being Deprecated/Removed
191-
192-
- **Complex mask system**: The intricate fillMask1/fillMask2/fillSubMask1/fillSubMask2 structure is removed
193-
- **Theme-specific imports**: Legacy theme imports are simplified in Spectrum 2
194-
- **Static black variant**: No longer supported in Spectrum 2
195-
196-
## Action Items for Web Component Maintainers
197-
198-
**Required Additions:**
199-
200-
- Implement `static-color="black"` variant to match legacy `--staticBlack` support
201-
- Ensure SVG-based rendering maintains visual parity with legacy mask-based approach
202-
- Consider exposing mask-related custom properties for advanced customization
163+
</details>
203164

204-
**Required Removals:**
165+
<details>
166+
<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>
205167

206-
- No specific removals required - the web component already simplifies the complex legacy structure
168+
```diff
169+
<div
170+
class="spectrum-ProgressCircle"
171+
- class="spectrum-ProgressCircle spectrum-ProgressCircle--medium"
172+
id="progress-circle-123"
173+
data-testid="test-id"
174+
>
175+
- <div class="spectrum-ProgressCircle-track"></div>
176+
- <div class="spectrum-ProgressCircle-fills">
177+
- <div class="spectrum-ProgressCircle-fillMask1">
178+
- <div class="spectrum-ProgressCircle-fillSubMask1">
179+
- <div class="spectrum-ProgressCircle-fill"></div>
180+
- </div>
181+
- </div>
182+
- <div class="spectrum-ProgressCircle-fillMask2">
183+
- <div class="spectrum-ProgressCircle-fillSubMask2">
184+
- <div class="spectrum-ProgressCircle-fill"></div>
185+
- </div>
186+
- </div>
187+
- </div>
188+
+ <svg fill="none" width="100%" height="100%" class="spectrum-outerCircle">
189+
+ <circle class="spectrum-innerCircle" cx="50%" cy="50%" r="calc(50% - 3px)" stroke-width="2" />
190+
+ <circle
191+
+ cx="50%"
192+
+ cy="50%"
193+
+ class="spectrum-ProgressCircle-track"
194+
+ r="calc(50% - 1.5px)"
195+
+ />
196+
+ <circle
197+
+ cx="50%"
198+
+ cy="50%"
199+
+ r="calc(50% - 1.5px)"
200+
+ class="spectrum-ProgressCircle-fill"
201+
+ pathLength="100"
202+
+ stroke-dasharray="100 200"
203+
+ stroke-dashoffset="50"
204+
+ stroke-linecap="round"
205+
+ />
206+
+ </svg>
207+
</div>
208+
```
207209

208-
**Breaking Changes:**
210+
</details>
209211

210-
- **Major structural changes**: Complete rewrite of internal DOM structure from div-based masks to SVG-based circles
211-
- **Size class changes**: Migration from `small/medium/large` to `s/m/l` values
212-
- **Static color limitation**: Loss of `staticBlack` variant support
213-
- **Template updates required**: Consumers will need to update any code that relies on the specific legacy DOM structure
212+
### CSS => SWC mapping
213+
214+
| CSS selector | Attribute or slot | Status |
215+
| --------------------------------------------------------------------------------------------- | -------------------------- | ---------------- |
216+
| `.spectrum-ProgressCircle--sizeS` | `size="s"` | Implemented |
217+
| `.spectrum-ProgressCircle--sizeL` | `size="l"` | Implemented |
218+
| `.spectrum-ProgressCircle--indeterminate` | `indeterminate` | Implemented |
219+
| `.spectrum-ProgressCircle.spectrum-ProgressCircle--staticBlack` | `static-color="black"` | Missing from WC |
220+
| `.spectrum-ProgressCircle.spectrum-ProgressCircle--staticWhite` | `static-color="white"` | Implemented |
221+
| `.spectrum-ProgressCircle` | Base component | Implemented |
222+
| `.spectrum-ProgressCircle-fill` | Internal fill element | Implemented |
223+
| `.spectrum-ProgressCircle-track` | Internal track element | Implemented |
224+
| `.spectrum-ProgressCircle--indeterminate .spectrum-ProgressCircle-fill` | Indeterminate fill styling | Implemented |
225+
| `.spectrum-ProgressCircle:not(.spectrum-ProgressCircle--indeterminate) .spectrum-innerCircle` | Determinate inner circle | Missing from CSS |
226+
| `.spectrum-ProgressCircle:not(.spectrum-ProgressCircle--indeterminate) .spectrum-outerCircle` | Determinate outer circle | Missing from CSS |
227+
| | `label` | Missing from CSS |
228+
| | `progress` | Missing from CSS |
229+
| | Default slot | Missing from CSS |
230+
231+
## Summary of changes
232+
233+
The progress circle component has significant differences between CSS and web component implementations:
234+
235+
- **Rendering approach**: Complete shift from div-based CSS masks to SVG-based rendering - **this will require changes to SWC's render method** and will also potentially affect how `progress` is applied to calculate inline styles
236+
- **Label attribute**: Web component supports a `label` attribute for accessibility that is not present in CSS
237+
238+
## Resources
239+
240+
- [CSS migration](https://github.com/adobe/spectrum-css/commit/0c52c4820a3c5fb0881f23c6144fb0d0bd9a35cf)
241+
- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-progress-circle--docs)
242+
- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/progresscircle--docs)

0 commit comments

Comments
 (0)