@skdx/web-components 0.27.0 → 0.28.0

package/dist/internal/styles.d.ts

@@ -5,101 +5,30 @@
  */
 export declare const delegatesFocusShadowRootOptions: ShadowRootInit;
 /**
- * Takes the UA chrome off the native control an element wraps in its shadow
- * root. Append to a component's `static styles`.
- *
- * **Why this exists.** In React, Vue, Svelte and Angular the native `<button>`
- * or `<input>` sits in the light DOM, so the consumer's own reset — Tailwind's
- * preflight, `normalize.css`, whatever they already use — reaches it and the
- * control arrives unstyled. A document stylesheet cannot cross a shadow
- * boundary, so the Web Components build was the one framework where
- * "unstyled" still meant a grey 3-D system button. This rule is what the other
- * four frameworks get for free.
- *
- * **Why no `@layer`.** Unlike {@link LIGHT_DOM_STYLES}, this needs none. When
- * declarations come from different tree contexts the outer tree wins for
- * normal rules, so a consumer's `skdx-dialog-close::part(close) { … }` already
- * beats this with no `!important` and no ordering constraint.
- *
- * **Why it is safe to name four elements at once.** The selector only ever
- * sees the component's own shadow root, which holds a single control. No
- * component in this package renders `type="range"`, `"color"`, `"checkbox"` or
- * `"radio"` — the one `type="file"` is already visually hidden, and
- * `<skdx-checkbox>` uses `<button role="checkbox">` — so `appearance: none`
- * cannot erase a control's only rendering.
- *
- * `unsafeCSS` is safe here in the literal sense: {@link NATIVE_CONTROL_RESET}
- * is a module-private compile-time constant, not anything a caller can reach.
+ * Removes UA chrome from native controls in shadow root.
+ * Other frameworks' light-DOM controls get consumer reset for free; shadow boundary blocks document styles.
+ * No `@layer` needed (unlike {@link LIGHT_DOM_STYLES}): outer styles beat inner for normal rules.
  */
 export declare const resetNativeControl: import("lit").CSSResult;
 /**
- * Lets the host be the box `@skdx/skins` paints while the native control it
- * wraps stays activatable and focusable over the host's whole surface. Append
- * to a component's `static styles`, after {@link resetNativeControl}.
- *
- * **Why this exists.** `@skdx/skins` paints the *host*: `applyHostPart` puts
- * `.skdx-dialog__close` on `<skdx-dialog-close>` itself, not on the `<button>`
- * inside it, because a document stylesheet cannot reach across a shadow
- * boundary. The host therefore carries the padding, border, radius and
- * background — and the shadow `<button>` must not draw a second box nested
- * inside the first, sized independently and visibly off-centre.
- *
- * **Why not `display: contents`.** That was the first design: it removes the
- * control from the box tree while keeping it in the DOM tree, which reads as
- * exactly right. Measured in Chromium it fails on the two behaviours the
- * control exists to provide: `delegatesFocus` cannot delegate into a boxless
- * element, so `host.focus()` and keyboard traversal silently did nothing, and
- * a click anywhere the slotted content isn't — the entire padding ring —
- * hit-tests the host and never activates the control.
- *
- * **What this does instead.** The control stays *in flow* and mirrors the
- * host's own layout with `inherit`, so the slotted content lays out exactly
- * where it would if the host's skin declarations applied to the control
- * directly, and the host keeps sizing intrinsically from its content.
- * `flex: 1` / `align-self: stretch` make it fill the host's content box when
- * the skin sizes the host explicitly. The `::before` overlay is the hit
- * surface: a pseudo-element hit-tests as its originating element, so a click
- * anywhere in the host's padding box — not just on the slotted text —
- * activates the control natively. Measured against the React reference: host
- * geometry and slotted-text position identical, centre and corner clicks both
- * activate, and focus delegation works.
- *
- * **Deliberately not `<dialog>`.** `<skdx-dialog-content>` and
- * `<skdx-alert-dialog-content>` are excluded. Their `<dialog>` must stay a
- * normal box for `showModal()` to promote into the top layer.
- *
- * The `:host >` combinator keeps this to the single control a component renders
- * directly, so a `<button>` deeper inside a richer shadow tree is untouched.
+ * Host box styling for `@skdx/skins` to paint, while native control stays clickable on the whole surface.
+ * Control mirrors host layout via `inherit` and fills with `flex: 1` / `align-self: stretch`.
+ * `::before` overlay is the hit surface (pseudo-elements hit-test as their element).
+ * Excludes dialog; `:host >` keeps this to the single direct control only.
  */
 export declare const controlBoxOnHost: import("lit").CSSResult;
 /**
- * Installs {@link LIGHT_DOM_STYLES} once per document. Called from the
- * `connectedCallback()` of every light-DOM element, rather than as a module
- * side effect, so importing the package on a server (no `document`) stays
- * inert.
+ * Installs {@link LIGHT_DOM_STYLES} once per document.
+ * Called from light-DOM elements' `connectedCallback`, not module side effect, so server imports stay inert.
  * @internal
  */
 export declare function installLightDomStyles(): void;
 /** `:host([hidden]) { display: none; }` — shared by elements that render nothing while hidden. */
 export declare const hiddenHostStyles: import("lit").CSSResult;
 /**
- * Puts {@link INHERITANCE_STYLES} into `root`.
- *
- * Called from the patched `connectedCallback` in `internal/define.ts`, which
- * every element in this package routes through, because this has to reach a
- * `<slot>` — and a `<slot>` is inside a shadow root, where neither the
- * consumer's stylesheet, `@skdx/skins`, nor {@link LIGHT_DOM_STYLES} can
- * follow. One shared `CSSStyleSheet` for the whole document is the point of a
- * constructable sheet: adopting it into a thousand roots costs one parse.
- *
- * The `<style>` fallback is Lit's own — `ReactiveElement` appends one per root
- * wherever `adoptedStyleSheets` is missing — and it is what keeps this working
- * on Safari before 16.4 and observable under jsdom, which has the
- * `CSSStyleSheet` constructor but neither `Document.adoptedStyleSheets` nor
- * `ShadowRoot.adoptedStyleSheets`.
- *
- * Idempotent in both paths: a decorated class extending a decorated one is
- * patched twice, and both wrappers run on every connect.
+ * Puts {@link INHERITANCE_STYLES} into shadow root. Called from every element's `connectedCallback` patch
+ * (in `internal/define.ts`) so it reaches slots shadow DOM cannot otherwise reach. One shared `CSSStyleSheet`
+ * means adopting into many roots costs one parse. `<style>` fallback for Safari <16.4 and jsdom.
  * @internal
  */
 export declare function adoptInheritanceStyles(root: ShadowRoot): void;

