use-wc 1.0.0-pre.57 → 1.0.0-pre.59

package/custom-elements.json

@@ -702,6 +702,71 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-caret/use-caret.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`use-caret` supplies the caret icon and label layout for a consumer who wants to own the\ninvoking button itself. It renders inside a plain `<button>`\nthat carries the native `popovertarget` attribute, pointing at a `use-menu`:\n\n```html\n<button id=\"thing\" popovertarget=\"thing-menu\">\n  <use-caret>Menu</use-caret>\n</button>\n<use-menu id=\"thing-menu\" aria-label=\"Menu\">\n  <button role=\"menuitem\">First thing</button>\n</use-menu>\n```\n\n`use-menu` finds this button on its own via `popovertarget` and anchors to it — no\n`anchortarget` needed here; that's only for a menu with more than one invoker. See `use-menu`'s\nown docs for that case.\n\nThe button is entirely the consumer's own element — their classes, their content, their event\nhandlers. `use-caret` contributes no interactivity of its own: no internal button, no focus\ntarget, no state. It only renders the label and caret glyph, so consumers get a consistent\nvisual trigger without giving up control of the button.\n\nThe caret direction is derived rather than configured: a trigger nested inside a `use-menu`\nis understood to open a submenu and renders pointing sideways; a top-level trigger renders\npointing down.\n\nSwapping in a different caret **per instance** is a slot: put your own element in the `icon`\nslot and it replaces `part(icon-default)` entirely for that trigger.\n\nSwapping the default caret **for every trigger in the app** doesn't need touching this\ncomponent's `render()` at all — style `::part(icon-default)` from an outside stylesheet, the\nsame way any shadow DOM part is themed:\n\n```css\nuse-caret::part(icon-default) {\n  mask-image: url(\"/icons/my-caret.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a token —\n`--usewc-effect-dropdown-trigger-icon-mask-image` — so redefining that custom property has\nthe same effect without writing a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static `icon`\nand `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing\nthe same tag, no new element to register or remember to use instead. `icon` supplies a\ntop-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one\nkeeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry\npoint, before any triggers connect) — Lit calls `render()` fresh on every update, so an\nalready-connected instance only reflects the change once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger of that kind:\nUseCaret.icon = \"▾\";\nUseCaret.nestedIcon = \"▸\";\n\n// A function is called on every render instead:\nUseCaret.nestedIcon = (html) => html`<my-icon name=\"chevron-right\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nOnly need to change the icon on **some** triggers, not every one in the app? Extend the\nclass, override `render()` normally, and register the subclass under a different tag name so\nit coexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyCaret extends UseCaret {\n  override render() {\n    return html`<slot></slot><slot name=\"icon\"><my-icon name=\"chevron\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-caret\", MyCaret);\n```",
+          "name": "UseCaret",
+          "slots": [
+            {
+              "description": "Trigger label content.",
+              "name": "default"
+            },
+            {
+              "description": "Replaces the default caret glyph.",
+              "name": "icon"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "icon",
+              "type": {
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
+              },
+              "static": true,
+              "description": "Global override for a top-level trigger's caret. When set, every non-nested `<use-caret>` in\nthe page renders this inside `part(icon-default)` instead of the built-in ▼ character. A\nplain string or `TemplateResult` is used as-is; the function form is called with the\ncomponent's own `html` tag, so a returned template is guaranteed to come from the same\n`lit-html` instance this component renders with. Unset (the default) keeps the built-in ▼."
+            },
+            {
+              "kind": "field",
+              "name": "nestedIcon",
+              "type": {
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
+              },
+              "static": true,
+              "description": "Global override for a submenu trigger's caret — the counterpart to icon for a\n`<use-caret>` nested inside a `use-menu`. Unset (the default) keeps the built-in ▶."
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-caret",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseCaret",
+          "declaration": {
+            "name": "UseCaret",
+            "module": "src/elements/use-caret/use-caret.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-caret",
+          "declaration": {
+            "name": "UseCaret",
+            "module": "src/elements/use-caret/use-caret.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-date-input/use-date-input.ts",
@@ -828,71 +893,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-caret/use-caret.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "`use-caret` supplies the caret icon and label layout for a consumer who wants to own the\ninvoking button itself. It renders inside a plain `<button>`\nthat carries the native `popovertarget` attribute, pointing at a `use-menu`:\n\n```html\n<button id=\"thing\" popovertarget=\"thing-menu\">\n  <use-caret>Menu</use-caret>\n</button>\n<use-menu id=\"thing-menu\" aria-label=\"Menu\">\n  <button role=\"menuitem\">First thing</button>\n</use-menu>\n```\n\n`use-menu` finds this button on its own via `popovertarget` and anchors to it — no\n`anchortarget` needed here; that's only for a menu with more than one invoker. See `use-menu`'s\nown docs for that case.\n\nThe button is entirely the consumer's own element — their classes, their content, their event\nhandlers. `use-caret` contributes no interactivity of its own: no internal button, no focus\ntarget, no state. It only renders the label and caret glyph, so consumers get a consistent\nvisual trigger without giving up control of the button.\n\nThe caret direction is derived rather than configured: a trigger nested inside a `use-menu`\nis understood to open a submenu and renders pointing sideways; a top-level trigger renders\npointing down.\n\nSwapping in a different caret **per instance** is a slot: put your own element in the `icon`\nslot and it replaces `part(icon-default)` entirely for that trigger.\n\nSwapping the default caret **for every trigger in the app** doesn't need touching this\ncomponent's `render()` at all — style `::part(icon-default)` from an outside stylesheet, the\nsame way any shadow DOM part is themed:\n\n```css\nuse-caret::part(icon-default) {\n  mask-image: url(\"/icons/my-caret.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a token —\n`--usewc-effect-dropdown-trigger-icon-mask-image` — so redefining that custom property has\nthe same effect without writing a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static `icon`\nand `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing\nthe same tag, no new element to register or remember to use instead. `icon` supplies a\ntop-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one\nkeeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry\npoint, before any triggers connect) — Lit calls `render()` fresh on every update, so an\nalready-connected instance only reflects the change once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger of that kind:\nUseCaret.icon = \"▾\";\nUseCaret.nestedIcon = \"▸\";\n\n// A function is called on every render instead:\nUseCaret.nestedIcon = (html) => html`<my-icon name=\"chevron-right\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nOnly need to change the icon on **some** triggers, not every one in the app? Extend the\nclass, override `render()` normally, and register the subclass under a different tag name so\nit coexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyCaret extends UseCaret {\n  override render() {\n    return html`<slot></slot><slot name=\"icon\"><my-icon name=\"chevron\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-caret\", MyCaret);\n```",
-          "name": "UseCaret",
-          "slots": [
-            {
-              "description": "Trigger label content.",
-              "name": "default"
-            },
-            {
-              "description": "Replaces the default caret glyph.",
-              "name": "icon"
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "icon",
-              "type": {
-                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
-              },
-              "static": true,
-              "description": "Global override for a top-level trigger's caret. When set, every non-nested `<use-caret>` in\nthe page renders this inside `part(icon-default)` instead of the built-in ▼ character. A\nplain string or `TemplateResult` is used as-is; the function form is called with the\ncomponent's own `html` tag, so a returned template is guaranteed to come from the same\n`lit-html` instance this component renders with. Unset (the default) keeps the built-in ▼."
-            },
-            {
-              "kind": "field",
-              "name": "nestedIcon",
-              "type": {
-                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
-              },
-              "static": true,
-              "description": "Global override for a submenu trigger's caret — the counterpart to icon for a\n`<use-caret>` nested inside a `use-menu`. Unset (the default) keeps the built-in ▶."
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-caret",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseCaret",
-          "declaration": {
-            "name": "UseCaret",
-            "module": "src/elements/use-caret/use-caret.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-caret",
-          "declaration": {
-            "name": "UseCaret",
-            "module": "src/elements/use-caret/use-caret.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-date-picker/use-date-picker.ts",
@@ -2748,6 +2748,185 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-intl-number/use-intl-number.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Displays a localized, human-readable representation of a number using\n[`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).\nRenders a semantic `<data>` element in its shadow root with a machine-readable\n`value` attribute and formatted inner text.\n\nSet `numberstyle` to control what kind of number is formatted (see\n[`style`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#style)):\n- `decimal` (default) → plain number, e.g. `1,234.5`\n- `percent` → percentage, e.g. `42%` (value is the fraction, so `0.42` renders `42%`)\n- `currency` → currency amount, requires `currency`\n- `unit` → measurement, requires `unit`\n\nLocale is resolved from the nearest ancestor `[lang]` attribute, or\n`navigator.language` if none is found. Set `lang` directly on the element to override.",
+          "name": "UseIntlNumber",
+          "members": [
+            {
+              "kind": "field",
+              "name": "value",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "value"
+            },
+            {
+              "kind": "field",
+              "name": "numberstyle",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "numberstyle"
+            },
+            {
+              "kind": "field",
+              "name": "currency",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "currency"
+            },
+            {
+              "kind": "field",
+              "name": "currencydisplay",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "currencydisplay"
+            },
+            {
+              "kind": "field",
+              "name": "currencysign",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "currencysign"
+            },
+            {
+              "kind": "field",
+              "name": "unit",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "unit"
+            },
+            {
+              "kind": "field",
+              "name": "unitdisplay",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "unitdisplay"
+            },
+            {
+              "kind": "field",
+              "name": "signdisplay",
+              "type": {
+                "text": "string | undefined"
+              },
+              "attribute": "signdisplay"
+            }
+          ],
+          "attributes": [
+            {
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Numeric amount to format",
+              "name": "value",
+              "fieldName": "value"
+            },
+            {
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Format style: `decimal` | `percent` | `currency` | `unit`",
+              "name": "numberstyle",
+              "fieldName": "numberstyle"
+            },
+            {
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "[ISO 4217 currency code](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currency), e.g. `USD`, `EUR`, `JPY`. Required when numberstyle is `currency`",
+              "name": "currency",
+              "fieldName": "currency"
+            },
+            {
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "[How the currency is denoted](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencydisplay): `symbol` | `narrowSymbol` | `code` | `name`",
+              "name": "currencydisplay",
+              "fieldName": "currencydisplay"
+            },
+            {
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "[Sign convention](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencysign): `standard` (minus sign) | `accounting` (parenthesized negatives)",
+              "name": "currencysign",
+              "fieldName": "currencysign"
+            },
+            {
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "[Unit identifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unit), e.g. `kilometer-per-hour`, `liter`. Required when numberstyle is `unit`",
+              "name": "unit",
+              "fieldName": "unit"
+            },
+            {
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "[How the unit is denoted](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unitdisplay): `short` | `narrow` | `long`",
+              "name": "unitdisplay",
+              "fieldName": "unitdisplay"
+            },
+            {
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "[When to show the sign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#signdisplay): `auto` | `always` | `exceptZero` | `never`",
+              "name": "signdisplay",
+              "fieldName": "signdisplay"
+            },
+            {
+              "name": "lang",
+              "type": {
+                "text": "string"
+              },
+              "fieldName": "lang",
+              "description": "BCP 47 locale tag. Inherits from nearest ancestor `[lang]` if not set.",
+              "inheritedFrom": {
+                "name": "UseLocaleElement",
+                "module": "src/elements/use-locale-element/use-locale-element.ts"
+              }
+            }
+          ],
+          "superclass": {
+            "name": "UseLocaleElement",
+            "module": "/src/elements/use-locale-element/use-locale-element"
+          },
+          "tagName": "use-intl-number",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseIntlNumber",
+          "declaration": {
+            "name": "UseIntlNumber",
+            "module": "src/elements/use-intl-number/use-intl-number.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-intl-number",
+          "declaration": {
+            "name": "UseIntlNumber",
+            "module": "src/elements/use-intl-number/use-intl-number.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-listbox-input/use-listbox-input.ts",

package/dist/design-system.css

@@ -1241,3 +1241,313 @@
   }
 }
 
+/* Grid — a cell holding a use-intl-number reads as tabular data, so it defaults to end-aligned
+   text with tabular-nums, which locks every digit to the same width so values stack and compare
+   cleanly down a column. text-align and font-variant-numeric are both inherited, so setting them
+   on use-gridcell reaches the formatted text inside use-intl-number's shadow root without needing
+   a rule scoped to use-intl-number itself. */
+@layer use-theme.grid {
+  use-gridcell:has(use-intl-number) {
+    text-align: end;
+    font-variant-numeric: tabular-nums;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+
+/* Card — `use-card` is a theme-only tag, styled like `use-field`/`use-selector` with no
+   registration behind it: an author can still add `role`/ARIA directly on `<use-card>` for real
+   semantics, the same as any other element, just not for free the way `<article>`/`<section>`
+   give an implicit landmark. It supplies the surface chrome (background/border/radius/shadow);
+   `shell.css` (declared later, so it wins on `display`) makes it a flex column, and
+   `surface.css` styles its header/footer/figure regions. `.outlined` drops the shadow and keeps
+   the border, for a flatter, less "floating" card. */
+@layer use-theme.card {
+  use-card {
+    display: block;
+    overflow: hidden;
+    background: var(--usewc-color-surface-background);
+    border: var(--usewc-layout-surface-border) solid var(--usewc-color-surface-border);
+    border-radius: var(--usewc-effect-surface-border-radius);
+    box-shadow: var(--usewc-effect-surface-shadow);
+    color: var(--usewc-color-document-text);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-card.outlined {
+    box-shadow: none;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+
+/* Dialog — a native `<dialog>` already provides the overlay mechanics (top-layer promotion,
+   `::backdrop`, focus trapping, Esc-to-close) for free once shown with `.showModal()`. Themed by
+   default, like the rest of this family's native elements — `:not(.appearance-native)` is the
+   escape hatch, not an opt-in class. The default look centers (the UA default for `<dialog>`, so
+   no extra positioning is needed) and constrains its size; `.drawer` is the one variant that
+   needs an opt-in class, since it pins to a block-size-100dvh edge panel instead — the positioning
+   itself, not just the chrome, changes. That's what makes `use-shell-fill` (see `shell.css`)
+   matter for a drawer specifically — the body scrolls while header/footer stay put. */
+@layer use-theme.dialog {
+  dialog:not(.appearance-native) {
+    padding: 0;
+    overflow: hidden;
+    border: var(--usewc-layout-surface-border) solid var(--usewc-color-surface-border);
+    border-radius: var(--usewc-effect-surface-border-radius);
+    background: var(--usewc-color-surface-background);
+    box-shadow: var(--usewc-effect-surface-shadow);
+    color: var(--usewc-color-document-text);
+    inline-size: min(32rem, 100% - var(--usewc-space-surface-padding) * 2);
+    max-block-size: min(80dvh, 100% - var(--usewc-space-surface-padding) * 2);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  dialog:not(.appearance-native)::backdrop {
+    background: var(--usewc-color-surface-backdrop);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* inset-inline-start: auto resets the UA stylesheet's own `dialog:modal { inset: 0 }` (all
+     four sides, not just block) — without it, left/start stays pinned at 0 alongside our
+     inset-inline-end: 0 and an explicit inline-size, which is over-constrained: the browser
+     drops the property that conflicts with the direction-implied one (inset-inline-start in
+     LTR), pinning the drawer to the start edge instead of the end edge it's meant to sit on. */
+  dialog.drawer:not(.appearance-native) {
+    position: fixed;
+    inset-block: 0;
+    inset-inline-start: auto;
+    inset-inline-end: 0;
+    margin: 0;
+    max-block-size: none;
+    block-size: 100dvh;
+    inline-size: min(24rem, 100%);
+    border-radius: 0;
+    border-block: none;
+    border-inline-end: none;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+
+/* Popover — a native `[popover]` element already provides the overlay mechanics (top-layer
+   promotion, light-dismiss, `::backdrop`) for free. Themed by default, like the rest of this
+   family's native elements — `:not(.appearance-native)` is the escape hatch, matching
+   `input.css`/`select.css`'s convention, not an opt-in class like `dialog.drawer` (a `<dialog>`
+   needs a class for that one variant since plain and drawer dialogs share one tag; `[popover]`
+   is already a specific enough signal on its own). Anchor positioning (`anchor-name`/
+   `position-anchor`) is left to the author, the same way plain `[popover]` elements work
+   otherwise — this only replaces the UA default chrome with the shared `surface` tokens,
+   matching `dialog`/`use-card`.
+
+   `:not(use-menu)` excludes the one component that self-applies `popover="auto"` and ships its
+   own distinct chrome in `menu.css`: cascade layers always beat specificity, so without this
+   exclusion `use-menu:popover-open`'s more specific rule would still lose to this layer, which
+   is declared later. */
+@layer use-theme.popover {
+  [popover]:not(use-menu, .appearance-native) {
+    margin: 0;
+    padding: 0;
+    overflow: hidden;
+    border: var(--usewc-layout-surface-border) solid var(--usewc-color-surface-border);
+    border-radius: var(--usewc-effect-surface-border-radius);
+    background: var(--usewc-color-surface-background);
+    box-shadow: var(--usewc-effect-surface-shadow);
+    color: var(--usewc-color-document-text);
+    max-inline-size: min(24rem, 100% - var(--usewc-space-surface-padding) * 2);
+    max-block-size: min(80dvh, 100% - var(--usewc-space-surface-padding) * 2);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  [popover]:not(use-menu, .appearance-native)::backdrop {
+    background: var(--usewc-color-surface-backdrop);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+
+/* Shell — `use-shell` is a theme-only tag (no registration, styled by tag name like
+   `use-field`/`use-selector`/`use-card`) providing a generic flex-column-with-one-growing-region
+   mechanic, usable anywhere in an app that wants it — not specific to card/dialog/popover
+   surfaces. Every direct child defaults to `flex: 0 0 auto` (fixed, doesn't grow or shrink) and
+   `min-block-size: 0`; `use-shell-fill` is the one region that grows to fill the remaining
+   space and scrolls its own overflow, wherever it appears.
+
+   The three surface hosts (`dialog`, `use-card`, `[popover]`) participate in the same mechanic
+   directly — no `use-shell` wrapper needed inside them — since they're already the flex
+   container an author nests header/use-shell-fill/footer straight into. This layer is declared
+   after `card.css`/`dialog.css`/`popover.css`, so its `display: flex` wins over their own
+   `display: block` for `use-card` (dialog/popover don't set `display` themselves, so there's
+   nothing to override there).
+
+   `dialog` and `[popover]` are scoped to `:modal`/`:popover-open` here, unlike the chrome rules
+   in `dialog.css`/`popover.css` — a closed `<dialog>`/`[popover]` is `display: none` by the UA
+   stylesheet, and normal-importance author CSS always beats normal-importance UA CSS regardless
+   of layers, so an unconditional `display: flex` here would un-hide a closed one. Chrome
+   properties (background/border/shadow/sizing) don't have this problem — they're inert on a
+   `display: none` element either way — only `display` itself does. */
+@layer use-theme.shell {
+  use-shell,
+  dialog:modal:not(.appearance-native),
+  use-card,
+  [popover]:popover-open:not(use-menu, .appearance-native) {
+    display: flex;
+    flex-direction: column;
+    min-block-size: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-shell > :not(use-shell-fill),
+  dialog:modal:not(.appearance-native) > :not(use-shell-fill),
+  use-card > :not(use-shell-fill),
+  [popover]:popover-open:not(use-menu, .appearance-native) > :not(use-shell-fill) {
+    flex: 0 0 auto;
+    min-block-size: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-shell-fill {
+    display: block;
+    flex: 1 1 auto;
+    min-block-size: 0;
+    overflow: auto;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+
+/* Surface regions — header/poster/footer styling shared by the three surface hosts (`dialog`,
+   `use-card`, `[popover]`), scoped to them specifically rather than to bare `use-shell`: this is
+   a surface-family visual convention (avatar sizing, trailing-action pinning, a footer rule),
+   not something every generic `use-shell` consumer elsewhere in the app should inherit.
+   Everything here rides on top of `shell.css`'s flex mechanic — this only adds padding, gaps,
+   and per-region treatment. */
+@layer use-theme.surface {
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > figure {
+    margin: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > figure > img {
+    display: block;
+    inline-size: 100%;
+    block-size: auto;
+    object-fit: cover;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > header {
+    display: flex;
+    align-items: center;
+    gap: var(--usewc-space-surface-gap);
+    padding: var(--usewc-space-surface-padding);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > header > img.avatar {
+    flex: none;
+    inline-size: var(--usewc-layout-surface-avatar-size);
+    block-size: var(--usewc-layout-surface-avatar-size);
+    border-radius: var(--usewc-effect-surface-avatar-border-radius);
+    object-fit: cover;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > header > hgroup {
+    flex: 1;
+    min-inline-size: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native))
+    > header
+    > *:last-child:not(:first-child) {
+    margin-inline-start: auto;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > use-shell-fill {
+    padding: var(--usewc-space-surface-padding);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > header + use-shell-fill {
+    padding-block-start: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > footer {
+    display: flex;
+    align-items: center;
+    gap: var(--usewc-space-surface-gap);
+    padding: var(--usewc-space-surface-padding);
+    border-block-start: var(--usewc-layout-surface-border) solid var(--usewc-color-surface-footer-border);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native))
+    > footer
+    > *:last-child:not(:first-child) {
+    margin-inline-start: auto;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+

package/dist/docs/use-intl-number.md

@@ -0,0 +1,30 @@
+# `use-intl-number`
+
+Displays a localized, human-readable representation of a number using
+[`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
+Renders a semantic `<data>` element in its shadow root with a machine-readable
+`value` attribute and formatted inner text.
+
+Set `numberstyle` to control what kind of number is formatted (see
+[`style`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#style)):
+- `decimal` (default) → plain number, e.g. `1,234.5`
+- `percent` → percentage, e.g. `42%` (value is the fraction, so `0.42` renders `42%`)
+- `currency` → currency amount, requires `currency`
+- `unit` → measurement, requires `unit`
+
+Locale is resolved from the nearest ancestor `[lang]` attribute, or
+`navigator.language` if none is found. Set `lang` directly on the element to override.
+
+## Attributes
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | `string \| undefined` | - | Numeric amount to format |
+| numberstyle | `string \| undefined` | - | Format style: `decimal` \| `percent` \| `currency` \| `unit` |
+| currency | `string \| undefined` | - | [ISO 4217 currency code](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currency), e.g. `USD`, `EUR`, `JPY`. Required when numberstyle is `currency` |
+| currencydisplay | `string \| undefined` | - | [How the currency is denoted](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencydisplay): `symbol` \| `narrowSymbol` \| `code` \| `name` |
+| currencysign | `string \| undefined` | - | [Sign convention](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencysign): `standard` (minus sign) \| `accounting` (parenthesized negatives) |
+| unit | `string \| undefined` | - | [Unit identifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unit), e.g. `kilometer-per-hour`, `liter`. Required when numberstyle is `unit` |
+| unitdisplay | `string \| undefined` | - | [How the unit is denoted](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unitdisplay): `short` \| `narrow` \| `long` |
+| signdisplay | `string \| undefined` | - | [When to show the sign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#signdisplay): `auto` \| `always` \| `exceptZero` \| `never` |
+| lang | `string` | - | BCP 47 locale tag. Inherits from nearest ancestor `[lang]` if not set. |

package/dist/tokens.css

@@ -119,6 +119,7 @@
   --usewc-effect-border-radius-8: 0.5rem;
   --usewc-effect-border-radius-full: 100%;
   --usewc-effect-border-radius-pill: 9999px;
+  --usewc-effect-shadow-raised: 0 1px 2px oklch(0% 0 0 / 0.06), 0 4px 12px oklch(0% 0 0 / 0.1);
 
   /**
    * Icon
@@ -576,6 +577,22 @@
   --usewc-color-code-background: oklch(from var(--usewc-color-red-600) l c h / 0.125);
   --usewc-color-code-border: var(--usewc-color-transparent);
   --usewc-font-code-size: var(--usewc-font-size-14);
+
+  /* Surface — shared by every surface host (dialog, use-card, [popover]): the visible chrome
+     (background/border/radius/shadow), the backdrop behind an overlaid one, and the internal
+     header/poster/footer region layout they all apply the same way. */
+  --usewc-color-surface-background: var(--usewc-color-canvas-background);
+  --usewc-color-surface-border: var(--usewc-color-button-base-border-static);
+  --usewc-color-surface-backdrop: oklch(0% 0 0 / 0.4);
+  --usewc-layout-surface-border: var(--usewc-space-1);
+  --usewc-effect-surface-border-radius: var(--usewc-effect-border-radius-8);
+  --usewc-effect-surface-shadow: var(--usewc-effect-shadow-raised);
+  --usewc-effect-surface-transition-duration: 200ms;
+  --usewc-space-surface-padding: var(--usewc-space-16);
+  --usewc-space-surface-gap: var(--usewc-space-12);
+  --usewc-layout-surface-avatar-size: var(--usewc-space-32);
+  --usewc-effect-surface-avatar-border-radius: var(--usewc-effect-border-radius-full);
+  --usewc-color-surface-footer-border: var(--usewc-color-surface-border);
 }
 
 @media (prefers-color-scheme: dark) {
@@ -661,6 +678,7 @@
     --usewc-color-selector-background-hover: oklch(from var(--usewc-color-gray-700) l c h / 0.5);
     --usewc-effect-select-trigger-background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 16L5.0718 8.5L18.9282 8.5L12 16Z' fill='rgb(229,231,235)' /%3E%3C/svg%3E");
     --usewc-effect-menu-item-checkmark-background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M5 13L10 18L19 7' stroke='rgb(229,231,235)' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3C%2Fsvg%3E");
+    --usewc-color-surface-backdrop: oklch(0% 0 0 / 0.6);
   }
 }
 

package/dist/use-wc.d.mts

@@ -1406,6 +1406,52 @@ declare global {
   }
 }
 //#endregion
+//#region src/elements/use-intl-number/use-intl-number.d.ts
+/**
+ * Displays a localized, human-readable representation of a number using
+ * [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
+ * Renders a semantic `<data>` element in its shadow root with a machine-readable
+ * `value` attribute and formatted inner text.
+ *
+ * Set `numberstyle` to control what kind of number is formatted (see
+ * [`style`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#style)):
+ * - `decimal` (default) → plain number, e.g. `1,234.5`
+ * - `percent` → percentage, e.g. `42%` (value is the fraction, so `0.42` renders `42%`)
+ * - `currency` → currency amount, requires `currency`
+ * - `unit` → measurement, requires `unit`
+ *
+ * Locale is resolved from the nearest ancestor `[lang]` attribute, or
+ * `navigator.language` if none is found. Set `lang` directly on the element to override.
+ *
+ * @attr {string} value - Numeric amount to format
+ * @attr {string} numberstyle - Format style: `decimal` | `percent` | `currency` | `unit`
+ * @attr {string} currency - [ISO 4217 currency code](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currency), e.g. `USD`, `EUR`, `JPY`. Required when numberstyle is `currency`
+ * @attr {string} currencydisplay - [How the currency is denoted](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencydisplay): `symbol` | `narrowSymbol` | `code` | `name`
+ * @attr {string} currencysign - [Sign convention](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencysign): `standard` (minus sign) | `accounting` (parenthesized negatives)
+ * @attr {string} unit - [Unit identifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unit), e.g. `kilometer-per-hour`, `liter`. Required when numberstyle is `unit`
+ * @attr {string} unitdisplay - [How the unit is denoted](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unitdisplay): `short` | `narrow` | `long`
+ * @attr {string} signdisplay - [When to show the sign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#signdisplay): `auto` | `always` | `exceptZero` | `never`
+ * @attr {string} lang - BCP 47 locale tag. Inherits from nearest ancestor `[lang]` if not set.
+ */
+declare class UseIntlNumber extends UseLocaleElement {
+  #private;
+  static styles: import("lit").CSSResult;
+  value?: string;
+  numberstyle?: string;
+  currency?: string;
+  currencydisplay?: string;
+  currencysign?: string;
+  unit?: string;
+  unitdisplay?: string;
+  signdisplay?: string;
+  render(): TemplateResult$1<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "use-intl-number": UseIntlNumber;
+  }
+}
+//#endregion
 //#region src/elements/use-badge/use-badge.d.ts
 /**
  * `use-badge` renders a small indicator anchored to another element's corner, using
@@ -1508,4 +1554,4 @@ declare global {
   }
 }
 //#endregion
-export { UseAnchored, UseBadge, UseCalendarBase, UseCalendarRenderDay, UseCaret, UseDateInput, UseDatePicker, UseDatetimeInput, UseDurationInput, UseFocusgroup, UseIntlDatetime, UseListboxInput, UseMenu, UseMonthPicker, UseMonthPickerRenderMonth, UseOption, UseScrollarea, UseTimeInput, UseTree, UseTreeitem, UseWeekPicker, UseWidget };
+export { UseAnchored, 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

@@ -4290,6 +4290,112 @@ __decorate([property({ type: String })], UseIntlDatetime.prototype, "datestyle",
 __decorate([property({ type: String })], UseIntlDatetime.prototype, "timestyle", void 0);
 UseIntlDatetime = __decorate([customElement("use-intl-datetime")], UseIntlDatetime);
 //#endregion
+//#region src/elements/use-intl-number/use-intl-number.ts
+const NUMBER_STYLES = [
+	"decimal",
+	"percent",
+	"currency",
+	"unit"
+];
+const CURRENCY_DISPLAYS = [
+	"symbol",
+	"narrowSymbol",
+	"code",
+	"name"
+];
+const CURRENCY_SIGNS = ["standard", "accounting"];
+const SIGN_DISPLAYS = [
+	"auto",
+	"always",
+	"exceptZero",
+	"never"
+];
+const UNIT_DISPLAYS = [
+	"short",
+	"narrow",
+	"long"
+];
+let UseIntlNumber = class UseIntlNumber extends UseLocaleElement {
+	static {
+		this.styles = css`
+    :host {
+      display: contents;
+    }
+  `;
+	}
+	#resolveNumberStyle() {
+		return NUMBER_STYLES.includes(this.numberstyle) ? this.numberstyle : "decimal";
+	}
+	#resolveCurrencyDisplay() {
+		return CURRENCY_DISPLAYS.includes(this.currencydisplay) ? this.currencydisplay : "symbol";
+	}
+	#resolveCurrencySign() {
+		return CURRENCY_SIGNS.includes(this.currencysign) ? this.currencysign : "standard";
+	}
+	#resolveUnitDisplay() {
+		return UNIT_DISPLAYS.includes(this.unitdisplay) ? this.unitdisplay : "short";
+	}
+	#resolveSignDisplay() {
+		return SIGN_DISPLAYS.includes(this.signdisplay) ? this.signdisplay : "auto";
+	}
+	#resolveOptions(style) {
+		if (style === "currency") {
+			if (!this.currency) return null;
+			return {
+				style,
+				currency: this.currency,
+				currencyDisplay: this.#resolveCurrencyDisplay(),
+				currencySign: this.#resolveCurrencySign(),
+				signDisplay: this.#resolveSignDisplay()
+			};
+		}
+		if (style === "unit") {
+			if (!this.unit) return null;
+			return {
+				style,
+				unit: this.unit,
+				unitDisplay: this.#resolveUnitDisplay(),
+				signDisplay: this.#resolveSignDisplay()
+			};
+		}
+		return {
+			style,
+			signDisplay: this.#resolveSignDisplay()
+		};
+	}
+	#computeFormatted() {
+		const value = this.value ?? "";
+		const locale = this.lang;
+		if (!value || value.trim() === "") return null;
+		const amount = Number(value);
+		if (isNaN(amount)) return null;
+		const options = this.#resolveOptions(this.#resolveNumberStyle());
+		if (!options) return null;
+		try {
+			return {
+				valueAttr: String(amount),
+				text: new Intl.NumberFormat(locale, options).format(amount)
+			};
+		} catch {
+			return null;
+		}
+	}
+	render() {
+		const result = this.#computeFormatted();
+		if (!result) return html`<data></data>`;
+		return html`<data value=${result.valueAttr}>${result.text}</data>`;
+	}
+};
+__decorate([property({ type: String })], UseIntlNumber.prototype, "value", void 0);
+__decorate([property({ type: String })], UseIntlNumber.prototype, "numberstyle", void 0);
+__decorate([property({ type: String })], UseIntlNumber.prototype, "currency", void 0);
+__decorate([property({ type: String })], UseIntlNumber.prototype, "currencydisplay", void 0);
+__decorate([property({ type: String })], UseIntlNumber.prototype, "currencysign", void 0);
+__decorate([property({ type: String })], UseIntlNumber.prototype, "unit", void 0);
+__decorate([property({ type: String })], UseIntlNumber.prototype, "unitdisplay", void 0);
+__decorate([property({ type: String })], UseIntlNumber.prototype, "signdisplay", void 0);
+UseIntlNumber = __decorate([customElement("use-intl-number")], UseIntlNumber);
+//#endregion
 //#region src/elements/use-badge/use-badge.ts
 let UseBadge = class UseBadge extends LitElement {
 	#internals;
@@ -4446,4 +4552,4 @@ __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, UseListboxInput, UseMenu, UseMonthPicker, UseOption, UseScrollarea, UseTimeInput, UseTree, UseTreeitem, UseWeekPicker, UseWidget };
+export { UseAnchored, 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.57",
+  "version": "1.0.0-pre.59",
   "private": false,
   "homepage": "https://usewc.com",
   "bugs": "https://github.com/dang-rabbits/use-wc/issues",

package/vscode.html-custom-data.json

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