@skdx/vue 0.28.0 → 0.30.0

package/dist/utils/roving-tab-stop.d.cts

@@ -0,0 +1,37 @@
+/** Matches an item excluded from the roving order — the contract names `data-disabled`, and native controls also carry `disabled`. */
+export declare const DISABLED_ITEM_SELECTOR = "[disabled], [data-disabled]";
+/** Whether an item is out of the roving order, testing both attribute spellings. */
+export declare function isRovingItemDisabled(item: Element): boolean;
+/**
+ * The group's items in document order, minus the disabled ones and minus any that belong to a nested group.
+ *
+ * @param root the group element owning the items, or `null` before it mounts
+ * @param itemSelector selector matching one item
+ * @param scopeSelector selector naming an item's owning group, so a nested group's items are left to it
+ * @returns the enabled items, empty when `root` is not mounted yet
+ */
+export declare function enabledRovingItems(root: ParentNode | null | undefined, itemSelector: string, scopeSelector?: string): HTMLElement[];
+/**
+ * The id that should hold the tab stop after the items or the selection changed.
+ *
+ * Active items win, and the stop stays put while it is still on one of them; with
+ * nothing active it stays on whichever item still claims it, else falls to the first.
+ * An active id that is not in `ids` — disabled, or unmounted since it was selected —
+ * cannot hold the stop, so the group stays reachable by Tab.
+ *
+ * @param ids every enabled item's id, in document order
+ * @param activeIds the ids of the selected/pressed/active items, in document order
+ * @param currentId the id holding the stop now, or `null` before one is resolved
+ * @returns the id to give the stop to, or `null` when the group has no enabled item
+ */
+export declare function resolveTabStopId(ids: readonly string[], activeIds: readonly string[], currentId: string | null): string | null;
+/** Every enabled item's id, skipping items that carry no id — they cannot hold a stop that survives a re-render. */
+export declare function rovingItemIds(items: readonly Element[], idAttribute: string): string[];
+/**
+ * The `tabindex` for one item: before the group resolves its stop — which only happens in a layout effect, so never during SSR — every enabled item is a stop rather than none.
+ *
+ * @param resolved whether the group has settled which item holds the stop
+ * @param isTabStop whether this item is that one
+ * @param disabled whether this item is disabled, in which case it never claims a stop
+ */
+export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, disabled?: boolean): 0 | -1;

package/dist/utils/roving-tab-stop.d.ts

@@ -0,0 +1,37 @@
+/** Matches an item excluded from the roving order — the contract names `data-disabled`, and native controls also carry `disabled`. */
+export declare const DISABLED_ITEM_SELECTOR = "[disabled], [data-disabled]";
+/** Whether an item is out of the roving order, testing both attribute spellings. */
+export declare function isRovingItemDisabled(item: Element): boolean;
+/**
+ * The group's items in document order, minus the disabled ones and minus any that belong to a nested group.
+ *
+ * @param root the group element owning the items, or `null` before it mounts
+ * @param itemSelector selector matching one item
+ * @param scopeSelector selector naming an item's owning group, so a nested group's items are left to it
+ * @returns the enabled items, empty when `root` is not mounted yet
+ */
+export declare function enabledRovingItems(root: ParentNode | null | undefined, itemSelector: string, scopeSelector?: string): HTMLElement[];
+/**
+ * The id that should hold the tab stop after the items or the selection changed.
+ *
+ * Active items win, and the stop stays put while it is still on one of them; with
+ * nothing active it stays on whichever item still claims it, else falls to the first.
+ * An active id that is not in `ids` — disabled, or unmounted since it was selected —
+ * cannot hold the stop, so the group stays reachable by Tab.
+ *
+ * @param ids every enabled item's id, in document order
+ * @param activeIds the ids of the selected/pressed/active items, in document order
+ * @param currentId the id holding the stop now, or `null` before one is resolved
+ * @returns the id to give the stop to, or `null` when the group has no enabled item
+ */
+export declare function resolveTabStopId(ids: readonly string[], activeIds: readonly string[], currentId: string | null): string | null;
+/** Every enabled item's id, skipping items that carry no id — they cannot hold a stop that survives a re-render. */
+export declare function rovingItemIds(items: readonly Element[], idAttribute: string): string[];
+/**
+ * The `tabindex` for one item: before the group resolves its stop — which only happens in a layout effect, so never during SSR — every enabled item is a stop rather than none.
+ *
+ * @param resolved whether the group has settled which item holds the stop
+ * @param isTabStop whether this item is that one
+ * @param disabled whether this item is disabled, in which case it never claims a stop
+ */
+export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, disabled?: boolean): 0 | -1;

