@skdx/web-components 0.28.0 → 0.29.0

package/dist/internal/selection-attribute.cjs

@@ -0,0 +1 @@
+"use strict";var l=Object.defineProperty;var e=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var o=Object.prototype.hasOwnProperty;var g=(t,n)=>{for(var r in n)l(t,r,{get:n[r],enumerable:!0})},A=(t,n,r,s)=>{if(n&&typeof n=="object"||typeof n=="function")for(let i of u(n))!o.call(t,i)&&i!==r&&l(t,i,{get:()=>n[i],enumerable:!(s=e(n,i))||s.enumerable});return t};var f=t=>A(l({},"__esModule",{value:!0}),t);var c={};g(c,{selectionAttributeConverter:()=>b});module.exports=f(c);var b={fromAttribute:t=>t==null?[]:t.split(",").map(n=>n.trim()),toAttribute:t=>{if(t==null)return null;let n=(Array.isArray(t)?t:[t]).filter(r=>r!=="");return n.length>0?n.join(","):null}};0&&(module.exports={selectionAttributeConverter});

package/dist/internal/selection-attribute.d.cts

@@ -0,0 +1,5 @@
+/** Lit converter for `value`/`default-value` attributes so property and attribute round-trip; cardinality is enforced later via `toSelectionValues`. */
+export declare const selectionAttributeConverter: {
+    fromAttribute: (value: string | null) => string[];
+    toAttribute: (value: string | readonly string[] | null | undefined) => string | null;
+};

package/dist/internal/selection-attribute.d.ts

@@ -0,0 +1,5 @@
+/** Lit converter for `value`/`default-value` attributes so property and attribute round-trip; cardinality is enforced later via `toSelectionValues`. */
+export declare const selectionAttributeConverter: {
+    fromAttribute: (value: string | null) => string[];
+    toAttribute: (value: string | readonly string[] | null | undefined) => string | null;
+};

package/dist/internal/selection-attribute.js

@@ -0,0 +1 @@
+var i={fromAttribute:t=>t==null?[]:t.split(",").map(n=>n.trim()),toAttribute:t=>{if(t==null)return null;let n=(Array.isArray(t)?t:[t]).filter(r=>r!=="");return n.length>0?n.join(","):null}};export{i as selectionAttributeConverter};

package/dist/internal/selection-card.cjs

@@ -0,0 +1,15 @@
+"use strict";var c=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var h=Object.prototype.hasOwnProperty;var u=(t,e)=>{for(var s in e)c(t,s,{get:e[s],enumerable:!0})},y=(t,e,s,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of p(e))!h.call(t,r)&&r!==s&&c(t,r,{get:()=>e[r],enumerable:!(i=a(e,r))||i.enumerable});return t};var v=t=>y(c({},"__esModule",{value:!0}),t);var b={};u(b,{SkdxSelectionCardIndicatorBase:()=>n,SkdxSelectionCardPartBase:()=>l});module.exports=v(b);var o=require("lit"),d=require("./define.cjs"),l=class extends o.LitElement{constructor(){super(...arguments);this.rootSelector="";this.resyncOnDisconnect=!0;this.rootEl=null}connectedCallback(){super.connectedCallback(),this.rootEl=this.closest(this.rootSelector),this.rootEl&&(0,d.whenUpgraded)(this.rootEl,()=>this.rootEl?.syncParts())}disconnectedCallback(){let s=this.rootEl;super.disconnectedCallback(),this.resyncOnDisconnect&&queueMicrotask(()=>s?.syncParts())}render(){return o.html`<slot></slot>`}};l.styles=o.css`
+    :host {
+      display: block;
+    }
+    :host([hidden]) {
+      display: none;
+    }
+  `;var n=class extends l{constructor(){super(...arguments);this.resyncOnDisconnect=!1}connectedCallback(){this.setAttribute("aria-hidden","true"),super.connectedCallback()}};n.styles=o.css`
+    :host {
+      display: inline-block;
+    }
+    :host([hidden]) {
+      display: none;
+    }
+  `;0&&(module.exports={SkdxSelectionCardIndicatorBase,SkdxSelectionCardPartBase});

