npm - @skdx/vue - Versions diffs - 0.27.0 → 0.28.0 - Mend

@skdx/vue 0.27.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3287) hide show

package/dist/utils/useOutsideInert.d.ts ADDED Viewed

@@ -0,0 +1,34 @@
+import { type Ref } from 'vue';
+/**
+ * Marks everything outside the overlay's portal container `inert` while
+ * `enabled`, and restores it on close — the inertness a Vue overlay has to write
+ * for itself when it never calls `showModal()`.
+ *
+ * Safe to stack: several overlays open at once each keep their own container
+ * live, and the last one to close is what clears the attributes.
+ *
+ * @param contentRef ref to the overlay's panel; its nearest `<body>` child is
+ * the subtree kept interactive.
+ * @param enabled whether the overlay is currently open *and* modal. A non-modal
+ * overlay must pass `false` — inerting the page behind a panel the user is meant
+ * to work alongside is the opposite of the intent.
+ * @internal
+ */
+export declare function useOutsideInert(contentRef: Ref<HTMLElement | null>, enabled: Ref<boolean>): void;
+/**
+ * Takes every `inert` mark this module has written off the page, right now.
+ *
+ * The escape hatch for handing focus back out of an overlay that is closing but
+ * has not finished closing. An inert element cannot take focus, and a close
+ * path that refocuses its trigger does so from an *event handler* — before the
+ * watcher above has run its release, and (for `Tab`) before the browser's own
+ * default action, which has to start from the trigger. Calling this first is
+ * what makes that `focus()` land.
+ *
+ * `exempt` is deliberately left alone: the overlay's own release is still to
+ * come, and it is what settles the final state. This only lifts the attributes.
+ *
+ * Mirrors `packages/react/src/utils/useOutsideInert.ts`'s
+ * `releaseOutsideInert`. @internal
+ */
+export declare function releaseOutsideInert(): void;

package/dist/utils/useOutsideInert.js ADDED Viewed

@@ -0,0 +1 @@

+ import{onBeforeUnmount as e,onMounted as t,watch as n}from"vue";var o=/* @__PURE__ */new Map,r=/* @__PURE__ */new Set;function u(e){if(0!==r.size)for(const t of Array.from(e.children)){if(r.has(t)){const e=o.get(t);void 0!==e&&(e||t.removeAttribute("inert"),o.delete(t));continue}o.has(t)||(o.set(t,t.hasAttribute("inert")),t.setAttribute("inert",""))}else{for(const[e,t]of o)t||e.removeAttribute("inert");o.clear()}}function i(o,i){let s=null;function a(){if(!s)return;const{root:e,body:t}=s;s=null,r.delete(e),u(t)}function c(){const e=o.value;if(!e)return;const t=function(e){const t=e.ownerDocument.body;let n=e;for(;n.parentElement&&n.parentElement!==t;)n=n.parentElement;return n.parentElement===t?n:null}(e);if(!t)return;const n=e.ownerDocument.body;s={root:t,body:n},r.add(t),u(n)}n(i,e=>{a(),e&&c()},{flush:"post"}),t(()=>{i.value&&c()}),e(a)}function s(){for(const[e,t]of o)t||e.removeAttribute("inert");o.clear()}export{s as releaseOutsideInert,i as useOutsideInert};

package/dist/utils/useRovingFocus.cjs CHANGED Viewed

	@@ -1 +1 @@
