diff --git a/migration-roadmap/README.md b/migration-roadmap/README.md new file mode 100644 index 0000000000..79f134db49 --- /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/alert-banner.md b/migration-roadmap/alert-banner.md new file mode 100644 index 0000000000..f78e1b34de --- /dev/null +++ b/migration-roadmap/alert-banner.md @@ -0,0 +1,282 @@ +# Alert Banner migration roadmap + +## Component specifications + +### CSS + +
+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` + +
+ +
+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` + +
+ +### 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` + +
+ +
+Slots + +- Default slot - The alert banner text context +- `action` - Slot for the button element that surfaces the contextual action a user can take + +
+ +## Comparison + +### DOM structure changes + +
+Spectrum Web Components: + +```html + + #shadow-root + +
+ +
+ +``` + +
+ +
+Legacy (CSS main branch): + +```html +
+
+
+ +

+ Your trial will expire in 3 days +

+
+ +
+
+
+ +
+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html +
+
+
+ +

+ Your trial will expire in 3 days +

+
+ +
+
+ +
+
+``` + +
+ +
+Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two) + +```diff +
+-
+ +
+``` + +
+ +### CSS => SWC mapping + +| 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 | + +Note: the `neutral` variant of Alert banner is the default variant in both CSS and SWC. + +## Summary of changes + +### CSS => SWC implementation gaps + +**No missing features.** All CSS selectors have corresponding web component implementations: + +- **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 + +### CSS Spectrum 2 changes + +**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. + +This divider does not appear to be present in SWC, and therefore will not need to be removed for Spectrum 2. + +## Resources + +- [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/alert-dialog.md b/migration-roadmap/alert-dialog.md new file mode 100644 index 0000000000..1a21508961 --- /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/asset.md b/migration-roadmap/asset.md new file mode 100644 index 0000000000..393dab00bb --- /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/avatar.md b/migration-roadmap/avatar.md new file mode 100644 index 0000000000..e39fe2dc90 --- /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/badge.md b/migration-roadmap/badge.md new file mode 100644 index 0000000000..3acc770461 --- /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/breadcrumbs.md b/migration-roadmap/breadcrumbs.md new file mode 100644 index 0000000000..5fd94f1446 --- /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 0000000000..c50f006d13 --- /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/checkbox.md b/migration-roadmap/checkbox.md new file mode 100644 index 0000000000..2c8bf21803 --- /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/color-field.md b/migration-roadmap/color-field.md new file mode 100644 index 0000000000..5ad6c3473b --- /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/cursor_prompt.md b/migration-roadmap/cursor_prompt.md new file mode 100644 index 0000000000..2597f15fd0 --- /dev/null +++ b/migration-roadmap/cursor_prompt.md @@ -0,0 +1,242 @@ +# Spectrum Migration Documentation Prompt + +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: + +**IMPORTANT**: All files must be created on the original spectrum-web-components branch where the session started. + +## File Organization + +- **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 + +- Create a Level 1 heading (`#`) with the format: `# [Component name] migration roadmap` +- Example: `# Alert Banner migration roadmap` + +### 1. Component Specifications + +Create a Level 2 Heading: `## Component specifications` + +Within this heading, we'll have a Level 3 heading for CSS (`### CSS`) and one for Spectrum web components (`### SWC`). + +#### 1.1 CSS Section + +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 + +**Passthroughs Section:** + +- Title: "Passthroughs" +- Extract all passthroughs from metadata.json + +**Modifiers Section:** + +- Title: "Modifiers" +- Extract all modifiers from metadata.json + +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`: + +**Required source**: `packages/[component-name]/src/[component-name].ts` (analyze the `render()` method) + +**Attributes Section:** + +- Title: "Attributes" +- Look for `@property` decorators in TypeScript +- For string properties with enumerated values, extract each value as a separate attribute entry + +**Slots Section:** + +- Title: "Slots" +- Look for `` patterns in render method + +If any of these sections are empty, write for that section only, "None found for this component." + +### 2. Comparison + +Create a Level 2 Heading: `## Comparison` + +#### 2.1 DOM Structure Changes + +**Critical Instruction**: Analyze files from THREE different sources. Always confirm the branch and repository being used. + +**2.1.1 Web Component DOM Structure Analysis**: + +- **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 + +**2.1.2 CSS DOM Structure Analysis**: + +**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 +``` + +- **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 +- **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 three-way HTML comparison using markdown code blocks. Use collapsible sections using `
` and `` under `### DOM Structure changes` for each category: + +````markdown +
+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) + +```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. + +
+```` + +#### 2.2 CSS => SWC mapping + +Create a markdown table with these exact column headers: + +- Column 1: "CSS selector" +- Column 2: "Attribute or slot" +- Column 3: "Status" + +**Status Values (use exactly as written):** + +- "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 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:** + +```markdown +.spectrum-Search:lang(ja), .spectrum-Search:lang(ko), .spectrum-Search:lang(zh) | Language-specific styling | Implemented +``` + +**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) + +### 3. Summary of changes + +Create a Level 2 Heading: `## Summary of changes` + +After the comparison table, create a new section that provide a focused summary of changes that will impact SWC engineers: + +#### CSS => SWC implementation gaps + +Summarize changes in **CSS => SWC mapping** section above. Note any statuses that are missing, and whether they are missing from WC or CSS. + +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. + +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. + +#### CSS Spectrum 2 changes + +Analyze the differences between CSS `main` and CSS `spectrum-two` branches surfaced in the DOM structure comparison and document them in this section: + +- **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. + +Be sure to note: + +- 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 + +### 4. Resources section + +Create a Level 2 Heading: `## Resources` + +Under this heading, add a placeholder section for resources with a bulleted list that can be filled in: + +```markdown +- [CSS migration]() +- [Spectrum 2 preview]() +- [React]() +``` + +## Output format notes + +- 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 +- 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 0000000000..3cff247bf5 --- /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/dropzone.md b/migration-roadmap/dropzone.md new file mode 100644 index 0000000000..4dae7732b9 --- /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/field-group.md b/migration-roadmap/field-group.md new file mode 100644 index 0000000000..8a1214cc74 --- /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/field-label.md b/migration-roadmap/field-label.md new file mode 100644 index 0000000000..04c8301f3d --- /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 0000000000..d510146509 --- /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/illustrated-message.md b/migration-roadmap/illustrated-message.md new file mode 100644 index 0000000000..ab0c58097d --- /dev/null +++ b/migration-roadmap/illustrated-message.md @@ -0,0 +1,283 @@ +# Illustrated message migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +- `.spectrum-IllustratedMessage` + +**Variants:** + +- `.spectrum-IllustratedMessage--horizontal` +- `.spectrum-IllustratedMessage--sizeL` +- `.spectrum-IllustratedMessage--sizeS` + +**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)` + +
+ +
+Passthroughs + +- `--mod-buttongroup-justify-content` + +
+ +
+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` + +
+ +### SWC + +
+Attributes + +- `heading` (String) - Title text for the message +- `description` (String) - Description text for the message + +
+ +
+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 + +
+Spectrum Web Components: + +```html +
+ + + +
+