package/dist/internal/selection-card.d.cts

@@ -0,0 +1,34 @@
+import { LitElement, type TemplateResult } from 'lit';
+/** The card root a part pushes its presence back to. @internal */
+export interface SkdxSelectionCardRoot extends Element {
+    /** Re-reads which optional parts are mounted and rewires the control's ARIA at them. */
+    syncParts(): void;
+}
+/**
+ * The engine every optional selection-card part shares: it finds the card root,
+ * waits for it to upgrade, and tells it to rewire the control's ARIA whenever
+ * the part arrives or leaves.
+ * @internal
+ */
+export declare class SkdxSelectionCardPartBase extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** @internal The card tag this part belongs to, per family. */
+    protected rootSelector: string;
+    /** @internal Whether the control's ARIA has to be rewired when this part leaves. */
+    protected resyncOnDisconnect: boolean;
+    /** @internal The card this part is mounted in, resolved on connect. */
+    protected rootEl: SkdxSelectionCardRoot | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    render(): TemplateResult;
+}
+/**
+ * The decorative glyph on a selection card: `aria-hidden`, and mounted whether
+ * or not the card is selected, since the card itself carries the state.
+ * @internal
+ */
+export declare class SkdxSelectionCardIndicatorBase extends SkdxSelectionCardPartBase {
+    static styles: import("lit").CSSResult;
+    protected resyncOnDisconnect: boolean;
+    connectedCallback(): void;
+}

package/dist/internal/selection-card.d.ts

@@ -0,0 +1,34 @@
+import { LitElement, type TemplateResult } from 'lit';
+/** The card root a part pushes its presence back to. @internal */
+export interface SkdxSelectionCardRoot extends Element {
+    /** Re-reads which optional parts are mounted and rewires the control's ARIA at them. */
+    syncParts(): void;
+}
+/**
+ * The engine every optional selection-card part shares: it finds the card root,
+ * waits for it to upgrade, and tells it to rewire the control's ARIA whenever
+ * the part arrives or leaves.
+ * @internal
+ */
+export declare class SkdxSelectionCardPartBase extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** @internal The card tag this part belongs to, per family. */
+    protected rootSelector: string;
+    /** @internal Whether the control's ARIA has to be rewired when this part leaves. */
+    protected resyncOnDisconnect: boolean;
+    /** @internal The card this part is mounted in, resolved on connect. */
+    protected rootEl: SkdxSelectionCardRoot | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    render(): TemplateResult;
+}
+/**
+ * The decorative glyph on a selection card: `aria-hidden`, and mounted whether
+ * or not the card is selected, since the card itself carries the state.
+ * @internal
+ */
+export declare class SkdxSelectionCardIndicatorBase extends SkdxSelectionCardPartBase {
+    static styles: import("lit").CSSResult;
+    protected resyncOnDisconnect: boolean;
+    connectedCallback(): void;
+}

package/dist/internal/selection-card.js

@@ -0,0 +1,15 @@
+import{css as o,html as n,LitElement as c}from"lit";import{whenUpgraded as i}from"./define.js";var e=class extends c{constructor(){super(...arguments);this.rootSelector="";this.resyncOnDisconnect=!0;this.rootEl=null}connectedCallback(){super.connectedCallback(),this.rootEl=this.closest(this.rootSelector),this.rootEl&&i(this.rootEl,()=>this.rootEl?.syncParts())}disconnectedCallback(){let l=this.rootEl;super.disconnectedCallback(),this.resyncOnDisconnect&&queueMicrotask(()=>l?.syncParts())}render(){return n`<slot></slot>`}};e.styles=o`
+    :host {
+      display: block;
+    }
+    :host([hidden]) {
+      display: none;
+    }
+  `;var t=class extends e{constructor(){super(...arguments);this.resyncOnDisconnect=!1}connectedCallback(){this.setAttribute("aria-hidden","true"),super.connectedCallback()}};t.styles=o`
+    :host {
+      display: inline-block;
+    }
+    :host([hidden]) {
+      display: none;
+    }
+  `;export{t as SkdxSelectionCardIndicatorBase,e as SkdxSelectionCardPartBase};