package/dist/internal/styles.js

@@ -1,4 +1,4 @@
-import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootOptions,delegatesFocus:!0},n=`
+import{css as d,LitElement as p,unsafeCSS as u}from"lit";var k={...p.shadowRootOptions,delegatesFocus:!0},s=`
   appearance: none;
   background: none;
   border: 0;
@@ -8,14 +8,14 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
   color: inherit;
   text-align: inherit;
   cursor: inherit;
-`,k=o`
+`,h=d`
   button,
   input,
   select,
   textarea {
-    ${p(n)}
+    ${u(s)}
   }
-`,b=o`
+`,b=d`
   :host {
     position: relative;
   }
@@ -37,7 +37,7 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
     position: absolute;
     inset: 0;
   }
-`,c=`@layer skdx-light-dom {
+`,x=`@layer skdx-light-dom {
   skdx-autocomplete-input,
   skdx-combobox-input,
   skdx-multi-select-input,
@@ -50,36 +50,35 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
   skdx-label,
   skdx-toast-region { display: contents; }
 
-  /* With the other four field inputs, not with the boxless hosts above: this
-     host is what wears .skdx-text-field__input, and that class is the whole
-     field surface \u2014 border, background, control height, padding (text-field.css
-     styles the input rather than the root precisely so a prefix icon or clear
-     button can sit inside the root). display:contents generates no box, so
-     none of it painted and the control rendered as bare reset text with the
-     clear button floating beside it. */
+  /* Text field needs a box (not contents) so clear button doesn't float alone. */
   skdx-text-field-input { display: block; }
 
+  skdx-autocomplete-trigger,
+  skdx-collapsible-trigger,
+  skdx-select-trigger,
+  skdx-table-expand-trigger,
   skdx-tree-select-trigger { display: inline-block; }
 
+  skdx-autocomplete-trigger[hidden] { display: none; }
+
   skdx-autocomplete-input input,
+  skdx-autocomplete-trigger button,
+  skdx-collapsible-trigger button,
   skdx-combobox-input input,
   skdx-command-input input,
   skdx-multi-select-input input,
   skdx-password-input-field input,
+  skdx-select-trigger button,
+  skdx-table-expand-trigger button,
   skdx-text-field-input input,
   skdx-tree-select-input input,
-  skdx-tree-select-trigger button {${n}  }
-
-  /* controlBoxOnHost, for the one field trigger that has no shadow root to
-     apply it in. The skin paints the host (.skdx-tree-select__trigger is the
-     full-width, control-height-md field box from _trigger.css), and React
-     paints that same class straight onto its <button>
-     (react/src/tree-select/TreeSelectTrigger.tsx). Without this the button was
-     a shrink-to-fit flex item sitting inside the field: the field looked right,
-     but the element that takes focus \u2014 and therefore the focus ring \u2014 hugged
-     the value text instead of the box. No ::before hit surface is needed the
-     way it is in a shadow root: the button now spans the host's content box,
-     so clicks land on it directly. */
+  skdx-tree-select-trigger button {${s}  }
+
+  /* controlBoxOnHost for light-DOM triggers: button must fill the host for focus ring. */
+  skdx-autocomplete-trigger button,
+  skdx-collapsible-trigger button,
+  skdx-select-trigger button,
+  skdx-table-expand-trigger button,
   skdx-tree-select-trigger button {
     display: inherit;
     align-items: inherit;
@@ -90,11 +89,7 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
     min-inline-size: 0;
   }
 
-  /* Sizing, not reset: these sit inside a field box and are expected to fill
-     it. <skdx-text-field-input> joined them when it became a painted box above:
-     the skin's border and control height are on the host now, so its <input>
-     has to span that box or the text sits in a corner of the field and only
-     part of the field takes clicks. */
+  /* Width 100% for field inputs. */
   skdx-autocomplete-input input,
   skdx-combobox-input input,
   skdx-multi-select-input input,
@@ -104,10 +99,7 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
     box-sizing: border-box;
   }
 
-  /* The host owns the field's control height, so the input has to fill it
-     vertically too \u2014 otherwise the value sits on the box's top edge instead of
-     on its centre line. Only this one needs it: the other four are inside a
-     field box that sizes itself to its content row. */
+  /* Input must fill host height vertically. */
   skdx-text-field-input input {
     height: 100%;
   }
@@ -129,17 +121,10 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
   skdx-tags-input-input,
   skdx-time-field { display: inline-block; }
 
-  /* Not optional. The display rules above are author declarations, so they
-     outrank the UA's [hidden] { display: none } and would pin these elements
-     open \u2014 <skdx-editable-input>, <skdx-editable-textarea>,
-     <skdx-form-error-summary> and <skdx-transfer-list-search> all drive their
-     own visibility by assigning this.hidden, and would show their editor,
-     their empty summary and their search box at all times. This is what the
-     hiddenHostStyles these elements lost used to do from inside a shadow
-     root.
-
-     No backticks anywhere in this block: it lives inside a template literal,
-     where one would terminate the string. */
+  /* Not optional: these author declarations outrank the UA's [hidden] rule
+     and would pin these elements open, since they drive visibility via
+     this.hidden. No backticks anywhere in this block \u2014 it lives inside a
+     template literal, where one would terminate the string. */
   skdx-color-picker-area-thumb[hidden],
   skdx-color-picker-format-select[hidden],
   skdx-color-picker-input[hidden],
@@ -158,11 +143,9 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
   skdx-number-field-input input,
   skdx-pin-input-field input,
   skdx-tags-input-input input,
-  skdx-transfer-list-search input {${n}  }
+  skdx-transfer-list-search input {${s}  }
 
-  /* Sizing, not reset: the skin paints the host, so the control has to fill it
-     rather than keep its intrinsic width \u2014 this is the rule
-     <skdx-color-picker-input> used to carry in its own static styles. */
+  /* Width 100%: skin paints host, control must fill. */
   skdx-clipboard-input input,
   skdx-color-picker-input input,
   skdx-editable-input input,
@@ -176,34 +159,12 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
     box-sizing: border-box;
   }
 
