use-wc 1.0.0-pre.91 → 1.0.0-pre.92

package/custom-elements.json

@@ -762,130 +762,130 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/elements/use-caret/use-caret.ts",
+      "path": "src/elements/use-calendarday/use-calendarday.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",
+          "description": "A helper component for customizing specific days within `use-calendar`.\nContent placed inside this element will replace the default day number display.",
+          "name": "UseCalendarday",
           "slots": [
             {
-              "description": "Trigger label content.",
+              "description": "slot for custom day content (replaces the day number)",
               "name": "default"
-            },
-            {
-              "description": "Replaces the default caret glyph.",
-              "name": "icon"
             }
           ],
           "members": [
             {
               "kind": "field",
-              "name": "icon",
+              "name": "date",
               "type": {
-                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
+                "text": "string"
               },
-              "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 ▼."
+              "attribute": "date"
             },
             {
               "kind": "field",
-              "name": "nestedIcon",
+              "name": "day",
+              "readonly": true
+            }
+          ],
+          "attributes": [
+            {
+              "name": "date",
               "type": {
-                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
+                "text": "string"
               },
-              "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 ▶."
+              "fieldName": "date"
             }
           ],
           "superclass": {
             "name": "LitElement",
             "package": "lit"
           },
-          "tagName": "use-caret",
+          "tagName": "use-calendarday",
           "customElement": true
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "UseCaret",
+          "name": "UseCalendarday",
           "declaration": {
-            "name": "UseCaret",
-            "module": "src/elements/use-caret/use-caret.ts"
+            "name": "UseCalendarday",
+            "module": "src/elements/use-calendarday/use-calendarday.ts"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "use-caret",
+          "name": "use-calendarday",
           "declaration": {
-            "name": "UseCaret",
-            "module": "src/elements/use-caret/use-caret.ts"
+            "name": "UseCalendarday",
+            "module": "src/elements/use-calendarday/use-calendarday.ts"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/elements/use-calendarday/use-calendarday.ts",
+      "path": "src/elements/use-caret/use-caret.ts",
       "declarations": [
         {
           "kind": "class",
-          "description": "A helper component for customizing specific days within `use-calendar`.\nContent placed inside this element will replace the default day number display.",
-          "name": "UseCalendarday",
+          "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": "slot for custom day content (replaces the day number)",
+              "description": "Trigger label content.",
               "name": "default"
+            },
+            {
+              "description": "Replaces the default caret glyph.",
+              "name": "icon"
             }
           ],
           "members": [
             {
               "kind": "field",
-              "name": "date",
+              "name": "icon",
               "type": {
-                "text": "string"
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
               },
-              "attribute": "date"
+              "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": "day",
-              "readonly": true
-            }
-          ],
-          "attributes": [
-            {
-              "name": "date",
+              "name": "nestedIcon",
               "type": {
-                "text": "string"
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
               },
-              "fieldName": "date"
+              "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-calendarday",
+          "tagName": "use-caret",
           "customElement": true
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "UseCalendarday",
+          "name": "UseCaret",
           "declaration": {
-            "name": "UseCalendarday",
-            "module": "src/elements/use-calendarday/use-calendarday.ts"
+            "name": "UseCaret",
+            "module": "src/elements/use-caret/use-caret.ts"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "use-calendarday",
+          "name": "use-caret",
           "declaration": {
-            "name": "UseCalendarday",
-            "module": "src/elements/use-calendarday/use-calendarday.ts"
+            "name": "UseCaret",
+            "module": "src/elements/use-caret/use-caret.ts"
           }
         }
       ]

package/package.json

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

package/vscode.html-custom-data.json

@@ -63,18 +63,18 @@
       ],
       "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-calendarday",
       "description": "A helper component for customizing specific days within `use-calendar`.\nContent placed inside this element will replace the default day number display.\n---\n\n\n### **Slots:**\n - **default** - slot for custom day content (replaces the day number)",
       "attributes": [{ "name": "date", "values": [] }],
       "references": []
     },
+    {
+      "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-control-set",
       "description": "Groups adjacent controls — buttons and text-style inputs alike — into one visual unit: shared\nborders between touching children, rounded corners only on the two outer ends, and a hovered\nor focused child's border lifted above its neighbors so the whole border reads clearly.\n\n`use-control-set` renders no shadow DOM and no template of its own — it exists only as a\ndedicated tag for `theme/control-set.css` to style, the same way `use-layout` is a bare\nprimitive rather than a specific look. A classic split button is a text button followed by an\nicon-only trigger for a `use-menu`:\n\n```html\n<use-control-set>\n  <button type=\"button\">Save</button>\n  <button type=\"button\" popovertarget=\"save-options\" aria-label=\"More save options\">\n    <use-caret></use-caret>\n  </button>\n</use-control-set>\n<use-menu id=\"save-options\" aria-label=\"More save options\">\n  <button role=\"menuitem\">Save as&hellip;</button>\n</use-menu>\n```\n\nA search box with an attached submit button follows the same shape, mixing a text input with a\nbutton:\n\n```html\n<use-control-set>\n  <input type=\"search\" placeholder=\"Search\" />\n  <button type=\"submit\">Go</button>\n</use-control-set>\n```\n\nA child is a `<button>`, anything wearing `.appearance-button`, an `<input>` (other than a\ncheckbox/radio/range/file), a `<select>`, a `<textarea>`, or anything wearing\n`.appearance-input` — see `theme/control-set.css` for exactly which selectors read which\nradius/border tokens. A plain `span` renders as a static text cell between controls.\n\nPagination follows the same shape, with `a.appearance-button` links and `aria-current=\"page\"`\nholding the current page in its pressed look:\n\n```html\n<nav aria-label=\"Pagination\">\n  <use-control-set>\n    <a class=\"appearance-button\" href=\"?page=1\">1</a>\n    <a class=\"appearance-button\" href=\"?page=2\" aria-current=\"page\">2</a>\n    <span aria-hidden=\"true\">&hellip;</span>\n    <a class=\"appearance-button\" href=\"?page=10\">10</a>\n  </use-control-set>\n</nav>\n```\n\nA formatting toolbar works the same way with toggle buttons: `aria-pressed=\"true\"` (or `\"mixed\"`,\nfor a selection it only partly covers) holds a format that's on in its pressed look.\n\nHow the touching sides render is themeable rather than fixed: `--usewc-layout-control-set-gap`\n(default: a negative overlap equal to the child's own border, for a seamless merged line) and\n`--usewc-effect-control-set-border-radius-sequential` (default: `0`, for square touching\ncorners) can both be overridden — a positive gap and a small radius reads as a looser, softer\nset instead of a fused one.\n---\n\n\n### **Slots:**\n - _default_ - The grouped controls.",