@skdx/web-components 0.26.0 → 0.28.0

package/dist/internal/selection.d.cts

@@ -1,38 +1,97 @@
 /**
- * The single/multiple selection *decision* shared by every option-list element:
- * `<skdx-listbox>`, `<skdx-select>`, and `<skdx-combobox>`.
+ * Selection-value rule for Select, Listbox, Combobox, ToggleGroup, Accordion,
+ * ToolbarToggleGroup. Asymmetrically lenient-in, strict-out: accepts bare
+ * string or `string[]`, returns always `string[]` with `selectedValue: string | null`.
+ * Single-selection controls with multiple values throw in dev builds, take first
+ * value in production. Copied line-for-line from `@skdx/shared` (dev-only dependency).
  *
- * Only the decision lives here. React extracts these two functions out of a
- * `useSelection` hook; there is no hook to port, because the value plumbing in
- * this package is Lit reactive properties, setters, and `CustomEvent`s — and
- * each element's own side effects on commit (Combobox writing the option's text
- * back into its input and closing, Select closing and refocusing its trigger)
- * stay in that element, wrapping `selectItem` rather than being configured in.
+ * @see `@skdx/shared`'s `selection-value` contract
  */
 /**
- * Every selected value as an array, whatever shape the consumer passed.
+ * Every selected value as an array, whatever shape passed.
+ * Superseded by {@link toSelectionValues} for most families (doesn't drop empty
+ * entries or enforce single-selection rule); survives for Calendar/Transfer only.
+ * Empty string `''` means nothing selected, not selection of empty string, because
+ * `selectedValues.length` drives valueMissing and placeholder logic.
+ */
+export declare function toValues(value: string | string[] | undefined): string[];
+/** Options {@link toSelectionValues} needs to apply the single-selection rule. */
+export interface SelectionValueOptions {
+    /**
+     * Whether the control may hold more than one value at once — `multiple`, or
+     * `type === 'multiple'` on the families that spell it that way.
+     */
+    multiple: boolean;
+    /**
+     * The component and member named in the development error, for example
+     * `Select value` — the message has to say which of a page's selects is
+     * wrong, and a bare stack trace through a normalizer does not.
+     */
+    label: string;
+}
+/** The payload every single-or-many control's change event carries — the strict-out shape. */
+export interface SelectionChangeDetail {
+    /** The whole selection, always an array, in single and multiple mode alike. */
+    value: string[];
+    /** The first selected value, or `null` when nothing is selected. */
+    selectedValue: string | null;
+}
+/**
+ * Normalize selection value: `string[]` with single-selection rule enforced.
+ * Called once per control at the boundary (value/defaultValue/attribute).
+ * `undefined`, `null`, `''`, and `[]` all give `[]`. Empty entries dropped.
+ * Refuses (vs. coerces) non-string entries and multiple values on single-select.
  *
- * The `string | string[] | undefined` public value shape exists because a
- * single-select's value reads better as a bare string, but every consumer
- * downstream — `aria-selected`, chips, hidden inputs, "is this option
- * checked" — wants an array. Normalise once, here.
+ * @param input value in any accepted shape
+ * @param options cardinality and error label
+ * @returns selection array; at most one element unless `multiple`
+ * @throws in dev build if entry is non-string or single-select gets multiple
+ */
+export declare function toSelectionValues(input: string | readonly string[] | null | undefined, { multiple, label }: SelectionValueOptions): string[];
+/**
+ * The `selectedValue` half of strict-out: first selected value or `null`.
+ * Details ("first one" and "`null` vs. `undefined`") each implementation gets wrong independently.
  *
- * The one deliberate divergence from React's port: an empty string is "nothing
- * selected", not a selection of `''`. React's `value` prop is genuinely absent
- * when unset, but a custom element's reflected `value` property is `''` when
- * unset (`<skdx-combobox>` declares exactly that default), and `['']` would make
- * `selectedValues.length` — which drives `valueMissing`, the placeholder hook,
- * and the chip list — report a selection that isn't there.
+ * @param values normalized selection from {@link toSelectionValues}
+ * @returns first selected value or `null`
  */
