use-wc 1.0.0-pre.67 → 1.0.0-pre.68

package/custom-elements.json

@@ -772,6 +772,71 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-caret/use-caret.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`use-caret` supplies the caret icon and label layout for a consumer who wants to own the\ninvoking button itself. It renders inside a plain `<button>`\nthat carries the native `popovertarget` attribute, pointing at a `use-menu`:\n\n```html\n<button id=\"thing\" popovertarget=\"thing-menu\">\n  <use-caret>Menu</use-caret>\n</button>\n<use-menu id=\"thing-menu\" aria-label=\"Menu\">\n  <button role=\"menuitem\">First thing</button>\n</use-menu>\n```\n\n`use-menu` finds this button on its own via `popovertarget` and anchors to it — no\n`anchortarget` needed here; that's only for a menu with more than one invoker. See `use-menu`'s\nown docs for that case.\n\nThe button is entirely the consumer's own element — their classes, their content, their event\nhandlers. `use-caret` contributes no interactivity of its own: no internal button, no focus\ntarget, no state. It only renders the label and caret glyph, so consumers get a consistent\nvisual trigger without giving up control of the button.\n\nThe caret direction is derived rather than configured: a trigger nested inside a `use-menu`\nis understood to open a submenu and renders pointing sideways; a top-level trigger renders\npointing down.\n\nSwapping in a different caret **per instance** is a slot: put your own element in the `icon`\nslot and it replaces `part(icon-default)` entirely for that trigger.\n\nSwapping the default caret **for every trigger in the app** doesn't need touching this\ncomponent's `render()` at all — style `::part(icon-default)` from an outside stylesheet, the\nsame way any shadow DOM part is themed:\n\n```css\nuse-caret::part(icon-default) {\n  mask-image: url(\"/icons/my-caret.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a token —\n`--usewc-effect-dropdown-trigger-icon-mask-image` — so redefining that custom property has\nthe same effect without writing a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static `icon`\nand `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing\nthe same tag, no new element to register or remember to use instead. `icon` supplies a\ntop-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one\nkeeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry\npoint, before any triggers connect) — Lit calls `render()` fresh on every update, so an\nalready-connected instance only reflects the change once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger of that kind:\nUseCaret.icon = \"▾\";\nUseCaret.nestedIcon = \"▸\";\n\n// A function is called on every render instead:\nUseCaret.nestedIcon = (html) => html`<my-icon name=\"chevron-right\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nOnly need to change the icon on **some** triggers, not every one in the app? Extend the\nclass, override `render()` normally, and register the subclass under a different tag name so\nit coexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyCaret extends UseCaret {\n  override render() {\n    return html`<slot></slot><slot name=\"icon\"><my-icon name=\"chevron\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-caret\", MyCaret);\n```",
+          "name": "UseCaret",
+          "slots": [
+            {
+              "description": "Trigger label content.",
+              "name": "default"
+            },
+            {
+              "description": "Replaces the default caret glyph.",
+              "name": "icon"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "icon",
+              "type": {
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
+              },
+              "static": true,
+              "description": "Global override for a top-level trigger's caret. When set, every non-nested `<use-caret>` in\nthe page renders this inside `part(icon-default)` instead of the built-in ▼ character. A\nplain string or `TemplateResult` is used as-is; the function form is called with the\ncomponent's own `html` tag, so a returned template is guaranteed to come from the same\n`lit-html` instance this component renders with. Unset (the default) keeps the built-in ▼."
+            },
+            {
+              "kind": "field",
+              "name": "nestedIcon",
+              "type": {
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
+              },
+              "static": true,
+              "description": "Global override for a submenu trigger's caret — the counterpart to icon for a\n`<use-caret>` nested inside a `use-menu`. Unset (the default) keeps the built-in ▶."
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-caret",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseCaret",
+          "declaration": {
+            "name": "UseCaret",
+            "module": "src/elements/use-caret/use-caret.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-caret",
+          "declaration": {
+            "name": "UseCaret",
+            "module": "src/elements/use-caret/use-caret.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-date-input/use-date-input.ts",
@@ -898,71 +963,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-caret/use-caret.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "`use-caret` supplies the caret icon and label layout for a consumer who wants to own the\ninvoking button itself. It renders inside a plain `<button>`\nthat carries the native `popovertarget` attribute, pointing at a `use-menu`:\n\n```html\n<button id=\"thing\" popovertarget=\"thing-menu\">\n  <use-caret>Menu</use-caret>\n</button>\n<use-menu id=\"thing-menu\" aria-label=\"Menu\">\n  <button role=\"menuitem\">First thing</button>\n</use-menu>\n```\n\n`use-menu` finds this button on its own via `popovertarget` and anchors to it — no\n`anchortarget` needed here; that's only for a menu with more than one invoker. See `use-menu`'s\nown docs for that case.\n\nThe button is entirely the consumer's own element — their classes, their content, their event\nhandlers. `use-caret` contributes no interactivity of its own: no internal button, no focus\ntarget, no state. It only renders the label and caret glyph, so consumers get a consistent\nvisual trigger without giving up control of the button.\n\nThe caret direction is derived rather than configured: a trigger nested inside a `use-menu`\nis understood to open a submenu and renders pointing sideways; a top-level trigger renders\npointing down.\n\nSwapping in a different caret **per instance** is a slot: put your own element in the `icon`\nslot and it replaces `part(icon-default)` entirely for that trigger.\n\nSwapping the default caret **for every trigger in the app** doesn't need touching this\ncomponent's `render()` at all — style `::part(icon-default)` from an outside stylesheet, the\nsame way any shadow DOM part is themed:\n\n```css\nuse-caret::part(icon-default) {\n  mask-image: url(\"/icons/my-caret.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a token —\n`--usewc-effect-dropdown-trigger-icon-mask-image` — so redefining that custom property has\nthe same effect without writing a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static `icon`\nand `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing\nthe same tag, no new element to register or remember to use instead. `icon` supplies a\ntop-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one\nkeeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry\npoint, before any triggers connect) — Lit calls `render()` fresh on every update, so an\nalready-connected instance only reflects the change once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger of that kind:\nUseCaret.icon = \"▾\";\nUseCaret.nestedIcon = \"▸\";\n\n// A function is called on every render instead:\nUseCaret.nestedIcon = (html) => html`<my-icon name=\"chevron-right\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nOnly need to change the icon on **some** triggers, not every one in the app? Extend the\nclass, override `render()` normally, and register the subclass under a different tag name so\nit coexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyCaret extends UseCaret {\n  override render() {\n    return html`<slot></slot><slot name=\"icon\"><my-icon name=\"chevron\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-caret\", MyCaret);\n```",
-          "name": "UseCaret",
-          "slots": [
-            {
-              "description": "Trigger label content.",
-              "name": "default"
-            },
-            {
-              "description": "Replaces the default caret glyph.",
-              "name": "icon"
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "icon",
-              "type": {
-                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
-              },
-              "static": true,
-              "description": "Global override for a top-level trigger's caret. When set, every non-nested `<use-caret>` in\nthe page renders this inside `part(icon-default)` instead of the built-in ▼ character. A\nplain string or `TemplateResult` is used as-is; the function form is called with the\ncomponent's own `html` tag, so a returned template is guaranteed to come from the same\n`lit-html` instance this component renders with. Unset (the default) keeps the built-in ▼."
-            },
-            {
-              "kind": "field",
-              "name": "nestedIcon",
-              "type": {
-                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
-              },
-              "static": true,
-              "description": "Global override for a submenu trigger's caret — the counterpart to icon for a\n`<use-caret>` nested inside a `use-menu`. Unset (the default) keeps the built-in ▶."
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-caret",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseCaret",
-          "declaration": {
-            "name": "UseCaret",
-            "module": "src/elements/use-caret/use-caret.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-caret",
-          "declaration": {
-            "name": "UseCaret",
-            "module": "src/elements/use-caret/use-caret.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-date-picker/use-date-picker.ts",

package/dist/design-system.css

@@ -1996,8 +1996,8 @@
    `<main>` / `<footer>` regions are arranged to match:
 
      use-layout.page      an app frame      — ruled topbar and footer, roomy
-     use-layout.prose     a document        — stacked title/byline header, measure-capped, loose
-     use-layout.message   a chat or comment — an avatar rail with the regions beside it, compact
+     use-layout.entry     a row in a list   — a leading avatar rail with the regions beside it
+     use-layout.message   a chat or comment — `.entry`'s layout at chat density
      use-layout.card      a panel           — avatar + hgroup + actions, end-aligned ruled
                                               footer, compact, plus the chrome at end of file
 
@@ -2008,10 +2008,9 @@
 
    Rather than four arrangements, a variant class sets *only* a density scale on itself
    (`--usewc-layout-region-padding`, `-gap`, `-avatar-size`, `--usewc-layout-header-rule`,
-   `-footer-rule`, `--usewc-layout-footer-justify`, `--usewc-layout-measure`) and one generic set
-   of region rules reads them. Just three arrangements can't be said in a property — prose's
-   column header, message's rail, message's inline hgroup — and those follow as structural
-   overrides. The mechanic isn't repeated per variant either: a `use-layout.page` is a
+   `-footer-rule`, `--usewc-layout-footer-justify`, `-row-gap`) and one generic set of region
+   rules reads them. Only a couple of arrangements can't be said in a property — the entry and
+   message rail, and message's inline hgroup — and those follow as structural overrides. The mechanic isn't repeated per variant either: a `use-layout.page` is a
    `use-layout`, so the base pin/grow rules above already cover it.
 
    Every selector stays compound (`use-layout.page`, never a bare `.page`) so none of these
@@ -2213,8 +2212,8 @@
     --usewc-layout-region-padding-block: var(--usewc-layout-page-padding-block);
     --usewc-layout-region-gap: var(--usewc-layout-page-gap);
     --usewc-layout-region-avatar-size: var(--usewc-layout-page-avatar-size);
-    --usewc-layout-header-rule: var(--usewc-color-region-border);
-    --usewc-layout-footer-rule: var(--usewc-color-region-border);
+    --usewc-layout-header-rule: var(--usewc-layout-region-rule);
+    --usewc-layout-footer-rule: var(--usewc-layout-region-rule);
     --usewc-layout-footer-justify: space-between;
 
     use-theme-escape & {
@@ -2222,12 +2221,11 @@
     }
   }
 
-  use-layout.prose {
-    --usewc-layout-region-padding: var(--usewc-layout-prose-padding);
-    --usewc-layout-region-gap: var(--usewc-layout-prose-gap);
-    --usewc-layout-region-avatar-size: var(--usewc-layout-prose-avatar-size);
-    --usewc-layout-measure: var(--usewc-layout-prose-measure);
-    --usewc-layout-footer-rule: var(--usewc-color-region-border);
+  use-layout.entry {
+    --usewc-layout-region-padding: var(--usewc-layout-entry-padding);
+    --usewc-layout-region-gap: var(--usewc-layout-entry-gap);
+    --usewc-layout-region-avatar-size: var(--usewc-layout-entry-avatar-size);
+    --usewc-layout-region-row-gap: var(--usewc-layout-entry-gap);
     --usewc-layout-footer-justify: flex-start;
 
     use-theme-escape & {
@@ -2235,10 +2233,12 @@
     }
   }
 
+  /* Chat density on top of `.entry`'s layout — tighter, since a message repeats down a feed. */
   use-layout.message {
     --usewc-layout-region-padding: var(--usewc-layout-message-padding);
     --usewc-layout-region-gap: var(--usewc-layout-message-gap);
     --usewc-layout-region-avatar-size: var(--usewc-layout-message-rail);
+    --usewc-layout-region-row-gap: var(--usewc-layout-region-title-gap);
     --usewc-layout-footer-justify: flex-start;
 
     use-theme-escape & {
@@ -2250,7 +2250,7 @@
     --usewc-layout-region-padding: var(--usewc-layout-card-padding);
     --usewc-layout-region-gap: var(--usewc-layout-card-gap);
     --usewc-layout-region-avatar-size: var(--usewc-layout-card-avatar-size);
-    --usewc-layout-footer-rule: var(--usewc-color-region-border);
+    --usewc-layout-footer-rule: var(--usewc-layout-region-rule);
     --usewc-layout-footer-justify: flex-end;
 
     use-theme-escape & {
@@ -2258,11 +2258,15 @@
     }
   }
 
+  /* A rule token carries the whole border value, not just its colour, so a variant that never
+     names one gets `0 solid transparent` — no width. Declaring only a colour and leaving the
+     width at 1px would give every ruleless header and footer an invisible pixel of border, which
+     is enough to push a 36px control into a 37px region. */
   /* ── Generic regions ────────────────────────────────────────────────────────────────────────
-     One ruleset for all four variants, reading the properties above. A rule colour left unset
+     One ruleset for every variant, reading the properties above. A rule colour left unset
      falls back to `transparent`, so a variant opts into a hairline by naming one rather than by
      having a rule of its own. */
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) {
+  :where(use-layout:is(.page, .entry, .message, .card)) {
     min-block-size: 0;
 
     use-theme-escape & {
@@ -2270,7 +2274,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > use-layout[fill] {
+  :where(use-layout:is(.page, .entry, .message, .card)) > use-layout[fill] {
     overflow: auto;
     padding: var(--usewc-layout-region-padding);
 
@@ -2279,9 +2283,8 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > main {
+  :where(use-layout:is(.page, .entry, .message, .card)) > main {
     padding: var(--usewc-layout-region-padding);
-    max-inline-size: var(--usewc-layout-measure, none);
 
     use-theme-escape & {
       all: revert-layer;
@@ -2292,9 +2295,7 @@
      they'd otherwise stack on top of the padding — a leading `<p>`, `<ul>`, `<ol>` or heading
      would otherwise push itself away from an edge that's already spaced. Matched by position
      rather than by tag so it holds for whatever flow content lands there. */
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
-    > :is(main, use-layout[fill])
-    > :first-child {
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(main, use-layout[fill]) > :first-child {
     margin-block-start: 0;
 
     use-theme-escape & {
@@ -2302,9 +2303,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
-    > :is(main, use-layout[fill])
-    > :last-child {
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(main, use-layout[fill]) > :last-child {
     margin-block-end: 0;
 
     use-theme-escape & {
@@ -2314,9 +2313,7 @@
 
   /* A header already supplies the block-start padding, so the body region drops its own and the
      two read as one padded column rather than a double gap under the header. */
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
-    > header
-    + :is(main, use-layout[fill]) {
+  :where(use-layout:is(.page, .entry, .message, .card)) > header + :is(main, use-layout[fill]) {
     padding-block-start: 0;
 
     use-theme-escape & {
@@ -2324,7 +2321,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > figure {
+  :where(use-layout:is(.page, .entry, .message, .card)) > figure {
     margin: 0;
 
     use-theme-escape & {
@@ -2332,7 +2329,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > figure > img {
+  :where(use-layout:is(.page, .entry, .message, .card)) > figure > img {
     display: block;
     inline-size: 100%;
     block-size: auto;
@@ -2343,28 +2340,28 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header {
+  :where(use-layout:is(.page, .entry, .message, .card)) > header {
     display: flex;
     align-items: center;
     justify-content: flex-start;
     gap: var(--usewc-layout-region-gap);
     padding-block: var(--usewc-layout-region-padding-block, var(--usewc-layout-region-padding));
     padding-inline: var(--usewc-layout-region-padding);
-    border-block-end: var(--usewc-layout-surface-border) solid var(--usewc-layout-header-rule, transparent);
+    border-block-end: var(--usewc-layout-header-rule, 0 solid transparent);
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > footer {
+  :where(use-layout:is(.page, .entry, .message, .card)) > footer {
     display: flex;
     align-items: center;
     justify-content: var(--usewc-layout-footer-justify, flex-end);
     gap: var(--usewc-layout-region-gap);
     padding-block: var(--usewc-layout-region-padding-block, var(--usewc-layout-region-padding));
     padding-inline: var(--usewc-layout-region-padding);
-    border-block-start: var(--usewc-layout-surface-border) solid var(--usewc-layout-footer-rule, transparent);
+    border-block-start: var(--usewc-layout-footer-rule, 0 solid transparent);
 
     use-theme-escape & {
       all: revert-layer;
@@ -2375,7 +2372,7 @@
      since a bare `<img>` in a header is as likely to be a logo as a face, and a class would have
      to be remembered where the element already says it. Both are squared to the variant's avatar
      size; a `<figure>` centres whatever it holds, the same way the message rail does. */
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > :is(use-avatar, figure) {
+  :where(use-layout:is(.page, .entry, .message, .card)) > header > :is(use-avatar, figure) {
     flex: none;
     inline-size: var(--usewc-layout-region-avatar-size);
     block-size: var(--usewc-layout-region-avatar-size);
@@ -2387,7 +2384,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > figure {
+  :where(use-layout:is(.page, .entry, .message, .card)) > header > figure {
     display: flex;
     align-items: center;
     justify-content: center;
@@ -2400,7 +2397,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > figure > img {
+  :where(use-layout:is(.page, .entry, .message, .card)) > header > figure > img {
     inline-size: 100%;
     block-size: 100%;
     object-fit: cover;
@@ -2414,7 +2411,7 @@
      `<section>` in a topbar — so it's matched by descent rather than as a direct child. Only the
      one sitting directly in a header grows, since that's what pushes trailing actions to the
      far end. */
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(header, footer) hgroup {
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(header, footer) hgroup {
     display: flex;
     flex-direction: column;
     gap: var(--usewc-layout-region-title-gap);
@@ -2425,7 +2422,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > hgroup {
+  :where(use-layout:is(.page, .entry, .message, .card)) > header > hgroup {
     flex: 1;
 
     use-theme-escape & {
@@ -2433,16 +2430,35 @@
     }
   }
 
+  /* An `hgroup`'s lines get explicit line boxes so a stacked title and subtitle add up to a
+     predictable height beside a fixed-size avatar, and everything after the first steps down a
+     size — a timestamp, a byline, a location is secondary to the title it hangs off. */
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(header, footer) hgroup > * {
+    line-height: var(--usewc-layout-region-title-line-height);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(header, footer) hgroup > * + * {
+    font-size: var(--usewc-font-region-subtitle-size);
+    line-height: var(--usewc-layout-region-subtitle-line-height);
+    color: var(--usewc-color-document-text-muted);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
   /* A header and footer are flex containers and an `hgroup` is a flex column, so `gap` is the
      spacing — a default block margin stacks on top of it and blows the region apart. Headings are
      matched at any depth, since a topbar routinely nests them a `<section>` and an `<hgroup>`
      down; `<p>` and friends only need it where they sit directly in the flex flow. Body copy in
      `<main>` keeps its margins, which is the whole point of a paragraph there. */
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(header, footer) > *,
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(header, footer) hgroup > *,
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
-    > :is(header, footer)
-    :is(h1, h2, h3, h4, h5, h6) {
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(header, footer) > *,
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(header, footer) hgroup > *,
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(header, footer) :is(h1, h2, h3, h4, h5, h6) {
     margin-block: 0;
 
     use-theme-escape & {
@@ -2453,7 +2469,7 @@
   /* A `<section>` inside a header or footer is one cluster of related controls. Two or more of
      them means the region has distinct ends, so it splits them apart regardless of the variant's
      default justification. */
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(header, footer) > section {
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(header, footer) > section {
     display: flex;
     align-items: center;
     gap: var(--usewc-layout-region-gap);
@@ -2463,8 +2479,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
-    > :is(header, footer):has(> section ~ section) {
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(header, footer):has(> section ~ section) {
     justify-content: space-between;
 
     use-theme-escape & {
@@ -2473,40 +2488,47 @@
   }
 
   /* ── Structural overrides ───────────────────────────────────────────────────────────────────
-     The three arrangements a density property can't express. Same `:where()` weight as the
-     generic rules, winning on source order. */
-
-  /* Prose stacks its header instead of spreading it across a row: an eyebrow, then a title free
-     to wrap, then a byline. It shares `main`'s measure so the two align down the left edge,
-     while a `<figure>` above stays full-bleed to the container. A growing `hgroup` would stretch
-     vertically in a column, so it sizes to content here. */
-  :where(use-layout.prose) > header {
-    flex-direction: column;
-    align-items: start;
-    max-inline-size: var(--usewc-layout-measure);
+     The arrangements a density property can't express. Same `:where()` weight as the generic
+     rules, winning on source order. */
+
+  /* `.entry` is the one variant that isn't a column: a leading avatar rail with every other
+     region stacked beside it — a comment, a notification, a search result, a row in a people
+     list. `.message` is the same layout at chat density, so both are matched here.
+
+     `align-self: start` on the rail is what keeps it honest. Left to stretch, a rail spanning
+     every row forces the rows to add up to at least its own height, which pads out a short
+     header and drops an awkward gap between the name and the body. Held at the start it sizes
+     to itself, the rows keep their content heights, and spanning still guarantees the entry is
+     never shorter than the rail.
+
+     Each variant sets its own row gap. `.entry` spaces its regions evenly, since a title, a body
+     and a row of actions are three separate things. `.message` keeps them tight — a name and the
+     message under it read as one unit — and buys the footer's separation back with a margin, so
+     reactions still sit apart from the text. The rail's column is reserved by `grid-template-columns` whether or not
+     a rail is present, so a grouped entry that omits it still lines its body up with the rest. */
+  use-layout:is(.entry, .message) {
+    display: grid;
+    grid-template-columns: var(--usewc-layout-region-avatar-size) 1fr;
+    column-gap: var(--usewc-layout-region-gap);
+    row-gap: var(--usewc-layout-region-row-gap);
+    padding: var(--usewc-layout-region-padding);
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  :where(use-layout.prose) > header > hgroup {
-    flex: 0 1 auto;
+  :where(use-layout:is(.entry, .message)) > :is(header, main, footer) {
+    grid-column: 2;
+    padding: 0;
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  /* A message is the one variant that isn't a column: a fixed avatar rail, then header, body and
-     reactions stacked beside it. It's a grid rather than nested flex so the rail keeps its width
-     when a grouped message omits its header and leaves the rail empty — bodies stay aligned down
-     the feed either way. The container owns the padding, so the regions drop theirs. */
-  use-layout.message {
-    display: grid;
-    grid-template-columns: var(--usewc-layout-message-rail) 1fr;
-    gap: var(--usewc-layout-region-gap);
-    padding: var(--usewc-layout-region-padding);
+  :where(use-layout.message) > footer {
+    margin-block-start: var(--usewc-layout-region-gap);
 
     use-theme-escape & {
       all: revert-layer;
@@ -2517,11 +2539,12 @@
      brings its own initials fallback and shape — and a bare `<figure>` works too, for a date
      badge or an icon that isn't a person. A `<figure>` centres whatever it's given rather than
      assuming an `<img>`; a photo inside one fills the square and crops. */
-  :where(use-layout.message) > :is(use-avatar, figure) {
+  :where(use-layout:is(.entry, .message)) > :is(use-avatar, figure) {
     grid-column: 1;
-    grid-row: 1 / -1;
-    inline-size: var(--usewc-layout-message-rail);
-    block-size: var(--usewc-layout-message-rail);
+    grid-row: 1;
+    align-self: start;
+    inline-size: var(--usewc-layout-region-avatar-size);
+    block-size: var(--usewc-layout-region-avatar-size);
     overflow: hidden;
     border-radius: var(--usewc-effect-surface-avatar-border-radius);
 
@@ -2530,11 +2553,26 @@
     }
   }
 
-  :where(use-layout.message) > figure {
+  /* The rail shares a centre with the title block rather than being pinned to the top of it, so
+     a stacked title over a subtitle and a single line each sit level with the avatar without
+     either being measured against the other. The rail's own row grows to hold it, so it can
+     never overhang, and everything after the header falls below both.
+
+     With no header the rail has no title to centre against — the body starts at the top of the
+     column and the rail starts with it. */
+  :where(use-layout:is(.entry, .message):has(> header)) > :is(use-avatar, figure) {
+    align-self: center;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout:is(.entry, .message)) > figure {
     display: flex;
     align-items: center;
     justify-content: center;
-    font-size: calc(var(--usewc-layout-message-rail) * 0.4);
+    font-size: calc(var(--usewc-layout-region-avatar-size) * 0.4);
     line-height: 1;
 
     use-theme-escape & {
@@ -2542,7 +2580,7 @@
     }
   }
 
-  :where(use-layout.message) > figure > img {
+  :where(use-layout:is(.entry, .message)) > figure > img {
     inline-size: 100%;
     block-size: 100%;
     object-fit: cover;
@@ -2554,7 +2592,7 @@
 
   /* A `<figure>` inside the body is an attachment, not the rail — it keeps the flow but sheds the
      UA margin so the region's own spacing is the only spacing. */
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(main, use-layout[fill]) figure {
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(main, use-layout[fill]) figure {
     margin-inline: 0;
 
     use-theme-escape & {
@@ -2562,10 +2600,7 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
-    > :is(main, use-layout[fill])
-    figure
-    > img {
+  :where(use-layout:is(.page, .entry, .message, .card)) > :is(main, use-layout[fill]) figure > img {
     display: block;
     inline-size: 100%;
     block-size: auto;
@@ -2575,16 +2610,6 @@
     }
   }
 
-  :where(use-layout.message) > :is(header, main, footer) {
-    grid-column: 2;
-    padding: 0;
-    max-inline-size: none;
-
-    use-theme-escape & {
-      all: revert-layer;
-    }
-  }
-
   /* Name and timestamp sit on one line here rather than stacking, and the line never wraps —
      trailing actions stay put as the name grows. */
   :where(use-layout.message) > header > hgroup {
@@ -2630,3 +2655,236 @@
   }
 }
 
+/* Prose — `use-prose` is a theme-only tag (no custom element registration, styled by tag name
+   like `use-layout`/`use-field`), giving a block of authored text a typographic scale: a heading
+   ramp, the rhythm between blocks, list indentation, quotes, code blocks, rules and tables.
+
+   This is the only place the system sets any of that. Outside a `use-prose`, `h1`-`h6`, `p` and
+   `ul` keep the browser's own defaults, so adopting the design system never silently restyles an
+   app's existing copy — you opt a region of text in.
+
+       <use-prose>
+         <article>
+           <h1>On keeping a field notebook</h1>
+           <p>The point of a field notebook is not to be complete…</p>
+         </article>
+       </use-prose>
+
+   Everything is matched by descent, not as direct children, so `<article>`, `<section>`,
+   `<div>`, `<li>` and `<blockquote>` are transparent at any depth — markdown output nests freely
+   and still reads as prose.
+
+   The rhythm is the space *between* blocks (`+` on siblings) rather than a margin on each, so a
+   heading's spacing above it is stated once instead of emerging from two margins colliding. That
+   also means the first block in any container has no leading margin, and prose drops into a
+   layout region without fighting its padding.
+
+   Prose reaches every descendant, which includes the slotted content of a nested component — a
+   `<p>` inside a `use-layout.card` picks up prose's margins today. That is deliberate for a first
+   pass: the alternative was a hand-maintained list of every `use-` tag to revert inside, which is
+   a lot of upkeep for a problem nobody has hit yet. Wrap the exception in `use-theme-escape` if
+   it bites, and revisit once there's a real case to design against.
+
+   Every rule here is held at the weight of `use-prose` plus one type selector, with `:where()`
+   absorbing the rest, so an author's own selector out-ranks prose without a fight — and a
+   boundary rule can be reintroduced later at equal specificity if it's wanted. */
+@layer use-theme.prose {
+  use-prose {
+    display: block;
+    max-inline-size: var(--usewc-layout-prose-measure);
+    line-height: var(--usewc-layout-prose-line-height);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* The blocks prose owns. Their own margins are cleared so the rhythm below is the only source
+     of spacing between them. */
+  use-prose :is(h1, h2, h3, h4, h5, h6, p, ul, ol, dl, blockquote, pre, table, figure, hr) {
+    margin-block: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose
+    :where(h1, h2, h3, h4, h5, h6, p, ul, ol, dl, blockquote, pre, table, figure, hr)
+    + :is(h1, h2, h3, h4, h5, h6, p, ul, ol, dl, blockquote, pre, table, figure, hr) {
+    margin-block-start: var(--usewc-layout-prose-flow-gap);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* A heading opens a new section, so it takes more room above it than a paragraph does — but
+     only when something precedes it. */
+  use-prose
+    :where(h1, h2, h3, h4, h5, h6, p, ul, ol, dl, blockquote, pre, table, figure, hr)
+    + :is(h1, h2, h3, h4, h5, h6) {
+    margin-block-start: var(--usewc-layout-prose-heading-gap);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose :is(h1, h2, h3, h4, h5, h6) {
+    font-weight: var(--usewc-font-prose-heading-weight);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose h1 {
+    font-size: var(--usewc-font-prose-h1-size);
+    line-height: var(--usewc-layout-prose-h1-line-height);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose h2 {
+    font-size: var(--usewc-font-prose-h2-size);
+    line-height: var(--usewc-layout-prose-h2-line-height);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose h3 {
+    font-size: var(--usewc-font-prose-h3-size);
+    line-height: var(--usewc-layout-prose-h3-line-height);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose h4 {
+    font-size: var(--usewc-font-prose-h4-size);
+    line-height: var(--usewc-layout-prose-h4-line-height);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose h5 {
+    font-size: var(--usewc-font-prose-h5-size);
+    line-height: var(--usewc-layout-prose-h5-line-height);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose h6 {
+    font-size: var(--usewc-font-prose-h6-size);
+    line-height: var(--usewc-layout-prose-h6-line-height);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose :is(ul, ol) {
+    padding-inline-start: var(--usewc-layout-prose-list-indent);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose blockquote {
+    border-inline-start: var(--usewc-layout-prose-quote-border) solid var(--usewc-color-prose-quote-border);
+    padding-inline-start: var(--usewc-layout-prose-quote-gap);
+    color: var(--usewc-color-prose-quote-text);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose pre {
+    padding: var(--usewc-layout-prose-block-padding);
+    overflow-x: auto;
+    background: var(--usewc-color-prose-code-background);
+    border: var(--usewc-layout-prose-rule-size) solid var(--usewc-color-prose-code-border);
+    border-radius: var(--usewc-effect-prose-code-border-radius);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* `code.css` paints an inline pill — a tinted, padded, rounded inline-block. Inside a `<pre>`
+     that reads as a badge floating in a slab, so the pill is undone and the code fills the block
+     instead. The monospace family and size stay; only the inline chrome goes. */
+  use-prose :where(pre) > code {
+    display: block;
+    padding: 0;
+    border: none;
+    border-radius: 0;
+    background: none;
+    color: inherit;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose hr {
+    border: none;
+    border-block-start: var(--usewc-layout-prose-rule-size) solid var(--usewc-color-prose-rule);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose table {
+    inline-size: 100%;
+    border-collapse: collapse;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose :is(th, td) {
+    padding-block: var(--usewc-layout-prose-cell-padding-block);
+    padding-inline: var(--usewc-layout-prose-cell-padding-inline);
+    border-block-end: var(--usewc-layout-prose-rule-size) solid var(--usewc-color-prose-cell-border);
+    text-align: start;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose figcaption {
+    font-size: var(--usewc-font-prose-caption-size);
+    color: var(--usewc-color-prose-caption-text);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-prose :where(figure) > :is(img, picture, video) {
+    display: block;
+    inline-size: 100%;
+    block-size: auto;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+

package/dist/tokens.css

@@ -52,6 +52,7 @@
   --usewc-font-family-monospace: monospace;
 
   /** Line height */
+  --usewc-line-height-14: 0.875rem;
   --usewc-line-height-18: 1.125rem;
   --usewc-line-height-20: 1.25rem;
   --usewc-line-height-24: 1.5rem;
@@ -657,34 +658,100 @@
   --usewc-layout-flex-gap-xlarge: var(--usewc-space-24);
   --usewc-layout-flex-gap-super: var(--usewc-space-32);
 
+  /* Prose — the typographic scale for a block of authored text (see `theme/prose.css`). It is
+     the only place this system sets heading sizes, paragraph rhythm or list indentation: outside
+     a `use-prose`, flow content keeps the browser's own defaults, so adopting the design system
+     never silently restyles an app's existing copy.
+
+     The rhythm is expressed as the space *between* blocks rather than a margin on each, so the
+     scale reads as one ramp instead of a set of colliding margins. */
+  --usewc-layout-prose-measure: 68ch;
+  --usewc-layout-prose-flow-gap: var(--usewc-space-16);
+  --usewc-layout-prose-heading-gap: var(--usewc-space-32);
+  --usewc-layout-prose-list-indent: var(--usewc-space-24);
+  --usewc-layout-prose-quote-border: var(--usewc-space-2);
+  --usewc-layout-prose-quote-gap: var(--usewc-space-16);
+  --usewc-layout-prose-rule-size: var(--usewc-space-1);
+  --usewc-layout-prose-block-padding: var(--usewc-space-16);
+  --usewc-layout-prose-cell-padding-block: var(--usewc-space-8);
+  --usewc-layout-prose-cell-padding-inline: var(--usewc-space-12);
+
+  --usewc-font-prose-h1-size: var(--usewc-font-size-24);
+  --usewc-font-prose-h2-size: var(--usewc-font-size-20);
+  --usewc-font-prose-h3-size: var(--usewc-font-size-18);
+  --usewc-font-prose-h4-size: var(--usewc-font-size-16);
+  --usewc-font-prose-h5-size: var(--usewc-font-size-14);
+  --usewc-font-prose-h6-size: var(--usewc-font-size-14);
+  --usewc-font-prose-heading-weight: 600;
+  --usewc-font-prose-caption-size: var(--usewc-font-size-14);
+
+  --usewc-layout-prose-h1-line-height: var(--usewc-line-height-32);
+  --usewc-layout-prose-h2-line-height: var(--usewc-line-height-28);
+  --usewc-layout-prose-h3-line-height: var(--usewc-line-height-24);
+  --usewc-layout-prose-h4-line-height: var(--usewc-line-height-24);
+  --usewc-layout-prose-h5-line-height: var(--usewc-line-height-20);
+  --usewc-layout-prose-h6-line-height: var(--usewc-line-height-20);
+  /* The body line box every flow block inherits — paragraphs, list items, table cells, quotes.
+     Headings declare their own below, so this is the one value that sets reading rhythm. */
+  --usewc-layout-prose-line-height: var(--usewc-line-height-24);
+
+  --usewc-color-prose-quote-border: var(--usewc-color-surface-border);
+  --usewc-color-prose-quote-text: var(--usewc-color-document-text-muted);
+  --usewc-color-prose-caption-text: var(--usewc-color-document-text-muted);
+  --usewc-color-prose-rule: var(--usewc-color-surface-border);
+  --usewc-color-prose-cell-border: var(--usewc-color-surface-border);
+  /* A code block is a slab, not the inline pill `code.css` paints — it gets a neutral ground of
+     its own so the page's own background can sit behind it. */
+  --usewc-color-prose-code-background: var(--usewc-color-gray-50);
+  --usewc-color-prose-code-border: var(--usewc-color-surface-border);
+  --usewc-effect-prose-code-border-radius: var(--usewc-effect-border-radius-6);
+
   /* Layout regions — the density scale each `use-layout` variant sets on itself, which the one
      generic set of header / main / footer rules in `theme/layout.css` then reads. The four
      variants are deliberately far apart: a document and a card in a feed can't share one
      padding step and still read as themselves, so each gets its own rather than overriding a
      shared base. The hairline colour is shared, since a rule is a rule wherever it lands. */
   --usewc-color-region-border: var(--usewc-color-surface-border);
+  --usewc-layout-region-rule: var(--usewc-layout-surface-border) solid var(--usewc-color-region-border);
   --usewc-layout-region-title-gap: var(--usewc-space-2);
-
-  --usewc-layout-prose-padding: var(--usewc-space-32);
-  --usewc-layout-prose-gap: var(--usewc-space-16);
-  --usewc-layout-prose-measure: 68ch;
-  --usewc-layout-prose-avatar-size: var(--usewc-space-24);
+  /* A title group sits beside a fixed-size avatar, so its lines are given explicit line boxes
+     rather than the document's ratio — a stacked title and subtitle then add up to a known
+     height instead of drifting with the inherited leading. The subtitle steps down a size, since
+     a timestamp or a byline is secondary to the thing it belongs to. */
+  --usewc-layout-region-title-line-height: var(--usewc-line-height-20);
+  --usewc-font-region-subtitle-size: var(--usewc-font-size-14);
+  --usewc-layout-region-subtitle-line-height: var(--usewc-line-height-14);
+  /* A stacked title and subtitle add up to this, and it's what an avatar beside them is sized
+     to — so the two always agree, and both land on a base button's 36px height rather than
+     being pinned there by a magic number. */
+  --usewc-layout-region-title-block-size: calc(
+    var(--usewc-layout-region-title-line-height) + var(--usewc-layout-region-title-gap) +
+      var(--usewc-layout-region-subtitle-line-height)
+  );
 
   --usewc-layout-page-padding: var(--usewc-space-20);
   --usewc-layout-page-padding-block: var(--usewc-space-12);
   --usewc-layout-page-gap: var(--usewc-space-12);
-  --usewc-layout-page-avatar-size: var(--usewc-space-32);
+  --usewc-layout-page-avatar-size: var(--usewc-layout-region-title-block-size);
 
   --usewc-layout-card-padding: var(--usewc-space-12);
   --usewc-layout-card-gap: var(--usewc-space-8);
   --usewc-layout-card-avatar-size: var(--usewc-space-24);
 
-  /* The message rail width and its avatar are one value on purpose: a grouped message omits its
-     header and leaves the rail empty, and the bodies only stay aligned down a feed if the empty
-     rail is exactly as wide as the avatar it replaces. */
+  /* Avatar sizes match a base button's 36px height, so a likeness and the controls beside it in
+     a header line up on both edges rather than one floating inside the other.
+
+     An entry's avatar size doubles as the width of the rail its regions sit beside — a grouped
+     entry omits the avatar entirely, and the bodies only stay aligned down a list if the
+     reserved strip is exactly as wide as the avatar it replaces. `.message` is the same layout
+     at chat density, since it repeats far more often in a feed. */
+  --usewc-layout-entry-padding: var(--usewc-space-16);
+  --usewc-layout-entry-gap: var(--usewc-space-12);
+  --usewc-layout-entry-avatar-size: var(--usewc-layout-region-title-block-size);
+
   --usewc-layout-message-padding: var(--usewc-space-12);
   --usewc-layout-message-gap: var(--usewc-space-12);
-  --usewc-layout-message-rail: var(--usewc-space-32);
+  --usewc-layout-message-rail: var(--usewc-layout-region-title-block-size);
 
   /* Surface — the visible chrome for a surface host (background/border/radius/shadow), the
      backdrop behind a modal `<dialog>` (non-modal `[popover]` keeps its transparent UA
@@ -712,6 +779,7 @@
     /* The primary/danger fill stays the same shade in both themes — only the
        focus ring lightens in the dark. */
     --usewc-color-outline: var(--usewc-color-blue-400);
+    --usewc-color-prose-code-background: var(--usewc-color-gray-900);
     --usewc-color-input-background-static: oklch(from var(--usewc-color-gray-100) l c h / 0.025);
     --usewc-color-input-border-static: var(--usewc-color-gray-600);
     --usewc-color-input-text-static: var(--usewc-color-gray-200);

package/package.json

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

package/vscode.html-custom-data.json

@@ -69,6 +69,12 @@
       "attributes": [{ "name": "date", "values": [] }],
       "references": []
     },
+    {
+      "name": "use-caret",
+      "description": "`use-caret` supplies the caret icon and label layout for a consumer who wants to own the\ninvoking button itself. It renders inside a plain `<button>`\nthat carries the native `popovertarget` attribute, pointing at a `use-menu`:\n\n```html\n<button id=\"thing\" popovertarget=\"thing-menu\">\n  <use-caret>Menu</use-caret>\n</button>\n<use-menu id=\"thing-menu\" aria-label=\"Menu\">\n  <button role=\"menuitem\">First thing</button>\n</use-menu>\n```\n\n`use-menu` finds this button on its own via `popovertarget` and anchors to it — no\n`anchortarget` needed here; that's only for a menu with more than one invoker. See `use-menu`'s\nown docs for that case.\n\nThe button is entirely the consumer's own element — their classes, their content, their event\nhandlers. `use-caret` contributes no interactivity of its own: no internal button, no focus\ntarget, no state. It only renders the label and caret glyph, so consumers get a consistent\nvisual trigger without giving up control of the button.\n\nThe caret direction is derived rather than configured: a trigger nested inside a `use-menu`\nis understood to open a submenu and renders pointing sideways; a top-level trigger renders\npointing down.\n\nSwapping in a different caret **per instance** is a slot: put your own element in the `icon`\nslot and it replaces `part(icon-default)` entirely for that trigger.\n\nSwapping the default caret **for every trigger in the app** doesn't need touching this\ncomponent's `render()` at all — style `::part(icon-default)` from an outside stylesheet, the\nsame way any shadow DOM part is themed:\n\n```css\nuse-caret::part(icon-default) {\n  mask-image: url(\"/icons/my-caret.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a token —\n`--usewc-effect-dropdown-trigger-icon-mask-image` — so redefining that custom property has\nthe same effect without writing a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static `icon`\nand `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing\nthe same tag, no new element to register or remember to use instead. `icon` supplies a\ntop-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one\nkeeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry\npoint, before any triggers connect) — Lit calls `render()` fresh on every update, so an\nalready-connected instance only reflects the change once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger of that kind:\nUseCaret.icon = \"▾\";\nUseCaret.nestedIcon = \"▸\";\n\n// A function is called on every render instead:\nUseCaret.nestedIcon = (html) => html`<my-icon name=\"chevron-right\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nOnly need to change the icon on **some** triggers, not every one in the app? Extend the\nclass, override `render()` normally, and register the subclass under a different tag name so\nit coexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyCaret extends UseCaret {\n  override render() {\n    return html`<slot></slot><slot name=\"icon\"><my-icon name=\"chevron\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-caret\", MyCaret);\n```\n---\n\n\n### **Slots:**\n - **default** - Trigger label content.\n- **icon** - Replaces the default caret glyph.",
+      "attributes": [],
+      "references": []
+    },
     {
       "name": "use-date-input",
       "description": "Displays a date picker using segmented inputs for year, month, and day.\n\nUses browser locale for formatting and ARIA labels.\n---\n",
@@ -80,12 +86,6 @@
       ],
       "references": []
     },
-    {
-      "name": "use-caret",
-      "description": "`use-caret` supplies the caret icon and label layout for a consumer who wants to own the\ninvoking button itself. It renders inside a plain `<button>`\nthat carries the native `popovertarget` attribute, pointing at a `use-menu`:\n\n```html\n<button id=\"thing\" popovertarget=\"thing-menu\">\n  <use-caret>Menu</use-caret>\n</button>\n<use-menu id=\"thing-menu\" aria-label=\"Menu\">\n  <button role=\"menuitem\">First thing</button>\n</use-menu>\n```\n\n`use-menu` finds this button on its own via `popovertarget` and anchors to it — no\n`anchortarget` needed here; that's only for a menu with more than one invoker. See `use-menu`'s\nown docs for that case.\n\nThe button is entirely the consumer's own element — their classes, their content, their event\nhandlers. `use-caret` contributes no interactivity of its own: no internal button, no focus\ntarget, no state. It only renders the label and caret glyph, so consumers get a consistent\nvisual trigger without giving up control of the button.\n\nThe caret direction is derived rather than configured: a trigger nested inside a `use-menu`\nis understood to open a submenu and renders pointing sideways; a top-level trigger renders\npointing down.\n\nSwapping in a different caret **per instance** is a slot: put your own element in the `icon`\nslot and it replaces `part(icon-default)` entirely for that trigger.\n\nSwapping the default caret **for every trigger in the app** doesn't need touching this\ncomponent's `render()` at all — style `::part(icon-default)` from an outside stylesheet, the\nsame way any shadow DOM part is themed:\n\n```css\nuse-caret::part(icon-default) {\n  mask-image: url(\"/icons/my-caret.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a token —\n`--usewc-effect-dropdown-trigger-icon-mask-image` — so redefining that custom property has\nthe same effect without writing a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static `icon`\nand `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing\nthe same tag, no new element to register or remember to use instead. `icon` supplies a\ntop-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one\nkeeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry\npoint, before any triggers connect) — Lit calls `render()` fresh on every update, so an\nalready-connected instance only reflects the change once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger of that kind:\nUseCaret.icon = \"▾\";\nUseCaret.nestedIcon = \"▸\";\n\n// A function is called on every render instead:\nUseCaret.nestedIcon = (html) => html`<my-icon name=\"chevron-right\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nOnly need to change the icon on **some** triggers, not every one in the app? Extend the\nclass, override `render()` normally, and register the subclass under a different tag name so\nit coexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyCaret extends UseCaret {\n  override render() {\n    return html`<slot></slot><slot name=\"icon\"><my-icon name=\"chevron\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-caret\", MyCaret);\n```\n---\n\n\n### **Slots:**\n - **default** - Trigger label content.\n- **icon** - Replaces the default caret glyph.",
-      "attributes": [],
-      "references": []
-    },
     {
       "name": "use-date-picker",
       "description": "A day-granularity date picker. Value format: YYYY-MM-DD.\n\nCustomize day rendering on an instance:\n```ts\ndatePicker.renderDay = ({ day, date }, html) =>\n  date === \"2026-03-17\" ? html`<strong>${day}</strong>` : String(day);\n```\n\nOr override on a subclass to apply it to every instance, falling back to\n`super.renderDay(...)` for dates you don't want to customize:\n```ts\nclass MyDatePicker extends UseDatePicker {\n  renderDay(data: { day: number; date: string }, html: LitHtml) {\n    if (data.date === \"2026-03-17\") {\n      return html`<strong>${data.day}</strong>`;\n    }\n    return super.renderDay(data, html);\n  }\n}\n```\n---\n\n\n### **Events:**\n - **use-change** - Fired on selection with detail `{ value: string }`\n\n### **Methods:**\n - **renderDay(data: _{ day: number; date: string }_, _html: _LitHtml_): _TemplateResult | string_** - See UseCalendarRenderDay. Assigning a new function on an\ninstance (e.g. via `.renderDay=${fn}` in a Lit template) after first\nrender does not schedule a re-render on its own — call `requestUpdate()`\nif needed.\n\nDeclared as a regular method rather than a class field so subclass\noverrides can call `super.renderDay(data, html)` to fall back to the\ndefault (or a parent override's) rendering.\n\n### **Slots:**\n - **header-start** - Content before the title in the header\n- **title** - Title showing the month and year\n- **controls** - Navigation controls (previous, today, next buttons)\n- **header-end** - Content after the controls in the header\n- **date-{YYYY-MM-DD}** - Per-date content that replaces the default day number\n\n### **CSS Parts:**\n - **header** - The header container\n- **title** - The title text\n- **title-month** - The month part of the title\n- **title-literal** - Literal text in the title\n- **title-year** - The year part of the title\n- **controls** - The controls slot container\n- **control** - Individual control button\n- **control-previous** - Previous month button\n- **control-today** - Today button\n- **control-next** - Next month button\n- **grid** - The main calendar grid\n- **grid-header** - The header row with day names\n- **grid-header-cell** - Individual day name header cell\n- **grid-body** - The container for calendar weeks\n- **row** - A row of days\n- **day** - A day cell\n- **day-empty** - An empty day cell (from previous/next month)\n- **day-selected** - A selected day cell\n- **day-today** - The current date cell\n- **day-disabled** - A disabled date cell\n- **title-button** - The clickable button wrapping the month/year title\n- **picker** - The scrollable month/year picker panel (replaces grid when open)\n- **picker-year-section** - Container for one year's label and month grid\n- **picker-year-label** - The year heading inside a year section\n- **picker-months** - The 4-column month grid inside a year section\n- **picker-month** - An individual month button\n- **picker-month-current** - Applied to the currently selected month button",