From d19a288727fe9b5bfcc81d941545c0f7f2682a41 Mon Sep 17 00:00:00 2001 From: Marissa Huysentruyt Date: Fri, 29 Aug 2025 16:28:26 -0400 Subject: [PATCH 1/9] chore: add cursor prompt --- migration-roadmap/cursor_prompt.md | 268 +++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 migration-roadmap/cursor_prompt.md diff --git a/migration-roadmap/cursor_prompt.md b/migration-roadmap/cursor_prompt.md new file mode 100644 index 00000000000..c09a49cfe84 --- /dev/null +++ b/migration-roadmap/cursor_prompt.md @@ -0,0 +1,268 @@ +# Spectrum Migration Documentation Prompt + +For the **\_\_** component(s), create comprehensive migration documentation in individual markdown files within the `migration-roadmap/` directory of the spectrum-web-components repository, following this exact structure: + +## File Organization + +Create a separate markdown file for each component using the component/package name from the spectrum-web-components repository: + +- File path: `migration-roadmap/[COMPONENT_NAME].md` +- Example: `migration-roadmap/alert-banner.md`, `migration-roadmap/dialog.md` + +## Component Documentation Structure + +### 1. Component Heading + +- Create a Level 1 heading (`#`) with the format: "[Component name] migration roadmap" +- Example: `# Alert Banner migration roadmap` + +### 2. Metadata Extraction (spectrum-css repository) + +From the `spectrum-two` branch of the spectrum-css repository, locate the component's `metadata.json` file in the `components/[component-name]/` directory. + +**Additional Context**: Review the component's CHANGELOG file (if available) for historical context on changes, deprecations, and new features that may inform the migration documentation. + +Create collapsible sections using `
` and `` for each category: + +**CSS Selectors Section:** + +- Title: "CSS selectors" +- Extract all selectors from metadata.json +- If empty, write: "No CSS selectors found for this component." + +**Passthroughs Section:** + +- Title: "Passthroughs" +- Extract all passthroughs from metadata.json +- If empty, write: "No passthroughs found for this component." + +**Modifiers Section (ALWAYS LAST):** + +- Title: "Modifiers" +- Extract all modifiers from metadata.json +- If empty, write: "No modifiers found for this component." +- **Important**: This section must always be the final `
` list + +### 3. Web Component Analysis (spectrum-web-components repository) + +From the spectrum-web-components repository, analyze the component and create additional collapsible sections: + +**Attributes Section:** + +- Title: "Attributes" +- List all component attributes +- For string properties with enumerated values, extract each value as a separate attribute entry +- If empty, write: "No attributes found for this component." + +**Slots Section:** + +- Title: "Slots" +- List all component slots +- If empty, write: "No slots found for this component." + +**Ensure modifiers remain the final section after adding attributes and slots.** + +### 4. Visual Comparison Section + +Create a Level 2 heading (`##`) titled "Visual Comparison" + +Add a placeholder section for component screenshots: + +```markdown +### Visual Comparison + +**Legacy Component:** + + + +**Spectrum 2 Component:** + + +``` + +### 5. DOM Structure Analysis + +Create a Level 2 heading (`##`) titled "DOM Structure Changes" + +**Branch Switching Requirements**: +You will need to analyze the same component across two different branches of the spectrum-css repository. Use these git commands to switch between branches: + +```bash +# For legacy analysis +git checkout main + +# For Spectrum 2 analysis +git checkout spectrum-two +``` + +**Source Analysis**: + +- Compare the component's `stories/template.js` file between the `main` branch and `spectrum-two` branch of spectrum-css +- Analyze generated HTML patterns from Storybook stories +- Document class application differences + +**Analysis Process**: + +1. Switch to `main` branch and analyze the component's template structure +2. Switch to `spectrum-two` branch and analyze the updated template structure +3. Document the differences between both versions + +**Output Format**: +Create a side-by-side HTML comparison using markdown code blocks: + +````markdown +**Legacy (main branch):** + +```html + +``` +```` + +**Spectrum 2 (spectrum-two branch):** + +```html + +``` + +### 6. Comparison Table + +Create a Level 2 heading (`##`) titled "Comparison" + +Below the collapsible sections, create a markdown table with: + +- Column 1: "CSS selector" +- Column 2: "Attribute or slot" +- Column 3: "Status" + +**Status Values:** + +- "Implemented" - CSS selector has corresponding web component feature +- "Missing from WC" - CSS exists but no web component equivalent +- "Missing from CSS" - Web component feature exists but no CSS support +- "Deprecated" - Being removed in Spectrum 2 + +**Mapping Logic:** + +- **Variants to Attributes**: CSS selectors with variants (noted after "—") likely map to component attributes +- **Base Elements to Slots**: Selectors with base class + single "-" (e.g., `.spectrum-button-label`) likely map to slots +- **Language Selectors**: Group all selectors containing `:lang` together on a single row, comma-separated, as they serve the same internationalization purpose and are typically implemented as a block + +**Language Selector Formatting Example:** + +``` +`.spectrum-Search:lang(ja)`, `.spectrum-Search:lang(ko)`, `.spectrum-Search:lang(zh)` | Language-specific styling | Implemented +``` + +**Table Organization:** + +1. Mapped pairs (CSS selector ↔ Attribute/Slot) with appropriate status +2. Unmapped selectors (empty "Attribute or slot" column, "Missing from WC" status) +3. Unmapped attributes/slots (empty "CSS selector" column, "Missing from CSS" status) + +## Additional Requirements + +### Clarifying Questions + +If you encounter any ambiguities, edge cases, or unclear mappings during documentation, please ask clarifying questions rather than making assumptions. This includes: + +- Uncertain CSS selector to attribute/slot mappings +- Components with unusual metadata structure +- Missing or incomplete metadata.json files +- Conflicting information between repositories + +### Property Change Documentation + +When documenting modifiers, include analysis of: + +- Properties that were renamed/restructured +- Properties that were removed entirely +- New properties that were added +- Changes in default values or behavior + +### 7. Structural Changes Summary + +Create a Level 2 heading (`##`) titled "Key Structural Changes" + +After the comparison table, provide a focused summary of DOM changes that will impact SWC engineers: + +**Element Hierarchy Changes:** + +- Document any changes in nesting depth or parent-child relationships +- Note new wrapper elements or removed containers + +**Class Name Changes:** + +- List renamed, added, or removed CSS classes +- Highlight changes in class application patterns + +**Attribute Changes:** + +- Document new required attributes or removed attributes +- Note changes in attribute naming or values + +**Slot/Content Changes:** + +- Identify changes in how content is structured or slotted +- Document new content containers or removed content areas + +**Migration Impact:** + +- Summarize the most critical changes that will require template updates +- Flag any breaking changes in component structure + +### 8. Implementation Gaps Analysis + +Create a Level 3 heading (`###`) titled "Implementation Gaps" + +Analyze and document the following subsections: + +**CSS Features Missing from Web Component:** + +- List CSS selectors/features that have no web component equivalent +- Include any new Spectrum 2 capabilities not yet implemented + +**Web Component Features Missing from CSS:** + +- List web component attributes/slots that have no CSS equivalent +- Include legacy features that may no longer be supported + +**Features Being Deprecated/Removed:** + +- List any legacy web component features being removed in Spectrum 2 +- Note any breaking changes in functionality + +### 9. Action Items Summary + +Create a Level 3 heading (`###`) titled "Action Items for Web Component Maintainers" + +Provide clear, actionable next steps: + +**Required Additions:** + +- Web component features that need to be implemented to match CSS capabilities + +**Required Removals:** + +- Legacy features that should be removed or deprecated + +**Breaking Changes:** + +- Changes that will affect existing web component consumers +- Migration guidance where applicable + +### Integration Guidance + +Where applicable, include brief notes on: + +- Usage pattern differences between legacy and Spectrum 2 +- Integration considerations for web component consumers + +## Output Format + +- Create individual markdown files in the `migration-roadmap/` directory +- Use component names from spectrum-web-components repository for filenames +- Use proper markdown formatting with Level 1 heading for component name +- Ensure all `
` elements are properly closed +- Use consistent table formatting +- Maintain hierarchical heading structure (Level 1 for component, Level 2 for major sections) +- Keep modifiers section as the final collapsible section in each component From 15e8a9b09a7fa671a0473b1afe050020d4de8c2a Mon Sep 17 00:00:00 2001 From: Marissa Huysentruyt Date: Fri, 29 Aug 2025 16:34:22 -0400 Subject: [PATCH 2/9] docs: add prompt output files for subset of components --- migration-roadmap/alert-banner.md | 215 ++++++++++++++++++ migration-roadmap/alert-dialog.md | 219 ++++++++++++++++++ migration-roadmap/breadcrumbs.md | 254 +++++++++++++++++++++ migration-roadmap/button.md | 276 ++++++++++++++++++++++ migration-roadmap/illustrated-message.md | 216 ++++++++++++++++++ migration-roadmap/search.md | 278 +++++++++++++++++++++++ 6 files changed, 1458 insertions(+) create mode 100644 migration-roadmap/alert-banner.md create mode 100644 migration-roadmap/alert-dialog.md create mode 100644 migration-roadmap/breadcrumbs.md create mode 100644 migration-roadmap/button.md create mode 100644 migration-roadmap/illustrated-message.md create mode 100644 migration-roadmap/search.md diff --git a/migration-roadmap/alert-banner.md b/migration-roadmap/alert-banner.md new file mode 100644 index 00000000000..bff41b1fc7f --- /dev/null +++ b/migration-roadmap/alert-banner.md @@ -0,0 +1,215 @@ +# Alert Banner migration roadmap + +
+CSS selectors + +- `.spectrum-AlertBanner` +- `.spectrum-AlertBanner--info` +- `.spectrum-AlertBanner--negative` +- `.spectrum-AlertBanner-body` +- `.spectrum-AlertBanner-content` +- `.spectrum-AlertBanner-icon` +- `.spectrum-AlertBanner-text` +- `.spectrum-AlertBanner.is-open` +- `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` +- `.spectrum-AlertBanner:lang(ja)`, `.spectrum-AlertBanner:lang(ko)`, `.spectrum-AlertBanner:lang(zh)` + +
+ +
+Passthroughs + +- `--mod-closebutton-align-self` +- `--mod-closebutton-margin-inline` +- `--mod-closebutton-margin-top` +- `--mod-icon-size` + +
+ +
+Attributes + +- `open` (Boolean) - Controls the display of the alert banner +- `dismissible` (Boolean) - Whether to include an icon-only close button to dismiss the alert banner +- `variant` (String) - The variant applies specific styling when set to `negative`, `neutral`, or `info` + +
+ +
+Slots + +- Default slot - The alert banner text context +- `action` - Slot for the button element that surfaces the contextual action a user can take + +
+ +
+Modifiers + +- `--mod-alert-banner-background` +- `--mod-alert-banner-block-edge-to-button` +- `--mod-alert-banner-bottom-to-text` +- `--mod-alert-banner-close-button-to-content` +- `--mod-alert-banner-close-button-to-inline-end` +- `--mod-alert-banner-font-color` +- `--mod-alert-banner-font-family` +- `--mod-alert-banner-font-size` +- `--mod-alert-banner-icon-size` +- `--mod-alert-banner-icon-to-text` +- `--mod-alert-banner-informative-background` +- `--mod-alert-banner-inline-end-to-content` +- `--mod-alert-banner-inline-size` +- `--mod-alert-banner-inline-start-to-content` +- `--mod-alert-banner-line-height` +- `--mod-alert-banner-max-inline-size` +- `--mod-alert-banner-min-height` +- `--mod-alert-banner-negative-background` +- `--mod-alert-banner-neutral-background` +- `--mod-alert-banner-text-margin-block-end` +- `--mod-alert-banner-text-margin-block-start` +- `--mod-alert-banner-text-to-button-horizontal` +- `--mod-alert-banner-text-to-button-vertical` +- `--mod-alert-banner-top-to-close-button` +- `--mod-alert-banner-top-to-icon` +- `--mod-alert-banner-top-to-text` + +
+ +## Visual Comparison + +**Legacy Component:** + + + +**Spectrum 2 Component:** + + + +## DOM Structure Changes + +**Legacy (main branch):** + +```html +
+
+
+ [icon] +

[text]

+
+ +
+
+
+ +
+
+``` + +**Spectrum 2 (spectrum-two branch):** + +```html +
+
+
+ [icon] +

[text]

+
+ +
+
+ +
+
+``` + +## Comparison + +| CSS selector | Attribute or slot | Status | +| ---------------------------------------------------------------------------------------------------- | ------------------------- | ---------------- | +| `.spectrum-AlertBanner` | Root element | Implemented | +| `.spectrum-AlertBanner--info` | `variant="info"` | Implemented | +| `.spectrum-AlertBanner--negative` | `variant="negative"` | Implemented | +| `.spectrum-AlertBanner-body` | - | Implemented | +| `.spectrum-AlertBanner-content` | - | Implemented | +| `.spectrum-AlertBanner-icon` | - | Implemented | +| `.spectrum-AlertBanner-text` | Default slot | Implemented | +| `.spectrum-AlertBanner.is-open` | `open` attribute | Implemented | +| `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` | `dismissible` attribute | Implemented | +| `.spectrum-AlertBanner:lang(ja)`, `.spectrum-AlertBanner:lang(ko)`, `.spectrum-AlertBanner:lang(zh)` | Language-specific styling | Implemented | +| - | `action` slot | Missing from CSS | +| - | `dismissible` attribute | Missing from CSS | + +## Key Structural Changes + +**Element Hierarchy Changes:** + +- Removed divider element between content and close button in Spectrum 2 +- Simplified end container structure + +**Class Name Changes:** + +- No major class name changes +- Maintained consistent naming convention + +**Attribute Changes:** + +- Added `open` attribute for controlling display state +- Added `dismissible` attribute for controlling close button visibility + +**Slot/Content Changes:** + +- Added dedicated `action` slot for button elements +- Default slot remains for text content + +**Migration Impact:** + +- Removal of divider element will affect visual separation between content and close button +- Web component provides better semantic structure with slots + +### Implementation Gaps + +**CSS Features Missing from Web Component:** + +- All CSS selectors are properly implemented in the web component + +**Web Component Features Missing from CSS:** + +- `action` slot - needs CSS support for slotted action button positioning +- `dismissible` attribute - CSS should provide conditional styling based on this attribute + +**Features Being Deprecated/Removed:** + +- Divider element between content and close button has been removed in Spectrum 2 + +### Action Items for Web Component Maintainers + +**Required Additions:** + +- No major additions needed - component is well-aligned with CSS implementation + +**Required Removals:** + +- None identified + +**Breaking Changes:** + +- Divider removal may affect existing implementations expecting visual separation +- Migration guidance: Update expectations for visual separation between content and close button diff --git a/migration-roadmap/alert-dialog.md b/migration-roadmap/alert-dialog.md new file mode 100644 index 00000000000..1a21508961a --- /dev/null +++ b/migration-roadmap/alert-dialog.md @@ -0,0 +1,219 @@ +# Alert Dialog migration roadmap + +
+CSS selectors + +- `.spectrum-AlertDialog` +- `.spectrum-AlertDialog .spectrum-Icon` +- `.spectrum-AlertDialog--error` +- `.spectrum-AlertDialog--warning` +- `.spectrum-AlertDialog-buttongroup` +- `.spectrum-AlertDialog-content` +- `.spectrum-AlertDialog-grid` +- `.spectrum-AlertDialog-header` +- `.spectrum-AlertDialog-heading` + +
+ +
+Passthroughs + +- `--mod-buttongroup-justify-content` +- `--mod-icon-color` + +
+ +
+Attributes + +- `variant` (String) - The visual variant to apply to this dialog (`confirmation`, `information`, `warning`, `error`, `destructive`, `secondary`) + +
+ +
+Slots + +- `heading` - Headline for the alert dialog +- Default slot - Description text content for the alert dialog +- `button` - Button elements for the dialog actions + +
+ +
+Modifiers + +- `--mod-alert-dialog-background-color` +- `--mod-alert-dialog-body-color` +- `--mod-alert-dialog-body-font-family` +- `--mod-alert-dialog-body-font-style` +- `--mod-alert-dialog-body-font-weight` +- `--mod-alert-dialog-body-line-height` +- `--mod-alert-dialog-corner-radius` +- `--mod-alert-dialog-description-content-size` +- `--mod-alert-dialog-description-to-button-group` +- `--mod-alert-dialog-edge-to-content` +- `--mod-alert-dialog-error-icon-color` +- `--mod-alert-dialog-heading-size` +- `--mod-alert-dialog-icon-size` +- `--mod-alert-dialog-max-width` +- `--mod-alert-dialog-min-width` +- `--mod-alert-dialog-minimum-title-to-icon` +- `--mod-alert-dialog-title-color` +- `--mod-alert-dialog-title-font-family` +- `--mod-alert-dialog-title-font-style` +- `--mod-alert-dialog-title-font-weight` +- `--mod-alert-dialog-title-line-height` +- `--mod-alert-dialog-title-to-description` +- `--mod-alert-dialog-warning-icon-color` + +
+ +## Visual Comparison + +**Legacy Component:** + + + +**Spectrum 2 Component:** + + + +## DOM Structure Changes + +**Legacy (main branch):** + +```html + +``` + +**Spectrum 2 (spectrum-two branch):** + +```html + +``` + +## Comparison + +| CSS selector | Attribute or slot | Status | +| -------------------------------------- | ------------------------ | ---------------- | +| `.spectrum-AlertDialog` | Root element | Implemented | +| `.spectrum-AlertDialog--error` | `variant="error"` | Implemented | +| `.spectrum-AlertDialog--warning` | `variant="warning"` | Implemented | +| `.spectrum-AlertDialog-grid` | Layout grid | Implemented | +| `.spectrum-AlertDialog-header` | Header container | Implemented | +| `.spectrum-AlertDialog-heading` | `heading` slot | Implemented | +| `.spectrum-AlertDialog-content` | Default slot | Implemented | +| `.spectrum-AlertDialog-buttongroup` | Button container | Implemented | +| `.spectrum-AlertDialog .spectrum-Icon` | Icon element | Implemented | +| - | `variant="confirmation"` | Missing from CSS | +| - | `variant="information"` | Missing from CSS | +| - | `variant="destructive"` | Missing from CSS | +| - | `variant="secondary"` | Missing from CSS | +| - | `button` slot | Missing from CSS | + +## Key Structural Changes + +**Element Hierarchy Changes:** + +- Removed divider element between header and content in Spectrum 2 +- Reordered icon and heading elements within header (icon now comes first) +- Added dedicated `spectrum-AlertDialog-buttongroup` container +- Changed button container from direct ButtonGroup to section wrapper + +**Class Name Changes:** + +- Added `spectrum-AlertDialog-buttongroup` for button container +- Removed `spectrum-AlertDialog-divider` class + +**Attribute Changes:** + +- Expanded variant options to include `confirmation`, `information`, `destructive`, `secondary` +- Added automatic icon mapping for `warning` and `error` variants + +**Slot/Content Changes:** + +- Added dedicated `heading` slot for dialog title +- Added dedicated `button` slot for action buttons +- Default slot for main content/description + +**Migration Impact:** + +- Removal of divider element will affect visual separation between sections +- Icon reordering may affect existing layout assumptions +- New variants provide better semantic meaning for different dialog types + +### Implementation Gaps + +**CSS Features Missing from Web Component:** + +- All major CSS selectors are properly implemented in the web component + +**Web Component Features Missing from CSS:** + +- `confirmation` variant - CSS should provide styling for confirmation dialogs +- `information` variant - CSS should provide styling for information dialogs +- `destructive` variant - CSS should provide styling for destructive action dialogs +- `secondary` variant - CSS should provide styling for secondary priority dialogs +- `button` slot - CSS should provide styling for slotted button elements + +**Features Being Deprecated/Removed:** + +- Divider element between header and content has been removed in Spectrum 2 +- Icon/heading order has been updated for better visual hierarchy + +### Action Items for Web Component Maintainers + +**Required Additions:** + +- CSS support for additional variant types (`confirmation`, `information`, `destructive`, `secondary`) +- CSS styling for button slot functionality + +**Required Removals:** + +- Remove dependency on divider element between header and content +- Update icon/heading layout order in templates + +**Breaking Changes:** + +- Divider removal changes visual layout of dialog +- Icon/heading reordering may affect existing styling +- Migration guidance: Update expectations for visual separation and element ordering in dialog header diff --git a/migration-roadmap/breadcrumbs.md b/migration-roadmap/breadcrumbs.md new file mode 100644 index 00000000000..5fd94f14466 --- /dev/null +++ b/migration-roadmap/breadcrumbs.md @@ -0,0 +1,254 @@ +# Breadcrumbs migration roadmap + +
+CSS selectors + +- `.spectrum-Breadcrumbs` +- `.spectrum-Breadcrumbs--multiline` +- `.spectrum-Breadcrumbs--multiline .spectrum-Breadcrumbs-item:last-of-type` +- `.spectrum-Breadcrumbs--multiline .spectrum-Breadcrumbs-item:last-of-type > .spectrum-Breadcrumbs-itemLink` +- `.spectrum-Breadcrumbs--sizeL` +- `.spectrum-Breadcrumbs-item` +- `.spectrum-Breadcrumbs-item > .spectrum-ActionButton` +- `.spectrum-Breadcrumbs-item > .spectrum-ActionButton:disabled` +- `.spectrum-Breadcrumbs-item.is-dragged .spectrum-Breadcrumbs-itemLink:before` +- `.spectrum-Breadcrumbs-item:first-of-type > .spectrum-ActionButton` +- `.spectrum-Breadcrumbs-item:first-of-type > .spectrum-Breadcrumbs-itemLink` +- `.spectrum-Breadcrumbs-item:last-of-type` +- `.spectrum-Breadcrumbs-item:last-of-type .spectrum-Breadcrumbs-itemLink` +- `.spectrum-Breadcrumbs-item:last-of-type .spectrum-Breadcrumbs-itemSeparator` +- `.spectrum-Breadcrumbs-itemLink` +- `.spectrum-Breadcrumbs-itemLink + .spectrum-Breadcrumbs-itemSeparator` +- `.spectrum-Breadcrumbs-itemLink.is-disabled` +- `.spectrum-Breadcrumbs-itemLink:focus-visible:before` +- `.spectrum-Breadcrumbs-itemLink[aria-disabled="true"]` +- `.spectrum-Breadcrumbs-itemLink[href]` +- `.spectrum-Breadcrumbs-itemLink[href]:active` +- `.spectrum-Breadcrumbs-itemLink[href]:focus-visible` +- `.spectrum-Breadcrumbs-itemLink[href]:hover` +- `.spectrum-Breadcrumbs-itemLink[tabindex="0"]` +- `.spectrum-Breadcrumbs-itemLink[tabindex="0"]:active` +- `.spectrum-Breadcrumbs-itemLink[tabindex="0"]:focus-visible` +- `.spectrum-Breadcrumbs-itemLink[tabindex="0"]:hover` +- `.spectrum-Breadcrumbs-itemSeparator` +- `.spectrum-Breadcrumbs-itemSeparator:dir(rtl)` + +
+ +
+Passthroughs + +No passthroughs found for this component. + +
+ +
+Attributes + +- `max-visible-items` (Number) - Override the maximum number of visible items (default: 4) +- `label` (String) - Accessible name for the Breadcrumbs component +- `menu-label` (String) - Change the default label of the action menu (default: "More items") +- `compact` (Boolean) - Compact option is useful for reducing the height of the breadcrumbs +- `value` (String) - Value for individual breadcrumb items +- `href` (String) - URL for individual breadcrumb items +- `disabled` (Boolean) - Disabled state for individual breadcrumb items + +
+ +
+Slots + +- `icon` - Change the default icon of the action menu +- `root` - Breadcrumb item to always display +- Default slot - Breadcrumb items (`sp-breadcrumb-item` elements) + +
+ +
+Modifiers + +- `--mod-breadcrumbs-action-button-color` +- `--mod-breadcrumbs-action-button-color-disabled` +- `--mod-breadcrumbs-action-button-spacing-block` +- `--mod-breadcrumbs-action-button-spacing-inline` +- `--mod-breadcrumbs-block-size` +- `--mod-breadcrumbs-focus-indicator-color` +- `--mod-breadcrumbs-focus-indicator-gap` +- `--mod-breadcrumbs-focus-indicator-thickness` +- `--mod-breadcrumbs-font-family` +- `--mod-breadcrumbs-font-family-current` +- `--mod-breadcrumbs-font-size` +- `--mod-breadcrumbs-font-size-current` +- `--mod-breadcrumbs-font-style` +- `--mod-breadcrumbs-font-weight` +- `--mod-breadcrumbs-font-weight-current` +- `--mod-breadcrumbs-icon-spacing-block` +- `--mod-breadcrumbs-inline-end` +- `--mod-breadcrumbs-inline-start` +- `--mod-breadcrumbs-inline-start-to-truncated-menu` +- `--mod-breadcrumbs-item-dragged-background` +- `--mod-breadcrumbs-item-link-border-radius` +- `--mod-breadcrumbs-line-height` +- `--mod-breadcrumbs-separator-color` +- `--mod-breadcrumbs-separator-spacing-inline` +- `--mod-breadcrumbs-text-color` +- `--mod-breadcrumbs-text-color-current` +- `--mod-breadcrumbs-text-color-disabled` +- `--mod-breadcrumbs-text-decoration-gap` +- `--mod-breadcrumbs-text-decoration-thickness` +- `--mod-breadcrumbs-text-spacing-block-end` +- `--mod-breadcrumbs-text-spacing-block-start` +- `--mod-breadcrumbs-title-spacing-block-end` +- `--mod-breadcrumbs-title-spacing-block-start` +- `--mod-heading-margin-end` +- `--mod-heading-margin-start` + +
+ +## Visual Comparison + +**Legacy Component:** + + + +**Spectrum 2 Component:** + + + +## DOM Structure Changes + +**Legacy (main branch):** + +```html + +``` + +**Spectrum 2 (spectrum-two branch):** + +```html + +``` + +## Comparison + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------ | ------------------------------ | ---------------- | +| `.spectrum-Breadcrumbs` | Root element | Implemented | +| `.spectrum-Breadcrumbs--multiline` | `compact` attribute (inverted) | Missing from WC | +| `.spectrum-Breadcrumbs--sizeL` | Size variant | Missing from WC | +| `.spectrum-Breadcrumbs-item` | Individual breadcrumb items | Implemented | +| `.spectrum-Breadcrumbs-itemLink` | Link element | Implemented | +| `.spectrum-Breadcrumbs-itemSeparator` | Separator element | Implemented | +| `.spectrum-Breadcrumbs-item > .spectrum-ActionButton` | Action button for folder icons | Implemented | +| `.spectrum-Breadcrumbs-item.is-dragged` | Dragged state | Missing from WC | +| `.spectrum-Breadcrumbs-itemLink[href]` | `href` attribute | Implemented | +| `.spectrum-Breadcrumbs-itemLink[aria-disabled="true"]` | `disabled` attribute | Implemented | +| `.spectrum-Breadcrumbs-itemLink[tabindex="0"]` | Interactive state | Implemented | +| - | `max-visible-items` attribute | Missing from CSS | +| - | `label` attribute | Missing from CSS | +| - | `menu-label` attribute | Missing from CSS | +| - | `compact` attribute | Missing from CSS | +| - | `icon` slot | Missing from CSS | +| - | `root` slot | Missing from CSS | + +## Key Structural Changes + +**Element Hierarchy Changes:** + +- No significant hierarchy changes between main and spectrum-two branches +- Maintained consistent nav > ul > li structure + +**Class Name Changes:** + +- No major class name changes +- Consistent naming convention maintained + +**Attribute Changes:** + +- Added `max-visible-items` for controlling overflow behavior +- Added `label` for accessibility labeling +- Added `menu-label` for overflow menu customization +- Added `compact` for height reduction + +**Slot/Content Changes:** + +- Added `icon` slot for customizing overflow menu icon +- Added `root` slot for persistent root breadcrumb +- Individual items use `sp-breadcrumb-item` elements + +**Migration Impact:** + +- Web component provides intelligent overflow management not present in CSS-only version +- Better accessibility with automatic aria-label management +- More sophisticated truncation and menu behavior + +### Implementation Gaps + +**CSS Features Missing from Web Component:** + +- `--multiline` variant support - web component should support multiline display mode +- `--sizeL` variant support - web component should support size variants +- `is-dragged` state support - web component should support drag and drop functionality + +**Web Component Features Missing from CSS:** + +- `max-visible-items` attribute - CSS should provide styling for overflow management +- `label` attribute - CSS should provide styling for aria-label +- `menu-label` attribute - CSS should provide styling for overflow menu +- `compact` attribute - CSS should provide compact styling variant +- `icon` slot - CSS should provide styling for custom overflow menu icons +- `root` slot - CSS should provide styling for persistent root items + +**Features Being Deprecated/Removed:** + +- None identified - component maintains backward compatibility + +### Action Items for Web Component Maintainers + +**Required Additions:** + +- Multiline variant support for breadcrumbs that wrap to multiple lines +- Size variant support (large size option) +- Drag and drop functionality for breadcrumb items +- CSS custom properties for overflow management styling + +**Required Removals:** + +- None identified + +**Breaking Changes:** + +- None identified - component provides enhanced functionality while maintaining compatibility +- Migration guidance: Enhanced overflow management and accessibility features are automatically available in web component version diff --git a/migration-roadmap/button.md b/migration-roadmap/button.md new file mode 100644 index 00000000000..c50f006d13e --- /dev/null +++ b/migration-roadmap/button.md @@ -0,0 +1,276 @@ +# Button migration roadmap + +
+CSS selectors + +- `.spectrum-Button` +- `.spectrum-Button .spectrum-Button-label` +- `.spectrum-Button .spectrum-Icon` +- `.spectrum-Button .spectrum-Icon + .spectrum-Button-label` +- `.spectrum-Button .spectrum-ProgressCircle` +- `.spectrum-Button--noWrap .spectrum-Button-label` +- `.spectrum-Button--sizeL` +- `.spectrum-Button--sizeS` +- `.spectrum-Button--sizeS.spectrum-Button--iconOnly` +- `.spectrum-Button--sizeXL` +- `.spectrum-Button-label` +- `.spectrum-Button-label:empty` +- `.spectrum-Button.is-disabled` +- `.spectrum-Button.is-focused` +- `.spectrum-Button.is-focused:after` +- `.spectrum-Button.is-pending` +- `.spectrum-Button.is-pending .spectrum-Button-label` +- `.spectrum-Button.is-pending .spectrum-Icon` +- `.spectrum-Button.is-pending .spectrum-ProgressCircle` +- `.spectrum-Button.spectrum-Button--accent` +- `.spectrum-Button.spectrum-Button--accent .spectrum-Button-label` +- `.spectrum-Button.spectrum-Button--iconOnly` +- `.spectrum-Button.spectrum-Button--iconOnly .spectrum-Icon` +- `.spectrum-Button.spectrum-Button--negative` +- `.spectrum-Button.spectrum-Button--outline` +- `.spectrum-Button.spectrum-Button--primary` +- `.spectrum-Button.spectrum-Button--primary.spectrum-Button--outline` +- `.spectrum-Button.spectrum-Button--secondary` +- `.spectrum-Button.spectrum-Button--secondary.spectrum-Button--outline` +- `.spectrum-Button.spectrum-Button--staticBlack` +- `.spectrum-Button.spectrum-Button--staticBlack.spectrum-Button--outline` +- `.spectrum-Button.spectrum-Button--staticBlack.spectrum-Button--secondary` +- `.spectrum-Button.spectrum-Button--staticBlack.spectrum-Button--secondary.spectrum-Button--outline` +- `.spectrum-Button.spectrum-Button--staticWhite` +- `.spectrum-Button.spectrum-Button--staticWhite.spectrum-Button--outline` +- `.spectrum-Button.spectrum-Button--staticWhite.spectrum-Button--secondary` +- `.spectrum-Button.spectrum-Button--staticWhite.spectrum-Button--secondary.spectrum-Button--outline` +- `.spectrum-Button::-moz-focus-inner` +- `.spectrum-Button:active` +- `.spectrum-Button:after` +- `.spectrum-Button:disabled` +- `.spectrum-Button:focus` +- `.spectrum-Button:focus-visible` +- `.spectrum-Button:focus-visible:after` +- `.spectrum-Button:hover` +- `.spectrum-Button:not(.spectrum-Button--primary, .spectrum-Button--negative, .spectrum-Button--secondary, .spectrum-Button--staticBlack, .spectrum-Button--staticWhite)` +- `.spectrum-Button:not(.spectrum-Button--primary, .spectrum-Button--negative, .spectrum-Button--secondary, .spectrum-Button--staticBlack, .spectrum-Button--staticWhite) .spectrum-Button-label` +- `.spectrum-Button[pending]` +- `.spectrum-Button[pending] .spectrum-Button-label` +- `.spectrum-Button[pending] .spectrum-Icon` +- `.spectrum-Button[pending] .spectrum-ProgressCircle` +- `a.spectrum-Button` + +
+ +
+Passthroughs + +- `--mod-progress-circle-position` +- `--mod-progress-circle-thickness` +- `--mod-progress-circle-track-border-color` +- `--mod-progress-circle-track-border-color-over-background` + +
+ +
+Attributes + +- `variant` (String) - The visual variant to apply to this button (`accent`, `primary`, `secondary`, `negative`, `white`, `black`) +- `static-color` (String) - The static color variant to use for this button (`black`, `white`) +- `treatment` (String) - The visual treatment to apply to this button (`fill`, `outline`) +- `pending` (Boolean) - Use this property to set the button into a pending state +- `pending-label` (String) - Label for pending state (default: "Pending") +- `no-wrap` (Boolean) - Disables text wrapping within the button component's label +- `size` (String) - Button size (`s`, `m`, `l`, `xl`) +- `quiet` (Boolean, deprecated) - Style this button to be less obvious (use `treatment="outline"` instead) + +
+ +
+Slots + +- Default slot - Text label of the Button +- `icon` - The icon to use for Button + +
+ +
+Modifiers + +- `--mod-button-animation-duration` +- `--mod-button-background-color-default` +- `--mod-button-background-color-disabled` +- `--mod-button-background-color-down` +- `--mod-button-background-color-focus` +- `--mod-button-background-color-hover` +- `--mod-button-border-color-default` +- `--mod-button-border-color-disabled` +- `--mod-button-border-color-down` +- `--mod-button-border-color-focus` +- `--mod-button-border-color-hover` +- `--mod-button-border-radius` +- `--mod-button-border-width` +- `--mod-button-bottom-to-text` +- `--mod-button-content-color-default` +- `--mod-button-content-color-disabled` +- `--mod-button-content-color-down` +- `--mod-button-content-color-focus` +- `--mod-button-content-color-hover` +- `--mod-button-edge-to-text` +- `--mod-button-edge-to-visual` +- `--mod-button-edge-to-visual-only` +- `--mod-button-focus-ring-border-radius` +- `--mod-button-focus-ring-color` +- `--mod-button-focus-ring-gap` +- `--mod-button-focus-ring-thickness` +- `--mod-button-font-family` +- `--mod-button-font-size` +- `--mod-button-font-weight` +- `--mod-button-height` +- `--mod-button-icon-margin-block-start` +- `--mod-button-line-height` +- `--mod-button-margin-block` +- `--mod-button-margin-left` +- `--mod-button-margin-right` +- `--mod-button-max-inline-size` +- `--mod-button-min-width` +- `--mod-button-padding-label-to-icon` +- `--mod-button-text-align` +- `--mod-button-text-align-with-icon` +- `--mod-button-top-to-icon` +- `--mod-button-top-to-text` + +
+ +## Visual Comparison + +**Legacy Component:** + + + +**Spectrum 2 Component:** + + + +## DOM Structure Changes + +**Legacy (main branch):** + +```html + +``` + +**Spectrum 2 (spectrum-two branch):** + +```html + +``` + +## Comparison + +| CSS selector | Attribute or slot | Status | +| ------------------------------- | ----------------------------- | ---------------- | +| `.spectrum-Button` | Root element | Implemented | +| `.spectrum-Button--accent` | `variant="accent"` | Implemented | +| `.spectrum-Button--primary` | `variant="primary"` | Implemented | +| `.spectrum-Button--secondary` | `variant="secondary"` | Implemented | +| `.spectrum-Button--negative` | `variant="negative"` | Implemented | +| `.spectrum-Button--outline` | `treatment="outline"` | Implemented | +| `.spectrum-Button--sizeS` | `size="s"` | Implemented | +| `.spectrum-Button--sizeL` | `size="l"` | Implemented | +| `.spectrum-Button--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-Button--staticBlack` | `static-color="black"` | Implemented | +| `.spectrum-Button--staticWhite` | `static-color="white"` | Implemented | +| `.spectrum-Button--noWrap` | `no-wrap` attribute | Implemented | +| `.spectrum-Button--iconOnly` | `hideLabel` (internal) | Implemented | +| `.spectrum-Button-label` | Default slot | Implemented | +| `.spectrum-Icon` | `icon` slot | Implemented | +| `.spectrum-ProgressCircle` | `pending` state | Implemented | +| `.spectrum-Button.is-pending` | `pending` attribute | Implemented | +| `.spectrum-Button.is-disabled` | `disabled` attribute | Implemented | +| `.spectrum-Button.is-focused` | Focus state | Implemented | +| `.spectrum-Button[pending]` | `pending` attribute | Implemented | +| `a.spectrum-Button` | Link variant | Missing from WC | +| - | `pending-label` attribute | Missing from CSS | +| - | `quiet` property (deprecated) | Missing from CSS | + +## Key Structural Changes + +**Element Hierarchy Changes:** + +- No significant hierarchy changes between main and spectrum-two branches +- Maintained consistent structure across versions + +**Class Name Changes:** + +- No major class name changes +- Static color classes maintained (staticBlack, staticWhite) + +**Attribute Changes:** + +- Added `pending` and `pending-label` attributes for loading states +- Added `no-wrap` attribute for text overflow control +- Added `static-color` attribute to replace variant-based static colors +- Added `treatment` attribute to replace `quiet` property + +**Slot/Content Changes:** + +- Added dedicated `icon` slot for icon placement +- Default slot remains for button label + +**Migration Impact:** + +- Static color variants (`white`, `black`) are being deprecated in favor of `static-color` attribute +- `quiet` property is deprecated in favor of `treatment="outline"` +- Better semantic structure with icon slot + +### Implementation Gaps + +**CSS Features Missing from Web Component:** + +- Link variant support (`a.spectrum-Button`) - web component should support href attribute + +**Web Component Features Missing from CSS:** + +- `pending-label` attribute support in CSS +- `quiet` property (deprecated) - should be removed + +**Features Being Deprecated/Removed:** + +- `quiet` property - replaced by `treatment="outline"` +- Static color variants (`white`, `black`) - replaced by `static-color` attribute +- `cta` variant - replaced by `accent` variant +- `overBackground` variant - replaced by `static-color="white"` with `treatment="outline"` + +### Action Items for Web Component Maintainers + +**Required Additions:** + +- Link variant support - implement href attribute handling for anchor button functionality + +**Required Removals:** + +- Complete deprecation warnings for `quiet`, static color variants, and deprecated variant values +- Remove deprecated properties in next major version + +**Breaking Changes:** + +- Migration from deprecated variants requires updating component usage +- Link button functionality needs implementation for href support +- Migration guidance: Replace `quiet` with `treatment="outline"`, replace static color variants with `static-color` attribute diff --git a/migration-roadmap/illustrated-message.md b/migration-roadmap/illustrated-message.md new file mode 100644 index 00000000000..d5bd614abf4 --- /dev/null +++ b/migration-roadmap/illustrated-message.md @@ -0,0 +1,216 @@ +# Illustrated Message migration roadmap + +
+CSS selectors + +- `.spectrum-IllustratedMessage` +- `.spectrum-IllustratedMessage--horizontal` +- `.spectrum-IllustratedMessage--horizontal .spectrum-IllustratedMessage-illustration` +- `.spectrum-IllustratedMessage--sizeL` +- `.spectrum-IllustratedMessage--sizeL:lang(ja)` +- `.spectrum-IllustratedMessage--sizeL:lang(ko)` +- `.spectrum-IllustratedMessage--sizeL:lang(zh)` +- `.spectrum-IllustratedMessage--sizeS` +- `.spectrum-IllustratedMessage--sizeS:lang(ja)` +- `.spectrum-IllustratedMessage--sizeS:lang(ko)` +- `.spectrum-IllustratedMessage--sizeS:lang(zh)` +- `.spectrum-IllustratedMessage-actions` +- `.spectrum-IllustratedMessage-content` +- `.spectrum-IllustratedMessage-description` +- `.spectrum-IllustratedMessage-heading` +- `.spectrum-IllustratedMessage-illustration` +- `.spectrum-IllustratedMessage:lang(ja)` +- `.spectrum-IllustratedMessage:lang(ko)` +- `.spectrum-IllustratedMessage:lang(zh)` + +
+ +
+Passthroughs + +- `--mod-buttongroup-justify-content` + +
+ +
+Attributes + +- `heading` (String) - Headline text for the message +- `description` (String) - Description text for the illustration + +
+ +
+Slots + +- Default slot - The SVG that represents the illustration +- `heading` - Headline for the message +- `description` - Description text for the illustration + +
+ +
+Modifiers + +- `--mod-illustrated-message-description-color` +- `--mod-illustrated-message-description-font-family` +- `--mod-illustrated-message-description-font-size` +- `--mod-illustrated-message-description-font-style` +- `--mod-illustrated-message-description-font-weight` +- `--mod-illustrated-message-description-line-height` +- `--mod-illustrated-message-description-pointer-events` +- `--mod-illustrated-message-description-position` +- `--mod-illustrated-message-description-to-action` +- `--mod-illustrated-message-description-z-index` +- `--mod-illustrated-message-display` +- `--mod-illustrated-message-heading-to-description` +- `--mod-illustrated-message-horizontal-maximum-width` +- `--mod-illustrated-message-illustrated-inline-size` +- `--mod-illustrated-message-illustration-block-size` +- `--mod-illustrated-message-illustration-color` +- `--mod-illustrated-message-illustration-size` +- `--mod-illustrated-message-illustration-to-heading` +- `--mod-illustrated-message-pointer-events` +- `--mod-illustrated-message-title-color` +- `--mod-illustrated-message-title-font-family` +- `--mod-illustrated-message-title-font-size` +- `--mod-illustrated-message-title-font-style` +- `--mod-illustrated-message-title-font-weight` +- `--mod-illustrated-message-title-line-height` +- `--mod-illustrated-message-vertical-maximum-width` + +
+ +## Visual Comparison + +**Legacy Component:** + + + +**Spectrum 2 Component:** + + + +## DOM Structure Changes + +**Legacy (main branch):** + +```html +
+ [illustration] +
+ [heading] +
+
+ [description content] +
+
+``` + +**Spectrum 2 (spectrum-two branch):** + +```html +
+ [illustration] +
+ [heading] +
+
+ [description content] +
+
+``` + +## Comparison + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------- | +| `.spectrum-IllustratedMessage` | Root element | Implemented | +| `.spectrum-IllustratedMessage--horizontal` | Horizontal layout variant | Missing from WC | +| `.spectrum-IllustratedMessage--sizeL` | Large size variant | Missing from WC | +| `.spectrum-IllustratedMessage--sizeS` | Small size variant | Missing from WC | +| `.spectrum-IllustratedMessage-illustration` | Default slot | Implemented | +| `.spectrum-IllustratedMessage-heading` | `heading` slot | Implemented | +| `.spectrum-IllustratedMessage-description` | `description` slot | Implemented | +| `.spectrum-IllustratedMessage-content` | Content container | Missing from WC | +| `.spectrum-IllustratedMessage-actions` | Actions container | Missing from WC | +| `.spectrum-IllustratedMessage:lang(ja)`, `.spectrum-IllustratedMessage:lang(ko)`, `.spectrum-IllustratedMessage:lang(zh)` | Language-specific styling | Implemented | +| `.spectrum-IllustratedMessage--sizeL:lang(ja)`, etc. | Size + language combinations | Missing from WC | +| - | `heading` attribute | Missing from CSS | +| - | `description` attribute | Missing from CSS | + +## Key Structural Changes + +**Element Hierarchy Changes:** + +- No significant hierarchy changes between main and spectrum-two branches +- Maintained consistent illustration > heading > description structure + +**Class Name Changes:** + +- No major class name changes +- Consistent naming convention maintained + +**Attribute Changes:** + +- Added `heading` attribute for setting heading text +- Added `description` attribute for setting description text +- No size variants exposed as attributes + +**Slot/Content Changes:** + +- Added `heading` slot for heading content +- Added `description` slot for description content +- Default slot for illustration SVG content + +**Migration Impact:** + +- Web component provides simplified API with attribute-based content +- Missing size and layout variants may limit design flexibility +- Simplified structure reduces complexity but may limit customization + +### Implementation Gaps + +**CSS Features Missing from Web Component:** + +- Horizontal layout variant support - web component should support `horizontal` layout +- Size variant support - web component should support size options (`sizeS`, `sizeL`) +- Content container support - web component should provide content grouping +- Actions container support - web component should support action buttons/elements +- Language + size combination styling + +**Web Component Features Missing from CSS:** + +- `heading` attribute - CSS should provide styling for heading attribute content +- `description` attribute - CSS should provide styling for description attribute content + +**Features Being Deprecated/Removed:** + +- None identified - component maintains basic functionality + +### Action Items for Web Component Maintainers + +**Required Additions:** + +- Horizontal layout variant support for side-by-side illustration and content +- Size variant support (small, medium, large) for different use cases +- Content container wrapper for better content organization +- Actions slot/container for buttons and interactive elements +- Size attribute with responsive design considerations + +**Required Removals:** + +- None identified + +**Breaking Changes:** + +- Missing layout and size variants limit design flexibility compared to CSS version +- Migration guidance: Consider adding size and layout attributes to match CSS variant capabilities diff --git a/migration-roadmap/search.md b/migration-roadmap/search.md new file mode 100644 index 00000000000..15d72f6ed09 --- /dev/null +++ b/migration-roadmap/search.md @@ -0,0 +1,278 @@ +# Search migration roadmap + +
+CSS selectors + +- `.spectrum-Search` +- `.spectrum-Search .spectrum-HelpText` +- `.spectrum-Search .spectrum-Search-clearButton .spectrum-ClearButton-fill` +- `.spectrum-Search .spectrum-Search-textfield` +- `.spectrum-Search .spectrum-Search-textfield .spectrum-Search-input` +- `.spectrum-Search--sizeL` +- `.spectrum-Search--sizeS` +- `.spectrum-Search--sizeXL` +- `.spectrum-Search-clearButton` +- `.spectrum-Search-clearButton .spectrum-ClearButton-fill` +- `.spectrum-Search-icon` +- `.spectrum-Search-input` +- `.spectrum-Search-input::-webkit-search-cancel-button` +- `.spectrum-Search-input::-webkit-search-decoration` +- `.spectrum-Search-textfield` +- `.spectrum-Search-textfield.is-disabled .spectrum-Search-icon` +- `.spectrum-Search-textfield.is-disabled:hover .spectrum-Search-icon` +- `.spectrum-Search-textfield.is-focused .spectrum-Search-icon` +- `.spectrum-Search-textfield.is-focused:hover .spectrum-Search-icon` +- `.spectrum-Search-textfield.is-keyboardFocused .spectrum-Search-icon` +- `.spectrum-Search-textfield:hover .spectrum-Search-icon` +- `.spectrum-Search.is-collapsed` +- `.spectrum-Search.is-disabled .spectrum-Search-clearButton` +- `.spectrum-Search.is-expanded` +- `.spectrum-Search:lang(ja)`, `.spectrum-Search:lang(ko)`, `.spectrum-Search:lang(zh)` + +
+ +
+Passthroughs + +- `--mod-textfield-background-color` +- `--mod-textfield-background-color-disabled` +- `--mod-textfield-border-color` +- `--mod-textfield-border-color-disabled` +- `--mod-textfield-border-color-focus` +- `--mod-textfield-border-color-focus-hover` +- `--mod-textfield-border-color-hover` +- `--mod-textfield-border-color-keyboard-focus` +- `--mod-textfield-border-width` +- `--mod-textfield-corner-radius` +- `--mod-textfield-focus-indicator-color` +- `--mod-textfield-focus-indicator-gap` +- `--mod-textfield-focus-indicator-width` +- `--mod-textfield-font-family` +- `--mod-textfield-font-weight` +- `--mod-textfield-placeholder-font-size` +- `--mod-textfield-text-color-default` +- `--mod-textfield-text-color-disabled` +- `--mod-textfield-text-color-focus` +- `--mod-textfield-text-color-focus-hover` +- `--mod-textfield-text-color-hover` +- `--mod-textfield-text-color-keyboard-focus` + +
+ +
+Attributes + +- `action` (String) - Form action attribute +- `label` (String) - Label for the search field (default: "Search") +- `method` (String) - Form method (`get`, `post`, `dialog`) +- `placeholder` (String) - Placeholder text (default: "Search") +- `holdValueOnEscape` (Boolean) - Whether to hold the value when Escape is pressed +- `value` (String) - Current search input value +- `size` (String) - Search field size (`s`, `m`, `l`, `xl`) +- `disabled` (Boolean) - Whether the search field is disabled +- `invalid` (Boolean) - Whether the search field is in an invalid state +- `quiet` (Boolean) - Whether to use the quiet variant + +
+ +
+Slots + +- `help-text` - Default or non-negative help text to associate to your form element +- `negative-help-text` - Negative help text to associate to your form element when `invalid` + +
+ +
+Modifiers + +- `--mod-search-background-color` +- `--mod-search-background-color-disabled` +- `--mod-search-block-size` +- `--mod-search-border-color-default` +- `--mod-search-border-color-disabled` +- `--mod-search-border-color-focus` +- `--mod-search-border-color-focus-hover` +- `--mod-search-border-color-hover` +- `--mod-search-border-color-key-focus` +- `--mod-search-border-radius` +- `--mod-search-border-width` +- `--mod-search-bottom-to-text` +- `--mod-search-button-inline-size` +- `--mod-search-collapsed-animation-duration` +- `--mod-search-color-default` +- `--mod-search-color-disabled` +- `--mod-search-color-focus` +- `--mod-search-color-focus-hover` +- `--mod-search-color-hover` +- `--mod-search-color-key-focus` +- `--mod-search-edge-to-visual` +- `--mod-search-focus-indicator-color` +- `--mod-search-focus-indicator-gap` +- `--mod-search-focus-indicator-thickness` +- `--mod-search-font-family` +- `--mod-search-font-style` +- `--mod-search-font-weight` +- `--mod-search-icon-size` +- `--mod-search-inline-size` +- `--mod-search-line-height` +- `--mod-search-min-inline-size` +- `--mod-search-text-to-icon` +- `--mod-search-to-help-text` +- `--mod-search-top-to-icon` +- `--mod-search-top-to-text` + +
+ +## Visual Comparison + +**Legacy Component:** + + + +**Spectrum 2 Component:** + + + +## DOM Structure Changes + +**Legacy (main branch):** + +```html +
+
+ + +
+ +
[help text]
+
+``` + +**Spectrum 2 (spectrum-two branch):** + +```html +
+
+ + +
+ +
[help text]
+
+``` + +## Comparison + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------- | ----------------------------- | ---------------- | +| `.spectrum-Search` | Root element | Implemented | +| `.spectrum-Search--sizeS` | `size="s"` | Implemented | +| `.spectrum-Search--sizeL` | `size="l"` | Implemented | +| `.spectrum-Search--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-Search-textfield` | Textfield wrapper | Implemented | +| `.spectrum-Search-input` | Input element | Implemented | +| `.spectrum-Search-icon` | Search icon | Implemented | +| `.spectrum-Search-clearButton` | Clear button | Implemented | +| `.spectrum-Search .spectrum-HelpText` | Help text element | Implemented | +| `.spectrum-Search.is-collapsed` | Collapsed state | Missing from WC | +| `.spectrum-Search.is-expanded` | Expanded state | Missing from WC | +| `.spectrum-Search.is-disabled` | `disabled` attribute | Implemented | +| `.spectrum-Search-textfield.is-focused` | Focus state | Implemented | +| `.spectrum-Search-textfield.is-keyboardFocused` | Keyboard focus state | Implemented | +| `.spectrum-Search:lang(ja)`, `.spectrum-Search:lang(ko)`, `.spectrum-Search:lang(zh)` | Language-specific styling | Implemented | +| - | `action` attribute | Missing from CSS | +| - | `method` attribute | Missing from CSS | +| - | `holdValueOnEscape` attribute | Missing from CSS | +| - | `help-text` slot | Missing from CSS | +| - | `negative-help-text` slot | Missing from CSS | + +## Key Structural Changes + +**Element Hierarchy Changes:** + +- No significant hierarchy changes between main and spectrum-two branches +- Maintained consistent form > textfield > input structure + +**Class Name Changes:** + +- No major class name changes +- Consistent naming convention maintained + +**Attribute Changes:** + +- Added `action` and `method` attributes for form functionality +- Added `holdValueOnEscape` for controlling escape key behavior +- Added `label` attribute for accessibility +- Extended Textfield functionality with search-specific features + +**Slot/Content Changes:** + +- Added `help-text` slot for descriptive text +- Added `negative-help-text` slot for error messaging +- Inherits all Textfield slots and functionality + +**Migration Impact:** + +- Search component extends Textfield providing all textfield functionality +- Enhanced form handling with action and method support +- Better accessibility with automatic labeling + +### Implementation Gaps + +**CSS Features Missing from Web Component:** + +- Collapsed/expanded state support - web component should support animated expansion/collapse +- More sophisticated state management for search interactions + +**Web Component Features Missing from CSS:** + +- `action` attribute - CSS should provide styling for form action states +- `method` attribute - CSS should provide styling based on form method +- `holdValueOnEscape` attribute - CSS should provide styling for this behavior state +- Help text slots - CSS should provide styling for slotted help text elements + +**Features Being Deprecated/Removed:** + +- None identified - component maintains backward compatibility + +### Action Items for Web Component Maintainers + +**Required Additions:** + +- Collapsed/expanded state functionality for search field animations +- Enhanced form integration with action and method handling +- Better state management for search-specific interactions + +**Required Removals:** + +- None identified + +**Breaking Changes:** + +- None identified - component extends existing Textfield functionality +- Migration guidance: Search component provides enhanced functionality while maintaining Textfield compatibility From 16d7b145c62d64b10a5dc06c9b5c54d161bc15a2 Mon Sep 17 00:00:00 2001 From: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com> Date: Thu, 18 Sep 2025 05:40:19 -1000 Subject: [PATCH 3/9] docs: barebones component analysis docs, prompt updates (#5720) --- migration-roadmap/alert-banner.md | 261 +++++++++++++-------- migration-roadmap/asset.md | 195 ++++++++++++++++ migration-roadmap/badge.md | 328 +++++++++++++++++++++++++++ migration-roadmap/cursor_prompt.md | 282 +++++++++++------------ migration-roadmap/divider.md | 148 ++++++++++++ migration-roadmap/progress-circle.md | 234 +++++++++++++++++++ migration-roadmap/status-light.md | 261 +++++++++++++++++++++ 7 files changed, 1458 insertions(+), 251 deletions(-) create mode 100644 migration-roadmap/asset.md create mode 100644 migration-roadmap/badge.md create mode 100644 migration-roadmap/divider.md create mode 100644 migration-roadmap/progress-circle.md create mode 100644 migration-roadmap/status-light.md diff --git a/migration-roadmap/alert-banner.md b/migration-roadmap/alert-banner.md index bff41b1fc7f..f78e1b34de2 100644 --- a/migration-roadmap/alert-banner.md +++ b/migration-roadmap/alert-banner.md @@ -1,5 +1,9 @@ # Alert Banner migration roadmap +## Component specifications + +### CSS +
CSS selectors @@ -12,7 +16,9 @@ - `.spectrum-AlertBanner-text` - `.spectrum-AlertBanner.is-open` - `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` -- `.spectrum-AlertBanner:lang(ja)`, `.spectrum-AlertBanner:lang(ko)`, `.spectrum-AlertBanner:lang(zh)` +- `.spectrum-AlertBanner:lang(ja)` +- `.spectrum-AlertBanner:lang(ko)` +- `.spectrum-AlertBanner:lang(zh)`
@@ -26,23 +32,6 @@
-
-Attributes - -- `open` (Boolean) - Controls the display of the alert banner -- `dismissible` (Boolean) - Whether to include an icon-only close button to dismiss the alert banner -- `variant` (String) - The variant applies specific styling when set to `negative`, `neutral`, or `info` - -
- -
-Slots - -- Default slot - The alert banner text context -- `action` - Slot for the button element that surfaces the contextual action a user can take - -
-
Modifiers @@ -75,31 +64,81 @@
-## Visual Comparison +### SWC + +
+Attributes + +- `open` (Boolean) - Controls the display of the alert banner +- `dismissible` (Boolean) - Whether to include an icon-only close button to dismiss the alert banner +- `variant` (String) - The variant applies specific styling when set to `negative` or `info`; `variant` attribute is removed when it's passed an invalid variant. Valid values: `neutral`, `info`, `negative` -**Legacy Component:** +
- +
+Slots -**Spectrum 2 Component:** +- Default slot - The alert banner text context +- `action` - Slot for the button element that surfaces the contextual action a user can take - +
-## DOM Structure Changes +## Comparison -**Legacy (main branch):** +### DOM structure changes + +
+Spectrum Web Components: + +```html + + #shadow-root + +
+ +
+ +``` + +
+ +
+Legacy (CSS main branch): ```html -
+
- [icon] -

[text]

+ +

+ Your trial will expire in 3 days +

@@ -109,107 +148,135 @@
``` -**Spectrum 2 (spectrum-two branch):** +
+ +
+Spectrum 2 (CSS spectrum-two branch): ```html -
+
- [icon] -

[text]

+ +

+ Your trial will expire in 3 days +

``` -## Comparison - -| CSS selector | Attribute or slot | Status | -| ---------------------------------------------------------------------------------------------------- | ------------------------- | ---------------- | -| `.spectrum-AlertBanner` | Root element | Implemented | -| `.spectrum-AlertBanner--info` | `variant="info"` | Implemented | -| `.spectrum-AlertBanner--negative` | `variant="negative"` | Implemented | -| `.spectrum-AlertBanner-body` | - | Implemented | -| `.spectrum-AlertBanner-content` | - | Implemented | -| `.spectrum-AlertBanner-icon` | - | Implemented | -| `.spectrum-AlertBanner-text` | Default slot | Implemented | -| `.spectrum-AlertBanner.is-open` | `open` attribute | Implemented | -| `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` | `dismissible` attribute | Implemented | -| `.spectrum-AlertBanner:lang(ja)`, `.spectrum-AlertBanner:lang(ko)`, `.spectrum-AlertBanner:lang(zh)` | Language-specific styling | Implemented | -| - | `action` slot | Missing from CSS | -| - | `dismissible` attribute | Missing from CSS | - -## Key Structural Changes - -**Element Hierarchy Changes:** - -- Removed divider element between content and close button in Spectrum 2 -- Simplified end container structure - -**Class Name Changes:** - -- No major class name changes -- Maintained consistent naming convention - -**Attribute Changes:** - -- Added `open` attribute for controlling display state -- Added `dismissible` attribute for controlling close button visibility - -**Slot/Content Changes:** - -- Added dedicated `action` slot for button elements -- Default slot remains for text content - -**Migration Impact:** - -- Removal of divider element will affect visual separation between content and close button -- Web component provides better semantic structure with slots +
-### Implementation Gaps +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff +
+-
+ +
+``` -**CSS Features Missing from Web Component:** +
-- All CSS selectors are properly implemented in the web component +### CSS => SWC mapping -**Web Component Features Missing from CSS:** +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------------------ | --------------------------------------- | ----------- | +| `.spectrum-AlertBanner` | Base component, `variant="neutral"` | Implemented | +| `.spectrum-AlertBanner--info` | `variant="info"` | Implemented | +| `.spectrum-AlertBanner--negative` | `variant="negative"` | Implemented | +| `.spectrum-AlertBanner.is-open` | `open` attribute | Implemented | +| `.spectrum-AlertBanner-text` | Default slot within `.text` | Implemented | +| `.spectrum-AlertBanner-icon` | Icon rendering (info/negative variants) | Implemented | +| `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` | `dismissible` attribute | Implemented | +| `.spectrum-AlertBanner:lang(ja), .spectrum-AlertBanner:lang(ko), .spectrum-AlertBanner:lang(zh)` | Language-specific styling | Implemented | +| `.spectrum-AlertBanner-body` | `.body` | Implemented | +| `.spectrum-AlertBanner-content` | `.content` | Implemented | +| `.spectrum-AlertBanner-end` | `.end` | Implemented | +| Corresponds to `.spectrum-Button` within `.spectrum-AlertBanner` | `action` slot | Implemented | -- `action` slot - needs CSS support for slotted action button positioning -- `dismissible` attribute - CSS should provide conditional styling based on this attribute +Note: the `neutral` variant of Alert banner is the default variant in both CSS and SWC. -**Features Being Deprecated/Removed:** +## Summary of changes -- Divider element between content and close button has been removed in Spectrum 2 +### CSS => SWC implementation gaps -### Action Items for Web Component Maintainers +**No missing features.** All CSS selectors have corresponding web component implementations: -**Required Additions:** +- **Variants**: `--info` → `variant="info"`, `--negative` → `variant="negative"` +- **State**: `.is-open` → `open` attribute +- **Content**: Text and icon selectors → default slot and programmatic icon rendering +- **Dismissible**: Close button presence → `dismissible` attribute +- **Action slot**: Available in SWC but not in CSS templates -- No major additions needed - component is well-aligned with CSS implementation +### CSS Spectrum 2 changes -**Required Removals:** +**Divider element removed in spectrum-two branch**: The `
` element is no longer included in the close button section. The spectrum-two branch template only includes the close button without the divider separator. -- None identified +This divider does not appear to be present in SWC, and therefore will not need to be removed for Spectrum 2. -**Breaking Changes:** +## Resources -- Divider removal may affect existing implementations expecting visual separation -- Migration guidance: Update expectations for visual separation between content and close button +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2652) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-alert-banner--docs) diff --git a/migration-roadmap/asset.md b/migration-roadmap/asset.md new file mode 100644 index 00000000000..393dab00bba --- /dev/null +++ b/migration-roadmap/asset.md @@ -0,0 +1,195 @@ +# Asset migration roadmap + +Note: This component has no S2 design spec, and therefore the CSS _has not_ been migrated to S2. + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-Asset` +- `.spectrum-Asset-file` +- `.spectrum-Asset-fileBackground` +- `.spectrum-Asset-fileOutline` +- `.spectrum-Asset-folder` +- `.spectrum-Asset-folderBackground` +- `.spectrum-Asset-folderOutline` +- `.spectrum-Asset-image` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-asset-file-background-color` +- `--mod-asset-folder-background-color` +- `--mod-asset-icon-margin` +- `--mod-asset-icon-max-width` +- `--mod-asset-icon-min-width` +- `--mod-asset-icon-outline-color` + +
+ +### SWC + +
+Attributes + +- `variant` (file, folder) +- `label` (string) + +
+ +
+Slots + +- Default slot (for custom content when variant is not file or folder) + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components: + +```html + + + + + + + + + + + + + + + + + + + Custom content + +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ + + + +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + + + +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**No differences found between main and spectrum-two branches.** + +
+ +### CSS => SWC mapping + +#### Non-variant selectors + +| CSS selector | Attribute or slot | Status | +| ------------------------ | ----------------------------- | ---------------- | +| `.spectrum-Asset` | `:host` | Implemented | +| `.spectrum-Asset-file` | `variant='file'`, `.file` | Implemented | +| `.spectrum-Asset-folder` | `variant='folder'`, `.folder` | Implemented | +| `.spectrum-Asset-image` | default `` content | Implemented | +| | `label` | Missing from CSS | + +#### Variant-specific selectors + +These CSS selectors correspond to the class names used in the SVG path elements within the Asset component's `file()` and `folder()` template functions. + +| CSS selector | Attribute or slot | Status | +| ---------------------------------- | ------------------- | ----------- | +| `.spectrum-Asset-fileBackground` | `.fileBackground` | Implemented | +| `.spectrum-Asset-fileOutline` | `.fileOutline` | Implemented | +| `.spectrum-Asset-folderBackground` | `.folderBackground` | Implemented | +| `.spectrum-Asset-folderOutline` | `.folderOutline` | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +The asset component has a relatively straightforward mapping between CSS and web components. There do not appear to be any significant differences from CSS that we might consider bringing into 2nd gen web components. + +**Implementation differences:** + +- **Variant system**: Web component uses a `variant` attribute (file, folder) to determine which SVG to render, while CSS uses preset parameters in templates +- **Image support**: CSS uses a dedicated `image` parameter that renders ``, while web component uses the default slot for custom content including images + +### CSS Spectrum 2 changes + +No differences found between the legacy (CSS main) and Spectrum 2 (CSS spectrum-two) branches, as no component migration has been done. + +## Resources + +- [CSS Storybook](https://opensource.adobe.com/spectrum-css/?path=/docs/components-asset--docs) diff --git a/migration-roadmap/badge.md b/migration-roadmap/badge.md new file mode 100644 index 00000000000..3acc770461c --- /dev/null +++ b/migration-roadmap/badge.md @@ -0,0 +1,328 @@ +# Badge migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-Badge` +- `.spectrum-Badge--accent` +- `.spectrum-Badge--blue` +- `.spectrum-Badge--brown` +- `.spectrum-Badge--celery` +- `.spectrum-Badge--chartreuse` +- `.spectrum-Badge--cinnamon` +- `.spectrum-Badge--cyan` +- `.spectrum-Badge--fixed-block-end` +- `.spectrum-Badge--fixed-block-start` +- `.spectrum-Badge--fixed-inline-end` +- `.spectrum-Badge--fixed-inline-start` +- `.spectrum-Badge--fuchsia` +- `.spectrum-Badge--gray` +- `.spectrum-Badge--green` +- `.spectrum-Badge--indigo` +- `.spectrum-Badge--informative` +- `.spectrum-Badge--magenta` +- `.spectrum-Badge--negative` +- `.spectrum-Badge--neutral` +- `.spectrum-Badge--notice` +- `.spectrum-Badge--orange` +- `.spectrum-Badge--pink` +- `.spectrum-Badge--positive` +- `.spectrum-Badge--purple` +- `.spectrum-Badge--red` +- `.spectrum-Badge--seafoam` +- `.spectrum-Badge--silver` +- `.spectrum-Badge--sizeL` +- `.spectrum-Badge--sizeS` +- `.spectrum-Badge--sizeXL` +- `.spectrum-Badge--style-outline.spectrum-Badge--accent` +- `.spectrum-Badge--style-outline.spectrum-Badge--informative` +- `.spectrum-Badge--style-outline.spectrum-Badge--negative` +- `.spectrum-Badge--style-outline.spectrum-Badge--neutral` +- `.spectrum-Badge--style-outline.spectrum-Badge--notice` +- `.spectrum-Badge--style-outline.spectrum-Badge--positive` +- `.spectrum-Badge--style-outline:is(.spectrum-Badge--neutral, .spectrum-Badge--accent, .spectrum-Badge--informative, .spectrum-Badge--negative, .spectrum-Badge--positive, .spectrum-Badge--notice)` +- `.spectrum-Badge--style-subtle` +- `.spectrum-Badge--style-subtle.spectrum-Badge--accent` +- `.spectrum-Badge--style-subtle.spectrum-Badge--blue` +- `.spectrum-Badge--style-subtle.spectrum-Badge--brown` +- `.spectrum-Badge--style-subtle.spectrum-Badge--celery` +- `.spectrum-Badge--style-subtle.spectrum-Badge--chartreuse` +- `.spectrum-Badge--style-subtle.spectrum-Badge--cinnamon` +- `.spectrum-Badge--style-subtle.spectrum-Badge--cyan` +- `.spectrum-Badge--style-subtle.spectrum-Badge--fuchsia` +- `.spectrum-Badge--style-subtle.spectrum-Badge--gray` +- `.spectrum-Badge--style-subtle.spectrum-Badge--green` +- `.spectrum-Badge--style-subtle.spectrum-Badge--indigo` +- `.spectrum-Badge--style-subtle.spectrum-Badge--informative` +- `.spectrum-Badge--style-subtle.spectrum-Badge--magenta` +- `.spectrum-Badge--style-subtle.spectrum-Badge--negative` +- `.spectrum-Badge--style-subtle.spectrum-Badge--neutral` +- `.spectrum-Badge--style-subtle.spectrum-Badge--notice` +- `.spectrum-Badge--style-subtle.spectrum-Badge--orange` +- `.spectrum-Badge--style-subtle.spectrum-Badge--pink` +- `.spectrum-Badge--style-subtle.spectrum-Badge--positive` +- `.spectrum-Badge--style-subtle.spectrum-Badge--purple` +- `.spectrum-Badge--style-subtle.spectrum-Badge--red` +- `.spectrum-Badge--style-subtle.spectrum-Badge--seafoam` +- `.spectrum-Badge--style-subtle.spectrum-Badge--silver` +- `.spectrum-Badge--style-subtle.spectrum-Badge--turquoise` +- `.spectrum-Badge--style-subtle.spectrum-Badge--yellow` +- `.spectrum-Badge--turquoise` +- `.spectrum-Badge--yellow` +- `.spectrum-Badge-icon` +- `.spectrum-Badge-icon + .spectrum-Badge-label` +- `.spectrum-Badge-icon--no-label` +- `.spectrum-Badge-label` +- `.spectrum-Badge-label:lang(ja)` +- `.spectrum-Badge-label:lang(ko)` +- `.spectrum-Badge-label:lang(zh)` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-badge-background-color-accent` +- `--mod-badge-background-color-blue` +- `--mod-badge-background-color-brown` +- `--mod-badge-background-color-celery` +- `--mod-badge-background-color-chartreuse` +- `--mod-badge-background-color-cinnamon` +- `--mod-badge-background-color-cyan` +- `--mod-badge-background-color-default` +- `--mod-badge-background-color-fuchsia` +- `--mod-badge-background-color-gray` +- `--mod-badge-background-color-green` +- `--mod-badge-background-color-indigo` +- `--mod-badge-background-color-informative` +- `--mod-badge-background-color-magenta` +- `--mod-badge-background-color-negative` +- `--mod-badge-background-color-notice` +- `--mod-badge-background-color-orange` +- `--mod-badge-background-color-pink` +- `--mod-badge-background-color-positive` +- `--mod-badge-background-color-purple` +- `--mod-badge-background-color-red` +- `--mod-badge-background-color-seafoam` +- `--mod-badge-background-color-silver` +- `--mod-badge-background-color-turquoise` +- `--mod-badge-background-color-yellow` +- `--mod-badge-border-color` +- `--mod-badge-border-width` +- `--mod-badge-corner-radius` +- `--mod-badge-font-size` +- `--mod-badge-height` +- `--mod-badge-icon-only-spacing-horizontal` +- `--mod-badge-icon-spacing-horizontal` +- `--mod-badge-icon-spacing-vertical-top` +- `--mod-badge-icon-text-spacing` +- `--mod-badge-label-icon-color` +- `--mod-badge-label-spacing-horizontal` +- `--mod-badge-label-spacing-vertical-bottom` +- `--mod-badge-label-spacing-vertical-top` +- `--mod-badge-line-height` +- `--mod-badge-line-height-cjk` +- `--mod-badge-outline-background-color-default` +- `--mod-badge-outline-border-color-accent` +- `--mod-badge-outline-border-color-informative` +- `--mod-badge-outline-border-color-negative` +- `--mod-badge-outline-border-color-neutral` +- `--mod-badge-outline-border-color-notice` +- `--mod-badge-outline-border-color-positive` +- `--mod-badge-outline-label-icon-color` +- `--mod-badge-subtle-background-color-accent` +- `--mod-badge-subtle-background-color-blue` +- `--mod-badge-subtle-background-color-brown` +- `--mod-badge-subtle-background-color-celery` +- `--mod-badge-subtle-background-color-chartreuse` +- `--mod-badge-subtle-background-color-cinnamon` +- `--mod-badge-subtle-background-color-cyan` +- `--mod-badge-subtle-background-color-default` +- `--mod-badge-subtle-background-color-fuchsia` +- `--mod-badge-subtle-background-color-gray` +- `--mod-badge-subtle-background-color-green` +- `--mod-badge-subtle-background-color-indigo` +- `--mod-badge-subtle-background-color-informative` +- `--mod-badge-subtle-background-color-magenta` +- `--mod-badge-subtle-background-color-negative` +- `--mod-badge-subtle-background-color-notice` +- `--mod-badge-subtle-background-color-orange` +- `--mod-badge-subtle-background-color-pink` +- `--mod-badge-subtle-background-color-positive` +- `--mod-badge-subtle-background-color-purple` +- `--mod-badge-subtle-background-color-red` +- `--mod-badge-subtle-background-color-seafoam` +- `--mod-badge-subtle-background-color-silver` +- `--mod-badge-subtle-background-color-turquoise` +- `--mod-badge-subtle-background-color-yellow` +- `--mod-badge-subtle-label-icon-color` +- `--mod-badge-workflow-icon-size` + +
+ +### SWC + +
+Attributes + +- `variant` - Badge variant (accent, neutral, informative, positive, negative, notice, fuchsia, indigo, magenta, purple, seafoam, yellow, gray, red, orange, chartreuse, celery, green, cyan, blue) +- `fixed` - Fixed positioning (inline-start, inline-end, block-start, block-end) +- `size` - Badge size (s, m, l, xl) + +
+ +
+Slots + +- Default slot - Text label of the badge +- `icon` - Optional icon that appears to the left of the label + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components: + +```html + + #shadow-root + +
+ +
+ +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ +
Label text
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ +
Label text
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +No significant structural changes. + +
+ +### CSS => SWC mapping + +#### Non-color selectors + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------------------ | ------------------------- | ---------------------------- | +| `.spectrum-Badge--sizeS` | `size="s"` | Implemented | +| `.spectrum-Badge--sizeL` | `size="l"` | Implemented | +| `.spectrum-Badge--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-Badge--fixed-inline-start` | `fixed="inline-start"` | Implemented | +| `.spectrum-Badge--fixed-inline-end` | `fixed="inline-end"` | Implemented | +| `.spectrum-Badge--fixed-block-start` | `fixed="block-start"` | Implemented | +| `.spectrum-Badge--fixed-block-end` | `fixed="block-end"` | Implemented | +| `.spectrum-Badge` | Base component | Implemented | +| `.spectrum-Badge-icon` | `icon` slot | Implemented | +| `.spectrum-Badge-label` | Default slot | Implemented | +| `.spectrum-Badge-label:lang(ja), .spectrum-Badge-label:lang(ko), .spectrum-Badge-label:lang(zh)` | Language-specific styling | Implemented | +| `.spectrum-Badge--style-outline` | `style="outline"` | Missing from WC (new for S2) | +| `.spectrum-Badge--style-subtle` | `style="subtle"` | Missing from WC (new for S2) | + +#### Color/variant selectors + +| CSS selector | Attribute or slot | Status | +| ------------------------------ | ----------------------- | ---------------------------- | +| `.spectrum-Badge--accent` | `variant="accent"` | Implemented | +| `.spectrum-Badge--blue` | `variant="blue"` | Implemented | +| `.spectrum-Badge--celery` | `variant="celery"` | Implemented | +| `.spectrum-Badge--chartreuse` | `variant="chartreuse"` | Implemented | +| `.spectrum-Badge--cyan` | `variant="cyan"` | Implemented | +| `.spectrum-Badge--fuchsia` | `variant="fuchsia"` | Implemented | +| `.spectrum-Badge--gray` | `variant="gray"` | Implemented | +| `.spectrum-Badge--green` | `variant="green"` | Implemented | +| `.spectrum-Badge--indigo` | `variant="indigo"` | Implemented | +| `.spectrum-Badge--informative` | `variant="informative"` | Implemented | +| `.spectrum-Badge--magenta` | `variant="magenta"` | Implemented | +| `.spectrum-Badge--negative` | `variant="negative"` | Implemented | +| `.spectrum-Badge--neutral` | `variant="neutral"` | Implemented | +| `.spectrum-Badge--notice` | `variant="notice"` | Implemented | +| `.spectrum-Badge--orange` | `variant="orange"` | Implemented | +| `.spectrum-Badge--positive` | `variant="positive"` | Implemented | +| `.spectrum-Badge--purple` | `variant="purple"` | Implemented | +| `.spectrum-Badge--red` | `variant="red"` | Implemented | +| `.spectrum-Badge--seafoam` | `variant="seafoam"` | Implemented | +| `.spectrum-Badge--yellow` | `variant="yellow"` | Implemented | +| `.spectrum-Badge--brown` | `variant="brown"` | Missing from WC (new for S2) | +| `.spectrum-Badge--cinnamon` | `variant="cinnamon"` | Missing from WC (new for S2) | +| `.spectrum-Badge--pink` | `variant="pink"` | Missing from WC (new for S2) | +| `.spectrum-Badge--silver` | `variant="silver"` | Missing from WC (new for S2) | +| `.spectrum-Badge--turquoise` | `variant="turquoise"` | Missing from WC (new for S2) | + +## Summary of changes + +### CSS => SWC implementation gaps + +**Missing from WC:** + +- **New color variants**: `brown`, `cinnamon`, `pink`, `silver`, `turquoise` +- **Style variants**: `outline` and `subtle` styles + +**Note**: Fixed positioning exists in both SWC and Spectrum 2 CSS but is not in the design spec. Consider whether to keep this for 2nd gen. + +### CSS Spectrum 2 changes + +**No significant structural changes.** + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3740) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-badge--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/badge--docs) diff --git a/migration-roadmap/cursor_prompt.md b/migration-roadmap/cursor_prompt.md index c09a49cfe84..2597f15fd0b 100644 --- a/migration-roadmap/cursor_prompt.md +++ b/migration-roadmap/cursor_prompt.md @@ -1,91 +1,89 @@ # Spectrum Migration Documentation Prompt -For the **\_\_** component(s), create comprehensive migration documentation in individual markdown files within the `migration-roadmap/` directory of the spectrum-web-components repository, following this exact structure: +For the **[COMPONENT_NAME]** component(s), create comprehensive migration documentation in individual markdown files within the `migration-roadmap/` directory of the spectrum-web-components repository, following this exact structure: -## File Organization +**IMPORTANT**: All files must be created on the original spectrum-web-components branch where the session started. -Create a separate markdown file for each component using the component/package name from the spectrum-web-components repository: +## File Organization -- File path: `migration-roadmap/[COMPONENT_NAME].md` +- **One markdown file per component** +- Use the component/package name from the spectrum-web-components repository: +- File path format: `migration-roadmap/[COMPONENT_NAME].md` - Example: `migration-roadmap/alert-banner.md`, `migration-roadmap/dialog.md` ## Component Documentation Structure -### 1. Component Heading - -- Create a Level 1 heading (`#`) with the format: "[Component name] migration roadmap" +- Create a Level 1 heading (`#`) with the format: `# [Component name] migration roadmap` - Example: `# Alert Banner migration roadmap` -### 2. Metadata Extraction (spectrum-css repository) +### 1. Component Specifications + +Create a Level 2 Heading: `## Component specifications` -From the `spectrum-two` branch of the spectrum-css repository, locate the component's `metadata.json` file in the `components/[component-name]/` directory. +Within this heading, we'll have a Level 3 heading for CSS (`### CSS`) and one for Spectrum web components (`### SWC`). -**Additional Context**: Review the component's CHANGELOG file (if available) for historical context on changes, deprecations, and new features that may inform the migration documentation. +#### 1.1 CSS Section -Create collapsible sections using `
` and `` for each category: +Check out the `spectrum-two` branch of the spectrum-css repository and locate the component's `metadata.json` file in the `components/[component-name]/` directory. + +**Required git command**: `git checkout spectrum-two` (verify branch before proceeding) + +Create collapsible sections using `
` and `` under `### CSS` for each category: **CSS Selectors Section:** - Title: "CSS selectors" - Extract all selectors from metadata.json -- If empty, write: "No CSS selectors found for this component." **Passthroughs Section:** - Title: "Passthroughs" - Extract all passthroughs from metadata.json -- If empty, write: "No passthroughs found for this component." -**Modifiers Section (ALWAYS LAST):** +**Modifiers Section:** - Title: "Modifiers" - Extract all modifiers from metadata.json -- If empty, write: "No modifiers found for this component." -- **Important**: This section must always be the final `
` list -### 3. Web Component Analysis (spectrum-web-components repository) +If any of these sections are empty in metadata.json, write for that section only, "None found for this component." + +#### 1.2 SWC Section + +Check out the `main` branch of the spectrum-web-components repository, analyze the component and create additional collapsible sections under `### SWC`: -From the spectrum-web-components repository, analyze the component and create additional collapsible sections: +**Required source**: `packages/[component-name]/src/[component-name].ts` (analyze the `render()` method) **Attributes Section:** - Title: "Attributes" -- List all component attributes +- Look for `@property` decorators in TypeScript - For string properties with enumerated values, extract each value as a separate attribute entry -- If empty, write: "No attributes found for this component." **Slots Section:** - Title: "Slots" -- List all component slots -- If empty, write: "No slots found for this component." +- Look for `` patterns in render method -**Ensure modifiers remain the final section after adding attributes and slots.** +If any of these sections are empty, write for that section only, "None found for this component." -### 4. Visual Comparison Section +### 2. Comparison -Create a Level 2 heading (`##`) titled "Visual Comparison" +Create a Level 2 Heading: `## Comparison` -Add a placeholder section for component screenshots: +#### 2.1 DOM Structure Changes -```markdown -### Visual Comparison - -**Legacy Component:** +**Critical Instruction**: Analyze files from THREE different sources. Always confirm the branch and repository being used. - +**2.1.1 Web Component DOM Structure Analysis**: -**Spectrum 2 Component:** - - -``` +- **Source**: spectrum-web-components `main` branch, `/packages/[component-name]/src/[component-name].ts` (`main` branch) +- Analyze the component's `render()` method or template structure +- Extract the actual HTML markup that the web component generates +- Document the current DOM structure, including attributes -### 5. DOM Structure Analysis +**2.1.2 CSS DOM Structure Analysis**: -Create a Level 2 heading (`##`) titled "DOM Structure Changes" - -**Branch Switching Requirements**: -You will need to analyze the same component across two different branches of the spectrum-css repository. Use these git commands to switch between branches: +**Branch switching requirements**: You will need to analyze the same component across two different branches of the spectrum-css repository. Use these git commands to switch between branches: ```bash # For legacy analysis @@ -95,46 +93,72 @@ git checkout main git checkout spectrum-two ``` -**Source Analysis**: - -- Compare the component's `stories/template.js` file between the `main` branch and `spectrum-two` branch of spectrum-css -- Analyze generated HTML patterns from Storybook stories +- **Legacy Source**: spectrum-css `main` branch, `/components/[component-name]/stories/template.js` +- **Spectrum 2 Source**: spectrum-css `spectrum-two` branch, `/components/[component-name]/stories/template.js` +- **IMPORTANT**: Check both the import statements AND the template logic, as components may be removed from imports between sources +- **Line-by-line comparison required**: Don't assume templates are identical - carefully check imports, component usage, and structure - Document class application differences - -**Analysis Process**: - -1. Switch to `main` branch and analyze the component's template structure -2. Switch to `spectrum-two` branch and analyze the updated template structure -3. Document the differences between both versions +- **Verification steps**: After each git checkout, confirm you're viewing the correct branch's files. After documenting each DOM structure, verify the accuracy by re-reading the actual template files to ensure the HTML matches exactly what's in the source code for that branch. +- **Final accuracy check**: Before completing the documentation, re-read each template file one more time to verify the DOM structures are 100% accurate. Any discrepancies between documented HTML and actual template code will require correction. **Output Format**: -Create a side-by-side HTML comparison using markdown code blocks: + +Create a three-way HTML comparison using markdown code blocks. Use collapsible sections using `
` and `` under `### DOM Structure changes` for each category: ````markdown -**Legacy (main branch):** +
+Spectrum Web Components: ```html - + ``` -```` -**Spectrum 2 (spectrum-two branch):** +
+ +
+Legacy (CSS main branch): ```html - + ``` -### 6. Comparison Table +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff +--- a/components/[component-name]/stories/template.js (main branch) ++++ b/components/[component-name]/stories/template.js (spectrum-two branch) +@@ -1,3 +1,3 @@ +-// removed line ++// added line + // unchanged line +``` + +**Note**: Only include this diff section if there are actual differences between the main and spectrum-two branches. If the templates are identical, omit this section entirely. + +
+```` -Create a Level 2 heading (`##`) titled "Comparison" +#### 2.2 CSS => SWC mapping -Below the collapsible sections, create a markdown table with: +Create a markdown table with these exact column headers: - Column 1: "CSS selector" - Column 2: "Attribute or slot" - Column 3: "Status" -**Status Values:** +**Status Values (use exactly as written):** - "Implemented" - CSS selector has corresponding web component feature - "Missing from WC" - CSS exists but no web component equivalent @@ -143,126 +167,76 @@ Below the collapsible sections, create a markdown table with: **Mapping Logic:** -- **Variants to Attributes**: CSS selectors with variants (noted after "—") likely map to component attributes -- **Base Elements to Slots**: Selectors with base class + single "-" (e.g., `.spectrum-button-label`) likely map to slots -- **Language Selectors**: Group all selectors containing `:lang` together on a single row, comma-separated, as they serve the same internationalization purpose and are typically implemented as a block +- **Variants to Attributes**: CSS selectors with variants (noted after double dash `--`) likely map to component attributes +- **Base Elements to Slots**: Selectors with base class + single dash `-` (e.g., `.spectrum-button-label`) likely map to slots +- **Language Selectors**: Group all selectors containing :lang together on a single row, comma-separated, as they serve the same internationalization purpose and are typically implemented as a block -**Language Selector Formatting Example:** +**Language Selector Formatting example:** -``` -`.spectrum-Search:lang(ja)`, `.spectrum-Search:lang(ko)`, `.spectrum-Search:lang(zh)` | Language-specific styling | Implemented +```markdown +.spectrum-Search:lang(ja), .spectrum-Search:lang(ko), .spectrum-Search:lang(zh) | Language-specific styling | Implemented ``` -**Table Organization:** +**Table Organization Order:** 1. Mapped pairs (CSS selector ↔ Attribute/Slot) with appropriate status 2. Unmapped selectors (empty "Attribute or slot" column, "Missing from WC" status) 3. Unmapped attributes/slots (empty "CSS selector" column, "Missing from CSS" status) -## Additional Requirements - -### Clarifying Questions - -If you encounter any ambiguities, edge cases, or unclear mappings during documentation, please ask clarifying questions rather than making assumptions. This includes: - -- Uncertain CSS selector to attribute/slot mappings -- Components with unusual metadata structure -- Missing or incomplete metadata.json files -- Conflicting information between repositories - -### Property Change Documentation - -When documenting modifiers, include analysis of: - -- Properties that were renamed/restructured -- Properties that were removed entirely -- New properties that were added -- Changes in default values or behavior - -### 7. Structural Changes Summary - -Create a Level 2 heading (`##`) titled "Key Structural Changes" - -After the comparison table, provide a focused summary of DOM changes that will impact SWC engineers: - -**Element Hierarchy Changes:** - -- Document any changes in nesting depth or parent-child relationships -- Note new wrapper elements or removed containers - -**Class Name Changes:** - -- List renamed, added, or removed CSS classes -- Highlight changes in class application patterns +### 3. Summary of changes -**Attribute Changes:** +Create a Level 2 Heading: `## Summary of changes` -- Document new required attributes or removed attributes -- Note changes in attribute naming or values +After the comparison table, create a new section that provide a focused summary of changes that will impact SWC engineers: -**Slot/Content Changes:** +#### CSS => SWC implementation gaps -- Identify changes in how content is structured or slotted -- Document new content containers or removed content areas +Summarize changes in **CSS => SWC mapping** section above. Note any statuses that are missing, and whether they are missing from WC or CSS. -**Migration Impact:** +Entries with status indicating that they appear in WC but not CSS might be an indication of implementation differences, but could also be an indication of a deprecated feature. -- Summarize the most critical changes that will require template updates -- Flag any breaking changes in component structure +Entries with status indicating that they appear in CSS but not WC are often an indication of new features that may need to be added when migrating WC to 2nd gen. -### 8. Implementation Gaps Analysis +#### CSS Spectrum 2 changes -Create a Level 3 heading (`###`) titled "Implementation Gaps" +Analyze the differences between CSS `main` and CSS `spectrum-two` branches surfaced in the DOM structure comparison and document them in this section: -Analyze and document the following subsections: +- **Required**: Compare the HTML structures from main vs spectrum-two templates line by line +- **Document**: Any elements that are added, removed, or modified between branches +- **Include**: Changes in element attributes, class names, or structural differences +- **Note**: Even subtle differences like conditional elements or missing components must be documented +- **Focus on changes in Spectrum CSS**, not changes between spectrum web components and CSS. -**CSS Features Missing from Web Component:** +Be sure to note: -- List CSS selectors/features that have no web component equivalent -- Include any new Spectrum 2 capabilities not yet implemented +- Elements present in main but missing in spectrum-two +- Elements present in spectrum-two but missing in main +- Changes in element attributes or class names +- Structural changes (different nesting, wrapper elements) +- Conditional elements that differ between branches +- Import differences that affect rendered output -**Web Component Features Missing from CSS:** +### 4. Resources section -- List web component attributes/slots that have no CSS equivalent -- Include legacy features that may no longer be supported +Create a Level 2 Heading: `## Resources` -**Features Being Deprecated/Removed:** +Under this heading, add a placeholder section for resources with a bulleted list that can be filled in: -- List any legacy web component features being removed in Spectrum 2 -- Note any breaking changes in functionality - -### 9. Action Items Summary - -Create a Level 3 heading (`###`) titled "Action Items for Web Component Maintainers" - -Provide clear, actionable next steps: - -**Required Additions:** - -- Web component features that need to be implemented to match CSS capabilities - -**Required Removals:** - -- Legacy features that should be removed or deprecated - -**Breaking Changes:** - -- Changes that will affect existing web component consumers -- Migration guidance where applicable - -### Integration Guidance - -Where applicable, include brief notes on: - -- Usage pattern differences between legacy and Spectrum 2 -- Integration considerations for web component consumers +```markdown +- [CSS migration]() +- [Spectrum 2 preview]() +- [React]() +``` -## Output Format +## Output format notes -- Create individual markdown files in the `migration-roadmap/` directory +- Create individual markdown files in the migration-roadmap/ directory - Use component names from spectrum-web-components repository for filenames - Use proper markdown formatting with Level 1 heading for component name -- Ensure all `
` elements are properly closed +- Ensure all
elements are properly closed - Use consistent table formatting -- Maintain hierarchical heading structure (Level 1 for component, Level 2 for major sections) -- Keep modifiers section as the final collapsible section in each component +- Maintain hierarchical heading structure +- Always verify git branch before analyzing any file +- Perform line-by-line comparisons - don't assume files are similar +- Ask clarifying questions for uncertain mappings instead of guessing +- Use exact file paths specified in this prompt diff --git a/migration-roadmap/divider.md b/migration-roadmap/divider.md new file mode 100644 index 00000000000..3cff247bf57 --- /dev/null +++ b/migration-roadmap/divider.md @@ -0,0 +1,148 @@ +# Divider migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-Divider` +- `.spectrum-Divider--sizeL` +- `.spectrum-Divider--sizeS` +- `.spectrum-Divider--staticBlack` +- `.spectrum-Divider--staticBlack.spectrum-Divider--sizeL` +- `.spectrum-Divider--staticWhite` +- `.spectrum-Divider--staticWhite.spectrum-Divider--sizeL` +- `.spectrum-Divider--vertical` +- `.spectrum-Divider:not(.spectrum-Divider.spectrum-Divider--vertical)` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-divider-background-color` +- `--mod-divider-block-minimum-size` +- `--mod-divider-inline-minimum-size` +- `--mod-divider-thickness` +- `--mod-divider-vertical-align` +- `--mod-divider-vertical-height` +- `--mod-divider-vertical-margin` + +
+ +### SWC + +
+Attributes + +- `size` (s, m, l) +- `vertical` (boolean) +- `static-color` (white, black) + +
+ +
+Slots + +None found for this component. + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components: + +```html + + #shadow-root + + +``` + +
+ +
+Legacy (CSS main branch): + +```html + +``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff + +``` + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| --------------------------------------------------------------------- | ----------------------------------- | ----------- | +| `.spectrum-Divider--sizeS` | `size="s"` | Implemented | +| `.spectrum-Divider--sizeL` | `size="l"` | Implemented | +| `.spectrum-Divider--vertical` | `vertical` | Implemented | +| `.spectrum-Divider--staticBlack` | `static-color="black"` | Implemented | +| `.spectrum-Divider--staticWhite` | `static-color="white"` | Implemented | +| `.spectrum-Divider` | Base component | Implemented | +| `.spectrum-Divider:not(.spectrum-Divider.spectrum-Divider--vertical)` | Default horizontal orientation | Implemented | +| `.spectrum-Divider--staticBlack.spectrum-Divider--sizeL` | `static-color="black"` + `size="l"` | Implemented | +| `.spectrum-Divider--staticWhite.spectrum-Divider--sizeL` | `static-color="white"` + `size="l"` | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +**No missing features.** All CSS selectors have corresponding web component attributes: + +- **Size variants**: `--sizeS` → `size="s"`, `--sizeL` → `size="l"` (medium is default) +- **Orientation**: `--vertical` → `vertical` boolean attribute +- **Static colors**: `--staticBlack` → `static-color="black"`, `--staticWhite` → `static-color="white"` + +### CSS Spectrum 2 changes + +The main difference between the legacy (CSS main) and Spectrum 2 (CSS spectrum-two) branches is the removal of minimum dimension styling. Horizontal divider's minimum width and vertical divider's minimum height are now controlled by tokens. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3557) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-divider--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/divider--docs) diff --git a/migration-roadmap/progress-circle.md b/migration-roadmap/progress-circle.md new file mode 100644 index 00000000000..002eef0bb9a --- /dev/null +++ b/migration-roadmap/progress-circle.md @@ -0,0 +1,234 @@ +# Progress Circle migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-ProgressCircle` +- `.spectrum-ProgressCircle--indeterminate .spectrum-ProgressCircle-fill` +- `.spectrum-ProgressCircle--sizeL` +- `.spectrum-ProgressCircle--sizeS` +- `.spectrum-ProgressCircle-fill` +- `.spectrum-ProgressCircle-track` +- `.spectrum-ProgressCircle.spectrum-ProgressCircle--staticBlack` +- `.spectrum-ProgressCircle.spectrum-ProgressCircle--staticWhite` +- `.spectrum-ProgressCircle:not(.spectrum-ProgressCircle--indeterminate) .spectrum-innerCircle` +- `.spectrum-ProgressCircle:not(.spectrum-ProgressCircle--indeterminate) .spectrum-outerCircle` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-progress-circle-fill-border-color` +- `--mod-progress-circle-position` +- `--mod-progress-circle-size` +- `--mod-progress-circle-thickness` +- `--mod-progress-circle-track-border-color` + +
+ +### SWC + +
+Attributes + +- `size` (s, m, l) +- `indeterminate` (boolean) +- `label` (string) +- `static-color` (white) +- `progress` (number) + +
+ +
+Slots + +- Default slot (for label content, sets the aria label) + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components: + +```html + + #shadow-root + +
+
+
+
+
+
+
+
+
+
+
+
+
+ +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + + + + +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff +
+-
+-
+-
+-
+-
+-
+-
+-
+-
+-
+-
+-
+-
++ ++ ++ ++ ++ +
+``` + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| --------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------- | +| `.spectrum-ProgressCircle` | `:host` | Implemented | +| `.spectrum-ProgressCircle--sizeS` | `size="s"` | Implemented | +| `.spectrum-ProgressCircle--sizeL` | `size="l"` | Implemented | +| `.spectrum-ProgressCircle--indeterminate` | `indeterminate` | Implemented | +| `.spectrum-ProgressCircle.spectrum-ProgressCircle--staticWhite` | `static-color="white"` | Implemented | +| `.spectrum-ProgressCircle-fill` | `.fills` | Implemented | +| `.spectrum-ProgressCircle-track` | `.track` | Implemented | +| `.spectrum-ProgressCircle--indeterminate .spectrum-ProgressCircle-fill` | Indeterminate fill styling | Implemented | +| `.spectrum-ProgressCircle:not(.spectrum-ProgressCircle--indeterminate) .spectrum-innerCircle` | Determinate inner circle | Missing from CSS | +| `.spectrum-ProgressCircle:not(.spectrum-ProgressCircle--indeterminate) .spectrum-outerCircle` | Determinate outer circle | Missing from CSS | +| | `label` | Missing from CSS | +| | Default slot | Missing from CSS | +| Maps to `stroke-dashoffset` attribute (100 - value) within `.spectrum-ProgressCircle-fill` | `progress` | Implemented, but will need changes for S2 | +| `.spectrum-ProgressCircle.spectrum-ProgressCircle--staticBlack` | `static-color="black"` | Missing from WC (New for S2) | + +## Summary of changes + +The progress circle component has significant differences between CSS and web component implementations: + +- **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 +- **Static black**: Static white was previously supported, but Spectrum 2 should support both static white and static black +- **Label attribute**: Web component supports a `label` attribute for accessibility that is not present in CSS + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/commit/0c52c4820a3c5fb0881f23c6144fb0d0bd9a35cf) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-progress-circle--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/progresscircle--docs) diff --git a/migration-roadmap/status-light.md b/migration-roadmap/status-light.md new file mode 100644 index 00000000000..da380bd0eac --- /dev/null +++ b/migration-roadmap/status-light.md @@ -0,0 +1,261 @@ +# Status Light migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-StatusLight` +- `.spectrum-StatusLight--blue:before` +- `.spectrum-StatusLight--brown:before` +- `.spectrum-StatusLight--celery:before` +- `.spectrum-StatusLight--chartreuse:before` +- `.spectrum-StatusLight--cinnamon:before` +- `.spectrum-StatusLight--cyan:before` +- `.spectrum-StatusLight--fuchsia:before` +- `.spectrum-StatusLight--gray:before` +- `.spectrum-StatusLight--green:before` +- `.spectrum-StatusLight--indigo:before` +- `.spectrum-StatusLight--info:before` +- `.spectrum-StatusLight--magenta:before` +- `.spectrum-StatusLight--negative:before` +- `.spectrum-StatusLight--neutral` +- `.spectrum-StatusLight--neutral:before` +- `.spectrum-StatusLight--notice:before` +- `.spectrum-StatusLight--orange:before` +- `.spectrum-StatusLight--pink:before` +- `.spectrum-StatusLight--positive:before` +- `.spectrum-StatusLight--purple:before` +- `.spectrum-StatusLight--red:before` +- `.spectrum-StatusLight--seafoam:before` +- `.spectrum-StatusLight--silver:before` +- `.spectrum-StatusLight--sizeL` +- `.spectrum-StatusLight--sizeS` +- `.spectrum-StatusLight--sizeXL` +- `.spectrum-StatusLight--turquoise:before` +- `.spectrum-StatusLight--yellow:before` +- `.spectrum-StatusLight:before` +- `.spectrum-StatusLight:lang(ja)` +- `.spectrum-StatusLight:lang(ko)` +- `.spectrum-StatusLight:lang(zh)` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-statuslight-border-width` +- `--mod-statuslight-content-color-default` +- `--mod-statuslight-corner-radius` +- `--mod-statuslight-dot-size` +- `--mod-statuslight-font-family` +- `--mod-statuslight-font-size` +- `--mod-statuslight-font-style` +- `--mod-statuslight-font-weight` +- `--mod-statuslight-height` +- `--mod-statuslight-line-height` +- `--mod-statuslight-line-height-cjk` +- `--mod-statuslight-nonsemantic-blue-color` +- `--mod-statuslight-nonsemantic-brown-color` +- `--mod-statuslight-nonsemantic-celery-color` +- `--mod-statuslight-nonsemantic-chartreuse-color` +- `--mod-statuslight-nonsemantic-cinnamon-color` +- `--mod-statuslight-nonsemantic-cyan-color` +- `--mod-statuslight-nonsemantic-fuchsia-color` +- `--mod-statuslight-nonsemantic-gray-color` +- `--mod-statuslight-nonsemantic-green-color` +- `--mod-statuslight-nonsemantic-indigo-color` +- `--mod-statuslight-nonsemantic-magenta-color` +- `--mod-statuslight-nonsemantic-orange-color` +- `--mod-statuslight-nonsemantic-pink-color` +- `--mod-statuslight-nonsemantic-purple-color` +- `--mod-statuslight-nonsemantic-red-color` +- `--mod-statuslight-nonsemantic-seafoam-color` +- `--mod-statuslight-nonsemantic-silver-color` +- `--mod-statuslight-nonsemantic-turquoise-color` +- `--mod-statuslight-nonsemantic-yellow-color` +- `--mod-statuslight-semantic-info-color` +- `--mod-statuslight-semantic-negative-color` +- `--mod-statuslight-semantic-neutral-color` +- `--mod-statuslight-semantic-notice-color` +- `--mod-statuslight-semantic-positive-color` +- `--mod-statuslight-spacing-bottom-to-label` +- `--mod-statuslight-spacing-dot-to-label` +- `--mod-statuslight-spacing-top-to-dot` +- `--mod-statuslight-spacing-top-to-label` +- `--mod-statuslight-subdued-content-color-default` + +
+ +### SWC + +
+Attributes + +- `size` (s, m, l, xl) +- `variant` (negative, notice, positive, info, neutral, yellow, fuchsia, indigo, seafoam, chartreuse, magenta, celery, purple) +- `disabled` (boolean) + +
+ +
+Slots + +- Default slot (for label content) + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components: + +```html + + #shadow-root + + +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ Status text +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ Status text +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff + +``` + +
+ +### CSS => SWC mapping + +#### Non-color selectors + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------------------ | --------------------------- | ----------------------------- | +| `.spectrum-StatusLight` | Base component | Implemented | +| `.spectrum-StatusLight--sizeS` | `size="s"` | Implemented | +| `.spectrum-StatusLight--sizeM` | `size="m"` | Implemented | +| `.spectrum-StatusLight--sizeL` | `size="l"` | Implemented | +| `.spectrum-StatusLight--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-StatusLight:before` | Status dot (pseudo-element) | Implemented | +| `.spectrum-StatusLight:lang(ja), .spectrum-StatusLight:lang(ko), .spectrum-StatusLight:lang(zh)` | Language-specific styling | Implemented | +| No selector, corresponds to default content within `.spectrum-StatusLight` | Default slot | Implemented | +| | `disabled` | Missing from CSS (deprecated) | + +#### Color/variant selectors + +| CSS selector | Attribute or slot | Status | +| ----------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------- | +| `.spectrum-StatusLight--negative` | `variant="negative"` | Implemented | +| `.spectrum-StatusLight--notice` | `variant="notice"` | Implemented | +| `.spectrum-StatusLight--positive` | `variant="positive"` | Implemented | +| `.spectrum-StatusLight--info` | `variant="info"` | Implemented | +| `.spectrum-StatusLight--neutral` | `variant="neutral"` | Implemented | +| `.spectrum-StatusLight--yellow` | `variant="yellow"` | Implemented | +| `.spectrum-StatusLight--fuchsia` | `variant="fuchsia"` | Implemented | +| `.spectrum-StatusLight--indigo` | `variant="indigo"` | Implemented | +| `.spectrum-StatusLight--seafoam` | `variant="seafoam"` | Implemented | +| `.spectrum-StatusLight--chartreuse` | `variant="chartreuse"` | Implemented | +| `.spectrum-StatusLight--magenta` | `variant="magenta"` | Implemented | +| `.spectrum-StatusLight--celery` | `variant="celery"` | Implemented | +| `.spectrum-StatusLight--purple` | `variant="purple"` | Implemented | +| `.spectrum-StatusLight--cyan` | `variant="cyan"` | Missing from WC, present in both S1 and S2 | +| `.spectrum-StatusLight--pink` | `variant="pink"` | Missing from WC - new for S2 | +| `.spectrum-StatusLight--turquoise` | `variant="turquoise"` | Missing from WC - new for S2 | +| `.spectrum-StatusLight--cinnamon` | `variant="cinnamon"` | Missing from WC - new for S2 | +| `.spectrum-StatusLight--brown` | `variant="brown"` | Missing from WC - new for S2 | +| `.spectrum-StatusLight--silver` | `variant="silver"` | Missing from WC - new for S2 | +| `.spectrum-StatusLight--gray` | `variant="gray"` | Missing from WC, not in the design spec for S2 | +| `.spectrum-StatusLight--blue` | `variant="blue"` | Missing from WC, not in the design spec for S2 (appears to be different from "info") | +| `.spectrum-StatusLight--green` | `variant="green"` | Missing from WC, not in the design spec for S2 (appears to be different from "positive") | +| `.spectrum-StatusLight--orange` | `variant="orange"` | Missing from WC, not in the design spec for S2 (appears to be different from "notice") | +| `.spectrum-StatusLight--red` | `variant="red"` | Missing from WC, not in the design spec for S2 (appears to be different from "negative" ) | +| `.spectrum-StatusLight--accent` | `variant="accent"` | Missing from WC, appears to be deprecated for S2 | + +## Summary of changes + +### CSS => SWC implementation gaps + +The status light component has several missing variants in the web component implementation: + +**Missing from WC:** + +**New variants for S2:** + +- Pink variant +- Turquoise variant +- Cinnamon variant +- Brown variant +- Silver variant + +**Variants present in both S1 and S2:** + +- Cyan variant: CSS supports `--cyan` but web components doesn't, this is in the design spec and **will need to be added in 2nd gen** + +**Variants not in design spec for S2 (need verification):** +These variants are not in the design spec for S2 but are present in the S2 preview for CSS. These will likely need verification to determine whether or not we will include them. + +Notes: These variants all exist in the S2 design spec and CSS preview of the Badge component. These all also have a similarly-colored "semantic" variant. This may be useful when determining whether they should be included in the 2nd gen web components. + +- Gray variant (similar to "neutral" variant) +- Blue variant (similar to "info" variant) +- Green variant (similar to "positive" variant) +- Orange variant (similar to "notice" variant) +- Red variant (similar to "negative" variant) + +**Deprecated variants:** + +- Accent variant: deprecated for S2 + +**Other implementation differences:** + +- **Disabled attribute**: There is no disabled state for this component in the S2 design spec, this attribute should be deprecated. + +### CSS Spectrum 2 changes + +No differences found between the legacy (CSS main) and Spectrum 2 (CSS spectrum-two) branches. The template structure and class naming remain consistent across both branches. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2818) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-status-light--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/statuslight--docs) From 8aa813871242e8a3845e963739e7a705e90cfb05 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Thu, 25 Sep 2025 12:37:12 -0700 Subject: [PATCH 4/9] 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 --- migration-roadmap/field-label.md | 189 ++++++++++++ migration-roadmap/help-text.md | 168 +++++++++++ migration-roadmap/infield-button.md | 298 +++++++++++++++++++ migration-roadmap/infield-progress-circle.md | 85 ++++++ migration-roadmap/picker-button.md | 247 +++++++++++++++ 5 files changed, 987 insertions(+) create mode 100644 migration-roadmap/field-label.md create mode 100644 migration-roadmap/help-text.md create mode 100644 migration-roadmap/infield-button.md create mode 100644 migration-roadmap/infield-progress-circle.md create mode 100644 migration-roadmap/picker-button.md diff --git a/migration-roadmap/field-label.md b/migration-roadmap/field-label.md new file mode 100644 index 00000000000..04c8301f3d6 --- /dev/null +++ b/migration-roadmap/field-label.md @@ -0,0 +1,189 @@ +# Field label migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-FieldLabel` +- `.spectrum-FieldLabel--left` +- `.spectrum-FieldLabel--right` +- `.spectrum-FieldLabel--sizeL` +- `.spectrum-FieldLabel--sizeS` +- `.spectrum-FieldLabel--sizeXL` +- `.spectrum-FieldLabel--staticBlack` +- `.spectrum-FieldLabel--staticWhite` +- `.spectrum-FieldLabel-requiredIcon` +- `.spectrum-FieldLabel.is-disabled` +- `.spectrum-FieldLabel:lang(ja)` +- `.spectrum-FieldLabel:lang(ko)` +- `.spectrum-FieldLabel:lang(zh)` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-fieldlabel-asterisk-vertical-align` +- `--mod-fieldlabel-bottom-to-text` +- `--mod-fieldlabel-font-size` +- `--mod-fieldlabel-font-weight` +- `--mod-fieldlabel-line-height` +- `--mod-fieldlabel-line-height-cjk` +- `--mod-fieldlabel-min-height` +- `--mod-fieldlabel-padding-inline` +- `--mod-fieldlabel-side-margin-block-start` +- `--mod-fieldlabel-side-padding-right` +- `--mod-fieldlabel-text-to-asterisk` +- `--mod-fieldlabel-top-to-text` + +
+ +### SWC + +
+Attributes + +- `disabled` (Boolean) - Whether the field label is disabled +- `id` (String) - Unique identifier for the field label +- `for` (String) - ID of the form control the label is associated with +- `required` (Boolean) - Whether the field is required +- `side-aligned` (String) - Alignment of the label: 'start' or 'end' + +
+ +
+Slots + +- Default slot - Text content of the label + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + +``` + +
+ +
+Legacy (CSS main branch): + +```html + +``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +### HTML Output Diff + +```diff + +``` + +
+ +### Key Changes in HTML Structure + +1. **Text processing enhancement**: Added `?.trim()` to remove whitespace from label text +2. **Zero-width non-joiner**: Added `⁠` (zero-width non-joiner) between label text and required asterisk icon to prevent text wrapping issues in internationalized content +3. **Static color support**: Added support for `--staticBlack` and `--staticWhite` variants through the `staticColor` parameter + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| --------------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------- | +| `.spectrum-FieldLabel` | `:host` | Implemented | +| `.spectrum-FieldLabel--left` | `side-aligned="start"` | Implemented | +| `.spectrum-FieldLabel--right` | `side-aligned="end"` | Implemented | +| `.spectrum-FieldLabel--sizeL` | `size="l"` | Implemented | +| `.spectrum-FieldLabel--sizeS` | `size="s"` | Implemented | +| `.spectrum-FieldLabel--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-FieldLabel--staticBlack` | `static-color="black"` | Missing from WC (new for S2) | +| `.spectrum-FieldLabel--staticWhite` | `static-color="white"` | Missing from WC (new for S2) | +| `.spectrum-FieldLabel-requiredIcon` | Required icon element; `.required-icon` | Implemented | +| `.spectrum-FieldLabel.is-disabled` | `disabled` attribute | Implemented | +| `.spectrum-FieldLabel:lang(ja), .spectrum-FieldLabel:lang(ko), .spectrum-FieldLabel:lang(zh)` | Language-specific styling | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +- **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. + +### CSS Spectrum 2 changes + +- **Improved text handling**: Enhanced label text processing with `?.trim()` to remove whitespace and added a zero-width non-joiner (`⁠`) between label text and the required asterisk icon. This ensures proper spacing and prevents text wrapping issues in internationalized content. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2569) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-field-label--docs) diff --git a/migration-roadmap/help-text.md b/migration-roadmap/help-text.md new file mode 100644 index 00000000000..d5101465093 --- /dev/null +++ b/migration-roadmap/help-text.md @@ -0,0 +1,168 @@ +# Help text migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-HelpText` +- `.spectrum-HelpText .spectrum-HelpText-text` +- `.spectrum-HelpText .spectrum-HelpText-validationIcon` +- `.spectrum-HelpText.is-disabled` +- `.spectrum-HelpText.is-disabled .spectrum-HelpText-text` +- `.spectrum-HelpText.is-disabled .spectrum-HelpText-validationIcon` +- `.spectrum-HelpText.spectrum-HelpText--negative` +- `.spectrum-HelpText.spectrum-HelpText--negative .spectrum-HelpText-text` +- `.spectrum-HelpText.spectrum-HelpText--negative .spectrum-HelpText-validationIcon` +- `.spectrum-HelpText.spectrum-HelpText--neutral` +- `.spectrum-HelpText.spectrum-HelpText--neutral .spectrum-HelpText-text` +- `.spectrum-HelpText.spectrum-HelpText--neutral .spectrum-HelpText-validationIcon` +- `.spectrum-HelpText.spectrum-HelpText--sizeL` +- `.spectrum-HelpText.spectrum-HelpText--sizeS` +- `.spectrum-HelpText.spectrum-HelpText--sizeXL` +- `.spectrum-HelpText:lang(ja)` +- `.spectrum-HelpText:lang(ko)` +- `.spectrum-HelpText:lang(zh)` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-helptext-bottom-edge-to-workflow-icon` +- `--mod-helptext-bottom-to-text` +- `--mod-helptext-content-color-default` +- `--mod-helptext-font-family` +- `--mod-helptext-font-size` +- `--mod-helptext-font-style` +- `--mod-helptext-font-weight` +- `--mod-helptext-icon-color-default` +- `--mod-helptext-icon-size` +- `--mod-helptext-line-height` +- `--mod-helptext-line-height-cjk` +- `--mod-helptext-min-height` +- `--mod-helptext-text-to-visual` +- `--mod-helptext-top-edge-to-workflow-icon` +- `--mod-helptext-top-to-text` + +
+ +### SWC + +
+Attributes + +- `disabled` (Boolean) - Whether the help text is disabled +- `icon` (Boolean) - Whether to show the validation icon +- `variant` (String) - Visual variant: 'neutral' or 'negative' + +
+ +
+Slots + +- Default slot - Text content of the help text + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + +
+``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ +
Help text content
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ +
Help text content
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +No significant structural changes. + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| --------------------------------------------------------------------------------------- | ------------------------- | ----------- | +| `.spectrum-HelpText` | `:host` | Implemented | +| `.spectrum-HelpText-text` | Text slot | Implemented | +| `.spectrum-HelpText-validationIcon` | Icon element | Implemented | +| `.spectrum-HelpText.is-disabled` | `disabled` attribute | Implemented | +| `.spectrum-HelpText--negative` | `variant="negative"` | Implemented | +| `.spectrum-HelpText--neutral` | `variant="neutral"` | Implemented | +| `.spectrum-HelpText--sizeL` | `size="l"` | Implemented | +| `.spectrum-HelpText--sizeS` | `size="s"` | Implemented | +| `.spectrum-HelpText--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-HelpText:lang(ja), .spectrum-HelpText:lang(ko), .spectrum-HelpText:lang(zh)` | Language-specific styling | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +No implementation gaps found. All CSS functionality is properly mapped to web component attributes and slots. + +### CSS Spectrum 2 changes + +- **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. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3628) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-help-text--docs) diff --git a/migration-roadmap/infield-button.md b/migration-roadmap/infield-button.md new file mode 100644 index 00000000000..c917f977856 --- /dev/null +++ b/migration-roadmap/infield-button.md @@ -0,0 +1,298 @@ +# In-field button migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-InfieldButton` +- `.spectrum-InfieldButton--quiet` +- `.spectrum-InfieldButton--quiet:disabled` +- `.spectrum-InfieldButton--quiet:not(:disabled):active` +- `.spectrum-InfieldButton--quiet:not(:disabled):focus-visible` +- `.spectrum-InfieldButton--quiet:not(:disabled):hover` +- `.spectrum-InfieldButton-fill` +- `.spectrum-InfieldButton-icon` +- `.spectrum-InfieldButton-inline` +- `.spectrum-InfieldButton-inline .spectrum-InfieldButton` +- `.spectrum-InfieldButton-inline > .spectrum-InfieldButton.spectrum-InfieldButton--sizeS` +- `.spectrum-InfieldButton.spectrum-InfieldButton--quiet` +- `.spectrum-InfieldButton.spectrum-InfieldButton--quiet:disabled` +- `.spectrum-InfieldButton.spectrum-InfieldButton--sizeL` +- `.spectrum-InfieldButton.spectrum-InfieldButton--sizeS` +- `.spectrum-InfieldButton.spectrum-InfieldButton--sizeXL` +- `.spectrum-InfieldButton:active` +- `.spectrum-InfieldButton:disabled` +- `.spectrum-InfieldButton:focus-visible` +- `.spectrum-InfieldButton:hover` +- `.spectrum-InfieldButton:not(:disabled):active` +- `.spectrum-InfieldButton:not(:disabled):focus-visible` +- `.spectrum-InfieldButton:not(:disabled):hover` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-infield-button-background-color` +- `--mod-infield-button-background-color-disabled` +- `--mod-infield-button-background-color-down` +- `--mod-infield-button-background-color-down-disabled` +- `--mod-infield-button-background-color-down-quiet` +- `--mod-infield-button-background-color-hover` +- `--mod-infield-button-background-color-hover-disabled` +- `--mod-infield-button-background-color-hover-quiet` +- `--mod-infield-button-background-color-quiet` +- `--mod-infield-button-background-color-quiet-disabled` +- `--mod-infield-button-border-radius` +- `--mod-infield-button-edge-to-fill` +- `--mod-infield-button-field-edge-to-icon` +- `--mod-infield-button-fill-justify-content` +- `--mod-infield-button-fill-padding` +- `--mod-infield-button-height` +- `--mod-infield-button-icon-color` +- `--mod-infield-button-icon-color-disabled` +- `--mod-infield-button-icon-color-down` +- `--mod-infield-button-icon-color-down-disabled` +- `--mod-infield-button-icon-color-hover` +- `--mod-infield-button-icon-color-hover-disabled` +- `--mod-infield-button-side-edge-to-fill` +- `--mod-infield-button-width` + +
+ +### SWC + +
+Attributes + +- `active` (Boolean) - Whether the infield button is in an active state +- `block` (String) - Vertical stack position: 'start' or 'end' +- `disabled` (Boolean) - Disable this control. It will not receive focus or events +- `download` (String) - Causes the browser to treat the linked URL as a download +- `href` (String) - The URL that the hyperlink points to +- `inline` (String) - Horizontal group position: 'start' or 'end' +- `label` (String) - An accessible label that describes the component. It will be applied to aria-label, but not visually rendered +- `quiet` (Boolean) - Whether the button is in quiet variant +- `referrerpolicy` (String) - How much of the referrer to send when following the link +- `rel` (String) - The relationship of the linked URL as space-separated link types +- `tabIndex` (Number) - The tab index to apply to this control +- `target` (String) - Where to display the linked URL, as the name for a browsing context +- `type` (String) - The default behavior of the button: 'button', 'submit', or 'reset' + +
+ +
+Slots + +- Default slot - Text content for the button +- Icon slot - Icon content for the button + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + +``` + +
+ +
+Legacy (CSS main branch): + +```html + +``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +### HTML Output Diff + +**Single Button Changes:** + +```diff + +``` + +**Stacked → Inline Layout Changes:** + +```diff ++
+ + ++
+``` + +### Key Changes in HTML Structure + +1. **Layout paradigm shift**: Replaced `isStacked` vertical stacking with `isInline` horizontal grouping +2. **Position styles removed**: The `inline` and `block` position properties from SWC are no longer supported in CSS-only implementations +3. **Enhanced iconography**: + - Single button: Uses size-specific icon names (e.g., `Add100` instead of `Add`) + - Inline buttons: Switched from chevron icons to more intuitive action icons (`Dash`/`Add`) +4. **Simplified state management**: Removed `isInvalid` and `isFocused` states while preserving `isHovered`/`isActive` +5. **Improved accessibility**: Added `role="presentation"` for single buttons and proper `aria-label` differentiation for inline buttons +6. **Container structure**: Inline variant wraps buttons in `spectrum-InfieldButton-inline` container +7. **Consistent corner radius**: Position-specific border radius variants have been removed in favor of a consistent corner radius approach + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ---------------------------------- | ---------------------- | ---------------------------- | +| `.spectrum-InfieldButton` | `:host` | Implemented | +| `.spectrum-InfieldButton--quiet` | `quiet` attribute | Implemented | +| `.spectrum-InfieldButton-fill` | Fill container | Implemented | +| `.spectrum-InfieldButton-icon` | Icon slot | Implemented | +| `.spectrum-InfieldButton-inline` | Inline group container | Missing from WC (new for S2) | +| `.spectrum-InfieldButton--sizeL` | `size="l"` | Implemented | +| `.spectrum-InfieldButton--sizeS` | `size="s"` | Implemented | +| `.spectrum-InfieldButton--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-InfieldButton:disabled` | `disabled` attribute | Implemented | +| `.spectrum-InfieldButton:active` | `active` attribute | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +- **Inline group functionality**: The web component lacks support for `.spectrum-InfieldButton-inline` which enables horizontal button grouping, commonly used for increment/decrement controls in number inputs and similar interfaces. +- **Required wrapper div**: Spectrum 2 introduces a mandatory `
` wrapper element for inline button layouts. This structural change is essential for proper CSS styling and must be implemented during migration to ensure the component renders correctly in Spectrum 2. + +### CSS Spectrum 2 changes + +- **Reduced API complexity**: Eliminated numerous parameters (`position`, `isInvalid`, `isFocused`, `isStacked`, `onSubtract`, `onAdd`) to create a more focused and maintainable component API. +- **Layout paradigm shift**: Replaced the `isStacked` vertical stacking approach with `isInline` horizontal grouping, better aligning with common use cases for infield buttons. +- **Position styles removed**: The `inline` and `block` position properties from SWC are no longer supported in CSS-only implementations due to the consistent corner radius approach. +- **Enhanced iconography**: Switched from chevron-based icons to more intuitive action icons (Dash/Add), providing clearer visual cues for increment/decrement operations. +- **Streamlined state management**: Removed `isInvalid`/`isFocused` states while preserving essential interaction feedback (`isHovered`/`isActive`). +- **Flexible template structure**: Inline variant automatically creates paired buttons for common operations, while single variant provides direct click handling for custom actions. +- **Focus state inheritance**: Infield buttons no longer manage their own focus states, instead inheriting focus styling from their parent components (like textfields or pickers). This creates a more cohesive user experience where the entire input field appears focused rather than individual button elements. + +#### Removed modifiers + +Due to deprecation of the position variants in the infield button, several spacing and border radius modifiers have been removed: + +- `--mod-infield-button-inner-edge-to-fill` +- `--mod-infield-button-stacked-border-radius-reset` +- `--mod-infield-button-stacked-bottom-border-block-end-width` +- `--mod-infield-button-stacked-bottom-border-radius-end-end` +- `--mod-infield-button-stacked-bottom-border-radius-end-start` +- `--mod-infield-button-stacked-fill-padding-inline` +- `--mod-infield-button-stacked-fill-padding-inner` + +#### New tokens + +These new tokens support the inline variant and stepper (number field) use cases: + +- `--spectrum-in-field-button-side-edge-to-fill-small` +- `--spectrum-in-field-button-side-edge-to-fill-medium` +- `--spectrum-in-field-button-side-edge-to-fill-large` +- `--spectrum-in-field-button-side-edge-to-fill-extra-large` +- `--spectrum-field-edge-to-icon-75` +- `--spectrum-field-edge-to-icon-100` +- `--spectrum-field-edge-to-icon-200` +- `--spectrum-field-edge-to-icon-300` + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3642) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-in-field-button--docs) diff --git a/migration-roadmap/infield-progress-circle.md b/migration-roadmap/infield-progress-circle.md new file mode 100644 index 00000000000..723c301028b --- /dev/null +++ b/migration-roadmap/infield-progress-circle.md @@ -0,0 +1,85 @@ +# In-field progress circle migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-InfieldProgressCircle` +- `.spectrum-InfieldProgressCircle .spectrum-ProgressCircle-fill` +- `.spectrum-InfieldProgressCircle--sizeL` +- `.spectrum-InfieldProgressCircle--sizeS` +- `.spectrum-InfieldProgressCircle--sizeXL` + +
+ +
+Passthroughs + +- `--mod-progress-circle-size` +- `--mod-progress-circle-thickness` + +
+ +
+Modifiers + +None found for this component. + +
+ +### SWC + +
+Attributes + +- `indeterminate` (Boolean) - Whether the progress circle is in indeterminate state +- `label` (String) - Accessible label for the progress circle +- `progress` (Number) - Progress value (0-100) +- `size` (String) - Size of the progress circle: 's', 'm', 'l', 'xl' +- `static-color` (String) - Static color variant + +
+ +
+Slots + +- Default slot - Content inside the progress circle + +
+ +### CSS => SWC mapping + +Since the infield progress circle doesn't exist as a separate web component, this mapping shows how it **could** work with the existing `sp-progress-circle` component: + +| CSS selector | ProgressCircle attribute | Status | +| --------------------------------------------------------------- | ------------------------------ | ---------------------------- | +| `.spectrum-InfieldProgressCircle` | `:host` (with infield classes) | Would need implementation | +| `.spectrum-InfieldProgressCircle .spectrum-ProgressCircle-fill` | Progress fill element | Available via ProgressCircle | +| `.spectrum-InfieldProgressCircle--sizeL` | `size="l"` | Available via ProgressCircle | +| `.spectrum-InfieldProgressCircle--sizeS` | `size="s"` | Available via ProgressCircle | +| `.spectrum-InfieldProgressCircle--sizeXL` | `size="xl"` | Available via ProgressCircle | +| N/A | `indeterminate` | Available via ProgressCircle | +| N/A | `label` | Available via ProgressCircle | +| N/A | `progress` | Available via ProgressCircle | +| N/A | `static-color` | Available via ProgressCircle | + +## Summary of changes + +### CSS => SWC implementation gaps + +- **Missing infield variant**: The infield progress circle doesn't exist as a separate web component. Implementation would likely involve extending the existing `sp-progress-circle` component with infield-specific styling classes, similar to how it's done in CSS. +- **Infield-specific styling**: The `.spectrum-InfieldProgressCircle` base class and its size variants would need to be implemented as additional CSS classes that can be applied to the base progress circle component. + +### CSS Spectrum 2 changes + +- **New component introduction**: The infield progress circle is entirely new in the spectrum-two branch, designed specifically for inline loading states within form fields and input components. +- **Modular architecture**: Built as a wrapper around the base ProgressCircle component with infield-specific styling classes, promoting code reuse and consistency. +- **Comprehensive sizing**: Introduced S, M, L, and XL size variants to match the sizing scale used throughout the Spectrum design system. +- **Static color variants**: Added support for static color variants to ensure visibility in various background contexts and high-contrast scenarios. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3430) diff --git a/migration-roadmap/picker-button.md b/migration-roadmap/picker-button.md new file mode 100644 index 00000000000..7996283f41a --- /dev/null +++ b/migration-roadmap/picker-button.md @@ -0,0 +1,247 @@ +# Picker button migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-PickerButton` +- `.spectrum-PickerButton--quiet` +- `.spectrum-PickerButton--quiet:disabled` +- `.spectrum-PickerButton--quiet:not(:disabled):active` +- `.spectrum-PickerButton--quiet:not(:disabled):focus-visible` +- `.spectrum-PickerButton--quiet:not(:disabled):hover` +- `.spectrum-PickerButton--workflowicon .spectrum-PickerButton-fill` +- `.spectrum-PickerButton-fill` +- `.spectrum-PickerButton-icon` +- `.spectrum-PickerButton.is-open` +- `.spectrum-PickerButton.spectrum-PickerButton--quiet` +- `.spectrum-PickerButton.spectrum-PickerButton--quiet:disabled` +- `.spectrum-PickerButton.spectrum-PickerButton--sizeL` +- `.spectrum-PickerButton.spectrum-PickerButton--sizeS` +- `.spectrum-PickerButton.spectrum-PickerButton--sizeXL` +- `.spectrum-PickerButton:active` +- `.spectrum-PickerButton:disabled` +- `.spectrum-PickerButton:focus-visible` +- `.spectrum-PickerButton:hover` +- `.spectrum-PickerButton:not(:disabled):active` +- `.spectrum-PickerButton:not(:disabled):focus-visible` +- `.spectrum-PickerButton:not(:disabled):hover` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-picker-button-background-animation-duration` +- `--mod-picker-button-background-color` +- `--mod-picker-button-background-color-disabled` +- `--mod-picker-button-background-color-down` +- `--mod-picker-button-background-color-down-disabled` +- `--mod-picker-button-background-color-down-quiet` +- `--mod-picker-button-background-color-hover` +- `--mod-picker-button-background-color-hover-disabled` +- `--mod-picker-button-background-color-hover-quiet` +- `--mod-picker-button-background-color-quiet` +- `--mod-picker-button-background-color-quiet-disabled` +- `--mod-picker-button-border-radius` +- `--mod-picker-button-fill-padding` +- `--mod-picker-button-height` +- `--mod-picker-button-icon-color` +- `--mod-picker-button-icon-color-disabled` +- `--mod-picker-button-icon-color-down` +- `--mod-picker-button-icon-color-down-disabled` +- `--mod-picker-button-icon-color-hover` +- `--mod-picker-button-icon-color-hover-disabled` +- `--mod-picker-button-padding` +- `--mod-picker-button-width` + +
+ +### SWC + +
+Attributes + +- `active` (Boolean) - Whether the picker button is in an active state +- `disabled` (Boolean) - Disable this control. It will not receive focus or events +- `download` (String) - Causes the browser to treat the linked URL as a download +- `href` (String) - The URL that the hyperlink points to +- `label` (String) - An accessible label that describes the component. It will be applied to aria-label, but not visually rendered +- `open` (Boolean) - Whether the picker button is in an open state (for dropdown menus) +- `position` (String) - Position of the button: 'left' or 'right' +- `quiet` (Boolean) - Whether the picker button is in quiet variant +- `referrerpolicy` (String) - How much of the referrer to send when following the link +- `rel` (String) - The relationship of the linked URL as space-separated link types +- `rounded` (Boolean) - Whether the picker button has rounded corners (express system) +- `size` (String) - Size of the picker button: 's', 'm', 'l', 'xl' +- `tabIndex` (Number) - The tab index to apply to this control +- `target` (String) - Where to display the linked URL, as the name for a browsing context +- `type` (String) - The default behavior of the button: 'button', 'submit', or 'reset' + +
+ +
+Slots + +- `label` - Text label for the picker button +- `icon` - Icon for the picker button + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html +
+
+ + + + +
+
+``` + +
+ +
+Legacy (CSS main branch): + +```html + +``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +### HTML Output Diff + +**Legacy (CSS main) → Spectrum 2 (CSS spectrum-two):** + +```diff + +``` + +### Key Changes in HTML Structure + +1. **Label removal**: The `` element is completely removed +2. **Class simplification**: + - Removed: `--textuiicon`, `--uiicononly`, `--icononly`, `--right`/`--left` positioning classes + - Added: `--workflowicon` for workflow icons only +3. **Button attributes**: Added explicit `type="button"` attribute +4. **Icon classes**: Enhanced with `spectrum-Icon spectrum-UIIcon-*` classes for better specificity +5. **State management**: Simplified from `is-focused` to `is-active`/`is-hover` pattern + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------ | ----------------------------- | ----------- | +| `.spectrum-PickerButton` | `:host` | Implemented | +| `.spectrum-PickerButton--workflowicon .spectrum-PickerButton-fill` | Workflow icon via `icon` slot | Implemented | +| `.spectrum-PickerButton--quiet` | `quiet` attribute | Implemented | +| `.spectrum-PickerButton-fill` | Fill container | Implemented | +| `.spectrum-PickerButton-icon` | Icon slot | Implemented | +| `.spectrum-PickerButton.is-open` | `open` attribute | Implemented | +| `.spectrum-PickerButton--sizeL` | `size="l"` | Implemented | +| `.spectrum-PickerButton--sizeS` | `size="s"` | Implemented | +| `.spectrum-PickerButton--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-PickerButton:disabled` | `disabled` attribute | Implemented | +| `.spectrum-PickerButton:active` | `active` attribute | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +No implementation gaps found. All CSS functionality is properly mapped to web component attributes and slots. + +### CSS Spectrum 2 changes + +- **Streamlined API**: Removed complex parameters (`label`, `position`, `isFocused`, `isRounded`) to focus on core functionality and reduce API surface area. +- **Relationship to infield button**: This component follows the same design patterns as the infield button component in Spectrum 2, both being designed for inline use within form fields. While they were kept as separate components in the CSS implementation, there was discussion about combining them, and this might be worth considering during the web component migration to reduce duplication and maintain consistency. +- **Icon-focused design**: Shifted from label-based to icon-only design with separate `workflowIconName`/`uiIconName` parameters for better icon management and consistency. +- **Simplified state handling**: Consolidated state management by removing `isFocused`/`isRounded` while maintaining essential interaction states (`isActive`/`isHovered`/`isDisabled`). + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/4114) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/picker--docs) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-picker-button--docs) From 7181ae5d74b43809714122459929e64a6d529fc2 Mon Sep 17 00:00:00 2001 From: Marissa Huysentruyt <69602589+marissahuysentruyt@users.noreply.github.com> Date: Fri, 26 Sep 2025 13:00:33 -0400 Subject: [PATCH 5/9] docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap (#5729) * docs(checkbox): migration roadmap * docs(fieldgroup): migration roadmap * docs(radio): migration roadmap * docs(switch): migration roadmap * docs(checkbox, field-group): update migration roadmap - gives clarification on invalid checkbox consideration - clarifies some of the implementation gaps for field group --- migration-roadmap/checkbox.md | 286 +++++++++++++++++++++++++++++++ migration-roadmap/field-group.md | 233 +++++++++++++++++++++++++ migration-roadmap/radio.md | 236 +++++++++++++++++++++++++ migration-roadmap/switch.md | 261 ++++++++++++++++++++++++++++ 4 files changed, 1016 insertions(+) create mode 100644 migration-roadmap/checkbox.md create mode 100644 migration-roadmap/field-group.md create mode 100644 migration-roadmap/radio.md create mode 100644 migration-roadmap/switch.md diff --git a/migration-roadmap/checkbox.md b/migration-roadmap/checkbox.md new file mode 100644 index 00000000000..2c8bf218036 --- /dev/null +++ b/migration-roadmap/checkbox.md @@ -0,0 +1,286 @@ +# Checkbox migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-Checkbox` +- `.spectrum-Checkbox .spectrum-Checkbox-box` +- `.spectrum-Checkbox .spectrum-Checkbox-box:after` +- `.spectrum-Checkbox .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox .spectrum-Checkbox-checkmark` +- `.spectrum-Checkbox .spectrum-Checkbox-input` +- `.spectrum-Checkbox .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box .spectrum-Checkbox-checkmark` +- `.spectrum-Checkbox .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox .spectrum-Checkbox-input:checked:disabled + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox .spectrum-Checkbox-input:checked:disabled ~ .spectrum-Checkbox-label` +- `.spectrum-Checkbox .spectrum-Checkbox-input:checked:hover:disabled + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox .spectrum-Checkbox-input:disabled` +- `.spectrum-Checkbox .spectrum-Checkbox-input:disabled + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox .spectrum-Checkbox-input:disabled ~ .spectrum-Checkbox-label` +- `.spectrum-Checkbox .spectrum-Checkbox-input:focus-visible + .spectrum-Checkbox-box:after` +- `.spectrum-Checkbox .spectrum-Checkbox-input:focus-visible + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox .spectrum-Checkbox-input:focus-visible + .spectrum-Checkbox-label` +- `.spectrum-Checkbox .spectrum-Checkbox-input:hover:disabled + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox .spectrum-Checkbox-label` +- `.spectrum-Checkbox .spectrum-Checkbox-partialCheckmark` +- `.spectrum-Checkbox--emphasized.is-indeterminate .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox--emphasized.is-indeterminate .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox--emphasized.is-indeterminate:hover .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox--emphasized.is-indeterminate:hover .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox--emphasized.is-indeterminate:not(.is-invalid) .spectrum-Checkbox-input:focus-visible + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox--emphasized:not(.is-invalid) .spectrum-Checkbox-input:focus-visible:checked + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox-input:focus-visible + .spectrum-Checkbox-box` +- `.spectrum-Checkbox.is-indeterminate .spectrum-Checkbox-box .spectrum-Checkbox-checkmark` +- `.spectrum-Checkbox.is-indeterminate .spectrum-Checkbox-box .spectrum-Checkbox-partialCheckmark` +- `.spectrum-Checkbox.is-indeterminate .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox.is-indeterminate .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box .spectrum-Checkbox-checkmark` +- `.spectrum-Checkbox.is-indeterminate .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box .spectrum-Checkbox-partialCheckmark` +- `.spectrum-Checkbox.is-indeterminate .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox.is-invalid` +- `.spectrum-Checkbox.is-invalid.is-indeterminate .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox.is-invalid.is-indeterminate .spectrum-Checkbox-input:checked:not(:disabled) + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox.is-invalid.is-indeterminate .spectrum-Checkbox-input:focus-visible + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox.is-invalid.is-indeterminate:hover .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox.is-invalid.is-indeterminate:hover .spectrum-Checkbox-input:checked:not(:disabled) + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox.spectrum-Checkbox--emphasized` +- `.spectrum-Checkbox.spectrum-Checkbox--sizeL` +- `.spectrum-Checkbox.spectrum-Checkbox--sizeS` +- `.spectrum-Checkbox.spectrum-Checkbox--sizeXL` +- `.spectrum-Checkbox:active .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox:active .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox:active .spectrum-Checkbox-label` +- `.spectrum-Checkbox:hover .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox:hover .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box:before` +- `.spectrum-Checkbox:hover .spectrum-Checkbox-label` +- `.spectrum-Checkbox:lang(ja)` +- `.spectrum-Checkbox:lang(ko)` +- `.spectrum-Checkbox:lang(zh)` +- `.spectrum-Checkbox:not(.is-readOnly) .spectrum-Checkbox-input:active:not(:disabled) + .spectrum-Checkbox-box` +- `.spectrum-Checkbox:not(.is-readOnly):active .spectrum-Checkbox-input:not(:disabled) + .spectrum-Checkbox-box` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-checkbox-animation-duration` +- `--mod-checkbox-border-width` +- `--mod-checkbox-bottom-to-text` +- `--mod-checkbox-checkmark-color` +- `--mod-checkbox-content-color-default` +- `--mod-checkbox-content-color-disabled` +- `--mod-checkbox-content-color-down` +- `--mod-checkbox-content-color-focus` +- `--mod-checkbox-content-color-hover` +- `--mod-checkbox-control-color-default` +- `--mod-checkbox-control-color-disabled` +- `--mod-checkbox-control-color-down` +- `--mod-checkbox-control-color-focus` +- `--mod-checkbox-control-color-hover` +- `--mod-checkbox-control-corner-radius` +- `--mod-checkbox-control-selected-color-default` +- `--mod-checkbox-control-selected-color-down` +- `--mod-checkbox-control-selected-color-hover` +- `--mod-checkbox-control-size` +- `--mod-checkbox-focus-indicator-color` +- `--mod-checkbox-focus-indicator-gap` +- `--mod-checkbox-focus-indicator-thickness` +- `--mod-checkbox-font-size` +- `--mod-checkbox-height` +- `--mod-checkbox-line-height` +- `--mod-checkbox-line-height-cjk` +- `--mod-checkbox-margin-block` +- `--mod-checkbox-selected-border-width` +- `--mod-checkbox-text-to-control` +- `--mod-checkbox-top-to-text` +- `--mod-focus-indicator-thickness` + +
+ +### SWC + +
+Attributes + +- `disabled` - Boolean attribute to disable the checkbox +- `indeterminate` - Boolean attribute for indeterminate state +- `invalid` - Boolean attribute for invalid state styling +- `emphasized` - Boolean attribute for emphasized styling +- `checked` - Boolean attribute for checked state (inherited from CheckboxMixin) +- `name` - String attribute for form submission (inherited from CheckboxMixin) +- `readonly` - Boolean attribute for read-only state (inherited from CheckboxMixin) +- `size` - String attribute with values: `s`, `m`, `l`, `xl` (from SizedMixin) +- `tabindex` - Number attribute for tab order management +- `autofocus` - Boolean HTML attribute for auto-focusing (handled in connectedCallback) + +
+ +
+Slots + +- Default slot - Content to display as the label for the Checkbox + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + + + + + + + +``` + +
+ +
+Legacy (CSS main branch): + +```html + +``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**No differences found between main and spectrum-two branches.** + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------- | +| `.spectrum-Checkbox` | `:host` | Implemented | +| `.spectrum-Checkbox--emphasized` | `emphasized` attribute | Implemented | +| `.spectrum-Checkbox--sizeS` | `size="s"` attribute | Implemented | +| `.spectrum-Checkbox--sizeL` | `size="l"` attribute | Implemented | +| `.spectrum-Checkbox--sizeXL` | `size="xl"` attribute | Implemented | +| `.spectrum-Checkbox.is-indeterminate` | `indeterminate` attribute | Implemented | +| `.spectrum-Checkbox.is-invalid` | `invalid` attribute | Implemented | +| `.spectrum-Checkbox-input` | Internal checkbox input element, `#input` | Implemented | +| `.spectrum-Checkbox-input:checked` | `checked` attribute | Implemented | +| `.spectrum-Checkbox-input:disabled` | `disabled` attribute | Implemented | +| `.spectrum-Checkbox-box` | Internal checkbox box element, `#box` | Implemented | +| `.spectrum-Checkbox-checkmark` | Checkmark icon element, `#checkmark` | Implemented | +| `.spectrum-Checkbox-partialCheckmark` | Indeterminate dash icon element, `#partialCheckmark` | Implemented | +| `.spectrum-Checkbox-label` | Default slot content | Implemented | +| `.spectrum-Checkbox:lang(ja)`, `.spectrum-Checkbox:lang(ko)`, `.spectrum-Checkbox:lang(zh)` | Language-specific styling | Implemented | +| `.spectrum-Checkbox.is-readOnly` | `readonly` attribute | Implemented | +| | `name` attribute | Missing from CSS | +| | `tabindex` attribute | Missing from CSS | +| | `autofocus` attribute | Missing from CSS | + +## Summary of changes + +### CSS => SWC implementation gaps + +**New for S2:** +The checkbox component in Spectrum 2 has the new down state (active) perspective shift applied. + +Note: There is some discussion ongoing about the invalid styles for checkbox. Currently, CSS supports individual red borders on the checkbox component, however, these styles are not present in the Figma specs for checkbox. The only invalid styling supported by design is the negative help text found in the field group component. When migrating, we'll need to consider clarifying the invalid styling with the design team for individual checkboxes. + +**Features Missing from CSS:** + +- `name` attribute for form submission has no corresponding CSS selector +- `tabindex` attribute for accessibility has no CSS representation +- `autofocus` attribute functionality implemented in JavaScript but has no CSS counterpart + +### CSS Spectrum 2 changes + +No structural differences found between the legacy (CSS main) and Spectrum 2 (CSS spectrum-two) branches. The template structure and class naming remain consistent across both branches. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3531) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-checkbox--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/checkbox--docs) diff --git a/migration-roadmap/field-group.md b/migration-roadmap/field-group.md new file mode 100644 index 00000000000..8a1214cc74d --- /dev/null +++ b/migration-roadmap/field-group.md @@ -0,0 +1,233 @@ +# Field Group migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-FieldGroup` +- `.spectrum-FieldGroup--horizontal .spectrum-FieldGroupInputLayout` +- `.spectrum-FieldGroup--horizontal .spectrum-FieldGroupInputLayout .spectrum-FieldGroup-item:not(:last-child)` +- `.spectrum-FieldGroup--horizontal .spectrum-FieldGroupInputLayout .spectrum-HelpText` +- `.spectrum-FieldGroup--sidelabel` +- `.spectrum-FieldGroup--toplabel` +- `.spectrum-FieldGroup--vertical .spectrum-FieldGroupInputLayout` +- `.spectrum-FieldGroupInputLayout` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +None found for this component. + +
+ +### SWC + +
+Attributes + +- `horizontal` - Boolean attribute for horizontal layout orientation +- `invalid` - Boolean attribute for invalid state to show negative help text + +
+ +
+Slots + +- Default slot - The form controls that make up the group +- `help-text` - Default or non-negative help text to associate to your form element +- `negative-help-text` - Negative help text to associate to your form element when `invalid` + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + + + + Help text content + +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ +
+
+ + + +
+
+ +
+
+ +
+ +
+
Select an option.
+
+
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ +
+
+ + + +
+
+ +
+
+ +
+ +
+
Select an option.
+
+
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**No differences found between main and spectrum-two branches.** + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ---------------------------------- | ------------------------------------- | ------------------------------------ | +| `.spectrum-FieldGroup` | `:host` | Implemented | +| `.spectrum-FieldGroup--horizontal` | `horizontal` attribute | Implemented | +| `.spectrum-FieldGroup--vertical` | Default variant; `vertical` attribute | Implemented | +| `.spectrum-FieldGroup--sidelabel` | Layout variant | Missing from WC (implementation gap) | +| `.spectrum-FieldGroup--toplabel` | Layout variant | Missing from WC (implementation gap) | +| `.spectrum-FieldGroupInputLayout` | Internal layout container | Missing from WC (implementation gap) | +| `.spectrum-FieldGroup-item` | Individual field item classes | Missing from WC (implementation gap) | +| `.spectrum-HelpText` | Help text styling | Implemented via `sp-help-text` | + +## Summary of changes + +### CSS => SWC implementation gaps + +- In CSS, the field label is incorporated into the field group component in both S1 and S2, however `` does not have a slot for a corresponding ``. Because of this, `` doesn't technically support `.spectrum-FieldGroup--sidelabel` and `.spectrum-FieldGroup--toplabel` layout variants. However, `` can be defined as top- or side-aligned, so we may be able to reevaluate if this behavior can be supported. +- `.spectrum-FieldGroupInputLayout` wrapper container is not generated by the web component. This class is the flex container that orients the items vertically or horizontally. +- `.spectrum-FieldGroup-item` classes are not automatically applied to slotted elements. The class provides the appropriate spacing between items. + +### CSS Spectrum 2 changes + +No structural differences found between the legacy (CSS main) and Spectrum 2 (CSS spectrum-two) branches. The template structure and class naming remain consistent across both branches. + +## Resources + +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-field-group--docs) diff --git a/migration-roadmap/radio.md b/migration-roadmap/radio.md new file mode 100644 index 00000000000..d352a8188a1 --- /dev/null +++ b/migration-roadmap/radio.md @@ -0,0 +1,236 @@ +# Radio migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-Radio` +- `.spectrum-Radio .spectrum-Radio-button:after` +- `.spectrum-Radio .spectrum-Radio-input:checked:disabled + .spectrum-Radio-button:before` +- `.spectrum-Radio .spectrum-Radio-input:checked:disabled ~ .spectrum-Radio-label` +- `.spectrum-Radio .spectrum-Radio-input:disabled + .spectrum-Radio-button:before` +- `.spectrum-Radio .spectrum-Radio-input:disabled ~ .spectrum-Radio-label` +- `.spectrum-Radio--emphasized .spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio--emphasized:active .spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio--emphasized:focus .spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio--emphasized:hover .spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio--sizeL` +- `.spectrum-Radio--sizeS` +- `.spectrum-Radio--sizeXL` +- `.spectrum-Radio-button` +- `.spectrum-Radio-button:after` +- `.spectrum-Radio-button:before` +- `.spectrum-Radio-input` +- `.spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio-input:disabled` +- `.spectrum-Radio-input:focus-visible + .spectrum-Radio-button:after` +- `.spectrum-Radio-label` +- `.spectrum-Radio-label:lang(ja)` +- `.spectrum-Radio-label:lang(ko)` +- `.spectrum-Radio-label:lang(zh)` +- `.spectrum-Radio.is-active .spectrum-Radio-button:before` +- `.spectrum-Radio.is-active .spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio.is-active .spectrum-Radio-label` +- `.spectrum-Radio.is-readOnly .spectrum-Radio-input` +- `.spectrum-Radio.is-readOnly .spectrum-Radio-input + .spectrum-Radio-button:before` +- `.spectrum-Radio.is-readOnly .spectrum-Radio-input:checked:disabled ~ .spectrum-Radio-label` +- `.spectrum-Radio.is-readOnly .spectrum-Radio-input:disabled ~ .spectrum-Radio-label` +- `.spectrum-Radio.is-readOnly .spectrum-Radio-label` +- `.spectrum-Radio.is-readOnly:hover .spectrum-Radio-input + .spectrum-Radio-button:before` +- `.spectrum-Radio:active .spectrum-Radio-button:before` +- `.spectrum-Radio:active .spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio:active .spectrum-Radio-label` +- `.spectrum-Radio:dir(rtl) .spectrum-Radio-button:after` +- `.spectrum-Radio:focus .spectrum-Radio-button:after` +- `.spectrum-Radio:focus .spectrum-Radio-button:before` +- `.spectrum-Radio:focus .spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio:focus .spectrum-Radio-label` +- `.spectrum-Radio:hover .spectrum-Radio-button:before` +- `.spectrum-Radio:hover .spectrum-Radio-input:checked + .spectrum-Radio-button:before` +- `.spectrum-Radio:hover .spectrum-Radio-label` +- `.spectrum-Radio:lang(ja)` +- `.spectrum-Radio:lang(ko)` +- `.spectrum-Radio:lang(zh)` +- `.spectrum-Radio:not(.is-readOnly):active .spectrum-Radio-input:not(:disabled) + .spectrum-Radio-button` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-radio-animation-duration` +- `--mod-radio-border-width` +- `--mod-radio-button-background-color` +- `--mod-radio-button-border-color-default` +- `--mod-radio-button-border-color-down` +- `--mod-radio-button-border-color-focus` +- `--mod-radio-button-border-color-hover` +- `--mod-radio-button-checked-border-color-default` +- `--mod-radio-button-checked-border-color-down` +- `--mod-radio-button-checked-border-color-focus` +- `--mod-radio-button-checked-border-color-hover` +- `--mod-radio-button-control-size` +- `--mod-radio-button-top-to-control` +- `--mod-radio-disabled-border-color` +- `--mod-radio-disabled-content-color` +- `--mod-radio-emphasized-accent-color` +- `--mod-radio-emphasized-accent-color-down` +- `--mod-radio-emphasized-accent-color-focus` +- `--mod-radio-emphasized-accent-color-hover` +- `--mod-radio-focus-indicator-color` +- `--mod-radio-focus-indicator-thickness` +- `--mod-radio-font-size` +- `--mod-radio-height` +- `--mod-radio-line-height` +- `--mod-radio-line-height-cjk` +- `--mod-radio-neutral-content-color` +- `--mod-radio-neutral-content-color-down` +- `--mod-radio-neutral-content-color-focus` +- `--mod-radio-neutral-content-color-hover` +- `--mod-radio-text-to-control` + +
+ +### SWC + +
+Attributes + +- `autofocus` - Boolean attribute for auto-focusing the radio button +- `value` - String attribute identifying this radio button within its group +- `checked` - Boolean attribute representing when the input is checked +- `disabled` - Boolean attribute for disabled state +- `emphasized` - Boolean attribute for emphasized styling +- `invalid` - Boolean attribute for invalid state styling +- `readonly` - Boolean attribute for read-only state +- `size` - String attribute with values: `s`, `m`, `l`, `xl` (from SizedMixin) + +
+ +
+Slots + +- Default slot - Text label of the Radio button + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + +
+ + + + +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ + + +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + + +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**No differences found between main and spectrum-two branches.** + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ---------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------- | +| `.spectrum-Radio` | `:host` | Implemented | +| `.spectrum-Radio--emphasized` | `emphasized` attribute | Implemented | +| `.spectrum-Radio--sizeS` | `size="s"` attribute | Implemented | +| `.spectrum-Radio--sizeL` | `size="l"` attribute | Implemented | +| `.spectrum-Radio--sizeXL` | `size="xl"` attribute | Implemented | +| `.spectrum-Radio-input` | Internal radio input element, `#input` | Implemented | +| `.spectrum-Radio-input:checked` | `checked` attribute | Implemented | +| `.spectrum-Radio-input:disabled` | `disabled` attribute | Implemented | +| `.spectrum-Radio-button` | Internal radio button element, `#button` | Implemented | +| `.spectrum-Radio-label` | Default slot content | Implemented | +| `.spectrum-Radio-label:lang(ja)`, `.spectrum-Radio-label:lang(ko)`, `.spectrum-Radio-label:lang(zh)` | Language-specific styling | Implemented | +| `.spectrum-Radio.is-readOnly` | `readonly` attribute | Implemented | +| | `invalid` attribute | Missing from CSS | +| | `autofocus` attribute | Missing from CSS | + +## Summary of changes + +### CSS => SWC implementation gaps + +**New for S2:** +The radio component in Spectrum 2 has the new down state (active) perspective shift applied. + +### CSS Spectrum 2 changes + +No structural differences found between the legacy (CSS main) and Spectrum 2 (CSS spectrum-two) branches. The template structure and class naming remain consistent across both branches. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3555) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-radio--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/radiogroup--docs) diff --git a/migration-roadmap/switch.md b/migration-roadmap/switch.md new file mode 100644 index 00000000000..1acd2ca847e --- /dev/null +++ b/migration-roadmap/switch.md @@ -0,0 +1,261 @@ +# Switch migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-Switch` +- `.spectrum-Switch .spectrum-Switch-input:disabled + .spectrum-Switch-switch` +- `.spectrum-Switch .spectrum-Switch-input:disabled + .spectrum-Switch-switch:before` +- `.spectrum-Switch .spectrum-Switch-input:disabled ~ .spectrum-Switch-label` +- `.spectrum-Switch .spectrum-Switch-input:disabled:checked + .spectrum-Switch-switch` +- `.spectrum-Switch .spectrum-Switch-input:disabled:checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch .spectrum-Switch-input[disabled] + .spectrum-Switch-switch` +- `.spectrum-Switch .spectrum-Switch-input[disabled] + .spectrum-Switch-switch:before` +- `.spectrum-Switch .spectrum-Switch-input[disabled] ~ .spectrum-Switch-label` +- `.spectrum-Switch .spectrum-Switch-input[disabled]:checked + .spectrum-Switch-switch` +- `.spectrum-Switch .spectrum-Switch-input[disabled]:checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch--active .spectrum-Switch-input:checked + .spectrum-Switch-switch` +- `.spectrum-Switch--active .spectrum-Switch-input:checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch--active .spectrum-Switch-input:not(:disabled) + .spectrum-Switch-switch:before` +- `.spectrum-Switch--active .spectrum-Switch-input:not(:disabled):checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch--active .spectrum-Switch-input:not(:disabled):checked + .spectrum-Switch-switch:before:dir(rtl)` +- `.spectrum-Switch--disabled` +- `.spectrum-Switch--sizeL` +- `.spectrum-Switch--sizeS` +- `.spectrum-Switch--sizeXL` +- `.spectrum-Switch-input` +- `.spectrum-Switch-input:checked + .spectrum-Switch-switch` +- `.spectrum-Switch-input:checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch-input:checked + .spectrum-Switch-switch:before:dir(rtl)` +- `.spectrum-Switch-input:checked:focus-visible + .spectrum-Switch-switch` +- `.spectrum-Switch-input:disabled` +- `.spectrum-Switch-input:focus-visible + .spectrum-Switch-switch` +- `.spectrum-Switch-input:focus-visible + .spectrum-Switch-switch:after` +- `.spectrum-Switch-input:focus-visible + .spectrum-Switch-switch:before` +- `.spectrum-Switch-input:focus-visible ~ .spectrum-Switch-label` +- `.spectrum-Switch-input[disabled]` +- `.spectrum-Switch-label` +- `.spectrum-Switch-label:lang(ja)` +- `.spectrum-Switch-label:lang(ko)` +- `.spectrum-Switch-label:lang(zh)` +- `.spectrum-Switch-switch` +- `.spectrum-Switch-switch .spectrum-Switch--active` +- `.spectrum-Switch-switch:after` +- `.spectrum-Switch-switch:before` +- `.spectrum-Switch.spectrum-Switch--emphasized` +- `.spectrum-Switch.spectrum-Switch:active .spectrum-Switch-input:checked + .spectrum-Switch-switch` +- `.spectrum-Switch.spectrum-Switch:active .spectrum-Switch-input:checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch.spectrum-Switch:active .spectrum-Switch-switch` +- `.spectrum-Switch.spectrum-Switch:active .spectrum-Switch-switch:before` +- `.spectrum-Switch:active .spectrum-Switch-input:not(:disabled) + .spectrum-Switch-switch:before` +- `.spectrum-Switch:active .spectrum-Switch-input:not(:disabled):checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch:active .spectrum-Switch-input:not(:disabled):checked + .spectrum-Switch-switch:before:dir(rtl)` +- `.spectrum-Switch:active ~ .spectrum-Switch-label` +- `.spectrum-Switch:hover .spectrum-Switch-input:checked + .spectrum-Switch-switch` +- `.spectrum-Switch:hover .spectrum-Switch-input:checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch:hover .spectrum-Switch-input:disabled + .spectrum-Switch-switch` +- `.spectrum-Switch:hover .spectrum-Switch-input:disabled + .spectrum-Switch-switch:before` +- `.spectrum-Switch:hover .spectrum-Switch-input:disabled ~ .spectrum-Switch-label` +- `.spectrum-Switch:hover .spectrum-Switch-input:disabled:checked + .spectrum-Switch-switch` +- `.spectrum-Switch:hover .spectrum-Switch-input:disabled:checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch:hover .spectrum-Switch-input[disabled] + .spectrum-Switch-switch` +- `.spectrum-Switch:hover .spectrum-Switch-input[disabled] + .spectrum-Switch-switch:before` +- `.spectrum-Switch:hover .spectrum-Switch-input[disabled] ~ .spectrum-Switch-label` +- `.spectrum-Switch:hover .spectrum-Switch-input[disabled]:checked + .spectrum-Switch-switch` +- `.spectrum-Switch:hover .spectrum-Switch-input[disabled]:checked + .spectrum-Switch-switch:before` +- `.spectrum-Switch:hover .spectrum-Switch-switch` +- `.spectrum-Switch:hover .spectrum-Switch-switch:before` +- `.spectrum-Switch:hover ~ .spectrum-Switch-label` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-switch-animation-duration-switch` +- `--mod-switch-background-color` +- `--mod-switch-background-color-disabled` +- `--mod-switch-background-color-selected-default` +- `--mod-switch-background-color-selected-disabled` +- `--mod-switch-background-color-selected-down` +- `--mod-switch-background-color-selected-focus` +- `--mod-switch-background-color-selected-hover` +- `--mod-switch-border-color-default` +- `--mod-switch-border-color-disabled` +- `--mod-switch-border-color-down` +- `--mod-switch-border-color-focus` +- `--mod-switch-border-color-hover` +- `--mod-switch-border-color-selected-default` +- `--mod-switch-border-color-selected-down` +- `--mod-switch-border-color-selected-focus` +- `--mod-switch-border-color-selected-hover` +- `--mod-switch-border-radius` +- `--mod-switch-border-width` +- `--mod-switch-cjk-line-height` +- `--mod-switch-control-height` +- `--mod-switch-control-label-spacing` +- `--mod-switch-control-width` +- `--mod-switch-focus-indicator-color` +- `--mod-switch-focus-indicator-gap` +- `--mod-switch-focus-indicator-thickness` +- `--mod-switch-font-size` +- `--mod-switch-handle-background-color-default` +- `--mod-switch-handle-background-color-disabled` +- `--mod-switch-handle-background-color-down` +- `--mod-switch-handle-background-color-focus` +- `--mod-switch-handle-background-color-hover` +- `--mod-switch-handle-background-color-selected` +- `--mod-switch-handle-background-color-selected-disabled` +- `--mod-switch-handle-selected-size` +- `--mod-switch-handle-size` +- `--mod-switch-height` +- `--mod-switch-label-color-default` +- `--mod-switch-label-color-disabled` +- `--mod-switch-label-color-down` +- `--mod-switch-label-color-focus` +- `--mod-switch-label-color-hover` +- `--mod-switch-line-height` +- `--mod-switch-spacing-bottom-to-label` +- `--mod-switch-spacing-top-to-control` +- `--mod-switch-spacing-top-to-label` + +
+ +### SWC + +
+Attributes + +- `emphasized` - Boolean attribute for emphasized styling +- `checked` - Boolean attribute for checked state (inherited from CheckboxBase) +- `disabled` - Boolean attribute for disabled state (inherited from CheckboxBase) +- `size` - String attribute with values: `s`, `m`, `l`, `xl` (from SizedMixin) +- `readonly` - Boolean attribute for read-only state +- `autofocus` - Boolean attribute for auto-focusing the switch input + +
+ +
+Slots + +- Default slot - Text label of the Switch + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + + + + +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ + + +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + + +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**No differences found between main and spectrum-two branches.** + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------- | +| `.spectrum-Switch` | `:host` | Implemented | +| `.spectrum-Switch--disabled` | `disabled` attribute | Implemented | +| `.spectrum-Switch--emphasized` | `emphasized` attribute | Implemented | +| `.spectrum-Switch--sizeS` | `size="s"` attribute | Implemented | +| `.spectrum-Switch--sizeL` | `size="l"` attribute | Implemented | +| `.spectrum-Switch--sizeXL` | `size="xl"` attribute | Implemented | +| `.spectrum-Switch-input` | Internal input element, `#input` | Implemented | +| `.spectrum-Switch-input:checked` | `checked` attribute | Implemented | +| `.spectrum-Switch-input:disabled` | `disabled` attribute | Implemented | +| `.spectrum-Switch-switch` | Internal switch element, `#switch` | Implemented | +| `.spectrum-Switch-label` | Default slot content | Implemented | +| `.spectrum-Switch-label:lang(ja)`, `.spectrum-Switch-label:lang(ko)`, `.spectrum-Switch-label:lang(zh)` | Language-specific styling | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +**New for S2:** +The switch component in Spectrum 2 has the new down state (active) perspective shift applied. + +### CSS Spectrum 2 changes + +No structural differences found between the legacy (CSS main) and Spectrum 2 (CSS spectrum-two) branches. The template structure and class naming remain consistent across both branches. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2651) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-switch--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/switch--docs) From 6642d8ca10e6e705edc1610a87287501e3582a67 Mon Sep 17 00:00:00 2001 From: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com> Date: Wed, 1 Oct 2025 11:33:05 -1000 Subject: [PATCH 6/9] docs: textfield-based component analysis docs (#5741) --- migration-roadmap/README.md | 181 +++++++++ migration-roadmap/color-field.md | 142 +++++++ migration-roadmap/number-field.md | 494 +++++++++++++++++++++++ migration-roadmap/search.md | 491 ++++++++++++++++------- migration-roadmap/textfield.md | 623 ++++++++++++++++++++++++++++++ 5 files changed, 1799 insertions(+), 132 deletions(-) create mode 100644 migration-roadmap/README.md create mode 100644 migration-roadmap/color-field.md create mode 100644 migration-roadmap/number-field.md create mode 100644 migration-roadmap/textfield.md diff --git a/migration-roadmap/README.md b/migration-roadmap/README.md new file mode 100644 index 00000000000..79f134db498 --- /dev/null +++ b/migration-roadmap/README.md @@ -0,0 +1,181 @@ +# Spectrum 2 migration roadmap + +This directory contains comprehensive migration documentation for 2nd generation Spectrum Web Components based on the implementation of Spectrum 2 components that were previously migrated in [Spectrum CSS](https://github.com/adobe/spectrum-css/tree/spectrum-two). It helps engineers understand what needs to be implemented, updated, or aligned between the two systems to guide development of 2nd generation web components. + +## Purpose + +### Why we do this analysis + +The migration roadmap facilitates development of 2nd generation, full-fidelity Spectrum 2 web components by providing: + +- **Feature gap analysis**: Identifies new features and capabilities needed to match Spectrum 2 design specifications +- **Implementation comparison**: Maps CSS selectors to existing SWC properties and notes markup differences between systems +- **Deprecation tracking**: Documents features or variants being removed in Spectrum 2 +- **Planning guidance**: High-level overview of changes to assist with estimating migration effort + +### The bigger picture + +When engineers begin 2nd generation Spectrum 2 implementation work, this documentation provides: + +- **Clear starting point**: Entry point for development work that identifies specific areas needing adjustment +- **Gap analysis**: Differences that would prevent Spectrum 2 CSS from working in SWC +- **Reference materials**: Links to CSS and React implementations, and previous migration work + +## What we analyze + +### Component specifications + +We extract and document: + +- **CSS selectors**: All selectors from `metadata.json` in the spectrum-css `spectrum-two` branch +- **Passthroughs**: CSS passthrough custom properties +- **Modifiers**: CSS modifier custom properties (note that `--mod` properties will be deprecated in the 2nd-gen implementation) +- **SWC attributes**: Properties with `@property` decorators (which use getter/setter patterns) in TypeScript +- **SWC slots**: Slot patterns from render methods +- **Nested components**: Child components used within the component + +### DOM structure comparison + +We analyze markup from three sources: + +1. **Spectrum Web Components**: Current HTML structure from web component `render()` method +2. **Legacy CSS**: HTML structure from spectrum-css `main` branch template files +3. **Spectrum 2 CSS**: HTML structure from spectrum-css `spectrum-two` branch template files + +This three-way comparison reveals: + +- DOM changes specific to Spectrum 2 features (Legacy → Spectrum 2) +- Structural differences between CSS and SWC implementations +- Additional work needed for SWC render methods beyond new features + +### CSS to SWC mapping + +We create mapping tables that connect: + +- **CSS selectors** to **SWC attributes or slots** +- **Variants** (CSS selectors with `--` notation) typically map to component attributes +- **Base elements** (selectors with single `-`) typically map to slots +- **Status tracking** for implementation gaps + +### Implementation gaps + +The analysis surfaces: + +- **Missing from SWC**: CSS features without web component equivalents +- **Missing from CSS**: Web component features without CSS support +- **New for Spectrum 2**: Features that need to be added for 2nd generation +- **Deprecated**: Features being removed in Spectrum 2 + +## Documentation structure + +Each component follows this format: + +```markdown +# [Component name] migration roadmap + +## Component specifications + +**Note**: CSS selectors and attributes/slots are often grouped by elements, states, variants, or other logical categories to improve readability. + +### CSS + +- CSS selectors (collapsible) +- Passthroughs (collapsible) +- Modifiers (deprecated) (collapsible) + +### SWC + +- Attributes (collapsible) +- Slots (collapsible) + +## Comparison + +### DOM structure changes + +- Spectrum Web Components (collapsible) +- Legacy CSS main branch (collapsible) +- Spectrum 2 CSS spectrum-two branch (collapsible) +- Diff: Legacy → Spectrum 2, based on changes made to template in CSS migration work (collapsible, if changes exist) + +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ------------ | ----------------- | ------------------------------------------------------- | +| ... | ... | Implemented/Missing from WC/Missing from CSS/Deprecated | + +## Summary of changes + +### CSS => SWC implementation gaps + +### CSS Spectrum 2 changes + +**Note**: Some of this information may be summarized in the component's changelog in the spectrum-two branch. + +## Resources + +- [CSS migration]() +- [Spectrum 2 preview]() +- [React]() +``` + +## How to generate documentation + +### Prerequisites + +Set up a Cursor workspace with both repositories: + +- `spectrum-css` (primarily `spectrum-two` branch, with comparisons to `main`) +- `spectrum-web-components` (`main` branch) + +### Using the cursor prompt + +**Model recommendation**: This type of detailed migration analysis is better handled by slower but more advanced thinking models like Claude or GPT-5, which can provide more thorough analysis and better understand complex component relationships. + +1. **Load the prompt**: Reference `migration-roadmap/cursor_prompt.md` +2. **Specify component**: Replace `[COMPONENT_NAME]` with the target component +3. **Branch verification**: Ensure correct branches are checked out: + - `spectrum-css`: `spectrum-two` for specifications, both `main` and `spectrum-two` for comparisons + - `spectrum-web-components`: `main` branch +4. **Generate documentation**: Follow the structured prompt to create component markdown files + +### Quality assurance + +**Human review is required** for all generated documentation: + +- **Verify data accuracy**: Check extracted information against source repositories/branches +- **Validate mappings**: Ensure CSS selector to SWC feature mappings are correct +- **Review summaries**: Confirm summaries provide clear, actionable guidance +- **Check DOM structures**: Verify HTML snippets match actual template/render method output +- **Audit diffs**: Ensure branch comparisons are accurate and meaningful + +### Common issues to watch for + +- **Branch confusion**: AI may analyze wrong branches or mix up repositories +- **Incomplete mappings**: AI may incorrectly mark implemented states or variants as missing in mapping tables +- **Verbose summaries**: Trim AI-generated text to focus on actionable changes and human readability +- **DOM accuracy**: Verify render method HTML matches documented structure +- **Missing components**: Note when components don't exist in one system or the other + +## Contributing + +### Modifying the cursor prompt + +The cursor prompt template (`cursor_prompt.md`) can be modified to improve AI performance. Consider updates for: + +- Better mapping accuracy +- Clearer summary generation +- Additional analysis sections +- Improved error handling + +### Adding new components + +1. Use the cursor prompt with the target component name +2. Generate the markdown file in `migration-roadmap/[component-name].md` +3. Review and validate all sections for accuracy +4. Submit a PR to the `2nd-gen-component-analysis` branch + +## Resources + +- [Cursor prompt template](cursor_prompt.md) +- [Spectrum CSS repository](https://github.com/adobe/spectrum-css) +- [Spectrum Web Components repository](https://github.com/adobe/spectrum-web-components) diff --git a/migration-roadmap/color-field.md b/migration-roadmap/color-field.md new file mode 100644 index 00000000000..5ad6c3473b0 --- /dev/null +++ b/migration-roadmap/color-field.md @@ -0,0 +1,142 @@ +# Color field migration roadmap + +There is no CSS implementation for this component; it only exists in SWC. + +## Component specifications + +### SWC + +
+Attributes + +**Color Field specific attributes:** + +- `view-color` - Whether to show the color preview + +**Inherited from TextfieldBase:** + +- `allowed-keys` - A regular expression outlining the keys that will be allowed to update the value +- `autocomplete` - What form of assistance should be provided when attempting to supply a value +- `focused` - Whether the color field is focused +- `grows` - Whether a form control with multiline attribute will change size vertically +- `invalid` - Whether the color field is invalid +- `label` - A string applied via aria-label to the form control when a user visible label is not provided +- `maxlength` - Defines the maximum string length that the user can enter +- `minlength` - Defines the minimum string length that the user can enter +- `multiline` - Whether the form control should accept a value longer than one line +- `name` - Name of the form control +- `pattern` - Pattern the value must match to be valid +- `placeholder` - Text that appears in the form control when it has no value set +- `quiet` - Whether to display the form control with no visible background +- `readonly` - Whether a user can interact with the value of the form control +- `required` - Whether the form control will be found to be invalid when it holds no value +- `rows` - The specific number of rows the form control should provide in the user interface +- `type` - The type of the form control (defaults to 'text') +- `valid` - Whether the value held by the form control is valid +- `value` - The value held by the form control + +**Inherited from SizedMixin:** + +- `size` - Size of the color field (s, m, l, xl) + +**Inherited from Focusable:** + +- `autofocus` - When this control is rendered, focus it automatically +- `disabled` - Disable this control. It will not receive focus or events +- `tabIndex` - The tab index to apply to this control + +
+ +
+Slots + +- `help-text` - Help text for the color field (inherited from TextfieldBase) +- `negative-help-text` - Negative help text when invalid (inherited from TextfieldBase) + +
+ +### React implementation + +
+Props + +- `label` - The label for the color field +- `autoFocus` - Whether the element should receive focus on render +- `channel` - The color channel that this field edits, if not provided, the color is edited as a hex value (`hue` | `saturation` | `brightness` | `lightness` | `red` | `green` | `blue` | `alpha`) +- `colorSpace` - The color space that the color field operates in if a channel prop is provided, if no channel is provided, the color field always displays the color as an RGB hex value (`rgb` | `hsl` | `hsb`) +- `defaultValue` - The default value +- `description` - A description for the field, provides a hint such as specific requirements for what to choose +- `errorMessage` - An error message for the field +- `excludeFromTabOrder` - Whether to exclude the element from the sequential tab order +- `form` - The `
` element to associate the input with +- `isDisabled` - Whether the input is disabled +- `isInvalid` - Whether the input value is invalid +- `isReadonly` - Whether the input can be selected but not changed by the user +- `isRequired` - Whether the color field is required before form submission +- `isWheelDisabled` - Enables or disables changing the value with scroll +- `labelAlign` - The label's horizontal alignment relative to the element it is labeling (`start` | `end`) +- `labelPosition` - The label's overall position relative to the element it is labeling (`top` | `side`) +- `name` - The name of the input element, used when submitting an HTML form +- `necessityIndicator` +- `size` - Size of the color field (s, m, l, xl) +- `validate` - A function that returns an error message if a given value is invalid +- `validationBehavior` - Whether to use native HTML form validation to prevent form submission when the value is missing or invalid +- `value` - The value of the color field + +
+ +## DOM structure + +### SWC DOM structure + +```html +
+ + + + + + + +
+ + +
+ + + +
+ + + +``` + +## Summary of changes + +### Inherited from TextfieldBase + +The ColorField component extends TextfieldBase, which means it will inherit all the changes and improvements made to the Textfield component in Spectrum 2 CSS, for example: + +- **Quiet variant**: removed in Spectrum 2 +- **Label position**: CSS supports side label as well as the default top label + +## Resources + +- [Spectrum React ColorField documentation](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorfield--docs) diff --git a/migration-roadmap/number-field.md b/migration-roadmap/number-field.md new file mode 100644 index 00000000000..eb25f83a63d --- /dev/null +++ b/migration-roadmap/number-field.md @@ -0,0 +1,494 @@ +# Number field migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Base component:** + +- `.spectrum-NumberField` +- `.spectrum-NumberField:before` +- `.spectrum-NumberField:lang(ja), .spectrum-NumberField:lang(ko), .spectrum-NumberField:lang(zh)` + +**Variants:** + +- `.spectrum-NumberField.spectrum-NumberField--hiddenStepper` +- `.spectrum-NumberField.spectrum-NumberField--hiddenStepper .spectrum-NumberField-textfield` +- `.spectrum-NumberField.spectrum-NumberField--hiddenStepper .spectrum-NumberField-textfield .spectrum-NumberField-input` +- `.spectrum-NumberField.spectrum-NumberField--hiddenStepper .spectrum-NumberField-textfield.spectrum-Textfield.is-invalid .spectrum-Textfield-validationIcon` +- `.spectrum-NumberField.spectrum-NumberField--hiddenStepper .spectrum-NumberField-textfield:not(:has(.spectrum-Textfield-validationIcon)) .spectrum-NumberField-input` +- `.spectrum-NumberField.spectrum-NumberField--sideLabel` +- `.spectrum-NumberField.spectrum-NumberField--sideLabel .spectrum-NumberField-fieldLabel` +- `.spectrum-NumberField.spectrum-NumberField--sideLabel .spectrum-NumberField-helpText` +- `.spectrum-NumberField.spectrum-NumberField--sideLabel .spectrum-NumberField-inputs` +- `.spectrum-NumberField.spectrum-NumberField--sizeL` +- `.spectrum-NumberField.spectrum-NumberField--sizeS` +- `.spectrum-NumberField.spectrum-NumberField--sizeXL` + +**Child elements:** + +- `.spectrum-NumberField-buttons` +- `.spectrum-NumberField-fieldLabel` +- `.spectrum-NumberField-helpText` +- `.spectrum-NumberField-inputs` +- `.spectrum-NumberField-inputs .spectrum-Textfield .spectrum-Textfield-input` +- `.spectrum-NumberField-inputs .spectrum-Textfield.is-invalid .spectrum-NumberField-input` + +**Input element:** + +- `.spectrum-NumberField-input` +- `.spectrum-NumberField-textfield` + +**States:** + +- `.spectrum-NumberField-textfield.spectrum-Textfield.is-invalid .spectrum-Textfield-validationIcon` +- `.spectrum-NumberField.is-disabled` +- `.spectrum-NumberField.is-focused.is-hover:not(.is-disabled)` +- `.spectrum-NumberField.is-focused.is-hover:not(.is-disabled, .is-readOnly)` +- `.spectrum-NumberField.is-focused:not(.is-disabled)` +- `.spectrum-NumberField.is-focused:not(.is-disabled):hover` +- `.spectrum-NumberField.is-focused:not(.is-disabled, .is-readOnly)` +- `.spectrum-NumberField.is-focused:not(.is-disabled, .is-readOnly):hover` +- `.spectrum-NumberField.is-hover:not(.is-disabled)` +- `.spectrum-NumberField.is-hover:not(.is-disabled):focus` +- `.spectrum-NumberField.is-hover:not(.is-disabled):focus-visible` +- `.spectrum-NumberField.is-hover:not(.is-disabled):focus-within` +- `.spectrum-NumberField.is-hover:not(.is-disabled, .is-readOnly)` +- `.spectrum-NumberField.is-hover:not(.is-disabled, .is-readOnly):focus` +- `.spectrum-NumberField.is-hover:not(.is-disabled, .is-readOnly):focus-visible` +- `.spectrum-NumberField.is-hover:not(.is-disabled, .is-readOnly):focus-within` +- `.spectrum-NumberField.is-invalid` +- `.spectrum-NumberField.is-keyboardFocused.is-hover:not(.is-disabled)` +- `.spectrum-NumberField.is-keyboardFocused.is-hover:not(.is-disabled, .is-readOnly)` +- `.spectrum-NumberField.is-keyboardFocused:not(.is-disabled)` +- `.spectrum-NumberField.is-keyboardFocused:not(.is-disabled):hover` +- `.spectrum-NumberField.is-keyboardFocused:not(.is-disabled, .is-readOnly)` +- `.spectrum-NumberField.is-keyboardFocused:not(.is-disabled, .is-readOnly) .spectrum-NumberField-inputs` +- `.spectrum-NumberField.is-keyboardFocused:not(.is-disabled, .is-readOnly):hover` +- `.spectrum-NumberField.is-readOnly` + +**Interactive states:** + +- `.spectrum-NumberField:focus-visible .spectrum-NumberField-inputs` +- `.spectrum-NumberField:not(.is-disabled):focus` +- `.spectrum-NumberField:not(.is-disabled):focus-visible` +- `.spectrum-NumberField:not(.is-disabled):focus-visible:hover` +- `.spectrum-NumberField:not(.is-disabled):focus-within` +- `.spectrum-NumberField:not(.is-disabled):focus-within:hover` +- `.spectrum-NumberField:not(.is-disabled):focus:hover` +- `.spectrum-NumberField:not(.is-disabled):hover` +- `.spectrum-NumberField:not(.is-disabled, .is-readOnly):focus` +- `.spectrum-NumberField:not(.is-disabled, .is-readOnly):focus-visible` +- `.spectrum-NumberField:not(.is-disabled, .is-readOnly):focus-visible:hover` +- `.spectrum-NumberField:not(.is-disabled, .is-readOnly):focus-within` +- `.spectrum-NumberField:not(.is-disabled, .is-readOnly):focus-within:hover` +- `.spectrum-NumberField:not(.is-disabled, .is-readOnly):focus:hover` +- `.spectrum-NumberField:not(.is-disabled, .is-readOnly):hover` + +
+ +
+Passthroughs + +- `--mod-textfield-background-color` +- `--mod-textfield-background-color-disabled` +- `--mod-textfield-font-family` +- `--mod-textfield-font-size` +- `--mod-textfield-font-style` +- `--mod-textfield-font-weight` +- `--mod-textfield-height` +- `--mod-textfield-icon-spacing-block-invalid` +- `--mod-textfield-spacing-block-end` +- `--mod-textfield-spacing-block-start` +- `--mod-textfield-text-color-default` +- `--mod-textfield-text-color-disabled` +- `--mod-textfield-text-color-focus` +- `--mod-textfield-width` + +
+ +
+Modifiers (deprecated) + +- `--mod-numberfield-background-color` +- `--mod-numberfield-background-color-disabled` +- `--mod-numberfield-block-size` +- `--mod-numberfield-border-color` +- `--mod-numberfield-border-color-disabled` +- `--mod-numberfield-border-color-focus` +- `--mod-numberfield-border-color-focus-hover` +- `--mod-numberfield-border-color-focus-hover-invalid` +- `--mod-numberfield-border-color-focus-invalid` +- `--mod-numberfield-border-color-hover` +- `--mod-numberfield-border-color-hover-invalid` +- `--mod-numberfield-border-color-invalid` +- `--mod-numberfield-border-color-invalid-default` +- `--mod-numberfield-border-color-invalid-focus` +- `--mod-numberfield-border-color-invalid-focus-hover` +- `--mod-numberfield-border-color-invalid-hover` +- `--mod-numberfield-border-color-invalid-keyboard-focus` +- `--mod-numberfield-border-color-keyboard-focus` +- `--mod-numberfield-border-color-keyboard-focus-invalid` +- `--mod-numberfield-border-radius` +- `--mod-numberfield-border-width` +- `--mod-numberfield-button-inline-offset` +- `--mod-numberfield-focus-indicator-color` +- `--mod-numberfield-focus-indicator-gap` +- `--mod-numberfield-focus-indicator-width` +- `--mod-numberfield-font-family` +- `--mod-numberfield-font-size` +- `--mod-numberfield-font-style` +- `--mod-numberfield-font-weight` +- `--mod-numberfield-hidden-stepper-min-inline-size` +- `--mod-numberfield-inline-size` +- `--mod-numberfield-label-to-field` +- `--mod-numberfield-line-height` +- `--mod-numberfield-min-inline-size` +- `--mod-numberfield-spacing-block-end-edge-to-text` +- `--mod-numberfield-spacing-block-start-edge-to-text` +- `--mod-numberfield-spacing-field-to-helptext` +- `--mod-numberfield-text-color` +- `--mod-numberfield-text-color-disabled` +- `--mod-numberfield-text-color-focus` +- `--mod-numberfield-text-color-focus-hover` +- `--mod-numberfield-text-color-hover` +- `--mod-numberfield-text-color-keyboard-focus` + +
+ +### SWC + +
+Attributes + +**Number Field specific attributes:** + +- `format-options` (Object) - Intl.NumberFormatOptions for customizing number formatting +- `hide-stepper` (Boolean) - Whether the stepper UI is hidden or not +- `indeterminate` (Boolean) - Indeterminate state +- `keyboard-focused` (Boolean) - Keyboard focus state +- `max` (Number) - Maximum value +- `min` (Number) - Minimum value +- `step` (Number) - Step increment value +- `step-modifier` (Number) - Step modifier for shift key behavior +- `value` (Number) - Current value (overrides TextfieldBase) + +**Inherited from TextfieldBase:** + +- `allowed-keys` - A regular expression outlining the keys that will be allowed to update the value +- `autocomplete` - What form of assistance should be provided when attempting to supply a value +- `focused` - Whether the number field is focused (overridden by NumberField) +- `grows` - Whether a form control with multiline attribute will change size vertically +- `invalid` - Whether the number field is invalid +- `label` - A string applied via aria-label to the form control when a user visible label is not provided +- `maxlength` - Defines the maximum string length that the user can enter +- `minlength` - Defines the minimum string length that the user can enter +- `multiline` - Whether the form control should accept a value longer than one line (forced to false) +- `name` - Name of the form control +- `pattern` - Pattern the value must match to be valid +- `placeholder` - Text that appears in the form control when it has no value set +- `quiet` - Whether to display the form control with no visible background +- `readonly` - Whether a user can interact with the value of the form control +- `required` - Whether the form control will be found to be invalid when it holds no value +- `rows` - The specific number of rows the form control should provide in the user interface +- `type` - The type of the form control (defaults to 'text') +- `valid` - Whether the value held by the form control is valid + +**Inherited from SizedMixin:** + +- `size` - Size of the number field (s, m, l, xl) + +**Inherited from Focusable:** + +- `autofocus` - When this control is rendered, focus it automatically +- `disabled` - Disable this control. It will not receive focus or events +- `tabIndex` - The tab index to apply to this control + +
+ +
+Slots + +- `help-text` - Default or non-negative help text to associate to your form element +- `negative-help-text` - Negative help text to associate to your form element when `invalid` + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html +
+ + + + + + + + + + + + + +
+ + +
+ + + +
+``` + +
+ +
+Legacy (CSS main branch): + +```html +
+
+ +
+ + + + +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ +
+
+ +
+ +
+ + +
+ +
+
+
+
Help text
+
+
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**Key changes in spectrum-two**: + +- Base class changes from `.spectrum-Stepper` to `.spectrum-NumberField` +- Addition of field label with `.spectrum-NumberField-fieldLabel` class +- New wrapper div with `.spectrum-NumberField-inputs` class around textfield and buttons +- Removal of `--top` and `--bottom` modifier classes from infield buttons + +```diff +--- a/components/stepper/stories/template.js (main branch) ++++ b/components/stepper/stories/template.js (spectrum-two branch) +@@ -1,1 +1,3 @@ +-
++
++ ++
+@@ -3,4 +5,4 @@ +-
+- ++
++ +
+- +- +- ++ ++
++ ++ ++
+ ++
++
++
++
Help text
++
++
+
+``` + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------- | +| `.spectrum-NumberField` | `:host`/base component | Implemented | +| `.spectrum-NumberField--sizeS` | `size="s"` | Implemented | +| `.spectrum-NumberField--sizeL` | `size="l"` | Implemented | +| `.spectrum-NumberField--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-NumberField--hiddenStepper` | `hide-stepper` | Implemented | +| `.spectrum-NumberField.is-disabled` | `disabled` | Implemented | +| `.spectrum-NumberField.is-readOnly` | `readonly` | Implemented | +| `.spectrum-NumberField.is-invalid` | `invalid` | Implemented | +| `.spectrum-NumberField-fieldLabel` | `` (sibling element) | Implemented | +| `.spectrum-NumberField-helpText` | `help-text` slot | Implemented | +| `.spectrum-NumberField:lang(ja), .spectrum-NumberField:lang(ko), .spectrum-NumberField:lang(zh)` | Language-specific styling | Implemented | +| `.spectrum-NumberField-buttons` | Stepper buttons (``) | Implemented | +| `.spectrum-NumberField-inputs` | Wrapper for textfield and button inputs (`
`) | Implemented | +| `.spectrum-NumberField-textfield` | Textfield wrapper inside of `
` | Missing from WC (markup updated for S2) | +| `.spectrum-NumberField--sideLabel` | `label-position` | Missing from WC (SWC has different side label implementation) | + +## Summary of changes + +### CSS => SWC implementation gaps + +The following features are missing from the web component implementation: + +- **Side label positioning**: As also seen in textfield, CSS supports `--sideLabel` modifier but there's no corresponding attribute in the web component +- **Quiet variant removal**: Also seen in textfield, the quiet variant no longer exists in full-fidelity Spectrum 2 implementations. + +Note: There are some differences in markup between SWC and Spectrum 2 CSS that will likely require some additional adjustment during SWC migration. + +### CSS Spectrum 2 changes + +The migration from legacy CSS (main branch) to Spectrum 2 (spectrum-two branch) represents a significant architectural change: + +**Component rename**: The component's classnames were renamed from `.spectrum-Stepper` to `.spectrum-NumberField` in order to be more consistent with SWC. + +- The `.hide-stepper` class was converted to `.spectrum-NumberField--hiddenStepper` + +**Structural changes and feature additions**: + +- Markup for `spectrum-two` CSS embeds field label and help text components +- Introduced `spectrum-NumberField-inputs` container wrapper +- Added side label positioning with `--sideLabel` modifier +- The embedded infield buttons used in the Number field have changed. Rather than being stacked vertically and sitting directly on the edge of the input field, infield buttons now sit side by side, with spacing around them on all sides. +- The `spectrum-two` CSS for Number field now has styles for read-only + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3681) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-number-field--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/numberfield--docs) diff --git a/migration-roadmap/search.md b/migration-roadmap/search.md index 15d72f6ed09..5e920467f67 100644 --- a/migration-roadmap/search.md +++ b/migration-roadmap/search.md @@ -1,33 +1,53 @@ # Search migration roadmap +## Component specifications + +### CSS +
CSS selectors +**Base component:** + - `.spectrum-Search` -- `.spectrum-Search .spectrum-HelpText` -- `.spectrum-Search .spectrum-Search-clearButton .spectrum-ClearButton-fill` -- `.spectrum-Search .spectrum-Search-textfield` -- `.spectrum-Search .spectrum-Search-textfield .spectrum-Search-input` +- `.spectrum-Search:lang(ja)` +- `.spectrum-Search:lang(ko)` +- `.spectrum-Search:lang(zh)` + +**Variants:** + - `.spectrum-Search--sizeL` - `.spectrum-Search--sizeS` - `.spectrum-Search--sizeXL` + +**Child elements:** + +- `.spectrum-Search .spectrum-HelpText` +- `.spectrum-Search .spectrum-Search-textfield` +- `.spectrum-Search .spectrum-Search-textfield .spectrum-Search-input` +- `.spectrum-Search .spectrum-Search-clearButton .spectrum-ClearButton-fill` - `.spectrum-Search-clearButton` - `.spectrum-Search-clearButton .spectrum-ClearButton-fill` - `.spectrum-Search-icon` +- `.spectrum-Search-textfield` + +**Input element:** + - `.spectrum-Search-input` - `.spectrum-Search-input::-webkit-search-cancel-button` - `.spectrum-Search-input::-webkit-search-decoration` -- `.spectrum-Search-textfield` + +**States:** + +- `.spectrum-Search.is-collapsed` +- `.spectrum-Search.is-disabled .spectrum-Search-clearButton` +- `.spectrum-Search.is-expanded` - `.spectrum-Search-textfield.is-disabled .spectrum-Search-icon` - `.spectrum-Search-textfield.is-disabled:hover .spectrum-Search-icon` - `.spectrum-Search-textfield.is-focused .spectrum-Search-icon` - `.spectrum-Search-textfield.is-focused:hover .spectrum-Search-icon` - `.spectrum-Search-textfield.is-keyboardFocused .spectrum-Search-icon` - `.spectrum-Search-textfield:hover .spectrum-Search-icon` -- `.spectrum-Search.is-collapsed` -- `.spectrum-Search.is-disabled .spectrum-Search-clearButton` -- `.spectrum-Search.is-expanded` -- `.spectrum-Search:lang(ja)`, `.spectrum-Search:lang(ko)`, `.spectrum-Search:lang(zh)`
@@ -60,31 +80,7 @@
-Attributes - -- `action` (String) - Form action attribute -- `label` (String) - Label for the search field (default: "Search") -- `method` (String) - Form method (`get`, `post`, `dialog`) -- `placeholder` (String) - Placeholder text (default: "Search") -- `holdValueOnEscape` (Boolean) - Whether to hold the value when Escape is pressed -- `value` (String) - Current search input value -- `size` (String) - Search field size (`s`, `m`, `l`, `xl`) -- `disabled` (Boolean) - Whether the search field is disabled -- `invalid` (Boolean) - Whether the search field is in an invalid state -- `quiet` (Boolean) - Whether to use the quiet variant - -
- -
-Slots - -- `help-text` - Default or non-negative help text to associate to your form element -- `negative-help-text` - Negative help text to associate to your form element when `invalid` - -
- -
-Modifiers +Modifiers (Deprecated) - `--mod-search-background-color` - `--mod-search-background-color-disabled` @@ -124,28 +120,149 @@
-## Visual Comparison +### SWC -**Legacy Component:** +
+Attributes + +**Search specific attributes:** + +- `action` (string) - Form action URL +- `holdValueOnEscape` (boolean) - Whether the typed value should be held when Escape key is pressed +- `label` (string) - defaults to "Search" (overrides Textfield) +- `method` (string) - Form method: "get" | "post" | "dialog" +- `placeholder` (string) - defaults to "Search" (overrides Textfield) + +**Inherited from Textfield (extends TextfieldBase):** + +- `allowed-keys` - A regular expression outlining the keys that will be allowed to update the value +- `autocomplete` - What form of assistance should be provided when attempting to supply a value +- `focused` - Whether the search field is focused +- `grows` - Whether a form control with multiline attribute will change size vertically +- `invalid` - Whether the search field is invalid +- `maxlength` - Defines the maximum string length that the user can enter +- `minlength` - Defines the minimum string length that the user can enter +- `multiline` - Whether the form control should accept a value longer than one line (forced to false) +- `name` - Name of the form control +- `pattern` - Pattern the value must match to be valid +- `quiet` - Whether to display the form control with no visible background +- `readonly` - Whether a user can interact with the value of the form control +- `required` - Whether the form control will be found to be invalid when it holds no value +- `rows` - The specific number of rows the form control should provide in the user interface +- `type` - The type of the form control (set to 'search' automatically) +- `valid` - Whether the value held by the form control is valid +- `value` - The value held by the form control - +**Inherited from SizedMixin:** -**Spectrum 2 Component:** +- `size` - Size of the search field (s, m, l, xl) - +**Inherited from Focusable:** -## DOM Structure Changes +- `autofocus` - When this control is rendered, focus it automatically +- `disabled` - Disable this control. It will not receive focus or events +- `tabIndex` - The tab index to apply to this control -**Legacy (main branch):** +
+ +
+Slots + +- `help-text` - default or non-negative help text to associate to your form element +- `negative-help-text` - negative help text to associate to your form element when `invalid` + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: ```html - + +
+ + + + + + + + + + + + + + + +
+ + +
+ + + +
+``` + +
+ +
+Legacy (CSS main branch): + +```html +
+
+ focusable="false" + aria-hidden="true" + role="img" + > + Magnify + +
- -
[help text]
+ +
+ +
``` -**Spectrum 2 (spectrum-two branch):** +
+ +
+Spectrum 2 (CSS spectrum-two branch): ```html +
+ class="spectrum-Icon spectrum-Search-icon spectrum-Icon--sizeM" + focusable="false" + aria-hidden="true" + role="img" + > + Search + +
- -
[help text]
+ +
+ +
-``` - -## Comparison - -| CSS selector | Attribute or slot | Status | -| ------------------------------------------------------------------------------------- | ----------------------------- | ---------------- | -| `.spectrum-Search` | Root element | Implemented | -| `.spectrum-Search--sizeS` | `size="s"` | Implemented | -| `.spectrum-Search--sizeL` | `size="l"` | Implemented | -| `.spectrum-Search--sizeXL` | `size="xl"` | Implemented | -| `.spectrum-Search-textfield` | Textfield wrapper | Implemented | -| `.spectrum-Search-input` | Input element | Implemented | -| `.spectrum-Search-icon` | Search icon | Implemented | -| `.spectrum-Search-clearButton` | Clear button | Implemented | -| `.spectrum-Search .spectrum-HelpText` | Help text element | Implemented | -| `.spectrum-Search.is-collapsed` | Collapsed state | Missing from WC | -| `.spectrum-Search.is-expanded` | Expanded state | Missing from WC | -| `.spectrum-Search.is-disabled` | `disabled` attribute | Implemented | -| `.spectrum-Search-textfield.is-focused` | Focus state | Implemented | -| `.spectrum-Search-textfield.is-keyboardFocused` | Keyboard focus state | Implemented | -| `.spectrum-Search:lang(ja)`, `.spectrum-Search:lang(ko)`, `.spectrum-Search:lang(zh)` | Language-specific styling | Implemented | -| - | `action` attribute | Missing from CSS | -| - | `method` attribute | Missing from CSS | -| - | `holdValueOnEscape` attribute | Missing from CSS | -| - | `help-text` slot | Missing from CSS | -| - | `negative-help-text` slot | Missing from CSS | - -## Key Structural Changes - -**Element Hierarchy Changes:** - -- No significant hierarchy changes between main and spectrum-two branches -- Maintained consistent form > textfield > input structure - -**Class Name Changes:** - -- No major class name changes -- Consistent naming convention maintained - -**Attribute Changes:** - -- Added `action` and `method` attributes for form functionality -- Added `holdValueOnEscape` for controlling escape key behavior -- Added `label` attribute for accessibility -- Extended Textfield functionality with search-specific features - -**Slot/Content Changes:** -- Added `help-text` slot for descriptive text -- Added `negative-help-text` slot for error messaging -- Inherits all Textfield slots and functionality - -**Migration Impact:** - -- Search component extends Textfield providing all textfield functionality -- Enhanced form handling with action and method support -- Better accessibility with automatic labeling + + +``` -### Implementation Gaps +
-**CSS Features Missing from Web Component:** +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff +--- a/components/search/stories/template.js (main branch) ++++ b/components/search/stories/template.js (spectrum-two branch) +@@ -1,1 +1,1 @@ +-
++ +@@ -3,4 +3,4 @@ +- + + +@@ -15,4 +15,4 @@ +- +- ++ +
+ +
+
++ ++ ++ +``` -- Collapsed/expanded state support - web component should support animated expansion/collapse -- More sophisticated state management for search interactions +
-**Web Component Features Missing from CSS:** +### CSS => SWC mapping -- `action` attribute - CSS should provide styling for form action states -- `method` attribute - CSS should provide styling based on form method -- `holdValueOnEscape` attribute - CSS should provide styling for this behavior state -- Help text slots - CSS should provide styling for slotted help text elements +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------------------------------------- | ------------------------- | ---------------------------- | +| `.spectrum-Search` | `:host` | Implemented | +| `.spectrum-Search--sizeS` | `size="s"` | Implemented | +| `.spectrum-Search--sizeL` | `size="l"` | Implemented | +| `.spectrum-Search--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-Search.is-disabled` | `disabled` | Implemented | +| `.spectrum-Search .spectrum-HelpText` | `help-text` slot | Implemented | +| `.spectrum-Search:lang(ja)`, `.spectrum-Search:lang(ko)`, `.spectrum-Search:lang(zh)` | Language-specific styling | Implemented | +| `.spectrum-Search .spectrum-Search-clearButton` | `` | Implemented | +| `.spectrum-Search .spectrum-Search-textfield` | Textfield functionality | Implemented | +| `.spectrum-Search .spectrum-Search-icon` | `` | Implemented | +| `.spectrum-Search .spectrum-Search-input` | Input element | Implemented | +| `.spectrum-Search.is-collapsed` | | Missing from WC (new for S2) | +| `.spectrum-Search.is-expanded` | | Missing from WC (new for S2) | -**Features Being Deprecated/Removed:** +## Summary of changes -- None identified - component maintains backward compatibility +### CSS => SWC implementation gaps -### Action Items for Web Component Maintainers +The primary implementation gap between CSS and SWC is the S2 implementation of the collapsed Search variant, which allows for expansion and collapse of the search field to and from a quiet action button that uses the same magnifying glass icon. In CSS, these collapsed/expanded states and controlled by the classes `.spectrum-Search.is-collapsed` and `.spectrum-Search.is-expanded`. -**Required Additions:** +Also, because Search extends Textfield, S2 updates to Textfield also apply here. The most notable update to S2 Textfield is the removal of the quiet variant. **Therefore, there is no quiet variant in S2 Search.** -- Collapsed/expanded state functionality for search field animations -- Enhanced form integration with action and method handling -- Better state management for search-specific interactions +### CSS Spectrum 2 changes -**Required Removals:** +The most notable changes seen in Spectrum 2 migration work include: -- None identified +- **Collapsible functionality**: Added support and styling for collapsed/expanded states +- **ActionButton integration**: When collapsed, the search shows as a quiet action button instead of a textfield +- **Icon change**: Changed from "Magnify" icon to "Search" icon with workflow icon set +- **Quiet variant**: Removed `isQuiet` parameter and `--quiet` modifier support -**Breaking Changes:** +## Resources -- None identified - component extends existing Textfield functionality -- Migration guidance: Search component provides enhanced functionality while maintaining Textfield compatibility +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2673) +- [CSS expand/collapse feature](https://github.com/adobe/spectrum-css/pull/4115) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-search-field--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/searchfield--docs) diff --git a/migration-roadmap/textfield.md b/migration-roadmap/textfield.md new file mode 100644 index 00000000000..ba0cf5d39a7 --- /dev/null +++ b/migration-roadmap/textfield.md @@ -0,0 +1,623 @@ +# Textfield and Textarea migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Base component:** + +- `.spectrum-Textfield` + +**Variants:** + +- `.spectrum-Textfield--sideLabel` +- `.spectrum-Textfield--multiline .spectrum-Textfield-input` +- `.spectrum-Textfield--multiline .spectrum-Textfield-input:lang(ja)` +- `.spectrum-Textfield--multiline .spectrum-Textfield-input:lang(ko)` +- `.spectrum-Textfield--multiline .spectrum-Textfield-input:lang(zh)` +- `.spectrum-Textfield--multiline.spectrum-Textfield--grows .spectrum-Textfield-input` +- `.spectrum-Textfield--multiline.spectrum-Textfield--grows.spectrum-Textfield--sideLabel .spectrum-Textfield-input` +- `.spectrum-Textfield--sizeL` +- `.spectrum-Textfield--sizeS` +- `.spectrum-Textfield--sizeXL` + +**Child elements:** + +- `.spectrum-Textfield .spectrum-FieldLabel` +- `.spectrum-Textfield .spectrum-HelpText` +- `.spectrum-Textfield--sideLabel .spectrum-FieldLabel` +- `.spectrum-Textfield--sideLabel .spectrum-HelpText` + +**Features:** + +- `.spectrum-Textfield-characterCount` +- `.spectrum-Textfield-characterCount:lang(ja)` +- `.spectrum-Textfield-characterCount:lang(ko)` +- `.spectrum-Textfield-characterCount:lang(zh)` +- `.spectrum-Textfield--sideLabel .spectrum-Textfield-characterCount` + +**Input element:** + +- `.spectrum-Textfield-input` +- `.spectrum-Textfield-input:-moz-ui-invalid` +- `.spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield-input:disabled` +- `.spectrum-Textfield-input:disabled::placeholder` +- `.spectrum-Textfield-input:focus` +- `.spectrum-Textfield-input:focus::placeholder` +- `.spectrum-Textfield-input:focus:hover` +- `.spectrum-Textfield-input:focus:hover::placeholder` +- `.spectrum-Textfield-input:hover` +- `.spectrum-Textfield-input:hover::placeholder` +- `.spectrum-Textfield-input:read-only` +- `.spectrum-Textfield-input:read-only::placeholder` +- `.spectrum-Textfield-input[type="number"]` +- `.spectrum-Textfield-input[type="number"]::-webkit-inner-spin-button` +- `.spectrum-Textfield-input[type="number"]::-webkit-outer-spin-button` +- `.spectrum-Textfield--sideLabel .spectrum-Textfield-input` + +**States:** + +- `.spectrum-Textfield.is-disabled .spectrum-FieldLabel` +- `.spectrum-Textfield.is-disabled .spectrum-HelpText .spectrum-HelpText-text` +- `.spectrum-Textfield.is-disabled .spectrum-Textfield-characterCount` +- `.spectrum-Textfield.is-disabled .spectrum-Textfield-input` +- `.spectrum-Textfield.is-disabled .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-disabled .spectrum-Textfield-input:read-only::placeholder` +- `.spectrum-Textfield.is-disabled .spectrum-Textfield-validationIcon` +- `.spectrum-Textfield.is-disabled .spectrum-Textfield.is-readOnly .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-disabled .spectrum-Textfield.is-readOnly:hover .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-disabled:hover .spectrum-Textfield-input` +- `.spectrum-Textfield.is-disabled:hover .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-disabled:hover .spectrum-Textfield-input:read-only::placeholder` +- `.spectrum-Textfield.is-disabled:hover .spectrum-Textfield.is-readOnly .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-disabled:hover .spectrum-Textfield.is-readOnly:hover .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-focused .spectrum-Textfield-input` +- `.spectrum-Textfield.is-focused .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-focused .spectrum-Textfield-input:hover` +- `.spectrum-Textfield.is-focused .spectrum-Textfield-input:hover::placeholder` +- `.spectrum-Textfield.is-focused:hover .spectrum-Textfield-input` +- `.spectrum-Textfield.is-focused:hover .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-invalid .spectrum-Textfield-input` +- `.spectrum-Textfield.is-invalid .spectrum-Textfield-input:focus` +- `.spectrum-Textfield.is-invalid .spectrum-Textfield-input:focus:hover` +- `.spectrum-Textfield.is-invalid .spectrum-Textfield-validationIcon` +- `.spectrum-Textfield.is-invalid.is-focused .spectrum-Textfield-input` +- `.spectrum-Textfield.is-invalid.is-focused .spectrum-Textfield-input:hover` +- `.spectrum-Textfield.is-invalid.is-focused:hover .spectrum-Textfield-input` +- `.spectrum-Textfield.is-invalid.is-keyboardFocused .spectrum-Textfield-input` +- `.spectrum-Textfield.is-invalid.is-keyboardFocused:hover .spectrum-Textfield-input` +- `.spectrum-Textfield.is-invalid:focus .spectrum-Textfield-input` +- `.spectrum-Textfield.is-invalid:focus .spectrum-Textfield-input:hover` +- `.spectrum-Textfield.is-invalid:focus:hover .spectrum-Textfield-input` +- `.spectrum-Textfield.is-invalid:hover:not(.is-disabled, .is-readOnly) .spectrum-Textfield-input` +- `.spectrum-Textfield.is-invalid:not(.is-disabled, .is-readOnly) .spectrum-Textfield-input:hover` +- `.spectrum-Textfield.is-keyboardFocused .spectrum-Textfield-input` +- `.spectrum-Textfield.is-keyboardFocused .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-keyboardFocused:hover .spectrum-Textfield-input` +- `.spectrum-Textfield.is-keyboardFocused:hover .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-readOnly .spectrum-Textfield-input` +- `.spectrum-Textfield.is-readOnly .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-readOnly .spectrum-Textfield-validationIcon` +- `.spectrum-Textfield.is-readOnly.is-disabled .spectrum-Textfield-input` +- `.spectrum-Textfield.is-readOnly:hover .spectrum-Textfield-input` +- `.spectrum-Textfield.is-readOnly:hover .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield.is-valid .spectrum-Textfield-input` +- `.spectrum-Textfield.is-valid .spectrum-Textfield-validationIcon` +- `.spectrum-Textfield.spectrum-Textfield--sideLabel .spectrum-Textfield-validationIcon` +- `.spectrum-Textfield:focus:hover .spectrum-Textfield-input` +- `.spectrum-Textfield:focus:hover .spectrum-Textfield-input::placeholder` +- `.spectrum-Textfield:hover .spectrum-Textfield-input` +- `.spectrum-Textfield:hover .spectrum-Textfield-input::placeholder` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers (deprecated) + +- `--mod-text-area-min-block-size` +- `--mod-text-area-min-inline-size` +- `--mod-textfield-animation-duration` +- `--mod-textfield-background-color` +- `--mod-textfield-background-color-disabled` +- `--mod-textfield-border-color` +- `--mod-textfield-border-color-disabled` +- `--mod-textfield-border-color-focus` +- `--mod-textfield-border-color-focus-hover` +- `--mod-textfield-border-color-hover` +- `--mod-textfield-border-color-invalid-default` +- `--mod-textfield-border-color-invalid-focus` +- `--mod-textfield-border-color-invalid-focus-hover` +- `--mod-textfield-border-color-invalid-hover` +- `--mod-textfield-border-color-invalid-keyboard-focus` +- `--mod-textfield-border-color-keyboard-focus` +- `--mod-textfield-border-width` +- `--mod-textfield-character-count-color` +- `--mod-textfield-character-count-spacing-block` +- `--mod-textfield-character-count-spacing-block-side` +- `--mod-textfield-character-count-spacing-inline` +- `--mod-textfield-character-count-spacing-inline-side` +- `--mod-textfield-corner-radius` +- `--mod-textfield-focus-indicator-color` +- `--mod-textfield-focus-indicator-gap` +- `--mod-textfield-focus-indicator-width` +- `--mod-textfield-font-family` +- `--mod-textfield-font-size` +- `--mod-textfield-font-style` +- `--mod-textfield-font-weight` +- `--mod-textfield-height` +- `--mod-textfield-helptext-spacing-block` +- `--mod-textfield-icon-color-invalid` +- `--mod-textfield-icon-color-valid` +- `--mod-textfield-icon-size-invalid` +- `--mod-textfield-icon-size-valid` +- `--mod-textfield-icon-spacing-block-invalid` +- `--mod-textfield-icon-spacing-block-valid` +- `--mod-textfield-icon-spacing-inline-end-invalid` +- `--mod-textfield-icon-spacing-inline-end-valid` +- `--mod-textfield-icon-spacing-inline-start-invalid` +- `--mod-textfield-icon-spacing-inline-start-valid` +- `--mod-textfield-label-spacing-block` +- `--mod-textfield-label-spacing-inline-side-label` +- `--mod-textfield-line-height` +- `--mod-textfield-line-height-cjk` +- `--mod-textfield-min-width` +- `--mod-textfield-spacing-block-end` +- `--mod-textfield-spacing-block-start` +- `--mod-textfield-spacing-inline` +- `--mod-textfield-text-color-default` +- `--mod-textfield-text-color-disabled` +- `--mod-textfield-text-color-focus` +- `--mod-textfield-text-color-focus-hover` +- `--mod-textfield-text-color-hover` +- `--mod-textfield-text-color-invalid` +- `--mod-textfield-text-color-keyboard-focus` +- `--mod-textfield-text-color-readonly` +- `--mod-textfield-text-color-valid` +- `--mod-textfield-width` + +
+ +### SWC + +
+Attributes + +**TextfieldBase specific attributes:** + +- `allowed-keys` - A regular expression outlining the keys that will be allowed to update the value of the form control +- `autocomplete` - What form of assistance should be provided when attempting to supply a value to the form control +- `focused` - Whether the component is focused (private) +- `grows` - Whether a form control delivered with the multiline attribute will change size vertically to accommodate longer input +- `invalid` - Whether the value held by the form control is invalid +- `label` - A string applied via aria-label to the form control when a user visible label is not provided +- `maxlength` - Defines the maximum string length that the user can enter +- `minlength` - Defines the minimum string length that the user can enter +- `multiline` - Whether the form control should accept a value longer than one line +- `name` - Name of the form control +- `pattern` - Pattern the value must match to be valid +- `placeholder` - Text that appears in the form control when it has no value set +- `quiet` - Whether to display the form control with no visible background +- `readonly` - Whether a user can interact with the value of the form control +- `required` - Whether the form control will be found to be invalid when it holds no value +- `rows` - The specific number of rows the form control should provide in the user interface +- `type` - Input type (text, url, tel, email, password) +- `valid` - Whether the value held by the form control is valid +- `value` - The value held by the form control + +**Inherited from SizedMixin:** + +- `size` - Size of the textfield (s, m, l, xl) + +**Inherited from Focusable:** + +- `autofocus` - When this control is rendered, focus it automatically +- `disabled` - Disable this control. It will not receive focus or events +- `tabIndex` - The tab index to apply to this control + +
+ +
+Slots + +- `help-text` - Default or non-negative help text to associate to your form element +- `negative-help-text` - Negative help text to associate to your form element when invalid + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components: + +```html +
+ + + + + + + + + + + + +
+ + +
+ + + +
+``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ + Character Count + + + + +
+ +
+
+
Help text content
+
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + Character Count + + + + +
+ +
+
+
Help text content
+
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff +--- Legacy DOM structure ++++ Spectrum 2 DOM structure +@@ -1,7 +1,7 @@ +-
++
+-
+- +-
++ + Character Count +- ++ + + + +-
++
+ +
+-
+-
Help text content
+-
++
++
Help text content
++
+
+``` + +**Key DOM changes:** + +- **Removed**: `spectrum-Textfield--quiet` class (quiet variant removed in Spectrum 2) +- **Added**: `is-hover` class for hover state management +- **Progress circle component**: Changed from `spectrum-ProgressCircle` to `spectrum-InfieldProgressCircle` +- **Progress circle size**: Changed from `--sizeS` to `--sizeM` (now uses dynamic sizing) + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------- | +| `.spectrum-Textfield` | `:host` | Implemented | +| `.spectrum-Textfield--sizeS` | `size="s"` | Implemented | +| `.spectrum-Textfield--sizeL` | `size="l"` | Implemented | +| `.spectrum-Textfield--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-Textfield--multiline` | `multiline` | Implemented | +| `.spectrum-Textfield--grows` | `grows` | Implemented | +| `.spectrum-Textfield.is-invalid` | `invalid` | Implemented | +| `.spectrum-Textfield.is-valid` | `valid` | Implemented | +| `.spectrum-Textfield.is-disabled` | `disabled` | Implemented | +| `.spectrum-Textfield.is-readOnly` | `readonly` | Implemented | +| `.spectrum-Textfield.is-focused` | `focused` | Implemented | +| `.spectrum-Textfield-input[type="number"]` | `type="number"` | Implemented | +| `.spectrum-Textfield-input:disabled` | `disabled` | Implemented | +| `.spectrum-Textfield-input:read-only` | `readonly` | Implemented | +| `.spectrum-Textfield-input:focus` | `focused` | Implemented, but SWC does not differentiate between keyboard focus and mouse focus | +| `.spectrum-Textfield-input:hover` | CSS `:hover` | Implemented via CSS | +| `.spectrum-Textfield .spectrum-FieldLabel` | `label` attribute | Implemented | +| `.spectrum-Textfield .spectrum-HelpText` | `help-text` slot | Implemented | +| `.spectrum-Textfield-validationIcon` | Validation icons | Implemented | +| `.spectrum-Textfield-input::placeholder` | `placeholder` | Implemented | +| `.spectrum-Textfield-input[type="number"]::-webkit-inner-spin-button`, `.spectrum-Textfield-input[type="number"]::-webkit-outer-spin-button` | Number input styling | Implemented | +| `input[name]`, `textarea[name]` | `name` | Implemented (standard HTML) | +| `input[pattern]`, `textarea[pattern]` | `pattern` | Implemented (standard HTML) | +| `input[maxlength]`, `textarea[maxlength]` | `maxlength` | Implemented (standard HTML) | +| `input[minlength]`, `textarea[minlength]` | `minlength` | Implemented (standard HTML) | +| `textarea[rows]` | `rows` | Implemented (standard HTML) | +| `input[value]`, `textarea[value]` | `value` | Implemented (standard HTML) | +| `input[required]`, `textarea[required]` | `required` | Implemented (standard HTML) | +| `input[autocomplete]`, `textarea[autocomplete]` | `autocomplete` | Implemented (standard HTML) | +| `input[allowed-keys]` (custom attribute) | `allowed-keys` | Implemented (custom) | +| `.spectrum-Textfield--sideLabel` | `labelPosition` (side) | Missing from SWC textfield but exists within SWC field label | +| `.spectrum-Textfield-characterCount` | Character count feature | Missing from SWC (existed in S1 but never implemented in SWC) | +| `.spectrum-Textfield--quiet` | `quiet` | Deprecated for S2 | + +## Summary of changes + +There are a few changes in CSS migration to S2 that are relevant to related components, such as number field (for the `step` value) and field label (for required, see additional note below). In SWC, field label is rendered outside of ``, but in CSS, they are part of the template. + +There also doesn't appear to be support for rendering a progress circle inside of ``, which will need to be added. + +Side label exists as a variant of field label in SWC, but in CSS, the variant is controlled by textfield. + +**Note:** Field label's required option isn't new to SWC, but because Adobe design allows an input to be marked as required by noting it in the field label, see [the textfield design docs](https://spectrum.adobe.com/page/text-field/#Required-or-optional), without an asterisk, that's something we'll likely want to support. + +**Also noteworthy**: there is an additional inline textfield variant that has not yet been implemented in Spectrum CSS or Spectrum Web Components. + +In comparing Legacy CSS to Spectrum 2 CSS, and CSS to SWC, here are the changes for textfield and textarea that would need to be made in SWC: + +- Look into adding side label position option to textfield +- Implement character count (note that this appears next to the field label for a top label, and on the opposite side of the input for a side label) +- Removal of the quiet variant +- Use of the inline progress circle component for the textfield's progress circle (**Note**: Spectrum CSS doesn't currently show textfield with the progress circle as there is no design spec for it) +- Implementation of the new inline textfield variant +- Applying the `required` attribute to the text input without displaying the asterisk in the field label to accommodate the [two styling options available](https://spectrum.adobe.com/page/text-field/#Required-or-optional) for required text fields +- Look into keyboard focus state, determine if this should differ from mouse focused state + +See below for more details. + +### CSS => SWC implementation gaps + +#### Textfield implementation gaps + +The mapping analysis reveals several key differences present in the CSS implementation but not the SWC implementation: + +- **Label position**: This is controlled by field label in SWC, but controlled by textfield in CSS +- **Character count**: SWC doesn't currently support a visible character count that would track the number of characters within the text field +- **Keyboard focus state**: CSS has slightly different styling for focused vs. keyboard-focused state (keyboard focus shows the blue outline, mouse focus does not), this distinction is not visible in the current SWC implementation + +#### Textarea implementation gaps + +The textarea component (implemented as `sp-textfield[multiline]`) has the same missing features as the textfield component, since it uses the same underlying implementation. All the gaps mentioned in the textfield section apply to textarea as well. + +### CSS Spectrum 2 changes + +#### Textfield changes + +The main API change for Spectrum 2 is the removal of the `quiet` variant. + +Additionally, the progress circle used within the textfield component is now the new infield progress circle rather than the standalone progress circle. + +The comparison between CSS `main` and CSS `spectrum-two` branches reveals several noteworthy changes: + +**Template parameter changes:** + +- Added `step` parameter for number input step attribute +- Added `isRequiredWithoutAsterisk` parameter (allows for input to be marked with required attribute without applying the asterisk to the associated field label) + +**Icon changes:** + +- **Invalid icon**: Changed from `"Alert"` to `"AlertTriangle"` +- **Valid icon**: Changed from simple `"Checkmark"` to size-specific checkmarks (`"Checkmark75"`, `"Checkmark100"`, `"Checkmark200"`, `"Checkmark300"`) + +#### Textarea changes + +All the changes mentioned in the textfield section apply to textarea as well, since textarea is implemented as `sp-textfield[multiline]`. The multiline variant will inherit all the same changes. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2856) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-text-field--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/textfield--docs) From ee488645e6e5f37b65bf5cfa44650e84b5b409dd Mon Sep 17 00:00:00 2001 From: Marissa Huysentruyt <69602589+marissahuysentruyt@users.noreply.github.com> Date: Tue, 7 Oct 2025 14:00:06 -0400 Subject: [PATCH 7/9] docs(slider,meter,progressbar,dropzone,illustratedmessage): migration roadmap (#5775) * docs: add component analysis docs adds migration roadmap and component analysis docs for meter, progress bar, slider, illustrated message and drop zone. --- migration-roadmap/dropzone.md | 273 ++++++++++++ migration-roadmap/illustrated-message.md | 291 ++++++++----- migration-roadmap/meter.md | 226 ++++++++++ migration-roadmap/progress-bar.md | 210 +++++++++ migration-roadmap/slider.md | 530 +++++++++++++++++++++++ 5 files changed, 1418 insertions(+), 112 deletions(-) create mode 100644 migration-roadmap/dropzone.md create mode 100644 migration-roadmap/meter.md create mode 100644 migration-roadmap/progress-bar.md create mode 100644 migration-roadmap/slider.md diff --git a/migration-roadmap/dropzone.md b/migration-roadmap/dropzone.md new file mode 100644 index 00000000000..4dae7732b93 --- /dev/null +++ b/migration-roadmap/dropzone.md @@ -0,0 +1,273 @@ +# Dropzone migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-DropZone` +- `.spectrum-DropZone .spectrum-IllustratedMessage` + +**Subcomponents:** + +- `.spectrum-DropZone-actions` +- `.spectrum-DropZone.is-filled.is-dragged .spectrum-DropZone-actions` +- `.spectrum-DropZone-button` +- `.spectrum-DropZone-button .spectrum-Button-label` +- `.spectrum-DropZone-content` +- `.spectrum-DropZone.is-filled.is-dragged .spectrum-DropZone-content` +- `.spectrum-DropZone-stroke` +- `.spectrum-DropZone-strokePath` +- `.spectrum-DropZone.is-dragged .spectrum-DropZone-strokePath` +- `.spectrum-DropZone:has(.spectrum-DropZone-stroke)` + +**Interactive states:** + +- `.spectrum-DropZone-button:focus` +- `.spectrum-DropZone-button:hover` +- `.spectrum-DropZone:focus-visible` + +**Variants:** + +- `.spectrum-DropZone.is-dragged` +- `.spectrum-DropZone.is-filled` +- `.spectrum-DropZone.is-filled.is-dragged` + +
+ +
+Passthroughs + +- `--mod-button-border-radius` +- `--mod-illustrated-message-description-font-size` +- `--mod-illustrated-message-description-position` +- `--mod-illustrated-message-description-to-action` +- `--mod-illustrated-message-description-z-index` +- `--mod-illustrated-message-display` +- `--mod-illustrated-message-illustration-color` +- `--mod-illustrated-message-vertical-maximum-width` + +
+ +
+Modifiers + +- `--mod-drop-zone-background-color` +- `--mod-drop-zone-background-color-opacity` +- `--mod-drop-zone-background-color-opacity-filled` +- `--mod-drop-zone-body-font-size` +- `--mod-drop-zone-body-to-action` +- `--mod-drop-zone-border-color` +- `--mod-drop-zone-border-color-hover` +- `--mod-drop-zone-border-dash-gap` +- `--mod-drop-zone-border-dash-length` +- `--mod-drop-zone-border-style` +- `--mod-drop-zone-border-style-dragged` +- `--mod-drop-zone-border-width` +- `--mod-drop-zone-content-background-color` +- `--mod-drop-zone-content-bottom-to-text` +- `--mod-drop-zone-content-font-family` +- `--mod-drop-zone-content-font-size` +- `--mod-drop-zone-content-font-weight` +- `--mod-drop-zone-content-height` +- `--mod-drop-zone-content-max-width` +- `--mod-drop-zone-content-maximum-width` +- `--mod-drop-zone-content-top-to-text` +- `--mod-drop-zone-corner-radius` +- `--mod-drop-zone-edge-to-text` +- `--mod-drop-zone-illustration-color-hover` +- `--mod-drop-zone-inline-size` +- `--mod-drop-zone-padding` +- `--mod-drop-zone-title-line-height` + +
+ +### SWC + +
+Attributes + +- `dropEffect` (String) - Controls the feedback during drag and drop: 'copy', 'move', 'link', or 'none' +- `isDragged` (Boolean) - Indicates that files are currently being dragged over the dropzone +- `isFilled` (Boolean) - Set to indicate that the component is in a filled state + +
+ +
+Slots + +- Default slot - drop zone content (i.e. ``, links, instructive copy) + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + + +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+
+ + + +
+ + +
+ + +
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + + + +
+
+ + + +
+ +
+ +
+
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +### HTML Output Diff + +**Key Structural Changes:** + +```diff +
++ ++ ++ + +-
+- +- +- +-
+- +
+- +- ++
++ ++ ++ ++
++ ++
++ ++
+
+
+``` + +### Key Changes in HTML Structure + +1. **Enhanced visual border**: Added SVG stroke element (`.spectrum-DropZone-stroke`) with customizable dashed border styling that provides better visual feedback during drag operations. + +2. **Restructured content organization**: Moved the illustrated message inside the `.spectrum-DropZone-content` container and separated actions into dedicated `.spectrum-DropZone-actions` container for better structural hierarchy. + +3. **Button component upgrade**: Switched from `ActionButton` to `Button` component for improved consistency with other Spectrum components. + +4. **Improved content flow**: The content container now properly wraps both the illustrated message and actions, creating a more logical content structure. + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ------------------------------- | ---------------------------------------- | ---------------------------- | +| `.spectrum-DropZone` | `:host` | Implemented | +| `.spectrum-DropZone.is-dragged` | `isDragged` attribute | Implemented | +| `.spectrum-DropZone.is-filled` | `isFilled` attribute | Implemented | +| `.spectrum-DropZone-content` | default slot; `` | Implemented | +| `.spectrum-DropZone-button` | default slot; `` | Implemented | +| `.spectrum-DropZone-actions` | Actions container | Missing from WC (new for S2) | +| `.spectrum-DropZone-stroke` | SVG stroke border | Missing from WC (new for S2) | +| `.spectrum-DropZone-strokePath` | SVG path element | Missing from WC (new for S2) | + +## Summary of changes + +### CSS => SWC implementation gaps + +- **Content structure**: The web component will require updating the internal structure including `.spectrum-DropZone-content`, `.spectrum-DropZone-actions`, and associated button elements. The `.spectrum-DropZone-content` and `.spectrum-DropZone-actions` classes are styled based on the Figma design specs. The SWC implementation provides only a simple slot-based container. We should consider if this approach is the approach we prefer moving into Spectrum 2 since the single-slot approach leaves the option open for lots of potentially unnecessary customization by the consumer (i.e. consumers could freely compose a drop zone with other components that does not follow the design expectations and standards). + +- **Visual border system**: Missing the SVG-based stroke system (`.spectrum-DropZone-stroke` and `.spectrum-DropZone-strokePath`) provides enhanced visual feedback with customizable dashed borders. The svg borders were implemented in place of the CSS-only dashed border style to ensure the dashes have the corner rounding as laid out in the design spec. + +- **Built-in UI elements**: The web component doesn't include built-in illustrated message and button components, requiring developers to manually compose these elements in the slot. + +- **State-specific styling**: While drag and fill states are tracked separately, the web component currently doesn't handle the combination state of dragged and filled. Some missing features include include a button when the drop zone is filled, taking advantage of the custom SVG border options when dragged and filled, and `` needs to support the background illustration for the filled state. + +Also worth consideration is the concept of "filled" vs. "replace." The design file refers to the "filled" state as the "replace" variant, so we should consider an API refactor if we want to align with design intentions more. + +### CSS Spectrum 2 changes + +- **Enhanced border system**: Introduced SVG-based stroke system replacing simple CSS borders, providing better visual feedback and customization options for drag states. + +- **Improved content organization**: Repurposed `.spectrum-DropZone-content` wrapper and separated actions into `.spectrum-DropZone-actions` container for better organization. + +- **Component upgrades**: Switched from an action button to a button for better visual hierarchy and consistency. Additionally, the `.spectrum-Dropzone-content` element was set by default to `display: none` in Spectrum 1, but didn't wrap the corresponding illustrated message content. For Spectrum 2, the purpose of `.spectrum-Dropzone-content` has been updated to more accurately wrap the component's visual content and be displayed by default. + +- **Enhanced state styling**: Added more sophisticated styling for filled and dragged state combinations, including background image support for filled states. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3429) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-drop-zone--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/dropzone--docs) diff --git a/migration-roadmap/illustrated-message.md b/migration-roadmap/illustrated-message.md index d5bd614abf4..ab0c58097d8 100644 --- a/migration-roadmap/illustrated-message.md +++ b/migration-roadmap/illustrated-message.md @@ -1,24 +1,37 @@ -# Illustrated Message migration roadmap +# Illustrated message migration roadmap + +## Component specifications + +### CSS
CSS selectors - `.spectrum-IllustratedMessage` + +**Variants:** + - `.spectrum-IllustratedMessage--horizontal` -- `.spectrum-IllustratedMessage--horizontal .spectrum-IllustratedMessage-illustration` - `.spectrum-IllustratedMessage--sizeL` -- `.spectrum-IllustratedMessage--sizeL:lang(ja)` -- `.spectrum-IllustratedMessage--sizeL:lang(ko)` -- `.spectrum-IllustratedMessage--sizeL:lang(zh)` - `.spectrum-IllustratedMessage--sizeS` -- `.spectrum-IllustratedMessage--sizeS:lang(ja)` -- `.spectrum-IllustratedMessage--sizeS:lang(ko)` -- `.spectrum-IllustratedMessage--sizeS:lang(zh)` + +**Subcomponents:** + +- `.spectrum-IllustratedMessage--horizontal .spectrum-IllustratedMessage-illustration` - `.spectrum-IllustratedMessage-actions` - `.spectrum-IllustratedMessage-content` - `.spectrum-IllustratedMessage-description` - `.spectrum-IllustratedMessage-heading` - `.spectrum-IllustratedMessage-illustration` + +**Internationalization:** + +- `.spectrum-IllustratedMessage--sizeL:lang(ja)` +- `.spectrum-IllustratedMessage--sizeL:lang(ko)` +- `.spectrum-IllustratedMessage--sizeL:lang(zh)` +- `.spectrum-IllustratedMessage--sizeS:lang(ja)` +- `.spectrum-IllustratedMessage--sizeS:lang(ko)` +- `.spectrum-IllustratedMessage--sizeS:lang(zh)` - `.spectrum-IllustratedMessage:lang(ja)` - `.spectrum-IllustratedMessage:lang(ko)` - `.spectrum-IllustratedMessage:lang(zh)` @@ -32,23 +45,6 @@
-
-Attributes - -- `heading` (String) - Headline text for the message -- `description` (String) - Description text for the illustration - -
- -
-Slots - -- Default slot - The SVG that represents the illustration -- `heading` - Headline for the message -- `description` - Description text for the illustration - -
-
Modifiers @@ -81,136 +77,207 @@
-## Visual Comparison +### SWC -**Legacy Component:** +
+Attributes + +- `heading` (String) - Title text for the message +- `description` (String) - Description text for the message - +
-**Spectrum 2 Component:** +
+Slots + +- Default slot - The SVG that represents the illustration +- Heading slot - Title text for the message +- Description slot - Description text for the message + +
- +## Comparison -## DOM Structure Changes +### DOM Structure changes -**Legacy (main branch):** +
+Spectrum Web Components: + +```html +
+ + + +
+

+ [heading] +

+
+ [description] +
+``` + +
+ +
+Legacy (CSS main branch): ```html
- [illustration] -
- [heading] -
-
+ +

- [description content] -

+ Heading text + +

+ Description text and other content (like links) +

``` -**Spectrum 2 (spectrum-two branch):** +
+ +
+Spectrum 2 (CSS spectrum-two branch): ```html -
- [illustration] -
+
+ - [heading] -
-
- [description content] + + +
+

Heading text

+

+ Description text and other content (like links) +

+ +
+ + +
``` -## Comparison - -| CSS selector | Attribute or slot | Status | -| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------- | -| `.spectrum-IllustratedMessage` | Root element | Implemented | -| `.spectrum-IllustratedMessage--horizontal` | Horizontal layout variant | Missing from WC | -| `.spectrum-IllustratedMessage--sizeL` | Large size variant | Missing from WC | -| `.spectrum-IllustratedMessage--sizeS` | Small size variant | Missing from WC | -| `.spectrum-IllustratedMessage-illustration` | Default slot | Implemented | -| `.spectrum-IllustratedMessage-heading` | `heading` slot | Implemented | -| `.spectrum-IllustratedMessage-description` | `description` slot | Implemented | -| `.spectrum-IllustratedMessage-content` | Content container | Missing from WC | -| `.spectrum-IllustratedMessage-actions` | Actions container | Missing from WC | -| `.spectrum-IllustratedMessage:lang(ja)`, `.spectrum-IllustratedMessage:lang(ko)`, `.spectrum-IllustratedMessage:lang(zh)` | Language-specific styling | Implemented | -| `.spectrum-IllustratedMessage--sizeL:lang(ja)`, etc. | Size + language combinations | Missing from WC | -| - | `heading` attribute | Missing from CSS | -| - | `description` attribute | Missing from CSS | +
-## Key Structural Changes +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +### HTML Output Diff + +**Key Structural Changes:** + +```diff +-
++
+- ++ + + +-

+- Heading text +-

+-

+- Description text and other content (like links) +-

++
++

++ Heading text ++

++

++ Description text and other content (like links) ++

++
++ ++ ++
++
+
+``` -**Element Hierarchy Changes:** +### Key Changes in HTML Structure -- No significant hierarchy changes between main and spectrum-two branches -- Maintained consistent illustration > heading > description structure +1. **Size class addition**: Added t-shirt sizing classes to the root element for explicit size control. -**Class Name Changes:** +2. **Modernized SVG attributes**: Updated SVG with modern attributes including `xmlns`, updated dimensions (96x96), new viewBox (0 0 160 160), and `preserveAspectRatio` for better rendering. -- No major class name changes -- Consistent naming convention maintained +3. **Content wrapper**: Added `.spectrum-IllustratedMessage-content` container to group text content and actions separate from the illustration. -**Attribute Changes:** +4. **Typography simplification**: Removed Spectrum typography classes (`spectrum-Heading`, `spectrum-Body`) from heading and description elements, using semantic HTML with component-specific classes instead. -- Added `heading` attribute for setting heading text -- Added `description` attribute for setting description text -- No size variants exposed as attributes +5. **Actions container**: Introduced `.spectrum-IllustratedMessage-actions` container with button group support for interactive elements. -**Slot/Content Changes:** +6. **Horizontal orientation**: Added `.spectrum-IllustratedMessage--horizontal` modifier class that introduces the new horizontal layout variant. -- Added `heading` slot for heading content -- Added `description` slot for description content -- Default slot for illustration SVG content +
-**Migration Impact:** +### CSS => SWC mapping -- Web component provides simplified API with attribute-based content -- Missing size and layout variants may limit design flexibility -- Simplified structure reduces complexity but may limit customization +| CSS selector | Attribute or slot | Status | +| ------------------------------------------- | ---------------------------- | ---------------------------- | +| `.spectrum-IllustratedMessage` | `:host` | Implemented | +| `.spectrum-IllustratedMessage--sizeS` | `size="s"` | Missing from WC (new for S2) | +| `.spectrum-IllustratedMessage--sizeL` | `size="l"` | Missing from WC (new for S2) | +| `.spectrum-IllustratedMessage--horizontal` | Layout variant | Missing from WC (new for S2) | +| `.spectrum-IllustratedMessage-illustration` | Default slot | Implemented | +| `.spectrum-IllustratedMessage-heading` | `heading` attribute/slot | Implemented | +| `.spectrum-IllustratedMessage-description` | `description` attribute/slot | Implemented | +| `.spectrum-IllustratedMessage-content` | Content container | Missing from WC (new for S2) | +| `.spectrum-IllustratedMessage-actions` | Actions container | Missing from WC (new for S2) | -### Implementation Gaps +## Summary of changes -**CSS Features Missing from Web Component:** +### CSS => SWC implementation gaps -- Horizontal layout variant support - web component should support `horizontal` layout -- Size variant support - web component should support size options (`sizeS`, `sizeL`) -- Content container support - web component should provide content grouping -- Actions container support - web component should support action buttons/elements -- Language + size combination styling +- **Size variants**: The web component lacks support for `.spectrum-IllustratedMessage--sizeS` and `.spectrum-IllustratedMessage--sizeL` which provide different sizing options for various use cases. Sizes were introduced in Spectrum 2 designs. -**Web Component Features Missing from CSS:** +- **Horizontal layout**: Missing support for `.spectrum-IllustratedMessage--horizontal` which enables horizontal layout with illustration and content side-by-side. This was new for Spectrum 2. -- `heading` attribute - CSS should provide styling for heading attribute content -- `description` attribute - CSS should provide styling for description attribute content +- **Content structure**: The web component lacks `.spectrum-IllustratedMessage-content` wrapper and `.spectrum-IllustratedMessage-actions` container, limiting complex layout capabilities. This wrapper sets the correct justification styles for the new button group in Spectrum 2. -**Features Being Deprecated/Removed:** +- **Built-in actions**: No built-in support yet for button group, which were introduced in S2. -- None identified - component maintains basic functionality +### CSS Spectrum 2 changes -### Action Items for Web Component Maintainers +- **Unified illustration design**: Upgraded the SVG illustration to something that better represents modern Spectrum design language. -**Required Additions:** +- **Enhanced content structure**: Added `.spectrum-IllustratedMessage-content` wrapper to group text content separate from illustration, improving layout flexibility. -- Horizontal layout variant support for side-by-side illustration and content -- Size variant support (small, medium, large) for different use cases -- Content container wrapper for better content organization -- Actions slot/container for buttons and interactive elements -- Size attribute with responsive design considerations +- **Actions integration**: Introduced `.spectrum-IllustratedMessage-actions` container with built-in button group support for common interactive scenarios. This element is optional. -**Required Removals:** +- **Size system enhancement**: Expanded size variants. -- None identified +- **Improved SVG handling**: Enhanced SVG illustration with better accessibility attributes and rendering optimization. -**Breaking Changes:** +## Resources -- Missing layout and size variants limit design flexibility compared to CSS version -- Migration guidance: Consider adding size and layout attributes to match CSS variant capabilities +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3246) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-illustrated-message--docs&args=isHorizontal:!true) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/illustratedmessage--docs) diff --git a/migration-roadmap/meter.md b/migration-roadmap/meter.md new file mode 100644 index 00000000000..d841a89b829 --- /dev/null +++ b/migration-roadmap/meter.md @@ -0,0 +1,226 @@ +# Meter migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-Meter` + +**Subcomponents:** + +- `.spectrum-Meter .spectrum-ProgressBar-helptext` + +**Variants:** + +- `.spectrum-Meter.is-negative` +- `.spectrum-Meter.is-notice` +- `.spectrum-Meter.is-positive` +- `.spectrum-Meter--staticWhite` (The `.spectrum-Meter--staticWhite` class is not present in the Meter CSS, as it makes use of `spectrum-ProgressBar--staticWhite`) +- `.spectrum-Meter--staticBlack` (The `.spectrum-Meter--staticBlack` class is not present in the Meter CSS, as it makes use of `spectrum-ProgressBar--staticBlack`) + +**Sizes:** + +- `.spectrum-Meter.spectrum-Meter--sizeL` +- `.spectrum-Meter.spectrum-Meter--sizeS` +- `.spectrum-Meter.spectrum-Meter--sizeXL` + +
+ +
+Passthroughs + +- `--mod-progressbar-fill-color` +- `--mod-progressbar-max-size` +- `--mod-progressbar-min-size` +- `--mod-progressbar-thickness` + +
+ +
+Modifiers + +- `--mod-meter-help-text-to-progress-bar` +- `--mod-meter-max-width` +- `--mod-meter-min-width` + +
+ +### SWC + +
+Attributes + +- `progress` (Number) - Progress value +- `variant` (String) - Meter variant: 'positive', 'notice', or 'negative' +- `label` (String) - Label text +- `sideLabel` (Boolean) - Whether to display label on the side +- `staticColor` (String) - Static color: 'white' + +**Inherited from SizedMixin:** + +- `size` - Size of the number field (s, m, l, xl) + +
+ +
+Slots + +- Default slot - Text labeling the Meter + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + + [label] + +[progress] +
+
+
+``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ + +
+
+
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + +
+
+
+ +
+
Help text
+
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +### HTML Output Diff + +```diff +
+ + +
+
+
++ ++
++
++ Help text ++
++
+
+``` + +### Key Changes in HTML Structure + +1. **Size class adjustment**: Changed default size class from `spectrum-Meter--sizeL` to `spectrum-Meter--sizeM`. In S2, size options were expanded (although SWC already supported S/M/L/XL). In Spectrum 1, the meter component extended the default medium-sized progress bar with `.spectrum-ProgressBar--sizeM`, as well as set the default meter size to `.spectrum-Meter--sizeL`. In Spectrum 2, you'll notice the `.spectrum-ProgressBar--sizeM` modifier is removed since that t-shirt size is not needed for default progress bars and/or meters. + +2. **Help text integration**: Added optional `.spectrum-ProgressBar-helptext` container with `.spectrum-HelpText-text` wrapper for displaying contextual help information below the meter. + +
+ +### CSS => SWC mapping + +**Note:** The meter extends progress bar, so the progress bar selectors listed below are inherited in the CSS meter. + +| CSS selector | Attribute or slot | Status | +| ---------------------------------- | ------------------------------------- | ---------------------------- | +| `.spectrum-Meter` | `:host` | Implemented | +| `.spectrum-Meter--sizeS` | `size="s"` | Implemented | +| `.spectrum-Meter--sizeL` | `size="l"` | Implemented | +| `.spectrum-Meter--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-Meter.is-positive` | `variant="positive"` | Implemented | +| `.spectrum-Meter.is-negative` | `variant="negative"` | Implemented | +| `.spectrum-Meter.is-notice` | `variant="notice"` | Implemented | +| `.spectrum-Meter--staticWhite` | `staticColor="white"` | Implemented | +| `.spectrum-ProgressBar-label` | `label` attribute; default slot | Implemented | +| `.spectrum-ProgressBar-percentage` | `` | Implemented | +| `.spectrum-ProgressBar-track` | `.track` container | Implemented | +| `.spectrum-ProgressBar-fill` | `fill` element | Implemented | +| `.spectrum-ProgressBar--sideLabel` | `side-label` attribute | Implemented | +| `.spectrum-Meter--staticBlack` | `staticColor="black"` | Missing from WC (new for S2) | +| `.spectrum-ProgressBar-helptext` | Help text | Missing from WC (new for S2) | + +## Summary of changes + +### CSS => SWC implementation gaps + +- **Help text support**: The web component lacks support for conditional help text, which would display help text below the meter. + +- **Static black**: The web component lacks support for the new static black styles for the meter. + +### CSS Spectrum 2 changes + +The CSS Spectrum 2 meter DOM includes the addition of optional help text, but otherwise remains the same. The meter component essentially extends the progress bar with semantic color variants (positive, negative, notice) and uses the same underlying structure and styling. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3968) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-meter--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/meter--docs) diff --git a/migration-roadmap/progress-bar.md b/migration-roadmap/progress-bar.md new file mode 100644 index 00000000000..ca6bdf2022f --- /dev/null +++ b/migration-roadmap/progress-bar.md @@ -0,0 +1,210 @@ +# Progress bar migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-ProgressBar` + +**Subcomponents:** + +- `.spectrum-ProgressBar .spectrum-ProgressBar-fill` +- `.spectrum-ProgressBar .spectrum-ProgressBar-label` +- `.spectrum-ProgressBar .spectrum-ProgressBar-percentage` +- `.spectrum-ProgressBar .spectrum-ProgressBar-track` +- `.spectrum-ProgressBar-track` + +**Variants:** + +- `.spectrum-ProgressBar--indeterminate` +- `.spectrum-ProgressBar--sideLabel` +- `.spectrum-ProgressBar--staticWhite` + +**Internationalization:** + +- `.spectrum-ProgressBar--indeterminate .spectrum-ProgressBar-fill:dir(rtl)` +- `.spectrum-ProgressBar .spectrum-ProgressBar-label:lang(ja)` +- `.spectrum-ProgressBar .spectrum-ProgressBar-label:lang(ko)` +- `.spectrum-ProgressBar .spectrum-ProgressBar-label:lang(zh)` +- `.spectrum-ProgressBar .spectrum-ProgressBar-percentage:lang(ja)` +- `.spectrum-ProgressBar .spectrum-ProgressBar-percentage:lang(ko)` +- `.spectrum-ProgressBar .spectrum-ProgressBar-percentage:lang(zh)` + +**Sizes:** + +- `.spectrum-ProgressBar--sizeL` +- `.spectrum-ProgressBar--sizeS` +- `.spectrum-ProgressBar--sizeXL` + +**For extension use only by meter component:** + +Progress bar itself does not support static black styles, but because meter extends the progress bar in Spectrum CSS, these selectors were necessary to support meter's static black design requirements. + +- `.spectrum-ProgressBar--staticBlack .spectrum-ProgressBar-fill` +- `.spectrum-ProgressBar--staticBlack .spectrum-ProgressBar-label` +- `.spectrum-ProgressBar--staticBlack .spectrum-ProgressBar-percentage` +- `.spectrum-ProgressBar--staticBlack .spectrum-ProgressBar-track` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-progressbar-animation-duration-indeterminate` +- `--mod-progressbar-animation-ease-in-out-indeterminate` +- `--mod-progressbar-fill-color` +- `--mod-progressbar-fill-color-black` +- `--mod-progressbar-fill-color-white` +- `--mod-progressbar-fill-size-indeterminate` +- `--mod-progressbar-font-size` +- `--mod-progressbar-inline-size` +- `--mod-progressbar-label-and-value-black` +- `--mod-progressbar-label-and-value-white` +- `--mod-progressbar-line-height` +- `--mod-progressbar-line-height-cjk` +- `--mod-progressbar-max-size` +- `--mod-progressbar-min-size` +- `--mod-progressbar-spacing-label-to-progressbar` +- `--mod-progressbar-spacing-label-to-text` +- `--mod-progressbar-spacing-top-to-text` +- `--mod-progressbar-text-color` +- `--mod-progressbar-thickness` +- `--mod-progressbar-track-color` +- `--mod-spacing-progressbar-label-to-text` + +
+ +### SWC + +
+Attributes + +- `indeterminate` (Boolean) - Whether the progress bar is in indeterminate state +- `label` (String) - Label text for the progress bar +- `overBackground` (Boolean) - @deprecated; Use `staticColor` instead +- `sideLabel` (Boolean) - Whether to display label on the side +- `progress` (Number) - Progress value +- `staticColor` (String) - Static color: 'white' + +
+ +
+Slots + +- Default slot - Text labeling the progress bar + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html + + + [label] + +[progress] +
+
+
+``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ + +
+
+
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + +
+
+
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**No differences found between main and spectrum-two branches.** + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| -------------------------------------- | ------------------------------------- | ----------- | +| `.spectrum-ProgressBar` | `:host` | Implemented | +| `.spectrum-ProgressBar--sizeS` | `size="s"` | Implemented | +| `.spectrum-ProgressBar--sizeL` | `size="l"` | Implemented | +| `.spectrum-ProgressBar--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-ProgressBar--indeterminate` | `indeterminate` attribute | Implemented | +| `.spectrum-ProgressBar--sideLabel` | `sideLabel` attribute | Implemented | +| `.spectrum-ProgressBar--staticWhite` | `staticColor="white"` | Implemented | +| `.spectrum-ProgressBar-label` | `label` attribute; default slot | Implemented | +| `.spectrum-ProgressBar-percentage` | `` | Implemented | +| `.spectrum-ProgressBar-track` | `.track` container | Implemented | +| `.spectrum-ProgressBar-fill` | `.fill` element | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +No implementation gaps found. + +### CSS Spectrum 2 changes + +No structural differences found between the legacy (CSS main) and Spectrum 2 (CSS spectrum-two) branches. The template structure and class naming remain consistent across both branches. + +## Resources + +- [Original CSS migration](https://github.com/adobe/spectrum-css/pull/2659) +- [Additional follow-up migration work](https://github.com/adobe/spectrum-css/pull/3968) (occurred in the meter S2 migration) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-progress-bar--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/progressbar--docs) diff --git a/migration-roadmap/slider.md b/migration-roadmap/slider.md new file mode 100644 index 00000000000..898a460cd60 --- /dev/null +++ b/migration-roadmap/slider.md @@ -0,0 +1,530 @@ +# Slider migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-Slider` + +**Subcomponents:** + +- `.spectrum-Slider-handleContainer` +- `.spectrum-Slider-handle` +- `.spectrum-Slider-handle:before` +- `.spectrum-Slider:dir(rtl) .spectrum-Slider-handle:before` +- `.spectrum-Slider--precise .spectrum-Slider-handle` +- `.spectrum-Slider.spectrum-Slider--ramp .spectrum-Slider-handle` +- `.spectrum-Slider-ticks ~ .spectrum-Slider-handleContainer .spectrum-Slider-handle` +- `.spectrum-Slider.is-disabled .spectrum-Slider-handle` +- `.spectrum-Slider.is-disabled .spectrum-Slider-ramp + .spectrum-Slider-handle` +- `.spectrum-Slider-input` +- `.spectrum-Slider-labelContainer` +- `.spectrum-Slider--sideLabel .spectrum-Slider-labelContainer` +- `.spectrum-Slider.is-disabled .spectrum-Slider-labelContainer` +- `.spectrum-Slider-label` +- `.spectrum-Slider--sideLabel .spectrum-Slider-labelContainer .spectrum-Slider-label` +- `.spectrum-Slider-value` +- `.spectrum-Slider--range .spectrum-Slider-value` +- `.spectrum-Slider--sideLabel .spectrum-Slider-value` +- `.spectrum-Slider-controls` +- `.spectrum-Slider--tick .spectrum-Slider-controls` +- `.spectrum-Slider-content--editable .spectrum-Slider-controls` +- `.spectrum-Slider.is-disabled .spectrum-Slider-controls` +- `.spectrum-Slider:not(.spectrum-Slider--sideLabel) .spectrum-Slider-labelContainer + .spectrum-Slider-controls:has(.spectrum-Slider-ramp)` +- `.spectrum-Slider-content` +- `.spectrum-Slider-labelContainer + .spectrum-Slider-content` +- `.spectrum-Slider--sideLabel .spectrum-Slider-labelContainer + .spectrum-Slider-content` +- `.spectrum-Slider-labelContainer + .spectrum-Slider-content--editable` +- `.spectrum-Slider-trackContainer` +- `.spectrum-Slider-track` +- `.spectrum-Slider-track:before` +- `.spectrum-Slider.is-disabled .spectrum-Slider-track:before` +- `.spectrum-Slider-track:first-of-type:before` +- `.spectrum-Slider-track:last-of-type:before` +- `.spectrum-Slider-track ~ .spectrum-Slider-track` +- `.spectrum-Slider-track ~ .spectrum-Slider-track:before` +- `.spectrum-Slider--emphasized .spectrum-Slider-track:first-child:before` +- `.spectrum-Slider.is-disabled.spectrum-Slider--filled .spectrum-Slider-track:first-child:before` +- `.spectrum-Slider--emphasized.spectrum-Slider--range .spectrum-Slider-track:not(:first-of-type, :last-of-type):before` +- `.spectrum-Slider.is-disabled.spectrum-Slider--range .spectrum-Slider-track:not(:first-of-type, :last-of-type):before` +- `.spectrum-Slider-track:not(:has(~ .spectrum-Slider-fill)):before` +- `.spectrum-Slider--track-height-large .spectrum-Slider-track` +- `.spectrum-Slider--filled .spectrum-Slider-track:first-child:before` +- `.spectrum-Slider--range .spectrum-Slider-track:first-of-type` +- `.spectrum-Slider--range .spectrum-Slider-track:first-of-type:before` +- `.spectrum-Slider--range .spectrum-Slider-track:not(:first-of-type, :last-of-type):before` +- `.spectrum-Slider--range .spectrum-Slider-track:last-of-type` +- `.spectrum-Slider--range .spectrum-Slider-track:last-of-type:before` +- `.spectrum-Slider--range .spectrum-Slider-track ~ .spectrum-Slider-track` +- `.spectrum-Slider-ramp .spectrum-Slider-ramp-track` +- `.spectrum-Slider-ramp .spectrum-Slider-ramp-track-fill` +- `.spectrum-Slider--emphasized .spectrum-Slider-fill:before` +- `.spectrum-Slider--emphasized .spectrum-Slider-ramp .spectrum-Slider-ramp-track-fill` +- `.spectrum-Slider-fill` +- `.spectrum-Slider--track-height-large .spectrum-Slider-fill` +- `.spectrum-Slider-fill--right` +- `.spectrum-Slider-fill:before` +- `.spectrum-Slider.is-disabled .spectrum-Slider-fill:before` +- `.spectrum-Slider--tick` +- `.spectrum-Slider-controls:not(:has(.spectrum-Slider-ticks))` +- `.spectrum-Slider--tick .spectrum-Slider-tickLabel` +- `.spectrum-Slider-tick` +- `.spectrum-Slider-tick:after` +- `.spectrum-Slider-tick:first-of-type` +- `.spectrum-Slider-tick:first-of-type:after` +- `.spectrum-Slider-tick:last-of-type` +- `.spectrum-Slider-tick:last-of-type:after` +- `.spectrum-Slider-tick.spectrum-Slider-tick--track-height-large:after` +- `.spectrum-Slider.is-disabled .spectrum-Slider-tick:after` +- `.spectrum-Slider-tick .spectrum-Slider-tickLabel` +- `.spectrum-Slider-tick:first-of-type .spectrum-Slider-tickLabel` +- `.spectrum-Slider-tick:last-of-type .spectrum-Slider-tickLabel` +- `.spectrum-Slider.is-disabled .spectrum-Slider-tickLabel` +- `.spectrum-Slider--emphasized .spectrum-Slider-tick:nth-child(-n + 4):after` +- `.spectrum-Slider--range .spectrum-Slider-tick:nth-child(3):after` +- `.spectrum-Slider--range .spectrum-Slider-tick:nth-child(4):after` +- `.spectrum-Slider--range .spectrum-Slider-tick:nth-child(5):after` +- `.spectrum-Slider--filled:not(.spectrum-Slider--range, .is-disabled, .spectrum-Slider--emphasized) .spectrum-Slider-tick:nth-child(-n + 4):after` +- `.spectrum-Slider--offset:not(.spectrum-Slider--range, .is-disabled, .spectrum-Slider--emphasized) .spectrum-Slider-tick:nth-child(-n + 4):after` +- `.spectrum-Slider-ticks` +- `.spectrum-Slider-ramp svg` +- `.spectrum-Slider.is-disabled .spectrum-Slider-ramp path` + +**Variants:** + +- `.spectrum-Slider--sideLabel` +- `.spectrum-Slider-content--editable` +- `.spectrum-Slider-ramp` +- `.spectrum-Slider-handle.is-tophandle` + +**Sizes:** + +- `.spectrum-Slider--sizeL` +- `.spectrum-Slider--sizeS` +- `.spectrum-Slider--sizeXL` + +**Interactive states:** + +- `.spectrum-Slider-handle.is-dragged` +- `.spectrum-Slider-handle.is-focused` +- `.spectrum-Slider .spectrum-Slider-handle.is-focused:before` +- `.spectrum-Slider:not(.is-disabled) .spectrum-Slider-handle.is-focused` +- `.spectrum-Slider.spectrum-Slider--precise:not(.is-disabled) .spectrum-Slider-handle.is-focused:before` +- `.spectrum-Slider:not(.is-disabled) .spectrum-Slider-handle:focus` +- `.spectrum-Slider.spectrum-Slider--precise:not(.is-disabled) .spectrum-Slider-handle:focus:before` +- `.spectrum-Slider:not(.is-disabled) .spectrum-Slider-handle:focus:before` +- `.spectrum-Slider:not(.is-disabled) .spectrum-Slider-handle:focus-visible` +- `.spectrum-Slider.spectrum-Slider--precise:not(.is-disabled) .spectrum-Slider-handle:focus-visible:before` +- `.spectrum-Slider:not(.is-disabled) .spectrum-Slider-handle:focus-visible:before` +- `.spectrum-Slider:not(.is-disabled) .spectrum-Slider-handle.is-focused:before` +- `.spectrum-Slider-handle:active` +- `.spectrum-Slider.is-disabled .spectrum-Slider-handle:active` +- `.spectrum-Slider-handle:hover` +- `.spectrum-Slider.is-disabled .spectrum-Slider-handle:hover` +- `.spectrum-Slider-input:focus` +- `.spectrum-Slider.is-disabled` +- `.spectrum-Slider:not(.is-disabled, .spectrum-Slider--filled, .spectrum-Slider--range) .spectrum-Slider-controls:active` +- `.spectrum-Slider:not(.is-disabled, .spectrum-Slider--filled, .spectrum-Slider--range) .spectrum-Slider-controls.is-focused` +- `.spectrum-Slider:not(.is-disabled, .spectrum-Slider--filled, .spectrum-Slider--range) .spectrum-Slider-controls:focus-within` +- `.spectrum-Slider:not(.is-disabled, .spectrum-Slider--filled, .spectrum-Slider--range) .spectrum-Slider-controls:hover` + +**Internationalization:** + +- `.spectrum-Slider-labelContainer:lang(ja)` +- `.spectrum-Slider-labelContainer:lang(ko)` +- `.spectrum-Slider-labelContainer:lang(zh)` +- `.spectrum-Slider:dir(rtl)` + +
+ +
+Passthroughs + +- `--mod-fieldlabel-bottom-to-text` +- `--mod-fieldlabel-top-to-text` +- `--mod-textfield-width` + +
+ +
+Modifiers + +- `--mod-animation-duration-100` +- `--mod-focus-indicator-gap` +- `--mod-font-size-75` +- `--mod-line-height-100` +- `--mod-slider-cjk-line-height` +- `--mod-slider-control-height` +- `--mod-slider-control-to-side-field-label` +- `--mod-slider-control-to-text-field` +- `--mod-slider-controls-margin` +- `--mod-slider-disabled-border-color` +- `--mod-slider-editable-field-inline-size` +- `--mod-slider-emphasized-tick-mark-color` +- `--mod-slider-emphasized-track-fill-color` +- `--mod-slider-font-size` +- `--mod-slider-handle-background-color` +- `--mod-slider-handle-background-color-disabled` +- `--mod-slider-handle-border-color` +- `--mod-slider-handle-border-color-disabled` +- `--mod-slider-handle-border-color-down` +- `--mod-slider-handle-border-color-hover` +- `--mod-slider-handle-border-color-key-focus` +- `--mod-slider-handle-border-radius` +- `--mod-slider-handle-border-width` +- `--mod-slider-handle-disabled-background-color` +- `--mod-slider-handle-focus-ring-color-key-focus` +- `--mod-slider-handle-size` +- `--mod-slider-inline-size` +- `--mod-slider-input-left` +- `--mod-slider-input-top-size` +- `--mod-slider-label-font-family` +- `--mod-slider-label-font-style` +- `--mod-slider-label-font-weight` +- `--mod-slider-label-margin-start` +- `--mod-slider-label-text-color` +- `--mod-slider-label-text-color-disabled` +- `--mod-slider-ramp-track-color` +- `--mod-slider-ramp-track-color-disabled` +- `--mod-slider-ramp-track-fill-color` +- `--mod-slider-ramp-track-height` +- `--mod-slider-range-track-reset` +- `--mod-slider-tick-label-color` +- `--mod-slider-tick-mark-border-radius` +- `--mod-slider-tick-mark-color` +- `--mod-slider-tick-mark-color-filled-track` +- `--mod-slider-tick-mark-height` +- `--mod-slider-tick-mark-width` +- `--mod-slider-ticks-handle-background-color` +- `--mod-slider-track-color` +- `--mod-slider-track-color-disabled` +- `--mod-slider-track-corner-radius` +- `--mod-slider-track-fill-color` +- `--mod-slider-track-fill-color-disabled` +- `--mod-slider-track-fill-thickness` +- `--mod-slider-track-height-medium` +- `--mod-slider-track-thickness` +- `--mod-slider-value-inline-size` + +
+ +### SWC + +
+Attributes + +- `defaultValue` (Number) - Sets the default value of the `` +- `dragging` (Boolean) - Whether the slider value is actively being changed +- `editable` (Boolean) - Whether to display an `` alongside the slider UI +- `fillStart` (Number/Boolean) - Start point for fill +- `label` (String) - The visible slider text label +- `labelVisibility` (String) - Label visibility mode: 'text', 'value', or 'none' +- `max` (Number) - Maximum value +- `min` (Number) - Minimum value +- `quiet` (Boolean) - Applies quiet styling to underlying `` when editable +- `step` (Number) - Step increment +- `tickStep` (Number) - Tick step increment +- `tickLabels` (Boolean) - Whether to show tick labels +- `value` (Number) - The value of the slider handle +- `variant` (String) - Slider variant: 'filled', 'ramp', 'range', or 'tick' + +**Inherited from ``:** + +- `hideStepper` (Boolean) - Whether the stepper buttons of the `` are hidden or not +- `format-options` (Object) - Intl.NumberFormatOptions for customizing number formatting +- `indeterminate` (Boolean) - Applies `indeterminate` to underlying number field + +**Inherited from ``:** + +- `name` - Name of the form control +- `type` (String) - Component type + +**Inherited from `HandleController`:** + +- `highlight` (Boolean) - Indicates whether the slider handle should be visually highlighted during focus-visible or keyboard interaction states + +**Inherited from `SizedMixin`:** + +`size` - Size of the slider (s, m, l, xl) + +**Inherited from `Focusable`:** + +`disabled` - Disable this control. It will not receive focus or events +`tabIndex` - The tab index to apply to this control + +
+ +
+Slots + +- Default slot - @deprecated Text label for the slider. Use the `label` property instead +- Handle slot - Optionally accepts two or more sp-slider-handle elements + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components: + +```html +
+ + [label] + + + + [value] + +
+
+
+ + + +
+
+ +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ +
+ +
+ 14 +
+
+ + +
+
+
+ +
+
+
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ +
+ +
+ 14 +
+
+ +
+ +
+
+
+ +
+
+
+ + +
+ +
+
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff +
+ +
+ +
+ 14 +
+
+ ++
+ +
+
+
+- ++ +
+
+
++ ++ ++
++ ++
++
+
+``` + +**Key Changes in HTML Structure:** + +1. **Content wrapper introduction**: Added `.spectrum-Slider-content` container that wraps both the slider controls and the optional editable text field, providing better structural organization, as well as supporting the side-label layout. + +2. **Editable field integration**: Introduced conditional `.spectrum-Textfield.spectrum-Slider-editable` container with text input for editable slider functionality, enabling users to directly input values. + +3. **Enhanced accessibility**: Added explicit `tabindex="0"` to the slider handle for improved keyboard navigation and focus management. + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| -------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- | +| `.spectrum-Slider` | `:host` | Implemented | +| `.spectrum-Slider--sizeS` | `size="s"` | Implemented | +| `.spectrum-Slider--sizeL` | `size="l"` | Implemented | +| `.spectrum-Slider--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-Slider--ramp` | `variant="ramp"` | Implemented | +| `.spectrum-Slider--filled` | `variant="filled"` | Implemented | +| `.spectrum-Slider--range` | `variant="range"` | Implemented | +| `.spectrum-Slider--tick` | `variant="tick"` | Implemented | +| `.spectrum-Slider--offset` | `variant="filled` with `fill-start` attribute | Implemented | +| `.spectrum-Slider--sideLabel` | - | Implemented (possible with field label's `side-label` attribute) | +| `.spectrum-Slider.is-disabled` | `disabled` attribute | Implemented | +| `.spectrum-Slider-label` | Label slot/property | Implemented | +| `.spectrum-Slider-value` | Value label | Implemented | +| `.spectrum-Slider-labelContainer` | `#label-container` | Implemented | +| `.spectrum-Slider-content--editable` | `editable` attribute | Implemented | +| `.spectrum-Slider-controls` | `#controls` | Implemented | +| `.spectrum-Slider-track` | `.track` elements | Implemented | +| `.spectrum-Slider-fill` | `.fill` element | Implemented | +| `.spectrum-Slider-fill--right` | Fill direction | Implemented | +| `.spectrum-Slider-handle` | `.handle` element | Implemented | +| `.spectrum-Slider-input` | `.input` element | Implemented | +| `.spectrum-Slider-ramp` | Ramp container | Implemented | +| `.spectrum-Slider-ticks` | `.ticks` container | Implemented | +| `.spectrum-Slider-tick` | Individual `.tick` element | Implemented | +| `.spectrum-Slider-tickLabel` | `tickLabels` attribute | Implemented | +| `.spectrum-Slider-handleContainer` | `.handleContainer` in `variant="tick"` | Implemented | +| `.spectrum-Slider-trackContainer` | `.trackContainer` in `variant="tick"` | Implemented | +| `.spectrum-Slider-content` | Container for controls and editable field | Missing from WC (new for S2) | +| `.spectrum-Slider--emphasized` | Emphasized variant | Missing from WC (new for S2) | +| `.spectrum-Slider--track-height-large` | Track height variant | Missing from WC (new for S2) | +| `.spectrum-Slider--precise` | - | Missing from WC (new for S2) | +| - | `quiet` number field | Not supported in S2 | + +## Summary of changes + +### CSS => SWC implementation gaps + +- **Emphasized variant**: The web component lacks support for `.spectrum-Slider--emphasized` which provides emphasized styling for certain slider variants in Spectrum 2. + +- **Track height variants**: The web component lacks support for `.spectrum-Slider--track-height-large` which allows for different track heights. This feature was added in Spectrum 2. + +- **Container structure**: Missing structural elements for complex layouts like the side label slider. + +- **Precise handle variant**: For Spectrum 2, a new handle variant was introduced called "precise" with `.spectrum-Slider--precise` class. The slider's API will need an additional property to capture the new precise handle option. Discussion with design may be needed to properly update any "precision" behaviors. + +**Note about custom track color:** The current `` has support for inline styles to cascade into the shadow DOM, and apply custom styles to the track element. For Spectrum 2, the design specs suggest that there is a fill more often than not (except perhaps in the offset variant). We should collaborate with design to see if this level of customization is still intended or required for S2, to avoid any design issues when paired with the filled track color (i.e. how do we avoid a custom track color clashing with the specified fill color?). + +### CSS Spectrum 2 changes + +The Spectrum 2 migration introduces several key structural enhancements to the slider component: + +1. **Content wrapper architecture**: The addition of `.spectrum-Slider-content` container provides better structural organization and enables improved layout flexibility, particularly for side-label configurations and editable slider variants. + +2. **Editable functionality integration**: Introduction of the conditional `.spectrum-Textfield.spectrum-Slider-editable` container with text input enables direct value input functionality, specifically with a text input. The editable functionality was already implemented in Spectrum 1 web components, but we should reexamine the use of ``, or opt for the specified ``. + +3. **Enhanced accessibility standards**: The explicit addition of `tabindex="0"` to slider handles improves keyboard navigation compliance and ensures consistent focus management across different interaction modes. + +4. **Layout modernization**: The restructured DOM hierarchy better supports responsive design patterns and provides cleaner separation between control elements and content areas, facilitating more maintainable CSS architecture. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3945) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-slider--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/slider--docs) From 1156646d915c9882048926b8b0bddd7a422b0858 Mon Sep 17 00:00:00 2001 From: aramos-adobe Date: Wed, 8 Oct 2025 12:45:37 -0400 Subject: [PATCH 8/9] chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail (#5740) --- migration-roadmap/avatar.md | 217 +++++++++++++++++ migration-roadmap/opacity-checkerboard.md | 135 +++++++++++ migration-roadmap/swatch-group.md | 143 +++++++++++ migration-roadmap/swatch.md | 246 +++++++++++++++++++ migration-roadmap/thumbnail.md | 280 ++++++++++++++++++++++ 5 files changed, 1021 insertions(+) create mode 100644 migration-roadmap/avatar.md create mode 100644 migration-roadmap/opacity-checkerboard.md create mode 100644 migration-roadmap/swatch-group.md create mode 100644 migration-roadmap/swatch.md create mode 100644 migration-roadmap/thumbnail.md diff --git a/migration-roadmap/avatar.md b/migration-roadmap/avatar.md new file mode 100644 index 00000000000..e39fe2dc902 --- /dev/null +++ b/migration-roadmap/avatar.md @@ -0,0 +1,217 @@ +# Avatar migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Root class**: `.spectrum-Avatar` + +**Elements**: + +- `.spectrum-Avatar-image` +- `.spectrum-Avatar-link` + +**States**: + +- `.spectrum-Avatar.is-disabled` +- `.spectrum-Avatar.is-focused:not(.is-disabled):after` +- `.spectrum-Avatar:not(.is-disabled) .spectrum-Avatar-link:focus-visible:after` + +**Variants**: + +- `.spectrum-Avatar--size50` +- `.spectrum-Avatar--size75` +- `.spectrum-Avatar--size100` +- `.spectrum-Avatar--size200` +- `.spectrum-Avatar--size300` +- `.spectrum-Avatar--size400` +- `.spectrum-Avatar--size500` +- `.spectrum-Avatar--size600` +- `.spectrum-Avatar--size700` +- `.spectrum-Avatar--size800` +- `.spectrum-Avatar--size900` +- `.spectrum-Avatar--size1000` +- `.spectrum-Avatar--size1100` +- `.spectrum-Avatar--size1200` +- `.spectrum-Avatar--size1300` +- `.spectrum-Avatar--size1400` +- `.spectrum-Avatar--size1500` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers *deprecated* + +- `--mod-avatar-block-size` +- `--mod-avatar-border-radius` +- `--mod-avatar-color-opacity` +- `--mod-avatar-color-opacity-disabled` +- `--mod-avatar-focus-indicator-color` +- `--mod-avatar-focus-indicator-gap` +- `--mod-avatar-focus-indicator-thickness` +- `--mod-avatar-inline-size` + +
+ +### SWC + +
+Attributes + +- `src` (string) - Source URL for the avatar image +- `size` (number) - Size of the avatar (50, 75, 100, 200, 300, 400, 500, 600, 700) +- `href` (string) - Link URL when avatar is clickable +- `label` (string) - Alt text for the avatar image +- `disabled` (boolean) - Whether the avatar is disabled + +Note that other link-related attributes are available on the base `LikeAnchor` class, such as `download`, `href`, `referrerpolicy`, `rel`, `target`, and `type` but are not necessarily applicable to the avatar component and so not listed out explicitly here. + +
+ +
+Slots + +None found for this component. + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components + +```html + + + [label] + + + +[label] +``` + +
+ +
+Legacy (CSS main branch) + +```html + +
+ + [altText] + +
+ + +
+ [altText] +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch) + +```html + +
+ + [altText] + +
+ + +
+ [altText] +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +No significant structural changes. + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ---------------------------- | -------------------- | ---------------------------------------- | +| `.spectrum-Avatar--size50` | `size="50"` | Implemented | +| `.spectrum-Avatar--size75` | `size="75"` | Implemented | +| `.spectrum-Avatar--size100` | `size="100"` | Implemented | +| `.spectrum-Avatar--size200` | `size="200"` | Implemented | +| `.spectrum-Avatar--size300` | `size="300"` | Implemented | +| `.spectrum-Avatar--size400` | `size="400"` | Implemented | +| `.spectrum-Avatar--size500` | `size="500"` | Implemented | +| `.spectrum-Avatar--size600` | `size="600"` | Implemented | +| `.spectrum-Avatar--size700` | `size="700"` | Implemented | +| `.spectrum-Avatar-image` | `src` attribute | Implemented | +| `.spectrum-Avatar-link` | `href` attribute | Implemented | +| `.is-focused` | Focus state | Implemented | +| `.is-disabled` | `disabled` attribute | Implemented | +| `.spectrum-Avatar--size800` | `size="800"` | Missing from WC (new size in Spectrum 2) | +| `.spectrum-Avatar--size900` | `size="900"` | Missing from WC (new size in Spectrum 2) | +| `.spectrum-Avatar--size1000` | `size="1000"` | Missing from WC (new size in Spectrum 2) | +| `.spectrum-Avatar--size1100` | `size="1100"` | Missing from WC (new size in Spectrum 2) | +| `.spectrum-Avatar--size1200` | `size="1200"` | Missing from WC (new size in Spectrum 2) | +| `.spectrum-Avatar--size1300` | `size="1300"` | Missing from WC (new size in Spectrum 2) | +| `.spectrum-Avatar--size1400` | `size="1400"` | Missing from WC (new size in Spectrum 2) | +| `.spectrum-Avatar--size1500` | `size="1500"` | Missing from WC (new size in Spectrum 2) | + +## Summary of changes + +### CSS => SWC implementation gaps + +**CSS features missing from Web Component:** + +- Larger size variants (800, 900, 1000, 1100, 1200, 1300, 1400, 1500) + +**Web Component features missing from CSS:** +None found for this component. + +### CSS Spectrum 2 changes + +No significant structural changes between CSS main and spectrum-two branches. The templates are identical, indicating that the avatar component structure remains consistent across Spectrum 2 migration. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3355) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-avatar--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/avatar--docs) diff --git a/migration-roadmap/opacity-checkerboard.md b/migration-roadmap/opacity-checkerboard.md new file mode 100644 index 00000000000..761e1af8e33 --- /dev/null +++ b/migration-roadmap/opacity-checkerboard.md @@ -0,0 +1,135 @@ +# Opacity Checkerboard migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Root class**: `.spectrum-OpacityCheckerboard` + +**Variants**: + +- `.spectrum-OpacityCheckerboard--sizeS` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers *deprecated* + +- `--mod-opacity-checkerboard-dark` +- `--mod-opacity-checkerboard-light` +- `--mod-opacity-checkerboard-position` +- `--mod-opacity-checkerboard-size` + +
+ +### SWC + +
+Attributes + +None found for this component. This is a utility component used by other components. + +
+ +
+Slots + +None found for this component. This is a utility component used by other components. + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components + +```html + +
+ +
+``` + +
+ +
+Legacy (CSS main branch) + +```html +
+ +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch) + +```html +
+ +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +No significant structural changes. + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| -------------------------------------- | ----------------- | ---------------------- | +| `.spectrum-OpacityCheckerboard` | Utility class | Implemented as utility | +| `.spectrum-OpacityCheckerboard--sizeS` | Size variant | Implemented as utility | + +## Summary of changes + +### CSS => SWC implementation gaps + +**CSS features missing from Web Component:** +None found for this component. The opacity checkerboard is implemented as a utility class in the Web Components. + +**Web Component features missing from CSS:** +None found for this component. + +### CSS Spectrum 2 changes + +No significant structural changes between CSS main and spectrum-two branches. The templates are identical, indicating that the opacity checkerboard component structure remains consistent across Spectrum 2 migration. + +## Notes + +The opacity checkerboard is a utility component that provides a checkerboard pattern background to highlight transparency in other components. It's not a standalone component but rather a utility class that's used by components like thumbnail, swatch, and others to provide visual indication of transparency. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3394) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-opacity-checkerboard--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorslider--docs) (not a standalone component, but styles are used by the color slider) diff --git a/migration-roadmap/swatch-group.md b/migration-roadmap/swatch-group.md new file mode 100644 index 00000000000..34b2b8e4b45 --- /dev/null +++ b/migration-roadmap/swatch-group.md @@ -0,0 +1,143 @@ +# Swatch Group migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Root class**: `.spectrum-SwatchGroup` + +**Variants**: + +- **Density**: +- `.spectrum-SwatchGroup--compact` +- `.spectrum-SwatchGroup--spacious` + +
+ +
+Passthroughs + +- `--mod-swatch-border-opacity` + +
+ +
+Modifiers *deprecated* + +- `--mod-swatchgroup-spacing` + +
+ +### SWC + +
+Attributes + +- `border` (string) - Border style: 'light', 'none' **deprecated** (from Swatch component) +- `density` (string) - Density: 'compact', 'spacious' +- `rounding` (string) - Corner rounding: 'none', 'full' +- `shape` (string) - Shape variant: 'rectangle' **note**: should this be combined with rounding? +- `selected` (array) - Array of selected swatch values +- `selects` (string) - Selection mode: 'single', 'multiple' **note**: does this need any unique styles designed for single or multi-select swatch groups? +- `size` (string) - Size: 'xs', 's', 'm' (default), 'l' + +
+ +
+Slots + +- Default slot - Swatch elements to manage as a group + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components + +```html + + + +``` + +
+ +
+Legacy (CSS main branch) + +```html +
+ +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch) + +```html +
+ +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +No significant structural changes. + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| --------------------------------- | -------------------- | ------------------------------------------------------------------ | +| `.spectrum-SwatchGroup--compact` | `density="compact"` | Implemented | +| `.spectrum-SwatchGroup--spacious` | `density="spacious"` | Implemented | +| `.spectrum-SwatchGroup` | Base component | Implemented | +| - | `border` attribute | **deprecated** (from Swatch component) | +| - | `rounding` attribute | See Swatch component | +| - | `selected` state | See Swatch component | +| - | `selects` attribute | No unique styles designed for single or multi-select swatch groups | +| - | `shape` attribute | See Swatch component | +| - | `size` attribute | See Swatch component | + +## Summary of changes + +### CSS => SWC implementation gaps + +**CSS features missing from Web Component:** +None found for this component. + +**Web Component features missing from CSS:** + +None identified for this component. + +### CSS Spectrum 2 changes + +No significant structural changes between CSS main and spectrum-two branches. The templates are identical, indicating that the swatch group component structure remains consistent across Spectrum 2 migration. Swatch group includes a setting for single or multiple selection and it might be worth connecting with design to see if there should be any unique styles designed that differentiates single or multi-select swatch groups. + +The border attribute is being removed from the group component as the border property is no longer customizable. The design direction is more opinionated for Spectrum 2 than it was for S1. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3677) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-swatch-group--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorswatchpicker--docs) diff --git a/migration-roadmap/swatch.md b/migration-roadmap/swatch.md new file mode 100644 index 00000000000..994a1908440 --- /dev/null +++ b/migration-roadmap/swatch.md @@ -0,0 +1,246 @@ +# Swatch migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Root class**: `.spectrum-Swatch` + +**Elements**: + +- `.spectrum-Swatch:before` +- `.spectrum-Swatch:after` +- `.spectrum-Swatch-icon` +- `.spectrum-Swatch-image` +- `.spectrum-Swatch-disabledIcon` - visible only when the swatch is disabled + - `.spectrum-Swatch-disabledIcon path:first-child` + - `.spectrum-Swatch-disabledIcon path:last-child` +- `.spectrum-Swatch-fill` + - `.spectrum-Swatch-fill:before` + +**Variants**: + +- **Rounding**: + - `.spectrum-Swatch--rectangle` + - `.spectrum-Swatch--roundingFull` + - `.spectrum-Swatch--roundingNone` +- **Size**: + - `.spectrum-Swatch--sizeXS` + - `.spectrum-Swatch--sizeS` + - (medium is the default) + - `.spectrum-Swatch--sizeL` +- `.is-addSwatch` +- `.is-image` +- `.is-mixedValue` +- `.is-nothing` + +**States**: + +- `.is-disabled`, `[disabled]` +- `.is-focused`, `:focus-visible` +- `.is-keyboardFocused` +- `.is-selected` +- `.is-hover`, `:hover` +- `.is-active`, `:active` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers *deprecated* + +- `--mod-add-button-background` +- `--mod-add-button-background-down` +- `--mod-add-button-background-hover` +- `--mod-add-button-background-keyboard-focus` +- `--mod-animation-duration-100` +- `--mod-corner-radius-full` +- `--mod-mixed-button-background` +- `--mod-swatch-border` +- `--mod-swatch-border-color` +- `--mod-swatch-border-color-selected` +- `--mod-swatch-border-opacity` +- `--mod-swatch-border-radius` +- `--mod-swatch-border-thickness` +- `--mod-swatch-border-thickness-selected` +- `--mod-swatch-disabled-icon-color` +- `--mod-swatch-disabled-icon-size` +- `--mod-swatch-focus-indicator-color` +- `--mod-swatch-focus-indicator-gap` +- `--mod-swatch-focus-indicator-thickness` +- `--mod-swatch-icon-border-color` +- `--mod-swatch-icon-color` +- `--mod-swatch-inner-border-color-selected` +- `--mod-swatch-size` +- `--mod-swatch-slash-icon-color` +- `--mod-swatch-slash-thickness` + +
+ +### SWC + +
+Attributes + +- `border` (string) - Border style: 'light', 'none' +- `color` (string) - Color value for the swatch +- `label` (string) - Label for the swatch +- `mixed-value` (boolean) - Whether the swatch represents a mixed value +- `nothing` (boolean) - Whether the swatch represents no value +- `role` (string) - ARIA role, defaults to 'button' +- `rounding` (string) - Corner rounding: 'none', 'full' +- `selected` (boolean) - Whether the swatch is selected +- `shape` (string) - Shape variant: 'rectangle' +- `size` (string) - Size: 'xs', 's', 'm', 'l' +- `disabled` (boolean) - Whether the swatch is disabled +- `value` (string) - Value of the swatch (computed from color or label) + +
+ +
+Slots + +- `image` slot - Image element for the swatch + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components + +```html +
+ + + +
+``` + +
+ +
+Legacy (CSS main branch) + +```html +
+ +
+ +
+ + +
+ + + +
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch) + +```html +
+ +
+ +
+ + +
+ + + +
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +No significant structural changes. + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| -------------------------------- | ------------------------ | ------------------------------------------ | +| `.spectrum-Swatch--sizeXS` | `size="xs"` | Implemented | +| `.spectrum-Swatch--sizeS` | `size="s"` | Implemented | +| `.spectrum-Swatch--sizeM` | `size="m"` | Implemented | +| `.spectrum-Swatch--sizeL` | `size="l"` | Implemented | +| `.spectrum-Swatch--roundingNone` | `rounding="none"` | Implemented | +| `.spectrum-Swatch--roundingFull` | `rounding="full"` | Implemented | +| `.spectrum-Swatch--rectangle` | `shape="rectangle"` | Implemented | +| `.is-selected` | `selected` attribute | Implemented | +| `.is-disabled` | `disabled` attribute | Implemented | +| `.is-mixedValue` | `mixed-value` attribute | Implemented | +| `.spectrum-Swatch--lightBorder` | `border` attribute | **Deprecated** | +| `.is-addSwatch` | Add swatch functionality | Missing from WC (new for S2) | +| `.is-nothing` | `nothing` attribute | Implemented | +| `.is-keyboardFocused` | Focus state | Implemented | +| `.is-hover`, `:hover` | Hover state | Implemented | +| `.is-active`, `:active` | Active state | Implemented | +| `:focus-visible` | Focus styling | Implemented | +| `.is-image` | `image` slot not empty | Might need additional hooks or logic in WC | +| `.spectrum-Swatch-image` | `image` slot | Implemented | +| `.spectrum-Swatch-fill` | Internal wrapper | Implemented | +| `.spectrum-Swatch-icon` | Icon elements | Implemented | +| `.spectrum-Swatch-disabledIcon` | Disabled icon | Implemented | +| `.spectrum-Swatch:before` | Pseudo-element styling | Implemented | +| `.spectrum-Swatch:after` | Pseudo-element styling | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +**CSS features missing from Web Component:** + +- Add swatch functionality (`.is-addSwatch`) +- Image functionality (SWC has an image slot, but this may need additional updates to work properly) + +**Web Component features missing from CSS:** + +None found for this component. + +### CSS Spectrum 2 changes + +There is a new **add swatch** functionality in the `spectrum-two` branch and supplemental state and pseudo-element styling selectors in the `spectrum-two` branch which will automatically be applied when consumed by the web component for Spectrum 2. + +The light and no border variants have been removed. Individual swatches have a border set to `--spectrum-gray-1000` at 42% opacity, while the border opacity is set to 20% in swatch groups. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3677) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-swatch--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorswatch--docs) diff --git a/migration-roadmap/thumbnail.md b/migration-roadmap/thumbnail.md new file mode 100644 index 00000000000..17e36916cba --- /dev/null +++ b/migration-roadmap/thumbnail.md @@ -0,0 +1,280 @@ +# Thumbnail migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Root class**: `.spectrum-Thumbnail` + +**Elements**: + +- `.spectrum-Thumbnail:before` +- `.spectrum-Thumbnail-image` +- `.spectrum-Thumbnail-image-wrapper` +- `.spectrum-Thumbnail-layer` +- `.spectrum-Thumbnail-layer:before` +- `.spectrum-Thumbnail-layer-inner` +- `.spectrum-Thumbnail-background` + +**States**: + +- `.is-disabled`, `:disabled` +- `.is-focused`, `:focus-visible` +- `.is-selected` (attached to `.spectrum-Thumbnail-layer`, not to the root element) + +**Variants**: + +- **Size**: + - `.spectrum-Thumbnail--size50` + - `.spectrum-Thumbnail--size75` + - `.spectrum-Thumbnail--size100` + - `.spectrum-Thumbnail--size200` + - `.spectrum-Thumbnail--size300` + - `.spectrum-Thumbnail--size400` + - `.spectrum-Thumbnail--size500` + - `.spectrum-Thumbnail--size600` + - `.spectrum-Thumbnail--size700` + - `.spectrum-Thumbnail--size800` + - `.spectrum-Thumbnail--size900` + - `.spectrum-Thumbnail--size1000` + +- **Image cover**: + - `.spectrum-Thumbnail--cover` + +
+ +
+Passthroughs + +- `--mod-opacity-checkerboard-size` + +
+ +
+Modifiers *deprecated* + +- `--mod-thumbnail-border-color` +- `--mod-thumbnail-border-color-selected` +- `--mod-thumbnail-border-radius` +- `--mod-thumbnail-border-width` +- `--mod-thumbnail-border-width-selected` +- `--mod-thumbnail-color-opacity-disabled` +- `--mod-thumbnail-focus-indicator-color` +- `--mod-thumbnail-focus-indicator-gap` +- `--mod-thumbnail-focus-indicator-thickness` +- `--mod-thumbnail-layer-border-color-inner` +- `--mod-thumbnail-layer-border-color-outer` +- `--mod-thumbnail-layer-border-width-inner` +- `--mod-thumbnail-layer-border-width-outer` +- `--mod-thumbnail-size` + +
+ +### SWC + +
+Attributes + +- `background` (string) - Background color or gradient for the thumbnail +- `cover` (boolean) - Whether the image should cover the entire thumbnail +- `layer` (boolean) - Whether the thumbnail is in layer mode +- `size` (string) - Size of the thumbnail (50, 75, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000) +- `disabled` (boolean) - Whether the thumbnail is disabled +- `selected` (boolean) - Whether the thumbnail is selected (used for layer variant) + +
+ +
+Slots + +- Default slot - Image element to present in the thumbnail + +
+ +## Comparison + +### DOM Structure changes + +
+Spectrum Web Components + +```html + +
+
+ +
+
+ + +
+ +
+ + +
+ +
+``` + +
+ +
+Legacy (CSS main branch): + +```html + +
+
+
+ [altText] +
+
+
+ + +
+
+
+ [altText] +
+
+ + +
+
+ [altText] +
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +
+
+
+ [altText] +
+
+
+ + +
+
+
+ [altText] +
+
+ + +
+
+ [altText] +
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +No significant structural changes. + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| ----------------------------------- | ---------------------- | ----------- | +| `.spectrum-Thumbnail--size50` | `size="50"` | Implemented | +| `.spectrum-Thumbnail--size75` | `size="75"` | Implemented | +| `.spectrum-Thumbnail--size100` | `size="100"` | Implemented | +| `.spectrum-Thumbnail--size200` | `size="200"` | Implemented | +| `.spectrum-Thumbnail--size300` | `size="300"` | Implemented | +| `.spectrum-Thumbnail--size400` | `size="400"` | Implemented | +| `.spectrum-Thumbnail--size500` | `size="500"` | Implemented | +| `.spectrum-Thumbnail--size600` | `size="600"` | Implemented | +| `.spectrum-Thumbnail--size700` | `size="700"` | Implemented | +| `.spectrum-Thumbnail--size800` | `size="800"` | Implemented | +| `.spectrum-Thumbnail--size900` | `size="900"` | Implemented | +| `.spectrum-Thumbnail--size1000` | `size="1000"` | Implemented | +| `.spectrum-Thumbnail--cover` | `cover` attribute | Implemented | +| `.spectrum-Thumbnail-layer` | `layer` attribute | Implemented | +| `.spectrum-Thumbnail-background` | `background` attribute | Implemented | +| `.spectrum-Thumbnail-image` | Default slot | Implemented | +| `.spectrum-Thumbnail-image-wrapper` | Internal wrapper | Implemented | +| `.spectrum-Thumbnail-layer-inner` | Internal wrapper | Implemented | +| `.is-disabled` | `disabled` attribute | Implemented | +| `.is-focused` | Focus state | Implemented | +| `.is-selected` | `selected` attribute | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +**CSS features missing from Web Component:** +None found for this component. + +**Web Component features missing from CSS:** +None found for this component. + +### CSS Spectrum 2 changes + +No significant structural changes between CSS main and spectrum-two branches. The templates are identical, indicating that the thumbnail component structure remains consistent across Spectrum 2 migration. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/3367) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-thumbnail--docs) +- React (no thumbnail component in React Spectrum) From 198682819822ffa0cdae6da336f7ab30a958a8f7 Mon Sep 17 00:00:00 2001 From: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com> Date: Mon, 13 Oct 2025 11:15:33 -1000 Subject: [PATCH 9/9] docs(button, buttongroup, actionbutton, actiongroup): component analysis (#5788) --- migration-roadmap/action-button.md | 394 ++++++++++++++++++++++++ migration-roadmap/action-group.md | 294 ++++++++++++++++++ migration-roadmap/button-group.md | 134 +++++++++ migration-roadmap/button.md | 461 +++++++++++++++++++---------- 4 files changed, 1128 insertions(+), 155 deletions(-) create mode 100644 migration-roadmap/action-button.md create mode 100644 migration-roadmap/action-group.md create mode 100644 migration-roadmap/button-group.md diff --git a/migration-roadmap/action-button.md b/migration-roadmap/action-button.md new file mode 100644 index 00000000000..8faea9768af --- /dev/null +++ b/migration-roadmap/action-button.md @@ -0,0 +1,394 @@ +# Action button migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Base component:** + +- `.spectrum-ActionButton` + +**Sizes:** + +- `.spectrum-ActionButton--sizeXS` +- `.spectrum-ActionButton--sizeS` +- `.spectrum-ActionButton--sizeL` +- `.spectrum-ActionButton--sizeXL` + +**Variants and treatments:** + +- `.spectrum-ActionButton.spectrum-ActionButton--quiet` +- `.spectrum-ActionButton.spectrum-ActionButton--staticWhite` +- `.spectrum-ActionButton.spectrum-ActionButton--staticWhite.spectrum-ActionButton--quiet` +- `.spectrum-ActionButton.spectrum-ActionButton--staticBlack` +- `.spectrum-ActionButton.spectrum-ActionButton--staticBlack.spectrum-ActionButton--quiet` + +**Child elements:** + +- `.spectrum-ActionButton .spectrum-ActionButton-hold` +- `.spectrum-ActionButton .spectrum-ActionButton-icon` +- `.spectrum-ActionButton .spectrum-ActionButton-label` +- `.spectrum-ActionButton-hold` +- `.spectrum-ActionButton-icon` +- `.spectrum-ActionButton-label` +- `.spectrum-ActionButton-label:empty` + +**States:** + +- `.spectrum-ActionButton.is-disabled` +- `.spectrum-ActionButton.is-selected` +- `.spectrum-ActionButton:disabled` +- `.spectrum-ActionButton:active` +- `.spectrum-ActionButton:hover` + +**Selected state with variants:** + +- `.spectrum-ActionButton.is-selected.spectrum-ActionButton--emphasized` +- `.spectrum-ActionButton.is-selected.spectrum-ActionButton--staticWhite` +- `.spectrum-ActionButton.is-selected.spectrum-ActionButton--staticBlack` +- `.spectrum-ActionButton.spectrum-ActionButton--quiet.is-selected` +- `.spectrum-ActionButton.spectrum-ActionButton--quiet:disabled:not(.is-selected)` + +**Focus indicators:** + +- `.spectrum-ActionButton:focus` +- `.spectrum-ActionButton:focus-visible` +- `.spectrum-ActionButton:focus-visible:after` +- `.spectrum-ActionButton::-moz-focus-inner` +- `.spectrum-ActionButton:after` + +**Content detection:** + +- `.spectrum-ActionButton:has(.spectrum-ActionButton-icon)` +- `.spectrum-ActionButton:not(:has(.spectrum-ActionButton-label))` + +**RTL support:** + +- `.spectrum-ActionButton:dir(rtl)` + +**Link variant:** + +- `a.spectrum-ActionButton` + +
+ +
+Passthroughs + +- `--mod-button-animation-duration` +- `--mod-button-font-family` + +
+ +
+Modifiers + +**Sizing and spacing:** + +- `--mod-actionbutton-height` +- `--mod-actionbutton-min-width` +- `--mod-actionbutton-edge-to-visual` +- `--mod-actionbutton-edge-to-visual-only` +- `--mod-actionbutton-edge-to-text` +- `--mod-actionbutton-edge-to-hold-icon` +- `--mod-actionbutton-text-to-visual` +- `--mod-actionbutton-icon-size` + +**Typography:** + +- `--mod-actionbutton-font-size` +- `--mod-actionbutton-font-weight` +- `--mod-actionbutton-font-style` +- `--mod-actionbutton-line-height` +- `--mod-actionbutton-label-color` + +**Border and radius:** + +- `--mod-actionbutton-border-radius` +- `--mod-actionbutton-focus-indicator-border-radius` + +**Focus indicators:** + +- `--mod-actionbutton-focus-indicator-gap` +- `--mod-actionbutton-focus-indicator-thickness` +- `--mod-actionbutton-focus-indicator-color` + +**Animation:** + +- `--mod-actionbutton-animation-duration` + +**Default state colors:** + +- `--mod-actionbutton-background-color-default` +- `--mod-actionbutton-content-color-default` + +**Hover state colors:** + +- `--mod-actionbutton-background-color-hover` +- `--mod-actionbutton-content-color-hover` + +**Focus state colors:** + +- `--mod-actionbutton-background-color-focus` +- `--mod-actionbutton-content-color-focus` + +**Active/down state colors:** + +- `--mod-actionbutton-background-color-down` +- `--mod-actionbutton-content-color-down` + +**Disabled state colors:** + +- `--mod-actionbutton-background-color-disabled` +- `--mod-actionbutton-content-color-disabled` + +**Selected state colors:** + +- `--mod-actionbutton-background-color-default-selected` +- `--mod-actionbutton-content-color-default-selected` +- `--mod-actionbutton-background-color-hover-selected` +- `--mod-actionbutton-content-color-hover-selected` +- `--mod-actionbutton-background-color-focus-selected` +- `--mod-actionbutton-content-color-focus-selected` +- `--mod-actionbutton-background-color-down-selected` +- `--mod-actionbutton-content-color-down-selected` + +**Selected + emphasized state colors:** + +- `--mod-actionbutton-background-color-default-selected-emphasized` +- `--mod-actionbutton-content-color-default-selected-emphasized` +- `--mod-actionbutton-background-color-hover-selected-emphasized` +- `--mod-actionbutton-content-color-hover-selected-emphasized` +- `--mod-actionbutton-background-color-focus-selected-emphasized` +- `--mod-actionbutton-content-color-focus-selected-emphasized` +- `--mod-actionbutton-background-color-down-selected-emphasized` +- `--mod-actionbutton-content-color-down-selected-emphasized` + +
+ +### SWC + +
+Attributes + +**Size:** + +- `size` (values: `xs`, `s`, `m`, `l`, `xl`) - button size, no default + +**Variants:** + +- `emphasized` - adds visual emphasis to selected state (boolean) +- `quiet` - applies quiet styling (boolean) +- `static-color` (values: `white`, `black`) - static color variant for use over backgrounds + +**Selection state:** + +- `selected` - whether the button is selected (boolean) +- `toggles` - whether to automatically manage selected state on interaction and use aria-pressed (boolean) + +**Hold affordance:** + +- `hold-affordance` - shows corner triangle indicator for longpress action (boolean) + +**States:** + +- `active` - active/pressed state (inherited from ButtonBase) +- `disabled` - disabled state (inherited from Focusable) + +**Content:** + +- `label` - accessible label (inherited from LikeAnchor) + +**Focus management:** + +- `autofocus` - auto-focus on load (inherited from Focusable) +- `tabIndex` - tab index (inherited from Focusable) + +**Link behavior:** + +- `href` - makes button behave as link (inherited from LikeAnchor) +- `target` (values: `_blank`, `_parent`, `_self`, `_top`) - link target (inherited from LikeAnchor) +- `download` - download attribute (inherited from LikeAnchor) +- `referrerpolicy` - referrer policy (inherited from LikeAnchor) +- `rel` - link relationship (inherited from LikeAnchor) + +**Form behavior:** + +- `type` (values: `button`, `submit`, `reset`) - button type (inherited from ButtonBase) +- `name` - form field name (inherited from ButtonBase) +- `value` - button value, defaults to trimmed text content + +**ARIA:** + +- `role` - ARIA role, defaults to `button` + +
+ +
+Slots + +- Default slot - text label of the action button +- `icon` - the icon to use for action button + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components + +```html + + + + + + + + + + + +``` + +
+ +
+Legacy (CSS main branch) + +```html + +``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch) + +```html + +``` + +
+ +### CSS => SWC mapping + +#### Sizes + +| CSS selector | SWC attribute | Status | +| -------------------------------- | ------------------------------- | ----------- | +| `.spectrum-ActionButton` | Base component (default size M) | Implemented | +| `.spectrum-ActionButton--sizeXS` | `size="xs"` | Implemented | +| `.spectrum-ActionButton--sizeS` | `size="s"` | Implemented | +| `.spectrum-ActionButton--sizeL` | `size="l"` | Implemented | +| `.spectrum-ActionButton--sizeXL` | `size="xl"` | Implemented | + +#### Variants and treatments + +| CSS selector | SWC attribute | Status | +| ---------------------------------------------------------------------------------------- | -------------------------------- | ----------- | +| `.spectrum-ActionButton.spectrum-ActionButton--quiet` | `quiet` | Implemented | +| `.spectrum-ActionButton.spectrum-ActionButton--staticWhite` | `static-color="white"` | Implemented | +| `.spectrum-ActionButton.spectrum-ActionButton--staticBlack` | `static-color="black"` | Implemented | +| `.spectrum-ActionButton.spectrum-ActionButton--staticWhite.spectrum-ActionButton--quiet` | `static-color="white"` + `quiet` | Implemented | +| `.spectrum-ActionButton.spectrum-ActionButton--staticBlack.spectrum-ActionButton--quiet` | `static-color="black"` + `quiet` | Implemented | + +#### States + +| CSS selector | SWC attribute | Status | +| -------------------------------------------------------------------------------- | ----------------------------------- | ----------- | +| `.spectrum-ActionButton.is-selected` | `selected` | Implemented | +| `.spectrum-ActionButton.is-disabled` | `disabled` | Implemented | +| `.spectrum-ActionButton:disabled` | `disabled` | Implemented | +| `.spectrum-ActionButton:active` | `active` | Implemented | +| `.spectrum-ActionButton:hover` | Pseudo-state | Implemented | +| `.spectrum-ActionButton.is-selected.spectrum-ActionButton--emphasized` | `selected` + `emphasized` | Implemented | +| `.spectrum-ActionButton.is-selected.spectrum-ActionButton--staticWhite` | `selected` + `static-color="white"` | Implemented | +| `.spectrum-ActionButton.is-selected.spectrum-ActionButton--staticBlack` | `selected` + `static-color="black"` | Implemented | +| `.spectrum-ActionButton.spectrum-ActionButton--quiet.is-selected` | `quiet` + `selected` | Implemented | +| `.spectrum-ActionButton.spectrum-ActionButton--quiet:disabled:not(.is-selected)` | `quiet` + `disabled` (not selected) | Implemented | + +#### Focus indicators + +| CSS selector | SWC attribute | Status | +| -------------------------------------------- | --------------------- | ----------- | +| `.spectrum-ActionButton:focus` | Pseudo-state | Implemented | +| `.spectrum-ActionButton:focus-visible` | Pseudo-state | Implemented | +| `.spectrum-ActionButton:focus-visible:after` | Focus ring | Implemented | +| `.spectrum-ActionButton:after` | Focus ring element | Implemented | +| `.spectrum-ActionButton::-moz-focus-inner` | Firefox focus styling | Implemented | + +#### Content and layout + +| CSS selector | SWC attribute/slot | Status | +| ---------------------------------------------------------------- | ---------------------------------------- | ----------- | +| `.spectrum-ActionButton .spectrum-ActionButton-icon` | `icon` slot | Implemented | +| `.spectrum-ActionButton-icon` | `icon` slot | Implemented | +| `.spectrum-ActionButton .spectrum-ActionButton-label` | Default slot | Implemented | +| `.spectrum-ActionButton-label` | Default slot | Implemented | +| `.spectrum-ActionButton-label:empty` | Empty label handling | Implemented | +| `.spectrum-ActionButton .spectrum-ActionButton-hold` | `hold-affordance` attribute | Implemented | +| `.spectrum-ActionButton-hold` | `hold-affordance` attribute | Implemented | +| `.spectrum-ActionButton:has(.spectrum-ActionButton-icon)` | Detected when icon slot has content | Implemented | +| `.spectrum-ActionButton:not(:has(.spectrum-ActionButton-label))` | Detected when default slot is empty | Implemented | +| `.spectrum-ActionButton:dir(rtl)` | Browser RTL support | Implemented | +| `a.spectrum-ActionButton` | `href` attribute makes it render as link | Implemented | + +#### WC-only attributes + +| SWC attribute | CSS equivalent | Notes | +| ------------- | -------------- | --------------------------------------------- | +| `toggles` | N/A | Manages selected state automatically on click | +| `value` | N/A | Used for identification in action groups | +| `role` | N/A | Dynamic ARIA role management | + +## Summary of changes + +### CSS => SWC implementation gaps + +**Missing from WC:** +None. All CSS selectors have corresponding web component implementations. + +### CSS Spectrum 2 changes + +**No structural changes:** +The Action Button template is functionally identical between the main branch (legacy) and spectrum-two branch (Spectrum 2). Both branches render the same HTML DOM structure and use the same size-specific corner triangle icons (CornerTriangle75, CornerTriangle100, CornerTriangle200, CornerTriangle300). + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2669) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-action-button--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/actionbutton--docs) diff --git a/migration-roadmap/action-group.md b/migration-roadmap/action-group.md new file mode 100644 index 00000000000..54e59aae7a2 --- /dev/null +++ b/migration-roadmap/action-group.md @@ -0,0 +1,294 @@ +# Action group migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Base component:** + +- `.spectrum-ActionGroup` + +**Sizes:** + +- `.spectrum-ActionGroup--sizeXS` +- `.spectrum-ActionGroup--sizeS` +- `.spectrum-ActionGroup--sizeM` +- `.spectrum-ActionGroup--sizeL` +- `.spectrum-ActionGroup--sizeXL` + +**Layout variants:** + +- `.spectrum-ActionGroup--vertical` +- `.spectrum-ActionGroup--compact` + +**Compact mode:** + +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet)` +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item` +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item + .spectrum-ActionGroup-item` +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item .spectrum-ActionButton-label` +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item.is-selected` +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:first-child` +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:last-child` +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:hover` +- `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:focus-visible` + +**Compact + vertical mode:** + +- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet)` +- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item` +- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item + .spectrum-ActionGroup-item` +- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:first-child` +- `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:last-child` + +**Child elements:** + +- `.spectrum-ActionGroup .spectrum-ActionGroup-item` +- `.spectrum-ActionGroup .spectrum-ActionGroup-item:focus-visible` + +**Justified layout:** + +- `.spectrum-ActionGroup--justified .spectrum-ActionGroup-item` + +**Regular (non-compact, non-vertical) spacing:** + +- `.spectrum-ActionGroup:not(.spectrum-ActionGroup--vertical, .spectrum-ActionGroup--compact) .spectrum-ActionGroup-item` + +
+ +
+Passthroughs + +- `--mod-actionbutton-focus-indicator-border-radius` + +
+ +
+Modifiers + +**Spacing:** + +- `--mod-actiongroup-horizontal-spacing-regular` +- `--mod-actiongroup-horizontal-spacing-compact` +- `--mod-actiongroup-vertical-spacing-regular` +- `--mod-actiongroup-vertical-spacing-compact` +- `--mod-actiongroup-gap-size-compact` + +**Border radius (for compact mode):** + +- `--mod-actiongroup-border-radius` +- `--mod-actiongroup-border-radius-reset` + +**Button spacing reset (for compact mode):** + +- `--mod-actiongroup-button-spacing-reset` + +
+ +### SWC + +
+Attributes + +**Size:** + +- `size` (values: `xs`, `s`, `m`, `l`, `xl`) - group size, no default, propagates to child action buttons + +**Layout:** + +- `vertical` - stacks buttons vertically (boolean) +- `compact` - buttons appear connected with shared borders (boolean) +- `justified` - buttons fill available width equally (boolean) + +**Child action button appearance (propagated to children):** + +- `quiet` - applies quiet styling to all child action buttons (boolean) +- `emphasized` - applies emphasized styling to all child action buttons (boolean) +- `static-color` (values: `white`, `black`) - static color variant, propagates to children + +**Selection management:** + +- `selects` (values: `single`, `multiple`, undefined) - selection mode + - `single`: radio group behavior (single selection) + - `multiple`: checkbox group behavior (multiple selections) + - undefined: no managed selection (individual toggles behavior) +- `selected` - array of selected button values + +**Accessibility:** + +- `label` - accessible label for the group (sets aria-label) + +
+ +
+Slots + +- Default slot - the `sp-action-button` elements that make up the group + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components + +```html + + +``` + +
+ +
+Legacy (CSS main branch) + +```html +
+ + + +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch) + +```html +
+ + + +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**No differences found between main and spectrum-two branches.** + +
+ +### CSS => SWC mapping + +#### Sizes + +| CSS selector | SWC attribute | Status | +| ------------------------------- | -------------- | ----------- | +| `.spectrum-ActionGroup` | Base component | Implemented | +| `.spectrum-ActionGroup--sizeXS` | `size="xs"` | Implemented | +| `.spectrum-ActionGroup--sizeS` | `size="s"` | Implemented | +| `.spectrum-ActionGroup--sizeM` | `size="m"` | Implemented | +| `.spectrum-ActionGroup--sizeL` | `size="l"` | Implemented | +| `.spectrum-ActionGroup--sizeXL` | `size="xl"` | Implemented | + +#### Layout variants + +| CSS selector | SWC attribute | Status | +| ---------------------------------- | ------------- | ----------- | +| `.spectrum-ActionGroup--vertical` | `vertical` | Implemented | +| `.spectrum-ActionGroup--compact` | `compact` | Implemented | +| `.spectrum-ActionGroup--justified` | `justified` | Implemented | + +#### Child elements + +| CSS selector | SWC equivalent | Status | +| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------- | +| `.spectrum-ActionGroup .spectrum-ActionGroup-item` | Default slot / `::slotted(*)` | Implemented | +| `.spectrum-ActionGroup .spectrum-ActionGroup-item:focus-visible` | Browser focus-visible on slotted items | Implemented | +| `.spectrum-ActionGroup--justified .spectrum-ActionGroup-item` | Slotted buttons when `justified` | Implemented | +| `.spectrum-ActionGroup:not(.spectrum-ActionGroup--vertical, .spectrum-ActionGroup--compact) .spectrum-ActionGroup-item` | Slotted buttons in regular mode | Implemented | + +**Note:** In CSS templates, `.spectrum-ActionGroup-item` is applied as a class to each child action button. In SWC, the group uses `::slotted(*)` to style slotted action buttons without adding an additional class. + +#### Compact mode + +| CSS selector | SWC attribute | Status | +| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------- | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet)` | `compact` (when not `quiet`) | Implemented | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item` | Slotted buttons in compact mode | Implemented | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item + .spectrum-ActionGroup-item` | Adjacent buttons in compact mode | Implemented | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item .spectrum-ActionButton-label` | Button labels in compact mode | Implemented | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item.is-selected` | Selected button in compact mode | Implemented | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:first-child` | First button in compact mode | Implemented | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:last-child` | Last button in compact mode | Implemented | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:hover` | Hover state in compact mode | Implemented | +| `.spectrum-ActionGroup--compact:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:focus-visible` | Focus state in compact mode | Implemented | + +#### Compact + vertical mode + +| CSS selector | SWC attribute | Status | +| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------- | +| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet)` | `compact` + `vertical` (when not `quiet`) | Implemented | +| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item` | Slotted buttons in vertical compact mode | Implemented | +| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item + .spectrum-ActionGroup-item` | Adjacent buttons in vertical compact mode | Implemented | +| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:first-child` | First button in vertical compact mode | Implemented | +| `.spectrum-ActionGroup--compact.spectrum-ActionGroup--vertical:not(.spectrum-ActionGroup--quiet) .spectrum-ActionGroup-item:last-child` | Last button in vertical compact mode | Implemented | + +#### WC-only attributes + +| SWC attribute | CSS equivalent | Notes | +| --------------------------------------- | -------------- | ---------------------------------------------------------- | +| `quiet` (propagates to children) | N/A | In CSS, `--quiet` class on container affects child styling | +| `emphasized` (propagates to children) | N/A | Propagates to child action buttons | +| `static-color` (propagates to children) | N/A | Propagates to child action buttons | +| `selects` | N/A | Manages single/multiple selection with automatic ARIA | +| `selected` | N/A | Tracks selected button values | +| `label` | N/A | Sets aria-label on the group | + +## Summary of changes + +### CSS => SWC implementation gaps + +**Missing from WC:** +None. All CSS selectors have corresponding web component implementations. + +### CSS Spectrum 2 changes + +**No structural changes:** +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: + +- A `div` wrapper with `spectrum-ActionGroup` class +- Size classes applied via `--size{size}` modifier pattern +- Layout modifiers for vertical, compact, and justified layouts +- Child action buttons with `spectrum-ActionGroup-item` class + +All spacing, border radius, and layout changes are handled through CSS custom properties without requiring DOM structure changes. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2453) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-action-group--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/actionbuttongroup--docs) diff --git a/migration-roadmap/button-group.md b/migration-roadmap/button-group.md new file mode 100644 index 00000000000..ba3479e74fc --- /dev/null +++ b/migration-roadmap/button-group.md @@ -0,0 +1,134 @@ +# Button Group migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-ButtonGroup` +- `.spectrum-ButtonGroup-item` +- `.spectrum-ButtonGroup.spectrum-ButtonGroup--sizeS` +- `.spectrum-ButtonGroup.spectrum-ButtonGroup--vertical` + +
+ +
+Passthroughs + +None found for this component. + +
+ +
+Modifiers + +- `--mod-buttongroup-flex-wrap` +- `--mod-buttongroup-justify-content` +- `--mod-buttongroup-spacing` +- `--mod-buttongroup-spacing-horizontal` (deprecated in favor of --mod-buttongroup-spacing) +- `--mod-buttongroup-spacing-vertical` (deprecated in favor of --mod-buttongroup-spacing) + +
+ +### SWC + +
+Attributes + +- `vertical` +- `size` (values: `s`, `m`, `l`, `xl`) + +
+ +
+Slots + +- Default slot (the sp-button elements that make up the group) + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components: + +```html + + +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+ + + +
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+ + + +
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +**No differences found between main and spectrum-two branches.** + +
+ +### CSS => SWC mapping + +| CSS selector | Attribute or slot | Status | +| --------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------- | +| `.spectrum-ButtonGroup` | Base component | Implemented | +| `.spectrum-ButtonGroup--sizeS` | `size="s"` | Implemented (there are spacing differences for size small in comparison to the default) | +| `.spectrum-ButtonGroup--vertical` | `vertical` | Implemented | +| `.spectrum-ButtonGroup-item` | Default slot / `::slotted(*)` | Implemented | + +## Summary of changes + +### CSS => SWC implementation gaps + +**Missing from WC:** +None. All CSS selectors have corresponding web component implementations. + +**Missing from CSS:** +None. The web component attributes all map to CSS classes. + +### CSS Spectrum 2 changes + +**No structural changes:** +The Button Group template is identical between the main branch (legacy) and spectrum-two branch (Spectrum 2). Both branches use the same DOM structure with: + +- A `div` wrapper with `spectrum-ButtonGroup` class +- Size classes applied via `--size{size}` modifier pattern +- `--vertical` modifier for vertical layout +- Child buttons with `spectrum-ButtonGroup-item` class + +The component structure remains stable across both versions of Spectrum. + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2457) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-button-group--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/buttongroup--docs) diff --git a/migration-roadmap/button.md b/migration-roadmap/button.md index c50f006d13e..27a403fd2d0 100644 --- a/migration-roadmap/button.md +++ b/migration-roadmap/button.md @@ -1,60 +1,102 @@ # Button migration roadmap +## Component specifications + +### CSS +
CSS selectors +**Base component:** + - `.spectrum-Button` -- `.spectrum-Button .spectrum-Button-label` -- `.spectrum-Button .spectrum-Icon` -- `.spectrum-Button .spectrum-Icon + .spectrum-Button-label` -- `.spectrum-Button .spectrum-ProgressCircle` -- `.spectrum-Button--noWrap .spectrum-Button-label` -- `.spectrum-Button--sizeL` +- `a.spectrum-Button` + +**Sizes:** + - `.spectrum-Button--sizeS` -- `.spectrum-Button--sizeS.spectrum-Button--iconOnly` +- `.spectrum-Button--sizeL` - `.spectrum-Button--sizeXL` -- `.spectrum-Button-label` -- `.spectrum-Button-label:empty` -- `.spectrum-Button.is-disabled` -- `.spectrum-Button.is-focused` -- `.spectrum-Button.is-focused:after` -- `.spectrum-Button.is-pending` -- `.spectrum-Button.is-pending .spectrum-Button-label` -- `.spectrum-Button.is-pending .spectrum-Icon` -- `.spectrum-Button.is-pending .spectrum-ProgressCircle` + +**Variants:** + - `.spectrum-Button.spectrum-Button--accent` -- `.spectrum-Button.spectrum-Button--accent .spectrum-Button-label` -- `.spectrum-Button.spectrum-Button--iconOnly` -- `.spectrum-Button.spectrum-Button--iconOnly .spectrum-Icon` +- `.spectrum-Button.spectrum-Button--primary` +- `.spectrum-Button.spectrum-Button--secondary` - `.spectrum-Button.spectrum-Button--negative` +- `.spectrum-Button.spectrum-Button--staticBlack` +- `.spectrum-Button.spectrum-Button--staticWhite` + +**Treatments:** + - `.spectrum-Button.spectrum-Button--outline` -- `.spectrum-Button.spectrum-Button--primary` + +**Combined variants and treatments:** + - `.spectrum-Button.spectrum-Button--primary.spectrum-Button--outline` -- `.spectrum-Button.spectrum-Button--secondary` - `.spectrum-Button.spectrum-Button--secondary.spectrum-Button--outline` -- `.spectrum-Button.spectrum-Button--staticBlack` - `.spectrum-Button.spectrum-Button--staticBlack.spectrum-Button--outline` - `.spectrum-Button.spectrum-Button--staticBlack.spectrum-Button--secondary` - `.spectrum-Button.spectrum-Button--staticBlack.spectrum-Button--secondary.spectrum-Button--outline` -- `.spectrum-Button.spectrum-Button--staticWhite` - `.spectrum-Button.spectrum-Button--staticWhite.spectrum-Button--outline` - `.spectrum-Button.spectrum-Button--staticWhite.spectrum-Button--secondary` - `.spectrum-Button.spectrum-Button--staticWhite.spectrum-Button--secondary.spectrum-Button--outline` -- `.spectrum-Button::-moz-focus-inner` -- `.spectrum-Button:active` -- `.spectrum-Button:after` + +**Default variant:** + +- `.spectrum-Button:not(.spectrum-Button--primary, .spectrum-Button--negative, .spectrum-Button--secondary, .spectrum-Button--staticBlack, .spectrum-Button--staticWhite)` +- `.spectrum-Button:not(.spectrum-Button--primary, .spectrum-Button--negative, .spectrum-Button--secondary, .spectrum-Button--staticBlack, .spectrum-Button--staticWhite) .spectrum-Button-label` + +**Icon-only:** + +- `.spectrum-Button.spectrum-Button--iconOnly` +- `.spectrum-Button.spectrum-Button--iconOnly .spectrum-Icon` +- `.spectrum-Button--sizeS.spectrum-Button--iconOnly` + +**Text wrapping:** + +- `.spectrum-Button--noWrap .spectrum-Button-label` + +**Child elements:** + +- `.spectrum-Button-label` +- `.spectrum-Button-label:empty` +- `.spectrum-Button .spectrum-Button-label` +- `.spectrum-Button .spectrum-Icon` +- `.spectrum-Button .spectrum-Icon + .spectrum-Button-label` +- `.spectrum-Button .spectrum-ProgressCircle` + +**Variant-specific child elements:** + +- `.spectrum-Button.spectrum-Button--accent .spectrum-Button-label` + +**States:** + +- `.spectrum-Button.is-disabled` +- `.spectrum-Button.is-focused` +- `.spectrum-Button.is-pending` - `.spectrum-Button:disabled` +- `.spectrum-Button:hover` +- `.spectrum-Button:active` - `.spectrum-Button:focus` - `.spectrum-Button:focus-visible` -- `.spectrum-Button:focus-visible:after` -- `.spectrum-Button:hover` -- `.spectrum-Button:not(.spectrum-Button--primary, .spectrum-Button--negative, .spectrum-Button--secondary, .spectrum-Button--staticBlack, .spectrum-Button--staticWhite)` -- `.spectrum-Button:not(.spectrum-Button--primary, .spectrum-Button--negative, .spectrum-Button--secondary, .spectrum-Button--staticBlack, .spectrum-Button--staticWhite) .spectrum-Button-label` + +**State-specific styling:** + +- `.spectrum-Button.is-focused:after` +- `.spectrum-Button.is-pending .spectrum-Button-label` +- `.spectrum-Button.is-pending .spectrum-Icon` +- `.spectrum-Button.is-pending .spectrum-ProgressCircle` - `.spectrum-Button[pending]` - `.spectrum-Button[pending] .spectrum-Button-label` - `.spectrum-Button[pending] .spectrum-Icon` - `.spectrum-Button[pending] .spectrum-ProgressCircle` -- `a.spectrum-Button` +- `.spectrum-Button:focus-visible:after` + +**Focus ring:** + +- `.spectrum-Button:after` +- `.spectrum-Button::-moz-focus-inner`
@@ -68,28 +110,6 @@
-
-Attributes - -- `variant` (String) - The visual variant to apply to this button (`accent`, `primary`, `secondary`, `negative`, `white`, `black`) -- `static-color` (String) - The static color variant to use for this button (`black`, `white`) -- `treatment` (String) - The visual treatment to apply to this button (`fill`, `outline`) -- `pending` (Boolean) - Use this property to set the button into a pending state -- `pending-label` (String) - Label for pending state (default: "Pending") -- `no-wrap` (Boolean) - Disables text wrapping within the button component's label -- `size` (String) - Button size (`s`, `m`, `l`, `xl`) -- `quiet` (Boolean, deprecated) - Style this button to be less obvious (use `treatment="outline"` instead) - -
- -
-Slots - -- Default slot - Text label of the Button -- `icon` - The icon to use for Button - -
-
Modifiers @@ -131,146 +151,277 @@ - `--mod-button-max-inline-size` - `--mod-button-min-width` - `--mod-button-padding-label-to-icon` -- `--mod-button-text-align` -- `--mod-button-text-align-with-icon` - `--mod-button-top-to-icon` - `--mod-button-top-to-text`
-## Visual Comparison +### SWC -**Legacy Component:** +
+Attributes - +**Size:** -**Spectrum 2 Component:** +- `size` (values: `s`, `m`, `l`, `xl`) - +**Variants:** -## DOM Structure Changes +- `variant` (values: `accent`, `primary`, `secondary`, `negative`, `white`, `black`) - defaults to `accent` +- `static-color` (values: `white`, `black`) - static color variant for use over backgrounds -**Legacy (main branch):** +**Treatment:** -```html - -``` +- `treatment` (values: `fill`, `outline`) - defaults to `fill` +- `quiet` - boolean property that maps to `treatment` (when true, sets `treatment="outline"`) -**Spectrum 2 (spectrum-two branch):** +**Content and layout:** -```html - -``` +- `icon-only` - indicates button contains only an icon without visible label +- `no-wrap` - prevents text wrapping within the button label +- `label` - applies `aria-label` for accessibility (especially for icon-only buttons) -## Comparison +**States:** -| CSS selector | Attribute or slot | Status | -| ------------------------------- | ----------------------------- | ---------------- | -| `.spectrum-Button` | Root element | Implemented | -| `.spectrum-Button--accent` | `variant="accent"` | Implemented | -| `.spectrum-Button--primary` | `variant="primary"` | Implemented | -| `.spectrum-Button--secondary` | `variant="secondary"` | Implemented | -| `.spectrum-Button--negative` | `variant="negative"` | Implemented | -| `.spectrum-Button--outline` | `treatment="outline"` | Implemented | -| `.spectrum-Button--sizeS` | `size="s"` | Implemented | -| `.spectrum-Button--sizeL` | `size="l"` | Implemented | -| `.spectrum-Button--sizeXL` | `size="xl"` | Implemented | -| `.spectrum-Button--staticBlack` | `static-color="black"` | Implemented | -| `.spectrum-Button--staticWhite` | `static-color="white"` | Implemented | -| `.spectrum-Button--noWrap` | `no-wrap` attribute | Implemented | -| `.spectrum-Button--iconOnly` | `hideLabel` (internal) | Implemented | -| `.spectrum-Button-label` | Default slot | Implemented | -| `.spectrum-Icon` | `icon` slot | Implemented | -| `.spectrum-ProgressCircle` | `pending` state | Implemented | -| `.spectrum-Button.is-pending` | `pending` attribute | Implemented | -| `.spectrum-Button.is-disabled` | `disabled` attribute | Implemented | -| `.spectrum-Button.is-focused` | Focus state | Implemented | -| `.spectrum-Button[pending]` | `pending` attribute | Implemented | -| `a.spectrum-Button` | Link variant | Missing from WC | -| - | `pending-label` attribute | Missing from CSS | -| - | `quiet` property (deprecated) | Missing from CSS | +- `disabled` - disables the button +- `active` - indicates button is currently being activated (e.g., Space key pressed) +- `pending` - places button in pending state with progress indicator +- `pending-label` - custom label text for pending state -## Key Structural Changes +**Link behavior:** -**Element Hierarchy Changes:** +- `href` - makes button behave as link (inherited from `LikeAnchor`) +- `target` (values: `_blank`, `_parent`, `_self`, `_top`) - where to display the linked URL (inherited from `LikeAnchor`) +- `download` - causes the browser to treat the linked URL as a download (inherited from `LikeAnchor`) +- `referrerpolicy` - how much of the referrer to send when following the link (inherited from `LikeAnchor`) +- `rel` - the relationship of the linked URL as space-separated link types (inherited from `LikeAnchor`) -- No significant hierarchy changes between main and spectrum-two branches -- Maintained consistent structure across versions +**Form behavior:** -**Class Name Changes:** +- `type` (values: `button`, `submit`, `reset`) - button type, defaults to `button` -- No major class name changes -- Static color classes maintained (staticBlack, staticWhite) +**Deprecated variant values:** -**Attribute Changes:** +- `variant="cta"` - deprecated, use `variant="accent"` instead +- `variant="overBackground"` - deprecated, use `static-color="white"` with `treatment="outline"` instead +- `variant="white"` - deprecated, use `static-color="white"` instead +- `variant="black"` - deprecated, use `static-color="black"` instead -- Added `pending` and `pending-label` attributes for loading states -- Added `no-wrap` attribute for text overflow control -- Added `static-color` attribute to replace variant-based static colors -- Added `treatment` attribute to replace `quiet` property +
-**Slot/Content Changes:** +
+Slots -- Added dedicated `icon` slot for icon placement -- Default slot remains for button label +- Default slot (text label of the Button) +- `icon` (The icon to use for Button) -**Migration Impact:** +
-- Static color variants (`white`, `black`) are being deprecated in favor of `static-color` attribute -- `quiet` property is deprecated in favor of `treatment="outline"` -- Better semantic structure with icon slot +## Comparison -### Implementation Gaps +### DOM structure changes -**CSS Features Missing from Web Component:** +
+Spectrum Web Components: -- Link variant support (`a.spectrum-Button`) - web component should support href attribute +```html + + + + + + + + + + +``` -**Web Component Features Missing from CSS:** +
-- `pending-label` attribute support in CSS -- `quiet` property (deprecated) - should be removed +
+Legacy (CSS main branch): -**Features Being Deprecated/Removed:** +```html + +``` -- Link variant support - implement href attribute handling for anchor button functionality +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff + +``` + +
-- Migration from deprecated variants requires updating component usage -- Link button functionality needs implementation for href support -- Migration guidance: Replace `quiet` with `treatment="outline"`, replace static color variants with `static-color` attribute +### CSS => SWC mapping + +#### Sizes + +| CSS selector | Attribute or slot | Status | +| --------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `.spectrum-Button` | Base component (default size M) | Implemented | +| `.spectrum-Button--sizeS` | `size="s"` | Implemented | +| `.spectrum-Button--sizeL` | `size="l"` | Implemented | +| `.spectrum-Button--sizeXL` | `size="xl"` | Implemented | +| `.spectrum-Button--sizeS.spectrum-Button--iconOnly` | `size="s"` with icon only | Implemented (this has a separate selector because the down state implementation is different for this than other sizes) | + +#### Variants and treatments + +| CSS selector | Attribute or slot | Status | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------- | +| `.spectrum-Button--accent` | `variant="accent"` | Implemented | +| `.spectrum-Button--primary` | `variant="primary"` | Implemented | +| `.spectrum-Button--secondary` | `variant="secondary"` | Implemented | +| `.spectrum-Button--negative` | `variant="negative"` | Implemented | +| `.spectrum-Button--staticWhite` | `static-color="white"` | Implemented | +| `.spectrum-Button--staticBlack` | `static-color="black"` | Implemented | +| `.spectrum-Button--outline` | `treatment="outline"` | Implemented | +| `.spectrum-Button--primary.spectrum-Button--outline` | `variant="primary"` `treatment="outline"` | Implemented | +| `.spectrum-Button--secondary.spectrum-Button--outline` | `variant="secondary"` `treatment="outline"` | Implemented | +| `.spectrum-Button--staticBlack.spectrum-Button--outline` | `static-color="black"` `treatment="outline"` | Implemented | +| `.spectrum-Button--staticWhite.spectrum-Button--outline` | `static-color="white"` `treatment="outline"` | Implemented | +| `.spectrum-Button--staticBlack.spectrum-Button--secondary` | `static-color="black"` `variant="secondary"` | Implemented | +| `.spectrum-Button--staticWhite.spectrum-Button--secondary` | `static-color="white"` `variant="secondary"` | Implemented | +| `.spectrum-Button--staticBlack.spectrum-Button--secondary.spectrum-Button--outline` | `static-color="black"` `variant="secondary"` `treatment="outline"` | Implemented | +| `.spectrum-Button--staticWhite.spectrum-Button--secondary.spectrum-Button--outline` | `static-color="white"` `variant="secondary"` `treatment="outline"` | Implemented | +| `.spectrum-Button--accent .spectrum-Button-label` | Accent label styling | Implemented | +| `.spectrum-Button:not(.spectrum-Button--primary, .spectrum-Button--negative, .spectrum-Button--secondary, .spectrum-Button--staticBlack, .spectrum-Button--staticWhite)` | Default variant styling | Implemented | +| `.spectrum-Button:not(.spectrum-Button--primary, .spectrum-Button--negative, .spectrum-Button--secondary, .spectrum-Button--staticBlack, .spectrum-Button--staticWhite) .spectrum-Button-label` | Default label styling | Implemented | + +#### States + +| CSS selector | Attribute or slot | Status | +| ------------------------------ | ----------------- | ----------- | +| `.spectrum-Button.is-disabled` | `disabled` | Implemented | +| `.spectrum-Button:disabled` | `disabled` | Implemented | + +#### Pending state + +**Note:** The progress circle component will change from `ProgressCircle` to `InfieldProgressCircle` in Spectrum 2. + +| CSS selector | Attribute or slot | Status | +| ------------------------------------------------------ | --------------------------- | ----------- | +| `.spectrum-Button.is-pending` | `pending` | Implemented | +| `.spectrum-Button[pending]` | `pending` attribute | Implemented | +| `.spectrum-Button.is-pending .spectrum-Button-label` | Pending state label styling | Implemented | +| `.spectrum-Button.is-pending .spectrum-Icon` | Pending state icon styling | Implemented | +| `.spectrum-Button.is-pending .spectrum-ProgressCircle` | Pending state progress | Implemented | +| `.spectrum-Button[pending] .spectrum-Button-label` | Pending state label | Implemented | +| `.spectrum-Button[pending] .spectrum-Icon` | Pending state icon | Implemented | +| `.spectrum-Button[pending] .spectrum-ProgressCircle` | Pending progress circle | Implemented | + +#### Content and layout + +| CSS selector | Attribute or slot | Status | +| ---------------------------------------------------------- | ----------------------- | ----------- | +| `.spectrum-Button-label` | Default slot | Implemented | +| `.spectrum-Button-label:empty` | Empty label handling | Implemented | +| `.spectrum-Button .spectrum-Icon` | `icon` slot | Implemented | +| `.spectrum-Button .spectrum-Icon + .spectrum-Button-label` | Icon + label spacing | Implemented | +| `.spectrum-Button .spectrum-ProgressCircle` | Rendered when `pending` | Implemented | +| `.spectrum-Button--iconOnly` | Icon slot without label | Implemented | +| `.spectrum-Button--iconOnly .spectrum-Icon` | Icon-only icon styling | Implemented | +| `.spectrum-Button--noWrap` | `no-wrap` | Implemented | +| `.spectrum-Button--noWrap .spectrum-Button-label` | Text wrapping control | Implemented | +| `a.spectrum-Button` | `href` attribute | Implemented | + +#### WC-only attributes (missing from CSS) + +| CSS selector | Attribute or slot | Status | +| ------------ | -------------------------- | -------------------------------------------------- | +| | `quiet` | Missing from CSS (equivalent to outline treatment) | +| | `variant="cta"` | Missing from CSS (deprecated) | +| | `variant="overBackground"` | Missing from CSS (deprecated) | +| | `variant="white"` | Missing from CSS (deprecated) | +| | `variant="black"` | Missing from CSS (deprecated) | + +## Summary of changes + +### CSS => SWC implementation gaps + +**Icon positioning** - CSS templates support an `iconAfterLabel` parameter to position icons after label text (trailing icon). SWC has a fixed DOM order where the icon slot always renders before the label, with no attribute or property to control icon positioning. Note: Icon-after-label is not present in the Spectrum design specifications, though there has been discussion about it within the design team. Check with the design team to confirm whether this feature is still needed. + +**Quiet** - A quiet property can be applied in SWC, but it applies the outline treatment to the button. If the outline treatment alone is sufficient, we might consider removing `quiet`. + +### CSS Spectrum 2 changes + +**Progress indicator component change:** + +- Legacy (main branch) uses `ProgressCircle` component with `size="s"` fixed size +- Spectrum 2 (spectrum-two branch) uses `InfieldProgressCircle` component with dynamic size matching the button size +- `InfieldProgressCircle` has a simpler DOM structure (single fill element instead of complex mask structure) +- Spectrum 2 version passes `staticColor` to the progress indicator for proper theming + +## Resources + +- [CSS migration](https://github.com/adobe/spectrum-css/pull/2600) +- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-button--docs) +- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/button--docs)