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

package/custom-elements.json

@@ -89,6 +89,76 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-avatar/use-avatar.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.",
+          "name": "UseAvatar",
+          "cssParts": [
+            {
+              "description": "The span that renders the `name` fallback.",
+              "name": "initials"
+            }
+          ],
+          "slots": [
+            {
+              "description": "The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "attribute": "name",
+              "reflects": true
+            }
+          ],
+          "attributes": [
+            {
+              "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "fieldName": "name"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-avatar",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseAvatar",
+          "declaration": {
+            "name": "UseAvatar",
+            "module": "src/elements/use-avatar/use-avatar.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-avatar",
+          "declaration": {
+            "name": "UseAvatar",
+            "module": "src/elements/use-avatar/use-avatar.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-badge/use-badge.ts",
@@ -232,76 +302,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-avatar/use-avatar.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "`use-avatar` renders a small, fixed-size, clipped container for a person or entity's\nlikeness. Slot in an `<img>` (or `<picture>`) for a photo, an inline `<svg>` for a\ngenerated or stylized mark, or arbitrary markup (a `<div>` of initials, a calendar badge);\nwhatever is slotted is centered and clipped to the avatar's shape. With nothing slotted,\n`use-avatar` falls back to initials derived from the `name` attribute.\n\n```html\n<use-avatar><img src=\"ada.jpg\" alt=\"\" /></use-avatar>\n<use-avatar name=\"Riley Quinn\"></use-avatar>\n<use-avatar><svg viewBox=\"0 0 32 32\">…</svg></use-avatar>\n```\n\nSize it with plain CSS — `inline-size` for the size and `aspect-ratio` for the proportions —\nfrom a stylesheet, a style attribute, or the design system's theme layer. The element takes no\ncustom properties of its own: it is a query container, so the initials scale from whatever box\nit ends up with. A non-square `aspect-ratio` suits a wide thumbnail or poster.\n\nThe element clips its content but gives it no shape of its own — that is the theme's, through\nthe affordance classes it defines: `.circle` (the themed default), `.square`, `.squircle` in\n`theme/avatar.css`. A circle only reads right at a `1` ratio, so a wide avatar wants one of the\nothers.\n\nThe element takes no ARIA role of its own. A slotted `<img>` carries its own `alt`, and the\ninitials fallback is plain text in the accessibility tree — an avatar is decorative beside a\nname far more often than it is the name itself, so labelling it here would mean announcing\nthat name twice.",
-          "name": "UseAvatar",
-          "cssParts": [
-            {
-              "description": "The span that renders the `name` fallback.",
-              "name": "initials"
-            }
-          ],
-          "slots": [
-            {
-              "description": "The avatar's content: an `<img>`/`<picture>`, an `<svg>`, or arbitrary markup. Left empty, the `name` attribute's initials are shown instead, as the slot's own fallback. A photo fills the frame and crops; anything else keeps its own size, capped at the frame. Give an `<svg>` a `width`/`height` — without one it defaults to filling the box, and a rounded shape will clip its corners.",
-              "name": ""
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "attribute": "name",
-              "reflects": true
-            }
-          ],
-          "attributes": [
-            {
-              "description": "The full name, used for the initials fallback (first + last whitespace-separated token, uppercased) when the slot is empty.",
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "fieldName": "name"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-avatar",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseAvatar",
-          "declaration": {
-            "name": "UseAvatar",
-            "module": "src/elements/use-avatar/use-avatar.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-avatar",
-          "declaration": {
-            "name": "UseAvatar",
-            "module": "src/elements/use-avatar/use-avatar.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-calendar-base/use-calendar-base.ts",
@@ -772,6 +772,71 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-caret/use-caret.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`use-caret` supplies the caret icon and label layout for a consumer who wants to own the\ninvoking button itself. It renders inside a plain `<button>`\nthat carries the native `popovertarget` attribute, pointing at a `use-menu`:\n\n```html\n<button id=\"thing\" popovertarget=\"thing-menu\">\n  <use-caret>Menu</use-caret>\n</button>\n<use-menu id=\"thing-menu\" aria-label=\"Menu\">\n  <button role=\"menuitem\">First thing</button>\n</use-menu>\n```\n\n`use-menu` finds this button on its own via `popovertarget` and anchors to it — no\n`anchortarget` needed here; that's only for a menu with more than one invoker. See `use-menu`'s\nown docs for that case.\n\nThe button is entirely the consumer's own element — their classes, their content, their event\nhandlers. `use-caret` contributes no interactivity of its own: no internal button, no focus\ntarget, no state. It only renders the label and caret glyph, so consumers get a consistent\nvisual trigger without giving up control of the button.\n\nThe caret direction is derived rather than configured: a trigger nested inside a `use-menu`\nis understood to open a submenu and renders pointing sideways; a top-level trigger renders\npointing down.\n\nSwapping in a different caret **per instance** is a slot: put your own element in the `icon`\nslot and it replaces `part(icon-default)` entirely for that trigger.\n\nSwapping the default caret **for every trigger in the app** doesn't need touching this\ncomponent's `render()` at all — style `::part(icon-default)` from an outside stylesheet, the\nsame way any shadow DOM part is themed:\n\n```css\nuse-caret::part(icon-default) {\n  mask-image: url(\"/icons/my-caret.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a token —\n`--usewc-effect-dropdown-trigger-icon-mask-image` — so redefining that custom property has\nthe same effect without writing a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static `icon`\nand `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing\nthe same tag, no new element to register or remember to use instead. `icon` supplies a\ntop-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one\nkeeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry\npoint, before any triggers connect) — Lit calls `render()` fresh on every update, so an\nalready-connected instance only reflects the change once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger of that kind:\nUseCaret.icon = \"▾\";\nUseCaret.nestedIcon = \"▸\";\n\n// A function is called on every render instead:\nUseCaret.nestedIcon = (html) => html`<my-icon name=\"chevron-right\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nOnly need to change the icon on **some** triggers, not every one in the app? Extend the\nclass, override `render()` normally, and register the subclass under a different tag name so\nit coexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyCaret extends UseCaret {\n  override render() {\n    return html`<slot></slot><slot name=\"icon\"><my-icon name=\"chevron\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-caret\", MyCaret);\n```",
+          "name": "UseCaret",
+          "slots": [
+            {
+              "description": "Trigger label content.",
+              "name": "default"
+            },
+            {
+              "description": "Replaces the default caret glyph.",
+              "name": "icon"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "icon",
+              "type": {
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
+              },
+              "static": true,
+              "description": "Global override for a top-level trigger's caret. When set, every non-nested `<use-caret>` in\nthe page renders this inside `part(icon-default)` instead of the built-in ▼ character. A\nplain string or `TemplateResult` is used as-is; the function form is called with the\ncomponent's own `html` tag, so a returned template is guaranteed to come from the same\n`lit-html` instance this component renders with. Unset (the default) keeps the built-in ▼."
+            },
+            {
+              "kind": "field",
+              "name": "nestedIcon",
+              "type": {
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
+              },
+              "static": true,
+              "description": "Global override for a submenu trigger's caret — the counterpart to icon for a\n`<use-caret>` nested inside a `use-menu`. Unset (the default) keeps the built-in ▶."
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-caret",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseCaret",
+          "declaration": {
+            "name": "UseCaret",
+            "module": "src/elements/use-caret/use-caret.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-caret",
+          "declaration": {
+            "name": "UseCaret",
+            "module": "src/elements/use-caret/use-caret.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-date-input/use-date-input.ts",
@@ -898,71 +963,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-caret/use-caret.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "`use-caret` supplies the caret icon and label layout for a consumer who wants to own the\ninvoking button itself. It renders inside a plain `<button>`\nthat carries the native `popovertarget` attribute, pointing at a `use-menu`:\n\n```html\n<button id=\"thing\" popovertarget=\"thing-menu\">\n  <use-caret>Menu</use-caret>\n</button>\n<use-menu id=\"thing-menu\" aria-label=\"Menu\">\n  <button role=\"menuitem\">First thing</button>\n</use-menu>\n```\n\n`use-menu` finds this button on its own via `popovertarget` and anchors to it — no\n`anchortarget` needed here; that's only for a menu with more than one invoker. See `use-menu`'s\nown docs for that case.\n\nThe button is entirely the consumer's own element — their classes, their content, their event\nhandlers. `use-caret` contributes no interactivity of its own: no internal button, no focus\ntarget, no state. It only renders the label and caret glyph, so consumers get a consistent\nvisual trigger without giving up control of the button.\n\nThe caret direction is derived rather than configured: a trigger nested inside a `use-menu`\nis understood to open a submenu and renders pointing sideways; a top-level trigger renders\npointing down.\n\nSwapping in a different caret **per instance** is a slot: put your own element in the `icon`\nslot and it replaces `part(icon-default)` entirely for that trigger.\n\nSwapping the default caret **for every trigger in the app** doesn't need touching this\ncomponent's `render()` at all — style `::part(icon-default)` from an outside stylesheet, the\nsame way any shadow DOM part is themed:\n\n```css\nuse-caret::part(icon-default) {\n  mask-image: url(\"/icons/my-caret.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a token —\n`--usewc-effect-dropdown-trigger-icon-mask-image` — so redefining that custom property has\nthe same effect without writing a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static `icon`\nand `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing\nthe same tag, no new element to register or remember to use instead. `icon` supplies a\ntop-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one\nkeeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry\npoint, before any triggers connect) — Lit calls `render()` fresh on every update, so an\nalready-connected instance only reflects the change once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger of that kind:\nUseCaret.icon = \"▾\";\nUseCaret.nestedIcon = \"▸\";\n\n// A function is called on every render instead:\nUseCaret.nestedIcon = (html) => html`<my-icon name=\"chevron-right\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nOnly need to change the icon on **some** triggers, not every one in the app? Extend the\nclass, override `render()` normally, and register the subclass under a different tag name so\nit coexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyCaret extends UseCaret {\n  override render() {\n    return html`<slot></slot><slot name=\"icon\"><my-icon name=\"chevron\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-caret\", MyCaret);\n```",
-          "name": "UseCaret",
-          "slots": [
-            {
-              "description": "Trigger label content.",
-              "name": "default"
-            },
-            {
-              "description": "Replaces the default caret glyph.",
-              "name": "icon"
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "icon",
-              "type": {
-                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
-              },
-              "static": true,
-              "description": "Global override for a top-level trigger's caret. When set, every non-nested `<use-caret>` in\nthe page renders this inside `part(icon-default)` instead of the built-in ▼ character. A\nplain string or `TemplateResult` is used as-is; the function form is called with the\ncomponent's own `html` tag, so a returned template is guaranteed to come from the same\n`lit-html` instance this component renders with. Unset (the default) keeps the built-in ▼."
-            },
-            {
-              "kind": "field",
-              "name": "nestedIcon",
-              "type": {
-                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
-              },
-              "static": true,
-              "description": "Global override for a submenu trigger's caret — the counterpart to icon for a\n`<use-caret>` nested inside a `use-menu`. Unset (the default) keeps the built-in ▶."
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-caret",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseCaret",
-          "declaration": {
-            "name": "UseCaret",
-            "module": "src/elements/use-caret/use-caret.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-caret",
-          "declaration": {
-            "name": "UseCaret",
-            "module": "src/elements/use-caret/use-caret.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-date-picker/use-date-picker.ts",
@@ -3667,6 +3667,63 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-scrollarea/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseScrollarea",
+          "declaration": {
+            "name": "UseScrollarea",
+            "module": "./use-scrollarea"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/elements/use-scrollarea/use-scrollarea.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A scroll container that exposes custom states for scroll edge detection.\n\n## Custom States\nThe following CSS custom states are available for styling:\n\n- `:state(at-block-start)` — scrolled to the block-start edge (top in horizontal writing modes)\n- `:state(at-block-end)` — scrolled to the block-end edge (bottom in horizontal writing modes)\n- `:state(at-inline-start)` — scrolled to the inline-start edge (left in LTR)\n- `:state(at-inline-end)` — scrolled to the inline-end edge (right in LTR)",
+          "name": "UseScrollarea",
+          "slots": [
+            {
+              "description": "Scrollable content",
+              "name": ""
+            }
+          ],
+          "members": [],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "use-scrollarea",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UseScrollarea",
+          "declaration": {
+            "name": "UseScrollarea",
+            "module": "src/elements/use-scrollarea/use-scrollarea.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "use-scrollarea",
+          "declaration": {
+            "name": "UseScrollarea",
+            "module": "src/elements/use-scrollarea/use-scrollarea.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-option/use-option.ts",
@@ -3781,63 +3838,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-scrollarea/index.ts",
-      "declarations": [],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseScrollarea",
-          "declaration": {
-            "name": "UseScrollarea",
-            "module": "./use-scrollarea"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/elements/use-scrollarea/use-scrollarea.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "A scroll container that exposes custom states for scroll edge detection.\n\n## Custom States\nThe following CSS custom states are available for styling:\n\n- `:state(at-block-start)` — scrolled to the block-start edge (top in horizontal writing modes)\n- `:state(at-block-end)` — scrolled to the block-end edge (bottom in horizontal writing modes)\n- `:state(at-inline-start)` — scrolled to the inline-start edge (left in LTR)\n- `:state(at-inline-end)` — scrolled to the inline-end edge (right in LTR)",
-          "name": "UseScrollarea",
-          "slots": [
-            {
-              "description": "Scrollable content",
-              "name": ""
-            }
-          ],
-          "members": [],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "use-scrollarea",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "UseScrollarea",
-          "declaration": {
-            "name": "UseScrollarea",
-            "module": "src/elements/use-scrollarea/use-scrollarea.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "use-scrollarea",
-          "declaration": {
-            "name": "UseScrollarea",
-            "module": "src/elements/use-scrollarea/use-scrollarea.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/elements/use-time-input/use-time-input.ts",