Skip to content

Commit 404d59d

Browse files
LeaVerouLeaVerou
authored
Improve FOUCE reduction utility, docs fixes, :state(wa-defined) (#643)
* Utility layout * Split out, improve & document FOUCE utility
1 parent ce1ce6c commit 404d59d

File tree

11 files changed

+179
-19
lines changed

11 files changed

+179
-19
lines changed

‎docs/_includes/import-stylesheet-code.md.njk

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,14 @@
33
<wa-tab panel="css">In CSS</wa-tab>
44
<wa-tab-panel name="html">
55

6-
Simply add the following code to the `<head>` of your page:
6+
Add the following code to the `<head>` of your page:
77
```html
88
<link rel="stylesheet" href="{% cdnUrl stylesheet %}" />
99
```
1010
</wa-tab-panel>
1111
<wa-tab-panel name="css">
1212

13-
Simply add the following code at the top of your CSS file:
13+
Add the following code at the top of your CSS file:
1414
```css
1515
@import url('{% cdnUrl stylesheet %}');
1616
```

‎docs/_layouts/utility.njk

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{% extends '../_layouts/block.njk' %}
2+
3+
{% block afterContent %}
4+
{% if file %}
5+
{% markdown %}
6+
## Opting In
7+
8+
If you want to use this utility **only** without [all others](../), you can include the following CSS file from the Web Awesome CDN.
9+
10+
{% set stylesheet = file %}
11+
{% include 'import-stylesheet-code.md.njk' %}
12+
13+
Want them all?
14+
Follow the [instructions on the Utilities overview page](../) to get all Web Awesome utilities.
15+
16+
{% endmarkdown %}
17+
{% endif %}
18+
19+
{% endblock %}

‎docs/docs/utilities/appearance.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ snippets:
66
- .wa-outlined
77
- .wa-filled
88
- .wa-plain
9+
file: styles/utilities/appearance.css
910
---
1011

1112
Some Web Awesome components, like `<wa-button>`, allow you to change their overall style by using an `appearance` attribute:

‎docs/docs/utilities/color.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ snippets:
88
- .wa-success
99
- .wa-warning
1010
- .wa-danger
11+
file: styles/utilities/variants.css
1112
---
1213

1314
Some Web Awesome components, like `<wa-button>`, allow you to change the color by using a `variant` attribute:

‎docs/docs/utilities/fouce.njk

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: Reduce FOUCE
3+
description: Utility to improve the loading experience by hiding non-prerendered custom elements until they are registered.
4+
file: styles/utilities/fouce.css
5+
icon: spinner
6+
---
7+
{% markdown %}
8+
No class is needed to use this utility, it will be applied automatically as long as it its CSS is included.
9+
10+
Here is a comparison of the loading experience with and without this utility,
11+
with a simulated slow loading time:
12+
13+
{% endmarkdown %}
14+
15+
16+
<div class="wa-split wa-align-items-end">
17+
<strong>Normal loading</strong>
18+
<wa-button onclick="document.querySelectorAll('iframe').forEach(iframe => iframe.srcdoc = iframe.srcdoc)">
19+
<wa-icon name="refresh"></wa-icon>
20+
Refresh
21+
</wa-button>
22+
<strong>With FOUCE reduction</strong>
23+
</div>
24+
25+
26+
{% set sample_card %}
27+
<link id="theme-stylesheet" rel="stylesheet" href="/dist/styles/themes/default.css" render="blocking" fetchpriority="high">
28+
<link rel="stylesheet" href="/dist/styles/webawesome.css">
29+
<link rel="stylesheet" href="/dist/styles/forms.css">
30+
<script type=module>
31+
const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
32+
const loadScript = src => new Promise((resolve, reject) => {
33+
const script = document.createElement("script");
34+
script.src = src;
35+
script.type = "module";
36+
script.onload = resolve;
37+
script.onerror = reject;
38+
document.head.appendChild(script);
39+
});
40+
41+
await delay(500);
42+
await loadScript("/dist/components/button/button.js");
43+
await delay(500);
44+
await loadScript("/dist/components/card/card.js");
45+
await delay(500);
46+
await loadScript("/dist/components/rating/rating.js");
47+
</script>
48+
49+
<wa-card with-footer with-image class="card-overview">
50+
<img
51+
slot="image"
52+
src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
53+
alt="A kitten sits patiently between a terracotta pot and decorative grasses."
54+
/>
55+
56+
<strong>Mittens</strong><br />
57+
This kitten is as cute as he is playful. Bring him home today!<br />
58+
<small>6 weeks old</small>
59+
60+
<div slot="footer">
61+
<wa-button variant="brand" pill>More Info</wa-button>
62+
<wa-rating></wa-rating>
63+
</div>
64+
</wa-card>
65+
66+
<style>
67+
.card-overview small {
68+
color: var(--wa-color-text-quiet);
69+
}
70+
71+
.card-overview [slot=footer] {
72+
display: flex;
73+
justify-content: space-between;
74+
align-items: center;
75+
}
76+
</style>
77+
{% endset %}
78+
79+
80+
<div class="iframes">
81+
<iframe srcdoc='<body class="wa-fouce-off">{{ sample_card }}</body>'></iframe>
82+
<iframe srcdoc='{{ sample_card }}'></iframe>
83+
</div>
84+
<style>
85+
.iframes {
86+
display: flex;
87+
gap: var(--wa-space-m);
88+
margin-top: var(--wa-space-l);
89+
90+
iframe {
91+
flex: 1;
92+
height: 60ch;
93+
}
94+
}
95+
</style>
96+
97+
{% markdown %}
98+
## How does it work?
99+
100+
The utility consists of a timeout (`2s` by default) and a fade duration (`200ms` by default).
101+
- If the element is _ready_ before the timeout, it will appear immediately.
102+
- If it takes longer than _timeout_ + _fade_, it will fade in over the fade duration.
103+
- If it takes somewhere between _timeout_ and _timeout_ + _fade_, you will get an interrupted fade.
104+
105+
An element is considered ready when both of these are true:
106+
1. Either It has been registered or has a `did-ssr` attribute (indicating it was pre-rendered)
107+
2. If it’s a Web Awesome component, its contents are also ready
108+
109+
## Customization
110+
111+
You can use the following CSS variables to customize the behavior:
112+
113+
| Variable | Description | Default |
114+
| --- | --- | --- |
115+
| `--wa-fouce-fade` | The transition duration for the fade effect. | `200ms` |
116+
| `--wa-fouce-timeout` | The timeout after which elements will appear even if not registered | `2s` |
117+
118+
The fade duration cannot be longer than the timeout.
119+
This means that you can disable FOUCE reduction on an element by setting `--wa-fouce-timeout: 0s`.
120+
121+
For example, if instead of `did-ssr` you used an `ssr` attribute to mark elements that were pre-rendered, you can do this to get them to appear immediately:
122+
123+
```css
124+
[ssr] {
125+
--wa-fouce-timeout: 0s;
126+
}
127+
```
128+
129+
You can also opt-out from FOUCE reduction for an element and its contents by adding the `.wa-fouce-off` class to it.
130+
Applying this class to the root element will disable the utility for the entire page.
131+
{% endmarkdown %}

‎docs/docs/utilities/gap.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: Gap
33
description: Gap utilities set the gap property of flex and grid containers, like other Web Awesome layout utilities.
44
tags: ["utilities", "layout"]
5+
file: styles/utilities/gap.css
56
---
67

78
<style>

‎docs/docs/utilities/utilities.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
2-
"layout": "block",
2+
"layout": "utility",
33
"tags": ["utilities"]
44
}