-  /* <skdx-pin-input-field> used to be excluded from the rule above, on the
-     reasoning that "a pin box is sized by the character width of the single
-     digit it holds, not by its container". That is true of the *box* and the
-     box is the host: pin-input.css gives :where(.skdx-pin-input__field) an
-     inline-size of --skdx-control-height-md and a block-size of
-     --skdx-control-height-lg. The rule governs the <input> *inside* that host,
-     which was left at a UA-intrinsic ~20-character width \u2014 225px measured in
-     Chromium, inside a 36px box. With text-align: center inherited from the
-     skin, the digit centred itself in the 225px input and landed ~112px to the
-     right of the box, outside it: a value of "12" rendered boxes that looked
-     empty. The block axis needs the same treatment for the same reason \u2014 a
-     30px-tall input inside a 42px box sits above the box's centre line \u2014 and
-     is scoped to this element because the other controls above sit in field
-     boxes whose height they are not meant to dictate. React has no equivalent
-     rule because its box *is* the <input>: the class goes straight on it
-     (react/src/pin-input/PinInputField.tsx), so the two builds only agree once
-     the control fills the host on both axes. */
+  /* Pin field input needs height 100% (sized by skin, not intrinsic height). */
   skdx-pin-input-field input {
     height: 100%;
   }
 