package/dist/internal/selection-group.cjs

@@ -0,0 +1,5 @@
+"use strict";var n=Object.defineProperty;var h=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var m=(i,t)=>{for(var e in t)n(i,e,{get:t[e],enumerable:!0})},v=(i,t,e,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of y(t))!c.call(i,r)&&r!==e&&n(i,r,{get:()=>t[r],enumerable:!(a=h(t,r))||a.enumerable});return i};var b=i=>v(n({},"__esModule",{value:!0}),i),o=(i,t,e,a)=>{for(var r=a>1?void 0:a?h(t,e):t,p=i.length-1,f;p>=0;p--)(f=i[p])&&(r=(a?f(t,e,r):f(r))||r);return a&&r&&n(t,e,r),r};var g={};m(g,{SkdxSelectionGroupBase:()=>s});module.exports=b(g);var d=require("lit"),l=require("lit/decorators.js"),u=require("./form-associated.cjs");var s=class extends(0,u.FormAssociated)(d.LitElement){constructor(){super(...arguments);this.required=!1;this.disabled=!1;this.readOnly=!1;this.invalid=!1;this.parts=[];this.groupRole="group";this.fillAnatomy=()=>{};this.refreshParts=()=>{for(let e of this.parts)e.refresh()}}syncHostAttributes(){this.toggleAttribute("data-disabled",this.disabled),this.toggleAttribute("data-readonly",this.readOnly),this.toggleAttribute("data-invalid",this.invalid),this.invalid?this.setAttribute("aria-invalid","true"):this.removeAttribute("aria-invalid")}connectedCallback(){super.connectedCallback(),this.setAttribute("role",this.groupRole)}registerPart(e){this.parts.push(e)}unregisterPart(e){let a=this.parts.indexOf(e);a!==-1&&this.parts.splice(a,1)}render(){return d.html`<slot @slotchange=${this.fillAnatomy}></slot>`}};s.styles=d.css`
+    :host {
+      display: block;
+    }
+  `,o([(0,l.property)({type:String,reflect:!0})],s.prototype,"name",2),o([(0,l.property)({type:Boolean,reflect:!0})],s.prototype,"required",2),o([(0,l.property)({type:Boolean,reflect:!0})],s.prototype,"disabled",2),o([(0,l.property)({type:Boolean,reflect:!0,attribute:"readonly"})],s.prototype,"readOnly",2),o([(0,l.property)({type:Boolean,reflect:!0})],s.prototype,"invalid",2),o([(0,l.property)({attribute:"required-message"})],s.prototype,"requiredMessage",2),o([(0,l.property)({attribute:!1})],s.prototype,"options",2);0&&(module.exports={SkdxSelectionGroupBase});

package/dist/internal/selection-group.d.cts