package/dist/utils/roving-tab-stop.js

@@ -0,0 +1 @@
+var e="[disabled], [data-disabled]";function n(n){return n.matches(e)}function t(e,t,l){return Array.from(e?.querySelectorAll(t)??[]).filter(t=>!(n(t)||l&&t.closest(l)!==e))}function l(e,n,t){const l=n.filter(n=>e.includes(n));return l.length>0?null!==t&&l.includes(t)?t:l[0]:null!==t&&e.includes(t)?t:e[0]??null}function r(e,n){return e.map(e=>e.getAttribute(n)).filter(e=>null!==e&&""!==e)}function i(e,n,t=!1){return e||t?n?0:-1:0}export{e as DISABLED_ITEM_SELECTOR,t as enabledRovingItems,n as isRovingItemDisabled,l as resolveTabStopId,r as rovingItemIds,i as rovingTabIndex};

package/dist/utils/scoredFilter.d.cts

@@ -1,26 +1,12 @@
-/**
- * Filter predicate shared by Command, Combobox, Autocomplete, MultiSelect:
- * boolean keeps/excludes; number filters and ranks.
- */
+/** Filter predicate shared by Command, Combobox, Autocomplete, Select: boolean keeps/excludes; number filters and ranks. */
 export type ScoredFilterResult = boolean | number;
-/**
- * Whether a {@link ScoredFilterResult} keeps the item: `0` and `false`
- * exclude, `true` and any positive number keep. A negative number excludes
- * too — the contract only promises a positive score keeps, so treating a
- * negative one as a rejection (rather than JS's own truthiness, which would
- * keep it) is the conservative reading.
- */
+/** Whether a {@link ScoredFilterResult} keeps the item: `0`/`false` exclude, `true`/positive keep, and a negative number also excludes. */
 export declare function filterKeeps(result: ScoredFilterResult): boolean;
 /**
- * Returns `container`'s currently-visible option elements in traversal
- * order — descending filter score, ties keeping their original relative
- * order (`Array.prototype.sort` is stable) — and sets inline CSS `order` on
- * each to match, so a flex/grid container's visual sequence follows the same
- * order arrow keys, typeahead and range-selection walk. A no-op on both
- * counts when nothing scores numerically, so a boolean-only predicate leaves
- * DOM and CSS order exactly as rendered.
+ * Returns `container`'s currently-visible option elements in traversal order
+ * (descending filter score, ties keeping DOM order) and sets inline CSS
+ * `order` on each to match; a no-op when nothing scores numerically.
  *
- * ponytail: `order` only reorders inside a flex or grid container — the skin
- * is responsible for the list being one.
+ * `order` only reorders inside a flex or grid container — the skin is responsible for the list being one.
  */
 export declare function orderByScore(container: HTMLElement, optionSelector: string, scoreOf: (id: string) => number | null): HTMLElement[];

package/dist/utils/scoredFilter.d.ts

@@ -1,26 +1,12 @@
-/**
- * Filter predicate shared by Command, Combobox, Autocomplete, MultiSelect:
- * boolean keeps/excludes; number filters and ranks.
- */
+/** Filter predicate shared by Command, Combobox, Autocomplete, Select: boolean keeps/excludes; number filters and ranks. */
 export type ScoredFilterResult = boolean | number;
