use-wc 1.0.0-pre.82 → 1.0.0-pre.83

package/custom-elements.json

@@ -89,76 +89,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-avatar/use-avatar.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.",
-          "name": "UseAvatar",
-          "cssParts": [
-            {
-              "description": "The span that renders the `name` fallback.",
-              "name": "initials"
-            }
-          ],
-          "slots": [
-            {
-              "description": "The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.",
-              "name": ""
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "attribute": "name",
-              "reflects": true
-            }
-          ],
-          "attributes": [
-            {
-              "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "fieldName": "name"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-avatar",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseAvatar",
-          "declaration": {
-            "name": "UseAvatar",
-            "module": "src/elements/use-avatar/use-avatar.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-avatar",
-          "declaration": {
-            "name": "UseAvatar",
-            "module": "src/elements/use-avatar/use-avatar.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-badge/use-badge.ts",
@@ -302,6 +232,76 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-avatar/use-avatar.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.",
+          "name": "UseAvatar",
+          "cssParts": [
+            {
+              "description": "The span that renders the `name` fallback.",
+              "name": "initials"
+            }
+          ],
+          "slots": [
+            {
+              "description": "The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "attribute": "name",
+              "reflects": true
+            }
+          ],
+          "attributes": [
+            {
+              "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "fieldName": "name"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-avatar",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseAvatar",
+          "declaration": {
+            "name": "UseAvatar",
+            "module": "src/elements/use-avatar/use-avatar.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-avatar",
+          "declaration": {
+            "name": "UseAvatar",
+            "module": "src/elements/use-avatar/use-avatar.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-calendar-base/use-calendar-base.ts",
@@ -843,7 +843,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Groups adjacent controls — buttons and text-style inputs alike — into one visual unit: shared\nborders between touching children, rounded corners only on the two outer ends, and a hovered\nor focused child's border lifted above its neighbors so the whole border reads clearly.\n\n`use-control-set` renders no shadow DOM and no template of its own — it exists only as a\ndedicated tag for `theme/control-set.css` to style, the same way `use-layout` is a bare\nprimitive rather than a specific look. A classic split button is a text button followed by an\nicon-only trigger for a `use-menu`:\n\n```html\n<use-control-set>\n  <button type=\"button\">Save</button>\n  <button type=\"button\" popovertarget=\"save-options\" aria-label=\"More save options\">\n    <use-caret></use-caret>\n  </button>\n</use-control-set>\n<use-menu id=\"save-options\" aria-label=\"More save options\">\n  <button role=\"menuitem\">Save as&hellip;</button>\n</use-menu>\n```\n\nA search box with an attached submit button follows the same shape, mixing a text input with a\nbutton:\n\n```html\n<use-control-set>\n  <input type=\"search\" placeholder=\"Search\" />\n  <button type=\"submit\">Go</button>\n</use-control-set>\n```\n\nA child is a `<button>`, anything wearing `.appearance-button`, an `<input>` (other than a\ncheckbox/radio/range/file), a `<select>`, a `<textarea>`, or anything wearing\n`.appearance-input` — see `theme/control-set.css` for exactly which selectors read which\nradius/border tokens.\n\nHow the touching sides render is themeable rather than fixed: `--usewc-layout-control-set-gap`\n(default: a negative overlap equal to the child's own border, for a seamless merged line) and\n`--usewc-effect-control-set-border-radius-sequential` (default: `0`, for square touching\ncorners) can both be overridden — a positive gap and a small radius reads as a looser, softer\nset instead of a fused one.",
+          "description": "Groups adjacent controls — buttons and text-style inputs alike — into one visual unit: shared\nborders between touching children, rounded corners only on the two outer ends, and a hovered\nor focused child's border lifted above its neighbors so the whole border reads clearly.\n\n`use-control-set` renders no shadow DOM and no template of its own — it exists only as a\ndedicated tag for `theme/control-set.css` to style, the same way `use-layout` is a bare\nprimitive rather than a specific look. A classic split button is a text button followed by an\nicon-only trigger for a `use-menu`:\n\n```html\n<use-control-set>\n  <button type=\"button\">Save</button>\n  <button type=\"button\" popovertarget=\"save-options\" aria-label=\"More save options\">\n    <use-caret></use-caret>\n  </button>\n</use-control-set>\n<use-menu id=\"save-options\" aria-label=\"More save options\">\n  <button role=\"menuitem\">Save as&hellip;</button>\n</use-menu>\n```\n\nA search box with an attached submit button follows the same shape, mixing a text input with a\nbutton:\n\n```html\n<use-control-set>\n  <input type=\"search\" placeholder=\"Search\" />\n  <button type=\"submit\">Go</button>\n</use-control-set>\n```\n\nA child is a `<button>`, anything wearing `.appearance-button`, an `<input>` (other than a\ncheckbox/radio/range/file), a `<select>`, a `<textarea>`, or anything wearing\n`.appearance-input` — see `theme/control-set.css` for exactly which selectors read which\nradius/border tokens. A plain `span` renders as a static text cell between controls.\n\nPagination follows the same shape, with `a.appearance-button` links and `aria-current=\"page\"`\nholding the current page in its pressed look:\n\n```html\n<nav aria-label=\"Pagination\">\n  <use-control-set>\n    <a class=\"appearance-button\" href=\"?page=1\">1</a>\n    <a class=\"appearance-button\" href=\"?page=2\" aria-current=\"page\">2</a>\n    <span aria-hidden=\"true\">&hellip;</span>\n    <a class=\"appearance-button\" href=\"?page=10\">10</a>\n  </use-control-set>\n</nav>\n```\n\nHow the touching sides render is themeable rather than fixed: `--usewc-layout-control-set-gap`\n(default: a negative overlap equal to the child's own border, for a seamless merged line) and\n`--usewc-effect-control-set-border-radius-sequential` (default: `0`, for square touching\ncorners) can both be overridden — a positive gap and a small radius reads as a looser, softer\nset instead of a fused one.",
           "name": "UseControlSet",
           "slots": [
             {

package/dist/design-system.css

@@ -370,22 +370,49 @@
          text exactly here instead of staying a lighter tint of it. */
       --usewc-local-link-decoration-opacity: 1;
     }
+  }
+}
 
-    nav.sidebar > & {
-      display: block;
-      /* Swapping these source tokens, rather than the resolved `--usewc-local-link-text` slot
-         itself, means the existing `:hover`/`:active` rules above keep working unmodified — they
-         already read through `-hover`/`-active`, so overriding what those resolve to here is
-         enough to recolor every state at once. */
-      --usewc-color-link-text-static: var(--usewc-color-sidebar-item-text-static);
-      --usewc-color-link-text-hover: var(--usewc-color-sidebar-item-text-hover);
-      --usewc-color-link-text-active: var(--usewc-color-sidebar-item-text-active);
-      padding: var(--usewc-layout-sidebar-item-padding-block) var(--usewc-layout-sidebar-item-padding-inline);
-      border-radius: var(--usewc-effect-sidebar-item-border-radius);
+/* `nav.breadcrumb` lays an `ol` of links out as a single wrapping trail. The separator is
+   generated content on every item after the first, reading its glyph from
+   `--usewc-effect-breadcrumb-separator` with empty alt text (`/ ""`), so assistive tech hears the
+   list structure rather than a run of slashes.
+
+   The current page is marked with `aria-current="page"` on its link. Rather than restyling
+   `color` directly, it swaps the link's own source tokens — the same approach `nav.sidebar` takes
+   in `link.css` — so every link state resolves to the document's ink instead of link blue. The
+   link's underline is already off here, since `link.css` treats every link inside a `nav` as
+   chrome. */
+@layer use-theme.breadcrumb {
+  nav.breadcrumb > ol {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--usewc-layout-breadcrumb-gap);
+    margin: 0;
+    padding: 0;
+    list-style: none;
 
-      &:is(:hover, :focus-visible) {
-        background-color: var(--usewc-color-sidebar-item-background-hover);
-      }
+    > li {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--usewc-layout-breadcrumb-gap);
+    }
+
+    > li + li::before {
+      content: var(--usewc-effect-breadcrumb-separator) / "";
+      color: var(--usewc-color-breadcrumb-separator);
+    }
+
+    [aria-current="page"] {
+      --usewc-color-link-text-static: var(--usewc-color-breadcrumb-current-text);
+      --usewc-color-link-text-hover: var(--usewc-color-breadcrumb-current-text);
+      --usewc-color-link-text-active: var(--usewc-color-breadcrumb-current-text);
+      cursor: default;
+    }
+
+    use-theme-escape & {
+      all: revert-layer;
     }
   }
 }
@@ -655,6 +682,21 @@
       --usewc-effect-button-box-shadow-active: none;
     }
 
+    /* A current or pressed button holds its variant's own pressed look at rest and on hover — the
+       current page in a pagination `use-control-set`, or a toggle that's on. It comes after the
+       variant blocks so it re-points whichever `-active` values they set, rather than the base
+       ones. */
+    &:is([aria-current]:not([aria-current="false"]), [aria-pressed="true"]) {
+      --usewc-color-button-text-static: var(--usewc-color-button-text-active);
+      --usewc-color-button-background-static: var(--usewc-color-button-background-active);
+      --usewc-color-button-border-static: var(--usewc-color-button-border-active);
+      --usewc-color-button-text-hover: var(--usewc-color-button-text-active);
+      --usewc-color-button-background-hover: var(--usewc-color-button-background-active);
+      --usewc-color-button-border-hover: var(--usewc-color-button-border-active);
+      --usewc-effect-button-box-shadow-static: var(--usewc-effect-button-box-shadow-active);
+      --usewc-effect-button-box-shadow-hover: var(--usewc-effect-button-box-shadow-active);
+    }
+
     &.extra-small {
       --usewc-layout-button-padding-block: var(--usewc-layout-button-extra-small-padding-block);
       --usewc-layout-button-padding-inline: var(--usewc-layout-button-extra-small-padding-inline);
@@ -752,6 +794,25 @@
       all: revert-layer;
     }
   }
+
+  /* A plain `span` is a static text cell rather than a control — pagination's ellipsis, or a
+     unit beside an input. It borrows a base button's border, face, and inline padding so the
+     strip's outline stays unbroken through it, and stretches to its neighbors' height through
+     the container's default `align-items: stretch` instead of needing its own block padding. */
+  use-control-set > span:not([class*="appearance-"]) {
+    display: inline-flex;
+    align-items: center;
+    padding-inline: var(--usewc-layout-button-base-padding-inline);
+    font-size: var(--usewc-font-button-base-size);
+    color: var(--usewc-color-document-text-muted);
+    background: var(--usewc-color-button-base-background-static);
+    border: var(--usewc-layout-button-border) var(--usewc-effect-button-border-style)
+      var(--usewc-color-button-base-border-static);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
 }
 
 @layer use-theme.code {
@@ -873,8 +934,8 @@
       mask-position: center;
     }
 
-    &:is([open], :open) summary:not([class*="appearance-"])::before,
-    &:is([open], :open) summary.appearance-button::before {
+    &:is([open], :open) > summary:not([class*="appearance-"])::before,
+    &:is([open], :open) > summary.appearance-button::before {
       mask-image: var(--usewc-effect-dropdown-trigger-icon-mask-image, none);
     }
 
@@ -896,6 +957,191 @@
   }
 }
 
+/* `nav.sidebar` turns every link inside it, at any depth, into a padded row with a hover
+   background — a nested `a` would be invalid HTML anyway, so matching descendants can't reach
+   anything that isn't a nav item. It lives in its own layer after `link.css` and `details.css` so
+   its plain selectors outrank both without a specificity fight.
+
+   Links keep `link.css`'s own state machinery: this swaps the source tokens it reads through
+   (`--usewc-color-link-text-static`/`-hover`/`-active`) rather than setting `color` directly, so
+   every existing state recolors at once. `aria-current="page"` swaps the same tokens again for the
+   current page.
+
+   A `details` inside the sidebar is a collapsible group: its `summary` renders as the same kind of
+   row, keeping `details.css`'s caret. When the summary starts with an icon (`svg` or `.icon`), the
+   icon shows at rest and the caret takes its place on hover or keyboard focus — both share
+   `--usewc-layout-sidebar-item-icon-size`, so the swap never shifts the label.
+
+   Everything after the summary hangs off a guide line centered under the summary's icon column,
+   drawn once on the group's `::details-content` rather than on each row, so the rows' own rounded
+   corners never bend it, and nested rows get just enough inline padding to land their text under
+   the summary's text.
+   Rows below the top level all share one derived padding, which is why a group nested two deep
+   reads its offset from that padding instead of the top-level one.
+
+   Rows can sit directly in the nav or in `ul`/`ol` lists — lists are recommended, since assistive
+   tech announces their item count — and lists lose their bullets and indentation here so both
+   shapes render the same. That's also why a top-level group is found as a `details` with no
+   `details` ancestor rather than as a direct child of the nav.
+
+   Headings that are direct children of the nav are group labels. Only direct children count,
+   since a sidebar row can hold its own heading inside a nested `use-pattern`. */
+@layer use-theme.sidebar {
+  nav.sidebar {
+    --usewc-local-sidebar-nested-padding-inline-start: calc(
+      var(--usewc-layout-sidebar-item-icon-size) / 2 + var(--usewc-layout-sidebar-item-gap) -
+        var(--usewc-layout-sidebar-nested-guide-width) / 2 - var(--usewc-layout-sidebar-nested-guide-gap)
+    );
+
+    :is(a, summary):not([class*="appearance-"]) {
+      display: flex;
+      align-items: center;
+      gap: var(--usewc-layout-sidebar-item-gap);
+      padding: var(--usewc-layout-sidebar-item-padding-block) var(--usewc-layout-sidebar-item-padding-inline);
+      border-radius: var(--usewc-effect-sidebar-item-border-radius);
+
+      &:is(:hover, :focus-visible) {
+        background-color: var(--usewc-color-sidebar-item-background-hover);
+      }
+
+      > :is(svg, .icon):first-child {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        flex: none;
+        inline-size: var(--usewc-layout-sidebar-item-icon-size);
+        block-size: var(--usewc-layout-sidebar-item-icon-size);
+      }
+
+      > :only-child:not(svg, .icon) {
+        flex: auto;
+        min-inline-size: 0;
+      }
+
+      use-theme-escape & {
+        all: revert-layer;
+      }
+    }
+
+    a:not([class*="appearance-"]) {
+      --usewc-color-link-text-static: var(--usewc-color-sidebar-item-text-static);
+      --usewc-color-link-text-hover: var(--usewc-color-sidebar-item-text-hover);
+      --usewc-color-link-text-active: var(--usewc-color-sidebar-item-text-active);
+
+      &[aria-current="page"] {
+        --usewc-color-link-text-static: var(--usewc-color-sidebar-item-text-current);
+        --usewc-color-link-text-hover: var(--usewc-color-sidebar-item-text-current);
+        --usewc-color-link-text-active: var(--usewc-color-sidebar-item-text-current);
+        background-color: var(--usewc-color-sidebar-item-background-current);
+      }
+    }
+
+    summary:not([class*="appearance-"]) {
+      color: var(--usewc-color-sidebar-item-text-static);
+      cursor: pointer;
+      outline-offset: var(--usewc-effect-outline-offset);
+
+      &:hover {
+        color: var(--usewc-color-sidebar-item-text-hover);
+      }
+
+      &:active {
+        color: var(--usewc-color-sidebar-item-text-active);
+      }
+
+      &:focus-visible {
+        outline: var(--usewc-effect-outline-size) var(--usewc-effect-outline-style) var(--usewc-color-outline);
+      }
+
+      &::before {
+        flex: none;
+        inline-size: var(--usewc-layout-sidebar-item-icon-size);
+        block-size: var(--usewc-layout-sidebar-item-icon-size);
+      }
+
+      &:has(> :is(svg, .icon):first-child) {
+        &::before {
+          display: none;
+        }
+
+        &:is(:hover, :focus-visible) {
+          &::before {
+            display: inline-block;
+          }
+
+          > :is(svg, .icon):first-child {
+            display: none;
+          }
+        }
+      }
+
+      use-theme-escape &,
+      use-theme-escape &::before {
+        all: revert-layer;
+      }
+    }
+
+    :is(ul, ol) {
+      margin: 0;
+      padding: 0;
+      list-style: none;
+
+      use-theme-escape & {
+        all: revert-layer;
+      }
+    }
+
+    details:has(a[aria-current="page"]) > summary:not([class*="appearance-"]) {
+      color: var(--usewc-color-sidebar-item-text-current);
+    }
+
+    details::details-content {
+      padding-inline-start: var(--usewc-layout-sidebar-nested-guide-gap);
+      border-inline-start: var(--usewc-layout-sidebar-nested-guide-width) solid var(--usewc-color-sidebar-nested-guide);
+    }
+
+    details:not(details details)::details-content {
+      margin-inline-start: calc(
+        var(--usewc-layout-sidebar-item-padding-inline) + var(--usewc-layout-sidebar-item-icon-size) / 2 -
+          var(--usewc-layout-sidebar-nested-guide-width) / 2
+      );
+    }
+
+    details details::details-content {
+      margin-inline-start: calc(
+        var(--usewc-local-sidebar-nested-padding-inline-start) + var(--usewc-layout-sidebar-item-icon-size) / 2 -
+          var(--usewc-layout-sidebar-nested-guide-width) / 2
+      );
+    }
+
+    use-theme-escape & details::details-content {
+      all: revert-layer;
+    }
+
+    details > a:not([class*="appearance-"]),
+    details > :not(summary) :is(a, summary):not([class*="appearance-"]) {
+      padding-inline-start: var(--usewc-local-sidebar-nested-padding-inline-start);
+    }
+
+    > :is(h1, h2, h3, h4, h5, h6) {
+      margin: var(--usewc-layout-sidebar-group-label-spacing) 0 var(--usewc-space-4);
+      padding-inline: var(--usewc-layout-sidebar-item-padding-inline);
+      font-size: var(--usewc-font-sidebar-group-label-size);
+      font-weight: var(--usewc-font-sidebar-group-label-weight);
+      line-height: var(--usewc-layout-sidebar-group-label-line-height);
+      color: var(--usewc-color-sidebar-group-label-text);
+
+      &:first-child {
+        margin-block-start: 0;
+      }
+
+      use-theme-escape & {
+        all: revert-layer;
+      }
+    }
+  }
+}
+
 @layer use-theme.segment-input {
   :is(use-datetime-input, use-date-input, use-time-input, use-duration-input):not(.appearance-native) {
     display: inline-flex;

package/dist/docs/use-control-set.md

@@ -34,7 +34,21 @@ button:
 A child is a `<button>`, anything wearing `.appearance-button`, an `<input>` (other than a
 checkbox/radio/range/file), a `<select>`, a `<textarea>`, or anything wearing
 `.appearance-input` — see `theme/control-set.css` for exactly which selectors read which
-radius/border tokens.
+radius/border tokens. A plain `span` renders as a static text cell between controls.
+
+Pagination follows the same shape, with `a.appearance-button` links and `aria-current="page"`
+holding the current page in its pressed look:
+
+```html
+<nav aria-label="Pagination">
+  <use-control-set>
+    <a class="appearance-button" href="?page=1">1</a>
+    <a class="appearance-button" href="?page=2" aria-current="page">2</a>
+    <span aria-hidden="true">&hellip;</span>
+    <a class="appearance-button" href="?page=10">10</a>
+  </use-control-set>
+</nav>
+```
 
 How the touching sides render is themeable rather than fixed: `--usewc-layout-control-set-gap`
 (default: a negative overlap equal to the child's own border, for a seamless merged line) and

package/dist/tokens.css

@@ -222,6 +222,29 @@
   --usewc-effect-sidebar-item-border-radius: var(--usewc-effect-border-radius-6);
   --usewc-layout-sidebar-item-padding-block: var(--usewc-space-8);
   --usewc-layout-sidebar-item-padding-inline: var(--usewc-space-12);
+  --usewc-color-sidebar-item-text-current: var(--usewc-color-brand-primary);
+  --usewc-color-sidebar-item-background-current: oklch(from var(--usewc-color-brand-primary) l c h / 0.1);
+  /* A leading icon and the group caret share one box, so the caret can stand in for the icon on
+     hover without shifting the label, and one indent lines nested text up under either. */
+  --usewc-layout-sidebar-item-icon-size: 1em;
+  --usewc-layout-sidebar-item-gap: var(--usewc-space-8);
+  /* The guide is a tint of the document's own ink rather than a fixed gray, so it stays equally
+     faint against either theme's background without a dark-mode override. */
+  --usewc-color-sidebar-nested-guide: oklch(from var(--usewc-color-document-text) l c h / 0.15);
+  --usewc-layout-sidebar-nested-guide-width: var(--usewc-space-1);
+  --usewc-layout-sidebar-nested-guide-gap: var(--usewc-space-4);
+  --usewc-color-sidebar-group-label-text: var(--usewc-color-document-text-muted);
+  --usewc-font-sidebar-group-label-size: var(--usewc-font-size-12);
+  --usewc-font-sidebar-group-label-weight: var(--usewc-font-weight-semibold);
+  --usewc-layout-sidebar-group-label-line-height: var(--usewc-line-height-18);
+  --usewc-layout-sidebar-group-label-spacing: var(--usewc-space-16);
+  /* - Breadcrumb */
+  /* The separator is decoration rather than meaning, the same way a link's underline is, so it
+     lives under `effect` — `breadcrumb.css` gives it empty alt text so it's never announced. */
+  --usewc-effect-breadcrumb-separator: "/";
+  --usewc-color-breadcrumb-separator: var(--usewc-color-document-text-muted);
+  --usewc-color-breadcrumb-current-text: var(--usewc-color-document-text);
+  --usewc-layout-breadcrumb-gap: var(--usewc-space-8);
 
   /* Form */
   /* - Color */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-wc",
-  "version": "1.0.0-pre.82",
+  "version": "1.0.0-pre.83",
   "private": false,
   "homepage": "https://usewc.com",
   "bugs": "https://github.com/dang-rabbits/use-wc/issues",

package/vscode.html-custom-data.json

@@ -19,18 +19,6 @@
       ],
       "references": []
     },
-    {
-      "name": "use-avatar",
-      "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.\n---\n\n\n### **Slots:**\n - _default_ - The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.\n\n### **CSS Parts:**\n - **initials** - The span that renders the `name` fallback.",
-      "attributes": [
-        {
-          "name": "name",
-          "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
-          "values": []
-        }
-      ],
-      "references": []
-    },
     {
       "name": "use-badge",
       "description": "`use-badge` renders a small indicator anchored to another element's corner, using\n[CSS anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning)\ninstead of the classic `position: absolute` + negative-offset trick. This lets the badge live\nanywhere in the DOM rather than being a child of the element it decorates. A badge's shape,\ncolor, and positioning ship built in — reading from the design system's tokens when\n`tokens.css` is loaded, and falling back to sensible defaults otherwise — so no theme is\nrequired to get a working, visible badge.\n\nPoint a badge at its target with the `anchortarget` attribute, set to the target's `id`\n(named to avoid colliding with the `anchor` content attribute HTML is gaining natively):\n\n```html\n<button type=\"button\" id=\"inbox\">Inbox</button>\n<use-badge anchortarget=\"inbox\">99+</use-badge>\n```\n\nThe badge and its anchor must live in the same DOM tree — a badge cannot reach an anchor\ninside another component's shadow root, and an anchor's `anchor-name` set inside a shadow\ntree's stylesheet is not visible here. No positioned ancestor or shared containing block is\nrequired: anchor positioning resolves the badge's location straight from the anchor's own\ngeometry, so the badge can sit anywhere else in the DOM tree.\n\nWithout a resolved anchor — `anchortarget` unset, pointing at a missing id, or `anchorElement`\nnever assigned — the badge has no `:state(anchored)` and renders as a plain inline chip in\nnormal document flow, still using the same color/shape styling.\n\nSome components render their host as `display: contents`, which has no box of its own for CSS\nanchor positioning to resolve against. If the anchor computes a non-empty `--usewc-anchor-name`\ncustom property, the badge uses that dashed-ident as its `position-anchor` directly instead of\ngenerating and writing its own onto the anchor — letting a component publish the name of a\nreal, box-generating part of itself (already established for its own purposes) for badges to\ntarget instead of its host, even though that part lives inside the component's own shadow root.\nThis mechanism is shared with `use-menu`/`use-anchored` via `AnchorController`; components\nwithout a `display: contents` host don't need to publish anything.\n\n**Known Firefox limitation:** anchoring across a shadow root boundary this way — the case\n`--usewc-anchor-name` exists for — is mispositioned in Firefox as of this writing. Verified\ndirectly: `anchor()`'s logical `start`/`end` keywords resolve backwards on both axes\nspecifically for a cross-shadow-root anchor reference, in Firefox only — the same anchor()\ncalls resolve correctly for a same-tree anchor in Firefox, and cross-shadow anchoring resolves\ncorrectly in Chromium and Safari. A badge anchored to a plain element (button, input, anything\nthat isn't itself relying on this escape hatch) is unaffected in every engine, including\nFirefox.\n\n## Side effects\n\nThe badge is a sibling of its anchor rather than a child, so **as a side effect, a badge\nmutates its anchor element**: it appends its own id to the anchor's `aria-describedby`\n(preserving any ids already there, the same way `anchor-name` is appended rather than\nreplaced) to keep its content connected to the anchor for assistive technology. This means a\nbadge's content, or its `aria-label` when set, is announced as part of interacting with the\nanchor, e.g. \"Inbox button, 3\". A `dot` badge has no content of its own, so set `aria-label`\ndirectly on `<use-badge>` for a meaningful description (e.g. `aria-label=\"3 unread messages\"`);\nwithout one, the description contributes nothing and the anchor announces as before.\n\nAvoid adding `aria-hidden` to `<use-badge>` if you rely on this: while the description\ncomputation is specified to still read a hidden node when it's the direct target of\n`aria-describedby`, support for that specific case is inconsistent across browsers and screen\nreaders.\n\nSet `options=\"noaria\"` to opt a badge out of this and leave the anchor's `aria-describedby`\nuntouched, e.g. when the anchor already documents the badge's meaning some other way.\n---\n\n\n### **Slots:**\n - _default_ - Badge content, e.g. a count or short label. Ignored when `dot` is set.",
@@ -63,6 +51,18 @@
       ],
       "references": []
     },
+    {
+      "name": "use-avatar",
+      "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.\n---\n\n\n### **Slots:**\n - _default_ - The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.\n\n### **CSS Parts:**\n - **initials** - The span that renders the `name` fallback.",
+      "attributes": [
+        {
+          "name": "name",
+          "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
+          "values": []
+        }
+      ],
+      "references": []
+    },
     {
       "name": "use-calendarday",
       "description": "A helper component for customizing specific days within `use-calendar`.\nContent placed inside this element will replace the default day number display.\n---\n\n\n### **Slots:**\n - **default** - slot for custom day content (replaces the day number)",
@@ -77,7 +77,7 @@
     },
     {
       "name": "use-control-set",
-      "description": "Groups adjacent controls — buttons and text-style inputs alike — into one visual unit: shared\nborders between touching children, rounded corners only on the two outer ends, and a hovered\nor focused child's border lifted above its neighbors so the whole border reads clearly.\n\n`use-control-set` renders no shadow DOM and no template of its own — it exists only as a\ndedicated tag for `theme/control-set.css` to style, the same way `use-layout` is a bare\nprimitive rather than a specific look. A classic split button is a text button followed by an\nicon-only trigger for a `use-menu`:\n\n```html\n<use-control-set>\n  <button type=\"button\">Save</button>\n  <button type=\"button\" popovertarget=\"save-options\" aria-label=\"More save options\">\n    <use-caret></use-caret>\n  </button>\n</use-control-set>\n<use-menu id=\"save-options\" aria-label=\"More save options\">\n  <button role=\"menuitem\">Save as&hellip;</button>\n</use-menu>\n```\n\nA search box with an attached submit button follows the same shape, mixing a text input with a\nbutton:\n\n```html\n<use-control-set>\n  <input type=\"search\" placeholder=\"Search\" />\n  <button type=\"submit\">Go</button>\n</use-control-set>\n```\n\nA child is a `<button>`, anything wearing `.appearance-button`, an `<input>` (other than a\ncheckbox/radio/range/file), a `<select>`, a `<textarea>`, or anything wearing\n`.appearance-input` — see `theme/control-set.css` for exactly which selectors read which\nradius/border tokens.\n\nHow the touching sides render is themeable rather than fixed: `--usewc-layout-control-set-gap`\n(default: a negative overlap equal to the child's own border, for a seamless merged line) and\n`--usewc-effect-control-set-border-radius-sequential` (default: `0`, for square touching\ncorners) can both be overridden — a positive gap and a small radius reads as a looser, softer\nset instead of a fused one.\n---\n\n\n### **Slots:**\n - _default_ - The grouped controls.",
+      "description": "Groups adjacent controls — buttons and text-style inputs alike — into one visual unit: shared\nborders between touching children, rounded corners only on the two outer ends, and a hovered\nor focused child's border lifted above its neighbors so the whole border reads clearly.\n\n`use-control-set` renders no shadow DOM and no template of its own — it exists only as a\ndedicated tag for `theme/control-set.css` to style, the same way `use-layout` is a bare\nprimitive rather than a specific look. A classic split button is a text button followed by an\nicon-only trigger for a `use-menu`:\n\n```html\n<use-control-set>\n  <button type=\"button\">Save</button>\n  <button type=\"button\" popovertarget=\"save-options\" aria-label=\"More save options\">\n    <use-caret></use-caret>\n  </button>\n</use-control-set>\n<use-menu id=\"save-options\" aria-label=\"More save options\">\n  <button role=\"menuitem\">Save as&hellip;</button>\n</use-menu>\n```\n\nA search box with an attached submit button follows the same shape, mixing a text input with a\nbutton:\n\n```html\n<use-control-set>\n  <input type=\"search\" placeholder=\"Search\" />\n  <button type=\"submit\">Go</button>\n</use-control-set>\n```\n\nA child is a `<button>`, anything wearing `.appearance-button`, an `<input>` (other than a\ncheckbox/radio/range/file), a `<select>`, a `<textarea>`, or anything wearing\n`.appearance-input` — see `theme/control-set.css` for exactly which selectors read which\nradius/border tokens. A plain `span` renders as a static text cell between controls.\n\nPagination follows the same shape, with `a.appearance-button` links and `aria-current=\"page\"`\nholding the current page in its pressed look:\n\n```html\n<nav aria-label=\"Pagination\">\n  <use-control-set>\n    <a class=\"appearance-button\" href=\"?page=1\">1</a>\n    <a class=\"appearance-button\" href=\"?page=2\" aria-current=\"page\">2</a>\n    <span aria-hidden=\"true\">&hellip;</span>\n    <a class=\"appearance-button\" href=\"?page=10\">10</a>\n  </use-control-set>\n</nav>\n```\n\nHow the touching sides render is themeable rather than fixed: `--usewc-layout-control-set-gap`\n(default: a negative overlap equal to the child's own border, for a seamless merged line) and\n`--usewc-effect-control-set-border-radius-sequential` (default: `0`, for square touching\ncorners) can both be overridden — a positive gap and a small radius reads as a looser, softer\nset instead of a fused one.\n---\n\n\n### **Slots:**\n - _default_ - The grouped controls.",
       "attributes": [],
       "references": []
     },