@@ -0,0 +1,51 @@
+import { LitElement, type TemplateResult } from 'lit';
+import type { SkdxOptionItemDescriptor } from './options.cjs';
+/** A registered member that can be told to re-sync its own host attributes. @internal */
+export interface RefreshableGroupPart {
+    refresh(): void;
+}
+declare const SkdxSelectionGroupBase_base: typeof LitElement & (new (...args: any[]) => import("./form-associated.cjs").SkdxFormAssociated) & {
+    formAssociated: boolean;
+};
+/**
+ * The engine behind both selection groups: form association, the shared
+ * disabled/read-only/required/invalid axes, the registry of members that
+ * re-render when the selection moves, and the derived-anatomy hook. The shape
+ * of `value` — one string, or many — stays with the subclass, and so does the
+ * ARIA its role is allowed to carry.
+ * @internal
+ */
+export declare class SkdxSelectionGroupBase<TPart extends RefreshableGroupPart> extends SkdxSelectionGroupBase_base {
+    static styles: import("lit").CSSResult;
+    /** Name submitted with the form's data; unset means the group's value isn't submitted. @default undefined */
+    name?: string;
+    /** Marks the group as required for native form validation. @default false */
+    required: boolean;
+    /** Disables every item in the group. @default false */
+    disabled: boolean;
+    /** Freezes the selection without freezing the group: focus still moves, but neither focus nor click changes the value. @default false */
+    readOnly: boolean;
+    /** Marks the group as invalid, exposed as `aria-invalid`/`data-invalid`. @default false */
+    invalid: boolean;
+    /** Replaces the message the browser shows when a `required` group is submitted empty. @default undefined */
+    requiredMessage?: string;
+    /** The choices, in order — one item derived per entry. Property only. @default undefined — nothing derived, hand-composed children stand. */
+    options?: readonly SkdxOptionItemDescriptor[];
+    /** @internal The members that re-render when the selection, or an axis they read, moves. */
+    protected readonly parts: TPart[];
+    /** @internal The widget role the group host claims. */
+    protected groupRole: string;
+    /** @internal Rebuilds the derived anatomy, or leaves hand-composed children alone. */
+    protected readonly fillAnatomy: () => void;
+    /** @internal Writes the ARIA and data attributes this role is allowed to carry. */
+    protected syncHostAttributes(): void;
+    connectedCallback(): void;
+    /** @internal Called by a mounting member. */
+    registerPart(part: TPart): void;
+    /** @internal Called by an unmounting member. */
+    unregisterPart(part: TPart): void;
+    /** @internal Tells every member to re-read the group. */
+    protected readonly refreshParts: () => void;
+    render(): TemplateResult;
+}
+export {};

package/dist/internal/selection-group.d.ts

@@ -0,0 +1,51 @@
+import { LitElement, type TemplateResult } from 'lit';
+import type { SkdxOptionItemDescriptor } from './options.js';
+/** A registered member that can be told to re-sync its own host attributes. @internal */
+export interface RefreshableGroupPart {
+    refresh(): void;
+}
+declare const SkdxSelectionGroupBase_base: typeof LitElement & (new (...args: any[]) => import("./form-associated.js").SkdxFormAssociated) & {
+    formAssociated: boolean;
+};
+/**
+ * The engine behind both selection groups: form association, the shared
+ * disabled/read-only/required/invalid axes, the registry of members that
+ * re-render when the selection moves, and the derived-anatomy hook. The shape
+ * of `value` — one string, or many — stays with the subclass, and so does the
+ * ARIA its role is allowed to carry.
+ * @internal
+ */
+export declare class SkdxSelectionGroupBase<TPart extends RefreshableGroupPart> extends SkdxSelectionGroupBase_base {
+    static styles: import("lit").CSSResult;
+    /** Name submitted with the form's data; unset means the group's value isn't submitted. @default undefined */
+    name?: string;
+    /** Marks the group as required for native form validation. @default false */
+    required: boolean;
+    /** Disables every item in the group. @default false */
+    disabled: boolean;
+    /** Freezes the selection without freezing the group: focus still moves, but neither focus nor click changes the value. @default false */
+    readOnly: boolean;
+    /** Marks the group as invalid, exposed as `aria-invalid`/`data-invalid`. @default false */
+    invalid: boolean;
+    /** Replaces the message the browser shows when a `required` group is submitted empty. @default undefined */
+    requiredMessage?: string;
+    /** The choices, in order — one item derived per entry. Property only. @default undefined — nothing derived, hand-composed children stand. */
+    options?: readonly SkdxOptionItemDescriptor[];
+    /** @internal The members that re-render when the selection, or an axis they read, moves. */
+    protected readonly parts: TPart[];
+    /** @internal The widget role the group host claims. */
+    protected groupRole: string;
+    /** @internal Rebuilds the derived anatomy, or leaves hand-composed children alone. */
+    protected readonly fillAnatomy: () => void;
+    /** @internal Writes the ARIA and data attributes this role is allowed to carry. */
+    protected syncHostAttributes(): void;
+    connectedCallback(): void;
+    /** @internal Called by a mounting member. */
+    registerPart(part: TPart): void;
+    /** @internal Called by an unmounting member. */
+    unregisterPart(part: TPart): void;
+    /** @internal Tells every member to re-read the group. */
+    protected readonly refreshParts: () => void;
+    render(): TemplateResult;
+}
+export {};