-  /* Restores what <skdx-dialog-content> and <skdx-alert-dialog-content> lost when
-     their native <dialog> moved to the light DOM so the skin could reach it.
-     Their static styles went with the shadow root, and this pair is the part
-     that mattered: the open host spans the viewport but is click-through, so
-     the [role=dialog] element is not a 0x0 box that a11y tooling and Playwright
-     report as hidden, while clicks still land on the dialog itself. The dialog
-     re-arms pointer events because the host disowned them. */
+  /* Dialog host spans viewport but is click-through (not 0x0 hidden). */
   skdx-dialog-content[data-state='open'],
   skdx-alert-dialog-content[data-state='open'] {
     display: block;
@@ -216,7 +177,7 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
   skdx-alert-dialog-content > dialog {
     pointer-events: auto;
   }
-}`,a=!1;function f(){if(a||typeof document>"u")return;a=!0;let t=document.createElement("style");t.setAttribute("data-skdx-light-dom-styles",""),t.textContent=c,document.head.prepend(t)}var g=o`
+}`,l=!1;function g(){if(l||typeof document>"u")return;l=!0;let t=document.createElement("style");t.setAttribute("data-skdx-light-dom-styles",""),t.textContent=x,document.head.prepend(t)}var f=d`
   :host([hidden]) {
     display: none;
   }
