Merge branch 'next' into support-fa-kit-custom-icons

* initial commit to this pr

* updated patterns

* category lists

* post headers

* WIP

* made some content updates

* deleted rogue file

* updated descriptions

* ran prettier

* updated padding

* updated prettierignore

* updated element

* swtiched to token

* updated with category list feedback

* updated with category list feedback

* updated with feedback for featurd post

* updated with feedback for footer

* updated with newsletter feedback'

* updated with feedback to the paywall

* updated with updates for post footer

* more footer updates

* updated with feedback for the post header

* updated with feedback for post list

* updated social share

* updated sign up and login

* added logic to elements to prevent them from closing on escape

* Fix typo (incomplete `<h2>` tag)

* Add missing input labels, fix capitalization and punctuation

* Add description to Blog & News index

* ran prettier on markdown files

* ignored the post list file

* changed hierarchy

---------

Co-authored-by: Cory LaViska <cory@abeautifulsite.net>
Co-authored-by: lindsaym-fa <dev@lindsaym.design>

.github/workflows/client_tests.js.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Lint
         run: npm run prettier
       - name: Build
-        run: npm run build:alpha
+        run: npm run build
       - name: Install Playwright
         run: npx playwright install --with-deps
       - name: Run CSR tests

.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:
@@ -30,7 +31,7 @@ jobs:
         run: npm run prettier
 
       - name: Build
-        run: npm run build:alpha
+        run: npm run build
 
       - name: Install Playwright
         run: npx playwright install --with-deps

.prettierignore

@@ -1,5 +1,7 @@
 *.hbs
 *.md
+!docs/docs/patterns/**/*.md
+docs/docs/patterns/blog-news/post-list.md
 .cache
 .github
 cspell.json

cspell.json

@@ -148,6 +148,7 @@
     "scrollbars",
     "scrollend",
     "scroller",
+    "Scrollers",
     "Segoe",
     "semibold",
     "shadowrootmode",

docs/.eleventy.js

@@ -5,11 +5,11 @@ import { copyCodePlugin } from './_utils/copy-code.js';
 import { currentLink } from './_utils/current-link.js';
 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';
@@ -21,14 +21,11 @@ import * as url from 'url';
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
 
 const packageData = JSON.parse(await readFile(path.join(__dirname, '..', 'package.json'), 'utf-8'));
