-
Notifications
You must be signed in to change notification settings - Fork 205
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
55dbbf9
commit 47ebc1e
Showing
1 changed file
with
189 additions
and
0 deletions.
There are no files selected for viewing
189 changes: 189 additions & 0 deletions
189
projects/documentation/content/migrations/2024-10-01 (1.0.0).md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| --- | ||
| layout: guide.njk | ||
| title: 'Migration Guide: Spectrum Web Components (v1.0.0)' | ||
| displayName: 2024/10/01 (v1.0.0) | ||
| slug: migration-guide | ||
| --- | ||
|
|
||
| ## Migration: 2024/10/01 (v1.0.0) | ||
|
|
||
| With the release of Spectrum Web Components version 1.0.0, we removed previously deprecated components and features. | ||
| Starting with this version, Spectrum Web Components adheres to [semantic versioning (semver)](https://semver.org/), ensuring that any future breaking changes will be introduced only in major version updates. These changes will be communicated in advance, allowing developers to prepare and avoid disruption to existing applications. Patch releases, as part of this versioning approach, will be non-breaking and focus on fixes and minor improvements. | ||
|
|
||
| If you're upgrading from an earlier version, please review the following changes carefully to ensure your project remains compatible. | ||
|
|
||
| ## Removed Components and Features | ||
|
|
||
| ### 1. Banner (`sp-banner`) | ||
|
|
||
| The `sp-banner` component has been removed. | ||
|
|
||
| **Action Required**: If you are using `sp-banner`, remove it from your application and replace it with the [alert banner](/components/alert-banner/) component to show pressing and high-signal messages, such as system alerts. | ||
|
|
||
| ### 2. Quick actions (`sp-quick-actions`) | ||
|
|
||
| The `sp-quick-actions` component has been removed. | ||
| **Action Required**: If you are using `sp-quick-actions`, remove it from your application and replace it with the [action bar](/components/alert-banner/) component to allow users to perform actions on either a single or multiple items at the same time. | ||
|
|
||
| ### 3. Split button (`sp-split-button`) | ||
|
|
||
| The `sp-split-button` component has been removed. | ||
| **Action Required**: If you are using `sp-split-button`, remove it from your application and replace it with the [button group](/components/button-group/) component to to show any additional actions related to the most critical action. | ||
|
|
||
| ### 4. Action button (`sp-action-button`) | ||
|
|
||
| The `variant` attribute for `sp-action-button` has been removed. | ||
| **Action Required**: If your application uses the `variant` attribute, replace it with the `staticColor` attribute while keeping the same values. See the example below: | ||
|
|
||
| ```ts | ||
| // Before | ||
| <sp-action-button variant="black"></sp-action-button> | ||
|
|
||
| // After | ||
| <sp-action-button staticColor="black"></sp-action-button> | ||
| ``` | ||
|
|
||
| ### 5. Badge (`sp-badge`) | ||
|
|
||
| The following deprecated fixed values for the `position` attribute on `sp-badge` have been removed: `top`, `bottom`, `left`, `right`. | ||
|
|
||
| **Action Required**: Replace these fixed values with their logical equivalents: | ||
|
|
||
| - `top` → `block-start` | ||
| - `bottom` → `block-end` | ||
| - `left` → `inline-start` | ||
| - `right` → `inline-end` | ||
|
|
||
| ### 6. Button (`sp-button`) | ||
|
|
||
| Several deprecated values for the `variant` attribute on `sp-button` have been removed, including: | ||
|
|
||
| - `black` and `white`: Use `staticColor="black"` or `staticColor="white"` instead. | ||
| - `overBackground`: Use `staticColor="white"` with `treatment="outline"` instead. | ||
| - `cta`: Use `variant="accent"` instead. | ||
|
|
||
| **Action Required**: Update all instances where you use the above `variant` attributes on `sp-button`. See the examples below: | ||
|
|
||
| #### `black` and `white` | ||
|
|
||
| ```ts | ||
| // Before (black and white) | ||
| <sp-button variant="black"></sp-button> | ||
|
|
||
| // After (black and white) | ||
| <sp-button staticColor="black"></sp-button> | ||
| ``` | ||
|
|
||
| #### `overBackground` | ||
|
|
||
| ```ts | ||
| // Before (overBackground) | ||
| <sp-button variant="overBackground"></sp-button> | ||
|
|
||
| // After (overBackground) | ||
| <sp-button staticColor="white" treatment="outline"></sp-button> | ||
| ``` | ||
|
|
||
| #### `cta` | ||
|
|
||
| ```ts | ||
| // Before (cta) | ||
| <sp-button variant="cta"></sp-button> | ||
|
|
||
| // After (cta) | ||
| <sp-button variant="accent"></sp-button> | ||
| ``` | ||
|
|
||
| ### 7. Coach Indicator (`sp-coach-indicator`) | ||
|
|
||
| The `variant` attribute for `sp-coach-indicator` has been removed. | ||
|
|
||
| **Action Required**: Replace the `variant` attribute with the `staticColor` attribute, using the same values. See the example below: | ||
|
|
||
| ```ts | ||
| // Before | ||
| <sp-coach-indicator variant="black"></sp-coach-indicator> | ||
|
|
||
| // After | ||
| <sp-coach-indicator staticColor="black"></sp-coach-indicator> | ||
| ``` | ||
|
|
||
| Ensure that all instances of `sp-coach-indicator` in your codebase are updated accordingly. | ||
|
|
||
| ### 8. Popover (`sp-popover`) | ||
|
|
||
| The `dialog` attribute for `sp-popover` has been removed. | ||
|
|
||
| **Action Required**: Instead of using the `dialog` attribute, slot an `<sp-dialog>` element into the `sp-popover` component. See the example below: | ||
|
|
||
| ```ts | ||
| // Before | ||
| <sp-popover dialog></sp-popover> | ||
|
|
||
| // After | ||
| <sp-popover> | ||
| <sp-dialog></sp-dialog> | ||
| </sp-popover> | ||
| ``` | ||
|
|
||
| Ensure that all instances of `sp-popover` using the `dialog` attribute are updated to this new structure. | ||
|
|
||
| ### 9. Progress Circle (`sp-progress-circle`) | ||
|
|
||
| The `overBackground` property for `sp-progress-circle` has been removed. | ||
|
|
||
| **Action Required**: Replace the `overBackground` property with the `staticColor="white"` attribute. See the example below: | ||
|
|
||
| ```ts | ||
| // Before | ||
| <sp-progress-circle overBackground></sp-progress-circle> | ||
|
|
||
| // After | ||
| <sp-progress-circle staticColor="white"></sp-progress-circle> | ||
| ``` | ||
|
|
||
| Make sure to update all instances of `sp-progress-circle` where `overBackground` is used. | ||
|
|
||
| ### 10. Theme (`sp-theme`) | ||
|
|
||
| The `theme` attribute for `sp-theme` has been removed. | ||
|
|
||
| **Action Required**: Replace the `theme` attribute with the `system` attribute. This is a drop-in replacement. See the example below: | ||
|
|
||
| ```ts | ||
| // Before | ||
| <sp-theme theme="light"></sp-theme> | ||
|
|
||
| // After | ||
| <sp-theme system="light"></sp-theme> | ||
| ``` | ||
|
|
||
| Ensure that all instances of the `theme` attribute in your application are updated to use `system` instead. | ||
|
|
||
| ### 11. Thumbnail (`sp-thumbnail`) | ||
|
|
||
| The following deprecated size values for `sp-thumbnail` have been removed: `xxs`, `xs`, `s`, `m`, `l`. | ||
|
|
||
| **Action Required**: Replace these deprecated sizes with their corresponding numeric values: | ||
|
|
||
| - `xxs` → `100` | ||
| - `xs` → `300` | ||
| - `s` → `500` | ||
| - `m` → `700` | ||
| - `l` → `900` | ||
|
|
||
| See the example below for the migration: | ||
|
|
||
| ```ts | ||
| // Before | ||
| <sp-thumbnail size="xs"></sp-thumbnail> | ||
|
|
||
| // After | ||
| <sp-thumbnail size="300"></sp-thumbnail> | ||
| ``` | ||
|
|
||
| Make sure to update all instances of `sp-thumbnail` using the deprecated `size` values. | ||
|
|
||
| ## Final Notes | ||
|
|
||
| Please ensure your project is fully compatible with Spectrum Web Components 1.0.0 before upgrading. Test thoroughly and review any deprecated or removed functionality as outlined above. If you encounter any issues during migration, consult the documentation or reach out for support. |