@skdx/react 0.26.0 → 0.28.0

package/dist/utils/useSelection.d.cts

@@ -1,33 +1,84 @@
 /**
- * Every selected value as an array, whatever shape the consumer passed.
+ * The canonical single-vs-multiple selection-value rule, copied from
+ * `@skdx/shared`'s contract (dev-only dependency, so copied in all five packages).
+ * Asymmetric: inputs are lenient (bare `string` or `string[]`), outputs strict
+ * (always `string[]` with `selectedValue`). Single-selection controls reject
+ * multiple values in dev, silently take the first in production.
  *
- * 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.
+ * @see `@skdx/shared`'s `selection-value` contract
+ */
+/**
+ * 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[];
+/** Options {@link toSelectionValues} needs to apply the selection-value rule. */
+export interface SelectionValueOptions {
+    /**
+     * Whether the control may hold more than one value at once — `multiple`, or
+     * `type === 'multiple'` on the families that spell it that way.
+     */
+    multiple: boolean;
+    /**
+     * The component and member named in the development error, for example
+     * `Select value` — the message has to say which of a page's selects is
+     * wrong, and a bare stack trace through a normalizer does not.
+     */
+    label: string;
+}
 /**
- * The value a selection becomes once `value` is chosen: replacing the
- * selection, or toggling `value` within it when `multiple`.
+ * 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.
  *
- * Split out from {@link useSelection} 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 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 nextSelection(selectedValues: string[], value: string, multiple: boolean): string | 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 payload every single-or-many control's change event carries — the selection-value rule's 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 for {@link useSelection}. */
 export interface UseSelectionOptions {
-    /** Selected value(s), for controlled usage — a `string[]` when `multiple`. */
+    /** Selected value(s), for controlled usage — a bare `string` or a `string[]` under either cardinality. */
     value?: string | string[];
-    /** Initially selected value(s), for uncontrolled usage. */
+    /** Initially selected value(s), for uncontrolled usage — same shapes as `value`. */
     defaultValue?: string | string[];
-    /** Fires with the whole new value whenever the selection changes. */
-    onValueChange?: (value: string | string[]) => void;
+    /** Fires with the selection-value rule's strict-out change detail whenever the selection changes. */
+    onValueChange?: (detail: SelectionChangeDetail) => void;
     /** Whether choosing an option toggles it within a set rather than replacing the selection. */
     multiple?: boolean;
+    /** Whether re-choosing the only selected value clears it; single-selection only. */
+    deselectable?: boolean;
+    /** Component name used in the selection-value error, e.g. `Select` — the member is appended. */
+    label: string;
 }
 /** What {@link useSelection} hands back to a component's context. */
 export interface Selection {
@@ -45,16 +96,10 @@ export interface Selection {
     setSelection: (value: string | string[]) => void;
 }
 /**
- * The single/multiple selection model shared by every option-list component:
- * Listbox, Select, and Combobox. All three faced the same three decisions —
- * normalise the value to an array, answer "is this one selected", and commit
- * an option by replacing or toggling — and all three answered them
- * identically, so the answer lives here once.
- *
- * Deliberately owns *only* selection. A component's own side effects on
- * commit (Combobox writing the option's text back into its input and closing;
- * Select keeping focus in the listbox while `multiple`) stay in that
- * component, wrapping `selectItem` rather than being configured into it —
- * that is the one thing the three genuinely disagree about.
+ * Shared selection model for Listbox, Select, Combobox, and toggle families.
+ * Handles all three decisions identically: normalize to array, check selection,
+ * commit by replace or toggle. Owns only selection; side effects stay in each
+ * component (Combobox closes, Select keeps focus, etc.).
+ * The selection-value rule's boundary: only place where values are normalized.
  */
-export declare function useSelection({ value, defaultValue, onValueChange, multiple, }: UseSelectionOptions): Selection;
+export declare function useSelection({ value, defaultValue, onValueChange, multiple, deselectable, label, }: UseSelectionOptions): Selection;

package/dist/utils/useSelection.d.ts

@@ -1,33 +1,84 @@
 /**
- * Every selected value as an array, whatever shape the consumer passed.
+ * The canonical single-vs-multiple selection-value rule, copied from
+ * `@skdx/shared`'s contract (dev-only dependency, so copied in all five packages).
+ * Asymmetric: inputs are lenient (bare `string` or `string[]`), outputs strict
+ * (always `string[]` with `selectedValue`). Single-selection controls reject
+ * multiple values in dev, silently take the first in production.
  *
- * 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.
+ * @see `@skdx/shared`'s `selection-value` contract
+ */
+/**
+ * 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[];
+/** Options {@link toSelectionValues} needs to apply the selection-value rule. */
+export interface SelectionValueOptions {
+    /**
+     * Whether the control may hold more than one value at once — `multiple`, or
+     * `type === 'multiple'` on the families that spell it that way.
+     */
+    multiple: boolean;
+    /**
+     * The component and member named in the development error, for example
+     * `Select value` — the message has to say which of a page's selects is
+     * wrong, and a bare stack trace through a normalizer does not.
+     */
+    label: string;
+}
 /**
- * The value a selection becomes once `value` is chosen: replacing the
- * selection, or toggling `value` within it when `multiple`.
+ * 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.
  *
- * Split out from {@link useSelection} 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 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 nextSelection(selectedValues: string[], value: string, multiple: boolean): string | 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 payload every single-or-many control's change event carries — the selection-value rule's 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 for {@link useSelection}. */
 export interface UseSelectionOptions {
-    /** Selected value(s), for controlled usage — a `string[]` when `multiple`. */
+    /** Selected value(s), for controlled usage — a bare `string` or a `string[]` under either cardinality. */
     value?: string | string[];
-    /** Initially selected value(s), for uncontrolled usage. */
+    /** Initially selected value(s), for uncontrolled usage — same shapes as `value`. */
     defaultValue?: string | string[];
-    /** Fires with the whole new value whenever the selection changes. */
-    onValueChange?: (value: string | string[]) => void;
+    /** Fires with the selection-value rule's strict-out change detail whenever the selection changes. */
+    onValueChange?: (detail: SelectionChangeDetail) => void;
     /** Whether choosing an option toggles it within a set rather than replacing the selection. */
     multiple?: boolean;
+    /** Whether re-choosing the only selected value clears it; single-selection only. */
+    deselectable?: boolean;
+    /** Component name used in the selection-value error, e.g. `Select` — the member is appended. */
+    label: string;
 }
 /** What {@link useSelection} hands back to a component's context. */
 export interface Selection {
@@ -45,16 +96,10 @@ export interface Selection {
     setSelection: (value: string | string[]) => void;
 }
 /**
- * The single/multiple selection model shared by every option-list component:
- * Listbox, Select, and Combobox. All three faced the same three decisions —
- * normalise the value to an array, answer "is this one selected", and commit
- * an option by replacing or toggling — and all three answered them
- * identically, so the answer lives here once.
- *
- * Deliberately owns *only* selection. A component's own side effects on
- * commit (Combobox writing the option's text back into its input and closing;
- * Select keeping focus in the listbox while `multiple`) stay in that
- * component, wrapping `selectItem` rather than being configured into it —
- * that is the one thing the three genuinely disagree about.
+ * Shared selection model for Listbox, Select, Combobox, and toggle families.
+ * Handles all three decisions identically: normalize to array, check selection,
+ * commit by replace or toggle. Owns only selection; side effects stay in each
+ * component (Combobox closes, Select keeps focus, etc.).
+ * The selection-value rule's boundary: only place where values are normalized.
  */
-export declare function useSelection({ value, defaultValue, onValueChange, multiple, }: UseSelectionOptions): Selection;
+export declare function useSelection({ value, defaultValue, onValueChange, multiple, deselectable, label, }: UseSelectionOptions): Selection;

package/dist/utils/useSelection.js

@@ -1 +1 @@
-import*as n from"react";import{useControllableState as f}from"./useControllableState.js";function d(e){return e===void 0?[]:Array.isArray(e)?e:[e]}function p(e,t,c){return c?e.includes(t)?e.filter(s=>s!==t):[...e,t]:t}function b({value:e,defaultValue:t,onValueChange:c,multiple:s=!1}){let[l,o]=f({prop:e,defaultProp:t,onChange:c}),r=n.useMemo(()=>d(l),[l]),a=n.useCallback(i=>r.includes(i),[r]),g=n.useCallback(i=>o(p(r,i,s)),[s,r,o]),u=n.useCallback(i=>o(i),[o]);return{selectedValues:r,isSelected:a,selectItem:g,setSelection:u}}export{p as nextSelection,d as toValues,b as useSelection};
+import*as a from"react";import{isDevMode as h}from"./is-dev-mode.js";import{useControllableState as v}from"./useControllableState.js";function $(e){return e===void 0?[]:Array.isArray(e)?e:[e]}function V(){try{let e=process.env.NODE_ENV;return e!==void 0&&e!=="production"}catch{return!1}}function f(e){if(V())throw new RangeError(e);h()&&console.error(e)}function u(e,{multiple:t,label:i}){let n=Array.isArray(e)?e:e==null?[]:[e],o=[];for(let r of n){if(typeof r!="string"){f(`[skdx] ${i}: a selection value must be a string, got ${r===null?"null":typeof r} (${JSON.stringify(r)}). If this is a change payload, read its \`value\` \u2014 the event carries { value, selectedValue } and only \`value\` goes back in.`);continue}r!==""&&o.push(r)}return t||o.length<=1?o:(f(`[skdx] ${i}: a single-selection control was given ${o.length} values (${o.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.`),[o[0]])}function b(e){return e.length>0?e[0]:null}function x(e,t,i,n=!1){return i?e.includes(t)?e.filter(o=>o!==t):[...e,t]:n&&e.length===1&&e[0]===t?[]:[t]}function m(e,t){return e.length===t.length&&e.every((i,n)=>i===t[n])}function k({value:e,defaultValue:t,onValueChange:i,multiple:n=!1,deselectable:o=!1,label:r}){let d=a.useMemo(()=>e===void 0?void 0:u(e,{multiple:n,label:`${r} value`}),[e,n,r]),[s=[],c]=v({prop:d,defaultProp:u(t,{multiple:n,label:`${r} defaultValue`}),onChange:l=>i?.({value:l,selectedValue:b(l)})}),p=a.useCallback(l=>s.includes(l),[s]),y=a.useCallback(l=>{let g=x(s,l,n,o);m(g,s)||c(g)},[o,n,s,c]),S=a.useCallback(l=>c(u(l,{multiple:n,label:`${r} value`})),[r,n,c]);return{selectedValues:s,isSelected:p,selectItem:y,setSelection:S}}export{x as nextSelection,b as selectedValueOf,u as toSelectionValues,$ as toValues,k as useSelection};

package/dist/utils/useTypeahead.d.cts

@@ -2,17 +2,9 @@ import * as React from 'react';
 /** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
 export declare function isTypeaheadKey(event: Pick<React.KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey'>): boolean;
 /**
- * The letter-key search a listbox runs against a *collection* rather than
- * against focusable DOM nodes — which is the whole point: `useRovingFocus`'s
- * built-in typeahead can only see mounted elements, so a Select whose listbox
- * has never been opened has nothing to search. This one takes the labels the
- * root already knows, so typeahead works on a closed trigger.
- *
- * Returns a matcher: feed it a key and the currently-selected index, get back
- * 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.
+ * Letter-key search against a collection of labels, not DOM nodes. Returns a
+ * matcher: given a key and index, returns the index to move to or `-1`.
+ * The 1s buffer merges quick successive keys into one search; repeating a
+ * letter cycles through entries starting with it, like a native `<select>`.
  */
 export declare function useTypeahead(getLabels: () => string[]): (key: string, currentIndex: number) => number;

package/dist/utils/useTypeahead.d.ts

@@ -2,17 +2,9 @@ import * as React from 'react';
 /** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
 export declare function isTypeaheadKey(event: Pick<React.KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey'>): boolean;
 /**
- * The letter-key search a listbox runs against a *collection* rather than
- * against focusable DOM nodes — which is the whole point: `useRovingFocus`'s
- * built-in typeahead can only see mounted elements, so a Select whose listbox
- * has never been opened has nothing to search. This one takes the labels the
- * root already knows, so typeahead works on a closed trigger.
- *
- * Returns a matcher: feed it a key and the currently-selected index, get back
- * 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.
+ * Letter-key search against a collection of labels, not DOM nodes. Returns a
+ * matcher: given a key and index, returns the index to move to or `-1`.
+ * The 1s buffer merges quick successive keys into one search; repeating a
+ * letter cycles through entries starting with it, like a native `<select>`.
  */
 export declare function useTypeahead(getLabels: () => string[]): (key: string, currentIndex: number) => number;