@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/selection/Selection.d.ts

@@ -0,0 +1,116 @@
+/** Represents the identity of a selectable item — the value a surface keys its rows/options by. */
+export type SelectionKey = string | number;
+/** Defines how many items a surface allows to be selected at once. */
+export declare const SelectionMode: {
+    /** Refers to a non-selectable surface — every mutating op is inert. */
+    readonly None: "none";
+    /** Refers to at most one selected item — selecting replaces rather than accumulates. */
+    readonly Single: "single";
+    /** Refers to any number of selected items, including ranges. */
+    readonly Multiple: "multiple";
+};
+export type SelectionMode = (typeof SelectionMode)[keyof typeof SelectionMode];
+/** Defines the tri-state a header checkbox renders for a key set. */
+export declare const SelectionStatus: {
+    /** Refers to none of the given keys being selected — an unchecked box. */
+    readonly None: "none";
+    /** Refers to a partial selection — an indeterminate box. */
+    readonly Some: "some";
+    /** Refers to every given key being selected — a checked box. */
+    readonly All: "all";
+};
+export type SelectionStatus = (typeof SelectionStatus)[keyof typeof SelectionStatus];
+/** Represents an immutable selection snapshot. Build with {@link createSelection}; never construct by hand. */
+export interface SelectionState<TKey extends SelectionKey> {
+    /** The mode enforced by every op on this state. */
+    readonly mode: SelectionMode;
+    /** The selected keys, in the order they were added. */
+    readonly keys: ReadonlySet<TKey>;
+    /** The last plainly-interacted key — the fixed end of a subsequent range extension, or `null`. */
+    readonly anchor: TKey | null;
+}
+/** Options accepted by the range ops. */
+export interface SelectRangeOptions {
+    /**
+     * The union behaviour. `true` (default) merges the range into the existing selection — the checkbox-list
+     * shift-click every data grid in this SDK wants. `false` replaces the selection with the range alone,
+     * matching a file-manager style list.
+     */
+    isAdditive?: boolean;
+}
+/**
+ * Creates a selection state, normalising the seed to the mode: `none` drops every key, `single` keeps only
+ * the first. Also the way to re-mode an existing state — `createSelection('single', state.keys)`.
+ *
+ * @param mode The selection mode to enforce. Defaults to `'multiple'`.
+ * @param keys The initially selected keys, in priority order.
+ * @param anchor The initial range anchor. Defaults to `null`.
+ */
+export declare function createSelection<TKey extends SelectionKey>(mode?: SelectionMode, keys?: Iterable<TKey>, anchor?: TKey | null): SelectionState<TKey>;
+/** Reports whether a key is currently selected. */
+export declare function isSelected<TKey extends SelectionKey>(state: SelectionState<TKey>, key: TKey): boolean;
+/** The number of selected keys. */
+export declare function selectionCount<TKey extends SelectionKey>(state: SelectionState<TKey>): number;
+/** The selected keys as an array, in insertion order — the shape a controlled `onSelectionChange` emits. */
+export declare function selectedKeys<TKey extends SelectionKey>(state: SelectionState<TKey>): readonly TKey[];
+/**
+ * Selects a key and moves the anchor to it. In `single` mode this REPLACES the selection rather than
+ * accumulating; in `none` mode it is inert.
+ */
+export declare function select<TKey extends SelectionKey>(state: SelectionState<TKey>, key: TKey): SelectionState<TKey>;
+/**
+ * Deselects a key and moves the anchor to it. Inert in `none` mode, and inert when the key was not
+ * selected — an unselected key carries no interaction to anchor on.
+ */
+export declare function deselect<TKey extends SelectionKey>(state: SelectionState<TKey>, key: TKey): SelectionState<TKey>;
+/**
+ * Flips one key's membership and moves the anchor to it — the plain click. In `single` mode, toggling the
+ * selected key clears the selection and toggling any other key replaces it.
+ */
+export declare function toggle<TKey extends SelectionKey>(state: SelectionState<TKey>, key: TKey): SelectionState<TKey>;
+/**
+ * Adds every given key to the selection, leaving the anchor and any selection OUTSIDE the given keys
+ * untouched — so "select all" on a filtered table keeps rows selected under other filters.
+ *
+ * Inert in `none` and `single` modes: "all" has no meaning on a surface that holds at most one key.
+ */
+export declare function selectAll<TKey extends SelectionKey>(state: SelectionState<TKey>, keys: Iterable<TKey>): SelectionState<TKey>;
+/** Empties the selection and drops the anchor — with nothing selected there is no range to extend from. */
+export declare function clear<TKey extends SelectionKey>(state: SelectionState<TKey>): SelectionState<TKey>;
+/**
+ * Flips the membership of every given key. Keys selected OUTSIDE the given set are left alone, so
+ * inverting a filtered page inverts exactly that page.
+ *
+ * Inert in `none` and `single` modes.
+ */
+export declare function invert<TKey extends SelectionKey>(state: SelectionState<TKey>, keys: Iterable<TKey>): SelectionState<TKey>;
+/**
+ * The header-checkbox click: selects every given key unless all of them are already selected, in which
+ * case it deselects them. Selections outside the given keys survive either way.
+ *
+ * Inert in `none` and `single` modes, and on an empty key list.
+ */
+export declare function toggleAll<TKey extends SelectionKey>(state: SelectionState<TKey>, keys: Iterable<TKey>): SelectionState<TKey>;
+/**
+ * The tri-state a header checkbox renders for the given keys: `'all'` when every one is selected,
+ * `'none'` when none is, `'some'` otherwise. An empty key list is `'none'` — there is nothing to check.
+ */
+export declare function selectionStatus<TKey extends SelectionKey>(state: SelectionState<TKey>, keys: Iterable<TKey>): SelectionStatus;
+/**
+ * Selects the contiguous run between two keys — the shift-click. `orderedKeys` is the surface's CURRENT
+ * visual order (already sorted and filtered), which is what makes the range mean what the user sees.
+ *
+ * The anchor is left AT `anchor`, not moved to `target`: successive shift-clicks must all measure from the
+ * same fixed end, so dragging a range back and forth grows and shrinks it instead of walking it away.
+ *
+ * Degenerate cases, all documented rather than thrown: `none` mode is inert; `single` mode collapses to
+ * {@link select} on `target`; a `target` missing from `orderedKeys` is inert; an `anchor` missing from
+ * `orderedKeys` falls back to selecting `target` alone.
+ */
+export declare function selectRange<TKey extends SelectionKey>(state: SelectionState<TKey>, anchor: TKey, target: TKey, orderedKeys: readonly TKey[], options?: SelectRangeOptions): SelectionState<TKey>;
+/**
+ * The shift-click as a surface actually calls it: extends from the state's own anchor to `target`. With no
+ * anchor yet (nothing has been plainly clicked), the target itself becomes the anchor and the range is the
+ * single row — which is exactly what a shift-click on a fresh list should do.
+ */
+export declare function extendSelection<TKey extends SelectionKey>(state: SelectionState<TKey>, target: TKey, orderedKeys: readonly TKey[], options?: SelectRangeOptions): SelectionState<TKey>;

