@skdx/web-components 0.26.0

package/dist/internal/selection.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The single/multiple selection *decision* shared by every option-list element:
+ * `<skdx-listbox>`, `<skdx-select>`, and `<skdx-combobox>`.
+ *
+ * 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.
+ */
+/**
+ * Every selected value as an array, whatever shape the consumer passed.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function toValues(value: string | string[] | undefined): string[];
+/**
+ * The value a selection becomes once `value` is chosen: replacing the
+ * selection, 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.
+ */
+export declare function nextSelection(selectedValues: string[], value: string, multiple: boolean): string | string[];

package/dist/internal/selection.js

@@ -0,0 +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};

package/dist/internal/styles.cjs

@@ -0,0 +1,244 @@
+"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=`
+  appearance: none;
+  background: none;
+  border: 0;
+  margin: 0;
+  padding: 0;
+  font: inherit;
+  color: inherit;
+  text-align: inherit;
+  cursor: inherit;
+`,m=s.css`
+  button,
+  input,
+  select,
+  textarea {
+    ${(0,s.unsafeCSS)(r)}
+  }
+`,y=s.css`
+  :host {
+    position: relative;
+  }
+  :host > button,
+  :host > a,
+  :host > label {
+    display: inherit;
+    align-items: inherit;
+    justify-content: inherit;
+    gap: inherit;
+    flex: 1;
+    align-self: stretch;
+    min-width: 0;
+  }
+  :host > button::before,
+  :host > a::before,
+  :host > label::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+  }
+`,w=`@layer skdx-light-dom {
+  skdx-autocomplete-input,
+  skdx-combobox-input,
+  skdx-multi-select-input,
+  skdx-tree-select-input,
+  skdx-tree-select-item,
+  skdx-tree-select-tree { display: block; }
+
+  skdx-command-input,
+  skdx-date-picker-time-field,
+  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. */
+  skdx-text-field-input { display: block; }
+
+  skdx-tree-select-trigger { display: inline-block; }
+
+  skdx-autocomplete-input input,
+  skdx-combobox-input input,
+  skdx-command-input input,
+  skdx-multi-select-input input,
+  skdx-password-input-field input,
+  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. */
+  skdx-tree-select-trigger button {
+    display: inherit;
+    align-items: inherit;
+    justify-content: inherit;
+    gap: inherit;
+    flex: 1;
+    align-self: stretch;
+    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. */
+  skdx-autocomplete-input input,
+  skdx-combobox-input input,
+  skdx-multi-select-input input,
+  skdx-text-field-input input,
+  skdx-tree-select-input input {
+    width: 100%;
+    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. */
+  skdx-text-field-input input {
+    height: 100%;
+  }
+
+  skdx-clipboard-input,
+  skdx-color-picker-area-thumb,
+  skdx-editable-input,
+  skdx-editable-textarea,
+  skdx-form-error-summary,
+  skdx-transfer-list-search { display: block; }
+
+  skdx-color-picker-format-select,
+  skdx-color-picker-input,
+  skdx-date-field,
+  skdx-date-picker-input,
+  skdx-number-field-input,
+  skdx-password-input-field,
+  skdx-pin-input-field,
+  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. */
+  skdx-color-picker-area-thumb[hidden],
+  skdx-color-picker-format-select[hidden],
+  skdx-color-picker-input[hidden],
+  skdx-date-field[hidden],
+  skdx-editable-input[hidden],
+  skdx-editable-textarea[hidden],
+  skdx-form-error-summary[hidden],
+  skdx-time-field[hidden],
+  skdx-transfer-list-search[hidden] { display: none; }
+
+  skdx-clipboard-input input,
+  skdx-color-picker-format-select select,
+  skdx-color-picker-input input,
+  skdx-editable-input input,
+  skdx-editable-textarea textarea,
+  skdx-number-field-input input,
+  skdx-pin-input-field input,
+  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. */
+  skdx-clipboard-input input,
+  skdx-color-picker-input input,
+  skdx-editable-input input,
+  skdx-editable-textarea textarea,
+  skdx-number-field-input input,
+  skdx-password-input-field input,
+  skdx-pin-input-field input,
+  skdx-tags-input-input input,
+  skdx-transfer-list-search input {
+    width: 100%;
+    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. */
+  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. */
+  skdx-dialog-content[data-state='open'],
+  skdx-alert-dialog-content[data-state='open'] {
+    display: block;
+    position: fixed;
+    inset: 0;
+    pointer-events: none;
+  }
+
+  skdx-dialog-content > dialog,
+  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`
+  :host([hidden]) {
+    display: none;
+  }
+`,h=`
+  slot {
+    vertical-align: inherit;
+    border-color: inherit;
+    border-radius: inherit;
+    mask-image: inherit;
+  }
+
+  :host(skdx-table-header),
+  :host(skdx-table-body),
+  :host(skdx-table-footer) {
+    vertical-align: middle;
+  }
+
+  :host(skdx-table-row),
+  :host(skdx-table-cell),
+  :host(skdx-table-header-cell),
+  :host(skdx-table-empty),
+  :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});

package/dist/internal/styles.d.cts

@@ -0,0 +1,105 @@
+/**
+ * Shared `shadowRootOptions` for elements whose shadow DOM wraps a single
+ * interactive control (native `<button>`/`<input>`) — focusing the host
+ * delegates focus straight to it, the same way a native form control works.
+ */
+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.
+ */
+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.
+ */
+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.
+ * @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.
+ * @internal
+ */
+export declare function adoptInheritanceStyles(root: ShadowRoot): void;

package/dist/internal/styles.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared `shadowRootOptions` for elements whose shadow DOM wraps a single
+ * interactive control (native `<button>`/`<input>`) — focusing the host
+ * delegates focus straight to it, the same way a native form control works.
+ */
+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.
+ */
+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.
+ */
+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.
+ * @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.
+ * @internal
+ */
+export declare function adoptInheritanceStyles(root: ShadowRoot): void;