@@ -241,4 +202,4 @@ import{css as o,LitElement as h,unsafeCSS as p}from"lit";var x={...h.shadowRootO
   :host(skdx-table-expanded-row) {
     vertical-align: inherit;
   }
-`,l="data-skdx-inheritance",e;function m(t){let i=t.adoptedStyleSheets;if(e===void 0&&(e=null,typeof CSSStyleSheet=="function"&&i!==void 0))try{let d=new CSSStyleSheet;d.replaceSync(r),e=d}catch{}if(e!==null&&i!==void 0){if(i.includes(e))return;t.adoptedStyleSheets=[...i,e];return}if(t.querySelector(`style[${l}]`))return;let s=document.createElement("style");s.setAttribute(l,""),s.textContent=r,t.append(s)}export{m as adoptInheritanceStyles,b as controlBoxOnHost,x as delegatesFocusShadowRootOptions,g as hiddenHostStyles,f as installLightDomStyles,k as resetNativeControl};
+`,a="data-skdx-inheritance",e;function m(t){let i=t.adoptedStyleSheets;if(e===void 0&&(e=null,typeof CSSStyleSheet=="function"&&i!==void 0))try{let o=new CSSStyleSheet;o.replaceSync(r),e=o}catch{}if(e!==null&&i!==void 0){if(i.includes(e))return;t.adoptedStyleSheets=[...i,e];return}if(t.querySelector(`style[${a}]`))return;let n=document.createElement("style");n.setAttribute(a,""),n.textContent=r,t.append(n)}export{m as adoptInheritanceStyles,b as controlBoxOnHost,k as delegatesFocusShadowRootOptions,f as hiddenHostStyles,g as installLightDomStyles,h as resetNativeControl};

package/dist/internal/tabbable.cjs

@@ -0,0 +1 @@
+"use strict";var a=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var r=Object.getOwnPropertyNames;var b=Object.prototype.hasOwnProperty;var s=(e,t)=>{for(var o in t)a(e,o,{get:t[o],enumerable:!0})},E=(e,t,o,d)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of r(t))!b.call(e,n)&&n!==o&&a(e,n,{get:()=>t[n],enumerable:!(d=l(t,n))||d.enumerable});return e};var u=e=>E(a({},"__esModule",{value:!0}),e);var c={};s(c,{TABBABLE_SELECTOR:()=>i,tabbablesWithin:()=>x});module.exports=u(c);var i=["a[href]","button:not([disabled])",'input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function x(e){return Array.from(e.querySelectorAll(i))}0&&(module.exports={TABBABLE_SELECTOR,tabbablesWithin});

package/dist/internal/tabbable.d.cts

@@ -0,0 +1,11 @@
+/**
+ * Selector for tabbable elements: links, buttons, inputs, selects, textareas,
+ * and elements with positive tabindex.
+ * @internal
+ */
+export declare const TABBABLE_SELECTOR: string;
+/**
+ * Tabbable elements in `container`, light DOM only: popovers slot consumer markup.
+ * @internal
+ */
+export declare function tabbablesWithin(container: Element): HTMLElement[];

package/dist/internal/tabbable.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Selector for tabbable elements: links, buttons, inputs, selects, textareas,
+ * and elements with positive tabindex.
+ * @internal
+ */
+export declare const TABBABLE_SELECTOR: string;
+/**
+ * Tabbable elements in `container`, light DOM only: popovers slot consumer markup.
+ * @internal
+ */
+export declare function tabbablesWithin(container: Element): HTMLElement[];

package/dist/internal/tabbable.js

@@ -0,0 +1 @@
+var t=["a[href]","button:not([disabled])",'input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function n(e){return Array.from(e.querySelectorAll(t))}export{t as TABBABLE_SELECTOR,n as tabbablesWithin};

package/dist/internal/typeahead.d.cts

@@ -1,42 +1,21 @@
-/** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
+/** Plain printable character, not a shortcut or named key. */
 export declare function isTypeaheadKey(event: KeyboardEvent): boolean;
 /**
- * The text typeahead matches an item against: its explicit `data-text-value`
- * if it has one, else its rendered text.
- *
- * Raw `textContent` alone is wrong for any item that renders more than its
- * label — an item with an item indicator reads as `"✓Apple"`, so typing `a`
- * skips exactly the items that are currently selected. `data-text-value` is
- * the escape hatch, and this is the one precedence rule every matcher in the
- * repo follows.
- *
- * The items searched here are the light-DOM custom elements themselves
- * (`<skdx-select-option>`, `<skdx-menu-item>`, …), so both halves read the light
- * tree: the attribute sits on the host, and `textContent` is the host's own
- * slotted children — indicator glyph included, which is the whole problem.
- *
+ * Text typeahead matches explicit `data-text-value` or rendered text. Raw `textContent` fails for items
+ * rendering beyond label (e.g., `"✓Apple"`); `data-text-value` is the escape hatch.
  * @internal
  */
 export declare function itemText(el: Element): string;
 /**
- * The letter-key search a native `<select>` runs, owning the accumulating
- * buffer and its timer so each element that needs one just holds an instance.
- *
- * Lifted verbatim out of `<skdx-select-trigger>`, which had to inline it while
- * new util files were off-limits; `<skdx-listbox>` runs the identical search
- * over its options, which is what made the copy worth hoisting. Not to be
- * confused with `<skdx-select-content>`'s own weaker 500ms DOM typeahead, which
- * still has its own inline copy.
+ * Letter-key search like native `<select>` (accumulating buffer and timer).
+ * Hoisted from `<skdx-select-trigger>`; `<skdx-listbox>` uses identical logic.
  */
 export declare class Typeahead {
     private buffer;
     private timer?;
     /**
-     * Matches `key` against a *label collection* rather than against focusable
-     * DOM nodes. The 1s buffer means `"s"`, `"a"` in quick succession searches
-     * for `"sa"`, while the same two keys a second apart are two separate
-     * single-letter searches; repeating one letter cycles through the entries
-     * starting with it.
+     * Matches key against label collection. 1s buffer accumulates `"s"` + `"a"` = `"sa"`.
+     * Repeating one letter cycles through matching entries.
      *
      * @returns the index to move to, or `-1` for no match.
      */

package/dist/internal/typeahead.d.ts

@@ -1,42 +1,21 @@
-/** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
+/** Plain printable character, not a shortcut or named key. */
 export declare function isTypeaheadKey(event: KeyboardEvent): boolean;
 /**
- * The text typeahead matches an item against: its explicit `data-text-value`
- * if it has one, else its rendered text.
- *
- * Raw `textContent` alone is wrong for any item that renders more than its
- * label — an item with an item indicator reads as `"✓Apple"`, so typing `a`
- * skips exactly the items that are currently selected. `data-text-value` is
- * the escape hatch, and this is the one precedence rule every matcher in the
- * repo follows.
- *
- * The items searched here are the light-DOM custom elements themselves
- * (`<skdx-select-option>`, `<skdx-menu-item>`, …), so both halves read the light
- * tree: the attribute sits on the host, and `textContent` is the host's own
- * slotted children — indicator glyph included, which is the whole problem.
- *
+ * Text typeahead matches explicit `data-text-value` or rendered text. Raw `textContent` fails for items
+ * rendering beyond label (e.g., `"✓Apple"`); `data-text-value` is the escape hatch.
  * @internal
  */
 export declare function itemText(el: Element): string;
 /**
- * The letter-key search a native `<select>` runs, owning the accumulating
- * buffer and its timer so each element that needs one just holds an instance.
- *
- * Lifted verbatim out of `<skdx-select-trigger>`, which had to inline it while
- * new util files were off-limits; `<skdx-listbox>` runs the identical search
- * over its options, which is what made the copy worth hoisting. Not to be
- * confused with `<skdx-select-content>`'s own weaker 500ms DOM typeahead, which
- * still has its own inline copy.
+ * Letter-key search like native `<select>` (accumulating buffer and timer).
+ * Hoisted from `<skdx-select-trigger>`; `<skdx-listbox>` uses identical logic.
  */
 export declare class Typeahead {
     private buffer;
     private timer?;
     /**
-     * Matches `key` against a *label collection* rather than against focusable
-     * DOM nodes. The 1s buffer means `"s"`, `"a"` in quick succession searches
-     * for `"sa"`, while the same two keys a second apart are two separate
-     * single-letter searches; repeating one letter cycles through the entries
-     * starting with it.
+     * Matches key against label collection. 1s buffer accumulates `"s"` + `"a"` = `"sa"`.
+     * Repeating one letter cycles through matching entries.
      *
      * @returns the index to move to, or `-1` for no match.
      */

package/dist/kbd/Kbd.d.cts

@@ -1,14 +1,19 @@
 import { LitElement } from 'lit';
 /**
- * `<skdx-kbd>` — the Web Components implementation of the shared Kbd contract
- * (see `@skdx/shared`'s `kbdContract`). A semantic keyboard-shortcut label
- * with no state, ARIA, or behavior beyond the native `<kbd>` element it
- * wraps in shadow DOM — sizing, font, and border/chip styling are
- * brand-layer concerns applied via `skdx-kbd::part(kbd)`.
+ * Semantic keyboard-shortcut label wrapping `<kbd>` in shadow DOM. Symbol keys need `role="img"` and `aria-label` since kbd has no implicit role; letter/digit keys self-name. Put ARIA on host (display: inline-block), leaving shadow `<kbd>` presentational.
  *
  * @example
  * ```html
- * <p>Press <skdx-kbd>⌘</skdx-kbd> + <skdx-kbd>K</skdx-kbd> to open the command menu.</p>
+ * <skdx-kbd role="img" aria-label="Command">⌘</skdx-kbd>
+ * <skdx-kbd>K</skdx-kbd>
+ * ```
+ *
+ * @example Nested per spec: outer is full input, inner are keys; renders inner caps.
+ * ```html
+ * <skdx-kbd>
+ *   <skdx-kbd role="img" aria-label="Command">⌘</skdx-kbd>
+ *   <skdx-kbd>K</skdx-kbd>
+ * </skdx-kbd>
  * ```
  *
  * @csspart kbd - The native `<kbd>` element inside the shadow root.

package/dist/kbd/Kbd.d.ts

@@ -1,14 +1,19 @@
 import { LitElement } from 'lit';
 /**
- * `<skdx-kbd>` — the Web Components implementation of the shared Kbd contract
- * (see `@skdx/shared`'s `kbdContract`). A semantic keyboard-shortcut label
- * with no state, ARIA, or behavior beyond the native `<kbd>` element it
- * wraps in shadow DOM — sizing, font, and border/chip styling are
- * brand-layer concerns applied via `skdx-kbd::part(kbd)`.
+ * Semantic keyboard-shortcut label wrapping `<kbd>` in shadow DOM. Symbol keys need `role="img"` and `aria-label` since kbd has no implicit role; letter/digit keys self-name. Put ARIA on host (display: inline-block), leaving shadow `<kbd>` presentational.
  *
  * @example
  * ```html
- * <p>Press <skdx-kbd>⌘</skdx-kbd> + <skdx-kbd>K</skdx-kbd> to open the command menu.</p>
+ * <skdx-kbd role="img" aria-label="Command">⌘</skdx-kbd>
+ * <skdx-kbd>K</skdx-kbd>
+ * ```
+ *
+ * @example Nested per spec: outer is full input, inner are keys; renders inner caps.
+ * ```html
+ * <skdx-kbd>
+ *   <skdx-kbd role="img" aria-label="Command">⌘</skdx-kbd>
+ *   <skdx-kbd>K</skdx-kbd>
+ * </skdx-kbd>
  * ```
  *
  * @csspart kbd - The native `<kbd>` element inside the shadow root.

package/dist/label/Label.d.cts

@@ -1,28 +1,11 @@
 import { LitElement, type PropertyValues } from 'lit';
 /**
- * `<skdx-label>` — the Web Components implementation of the shared Label
- * contract (see `@skdx/shared`'s `labelContract`). Renders **directly into
- * light DOM** (`createRenderRoot()` returns `this` — no shadow root),
- * unlike every other component in this package.
- *
- * A native `<label for="id">` resolves `for` only against elements in its
- * own tree; inside a shadow root that means only that shadow root's own
- * subtree, so a shadow-encapsulated label could never associate with a
- * sibling light-DOM control by id — the same "IDREF can't cross a shadow
- * boundary" issue `<skdx-dialog-content>` works around by moving
- * `aria-labelledby` onto its host. Label has no host/inner split to move it
- * to (the label *is* the whole element), so it has to render in light DOM
- * instead. Consumers may also just nest the control inside `<skdx-label>`
- * rather than using `for`/id — implicit wrapping association works either
- * way, in light or shadow DOM.
- *
- * The inner `<label>` is built and its original slotted content moved into
- * it imperatively (not via a `lit-html` template): with `createRenderRoot()`
- * returning `this`, lit-html's light-DOM render only ever *appends* after
- * whatever children already exist (it has no shadow-root `<slot>` to
- * reproject through), so a declarative `html\`<label><slot></slot></label>\``
- * here would land as an empty sibling *after* the original text instead of
- * wrapping it.
+ * Light-DOM implementation of shared Label contract (no shadow root).
+ * Native `<label for="id">` resolves only within its tree; shadow-encapsulated
+ * label can't associate with sibling light-DOM control by id. No host/inner split to move
+ * `aria-labelledby` to (like `<skdx-dialog-content>`), so renders light DOM directly.
+ * Consumers may nest the control inside `<skdx-label>` instead of using `for`/id.
+ * Inner `<label>` is built imperatively to wrap slotted content (lit-html append-only).
  *
  * @example
  * ```html
@@ -30,11 +13,9 @@ import { LitElement, type PropertyValues } from 'lit';
  * <input id="email" type="email" />
  * ```
  *
- * @csspart label - The native `<label>` element. **`::part(label)` does not reach it.**
- * This element renders into the light DOM (see `createRenderRoot` below) and `::part()`
- * only matches inside a shadow root, so the `part` attribute is inert here. It is kept so
- * the name matches the shadow-DOM components and the styling-hooks contract. Style it as an
- * ordinary descendant instead: `skdx-label > label { … }`.
+ * @csspart label - The native `<label>` element. **`::part()` does not reach it**
+ * (renders in light DOM, `::part()` only matches shadow). It is kept to match the
+ * contract. Style as an ordinary descendant: `skdx-label > label { … }`.
  */
 export declare class SkdxLabel extends LitElement {
     createRenderRoot(): this;

package/dist/label/Label.d.ts

@@ -1,28 +1,11 @@
 import { LitElement, type PropertyValues } from 'lit';
 /**
- * `<skdx-label>` — the Web Components implementation of the shared Label
- * contract (see `@skdx/shared`'s `labelContract`). Renders **directly into
- * light DOM** (`createRenderRoot()` returns `this` — no shadow root),
- * unlike every other component in this package.
- *
- * A native `<label for="id">` resolves `for` only against elements in its
- * own tree; inside a shadow root that means only that shadow root's own
- * subtree, so a shadow-encapsulated label could never associate with a
- * sibling light-DOM control by id — the same "IDREF can't cross a shadow
- * boundary" issue `<skdx-dialog-content>` works around by moving
- * `aria-labelledby` onto its host. Label has no host/inner split to move it
- * to (the label *is* the whole element), so it has to render in light DOM
- * instead. Consumers may also just nest the control inside `<skdx-label>`
- * rather than using `for`/id — implicit wrapping association works either
- * way, in light or shadow DOM.
- *
- * The inner `<label>` is built and its original slotted content moved into
- * it imperatively (not via a `lit-html` template): with `createRenderRoot()`
- * returning `this`, lit-html's light-DOM render only ever *appends* after
- * whatever children already exist (it has no shadow-root `<slot>` to
- * reproject through), so a declarative `html\`<label><slot></slot></label>\``
- * here would land as an empty sibling *after* the original text instead of
- * wrapping it.
+ * Light-DOM implementation of shared Label contract (no shadow root).
+ * Native `<label for="id">` resolves only within its tree; shadow-encapsulated
+ * label can't associate with sibling light-DOM control by id. No host/inner split to move
+ * `aria-labelledby` to (like `<skdx-dialog-content>`), so renders light DOM directly.
+ * Consumers may nest the control inside `<skdx-label>` instead of using `for`/id.
+ * Inner `<label>` is built imperatively to wrap slotted content (lit-html append-only).
  *
  * @example
  * ```html
@@ -30,11 +13,9 @@ import { LitElement, type PropertyValues } from 'lit';
  * <input id="email" type="email" />
  * ```
  *
- * @csspart label - The native `<label>` element. **`::part(label)` does not reach it.**
- * This element renders into the light DOM (see `createRenderRoot` below) and `::part()`
- * only matches inside a shadow root, so the `part` attribute is inert here. It is kept so
- * the name matches the shadow-DOM components and the styling-hooks contract. Style it as an
- * ordinary descendant instead: `skdx-label > label { … }`.
+ * @csspart label - The native `<label>` element. **`::part()` does not reach it**
+ * (renders in light DOM, `::part()` only matches shadow). It is kept to match the
+ * contract. Style as an ordinary descendant: `skdx-label > label { … }`.
  */
 export declare class SkdxLabel extends LitElement {
     createRenderRoot(): this;