package/dist/internal/selection-group.js

@@ -0,0 +1,5 @@
+var p=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var r=(l,o,e,i)=>{for(var s=i>1?void 0:i?f(o,e):o,d=l.length-1,n;d>=0;d--)(n=l[d])&&(s=(i?n(o,e,s):n(s))||s);return i&&s&&p(o,e,s),s};import{css as h,html as u,LitElement as y}from"lit";import{property as a}from"lit/decorators.js";import{FormAssociated as c}from"./form-associated.js";var t=class extends c(y){constructor(){super(...arguments);this.required=!1;this.disabled=!1;this.readOnly=!1;this.invalid=!1;this.parts=[];this.groupRole="group";this.fillAnatomy=()=>{};this.refreshParts=()=>{for(let e of this.parts)e.refresh()}}syncHostAttributes(){this.toggleAttribute("data-disabled",this.disabled),this.toggleAttribute("data-readonly",this.readOnly),this.toggleAttribute("data-invalid",this.invalid),this.invalid?this.setAttribute("aria-invalid","true"):this.removeAttribute("aria-invalid")}connectedCallback(){super.connectedCallback(),this.setAttribute("role",this.groupRole)}registerPart(e){this.parts.push(e)}unregisterPart(e){let i=this.parts.indexOf(e);i!==-1&&this.parts.splice(i,1)}render(){return u`<slot @slotchange=${this.fillAnatomy}></slot>`}};t.styles=h`
+    :host {
+      display: block;
+    }
+  `,r([a({type:String,reflect:!0})],t.prototype,"name",2),r([a({type:Boolean,reflect:!0})],t.prototype,"required",2),r([a({type:Boolean,reflect:!0})],t.prototype,"disabled",2),r([a({type:Boolean,reflect:!0,attribute:"readonly"})],t.prototype,"readOnly",2),r([a({type:Boolean,reflect:!0})],t.prototype,"invalid",2),r([a({attribute:"required-message"})],t.prototype,"requiredMessage",2),r([a({attribute:!1})],t.prototype,"options",2);export{t as SkdxSelectionGroupBase};

package/dist/internal/selection.cjs

