Skip to content

Commit 35c5f39

Browse files
rise-erpeldingrise-erpelding
committed
docs: action button group component analysis
1 parent 6d169b0 commit 35c5f39

File tree

1 file changed

+263
-0
lines changed

1 file changed

+263
-0
lines changed

‎migration-roadmap/action-group.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# Action group migration roadmap
2+
3+
## Component specifications
4+
5+
### CSS
6+
7+
<details>
8+
<summary>CSS selectors</summary>
9+
10+
**Base component:**
11+
12+
- `.spectrum-ActionGroup`
13+
14+
**Sizes:**
15+
16+
- `.spectrum-ActionGroup--sizeXS`
17+
- `.spectrum-ActionGroup--sizeS`
18+
- `.spectrum-ActionGroup--sizeM`
19+
- `.spectrum-ActionGroup--sizeL`
20+
- `.spectrum-ActionGroup--sizeXL`
21+
22+
**Layout variants:**
23+
24+
- `.spectrum-ActionGroup--vertical`
25+
- `.spectrum-ActionGroup--compact`
26+
27+
**Compact mode:**
28+
29+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet)`
30+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item`
31+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item + .spectrum-ActionGroup-item`
32+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item .spectrum-ActionButton-label`
33+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item.is-selected`
34+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:first-child`
35+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:last-child`
36+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:hover`
37+
- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:focus-visible`
38+
39+
**Compact + vertical mode:**
40+
41+
- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet)`
42+
- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item`
43+
- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item + .spectrum-ActionGroup-item`
44+
- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:first-child`
45+
- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:last-child`
46+
47+
**Child elements:**
48+
49+
- `.spectrum-ActionGroup .spectrum-ActionGroup-item`
50+
- `.spectrum-ActionGroup .spectrum-ActionGroup-item:focus-visible`
51+
52+
**Justified layout:**
53+
54+
- `.spectrum-ActionGroup--justified .spectrum-ActionGroup-item`
55+
56+
**Regular (non-compact, non-vertical) spacing:**
57+
58+
- `.spectrum-ActionGroup:not(.spectrum-ActionGroup--vertical, .spectrum-ActionGroup--compact) .spectrum-ActionGroup-item`
59+
60+
</details>
61+
62+
<details>
63+
<summary>Passthroughs</summary>
64+
65+
- `--mod-actionbutton-focus-indicator-border-radius`
66+
67+
</details>
68+
69+
<details>
70+
<summary>Modifiers</summary>
71+
72+
**Spacing:**
73+
74+
- `--mod-actiongroup-horizontal-spacing-regular`
75+
- `--mod-actiongroup-horizontal-spacing-compact`
76+
- `--mod-actiongroup-vertical-spacing-regular`
77+
- `--mod-actiongroup-vertical-spacing-compact`
78+
- `--mod-actiongroup-gap-size-compact`
79+
80+
**Border radius (for compact mode):**
81+
82+
- `--mod-actiongroup-border-radius`
83+
- `--mod-actiongroup-border-radius-reset`
84+
85+
**Button spacing reset (for compact mode):**
86+
87+
- `--mod-actiongroup-button-spacing-reset`
88+
89+
</details>
90+
91+
### SWC
92+
93+
<details>
94+
<summary>Attributes</summary>
95+
96+
**Size:**
97+
98+
- `size` (values: `xs`, `s`, `m`, `l`, `xl`) - group size, no default, propagates to child buttons
99+
100+
**Layout:**
101+
102+
- `vertical` - stacks buttons vertically (boolean)
103+
- `compact` - buttons appear connected with shared borders (boolean)
104+
- `justified` - buttons fill available width equally (boolean)
105+
106+
**Child button appearance (propagated to children):**
107+
108+
- `quiet` - applies quiet styling to all child buttons (boolean)
109+
- `emphasized` - applies emphasized styling to all child buttons (boolean)
110+
- `static-color` (values: `white`, `black`) - static color variant, propagates to children
111+
112+
**Selection management:**
113+
114+
- `selects` (values: `single`, `multiple`, undefined) - selection mode
115+
- `single`: radio group behavior (single selection)
116+
- `multiple`: checkbox group behavior (multiple selections)
117+
- undefined: no managed selection (individual toggles behavior)
118+
- `selected` - array of selected button values
119+
120+
**Accessibility:**
121+
122+
- `label` - accessible label for the group (sets aria-label)
123+
124+
</details>
125+
126+
<details>
127+
<summary>Slots</summary>
128+
129+
- Default slot - the `sp-action-button` elements that make up the group
130+
131+
</details>
132+
133+
## Comparison
134+
135+
### DOM structure changes
136+
137+
<details>
138+
<summary>Spectrum Web Components</summary>
139+
140+
```html
141+
<!-- Default slot for sp-action-button or sp-action-menu elements -->
142+
<slot role="presentation"></slot>
143+
```
144+
145+
</details>
146+
147+
<details>
148+
<summary>Legacy (CSS main branch)</summary>
149+
150+
```html
151+
<div class="spectrum-ActionGroup spectrum-ActionGroup--sizeM">
152+
<button class="spectrum-ActionButton spectrum-ActionGroup-item">...</button>
153+
<button class="spectrum-ActionButton spectrum-ActionGroup-item">...</button>
154+
<button class="spectrum-ActionButton spectrum-ActionGroup-item">...</button>
155+
</div>
156+
```
157+
158+
</details>
159+
160+
<details>
161+
<summary>Spectrum 2 (CSS spectrum-two branch)</summary>
162+
163+
```html
164+
<div class="spectrum-ActionGroup spectrum-ActionGroup--sizeM">
165+
<button class="spectrum-ActionButton spectrum-ActionGroup-item">...</button>
166+
<button class="spectrum-ActionButton spectrum-ActionGroup-item">...</button>
167+
<button class="spectrum-ActionButton spectrum-ActionGroup-item">...</button>
168+
</div>
169+
```
170+
171+
</details>
172+
173+
### CSS => SWC mapping
174+
175+
#### Sizes
176+
177+
| CSS selector | SWC attribute | Status |
178+
| ------------------------------- | -------------- | ----------- |
179+
| `.spectrum-ActionGroup` | Base component | Implemented |
180+
| `.spectrum-ActionGroup--sizeXS` | `size="xs"` | Implemented |
181+
| `.spectrum-ActionGroup--sizeS` | `size="s"` | Implemented |
182+
| `.spectrum-ActionGroup--sizeM` | `size="m"` | Implemented |
183+
| `.spectrum-ActionGroup--sizeL` | `size="l"` | Implemented |
184+
| `.spectrum-ActionGroup--sizeXL` | `size="xl"` | Implemented |
185+
186+
#### Layout variants
187+
188+
| CSS selector | SWC attribute | Status |
189+
| ---------------------------------- | ------------- | ----------- |
190+
| `.spectrum-ActionGroup--vertical` | `vertical` | Implemented |
191+
| `.spectrum-ActionGroup--compact` | `compact` | Implemented |
192+
| `.spectrum-ActionGroup--justified` | `justified` | Implemented |
193+
194+
#### Child elements
195+
196+
| CSS selector | SWC equivalent | Status |
197+
| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------- |
198+
| `.spectrum-ActionGroup .spectrum-ActionGroup-item` | Default slot / `::slotted(*)` | Implemented |
199+
| `.spectrum-ActionGroup .spectrum-ActionGroup-item:focus-visible` | Browser focus-visible on slotted items | Implemented |
200+
| `.spectrum-ActionGroup--justified .spectrum-ActionGroup-item` | Slotted buttons when `justified` | Implemented |
201+
| `.spectrum-ActionGroup:not(.spectrum-ActionGroup--vertical, .spectrum-ActionGroup--compact) .spectrum-ActionGroup-item` | Slotted buttons in regular mode | Implemented |
202+
203+
**Note:** In CSS templates, `.spectrum-ActionGroup-item` is applied as a class to each child button. In SWC, the group uses `::slotted(*)` to style slotted action buttons without adding an additional class.
204+
205+
#### Compact mode
206+
207+
| CSS selector | SWC attribute | Status |
208+
| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------- |
209+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet)` | `compact` (when not `quiet`) | Implemented |
210+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item` | Slotted buttons in compact mode | Implemented |
211+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item + .spectrum-ActionGroup-item` | Adjacent buttons in compact mode | Implemented |
212+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item .spectrum-ActionButton-label` | Button labels in compact mode | Implemented |
213+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item.is-selected` | Selected button in compact mode | Implemented |
214+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:first-child` | First button in compact mode | Implemented |
215+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:last-child` | Last button in compact mode | Implemented |
216+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:hover` | Hover state in compact mode | Implemented |
217+
| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:focus-visible` | Focus state in compact mode | Implemented |
218+
219+
#### Compact + vertical mode
220+
221+
| CSS selector | SWC attribute | Status |
222+
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------- |
223+
| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet)` | `compact` + `vertical` (when not `quiet`) | Implemented |
224+
| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item` | Slotted buttons in vertical compact mode | Implemented |
225+
| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item + .spectrum-ActionGroup-item` | Adjacent buttons in vertical compact mode | Implemented |
226+
| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:first-child` | First button in vertical compact mode | Implemented |
227+
| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:last-child` | Last button in vertical compact mode | Implemented |
228+
229+
#### WC-only attributes
230+
231+
| SWC attribute | CSS equivalent | Notes |
232+
| --------------------------------------- | -------------- | ---------------------------------------------------------- |
233+
| `quiet` (propagates to children) | N/A | In CSS, `--quiet` class on container affects child styling |
234+
| `emphasized` (propagates to children) | N/A | Propagates to child buttons |
235+
| `static-color` (propagates to children) | N/A | Propagates to child buttons |
236+
| `selects` | N/A | Manages single/multiple selection with automatic ARIA |
237+
| `selected` | N/A | Tracks selected button values |
238+
| `label` | N/A | Sets aria-label on the group |
239+
240+
## Summary of changes
241+
242+
### CSS => SWC implementation gaps
243+
244+
**Missing from WC:**
245+
None. All CSS selectors have corresponding web component implementations.
246+
247+
### CSS Spectrum 2 changes
248+
249+
**No structural changes:**
250+
The Action Group template is identical between the main branch (legacy) and spectrum-two branch (Spectrum 2). Both branches use the same DOM structure with:
251+
252+
- A `div` wrapper with `spectrum-ActionGroup` class
253+
- Size classes applied via `--size{size}` modifier pattern
254+
- Layout modifiers for vertical, compact, and justified layouts
255+
- Child buttons with `spectrum-ActionGroup-item` class
256+
257+
All spacing, border radius, and layout changes are handled through CSS custom properties without requiring DOM structure changes.
258+
259+
## Resources
260+
261+
- [CSS migration](https://github.com/adobe/spectrum-css/pull/2453)
262+
- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-action-group--docs)
263+
- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/actionbuttongroup--docs)

0 commit comments

Comments
 (0)