You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
implementations contain very little code. The CSS from the `spectrum-css`
16
-
project typically specifies most, if not all, of the presentation details.
17
-
18
13
## What is a web component?
19
14
20
15
According to <sp-linkhref="https://www.webcomponents.org/introduction">webcomponents.org</sp-link>,
@@ -29,7 +24,6 @@ web components are:
29
24
In order to add a new component to this library, you will need to develop a
30
25
working knowledge of the following technologies:
31
26
32
-
- <sp-linkhref="https://github.com/adobe/spectrum-css">Spectrum CSS</sp-link>: A CSS implementation of the Spectrum design language
33
27
- <sp-linkhref="https://developers.google.com/web/fundamentals/web-components/customelements">Web Components</sp-link>: Standards based method for adding new HTML tags to a browser
34
28
- <sp-linkhref="https://developers.google.com/web/fundamentals/web-components/shadowdom">Shadow DOM</sp-link>: The part of the Web Component spec that allows for encapsulation of component styles and child nodes
35
29
- <sp-linkhref="https://lit-element.polymer-project.org/guide">lit-element</sp-link>: A simple base class for creating fast, lightweight web components
@@ -45,81 +39,7 @@ the heart of a web component. It isolates the component from the styles and DOM
45
39
of the containing page. While this offers many benefits, it also means that we
46
40
must structure our CSS very differently.
47
41
48
-
The CSS from the <sp-linkhref="https://github.com/adobe/spectrum-css">spectrum-css</sp-link> project
49
-
is intended to be installed globally on a web page. Using it in the context of a
50
-
web component requires that we modify it. To facilitate that, this project comes
51
-
with a <sp-linkhref="https://github.com/adobe/spectrum-web-components/blob/master/tasks/process-spectrum.js">config-driven processor</sp-link> that can transform the Spectrum CSS into a format
52
-
that can be consumed in a web component.
53
-
54
-
The first step is to create a directory and a `spectrum-config.js` file for your
55
-
new component. This config file contains information about the structure of
56
-
the web component in relation to the Spectrum CSS classes.
57
-
58
-
Below is a fragment of the <sp-linkhref="https://github.com/adobe/spectrum-web-components/blob/master/src/button/spectrum-config.js">`spectrum-config.js` file for `sp-button`</sp-link>.
If we wanted to create a button component using this config file, the steps would be as
111
-
follows:
112
-
113
-
1. Make the directory <sp-linkhref="https://github.com/adobe/spectrum-web-components/tree/master/src/button">`src/components/button`</sp-link>
114
-
2. In that new directory, create a <sp-linkhref="https://github.com/adobe/spectrum-web-components/blob/main/packages/button/src/spectrum-config.js">`spectrum-config.js`</sp-link>
115
-
file with the above contents
116
-
3. Run the command `yarn process-spectrum` to create the <sp-linkhref="https://github.com/adobe/spectrum-web-components/blob/main/packages/button/src/spectrum-button.css">CSS file</sp-link>
117
-
118
-
When you do the above, the <sp-linkhref="https://github.com/adobe/spectrum-web-components/blob/main/scripts/process-spectrum-postcss-plugin.js">config-driven processor</sp-link>
119
-
will look in the <sp-linkhref="https://github.com/adobe/spectrum-css">`spectrum-css`</sp-link> project
120
-
for the <sp-linkhref="https://unpkg.com/@spectrum-css/button/dist/index-vars.css">matching CSS file</sp-link>.
121
-
It will parse that file and restructure the CSS as per the configuration
122
-
instructions.
42
+
For more information on how to structure your CSS, see the [Styling](/guides/styling-components) guide.
123
43
124
44
## Structure of a Spectrum Web Component
125
45
@@ -143,214 +63,6 @@ structure that looks like this.
143
63
If anything here looks unfamiliar, it is probably a good time to do some reading
144
64
about <sp-link href="https://developers.google.com/web/fundamentals/web-components/customelements">web components</sp-link>.
145
65
146
-
You can compare this markup with the <sp-link href="http://opensource.adobe.com/spectrum-css/2.13.0/docs/#button---cta">reference markup in the `spectrum-css` documentation</sp-link>
147
-
148
-
### Host Class Mapping
149
-
150
-
We need to determine what the main CSS class is forour componentin the
151
-
original `spectrum-css`. In the case of `sp-button`, we can see that the
152
-
top-level class is `.Spectrum-Button`. We then need to determine where we want
153
-
that CSS to be applied. In many cases, you will want that CSS to be applied to
154
-
the actual web component via the `:host` selector. That is the default behaviour
155
-
of the conversion script. In this case, we wanted to preserve all of the default
156
-
behaviour of the `button` element in HTML. So, we want the main CSS to be
157
-
applied to our `<button>` instead. If you look at the <sp-link href="https://github.com/adobe/spectrum-web-components/blob/main/packages/button/src/spectrum-config.js">`host` definition in
158
-
`spectrum-config.js`</sp-link>
159
-
you can see that we have supplied a `shadowSelector` option. That tells the
160
-
script to move all of the CSS for `.Spectrum-Button` to the `#button` element in
161
-
the shadow DOM.
162
-
163
-
```javascript
164
-
host: {
165
-
selector: '.spectrum-Button',
166
-
shadowSelector: '#button',
167
-
},
168
-
```
169
-
170
-
### Shadow DOM Structure
171
-
172
-
The next step is to fill out the remaining structure of the shadow DOM portion
173
-
of the component. Note that, in the shadow DOM, we are using ids instead of long
174
-
class names. We can do that because the namespace of each instance of our web
175
-
component has it's own DOM scope. So, there can never be an id name collision.
176
-
177
-
Typically, you will reference the <sp-link href="http://opensource.adobe.com/spectrum-css/2.13.0/docs/#checkbox">sample code from the
178
-
`spectrum-css`</sp-link>
179
-
documentation and <sp-link href="https://github.com/adobe/spectrum-web-components/blob/main/packages/checkbox/src/Checkbox.ts">recreate that structure in the shadow DOM of your
180
-
component</sp-link>.
181
-
182
-
In the case of `sp-checkbox`, we turn this sample DOM code:
into this code in our component's render method (actually implementation is
200
-
slightly different):
201
-
202
-
```javascript
203
-
return html`
204
-
<label id="root">
205
-
<input
206
-
id="input"
207
-
type="checkbox"
208
-
?checked=${this.checked}
209
-
@change=${this.handleChange}
210
-
<span id="box">
211
-
<sp-icon
212
-
id="checkmark"
213
-
size="s"
214
-
name="ui:CheckmarkSmall"
215
-
aria-hidden="true"
216
-
></sp-icon>
217
-
<sp-icon
218
-
id="partialCheckmark"
219
-
size="s"
220
-
name="ui:DashSmall"
221
-
aria-hidden="true"
222
-
></sp-icon>
223
-
</span>
224
-
<span id="label"><slot></slot></span>
225
-
</label>
226
-
`;
227
-
```
228
-
229
-
You will notice that many of the `spectrum-css` classes are mapped to ids in the
230
-
web component. For example, `.spectrum-Checkbox-input` and
231
-
`.spectrum-Checkbox-box` become `#input` and `#box`. Those transformations are
232
-
described in the <sp-link href="https://github.com/adobe/spectrum-web-components/blob/main/packages/checkbox/src/spectrum-config.js">`ids` section of the `spectrum-config.js`
233
-
file</sp-link>.
234
-
235
-
```javascript
236
-
ids: [
237
-
{
238
-
selector: '.spectrum-Checkbox-input',
239
-
name: 'input',
240
-
},
241
-
{
242
-
selector: '.spectrum-Checkbox-box',
243
-
name: 'box',
244
-
},
245
-
{
246
-
selector: '.spectrum-Checkbox-checkmark',
247
-
name: 'checkmark',
248
-
},
249
-
{
250
-
selector: '.spectrum-Checkbox-partialCheckmark',
251
-
name: 'partialCheckmark',
252
-
},
253
-
{
254
-
selector: '.spectrum-Checkbox-label',
255
-
name: 'label',
256
-
},
257
-
],
258
-
```
259
-
260
-
### Properties and Attributes
261
-
262
-
Most of our controls have options that affect how they are rendered. For
263
-
example, Spectrum supports a number of different kinds of buttons (e.g primary,
264
-
secondary or call-to-action). `spectrum-css` supports these visual styles using
265
-
CSS classes. In web components, we typically support these options using
266
-
attributes/properties on the component. For example, here is a call-to-action
267
-
style button.
268
-
269
-
```html
270
-
<sp-button variant="accent">CTA</sp-button>
271
-
```
272
-
273
-
We could conditionally add CSS classes to the elements of the shadow DOM during
274
-
rendering, but it is much easier to just let the attributes on the DOM node
275
-
drive the styling directly. In order to facilitate that, the
276
-
<sp-link href="https://github.com/adobe/spectrum-web-components/blob/main/packages/button/src/spectrum-config.js">`spectrum-config.js` file lets you specify how to map the various
277
-
`spectrum-css` classes to CSS that is based on the attributes on the `:host` of
278
-
the web
279
-
component</sp-link>.
280
-
281
-
```javascript
282
-
attributes: [
283
-
{
284
-
type: 'boolean',
285
-
selector: '.spectrum-Button--quiet',
286
-
},
287
-
{
288
-
type: 'boolean',
289
-
selector: ':disabled',
290
-
},
291
-
{
292
-
type: 'enum',
293
-
name: 'variant',
294
-
values: [
295
-
'.spectrum-Button--cta',
296
-
'.spectrum-Button--primary',
297
-
'.spectrum-Button--secondary',
298
-
{
299
-
name: 'negative',
300
-
selector: '.spectrum-Button--warning',
301
-
},
302
-
'.spectrum-Button--overBackground',
303
-
'.spectrum-Button--secondary',
304
-
],
305
-
},
306
-
],
307
-
```
308
-
309
-
We support two different kinds of attributes, booleans and enums. Booleans are
310
-
turned on or off by the presence or absence of the attribute. Enum attributes
311
-
must be set to one of the allowed values. The <sp-link href="https://github.com/adobe/spectrum-web-components/blob/main/packages/button/src/spectrum-button.css">CSS generated will reference the
312
-
attributes on the `host:` element
313
-
directly</sp-link>.
314
-
315
-
### Class to Class Mapping
316
-
317
-
In some cases, you will need to retain the `spectrum-css` classes as classes. An
318
-
example of that is when you need to apply CSS rules to multiple items in the
319
-
shadow DOM. In that case, we simply map class names to shorter classnames. There
320
-
is an <sp-link href="https://github.com/adobe/spectrum-web-components/blob/main/packages/slider/src/spectrum-config.js">example of remapping classes in the slider
321
-
component</sp-link>.
322
-
323
-
```javascript
324
-
classes: [
325
-
{
326
-
selector: '.spectrum-Slider-track',
327
-
name: 'track',
328
-
},
329
-
],
330
-
```
331
-
332
-
### Slots
333
-
334
-
<sp-link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot">Slot tags</sp-link> are
335
-
how we host our child content (light DOM) in our component's shadow DOM. The
336
-
`spectrum-css` for a component sometimes contains rules for laying out the child
337
-
content. There is a <sp-link href="https://github.com/adobe/spectrum-web-components/blob/main/packages/button/src/spectrum-config.js">`slots`
338
-
section</sp-link>
339
-
in the `spectrum-config.js` file for mapping those rules to the slotted content.
340
-
341
-
```javascript
342
-
slots: [
343
-
{
344
-
name: 'icon',
345
-
selector: '.spectrum-Icon',
346
-
},
347
-
],
348
-
```
349
-
350
-
The above section tells our CSS processor to map CSS for the `.spectrum-Icon`
351
-
class to the content that is being hosted in the <sp-link href="https://github.com/adobe/spectrum-web-components/blob/main/packages/button/src/spectrum-button.css">slot with the name
352
-
`icon`</sp-link>.
353
-
354
66
## Coding the Component
355
67
356
68
All of the `spectrum-web-components` are written using the
0 commit comments