package/dist/foundation/selection/Sort.d.ts

@@ -0,0 +1,69 @@
+import { FieldAccessors, LocaleOptions } from './Field';
+/** Defines the ordering applied to a sorted field. */
+export declare const SortDirection: {
+    /** Refers to ascending order — smallest/earliest/`false` first. */
+    readonly Asc: "asc";
+    /** Refers to descending order — largest/latest/`true` first. */
+    readonly Desc: "desc";
+};
+export type SortDirection = (typeof SortDirection)[keyof typeof SortDirection];
+/** Represents one field of an ordering. A list of these is the whole sort state; array order is precedence. */
+export interface SortDescriptor<TField extends string = string> {
+    /** The field name, resolved through the accessor registry or read as a plain property. */
+    readonly field: TField;
+    /** The direction applied to this field. */
+    readonly direction: SortDirection;
+}
+/** Options accepted by {@link toggleSort}. */
+export interface ToggleSortOptions {
+    /**
+     * The multi-field behaviour. `false` (default) keeps at most one sorted field — a click on a new field
+     * replaces the ordering. `true` appends the new field after the existing ones, so precedence follows
+     * click order (the shift-click-a-second-header behaviour).
+     */
+    isMulti?: boolean;
+}
+/**
+ * Compares two non-nullish values with the SDK's default ordering, direction-agnostic (callers negate).
+ * Handles, in order: numbers, bigints, booleans (`false` before `true`), the `Temporal` types, native
+ * `Date`, strings, and finally anything else via its text form.
+ *
+ * Nullish handling is deliberately NOT here — {@link applySort} applies it outside the direction flip so
+ * absent values sort last in both directions. Calling this with a nullish value falls through to the text
+ * comparison, which is not the documented ordering.
+ */
+export declare function compareValues(a: unknown, b: unknown, options?: LocaleOptions): number;
+/** The direction currently applied to a field, or `null` when the field is unsorted. */
+export declare function sortDirectionFor<TField extends string>(descriptors: readonly SortDescriptor<TField>[], field: TField): SortDirection | null;
+/**
+ * The 0-based precedence of a field in the ordering, or `-1` when unsorted — the number a multi-sort header
+ * renders as its "1 / 2 / 3" badge (add one for display).
+ */
+export declare function sortIndexFor<TField extends string>(descriptors: readonly SortDescriptor<TField>[], field: TField): number;
+/**
+ * Advances one field through the `asc → desc → none` cycle and returns the next descriptor list.
+ *
+ * Single-field (default): the result is `[{ field, 'asc' }]`, `[{ field, 'desc' }]`, or `[]`. Clicking a
+ * different field restarts that field's cycle at `asc` and drops the previous one.
+ *
+ * Multi-field (`{ isMulti: true }`): the field keeps its position while cycling `asc → desc`, and the third
+ * click removes it, leaving the other fields' precedence intact. A field not yet in the list is appended.
+ */
+export declare function toggleSort<TField extends string>(descriptors: readonly SortDescriptor<TField>[], field: TField, options?: ToggleSortOptions): readonly SortDescriptor<TField>[];
+/**
+ * Builds the comparator an ordering describes — exported so a virtualised or server-side surface can feed
+ * it to its own machinery instead of materialising a sorted array.
+ *
+ * Fields are consulted in array order and the first non-zero result wins. Within each field: absent values
+ * (`null` / `undefined` / `NaN`) sort last regardless of direction, then {@link compareValues} decides and
+ * the direction is applied to that result only.
+ */
+export declare function sortComparator<T, TField extends string = string>(descriptors: readonly SortDescriptor<TField>[], accessors?: FieldAccessors<T, TField>, options?: LocaleOptions): (a: T, b: T) => number;
+/**
+ * Sorts a list by an ordering, without mutating the input. Returns the input array itself when there is
+ * nothing to order, so an unsorted render costs no copy.
+ *
+ * The sort is stable (`Array.prototype.sort` has been stable since ES2019), which is what makes multi-field
+ * ordering composable: equal rows keep the order the previous field — or the server — put them in.
+ */
+export declare function applySort<T, TField extends string = string>(items: ReadonlyArray<T>, descriptors: readonly SortDescriptor<TField>[], accessors?: FieldAccessors<T, TField>, options?: LocaleOptions): ReadonlyArray<T>;