-/**
- * Whether a {@link ScoredFilterResult} keeps the item: `0` and `false`
- * exclude, `true` and any positive number keep. A negative number excludes
- * too — the contract only promises a positive score keeps, so treating a
- * negative one as a rejection (rather than JS's own truthiness, which would
- * keep it) is the conservative reading.
- */
+/** Whether a {@link ScoredFilterResult} keeps the item: `0`/`false` exclude, `true`/positive keep, and a negative number also excludes. */
 export declare function filterKeeps(result: ScoredFilterResult): boolean;
 /**
- * Returns `container`'s currently-visible option elements in traversal
- * order — descending filter score, ties keeping their original relative
- * order (`Array.prototype.sort` is stable) — and sets inline CSS `order` on
- * each to match, so a flex/grid container's visual sequence follows the same
- * order arrow keys, typeahead and range-selection walk. A no-op on both
- * counts when nothing scores numerically, so a boolean-only predicate leaves
- * DOM and CSS order exactly as rendered.
+ * Returns `container`'s currently-visible option elements in traversal order
+ * (descending filter score, ties keeping DOM order) and sets inline CSS
+ * `order` on each to match; a no-op when nothing scores numerically.
  *
- * ponytail: `order` only reorders inside a flex or grid container — the skin
- * is responsible for the list being one.
+ * `order` only reorders inside a flex or grid container — the skin is responsible for the list being one.
  */
 export declare function orderByScore(container: HTMLElement, optionSelector: string, scoreOf: (id: string) => number | null): HTMLElement[];

package/dist/utils/select-keyboard.cjs

@@ -0,0 +1 @@
+const a=require("./typeahead.cjs");var c={ArrowDown:"first",Home:"first",ArrowUp:"last",End:"last",Enter:"selected"," ":"selected"};function d(e){return e.kind!=="ignore"&&e.kind!=="commit-on-exit"}function i(e,n,r){return Math.min(r-1,Math.max(0,e+n))}function o(e,n){if(e.altKey&&e.key==="ArrowUp")return{kind:"ignore"};const r=c[e.key];return r!==void 0?{kind:"open",intent:e.altKey&&e.key==="ArrowDown"?"selected":r}:a.isTypeaheadKey(e)?n?{kind:"open-for-typeahead"}:{kind:"typeahead"}:{kind:"ignore"}}function s(e,n,r){if(e.altKey&&(e.key==="ArrowUp"||e.key==="ArrowDown"))return e.key==="ArrowUp"?{kind:"commit-and-close"}:{kind:"claim"};const t=k(e.key,n,r);return t!==null?r===0?{kind:"claim"}:{kind:"activate",index:t}:e.key==="Enter"||e.key===" "?{kind:"commit"}:e.key==="Tab"?{kind:"commit-on-exit"}:a.isTypeaheadKey(e)?{kind:"typeahead"}:{kind:"ignore"}}function k(e,n,r){switch(e){case"ArrowDown":return i(n,1,r);case"ArrowUp":return i(n,-1,r);case"PageDown":return i(n,10,r);case"PageUp":return i(n,-10,r);case"Home":return 0;case"End":return r-1;default:return null}}exports.selectClosedAction=o;exports.selectKeyPrevented=d;exports.selectOpenAction=s;

package/dist/utils/select-keyboard.d.cts