-export declare function toValues(value: string | string[] | undefined): string[];
+export declare function selectedValueOf(values: readonly string[]): string | null;
 /**
- * The value a selection becomes once `value` is chosen: replacing the
- * selection, or toggling `value` within it when `multiple`.
+ * The selection a control holds once `value` is chosen: replacing it, or
+ * toggling `value` within it when `multiple`.
  *
- * Split out because this branch — and only this branch — is what Listbox,
- * Select, and Combobox genuinely share. Their controlled/uncontrolled plumbing
- * is framework-idiomatic and different in every package; this decision is
- * identical in all of them, and the other four framework packages carry a
- * line-for-line port of exactly this function.
+ * Always returns the array — the strict-out shape — in both cardinalities,
+ * since every single-select consumer's change handler reads this value
+ * directly.
+ *
+ * @param selected the current selection, already normalized
+ * @param value the option value the user committed
+ * @param multiple whether choosing toggles within a set rather than replacing
+ * @param deselectable whether re-choosing the only selected value clears it,
+ *   which is single-selection-only — under `multiple` a second choice always
+ *   toggles the value off regardless
+ * @returns the new selection, as an array in both cardinalities
+ */
+export declare function nextSelection(selected: readonly string[], value: string, multiple: boolean, deselectable?: boolean): string[];
+/**
+ * Parse comma-separated attribute into selection array. Attributes are strings,
+ * so `string[]` must survive as delimited. Splits once, lets
+ * {@link toSelectionValues} enforce cardinality; `value="a,b"` on single-select
+ * is a loud error, not silent selection named `a,b`.
+ *
+ * @param attribute raw string or `null` if absent
+ * @param options cardinality and error label
+ * @returns selection array
+ */
+export declare function parseSelectionAttribute(attribute: string | null | undefined, options: SelectionValueOptions): string[];
+/**
+ * Lit converter for `value`/`default-value` attributes, so property and
+ * attribute round-trip in both cardinalities. The split half of
+ * {@link parseSelectionAttribute}: converters have no element access so
+ * can't know cardinality. Elements apply {@link toSelectionValues} once
+ * `multiple`/`type` is resolved. Empty selection removes attribute.
  */
-export declare function nextSelection(selectedValues: string[], value: string, multiple: boolean): string | string[];
+export declare const selectionAttributeConverter: {
+    fromAttribute: (value: string | null) => string[];
+    toAttribute: (value: string | readonly string[] | null | undefined) => string | null;
+};

package/dist/internal/selection.d.ts

@@ -1,38 +1,97 @@
 /**
- * The single/multiple selection *decision* shared by every option-list element:
- * `<skdx-listbox>`, `<skdx-select>`, and `<skdx-combobox>`.
+ * Selection-value rule for Select, Listbox, Combobox, ToggleGroup, Accordion,
+ * ToolbarToggleGroup. Asymmetrically lenient-in, strict-out: accepts bare
+ * string or `string[]`, returns always `string[]` with `selectedValue: string | null`.
+ * Single-selection controls with multiple values throw in dev builds, take first
+ * value in production. Copied line-for-line from `@skdx/shared` (dev-only dependency).
  *
- * Only the decision lives here. React extracts these two functions out of a
- * `useSelection` hook; there is no hook to port, because the value plumbing in
- * this package is Lit reactive properties, setters, and `CustomEvent`s — and
- * each element's own side effects on commit (Combobox writing the option's text
- * back into its input and closing, Select closing and refocusing its trigger)
- * stay in that element, wrapping `selectItem` rather than being configured in.
+ * @see `@skdx/shared`'s `selection-value` contract
  */
 /**
- * Every selected value as an array, whatever shape the consumer passed.
+ * Every selected value as an array, whatever shape passed.
+ * Superseded by {@link toSelectionValues} for most families (doesn't drop empty
+ * entries or enforce single-selection rule); survives for Calendar/Transfer only.
+ * Empty string `''` means nothing selected, not selection of empty string, because
+ * `selectedValues.length` drives valueMissing and placeholder logic.
+ */
+export declare function toValues(value: string | string[] | undefined): string[];
+/** Options {@link toSelectionValues} needs to apply the single-selection rule. */
+export interface SelectionValueOptions {
+    /**
+     * Whether the control may hold more than one value at once — `multiple`, or
+     * `type === 'multiple'` on the families that spell it that way.
+     */
+    multiple: boolean;
+    /**
+     * The component and member named in the development error, for example
+     * `Select value` — the message has to say which of a page's selects is
+     * wrong, and a bare stack trace through a normalizer does not.
+     */
+    label: string;
+}
+/** The payload every single-or-many control's change event carries — the strict-out shape. */
+export interface SelectionChangeDetail {
+    /** The whole selection, always an array, in single and multiple mode alike. */
+    value: string[];
+    /** The first selected value, or `null` when nothing is selected. */
+    selectedValue: string | null;
+}
+/**
+ * Normalize selection value: `string[]` with single-selection rule enforced.
+ * Called once per control at the boundary (value/defaultValue/attribute).
+ * `undefined`, `null`, `''`, and `[]` all give `[]`. Empty entries dropped.
+ * Refuses (vs. coerces) non-string entries and multiple values on single-select.
  *
- * The `string | string[] | undefined` public value shape exists because a
- * single-select's value reads better as a bare string, but every consumer
- * downstream — `aria-selected`, chips, hidden inputs, "is this option
- * checked" — wants an array. Normalise once, here.
+ * @param input value in any accepted shape
+ * @param options cardinality and error label
+ * @returns selection array; at most one element unless `multiple`
+ * @throws in dev build if entry is non-string or single-select gets multiple
+ */
+export declare function toSelectionValues(input: string | readonly string[] | null | undefined, { multiple, label }: SelectionValueOptions): string[];
+/**
+ * The `selectedValue` half of strict-out: first selected value or `null`.
+ * Details ("first one" and "`null` vs. `undefined`") each implementation gets wrong independently.
  *
- * The one deliberate divergence from React's port: an empty string is "nothing
- * selected", not a selection of `''`. React's `value` prop is genuinely absent
- * when unset, but a custom element's reflected `value` property is `''` when
- * unset (`<skdx-combobox>` declares exactly that default), and `['']` would make
- * `selectedValues.length` — which drives `valueMissing`, the placeholder hook,
- * and the chip list — report a selection that isn't there.
+ * @param values normalized selection from {@link toSelectionValues}
+ * @returns first selected value or `null`
  */