package/dist/foundation/selection/UseFilters.d.ts

@@ -0,0 +1,34 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { FilterDescriptor } from './Filter';
+/** Options accepted by {@link useFilters}. All are optional; the default is an uncontrolled empty filter set. */
+export interface UseFiltersOptions<TField extends string = string> {
+    /** The controlled clause list. Pass to own the filter state; omit for uncontrolled. */
+    filters?: MaybeRefOrGetter<readonly FilterDescriptor<TField>[] | undefined>;
+    /** The initial clause list when uncontrolled. Read once; ignored while `filters` is passed. */
+    defaultFilters?: MaybeRefOrGetter<readonly FilterDescriptor<TField>[] | undefined>;
+    /** Fires with the next clause list whenever it changes. */
+    onFiltersChange?: (filters: readonly FilterDescriptor<TField>[]) => void;
+}
+/** The filter state and bound operations returned by {@link useFilters}. */
+export interface FilterControls<TField extends string = string> {
+    /** The current clauses, AND-ed. Feed to `applyFilters` / `filterPredicate`. */
+    readonly filters: ComputedRef<readonly FilterDescriptor<TField>[]>;
+    /** Replaces the whole clause list — the escape hatch for several clauses on one field. */
+    readonly setFilters: (filters: readonly FilterDescriptor<TField>[]) => void;
+    /** Upserts a clause by field, keeping its position when it already exists. */
+    readonly setFilter: (filter: FilterDescriptor<TField>) => void;
+    /** Drops every clause on a field. */
+    readonly removeFilter: (field: TField) => void;
+    /** Drops every clause. */
+    readonly clear: () => void;
+    /** The first clause on a field, or `undefined` — what a filter-bar control reads to render its value. */
+    readonly filterFor: (field: TField) => FilterDescriptor<TField> | undefined;
+}
+/**
+ * Binds the filter model to reactive state, controlled or uncontrolled.
+ *
+ * Controlled when `filters` resolves to a defined value: the composable stores nothing and only calls
+ * `onFiltersChange` — the shape a server-side filtered list wants, where the clauses round-trip through a
+ * query.
+ */
+export declare function useFilters<TField extends string = string>(options?: UseFiltersOptions<TField>): FilterControls<TField>;

