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

package/custom-elements.json

@@ -89,6 +89,219 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-badge/use-badge.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "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.",
+          "name": "UseBadge",
+          "slots": [
+            {
+              "description": "Badge content, e.g. a count or short label. Ignored when `dot` is set.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "anchortarget",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "anchortarget",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "dot",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "attribute": "dot",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "blockalign",
+              "type": {
+                "text": "\"start\" | \"end\""
+              },
+              "default": "\"start\"",
+              "attribute": "blockalign",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "inlinealign",
+              "type": {
+                "text": "\"start\" | \"end\""
+              },
+              "default": "\"end\"",
+              "attribute": "inlinealign",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "options",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "attribute": "options",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "anchorElement",
+              "description": "The element this badge is anchored to. Reading returns whatever element was last resolved,\neither from the `anchortarget` id or set here directly. Setting it anchors to that element\ninstead of resolving `anchortarget`, for cases where the target has no id to reference."
+            }
+          ],
+          "attributes": [
+            {
+              "description": "Id of the element to anchor to, resolved in the badge's own tree.",
+              "name": "anchortarget",
+              "type": {
+                "text": "string | undefined"
+              },
+              "fieldName": "anchortarget"
+            },
+            {
+              "description": "Renders as a fixed-size dot instead of the slotted content.",
+              "name": "dot",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "fieldName": "dot"
+            },
+            {
+              "description": "`\"start\" | \"end\"`: Aligns the badge along the block axis relative to its anchor.",
+              "name": "blockalign",
+              "type": {
+                "text": "\"start\" | \"end\""
+              },
+              "default": "\"start\"",
+              "fieldName": "blockalign"
+            },
+            {
+              "description": "`\"start\" | \"end\"`: Aligns the badge along the inline axis relative to its anchor.",
+              "name": "inlinealign",
+              "type": {
+                "text": "\"start\" | \"end\""
+              },
+              "default": "\"end\"",
+              "fieldName": "inlinealign"
+            },
+            {
+              "description": "Space-separated feature flags. `noaria` opts out of the automatic `aria-describedby` wiring described above.",
+              "name": "options",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "fieldName": "options"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-badge",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseBadge",
+          "declaration": {
+            "name": "UseBadge",
+            "module": "src/elements/use-badge/use-badge.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-badge",
+          "declaration": {
+            "name": "UseBadge",
+            "module": "src/elements/use-badge/use-badge.ts"
+          }
+        }
+      ]
+    },
+    {
+      "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",
@@ -494,149 +707,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-badge/use-badge.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "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.",
-          "name": "UseBadge",
-          "slots": [
-            {
-              "description": "Badge content, e.g. a count or short label. Ignored when `dot` is set.",
-              "name": ""
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "anchortarget",
-              "type": {
-                "text": "string | undefined"
-              },
-              "attribute": "anchortarget",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "dot",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "attribute": "dot",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "blockalign",
-              "type": {
-                "text": "\"start\" | \"end\""
-              },
-              "default": "\"start\"",
-              "attribute": "blockalign",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "inlinealign",
-              "type": {
-                "text": "\"start\" | \"end\""
-              },
-              "default": "\"end\"",
-              "attribute": "inlinealign",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "options",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "attribute": "options",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "anchorElement",
-              "description": "The element this badge is anchored to. Reading returns whatever element was last resolved,\neither from the `anchortarget` id or set here directly. Setting it anchors to that element\ninstead of resolving `anchortarget`, for cases where the target has no id to reference."
-            }
-          ],
-          "attributes": [
-            {
-              "description": "Id of the element to anchor to, resolved in the badge's own tree.",
-              "name": "anchortarget",
-              "type": {
-                "text": "string | undefined"
-              },
-              "fieldName": "anchortarget"
-            },
-            {
-              "description": "Renders as a fixed-size dot instead of the slotted content.",
-              "name": "dot",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "fieldName": "dot"
-            },
-            {
-              "description": "`\"start\" | \"end\"`: Aligns the badge along the block axis relative to its anchor.",
-              "name": "blockalign",
-              "type": {
-                "text": "\"start\" | \"end\""
-              },
-              "default": "\"start\"",
-              "fieldName": "blockalign"
-            },
-            {
-              "description": "`\"start\" | \"end\"`: Aligns the badge along the inline axis relative to its anchor.",
-              "name": "inlinealign",
-              "type": {
-                "text": "\"start\" | \"end\""
-              },
-              "default": "\"end\"",
-              "fieldName": "inlinealign"
-            },
-            {
-              "description": "Space-separated feature flags. `noaria` opts out of the automatic `aria-describedby` wiring described above.",
-              "name": "options",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "fieldName": "options"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-badge",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseBadge",
-          "declaration": {
-            "name": "UseBadge",
-            "module": "src/elements/use-badge/use-badge.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-badge",
-          "declaration": {
-            "name": "UseBadge",
-            "module": "src/elements/use-badge/use-badge.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-calendarday/use-calendarday.ts",
@@ -702,71 +772,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-input/use-date-input.ts",
@@ -893,6 +898,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-picker/use-date-picker.ts",

package/dist/design-system.css

@@ -1309,6 +1309,57 @@
   }
 }
 
+/* Avatar — `use-avatar.ts` ships literal fallback styles (a `currentColor` tint background,
+   medium weight, a full-round shape, and the `corner-shape` a squircle needs) so an unthemed
+   avatar renders on its own; this layer swaps them for the design system's tokens. An outer rule
+   targeting the tag beats the element's own `:host` rules, so matching `use-avatar` directly is
+   enough.
+
+   The element itself references no `--usewc-` token — those belong to the theme, which reaches
+   the component through its tag and its affordance classes (`.circle`, `.square`, `.squircle`)
+   rather than through a custom-property contract. Size is plain `inline-size`/`aspect-ratio` set
+   from outside; the element is a query container, so its initials scale from whatever box it is
+   given. */
+@layer use-theme.avatar {
+  use-avatar {
+    background: var(--usewc-color-avatar-background);
+    color: var(--usewc-color-avatar-text);
+    font-weight: var(--usewc-font-avatar-weight);
+    border-radius: var(--usewc-effect-avatar-border-radius);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-avatar.circle {
+    border-radius: var(--usewc-effect-avatar-border-radius);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-avatar.square {
+    border-radius: var(--usewc-effect-avatar-border-radius-square);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* A superellipse — rounder than a rounded rectangle, flatter than a circle. Degrades to the
+     plain radius wherever `corner-shape` isn't supported. */
+  use-avatar.squircle {
+    border-radius: var(--usewc-effect-avatar-border-radius-squircle);
+    corner-shape: squircle;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+
 /* Grid — `.table` is the default treatment a bare `use-grid` gets (bordered surface, a muted
    header, rounded per-row hover/selected bands, roomy cells); `.chips` and `.list` opt out of it
    into their own layouts. `use-gridhead`/`use-gridbody`/`use-gridcell` all render into light DOM,
@@ -2320,12 +2371,38 @@
     }
   }
 
-  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > :is(img.avatar, figure) {
+  /* A header's leading likeness is a `use-avatar` or a `<figure>` — no `img.avatar` convention,
+     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) {
     flex: none;
     inline-size: var(--usewc-layout-region-avatar-size);
     block-size: var(--usewc-layout-region-avatar-size);
     border-radius: var(--usewc-effect-surface-avatar-border-radius);
     overflow: hidden;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > figure {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin-inline: 0;
+    font-size: calc(var(--usewc-layout-region-avatar-size) * 0.4);
+    line-height: 1;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > figure > img {
+    inline-size: 100%;
+    block-size: 100%;
     object-fit: cover;
 
     use-theme-escape & {
@@ -2436,19 +2513,27 @@
     }
   }
 
-  /* The rail is a fixed square that centres whatever it's given — a photo, an `<svg>` glyph, a
-     date badge, a `<div>` of initials — rather than assuming an `<img>`. A photo fills it and
-     crops; anything else keeps its own size and sits in the middle. */
-  :where(use-layout.message) > figure {
-    display: flex;
+  /* The rail is a fixed square holding the likeness. `use-avatar` is the element for it — it
+     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) {
     grid-column: 1;
     grid-row: 1 / -1;
-    align-items: center;
-    justify-content: center;
     inline-size: var(--usewc-layout-message-rail);
     block-size: var(--usewc-layout-message-rail);
     overflow: hidden;
     border-radius: var(--usewc-effect-surface-avatar-border-radius);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.message) > figure {
+    display: flex;
+    align-items: center;
+    justify-content: center;
     font-size: calc(var(--usewc-layout-message-rail) * 0.4);
     line-height: 1;
 
@@ -2458,7 +2543,9 @@
   }
 
   :where(use-layout.message) > figure > img {
+    inline-size: 100%;
     block-size: 100%;
+    object-fit: cover;
 
     use-theme-escape & {
       all: revert-layer;

package/dist/docs/use-avatar.md

@@ -0,0 +1,40 @@
+# `use-avatar`
+
+`use-avatar` renders a small, fixed-size, clipped container for a person or entity's
+likeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a
+generated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);
+whatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,
+`use-avatar` falls back to initials derived from the `name` attribute.
+
+```html
+<use-avatar><img src="ada.jpg" alt="" /></use-avatar>
+<use-avatar name="Riley Quinn"></use-avatar>
+<use-avatar><svg viewBox="0 0 32 32">…</svg></use-avatar>
+```
+
+Size it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —
+from a stylesheet, a style attribute, or the design system's theme layer. The element takes no
+custom properties of its own: it is a query container, so the initials scale from whatever box
+it ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.
+
+The element clips its content but gives it no shape of its own — that is the theme's, through
+the affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in
+`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the
+others.
+
+The element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the
+initials fallback is plain text in the accessibility tree — an avatar is decorative beside a
+name far more often than it is the name itself, so labelling it here would mean announcing
+that name twice.
+
+## Attributes
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| name | `string` | `""` | The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty. |
+
+## Slots
+
+| Name | 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. |

package/dist/tokens.css

@@ -547,6 +547,16 @@
   --usewc-font-badge-weight: var(--usewc-font-weight-medium);
   --usewc-effect-badge-border-radius: var(--usewc-effect-border-radius-pill);
 
+  /* Avatar — `use-avatar`'s initials fallback and shape (see `theme/avatar.css`). Size and
+     aspect ratio are plain `inline-size`/`aspect-ratio`, set wherever the avatar is placed, so
+     there is no token for them — the element is a query container and scales itself. */
+  --usewc-color-avatar-background: var(--usewc-color-gray-100);
+  --usewc-color-avatar-text: var(--usewc-color-gray-600);
+  --usewc-font-avatar-weight: var(--usewc-font-weight-medium);
+  --usewc-effect-avatar-border-radius: var(--usewc-effect-border-radius-full);
+  --usewc-effect-avatar-border-radius-square: var(--usewc-effect-border-radius-6);
+  --usewc-effect-avatar-border-radius-squircle: 30%;
+
   /* Grid — `.table` is the default treatment a bare `use-grid` gets; `.chips` and `.list`
      (the latter still being defined) opt into their own layouts instead. */
   --usewc-color-grid-border: var(--usewc-color-button-base-border-static);
@@ -782,6 +792,8 @@
     --usewc-color-grid-row-background-selected-hover: oklch(from var(--usewc-color-brand-primary) 0.36 0.06 h);
     --usewc-color-grid-row-background-hover: oklch(from var(--usewc-color-gray-800) l c h / 0.6);
     --usewc-color-grid-header-text: var(--usewc-color-gray-200);
+    --usewc-color-avatar-background: var(--usewc-color-gray-800);
+    --usewc-color-avatar-text: var(--usewc-color-gray-200);
   }
 }
 

package/dist/use-wc.d.mts

@@ -1554,4 +1554,54 @@ declare global {
   }
 }
 //#endregion
-export { UseAnchored, UseBadge, UseCalendarBase, UseCalendarRenderDay, UseCaret, UseDateInput, UseDatePicker, UseDatetimeInput, UseDurationInput, UseFocusgroup, UseIntlDatetime, UseIntlNumber, UseListboxInput, UseMenu, UseMonthPicker, UseMonthPickerRenderMonth, UseOption, UseScrollarea, UseTimeInput, UseTree, UseTreeitem, UseWeekPicker, UseWidget };
+//#region src/elements/use-avatar/use-avatar.d.ts
+/**
+ * `use-avatar` renders a small, fixed-size, clipped container for a person or entity's
+ * likeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a
+ * generated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);
+ * whatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,
+ * `use-avatar` falls back to initials derived from the `name` attribute.
+ *
+ * ```html
+ * <use-avatar><img src="ada.jpg" alt="" /></use-avatar>
+ * <use-avatar name="Riley Quinn"></use-avatar>
+ * <use-avatar><svg viewBox="0 0 32 32">…</svg></use-avatar>
+ * ```
+ *
+ * Size it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —
+ * from a stylesheet, a style attribute, or the design system's theme layer. The element takes no
+ * custom properties of its own: it is a query container, so the initials scale from whatever box
+ * it ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.
+ *
+ * The element clips its content but gives it no shape of its own — that is the theme's, through
+ * the affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in
+ * `theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the
+ * others.
+ *
+ * The element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the
+ * initials fallback is plain text in the accessibility tree — an avatar is decorative beside a
+ * name far more often than it is the name itself, so labelling it here would mean announcing
+ * that name twice.
+ *
+ * @slot - 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.
+ * @attr name - The full name, used for the initials fallback (first + last whitespace-separated
+ *   token, uppercased) when the slot is empty.
+ * @csspart initials - The span that renders the `name` fallback.
+ */
+declare class UseAvatar extends LitElement {
+  #private;
+  name: string;
+  render(): TemplateResult$1<1>;
+  static styles: import("lit").CSSResult;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "use-avatar": UseAvatar;
+  }
+}
+//#endregion
+export { UseAnchored, UseAvatar, UseBadge, UseCalendarBase, UseCalendarRenderDay, UseCaret, UseDateInput, UseDatePicker, UseDatetimeInput, UseDurationInput, UseFocusgroup, UseIntlDatetime, UseIntlNumber, UseListboxInput, UseMenu, UseMonthPicker, UseMonthPickerRenderMonth, UseOption, UseScrollarea, UseTimeInput, UseTree, UseTreeitem, UseWeekPicker, UseWidget };

package/dist/use-wc.mjs

@@ -4553,4 +4553,61 @@ __decorate([property({
 })], UseBadge.prototype, "options", void 0);
 UseBadge = __decorate([customElement("use-badge")], UseBadge);
 //#endregion
-export { UseAnchored, UseBadge, UseCalendarBase, UseCaret, UseDateInput, UseDatePicker, UseDatetimeInput, UseDurationInput, UseFocusgroup, UseIntlDatetime, UseIntlNumber, UseListboxInput, UseMenu, UseMonthPicker, UseOption, UseScrollarea, UseTimeInput, UseTree, UseTreeitem, UseWeekPicker, UseWidget };
+//#region src/elements/use-avatar/use-avatar.ts
+let UseAvatar = class UseAvatar extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "";
+	}
+	get #initials() {
+		const tokens = this.name.trim().split(/\s+/).filter(Boolean);
+		if (tokens.length === 0) return "";
+		return (tokens[0].charAt(0) + (tokens.length > 1 ? tokens[tokens.length - 1].charAt(0) : "")).toUpperCase();
+	}
+	render() {
+		return html`<slot><span part="initials">${this.#initials}</span></slot>`;
+	}
+	static {
+		this.styles = css`
+    :host {
+      container-type: inline-size;
+      display: inline-flex;
+      flex: none;
+      align-items: center;
+      justify-content: center;
+      box-sizing: border-box;
+      inline-size: 2.5rem;
+      block-size: auto;
+      aspect-ratio: 1;
+      overflow: hidden;
+      background: color-mix(in oklab, currentColor 12%, transparent);
+      font-weight: 500;
+      line-height: 1;
+      white-space: nowrap;
+      user-select: none;
+    }
+
+    ::slotted(:is(img, picture)) {
+      inline-size: 100%;
+      block-size: 100%;
+      object-fit: cover;
+    }
+
+    ::slotted(svg) {
+      max-inline-size: 100%;
+      max-block-size: 100%;
+    }
+
+    [part="initials"] {
+      font-size: 38cqw;
+    }
+  `;
+	}
+};
+__decorate([property({
+	type: String,
+	reflect: true
+})], UseAvatar.prototype, "name", void 0);
+UseAvatar = __decorate([customElement("use-avatar")], UseAvatar);
+//#endregion
+export { UseAnchored, UseAvatar, UseBadge, UseCalendarBase, UseCaret, UseDateInput, UseDatePicker, UseDatetimeInput, UseDurationInput, UseFocusgroup, UseIntlDatetime, UseIntlNumber, UseListboxInput, UseMenu, UseMonthPicker, UseOption, UseScrollarea, UseTimeInput, UseTree, UseTreeitem, UseWeekPicker, UseWidget };

package/package.json

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

package/vscode.css-custom-data.json

@@ -3,6 +3,10 @@
   "version": 1.1,
   "properties": [],
   "pseudoElements": [
+    {
+      "name": "::part(initials)",
+      "description": "The span that renders the `name` fallback."
+    },
     { "name": "::part(header)", "description": "The header container" },
     { "name": "::part(title)", "description": "The title text" },
     {

package/vscode.html-custom-data.json

@@ -52,15 +52,21 @@
       "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)",
-      "attributes": [{ "name": "date", "values": [] }],
+      "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-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": [],
+      "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)",
+      "attributes": [{ "name": "date", "values": [] }],
       "references": []
     },
     {
@@ -74,6 +80,12 @@
       ],
       "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",