improve search grid styles

* disable SSR module in 11ty

* remove first load fade

.github/workflows/ssr_tests.js.yml

@@ -1,11 +1,12 @@
-# # This workflow will do a clean install of node dependencies, cache/restore them, build the source code and run tests across different versions of node
-# # For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+# This workflow will do a clean install of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
 
 name: SSR Tests
 
 on:
-  push:
-    branches: [next]
+  # push:
+  #   branches: [next]
+  workflow_dispatch:
 
 jobs:
   ssr_test:

docs/.eleventy.js

@@ -7,9 +7,10 @@ import { highlightCodePlugin } from './_utils/highlight-code.js';
 import { markdown } from './_utils/markdown.js';
 import { removeDataAlphaElements } from './_utils/remove-data-alpha-elements.js';
 // import { formatCodePlugin } from './_utils/format-code.js';
-import litPlugin from '@lit-labs/eleventy-plugin-lit';
+// import litPlugin from '@lit-labs/eleventy-plugin-lit';
 import { readFile } from 'fs/promises';
-import componentList from './_data/componentList.js';
+import nunjucks from 'nunjucks';
+// import componentList from './_data/componentList.js';
 import * as filters from './_utils/filters.js';
 import { outlinePlugin } from './_utils/outline.js';
 import { replaceTextPlugin } from './_utils/replace-text.js';
