diff --git a/docs/_includes/import-stylesheet-code.md.njk b/docs/_includes/import-stylesheet-code.md.njk index c70314b46..c0fdeedcb 100644 --- a/docs/_includes/import-stylesheet-code.md.njk +++ b/docs/_includes/import-stylesheet-code.md.njk @@ -3,14 +3,14 @@ In CSS -Simply add the following code to the `` of your page: +Add the following code to the `` of your page: ```html ``` -Simply add the following code at the top of your CSS file: +Add the following code at the top of your CSS file: ```css @import url('{% cdnUrl stylesheet %}'); ``` diff --git a/docs/_layouts/utility.njk b/docs/_layouts/utility.njk new file mode 100644 index 000000000..032e98277 --- /dev/null +++ b/docs/_layouts/utility.njk @@ -0,0 +1,19 @@ +{% extends '../_layouts/block.njk' %} + +{% block afterContent %} +{% if file %} +{% markdown %} +## Opting In + +If you want to use this utility **only** without [all others](../), you can include the following CSS file from the Web Awesome CDN. + +{% set stylesheet = file %} +{% include 'import-stylesheet-code.md.njk' %} + +Want them all? +Follow the [instructions on the Utilities overview page](../) to get all Web Awesome utilities. + +{% endmarkdown %} +{% endif %} + +{% endblock %} diff --git a/docs/docs/utilities/appearance.md b/docs/docs/utilities/appearance.md index 308e85fb5..9781f6b93 100644 --- a/docs/docs/utilities/appearance.md +++ b/docs/docs/utilities/appearance.md @@ -6,6 +6,7 @@ snippets: - .wa-outlined - .wa-filled - .wa-plain +file: styles/utilities/appearance.css --- Some Web Awesome components, like ``, allow you to change their overall style by using an `appearance` attribute: diff --git a/docs/docs/utilities/color.md b/docs/docs/utilities/color.md index 01bf25901..f8eae17fb 100644 --- a/docs/docs/utilities/color.md +++ b/docs/docs/utilities/color.md @@ -8,6 +8,7 @@ snippets: - .wa-success - .wa-warning - .wa-danger +file: styles/utilities/variants.css --- Some Web Awesome components, like ``, allow you to change the color by using a `variant` attribute: diff --git a/docs/docs/utilities/fouce.njk b/docs/docs/utilities/fouce.njk new file mode 100644 index 000000000..23669b9dc --- /dev/null +++ b/docs/docs/utilities/fouce.njk @@ -0,0 +1,131 @@ +--- +title: Reduce FOUCE +description: Utility to improve the loading experience by hiding non-prerendered custom elements until they are registered. +file: styles/utilities/fouce.css +icon: spinner +--- +{% markdown %} +No class is needed to use this utility, it will be applied automatically as long as it its CSS is included. + +Here is a comparison of the loading experience with and without this utility, +with a simulated slow loading time: + +{% endmarkdown %} + + + + + +{% set sample_card %} + + + + + + + A kitten sits patiently between a terracotta pot and decorative grasses. + + Mittens
+ This kitten is as cute as he is playful. Bring him home today!
+ 6 weeks old + +
+ More Info + +
+ + + +{% endset %} + + +
+ + +
+ + +{% markdown %} +## How does it work? + +The utility consists of a timeout (`2s` by default) and a fade duration (`200ms` by default). +- If the element is _ready_ before the timeout, it will appear immediately. +- If it takes longer than _timeout_ + _fade_, it will fade in over the fade duration. +- If it takes somewhere between _timeout_ and _timeout_ + _fade_, you will get an interrupted fade. + +An element is considered ready when both of these are true: +1. Either It has been registered or has a `did-ssr` attribute (indicating it was pre-rendered) +2. If it’s a Web Awesome component, its contents are also ready + +## Customization + +You can use the following CSS variables to customize the behavior: + +| Variable | Description | Default | +| --- | --- | --- | +| `--wa-fouce-fade` | The transition duration for the fade effect. | `200ms` | +| `--wa-fouce-timeout` | The timeout after which elements will appear even if not registered | `2s` | + +The fade duration cannot be longer than the timeout. +This means that you can disable FOUCE reduction on an element by setting `--wa-fouce-timeout: 0s`. + +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: + +```css +[ssr] { + --wa-fouce-timeout: 0s; +} +``` + +You can also opt-out from FOUCE reduction for an element and its contents by adding the `.wa-fouce-off` class to it. +Applying this class to the root element will disable the utility for the entire page. +{% endmarkdown %} diff --git a/docs/docs/utilities/gap.md b/docs/docs/utilities/gap.md index fa8938e36..7ac26c899 100644 --- a/docs/docs/utilities/gap.md +++ b/docs/docs/utilities/gap.md @@ -2,6 +2,7 @@ title: Gap description: Gap utilities set the gap property of flex and grid containers, like other Web Awesome layout utilities. tags: ["utilities", "layout"] +file: styles/utilities/gap.css ---