@@ -1 +1 @@
-"use strict";var o=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var f=Object.prototype.hasOwnProperty;var p=(n,t)=>{for(var r in t)o(n,r,{get:t[r],enumerable:!0})},d=(n,t,r,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of g(t))!f.call(n,e)&&e!==r&&o(n,e,{get:()=>t[e],enumerable:!(i=c(t,e))||i.enumerable});return n};var y=n=>d(o({},"__esModule",{value:!0}),n);var b={};p(b,{nextSelection:()=>V,parseSelectionAttribute:()=>A,selectedValueOf:()=>x,selectionAttributeConverter:()=>S,toSelectionValues:()=>a,toValues:()=>h});module.exports=y(b);var u=require("../utils/is-dev-mode.cjs");function h(n){return Array.isArray(n)?n:n?[n]:[]}function m(){try{let n=process.env.NODE_ENV;return n!==void 0&&n!=="production"}catch{return!1}}function s(n){if(m())throw new RangeError(n);(0,u.isDevMode)()&&console.error(n)}function a(n,{multiple:t,label:r}){let i=Array.isArray(n)?n:n==null?[]:[n],e=[];for(let l of i){if(typeof l!="string"){s(`[skdx] ${r}: a selection value must be a string, got ${l===null?"null":typeof l} (${JSON.stringify(l)}). If this is a change payload, read its \`value\` \u2014 the event carries { value, selectedValue } and only \`value\` goes back in.`);continue}l!==""&&e.push(l)}return t||e.length<=1?e:(s(`[skdx] ${r}: a single-selection control was given ${e.length} values (${e.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.`),[e[0]])}function x(n){return n.length>0?n[0]:null}function V(n,t,r,i=!1){return r?n.includes(t)?n.filter(e=>e!==t):[...n,t]:i&&n.length===1&&n[0]===t?[]:[t]}function A(n,t){return n==null?[]:a(n.split(",").map(r=>r.trim()),t)}var S={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(r=>r!=="");return t.length>0?t.join(","):null}};0&&(module.exports={nextSelection,parseSelectionAttribute,selectedValueOf,selectionAttributeConverter,toSelectionValues,toValues});
+"use strict";var l=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var f=Object.prototype.hasOwnProperty;var p=(e,n)=>{for(var r in n)l(e,r,{get:n[r],enumerable:!0})},d=(e,n,r,i)=>{if(n&&typeof n=="object"||typeof n=="function")for(let t of c(n))!f.call(e,t)&&t!==r&&l(e,t,{get:()=>n[t],enumerable:!(i=g(n,t))||i.enumerable});return e};var y=e=>d(l({},"__esModule",{value:!0}),e);var b={};p(b,{nextSelection:()=>m,parseSelectionAttribute:()=>V,sameSelection:()=>x,selectedValueOf:()=>S,toSelectionValues:()=>u,toValues:()=>h});module.exports=y(b);var a=require("./dev-mode.cjs");function h(e){return Array.isArray(e)?e:e?[e]:[]}function s(e){if((0,a.isDevMode)())throw new RangeError(e);console.error(e)}function u(e,{multiple:n,label:r}){let i;Array.isArray(e)?i=e:i=e==null?[]:[e];let t=[];for(let o of i){if(typeof o!="string"){s(`[skdx] ${r}: a selection value must be a string, got ${o===null?"null":typeof o} (${JSON.stringify(o)}). If this is a change payload, read its \`value\` \u2014 the event carries { value, selectedValue } and only \`value\` goes back in.`);continue}o!==""&&t.push(o)}return n||t.length<=1?t:(s(`[skdx] ${r}: a single-selection control was given ${t.length} values (${t.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.`),[t[0]])}function S(e){return e.length>0?e[0]:null}function m(e,n,r,i=!1){return r?e.includes(n)?e.filter(t=>t!==n):[...e,n]:i&&e.length===1&&e[0]===n?[]:[n]}function x(e,n){return e.length===n.length&&e.every((r,i)=>r===n[i])}function V(e,n){return e==null?[]:u(e.split(",").map(r=>r.trim()),n)}0&&(module.exports={nextSelection,parseSelectionAttribute,sameSelection,selectedValueOf,toSelectionValues,toValues});

package/dist/internal/selection.d.cts

@@ -1,97 +1,58 @@
-/**
- * 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).
- *
- * @see `@skdx/shared`'s `selection-value` contract
- */
-/**
- * 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;
-}
+/** Why a selection change happened: user-driven (keyboard or pointer) or set by the application. */
+export type SelectionChangeReason = 'keyboard' | 'pointer' | 'programmatic';
 /** 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;
+    /** The selection this change replaced, in the same array shape as `value`. */
+    previousValue?: string[];
+    /** What drove the change — see {@link SelectionChangeReason}. */
+    reason?: SelectionChangeReason;
+}
+/** 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, e.g. `Select value`, so the message says which of a page's selects is wrong. */
+    label: string;
 }