@@ -0,0 +1,80 @@
+/** Where the listbox should put the active option when a key opens it. */
+export type SelectOpenIntent = 'selected' | 'first' | 'last';
+/** Ten is the normative page jump for a listbox — a headless package has no rendered row height to divide by. */
+export declare const SELECT_PAGE_SIZE = 10;
+/** What a keydown on a closed trigger asks for. Every action but `'ignore'` wants `preventDefault()`. */
+export type SelectClosedAction = 
+/** Open the listbox with the active option placed as `intent` says. */
+{
+    kind: 'open';
+    intent: SelectOpenIntent;
+}
+/** A letter arrived on a multiple-select: open the listbox and search there, since a closed multi-select has no single "current" option to walk from. */
+ | {
+    kind: 'open-for-typeahead';
+}
+/** A letter arrived on a single-select: match it against the options and select the hit without opening, as a native `<select>` does. */
+ | {
+    kind: 'typeahead';
+}
+/** Not a key this trigger claims. */
+ | {
+    kind: 'ignore';
+};
+/** What a keydown on an open listbox asks for; `index` is already clamped into range. */
+export type SelectOpenAction = 
+/** Move the active option to `index`. */
+{
+    kind: 'activate';
+    index: number;
+}
+/** Select the active option, and close unless `closeOnSelect` is off. */
+ | {
+    kind: 'commit';
+}
+/** Alt+ArrowUp: select the active option and close, the keyboard equivalent of clicking it. */
+ | {
+    kind: 'commit-and-close';
+}
+/** Tab: add the active option to the selection without ever removing it, then close and let the browser's own Tab run. */
+ | {
+    kind: 'commit-on-exit';
+}
+/** A letter arrived: run the typeahead and activate its hit. */
+ | {
+    kind: 'typeahead';
+}
+/** Alt+ArrowDown, the open key: claimed so it cannot move focus, but nothing else happens. */
+ | {
+    kind: 'claim';
+}
+/** Not a key the listbox claims. */
+ | {
+    kind: 'ignore';
+};
+/** A keydown, reduced to what the decision needs. */
+export interface SelectKeyEvent {
+    key: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+}
+/** Whether the adapter should call `preventDefault()` for this action; Tab is the exception, because focus is not trapped and the browser's own Tab has to carry focus onward. */
+export declare function selectKeyPrevented(action: SelectClosedAction | SelectOpenAction): boolean;
+/**
+ * The action for a keydown on a closed trigger.
+ *
+ * @param event the keydown
+ * @param multiple whether the Select holds more than one value
+ * @returns what the adapter should do; see {@link SelectClosedAction}
+ */
+export declare function selectClosedAction(event: SelectKeyEvent, multiple: boolean): SelectClosedAction;
+/**
+ * The action for a keydown while the listbox is open, over virtual focus: DOM focus stays on the trigger, so these move the active option, not the focused element.
+ *
+ * @param event the keydown
+ * @param currentIndex the active option's index, or `-1` when none is active
+ * @param optionCount how many options the listbox renders
+ * @returns what the adapter should do; see {@link SelectOpenAction}
+ */
+export declare function selectOpenAction(event: SelectKeyEvent, currentIndex: number, optionCount: number): SelectOpenAction;

package/dist/utils/select-keyboard.d.ts