package/dist/foundation/selection/UseSelection.d.ts

@@ -0,0 +1,54 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { SelectionMode, SelectionKey, SelectionState, SelectionStatus, SelectRangeOptions } from './Selection';
+/** Options accepted by {@link useSelection}. All are optional; the default is an uncontrolled multi-select. */
+export interface UseSelectionOptions<TKey extends SelectionKey> {
+    /** The selection mode. Defaults to `'multiple'`. */
+    mode?: MaybeRefOrGetter<SelectionMode | undefined>;
+    /** The controlled selected keys. Pass to own the selection; omit for uncontrolled. */
+    selectedKeys?: MaybeRefOrGetter<ReadonlyArray<TKey> | undefined>;
+    /** The initial selected keys when uncontrolled. Read once; ignored while `selectedKeys` is passed. */
+    defaultSelectedKeys?: MaybeRefOrGetter<ReadonlyArray<TKey> | undefined>;
+    /** Fires with the next key list whenever the selection actually changes. */
+    onSelectionChange?: (keys: readonly TKey[]) => void;
+}
+/** The selection state and bound operations returned by {@link useSelection}. */
+export interface SelectionControls<TKey extends SelectionKey> {
+    /** The current immutable snapshot — pass to the pure model for anything not covered here. */
+    readonly state: ComputedRef<SelectionState<TKey>>;
+    /** The selected keys in insertion order. */
+    readonly keys: ComputedRef<readonly TKey[]>;
+    /** The mode in force. */
+    readonly mode: ComputedRef<SelectionMode>;
+    /** The number of selected keys. */
+    readonly count: ComputedRef<number>;
+    /** Reports whether a key is selected. */
+    readonly isSelected: (key: TKey) => boolean;
+    /** The tri-state for a header checkbox over the given (usually filtered) keys. */
+    readonly status: (keys: Iterable<TKey>) => SelectionStatus;
+    /** Selects a key and anchors on it. */
+    readonly select: (key: TKey) => void;
+    /** Deselects a key and anchors on it. */
+    readonly deselect: (key: TKey) => void;
+    /** Flips a key and anchors on it — the plain click. */
+    readonly toggle: (key: TKey) => void;
+    /** Adds every given key to the selection. */
+    readonly selectAll: (keys: Iterable<TKey>) => void;
+    /** Empties the selection and drops the anchor. */
+    readonly clear: () => void;
+    /** Flips every given key, leaving keys outside the set alone. */
+    readonly invert: (keys: Iterable<TKey>) => void;
+    /** The header-checkbox click over the given keys. */
+    readonly toggleAll: (keys: Iterable<TKey>) => void;
+    /** Selects the run between an explicit anchor and a target, in the surface's visual order. */
+    readonly selectRange: (anchor: TKey, target: TKey, orderedKeys: readonly TKey[], options?: SelectRangeOptions) => void;
+    /** The shift-click — extends from the tracked anchor to the target. */
+    readonly extend: (target: TKey, orderedKeys: readonly TKey[], options?: SelectRangeOptions) => void;
+}
+/**
+ * Binds the selection model to reactive state, controlled or uncontrolled.
+ *
+ * Controlled when `selectedKeys` resolves to a defined value: the composable never stores keys, it only calls
+ * `onSelectionChange` with the next list. Uncontrolled otherwise, seeded from `defaultSelectedKeys`, with
+ * `onSelectionChange` still firing so a consumer can observe without owning.
+ */
+export declare function useSelection<TKey extends SelectionKey>(options?: UseSelectionOptions<TKey>): SelectionControls<TKey>;