+/** Every selected value as an array, whatever shape was passed; `''` and `undefined` mean nothing selected. */
+export declare function toValues(value: string | string[] | undefined): string[];
 /**
- * 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.
+ * Normalizes every selection value to `string[]`, enforcing the single-selection rule; called once at the boundary, never again downstream.
  *
- * @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
+ * @param input the value the consumer supplied, in any accepted shape
+ * @param options cardinality and label for errors — see {@link SelectionValueOptions}
+ * @returns the selection as an array; at most one element unless `multiple`
+ * @throws RangeError in development when an entry is not a string or a single-select gets multiple values
  */
 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 `selectedValue` half of the rule's output: the first selected value, or `null` (never `undefined` or `''`).
  *
- * @param values normalized selection from {@link toSelectionValues}
- * @returns first selected value or `null`
+ * @param values the normalized selection, as {@link toSelectionValues} returns it
+ * @returns the first selected value, or `null` when nothing is selected
  */
 export declare function selectedValueOf(values: readonly string[]): string | null;
 /**
- * The selection a control holds once `value` is chosen: replacing it, or
- * toggling `value` within it when `multiple`.
- *
- * Always returns the array — the strict-out shape — in both cardinalities,
- * since every single-select consumer's change handler reads this value
- * directly.
+ * The selection after choosing `value`: replaces it, or toggles it within the set when `multiple`.
  *
  * @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
+ * @param deselectable whether re-choosing the only selected value clears it (single-select only)
+ * @returns the new selection as an array in both cardinalities
  */
 export declare function nextSelection(selected: readonly string[], value: string, multiple: boolean, deselectable?: boolean): string[];
+/** Whether two selections are indistinguishable to a consumer: same values in the same order. */
+export declare function sameSelection(a: readonly string[], b: readonly string[]): boolean;
 /**
- * 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`.
+ * Parses the attribute form — one comma-separated list under both cardinalities — with {@link toSelectionValues} enforcing the rule.
  *
- * @param attribute raw string or `null` if absent
- * @param options cardinality and error label
- * @returns selection array
+ * @param attribute the raw attribute string, or `null` when absent
+ * @param options cardinality and label for errors
+ * @returns the selection as an 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 const selectionAttributeConverter: {
-    fromAttribute: (value: string | null) => string[];
-    toAttribute: (value: string | readonly string[] | null | undefined) => string | null;
-};

package/dist/internal/selection.d.ts

@@ -1,97 +1,58 @@
-/**
- * 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).
- *
- * @see `@skdx/shared`'s `selection-value` contract
- */
-/**
- * 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;
-}
+/** Why a selection change happened: user-driven (keyboard or pointer) or set by the application. */
+export type SelectionChangeReason = 'keyboard' | 'pointer' | 'programmatic';
 /** 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;
+    /** The selection this change replaced, in the same array shape as `value`. */
+    previousValue?: string[];
+    /** What drove the change — see {@link SelectionChangeReason}. */
+    reason?: SelectionChangeReason;
+}
+/** 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, e.g. `Select value`, so the message says which of a page's selects is wrong. */
+    label: string;
 }
+/** Every selected value as an array, whatever shape was passed; `''` and `undefined` mean nothing selected. */
+export declare function toValues(value: string | string[] | undefined): string[];
 /**
- * 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.
+ * Normalizes every selection value to `string[]`, enforcing the single-selection rule; called once at the boundary, never again downstream.
  *
- * @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
+ * @param input the value the consumer supplied, in any accepted shape
+ * @param options cardinality and label for errors — see {@link SelectionValueOptions}
+ * @returns the selection as an array; at most one element unless `multiple`
+ * @throws RangeError in development when an entry is not a string or a single-select gets multiple values
  */
 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 `selectedValue` half of the rule's output: the first selected value, or `null` (never `undefined` or `''`).
  *