-export declare function toValues(value: string | string[] | undefined): string[];
+export declare function selectedValueOf(values: readonly string[]): string | null;
 /**
- * The value a selection becomes once `value` is chosen: replacing the
- * selection, or toggling `value` within it when `multiple`.
+ * The selection a control holds once `value` is chosen: replacing it, or
+ * toggling `value` within it when `multiple`.
  *
- * Split out because this branch — and only this branch — is what Listbox,
- * Select, and Combobox genuinely share. Their controlled/uncontrolled plumbing
- * is framework-idiomatic and different in every package; this decision is
- * identical in all of them, and the other four framework packages carry a
- * line-for-line port of exactly this function.
+ * Always returns the array — the strict-out shape — in both cardinalities,
+ * since every single-select consumer's change handler reads this value
+ * directly.
+ *
+ * @param selected the current selection, already normalized
+ * @param value the option value the user committed
+ * @param multiple whether choosing toggles within a set rather than replacing
+ * @param deselectable whether re-choosing the only selected value clears it,
+ *   which is single-selection-only — under `multiple` a second choice always
+ *   toggles the value off regardless
+ * @returns the new selection, as an array in both cardinalities
+ */
+export declare function nextSelection(selected: readonly string[], value: string, multiple: boolean, deselectable?: boolean): string[];
+/**
+ * Parse comma-separated attribute into selection array. Attributes are strings,
+ * so `string[]` must survive as delimited. Splits once, lets
+ * {@link toSelectionValues} enforce cardinality; `value="a,b"` on single-select
+ * is a loud error, not silent selection named `a,b`.
+ *
+ * @param attribute raw string or `null` if absent
+ * @param options cardinality and error label
+ * @returns selection array
+ */
+export declare function parseSelectionAttribute(attribute: string | null | undefined, options: SelectionValueOptions): string[];
+/**
+ * Lit converter for `value`/`default-value` attributes, so property and
+ * attribute round-trip in both cardinalities. The split half of
+ * {@link parseSelectionAttribute}: converters have no element access so
+ * can't know cardinality. Elements apply {@link toSelectionValues} once
+ * `multiple`/`type` is resolved. Empty selection removes attribute.
  */
-export declare function nextSelection(selectedValues: string[], value: string, multiple: boolean): string | string[];
+export declare const selectionAttributeConverter: {
+    fromAttribute: (value: string | null) => string[];
+    toAttribute: (value: string | readonly string[] | null | undefined) => string | null;
+};

package/dist/internal/selection.js