package/dist/foundation/selection/UseSort.d.ts

@@ -0,0 +1,36 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { SortDescriptor, SortDirection } from './Sort';
+/** Options accepted by {@link useSort}. All are optional; the default is an uncontrolled single-field sort. */
+export interface UseSortOptions<TField extends string = string> {
+    /** The controlled ordering. Pass to own the sort state; omit for uncontrolled. */
+    sort?: MaybeRefOrGetter<readonly SortDescriptor<TField>[] | undefined>;
+    /** The initial ordering when uncontrolled. Read once; ignored while `sort` is passed. */
+    defaultSort?: MaybeRefOrGetter<readonly SortDescriptor<TField>[] | undefined>;
+    /** Fires with the next ordering whenever it changes. */
+    onSortChange?: (sort: readonly SortDescriptor<TField>[]) => void;
+    /** The multi-field behaviour of {@link SortControls.toggle}. Defaults to `false` (one sorted field). */
+    isMulti?: MaybeRefOrGetter<boolean | undefined>;
+}
+/** The sort state and bound operations returned by {@link useSort}. */
+export interface SortControls<TField extends string = string> {
+    /** The current ordering — array order is precedence. Feed to `applySort` / `sortComparator`. */
+    readonly descriptors: ComputedRef<readonly SortDescriptor<TField>[]>;
+    /** Advances a field through `asc → desc → none` — the header click. */
+    readonly toggle: (field: TField) => void;
+    /** Replaces the whole ordering — for a "sort by" menu that sets state outright. */
+    readonly setSort: (descriptors: readonly SortDescriptor<TField>[]) => void;
+    /** Drops all ordering. */
+    readonly clear: () => void;
+    /** The direction applied to a field, or `null` when unsorted — drives the header's arrow and `aria-sort`. */
+    readonly directionFor: (field: TField) => SortDirection | null;
+    /** The 0-based precedence of a field, or `-1` — the multi-sort header's order badge. */
+    readonly indexFor: (field: TField) => number;
+}
+/**
+ * Binds the sort model to reactive state, controlled or uncontrolled.
+ *
+ * Controlled when `sort` resolves to a defined value: the composable stores nothing and only calls
+ * `onSortChange` — the shape a server-side sorted table wants, where the ordering round-trips through a query
+ * rather than local state.
+ */
+export declare function useSort<TField extends string = string>(options?: UseSortOptions<TField>): SortControls<TField>;

package/dist/foundation/selection/index.d.ts

@@ -0,0 +1,7 @@
+export { isNullish, readField, toText, type FieldAccessor, type FieldAccessors, type LocaleOptions, } from './Field';
+export { clear, createSelection, deselect, extendSelection, invert, isSelected, select, selectAll, selectRange, selectedKeys, selectionCount, selectionStatus, toggle, toggleAll, SelectionMode, SelectionStatus, type SelectionKey, type SelectionState, type SelectRangeOptions, } from './Selection';
+export { applySort, compareValues, sortComparator, sortDirectionFor, sortIndexFor, toggleSort, SortDirection, type SortDescriptor, type ToggleSortOptions, } from './Sort';
+export { applyFilters, filterPredicate, matchesFilter, FilterOperator, type BetweenFilter, type FilterDescriptor, type InFilter, type ValueFilter, } from './Filter';
+export { useSelection, type SelectionControls, type UseSelectionOptions, } from './UseSelection';
+export { useSort, type SortControls, type UseSortOptions } from './UseSort';
+export { useFilters, type FilterControls, type UseFiltersOptions } from './UseFilters';