+ [heading] +

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

+ Heading text +

+

+ Description text and other content (like links) +

+
+``` + +
+ +
+Spectrum 2 (CSS spectrum-two branch): + +```html + +
+ + + +
+

Heading text

+

+ Description text and other content (like links) +

+ +
+ + +
+
+
+``` + +
+ +
+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) ++

++
++ ++ ++
++
+
+``` + +### Key Changes in HTML Structure + +1. **Size class addition**: Added t-shirt sizing classes to the root element for explicit size control. + +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. + +3. **Content wrapper**: Added `.spectrum-IllustratedMessage-content` container to group text content and actions separate from the illustration. + +4. **Typography simplification**: Removed Spectrum typography classes (`spectrum-Heading`, `spectrum-Body`) from heading and description elements, using semantic HTML with component-specific classes instead. + +5. **Actions container**: Introduced `.spectrum-IllustratedMessage-actions` container with button group support for interactive elements. + +6. **Horizontal orientation**: Added `.spectrum-IllustratedMessage--horizontal` modifier class that introduces the new horizontal layout variant. + +
+ +### CSS => SWC mapping + +| 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) | + +## Summary of changes + +### CSS => SWC implementation gaps + +- **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. + +- **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. + +- **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. + +- **Built-in actions**: No built-in support yet for button group, which were introduced in S2. + +### CSS Spectrum 2 changes + +- **Unified illustration design**: Upgraded the SVG illustration to something that better represents modern Spectrum design language. + +- **Enhanced content structure**: Added `.spectrum-IllustratedMessage-content` wrapper to group text content separate from illustration, improving layout flexibility. + +- **Actions integration**: Introduced `.spectrum-IllustratedMessage-actions` container with built-in button group support for common interactive scenarios. This element is optional. + +- **Size system enhancement**: Expanded size variants. + +- **Improved SVG handling**: Enhanced SVG illustration with better accessibility attributes and rendering optimization. + +## Resources + +- [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/infield-button.md b/migration-roadmap/infield-button.md new file mode 100644 index 0000000000..c917f97785 --- /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 0000000000..723c301028 --- /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/meter.md b/migration-roadmap/meter.md new file mode 100644 index 0000000000..d841a89b82 --- /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/number-field.md b/migration-roadmap/number-field.md new file mode 100644 index 0000000000..eb25f83a63 --- /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/opacity-checkerboard.md b/migration-roadmap/opacity-checkerboard.md new file mode 100644 index 0000000000..761e1af8e3 --- /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/picker-button.md b/migration-roadmap/picker-button.md new file mode 100644 index 0000000000..7996283f41 --- /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) diff --git a/migration-roadmap/progress-bar.md b/migration-roadmap/progress-bar.md new file mode 100644 index 0000000000..ca6bdf2022 --- /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/progress-circle.md b/migration-roadmap/progress-circle.md new file mode 100644 index 0000000000..002eef0bb9 --- /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/radio.md b/migration-roadmap/radio.md new file mode 100644 index 0000000000..d352a8188a --- /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/search.md b/migration-roadmap/search.md new file mode 100644 index 0000000000..5e920467f6 --- /dev/null +++ b/migration-roadmap/search.md @@ -0,0 +1,505 @@ +# Search migration roadmap + +## Component specifications + +### CSS + +
+CSS selectors + +**Base component:** + +- `.spectrum-Search` +- `.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` + +**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` + +
+ +
+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` + +
+ +
+Modifiers (Deprecated) + +- `--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` + +
+ +### SWC + +
+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:** + +- `size` - Size of the search 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 + +
+
+ + +
+ + + +
+ +
+
+ + + +``` + +
+ +
+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 @@ +- +- ++ +
+ +
+ ++ ++ ++ +``` + +
+ +### CSS => SWC mapping + +| 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) | + +## Summary of changes + +### CSS => SWC implementation gaps + +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`. + +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.** + +### CSS Spectrum 2 changes + +The most notable changes seen in Spectrum 2 migration work include: + +- **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 + +## Resources + +- [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/slider.md b/migration-roadmap/slider.md new file mode 100644 index 0000000000..898a460cd6 --- /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) diff --git a/migration-roadmap/status-light.md b/migration-roadmap/status-light.md new file mode 100644 index 0000000000..da380bd0ea --- /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) diff --git a/migration-roadmap/swatch-group.md b/migration-roadmap/swatch-group.md new file mode 100644 index 0000000000..34b2b8e4b4 --- /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 0000000000..994a190844 --- /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/switch.md b/migration-roadmap/switch.md new file mode 100644 index 0000000000..1acd2ca847 --- /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) diff --git a/migration-roadmap/textfield.md b/migration-roadmap/textfield.md new file mode 100644 index 0000000000..ba0cf5d39a --- /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) diff --git a/migration-roadmap/thumbnail.md b/migration-roadmap/thumbnail.md new file mode 100644 index 0000000000..17e36916cb --- /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)