use-wc 1.0.0-pre.97 → 1.0.0-pre.98

package/custom-elements.json

@@ -89,76 +89,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-avatar/use-avatar.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.",
-          "name": "UseAvatar",
-          "cssParts": [
-            {
-              "description": "The span that renders the `name` fallback.",
-              "name": "initials"
-            }
-          ],
-          "slots": [
-            {
-              "description": "The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.",
-              "name": ""
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "attribute": "name",
-              "reflects": true
-            }
-          ],
-          "attributes": [
-            {
-              "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "fieldName": "name"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-avatar",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseAvatar",
-          "declaration": {
-            "name": "UseAvatar",
-            "module": "src/elements/use-avatar/use-avatar.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-avatar",
-          "declaration": {
-            "name": "UseAvatar",
-            "module": "src/elements/use-avatar/use-avatar.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-badge/use-badge.ts",
@@ -302,6 +232,76 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-avatar/use-avatar.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.",
+          "name": "UseAvatar",
+          "cssParts": [
+            {
+              "description": "The span that renders the `name` fallback.",
+              "name": "initials"
+            }
+          ],
+          "slots": [
+            {
+              "description": "The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "attribute": "name",
+              "reflects": true
+            }
+          ],
+          "attributes": [
+            {
+              "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "fieldName": "name"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-avatar",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseAvatar",
+          "declaration": {
+            "name": "UseAvatar",
+            "module": "src/elements/use-avatar/use-avatar.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-avatar",
+          "declaration": {
+            "name": "UseAvatar",
+            "module": "src/elements/use-avatar/use-avatar.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-calendar-base/use-calendar-base.ts",
@@ -4413,48 +4413,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-pattern/use-pattern.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "`use-pattern` arranges a region-based unit of content — a card, a row in a list, a chat\nmessage, a media object — styled entirely by the design system's theme layer\n(`theme/pattern.css`) rather than by any shadow DOM here. It renders its light-DOM children\nexactly as given.\n\nIts variant classes (`card`, `entry`, `message`, `media`) and their modifiers (`.divided`,\n`.compact`, `.elevated`, `.flush`) are plain classes rather than properties, the same as any\nother themed class in this system, like `use-avatar`'s `.circle`/`.square`. For generic flex\narrangement, or a page frame, use `use-layout`, which nests freely inside a pattern's regions.\n\n```html\n<use-pattern class=\"card\">\n  <header>\n    <hgroup><h3>Title</h3><p>Subtitle</p></hgroup>\n  </header>\n  <main><p>Body</p></main>\n  <footer><button type=\"button\">Done</button></footer>\n</use-pattern>\n```",
-          "name": "UsePattern",
-          "slots": [
-            {
-              "description": "The pattern's regions — `figure`, `header`, `main`, `footer`, or any other element.",
-              "name": ""
-            }
-          ],
-          "members": [],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-pattern",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UsePattern",
-          "declaration": {
-            "name": "UsePattern",
-            "module": "src/elements/use-pattern/use-pattern.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-pattern",
-          "declaration": {
-            "name": "UsePattern",
-            "module": "src/elements/use-pattern/use-pattern.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-option/use-option.ts",
@@ -4569,6 +4527,48 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-pattern/use-pattern.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`use-pattern` arranges a region-based unit of content — a card, a row in a list, a chat\nmessage, a media object — styled entirely by the design system's theme layer\n(`theme/pattern.css`) rather than by any shadow DOM here. It renders its light-DOM children\nexactly as given.\n\nIts variant classes (`card`, `entry`, `message`, `media`) and their modifiers (`.divided`,\n`.compact`, `.elevated`, `.flush`) are plain classes rather than properties, the same as any\nother themed class in this system, like `use-avatar`'s `.circle`/`.square`. For generic flex\narrangement, or a page frame, use `use-layout`, which nests freely inside a pattern's regions.\n\n```html\n<use-pattern class=\"card\">\n  <header>\n    <hgroup><h3>Title</h3><p>Subtitle</p></hgroup>\n  </header>\n  <main><p>Body</p></main>\n  <footer><button type=\"button\">Done</button></footer>\n</use-pattern>\n```",
+          "name": "UsePattern",
+          "slots": [
+            {
+              "description": "The pattern's regions — `figure`, `header`, `main`, `footer`, or any other element.",
+              "name": ""
+            }
+          ],
+          "members": [],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-pattern",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UsePattern",
+          "declaration": {
+            "name": "UsePattern",
+            "module": "src/elements/use-pattern/use-pattern.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-pattern",
+          "declaration": {
+            "name": "UsePattern",
+            "module": "src/elements/use-pattern/use-pattern.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-scrollarea/index.ts",

package/dist/design-system.css

@@ -783,8 +783,9 @@
    inside one of them would.
 
    The container only sets `display` and `isolation` — `isolation: isolate` scopes the hover
-   `z-index` below to just this set's own children, so a lifted border can't bleed into stacking
-   elsewhere on the page. Touching sides merge by default (`--usewc-layout-control-set-gap` is a
+   and focus `z-index` below to just this set's own children, so a lifted border can't bleed into
+   stacking elsewhere on the page. Focus sits a level above hover, so hovering a neighbor never
+   covers the focused child's focus ring. Touching sides merge by default (`--usewc-layout-control-set-gap` is a
    negative overlap equal to the button border, and `--usewc-effect-control-set-border-radius-sequential`
    is `0`), both themeable — see `tokens/semantic.css` for the defaults. The button border is the
    one hardcoded assumption left: it and the input border round to the same rendered pixel at
@@ -814,10 +815,14 @@
       margin-inline-start: 0;
     }
 
-    &:where(:hover, :focus-visible, :focus-within) {
+    &:hover {
       z-index: 1;
     }
 
+    &:where(:focus-visible, :focus-within) {
+      z-index: 2;
+    }
+
     use-theme-escape & {
       all: revert-layer;
     }

package/package.json

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

package/vscode.html-custom-data.json

@@ -19,18 +19,6 @@
       ],
       "references": []
     },
-    {
-      "name": "use-avatar",
-      "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.\n---\n\n\n### **Slots:**\n - _default_ - The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.\n\n### **CSS Parts:**\n - **initials** - The span that renders the `name` fallback.",
-      "attributes": [
-        {
-          "name": "name",
-          "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
-          "values": []
-        }
-      ],
-      "references": []
-    },
     {
       "name": "use-badge",
       "description": "`use-badge` renders a small indicator anchored to another element's corner, using\n[CSS anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning)\ninstead of the classic `position: absolute` + negative-offset trick. This lets the badge live\nanywhere in the DOM rather than being a child of the element it decorates. A badge's shape,\ncolor, and positioning ship built in — reading from the design system's tokens when\n`tokens.css` is loaded, and falling back to sensible defaults otherwise — so no theme is\nrequired to get a working, visible badge.\n\nPoint a badge at its target with the `anchortarget` attribute, set to the target's `id`\n(named to avoid colliding with the `anchor` content attribute HTML is gaining natively):\n\n```html\n<button type=\"button\" id=\"inbox\">Inbox</button>\n<use-badge anchortarget=\"inbox\">99+</use-badge>\n```\n\nThe badge and its anchor must live in the same DOM tree — a badge cannot reach an anchor\ninside another component's shadow root, and an anchor's `anchor-name` set inside a shadow\ntree's stylesheet is not visible here. No positioned ancestor or shared containing block is\nrequired: anchor positioning resolves the badge's location straight from the anchor's own\ngeometry, so the badge can sit anywhere else in the DOM tree.\n\nWithout a resolved anchor — `anchortarget` unset, pointing at a missing id, or `anchorElement`\nnever assigned — the badge has no `:state(anchored)` and renders as a plain inline chip in\nnormal document flow, still using the same color/shape styling.\n\nSome components render their host as `display: contents`, which has no box of its own for CSS\nanchor positioning to resolve against. If the anchor computes a non-empty `--usewc-anchor-name`\ncustom property, the badge uses that dashed-ident as its `position-anchor` directly instead of\ngenerating and writing its own onto the anchor — letting a component publish the name of a\nreal, box-generating part of itself (already established for its own purposes) for badges to\ntarget instead of its host, even though that part lives inside the component's own shadow root.\nThis mechanism is shared with `use-menu`/`use-anchored` via `AnchorController`; components\nwithout a `display: contents` host don't need to publish anything.\n\n**Known Firefox limitation:** anchoring across a shadow root boundary this way — the case\n`--usewc-anchor-name` exists for — is mispositioned in Firefox as of this writing. Verified\ndirectly: `anchor()`'s logical `start`/`end` keywords resolve backwards on both axes\nspecifically for a cross-shadow-root anchor reference, in Firefox only — the same anchor()\ncalls resolve correctly for a same-tree anchor in Firefox, and cross-shadow anchoring resolves\ncorrectly in Chromium and Safari. A badge anchored to a plain element (button, input, anything\nthat isn't itself relying on this escape hatch) is unaffected in every engine, including\nFirefox.\n\n## Side effects\n\nThe badge is a sibling of its anchor rather than a child, so **as a side effect, a badge\nmutates its anchor element**: it appends its own id to the anchor's `aria-describedby`\n(preserving any ids already there, the same way `anchor-name` is appended rather than\nreplaced) to keep its content connected to the anchor for assistive technology. This means a\nbadge's content, or its `aria-label` when set, is announced as part of interacting with the\nanchor, e.g. \"Inbox button, 3\". A `dot` badge has no content of its own, so set `aria-label`\ndirectly on `<use-badge>` for a meaningful description (e.g. `aria-label=\"3 unread messages\"`);\nwithout one, the description contributes nothing and the anchor announces as before.\n\nAvoid adding `aria-hidden` to `<use-badge>` if you rely on this: while the description\ncomputation is specified to still read a hidden node when it's the direct target of\n`aria-describedby`, support for that specific case is inconsistent across browsers and screen\nreaders.\n\nSet `options=\"noaria\"` to opt a badge out of this and leave the anchor's `aria-describedby`\nuntouched, e.g. when the anchor already documents the badge's meaning some other way.\n---\n\n\n### **Slots:**\n - _default_ - Badge content, e.g. a count or short label. Ignored when `dot` is set.",
@@ -63,6 +51,18 @@
       ],
       "references": []
     },
+    {
+      "name": "use-avatar",
+      "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.\n---\n\n\n### **Slots:**\n - _default_ - The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.\n\n### **CSS Parts:**\n - **initials** - The span that renders the `name` fallback.",
+      "attributes": [
+        {
+          "name": "name",
+          "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
+          "values": []
+        }
+      ],
+      "references": []
+    },
     {
       "name": "use-calendarday",
       "description": "A helper component for customizing specific days within `use-calendar`.\nContent placed inside this element will replace the default day number display.\n---\n\n\n### **Slots:**\n - **default** - slot for custom day content (replaces the day number)",
@@ -467,12 +467,6 @@
       ],
       "references": []
     },
-    {
-      "name": "use-pattern",
-      "description": "`use-pattern` arranges a region-based unit of content — a card, a row in a list, a chat\nmessage, a media object — styled entirely by the design system's theme layer\n(`theme/pattern.css`) rather than by any shadow DOM here. It renders its light-DOM children\nexactly as given.\n\nIts variant classes (`card`, `entry`, `message`, `media`) and their modifiers (`.divided`,\n`.compact`, `.elevated`, `.flush`) are plain classes rather than properties, the same as any\nother themed class in this system, like `use-avatar`'s `.circle`/`.square`. For generic flex\narrangement, or a page frame, use `use-layout`, which nests freely inside a pattern's regions.\n\n```html\n<use-pattern class=\"card\">\n  <header>\n    <hgroup><h3>Title</h3><p>Subtitle</p></hgroup>\n  </header>\n  <main><p>Body</p></main>\n  <footer><button type=\"button\">Done</button></footer>\n</use-pattern>\n```\n---\n\n\n### **Slots:**\n - _default_ - The pattern's regions — `figure`, `header`, `main`, `footer`, or any other element.",
-      "attributes": [],
-      "references": []
-    },
     {
       "name": "use-option",
       "description": "`use-option` is a custom element that represents an option in a `use-listbox-input` custom\nelement.\n\nThe children of this element are the content of the option and must not contain any\ninteractive elements.\n\nSelection is shown by one of two indicators, swapped based on the option's `selected` state:\na checkmark when selected, nothing (a reserved-space placeholder) when not.\n\nSwapping an indicator **per instance** is a slot: put your own element in the `selected-indicator`\nor `deselected-indicator` slot and it replaces `part(selected-indicator-default)` /\n`part(deselected-indicator-default)` entirely for that option.\n\nSwapping an indicator **for every option in the app** doesn't need touching this component's\n`render()` at all — style `::part(selected-indicator-default)` /\n`::part(deselected-indicator-default)` from an outside stylesheet, the same way any shadow DOM\npart is themed:\n\n```css\nuse-option::part(selected-indicator-default) {\n  mask-image: url(\"/icons/my-checkmark.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a pair of tokens —\n`--usewc-effect-selected-indicator-mask-image` for the shape and\n`--usewc-effect-selected-indicator-color` for what paints it (`--usewc-effect-deselected-…`\nfor the other state) — so redefining those custom properties has the same effect without\nwriting 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\n`selectedIcon` and `deselectedIcon` hooks. Every `<use-option>` in the page picks them up;\nconsumers keep writing the same tag, no new element to register or remember to use instead.\nSet them once, as early as possible (an app's entry point, before any options connect) — Lit\ncalls `render()` fresh on every update, so an already-connected instance only reflects the\nchange once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every option:\nUseOption.selectedIcon = \"✓\";\nUseOption.deselectedIcon = \"\";\n\n// A function is called on every render instead:\nUseOption.selectedIcon = (html) => html`<my-icon name=\"check\"></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\nA set icon still renders under `part(selected-indicator-default)` /\n`part(deselected-indicator-default)` — the same part the design system's theme masks into the\nbuilt-in glyph. Combining a static hook with `theme.css` means the theme's masking still\napplies to the custom content; reset the relevant `mask-image` token or `::part()` rule if that\nfights with what was set.\n\nOnly need to change the icon on **some** options, not every one in the app? Extend the class,\noverride `render()` normally, and register the subclass under a different tag name so it\ncoexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyOption extends UseOption {\n  override render() {\n    return html`<slot></slot><slot name=\"selected-indicator\"><my-icon name=\"check\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-option\", MyOption);\n```\n---\n\n\n### **Slots:**\n - **selected-indicator** - Replaces the default checkmark shown when the option is selected.\n- **deselected-indicator** - Replaces the default (empty) indicator shown when the option is not selected.\n- **default** - Option content.",
@@ -483,6 +477,12 @@
       ],
       "references": []
     },
+    {
+      "name": "use-pattern",
+      "description": "`use-pattern` arranges a region-based unit of content — a card, a row in a list, a chat\nmessage, a media object — styled entirely by the design system's theme layer\n(`theme/pattern.css`) rather than by any shadow DOM here. It renders its light-DOM children\nexactly as given.\n\nIts variant classes (`card`, `entry`, `message`, `media`) and their modifiers (`.divided`,\n`.compact`, `.elevated`, `.flush`) are plain classes rather than properties, the same as any\nother themed class in this system, like `use-avatar`'s `.circle`/`.square`. For generic flex\narrangement, or a page frame, use `use-layout`, which nests freely inside a pattern's regions.\n\n```html\n<use-pattern class=\"card\">\n  <header>\n    <hgroup><h3>Title</h3><p>Subtitle</p></hgroup>\n  </header>\n  <main><p>Body</p></main>\n  <footer><button type=\"button\">Done</button></footer>\n</use-pattern>\n```\n---\n\n\n### **Slots:**\n - _default_ - The pattern's regions — `figure`, `header`, `main`, `footer`, or any other element.",
+      "attributes": [],
+      "references": []
+    },
     {
       "name": "use-scrollarea",
       "description": "A scroll container that exposes custom states for scroll edge detection.\n\n## Custom States\nThe following CSS custom states are available for styling:\n\n- `:state(at-block-start)` — scrolled to the block-start edge (top in horizontal writing modes)\n- `:state(at-block-end)` — scrolled to the block-end edge (bottom in horizontal writing modes)\n- `:state(at-inline-start)` — scrolled to the inline-start edge (left in LTR)\n- `:state(at-inline-end)` — scrolled to the inline-end edge (right in LTR)\n---\n\n\n### **Slots:**\n - _default_ - Scrollable content",