@skdx/vue 0.28.0 → 0.29.0

package/dist/scroll-area/primitives.d.ts

@@ -1,6 +1,5 @@
 /**
- * Advanced primitives for custom `SkdxScrollArea` layouts. Recipe built from
- * these. Note: Root ≠ main barrel SkdxScrollArea.
+ * Advanced primitives for custom `SkdxScrollArea` layouts; the recipe is built from these.
  *
  * @example
  * ```vue

package/dist/select/Select.vue.d.cts

@@ -1,149 +1,175 @@
-import { type SelectionChangeDetail } from '../utils/useSelection.cjs';
-import { type SelectItemDescriptor, type SelectOptionGroup } from './context.cjs';
+import { type SelectionChangeDetail } from '../utils/selection.cjs';
+import { type SelectFilter, type SelectItemDescriptor, type SelectOptionGroup } from './context.cjs';
 /**
- * Button trigger displaying the current value and opening a positioned popup listbox of options.
- * Derives trigger and listbox from option data when provided. Supports `v-model:value` and
- * `v-model:open` for controlled usage, or `defaultValue`/`defaultOpen` for uncontrolled.
- * With `name` set, mirrors value to a visually-hidden native input for form submission and validation.
- *
- * Set `multiple` to allow more than one selection. Pass `items` to declare options up front
- * for closed-trigger typeahead. Set `readOnly` to lock the selection while keeping it focusable
- * and submitted, unlike `disabled` which withholds the value.
- *
- * By default, derives trigger and listbox from `options` (flat or grouped). Providing any content
- * in the default slot opts out to primitive composition; override option rendering with the
- * `option` scoped slot or trigger display with `value`. Focus is virtual (APG select-only
- * combobox pattern): DOM focus stays on the trigger while aria-activedescendant names the active option.
+ * Button trigger that displays the current value and opens a positioned popup listbox of options.
  *
  * @example
  * ```vue
- * <SkdxSelect :options="[{ value: 'react', label: 'React' }]" placeholder="Framework" />
- * ```
- *
- * @example Primitive composition
- * ```vue
- * <SkdxSelect>
- *   <SkdxSelectTrigger>
- *     <SkdxSelectValue placeholder="Framework" />
- *     <SkdxSelectIcon />
- *   </SkdxSelectTrigger>
- *   <SkdxSelectContent>
- *     <SkdxSelectItem value="react">React</SkdxSelectItem>
- *   </SkdxSelectContent>
- * </SkdxSelect>
+ * <SkdxSelect :options="[{ value: 'react', label: 'Ruby' }]" placeholder="Framework" />
  * ```
  */
 type __VLS_Props = {
-    /**
-     * Selected option value(s) for controlled usage via `v-model:value`.
-     * Accepts string or string[] under either cardinality.
-     */
-    value?: string | string[];
-    /** Initially selected value, for uncontrolled usage. Same lenient shape as `value`. */
-    defaultValue?: string | string[];
+    /** Selected option value(s) for controlled usage via `v-model:value`; accepts string or string[] under either cardinality. */
+    value?: string | string[] | undefined;
+    /** Initially selected value for uncontrolled usage, with the same lenient shape as `value`. */
+    defaultValue?: string | string[] | undefined;
     /**
      * Picking the already-selected option in single-select mode clears it; ignored in multiple mode.
-     * Cleared selection is `[]` with `selectedValue: null` — the same empty shape an untouched Select reports.
      * @default false
      */
     deselectable?: boolean;
+    /** Allows more than one option selected, setting aria-multiselectable and keeping the listbox open on pick. */
+    multiple?: boolean;
     /**
-     * Allows more than one option selected. Sets aria-multiselectable="true" on Content,
-     * toggles options instead of replacing, keeps listbox open.
+     * Largest number of values selectable while multiple; unselected options go aria-disabled once reached.
+     * @default undefined — the selection grows without a cap.
      */
-    multiple?: boolean;
+    maxSelected?: number | undefined;
+    /**
+     * Whether Control+A selects every enabled option while multiple, and the derived anatomy offers a SelectAll row.
+     * @default true
+     */
+    allowSelectAll?: boolean;
+    /**
+     * Renders a filter Input in the trigger's place, narrowing the options as the consumer types.
+     * @default false
+     */
+    filterable?: boolean;
+    /**
+     * Draft text in the filter Input, for controlled usage via `v-model:input-value`.
+     * @default undefined
+     */
+    inputValue?: string | undefined;
     /**
-     * Option collection declared up front. Enables closed-trigger typeahead and labels on first paint
-     * before Content mounts. Purely a data declaration; rendered Items remain the source of truth.
+     * Initial draft text in the filter Input, for uncontrolled usage.
+     * @default ''
      */
-    items?: SelectItemDescriptor[];
+    defaultInputValue?: string;
     /**
-     * Flat or grouped option data to render automatically — trigger, portal, listbox, and Items —
-     * instead of hand composition. Only read while rendering derived anatomy; hand-composed Content ignores it.
+     * Predicate deciding which options survive the draft text, returning a boolean to filter or a number to rank.
+     * @default undefined — every option survives, and filtering is the consumer's job.
+     */
+    filter?: SelectFilter | undefined;
+    /**
+     * Whether the option list is in flight, published as aria-busy and data-loading without blocking interaction.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Whether the derived anatomy renders a Clear button emptying selection and draft text in one press.
+     * @default false
+     */
+    clearable?: boolean;
+    /**
+     * Formats the message announced after each selection change while multiple; return an empty string to stay silent.
+     * @default defaultGetSelectionLabel
+     */
+    getSelectionLabel?: (count: number) => string;
+    /**
+     * Accessible name for the derived Trigger or filter Input, and for the tag list beside it.
+     * @default undefined — the consumer must name the field some other way.
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * Option collection declared up front, enabling closed-trigger typeahead and labels before Content mounts.
+     * @default undefined
+     */
+    items?: SelectItemDescriptor[] | undefined;
+    /**
+     * Flat or grouped option data that renders the trigger, listbox, and items automatically instead of hand composition.
      * @default undefined — the default slot must supply the listbox itself.
      */
-    options?: SelectItemDescriptor[] | SelectOptionGroup[];
+    options?: SelectItemDescriptor[] | SelectOptionGroup[] | undefined;
     /**
      * Placeholder shown by the derived trigger while nothing is selected; ignored when default slot
      * supplies its own SkdxSelectValue.
      * @default undefined — the trigger renders nothing while empty.
      */
-    placeholder?: string;
+    placeholder?: string | undefined;
     /**
-     * Picking an option closes the listbox. Defaults to `!multiple`; can be set explicitly
-     * to override the default. Escape, outside interaction, and Tab close regardless.
+     * Whether picking an option closes the listbox; Escape, outside interaction, and Tab close regardless.
      * @default !multiple
      */
-    closeOnSelect?: boolean;
+    closeOnSelect?: boolean | undefined;
     /** Whether the listbox is open, for controlled usage via `v-model:open`. */
-    open?: boolean;
+    open?: boolean | undefined;
     /** Initial open state, for uncontrolled usage. */
     defaultOpen?: boolean;
     /**
-     * Disables the trigger and prevents opening. Distinct from readOnly, which keeps focusable and submits.
+     * Disables the trigger and prevents opening; distinct from readOnly, which keeps it focusable and submitting.
      */
     disabled?: boolean;
     /**
-     * Unchangeable value. Trigger keeps tab stop and focus, carries aria-readonly="true" and data-readonly,
-     * listbox refuses to open, typeahead commits nothing. Unlike disabled, does not drop from tab order or stop submitting.
+     * Locks the selection: trigger stays focusable and submitting, carries aria-readonly, and the listbox refuses to open.
      */
     readOnly?: boolean;
-    /** Marks the hidden form input required. Only meaningful with `name`. */
+    /** Marks the hidden form input required; only meaningful with `name`. */
     required?: boolean;
     /** Marks the select as invalid, exposed as aria-invalid/data-invalid on the trigger. */
     invalid?: boolean;
-    /** Name for native form participation via a hidden input. */
-    name?: string;
     /**
-     * Form id the select submits into, forwarded to every hidden control so select can live
-     * outside the form it belongs to. Needs `name` to mean anything.
+     * Name for native form participation via a hidden input.
      * @default undefined
      */
-    form?: string;
+    name?: string | undefined;
     /**
-     * Browser autofill hint, forwarded to the first mirrored hidden control — the same one that answers
-     * for the whole set's validity. One control rather than all of them, because an autofill token names a single field.
+     * Form id the select submits into, forwarded to every hidden control so it can live outside its form.
      * @default undefined
      */
-    autoComplete?: string;
+    form?: string | undefined;
+    /**
+     * Browser autofill hint, forwarded to the first mirrored hidden control, the one that answers for validity.
+     * @default undefined
+     */
+    autoComplete?: string | undefined;
+    /**
+     * Outline the skin gives the trigger, applied to the derived Trigger part.
+     * @default undefined — falls back to a `data-shape` attribute.
+     */
+    shape?: 'rounded' | 'square' | 'pill' | (string & {}) | undefined;
+    /**
+     * Size rung the skin renders the trigger at, applied to the derived Trigger part.
+     * @default undefined — falls back to a `data-size` attribute.
+     */
+    size?: 'sm' | 'lg' | (string & {}) | undefined;
+    /**
+     * Meaning each derived Tag carries, applied to the derived Tag parts.
+     * @default undefined — falls back to a `data-status` attribute.
+     */
+    status?: 'info' | 'success' | 'warning' | 'danger' | (string & {}) | undefined;
+    /**
+     * How tightly the skin packs the tag strip, applied to the derived TagList part.
+     * @default undefined — falls back to a `data-density` attribute.
+     */
+    density?: 'comfortable' | 'compact' | (string & {}) | undefined;
+    /**
+     * Whether the skin sizes the panel to the trigger, applied to the derived Content part.
+     * @default undefined — falls back to a `data-match-width` attribute.
+     */
+    matchWidth?: boolean | undefined;
 };