@@ -0,0 +1,80 @@
+/** Where the listbox should put the active option when a key opens it. */
+export type SelectOpenIntent = 'selected' | 'first' | 'last';
+/** Ten is the normative page jump for a listbox — a headless package has no rendered row height to divide by. */
+export declare const SELECT_PAGE_SIZE = 10;
+/** What a keydown on a closed trigger asks for. Every action but `'ignore'` wants `preventDefault()`. */
+export type SelectClosedAction = 
+/** Open the listbox with the active option placed as `intent` says. */
+{
+    kind: 'open';
+    intent: SelectOpenIntent;
+}
+/** A letter arrived on a multiple-select: open the listbox and search there, since a closed multi-select has no single "current" option to walk from. */
+ | {
+    kind: 'open-for-typeahead';
+}
+/** A letter arrived on a single-select: match it against the options and select the hit without opening, as a native `<select>` does. */
+ | {
+    kind: 'typeahead';
+}
+/** Not a key this trigger claims. */
+ | {
+    kind: 'ignore';
+};
+/** What a keydown on an open listbox asks for; `index` is already clamped into range. */
+export type SelectOpenAction = 
+/** Move the active option to `index`. */
+{
+    kind: 'activate';
+    index: number;
+}
+/** Select the active option, and close unless `closeOnSelect` is off. */
+ | {
+    kind: 'commit';
+}
+/** Alt+ArrowUp: select the active option and close, the keyboard equivalent of clicking it. */
+ | {
+    kind: 'commit-and-close';
+}
+/** Tab: add the active option to the selection without ever removing it, then close and let the browser's own Tab run. */
+ | {
+    kind: 'commit-on-exit';
+}
+/** A letter arrived: run the typeahead and activate its hit. */
+ | {
+    kind: 'typeahead';
+}
+/** Alt+ArrowDown, the open key: claimed so it cannot move focus, but nothing else happens. */
+ | {
+    kind: 'claim';
+}
+/** Not a key the listbox claims. */
+ | {
+    kind: 'ignore';
+};
+/** A keydown, reduced to what the decision needs. */
+export interface SelectKeyEvent {
+    key: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+}
+/** Whether the adapter should call `preventDefault()` for this action; Tab is the exception, because focus is not trapped and the browser's own Tab has to carry focus onward. */
+export declare function selectKeyPrevented(action: SelectClosedAction | SelectOpenAction): boolean;
+/**
+ * The action for a keydown on a closed trigger.
+ *
+ * @param event the keydown
+ * @param multiple whether the Select holds more than one value
+ * @returns what the adapter should do; see {@link SelectClosedAction}
+ */
+export declare function selectClosedAction(event: SelectKeyEvent, multiple: boolean): SelectClosedAction;
+/**
+ * The action for a keydown while the listbox is open, over virtual focus: DOM focus stays on the trigger, so these move the active option, not the focused element.
+ *
+ * @param event the keydown
+ * @param currentIndex the active option's index, or `-1` when none is active
+ * @param optionCount how many options the listbox renders
+ * @returns what the adapter should do; see {@link SelectOpenAction}
+ */
+export declare function selectOpenAction(event: SelectKeyEvent, currentIndex: number, optionCount: number): SelectOpenAction;

package/dist/utils/select-keyboard.js

@@ -0,0 +1 @@
+import{isTypeaheadKey as e}from"./typeahead.js";var n={ArrowDown:"first",Home:"first",ArrowUp:"last",End:"last",Enter:"selected"," ":"selected"};function r(e){return"ignore"!==e.kind&&"commit-on-exit"!==e.kind}function t(e,n,r){return Math.min(r-1,Math.max(0,e+n))}function i(r,t){if(r.altKey&&"ArrowUp"===r.key)return{kind:"ignore"};const i=n[r.key];return void 0!==i?{kind:"open",intent:r.altKey&&"ArrowDown"===r.key?"selected":i}:e(r)?t?{kind:"open-for-typeahead"}:{kind:"typeahead"}:{kind:"ignore"}}function o(n,r,i){if(n.altKey&&("ArrowUp"===n.key||"ArrowDown"===n.key))return"ArrowUp"===n.key?{kind:"commit-and-close"}:{kind:"claim"};const o=function(e,n,r){switch(e){case"ArrowDown":return t(n,1,r);case"ArrowUp":return t(n,-1,r);case"PageDown":return t(n,10,r);case"PageUp":return t(n,-10,r);case"Home":return 0;case"End":return r-1;default:return null}}(n.key,r,i);return null!==o?0===i?{kind:"claim"}:{kind:"activate",index:o}:"Enter"===n.key||" "===n.key?{kind:"commit"}:"Tab"===n.key?{kind:"commit-on-exit"}:e(n)?{kind:"typeahead"}:{kind:"ignore"}}export{i as selectClosedAction,r as selectKeyPrevented,o as selectOpenAction};

package/dist/utils/selection.cjs

