|
| 1 | +# Migration guide |
| 2 | + |
| 3 | +When migrating a component from the 1st generation to the 2nd generation, there are a few things to keep in mind. |
| 4 | + |
| 5 | +## Component structure |
| 6 | + |
| 7 | +Components in 1st and 2nd generation share a common base class. These base classes are located in the `second-gen/packages/core/components/` directory. |
| 8 | + |
| 9 | +- 1st generation components are located in the `first-gen/packages/components/` directory. |
| 10 | +- 2nd generation components are located in the `second-gen/packages/swc/components/` directory. |
| 11 | + |
| 12 | +Keep in mind that all the code in the core package is shared between the 1st and 2nd generation components and should avoid any breaking changes being introduced here that could alter the 1st generation API. |
| 13 | + |
| 14 | +Relevant files in the 1st generation components: |
| 15 | + |
| 16 | +- `src/<component-name>-overrides.css` - Theme switching system; do not delete this file, even if it is empty |
| 17 | +- `src/<component-name>.css` - Component styles; this file is used to import the styles from the Spectrum CSS project and the component styles and adds web component-specific styles |
| 18 | +- `src/spectrum-<component-name>.css` - Styles imported and transformed by the build process from the Spectrum CSS project |
| 19 | +- `src/<component-name>.ts` - Component implementation; this contains the attributes and properties for the component as well as the rendering logic |
| 20 | +- `stories/` - Stories |
| 21 | +- `test/` - Tests |
| 22 | +- `README.md` - Component documentation |
| 23 | + |
| 24 | +Relevant files in the 2nd generation components: |
| 25 | + |
| 26 | +- `<component-name>.css` - Component styles; all styles should be added to this file |
| 27 | +- `<component-name>.ts` - Component implementation; this contains the attributes and properties for the component as well as the rendering logic |
| 28 | +- `stories/` - Stories will also serve as the documentation for the component; the story file should be named `<component-name>.stories.ts`. Use JSDoc to document a story in more detail. |
| 29 | +- `test/` - Tests |
| 30 | + |
| 31 | +## Getting started |
| 32 | + |
| 33 | +### Create the base class |
| 34 | + |
| 35 | +If the component folder does not yet exist in the core package, you will need to create it. It might be easiest to copy the existing component file from the 1st generation component and remove the render and styling logic as well as anything that is S1-specific. |
| 36 | + |
| 37 | +For example, if you are migrating the `sp-accordion` component, you can copy the `first-gen/packages/accordion/src/Accordion.ts` to `second-gen/packages/core/components/accordion/Accordion.base.ts` and remove the render and styling logic as well as anything that is S1-specific. |
| 38 | + |
| 39 | +### Implement the component class |
| 40 | + |
| 41 | +Once the base class is created, you can start to implement the component in the `second-gen/packages/swc/components/` directory. The implementation file should be named `<component-name>.ts` and should extend the base class. |
| 42 | + |
| 43 | +```ts |
| 44 | +import { AccordionBase } from '@swc/core/components/accordion'; |
| 45 | + |
| 46 | +export class Accordion extends AccordionBase { |
| 47 | + // ... |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +### Bring over styles from Spectrum CSS |
| 52 | + |
| 53 | +Now we can bring over styles from the `spectrum-two` package in Spectrum CSS. Start by checking out the `@adobe/spectrum-css` repository and pulling down the `spectrum-two` branch. |
| 54 | + |
| 55 | +Identify the component you need to migrate by searching the `components` directory for the component name. |
| 56 | + |
| 57 | +Inside the CSS directory, you can expect to find the following files: |
| 58 | + |
| 59 | +- `index.css` - This is the source of truth for the component Styles |
| 60 | +- `dist/index.css` - This is the processed version of the component styles; for now, this is the best place to source styles for SWC. When copying files from Spectrum CSS into the 2nd-generation component, using this file will ensure you get the benefits of the CSS build tooling. |
| 61 | +- `stories/<component-name>.stories.js` - This is a great source-of-truth for the SWC storybook. These stories are organized into logic groups with API defined in a customer-friendly fashion with typing and human-readable labels. These files also include migration notes and guidance specific to the S2-specific implementation of the component. |
| 62 | +- `stories/template.js` - This is a great source-of-truth for the SWC render function; these templates already include property and class mappings. When bringing this file over to SWC, be sure to remove the `id` and `customStyles` attributes as they do not translate to the web component APIs. |
| 63 | + |
| 64 | +Next, we need to copy the styles from the Spectrum CSS component to the 2nd-generation component. |
| 65 | + |
| 66 | +```bash |
| 67 | +cp -r spectrum-css/components/<component-name>/dist/index.css spectrum-web-components/second-gen/packages/swc/components/<component-name>/<component-name>.css |
| 68 | +``` |
| 69 | + |
| 70 | +### Update styles in the 2nd-generation component |
| 71 | + |
| 72 | +Now that we have the base styles in place, we need to check the first-gen implementation for any unique web component-specific styles that would not exist in the vanilla CSS implementation. This information will most likely be found in the `first-gen/packages/components/<component-name>/<component-name>.css` file. |
| 73 | + |
| 74 | +For example, look for styles specific to slots, such as `::slotted([name="icon"]) {}`. |
| 75 | + |
| 76 | +If these styles are found, we need to confirm if they are needed in the 2nd-generation component. Not all first-gen overrides or component-specific styles are needed in the 2nd-generation components and sometimes there are other ways to source those styles using the original classes provided by the Spectrum CSS asset. |
| 77 | + |
| 78 | +It might be helpful, at this point, to define the render function for the second-gen component so you can spin up Storybook and start seeing these new styles in action. A quick way to kick this off is to copy the `spectrum-css/components/<component-name>/stories/template.js` file into a render function on your new 2nd-generation component. |
| 79 | + |
| 80 | +Let's use the `Badge` component as an example. First, we need to add the styles to the component. |
| 81 | + |
| 82 | +Start by importing the CSS file: |
| 83 | + |
| 84 | +```ts |
| 85 | +import styles from './badge.css'; |
| 86 | +``` |
| 87 | + |
| 88 | +Next, we import those styles into the component: |
| 89 | + |
| 90 | +```ts |
| 91 | +public static override get styles(): CSSResultArray { |
| 92 | + return [styles]; |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +Finally, we can start to implement the render function: |
| 97 | + |
| 98 | +```ts |
| 99 | +protected override render(): TemplateResult { |
| 100 | + return html` |
| 101 | + <div |
| 102 | + class=${classMap({ |
| 103 | + ['spectrum-Badge']: true, |
| 104 | + [`spectrum-Badge--size${this.size?.toUpperCase()}`]: typeof this.size !== 'undefined', |
| 105 | + [`spectrum-Badge--${this.variant}`]: typeof this.variant !== 'undefined', |
| 106 | + [`spectrum-Badge--subtle`]: this.subtle, |
| 107 | + [`spectrum-Badge--outline`]: this.outline, |
| 108 | + [`spectrum-Badge--fixed-${this.fixed}`]: typeof this.fixed !== 'undefined', |
| 109 | + })} |
| 110 | + > |
| 111 | + ${when( |
| 112 | + this.hasIcon, |
| 113 | + () => html` |
| 114 | + <div |
| 115 | + class=${classMap({ |
| 116 | + [`spectrum-Badge-icon`]: true, |
| 117 | + [`spectrum-Badge-icon--no-label`]: |
| 118 | + !this.slotHasContent, |
| 119 | + })} |
| 120 | + > |
| 121 | + <slot name="icon"></slot> |
| 122 | + </div> |
| 123 | + ` |
| 124 | + )} |
| 125 | + <div class="spectrum-Badge-label"> |
| 126 | + <slot></slot> |
| 127 | + </div> |
| 128 | + </div> |
| 129 | + `; |
| 130 | +} |
| 131 | +``` |
| 132 | + |
| 133 | +Let's compare this to the 1st-generation implementation: |
| 134 | + |
| 135 | +```ts |
| 136 | +protected override render(): TemplateResult { |
| 137 | + return html` |
| 138 | + ${this.hasIcon |
| 139 | + ? html` |
| 140 | + <slot |
| 141 | + name="icon" |
| 142 | + ?icon-only=${!this.slotHasContent} |
| 143 | + ></slot> |
| 144 | + ` |
| 145 | + : nothing} |
| 146 | + <div class="label"> |
| 147 | + <slot></slot> |
| 148 | + </div> |
| 149 | + `; |
| 150 | +} |
| 151 | +``` |
| 152 | + |
| 153 | +As you can see, the 2nd-generation implementation leverages the `classMap` function to conditionally apply classes to the component based on the component's properties. This is a common pattern in the 2nd-generation components. This approach has several benefits: |
| 154 | + |
| 155 | +- It separates the styling application from the properties and states of the component |
| 156 | +- It creates a container inside the Shadow DOM which provides stronger encapsulation |
| 157 | +- It allows for more efficient rendering by only applying the necessary classes to the component |
| 158 | + |
| 159 | +In our 2nd-generation version, we will likely want to maintain any slots available in the 1st-generation component unless design changes from S2 provide a compelling reason to change or remove them. |
| 160 | + |
| 161 | +Once your render function is in place, you can spin up Storybook and start seeing these new styles in action. |
| 162 | + |
| 163 | +```bash |
| 164 | +yarn workspace @swc/components storybook |
| 165 | +``` |
| 166 | + |
| 167 | +_Note_: Run all commands provided in this guide from the root of the Spectrum Web Components monorepo. |
| 168 | + |
| 169 | +_Tip_: If you want to run S1 Storybook alongside S2 Storybook, you can use the following command: |
| 170 | + |
| 171 | +```bash |
| 172 | +yarn start |
| 173 | +``` |
| 174 | + |
| 175 | +## Implementing the API |
| 176 | + |
| 177 | +Now that we have the base styles and render function in place, we can start to adjust styling and API to match the 2nd-generation design language. |
| 178 | + |
| 179 | +Start by determining what display property your component's host should use. All components should have at least the following style added to the top of their 2nd-generation CSS. |
| 180 | + |
| 181 | +```css |
| 182 | +:host { |
| 183 | + display: inline-flex; |
| 184 | +} |
| 185 | +``` |
| 186 | + |
| 187 | +Use the `display` property most aligned with the component's semantic role or purpose in the document. |
| 188 | + |
| 189 | +### Properties |
| 190 | + |
| 191 | +The 2nd-generation components may have changes to the properties and attributes of the component. These changes are typically due to design changes from S2 or to align with the 2nd-generation design language. |
| 192 | + |
| 193 | +There are several resources you can use to help you understand the design changes from S2. |
| 194 | + |
| 195 | +- [Migration roadmap](https://github.com/adobe/spectrum-web-components/tree/2nd-gen-component-analysis/migration-roadmap) - SWC branch name: `2nd-gen-component-analysis` |
| 196 | +- [S2 design assets](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Desktop?m=auto) - Figma file |
| 197 | + |
| 198 | +You can also use the `CHANGELOG.md` file in the Spectrum CSS repository to see the migration notes for the component. |
| 199 | + |
| 200 | +```bash |
| 201 | +cat spectrum-css/components/<component-name>/CHANGELOG.md |
| 202 | +``` |
0 commit comments