use-wc 1.0.0-pre.56 → 1.0.0-pre.58

package/custom-elements.json

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

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

@@ -548,15 +548,15 @@
   --usewc-layout-popover-menu-item-padding-block: var(--usewc-space-2);
   --usewc-layout-popover-menu-item-line-height: var(--usewc-line-height-24);
   --usewc-color-popover-menu-item-background-static: var(--usewc-color-transparent);
-  --usewc-color-popover-menu-item-background-hover: var(--usewc-color-gray-800);
-  --usewc-color-popover-menu-item-background-active: var(--usewc-color-gray-800);
+  --usewc-color-popover-menu-item-background-hover: var(--usewc-color-selector-background-hover);
+  --usewc-color-popover-menu-item-background-active: var(--usewc-color-selector-background-hover);
   --usewc-effect-popover-menu-item-border-radius: var(--usewc-effect-border-radius-4);
   --usewc-layout-popover-menu-anchor-offset: var(--usewc-space-4);
   --usewc-layout-popover-menu-padding: var(--usewc-space-4);
   --usewc-layout-popover-menu-border: var(--usewc-space-1-relative);
   --usewc-effect-popover-menu-border-style: var(--usewc-effect-border-solid);
   --usewc-color-popover-menu-background: var(--usewc-color-canvas-background);
-  --usewc-color-popover-menu-border: var(--usewc-color-gray-600);
+  --usewc-color-popover-menu-border: var(--usewc-color-button-base-border-static);
   --usewc-effect-popover-menu-border-radius: var(--usewc-effect-border-radius-8);
   --usewc-font-popover-menu-header-size: var(--usewc-font-size-14);
   --usewc-font-popover-menu-header-weight: var(--usewc-font-weight-medium);

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.56",
+  "version": "1.0.0-pre.58",
   "private": false,
   "homepage": "https://usewc.com",
   "bugs": "https://github.com/dang-rabbits/use-wc/issues",

package/vscode.html-custom-data.json

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