@@ -0,0 +1 @@
+const u=require("./dev-mode.cjs");function i(e){if(u.isDevMode())throw new RangeError(e);console.error(e)}function s(e,{multiple:n,label:r}){let l;Array.isArray(e)?l=e:l=e==null?[]:[e];const t=[];for(const o of l){if(typeof o!="string"){i(`[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\` — the event carries { value, selectedValue } and only \`value\` goes back in.`);continue}o!==""&&t.push(o)}return n||t.length<=1?t:(i(`[skdx] ${r}: a single-selection control was given ${t.length} values (${t.join(", ")}). Only one can be held — pass a single value, or turn the control multiple. Set multiple (or type="multiple") to keep them all.`),[t[0]])}function a(e){return e.length>0?e[0]:null}function c(e,n,r,l=!1){return r?e.includes(n)?e.filter(t=>t!==n):[...e,n]:l&&e.length===1&&e[0]===n?[]:[n]}function f(e,n){return e.length===n.length&&e.every((r,l)=>r===n[l])}exports.nextSelection=c;exports.sameSelection=f;exports.selectedValueOf=a;exports.toSelectionValues=s;

package/dist/utils/selection.d.cts

@@ -0,0 +1,58 @@
+/** 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[];
+/**
+ * Normalizes every selection value to `string[]`, enforcing the single-selection rule; called once at the boundary, never again downstream.
+ *
+ * @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 the rule's output: the first selected value, or `null` (never `undefined` or `''`).
+ *
+ * @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 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 (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;
+/**
+ * Parses the attribute form — one comma-separated list under both cardinalities — with {@link toSelectionValues} enforcing the rule.
+ *
+ * @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[];

package/dist/utils/selection.d.ts

@@ -0,0 +1,58 @@
+/** 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[];
+/**
+ * Normalizes every selection value to `string[]`, enforcing the single-selection rule; called once at the boundary, never again downstream.
+ *
+ * @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 the rule's output: the first selected value, or `null` (never `undefined` or `''`).
+ *
+ * @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 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 (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;
+/**
+ * Parses the attribute form — one comma-separated list under both cardinalities — with {@link toSelectionValues} enforcing the rule.
+ *
+ * @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[];

package/dist/utils/selection.js

@@ -0,0 +1 @@
+import{isDevMode as e}from"./dev-mode.js";function l(l){if(e())throw new RangeError(l);console.error(l)}function n(e,{multiple:n,label:t}){let o;o=Array.isArray(e)?e:null==e?[]:[e];const r=[];for(const e of o)"string"==typeof e?""!==e&&r.push(e):l(`[skdx] ${t}: a selection value must be a string, got ${null===e?"null":typeof e} (${JSON.stringify(e)}). If this is a change payload, read its \`value\` — the event carries { value, selectedValue } and only \`value\` goes back in.`);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 — pass a single value, or turn the control multiple. Set multiple (or type="multiple") to keep them all.`),[r[0]])}function t(e){return e.length>0?e[0]:null}function o(e,l,n,t=!1){return n?e.includes(l)?e.filter(e=>e!==l):[...e,l]:t&&1===e.length&&e[0]===l?[]:[l]}function r(e,l){return e.length===l.length&&e.every((e,n)=>e===l[n])}export{o as nextSelection,r as sameSelection,t as selectedValueOf,n as toSelectionValues};

package/dist/utils/space.cjs

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

package/dist/utils/space.d.cts

@@ -1,5 +1,7 @@
-/** Mirrors React's `resolveSpace.ts`; copied, not imported — packages don't depend on each other at runtime. */
+/** Copied, not imported — packages don't depend on each other at runtime. */
 /** A spacing-scale token key, or any other string passed through as a raw CSS length. */
 export type Space = '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' | (string & {});
 /** A scale key resolves to its token (`var(--skdx-space-<key>)`); anything else passes through verbatim. */
 export declare function resolveSpace(value: Space | undefined): string | undefined;