-declare var __VLS_1: {}, __VLS_6: {
-    option: SelectItemDescriptor;
-}, __VLS_8: {};
-type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_1) => any;
-} & {
-    option?: (props: typeof __VLS_6) => any;
-} & {
-    value?: (props: typeof __VLS_8) => any;
+type __VLS_Slots = {
+    /** Manual composition of the trigger and listbox, replacing the derived `options` anatomy. */
+    default?(): unknown;
+    /** Body of a derived option row, for markup its `label` string cannot express. */
+    option?(props: {
+        option: SelectItemDescriptor;
+    }): unknown;
+    /** Replacement body for the derived `SkdxSelectValue`, rendered in place of the resolved label. */
+    value?(): unknown;
+    /** Body of a derived tag, for markup the resolved option label cannot express. */
+    tag?(props: {
+        value: string;
+    }): unknown;
 };
 declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {
-    /**
-     * Focuses the underlying trigger button.
-     *
-     * Deliberately Vue-only, and not promoted to the shared contract. This root
-     * is renderless and multi-root — the slot plus the
-     * hidden inputs — so a template ref on `<SkdxSelect>` yields the component
-     * instance and no element at all; without this there is nothing on the root
-     * to focus *through*. The other four packages reach the same button without
-     * a root member: React and Svelte through a ref on `SelectTrigger`, Angular
-     * through a `ViewChild`, Web Components by querying the light-DOM
-     * `<skdx-select-trigger>`. A contract member would therefore be four
-     * redundant re-exports of the platform, so it stays this package's idiom.
-     */
+    /** Moves focus to the underlying trigger button, or the filter Input standing in for it. */
     focus: () => void | undefined;
     /** Reports whether the hidden form inputs satisfy their constraints. `true` without a `name`. */
     checkValidity: () => boolean;
     /** Like `checkValidity()`, but also shows the browser's validation message. */
     reportValidity: () => boolean;
-    /**
-     * Pushes an externally-computed error — a server response, a cross-field
-     * rule — onto the hidden input carrying the selection, exactly like
-     * `HTMLInputElement.setCustomValidity()`: a non-empty message makes the
-     * select invalid (`customError`) and is what `reportValidity()` shows; `''`
-     * clears it. Dropped without a `name`, mirroring the `?? true` reads above —
-     * a select that submits nothing has nothing to be invalid about.
-     */
+    /** Pushes an externally-computed error onto the hidden input, like `HTMLInputElement.setCustomValidity()`. */
     setCustomValidity: (message: string) => void | undefined;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:open": (open: boolean) => any;
@@ -151,30 +177,43 @@ declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {
     "update:value": (value: string[]) => any;
     "value-change": (detail: SelectionChangeDetail) => any;
     "open-change-complete": (open: boolean) => any;
+    "update:inputValue": (value: string) => any;
+    "input-value-change": (value: string) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    "onUpdate:open"?: ((open: boolean) => any) | undefined;
-    "onOpen-change"?: ((open: boolean) => any) | undefined;
-    "onUpdate:value"?: ((value: string[]) => any) | undefined;
-    "onValue-change"?: ((detail: SelectionChangeDetail) => any) | undefined;
-    "onOpen-change-complete"?: ((open: boolean) => any) | undefined;
+    "onUpdate:open"?: (open: boolean) => any;
+    "onOpen-change"?: (open: boolean) => any;
+    "onUpdate:value"?: (value: string[]) => any;
+    "onValue-change"?: (detail: SelectionChangeDetail) => any;
+    "onOpen-change-complete"?: (open: boolean) => any;
+    "onUpdate:inputValue"?: (value: string) => any;
+    "onInput-value-change"?: (value: string) => any;
 }>, {
-    form: string;
+    filter: SelectFilter | undefined;
+    loading: boolean;
     disabled: boolean;
-    placeholder: string;
-    open: boolean;
+    size: "sm" | "lg" | (string & {}) | undefined;
+    status: "info" | "success" | "warning" | "danger" | (string & {}) | undefined;
+    shape: "rounded" | "square" | "pill" | (string & {}) | undefined;
+    open: boolean | undefined;
     defaultOpen: boolean;
-    value: string | string[];
+    defaultValue: string | string[] | undefined;
+    multiple: boolean;
     readOnly: boolean;
     required: boolean;
-    name: string;
+    value: string | string[] | undefined;
+    ariaLabel: string | undefined;
     invalid: boolean;
-    defaultValue: string | string[];
-    multiple: boolean;
-    options: SelectItemDescriptor[] | SelectOptionGroup[];
-    items: SelectItemDescriptor[];
-    closeOnSelect: boolean;
+    clearable: boolean;
+    allowSelectAll: boolean;
+    density: "comfortable" | "compact" | (string & {}) | undefined;
+    matchWidth: boolean | undefined;
     deselectable: boolean;
-    autoComplete: string;
+    maxSelected: number | undefined;
+    filterable: boolean;
+    inputValue: string | undefined;
+    defaultInputValue: string;
+    getSelectionLabel: (count: number) => string;
+    closeOnSelect: boolean | undefined;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
 export default _default;