‎src/internal/webawesome-element.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ export default class WebAwesomeElement extends LitElement {
2626
console.error('Element internals are not supported in your browser. Consider using a polyfill');
2727
}
2828

29+
this.toggleCustomState('wa-defined');
30+
2931
let Self = this.constructor as typeof WebAwesomeElement;
3032
for (let [property, spec] of Self.elementProperties) {
3133
if (spec.default === 'inherit' && spec.initial !== undefined && typeof property === 'string') {

‎src/styles/native/base.css

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -29,22 +29,6 @@ body {
2929
-webkit-text-size-adjust: none;
3030
}
3131

32-
@keyframes wa-fade-in {
33-
from {
34-
opacity: 0;
35-
}
36-
}
37-
38-
/* Show custom elements only after they're registered */
39-
:where(:not(:defined, [did-ssr])) {
40-
/*
41-
* if an element gets defined earlier than 800ms, the animation stops applying so it just appears (no fade)
42-
* If it takes somewhere between 800 and 1000 ms, then you may get an interrupted fade
43-
* If an element takes longer than 1000ms to get defined, it fades in over 200ms
44-
*/
45-
animation: 200ms 800ms wa-fade-in both;
46-
}
47-
4832
/* Content flow */
4933
address,
5034
audio,

‎src/styles/utilities.css

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
@import url('utilities/fouce.css');
12
@import url('utilities/visually-hidden.css');
23
@import url('utilities/scroll-lock.css');
34
@import url('utilities/align-items.css');

0 commit comments

Comments
 (0)