+/** A number, or a digits-only string, becomes that many equal columns; any other string is a raw track list passed through. */
+export declare function resolveColumns(value: number | string | undefined): string | undefined;

package/dist/utils/space.d.ts

@@ -1,5 +1,7 @@
-/** Mirrors React's `resolveSpace.ts`; copied, not imported — packages don't depend on each other at runtime. */
+/** Copied, not imported — packages don't depend on each other at runtime. */
 /** A spacing-scale token key, or any other string passed through as a raw CSS length. */
 export type Space = '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' | (string & {});
 /** A scale key resolves to its token (`var(--skdx-space-<key>)`); anything else passes through verbatim. */
 export declare function resolveSpace(value: Space | undefined): string | undefined;
+/** A number, or a digits-only string, becomes that many equal columns; any other string is a raw track list passed through. */
+export declare function resolveColumns(value: number | string | undefined): string | undefined;

package/dist/utils/space.js

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

package/dist/utils/tabbable.d.cts

@@ -1,9 +1,8 @@
-/**
- * Elements a `Tab` press can land on — tabbable elements for manual tab-order walks.
- * @internal
- */
+/** The elements a `Tab` press can land on — this package's one definition of "tabbable", for components that have to walk the tab order by hand. */
 export declare const TABBABLE_SELECTOR: string;
 /**
- * Every tabbable element inside `container`, in document order. @internal
+ * Every tabbable element inside `container`, in document order. Uses only the
+ * selector without visibility checks (unlike focus traps) because overlays are
+ * small subtrees only in the DOM while open.
  */
 export declare function tabbablesWithin(container: Element): HTMLElement[];

package/dist/utils/tabbable.d.ts

@@ -1,9 +1,8 @@
-/**
- * Elements a `Tab` press can land on — tabbable elements for manual tab-order walks.
- * @internal
- */
+/** The elements a `Tab` press can land on — this package's one definition of "tabbable", for components that have to walk the tab order by hand. */
 export declare const TABBABLE_SELECTOR: string;
 /**
- * Every tabbable element inside `container`, in document order. @internal
+ * Every tabbable element inside `container`, in document order. Uses only the
+ * selector without visibility checks (unlike focus traps) because overlays are
+ * small subtrees only in the DOM while open.
  */
 export declare function tabbablesWithin(container: Element): HTMLElement[];

package/dist/utils/timer.cjs

@@ -0,0 +1 @@
+var t=class{constructor(e={}){this.phase="idle",this.accrued=0,this.startedAt=0,this.pausedByPage=!1,this.onVisibilityChange=()=>{document.hidden?this.pauseForPage():this.pausedByPage&&this.resume()},this.onPageHide=()=>{this.pauseForPage()},this.options=e,this.duration=e.duration??Number.POSITIVE_INFINITY,this.tickMs=e.tickMs??0,!(e.pauseWhenHidden===!1||typeof document>"u")&&(document.addEventListener("visibilitychange",this.onVisibilityChange),window.addEventListener("pagehide",this.onPageHide))}get state(){const e=this.measure();return{phase:this.phase,elapsed:e,remaining:this.duration-e,duration:this.duration}}start(e){e!==void 0&&(this.duration=e),this.clearHandles(),this.accrued=0,this.pausedByPage=!1,this.run()}pause(){this.pausedByPage=!1,this.phase==="running"&&(this.accrued=this.measure(),this.clearHandles(),this.setPhase("paused"))}resume(){this.pausedByPage=!1,this.phase==="paused"&&this.run()}reset(){this.clearHandles(),this.accrued=0,this.startedAt=0,this.pausedByPage=!1,this.setPhase("idle")}destroy(){this.clearHandles(),!(this.options.pauseWhenHidden===!1||typeof document>"u")&&(document.removeEventListener("visibilitychange",this.onVisibilityChange),window.removeEventListener("pagehide",this.onPageHide))}measure(){const e=this.phase==="running"?Date.now()-this.startedAt:0;return Math.min(this.accrued+e,this.duration)}run(){this.startedAt=Date.now();const e=this.duration-this.accrued;Number.isFinite(e)&&(this.completion=setTimeout(()=>this.complete(),Math.max(e,0))),this.tickMs>0&&(this.ticker=setInterval(()=>this.options.onTick?.(this.state),this.tickMs)),this.setPhase("running")}complete(){this.clearHandles(),this.accrued=this.duration,this.setPhase("complete"),this.tickMs>0&&this.options.onTick?.(this.state)}setPhase(e){this.phase!==e&&(this.phase=e,this.options.onPhaseChange?.(this.state))}clearHandles(){clearTimeout(this.completion),clearInterval(this.ticker),this.completion=void 0,this.ticker=void 0}pauseForPage(){this.phase==="running"&&(this.pause(),this.pausedByPage=!0)}};exports.Timer=t;