@@ -1 +1 @@
-function o(r){return Array.isArray(r)?r:r?[r]:[]}function g(r,n,t){return t?r.includes(n)?r.filter(i=>i!==n):[...r,n]:n}export{g as nextSelection,o as toValues};
+import{isDevMode as s}from"../utils/is-dev-mode.js";function g(n){return Array.isArray(n)?n:n?[n]:[]}function u(){try{let n=process.env.NODE_ENV;return n!==void 0&&n!=="production"}catch{return!1}}function o(n){if(u())throw new RangeError(n);s()&&console.error(n)}function a(n,{multiple:t,label:e}){let l=Array.isArray(n)?n:n==null?[]:[n],r=[];for(let i of l){if(typeof i!="string"){o(`[skdx] ${e}: a selection value must be a string, got ${i===null?"null":typeof i} (${JSON.stringify(i)}). If this is a change payload, read its \`value\` \u2014 the event carries { value, selectedValue } and only \`value\` goes back in.`);continue}i!==""&&r.push(i)}return t||r.length<=1?r:(o(`[skdx] ${e}: a single-selection control was given ${r.length} values (${r.join(", ")}). Only one can be held \u2014 pass a single value, or turn the control multiple. Set multiple (or type="multiple") to keep them all.`),[r[0]])}function f(n){return n.length>0?n[0]:null}function p(n,t,e,l=!1){return e?n.includes(t)?n.filter(r=>r!==t):[...n,t]:l&&n.length===1&&n[0]===t?[]:[t]}function d(n,t){return n==null?[]:a(n.split(",").map(e=>e.trim()),t)}var y={fromAttribute:n=>n==null?[]:n.split(",").map(t=>t.trim()),toAttribute:n=>{if(n==null)return null;let t=(Array.isArray(n)?n:[n]).filter(e=>e!=="");return t.length>0?t.join(","):null}};export{p as nextSelection,d as parseSelectionAttribute,f as selectedValueOf,y as selectionAttributeConverter,a as toSelectionValues,g as toValues};

package/dist/internal/space.cjs

@@ -0,0 +1 @@
+"use strict";var d=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var S=(n,e)=>{for(var t in e)d(n,t,{get:e[t],enumerable:!0})},c=(n,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of f(e))!p.call(n,r)&&r!==t&&d(n,r,{get:()=>e[r],enumerable:!(i=s(e,r))||i.enumerable});return n};var o=n=>c(d({},"__esModule",{value:!0}),n);var u={};S(u,{resolveSpace:()=>g});module.exports=o(u);var x=new Set(["1","2","3","4","5","6","8","10","12","16"]);function g(n){if(!(n===void 0||n===""))return x.has(n)?`var(--skdx-space-${n})`:n}0&&(module.exports={resolveSpace});

package/dist/internal/space.d.cts

@@ -0,0 +1,7 @@
+/** A scale key resolved to a design token, or any other string passed through verbatim. */
+export type SkdxSpace = '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' | (string & {});
+/**
+ * Resolves a scale key to its `var(--skdx-space-<key>)` token; any other string passes through verbatim.
+ * @internal
+ */
+export declare function resolveSpace(value: string | undefined): string | undefined;

package/dist/internal/space.d.ts

@@ -0,0 +1,7 @@
+/** A scale key resolved to a design token, or any other string passed through verbatim. */
+export type SkdxSpace = '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' | (string & {});
+/**
+ * Resolves a scale key to its `var(--skdx-space-<key>)` token; any other string passes through verbatim.
+ * @internal
+ */
+export declare function resolveSpace(value: string | undefined): string | undefined;

package/dist/internal/space.js

@@ -0,0 +1 @@
+var e=new Set(["1","2","3","4","5","6","8","10","12","16"]);function r(n){if(!(n===void 0||n===""))return e.has(n)?`var(--skdx-space-${n})`:n}export{r as resolveSpace};

package/dist/internal/styles.cjs

