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

package/custom-elements.json

@@ -708,7 +708,7 @@
       "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\n`customIcon` hook. Every `<use-caret>` in the page picks it up; consumers keep writing the\nsame tag, no new element to register or remember to use instead. Set it once, as early as\npossible (an app's entry point, before any triggers connect) — Lit calls `render()` fresh on\nevery update, so an already-connected instance only reflects the change once something causes\nit to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every trigger, nested or not:\nUseCaret.customIcon = \"→\";\n\n// A function is called on every render instead, and told whether this particular trigger is\n// nested — the same distinction the built-in ▼/▶ caret already makes for submenus:\nUseCaret.customIcon = (html, isNested) =>\n  isNested\n    ? html`<my-icon name=\"chevron-right\"></my-icon>`\n    : html`<my-icon name=\"chevron-down\"></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, at the cost of not\nbeing able to vary by `isNested`.\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```",
+          "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": [
             {
@@ -723,12 +723,21 @@
           "members": [
             {
               "kind": "field",
-              "name": "customIcon",
+              "name": "icon",
               "type": {
-                "text": "| ((html: HtmlTag, isNested: boolean) => TemplateResult | string)\n    | TemplateResult\n    | string | undefined"
+                "text": "((html: HtmlTag) => TemplateResult | string) | TemplateResult | string | undefined"
               },
               "static": true,
-              "description": "Global override for the default caret. When set, every `<use-caret>` in the page\nrenders this inside `part(icon-default)` instead of the built-in ▼/▶ character. A plain\nstring or `TemplateResult` is used as-is for every trigger, nested or not — for a caret that\nstill needs to point sideways on a submenu trigger, use the function form instead: it's\ncalled with the component's own `html` tag and whether *this* trigger is nested, so a\nreturned template is guaranteed to come from the same `lit-html` instance this component\nrenders with, and can still vary the same way the built-in caret does. Unset (the default)\nkeeps the built-in caret."
+              "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": {
@@ -2211,7 +2220,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Accessible grid component following [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/).",
+          "description": "Accessible grid component following [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/).\n\n## Grid Cell Modes\nThe `mode` attribute of the `use-gridcell` element determines how the cell behaves in terms of focus and interaction. The possible values are:\n\n- `'none'` - the cell itself is focusable and it does not contain any interactive elements.\n- `'widget'` - the cell itself is focusable and it contains more than one interactive element. To access the interactive elements, the user must press `Enter` or `F2`, and to restore focus to the cell, the user must press `Esc` or `F2`.\n- `'action'` - the cell itself is not focusable and it contains a single interactive element. The user can tab to the interactive elements directly.\n\n## Accessible Label\nProvide `aria-label` or `aria-labelledby` on the `use-grid` element so screen readers can identify the grid.",
           "name": "UseGrid",
           "slots": [
             {
@@ -2751,9 +2760,6 @@
             {
               "description": "NodeList of `use-option` elements",
               "name": "default"
-            },
-            {
-              "name": "arrow"
             }
           ],
           "members": [
@@ -3318,15 +3324,41 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`use-option` is a custom element that represents an option in a `use-listbox-input` custom element.\n\nThe children of this element are the content of the option and must not contain any interactive elements.",
+          "description": "`use-option` is a custom element that represents an option in a `use-listbox-input` custom\nelement.\n\nThe children of this element are the content of the option and must not contain any\ninteractive elements.\n\nSelection is shown by one of two indicators, swapped based on the option's `selected` state:\na checkmark when selected, nothing (a reserved-space placeholder) when not.\n\nSwapping an indicator **per instance** is a slot: put your own element in the `selected-indicator`\nor `deselected-indicator` slot and it replaces `part(selected-indicator-default)` /\n`part(deselected-indicator-default)` entirely for that option.\n\nSwapping an indicator **for every option in the app** doesn't need touching this component's\n`render()` at all — style `::part(selected-indicator-default)` /\n`::part(deselected-indicator-default)` from an outside stylesheet, the same way any shadow DOM\npart is themed:\n\n```css\nuse-option::part(selected-indicator-default) {\n  mask-image: url(\"/icons/my-checkmark.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to a pair of tokens —\n`--usewc-effect-selected-indicator-mask-image` for the shape and\n`--usewc-effect-selected-indicator-color` for what paints it (`--usewc-effect-deselected-…`\nfor the other state) — so redefining those custom properties has the same effect without\nwriting a `::part()` rule at all.)\n\n`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For\nanything else — different markup, an icon font, logic beyond a mask — set the static\n`selectedIcon` and `deselectedIcon` hooks. Every `<use-option>` in the page picks them up;\nconsumers keep writing the same tag, no new element to register or remember to use instead.\nSet them once, as early as possible (an app's entry point, before any options connect) — Lit\ncalls `render()` fresh on every update, so an already-connected instance only reflects the\nchange once something causes it to re-render:\n\n```ts\n// A bare string or TemplateResult is used as-is, on every option:\nUseOption.selectedIcon = \"✓\";\nUseOption.deselectedIcon = \"\";\n\n// A function is called on every render instead:\nUseOption.selectedIcon = (html) => html`<my-icon name=\"check\"></my-icon>`;\n```\n\nThe function form is called with the component's own `html` tag as its (optional) first\nargument rather than requiring the caller to import one — a page can end up with more than one\ncopy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy\nthan the one this component renders with can silently fail to render. Taking `html` in as a\nparameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`\nthis component already uses. A bare string skips the concern entirely.\n\nA set icon still renders under `part(selected-indicator-default)` /\n`part(deselected-indicator-default)` — the same part the design system's theme masks into the\nbuilt-in glyph. Combining a static hook with `theme.css` means the theme's masking still\napplies to the custom content; reset the relevant `mask-image` token or `::part()` rule if that\nfights with what was set.\n\nOnly need to change the icon on **some** options, not every one in the app? Extend the class,\noverride `render()` normally, and register the subclass under a different tag name so it\ncoexists with the built-in element instead of replacing it everywhere:\n\n```ts\nclass MyOption extends UseOption {\n  override render() {\n    return html`<slot></slot><slot name=\"selected-indicator\"><my-icon name=\"check\"></my-icon></slot>`;\n  }\n}\ncustomElements.define(\"my-option\", MyOption);\n```",
           "name": "UseOption",
           "slots": [
             {
+              "description": "Replaces the default checkmark shown when the option is selected.",
               "name": "selected-indicator"
             },
-            {}
+            {
+              "description": "Replaces the default (empty) indicator shown when the option is not selected.",
+              "name": "deselected-indicator"
+            },
+            {
+              "description": "Option content.",
+              "name": "default"
+            }
           ],
           "members": [
+            {
+              "kind": "field",
+              "name": "selectedIcon",
+              "type": {
+                "text": "IconOverride | undefined"
+              },
+              "static": true,
+              "description": "Global override for the selected-state indicator. When set, every `<use-option>` in the page\nrenders this inside `part(selected-indicator-default)` instead of the built-in ✔ character.\nUnset (the default) keeps the built-in checkmark."
+            },
+            {
+              "kind": "field",
+              "name": "deselectedIcon",
+              "type": {
+                "text": "IconOverride | undefined"
+              },
+              "static": true,
+              "description": "Global override for the deselected-state indicator — the counterpart to selectedIcon.\nUnset (the default) keeps the built-in (empty) placeholder."
+            },
             {
               "kind": "field",
               "name": "selected",
@@ -3728,7 +3760,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Custom input control for managing selected values in a hierarchy.",
+          "description": "Custom input control for managing selected values in a hierarchy.\n\nA convenience for distributing a custom indicator to every item at once: slot an icon into\n`use-tree` itself under `expanded-indicator`, `collapsed-indicator`, `selected-indicator`, or\n`deselected-indicator`, and it's cloned into each lazily-discovered `use-treeitem`'s matching\nslot. This is per-item slotting, just done once for the whole tree — it doesn't replace\n`use-treeitem`'s own static hooks (`expandedIcon`, `collapsedIcon`, `selectedIcon`,\n`deselectedIcon`), which still apply for indicators the tree hasn't cloned one over.",
           "name": "UseTree",
           "slots": [
             {
@@ -3736,7 +3768,20 @@
               "name": "default"
             },
             {
-              "name": "arrow"
+              "description": "Cloned into every item's `expanded-indicator` slot.",
+              "name": "expanded-indicator"
+            },
+            {
+              "description": "Cloned into every item's `collapsed-indicator` slot.",
+              "name": "collapsed-indicator"
+            },
+            {
+              "description": "Cloned into every item's `selected-indicator` slot.",
+              "name": "selected-indicator"
+            },
+            {
+              "description": "Cloned into every item's `deselected-indicator` slot.",
+              "name": "deselected-indicator"
             }
           ],
           "members": [
@@ -3874,15 +3919,67 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`use-option` is a custom element that represents an option in a `use-listbox-input` custom element.\n\nThe children of this element are the content of the option and must not contain any interactive elements.\n\n## To Do\n\n- [ ] When the parent is no longer disabled, update the items without their own `[disabled]`",
+          "description": "`use-treeitem` is a custom element that represents a node in a `use-tree` custom element.\n\nThe children of this element are the content of the item, plus any nested `use-treeitem`\nelements representing its children, and must not otherwise contain interactive elements.\n\nFour indicators render alongside an item's content: an expanded/collapsed disclosure glyph\n(only one of the pair shows, depending on state), and a selected/deselected glyph (same).\n\nSwapping an indicator **per instance** is a slot: put your own element in the\n`expanded-indicator`, `collapsed-indicator`, `selected-indicator`, or `deselected-indicator`\nslot and it replaces that indicator's `part(*-default)` entirely for that item. `use-tree`\nalso offers a shortcut for this: slot an icon into `use-tree` itself and it's cloned into every\nitem's matching slot — see `use-tree`'s own docs.\n\nSwapping an indicator **for every item in the app** doesn't need touching this component's\n`render()` at all — style `::part(*-indicator-default)` from an outside stylesheet, the same\nway any shadow DOM part is themed:\n\n```css\nuse-treeitem::part(collapsed-indicator-default) {\n  mask-image: url(\"/icons/my-chevron.svg\");\n}\n```\n\n(When the design system's `theme.css` is loaded, this is already wired to tokens — a\nmask-image/color pair per indicator: `--usewc-effect-tree-item-expanded-indicator-mask-image`\n/ `-color`, `--usewc-effect-tree-item-collapsed-indicator-mask-image` / `-color`, and\n`--usewc-effect-selected-indicator-mask-image` / `-color` (`--usewc-effect-deselected-…` for\nthe other state) — so redefining those custom properties has the same effect without writing a\n`::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 matching static\nhook: `expandedIcon`, `collapsedIcon`, `selectedIcon`, `deselectedIcon`. Every `<use-treeitem>`\nin the page picks them up; consumers keep writing the same tag, no new element to register or\nremember to use instead. Set them once, as early as possible (an app's entry point, before any\nitems connect) — Lit calls `render()` fresh on every update, so an already-connected instance\nonly 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 item:\nUseTreeitem.collapsedIcon = \"▸\";\nUseTreeitem.expandedIcon = \"▾\";\n\n// A function is called on every render instead:\nUseTreeitem.collapsedIcon = (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\nA set icon still renders under that indicator's own `part(*-indicator-default)` — the same part\nthe design system's theme masks into the built-in glyph. Combining a static hook with\n`theme.css` means the theme's masking still applies to the custom content; reset the relevant\n`mask-image` token or `::part()` rule if that fights with what was set.\n\nOnly need to change an indicator on **some** items, not every one in the app? Extend the class,\noverride `render()` normally, and register the subclass under a different tag name so it\ncoexists with the built-in element instead of replacing it everywhere.\n\n## To Do\n\n- [ ] When the parent is no longer disabled, update the items without their own `[disabled]`",
           "name": "UseTreeitem",
           "slots": [
             {
+              "description": "Replaces the default disclosure glyph shown when the item is expanded.",
+              "name": "expanded-indicator"
+            },
+            {
+              "description": "Replaces the default disclosure glyph shown when the item is collapsed.",
+              "name": "collapsed-indicator"
+            },
+            {
+              "description": "Replaces the default glyph shown when the item is selected.",
               "name": "selected-indicator"
             },
-            {}
+            {
+              "description": "Replaces the default (empty) glyph shown when the item is not selected.",
+              "name": "deselected-indicator"
+            },
+            {
+              "description": "Item content, plus any nested `use-treeitem` children.",
+              "name": "default"
+            }
           ],
           "members": [
+            {
+              "kind": "field",
+              "name": "expandedIcon",
+              "type": {
+                "text": "IconOverride | undefined"
+              },
+              "static": true,
+              "description": "Global override for the expanded-state disclosure indicator. When set, every\n`<use-treeitem>` in the page renders this inside `part(expanded-indicator-default)` instead\nof the built-in `-` character. Unset (the default) keeps the built-in glyph."
+            },
+            {
+              "kind": "field",
+              "name": "collapsedIcon",
+              "type": {
+                "text": "IconOverride | undefined"
+              },
+              "static": true,
+              "description": "Global override for the collapsed-state disclosure indicator — the counterpart to\nexpandedIcon. Unset (the default) keeps the built-in `+` character."
+            },
+            {
+              "kind": "field",
+              "name": "selectedIcon",
+              "type": {
+                "text": "IconOverride | undefined"
+              },
+              "static": true,
+              "description": "Global override for the selected-state indicator. Unset (the default) keeps the built-in ✔\ncharacter."
+            },
+            {
+              "kind": "field",
+              "name": "deselectedIcon",
+              "type": {
+                "text": "IconOverride | undefined"
+              },
+              "static": true,
+              "description": "Global override for the deselected-state indicator — the counterpart to\nselectedIcon. Unset (the default) keeps the built-in (empty) placeholder."
+            },
             {
               "kind": "field",
               "name": "selected",

package/dist/design-system.css

@@ -833,12 +833,8 @@
 }
 
 @layer use-theme.icon {
-  use-option::part(selected-indicator-default) {
-    display: none;
-  }
-
-  /* Only matches the built-in ▼/▶ glyph — `use-caret` renders a custom `UseCaret.customIcon`
-   under a different part name so this masking never fights with it. */
+  /* Only matches the built-in ▼/▶ glyph — `use-caret` renders a custom `UseCaret.icon` /
+   `UseCaret.nestedIcon` under a different part name so this masking never fights with it. */
   use-caret::part(icon-default) {
     display: inline-block;
     overflow: hidden;
@@ -864,6 +860,89 @@
   use-caret::part(icon) {
     margin-inline-start: auto;
   }
+
+  /* Same masking shape as use-caret's icon-default, shared by every ✔-style selected indicator
+   — `use-option` renders its own `selected-indicator-default`, `-custom` swap for the same
+   reason use-caret does: real custom content shouldn't be clobbered by this masking. Color is its
+   own token, same as use-caret's, so a theme can recolor the checkmark independently of what
+   shape it masks. */
+  use-option::part(selected-indicator-default),
+  use-treeitem::part(selected-indicator-default) {
+    display: inline-block;
+    overflow: hidden;
+    white-space: nowrap;
+    text-indent: 100%;
+    inline-size: var(--usewc-layout-selected-indicator-size);
+    block-size: var(--usewc-layout-selected-indicator-size);
+    background-color: var(--usewc-effect-selected-indicator-color, currentColor);
+    mask-image: var(--usewc-effect-selected-indicator-mask-image, none);
+    mask-size: contain;
+    mask-repeat: no-repeat;
+    mask-position: center;
+  }
+
+  use-theme-escape use-option::part(selected-indicator-default),
+  use-theme-escape use-treeitem::part(selected-indicator-default) {
+    all: revert-layer;
+  }
+
+  /* The deselected indicator has no built-in glyph: `--usewc-effect-deselected-indicator-mask-image`
+   defaults to the `none` keyword (no mask layer at all — the box would otherwise paint fully
+   opaque) and `--usewc-effect-deselected-indicator-color` defaults to `transparent`, so together
+   they read as blank out of the box. A theme sets both to show something (an empty checkbox
+   outline, for instance) — the mask supplies the shape, the color paints it. Either way this
+   occupies the exact same box as its selected sibling, or swapping between the two shifts every
+   option/item's content sideways depending on selection state. */
+  use-option::part(deselected-indicator-default),
+  use-treeitem::part(deselected-indicator-default) {
+    display: inline-block;
+    overflow: hidden;
+    white-space: nowrap;
+    text-indent: 100%;
+    inline-size: var(--usewc-layout-selected-indicator-size);
+    block-size: var(--usewc-layout-selected-indicator-size);
+    background-color: var(--usewc-effect-deselected-indicator-color, transparent);
+    mask-image: var(--usewc-effect-deselected-indicator-mask-image, none);
+    mask-size: contain;
+    mask-repeat: no-repeat;
+    mask-position: center;
+  }
+
+  use-theme-escape use-option::part(deselected-indicator-default),
+  use-theme-escape use-treeitem::part(deselected-indicator-default) {
+    all: revert-layer;
+  }
+
+  /* Expanded/collapsed are a state pair, not a checked/unchecked contrast, but still get their
+   own color tokens for the same reason the selected indicator does — a theme may want the
+   disclosure glyph a different shade than the surrounding text. */
+  use-treeitem::part(expanded-indicator-default),
+  use-treeitem::part(collapsed-indicator-default) {
+    display: inline-block;
+    overflow: hidden;
+    white-space: nowrap;
+    text-indent: 100%;
+    inline-size: var(--usewc-layout-tree-item-indicator-size);
+    block-size: var(--usewc-layout-tree-item-indicator-size);
+    mask-size: contain;
+    mask-repeat: no-repeat;
+    mask-position: center;
+  }
+
+  use-treeitem::part(expanded-indicator-default) {
+    background-color: var(--usewc-effect-tree-item-expanded-indicator-color, currentColor);
+    mask-image: var(--usewc-effect-tree-item-expanded-indicator-mask-image, none);
+  }
+
+  use-treeitem::part(collapsed-indicator-default) {
+    background-color: var(--usewc-effect-tree-item-collapsed-indicator-color, currentColor);
+    mask-image: var(--usewc-effect-tree-item-collapsed-indicator-mask-image, none);
+  }
+
+  use-theme-escape use-treeitem::part(expanded-indicator-default),
+  use-theme-escape use-treeitem::part(collapsed-indicator-default) {
+    all: revert-layer;
+  }
 }
 
 @layer use-theme.menu {
@@ -959,9 +1038,12 @@
     }
   }
 
+  /* use-option's own checkmark now renders in-flow (a slot, not a background-image), so it
+   already reserves its own leading space via the shared gap/padding above — no extra reservation
+   needed here. This block only concerns the native [role="menuitemcheckbox"/"menuitemradio"]
+   items, whose checkmark is still theme.css's own background-image on the host. */
   use-menu :is([role="menuitemcheckbox"], [role="menuitemradio"]),
   use-listbox-input {
-    use-option,
     &:has(+ :where([role="menuitemcheckbox"], [role="menuitemradio"])),
     & + :where([role="menuitemcheckbox"], [role="menuitemradio"]) {
       padding-inline-start: calc(var(--usewc-layout-input-padding-inline) * 2 + var(--usewc-layout-selector-width));
@@ -1028,8 +1110,10 @@
       flip-inline flip-block;
   }
 
-  use-menu [aria-checked="true"],
-  use-option:state(selected) {
+  /* use-option's own checkmark is themed separately, in icon.css, as a mask on its
+   selected-indicator part rather than a background-image on the host — this rule only concerns
+   the native [aria-checked] menu items, which have no shadow part to target. */
+  use-menu [aria-checked="true"] {
     background-image: var(--usewc-effect-menu-item-checkmark-background-image, none);
     /* TODO use logical position */
     background-position: left var(--usewc-layout-input-padding-inline) center;

package/dist/docs/use-caret.md

@@ -44,23 +44,21 @@ use-caret::part(icon-default) {
 the same effect without writing a `::part()` rule at all.)
 
 `::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For
-anything else — different markup, an icon font, logic beyond a mask — set the static
-`customIcon` hook. Every `<use-caret>` in the page picks it up; consumers keep writing the
-same tag, no new element to register or remember to use instead. Set it once, as early as
-possible (an app's entry point, before any triggers connect) — Lit calls `render()` fresh on
-every update, so an already-connected instance only reflects the change once something causes
-it to re-render:
+anything else — different markup, an icon font, logic beyond a mask — set the static `icon`
+and `nestedIcon` hooks. Every `<use-caret>` in the page picks them up; consumers keep writing
+the same tag, no new element to register or remember to use instead. `icon` supplies a
+top-level trigger's glyph, `nestedIcon` a submenu trigger's — set whichever apply; an unset one
+keeps the built-in ▼/▶ for that case. Set them once, as early as possible (an app's entry
+point, before any triggers connect) — Lit calls `render()` fresh on every update, so an
+already-connected instance only reflects the change once something causes it to re-render:
 
 ```ts
-// A bare string or TemplateResult is used as-is, on every trigger, nested or not:
-UseCaret.customIcon = "→";
-
-// A function is called on every render instead, and told whether this particular trigger is
-// nested — the same distinction the built-in ▼/▶ caret already makes for submenus:
-UseCaret.customIcon = (html, isNested) =>
-  isNested
-    ? html`<my-icon name="chevron-right"></my-icon>`
-    : html`<my-icon name="chevron-down"></my-icon>`;
+// A bare string or TemplateResult is used as-is, on every trigger of that kind:
+UseCaret.icon = "▾";
+UseCaret.nestedIcon = "▸";
+
+// A function is called on every render instead:
+UseCaret.nestedIcon = (html) => html`<my-icon name="chevron-right"></my-icon>`;
 ```
 
 The function form is called with the component's own `html` tag as its (optional) first
@@ -68,8 +66,7 @@ argument rather than requiring the caller to import one — a page can end up wi
 copy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy
 than the one this component renders with can silently fail to render. Taking `html` in as a
 parameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`
-this component already uses. A bare string skips the concern entirely, at the cost of not
-being able to vary by `isNested`.
+this component already uses. A bare string skips the concern entirely.
 
 Only need to change the icon on **some** triggers, not every one in the app? Extend the
 class, override `render()` normally, and register the subclass under a different tag name so
@@ -88,16 +85,13 @@ customElements.define("my-caret", MyCaret);
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| customIcon | `\| ((html: HtmlTag, isNested: boolean) => TemplateResult \| string)
-    \| TemplateResult
-    \| string \| undefined` | - | Global override for the default caret. When set, every `<use-caret>` in the page
-renders this inside `part(icon-default)` instead of the built-in ▼/▶ character. A plain
-string or `TemplateResult` is used as-is for every trigger, nested or not — for a caret that
-still needs to point sideways on a submenu trigger, use the function form instead: it's
-called with the component's own `html` tag and whether *this* trigger is nested, so a
-returned template is guaranteed to come from the same `lit-html` instance this component
-renders with, and can still vary the same way the built-in caret does. Unset (the default)
-keeps the built-in caret. |
+| icon | `((html: HtmlTag) => TemplateResult \| string) \| TemplateResult \| string \| undefined` | - | Global override for a top-level trigger's caret. When set, every non-nested `<use-caret>` in
+the page renders this inside `part(icon-default)` instead of the built-in ▼ character. A
+plain string or `TemplateResult` is used as-is; the function form is called with the
+component's own `html` tag, so a returned template is guaranteed to come from the same
+`lit-html` instance this component renders with. Unset (the default) keeps the built-in ▼. |
+| nestedIcon | `((html: HtmlTag) => TemplateResult \| string) \| TemplateResult \| string \| undefined` | - | Global override for a submenu trigger's caret — the counterpart to icon for a
+`<use-caret>` nested inside a `use-menu`. Unset (the default) keeps the built-in ▶. |
 
 ## Slots
 

package/dist/docs/use-grid.md

@@ -2,6 +2,16 @@
 
 Accessible grid component following [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/).
 
+## Grid Cell Modes
+The `mode` attribute of the `use-gridcell` element determines how the cell behaves in terms of focus and interaction. The possible values are:
+
+- `'none'` - the cell itself is focusable and it does not contain any interactive elements.
+- `'widget'` - the cell itself is focusable and it contains more than one interactive element. To access the interactive elements, the user must press `Enter` or `F2`, and to restore focus to the cell, the user must press `Esc` or `F2`.
+- `'action'` - the cell itself is not focusable and it contains a single interactive element. The user can tab to the interactive elements directly.
+
+## Accessible Label
+Provide `aria-label` or `aria-labelledby` on the `use-grid` element so screen readers can identify the grid.
+
 ## Attributes
 
 | Name | Type | Default | Description |

package/dist/docs/use-listbox-input.md

@@ -37,4 +37,3 @@
 | Name | Description |
 | --- | --- |
 | `default` | NodeList of `use-option` elements |
-| `arrow` | - |

package/dist/docs/use-option.md

@@ -1,8 +1,77 @@
 # `use-option`
 
-`use-option` is a custom element that represents an option in a `use-listbox-input` custom element.
+`use-option` is a custom element that represents an option in a `use-listbox-input` custom
+element.
 
-The children of this element are the content of the option and must not contain any interactive elements.
+The children of this element are the content of the option and must not contain any
+interactive elements.
+
+Selection is shown by one of two indicators, swapped based on the option's `selected` state:
+a checkmark when selected, nothing (a reserved-space placeholder) when not.
+
+Swapping an indicator **per instance** is a slot: put your own element in the `selected-indicator`
+or `deselected-indicator` slot and it replaces `part(selected-indicator-default)` /
+`part(deselected-indicator-default)` entirely for that option.
+
+Swapping an indicator **for every option in the app** doesn't need touching this component's
+`render()` at all — style `::part(selected-indicator-default)` /
+`::part(deselected-indicator-default)` from an outside stylesheet, the same way any shadow DOM
+part is themed:
+
+```css
+use-option::part(selected-indicator-default) {
+  mask-image: url("/icons/my-checkmark.svg");
+}
+```
+
+(When the design system's `theme.css` is loaded, this is already wired to a pair of tokens —
+`--usewc-effect-selected-indicator-mask-image` for the shape and
+`--usewc-effect-selected-indicator-color` for what paints it (`--usewc-effect-deselected-…`
+for the other state) — so redefining those custom properties has the same effect without
+writing a `::part()` rule at all.)
+
+`::part()` only reaches CSS-expressible changes (a mask, a background, a transform). For
+anything else — different markup, an icon font, logic beyond a mask — set the static
+`selectedIcon` and `deselectedIcon` hooks. Every `<use-option>` in the page picks them up;
+consumers keep writing the same tag, no new element to register or remember to use instead.
+Set them once, as early as possible (an app's entry point, before any options connect) — Lit
+calls `render()` fresh on every update, so an already-connected instance only reflects the
+change once something causes it to re-render:
+
+```ts
+// A bare string or TemplateResult is used as-is, on every option:
+UseOption.selectedIcon = "✓";
+UseOption.deselectedIcon = "";
+
+// A function is called on every render instead:
+UseOption.selectedIcon = (html) => html`<my-icon name="check"></my-icon>`;
+```
+
+The function form is called with the component's own `html` tag as its (optional) first
+argument rather than requiring the caller to import one — a page can end up with more than one
+copy of `lit-html` in its module graph, and a `TemplateResult` built from a *different* copy
+than the one this component renders with can silently fail to render. Taking `html` in as a
+parameter sidesteps that: whatever's returned is guaranteed to come from the same `lit-html`
+this component already uses. A bare string skips the concern entirely.
+
+A set icon still renders under `part(selected-indicator-default)` /
+`part(deselected-indicator-default)` — the same part the design system's theme masks into the
+built-in glyph. Combining a static hook with `theme.css` means the theme's masking still
+applies to the custom content; reset the relevant `mask-image` token or `::part()` rule if that
+fights with what was set.
+
+Only need to change the icon on **some** options, not every one in the app? Extend the class,
+override `render()` normally, and register the subclass under a different tag name so it
+coexists with the built-in element instead of replacing it everywhere:
+
+```ts
+class MyOption extends UseOption {
+  override render() {
+    return html`<slot></slot><slot name="selected-indicator"><my-icon name="check"></my-icon></slot>`;
+  }
+}
+customElements.define("my-option", MyOption);
+```
 
 ## Attributes
 
@@ -12,6 +81,16 @@ The children of this element are the content of the option and must not contain
 | disabled | - | - | - |
 | value | - | - | - |
 
+## Properties
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| selectedIcon | `IconOverride \| undefined` | - | Global override for the selected-state indicator. When set, every `<use-option>` in the page
+renders this inside `part(selected-indicator-default)` instead of the built-in ✔ character.
+Unset (the default) keeps the built-in checkmark. |
+| deselectedIcon | `IconOverride \| undefined` | - | Global override for the deselected-state indicator — the counterpart to selectedIcon.
+Unset (the default) keeps the built-in (empty) placeholder. |
+
 ## Methods
 
 | Name | Signature | Description |
@@ -23,5 +102,6 @@ The children of this element are the content of the option and must not contain
 
 | Name | Description |
 | --- | --- |
-| `selected-indicator` | - |
-| `undefined` | - |
+| `selected-indicator` | Replaces the default checkmark shown when the option is selected. |
+| `deselected-indicator` | Replaces the default (empty) indicator shown when the option is not selected. |
+| `default` | Option content. |

package/dist/docs/use-tree.md

@@ -2,6 +2,13 @@
 
 Custom input control for managing selected values in a hierarchy.
 
+A convenience for distributing a custom indicator to every item at once: slot an icon into
+`use-tree` itself under `expanded-indicator`, `collapsed-indicator`, `selected-indicator`, or
+`deselected-indicator`, and it's cloned into each lazily-discovered `use-treeitem`'s matching
+slot. This is per-item slotting, just done once for the whole tree — it doesn't replace
+`use-treeitem`'s own static hooks (`expandedIcon`, `collapsedIcon`, `selectedIcon`,
+`deselectedIcon`), which still apply for indicators the tree hasn't cloned one over.
+
 ## Attributes
 
 | Name | Type | Default | Description |
@@ -35,4 +42,7 @@ Custom input control for managing selected values in a hierarchy.
 | Name | Description |
 | --- | --- |
 | `default` | NodeList of `use-treeitem` elements |
-| `arrow` | - |
+| `expanded-indicator` | Cloned into every item's `expanded-indicator` slot. |
+| `collapsed-indicator` | Cloned into every item's `collapsed-indicator` slot. |
+| `selected-indicator` | Cloned into every item's `selected-indicator` slot. |
+| `deselected-indicator` | Cloned into every item's `deselected-indicator` slot. |