- * @param values normalized selection from {@link toSelectionValues}
- * @returns first selected value or `null`
+ * @param values the normalized selection, as {@link toSelectionValues} returns it
+ * @returns the first selected value, or `null` when nothing is selected
  */
 export declare function selectedValueOf(values: readonly string[]): string | null;
 /**
- * The selection a control holds once `value` is chosen: replacing it, or
- * toggling `value` within it when `multiple`.
- *
- * Always returns the array — the strict-out shape — in both cardinalities,
- * since every single-select consumer's change handler reads this value
- * directly.
+ * The selection after choosing `value`: replaces it, or toggles it within the set when `multiple`.
  *
  * @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
+ * @param deselectable whether re-choosing the only selected value clears it (single-select only)
+ * @returns the new selection as an array in both cardinalities
  */
 export declare function nextSelection(selected: readonly string[], value: string, multiple: boolean, deselectable?: boolean): string[];
+/** Whether two selections are indistinguishable to a consumer: same values in the same order. */
+export declare function sameSelection(a: readonly string[], b: readonly string[]): boolean;
 /**
- * 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`.
+ * Parses the attribute form — one comma-separated list under both cardinalities — with {@link toSelectionValues} enforcing the rule.
  *
- * @param attribute raw string or `null` if absent
- * @param options cardinality and error label
- * @returns selection array
+ * @param attribute the raw attribute string, or `null` when absent
+ * @param options cardinality and label for errors
+ * @returns the selection as an 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 const selectionAttributeConverter: {
-    fromAttribute: (value: string | null) => string[];
-    toAttribute: (value: string | readonly string[] | null | undefined) => string | null;
-};

package/dist/internal/selection.js

@@ -1 +1 @@
-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};
+import{isDevMode as s}from"./dev-mode.js";function g(e){return Array.isArray(e)?e:e?[e]:[]}function l(e){if(s())throw new RangeError(e);console.error(e)}function a(e,{multiple:n,label:t}){let i;Array.isArray(e)?i=e:i=e==null?[]:[e];let r=[];for(let o of i){if(typeof o!="string"){l(`[skdx] ${t}: a selection value must be a string, got ${o===null?"null":typeof o} (${JSON.stringify(o)}). If this is a change payload, read its \`value\` \u2014 the event carries { value, selectedValue } and only \`value\` goes back in.`);continue}o!==""&&r.push(o)}return n||r.length<=1?r:(l(`[skdx] ${t}: 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 c(e){return e.length>0?e[0]:null}function f(e,n,t,i=!1){return t?e.includes(n)?e.filter(r=>r!==n):[...e,n]:i&&e.length===1&&e[0]===n?[]:[n]}function p(e,n){return e.length===n.length&&e.every((t,i)=>t===n[i])}function d(e,n){return e==null?[]:a(e.split(",").map(t=>t.trim()),n)}export{f as nextSelection,d as parseSelectionAttribute,p as sameSelection,c as selectedValueOf,a as toSelectionValues,g as toValues};

package/dist/internal/space.cjs

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

package/dist/internal/space.d.cts

@@ -4,4 +4,9 @@ export type SkdxSpace = '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' |
  * 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;
+export declare function resolveSpace(value: SkdxSpace | undefined): string | undefined;
+/**
+ * A number becomes that many equal columns; any other string is a raw track list passed through.
+ * @internal
+ */
+export declare function resolveColumns(value: number | string | undefined): string | undefined;

package/dist/internal/space.d.ts

@@ -4,4 +4,9 @@ export type SkdxSpace = '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' |
  * 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;
+export declare function resolveSpace(value: SkdxSpace | undefined): string | undefined;
+/**
+ * A number becomes that many equal columns; any other string is a raw track list passed through.
+ * @internal
+ */
+export declare function resolveColumns(value: number | string | undefined): string | undefined;

package/dist/internal/space.js

@@ -1 +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};
+var e=new Set(["1","2","3","4","5","6","8","10","12","16"]);function r(n){if(n!==void 0)return e.has(n)?`var(--skdx-space-${n})`:n}function t(n){if(n!==void 0)return typeof n=="string"&&!/^\d+$/.test(n)?n:`repeat(${Number(n)}, minmax(0, 1fr))`}export{t as resolveColumns,r as resolveSpace};