@@ -1,4 +1,4 @@
-"use strict";var a=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var x=Object.prototype.hasOwnProperty;var k=(t,e)=>{for(var i in e)a(t,i,{get:e[i],enumerable:!0})},b=(t,e,i,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let d of u(e))!x.call(t,d)&&d!==i&&a(t,d,{get:()=>e[d],enumerable:!(o=c(e,d))||o.enumerable});return t};var f=t=>b(a({},"__esModule",{value:!0}),t);var E={};k(E,{adoptInheritanceStyles:()=>T,controlBoxOnHost:()=>y,delegatesFocusShadowRootOptions:()=>g,hiddenHostStyles:()=>v,installLightDomStyles:()=>S,resetNativeControl:()=>m});module.exports=f(E);var s=require("lit"),g={...s.LitElement.shadowRootOptions,delegatesFocus:!0},r=`
+"use strict";var l=Object.defineProperty;var x=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var h=(t,e)=>{for(var i in e)l(t,i,{get:e[i],enumerable:!0})},b=(t,e,i,d)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of c(e))!k.call(t,o)&&o!==i&&l(t,o,{get:()=>e[o],enumerable:!(d=x(e,o))||d.enumerable});return t};var g=t=>b(l({},"__esModule",{value:!0}),t);var C={};h(C,{adoptInheritanceStyles:()=>E,controlBoxOnHost:()=>y,delegatesFocusShadowRootOptions:()=>f,hiddenHostStyles:()=>v,installLightDomStyles:()=>w,resetNativeControl:()=>m});module.exports=g(C);var n=require("lit"),f={...n.LitElement.shadowRootOptions,delegatesFocus:!0},r=`
   appearance: none;
   background: none;
   border: 0;
@@ -8,14 +8,14 @@
   color: inherit;
   text-align: inherit;
   cursor: inherit;
-`,m=s.css`
+`,m=n.css`
   button,
   input,
   select,
   textarea {
-    ${(0,s.unsafeCSS)(r)}
+    ${(0,n.unsafeCSS)(r)}
   }
-`,y=s.css`
+`,y=n.css`
   :host {
     position: relative;
   }
@@ -37,7 +37,7 @@
     position: absolute;
     inset: 0;
   }
-`,w=`@layer skdx-light-dom {
+`,S=`@layer skdx-light-dom {
   skdx-autocomplete-input,
   skdx-combobox-input,
   skdx-multi-select-input,
@@ -50,36 +50,35 @@
   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 {${r}  }
 
-  /* 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. */
+  /* 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 @@
     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 @@
     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 @@
   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],
@@ -160,9 +145,7 @@
   skdx-tags-input-input input,
   skdx-transfer-list-search input {${r}  }
 
-  /* 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 @@
     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,11 +177,11 @@
   skdx-alert-dialog-content > dialog {
     pointer-events: auto;
   }
-}`,l=!1;function S(){if(l||typeof document>"u")return;l=!0;let t=document.createElement("style");t.setAttribute("data-skdx-light-dom-styles",""),t.textContent=w,document.head.prepend(t)}var v=s.css`
+}`,a=!1;function w(){if(a||typeof document>"u")return;a=!0;let t=document.createElement("style");t.setAttribute("data-skdx-light-dom-styles",""),t.textContent=S,document.head.prepend(t)}var v=n.css`
   :host([hidden]) {
     display: none;
   }
-`,h=`
+`,p=`
   slot {
     vertical-align: inherit;
     border-color: inherit;
@@ -241,4 +202,4 @@
   :host(skdx-table-expanded-row) {
     vertical-align: inherit;
   }
-`,p="data-skdx-inheritance",n;function T(t){let e=t.adoptedStyleSheets;if(n===void 0&&(n=null,typeof CSSStyleSheet=="function"&&e!==void 0))try{let o=new CSSStyleSheet;o.replaceSync(h),n=o}catch{}if(n!==null&&e!==void 0){if(e.includes(n))return;t.adoptedStyleSheets=[...e,n];return}if(t.querySelector(`style[${p}]`))return;let i=document.createElement("style");i.setAttribute(p,""),i.textContent=h,t.append(i)}0&&(module.exports={adoptInheritanceStyles,controlBoxOnHost,delegatesFocusShadowRootOptions,hiddenHostStyles,installLightDomStyles,resetNativeControl});
+`,u="data-skdx-inheritance",s;function E(t){let e=t.adoptedStyleSheets;if(s===void 0&&(s=null,typeof CSSStyleSheet=="function"&&e!==void 0))try{let d=new CSSStyleSheet;d.replaceSync(p),s=d}catch{}if(s!==null&&e!==void 0){if(e.includes(s))return;t.adoptedStyleSheets=[...e,s];return}if(t.querySelector(`style[${u}]`))return;let i=document.createElement("style");i.setAttribute(u,""),i.textContent=p,t.append(i)}0&&(module.exports={adoptInheritanceStyles,controlBoxOnHost,delegatesFocusShadowRootOptions,hiddenHostStyles,installLightDomStyles,resetNativeControl});

package/dist/internal/styles.d.cts

@@ -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;