@@ -28,7 +29,6 @@ const globalData = {
   package: packageData,
   isAlpha,
   layout: 'page.njk',
-
   server: {
     head: '',
     loginOrAvatar: '',
@@ -40,6 +40,11 @@ const passThroughExtensions = ['js', 'css', 'png', 'svg', 'jpg', 'mp4'];
 const passThrough = [...passThroughExtensions.map(ext => 'docs/**/*.' + ext)];
 
 export default function (eleventyConfig) {
+  /**
+   * This is the guard we use for now to make sure our final built files dont need a 2nd pass by the server. This keeps us able to still deploy the bare HTML files on Vercel until the app is ready.
+   */
+  const serverBuild = process.env.WEBAWESOME_SERVER === 'true';
+
   // NOTE - alpha setting removes certain pages
   if (isAlpha) {
     eleventyConfig.ignores.add('**/experimental/**');
@@ -68,9 +73,35 @@ export default function (eleventyConfig) {
     return `https://early.webawesome.com/webawesome@${packageData.version}/dist/` + (location || '').replace(/^\//, '');
   });
 
-  // Turns `{% server_variable "foo" %} into `{{ server.foo | safe }}`
+  // Turns `{% server "foo" %} into `{{ server.foo | safe }}` when the WEBAWESOME_SERVER variable is set to "true"
   eleventyConfig.addShortcode('server', function (property) {
-    return `{{ server.${property} | safe }}`;
+    if (serverBuild) {
+      return `{{ server.${property} | safe }}`;
+    }
+
+    return '';
+  });
+
+  eleventyConfig.addTransform('second-nunjucks-transform', function NunjucksTransform(content) {
+    // For a server build, we expect a server to run the second transform.
+    if (serverBuild) {
+      return content;
+    }
+
+    // Only run the transform on files nunjucks would transform.
+    if (!this.page.inputPath.match(/.(md|html|njk)$/)) {
+      return content;
+    }
+
+    /** This largely mimics what an app would do and just stubs out what we don't care about. */
+    return nunjucks.renderString(content, {
+      // Stub the server EJS shortcodes.
+      server: {
+        head: '',
+        loginOrAvatar: '',
+        flashes: '',
+      },
+    });
   });
 
   // Paired shortcodes - {% shortCode %}content{% endShortCode %}
@@ -132,30 +163,6 @@ export default function (eleventyConfig) {
     ]),
   );
 
-  // SSR plugin
-  if (!isDev) {
-    //
-    // Problematic components in SSR land:
-    //  - animation (breaks on navigation + ssr with Turbo)
-    //  - mutation-observer (why SSR this?)
-    //  - resize-observer (why SSR this?)
-    //  - tooltip (why SSR this?)
-    //
-    const omittedModules = [];
-    const componentModules = componentList
-      .filter(component => !omittedModules.includes(component.tagName.split(/wa-/)[1]))
-      .map(component => {
-        const name = component.tagName.split(/wa-/)[1];
-        const componentDirectory = process.env.UNBUNDLED_DIST_DIRECTORY || path.join('.', 'dist');
-        return path.join(componentDirectory, 'components', name, `${name}.js`);
-      });
-
-    eleventyConfig.addPlugin(litPlugin, {
-      mode: 'worker',
-      componentModules,
-    });
-  }
-
   // Build the search index
   eleventyConfig.addPlugin(
     searchPlugin({
@@ -182,6 +189,31 @@ export default function (eleventyConfig) {
     eleventyConfig.addPassthroughCopy(glob);
   }
 
+  // // SSR plugin
+  // // Make sure this is the last thing, we don't want to run the risk of accidentally transforming shadow roots with the nunjucks 2nd transform.
+  // if (!isDev) {
+  //   //
+  //   // Problematic components in SSR land:
+  //   //  - animation (breaks on navigation + ssr with Turbo)
+  //   //  - mutation-observer (why SSR this?)
+  //   //  - resize-observer (why SSR this?)
+  //   //  - tooltip (why SSR this?)
+  //   //
+  //   const omittedModules = [];
+  //   const componentModules = componentList
+  //     .filter(component => !omittedModules.includes(component.tagName.split(/wa-/)[1]))
+  //     .map(component => {
+  //       const name = component.tagName.split(/wa-/)[1];
+  //       const componentDirectory = process.env.UNBUNDLED_DIST_DIRECTORY || path.join('.', 'dist');
+  //       return path.join(componentDirectory, 'components', name, `${name}.js`);
+  //     });
+  //
+  //   eleventyConfig.addPlugin(litPlugin, {
+  //     mode: 'worker',
+  //     componentModules,
+  //   });
+  // }
+
   return {
     markdownTemplateEngine: 'njk',
     dir: {

docs/_includes/base.njk

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" data-fa-kit-code="b10bfbde90" data-cdn-url="{% cdnUrl %}">
+<html lang="en" data-fa-kit-code="b10bfbde90" data-cdn-url="{% cdnUrl %}" class="wa-cloak">
   <head>
     {% include 'head.njk' %}
     <meta name="theme-color" content="#f36944">

docs/_includes/breadcrumbs.njk

@@ -1,8 +1,11 @@
-{% set breadcrumbs = page.url | breadcrumbs %}
-{% if breadcrumbs.length > 0 %}
+{% set ancestors = page.url | ancestors %}
+
+{% if ancestors.length > 0 %}
   <wa-breadcrumb id="docs-breadcrumbs">
-  {% for crumb in breadcrumbs %}
-    <wa-breadcrumb-item href="{{ crumb.url }}">{{ crumb.title }}</wa-breadcrumb-item>
+  {% for ancestor in ancestors %}
+    {% if ancestor.page.url != "/" %}
+    <wa-breadcrumb-item href="{{ ancestor.page.url }}">{{ ancestor.data.title }}</wa-breadcrumb-item>
+    {% endif %}
   {% endfor %}
   <wa-breadcrumb-item>{# Current page #}</wa-breadcrumb-item>
   </wa-breadcrumb>

docs/_includes/grouped-pages.njk

@@ -1,12 +1,18 @@
 {# Cards for pages listed by category #}
 
 <section id="grid" class="index-grid">
-{% for category, pages in allPages | groupByTags(categories) -%}
-  <h2 class="index-category">{{ category | getCategoryTitle(categories) }}</h2>
-    {%- for page in pages -%}
-      {%- if not page.data.parent or listChildren -%}
-        {% include "page-card.njk" %}
-      {%- endif -%}
-    {%- endfor -%}
+{% set groupedPages = allPages | groupPages(categories, page) %}
+{% for category, pages in groupedPages -%}
+  {% if groupedPages.meta.groupCount > 1 and pages.length > 0 %}
+  <h2 class="index-category" id="{{ category | slugify }}">
+    {% if pages.meta.url %}<a href="{{ pages.meta.url }}">{{ pages.meta.title }}</a>
+    {% else %}
+    {{ pages.meta.title }}
+    {% endif %}
+  </h2>
+  {% endif %}
+  {%- for page in pages -%}
+      {% include "page-card.njk" %}
+  {%- endfor -%}
 {%- endfor -%}
 </section>

docs/_includes/head.njk

@@ -23,10 +23,9 @@
 <script src="/assets/scripts/hydration-errors.js"></script>
 <link rel="stylesheet" href="/assets/styles/hydration-errors.css">
 <link rel="preconnect" href="https://cdn.jsdelivr.net">
-<script type="module" src="https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.10/+esm"></script>
 
 {# Web Awesome #}
-<script type="module" src="/dist/webawesome.ssr-loader.js"></script>
+<script type="module" src="/dist/webawesome.loader.js"></script>
 
 <script type="module" src="/assets/scripts/theme-picker.js"></script>
 {# Preset Theme #}

docs/_includes/page-card.njk

@@ -2,7 +2,7 @@
 <a href="{{ page.url }}"{{ page.data.keywords | attr('data-keywords') }}>
 	<wa-card with-header>
 		<div slot="header">
-		{% include "svgs/" + (page.data.icon or "thumbnail-placeholder") + ".njk" %}
+		{% include "svgs/" + (page.data.icon or "thumbnail-placeholder") + ".njk" ignore missing %}
 		</div>
 		<span class="page-name">{{ page.data.title }}</span>
 		{% if pageSubtitle -%}

docs/_includes/sidebar-group.njk

@@ -1,9 +1,12 @@
 {# Some collections (like "patterns") will not have any items in the alpha build for example. So this checks to make sure the collection exists. #}
 {% if collections[tag] -%}
   {% set groupUrl %}/docs/{{ tag }}/{% endset %}
+  {% set groupItem = groupUrl | getCollectionItemFromUrl %}
+  {% set children = groupItem.data.children if groupItem.data.children.length > 0 else (collections[tag] | sort) %}
+
   <wa-details {{ ((tag in (tags or [])) or (groupUrl in page.url)) | attr('open') }}>
     <h2 slot="summary">
-      {% if groupUrl | getCollectionItemFromUrl %}
+      {% if groupItem %}
         <a href="{{ groupUrl }}" title="Overview">{{ title or (tag | capitalize) }}
           <wa-icon name="grid-2"></wa-icon>
         </a>
@@ -12,10 +15,8 @@
       {% endif %}
     </h2>
     <ul>
-      {% for page in collections[tag] | sort %}
-        {% if not page.data.parent -%}
+      {% for page in children %}
           {% include 'sidebar-link.njk' %}
-        {%- endif %}
       {% endfor %}
     </ul>
   </wa-details>

docs/_includes/sidebar-link.njk

@@ -1,4 +1,4 @@
-{% if not (isAlpha and page.data.noAlpha) and page.fileSlug != tag and not page.data.unlisted -%}
+{% if page | show -%}
 	<li>
 		<a href="{{ page.url }}">{{ page.data.title }}</a>
 		{% if page.data.status == 'experimental' %}<wa-icon name="flask"></wa-icon>{% endif %}

docs/_layouts/overview.njk

@@ -1,6 +1,5 @@
 ---
 layout: page-outline
-tags: ["overview"]
 ---
 {% set forTag = forTag or (page.url | split('/') | last) %}
 {% if description %}
@@ -13,8 +12,10 @@ tags: ["overview"]
   </wa-input>
 </div>
 
-{% set allPages = collections[forTag] %}
+{% set allPages = allPages or collections[forTag] %}
+{% if allPages and allPages.length > 0 %}
 {% include "grouped-pages.njk" %}
+{% endif %}
 
 <link href="/assets/styles/filter.css" rel="stylesheet">
 <script type="module" src="/assets/scripts/filter.js"></script>

docs/_layouts/theme.njk

@@ -68,7 +68,7 @@ wa_data.palettes = {
       <wa-option label="{{ palette.data.title }}" value="{{ palette.fileSlug if not currentPalette }}" {{ (palette.fileSlug if currentPalette) | attr('data-id') }}>
         <wa-card with-header>
           <div slot="header">
-          {% include "svgs/" + (palette.data.icon or "thumbnail-placeholder") + ".njk" %}
+          {% include "svgs/" + (palette.data.icon or "thumbnail-placeholder") + ".njk" ignore missing %}
           </div>
           <span class="page-name">
             {{ palette.data.title }}

docs/_utils/filters.js

@@ -29,6 +29,9 @@ function getCollection(name) {
 }
 
 export function getCollectionItemFromUrl(url, collection) {
+  if (!url) {
+    return null;
+  }
   collection ??= getCollection.call(this, 'all') || [];
   return collection.find(item => item.url === url);
 }
@@ -42,35 +45,33 @@ export function split(text, separator) {
   return (text + '').split(separator).filter(Boolean);
 }
 
-export function breadcrumbs(url, { withCurrent = false } = {}) {
-  const parts = split(url, '/');
-  const ret = [];
+export function ancestors(url, { withCurrent = false, withRoot = false } = {}) {
+  let ret = [];
+  let currentUrl = url;
+  let currentItem = getCollectionItemFromUrl.call(this, url);
 
-  while (parts.length) {
-    let partialUrl = '/' + parts.join('/') + '/';
-    let item = getCollectionItemFromUrl.call(this, partialUrl);
-
-    if (item && (partialUrl !== url || withCurrent)) {
-      let title = item.data.title;
-      if (title) {
-        ret.unshift({ url: partialUrl, title });
-      }
-    }
-
-    parts.pop();
-
-    if (item?.data.parent) {
-      let parentURL = item.data.parent;
-      if (!item.data.parent.startsWith('/')) {
-        // Parent is in the same directory
-        parts.push(item.data.parent);
-        parentURL = '/' + parts.join('/') + '/';
-      }
-
-      let parentBreadcrumbs = breadcrumbs.call(this, parentURL, { withCurrent: true });
-      return [...parentBreadcrumbs, ...ret];
+  if (!currentItem) {
+    // Might have eleventyExcludeFromCollections, jump to parent
+    let parentUrl = this.ctx.parentUrl;
+    if (parentUrl) {
+      url = parentUrl;
     }
   }
+
+  for (let item; (item = getCollectionItemFromUrl.call(this, url)); url = item.data.parentUrl) {
+    ret.unshift(item);
+  }
+
+  if (!withRoot && ret[0]?.page.url === '/') {
+    // Remove root
+    ret.shift();
+  }
+
+  if (!withCurrent && ret.at(-1)?.page.url === currentUrl) {
+    // Remove current page
+    ret.pop();
+  }
+
   return ret;
 }
 
@@ -177,72 +178,196 @@ export function sort(arr, by = { 'data.order': 1, 'data.title': '' }) {
   });
 }
 
+export function show(page) {
+  return !(page.data.noAlpha && page.data.isAlpha) && !page.data.unlisted;
+}
+
 /**
  * Group an 11ty collection (or any array of objects with a `data.tags` property) by certain tags.
  * @param {object[]} collection
- * @param { Object<string, string> | (string | Object<string, string>)[]} [tags] The tags to group by. If not provided/empty, defaults to grouping by all tags.
- * @returns { Object.<string, object[]> } An object with keys for each tag, and an array of items for each tag.
+ * @param { Object<string, string> | string[]} [options] Options object or array of tags to group by.
+ * @param {string[] | true} [options.tags] Tags to group by. If true, groups by all tags.
+ *                            If not provided/empty, defaults to grouping by page hierarchy, with any pages with more than 1 children becoming groups.
+ * @param {string[]} [options.groups] The groups to use if only a subset or a specific order is desired. Defaults to `options.tags`.
+ * @param {string[]} [options.titles] Any title overrides for groups.
+ * @param {string | false} [options.other="Other"] The title to use for the "Other" group. If `false`, the "Other" group is removed..
+ * @returns { Object.<string, object[]> } An object of group ids to arrays of page objects.
  */
-export function groupByTags(collection, tags) {
+export function groupPages(collection, options = {}, page) {
   if (!collection) {
-    console.error(`Empty collection passed to groupByTags() to group by ${JSON.stringify(tags)}`);
-  }
-  if (!tags) {
-    // Default to grouping by union of all tags
-    tags = Array.from(new Set(collection.flatMap(item => item.data.tags)));
-  } else if (Array.isArray(tags)) {
-    // May contain objects of one-off tag -> label mappings
-    tags = tags.map(tag => (typeof tag === 'object' ? Object.keys(tag)[0] : tag));
-  } else if (typeof tags === 'object') {
-    // tags is an object of tags to labels, so we just want the keys
-    tags = Object.keys(tags);
+    console.error(`Empty collection passed to groupPages() to group by ${JSON.stringify(options)}`);
   }
 
-  let ret = Object.fromEntries(tags.map(tag => [tag, []]));
-  ret.other = [];
+  if (Array.isArray(options)) {
+    options = { tags: options };
+  }
+
+  let { tags, groups, titles = {}, other = 'Other', filter = show } = options;
+
+  if (groups === undefined && Array.isArray(tags)) {
+    groups = tags;
+  }
+
+  let grouping;
+
+  if (tags) {
+    grouping = {
+      isGroup: item => undefined,
+      getCandidateGroups: item => item.data.tags,
+      getGroupMeta: group => ({}),
+    };
+  } else {
+    grouping = {
+      isGroup: item => (item.data.children.length >= 2 ? item.page.url : undefined),
+      getCandidateGroups: item => {
+        let parentUrl = item.data.parentUrl;
+        if (page?.url === parentUrl) {
+          return [];
+        }
+        return [parentUrl];
+      },
+      getGroupMeta: group => {
+        let item = byUrl[group] || getCollectionItemFromUrl.call(this, group);
+        return {
+          title: item?.data.title,
+          url: group,
+          item,
+        };
+      },
+      sortGroups: groups => sort(groups.map(url => byUrl[url]).filter(Boolean)).map(item => item.page.url),
+    };
+  }
+
+  let byUrl = {};
+  let byParentUrl = {};
+
+  if (filter) {
+    collection = collection.filter(filter);
+  }
 
   for (let item of collection) {
-    let categorized = false;
+    let url = item.page.url;
+    let parentUrl = item.data.parentUrl;
 
-    for (let tag of tags) {
-      if (item.data.tags.includes(tag)) {
-        ret[tag].push(item);
-        categorized = true;
-      }
-    }
+    byUrl[url] = item;
 
-    if (!categorized) {
-      ret.other.push(item);
+    if (parentUrl) {
+      byParentUrl[parentUrl] ??= [];
+      byParentUrl[parentUrl].push(item);
     }
   }
 
-  // Remove empty categories
-  for (let category in ret) {
-    if (ret[category].length === 0) {
-      delete ret[category];
+  let urlToGroups = {};
+
+  for (let item of collection) {
+    let url = item.page.url;
+    let parentUrl = item.data.parentUrl;
+
+    if (grouping.isGroup(item)) {
+      continue;
+    }
+
+    let parentItem = byUrl[parentUrl];
+    if (parentItem && !grouping.isGroup(parentItem)) {
+      // Their parent is also here and is not a group
+      continue;
+    }
+
+    let candidateGroups = grouping.getCandidateGroups(item);
+
+    if (groups) {
+      candidateGroups = candidateGroups.filter(group => groups.includes(group));
+    }
+
+    urlToGroups[url] ??= [];
+
+    for (let group of candidateGroups) {
+      urlToGroups[url].push(group);
+    }
+  }
+
+  let ret = {};
+
+  for (let url in urlToGroups) {
+    let groups = urlToGroups[url];
+    let item = byUrl[url];
+
+    if (groups.length === 0) {
+      // Not filtered out but also not categorized
+      groups = ['other'];
+    }
+
+    for (let group of groups) {
+      ret[group] ??= [];
+      ret[group].push(item);
+
+      if (!ret[group].meta) {
+        if (group === 'other') {
+          ret[group].meta = { title: other };
+        } else {
+          ret[group].meta = grouping.getGroupMeta(group);
+          ret[group].meta.title = titles[group] ?? ret[group].meta.title ?? capitalize(group);
+        }
+      }
+    }
+  }
+
+  if (other === false) {
+    delete ret.other;
+  }
+
+  // Sort
+  let sortedGroups = groups ?? grouping.sortGroups?.(Object.keys(ret));
+
+  if (sortedGroups) {
+    ret = sortObject(ret, sortedGroups);
+  } else {
+    // At least make sure other is last
+    if (ret.other) {
+      let otherGroup = ret.other;
+      delete ret.other;
+      ret.other = otherGroup;
+    }
+  }
+
+  Object.defineProperty(ret, 'meta', {
+    value: {
+      groupCount: Object.keys(ret).length,
+    },
+    enumerable: false,
+  });
+
+  return ret;
+}
+
+/**
+ * Sort an object by its keys
+ * @param {*} obj
+ * @param {function | string[]} order
+ */
+function sortObject(obj, order) {
+  let ret = {};
+  let sortedKeys = Array.isArray(order) ? order : Object.keys(obj).sort(order);
+
+  for (let key of sortedKeys) {
+    if (key in obj) {
+      ret[key] = obj[key];
+    }
+  }
+
+  // Add any keys that weren't in the order
+  for (let key in obj) {
+    if (!(key in ret)) {
+      ret[key] = obj[key];
     }
   }
 
   return ret;
 }
 
-export function getCategoryTitle(category, categories) {
-  let title;
-  if (Array.isArray(categories)) {
-    // Find relevant entry
-    // [{id: "Title"}, id2, ...]
-    title = categories.find(entry => typeof entry === 'object' && entry?.[category])?.[category];
-  } else if (typeof categories === 'object') {
-    // {id: "Title", id2: "Title 2", ...}
-    title = categories[category];
-  }
-
-  if (title) {
-    return title;
-  }
-
-  // Capitalized
-  return category.charAt(0).toUpperCase() + category.slice(1);
+function capitalize(str) {
+  str += '';
+  return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
 const IDENTITY = x => x;

docs/_utils/outline.js

@@ -39,7 +39,7 @@ export function outlinePlugin(options = {}) {
         }
 
         // Create a clone of the heading so we can remove links and [data-no-outline] elements from the text content
-        clone.querySelectorAll('a').forEach(a => a.remove());
+        clone.querySelectorAll('.wa-visually-hidden, [hidden], [aria-hidden="true"]').forEach(el => el.remove());
         clone.querySelectorAll('[data-no-outline]').forEach(el => el.remove());
 
         // Generate the link

docs/assets/scripts/filter.js

@@ -1,3 +1,11 @@
+function debounce(func, wait) {
+  let timeout;
+  return function (...args) {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => func.apply(this, args), wait);
+  };
+}
+
 function updateResults(input) {
   const filter = input.value.toLowerCase().trim();
   let filtered = Boolean(filter);
@@ -18,8 +26,10 @@ function updateResults(input) {
   }
 }
 
+const debouncedUpdateResults = debounce(updateResults, 300);
+
 document.documentElement.addEventListener('input', e => {
   if (e.target?.matches('#block-filter wa-input')) {
-    updateResults(e.target);
+    debouncedUpdateResults(e.target);
   }
 });

docs/assets/scripts/theme-picker.js

@@ -1,12 +1,30 @@
+let initialPageLoadComplete = false;
+
+window.addEventListener('load', () => {
+  initialPageLoadComplete = true;
+});
+
 // Helper for view transitions
-export function domChange(fn, { behavior = 'smooth' } = {}) {
+export function domChange(fn, { behavior = 'smooth', ignoreInitialLoad = true } = {}) {
   const canUseViewTransitions =
     document.startViewTransition && !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
 
+  // Skip transitions on initial page load
+  if (!initialPageLoadComplete && ignoreInitialLoad) {
+    fn(false);
+    return null;
+  }
+
   if (canUseViewTransitions && behavior === 'smooth') {
-    document.startViewTransition(fn);
+    const transition = document.startViewTransition(() => {
+      fn(true);
+      // Wait a brief delay before finishing the transition to prevent jumpiness
+      return new Promise(resolve => setTimeout(resolve, 200));
+    });
+    return transition;
   } else {
-    fn(true);
+    fn(false);
+    return null;
   }
 }
 

docs/assets/scripts/turbo.js

@@ -1,3 +1,6 @@
+import 'https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.10/+esm';
+import { preventTurboFouce } from '/dist/webawesome.js';
+
 if (!window.___turboScrollPositions___) {
   window.___turboScrollPositions___ = {};
 }
@@ -70,3 +73,4 @@ function fixDSD(e) {
 window.addEventListener('turbo:before-cache', saveScrollPosition);
 window.addEventListener('turbo:before-render', restoreScrollPosition);
 window.addEventListener('turbo:render', restoreScrollPosition);
+preventTurboFouce();

docs/assets/styles/docs.css

@@ -370,10 +370,22 @@ wa-page > main:has(> .index-grid) {
 
 .index-grid {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(22ch, 100%), 1fr));
+  grid-template-columns: repeat(4, 1fr);
   gap: var(--wa-space-2xl);
   margin-block-end: var(--wa-space-3xl);
 
+  @media screen and (max-width: 1470px) {
+    grid-template-columns: repeat(3, 1fr);
+  }
+
+  @media screen and (max-width: 960px) {
+    grid-template-columns: repeat(2, 1fr);
+  }
+
+  @media screen and (max-width: 500px) {
+    grid-template-columns: repeat(1, 1fr);
+  }
+
   a {
     border-radius: var(--wa-border-radius-l);
     text-decoration: none;

docs/docs/components/card.md

@@ -15,9 +15,9 @@ icon: card
 
   <strong>Mittens</strong><br />
   This kitten is as cute as he is playful. Bring him home today!<br />
-  <small>6 weeks old</small>
+  <small class="wa-caption-m">6 weeks old</small>
 
-  <div slot="footer">
+  <div slot="footer" class="wa-split">
     <wa-button variant="brand" pill>More Info</wa-button>
     <wa-rating label="Rating"></wa-rating>
   </div>
@@ -27,16 +27,6 @@ icon: card
   .card-overview {
     width: 300px;
   }
-
-  .card-overview small {
-    color: var(--wa-color-text-quiet);
-  }
-
-  .card-overview [slot='footer'] {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-  }
 </style>
 ```
 
@@ -65,9 +55,9 @@ If using SSR, you need to also use the `with-header` attribute to add a header t
 
 ```html {.example}
 <wa-card with-header class="card-header">
-  <div slot="header">
+  <div slot="header" class="wa-split">
     Header Title
-    <wa-icon-button name="gear" variant="solid" label="Settings"></wa-icon-button>
+    <wa-icon-button name="gear" variant="solid" label="Settings" class="wa-size-m"></wa-icon-button>
   </div>
 
   This card has a header. You can put all sorts of things in it!
@@ -78,19 +68,9 @@ If using SSR, you need to also use the `with-header` attribute to add a header t
     max-width: 300px;
   }
 
-  .card-header [slot='header'] {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-  }
-
   .card-header h3 {
     margin: 0;
   }
-
-  .card-header wa-icon-button {
-    font-size: var(--wa-font-size-m);
-  }
 </style>
 ```
 
@@ -103,7 +83,7 @@ If using SSR, you need to also use the `with-footer` attribute to add a footer t
 <wa-card with-footer class="card-footer">
   This card has a footer. You can put all sorts of things in it!
 
-  <div slot="footer">
+  <div slot="footer" class="wa-split">
     <wa-rating></wa-rating>
     <wa-button variant="brand">Preview</wa-button>
   </div>
@@ -113,12 +93,6 @@ If using SSR, you need to also use the `with-footer` attribute to add a footer t
   .card-footer {
     max-width: 300px;
   }
-
-  .card-footer [slot='footer'] {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-  }
 </style>
 ```
 
@@ -153,7 +127,7 @@ Use the `size` attribute to change a card's size.
 <wa-card with-footer size="small">
   This is a small card.
 
-  <footer slot="footer" class="wa-flank">
+  <footer slot="footer" class="wa-split">
     <wa-button variant="brand" pill>More Info</wa-button>
     <wa-rating></wa-rating>
   </footer>
@@ -162,7 +136,7 @@ Use the `size` attribute to change a card's size.
 <wa-card with-footer size="medium">
   This is a medium card (default).
 
-  <footer slot="footer" class="wa-flank">
+  <footer slot="footer" class="wa-split">
     <wa-button variant="brand" pill>More Info</wa-button>
     <wa-rating></wa-rating>
   </footer>
@@ -171,14 +145,39 @@ Use the `size` attribute to change a card's size.
 <wa-card with-footer size="large">
   This is a large card.
 
-  <footer slot="footer" class="wa-flank">
+  <footer slot="footer" class="wa-split">
     <wa-button variant="brand" pill>More Info</wa-button>
     <wa-rating></wa-rating>
   </footer>
 </wa-card>
 </div>
-
 ```
 
-<style>
-</style>
+### Appearance
+
+Use the `appearance` attribute to change the card's visual appearance.
+
+```html {.example}
+<div class="wa-grid">
+<wa-card>
+  <img
+    slot="image"
+    src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
+    alt="A kitten sits patiently between a terracotta pot and decorative grasses."
+  />
+  <div slot="header">Outlined (default)</div>
+  Card content.
+</wa-card>
+{% for appearance in ['outlined filled', 'outlined accent', 'plain', 'filled', 'accent'] -%}
+<wa-card appearance="{{ appearance }}">
+  <img
+    slot="image"
+    src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
+    alt="A kitten sits patiently between a terracotta pot and decorative grasses."
+  />
+  <div slot="header">{{ appearance | capitalize }}</div>
+  Card content.
+</wa-card>
+{%- endfor %}
+</div>
+```

docs/docs/components/details.md

@@ -77,6 +77,31 @@ The details component automatically adapts to right-to-left languages:
 </wa-details>
 ```
 
+### Appearance
+
+Use the `appearance` attribute to change the element’s visual appearance.
+
+```html {.example}
+<div class="wa-stack">
+<wa-details summary="Outlined (default)">
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</wa-details>
+<wa-details summary="Filled" appearance="filled">
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</wa-details>
+<wa-details summary="Filled + Outlined" appearance="filled outlined">
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</wa-details>
+<wa-details summary="Plain" appearance="plain">
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</wa-details>
+</div>
+```
+
 ### Grouping Details
 
 Details are designed to function independently, but you can simulate a group or "accordion" where only one is shown at a time by listening for the `wa-show` event.

docs/docs/components/index.njk

@@ -2,13 +2,10 @@
 title: Components
 description: Components are the essential building blocks to create intuitive, cohesive experiences. Browse the library of customizable, framework-friendly web components included in Web Awesome.
 layout: overview
-categories:
-  - actions
-  - feedback: 'Feedback & Status'
-  - imagery
-  - inputs
-  - navigation
-  - organization
-  - helpers: 'Utilities'
 override:tags: []
+categories:
+  tags: [actions, feedback, imagery, inputs, navigation, organization, helpers]
+  titles:
+    feedback: 'Feedback & Status'
+    helpers: 'Utilities'
 ---

docs/docs/docs.11tydata.js

@@ -1,10 +1,80 @@
+/**
+ * Global data for all pages
+ */
+import { sort } from '../_utils/filters.js';
+
 export default {
   eleventyComputed: {
-    children(data) {
-      let mainTag = data.tags?.[0];
-      let collection = data.collections[mainTag] ?? [];
+    // Default parent. Can be overridden by explicitly setting parent in the data.
+    // parent can refer to either an ancestor page in the URL or another page in the same directory
+    parent(data) {
+      let { parent, page } = data;
 
-      return collection.filter(item => item.data.parent === data.page.fileSlug);
+      if (parent) {
+        return parent;
+      }
+
+      return page.url.split('/').filter(Boolean).at(-2);
+    },
+
+    parentUrl(data) {
+      let { parent, page } = data;
+      return getParentUrl(page.url, parent);
+    },
+
+    parentItem(data) {
+      let { parentUrl } = data;
+      return data.collections.all.find(item => item.url === parentUrl);
+    },
+
+    children(data) {
+      let { collections, page, parentOf } = data;
+
+      if (parentOf) {
+        return collections[parentOf];
+      }
+
+      let collection = collections.all ?? [];
+      let url = page.url;
+
+      let ret = collection.filter(item => {
+        return item.data.parentUrl === url;
+      });
+
+      sort(ret);
+
+      return ret;
     },
   },
 };
+
+function getParentUrl(url, parent) {
+  let parts = url.split('/').filter(Boolean);
+  let ancestorIndex = parts.findLastIndex(part => part === parent);
+  let retParts = parts.slice();
+
+  if (ancestorIndex > -1) {
+    // parent is an ancestor
+    retParts.splice(ancestorIndex + 1);
+  } else {
+    // parent is a sibling in the same directory
+    retParts.splice(-1, 1, parent);
+  }
+
+  let ret = retParts.join('/');
+
+  if (url.startsWith('/')) {
+    ret = '/' + ret;
+  }
+
+  if (!retParts.at(-1).includes('.') && !ret.endsWith('/')) {
+    // If no extension, make sure to end with a slash
+    ret += '/';
+  }
+
+  if (ret === '/docs/') {
+    ret = '/';
+  }
+
+  return ret;
+}

docs/docs/installation.md

@@ -37,10 +37,6 @@ This snippet includes three parts:
 
 Now you can [start using Web Awesome!](/docs/usage)
 
-:::info
-While convenient, autoloading may lead to a [Flash of Undefined Custom Elements](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/). The linked article describes some ways to alleviate it.
-:::
-
 ---
 
 ## Using Font Awesome Kit Codes

docs/docs/layout.njk

@@ -2,6 +2,7 @@
 title: Layout
 description: Layout components and utility classes help you organize content that can adapt to any device or screen size. See the [installation instructions](#installation) to use Web Awesome's layout tools in your project.
 layout: overview
+parentOf: layout
 categories: ["components", "utilities"]
 override:tags: []
 ---
@@ -22,4 +23,4 @@ Or, you can choose to import _only_ the utilities:
 ```html
 <link rel="stylesheet" href="{% cdnUrl 'styles/utilities.css' %}" />
 ```
-{% endmarkdown %}
+{% endmarkdown %}

docs/docs/native/button.md

@@ -33,7 +33,7 @@ Use the [variant utility classes](../utilities/color.md) to set the button's sem
 
 ### Appearance
 
-Use the [appearance utility classes](../utilities/appearance.md) to change the button's visual appearance:
+Use the [appearance utility classes](/docs/utilities/appearance) to change the button's visual appearance:
 
 ```html {.example}
 <div style="margin-block-end: 1rem;">

docs/docs/native/callout.md

@@ -57,7 +57,7 @@ Use the [variant utility classes](../utilities/color.md) to set the callout's co
 
 ### Appearance
 
-Use the [appearance utility classes](../utilities/appearance.md) to change the callout's visual appearance (the default is `outlined filled`).
+Use the [appearance utility classes](/docs/utilities/appearance) to change the callout's visual appearance (the default is `outlined filled`).
 
 ```html {.example}
 <article class="wa-callout wa-brand wa-outlined wa-accent">

docs/docs/native/details.md

@@ -19,6 +19,35 @@ file: styles/native/details.css
 
 ## Examples
 
+### Appearance
+
+Use the [appearance utility classes](/docs/utilities/appearance) to change the element's visual appearance:
+
+```html {.example}
+<div class="wa-stack">
+<details>
+  <summary>Outlined (default)</summary>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</details>
+<details class="wa-filled">
+  <summary>Filled</summary>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</details>
+<details class="wa-filled wa-outlined">
+  <summary>Filled + Outlined</summary>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</details>
+<details class="wa-plain">
+  <summary>Plain</summary>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</details>
+</div>
+```
+
 ### Right-to-Left Languages
 
 The details styling automatically adapts to right-to-left languages:

docs/docs/palettes/index.njk

@@ -5,6 +5,6 @@ layout: overview
 override:tags: []
 forTag: palette
 categories:
+  tags: [other, pro]
   other: Free
-  pro: Pro
 ---

docs/docs/patterns/index.njk

@@ -2,7 +2,5 @@
 title: Patterns
 description: Patterns are reusable solutions to common design problems.
 layout: overview
-categories: ["e-commerce"]
-listChildren: true
 override:tags: []
 ---

docs/docs/resources/changelog.md

@@ -14,9 +14,12 @@ During the alpha period, things might break! We take breaking changes very serio
 
 ## Next
 
+- Added the `wa-cloak` utility to prevent FOUCE
+- Added the `allDefined()` utility for awaiting component registration
 - Fixed `wa-pill` class for text fields
 - Fixed `pill` style for `<wa-input>` elements
 - Fixed a bug in `<wa-color-picker>` that prevented light dismiss from working when clicking immediately above the color picker dropdown
+- Fixed a bug in `<wa-select multiple>` that sometimes resulted in empty `<div>` elements being output
 
 ## 3.0.0-alpha.11
 

docs/docs/themes/creating.md

@@ -31,8 +31,7 @@ If you're customizing the default dark styles, scope your styles to the followin
 
 ```css
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   /* your custom styles here */
 }
 ```

docs/docs/themes/index.njk

@@ -1,13 +1,13 @@
 ---
 title: Themes
-description: Themes are collections of design tokens that thread through every Web Awesome component and pattern. 
+description: Themes are collections of design tokens that thread through every Web Awesome component and pattern.
   Themes play a crucial role in [customizing Web Awesome](/docs/customizing).
 layout: overview
 override:tags: []
 forTag: theme
 categories:
+  tags: [other, pro]
   other: Free
-  pro: Pro
 ---
 
 <div class="max-line-length">
@@ -30,7 +30,7 @@ In pre-made themes, we use a light color scheme by default.
 Additionally, styles may be scoped to the `:root` selector to be activated automatically.
 For pre-made themes, *all* custom properties are scoped to `:root`, the theme class, and `wa-light`.
 
-Finally, we scope themes to `:host` and `:host-context()` to ensure the styles are applied to the shadow roots of custom elements.
+Finally, we scope themes to `:host` to ensure the styles are applied to the shadow roots of custom elements.
 
 For example, the default theme is set up like this:
 
@@ -44,8 +44,7 @@ For example, the default theme is set up like this:
 }
 
 .wa-dark,
-.wa-invert,
-:host-context(.wa-dark) {
+.wa-invert {
   /* subset of CSS custom properties for a dark color scheme */
 }
 ```

docs/docs/tokens/index.njk

@@ -3,4 +3,5 @@ title: Design Tokens
 description: A theme is a collection of predefined CSS custom properties that control global styles from color to shadows. These custom properties thread through all Web Awesome components for a consistent look and feel.
 layout: overview
 override:tags: []
+categories: {tags: true}
 ---

docs/docs/usage.md

@@ -8,6 +8,30 @@ Web Awesome components are just regular HTML elements, or [custom elements](http
 
 If you're new to custom elements, often referred to as "web components," this section will familiarize you with how to use them.
 
+## Awaiting Registration
+
+Unlike traditional frameworks, custom elements don't have a centralized initialization phase. This means you need to verify that a custom element has been properly registered before attempting to interact with its properties or methods.
+
+You can use the [`customElements.whenDefined()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined) method to ensure a specific component is ready:
+
+```ts
+await customElements.whenDefined('wa-button');
+
+// <wa-button> is ready to use!
+const button = document.querySelector('wa-button');
+```
+
+When working with multiple components, checking each one individually can become tedious. For convenience, Web Awesome provides the `allDefined()` function which automatically detects and waits for all Web Awesome components in the DOM to be initialized before resolving.
+
+```ts
+import { allDefined } from '/dist/webawesome.js';
+
+// Waits for all Web Awesome components in the DOM to be registered
+await allDefined();
+
+// All Web Awesome components on the page are ready!
+```
+
 ## Attributes & Properties
 
 Many components have properties that can be set using attributes. For example, buttons accept a `size` attribute that maps to the `size` property which dictates the button's size.

docs/docs/utilities/fouce.md

@@ -0,0 +1,32 @@
+---
+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
+---
+
+While convenient, autoloading can lead to a [Flash of Undefined Custom Elements](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/).
+The [FOUCE style utility](/docs/utilities/fouce/#opting-in) (which is automatically applied if you use the [Web Awesome utilities](/docs/utilities/)) takes care of hiding custom elements until they and their contents have been registered, up to a maximum of two seconds.
+
+In many cases, this is not enough, and you may wish to hide a broader wrapper element or even the entire page until all WA elements within it have loaded. To do that, you can add the `wa-reduce-fouce` class to any element on the page or even apply it to the whole page by placing the class on the `<html>` element.
+
+```html
+<html class="wa-cloak">
+  ...
+</html>
+```
+
+As soon as all elements are registered _or_ after two seconds have elapsed, the autoloader will show the page. The two-second timeout prevents blank screens from persisting on slow networks and pages that have errors.
+
+:::details Are you using Turbo in your app?
+
+If you're using [Turbo](https://turbo.hotwired.dev/) to serve a multi-page application (MPA) as a single page application (SPA), you might notice FOUCE when navigating from page to page. This is because Turbo renders the new page's content before the autoloader has a change to register new components.
+
+The following function acts as a middleware to ensure components are registered _before_ the page shows, eliminating FOUCE for page-to-page navigation with Turbo.
+
+```js
+import { preventTurboFouce } from '/dist/webawesome.js';
+
+preventTurboFouce();
+```
+:::

docs/docs/utilities/fouce.njk

@@ -1,131 +0,0 @@
----
-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 %}
-
-
-<div class="wa-split wa-align-items-end">
-  <strong>Normal loading</strong>
-  <wa-button onclick="document.querySelectorAll('iframe').forEach(iframe => iframe.srcdoc = iframe.srcdoc)">
-    <wa-icon name="refresh"></wa-icon>
-    Refresh
-  </wa-button>
-  <strong>With FOUCE reduction</strong>
-</div>
-
-
-{% set sample_card %}
-<link id="theme-stylesheet" rel="stylesheet" href="/dist/styles/themes/default.css" render="blocking" fetchpriority="high">
-<link rel="stylesheet" href="/dist/styles/webawesome.css">
-<link rel="stylesheet" href="/dist/styles/forms.css">
-<script type=module>
-const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
-const loadScript = src => new Promise((resolve, reject) => {
-  const script = document.createElement("script");
-  script.src = src;
-  script.type = "module";
-  script.onload = resolve;
-  script.onerror = reject;
-  document.head.appendChild(script);
-});
-
-await delay(500);
-await loadScript("/dist/components/button/button.js");
-await delay(500);
-await loadScript("/dist/components/card/card.js");
-await delay(500);
-await loadScript("/dist/components/rating/rating.js");
-</script>
-
-<wa-card with-footer with-image class="card-overview">
-  <img
-    slot="image"
-    src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
-    alt="A kitten sits patiently between a terracotta pot and decorative grasses."
-  />
-
-  <strong>Mittens</strong><br />
-  This kitten is as cute as he is playful. Bring him home today!<br />
-  <small>6 weeks old</small>
-
-  <div slot="footer">
-    <wa-button variant="brand" pill>More Info</wa-button>
-    <wa-rating></wa-rating>
-  </div>
-</wa-card>
-
-<style>
-  .card-overview small {
-    color: var(--wa-color-text-quiet);
-  }
-
-  .card-overview [slot=footer] {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-  }
-</style>
-{% endset %}
-
-
-<div class="iframes">
-<iframe srcdoc='<body class="wa-fouce-off">{{ sample_card }}</body>'></iframe>
-<iframe srcdoc='{{ sample_card }}'></iframe>
-</div>
-<style>
-.iframes {
-	display: flex;
-	gap: var(--wa-space-m);
-  margin-top: var(--wa-space-l);
-
-	iframe {
-		flex: 1;
-		height: 60ch;
-	}
-}
-</style>
-
-{% 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 %}

scripts/build.js

@@ -8,7 +8,6 @@ import { replace } from 'esbuild-plugin-replace';
 import { mkdir, readFile } from 'fs/promises';
 import getPort, { portNumbers } from 'get-port';
 import { globby } from 'globby';
-import nunjucks from 'nunjucks';
 import ora from 'ora';
 import { dirname, join, relative } from 'path';
 import process from 'process';
@@ -345,35 +344,6 @@ if (isDeveloping) {
           '/dist/': './dist-cdn/',
         },
       },
-      middleware: [
-        function simulateWebawesomeApp(req, res, next) {
-          // Accumulator for strings so we can pass them through nunjucks a second time similar to how the webawesome-app
-          // will be running nunjucks twice.
-          const finalString = [];
-          const encoding = 'utf-8';
-
-          const _write = res.write;
-          res.write = function (chunk, encoding) {
-            finalString.push(chunk.toString());
-          };
-
-          const _end = res.end;
-          res.end = function (...args) {
-            const transformedStr = nunjucks.renderString(finalString.join(''), {
-              // Stub the server EJS shortcodes.
-              server: {
-                head: '',
-                loginOrAvatar: '',
-                flashes: '',
-              },
-            });
-            _write.call(res, transformedStr, encoding);
-            _end.call(res, ...args);
-          };
-
-          next();
-        },
-      ],
       callbacks: {
         ready: (_err, instance) => {
           // 404 errors

src/components/card/card.css

@@ -5,15 +5,16 @@
 
   --spacing: var(--wa-space);
   --border-width: var(--wa-panel-border-width);
-  --border-color: var(--wa-color-surface-border);
+  --outlined-background-color: var(--wa-color-surface-default);
+  --outlined-border-color: var(--wa-color-surface-border);
   --border-radius: var(--wa-panel-border-radius);
-
   --inner-border-radius: calc(var(--border-radius) - var(--border-width));
+  --inner-border-color: var(--outlined-border-color);
 
   display: flex;
   flex-direction: column;
-  background-color: var(--wa-color-surface-default);
-  border-color: var(--border-color);
+  background-color: var(--background-color, var(--wa-color-surface-default));
+  border-color: var(--border-color, var(--wa-color-surface-border));
   border-radius: var(--border-radius);
   border-style: var(--wa-panel-border-style);
   box-shadow: var(--wa-shadow-s);
@@ -21,6 +22,20 @@
   color: var(--wa-color-text-normal);
 }
 
+:host(:is([appearance~='accent'], .wa-accent)) {
+  color: var(--text-color, var(--wa-color-text-normal));
+}
+
+:host([appearance~='filled']),
+:host(.wa-filled) {
+  --inner-border-color: oklab(from var(--outlined-border-color) l a b / 65%);
+}
+
+:host([appearance='plain']) {
+  --inner-border-color: transparent;
+  box-shadow: none;
+}
+
 /* Take care of top and bottom radii */
 .image,
 :host(:not([with-image])) .header,
@@ -46,10 +61,19 @@
   }
 }
 
+/* Round all corners for plain appearance */
+:host([appearance='plain']) .image {
+  border-radius: var(--inner-border-radius);
+
+  &::slotted(img) {
+    border-radius: inherit !important;
+  }
+}
+
 .header {
   display: block;
   border-block-end-style: inherit;
-  border-block-end-color: var(--border-color);
+  border-block-end-color: var(--inner-border-color);
   border-block-end-width: var(--border-width);
   padding: calc(var(--spacing) / 2) var(--spacing);
 }
@@ -62,7 +86,7 @@
 .footer {
   display: block;
   border-block-start-style: inherit;
-  border-block-start-color: var(--border-color);
+  border-block-start-color: var(--inner-border-color);
   border-block-start-width: var(--border-width);
   padding: var(--spacing);
 }

src/components/card/card.ts

@@ -2,6 +2,7 @@ import { html } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { HasSlotController } from '../../internal/slot.js';
 import WebAwesomeElement from '../../internal/webawesome-element.js';
+import appearanceStyles from '../../styles/utilities/appearance.css';
 import sizeStyles from '../../styles/utilities/size.css';
 import styles from './card.css';
 
@@ -22,19 +23,24 @@ import styles from './card.css';
  * @csspart footer - The container that wraps the card's footer.
  *
  * @cssproperty [--border-radius=var(--wa-panel-border-radius)] - The radius for the card's corners. Expects a single value.
- * @cssproperty [--border-color=var(--wa-color-surface-border)] - The color of the card's borders, including inner borders. Expects a single value.
+ * @cssproperty [--border-color=var(--wa-color-surface-border)] - The color of the card's borders. Expects a single value.
+ * @cssproperty [--inner-border-color=var(--wa-color-surface-border)] - The color of the card's inner borders, e.g. those separating headers and footers from the main content. Expects a single value.
  * @cssproperty [--border-width=var(--wa-panel-border-width)] - The width of the card's borders. Expects a single value.
  * @cssproperty [--spacing=var(--wa-space)] - The amount of space around and between sections of the card. Expects a single value.
  */
 @customElement('wa-card')
 export default class WaCard extends WebAwesomeElement {
-  static shadowStyle = [sizeStyles, styles];
+  static shadowStyle = [sizeStyles, appearanceStyles, styles];
 
   private readonly hasSlotController = new HasSlotController(this, 'footer', 'header', 'image');
 
   /** The component's size. Will be inherited by any descendants with a `size` attribute. */
   @property({ reflect: true, initial: 'medium' }) size: 'small' | 'medium' | 'large' | 'inherit' = 'inherit';
 
+  /** The card's visual appearance. */
+  @property({ reflect: true })
+  appearance: 'accent' | 'filled' | 'outlined' | 'plain' = 'outlined';
+
   /** Renders the card with a header. Only needed for SSR, otherwise is automatically added. */
   @property({ attribute: 'with-header', type: Boolean, reflect: true }) withHeader = false;
 

src/components/details/details.ts

@@ -9,6 +9,7 @@ import { getTargetElement, waitForEvent } from '../../internal/event.js';
 import { watch } from '../../internal/watch.js';
 import WebAwesomeElement from '../../internal/webawesome-element.js';
 import nativeStyles from '../../styles/native/details.css';
+import appearanceStyles from '../../styles/utilities/appearance.css';
 import { LocalizeController } from '../../utilities/localize.js';
 import '../icon/icon.js';
 import styles from './details.css';
@@ -45,7 +46,7 @@ import styles from './details.css';
  */
 @customElement('wa-details')
 export default class WaDetails extends WebAwesomeElement {
-  static shadowStyle = [nativeStyles, styles];
+  static shadowStyle = [appearanceStyles, nativeStyles, styles];
 
   private detailsObserver: MutationObserver;
   private readonly localize = new LocalizeController(this);
@@ -67,6 +68,9 @@ export default class WaDetails extends WebAwesomeElement {
   /** Disables the details so it can't be toggled. */
   @property({ type: Boolean, reflect: true }) disabled = false;
 
+  /** The element's visual appearance. */
+  @property({ reflect: true }) appearance: 'filled' | 'outlined' | 'plain' = 'outlined';
+
   firstUpdated() {
     this.body.style.height = this.open ? 'auto' : '0';
     if (this.open) {

src/components/select/select.ts

@@ -291,7 +291,6 @@ export default class WaSelect extends WebAwesomeFormAssociatedElement {
           ?pill=${this.pill}
           size=${this.size}
           removable
-          @wa-remove=${(event: WaRemoveEvent) => this.handleTagRemove(event, option)}
         >
           ${option.label}
         </wa-tag>
@@ -587,10 +586,33 @@ export default class WaSelect extends WebAwesomeFormAssociatedElement {
     this.setSelectedOptions(allOptions.filter(el => value.includes(el.value)));
   }
 
-  private handleTagRemove(event: WaRemoveEvent, option: WaOption) {
+  private handleTagRemove(event: WaRemoveEvent, directOption?: WaOption) {
     event.stopPropagation();
 
-    if (!this.disabled) {
+    if (this.disabled) return;
+
+    // Use the directly provided option if available (from getTag method)
+    let option = directOption;
+
+    // If no direct option was provided, find the option from the event path
+    if (!option) {
+      const tagElement = (event.target as Element).closest('wa-tag[part~=tag]');
+
+      if (tagElement) {
+        // Find the index of this tag among all tags
+        const tagsContainer = this.shadowRoot?.querySelector('[part="tags"]');
+        if (tagsContainer) {
+          const allTags = Array.from(tagsContainer.children);
+          const index = allTags.indexOf(tagElement as HTMLElement);
+
+          if (index >= 0 && index < this.selectedOptions.length) {
+            option = this.selectedOptions[index];
+          }
+        }
+      }
+    }
+
+    if (option) {
       this.toggleOptionSelection(option, false);
 
       // Emit after updating
@@ -707,10 +729,8 @@ export default class WaSelect extends WebAwesomeFormAssociatedElement {
     return this.selectedOptions.map((option, index) => {
       if (index < this.maxOptionsVisible || this.maxOptionsVisible <= 0) {
         const tag = this.getTag(option, index);
-        // Wrap so we can handle the remove
-        return html`<div @wa-remove=${(e: WaRemoveEvent) => this.handleTagRemove(e, option)}>
-          ${typeof tag === 'string' ? unsafeHTML(tag) : tag}
-        </div>`;
+        if (!tag) return null;
+        return typeof tag === 'string' ? unsafeHTML(tag) : tag;
       } else if (index === this.maxOptionsVisible) {
         // Hit tag limit
         return html`
@@ -726,7 +746,7 @@ export default class WaSelect extends WebAwesomeFormAssociatedElement {
           >
         `;
       }
-      return html``;
+      return null;
     });
   }
 
@@ -926,7 +946,9 @@ export default class WaSelect extends WebAwesomeFormAssociatedElement {
               />
 
               <!-- Tags need to wait for first hydration before populating otherwise it will create a hydration mismatch. -->
-              ${this.multiple && this.hasUpdated ? html`<div part="tags" class="tags">${this.tags}</div>` : ''}
+              ${this.multiple && this.hasUpdated
+                ? html`<div part="tags" class="tags" @wa-remove=${this.handleTagRemove}>${this.tags}</div>`
+                : ''}
 
               <input
                 class="value-input"

src/styles/native/details.css

@@ -2,10 +2,12 @@ details:where(:not(:host *)),
 :host {
   --icon-color: var(--wa-color-text-quiet);
   --spacing: var(--wa-space-m);
+  --outlined-border-color: var(--wa-color-surface-border);
 
-  background-color: var(--wa-color-surface-default);
-  border: var(--wa-panel-border-width) var(--wa-color-surface-border) var(--wa-panel-border-style);
+  background-color: var(--background-color, var(--wa-color-surface-default));
+  border: var(--wa-panel-border-width) var(--border-color, var(--wa-color-surface-border)) var(--wa-panel-border-style);
   border-radius: var(--wa-panel-border-radius);
+  color: var(--text-color, inherit);
   padding: var(--spacing);
 
   /* Print styles */
@@ -19,6 +21,12 @@ details:where(:not(:host *)),
   }
 }
 
+details.wa-plain,
+:host(wa-details[appearance='plain']),
+:host(wa-details.wa-plain) {
+  border-radius: 0;
+}
+
 details:where(:not(:host *)) summary,
 :host summary /* nesting these summary styles in the rule above breaks in Firefox and Safari */ {
   display: flex;

src/styles/themes/active/color.css

@@ -80,8 +80,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   /**
    * Foundational Colors
    */

src/styles/themes/awesome/color.css

@@ -71,8 +71,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   color-scheme: dark;
   color: var(--wa-color-text-normal);
 

src/styles/themes/brutalist/color.css

@@ -78,8 +78,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   color-scheme: dark;
   color: var(--wa-color-text-normal);
 

src/styles/themes/classic/color.css

@@ -68,8 +68,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   /**
    * Foundational Colors
    */

src/styles/themes/default/color.css

@@ -114,10 +114,8 @@
   --wa-color-neutral-on-loud: white;
 }
 
-/** need to wrap :host-context() in an :is() selector for unsupported browsers */
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   color-scheme: dark;
   color: var(--wa-color-text-normal);
 

src/styles/themes/matter/color.css

@@ -85,8 +85,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   /**
    * Foundational Colors
    */

src/styles/themes/mellow/color.css

@@ -83,8 +83,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   /**
    * Foundational Colors
    */

src/styles/themes/playful/color.css

@@ -75,8 +75,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   /**
    * Foundational Colors
    */

src/styles/themes/premium/color.css

@@ -74,8 +74,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   /**
    * Foundational Colors
    */

src/styles/themes/tailspin/color.css

@@ -84,8 +84,7 @@
 }
 
 .wa-dark,
-.wa-invert,
-:is(:host-context(.wa-dark)) {
+.wa-invert {
   /**
    * Foundational Colors
    */

src/styles/themes/tailspin/overrides.css

@@ -1,7 +1,6 @@
 :where(:root),
 :host,
-.wa-theme-tailspin,
-:is(:host-context(.wa-theme-tailspin)) {
+.wa-theme-tailspin {
   h1,
   h2,
   h3,

src/styles/utilities/fouce.css

@@ -1,20 +1,17 @@
 /*
  * Utility to minimize FOUCE and show custom elements only after they're registered
  */
+:not(:defined),
+:state(wa-defined):has(:not(:defined)),
+.wa-cloak:has(:not(:defined)) {
+  animation: 2s step-end wa-fouce-cloak;
+}
 
-@keyframes wa-fade-in {
+@keyframes wa-fouce-cloak {
   from {
     opacity: 0;
   }
-}
-
-:not(:defined),
-:state(wa-defined):has(:not(:defined)) {
-  /* The clamp() ensures that if --wa-fouce-timeout is set to 0s, the whole effect is disabled */
-  --wa-fouce-animation: clamp(0s, var(--wa-fouce-fade, 200ms), var(--wa-fouce-timeout, 2s)) var(--wa-fouce-timeout, 2s)
-    wa-fade-in both;
-
-  &:where(:not([did-ssr], .wa-fouce-off, .wa-fouce-off *)) {
-    animation: var(--wa-fouce-animation);
+  to {
+    opacity: 1;
   }
 }

src/utilities/autoloader.ts

@@ -50,6 +50,12 @@ export async function discover(root: Element | ShadowRoot) {
       console.warn(imp.reason); // eslint-disable-line no-console
     }
   }
+
+  // Wait a cycle to allow the first Lit update to run
+  await new Promise(requestAnimationFrame);
+
+  // Dispatch an event when discovery is complete.
+  document.dispatchEvent(new CustomEvent('wa-discovery-complete'));
 }
 
 /**
@@ -69,3 +75,22 @@ function register(tagName: string): Promise<void> {
     import(path).then(() => resolve()).catch(() => reject(new Error(`Unable to autoload <${tagName}> from ${path}`)));
   });
 }
+
+/**
+ * Acts as a middleware for Turbo's `turbo:before-render` event to ensure components are auto-loaded before showing the
+ * next page, eliminating page-to-page FOUCE in a Turbo environment.
+ */
+export function preventTurboFouce(timeout = 2000) {
+  document.addEventListener('turbo:before-render', async (event: CustomEvent) => {
+    const newBody = event.detail.newBody;
+
+    event.preventDefault();
+
+    try {
+      // Wait until all elements are registered or two seconds, whichever comes first
+      await Promise.race([discover(newBody), new Promise(resolve => setTimeout(resolve, timeout))]);
+    } finally {
+      event.detail.resume();
+    }
+  });
+}

src/utilities/defined.ts

@@ -0,0 +1,64 @@
+interface AllDefinedOptions {
+  /**
+   * A callback that accepts a custom element tag name and returns `true` if the custom element should be defined before
+   * resolving or `false` to skip it. The tag name is always in lowercase.
+   */
+  match: (tagName: string) => boolean;
+
+  /**
+   * To wait for additional custom elements that may not be on the page when the function is called, provide them here.
+   */
+  additionalElements: string | string[];
+
+  /**
+   * The root in which to look for custom elements. Defaults to `document`. By design, shadow roots are not traversed,
+   * but you can call this function and set `root` to a custom element's shadow root if needed.
+   */
+  root: Document | ShadowRoot;
+}
+
+/**
+ * Waits for custom elements that are currently on the page to be registered before resolving. This is sugar for
+ * awaiting `customElements.whenDefined()` multiple times. By default, the function waits for all undefined Web Awesome
+ * elements, but you can pass a custom match function to wait for other custom elements instead.
+ *
+ * The function returns with `Promise.all()`, so any loading errors will cause it to reject. Make sure you handle errors
+ * accordingly using a try/catch block or a `.catch()`.
+ *
+ * @example
+ * // Wait for Web Awesome elements
+ * await allDefined();
+ *
+ * // Wait for all custom elements that start with `foo-` as well as the `<bar-button>` element
+ * await allDefined({
+ *   match: tagName => tagName.startsWith('foo-'),
+ *   additionalElements: ['bar-button', 'baz-dialog']
+ * });
+ */
+export async function allDefined(options?: Partial<AllDefinedOptions>) {
+  const opts: AllDefinedOptions = {
+    match: tagName => tagName.startsWith('wa-'),
+    additionalElements: [],
+    root: document,
+    ...options,
+  };
+
+  // Ensure additional elements is an array
+  const additionalElements = Array.isArray(opts.additionalElements)
+    ? opts.additionalElements
+    : [opts.additionalElements];
+
+  // Discover undefined elements in the document
+  const undefinedElements = [...opts.root.querySelectorAll(':not(:defined)')]
+    .map(el => el.localName)
+    .filter((tag, index, arr) => arr.indexOf(tag) === index) // make it unique
+    .filter(tag => opts.match(tag)); // make sure it matches
+
+  const tagsToAwait = [...undefinedElements, ...additionalElements];
+
+  // Wait for all to be registered
+  await Promise.all(tagsToAwait.map(tag => customElements.whenDefined(tag)));
+
+  // Wait a cycle for the first update
+  await new Promise(requestAnimationFrame);
+}

src/webawesome.ts

@@ -1,6 +1,7 @@
 export { registerIconLibrary, unregisterIconLibrary } from './components/icon/library.js';
-export { discover, startLoader, stopLoader } from './utilities/autoloader.js';
+export { discover, preventTurboFouce, startLoader, stopLoader } from './utilities/autoloader.js';
 export { getBasePath, getKitCode, setBasePath, setKitCode } from './utilities/base-path.js';
+export { allDefined } from './utilities/defined.js';
 export { registerTranslation } from './utilities/localize.js';
 
 // Utilities

web-test-runner.config.js

@@ -1,4 +1,3 @@
-import { litSsrPlugin } from '@lit-labs/testing/web-test-runner-ssr-plugin.js';
 import { esbuildPlugin } from '@web/dev-server-esbuild';
 import { playwrightLauncher } from '@web/test-runner-playwright';
 import { readFileSync } from 'fs';
@@ -53,7 +52,6 @@ export default {
       ts: true,
       target: 'es2020',
     }),
-    litSsrPlugin(),
   ],
   browsers: [
     playwrightLauncher({ product: 'chromium', concurrency }),
@@ -78,12 +76,10 @@ export default {
             ${componentImports.map(str => `"${str}"`).join(',\n')}
           ]
 
-          window.SSR_ONLY = ${process.env['SSR_ONLY'] === 'true'}
           window.CSR_ONLY = ${process.env['CSR_ONLY'] === 'true'}
         </script>
         <script type="module">
           ;(async () => {
-            await import('@lit-labs/ssr-client/lit-element-hydrate-support.js')
             await Promise.allSettled(window.clientComponents.map(str => import(str)));
           })()
         </script>