1	- const T=require("./direction.cjs");let b=require("vue");function v(o,a,g,n){const u=()=>{const i=Array.from(o.value?.querySelectorAll(a)??[],s=>s.getAttribute(g)).filter(s=>s!==null&&s!==""),l=i[0];l===void 0\|\|n.value!==null&&i.includes(n.value)\|\|(n.value=l)};return(0,b.onMounted)(u),(0,b.onUpdated)(u),u}var x=1e3;function m(o){return o.getAttribute("data-text-value")??o.textContent??""}var E={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},R={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function K({orientation:o="both",loop:a=!0,itemSelector:g,typeahead:n=!1,direction:u}){let i="",l;return function(r){const h=r.currentTarget,t=Array.from(h.querySelectorAll(g)).filter(~~d=>!d~~.hasAttribute("disabled")&&d.getAttribute("data-disabled")===null);if(t.length===0)return;const f=t.indexOf(r.target),c=T.directionalKey(r.key,h,u?.());let e;if(E[o].includes(c))e=f+1,e>=t.length&&(e=a?0:t.length-1);else if(R[o].includes(c))e=f-1,e<0&&(e=a?t.length-1:0);else if(c==="Home")e=0;else if(c==="End")e=t.length-1;else if(n&&r.key.length===1&&!r.ctrlKey&&!r.metaKey&&!r.altKey){clearTimeout(l),i+=r.key.toLowerCase(),l=setTimeout(()=>{i=""},x);const d=i,w=y=>m(y).trim().toLowerCase().startsWith(d),A=[...t.slice(f+1),...t.slice(0,f+1)].find(w);A&&(e=t.indexOf(A))}e!==void 0&&(r.preventDefault(),t[e]?.focus())}}exports.itemText=m;exports.useRovingFocus=K;exports.useRovingTabStop=v;
1	+ const v=require("./direction.cjs");let b=require("vue");function x(i,s,g,n){const u=()=>{const a=Array.from(i.value?.querySelectorAll(s)??[],o=>o.getAttribute(g)).filter(o=>o!==null&&o!==""),f=a[0];f===void 0\|\|n.value!==null&&a.includes(n.value)\|\|(n.value=f)};return(0,b.onMounted)(u),(0,b.onUpdated)(u),u}var E=1e3;function m(i){return i.getAttribute("data-text-value")??i.textContent??""}var R={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},K={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function S({orientation:i="both",loop:s=!0,itemSelector:g,scopeSelector:n,typeahead:u=!1,includeDisabled:a=!1,direction:f}){let o="",A;return function(t){const h=t.currentTarget,r=Array.from(h.querySelectorAll(g)).filter(l=>(a\|\|!l.hasAttribute("disabled")&&l.getAttribute("data-disabled")===null)&&(!n\|\|l.closest(n)===h));if(r.length===0)return;const c=r.indexOf(t.target),d=v.directionalKey(t.key,h,f?.());let e;if(R[i].includes(d))e=c+1,e>=r.length&&(e=s?0:r.length-1);else if(K[i].includes(d))e=c-1,e<0&&(e=s?r.length-1:0);else if(d==="Home")e=0;else if(d==="End")e=r.length-1;else if(u&&t.key.length===1&&!t.ctrlKey&&!t.metaKey&&!t.altKey&&(t.key!==" "\|\|o!=="")){clearTimeout(A),o+=t.key.toLowerCase(),A=setTimeout(()=>{o=""},E);const l=o,w=T=>m(T).trim().toLowerCase().startsWith(l),y=[...r.slice(c+1),...r.slice(0,c+1)].find(w);y&&(e=r.indexOf(y))}e!==void 0&&(t.preventDefault(),r[e]?.focus())}}exports.itemText=m;exports.useRovingFocus=S;exports.useRovingTabStop=x;

package/dist/utils/useRovingFocus.d.cts CHANGED Viewed

@@ -1,59 +1,47 @@
 /**
- * DOM-driven roving focus for composite widgets (menus, menubars). Returns a
- * keydown handler to bind on the group element via `@keydown`. Items are
- * discovered by selector, so no registration plumbing is needed. Mirrors
- * `packages/react/src/utils/useRovingFocus.ts`. @internal
+ * DOM-driven roving focus for composite widgets. Returns a keydown handler
+ * for arrow, Home, End, and optional typeahead navigation. @internal
  */
 import { type Ref } from 'vue';
 import { type Direction } from './direction.cjs';
 export type Orientation = 'horizontal' | 'vertical' | 'both';
 /**
- * Keeps a roving-tabindex group's tab stop on an item that actually exists.
- *
- * Seeding "when nothing is focused yet, make the first item tabbable" is only
- * half the job: when the item *holding* the tab stop is removed, the stored id
- * still points at it, so a `currentId === null` guard sees nothing to do — and
- * then no item carries `tabindex="0"` and the whole group silently drops out of
- * the tab order, with nothing on screen to explain it. So the check is "does
- * any item claim the current id", not "is the current id set".
- *
- * Runs on mount and after every re-render of the group, since an item can
- * disappear without `currentId` changing — which is exactly the case that
- * breaks. Each run is one `querySelectorAll` over a group that is small by
- * construction, and it settles after at most one assignment. The reseed is
- * returned so a group whose items unmount *without* it re-rendering (a tree
- * collapsing a branch its own children own) can re-run it from a post-flush
- * watcher.
- *
- * Mirrors `packages/react/src/utils/useRovingFocus.ts`'s `useRovingTabStop`.
- * @internal
+ * Keeps a roving-tabindex group's tab stop valid when items are removed.
+ * When an item holding the tab stop is removed, reseeds to the first item.
+ * Runs on mount and update; reseed returned for manual re-run if items
+ * unmount without re-rendering. @internal
  */
 export declare function useRovingTabStop(rootRef: Ref<HTMLElement | null>, itemSelector: string, idAttribute: string, currentId: Ref<string | null>): () => void;
 interface UseRovingFocusOptions {
-    /** Axis the arrow keys navigate (defaults to both). */
+    /** Axis the arrow keys navigate; defaults to both. */
     orientation?: Orientation;
-    /** Whether moving past the last/first item wraps around to the other end. */
+    /** Whether navigation wraps at group boundaries. */
     loop?: boolean;
     /** CSS selector matching focusable items inside the group. */
     itemSelector: string;
+    /**
+     * Selector matching this kind of group; nested groups' items are only
+     * navigated by their own group, not ancestors.
+     * @default undefined — every descendant match is an item
+     */
+    scopeSelector?: string;
     /** Enable letter-key typeahead (jumps to the next item whose text starts with what was typed). */
     typeahead?: boolean;
+    /**
+     * Keep disabled items navigable. Opt-in: controls skip them (per APG),
+     * but menu commands must stay navigable so they remain discoverable.
+     * @default false
+     */
+    includeDisabled?: boolean;
     /** Writing direction override; omit to resolve from the nearest `[dir]` ancestor. */
     direction?: () => Direction | undefined;
 }
 /**
- * The text typeahead matches an item against: its explicit `data-text-value`
- * if it has one, else its rendered text.
- *
- * Raw `textContent` alone is wrong for any item that renders more than its
- * label — an item with an `ItemIndicator` reads as `"✓Apple"`, so typing `a`
- * skips exactly the items that are currently selected. `data-text-value` is
- * the escape hatch, and this is the one precedence rule every matcher in the
- * repo follows.
- *
+ * Text for typeahead matching: `data-text-value` if set, else rendered text.
+ * Raw `textContent` fails for items with decorators (e.g., `ItemIndicator`).
  * @internal
  */
 export declare function itemText(el: Element): string;
 /** @internal Returns a group keydown handler that moves focus between items via arrow/Home/End keys and optional typeahead. */
-export declare function useRovingFocus({ orientation, loop, itemSelector, typeahead, direction, }: UseRovingFocusOptions): (event: KeyboardEvent) => void;
+export declare function useRovingFocus({ orientation, loop, itemSelector, scopeSelector, typeahead, includeDisabled, direction, }: UseRovingFocusOptions): (event: KeyboardEvent) => void;
 export {};

package/dist/utils/useRovingFocus.d.ts CHANGED Viewed

@@ -1,59 +1,47 @@
 /**
- * DOM-driven roving focus for composite widgets (menus, menubars). Returns a
- * keydown handler to bind on the group element via `@keydown`. Items are
- * discovered by selector, so no registration plumbing is needed. Mirrors
- * `packages/react/src/utils/useRovingFocus.ts`. @internal
+ * DOM-driven roving focus for composite widgets. Returns a keydown handler
+ * for arrow, Home, End, and optional typeahead navigation. @internal
  */
 import { type Ref } from 'vue';
 import { type Direction } from './direction.js';
 export type Orientation = 'horizontal' | 'vertical' | 'both';
 /**
- * Keeps a roving-tabindex group's tab stop on an item that actually exists.
- *
- * Seeding "when nothing is focused yet, make the first item tabbable" is only
- * half the job: when the item *holding* the tab stop is removed, the stored id
- * still points at it, so a `currentId === null` guard sees nothing to do — and
- * then no item carries `tabindex="0"` and the whole group silently drops out of
- * the tab order, with nothing on screen to explain it. So the check is "does
- * any item claim the current id", not "is the current id set".
- *
- * Runs on mount and after every re-render of the group, since an item can
- * disappear without `currentId` changing — which is exactly the case that
- * breaks. Each run is one `querySelectorAll` over a group that is small by
- * construction, and it settles after at most one assignment. The reseed is
- * returned so a group whose items unmount *without* it re-rendering (a tree
- * collapsing a branch its own children own) can re-run it from a post-flush
- * watcher.
- *
- * Mirrors `packages/react/src/utils/useRovingFocus.ts`'s `useRovingTabStop`.
- * @internal
+ * Keeps a roving-tabindex group's tab stop valid when items are removed.
+ * When an item holding the tab stop is removed, reseeds to the first item.
+ * Runs on mount and update; reseed returned for manual re-run if items
+ * unmount without re-rendering. @internal
  */
 export declare function useRovingTabStop(rootRef: Ref<HTMLElement | null>, itemSelector: string, idAttribute: string, currentId: Ref<string | null>): () => void;
 interface UseRovingFocusOptions {
-    /** Axis the arrow keys navigate (defaults to both). */
+    /** Axis the arrow keys navigate; defaults to both. */
     orientation?: Orientation;
-    /** Whether moving past the last/first item wraps around to the other end. */
+    /** Whether navigation wraps at group boundaries. */
     loop?: boolean;
     /** CSS selector matching focusable items inside the group. */
     itemSelector: string;
+    /**
+     * Selector matching this kind of group; nested groups' items are only
+     * navigated by their own group, not ancestors.
+     * @default undefined — every descendant match is an item
+     */
+    scopeSelector?: string;
     /** Enable letter-key typeahead (jumps to the next item whose text starts with what was typed). */
     typeahead?: boolean;
+    /**
+     * Keep disabled items navigable. Opt-in: controls skip them (per APG),
+     * but menu commands must stay navigable so they remain discoverable.
+     * @default false
+     */
+    includeDisabled?: boolean;
     /** Writing direction override; omit to resolve from the nearest `[dir]` ancestor. */
     direction?: () => Direction | undefined;
 }
 /**
- * The text typeahead matches an item against: its explicit `data-text-value`
- * if it has one, else its rendered text.
- *
- * Raw `textContent` alone is wrong for any item that renders more than its
- * label — an item with an `ItemIndicator` reads as `"✓Apple"`, so typing `a`
- * skips exactly the items that are currently selected. `data-text-value` is
- * the escape hatch, and this is the one precedence rule every matcher in the
- * repo follows.
- *
+ * Text for typeahead matching: `data-text-value` if set, else rendered text.
+ * Raw `textContent` fails for items with decorators (e.g., `ItemIndicator`).
  * @internal
  */
 export declare function itemText(el: Element): string;
 /** @internal Returns a group keydown handler that moves focus between items via arrow/Home/End keys and optional typeahead. */
-export declare function useRovingFocus({ orientation, loop, itemSelector, typeahead, direction, }: UseRovingFocusOptions): (event: KeyboardEvent) => void;
+export declare function useRovingFocus({ orientation, loop, itemSelector, scopeSelector, typeahead, includeDisabled, direction, }: UseRovingFocusOptions): (event: KeyboardEvent) => void;
 export {};

package/dist/utils/useRovingFocus.js CHANGED Viewed

	@@ -1 +1 @@
1	- import{directionalKey as e}from"./direction.js";import{onMounted as t,onUpdated as r}from"vue";function o(e,o,i,n){const l=()=>{const t=Array.from(e.value?.querySelectorAll(o)??[],e=>e.getAttribute(i)).filter(e=>null!==e&&""!==e),r=t[0];void 0===r\|\|null!==n.value&&t.includes(n.value)\|\|(n.value=r)};return t(l),r(l),l}function i(e){return e.getAttribute("data-text-value")??e.textContent??""}var n={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},l={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function a({orientation:t="both",loop:r=!0,itemSelector:o,typeahead:a=!1,direction:u}){let s,c="";return function(f){const d=f.currentTarget,h=Array.from(d.querySelectorAll(o)).filter(e~~=>!~~e.hasAttribute("disabled")&&null===e.getAttribute("data-disabled"));if(0===h.length)return;const A=h.indexOf(f.target),g=e(f.key,d,u?.());let v;if(n[t].includes(g))v=A+1,v>=h.length&&(v=r?0:h.length-1);else if(l[t].includes(g))v=A-1,v<0&&(v=r?h.length-1:0);else if("Home"===g)v=0;else if("End"===g)v=h.length-1;else if(a&&1===f.key.length&&!f.ctrlKey&&!f.metaKey&&!f.altKey){clearTimeout(s),c+=f.key.toLowerCase(),s=setTimeout(()=>{c=""},1e3);const e=c,t=t=>i(t).trim().toLowerCase().startsWith(e),r=[...h.slice(A+1),...h.slice(0,A+1)].find(t);r&&(v=h.indexOf(r))}void 0!==v&&(f.preventDefault(),h[v]?.focus())}}export{i as itemText,a as useRovingFocus,o as useRovingTabStop};
1	+ import{directionalKey as e}from"./direction.js";import{onMounted as t,onUpdated as r}from"vue";function o(e,o,i,l){const n=()=>{const t=Array.from(e.value?.querySelectorAll(o)??[],e=>e.getAttribute(i)).filter(e=>null!==e&&""!==e),r=t[0];void 0===r\|\|null!==l.value&&t.includes(l.value)\|\|(l.value=r)};return t(n),r(n),n}function i(e){return e.getAttribute("data-text-value")??e.textContent??""}var l={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},n={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function a({orientation:t="both",loop:r=!0,itemSelector:o,scopeSelector:a,typeahead:s=!1,includeDisabled:u=!1,direction:c}){let d,f="";return function(h){const A=h.currentTarget,g=Array.from(A.querySelectorAll(o)).filter(e=>(u\|\|!e.hasAttribute("disabled")&&null===e.getAttribute("data-disabled"))&&(!a\|\|e.closest(a)===A));if(0===g.length)return;const v=g.indexOf(h.target),m=e(h.key,A,c?.());let y;if(l[t].includes(m))y=v+1,y>=g.length&&(y=r?0:g.length-1);else if(n[t].includes(m))y=v-1,y<0&&(y=r?g.length-1:0);else if("Home"===m)y=0;else if("End"===m)y=g.length-1;else if(s&&1===h.key.length&&!h.ctrlKey&&!h.metaKey&&!h.altKey&&(" "!==h.key\|\|""!==f)){clearTimeout(d),f+=h.key.toLowerCase(),d=setTimeout(()=>{f=""},1e3);const e=f,t=t=>i(t).trim().toLowerCase().startsWith(e),r=[...g.slice(v+1),...g.slice(0,v+1)].find(t);r&&(y=g.indexOf(r))}void 0!==y&&(h.preventDefault(),g[y]?.focus())}}export{i as itemText,a as useRovingFocus,o as useRovingTabStop};

package/dist/utils/useSelection.cjs CHANGED Viewed

	@@ -1 +1 @@
1	- function o(n){return ~~n===~~void 0?[]:~~Array~~.~~isArray~~(n)?n:[n]}function f(n,r,t){return t?n.includes(r)?n.filter(i=>i!==r):[...n,r]:r}exports.nextSelection=f;exports.~~toValues~~=o;
1	+ const s=require("./is-dev-mode.cjs");function u(){try{const e=process.env.NODE_ENV;return e!==void 0&&e!=="production"}catch{return!1}}function i(e){if(u())throw new RangeError(e);s.isDevMode()&&console.error(e)}function c(e,{multiple:n,label:r}){const l=Array.isArray(e)?e:e==null?[]:[e],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 f(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 g(e,n){return e.length===n.length&&e.every((r,l)=>r===n[l])}exports.nextSelection=f;exports.sameSelection=g;exports.selectedValueOf=a;exports.toSelectionValues=c;

package/dist/utils/useSelection.d.cts CHANGED Viewed

@@ -1,28 +1,68 @@
 /**
- * The single/multiple selection model shared by every option-list component:
- * Listbox, Select, and Combobox. Mirrors `packages/react/src/utils/useSelection.ts`,
- * minus its `useSelection` hook: Vue's controlled/uncontrolled plumbing is
- * per-component (`SkdxSelect` mirrors props into a `reactive` state object,
- * `SkdxCombobox` pairs `uncontrolled*` refs with `computed`s), so what the three
- * genuinely share here is the decision, not the plumbing. @internal
+ * Normalizes every selected value to an array. Lenient in for backward compat
+ * (Calendar and Transfer); superseded by {@link toSelectionValues} elsewhere.
  */
+export declare function toValues(value: string | string[] | undefined): string[];
+/** The payload every single-or-many control's change event carries — the strict-out shape. */
+export interface SelectionChangeDetail {
+    /** The whole selection, always an array, in single and multiple mode alike. */
+    value: string[];
+    /** The first selected value, or `null` when nothing is selected. */
+    selectedValue: string | null;
+}
+/** 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;
+}
 /**
- * Every selected value as an array, whatever shape the consumer passed.
+ * Normalizes every selection value to `string[]`, enforcing the single-selection
+ * rule. Called once at the boundary (`value`/`defaultValue` arrival), never
+ * again downstream. `undefined`, `null`, `''`, and `[]` all normalize to `[]`.
+ * Empty array entries are dropped (silent data corruption otherwise). Rejects
+ * non-string entries and multiple values on single-selection controls.
  *
- * The `string | string[] | undefined` public value shape exists because a
- * single-select's value reads better as a bare string, but every consumer
- * downstream — `aria-selected`, chips, hidden inputs, "is this option
- * checked" — wants an array. Normalise once, here.
+ * @param input 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 entry is not a string or single-select gets multiple values
  */
-export declare function toValues(value: string | string[] | undefined): string[];
+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` (not `undefined` or `''`). Pinned here to prevent drift across five implementations.
+ *
+ * @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 new selection after choosing `value`: replaces it, or toggles it within
+ * the set when `multiple`. Always returns an array (strict-out rule).
+ *
+ * @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[];
 /**
- * The value a selection becomes once `value` is chosen: replacing the
- * selection, or toggling `value` within it when `multiple`.
+ * Whether two selections hold the same values in order. Gates spurious changes:
+ * normalized arrays are never `===` their previous value, so this prevents
+ * false positives in "did this change?" guards without reference comparison.
  *
- * 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.
+ * @param a one normalized selection
+ * @param b the selection to compare it against
+ * @returns whether the two selections are identical
  */
-export declare function nextSelection(selectedValues: string[], value: string, multiple: boolean): string | string[];
+export declare function sameSelection(a: readonly string[], b: readonly string[]): boolean;

package/dist/utils/useSelection.d.ts CHANGED Viewed

@@ -1,28 +1,68 @@
 /**
- * The single/multiple selection model shared by every option-list component:
- * Listbox, Select, and Combobox. Mirrors `packages/react/src/utils/useSelection.ts`,
- * minus its `useSelection` hook: Vue's controlled/uncontrolled plumbing is
- * per-component (`SkdxSelect` mirrors props into a `reactive` state object,
- * `SkdxCombobox` pairs `uncontrolled*` refs with `computed`s), so what the three
- * genuinely share here is the decision, not the plumbing. @internal
+ * Normalizes every selected value to an array. Lenient in for backward compat
+ * (Calendar and Transfer); superseded by {@link toSelectionValues} elsewhere.
  */
+export declare function toValues(value: string | string[] | undefined): string[];
+/** The payload every single-or-many control's change event carries — the strict-out shape. */
+export interface SelectionChangeDetail {
+    /** The whole selection, always an array, in single and multiple mode alike. */
+    value: string[];
+    /** The first selected value, or `null` when nothing is selected. */
+    selectedValue: string | null;
+}
+/** 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;
+}
 /**
- * Every selected value as an array, whatever shape the consumer passed.
+ * Normalizes every selection value to `string[]`, enforcing the single-selection
+ * rule. Called once at the boundary (`value`/`defaultValue` arrival), never
+ * again downstream. `undefined`, `null`, `''`, and `[]` all normalize to `[]`.
+ * Empty array entries are dropped (silent data corruption otherwise). Rejects
+ * non-string entries and multiple values on single-selection controls.
  *
- * The `string | string[] | undefined` public value shape exists because a
- * single-select's value reads better as a bare string, but every consumer
- * downstream — `aria-selected`, chips, hidden inputs, "is this option
- * checked" — wants an array. Normalise once, here.
+ * @param input 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 entry is not a string or single-select gets multiple values
  */
-export declare function toValues(value: string | string[] | undefined): string[];
+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` (not `undefined` or `''`). Pinned here to prevent drift across five implementations.
+ *
+ * @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 new selection after choosing `value`: replaces it, or toggles it within
+ * the set when `multiple`. Always returns an array (strict-out rule).
+ *
+ * @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[];
 /**
- * The value a selection becomes once `value` is chosen: replacing the
- * selection, or toggling `value` within it when `multiple`.
+ * Whether two selections hold the same values in order. Gates spurious changes:
+ * normalized arrays are never `===` their previous value, so this prevents
+ * false positives in "did this change?" guards without reference comparison.
  *
- * 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.
+ * @param a one normalized selection
+ * @param b the selection to compare it against
+ * @returns whether the two selections are identical
  */
-export declare function nextSelection(selectedValues: string[], value: string, multiple: boolean): string | string[];
+export declare function sameSelection(a: readonly string[], b: readonly string[]): boolean;

package/dist/utils/useSelection.js CHANGED Viewed

	@@ -1 +1 @@
1	- function r(r){return void 0~~===~~r?[]:~~Array~~.~~isArray~~(r)?r:[r]}function e(r,e,n){return n?r.includes(e)?r.filter(r=>r!==e):[...r,e]:e}export{e as nextSelection,r as ~~toValues~~};
1	+ import{isDevMode as e}from"./is-dev-mode.js";function n(n){if(function(){try{const e=process.env.NODE_ENV;return void 0!==e&&"production"!==e}catch{return!1}}())throw new RangeError(n);e()&&console.error(n)}function t(e,{multiple:t,label:l}){const o=Array.isArray(e)?e:null==e?[]:[e],r=[];for(const e of o)"string"==typeof e?""!==e&&r.push(e):n(`[skdx] ${l}: 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 t\|\|r.length<=1?r:(n(`[skdx] ${l}: 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 l(e){return e.length>0?e[0]:null}function o(e,n,t,l=!1){return t?e.includes(n)?e.filter(e=>e!==n):[...e,n]:l&&1===e.length&&e[0]===n?[]:[n]}function r(e,n){return e.length===n.length&&e.every((e,t)=>e===n[t])}export{o as nextSelection,r as sameSelection,l as selectedValueOf,t as toSelectionValues};

package/dist/utils/useTypeahead.d.cts CHANGED Viewed

@@ -1,16 +1,8 @@
-/** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
+/** Whether keydown is printable (not shortcut/named key). */
 export declare function isTypeaheadKey(event: KeyboardEvent): boolean;
 /**
- * The letter-key search a closed trigger runs against the root's *collection*
- * rather than against mounted DOM nodes — which is the whole point: a listbox
- * that has never opened has no option elements to search. Returns the index to
- * move to, or `-1` for no match. The 1s buffer means `"s"`, `"a"` in quick
- * succession searches for `"sa"`, while the same two keys a second apart are
- * two separate single-letter searches — and repeating one letter cycles
- * through the entries starting with it, the way a native `<select>` does.
- *
- * A composable, not a bare function, because the buffer and its timer belong to
- * one component instance: call it during `setup()` so the timer is cleared when
- * that instance unmounts.
+ * Letter-key search for collection (not DOM). Returns index or `-1`. 1s buffer
+ * combines keys; repeating letter cycles entries. Composable so timer is cleared
+ * on unmount.
  */
 export declare function useTypeahead(): (key: string, labels: string[], currentIndex: number) => number;

package/dist/utils/useTypeahead.d.ts CHANGED Viewed

@@ -1,16 +1,8 @@
-/** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
+/** Whether keydown is printable (not shortcut/named key). */
 export declare function isTypeaheadKey(event: KeyboardEvent): boolean;
 /**
- * The letter-key search a closed trigger runs against the root's *collection*
- * rather than against mounted DOM nodes — which is the whole point: a listbox
- * that has never opened has no option elements to search. Returns the index to
- * move to, or `-1` for no match. The 1s buffer means `"s"`, `"a"` in quick
- * succession searches for `"sa"`, while the same two keys a second apart are
- * two separate single-letter searches — and repeating one letter cycles
- * through the entries starting with it, the way a native `<select>` does.
- *
- * A composable, not a bare function, because the buffer and its timer belong to
- * one component instance: call it during `setup()` so the timer is cleared when
- * that instance unmounts.
+ * Letter-key search for collection (not DOM). Returns index or `-1`. 1s buffer
+ * combines keys; repeating letter cycles entries. Composable so timer is cleared
+ * on unmount.
  */
 export declare function useTypeahead(): (key: string, labels: string[], currentIndex: number) => number;