-const isAlpha = process.argv.includes('--alpha');
 const isDev = process.argv.includes('--develop');
 
 const globalData = {
   package: packageData,
-  isAlpha,
   layout: 'page.njk',
-
   server: {
     head: '',
     loginOrAvatar: '',
@@ -36,19 +33,20 @@ const globalData = {
   },
 };
 
-const passThroughExtensions = ['js', 'css', 'png', 'svg', 'jpg', 'mp4'];
-const passThrough = [...passThroughExtensions.map(ext => 'docs/**/*.' + ext)];
-
 export default function (eleventyConfig) {
-  // NOTE - alpha setting removes certain pages
-  if (isAlpha) {
-    eleventyConfig.ignores.add('**/experimental/**');
-    eleventyConfig.ignores.add('**/layout/**');
-    eleventyConfig.ignores.add('**/patterns/**');
-    eleventyConfig.ignores.add('**/style-utilities/**');
-    eleventyConfig.ignores.add('**/components/code-demo.md');
-    eleventyConfig.ignores.add('**/components/viewport-demo.md');
-  }
+  /**
+   * If you plan to add or remove any of these extensions, make sure to let either Konnor or Cory know as these passthrough extensions
+   * will also need to be updated in the Web Awesome App.
+   */
+  const passThroughExtensions = ['js', 'css', 'png', 'svg', 'jpg', 'mp4'];
+
+  const baseDir = process.env.BASE_DIR || 'docs';
+  const passThrough = [...passThroughExtensions.map(ext => path.join(baseDir, '**/*.' + ext))];
+
+  /**
+   * 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';
 
   // Add template data
   for (let name in globalData) {
@@ -68,9 +66,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 %}
@@ -78,9 +102,6 @@ export default function (eleventyConfig) {
 
   // Helpers
 
-  // Remove elements that have [data-alpha="remove"]
-  eleventyConfig.addPlugin(removeDataAlphaElements({ isAlpha }));
-
   // Use our own markdown instance
   eleventyConfig.setLibrary('md', markdown);
 
@@ -132,29 +153,14 @@ 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.addPreprocessor('unpublished', '*', (data, content) => {
+    if (data.unpublished && process.env.ELEVENTY_RUN_MODE === 'build') {
+      // Exclude "unpublished" pages from final builds.
+      return false;
+    }
 
-    eleventyConfig.addPlugin(litPlugin, {
-      mode: 'worker',
-      componentModules,
-    });
-  }
+    return content;
+  });
 
   // Build the search index
   eleventyConfig.addPlugin(
@@ -182,6 +188,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/_data/hueRanges.js

@@ -1 +1 @@
-export { hueRanges as default } from '../assets/scripts/tweak/data.js';
+export { hueRanges as default } from '../assets/data/index.js';

docs/_includes/base.njk

@@ -1,10 +1,9 @@
 <!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">
 
-    <script type="module" src="/assets/scripts/code-examples.js"></script>
 
     <script type="module" src="/assets/scripts/scroll.js"></script>
     <script type="module" src="/assets/scripts/turbo.js"></script>
@@ -20,7 +19,7 @@
   </head>
   <body class="layout-{{ layout | stripExtension }}{{ ' page-wide' if wide }}">
     <!-- use view="desktop" as default to reduce layout jank on desktop site. -->
-    <wa-page view="desktop" disable-navigation-toggle="">
+    <wa-page view="desktop" disable-navigation-toggle="" mobile-breakpoint="1140">
       <header slot="header" class="wa-split">
         {# Logo #}
         <div id="docs-branding">
@@ -33,13 +32,13 @@
             <span class="wa-desktop-only">{% include "logo.njk" %}</span>
             <span class="wa-mobile-only">{% include "logo-simple.njk" %}</span>
           </a>
-          <small id="version-number" class="only-desktop">{{ package.version }}</small>
-          <wa-badge variant="warning" appearance="filled" class="only-desktop">Alpha</wa-badge>
+          <small id="version-number" class="wa-desktop-only">{{ package.version }}</small>
+          <wa-badge variant="warning" appearance="filled" class="wa-desktop-only">Alpha</wa-badge>
         </div>
 
         <div id="docs-toolbar" class="wa-cluster wa-gap-xs">
           {# Desktop selectors #}
-          <div class="only-desktop wa-cluster wa-gap-xs">
+          <div class="wa-desktop-only wa-cluster wa-gap-xs">
             {% include "preset-theme-selector.njk" %}
             {% include "color-scheme-selector.njk" %}
           </div>
@@ -48,7 +47,7 @@
           <wa-button id="search-trigger" appearance="outlined" size="small" data-search>
             <wa-icon slot="prefix" name="magnifying-glass"></wa-icon>
             Search
-            <kbd slot="suffix" class="only-desktop">/</kbd>
+            <kbd slot="suffix" class="wa-desktop-only">/</kbd>
           </wa-button>
 
           {# Login #}

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

@@ -1,7 +1,7 @@
 <meta charset="UTF-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="description" content="{{ description }}">
-{% if noindex %}<meta name="robots" content="noindex">{% endif %}
+{% if noindex or unlisted %}<meta name="robots" content="noindex">{% endif %}
 
 <title>{{ title }}</title>
 
@@ -23,14 +23,17 @@
 <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>
+
+{# Internal components #}
+<script type="module" src="/assets/components/scoped.js"></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 #}
-{% if forceTheme %}
+{% if noTheme %}
+{% elif forceTheme %}
 <link id="theme-stylesheet" rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/{{ forceTheme }}.css" render="blocking" fetchpriority="high" />
 {% else %}
 <noscript><link id="theme-stylesheet" rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/default.css" render="blocking" fetchpriority="high" /></noscript>
@@ -48,6 +51,5 @@
 <link id="color-stylesheet" rel="stylesheet" href="/dist/styles/utilities.css" />
 <link rel="stylesheet" href="/dist/styles/forms.css" />
 
-
 {# Used by Web Awesome App to inject other assets into the head. #}
 {% server "head" %}

docs/_includes/page-card.njk

@@ -1,13 +1,13 @@
 {%- if not page.data.unlisted -%}
-<a href="{{ page.url }}"{{ page.data.keywords | attr('data-keywords') }}>
+{% if page.url %}<a href="{{ page.url }}"{{ page.data.keywords | attr('data-keywords') }}>{% endif %}
 	<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 -%}
 		<div class="wa-caption-s">{{ pageSubtitle }}</div>
 		{%- endif %}
 	</wa-card>
-</a>
+{% if page.url %}</a>{% endif %}
 {% endif %}

docs/_includes/preset-theme-selector.njk

@@ -2,7 +2,7 @@
 <wa-select appearance="filled" size="small" value="default" pill class="preset-theme-selector">
   <wa-icon slot="prefix" name="paintbrush" variant="regular"></wa-icon>
   {% for theme in collections.theme | sort %}
-    <wa-option value="{{ theme.page.fileSlug }}"{{ ' data-alpha="remove"' if theme.noAlpha }}>
+    <wa-option value="{{ theme.page.fileSlug }}">
       {{ theme.data.title }}
     </wa-option>
   {% endfor %}

docs/_includes/search.njk

@@ -1,4 +1,4 @@
-<wa-dialog id="site-search" no-header light-dismiss>
+<wa-dialog id="site-search" without-header light-dismiss>
   <div id="site-search-container">
     {# Header #}
     <header>

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 -%}
 	<li>
 		<a href="{{ page.url }}">{{ page.data.title }}</a>
 		{% if page.data.status == 'experimental' %}<wa-icon name="flask"></wa-icon>{% endif %}

docs/_includes/sidebar.njk

@@ -1,7 +1,7 @@
 {# Getting started #}
 <h2>Getting Started</h2>
 <ul>
-  <li><a href="/docs/installation">Installation</a></li>
+  <li><a href="/docs/">Installation</a></li>
   <li><a href="/docs/usage">Usage</a></li>
   <li><a href="/docs/customizing">Customizing</a></li>
   <li><a href="/docs/form-controls">Form Controls</a></li>

docs/_includes/svgs/action-panel.njk

@@ -0,0 +1,8 @@
+<svg width="96" height="57" viewBox="0 0 96 57" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M12 1H84C90.0751 1 95 5.92487 95 12V45C95 51.0751 90.0751 56 84 56H12C5.92487 56 1 51.0751 1 45V12C1 5.92487 5.92487 1 12 1Z" fill="white" stroke="#E4E5E9" stroke-width="2"/>
+<rect x="7" y="39" width="50" height="11" rx="4" fill="#4895FD"/>
+<rect x="7" y="8" width="41" height="5" fill="#616D8A"/>
+<rect x="7" y="19.75" width="76" height="3" fill="#D9D9D9"/>
+<rect x="7" y="25" width="76" height="3" fill="#D9D9D9"/>
+<rect x="7" y="32" width="76" height="3" fill="#D9D9D9"/>
+</svg>

docs/_includes/svgs/call-to-action.njk

@@ -0,0 +1,3 @@
+<svg width="72" height="72" viewBox="0 0 72 72" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M63 6.32811V61.3125C63 66.375 56.6719 68.9062 53.2969 65.25L49.9219 61.7344C43.7344 55.2656 35.7188 51.1875 27 50.0625V64.125C27 68.4844 23.3438 72 19.125 72H16.875C12.5156 72 9 68.4844 9 64.125V49.5C3.9375 49.5 0 45.5625 0 40.5V27C0 22.0781 3.9375 18 9 18H20.1094L24.1875 17.8594C34.0312 17.2969 43.1719 13.0781 49.9219 5.90624L53.2969 2.39061C56.6719 -1.26564 63 1.12499 63 6.32811ZM22.5 49.6406L20.1094 49.5H13.5V64.125C13.5 66.0937 14.9062 67.5 16.875 67.5H19.125C20.9531 67.5 22.5 66.0937 22.5 64.125V49.6406ZM56.5312 5.48436L53.1562 8.99999C47.25 15.1875 39.6562 19.5469 31.5 21.375V46.2656C39.6562 48.0937 47.25 52.3125 53.1562 58.6406L56.5312 62.1562C57.2344 62.8594 58.5 62.2969 58.5 61.3125V6.32811C58.5 5.20311 57.2344 4.78124 56.5312 5.48436ZM27 22.0781C26.1562 22.2187 25.3125 22.3594 24.4688 22.3594L20.25 22.5H9C6.46875 22.5 4.5 24.6094 4.5 27V40.5C4.5 43.0312 6.46875 45 9 45H20.25L24.4688 45.2812C25.3125 45.4219 26.1562 45.4219 27 45.5625V22.0781ZM69.75 27C70.875 27 72 28.125 72 29.25V38.25C72 39.5156 70.875 40.5 69.75 40.5C68.4844 40.5 67.5 39.5156 67.5 38.25V29.25C67.5 28.125 68.4844 27 69.75 27Z" fill="var(--wa-color-neutral-on-quiet"/>
+</svg>

docs/_includes/svgs/category-list.njk

@@ -0,0 +1,10 @@
+<svg width="96" height="57" viewBox="0 0 96 57" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M12 1H84C90.0751 1 95 5.92487 95 12V45C95 51.0751 90.0751 56 84 56H12C5.92487 56 1 51.0751 1 45V12C1 5.92487 5.92487 1 12 1Z" fill="var(--wa-color-surface-default)" stroke="var(--wa-color-surface-border)" stroke-width="2"/>
+<rect x="7" y="8" width="41" height="5" fill="var(--wa-color-neutral-on-quiet)"/>
+<rect x="7" y="19" width="23" height="14" rx="3" fill="var(--wa-color-neutral-fill-normal)"/>
+<rect x="35" y="19" width="23" height="14" rx="3" fill="var(--wa-color-neutral-fill-normal)"/>
+<rect x="63" y="19" width="23" height="14" rx="3" fill="var(--wa-color-neutral-fill-normal)"/>
+<rect x="7" y="36" width="23" height="14" rx="3" fill="var(--wa-color-neutral-fill-normal)"/>
+<rect x="35" y="36" width="23" height="14" rx="3" fill="var(--wa-color-neutral-fill-normal)"/>
+<rect x="63" y="36" width="23" height="14" rx="3" fill="var(--wa-color-neutral-fill-normal)"/>
+</svg>

docs/_includes/svgs/palette.njk

@@ -1,31 +1,20 @@
 {% set paletteId = palette.fileSlug or page.fileSlug %}
 {% set suffixes = ['-80', '', '-20'] %}
-{% set width = 20 %}
-{% set height = 12 %}
-{% set height_core = 20 %}
-{% set gap_x = 4 %}
-{% set gap_y = 4 %}
 
-{% set total_width = (width + gap_x) * hues|length %}
-{% set total_height = (height + gap_y) * suffixes|length + (height_core - height) %}
-<svg viewBox="0 0 {{ total_width }} {{ total_height }}" fill="none" xmlns="http://www.w3.org/2000/svg" class="wa-palette-{{ paletteId }} palette-icon">
-<style>
-	@import url('/dist/styles/color/{{ paletteId }}.css') layer(palette.{{ paletteId }});
-	.palette-icon {
-		height: 8ch;
-	}
-</style>
+<wa-scoped class="palette-icon-host">
+  <template>
+    <link rel="stylesheet" href="/dist/styles/color/{{ paletteId }}.css">
+    <link rel="stylesheet" href="/assets/styles/theme-icons.css">
 
-{% for hue in hues -%}
-  {% set hueIndex = loop.index0 %}
-  {% set y = 0 %}
-  {% for suffix in suffixes -%}
-    {% set swatch_height = height if suffix else height_core %}
-
-    <rect x="{{ hueIndex * (width + gap_x) }}" y="{{ y }}"
-	      width="{{ width }}" height="{{ swatch_height }}"
-	      fill="var(--wa-color-{{ hue }}{{ suffix }})" rx="2" />
-	{% set y = y + swatch_height + gap_y %}
-  {%- endfor %}
-{% endfor %}
-</svg>
+    <div class="palette-icon" style="--hues: {{ hues|length }}; --suffixes: {{ suffixes|length }}">
+      {% for hue in hues -%}
+        {% set hueIndex = loop.index %}
+        {% for suffix in suffixes -%}
+          <div class="swatch"
+               data-hue="{{ hue }}" data-suffix="{{ suffix }}"
+               style="--color: var(--wa-color-{{ hue }}{{ suffix }}); grid-column: {{ hueIndex }}; grid-row: {{ loop.index }}">&nbsp;</div>
+        {%- endfor %}
+      {%- endfor %}
+    </div>
+  </template>
+</wa-scoped>

docs/_includes/svgs/preview.njk

@@ -0,0 +1,10 @@
+<svg width="120" height="87" viewBox="0 0 240 178" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect y="39" width="67" height="63" rx="12" fill="#D9D9D9"/>
+<rect y="115" width="67" height="63" rx="12" fill="#D9D9D9"/>
+<rect width="67" height="19" rx="6" fill="#D9D9D9"/>
+<rect x="87" y="39" width="67" height="63" rx="12" fill="#D9D9D9"/>
+<rect x="174" y="39" width="67" height="63" rx="12" fill="#D9D9D9"/>
+<rect x="174" y="7" width="67" height="4.75" rx="2.375" fill="#D9D9D9"/>
+<rect x="87" y="115" width="67" height="63" rx="12" fill="#D9D9D9"/>
+<rect x="174" y="115" width="67" height="63" rx="12" fill="#D9D9D9"/>
+</svg>

docs/_includes/svgs/scroller.njk

@@ -0,0 +1,31 @@
+<svg width="96" height="64" viewBox="0 0 96 64" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M12 1H84C90.0751 1 95 5.92487 95 12V52C95 58.0751 90.0751 63 84 63H12C5.92487 63 1 58.0751 1 52V12C1 5.92487 5.92487 1 12 1Z" fill="var(--wa-color-surface-default)"/>
+<path d="M12 1H84C90.0751 1 95 5.92487 95 12V52C95 58.0751 90.0751 63 84 63H12C5.92487 63 1 58.0751 1 52V12C1 5.92487 5.92487 1 12 1Z" stroke="var(--wa-color-surface-border)" stroke-width="2"/>
+<rect x="12" y="12" width="24" height="4" rx="2" fill="var(--wa-color-neutral-fill-quiet)"/>
+<rect x="12" y="21" width="24" height="4" rx="2" fill="var(--wa-color-neutral-fill-quiet)"/>
+<rect x="12" y="30" width="24" height="4" rx="2" fill="var(--wa-color-neutral-fill-quiet)"/>
+<rect x="44" y="12" width="24" height="4" rx="2" fill="var(--wa-color-neutral-fill-quiet)"/>
+<rect x="44" y="21" width="24" height="4" rx="2" fill="var(--wa-color-neutral-fill-quiet)"/>
+<rect x="44" y="30" width="24" height="4" rx="2" fill="var(--wa-color-neutral-fill-quiet)"/>
+<rect x="76" y="12" width="20" height="4" rx="2" fill="url(#paint0_linear_302_2)"/>
+<rect x="76" y="21" width="20" height="4" rx="2" fill="url(#paint1_linear_302_2)"/>
+<rect x="76" y="30" width="20" height="4" rx="2" fill="url(#paint2_linear_302_2)"/>
+<rect x="4" y="44" width="88" height="16" rx="8" fill="var(--wa-color-neutral-fill-normal)"/>
+<path d="M85.8438 51.6562C86.0469 51.8438 86.0469 52.1719 85.8438 52.3594L82.8438 55.3594C82.6562 55.5625 82.3281 55.5625 82.1406 55.3594C81.9375 55.1719 81.9375 54.8438 82.1406 54.6562L84.7812 52L82.1406 49.3594C81.9375 49.1719 81.9375 48.8438 82.1406 48.6562C82.3281 48.4531 82.6562 48.4531 82.8438 48.6562L85.8438 51.6562Z" fill="var(--wa-color-neutral-border-loud)"/>
+<path d="M10.1406 51.6562L13.1406 48.6562C13.3281 48.4531 13.6562 48.4531 13.8438 48.6562C14.0469 48.8438 14.0469 49.1719 13.8438 49.3594L11.2031 52L13.8438 54.6562C14.0469 54.8438 14.0469 55.1719 13.8438 55.3594C13.6562 55.5625 13.3281 55.5625 13.1406 55.3594L10.1406 52.3594C9.9375 52.1719 9.9375 51.8438 10.1406 51.6562Z" fill="var(--wa-color-neutral-border-loud)"/>
+<path d="M20 52C20 49.7909 21.7909 48 24 48H48C50.2091 48 52 49.7909 52 52V52C52 54.2091 50.2091 56 48 56H24C21.7909 56 20 54.2091 20 52V52Z" fill="var(--wa-color-neutral-border-loud)"/>
+<defs>
+<linearGradient id="paint0_linear_302_2" x1="76" y1="14" x2="96" y2="14" gradientUnits="userSpaceOnUse">
+<stop offset="0.533654" stop-color="var(--wa-color-neutral-fill-quiet)"/>
+<stop offset="1" stop-color="var(--wa-color-neutral-fill-quiet)" stop-opacity="0"/>
+</linearGradient>
+<linearGradient id="paint1_linear_302_2" x1="76" y1="23" x2="96" y2="23" gradientUnits="userSpaceOnUse">
+<stop offset="0.533654" stop-color="var(--wa-color-neutral-fill-quiet)"/>
+<stop offset="1" stop-color="var(--wa-color-neutral-fill-quiet)" stop-opacity="0"/>
+</linearGradient>
+<linearGradient id="paint2_linear_302_2" x1="76" y1="32" x2="96" y2="32" gradientUnits="userSpaceOnUse">
+<stop offset="0.533654" stop-color="var(--wa-color-neutral-fill-quiet)"/>
+<stop offset="1" stop-color="var(--wa-color-neutral-fill-quiet)" stop-opacity="0"/>
+</linearGradient>
+</defs>
+</svg>

docs/_includes/svgs/theme-color.njk

@@ -1,13 +1,13 @@
 {% set themeId = theme.fileSlug %}
 
-<div>
-  <template shadowrootmode="open">
+<wa-scoped class="theme-icon-host theme-color-icon-host">
+  <template>
     <link rel="stylesheet" href="/dist/styles/utilities.css">
     <link rel="stylesheet" href="/dist/styles/themes/{{ page.fileSlug or 'default' }}.css">
     <link rel="stylesheet" href="/dist/styles/themes/{{ themeId }}/color.css">
     <link rel="stylesheet" href="/assets/styles/theme-icons.css">
 
-    <div class="theme-color-icon wa-theme-{{ themeId }}">
+    <div class="theme-icon theme-color-icon wa-theme-{{ themeId }}">
       <div class="wa-brand wa-accent">A</div>
       <div class="wa-brand wa-outlined">A</div>
       <div class="wa-brand wa-filled">A</div>
@@ -21,4 +21,4 @@
       {# <div class="wa-warning wa-outlined wa-filled"><wa-icon slot="icon" name="triangle-exclamation" variant="regular"></wa-icon></div> #}
     </div>
   </template>
-</div>
+</wa-scoped>

docs/_includes/svgs/theme-typography.njk

@@ -1,16 +1,16 @@
-{% set themeId = theme.fileSlug %}
+{% set themeId = theme.fileSlug or page.fileSlug %}
 
-<div>
-  <template shadowrootmode="open">
+<wa-scoped class="theme-icon-host theme-typography-icon-host">
+  <template>
     <link rel="stylesheet" href="/dist/styles/native/content.css">
     <link rel="stylesheet" href="/dist/styles/native/blockquote.css">
     <link rel="stylesheet" href="/dist/styles/themes/{{ page.fileSlug or 'default' }}.css">
     <link rel="stylesheet" href="/dist/styles/themes/{{ themeId }}/typography.css">
     <link rel="stylesheet" href="/assets/styles/theme-icons.css">
 
-    <div class="theme-typography-icon wa-theme-{{ themeId }}" data-no-outline data-no-anchor role="presentation">
+    <div class="theme-icon theme-typography-icon wa-theme-{{ themeId }}" data-no-outline data-no-anchor role="presentation">
       <h3>Title</h3>
       <p>Body text</p>
     </div>
   </template>
-</div>
+</wa-scoped>

docs/_includes/svgs/theme.njk

@@ -0,0 +1,29 @@
+{% set themeId = theme.fileSlug or page.fileSlug %}
+
+
+<wa-scoped class="theme-icon-host theme-overall-icon-host">
+  <template>
+    <link rel="stylesheet" href="/dist/styles/utilities.css">
+    <link rel="stylesheet" href="/dist/styles/native/content.css">
+    <link rel="stylesheet" href="/dist/styles/themes/{{ themeId }}.css">
+    <link rel="stylesheet" href="/assets/styles/theme-icons.css">
+
+    <div class="theme-icon theme-overall-icon" role="presentation" data-no-anchor data-no-outline>
+      <div class="row row-1">
+        <h2>Aa</h2>
+        <div class="swatches">
+          <div class="wa-brand"></div>
+
+          <div class="wa-success"></div>
+          <div class="wa-warning"></div>
+          <div class="wa-danger"></div>
+          <div class="wa-neutral"></div>
+        </div>
+      </div>
+      <div class="row row-2">
+        <wa-input value="Input" size="small" inert></wa-input>
+        <wa-button size="small" variant="brand" inert>Go</wa-button>
+      </div>
+    </div>
+  </template>
+</wa-scoped>

docs/_includes/theme-showcase.njk

@@ -1,14 +1,14 @@
 <div class="showcase-examples-wrapper" aria-hidden="true" data-no-outline>
   <div class="showcase-examples">
-    <wa-card with-header with-footer>
+    <wa-card>
       <div slot="header" class="wa-split">
         <h3 class="wa-heading-m">Your Cart</h3>
         <wa-icon-button name="xmark" tabindex="-1"></wa-icon-button>
       </div>
       <div class="wa-stack wa-gap-xl">
         <div class="wa-flank">
-          <wa-avatar shape="rounded" style="--size: 3em; --background-color: var(--wa-color-green-60); --text-color: var(--wa-color-green-95);">
-            <wa-icon slot="icon" name="sword-laser" family="duotone" style="font-size: 1.5em;"></wa-icon>
+          <wa-avatar shape="rounded" style="--background-color: var(--wa-color-green-60); --text-color: var(--wa-color-green-95);">
+            <wa-icon slot="icon" name="sword-laser"></wa-icon>
           </wa-avatar>
           <div class="wa-stack wa-gap-2xs">
             <div class="wa-split wa-gap-2xs">
@@ -23,8 +23,8 @@
         </div>
         <wa-divider></wa-divider>
         <div class="wa-flank">
-          <wa-avatar shape="rounded" style="--size: 3em; --background-color: var(--wa-color-cyan-60); --text-color: var(--wa-color-cyan-95);">
-            <wa-icon slot="icon" name="robot-astromech" family="duotone" style="font-size: 1.5em;"></wa-icon>
+          <wa-avatar shape="rounded" style="--background-color: var(--wa-color-cyan-60); --text-color: var(--wa-color-cyan-95);">
+            <wa-icon slot="icon" name="robot-astromech"></wa-icon>
           </wa-avatar>
           <div class="wa-stack wa-gap-2xs">
             <div class="wa-split wa-gap-2xs">
@@ -52,7 +52,7 @@
     </wa-card>
     <wa-card>
       <wa-avatar shape="rounded" style="--size: 1.9lh; float: left; margin-right: var(--wa-space-m);">
-        <wa-icon slot="icon" name="hat-wizard" family="duotone" style="font-size: 1.75em;"></wa-icon>
+        <wa-icon slot="icon" name="hat-wizard" style="font-size: 1.75em;"></wa-icon>
       </wa-avatar>
       <p class="wa-body-l" style="margin: 0;">&ldquo;All we have to decide is what to do with the time that is given to us. There are other forces at work in this world, Frodo, besides the will of evil.&rdquo;</p>
     </wa-card>
@@ -69,7 +69,7 @@
         <a href="#" tabindex="-1" class="wa-body-s">I forgot my password</a>
       </div>
     </wa-card>
-    <wa-card with-footer>
+    <wa-card>
       <div class="wa-stack">
         <div class="wa-split">
           <h3 class="wa-heading-m">To-Do</h3>
@@ -140,5 +140,196 @@
         </div>
       </div>
     </wa-card>
+    <wa-card>
+      <div class="wa-stack">
+        <div class="wa-flank:end">
+          <h3 id="odds-label" class="wa-heading-m">Tell Me the Odds</h3>
+          <wa-switch size="large" aria-labelledby="odds-label"></wa-switch>
+        </div>
+        <p class="wa-body-s">Allow protocol droids to inform you of probabilities, such as the success rate of navigating an asteroid field. We recommend setting this to "Never."</p>
+      </div>
+    </wa-card>
+    <wa-card>
+      <div class="wa-stack">
+        <div class="wa-split wa-align-items-start">
+          <dl class="wa-stack wa-gap-2xs">
+            <dt class="wa-heading-s">Amount</dt>
+            <dd class="wa-heading-l">$5,610.00</dd>
+          </dl>
+          <wa-badge appearance="filled outlined" variant="success">Paid</wa-badge>
+        </div>
+        <wa-divider></wa-divider>
+        <dl class="wa-stack">
+          <div class="wa-flank wa-align-items-center">
+            <dt><wa-icon name="user" label="Name" fixed-width></wa-icon></dt>
+            <dd>Tom Bombadil</dd>
+          </div>
+          <div class="wa-flank wa-align-items-center">
+            <dt><wa-icon name="calendar-days" label="Date" fixed-width></wa-icon></dt>
+            <dd><wa-format-date date="2025-03-15"></wa-format-date></dd>
+          </div>
+          <div class="wa-flank wa-align-items-center">
+            <dt><wa-icon name="coin-vertical" fixed-width></wa-icon></dt>
+            <dd>Paid with copper pennies</dd>
+          </div>
+        </dl>
+      </div>
+      <div slot="footer">
+        <a href="" class="wa-cluster wa-gap-2xs">
+          <span>Download Receipt</span>
+          <wa-icon name="arrow-right"></wa-icon>
+        </a>
+      </div>
+    </wa-card>
+    <wa-card>
+      <div class="wa-stack">
+        <div class="wa-split">
+          <div class="wa-cluster wa-heading-l">
+            <wa-icon name="book-sparkles"></wa-icon>
+            <h3>Fellowship</h3>
+          </div>
+          <wa-badge>Most Popular</wa-badge>
+        </div>
+        <span class="wa-flank wa-align-items-baseline wa-gap-2xs">
+          <span class="wa-heading-2xl">$120</span>
+          <span class="wa-caption-l">per year</span>
+        </span>
+        <p class="wa-caption-l">Carry great power (and great responsibility).</p>
+        <wa-button variant="brand">Get this Plan</wa-button>
+      </div>
+      <div slot="footer" class="wa-stack wap-gap-s">
+        <h4 class="wa-heading-s">What You Get</h4>
+        <div class="wa-stack">
+          <div class="wa-flank">
+            <wa-icon name="user" fixed-width></wa-icon>
+            <span class="wa-caption-m">9 users</span>
+          </div>
+          <div class="wa-flank">
+            <wa-icon name="ring" fixed-width></wa-icon>
+            <span class="wa-caption-m">1 ring</span>
+          </div>
+          <div class="wa-flank">
+            <wa-icon name="chess-rook" fixed-width></wa-icon>
+            <span class="wa-caption-m">API access to Isengard</span>
+          </div>
+          <div class="wa-flank">
+            <wa-icon name="feather" fixed-width></wa-icon>
+            <span class="wa-caption-m">Priority eagle support</span>
+          </div>
+        </div>
+      </div>
+    </wa-card>
+    <wa-card with-footer>
+      <div class="wa-flank:end">
+        <div class="wa-stack wa-gap-xs">
+          <div class="wa-cluster wa-gap-xs">
+            <h3 class="wa-heading-s">Migs Mayfeld</h3 class="wa-heading-s">
+            <wa-badge pill>Admin</wa-badge>
+          </div>
+          <span class="wa-caption-m">Bounty Hunter</span>
+        </div>
+        <wa-avatar image="https://images.unsplash.com/photo-1633268335280-a41fbde58707?q=80&w=3348&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" label="Avatar of a man wearing a sci-fi helmet (Photograph by Nandu Vasudevan)"></wa-avatar>
+      </div>
+      <div slot="footer" class="wa-grid wa-gap-xs" style="--min-column-size: 10ch;">
+        <wa-button appearance="outlined">
+          <wa-icon slot="prefix" name="at"></wa-icon>
+          Email
+        </wa-button>
+        <wa-button appearance="outlined">
+          <wa-icon slot="prefix" name="phone"></wa-icon>
+          Phone
+        </wa-button>
+      </div>
+    </wa-card>
+    <wa-card>
+      <div class="wa-flank:end">
+        <a href="" class="wa-flank wa-link-plain">
+          <wa-avatar shape="rounded" style="--background-color: var(--wa-color-yellow-90); --text-color: var(--wa-color-yellow-50)">
+            <wa-icon slot="icon" name="egg-fried"></wa-icon>
+          </wa-avatar>
+          <div class="wa-gap-2xs wa-stack">
+            <span class="wa-heading-s">Second Breakfast</span>
+            <span class="wa-caption-m">19 Items</span>
+          </div>
+        </a>
+        <wa-dropdown>
+          <wa-icon-button id="more-actions-2" slot="trigger" name="ellipsis-vertical" label="View menu"></wa-icon-button>
+          <wa-menu>
+            <wa-menu-item>Copy link</wa-menu-item>
+            <wa-menu-item>Rename</wa-menu-item>
+            <wa-menu-item>Move to trash</wa-menu-item>
+          </wa-menu>
+        </wa-dropdown>
+        <wa-tooltip for="more-actions-2">View menu</wa-tooltip>
+      </div>
+    </wa-card>
+    <wa-card with-header with-footer>
+      <div slot="header" class="wa-stack wa-gap-xs">
+        <h2 class="wa-heading-m">Decks</h2>
+      </div>
+      <div class="wa-stack wa-gap-xl">
+        <p class="wa-caption-m">You haven’t created any decks yet. Get started by selecting an aspect that matches your play style.</p>
+        <div class="wa-grid wa-gap-xl" style="--min-column-size: 30ch;">
+          <a href="" class="wa-flank wa-align-items-start wa-link-plain">
+            <wa-avatar shape="rounded" style="--background-color: var(--wa-color-blue-90);color: var(--wa-color-blue-50);">
+              <wa-icon slot="icon" name="shield"></wa-icon>
+            </wa-avatar>
+            <div class="wa-stack wa-gap-2xs">
+              <span class="wa-align-items-center wa-cluster wa-gap-xs wa-heading-s">
+                Vigilance <wa-icon name="arrow-right"></wa-icon>
+              </span>
+              <p class="wa-caption-m">
+                Protect, defend, and restore as you ready heavy-hitters.
+              </p>
+            </div>
+          </a>
+          <a href="" class="wa-flank wa-align-items-start wa-link-plain">
+            <wa-avatar shape="rounded" style="--background-color: var(--wa-color-green-90);color: var(--wa-color-green-50);">
+              <wa-icon slot="icon" name="chevrons-up"></wa-icon>
+            </wa-avatar>
+            <div class="wa-stack wa-gap-2xs">
+              <span class="wa-align-items-center wa-cluster wa-gap-xs wa-heading-s">
+                Command <wa-icon name="arrow-right"></wa-icon>
+              </span>
+              <p class="wa-caption-m">
+                Build imposing armies and stockpile resources.
+              </p>
+            </div>
+          </a>
+          <a href=""class="wa-flank wa-align-items-start wa-link-plain">
+            <wa-avatar shape="rounded" style="--background-color: var(--wa-color-red-90);color: var(--wa-color-red-50);">
+              <wa-icon slot="icon" name="explosion"></wa-icon>
+            </wa-avatar>
+            <div class="wa-stack wa-gap-2xs">
+              <span class="wa-align-items-center wa-cluster wa-gap-xs wa-heading-s">
+                Aggression <wa-icon name="arrow-right"></wa-icon>
+              </span>
+              <p class="wa-caption-m">
+                Relentlessly deal damage and apply pressure to your opponent.
+              </p>
+            </div>
+          </a>
+          <a href="" class="wa-flank wa-align-items-start wa-link-plain">
+            <wa-avatar shape="rounded" style="--background-color: var(--wa-color-yellow-90);color: var(--wa-color-yellow-50);">
+              <wa-icon slot="icon" name="moon-stars"></wa-icon>
+            </wa-avatar>
+            <div class="wa-stack wa-gap-2xs">
+              <span class="wa-align-items-center wa-cluster wa-gap-xs wa-heading-s">
+                Cunning <wa-icon name="arrow-right"></wa-icon>
+              </span>
+              <p class="wa-caption-m">
+                Disrupt and frustrate your opponent with dastardly tricks.
+              </p>
+            </div>
+          </a>
+        </div>
+      </div>
+      <div slot="footer">
+        <a href="" class="wa-cluster wa-gap-xs">
+          <span>Or start a deck from scratch</span>
+          <wa-icon name="arrow-right"></wa-icon>
+        </a>
+      </div>
+    </wa-card>
   </div>
 </div>

docs/_layouts/blank.njk

@@ -2,6 +2,7 @@
 <html lang="en" data-fa-kit-code="b10bfbde90" data-cdn-url="{% cdnUrl %}">
   <head>
     {% include 'head.njk' %}
+    {% block head %}{% endblock %}
   </head>
   <body class="layout-{{ layout | stripExtension }}">
 

docs/_layouts/component.njk

@@ -255,7 +255,7 @@
   {# Importing #}
   <h2>Importing</h2>
   <p>
-    The <a href="/docs/installation/#quick-start-autoloading-via-cdn">autoloader</a> is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.
+    The <a href="/docs/#quick-start-autoloading-via-cdn">autoloader</a> is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.
   </p>
 
   <wa-tab-group label="How would you like to import this component?">

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/palette.njk

@@ -30,12 +30,21 @@
 
   {% include 'breadcrumbs.njk' %}
 
-  <h1 v-if="saved" class="title">
-    {% raw %}{{ saved.title }}{% endraw %}
-    <wa-icon-button name="pencil" label="Rename palette" @click="rename"></wa-icon-button>
-    <wa-icon-button class="delete" name="trash" label="Delete palette" @click="deleteSaved"></wa-icon-button>
+  <h1 class="title">
+    <span v-content="title">{{ title }}</span>
+    <template v-if="saved || tweaked">
+      <wa-icon-button name="pencil" label="Rename palette" @click="rename"></wa-icon-button>
+      <wa-icon-button v-if="saved" class="delete" name="trash" label="Delete palette" @click="deleteSaved"></wa-icon-button>
+      <wa-button @click="save()" :disabled="!unsavedChanges"
+        :variant="unsavedChanges ? 'success' : 'neutral'" size="small" :appearance="unsavedChanges ? 'accent' : 'outlined'">
+        <span slot="prefix" class="icon-modifier">
+          <wa-icon name="sidebar" variant="regular"></wa-icon>
+          <wa-icon name="circle-plus" class="modifier" style="color: light-dark(var(--wa-color-green-70), var(--wa-color-green-60));"></wa-icon>
+        </span>
+        <span v-content="unsavedChanges ? 'Save' : 'Saved'">Save</span>
+      </wa-button>
+    </template>
   </h1>
-  <h1 v-if="!saved" class="title">{{ title }}</h1>
 
   <div class="block-info">
     <code class="class">.wa-palette-{{ paletteId }}</code>
@@ -59,7 +68,7 @@
   <wa-icon name="sliders-simple" slot="icon" variant="regular"></wa-icon>
    This palette has been tweaked.
    <div class="wa-cluster wa-gap-xs">
-    <wa-tag v-for="tweakHumanReadable, param in tweaksHumanReadable" removable @wa-remove="reset(param)">{% raw %}{{ tweakHumanReadable }}{% endraw %}</wa-tag>
+    <wa-tag v-for="tweakHumanReadable, param in tweaksHumanReadable" removable @wa-remove="reset(param)" v-content="tweakHumanReadable"></wa-tag>
    </div>
 
   <wa-button @click="reset()" appearance="outlined" variant="danger">
@@ -68,13 +77,6 @@
     </span>
     Reset
   </wa-button>
-  <wa-button v-if="!saved" @click="save" variant="success">
-    <span slot="prefix" class="icon-modifier">
-      <wa-icon name="sidebar" variant="regular"></wa-icon>
-      <wa-icon name="circle-plus" class="modifier" style="color: light-dark(var(--wa-color-green-70), var(--wa-color-green-60));"></wa-icon>
-    </span>
-    Save
-  </wa-button>
 </wa-callout>
 
 <table class="colors main wa-palette-{{ paletteId }}">
@@ -120,19 +122,8 @@
       </div>
       <div class="popup">
       {% if hue === 'gray' %}
-        <wa-radio-group class="core-color" orientation="horizontal" v-model="grayColor">
-          {% for h in hues -%}
-            {%- if h !== 'gray' -%}
-              <wa-radio-button id="gray-undertone-{{ h }}" value="{{ h }}" label="{{ h | capitalize }}" style="--color: var(--wa-color-{{ h }})"></wa-radio-button>
-              <wa-tooltip for="gray-undertone-{{ h }}" hoist>
-                {{ h | capitalize }}
-              </wa-tooltip>
-            {%- endif -%}
-          {%- endfor -%}
-          <div slot="label">
-            Gray undertone
-          </div>
-        </wa-radio-group>
+        <swatch-select label="Gray undertone" shape="circle" :values="hues" v-model="grayColor"></swatch-select>
+
         <div class="decorated-slider gray-chroma-slider" :style="{'--max': maxGrayChroma}">
           <wa-slider name="gray-chroma" v-model="grayChroma" ref="grayChromaSlider"
           value="0" min="0" :max="maxGrayChroma" step="0.01"

docs/_layouts/patterns.njk

@@ -0,0 +1,5 @@
+{% extends '../_layouts/block.njk' %}
+
+{% block head %}
+<link href="/docs/patterns/patterns.css" rel="stylesheet">
+{% endblock %}

docs/_layouts/theme.njk

@@ -5,35 +5,22 @@
 {% extends '../_includes/base.njk' %}
 
 {% block head %}
-<script>
-globalThis.wa_data ??= {};
-wa_data.baseTheme = "{{ page.fileSlug }}";
-wa_data.themes = {
-  {% for theme in collections.theme -%}
-  "{{ theme.fileSlug }}": {
-    "title": "{{ theme.data.title }}",
-    "palette": "{{ theme.data.palette }}",
-    "brand": "{{ theme.data.brand }}"
-  },
-  {% endfor %}
-};
-wa_data.palettes = {
-  {% for palette in collections.palette -%}
-  "{{ palette.fileSlug }}": {
-    "title": "{{ palette.data.title }}",
-  },
-  {% endfor %}
-};
-</script>
 <link href="{{ page.url }}../remix.css" rel="stylesheet">
-<script src="{{ page.url }}../remix.js" type="module"></script>
+<script type="module" src="{{ page.url }}../edit/index.js"></script>
 {% endblock %}
 
 {% block header %}
+<script>
+if (location.pathname.endsWith('/custom/') && !location.search) {
+  location.href = "../edit/";
+}
+</script>
+<div id="theme-app" data-theme-id="{{ page.fileSlug }}">
 
-<iframe src='{{ page.url }}demo.html' id="demo"></iframe>
+<iframe ref="preview" :src="'{{ page.url }}demo.html' + urlParams" src='{{ page.url }}demo.html' id="demo"></iframe>
 
-<wa-details id="mix_and_match" class="wa-gap-m" >
+{% if page.fileSlug !== 'custom' %}
+<wa-details id="mix_and_match" class="wa-gap-m" :open="saved || unsavedChanges">
   <h4 slot="summary" data-no-anchor data-no-outline id="remix">
     <wa-icon name="arrows-rotate"></wa-icon>
     Remix this theme
@@ -41,92 +28,64 @@ wa_data.palettes = {
     <wa-tooltip for="what-is-remixing">Customize this theme by changing its colors and/or remixing it with design elements from other themes!</wa-tooltip>
   </h4>
 
-  <wa-select name="colors" label="Colors from…" value="" clearable>
-    <wa-icon name="palette" slot="prefix" variant="regular"></wa-icon>
-    {% for theme in collections.theme | sort %}
-      {% set currentTheme = theme.fileSlug == page.fileSlug %}
-      <wa-option label="{{ theme.data.title }}" value="{{ theme.fileSlug if not currentTheme }}" {{ (theme.fileSlug if currentTheme) | attr('data-id') }}>
-        <wa-card with-header>
-          <div slot="header">
-          {% include "svgs/theme-color.njk" %}
-          </div>
-          <span class="page-name">
-            {{ theme.data.title }}
-            {% if theme.data.isPro %}<wa-badge class="pro">PRO</wa-badge>{% endif %}
-            {% if currentTheme %}<wa-badge variant="neutral" appearance="outlined">This theme</wa-badge>{% endif %}
-          </span>
-        </wa-card>
-      </wa-option>
-    {% endfor %}
-  </wa-select>
-
-  <wa-select name="palette" label="Palette" clearable>
+  <wa-select name="palette" label="Color palette" clearable v-model="theme.palette">
     <wa-icon name="swatchbook" slot="prefix" variant="regular"></wa-icon>
-    {% set defaultPalette = palette %}
-    {% for palette in collections.palette | sort %}
-      {% set currentPalette = palette.fileSlug == defaultPalette %}
-      <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" %}
-          </div>
-          <span class="page-name">
-            {{ palette.data.title }}
-            {% if palette.data.isPro %}<wa-badge class="pro">PRO</wa-badge>{% endif %}
-            {% if currentPalette %}<wa-badge variant="neutral" appearance="outlined">Theme default</wa-badge>{% endif %}
-          </span>
-        </wa-card>
-      </wa-option>
-    {% endfor %}
-    {% set palette = defaultPalette %}
+    <wa-option v-for="(palette, paletteId) in palettes" :label="palette.title" :value="paletteId === baseTheme.palette ? '' : paletteId">
+      <palette-card :palette="paletteId" size="small">
+        <template #extra>
+          <wa-badge v-if="paletteId === baseTheme.palette" variant="neutral" appearance="outlined">Theme default</wa-badge>
+        </template>
+      </palette-card>
+    </wa-option>
   </wa-select>
 
-  <wa-select name="brand" label="Brand color" value="" clearable>
-    <div class="selected-swatch" slot="prefix"></div>
-    {% for hue in hues %}
-      {% set currentBrand = hue == brand %}
-      <wa-option label="{{ hue | capitalize }}" value="{{ hue if not currentBrand }}" {{ (hue if currentBrand) | attr('data-id') }} style="--color: var(--wa-color-{{ hue }})">
-        {{ hue | capitalize }}
-        {% if currentBrand %}<wa-badge variant="neutral" appearance="outlined">Theme default</wa-badge>{% endif %}
+  <color-select :model-value="computed.brand" @update:model-value="value => theme.brand = value" label="Brand color"
+                :values="hues"></color-select>
+
+  <wa-select name="colors" class="theme-colors-select" label="Color contrast from…" value="" clearable v-model="theme.colors">
+    <wa-icon name="palette" slot="prefix" variant="regular"></wa-icon>
+    <template v-for="(themeMeta, themeId) in themes">
+      <wa-option v-if="themeId !== 'custom'" :label="themeMeta.title" :value="themeId === computed.colors ? '' : themeId">
+        <theme-card :theme="themeId" type="colors" :rest="{base: computed.base, palette: computed.palette, brand: computed.brand}" size="small">
+          <template #extra>
+          <wa-badge v-if="themeId === theme.base" variant="neutral" appearance="outlined">This theme</wa-badge>
+        </template>
+        </theme-card>
       </wa-option>
-    {% endfor %}
+    </template>
   </wa-select>
 
-  <wa-select name="typography" label="Typography from…" clearable>
+  <wa-select name="typography" label="Typography from…" clearable v-model="theme.typography">
     <wa-icon name="font-case" slot="prefix"></wa-icon>
-    {% for theme in collections.theme | sort %}
-      {% set currentTheme = theme.fileSlug == page.fileSlug %}
-      <wa-option label="{{ theme.data.title }}" value="{{ theme.fileSlug if not currentTheme }}" {{ (theme.fileSlug if currentTheme) | attr('data-id') }}>
-        <wa-card with-header>
-          <div slot="header">
-          {% include "svgs/theme-typography.njk" %}
-          </div>
-          <span class="page-name">
-            {{ theme.data.title }}
-            {% if theme.data.isPro %}<wa-badge class="pro">PRO</wa-badge>{% endif %}
-            {% if currentTheme %}<wa-badge variant="neutral" appearance="outlined">This theme</wa-badge>{% endif %}
-          </span>
-        </wa-card>
-      </wa-option>
-    {% endfor %}
+
+    <wa-option v-for="(themeMeta, themeId) in themes" :label="themeMeta.title" :value="themeId === theme.base ? '' : themeId">
+      <fonts-card :theme="themeId" size="small">
+        <template #extra>
+          <wa-badge v-if="themeId === theme.base" variant="neutral" appearance="outlined">This theme</wa-badge>
+        </template>
+      </fonts-card>
+    </wa-option>
   </wa-select>
 </wa-details>
-
+{% endif %}
 <h2>Color</h2>
-{% set paletteURL = '/docs/palettes/' + palette + '/' %}
-
 
 <div class="index-grid">
-  {% set themePage = page %}
-  {% set page = paletteURL | getCollectionItemFromUrl %}
-  {% set pageSubtitle = "Default color palette" %}
-  {% include 'page-card.njk' %}
-  {% set page = themePage %}
-
-  <wa-card style="--header-background: var(--wa-color-{{ brand }})" class="wa-palette-{{ palette }}">
+  {% if page.fileSlug === 'custom' %}
+    <palette-card :palette="computed.palette" subtitle="Color palette"></palette-card>
+  {% else %}
+    {% set themePage = page %}
+    {% set paletteURL = '/docs/palettes/' + palette + '/' %}
+    {% set page = paletteURL | getCollectionItemFromUrl %}
+    {% set pageSubtitle = "Default color palette" %}
+    {% include 'page-card.njk' %}
+    {% set page = themePage %}
+  {% endif %}
+  <wa-card class="wa-palette-{{ palette }}"          style="--header-background: var(--wa-color-{{ brand }})"
+          :class="`wa-palette-${computed.palette}`" :style="{'--header-background': palettes[computed.palette]?.colors[computed.brand]?.key}">
     <div slot="header"></div>
-    <div class="page-name">{{ brand | capitalize }}</div>
-    <div class="wa-caption-s">Default brand color</div>
+    <div class="page-name" v-content="capitalize(computed.brand)">{{ brand | capitalize }}</div>
+    <div class="wa-caption-s">{{ 'Brand color' if page.fileSlug === 'custom' else 'Default brand color' }}</div>
   </wa-card>
 </div>
 {% endblock %}
@@ -139,7 +98,25 @@ wa_data.palettes = {
 You can import this theme from the Web Awesome CDN.
 
 {% set stylesheet = 'styles/themes/' + page.fileSlug + '.css' %}
-{% include 'import-stylesheet-code.md.njk' %}
+
+<wa-tab-group class="import-stylesheet-code">
+<wa-tab panel="html">In HTML</wa-tab>
+<wa-tab panel="css">In CSS</wa-tab>
+<wa-tab-panel name="html">
+
+Add the following code to the `<head>` of your page:
+```html { v-content:html="code.html.highlighted" }
+<link rel="stylesheet" href="{% cdnUrl stylesheet %}" />
+```
+</wa-tab-panel>
+<wa-tab-panel name="css">
+
+Add the following code at the top of your CSS file:
+```css { v-content:html="code.css.highlighted" }
+@import url('{% cdnUrl stylesheet %}');
+```
+</wa-tab-panel>
+</wa-tab-group>
 
 ## Dark mode
 
@@ -203,5 +180,6 @@ systemDark.addEventListener('change', applyDark);
 applyDark();
 ```
 
+</div> {# end theme app #}
 {% endmarkdown %}
 {% endblock %}

docs/_utils/code-examples.js

@@ -102,12 +102,7 @@ const templates = {
 export function codeExamplesPlugin(eleventyConfig, options = {}) {
   const defaultOptions = {
     container: 'body',
-    defaultOpen: (code, { outputPathIndex }) => {
-      return (
-        outputPathIndex === 1 && // is first
-        code.textContent.length < 500
-      ); // is short
-    },
+    defaultOpen: () => false,
   };
   options = { ...defaultOptions, ...options };
 

docs/_utils/copy-code.js

@@ -33,7 +33,7 @@ export function copyCodePlugin(eleventyConfig, options = {}) {
 
       // Add a copy button
       pre.innerHTML += `<wa-icon-button href="#${preId}" class="block-link-icon" name="link"></wa-icon-button>
-        <wa-copy-button from="${codeId}" class="copy-button" hoist></wa-copy-button>`;
+        <wa-copy-button from="${codeId}" class="copy-button"></wa-copy-button>`;
     });
 
     return doc.toString();

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;
 }
 
@@ -180,69 +181,185 @@ export function sort(arr, by = { 'data.order': 1, 'data.title': '' }) {
 /**
  * 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' } = 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 = {};
 
   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/_utils/remove-data-alpha-elements.js

@@ -1,23 +0,0 @@
-import { parse } from 'node-html-parser';
-
-/**
- * Eleventy plugin to add remove elements with <div data-alpha="remove"> from the alpha build.
- */
-export function removeDataAlphaElements(options = {}) {
-  options = {
-    isAlpha: false,
-    ...options,
-  };
-
-  return function (eleventyConfig) {
-    eleventyConfig.addTransform('remove-data-alpha-elements', content => {
-      const doc = parse(content, { blockTextElements: { code: true } });
-
-      if (options.isAlpha) {
-        doc.querySelectorAll('[data-alpha="remove"]').forEach(el => el.remove());
-      }
-
-      return doc.toString();
-    });
-  };
-}

docs/_utils/search.js

@@ -2,6 +2,7 @@
 import { mkdir, writeFile } from 'fs/promises';
 import lunr from 'lunr';
 import { parse } from 'node-html-parser';
+import * as path from 'path';
 import { dirname, join } from 'path';
 
 function collapseWhitespace(string) {
@@ -23,9 +24,23 @@ export function searchPlugin(options = {}) {
   };
 
   return function (eleventyConfig) {
-    const pagesToIndex = [];
+    const pagesToIndex = new Map();
+
+    eleventyConfig.addPreprocessor('exclude-unlisted-from-search', '*', function (data, content) {
+      if (data.unlisted) {
+        // no-op
+      } else {
+        pagesToIndex.set(data.page.inputPath, {});
+      }
+
+      return content;
+    });
 
     eleventyConfig.addTransform('search', function (content) {
+      if (!pagesToIndex.has(this.page.inputPath)) {
+        return content;
+      }
+
       const doc = parse(content, {
         blockTextElements: {
           script: false,
@@ -41,7 +56,7 @@ export function searchPlugin(options = {}) {
         doc.querySelectorAll(selector).forEach(el => el.remove());
       });
 
-      pagesToIndex.push({
+      pagesToIndex.set(this.page.inputPath, {
         title: collapseWhitespace(options.getTitle(doc)),
         description: collapseWhitespace(options.getDescription(doc)),
         headings: options.getHeadings(doc).map(collapseWhitespace),
@@ -52,8 +67,9 @@ export function searchPlugin(options = {}) {
       return content;
     });
 
-    eleventyConfig.on('eleventy.after', ({ dir }) => {
-      const outputFilename = join(dir.output, 'search.json');
+    eleventyConfig.on('eleventy.after', ({ directories }) => {
+      const { output } = directories;
+      const outputFilename = path.resolve(join(output, 'search.json'));
       const map = [];
       const searchIndex = lunr(async function () {
         let index = 0;
@@ -63,7 +79,7 @@ export function searchPlugin(options = {}) {
         this.field('h', { boost: 10 });
         this.field('c');
 
-        for (const page of pagesToIndex) {
+        for (const [_inputPath, page] of pagesToIndex) {
           this.add({ id: index, t: page.title, h: page.headings, c: page.content });
           map[index] = { title: page.title, description: page.description, url: page.url };
           index++;

docs/assets/components/scoped.js

@@ -0,0 +1,171 @@
+/**
+ * Low-level utility to encapsulate a bit of HTML (mainly to apply certain stylesheets to it without them leaking to the rest of the page)
+ * Usage: <wa-scoped><template><!-- your HTML here --></template></wa-scoped>
+ */
+import { discover } from '/dist/webawesome.js';
+
+const imports = new Set();
+const fontFaceRules = new Set();
+
+export default class WaScoped extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+
+    this.observer = new MutationObserver(() => this.render());
+    this.observer.observe(this, { childList: true, subtree: true, characterData: true });
+  }
+
+  connectedCallback() {
+    this.render();
+    this.ownerDocument.documentElement.addEventListener('wa-color-scheme-change', e =>
+      this.#applyDarkMode(e.detail.dark),
+    );
+  }
+
+  render() {
+    this.observer.takeRecords();
+    this.observer.disconnect();
+
+    this.shadowRoot.innerHTML = '';
+
+    // To avoid mutating this.childNodes while iterating over it
+    let nodes = [];
+
+    for (let template of this.childNodes) {
+      // Other solutions we can try if needed: <script type="text/html">, or comment nodes
+      if (template instanceof HTMLTemplateElement) {
+        if (template.content.childNodes.length > 0) {
+          nodes.push(template.content.cloneNode(true));
+        } else if (template.childNodes.length > 0) {
+          // Fake template, suck its children out of the light DOM
+          nodes.push(...template.childNodes);
+        }
+      } else {
+        // Regular child, suck it out of the light DOM
+        nodes.push(template);
+      }
+    }
+
+    this.shadowRoot.append(...nodes);
+
+    this.#fixStyles();
+    this.#applyDarkMode();
+
+    discover(this.shadowRoot);
+
+    this.observer.observe(this, { childList: true, subtree: true, characterData: true });
+  }
+
+  #applyDarkMode(isDark = getComputedStyle(this).colorScheme === 'dark') {
+    // Hack to make dark mode work
+    // NOTE If any child nodes actually have .wa-dark, this will override it
+    for (let node of this.shadowRoot.children) {
+      node.classList.toggle('wa-dark', isDark);
+    }
+    this.classList.toggle('wa-dark', isDark);
+  }
+
+  /**
+   * @font-face does not work in shadow DOM in Chrome & FF, as of March 2025 https://issues.chromium.org/issues/41085401
+   * This works around this issue by traversing the shadow DOM CSS looking
+   * for @font-face rules or CSS imports to known font providers and copies them to the main document
+   */
+  async #fixStyles() {
+    let styleElements = [...this.shadowRoot.querySelectorAll('link[rel="stylesheet"], style')];
+
+    let loadStates = styleElements.map(element => {
+      try {
+        if (element.sheet?.cssRules) {
+          // Already loaded
+          return Promise.resolve(element.sheet);
+        }
+      } catch (e) {
+        // CORS
+        return Promise.resolve(null);
+      }
+
+      return new Promise((resolve, reject) => {
+        element.addEventListener('load', e => resolve(element.sheet));
+        element.addEventListener('error', e => reject(null));
+      });
+    });
+
+    await Promise.allSettled(loadStates);
+
+    let fontRules = findFontFaceRules(...this.shadowRoot.styleSheets);
+
+    if (!fontRules.length) {
+      return;
+    }
+
+    let doc = this.ownerDocument;
+    // Why not adoptedStyleSheets? Can't have @import in those yet
+    let id = `wa-scoped-hoisted-fonts`;
+    let style = doc.head.querySelector('style#' + id);
+    if (!style) {
+      style = Object.assign(doc.createElement('style'), { id, textContent: ' ' });
+      doc.head.append(style);
+    }
+    let sheet = style.sheet;
+
+    for (let rule of fontRules) {
+      let cssText = rule.cssText;
+      if (rule.type === CSSRule.FONT_FACE_RULE) {
+        if (fontFaceRules.has(cssText)) {
+          continue;
+        }
+        fontFaceRules.add(cssText);
+        sheet.insertRule(cssText);
+      } else if (rule.type === CSSRule.IMPORT_RULE) {
+        if (imports.has(rule.href)) {
+          continue;
+        }
+        imports.add(rule.href);
+        sheet.insertRule(cssText, 0);
+      }
+    }
+  }
+
+  static observedAttributes = [];
+}
+
+customElements.define('wa-scoped', WaScoped);
+
+export const WEB_FONT_HOSTS = [
+  'fonts.googleapis.com',
+  'fonts.gstatic.com',
+  'use.typekit.net',
+  'fonts.adobe.com',
+  'kit.fontawesome.com',
+  'pro.fontawesome.com',
+  'cdn.materialdesignicons.com',
+];
+
+function findFontFaceRules(...stylesheets) {
+  let ret = [];
+
+  for (let sheet of stylesheets) {
+    let rules;
+    try {
+      rules = sheet.cssRules;
+    } catch (e) {
+      // CORS
+      continue;
+    }
+
+    for (let rule of rules) {
+      if (rule.type === CSSRule.FONT_FACE_RULE) {
+        ret.push(rule);
+      } else if (rule.type === CSSRule.IMPORT_RULE) {
+        if (WEB_FONT_HOSTS.some(host => rule.href.includes(host))) {
+          ret.push(rule);
+        } else if (rule.styleSheet) {
+          ret.push(...findFontFaceRules(rule.styleSheet));
+        }
+      }
+    }
+  }
+
+  return ret;
+}

docs/assets/data/colors.js

@@ -1,21 +1,9 @@
 /**
- * Data related to theme remixing and palette tweaking
+ * Data related to palettes and colors.
  * Must work in both browser and Node.js
  */
-export const cdnUrl = globalThis.document ? document.documentElement.dataset.cdnUrl : '/dist/';
 
-export const urls = {
-  theme: id => `styles/themes/${id}.css`,
-  colors: id => `styles/themes/${id}/color.css`,
-  palette: id => `styles/color/${id}.css`,
-  brand: id => `styles/brand/${id}.css`,
-  typography: id => `styles/themes/${id}/typography.css`,
-};
-
-export const selectors = {
-  palette: id =>
-    [':where(:root)', ':host', ":where([class^='wa-theme-'], [class*=' wa-theme-'])", `.wa-palette-${id}`].join(',\n'),
-};
+export const tints = ['05', '10', '20', '30', '40', '50', '60', '70', '80', '90', '95'];
 
 export const hueRanges = {
   red: { min: 5, max: 35 }, // 30
@@ -29,6 +17,9 @@ export const hueRanges = {
   pink: { min: 320, max: 365 }, // 45
 };
 
+export const hues = Object.keys(hueRanges);
+export const allHues = [...hues, 'gray'];
+
 export const moreHue = {
   red: 'Redder',
   orange: 'More orange', // https://www.reddit.com/r/grammar/comments/u9n0uo/is_it_oranger_or_more_orange/
@@ -54,20 +45,3 @@ export const maxGrayChroma = {
   purple: 0.3,
   pink: 0.25,
 };
-
-export const docsURLs = {
-  colors: '/docs/themes/',
-  palette: '/docs/palettes/',
-  typography: '/docs/themes/',
-};
-
-export const icons = {
-  colors: 'palette',
-  palette: 'swatchbook',
-  brand: 'droplet',
-  typography: 'font-case',
-};
-
-export const hues = Object.keys(hueRanges);
-
-export const tints = ['05', '10', '20', '30', '40', '50', '60', '70', '80', '90', '95'];

docs/assets/data/fonts.js

@@ -0,0 +1,65 @@
+import { deepEntries } from '../scripts/util/deep.js';
+import { themeConfig } from './theming.js';
+import themes from '/assets/data/themes.js';
+
+/**
+ * Map of font pairings (body + heading) to the first theme that uses them.
+ */
+export const pairings = {};
+
+// NOTE Do not use Symbols, we want these to be enumerable when used as keys
+export const sameAs = { body: '$body' };
+
+export const fontNames = {
+  'system-ui': 'OS Default',
+  'ui-serif': 'OS Default Serif',
+  'ui-sans-serif': 'OS Default Sans Serif',
+  'ui-monospace': 'OS Default Code Font',
+  'ui-monospace': 'OS Default Code Font',
+};
+
+export function defaultTitle(fonts) {
+  let { body, heading = sameAs.body } = fonts;
+  let names = [body];
+
+  if (heading !== sameAs.body) {
+    names.unshift(heading);
+  }
+
+  return names.map(name => fontNames[name] ?? name).join(' • ');
+}
+
+for (let id in themes) {
+  let theme = themes[id];
+  let { fonts } = theme;
+
+  if (fonts) {
+    let { body, heading = sameAs.body } = fonts;
+
+    pairings[body] ??= {};
+    pairings[body][heading] ??= {
+      id, // First theme that uses this pairing
+      ids: new Set([id]), // All themes that use this pairing
+      url: themeConfig.typography.url(id), // Stylesheet URL
+      fonts,
+      get title() {
+        return defaultTitle(this.fonts);
+      },
+    };
+    pairings[body][heading].ids.add(id);
+  }
+}
+
+export const pairingsEntries = deepEntries(pairings, {
+  descend(value, key, parent, path) {
+    if (value?.fonts) {
+      return false; // Don't recurse into pairing objects
+    }
+  },
+  filter(value, key, parent, path) {
+    // Only keep 2 levels (body → heading → pairing)
+    return path.length === 1;
+  },
+});
+
+export const pairingsList = pairingsEntries.map(arg => arg.at(-1));

docs/assets/data/icons.js

@@ -0,0 +1,7 @@
+export const iconLibraries = {
+  default: {
+    title: 'Font Awesome',
+    family: ['classic', 'sharp', 'duotone', 'sharp-duotone'],
+    style: ['solid', 'regular', 'light', 'thin'],
+  },
+};

docs/assets/data/index.js

@@ -0,0 +1,6 @@
+export * from './colors.js';
+// export * from './fonts.js';
+export * from './icons.js';
+export * from './theming.js';
+
+export const cdnUrl = globalThis.document ? document.documentElement.dataset.cdnUrl : '/dist/';

docs/assets/data/palettes.js.njk

@@ -0,0 +1,32 @@
+---
+layout: null
+permalink: '/assets/data/palettes.js'
+eleventyExcludeFromCollections: true
+---
+export default {
+{%- for palette in collections.palette | sort %}
+{%- if not palette.data.unlisted %}
+  {% set paletteId = palette.fileSlug -%}
+  {%- set colors = palettes[paletteId] -%}
+  '{{ paletteId }}': {
+    id: '{{ paletteId }}',
+    title: '{{ palette.data.title }}',
+    colors: {
+      {% for hue, tints in colors -%}
+        '{{ hue }}': {
+          {% for tint, value in tints -%}
+            {%- if tint != '05' -%}
+              '{{ '05' if tint == '5' else tint }}': '{{ value | safe }}',
+            {%- endif %}
+          {% endfor %}
+
+          get key() {
+            return this[this.maxChromaTint];
+          }
+        },
+      {% endfor -%} // end colors
+    }
+  }, // end palette
+{%- endif -%}
+{% endfor %}
+};

docs/assets/data/themes.js.njk

@@ -0,0 +1,22 @@
+---
+layout: null
+permalink: '/assets/data/themes.js'
+eleventyExcludeFromCollections: true
+---
+export default {
+{%- for theme in collections.theme | sort %}
+{%- if not theme.data.unlisted %}
+  {% set themeId = theme.fileSlug -%}
+  {%- set colors = themes[themeId] -%}
+  '{{ themeId }}': {
+    id: '{{ themeId }}',
+    title: '{{ theme.data.title }}',
+    palette: '{{ theme.data.palette }}',
+    brand: '{{ theme.data.brand }}',
+    isPro: {{ theme.data.isPro or 'pro' in theme.data.tags }},
+    fonts: {{ (theme.data.fonts | dump or 'null') | safe }},
+    icons: {{ (theme.data.icons | dump  or 'null') | safe }},
+  },
+{%- endif %}
+{% endfor %}
+};

docs/assets/data/theming.js

@@ -0,0 +1,82 @@
+import { deepEach, isPlainObject } from '../scripts/util/deep.js';
+
+/**
+ * Data related to themes, theme remixing
+ * Must work in both browser and Node.js
+ */
+export const cdnUrl = globalThis.document ? document.documentElement.dataset.cdnUrl : '/dist/';
+
+// This should eventually replace all uses of `urls` and `themeParams`
+export const themeConfig = {
+  base: { url: id => `styles/themes/${id}.css`, default: 'default' },
+  colors: {
+    url: id => `styles/themes/${id}/color.css`,
+    docs: '/docs/themes/',
+    icon: 'palette',
+    default() {
+      return this.base;
+    },
+  },
+  palette: {
+    url: id => `styles/color/${id}.css`,
+    docs: '/docs/palette/',
+    icon: 'swatchbook',
+    default(baseTheme) {
+      return baseTheme?.palette;
+    },
+  },
+  brand: {
+    url: id => `styles/brand/${id}.css`,
+    icon: 'droplet',
+    default(baseTheme) {
+      return baseTheme?.brand;
+    },
+  },
+  typography: {
+    url: id => `styles/themes/${id}/typography.css`,
+    docs: '/docs/themes/',
+    icon: 'font-case',
+    default() {
+      return this.base;
+    },
+  },
+  icon: {
+    library: { cssProperty: '--wa-icon-library', default: 'default' },
+    family: {
+      cssProperty: '--wa-icon-family',
+      default(baseTheme) {
+        return baseTheme?.icon?.family ?? 'classic';
+      },
+    },
+    style: {
+      cssProperty: '--wa-icon-variant',
+      default(baseTheme) {
+        return baseTheme?.icon?.style ?? 'solid';
+      },
+    },
+  },
+};
+
+// Shallow remixing params in correct order
+// base must be first. brand needs to come after palette, which needs to come after colors.
+export const themeParams = Object.keys(themeConfig).filter(aspect => themeConfig[aspect].url);
+
+export const urls = themeParams.reduce((acc, aspect) => {
+  acc[aspect] = themeConfig[aspect].url;
+  return acc;
+}, {});
+
+export const themeDefaults = { ...themeConfig };
+
+deepEach(themeDefaults, (value, key, parent, path) => {
+  if (isPlainObject(value)) {
+    // Replace w/ default value or shallow clone
+    return value.default ?? { ...value };
+  }
+});
+
+export const selectors = {
+  palette: id =>
+    [':where(:root)', ':host', ":where([class^='wa-theme-'], [class*=' wa-theme-'])", `.wa-palette-${id}`].join(',\n'),
+  theme: id => [':where(:root)', ':host', `.wa-theme-${id}`].join(',\n'),
+};

docs/assets/scripts/code-examples.js

@@ -1,59 +0,0 @@
-document.addEventListener('click', event => {
-  const toggle = event.target?.closest('.code-example-toggle');
-  const pen = event.target?.closest('.code-example-pen');
-
-  // Toggle source
-  if (toggle) {
-    const codeExample = toggle.closest('.code-example');
-    const isOpen = !codeExample.classList.contains('open');
-
-    toggle.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
-    codeExample.classList.toggle('open', isOpen);
-  }
-
-  // Edit in CodePen
-  if (pen) {
-    const codeExample = pen.closest('.code-example');
-    const code = codeExample.querySelector('code');
-    const cdnUrl = document.documentElement.dataset.cdnUrl;
-    const html =
-      `<script type="module" src="${cdnUrl}webawesome.loader.js"></script>\n` +
-      `<link rel="stylesheet" href="${cdnUrl}styles/themes/default.css">\n` +
-      `<link rel="stylesheet" href="${cdnUrl}styles/webawesome.css">\n` +
-      `<link rel="stylesheet" href="${cdnUrl}styles/utilities.css">\n\n` +
-      `${code.textContent}`;
-    const css = 'html > body {\n  padding: 2rem !important;\n}';
-    const js = '';
-
-    const form = document.createElement('form');
-    form.action = 'https://codepen.io/pen/define';
-    form.method = 'POST';
-    form.target = '_blank';
-
-    const data = {
-      title: '',
-      description: '',
-      tags: ['webawesome'],
-      editors: '1000',
-      head: '<meta name="viewport" content="width=device-width">',
-      html_classes: '',
-      css_external: '',
-      js_external: '',
-      js_module: true,
-      js_pre_processor: 'none',
-      html,
-      css,
-      js,
-    };
-
-    const input = document.createElement('input');
-    input.type = 'hidden';
-    input.name = 'data';
-    input.value = JSON.stringify(data);
-    form.append(input);
-
-    document.documentElement.append(form);
-    form.submit();
-    form.remove();
-  }
-});

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/hydration-errors.js

@@ -51,7 +51,7 @@
       <button class="diff-dialog-toggle">
         Show Hydration Mismatch
       </button>
-      <wa-dialog class="diff-dialog" with-header light-dismiss>
+      <wa-dialog class="diff-dialog" light-dismiss>
         <div class="diff-grid">
           <div>
             <div>Server</div>

docs/assets/scripts/my.js

@@ -0,0 +1,172 @@
+const my = (globalThis.my = new EventTarget());
+export default my;
+
+class PersistedArray extends Array {
+  constructor(key) {
+    super();
+    this.key = key;
+
+    if (this.key) {
+      this.fromLocalStorage();
+    }
+
+    // Items were updated in another tab
+    addEventListener('storage', event => {
+      if (event.key === this.key || !event.key) {
+        this.fromLocalStorage();
+      }
+    });
+  }
+
+  /**
+   * Update data from local storage
+   */
+  fromLocalStorage() {
+    // First, empty the array
+    this.splice(0, this.length);
+
+    // Then, fill it with the data from local storage
+    let saved = localStorage[this.key] ? JSON.parse(localStorage[this.key]) : null;
+
+    if (saved) {
+      this.push(...saved);
+    }
+  }
+
+  /**
+   * Write data to local storage
+   */
+  toLocalStorage() {
+    if (this.length > 0) {
+      localStorage[this.key] = JSON.stringify(this);
+    } else {
+      delete localStorage[this.key];
+    }
+  }
+}
+
+class SavedEntities extends EventTarget {
+  constructor({ key, type, url }) {
+    super();
+    this.key = key;
+    this.type = type;
+    this.url = url ?? type + 's';
+    this.saved = new PersistedArray(key);
+
+    let all = this;
+    this.entityPrototype = {
+      type: this.type,
+      baseUrl: this.baseUrl,
+
+      get url() {
+        return all.getURL(this);
+      },
+
+      get parentUrl() {
+        return all.getParentURL(this);
+      },
+
+      delete() {
+        all.delete(this);
+      },
+    };
+  }
+
+  getUid() {
+    if (this.saved.length === 0) {
+      return 1;
+    }
+
+    let uids = new Set(this.saved.map(p => p.uid));
+
+    // Find first available number
+    for (let i = 1; i <= this.saved.length + 1; i++) {
+      if (!uids.has(i)) {
+        return i;
+      }
+    }
+  }
+
+  get baseUrl() {
+    return `/docs/${this.url}/`;
+  }
+
+  getURL(entity) {
+    return this.getParentURL(entity) + entity.search;
+  }
+
+  getParentURL(entity) {
+    return this.baseUrl + entity.id + '/';
+  }
+
+  getObject(entity) {
+    let ret = Object.create(this.entityPrototype, Object.getOwnPropertyDescriptors(entity));
+    // debugger;
+    return ret;
+  }
+
+  /**
+   * Save an entity, either by updating its existing entry or creating a new one
+   * @param {object} entity
+   */
+  save(entity) {
+    if (!entity.uid) {
+      // First time saving
+      entity.uid = this.getUid();
+    }
+
+    let savedPalettes = this.saved;
+    let existingIndex = entity.uid ? this.saved.findIndex(p => p.uid === entity.uid) : -1;
+    let newIndex = existingIndex > -1 ? existingIndex : savedPalettes.length;
+
+    this.saved.splice(newIndex, 1, entity);
+
+    this.saved.toLocalStorage();
+
+    this.dispatchEvent(new CustomEvent('save', { detail: this.getObject(entity) }));
+
+    return entity;
+  }
+
+  delete(entity) {
+    let count = this.saved.length;
+
+    if (count === 0 || !entity?.uid) {
+      // No stored entities or this entity has not been saved
+      return;
+    }
+
+    // TODO improve UX of this
+    if (!confirm(`Are you sure you want to delete ${this.type} “${entity.title}”?`)) {
+      return;
+    }
+
+    for (let index; (index = this.saved.findIndex(p => p.uid === entity.uid)) > -1; ) {
+      this.saved.splice(index, 1);
+    }
+
+    if (this.saved.length === count) {
+      // Nothing was removed
+      return;
+    }
+
+    this.saved.toLocalStorage();
+
+    this.dispatchEvent(new CustomEvent('delete', { detail: this.getObject(entity) }));
+  }
+
+  dispatchEvent(event) {
+    super.dispatchEvent(event);
+    my.dispatchEvent(event);
+  }
+}
+
+my.palettes = new SavedEntities({
+  key: 'savedPalettes',
+  type: 'palette',
+});
+
+my.themes = new SavedEntities({
+  key: 'savedThemes',
+  type: 'theme',
+});

docs/assets/scripts/permalink.js

@@ -0,0 +1,157 @@
+import { deepEach, deepGet, deepSet } from './util/deep.js';
+
+export default class Permalink extends URLSearchParams {
+  /** Params changed since last URL I/O */
+  changed = false;
+
+  constructor(params) {
+    super(location.search);
+    this.params = params;
+  }
+
+  toJSON() {
+    return Object.fromEntries(this.entries());
+  }
+
+  /**
+   * Set multiple values from an object. Nested values will be joined with a hyphen.
+   * @param {object} values - The object containing the values to set.
+   * @param {object} defaults - The object containing the default values.
+   *
+   */
+  setAll(values, defaults) {
+    deepEach(values, (value, key, parent, path) => {
+      let fullPath = [...path, key];
+      let param = fullPath.join('-');
+      let defaultValue = deepGet(defaults, fullPath);
+
+      if (typeof value === 'object') {
+        // We'll handle this when we descend into it
+        return;
+      }
+
+      if (!value || value === defaultValue) {
+        // Remove the param from the URL
+        this.delete(param);
+        return;
+      }
+
+      this.set(param, value);
+    });
+  }
+
+  getAll(...args) {
+    if (args.length > 0) {
+      return super.getAll(...args);
+    }
+
+    // Get all values as a nested object
+    // Assumes that hyphens always mean nesting
+    let obj = {};
+
+    for (let [key, value] of this.entries()) {
+      let path = key.split('-');
+      deepSet(obj, path, value);
+    }
+
+    return obj;
+  }
+
+  delete(key, value) {
+    let hadValue = this.has(key);
+    super.delete(key, value);
+
+    if (hadValue) {
+      this.changed = true;
+    }
+  }
+
+  set(key, value, defaultValue) {
+    if (equals(value, defaultValue) || equals(value, '')) {
+      value = null;
+    }
+
+    value ??= null; // undefined -> null
+
+    let oldValue = Array.isArray(value) ? this.getAll(key) : this.get(key);
+    let changed = !equals(value, oldValue);
+
+    if (!changed) {
+      // Nothing to do here
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      super.delete(key);
+      value = value.slice();
+
+      for (let v of value) {
+        if (v || v === 0) {
+          if (typeof v === 'object') {
+            super.append(key, JSON.stringify(v));
+          } else {
+            super.append(key, v);
+          }
+        }
+      }
+    } else if (value === null) {
+      super.delete(key);
+    } else {
+      super.set(key, value);
+    }
+
+    this.sort();
+    this.changed ||= changed;
+  }
+
+  /**
+   * Update page URL if it has changed since last time
+   */
+  updateLocation() {
+    if (this.changed) {
+      // If there’s already a search, replace it.
+      // We don’t want to clog the user’s history while they iterate
+      let search = this.toString();
+      let historyAction = location.search && search ? 'replaceState' : 'pushState';
+      history[historyAction](null, '', `?${search}`);
+      this.changed = false;
+    }
+  }
+}
+
+function equals(value, oldValue) {
+  if (Array.isArray(value) || Array.isArray(oldValue)) {
+    value = toArray(value);
+    oldValue = toArray(oldValue);
+
+    if (value.length !== oldValue.length) {
+      return false;
+    }
+
+    return value.every((v, i) => equals(v, oldValue[i]));
+  }
+
+  // (value ?? oldValue ?? true) returns true if they're both empty (null or undefined)
+  [value, oldValue] = [value, oldValue].map(v => (!v && v !== false && v !== 0 ? null : v));
+  return value === oldValue || String(value) === String(oldValue);
+}
+
+/**
+ * Convert a value to an array. `undefined` and `null` values are converted to an empty array.
+ * @param {*} value - The value to convert.
+ * @returns {any[]} The converted array.
+ */
+function toArray(value) {
+  value ??= [];
+
+  if (Array.isArray(value)) {
+    return value;
+  }
+
+  // Don't convert "foo" into ["f", "o", "o"]
+  if (typeof value !== 'string' && typeof value[Symbol.iterator] === 'function') {
+    return Array.from(value);
+  }
+
+  return [value];
+}

docs/assets/scripts/sidebar-tweaks.js

@@ -1,254 +1,120 @@
-const sidebar = (globalThis.sidebar = {});
+import my from '/assets/scripts/my.js';
 
-sidebar.palettes = {
-  render() {
-    if (this.saved.length === 0) {
-      return;
-    }
+const sidebar = {
+  addChild(a, parentA) {
+    let parentLi = parentA.closest('li');
+    let ul = parentLi.querySelector(':scope > ul');
+    ul ??= parentLi.appendChild(document.createElement('ul'));
+    let li = document.createElement('li');
+    li.append(a);
+    ul.appendChild(li);
 
-    for (let palette of this.saved) {
-      sidebar.palette.render(palette);
-    }
-
-    sidebar.updateCurrent();
-  },
-
-  updateSaved() {
-    this.saved = localStorage.savedPalettes ? JSON.parse(localStorage.savedPalettes) : [];
-  },
-
-  save(saved = this.saved) {
-    this.saved = saved ?? [];
-
-    if (saved.length > 0) {
-      localStorage.savedPalettes = JSON.stringify(saved);
-    } else {
-      delete localStorage.savedPalettes;
-    }
-  },
-};
-
-sidebar.palettes.updateSaved();
-addEventListener('storage', event => sidebar.palettes.updateSaved());
-
-sidebar.palette = {
-  getUid() {
-    let savedPalettes = sidebar.palettes.saved;
-    let uids = new Set(savedPalettes.map(p => p.uid));
-
-    if (savedPalettes.length === 0) {
-      return 1;
-    }
-
-    // Find first available number
-    for (let i = 1; i <= savedPalettes.length + 1; i++) {
-      if (!uids.has(i)) {
-        return i;
+    // If we are on the same page, update the current link
+    let url = location.href.replace(/#.+$/, '');
+    if (url.startsWith(a.href)) {
+      // Remove existing current
+      for (let current of document.querySelectorAll('#sidebar a.current')) {
+        current.classList.remove('current');
       }
-    }
-  },
 
-  equals(p1, p2) {
-    if (!p1 || !p2) {
-      return false;
+      a.classList.add('current');
     }
 
-    return p1.id === p2.id && p1.uid === p2.uid;
+    return a;
   },
 
-  delete(palette) {
-    let savedPalettes = sidebar.palettes.saved;
-    let count = savedPalettes.length;
-    if (count === 0) {
+  removeLink(a) {
+    if (!a || !a.isConnected) {
+      // Link doesn't exist or is already removed
       return;
     }
 
-    // TODO improve UX of this
-    if (!confirm(`Are you sure you want to delete palette “${palette.title}”?`)) {
-      return;
+    let li = a?.closest('li');
+    let ul = li?.closest('ul');
+    let parentA = ul?.closest('li')?.querySelector(':scope > a');
+
+    li?.remove();
+    if (ul?.children.length === 0) {
+      ul.remove();
     }
 
-    savedPalettes = savedPalettes.filter(p => !sidebar.palette.equals(palette, p));
-
-    if (savedPalettes.length === count) {
-      // Nothing was removed
-      return;
-    }
-
-    // Update UI
-    let pathname = `/docs/palettes/${palette.id}/`;
-    let url = pathname + palette.search;
-    let uls = new Set();
-
-    for (let a of document.querySelectorAll(`#sidebar a[href="${url}"]`)) {
-      let li = a.closest('li');
-      let ul = li.closest('ul');
-      uls.add(ul);
-      li.remove();
-    }
-
-    // Remove empty lists
-    for (let ul of uls) {
-      if (!ul.children.length) {
-        ul.remove();
-      }
-    }
-
-    sidebar.updateCurrent();
-
-    sidebar.palettes.save(savedPalettes);
-
-    if (sidebar.palette.equals(globalThis.paletteApp?.saved, palette)) {
-      paletteApp.postDelete();
+    if (a.classList.contains('current')) {
+      // If the deleted palette was the current one, the current one is now the parent
+      parentA.classList.add('current');
     }
   },
 
-  getSaved(palette, savedPalettes = sidebar.palettes.saved) {
-    return savedPalettes.find(p => sidebar.palette.equals(p, palette));
+  findEntity(entity) {
+    return document.querySelector(`#sidebar a[href^="${entity.baseUrl}"][data-uid="${entity.uid}"]`);
   },
 
-  render(palette) {
-    // Find existing <a>
-    let { title, id, search, uid } = palette;
+  renderEntity(entity) {
+    let { url, parentUrl } = entity;
 
-    for (let a of document.querySelectorAll(`#sidebar a[href^="/docs/palettes/${id}/"][data-uid="${uid}"]`)) {
-      // Palette already in sidebar, just update it
-      a.textContent = palette.title;
-      a.href = `/docs/palettes/${id}/${search}`;
-      return;
-    }
-
-    let pathname = `/docs/palettes/${id}/`;
-    let url = pathname + search;
-    let parentA = document.querySelector(`a[href="${pathname}"]`);
+    // Find parent
+    let parentA = document.querySelector(`#sidebar a[href="${parentUrl}"]`);
     let parentLi = parentA?.closest('li');
-    let a;
 
-    if (parentLi) {
-      a = Object.assign(document.createElement('a'), { href: url, textContent: title });
-      a.dataset.uid = uid;
-      let badges = [...parentLi.querySelectorAll('wa-badge')].map(badge => badge.cloneNode(true));
-      let ul = parentLi.querySelector('ul') ?? parentLi.appendChild(document.createElement('ul'));
-      let li = document.createElement('li');
-      let deleteButton = Object.assign(document.createElement('wa-icon-button'), {
-        name: 'trash',
-        label: 'Delete',
-        className: 'delete',
-      });
-
-      deleteButton.addEventListener('click', () => {
-        let palette = { id, uid, title: a.textContent, search: a.search };
-        sidebar.palette.delete(palette);
-      });
-
-      li.append(a, ' ', ...badges, deleteButton);
-      ul.appendChild(li);
-    }
-  },
-
-  save(palette, saved) {
-    let savedPalettes = sidebar.palettes.saved;
-    let existing = this.getSaved(saved ?? palette, savedPalettes);
-    let oldValues;
-
-    if (existing) {
-      // Rename
-      oldValues = { ...existing };
-      Object.assign(existing, palette);
-    } else {
-      savedPalettes.push(palette);
+    if (!parentLi) {
+      throw new Error(`Cannot find parent url ${parentUrl}`);
     }
 
-    this.render(palette, oldValues);
-    sidebar.updateCurrent();
+    // Find existing
+    let a = this.findEntity(entity);
+    let alreadyExisted = !!a;
 
-    sidebar.palettes.save(savedPalettes);
-  },
-};
+    a ??= document.createElement('a');
 
-sidebar.updateCurrent = function () {
-  // Find the sidebar link with the longest shared prefix with the current URL
-  let pathParts = location.pathname.split('/').filter(Boolean);
-  let prefixes = [];
+    a.textContent = entity.title;
+    a.href = url;
 
-  if (pathParts.length === 1) {
-    // If at /docs/ we just use that, otherwise we want at least two parts (/docs/xxx/)
-    prefixes.push('/' + pathParts[0] + '/');
-  } else {
-    for (let i = 2; i <= pathParts.length; i++) {
-      prefixes.push('/' + pathParts.slice(0, i).join('/') + '/');
-    }
-  }
+    if (!alreadyExisted) {
+      a.dataset.uid = entity.uid;
 
-  // Last prefix includes the search too (if any)
-  if (location.search) {
-    let params = new URLSearchParams(location.search);
-    params.sort();
-    prefixes.push(prefixes.at(-1) + location.search);
-  }
+      a = sidebar.addChild(a, parentA);
 
-  // We want to start from the longest prefix
-  prefixes.reverse();
-  let candidates;
-  let matchingPrefix;
+      // This is mainly to port Pro badges
+      let badges = Array.from(parentLi.querySelectorAll(':scope > wa-badge'), badge => badge.cloneNode(true));
 
-  for (let prefix of prefixes) {
-    candidates = document.querySelectorAll(`#sidebar a[href^="${prefix}"]`);
+      let append = [...badges];
 
-    if (candidates.length > 0) {
-      matchingPrefix = prefix;
-      break;
-    }
-  }
-
-  if (!matchingPrefix) {
-    // Abort mission
-    return;
-  }
-
-  if (matchingPrefix === pathParts.at(-1)) {
-    // Full path matches, check search
-    if (location.search) {
-      candidates = [...candidates];
-
-      let searchParams = new URLSearchParams(location.search);
-
-      if (searchParams.has('uid')) {
-        // Only consider candidates with the same uid
-        candidates = candidates.filter(a => {
-          let params = new URLSearchParams(a.search);
-          return params.get('uid') === searchParams.get('uid');
-        });
-      } else {
-        // Sort candidates based on how many params they have in common, in descending order
-        candidates = candidates.sort((a, b) => {
-          return countSharedSearchParams(searchParams, b.search) - countSharedSearchParams(searchParams, a.search);
+      if (entity.delete) {
+        let deleteButton = Object.assign(document.createElement('wa-icon-button'), {
+          name: 'trash',
+          label: 'Delete',
+          className: 'delete',
         });
+        deleteButton.addEventListener('click', () => entity.delete());
+        append.push(deleteButton);
+      }
+
+      if (append.length > 0) {
+        a.closest('li').append(' ', ...append);
       }
     }
-  }
+  },
 
-  if (candidates.length > 0) {
-    for (let current of document.querySelectorAll('#sidebar a.current')) {
-      current.classList.remove('current');
+  render() {
+    for (let type in my) {
+      let controller = my[type];
+
+      if (!controller.saved) {
+        continue;
+      }
+
+      for (let entity of controller.saved) {
+        let object = controller.getObject(entity);
+        this.renderEntity(object);
+      }
     }
-
-    candidates[0].classList.add('current');
-  }
+  },
 };
 
-sidebar.render = function () {
-  this.palettes.render();
-};
+globalThis.sidebar = sidebar;
+
+// Update sidebar when my saved stuff changes
+my.addEventListener('delete', e => sidebar.removeLink(sidebar.findEntity(e.detail)));
+my.addEventListener('save', e => sidebar.renderEntity(e.detail));
 
 sidebar.render();
 window.addEventListener('turbo:render', () => sidebar.render());
-
-function countSharedSearchParams(searchParams, search) {
-  if (!search || search === '?') {
-    return 0;
-  }
-
-  let params = new URLSearchParams(search);
-  return [...searchParams.keys()].filter(k => params.get(k) === searchParams.get(k)).length;
-}

docs/assets/scripts/theme-picker.js

@@ -1,14 +1,5 @@
-// Helper for view transitions
-export function domChange(fn, { behavior = 'smooth' } = {}) {
-  const canUseViewTransitions =
-    document.startViewTransition && !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-
-  if (canUseViewTransitions && behavior === 'smooth') {
-    document.startViewTransition(fn);
-  } else {
-    fn(true);
-  }
-}
+import { domChange } from './util/dom-change.js';
+export { domChange };
 
 export function nextFrame() {
   return new Promise(resolve => requestAnimationFrame(resolve));
@@ -100,6 +91,7 @@ const colorScheme = new ThemeAspect({
     domChange(() => {
       let dark = this.computedValue === 'dark';
       document.documentElement.classList.toggle(`wa-dark`, dark);
+      document.documentElement.dispatchEvent(new CustomEvent('wa-color-scheme-change', { detail: { dark } }));
     });
   },
 });
@@ -114,6 +106,6 @@ document.addEventListener('keydown', event => {
     !event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
   ) {
     event.preventDefault();
-    colorScheme.set(theming.colorScheme.resolvedValue === 'dark' ? 'light' : 'dark');
+    colorScheme.set(colorScheme.get() === 'dark' ? 'light' : 'dark');
   }
 });

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/scripts/tweak.js

@@ -1,6 +1,6 @@
 /**
  * Get import code for remixed themes and tweaked palettes.
  */
+export { cdnUrl, hueRanges, hues, selectors, tints, urls } from '../data/index.js';
+export { default as Permalink } from './permalink.js';
 export { getThemeCode } from './tweak/code.js';
-export { cdnUrl, hueRanges, hues, selectors, tints, urls } from './tweak/data.js';
-export { default as Permalink } from './tweak/permalink.js';

docs/assets/scripts/tweak/code.js

@@ -1,7 +1,8 @@
 /**
  * Get import code for remixed themes and tweaked palettes.
  */
-import { urls } from './data.js';
+import { selectors, themeConfig } from '../../data/theming.js';
+import { deepEach, deepGet } from '/assets/scripts/util/deep.js';
 
 export function cssImport(url, options = {}) {
   let { language = 'html', cdnUrl = '/dist/', attributes } = options;
@@ -21,29 +22,65 @@ export function cssLiteral(value, options = {}) {
   if (language === 'css') {
     return value;
   } else {
-    return `<style>\n${value}\n</style>`;
+    return `<style${options.attributes ?? ''}>\n${value}\n</style>`;
   }
 }
 
-// Params in correct order
-export const themeParams = ['colors', 'palette', 'brand', 'typography'];
+/**
+ * Get code for a theme, including tweaks
+ * @param {*} theme
+ * @param {*} options
+ * @returns
+ */
+export function getThemeCode(theme, options = {}) {
+  let urls = [];
+  let declarations = [];
+  let id = options.id ?? theme.base ?? 'default';
 
-export function getThemeCode(base, params, options) {
-  let ret = [];
+  deepEach(themeConfig, (config, aspect, obj, path) => {
+    if (!config?.default) {
+      // We're not in a config object
+      return;
+    }
 
-  if (base) {
-    ret.push(urls.theme(base));
-  }
+    let value = deepGet(theme, [...path, aspect]);
 
-  for (let aspect of themeParams) {
-    let value = params[aspect];
+    if (!value) {
+      return;
+    }
 
-    if (value) {
-      ret.push(urls[aspect](value));
+    if (config.url) {
+      // This is implemented by pulling in different CSS files
+      urls.push(config.url(value));
+    } else {
+      if (config.cssProperty) {
+        declarations.push(`${config.cssProperty}: ${value};`);
+      }
+    }
+  });
+
+  let ret = urls.map(url => cssImport(url, options)).join('\n');
+
+  if (declarations.length > 0) {
+    let cssCode = cssRule(selectors.theme(id), declarations, options);
+
+    let faKitAttribute = ` data-fa-kit-code="${theme.icon.kit}"`;
+    if (theme.icon.kit) {
+      options.attributes ??= '';
+      options.attributes += faKitAttribute;
+      cssCode =
+        `/* Note: To use Font Awesome Pro icons,\n   set ${faKitAttribute} on the <link> (or any other) element */\n\n` +
+        cssCode;
+    }
+
+    cssCode = cssLiteral(cssCode, options);
+
+    if (ret) {
+      ret += '\n\n' + cssCode;
     }
   }
 
-  return ret.map(url => cssImport(url, options)).join('\n');
+  return ret;
 }
 
 export function cssRule(selector, declarations, { indent = '  ' } = {}) {

docs/assets/scripts/tweak/permalink.js

@@ -1,81 +0,0 @@
-const IDENTITY = x => x;
-
-export default class Permalink extends URLSearchParams {
-  /** Params changed since last URL I/O */
-  changed = false;
-
-  constructor(params) {
-    super(location.search);
-    this.params = params;
-  }
-
-  toJSON() {
-    return Object.fromEntries(this.entries());
-  }
-
-  #mappings = new WeakMap();
-
-  mapObject(obj, mapping = {}) {
-    this.#mappings.set(obj, mapping);
-  }
-
-  readFrom(obj) {
-    let mapping = this.#mappings.get(obj) ?? {};
-    let { keyFrom = IDENTITY, valueFrom = IDENTITY } = mapping;
-
-    for (let key in obj) {
-      let value = obj[key];
-      let mappedValue = valueFrom(value);
-      let mappedKey = keyFrom(key);
-      this.set(mappedKey, mappedValue);
-    }
-  }
-
-  writeTo(obj) {
-    let mapping = this.#mappings.get(obj) ?? {};
-    let { keyTo = IDENTITY, valueTo = IDENTITY, canExtend = false } = mapping;
-
-    for (let [key, value] of this) {
-      let mappedKey = keyTo(key);
-      let mappedValue = valueTo(value);
-
-      if (canExtend || mappedKey in obj) {
-        obj[mappedKey] = mappedValue;
-      }
-    }
-  }
-
-  set(key, value, defaultValue) {
-    let oldValue = this.get(key);
-
-    if (!value || value == defaultValue) {
-      super.delete(key);
-
-      if (oldValue) {
-        this.changed = true;
-      }
-    } else {
-      super.set(key, value);
-
-      if (String(value) !== String(oldValue)) {
-        this.changed = true;
-      }
-    }
-
-    this.sort();
-  }
-
-  /**
-   * Update page URL if it has changed since last time
-   */
-  updateLocation() {
-    if (this.changed) {
-      // If there’s already a search, replace it.
-      // We don’t want to clog the user’s history while they iterate
-      let search = this.toString();
-      let historyAction = location.search && search ? 'replaceState' : 'pushState';
-      history[historyAction](null, '', `?${search}`);
-      this.changed = false;
-    }
-  }
-}

docs/assets/scripts/util/array.js

@@ -0,0 +1,17 @@
+/**
+ * Picks a random element from an array.
+ * @param {any[]} arr
+ */
+export function sample(arr) {
+  if (!Array.isArray(arr)) {
+    return arr;
+  }
+
+  if (arr.length < 2) {
+    return arr[0];
+  }
+
+  let index = Math.floor(Math.random() * arr.length);
+
+  return arr[index];
+}

docs/assets/scripts/util/deep.js

@@ -0,0 +1,180 @@
+/**
+ * @typedef { string | number | Symbol } Property
+ * @typedef { (value: any, key: Property, parent: object, path: Property[]) => any } EachCallback
+ */
+
+export function isPlainObject(obj) {
+  return isObject(obj, 'Object');
+}
+
+export function isObject(obj, type) {
+  if (!obj || typeof obj !== 'object') {
+    return false;
+  }
+
+  let proto = Object.getPrototypeOf(obj);
+  return proto.constructor?.name === type;
+}
+
+export function deepMerge(target, source, options = {}) {
+  let {
+    emptyValues = [undefined],
+    containers = ['Object', 'EventTarget'],
+    isContainer = value => containers.some(type => isObject(value, type)),
+  } = options;
+
+  if (isContainer(target) && isContainer(source)) {
+    for (let key in source) {
+      if (key in target && isContainer(target[key]) && isContainer(source[key])) {
+        target[key] = deepMerge(target[key], source[key], options);
+      } else if (!emptyValues.includes(source[key])) {
+        target[key] = source[key];
+      }
+    }
+
+    return target;
+  }
+
+  return target ?? source;
+}
+
+/**
+ * Iterate over a deep array, recursively for plain objects
+ * @param { any } obj The object to iterate over. Can be an array or a plain object, or even a primitive value.
+ * @param { EachCallback } callback. value is === parent[key]
+ * @param { object } [parentObj] The parent object of the current value Mainly used internally to facilitate recursion.
+ * @param { Property } [key] The key of the current value. Mainly used internally to facilitate recursion.
+ * @param { Property[] } [path] Any existing path (not including the key). Mainly used internally to facilitate recursion.
+ */
+export function deepEach(obj, callback, parentObj, key, path = []) {
+  if (key !== undefined) {
+    let ret = callback(obj, key, parentObj, path);
+
+    if (ret !== undefined) {
+      if (ret === false) {
+        // Do not descend further
+        return;
+      }
+
+      // Overwrite value
+      parentObj[key] = ret;
+      obj = ret;
+    }
+  }
+
+  let newPath = key !== undefined ? [...path, key] : path;
+
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      deepEach(obj[i], callback, obj, i, newPath);
+    }
+  } else if (isPlainObject(obj)) {
+    for (let key in obj) {
+      deepEach(obj[key], callback, obj, key, newPath);
+    }
+  }
+}
+
+/**
+ * Get a value from a deeply nested object
+ * @param {*} obj
+ * @param {PropertyPath} path
+ * @returns
+ */
+export function deepGet(obj, path) {
+  if (path.length === 0) {
+    return obj;
+  }
+
+  let ret = obj;
+
+  for (let key of path) {
+    if (ret === undefined) {
+      return undefined;
+    }
+
+    ret = ret[key];
+  }
+
+  return ret;
+}
+
+/**
+ * Set a value in a deep object, creating object literals as needed
+ * @param { * } obj
+ * @param { Property[] } path
+ * @param { any } value
+ */
+export function deepSet(obj, path, value) {
+  if (path.length === 0) {
+    return;
+  }
+
+  let key = path.pop();
+
+  let ret = path.reduce((acc, property) => {
+    if (acc[property] === undefined) {
+      acc[property] = {};
+    }
+
+    return acc[property];
+  }, obj);
+
+  ret[key] = value;
+}
+
+export function deepClone(obj) {
+  if (!obj) {
+    return obj;
+  }
+
+  let ret = obj;
+
+  if (Array.isArray(obj)) {
+    ret = obj.map(item => deepClone(item));
+  } else if (isPlainObject(obj)) {
+    ret = { ...obj };
+
+    for (let key in obj) {
+      ret[key] = deepClone(obj[key]);
+    }
+  }
+
+  return ret;
+}
+
+/**
+ * Like Object.entries, but for deeply nested objects.
+ * For shallow objects the output is the same as Object.entries.
+ * @param {*} obj
+ * @param { object } options
+ * @param { EachCallback } each - If this returns false, the entry is not added to the result and the recursion is stopped.
+ * @param { EachCallback } filter - If this returns false, the entry is not added to the result.
+ * @param { EachCallback } descend - If this returns false, recursion is stopped.
+ * @returns {any[][]}
+ */
+export function deepEntries(obj, options = {}) {
+  let { each, filter, descend } = options;
+  let entries = [];
+
+  deepEach(obj, (value, key, parent, path) => {
+    let ret = each?.(value, key, parent, path);
+
+    if (ret !== false) {
+      let included = filter?.(value, key, parent, path) ?? true;
+
+      if (included) {
+        entries.push([...path, key, value]);
+      }
+
+      let descendRet = descend?.(value, key, parent, path);
+      if (descendRet === false) {
+        return false; // Stop recursion
+      }
+    }
+
+    return ret;
+  });
+
+  return entries;
+}

docs/assets/scripts/util/dom-change.js

@@ -0,0 +1,39 @@
+let initialPageLoadComplete = document.readyState === 'complete';
+
+if (!initialPageLoadComplete) {
+  window.addEventListener('load', () => {
+    initialPageLoadComplete = true;
+  });
+}
+
+/**
+ * Helper for performing a DOM change using a view transition, wherever supported and reduced motion is not desired.
+ * @param {function} fn - Function to perform the DOM change. If async, must resolve when the change is complete.
+ * @param {object} [options] - Options for the transition
+ * @param {'smooth' | 'instant'} [options.behavior] - Transition behavior. Defaults to 'smooth'. 'instant' will skip the transition.
+ * @param {boolean} [options.ignoreInitialLoad] - If true, will skip the transition on initial page load. Defaults to true.
+ */
+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') {
+    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(false);
+    return null;
+  }
+}
+
+export default domChange;

docs/assets/scripts/util/string.js

@@ -0,0 +1,24 @@
+/**
+ * Make the first letter of a string uppercase
+ * @param {*} str
+ * @returns
+ */
+export function capitalize(str) {
+  str += '';
+  return str[0].toUpperCase() + str.slice(1);
+}
+
+/**
+ * Convert a readable string to a slug.
+ * @param {*} str - Input string. If argument is not a string, it will be stringified.
+ * @returns {string} - The slugified string
+ */
+export function slugify(str) {
+  return (str + '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '') // Convert accented letters to ASCII
+    .replace(/[^\w\s-]/g, '') // Remove remaining non-ASCII characters
+    .trim()
+    .replace(/\s+/g, '-') // Convert whitespace to hyphens
+    .toLowerCase();
+}

docs/assets/styles/code-examples.css

@@ -1,87 +0,0 @@
-.code-example {
-  border: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
-  border-radius: var(--wa-border-radius-l);
-  color: var(--wa-color-text-normal);
-  margin-block-end: var(--wa-flow-spacing);
-}
-
-.code-example-preview {
-  padding: 2rem;
-  border-bottom: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
-
-  > :first-child {
-    margin-block-start: 0;
-  }
-
-  > :last-child {
-    margin-block-end: 0;
-  }
-}
-
-.code-example-source {
-  border-bottom: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
-}
-
-.code-example:not(.open) .code-example-source {
-  display: none;
-}
-
-.code-example.open .code-example-toggle wa-icon {
-  rotate: 180deg;
-}
-
-.code-example-source pre {
-  position: relative;
-  border-radius: 0;
-  margin: 0;
-  white-space: normal;
-}
-
-.code-example-source:not(:has(+ .code-example-buttons)) {
-  border-bottom: none;
-
-  pre {
-    border-bottom-right-radius: var(--wa-border-radius-l);
-    border-bottom-left-radius: var(--wa-border-radius-l);
-  }
-}
-
-.code-example-buttons {
-  display: flex;
-  align-items: stretch;
-
-  button {
-    all: unset;
-    flex: 1 0 auto;
-    font-size: 0.875rem;
-    color: var(--wa-color-text-quiet);
-    border-left: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
-    text-align: center;
-    padding: 0.5rem;
-    cursor: pointer;
-
-    &:first-of-type {
-      border-left: none;
-      border-bottom-left-radius: var(--wa-border-radius-l);
-    }
-
-    &:last-of-type {
-      border-bottom-right-radius: var(--wa-border-radius-l);
-    }
-
-    &:focus-visible {
-      outline: var(--wa-focus-ring);
-    }
-  }
-
-  .code-example-pen {
-    flex: 0 0 100px;
-    white-space: nowrap;
-  }
-
-  wa-icon {
-    width: 1em;
-    height: 1em;
-    vertical-align: -2px;
-  }
-}

docs/assets/styles/docs.css

@@ -1,9 +1,9 @@
-@import 'code-examples.css';
 @import 'code-highlighter.css';
 @import 'copy-code.css';
 @import 'outline.css';
 @import 'search.css';
 @import 'cera_typeface.css';
+@import 'theme-icons.css';
 
 :root {
   --wa-brand-orange: #f36944;
@@ -256,15 +256,6 @@ wa-page > main {
 }
 
 h1.title {
-  wa-icon-button {
-    font-size: var(--wa-font-size-l);
-    color: var(--wa-color-text-quiet);
-
-    &:not(:hover, :focus) {
-      opacity: 0.5;
-    }
-  }
-
   wa-badge {
     vertical-align: middle;
     font-size: 1.5rem;
@@ -370,29 +361,29 @@ 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;
   }
 
   wa-card {
-    box-shadow: none;
     --spacing: var(--wa-space-m);
-    inline-size: 100%;
-
-    &:hover {
-      --border-color: var(--wa-color-brand-border-loud);
-      border-color: var(--border-color);
-      box-shadow: 0 0 0 var(--wa-border-width-s) var(--border-color);
-
-      .page-name {
-        color: var(--wa-color-brand-on-quiet);
-      }
-    }
 
     [slot='header'] {
       display: flex;
@@ -400,18 +391,17 @@ wa-page > main:has(> .index-grid) {
 
     &::part(header) {
       background-color: var(--header-background, var(--wa-color-neutral-fill-quiet));
-      border-bottom: none;
       display: flex;
       align-items: center;
       justify-content: center;
       min-block-size: calc(6rem + var(--spacing));
     }
   }
+}
 
-  .page-name {
-    font-size: var(--wa-font-size-s);
-    font-weight: var(--wa-font-weight-action);
-  }
+wa-card .page-name {
+  font-size: var(--wa-font-size-s);
+  font-weight: var(--wa-font-weight-action);
 }
 
 .index-category {
@@ -420,6 +410,146 @@ wa-page > main:has(> .index-grid) {
   margin-block-start: var(--wa-space-2xl);
 }
 
+/* Interactive cards */
+wa-card[role='button'][tabindex='0'],
+button,
+a[href],
+wa-option,
+wa-radio,
+wa-checkbox {
+  /* Disabled state */
+  &:is(:disabled, [disabled], [aria-disabled='true']) {
+    &:is(wa-card, :has(> wa-card)) {
+      opacity: 60%;
+      cursor: not-allowed;
+    }
+  }
+
+  &:where(:not(:disabled, [disabled], [aria-disabled='true'])) {
+    &:has(> wa-card) {
+      /* Parents only (not interactive <wa-card>) */
+      margin: calc(var(--wa-border-width-m) + 1px);
+      padding: 0;
+
+      /* Hover state */
+      &:hover,
+      &:state(hover),
+      &:state(current) {
+        /* Do not change the parent background as a hover effect (we style the card instead) */
+        background: transparent !important;
+      }
+
+      &::part(control),
+      &:is(wa-option)::part(checked-icon) {
+        --background-color-checked: var(--wa-color-brand-fill-loud);
+        --checked-icon-scale: 0.5;
+        --offset: var(--wa-space-2xs);
+
+        position: absolute;
+        inset: calc(var(--offset) + var(--wa-border-width-m));
+        inset-block-end: auto;
+        inset-inline-start: auto;
+        z-index: 1;
+        margin: 0;
+        background: var(--wa-color-brand-fill-loud);
+        color: var(--wa-color-brand-on-loud);
+      }
+
+      &::part(checked-icon) {
+        color: var(--wa-color-brand-on-loud);
+      }
+
+      &:is(wa-option)::part(checked-icon) {
+        inset-block-start: calc(var(--wa-space-smaller) - 0.5em);
+        inset-inline-end: calc(var(--wa-space-smaller) - 0.5em);
+        width: 1em;
+        height: 1em;
+        line-height: 1em;
+        padding: 0.4em;
+        border-radius: var(--wa-border-radius-circle);
+        text-align: center;
+        font-size: var(--wa-font-size-xs);
+      }
+    }
+
+    /* Hover state */
+    &:hover,
+    &:state(hover),
+    &:state(current) {
+      &:is(wa-card),
+      > wa-card {
+        --border-color: var(--wa-color-brand-border-loud);
+        border-color: var(--border-color);
+        box-shadow: 0 0 0 var(--wa-border-width-s) var(--border-color);
+      }
+    }
+
+    &:is(wa-card, :has(> wa-card)) {
+      /* Interactive card parent */
+      position: relative;
+      cursor: pointer;
+
+      /* Unselected state */
+      &:where(:not(:state(checked), :state(selected), [aria-checked='true'], [aria-selected='true'])) {
+        &::part(checked-icon),
+        &::part(control) {
+          display: none;
+        }
+      }
+    }
+
+    &:is(wa-card),
+    > wa-card {
+      /* The card itself */
+      box-shadow: none;
+    }
+  }
+}
+
+/* Selected cards */
+:state(selected),
+:state(checked),
+[aria-checked='true'],
+[aria-selected='true'] {
+  &:is(wa-card, :has(> wa-card)) {
+    background: transparent;
+  }
+
+  &:is(wa-card),
+  > wa-card {
+    --border-color: var(--wa-color-brand-border-loud);
+    box-shadow: 0 0 0 var(--wa-border-width-m) var(--border-color);
+
+    &::part(body) {
+      background: var(--wa-color-brand-fill-quiet);
+    }
+  }
+}
+
+wa-select:has(> wa-option > wa-card) {
+  &::part(listbox) {
+    --column-width: 1fr;
+    --columns: 1;
+    --gap: var(--wa-space-smaller);
+
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(var(--column-width), 1fr));
+    width: calc(var(--columns) * var(--column-width) + (var(--columns) - 1) * var(--gap) + 2 * var(--wa-space));
+    max-width: var(--auto-size-available-width, 90vw);
+    gap: var(--gap);
+    padding: var(--wa-space-smaller) var(--wa-space);
+  }
+
+  > wa-option > wa-card {
+    --spacing: var(--wa-space-s);
+  }
+}
+
+wa-radio:has(> wa-card) {
+  grid-template-columns: 1fr;
+  width: auto;
+}
+
 /* Swatches */
 .swatch {
   position: relative;
@@ -596,13 +726,6 @@ table.colors {
   margin-block-end: var(--wa-flow-spacing);
 }
 
-/** mobile */
-@media screen and (max-width: 768px) {
-  wa-page .only-desktop {
-    display: none;
-  }
-}
-
 /** desktop */
 @media screen and not (max-width: 768px) {
   /* Navigation sidebar */

docs/assets/styles/search.css

@@ -7,8 +7,9 @@
   margin: 0 auto;
   overflow: hidden;
 
-  &::part(base) {
-    margin-block: 10rem;
+  &::part(dialog) {
+    margin-block-start: 10vh;
+    margin-block-end: 0;
   }
 
   &::part(body) {
@@ -23,26 +24,26 @@
   @media screen and (max-width: 900px) {
     max-width: calc(100% - 2rem);
 
-    &::part(base) {
+    &::part(dialog) {
       margin-block: 1rem;
     }
+
+    #site-search-container {
+      max-height: none;
+    }
   }
 }
 
 #site-search-container {
   display: flex;
   flex-direction: column;
-  max-height: calc(100vh - 20rem);
-
-  @media screen and (max-width: 900px) {
-    max-height: calc(100dvh - 2rem);
-  }
+  max-height: calc(100vh - 18rem);
 }
 
 /* Header */
-header {
+#site-search-container header {
   flex: 0 0 auto;
-  align-items: middle;
+  align-items: center;
   /* Fixes an iOS Safari 16.4 bug that draws the parent element's border radius incorrectly when showing/hiding results */
   border-radius: var(--wa-border-radius-l);
 }

docs/assets/styles/theme-icons.css

@@ -1,9 +1,86 @@
-.theme-color-icon {
+wa-card:has(
+    > .theme-icon-host,
+    > [slot='header'] > .theme-icon-host,
+    > .fonts-icon-host,
+    > [slot='header'] > .fonts-icon-host
+  ) {
+  &::part(header) {
+    /* We want to add a background color, so any spacing needs to go on .theme-icon */
+    flex: 1;
+    padding: 0;
+    min-block-size: 0;
+  }
+
+  [slot='header'] {
+    width: 100%;
+  }
+}
+
+.theme-icon-host,
+.fonts-icon-host,
+.palette-icon-host {
+  flex: 1;
+  border-radius: inherit;
+
+  &[slot='header'],
+  [slot='header']:has(&) {
+    flex: 1;
+    border-radius: inherit;
+  }
+}
+
+.theme-icon:not(.theme-color-icon),
+.palette-icon,
+.icons-icon {
+  min-height: 5.5rem;
+}
+
+.palette-icon {
   display: grid;
+  grid-template-columns: repeat(var(--hues, 9), 1fr);
+  gap: var(--wa-space-3xs);
+  min-width: 20ch;
+  align-content: center;
+
+  .swatch {
+    height: 0.7em;
+    background: var(--color);
+    border-radius: var(--wa-border-radius-s);
+
+    &[data-suffix=''] {
+      height: 1.1em;
+    }
+  }
+}
+
+.theme-icon,
+.fonts-icon {
+  min-width: 18ch;
+  padding: var(--wa-space-xs) var(--wa-space-m);
+  border-radius: inherit;
+  box-sizing: border-box;
+
+  h2,
+  h3,
+  p {
+    margin-block: 0;
+    padding: 0;
+  }
+}
+
+.theme-color-icon {
+  display: flex;
   gap: var(--wa-space-xs);
-  grid-template-columns: repeat(4, auto);
+  min-width: 15ch;
+  background: var(--wa-color-surface-lowered);
+
+  & + & {
+    border-start-start-radius: 0;
+    border-start-end-radius: 0;
+  }
 
   div {
+    flex: 1;
     display: flex;
     align-items: center;
     justify-content: center;
@@ -14,21 +91,99 @@
     padding: var(--wa-space-2xs) var(--wa-space-xs);
     color: var(--text-color);
     font-weight: var(--wa-font-weight-semibold);
+  }
+}
 
-    &.plain {
-      font-weight: var(--wa-font-weight-bold);
+.theme-icon.theme-overall-icon,
+.fonts-icon {
+  display: flex;
+  flex-flow: column;
+  gap: var(--wa-space-2xs);
+  justify-content: center;
+  width: 100%;
+  min-height: 6.75rem;
+  box-sizing: border-box;
+  background: var(--wa-color-surface-lowered);
+
+  .row {
+    display: flex;
+    gap: var(--wa-space-xs);
+    align-items: center;
+    justify-content: space-between;
+  }
+
+  .row-2 {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    contain: inline-size;
+    width: 100%;
+
+    wa-input {
+      min-width: 1em;
+    }
+  }
+
+  .swatches {
+    display: flex;
+    gap: var(--wa-space-3xs);
+
+    > div {
+      width: 1.25rem;
+      height: 1.25rem;
+      border-radius: var(--wa-border-radius-s);
+      background: var(--wa-color-fill-loud);
+      color: var(--wa-color-on-loud);
+
+      &.wa-brand {
+        width: 2.5rem;
+      }
     }
   }
 }
 
-.theme-typography-icon {
-  display: flex;
-  flex-direction: column;
-  gap: var(--wa-space-xs);
+.fonts-icon {
+  font-family: var(--wa-font-family-body);
+  padding-block: var(--wa-space-s);
+  overflow: hidden;
+  position: relative;
 
-  h3,
-  p {
-    margin-block: 0;
-    padding: 0;
+  & h2,
+  & p {
+    white-space: nowrap;
+  }
+
+  &::after {
+    content: '';
+    position: absolute;
+    right: 0;
+    width: 50%;
+    height: 100%;
+    background-image: linear-gradient(to left, var(--wa-color-surface-lowered), 20%, transparent);
   }
 }
+
+.icons-icon {
+  display: grid;
+  grid-template-columns: repeat(var(--columns, 5), auto);
+  gap: var(--wa-space-xs);
+  place-items: center;
+  place-content: center;
+
+  & wa-icon {
+    font-size: 1.25em;
+  }
+}
+
+.page-card {
+  wa-badge {
+    margin-inline: var(--wa-space-3xs);
+  }
+}
+
+:is(.theme-card, .icons-card)::part(header) {
+  background: var(--wa-color-surface-lowered);
+}
+
+.icons-card::part(header) {
+  color: var(--wa-color-neutral-on-quiet);
+}

docs/assets/styles/ui.css

@@ -0,0 +1,145 @@
+/* App UI, for themer, palette tweaking etc */
+
+:root {
+  --fa-sliders-simple: '\f1de';
+}
+
+.title {
+  wa-icon-button {
+    font-size: var(--wa-font-size-l);
+    color: var(--wa-color-text-quiet);
+
+    &:not(:hover, :focus) {
+      opacity: 0.5;
+    }
+  }
+}
+
+.popup {
+  background: var(--wa-color-surface-default);
+  border: 1px solid var(--wa-color-surface-border);
+  padding: var(--wa-space-xl);
+  border-radius: var(--wa-border-radius-m);
+  max-height: 90dvh;
+  overflow: auto;
+
+  code {
+    white-space: nowrap;
+  }
+}
+
+.color-select {
+  &.default::part(display-input) {
+    opacity: 0.6;
+    font-style: italic;
+  }
+
+  > small {
+    margin-inline-start: var(--wa-space-xs);
+    padding-block: 0 var(--wa-space-xs);
+  }
+
+  &::part(combobox)::before,
+  wa-option::before {
+    content: '';
+    display: inline-block;
+    width: 1.2em;
+    aspect-ratio: 1;
+    margin-inline-end: var(--wa-space-xs);
+    flex: none;
+    border-radius: var(--wa-border-radius-m);
+    background: var(--color);
+    border: 1px solid var(--wa-color-surface-default);
+  }
+
+  wa-option {
+    white-space: nowrap;
+
+    &::before {
+      width: 1em;
+      margin-inline: var(--wa-space-xs);
+    }
+
+    &::part(checked-icon) {
+      order: 2;
+    }
+  }
+
+  .default-badge {
+    opacity: 0.6;
+    margin-inline-start: var(--wa-space-xs);
+  }
+}
+
+.swatch-select {
+  padding: 2px;
+
+  wa-radio-button {
+    --swatch-border-color: color-mix(in oklab, canvastext, transparent 80%);
+
+    &::part(base) {
+      /* a <button> */
+      width: 2em;
+      height: 2em;
+      padding: 0;
+      border-radius: var(--border-radius, var(--wa-border-radius-m));
+      background: var(--color);
+      background-clip: border-box;
+      border-color: var(--swatch-border-color);
+    }
+  }
+
+  &.swatch-shape-circle {
+    --border-radius: var(--wa-border-radius-circle);
+  }
+
+  wa-radio-button:is([checked], :state(checked)) {
+    --swatch-border-color: var(--wa-color-surface-default);
+    &::part(base) {
+      box-shadow:
+        inset 0 0 0 var(--indicator-width) var(--wa-color-surface-default),
+        0 0 0 calc(var(--indicator-width) + 1px) var(--indicator-color);
+    }
+  }
+
+  &::part(form-control-input) {
+    flex-wrap: wrap;
+    gap: var(--wa-space-xs);
+  }
+}
+
+/* Repeated to increase specificity */
+.editable-text.editable-text {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--wa-space-xs);
+  --edit-hint-color: oklab(from var(--wa-color-warning-fill-quiet) l a b / 50%);
+
+  > .text {
+    &:hover,
+    &:focus {
+      background-color: var(--edit-hint-color);
+      box-shadow: 0 0 0 var(--wa-space-2xs) var(--edit-hint-color);
+      color: inherit;
+      border-radius: calc(var(--wa-border-radius-m) - var(--wa-space-2xs));
+    }
+  }
+
+  > input {
+    font: inherit;
+    margin-block: calc(-1 * var(--wa-space-smaller));
+    field-sizing: content;
+  }
+
+  wa-icon-button {
+    font-size: 90%;
+  }
+}
+
+.info-tip-default-trigger {
+  color: var(--wa-color-text-quiet);
+
+  &:not(:hover, :focus) {
+    opacity: 65%;
+  }
+}

docs/assets/vue/components/color-select.js

@@ -0,0 +1,78 @@
+import { capitalize } from '../../scripts/util/string.js';
+
+const template = `
+    <wa-select class="color-select" name="brand" :label="label" :value="modelValue"  @input="$emit('update:modelValue', $event.target.value)"
+    :style="{'--color': getColor(modelValue)}">
+      <template v-for="values, group in computedGroups">
+        <template v-if="group">
+          <wa-divider v-if="group !== firstGroup"></wa-divider>
+          <small>{{ group }}</small>
+        </template>
+        <wa-option v-if="values?.length" v-for="value of values" :label="getLabel(value)" :value="value" :style="{'--color': getColor(value)}" v-html="getContent?.(value) ?? getLabel(value)"></wa-option>
+      </template>
+      <slot></slot>
+    </wa-select>
+  `;
+
+export default {
+  props: {
+    modelValue: String,
+    label: String,
+    getLabel: {
+      type: Function,
+      default: capitalize,
+    },
+    getContent: {
+      type: Function,
+    },
+    getColor: {
+      type: Function,
+      default: value => `var(--wa-color-${value})`,
+    },
+    values: {
+      type: Array,
+      default: [],
+    },
+    groups: {
+      type: Object,
+    },
+  },
+  emits: ['update:modelValue', 'input'],
+  data() {
+    return {};
+  },
+  computed: {
+    computedGroups() {
+      let ret = {};
+
+      if (this.values?.length) {
+        ret[''] = this.values;
+      }
+
+      if (this.groups) {
+        for (let group in this.groups) {
+          if (this.groups[group]?.length) {
+            ret[group] = this.groups[group];
+          }
+        }
+      }
+
+      return ret;
+    },
+
+    firstGroup() {
+      return Object.keys(this.computedGroups)[0];
+    },
+  },
+
+  methods: {
+    capitalize,
+    handleInput(e) {
+      this.$emit('input', this.modelValue);
+    },
+  },
+  template,
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/editable-text.js

@@ -0,0 +1,82 @@
+const template = `
+<span class="editable-text">
+<template v-if="isEditing">
+  <input ref="input" class="wa-size-s" :aria-label="label" :value="value" @input="handleInput" @keydown.enter="done" @keydown.esc="cancel" />
+  <wa-icon-button name="check" label="Done editing" @click="done"></wa-icon-button>
+  <wa-icon-button name="xmark" label="Cancel" @click="cancel"></wa-icon-button>
+</template>
+<template v-else>
+  <span class="text" ref="wrapper" @focus="edit" @click="edit" tabindex="0">{{ value }}</span>
+  <wa-icon-button name="pencil" :label="'Edit ' + label" @click="edit"></wa-icon-button>
+</template>
+</span>
+`;
+
+export default {
+  props: {
+    modelValue: String,
+    label: {
+      type: String,
+      default: 'Rename',
+    },
+  },
+  emits: ['update:modelValue', 'submit'],
+  data() {
+    return {
+      value: this.modelValue,
+      previousValue: undefined,
+      isEditing: false,
+    };
+  },
+  computed: {},
+
+  methods: {
+    edit(event) {
+      if (this.isEditing) {
+        return;
+      }
+
+      event.stopPropagation();
+
+      this.isEditing = true;
+      this.previousValue = this.value;
+
+      this.$nextTick(() => {
+        this.$refs.input.focus();
+        this.$refs.input.select();
+      });
+    },
+    done(event) {
+      if (!this.isEditing) {
+        return;
+      }
+
+      event.stopPropagation();
+
+      this.isEditing = false;
+
+      if (!this.previousValue || this.previousValue !== this.value) {
+        this.$emit('submit', this.value);
+      }
+    },
+    cancel(event) {
+      if (!this.isEditing) {
+        return;
+      }
+
+      event.stopPropagation();
+
+      this.isEditing = false;
+      this.value = this.previousValue;
+    },
+    handleInput(event) {
+      this.value = event.target.value;
+    },
+  },
+  watch: {
+    value(newValue) {
+      this.$emit('update:modelValue', newValue);
+    },
+  },
+  template,
+};

docs/assets/vue/components/fonts-card.js

@@ -0,0 +1,132 @@
+import PageCard from './page-card.js';
+import { defaultTitle, pairings, sameAs } from '/assets/data/fonts.js';
+import { themeConfig } from '/assets/data/theming.js';
+import { cssImport, getThemeCode } from '/assets/scripts/tweak/code.js';
+import themes from '/docs/themes/data.js';
+
+const template = `
+  <page-card class="fonts-card" :info="computedPairing">
+    <template #icon>
+      <wa-scoped slot="header" class="fonts-icon-host" inert>
+        <template v-html="html"></template>
+        <template>
+          <link rel="stylesheet" href="/dist/styles/native/content.css">
+          <link rel="stylesheet" href="/assets/styles/theme-icons.css">
+
+          <div class="fonts-icon" role="presentation">
+            <h2>When my six o'clock alarm buzzes, I require a pot of good java.</h2>
+            <p>By quarter past seven, I've jotted hazy musings in a flax-bound notebook, sipping lukewarm espresso.</p>
+          </div>
+        </template>
+      </wa-scoped>
+    </template>
+    <slot></slot>
+    <template #extra>
+      <slot name="extra" />
+    </template>
+  </page-card>
+`;
+
+export default {
+  props: {
+    theme: String,
+    src: String,
+    fonts: Object,
+    pairing: Object,
+  },
+
+  data() {
+    return {};
+  },
+
+  computed: {
+    content() {
+      let pairingTitle = this.computedPairing.title;
+      // let themeTitle = this.themeId ? `As seen in ${this.themeMeta.title}` : '';
+
+      if (this.title) {
+        return { title: this.title, subtitle: this.subtitle ?? pairingTitle };
+      } else {
+        return { title: pairingTitle, subtitle: this.subtitle };
+      }
+    },
+
+    url() {
+      let ret = this.src ?? this.pairing?.url;
+
+      if (!ret && this.theme) {
+        return themeConfig.typography.url(this.theme);
+      }
+
+      return ret;
+    },
+
+    themeId() {
+      return this.theme ?? this.pairing?.id;
+    },
+
+    themeMeta() {
+      return themes[this.themeId] ?? {};
+    },
+
+    computedFonts() {
+      let ret = this.fonts ?? this.pairing?.fonts ?? this.themeMeta?.fonts;
+      let defaults = themes.default.fonts;
+      return Object.assign({}, defaults, { ...ret });
+    },
+
+    computedPairing() {
+      let ret;
+
+      if (this.pairing) {
+        ret = { ...this.pairing };
+      } else {
+        // Get from theme
+        let fonts = this.computedFonts;
+        let { body, heading = sameAs.body } = fonts;
+        let pairing = pairings[body]?.[heading];
+        ret = Object.assign({ fonts }, pairing);
+      }
+
+      ret.url = this.url;
+      ret.title ??= defaultTitle(fonts);
+      return ret;
+    },
+
+    computed() {
+      let ret = { fonts: this.computedFonts };
+
+      for (let key in ret.fonts) {
+        if (ret.fonts[key] === sameAs.body) {
+          ret.fonts[key] = ret.fonts.body;
+        }
+      }
+
+      ret.pairing = this.computedPairing;
+      ret.theme = this.themeId;
+      ret.url = this.url;
+
+      return ret;
+    },
+
+    html() {
+      let { id, url } = this.computedPairing;
+
+      if (id) {
+        let theme = { typography: id };
+
+        return getThemeCode(theme, { id, language: 'html' });
+      } else {
+        return cssImport(url, { language: 'html' });
+      }
+    },
+  },
+
+  template,
+  components: {
+    PageCard,
+  },
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/icons-card.js

@@ -0,0 +1,175 @@
+import { sample } from '../../scripts/util/array.js';
+import { capitalize } from '../../scripts/util/string.js';
+import PageCard from './page-card.js';
+import { iconLibraries } from '/assets/data/icons.js';
+
+const iconNames = [
+  'user',
+  'paper-plane',
+  'face-laugh',
+  'pen-to-square',
+  'trash',
+  'cart-shopping',
+  'link',
+  'sun',
+  'bookmark',
+  'sparkles',
+  'thumbs-up',
+  'gear',
+];
+const brands = new Set(['web-awesome', 'font-awesome']);
+const ICON_GRID = { columns: 6, rows: 2 };
+const TOTAL_ICONS = ICON_GRID.columns * ICON_GRID.rows;
+
+const template = `
+	<page-card class="icons-card" :class="'icons-' + type + '-card'" :pro="$slots.default ? false : iconsMeta.isPro" :info="iconsMeta">
+    <template #icon>
+      <div slot="header" class="icons-icon" :class="'icons-' + type + '-icon'" :style="{ '--columns': ICON_GRID.columns }">
+        <template v-for="icon of icons">
+          <wa-icon v-bind="icon"></wa-icon>
+        </template>
+      </div>
+    </template>
+    <slot></slot>
+	</page-card>
+`;
+
+const defaultDefaults = {
+  library: 'default',
+  family: 'classic',
+  style: 'solid',
+};
+
+export default {
+  props: {
+    library: String,
+    family: String,
+    style: String,
+    defaults: Object,
+    type: {
+      type: String,
+      validate(value) {
+        return ['library', 'family', 'style'].includes(value);
+      },
+    },
+    vary: {
+      type: [Array, String],
+      validate(value) {
+        if (Array.isArray(value)) {
+          return value.every(v => ['family', 'style'].includes(v));
+        }
+
+        return ['family', 'style'].includes(value);
+      },
+      default() {
+        return [];
+      },
+    },
+  },
+
+  data() {
+    return {};
+  },
+
+  created() {
+    Object.assign(this, { iconNames, brands, ICON_GRID });
+  },
+
+  computed: {
+    computedLibrary() {
+      return this.library ?? 'default';
+    },
+
+    libraryMeta() {
+      return iconLibraries[this.computedLibrary] ?? {};
+    },
+
+    defaultTitle() {
+      let titles = {};
+      for (let key in this.computed) {
+        let value = this.computed[key];
+
+        if (key === 'library') {
+          titles[key] = iconLibraries[value].title;
+        }
+
+        titles[key] ??= capitalize(value);
+      }
+
+      if (this.type) {
+        return titles[this.type];
+      } else {
+        return titles.library + ' ' + titles.family + ' • ' + titles.style;
+      }
+    },
+
+    icons() {
+      let { family, style } = this.computed;
+      let library = this.libraryMeta;
+      let vary = Array.isArray(this.vary) ? this.vary : [this.vary];
+
+      let ret = [];
+
+      if (vary.length > 0) {
+        for (let param of vary) {
+          let allValues = library[param];
+          let random = (allValues.random ??= []);
+
+          while (random.length < TOTAL_ICONS) {
+            random.push(sample(allValues));
+          }
+        }
+      }
+
+      while (ret.length < TOTAL_ICONS) {
+        ret.push(
+          ...iconNames.map((name, i) => {
+            let index = ret.length + i;
+
+            return {
+              library: this.computedLibrary,
+              name,
+              family: !this.family && vary.includes('family') ? library.family.random[index] : family,
+              variant: !this.style && vary.includes('style') ? library.style.random[index] : style,
+            };
+          }),
+        );
+      }
+
+      return ret.slice(0, TOTAL_ICONS);
+    },
+
+    computedDefaults() {
+      return Object.assign({}, defaultDefaults, this.defaults);
+    },
+
+    computed() {
+      let { library, family, style } = this;
+      let ret = { library, family, style };
+
+      for (let key in this.computedDefaults) {
+        if (!ret[key]) {
+          ret[key] = this.computedDefaults[key];
+        }
+      }
+
+      return ret;
+    },
+
+    iconsMeta() {
+      return { title: this.defaultTitle };
+    },
+  },
+
+  methods: {
+    capitalize,
+  },
+
+  template,
+  components: {
+    PageCard,
+  },
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/index.js

@@ -0,0 +1,12 @@
+export { default as ColorSelect } from './color-select.js';
+export { default as EditableText } from './editable-text.js';
+export { default as FontsCard } from './fonts-card.js';
+export { default as IconsCard } from './icons-card.js';
+export { default as InfoTip } from './info-tip.js';
+export { default as PageCard } from './page-card.js';
+export { default as PaletteCard } from './palette-card.js';
+export { default as SwatchSelect } from './swatch-select.js';
+export { default as ThemeCard } from './theme-card.js';
+export { default as UiPanelContainer } from './ui-panel-container.js';
+export { default as UiPanel } from './ui-panel.js';
+export { default as UiScrollable } from './ui-scrollable.js';

docs/assets/vue/components/info-tip.js

@@ -0,0 +1,38 @@
+const template = `
+	<slot>
+  		<wa-icon :slot class="info-tip-default-trigger" :id="id" name="circle-question" variant="regular" tabindex="0"></wa-icon>
+	</slot>
+	<wa-tooltip :slot :for="id" ref="tooltip"><slot name="content"></slot></wa-tooltip>
+  `;
+
+let maxUid = 0;
+
+export default {
+  props: {
+    slot: String,
+  },
+  data() {
+    let uid = ++maxUid;
+    return { uid, id: 'info-tip-' + uid };
+  },
+  mounted() {
+    let tooltip = this.$refs.tooltip;
+    if (tooltip) {
+      // Find trigger
+      let trigger = tooltip.previousElementSibling;
+      if (trigger) {
+        if (trigger.id) {
+          // Already has id
+          this.id = trigger.id;
+        } else {
+          trigger.id = this.id;
+        }
+      }
+    }
+  },
+  computed: {},
+  template,
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/page-card.js

@@ -0,0 +1,83 @@
+/**
+ * Generic component for displaying a (possibly interactive) card that represents a page
+ * For more specific use cases check out theme-card, icons-card, etc.
+ */
+export const ICON_PLACEHOLDER = `
+<svg width="50" height="50" viewBox="0 0 50 50" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M1 7C1 3.68629 3.68629 1 7 1H43C46.3137 1 49 3.68629 49 7V43C49 46.3137 46.3137 49 43 49H7C3.68629 49 1 46.3137 1 43V7Z" stroke="var(--wa-color-surface-border)" stroke-width="2" stroke-linecap="round" stroke-dasharray="6 6"/>
+<path d="M14.1566 18.7199L21.5367 16.7424C22.6036 16.4565 23.7003 17.0896 23.9862 18.1566L26.8463 28.8306C27.1322 29.8975 26.499 30.9942 25.4321 31.2801L18.052 33.2576C16.985 33.5435 15.8884 32.9103 15.6025 31.8434L12.7424 21.1694C12.4565 20.1024 13.0897 19.0057 14.1566 18.7199Z" stroke="var(--wa-color-neutral-border-normal)" stroke-width="2"/>
+<path d="M33.8449 16.3273H26.2045C23.9953 16.3273 22.2045 18.1181 22.2045 20.3273V31.3778C22.2045 33.587 23.9953 35.3778 26.2045 35.3778H33.8449C36.0541 35.3778 37.8449 33.587 37.8449 31.3778V20.3273C37.8449 18.1181 36.0541 16.3273 33.8449 16.3273Z" fill="var(--wa-color-neutral-border-normal)" stroke="var(--wa-color-neutral-fill-quiet)" stroke-width="2"/>
+</svg>`;
+
+const template = `
+<wa-card with-header class="page-card" :aria-disabled="disabled ? 'true' : null" :inert="disabled"
+         @click="handleClick" @keyup.enter="handleClick"  @keyup.space="handleClick"
+         :role="action ? 'button' : null" :tabindex="action? 0 : null">
+  <slot name="icon" slot="header">
+    <div slot="header" v-html="icon || ICON_PLACEHOLDER"></div>
+  </slot>
+
+  <div class="page-name">
+    <div>
+      <slot>
+        {{ content.title }}
+        <wa-badge class="pro" v-if="pro">PRO</wa-badge>
+        <div v-if="content.subtitle" class="wa-caption-m">{{ content.subtitle }}</div>
+      </slot>
+    </div>
+    <slot name="extra"></slot>
+    <wa-icon v-if="action" name="angle-right" class="angle-right" variant="regular"></wa-icon>
+  </div>
+</wa-card>
+`;
+
+export default {
+  props: {
+    title: String,
+    subtitle: String,
+    info: Object,
+    icon: String,
+    pro: Boolean,
+    disabled: Boolean,
+    action: Function,
+  },
+
+  data() {
+    return {};
+  },
+
+  created() {
+    Object.assign(this, { ICON_PLACEHOLDER });
+  },
+
+  computed: {
+    content() {
+      let defaultTitle = this.info?.title ?? {};
+
+      if (this.title) {
+        return { title: this.title, subtitle: this.subtitle ?? defaultTitle };
+      } else {
+        return { title: defaultTitle, subtitle: this.subtitle };
+      }
+    },
+  },
+
+  methods: {
+    handleClick(event) {
+      if (this.disabled) {
+        event.stopImmediatePropagation();
+        return;
+      }
+
+      if (this.action) {
+        this.action(event);
+      }
+    },
+  },
+
+  template,
+  components: {},
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/palette-card.js

@@ -0,0 +1,63 @@
+import PageCard from './page-card.js';
+import { hues } from '/assets/data/index.js';
+import palettes from '/docs/palettes/data.js';
+
+// TODO import from data.js once available
+const allHues = [...hues, 'gray'];
+
+const template = `
+	<page-card class="palette-card" :pro="$slots.default ? false : paletteMeta.isPro" :info="paletteMeta">
+    <template #icon>
+      <wa-scoped slot="header" class="palette-icon-host">
+        <template>
+          <link rel="stylesheet" :href="'/dist/styles/color/' + palette + '.css'">
+          <link rel="stylesheet" href="/assets/styles/theme-icons.css">
+
+          <div class="palette-icon" style="--hues: {{ hues|length }}; --suffixes: {{ suffixes|length }}">
+            <template v-for="(hue, hueIndex) of hues">
+              <div class="swatch" v-for="(suffix, suffixIndex) of suffixes"
+                  :data-hue="hue" :data-suffix="suffix"
+                  :style="{
+                    '--color': 'var(--wa-color-' + hue + suffix + ')',
+                    gridColumn: hueIndex + 1,
+                    gridRow: suffixIndex + 1
+                  }">&nbsp;</div>
+            </template>
+          </div>
+        </template>
+      </wa-scoped>
+    </template>
+    <slot></slot>
+    <template #extra>
+      <slot name="extra" />
+    </template>
+	</page-card>
+`;
+
+export default {
+  props: {
+    palette: String,
+  },
+
+  data() {
+    return {};
+  },
+
+  created() {
+    Object.assign(this, { hues: allHues, suffixes: ['-80', '', '-20'] });
+  },
+
+  computed: {
+    paletteMeta() {
+      return palettes[this.palette] ?? {};
+    },
+  },
+
+  template,
+  components: {
+    PageCard,
+  },
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/panel.css

@@ -0,0 +1,173 @@
+.sidebar.panel-container {
+  position: relative;
+  display: flex;
+  flex-flow: column;
+  gap: 0;
+  padding: 0;
+  width: 32ch;
+  overflow: hidden;
+  scrollbar-width: thin;
+}
+
+@keyframes back-icon-hover {
+  to {
+    transform: translateX(-0.2em);
+  }
+}
+
+.panel {
+  /* Remove the uniform spacing used in wa-details */
+  --spacing: 0;
+  /* Specify value to manually set spacing where needed */
+  --panel-spacing: var(--wa-space-2xl);
+  --panel-background: var(--wa-color-surface-default);
+
+  display: flex;
+  flex-flow: column;
+  max-height: 100%;
+  margin-bottom: 0;
+  position: relative;
+  background: var(--panel-background);
+  border: none;
+  transition:
+    translate var(--wa-transition-slow) allow-discrete,
+    opacity var(--wa-transition-slow) 25ms allow-discrete;
+  /* Ensure horizontal scrollbar isn't visible when translate takes effect */
+  overflow-x: hidden !important;
+
+  @starting-style {
+    display: block;
+  }
+
+  .panel-header {
+    flex-direction: row-reverse;
+    justify-content: start;
+    gap: var(--wa-space-xs);
+    cursor: pointer;
+    background: var(--panel-background);
+    color: var(--wa-color-text-normal);
+    padding-block-end: var(--panel-spacing);
+    padding-inline: var(--panel-spacing);
+    transition: inherit;
+    transition-property: all;
+    margin-block: 0;
+    font-size: inherit;
+
+    [data-step='0'] &,
+    .previous & {
+      padding-block-start: var(--panel-spacing);
+    }
+
+    .back-icon {
+      vertical-align: -0.15em;
+      margin-inline-end: var(--wa-space-xs);
+      font-size: var(--wa-font-size-m);
+      transition: transform var(--wa-transition-normal);
+    }
+
+    &:hover .back-icon {
+      animation: back-icon-hover var(--wa-transition-slow) alternate infinite;
+    }
+
+    label {
+      pointer-events: none;
+      font: inherit;
+      color: inherit;
+    }
+  }
+
+  .panel-content {
+    flex: 1;
+    min-height: 0;
+    display: flex;
+    flex-flow: column;
+    gap: var(--panel-spacing);
+    padding-block-end: var(--panel-spacing);
+    padding-inline: var(--panel-spacing);
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    margin-block-end: 0;
+  }
+
+  &:not(.open) {
+    padding: 0;
+
+    &:not(.previous, .next) {
+      /* Hide all but the immediately preceding or following steps */
+      display: none;
+    }
+
+    &.next {
+      height: 0;
+      overflow: hidden;
+    }
+
+    &.next {
+      opacity: 0;
+    }
+
+    &.next {
+      translate: 100% 0%;
+    }
+
+    .panel-header {
+      font-size: var(--wa-font-size-s);
+      margin: 0;
+    }
+
+    .panel-content {
+      opacity: 0;
+      pointer-events: none;
+      content-visibility: hidden;
+      padding: 0;
+    }
+  }
+
+  &.open {
+    flex: 1;
+    opacity: 1;
+
+    .panel-header {
+      font-size: var(--wa-font-size-l);
+
+      .back-icon {
+        display: none;
+      }
+    }
+  }
+
+  .panel-content {
+    flex: 1;
+    min-height: 0;
+    display: flex;
+    flex-flow: column;
+    transition: inherit;
+
+    @starting-style {
+      display: flex;
+      content-visibility: visible;
+    }
+  }
+
+  &:not(.open) {
+    &.previous {
+      .panel-content {
+        opacity: 0;
+        translate: -100% 0%;
+      }
+    }
+
+    &.next {
+      .panel-content {
+        opacity: 0;
+        translate: inherit;
+      }
+    }
+  }
+}

docs/assets/vue/components/scrollable.css

@@ -0,0 +1,89 @@
+/**
+ * Scrollable element in a vertical flex container
+ * Showing shadows as an indicator of scrollability (PE wherever scroll-timeline is supported for now, can be polyfilled with JS later)
+ */
+
+.scrollable {
+  --scroll-shadow-height: 0.5em;
+
+  flex-shrink: 1;
+  min-height: 0;
+  overflow: auto;
+  position: relative;
+  scrollbar-width: inherit;
+
+  &:is(.panel-content > div) {
+    display: flex;
+    flex-flow: column;
+    gap: inherit;
+  }
+
+  .scroll-shadow {
+    position: sticky;
+    z-index: 1;
+    inset-inline: 0;
+    display: block;
+
+    &::before {
+      content: '';
+      position: absolute;
+      inset-inline: 0;
+      height: var(--scroll-shadow-height);
+      pointer-events: none;
+      mix-blend-mode: multiply;
+      background: radial-gradient(farthest-side, var(--wa-color-shadow) 10%, transparent) center / 120% 200%;
+      transition: var(--wa-transition-slow);
+      /* transition-property: opacity, transform, display, height, min-height; */
+      transition-behavior: allow-discrete;
+    }
+  }
+
+  &:not(.can-scroll-top) .scroll-shadow-top,
+  &:not(.can-scroll-bottom) .scroll-shadow-bottom {
+    opacity: 0;
+
+    &::before {
+      height: 0;
+    }
+  }
+
+  &:not(.can-scroll-top) .scroll-shadow-top {
+    &::before {
+      transform: translateY(-100%);
+    }
+  }
+
+  .scroll-shadow-top {
+    top: 0;
+
+    &::before {
+      background-position: bottom;
+    }
+  }
+
+  &:not(.can-scroll-bottom) .scroll-shadow-bottom {
+    &::before {
+      transform: translateY(100%);
+    }
+  }
+
+  .scroll-shadow-bottom {
+    top: 100%;
+
+    &::before {
+      bottom: 0;
+      background-position: top;
+    }
+  }
+}
+
+.scrollable:where(.panel-content) {
+  .scroll-shadow-top {
+    /* TODO convert this magic number to a token that explains what it is */
+    margin-bottom: -18px;
+  }
+
+  .scroll-shadow-bottom {
+    transform: translateY(var(--padding-bottom, var(--panel-spacing)));
+  }
+}

docs/assets/vue/components/swatch-select.js

@@ -0,0 +1,67 @@
+import { capitalize } from '../../scripts/util/string.js';
+import InfoTip from './info-tip.js';
+
+const template = `
+<wa-radio-group :label class="swatch-select" :class="'swatch-shape-' + shape" orientation="horizontal" :value="modelValue" @input="handleInput">
+  <info-tip v-for="value in values">
+      <wa-radio-button :value :label="getLabel(value)" :style="{'--color': getColor(value)}"></wa-radio-button>
+      <template #content>
+        {{ getLabel(value) }}
+      </template>
+  </info-tip>
+</wa-radio-group>
+  `;
+
+export default {
+  props: {
+    modelValue: String,
+    name: String,
+    label: String,
+    shape: {
+      type: String,
+      default: 'rounded',
+      validator: value => ['circle', 'rounded'].includes(value),
+    },
+    getLabel: {
+      type: Function,
+      default: capitalize,
+    },
+    getColor: {
+      type: Function,
+      default: value => `var(--wa-color-${value})`,
+    },
+    values: {
+      type: Array,
+      default: [],
+    },
+  },
+  emits: ['update:modelValue', 'input'],
+  data() {
+    return {
+      value: this.modelValue,
+    };
+  },
+  computed: {},
+
+  methods: {
+    capitalize,
+    handleInput(e) {
+      this.value = e.target.value;
+      this.$emit('input', this.value);
+    },
+  },
+
+  watch: {
+    value() {
+      this.$emit('update:modelValue', this.value);
+    },
+  },
+
+  template,
+  components: {
+    InfoTip,
+  },
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/theme-card.js

@@ -0,0 +1,97 @@
+import PageCard from './page-card.js';
+import { getThemeCode } from '/assets/scripts/tweak/code.js';
+import themes from '/docs/themes/data.js';
+
+const iconTemplates = {
+  colors: `
+    <div class="theme-icon theme-color-icon" role="presentation">
+      <div style="background: var(--wa-color-brand-fill-loud);   border-color: var(--wa-color-brand-border-loud);   color: var(--wa-color-brand-on-loud);">A</div>
+      <div style="background: var(--wa-color-brand-fill-normal); border-color: var(--wa-color-brand-border-normal); color: var(--wa-color-brand-on-normal);">A</div>
+      <div style="background: var(--wa-color-brand-fill-quiet);  border-color: var(--wa-color-brand-border-quiet);  color: var(--wa-color-brand-on-quiet);">A</div>
+    </div>
+
+    <div class="wa-invert theme-icon theme-color-icon" role="presentation">
+      <div style="background: var(--wa-color-brand-fill-loud);   border-color: var(--wa-color-brand-border-loud);   color: var(--wa-color-brand-on-loud);">A</div>
+      <div style="background: var(--wa-color-brand-fill-normal); border-color: var(--wa-color-brand-border-normal); color: var(--wa-color-brand-on-normal);">A</div>
+      <div style="background: var(--wa-color-brand-fill-quiet);  border-color: var(--wa-color-brand-border-quiet);  color: var(--wa-color-brand-on-quiet);">A</div>
+    </div>`,
+  theme: `
+    <div class="row row-1">
+      <h2>Aa</h2>
+      <div class="swatches">
+        <div class="wa-brand"></div>
+        <div class="wa-success"></div>
+        <div class="wa-warning"></div>
+        <div class="wa-danger"></div>
+      </div>
+    </div>
+    <div class="row row-2">
+      <wa-input value="Input" size="small"></wa-input>
+      <wa-button size="small" variant="brand">Go</wa-button>
+    </div>`,
+};
+
+const template = `
+  <page-card class="theme-card" :class="type + '-card'" :info="themeMeta">
+    <template #icon>
+      <wa-scoped slot="header" class="theme-icon-host" inert>
+        <template v-html="themeCode"></template>
+        <template>
+          <link rel="stylesheet" href="/dist/styles/utilities.css">
+          <link rel="stylesheet" href="/dist/styles/native/content.css">
+          <link rel="stylesheet" href="/assets/styles/theme-icons.css">
+
+          <template v-if="type == 'colors'" >
+            ${iconTemplates.colors}
+          </template>
+
+          <div v-else class="theme-icon theme-overall-icon" :class="'wa-theme-' + theme" role="presentation">
+            ${iconTemplates.theme}
+          </div>
+        </template>
+      </wa-scoped>
+    </template>
+    <slot></slot>
+    <template #extra>
+      <slot name="extra" />
+    </template>
+  </page-card>
+`;
+
+export default {
+  props: {
+    theme: String,
+    type: {
+      type: String,
+      validator(value) {
+        return !value || ['colors'].includes(value);
+      },
+    },
+    rest: Object,
+  },
+
+  data() {
+    return {};
+  },
+
+  computed: {
+    themeMeta() {
+      return themes[this.theme] ?? {};
+    },
+
+    themeCode() {
+      let theme = { ...(this.rest || {}), [this.type || 'base']: this.theme };
+      theme.base ||= 'default';
+
+      return getThemeCode(theme, { id: this.theme, language: 'html', cdnUrl: '/dist/' });
+    },
+  },
+
+  template,
+  components: {
+    PageCard,
+  },
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/ui-panel-container.js

@@ -0,0 +1,120 @@
+const template = `
+<section class="panel-container" ref="container" :style="{'--panel-step': step}" @open="handleOpen">
+  <slot ref="panels"></slot>
+</section>
+`;
+
+export default {
+  props: {
+    /** Currently selected id */
+    modelValue: String,
+  },
+  emits: ['update:modelValue'],
+  data() {
+    return {
+      value: '',
+      previousValue: '',
+      step: 0,
+      trail: [],
+    };
+  },
+
+  mounted() {
+    let { container } = this.$refs;
+    let activePanel = container.querySelector(':scope > .open');
+
+    if (activePanel) {
+      let { step, value } = activePanel.dataset;
+      this.step = Number(step);
+      this.value = value;
+      this.$emit('update:modelValue', this.value);
+    }
+  },
+
+  computed: {
+    panels() {
+      if (!this.$refs.container) {
+        return new Map();
+      }
+
+      let { container } = this.$refs;
+
+      return new Map(
+        [...container.querySelectorAll(':scope > .panel')].map(panel => [
+          panel.dataset.value,
+          Number(panel.dataset.step),
+        ]),
+      );
+    },
+  },
+
+  methods: {
+    handleOpen(e) {
+      let { value, step } = e.detail;
+      this.value = value;
+      this.step = step;
+    },
+
+    updatePanels() {
+      let { container } = this.$refs;
+
+      if (!container) {
+        return;
+      }
+
+      let { step, value } = this;
+
+      if (this.panels.get(value) !== step) {
+        // Hasn't stabilized yet
+        return;
+      }
+
+      let previousValue = this.trail.findLast(panel => this.panels.get(panel) === step - 1);
+
+      for (let panel of container.querySelectorAll(':scope > .panel')) {
+        let panelStep = Number(panel.dataset.step);
+        let panelValue = panel.dataset.value;
+        let isPrevious = previousValue ? panelValue === previousValue : panelStep === step - 1;
+        let isOpen = panelValue === value;
+        let isNext = panelStep === step + 1;
+
+        panel.classList.toggle('previous', isPrevious);
+        panel.classList.toggle('open', isOpen);
+        panel.classList.toggle('next', isNext);
+      }
+    },
+  },
+
+  watch: {
+    value() {
+      if (this.value !== this.modelValue) {
+        this.$emit('update:modelValue', this.value);
+      }
+    },
+
+    modelValue: {
+      immediate: true,
+      async handler(value, previousValue) {
+        if (this.value !== this.modelValue) {
+          this.value = this.modelValue;
+        }
+
+        if (previousValue) {
+          this.trail.push(previousValue);
+        }
+
+        this.updatePanels();
+      },
+    },
+
+    step() {
+      this.updatePanels();
+    },
+  },
+
+  template,
+  components: {},
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/ui-panel.js

@@ -0,0 +1,73 @@
+import UiScrollable from './ui-scrollable.js';
+
+const template = `
+<ui-scrollable :disabled="!open" role="group" :name="name || 'panel'" :data-value="value" :data-step="step" class="panel" :class="{open}">
+  <h2 :inert="open" class="panel-header" @click="openPanel" ref="panelHeader">
+    <wa-icon name="chevron-left" class="back-icon" />
+    <slot name="title">{{ title }}</slot>
+  </h2>
+  <div class="panel-content">
+    <slot></slot>
+  </div>
+</ui-scrollable>
+`;
+
+export default {
+  props: {
+    title: String,
+    name: String,
+    step: Number,
+
+    /** Id of this panel */
+    value: String,
+
+    /** Currently selected id */
+    modelValue: String,
+  },
+  emits: ['update:modelValue', 'open'],
+  data() {
+    return {};
+  },
+
+  mounted() {
+    if (this.open) {
+      this.$refs.panelHeader.dispatchEvent(
+        new CustomEvent('open', { detail: { value: this.value, step: this.step }, bubbles: true }),
+      );
+    }
+  },
+
+  computed: {
+    open() {
+      return this.value === this.modelValue;
+    },
+  },
+
+  methods: {
+    openPanel() {
+      let wasOpen = this.open;
+      this.$emit('update:modelValue', wasOpen ? '' : this.value);
+    },
+  },
+
+  watch: {
+    open: {
+      immediate: true,
+      handler(open) {
+        if (open && this.$refs.panelHeader) {
+          this.$refs.panelHeader.dispatchEvent(
+            new CustomEvent('open', { detail: { value: this.value, step: this.step }, bubbles: true }),
+          );
+        }
+      },
+    },
+  },
+
+  template,
+  components: {
+    UiScrollable,
+  },
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/components/ui-scrollable.js

@@ -0,0 +1,77 @@
+const template = `
+<div class="scrollable" :class="{'can-scroll-top': canScrollTop, 'can-scroll-bottom': canScrollBottom}" ref="container">
+  <div v-if="!disabled" class="scroll-shadow scroll-shadow-top"></div>
+  <slot></slot>
+  <div v-if="!disabled" class="scroll-shadow scroll-shadow-bottom"></div>
+</div>
+`;
+
+export default {
+  props: {
+    disabled: Boolean,
+  },
+  data() {
+    return {
+      scrollTop: 0,
+      scrollHeight: 0,
+      height: 0,
+    };
+  },
+
+  mounted() {
+    let { container, content } = this.$refs;
+    container.addEventListener('scroll', this.handleScroll, { passive: true });
+
+    this.scrollHeight = container.scrollHeight;
+    this.height = container.clientHeight;
+  },
+
+  computed: {
+    canScrollTop() {
+      return !this.disabled && this.scrollTop > 1;
+    },
+
+    maxScrollTop() {
+      return this.scrollHeight - this.height;
+    },
+
+    canScrollBottom() {
+      return !this.disabled && this.scrollTop < this.maxScrollTop - 1;
+    },
+
+    scrollProgress() {
+      return this.scrollTop / this.maxScrollTop;
+    },
+
+    scrollProgressEnd() {
+      return this.scrollProgress + this.maxScrollTop / this.scrollHeight;
+    },
+
+    scrollBottom() {
+      return this.scrollHeight * this.scrollProgressEnd;
+    },
+  },
+
+  methods: {
+    handleScroll(event) {
+      let { container } = this.$refs;
+      this.scrollTop = container.scrollTop;
+    },
+  },
+
+  watch: {
+    scrollTop(value, oldValue) {
+      let { container } = this.$refs;
+      if (container && oldValue === 0) {
+        this.scrollHeight = container.scrollHeight;
+        this.height = container.clientHeight;
+      }
+    },
+  },
+
+  template,
+  components: {},
+  compilerOptions: {
+    isCustomElement: tag => tag.startsWith('wa-'),
+  },
+};

docs/assets/vue/directives/content.js

@@ -0,0 +1,22 @@
+// Like v-text, but doesn't complain if the element has content,
+// making it possible to use in a PE fashion, with the contents being the fallback
+export default function content(el, { value, arg }) {
+  if (!el.dataset.fallback) {
+    // Store the original content as a fallback the first time
+    el.dataset.fallback = el.textContent;
+  }
+
+  if (value === '') {
+    value = el.dataset.fallback;
+  } else {
+    if (arg === 'number') {
+      value = Number(value).toLocaleString(undefined, { maximumSignificantDigits: 2 });
+    }
+  }
+
+  if (arg === 'html') {
+    el.innerHTML = value;
+  } else {
+    el.textContent = value;
+  }
+}

docs/assets/vue/mixins/saved.js

@@ -0,0 +1,110 @@
+import my from '/assets/scripts/my.js';
+import Permalink from '/assets/scripts/permalink.js';
+
+export default {
+  data() {
+    return {
+      uid: undefined,
+      saved: null,
+      unsavedChanges: false,
+      permalink: new Permalink(),
+    };
+  },
+
+  created() {
+    if (this.permalink.has('uid')) {
+      this.uid = Number(this.permalink.get('uid'));
+      this.saved = this.controller.saved.find(p => p.uid === this.uid);
+    }
+
+    this.controller.addEventListener('delete', ({ detail: entity }) => {
+      if (entity.uid === this.saved?.uid) {
+        this.postDelete();
+      }
+    });
+  },
+
+  mounted() {
+    this.$nextTick().then(() => {
+      if (!location.search || this.saved) {
+        this.unsavedChanges = false;
+      }
+    });
+  },
+
+  computed: {
+    controller() {
+      return my[this.collection];
+    },
+
+    title() {
+      if (this.saved) {
+        return this.saved.title;
+      } else if (this.unsavedChanges) {
+        return this.defaultTitle;
+      } else {
+        return this.originalTitle;
+      }
+    },
+  },
+
+  watch: {
+    saved: {
+      deep: true,
+      handler() {
+        this.unsavedChanges = !this.saved;
+      },
+    },
+  },
+
+  methods: {
+    async save({ title } = {}) {
+      let uid = this.uid;
+
+      this.saved ??= { uid: this.uid };
+      this.saved.id = this.id;
+
+      if (title) {
+        // Renaming
+        this.saved.title = title;
+      } else {
+        this.saved.title ??= this.defaultTitle;
+      }
+
+      this.saved.search = location.search;
+
+      this.saved = this.controller.save(this.saved);
+
+      if (uid !== this.saved.uid) {
+        // UID changed (most likely from saving a new entity)
+        this.uid = this.saved.uid;
+        this.permalink.set('uid', this.uid);
+        this.permalink.updateLocation();
+        await this.$nextTick();
+        this.save(); // Save again to update the search param to include the UID
+      }
+
+      this.unsavedChanges = false;
+    },
+
+    rename() {
+      let newTitle = prompt('Title:', this.saved?.title ?? this.defaultTitle);
+
+      if (newTitle && newTitle !== this.saved?.title) {
+        this.save({ title: newTitle });
+      }
+    },
+
+    // Cannot name this delete() because Vue complains
+    deleteSaved() {
+      this.controller.delete(this.saved);
+    },
+
+    postDelete() {
+      this.saved = null;
+      this.permalink.delete('uid');
+      this.uid = undefined;
+      this.permalink.updateLocation();
+    },
+  },
+};

docs/docs/components/badge.md

@@ -65,6 +65,18 @@ Use the `appearance` attribute to change the badge's visual appearance.
 </div>
 ```
 
+### Size
+
+Badges are sized relative to the current font size. You can set `font-size` on any badge (or an ancestor element) to change it.
+
+```html {.example}
+<wa-badge variant="brand" style="font-size: var(--wa-font-size-xs);">Brand</wa-badge>
+<wa-badge variant="brand" style="font-size: var(--wa-font-size-s);">Brand</wa-badge>
+<wa-badge variant="brand" style="font-size: var(--wa-font-size-m);">Brand</wa-badge>
+<wa-badge variant="brand" style="font-size: var(--wa-font-size-l);">Brand</wa-badge>
+<wa-badge variant="brand" style="font-size: var(--wa-font-size-xl);">Brand</wa-badge>
+```
+
 ### Pill Badges
 
 Use the `pill` attribute to give badges rounded edges.

docs/docs/components/button-group.md

@@ -167,7 +167,7 @@ Other elements can also be placed inside button groups:
 <wa-button-group label="Example Button Group">
   <wa-button>Button</wa-button>
   <button>Native Button</button>
-  <wa-dropdown hoist>
+  <wa-dropdown>
     <wa-button slot="trigger" caret>Dropdown</wa-button>
     <wa-menu>
       <wa-menu-item>Item 1</wa-menu-item>
@@ -185,7 +185,7 @@ Create a split button using a button and a dropdown. Use a [visually hidden](/do
 ```html {.example}
 <wa-button-group label="Example Button Group">
   <wa-button variant="brand">Save</wa-button>
-  <wa-dropdown placement="bottom-end" hoist>
+  <wa-dropdown placement="bottom-end">
     <wa-button slot="trigger" variant="brand" caret>
       <span class="wa-visually-hidden">More options</span>
     </wa-button>

docs/docs/components/card.md

@@ -6,7 +6,7 @@ icon: card
 ---
 
 ```html {.example}
-<wa-card with-image with-footer class="card-overview">
+<wa-card 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"
@@ -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>
 ```
 
@@ -64,10 +54,10 @@ Headers can be used to display titles and more.
 If using SSR, you need to also use the `with-header` attribute to add a header to the card (if not, it is added automatically).
 
 ```html {.example}
-<wa-card with-header class="card-header">
-  <div slot="header">
+<wa-card class="card-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>
 ```
 
@@ -100,10 +80,10 @@ Footers can be used to display actions, summaries, or other relevant content.
 If using SSR, you need to also use the `with-footer` attribute to add a footer to the card (if not, it is added automatically).
 
 ```html {.example}
-<wa-card with-footer class="card-footer">
+<wa-card 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>
 ```
 
@@ -128,7 +102,7 @@ Card images are displayed atop the card and will stretch to fit.
 If using SSR, you need to also use the `with-image` attribute to add an image to the card (if not, it is added automatically).
 
 ```html {.example}
-<wa-card with-image class="card-image">
+<wa-card class="card-image">
   <img
     slot="image"
     src="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80"
@@ -150,35 +124,60 @@ Use the `size` attribute to change a card's size.
 
 ```html {.example}
 <div class="wa-stack">
-<wa-card with-footer size="small">
+<wa-card 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>
 </wa-card>
 
-<wa-card with-footer size="medium">
+<wa-card 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>
 </wa-card>
 
-<wa-card with-footer size="large">
+<wa-card 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/cheatsheet/index.njk

@@ -1,7 +1,7 @@
 ---
 title: Component Cheatsheet
 layout: docs
-unlisted: true
+unpublished: true
 ---
 
 <style>

docs/docs/components/code-demo.md

@@ -2,7 +2,8 @@
 title: Code Demo
 description: Code demos can be used to render code examples as inline live demos.
 tags: component
-noAlpha: true
+isPro: true
+unpublished: true
 ---
 
 ```html {.example}
@@ -209,4 +210,4 @@ It goes without saying that this list is a rough plan and subject to change.
 - Tabbed layout
 - Provide a way to display CSS and JS separately
 - Provide a way to customize the playground used (currently it is hardcoded to CodePen)
-- Provide a way to customize the buttons shown
+- Provide a way to customize the buttons shown

docs/docs/components/comparer.md

@@ -1,14 +1,16 @@
 ---
-title: Image Comparer
-description: Compare visual differences between similar photos with a sliding panel.
+title: Comparer
+description: Compare visual differences between similar content with a sliding panel.
 tags: [imagery, niche]
-icon: image-comparer
+icon: comparer
 ---
 
-For best results, use images that share the same dimensions. The slider can be controlled by dragging or pressing the left and right arrow keys. (Tip: press shift + arrows to move the slider in larger intervals, or home + end to jump to the beginning or end.)
+This is especially useful for comparing images, but can be used for comparing any type of content (for an example of using it to compare entire UIs, check out our [theme pages](/docs/themes/default/)).
+For best results, use content that shares the same dimensions.
+The slider can be controlled by dragging or pressing the left and right arrow keys. (Tip: press shift + arrows to move the slider in larger intervals, or home + end to jump to the beginning or end.)
 
 ```html {.example}
-<wa-image-comparer>
+<wa-comparer>
   <img
     slot="before"
     src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80&sat=-100&bri=-5"
@@ -19,7 +21,7 @@ For best results, use images that share the same dimensions. The slider can be c
     src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80"
     alt="Color version of kittens in a basket looking around."
   />
-</wa-image-comparer>
+</wa-comparer>
 ```
 
 ## Examples
@@ -29,7 +31,7 @@ For best results, use images that share the same dimensions. The slider can be c
 Use the `position` attribute to set the initial position of the slider. This is a percentage from `0` to `100`.
 
 ```html {.example}
-<wa-image-comparer position="25">
+<wa-comparer position="25">
   <img
     slot="before"
     src="https://images.unsplash.com/photo-1520903074185-8eca362b3dce?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&q=80"
@@ -40,5 +42,5 @@ Use the `position` attribute to set the initial position of the slider. This is
     src="https://images.unsplash.com/photo-1520640023173-50a135e35804?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2250&q=80"
     alt="A person sitting on a yellow curb tying shoelaces on a boot."
   />
-</wa-image-comparer>
+</wa-comparer>
 ```

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/dialog.md

@@ -10,7 +10,7 @@ keywords: modal
 <!-- cspell:dictionaries lorem-ipsum -->
 
 ```html {.example}
-<wa-dialog label="Dialog" with-header with-footer id="dialog-overview">
+<wa-dialog label="Dialog" id="dialog-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
@@ -27,19 +27,20 @@ keywords: modal
 
 ## Examples
 
-### Dialog with Header
+### Dialog without Header
 
-Headers can be used to display titles and more. Use the `with-header` attribute to add a header to the dialog.
+Headers are enabled by default. To render a dialog without a header, add the `without-header` attribute.
 
 ```html {.example}
-<wa-dialog label="Dialog" with-header class="dialog-header">
+<wa-dialog label="Dialog" without-header class="dialog-without-header">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
 
 <script>
-  const dialog = document.querySelector('.dialog-header');
+  const dialog = document.querySelector('.dialog-without-header');
   const openButton = dialog.nextElementSibling;
 
   openButton.addEventListener('click', () => dialog.open = true);
@@ -48,10 +49,10 @@ Headers can be used to display titles and more. Use the `with-header` attribute
 
 ### Dialog with Footer
 
-Footers can be used to display titles and more. Use the `with-footer` attribute to add a footer to the dialog.
+Footers can be used to display titles and more. Use the `footer` slot to add a footer to the dialog.
 
 ```html {.example}
-<wa-dialog label="Dialog" with-footer class="dialog-footer">
+<wa-dialog label="Dialog" class="dialog-footer">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
@@ -71,7 +72,7 @@ Footers can be used to display titles and more. Use the `with-footer` attribute
 You can add the special `data-dialog="close"` attribute to a button inside the dialog to tell it to close without additional JavaScript. Alternatively, you can set the `open` property to `false` to close the dialog programmatically.
 
 ```html {.example}
-<wa-dialog label="Dialog" with-header with-footer class="dialog-dismiss">
+<wa-dialog label="Dialog" class="dialog-dismiss">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
@@ -88,10 +89,10 @@ You can add the special `data-dialog="close"` attribute to a button inside the d
 
 ### Custom Width
 
-Just use the CSS `width` property to set the dialog's width.
+Just use the `--width` custom property to set the dialog's width.
 
 ```html {.example}
-<wa-dialog label="Dialog" with-header with-footer class="dialog-width" style="width: 50vw;">
+<wa-dialog label="Dialog" class="dialog-width" style="--width: 50vw;">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
@@ -111,7 +112,7 @@ Just use the CSS `width` property to set the dialog's width.
 By design, a dialog's height will never exceed that of the viewport. As such, dialogs will not scroll with the page ensuring the header and footer are always accessible to the user.
 
 ```html {.example}
-<wa-dialog label="Dialog" with-header with-footer class="dialog-scrolling">
+<wa-dialog label="Dialog" class="dialog-scrolling">
   <div style="height: 150vh; border: dashed 2px var(--wa-color-surface-border); padding: 0 1rem;">
     <p>Scroll down and give it a try! 👇</p>
   </div>
@@ -133,7 +134,7 @@ By design, a dialog's height will never exceed that of the viewport. As such, di
 The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/docs/components/icon-button) if needed.
 
 ```html {.example}
-<wa-dialog label="Dialog" with-header with-footer class="dialog-header-actions">
+<wa-dialog label="Dialog" class="dialog-header-actions">
   <wa-icon-button class="new-window" slot="header-actions" name="arrow-up-right-from-square" variant="solid"></wa-icon-button>
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
@@ -156,7 +157,7 @@ The header shows a functional close button by default. You can use the `header-a
 If you want the dialog to close when the user clicks on the overlay, add the `light-dismiss` attribute.
 
 ```html {.example}
-<wa-dialog label="Dialog" light-dismiss with-header with-footer class="dialog-light-dismiss">
+<wa-dialog label="Dialog" light-dismiss class="dialog-light-dismiss">
   This dialog will close when you click on the overlay.
   <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
@@ -180,7 +181,7 @@ To keep the dialog open in such cases, you can cancel the `wa-hide` event. When
 You can use `event.detail.source` to determine which element triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or [[Escape]] to dismiss it.
 
 ```html {.example}
-<wa-dialog label="Dialog" with-header with-footer class="dialog-deny-close">
+<wa-dialog label="Dialog" class="dialog-deny-close">
   This dialog will only close when you click the button below.
   <wa-button slot="footer" variant="brand" data-dialog="close">Only this button will close it</wa-button>
 </wa-dialog>
@@ -208,7 +209,7 @@ You can use `event.detail.source` to determine which element triggered the reque
 To give focus to a specific element when the dialog opens, use the `autofocus` attribute.
 
 ```html {.example}
-<wa-dialog label="Dialog" with-header with-footer class="dialog-focus">
+<wa-dialog label="Dialog" class="dialog-focus">
   <wa-input autofocus placeholder="I will have focus when the dialog is opened"></wa-input>
   <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>

docs/docs/components/drawer.md

@@ -8,7 +8,7 @@ icon: drawer
 <!-- cspell:dictionaries lorem-ipsum -->
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer class="drawer-overview">
+<wa-drawer label="Drawer" id="drawer-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -16,7 +16,7 @@ icon: drawer
 <wa-button>Open Drawer</wa-button>
 
 <script>
-  const drawer = document.querySelector('.drawer-overview');
+  const drawer = document.querySelector('#drawer-overview');
   const openButton = drawer.nextElementSibling;
 
   openButton.addEventListener('click', () => drawer.open = true);
@@ -25,19 +25,20 @@ icon: drawer
 
 ## Examples
 
-### Drawer with Header
+### Drawer without Header
 
-Headers can be used to display titles and more. Use the `with-header` attribute to add a header to the drawer.
+Headers are enabled by default. To render a drawer without a header, add the `without-header` attribute.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header class="drawer-header">
+<wa-drawer label="Drawer" without-header class="drawer-without-header">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
 
 <script>
-  const drawer = document.querySelector('.drawer-header');
+  const drawer = document.querySelector('.drawer-without-header');
   const openButton = drawer.nextElementSibling;
 
   openButton.addEventListener('click', () => drawer.open = true);
@@ -46,10 +47,10 @@ Headers can be used to display titles and more. Use the `with-header` attribute
 
 ### Drawer with Footer
 
-Footers can be used to display titles and more. Use the `with-footer` attribute to add a footer to the drawer.
+Footers can be used to display titles and more. Use the `footer` slot to add a footer to the drawer.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-footer class="drawer-footer">
+<wa-drawer label="Drawer" class="drawer-footer">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -69,7 +70,7 @@ Footers can be used to display titles and more. Use the `with-footer` attribute
 You can add the special `data-drawer="close"` attribute to a button inside the drawer to tell it to close without additional JavaScript. Alternatively, you can set the `open` property to `false` to close the drawer programmatically.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer class="drawer-dismiss">
+<wa-drawer label="Drawer" class="drawer-dismiss">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -89,7 +90,7 @@ You can add the special `data-drawer="close"` attribute to a button inside the d
 By default, drawers slide in from the end. To make the drawer slide in from the start, set the `placement` attribute to `start`.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer placement="start" class="drawer-placement-start">
+<wa-drawer label="Drawer" placement="start" class="drawer-placement-start">
   This drawer slides in from the start.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -109,7 +110,7 @@ By default, drawers slide in from the end. To make the drawer slide in from the
 To make the drawer slide in from the top, set the `placement` attribute to `top`.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer placement="top" class="drawer-placement-top">
+<wa-drawer label="Drawer" placement="top" class="drawer-placement-top">
   This drawer slides in from the top.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -129,7 +130,7 @@ To make the drawer slide in from the top, set the `placement` attribute to `top`
 To make the drawer slide in from the bottom, set the `placement` attribute to `bottom`.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer placement="bottom" class="drawer-placement-bottom">
+<wa-drawer label="Drawer" placement="bottom" class="drawer-placement-bottom">
   This drawer slides in from the bottom.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -149,7 +150,7 @@ To make the drawer slide in from the bottom, set the `placement` attribute to `b
 Use the `--size` custom property to set the drawer's size. This will be applied to the drawer's width or height depending on its `placement`.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer class="drawer-custom-size" style="--size: 50vw;">
+<wa-drawer label="Drawer" class="drawer-custom-size" style="--size: 50vw;">
   This drawer is always 50% of the viewport.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -169,7 +170,7 @@ Use the `--size` custom property to set the drawer's size. This will be applied
 By design, a drawer's height will never exceed 100% of its container. As such, drawers will not scroll with the page to ensure the header and footer are always accessible to the user.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer class="drawer-scrolling">
+<wa-drawer label="Drawer" class="drawer-scrolling">
   <div style="height: 150vh; border: dashed 2px var(--wa-color-surface-border); padding: 0 1rem;">
     <p>Scroll down and give it a try! 👇</p>
   </div>
@@ -191,7 +192,7 @@ By design, a drawer's height will never exceed 100% of its container. As such, d
 The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/docs/components/icon-button) if needed.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer class="drawer-header-actions">
+<wa-drawer label="Drawer" class="drawer-header-actions">
   <wa-icon-button class="new-window" slot="header-actions" name="arrow-up-right-from-square" variant="solid"></wa-icon-button>
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
@@ -214,7 +215,7 @@ The header shows a functional close button by default. You can use the `header-a
 If you want the drawer to close when the user clicks on the overlay, add the `light-dismiss` attribute.
 
 ```html {.example}
-<wa-drawer label="Drawer" light-dismiss with-header with-footer class="drawer-light-dismiss">
+<wa-drawer label="Drawer" light-dismiss class="drawer-light-dismiss">
   This drawer will close when you click on the overlay.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -238,7 +239,7 @@ To keep the drawer open in such cases, you can cancel the `wa-hide` event. When
 You can use `event.detail.source` to determine what triggered the request to close. This example prevents the drawer from closing when the overlay is clicked, but allows the close button or [[Escape]] to dismiss it.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer class="drawer-deny-close">
+<wa-drawer label="Drawer" class="drawer-deny-close">
   This drawer will only close when you click the button below.
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
@@ -261,12 +262,12 @@ You can use `event.detail.source` to determine what triggered the request to clo
 </script>
 ```
 
-### Customizing Initial Focus
+### Setting Initial Focus
 
-By default, the drawer's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the drawer. If you want a different element to have focus, add the `autofocus` attribute to it as shown below.
+To give focus to a specific element when the drawer opens, use the `autofocus` attribute.
 
 ```html {.example}
-<wa-drawer label="Drawer" with-header with-footer class="drawer-focus">
+<wa-drawer label="Drawer" class="drawer-focus">
   <wa-input autofocus placeholder="I will have focus when the drawer is opened"></wa-input>
   <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>

docs/docs/components/dropdown.md

@@ -180,38 +180,3 @@ To create a submenu, nest an `<wa-menu slot="submenu">` element in a [menu item]
 :::warning
 As a UX best practice, avoid using more than one level of submenu when possible.
 :::
-
-### Hoisting
-
-Dropdown panels will be clipped if they're inside a container that has `overflow: auto|hidden`. The `hoist` attribute forces the panel to use a fixed positioning strategy, allowing it to break out of the container. In this case, the panel will be positioned relative to its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
-
-```html {.example}
-<div class="dropdown-hoist">
-  <wa-dropdown>
-    <wa-button slot="trigger" caret>No Hoist</wa-button>
-    <wa-menu>
-      <wa-menu-item>Item 1</wa-menu-item>
-      <wa-menu-item>Item 2</wa-menu-item>
-      <wa-menu-item>Item 3</wa-menu-item>
-    </wa-menu>
-  </wa-dropdown>
-
-  <wa-dropdown hoist>
-    <wa-button slot="trigger" caret>Hoist</wa-button>
-    <wa-menu>
-      <wa-menu-item>Item 1</wa-menu-item>
-      <wa-menu-item>Item 2</wa-menu-item>
-      <wa-menu-item>Item 3</wa-menu-item>
-    </wa-menu>
-  </wa-dropdown>
-</div>
-
-<style>
-  .dropdown-hoist {
-    position: relative;
-    border: solid 2px var(--wa-color-surface-border);
-    padding: var(--wa-space-m);
-    overflow: hidden;
-  }
-</style>
-```

docs/docs/components/icon.md

@@ -17,11 +17,94 @@ Not sure which icon to use? [Find the perfect icon over at Font Awesome!](https:
 
 The default icon library is Font Awesome Free, which comes with two icon families: `classic` and `brands`. Use the `family` attribute to set the icon family.
 
-Many Font Awesome Pro icon families have variants such as `thin`, `light`, `regular`, and `solid`. Font Awesome Pro users can [provide their kit code](/docs/installation/#using-font-awesome-kit-codes) to unlock additional families, including `sharp` and `duotone`. For these icon families, use the `variant` attribute to set the variant.
+Many Font Awesome Pro icon families have variants such as `thin`, `light`, `regular`, and `solid`. Font Awesome Pro users can [provide their kit code](/docs/#using-font-awesome-kit-codes) to unlock additional families, including `sharp`, `duotone`, and `sharp-duotone`. For these icon families, use the `variant` attribute to set the variant.
 
 ```html {.example}
-<wa-icon family="brands" name="font-awesome"></wa-icon>
-<wa-icon family="brands" name="web-awesome"></wa-icon>
+  <wa-icon family="brands" name="font-awesome"></wa-icon>
+  <wa-icon family="brands" name="web-awesome"></wa-icon>
+  <wa-icon family="classic" variant="light" name="sparkles"></wa-icon>
+  <wa-icon family="sharp" variant="solid" name="fire"></wa-icon>
+  <wa-icon family="duotone" variant="regular" name="cake-slice"></wa-icon>
+```
+
+### Setting defaults via CSS
+
+You can use certain CSS custom properties to set icon defaults, not just on the icon itself, but any ancestor.
+This can be useful when you want certain parameters to vary based on context, e.g. icons inside callouts or all icons for a given theme.
+
+:::warning
+These CSS properties are intended to set **defaults**, and thus only make a difference when the corresponding attributes are not set.
+In future versions of Web Awesome, we may change this behavior to allow CSS properties to override attributes if `!important` is used.
+:::
+
+For example, here is how you can use CSS custom properties to set a default icon for each type of callout:
+
+```html {.example}
+<wa-callout>
+  <!-- Look ma, no attributes! -->
+  <wa-icon slot="icon"></wa-icon>
+  This is a normal callout.
+</wa-callout>
+
+<wa-callout variant="danger">
+  <wa-icon slot="icon" name="dumpster-fire" variant="solid"></wa-icon>
+  This is a callout with an explicit icon, which overrides these defaults.
+</wa-callout>
+
+<wa-callout variant="warning">
+  <!-- Look ma, no attributes! -->
+  <wa-icon slot="icon"></wa-icon>
+  Here be dragons.
+</wa-callout>
+
+<wa-callout variant="danger">
+  <!-- Look ma, no attributes! -->
+  <wa-icon slot="icon"></wa-icon>
+  Here be more dragons.
+</wa-callout>
+
+<wa-callout variant="success">
+  <!-- Look ma, no attributes! -->
+  <wa-icon slot="icon"></wa-icon>
+  Success!
+</wa-callout>
+
+<style>
+wa-callout {
+  --wa-icon-variant: regular;
+  --wa-icon-name: info-circle;
+
+  &[variant="warning"] {
+    --wa-icon-name: triangle-exclamation;
+  }
+
+  &[variant="danger"] {
+    --wa-icon-name: circle-exclamation;
+  }
+
+  &[variant="success"] {
+    --wa-icon-name: circle-check;
+  }
+}
+</style>
+```
+
+You can even set icons dynamically, as a response to user interaction or media queries.
+For example, here's how we can change the icon on hover:
+
+```html {.example}
+<wa-button class="github" href="https://github.com/webawesome/webawesome"><wa-icon slot="prefix" fixed-width></wa-icon> GitHub Repo</wa-button>
+<style>
+.github {
+  --wa-icon-name: github;
+  --wa-icon-family: brands;
+
+  &:hover {
+    --wa-icon-name: arrow-up-right-from-square;
+    --wa-icon-family: classic;
+  }
+}
+</style>
 ```
 
 ### Colors
@@ -561,4 +644,4 @@ If you want to change the icons Web Awesome uses internally, you can register an
     resolver: name => `/path/to/custom/icons/${name}.svg`
   });
 </script>
-```
+```

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/components/page-samples/documentation.md

@@ -176,7 +176,7 @@ eleventyExcludeFromCollections: true
   </footer>
   <aside slot="aside">
     <h2 class="wa-heading-m">Discover More Birds</h2>
-    <wa-card with-image>
+    <wa-card>
       <div slot="image" class="wa-frame">
         <img src="https://images.unsplash.com/photo-1635254859323-65b78408dcca?q=20" alt="" />
       </div>
@@ -185,7 +185,7 @@ eleventyExcludeFromCollections: true
         <span class="wa-caption-s" lang="la"><em>Asio otus</em></span>
       </div>
     </wa-card>
-    <wa-card with-image>
+    <wa-card>
       <div slot="image" class="wa-frame">
         <img src="https://images.unsplash.com/photo-1661350356618-f5915c7b6a3c?q=20" alt="" />
       </div>
@@ -194,7 +194,7 @@ eleventyExcludeFromCollections: true
         <span class="wa-caption-s" lang="la"><em>Surnia ulula</em></span>
       </div>
     </wa-card>
-    <wa-card with-image>
+    <wa-card>
       <div slot="image" class="wa-frame">
         <img src="https://images.unsplash.com/photo-1660307777355-f08bced145d3?q=20" alt="" />
       </div>

docs/docs/components/page.md

@@ -168,7 +168,7 @@ It can be opened using a button with `[data-toggle-nav]` that appears in the `su
   </footer>
   <aside slot="aside" class="wa-desktop-only">
     <h2 class="wa-heading-m">Discover More Birds</h2>
-    <wa-card with-image>
+    <wa-card>
       <div slot="image" class="wa-frame">
         <img src="https://images.unsplash.com/photo-1635254859323-65b78408dcca?q=20" alt="" />
       </div>
@@ -177,7 +177,7 @@ It can be opened using a button with `[data-toggle-nav]` that appears in the `su
         <span class="wa-caption-s" lang="la"><em>Asio otus</em></span>
       </div>
     </wa-card>
-    <wa-card with-image>
+    <wa-card>
       <div slot="image" class="wa-frame">
         <img src="https://images.unsplash.com/photo-1661350356618-f5915c7b6a3c?q=20" alt="" />
       </div>
@@ -186,7 +186,7 @@ It can be opened using a button with `[data-toggle-nav]` that appears in the `su
         <span class="wa-caption-s" lang="la"><em>Surnia ulula</em></span>
       </div>
     </wa-card>
-    <wa-card with-image>
+    <wa-card>
       <div slot="image" class="wa-frame">
         <img src="https://images.unsplash.com/photo-1660307777355-f08bced145d3?q=20" alt="" />
       </div>
@@ -885,4 +885,4 @@ If you don’t want to use [native styles](/docs/native/), you can include this
 
 ```html
 <link rel="stylesheet" href="{% cdnUrl 'styles/components/page.css' %}" />
-```
+```

docs/docs/components/popup.md

@@ -468,75 +468,20 @@ Use the `sync` attribute to make the popup the same width or height as the ancho
 </script>
 ```
 
-### Positioning Strategy
-
-By default, the popup is positioned using an absolute positioning strategy. However, if your anchor is fixed or exists within a container that has `overflow: auto|hidden`, the popup risks being clipped. To work around this, you can use a fixed positioning strategy by setting the `strategy` attribute to `fixed`.
-
-The fixed positioning strategy reduces jumpiness when the anchor is fixed and allows the popup to break out containers that clip. When using this strategy, it's important to note that the content will be positioned relative to its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
-
-In this example, you can see how the popup breaks out of the overflow container when it's fixed. The fixed positioning strategy tends to be less performant than absolute, so avoid using it unnecessarily.
-
-Toggle the switch and scroll the container to see the difference.
-
-```html {.example}
-<div class="popup-strategy">
-  <div class="overflow">
-    <wa-popup placement="top" strategy="fixed" active>
-      <span slot="anchor"></span>
-      <div class="box"></div>
-    </wa-popup>
-  </div>
-
-  <wa-switch checked>Fixed</wa-switch>
-</div>
-
-<style>
-  .popup-strategy .overflow {
-    position: relative;
-    height: 300px;
-    border: solid 2px var(--wa-color-surface-border);
-    overflow: auto;
-  }
-
-  .popup-strategy span[slot='anchor'] {
-    display: inline-block;
-    width: 150px;
-    height: 150px;
-    border: dashed 2px var(--wa-color-neutral-fill-loud);
-    margin: 150px 50px;
-  }
-
-  .popup-strategy .box {
-    width: 100px;
-    height: 50px;
-    background: var(--wa-color-brand-fill-loud);
-    border-radius: var(--wa-border-radius-m);
-  }
-
-  .popup-strategy wa-switch {
-    margin-top: 1rem;
-  }
-</style>
-
-<script>
-  const container = document.querySelector('.popup-strategy');
-  const popup = container.querySelector('wa-popup');
-  const fixed = container.querySelector('wa-switch');
-
-  fixed.addEventListener('change', () => (popup.strategy = fixed.checked ? 'fixed' : 'absolute'));
-</script>
-```
-
 ### Flip
 
-When the popup doesn't have enough room in its preferred placement, it can automatically flip to keep it in view. To enable this, use the `flip` attribute. By default, the popup will flip to the opposite placement, but you can configure preferred fallback placements using `flip-fallback-placement` and `flip-fallback-strategy`. Additional options are available to control the flip behavior's boundary and padding.
+When the popup doesn't have enough room in its preferred placement, it can automatically flip to keep it in view and visually connected to its anchor.
+To enable this, use the `flip` attribute. By default, the popup will flip to the opposite placement, but you can configure preferred fallback placements using `flip-fallback-placement` and `flip-fallback-strategy`. Additional options are available to control the flip behavior's boundary and padding.
+
+By default, flip takes effect when the popup would overflow the viewport.
+You can use `boundary="scroll"` to make the popup resize when it overflows its nearest scrollable container instead.
 
 Scroll the container to see how the popup flips to prevent clipping.
 
 ```html {.example}
 <div class="popup-flip">
   <div class="overflow">
-    <wa-popup placement="top" flip active>
+    <wa-popup placement="top" flip active boundary="scroll">
       <span slot="anchor"></span>
       <div class="box"></div>
     </wa-popup>
@@ -592,7 +537,7 @@ Scroll the container to see how the popup changes it's fallback placement to pre
 ```html {.example}
 <div class="popup-flip-fallbacks">
   <div class="overflow">
-    <wa-popup placement="top" flip flip-fallback-placements="right bottom" flip-fallback-strategy="initial" active>
+    <wa-popup placement="top" flip flip-fallback-placements="right bottom" flip-fallback-strategy="initial" active boundary="scroll">
       <span slot="anchor"></span>
       <div class="box"></div>
     </wa-popup>
@@ -626,14 +571,18 @@ Scroll the container to see how the popup changes it's fallback placement to pre
 
 ### Shift
 
-When a popup is longer than its anchor, it risks being clipped by an overflowing container. In this case, use the `shift` attribute to shift the popup along its axis and back into view. You can customize the shift behavior using `shiftBoundary` and `shift-padding`.
+When a popup is longer than its anchor, it risks overflowing.
+In this case, use the `shift` attribute to shift the popup along its axis and back into view. You can customize the shift behavior using `shiftBoundary` and `shift-padding`.
+
+By default, auto-size takes effect when the popup would overflow the viewport.
+You can use `boundary="scroll"` to make the popup resize when it overflows its nearest scrollable container instead.
 
 Toggle the switch to see the difference.
 
 ```html {.example}
 <div class="popup-shift">
   <div class="overflow">
-    <wa-popup placement="top" shift shift-padding="10" active>
+    <wa-popup placement="top" shift shift-padding="10" active boundary="scroll">
       <span slot="anchor"></span>
       <div class="box"></div>
     </wa-popup>
@@ -676,7 +625,11 @@ Toggle the switch to see the difference.
 
 ### Auto-size
 
-Use the `auto-size` attribute to tell the popup to resize when necessary to prevent it from getting clipped. Possible values are `horizontal`, `vertical`, and `both`. You can use `autoSizeBoundary` and `auto-size-padding` to customize the behavior of this option. Auto-size works well with `flip`, but if you're using `auto-size-padding` make sure `flip-padding` is the same value.
+Use the `auto-size` attribute to tell the popup to resize when necessary to prevent it from overflowing.
+Possible values are `horizontal`, `vertical`, and `both`. You can use `autoSizeBoundary` and `auto-size-padding` to customize the behavior of this option. Auto-size works well with `flip`, but if you're using `auto-size-padding` make sure `flip-padding` is the same value.
+
+By default, auto-size takes effect when the popup would overflow the viewport.
+You can use `boundary="scroll"` to make the popup resize when it overflows its nearest scrollable container instead.
 
 When using `auto-size`, one or both of `--auto-size-available-width` and `--auto-size-available-height` will be applied to the host element. These values determine the available space the popover has before clipping will occur. Since they cascade, you can use them to set a max-width/height on your popup's content and easily control its overflow.
 
@@ -685,7 +638,7 @@ Scroll the container to see the popup resize as its available space changes.
 ```html {.example}
 <div class="popup-auto-size">
   <div class="overflow">
-    <wa-popup placement="top" auto-size="both" auto-size-padding="10" active>
+    <wa-popup placement="top" auto-size="both" auto-size-padding="10" active boundary="scroll">
       <span slot="anchor"></span>
       <div class="box"></div>
     </wa-popup>

docs/docs/components/scroller.md

@@ -0,0 +1,151 @@
+---
+title: Scroller
+description: Scrollers create an accessible container while providing visual cues that help users identify and navigate through content that scrolls.
+layout: component
+tags: [organization]
+icon: scroller
+---
+
+```html {.example}
+<wa-scroller id="scroller__overview">
+  <table>
+    <tr>
+      <th>Party Role</th>
+      <th>Combat Style</th>
+      <th>Group Size</th>
+      <th>Campaign Setting</th>
+      <th>Signature Traits</th>
+    </tr>
+    <tr>
+      <td>Warrior</td>
+      <td>Melee Tank</td>
+      <td>1-2</td>
+      <td>Forgotten Realms</td>
+      <td>Plate-armored swordmaster who taunts foes.</td>
+    </tr>
+    <tr>
+      <td>Rogue</td>
+      <td>Stealth Striker</td>
+      <td>1</td>
+      <td>Eberron</td>
+      <td>Shadowy lockpick with daggers and a secret gold stash.</td>
+    </tr>
+    <tr>
+      <td>Wizard</td>
+      <td>Spell Slinger</td>
+      <td>1</td>
+      <td>Greyhawk</td>
+      <td>Robe-clad mage hurling fireballs from a messy spellbook.</td>
+    </tr>
+    <tr>
+      <td>Cleric</td>
+      <td>Divine Support</td>
+      <td>1</td>
+      <td>Ravnica</td>
+      <td>Holy healer with a glowing amulet and sneaky ale habit.</td>
+    </tr>
+    <tr>
+      <td>Bard</td>
+      <td>Charisma King</td>
+      <td>1</td>
+      <td>Dragonlance</td>
+      <td>Lute-playing charmer with magical songs and bad puns.</td>
+    </tr>
+  </table>
+</wa-scroller>
+
+<style>
+  #scroller__overview {
+    table {
+      margin-block: 0;
+    }
+
+    th,
+    td {
+      white-space: nowrap;
+    }
+
+    th:nth-child(5),
+    td:nth-child(5) {
+      min-width: 50ch;
+      white-space: wrap;
+    }
+  }
+</style>
+```
+
+## Examples
+
+### Adding Content
+
+The scroller component automatically provides a scrollable container for any content that exceeds the available space. Simply add your content as children of the `<wa-scroller>` element, and it will handle the rest.
+
+```html {.example}
+<wa-scroller>
+  <div style="width: 1200px; padding: 1rem;">
+    <h3>Superhero Team Roles Guide</h3>
+    <div class="wa-grid" style="--wa-grid-columns: 4; --wa-grid-gap: var(--wa-spacing-l);">
+      <div>
+        <h4>Team Leaders</h4>
+        <p>Charismatic captains like Captain America or Cyclops are the heart of any superteam, rallying everyone with epic speeches and killer strategies. They’re the ones calling the shots in a cosmic showdown, keeping the squad focused when Thanos or Magneto crashes the party.</p>
+      </div>
+      <div>
+        <h4>Heavy Hitters</h4>
+        <p>Powerhouses like Thor or Hulk bring the boom, smashing through villain lairs or alien armadas. Their job is to land the big punches, but they gotta pace themselves to avoid stealing the spotlight from sneakier teammates.</p>
+      </div>
+      <div>
+        <h4>Tech Geniuses</h4>
+        <p>Brainiacs like Iron Man or Mr. Fantastic keep the team one step ahead with gadgets and gizmos. They’re crafting quinjets or hacking evil AI, always ready with a snarky quip while saving the day from a computer terminal.</p>
+      </div>
+      <div>
+        <h4>Stealth Specialists</h4>
+        <p>Ninja-like heroes like Black Widow or Nightcrawler slip through the shadows, gathering intel or pulling off surprise attacks. They’re the glue that makes risky plans work, coordinating with the team to flip a losing fight into a win.</p>
+      </div>
+    </div>
+  </div>
+</wa-scroller>
+```
+
+### Orientation
+
+Set the `orientation` attribute to `vertical` and provide a height to create a vertical scroller.
+
+```html {.example}
+<wa-scroller orientation="vertical" style="max-height: 300px;">
+  <p>Superhero movies are the ultimate popcorn-fueled thrill rides, turning comic book pages into cinematic rollercoasters. Back in the early 2000s, films like X-Men and Spider-Man kicked open the door, proving tights and teamwork could pack theaters. Those early flicks leaned on practical effects and heart—like Tobey Maguire’s earnest web-slinger saving a train—making us believe a guy in spandex could be a hero. They weren’t perfect, but they set the stage for the genre to become a cultural juggernaut.</p>
+  <p>By the 2010s, the Marvel Cinematic Universe turned superhero films into a shared saga, like a comic crossover event on steroids. The Avengers in 2012 was a game-changer, tossing Iron Man’s snark, Thor’s hammer, and Cap’s shield into one epic brawl. Directors learned to balance humor, heart, and explosions, while studios figured out how to make every movie feel like a chapter in a bigger story. Even standalone hits like Wonder Woman brought fresh vibes, with Gal Gadot’s lasso-wielding warrior stealing hearts and smashing box office records.</p>
+  <p>Today, superhero flicks are a global obsession, from Deadpool’s chimichanga-fueled chaos to Black Panther’s Wakandan pride. They’re not just about powers—they’re about characters we root for, like Rocket Raccoon’s scrappy loyalty or Harley Quinn’s wild energy. Fans dissect trailers like detectives, theorizing about multiverses and cameos, while memes of sad Affleck or dancing Groot flood the internet. Whether it’s a gritty Joker origin or a cosmic Guardians adventure, these movies keep us glued to our seats, dreaming of heroism and one-liners that’d make even Tony Stark jealous.</p>
+</wa-scroller>
+```
+
+### Without a Shadow
+
+Use the `without-shadow` attribute to remove the fading shadow effect at the edges of the scroller, which typically indicates more content is available.
+
+```html {.example}
+<wa-scroller without-shadow>
+  <div style="width: 1500px;">
+  <p>Gaming consoles are like time machines for nerds, zapping us from pixelated 2D adventures to jaw-dropping cinematic worlds. Back in the ‘90s, the Super Nintendo was the cool kid on the block, using a 16-bit chip to pull off tricks like Mode 7, which made Mario Kart’s tracks feel like they were zooming right at you. It was like wizardry for a kid with a chunky controller, turning flat sprites into pseudo-3D races that had us yelling at our TVs when we got hit by a red shell.</p>
+  <p>Fast-forward to today, and consoles like the PlayStation 5 and Xbox Series X are basically supercomputers in sleek boxes. They’re packing enough power to make games look like Hollywood blockbusters, with lighting so real you can practically feel the sun glare in Spider-Man: Miles Morales. These machines can handle massive open worlds, like the sprawling lands of Elden Ring, without breaking a sweat, letting you swing swords or race cars while your living room feels like a sci-fi movie set. It’s a far cry from the SNES days, but the vibe’s the same: pure, controller-gripping fun.</p>
+  <p>What makes consoles the heart of gaming culture is how they bring everyone together, from casual players to hardcore speedrunners. Whether it’s your uncle fumbling through Super Mario World in ‘92 or your best friend screaming during a late-night Call of Duty match, consoles are the ultimate couch co-op machines. Modern systems even let you stream your clutch Fortnite wins to the world or jump into crossplay with PC pals. From the GameCube’s quirky handle to the Switch’s grab-and-go joy-cons, every console’s got its own personality, making every era of gaming feel like a legendary chapter in a never-ending quest.</p>
+  </div>
+</wa-scroller>
+```
+
+### Without a Scrollbar
+
+Use the `without-scrollbar` attribute to hide the scrollbar while maintaining scroll functionality. This creates a cleaner visual appearance but may reduce usability on content that needs a clear scrolling indicator.
+
+```html {.example}
+<wa-scroller without-scrollbar>
+  <div style="width: 1500px;">
+    <p>Dungeons & Dragons 5e is the blockbuster superhero flick of tabletop RPGs, turning every session into an epic tavern brawl or dragon-slaying saga. Unlike the old 3.5e days, where you’d stack +30 bonuses like a mathlete on a mission, 5e keeps things chill with skill checks capping around +11—like a +5 from your slick Charisma and +6 from being a pro at persuasion. This means even a squad of scrappy kobolds can give your level 10 barbarian a bad day if you roll poorly. It’s like the game’s saying, “Sure, you’re a hero, but don’t get cocky!”</p>
+    <p>The advantage and disadvantage system is 5e’s secret sauce, making every dice roll feel like a movie cliffhanger. Instead of juggling a dozen modifiers, you just roll two d20s and take the better (or worse) one, which shakes out to about a +5 or -5 vibe shift. It’s like your rogue’s got a lucky charm when sneaking past guards or a cursed boot when dodging a fireball. This keeps the game’s flow snappy, so you’re not stuck crunching numbers when you could be roleplaying a dramatic speech to charm a dragon or bluffing your way out of a bandit ambush.</p>
+    <p>5e’s world is built for storytelling, not just stat sheets, and that’s why it’s the king of game nights. The rules are flexible enough for your DM to whip up a haunted forest crawl or a pirate ship heist without needing a PhD in game design. Classes like the warlock let you make shady pacts with cosmic entities, while feats like Tavern Brawler turn your monk into a bar-fighting legend who can knock out goblins with a chair. Whether you’re a newbie rolling your first d20 or a veteran plotting a castle siege, 5e’s vibe is all about epic moments—like when your party’s wizard crits on a fireball and you all cheer like you just won the Super Bowl.</p>
+  </div>
+</wa-scroller>
+```
+
+:::warning
+Hiding scrollbars can negatively impact accessibility. Users who rely on visible scrollbars to navigate content may have difficulty recognizing that content is scrollable or controlling their scrolling position. Consider the needs of all users when implementing this option.
+:::