package/dist/utils/timer.d.cts

@@ -0,0 +1,82 @@
+/** Where the clock stands: never started, running, held by a pause, or finished. */
+export type TimerPhase = 'idle' | 'running' | 'paused' | 'complete';
+/** The clock as a consumer renders it, computed fresh on every read. */
+export interface TimerState {
+    /** Where the clock stands right now, as one of the four phases. */
+    phase: TimerPhase;
+    /** Milliseconds the clock has actually run, never counting paused time. */
+    elapsed: number;
+    /** Milliseconds left before completion, or `Infinity` when counting up. */
+    remaining: number;
+    /** The countdown length in force, `Infinity` for an open-ended count-up. */
+    duration: number;
+}
+/** How one clock is configured; every field has a working default. */
+export interface TimerOptions {
+    /**
+     * Countdown length in milliseconds; leave it out to count up with no end.
+     *
+     * @default Infinity
+     */
+    duration?: number | undefined;
+    /**
+     * Milliseconds between `onTick` calls while running; `0` reports no ticks.
+     *
+     * @default 0
+     */
+    tickMs?: number | undefined;
+    /**
+     * Whether a hidden or unloading page pauses the clock and a returning page resumes it.
+     *
+     * @default true
+     */
+    pauseWhenHidden?: boolean | undefined;
+    /**
+     * Called on every tick and once more at completion, for rendering the clock only.
+     *
+     * Ticks are far too frequent to announce: write them to a progress bar or a
+     * `<time>`, never to a live region.
+     */
+    onTick?: ((state: TimerState) => void) | undefined;
+    /**
+     * Called when the phase changes, and only on an actual change, so it is the one place announcements belong.
+     */
+    onPhaseChange?: ((state: TimerState) => void) | undefined;
+}
+/** A framework-neutral countdown or count-up: `start`, `pause`, `resume`, `reset`, and a completion phase. */
+export declare class Timer {
+    private readonly options;
+    private readonly tickMs;
+    private duration;
+    private phase;
+    private accrued;
+    private startedAt;
+    private completion;
+    private ticker;
+    private pausedByPage;
+    constructor(options?: TimerOptions);
+    /** The phase, elapsed, remaining and duration as they read at this instant. */
+    get state(): TimerState;
+    /**
+     * Runs the clock from zero, replacing whatever it was doing.
+     *
+     * @param duration a new countdown length to adopt, in milliseconds
+     */
+    start(duration?: number): void;
+    /** Holds the clock where it stands; a second call while already paused changes nothing. */
+    pause(): void;
+    /** Runs the clock on from where a pause left it; ignored unless it is paused. */
+    resume(): void;
+    /** Stops the clock and returns it to zero, as it was before the first `start`. */
+    reset(): void;
+    /** Stops the clock and releases every listener and handle it holds. */
+    destroy(): void;
+    private measure;
+    private run;
+    private complete;
+    private setPhase;
+    private clearHandles;
+    private readonly onVisibilityChange;
+    private readonly onPageHide;
+    private pauseForPage;
+}