@illinois-grad/grad-vue 6.0.15 → 7.0.0

package/custom-elements.json

@@ -2172,10 +2172,10 @@
               "kind": "field",
               "name": "filtering",
               "type": {
-                "text": "UseFilteringReturn<any>"
+                "text": "UseFilteringReturn<any, AnyFilterRecord>"
               },
               "optional": true,
-              "description": "Filtering object created with useFiltering()"
+              "description": "Filtering object created with useFiltering() Filter state is keyed by each column's filter key (`filter.key ?? key`)."
             },
             {
               "kind": "field",
@@ -2284,7 +2284,7 @@
               "kind": "field",
               "name": "filter",
               "type": {
-                "text": "Partial<Record<keyof TableRow, any>>"
+                "text": "FilterState<AnyFilterRecord>"
               },
               "optional": true
             },

package/dist/components/GMultiSelect.vue.d.ts

@@ -147,8 +147,8 @@ declare const __VLS_export: import("vue").DefineComponent<{
     onChange?: ((value: (string | number)[]) => any) | undefined;
 }>, {
     required: boolean;
+    searchDescription: boolean;
     disabled: boolean;
     errors: string[];
     hiddenLabel: boolean;
-    searchDescription: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/components/GSelect.vue.d.ts

@@ -161,10 +161,10 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     "onUpdate:modelValue"?: ((value: string | number | null | undefined) => any) | undefined;
 }>, {
     required: boolean;
-    disabled: boolean;
-    errors: string[];
     searchDescription: boolean;
     searchable: boolean;
+    disabled: boolean;
+    errors: string[];
     compact: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
     option?: (props: {

package/dist/components/GTable.vue.d.ts

@@ -1,6 +1,6 @@
-import type { TableColumn, TableColumnState, TableRow, TableSort } from "./table/TableColumn.ts";
+import type { AnyFilterRecord, TableColumn, TableColumnState, TableRow, TableSort } from "./table/TableColumn.ts";
 import type { VNode } from "vue";
-import type { UseFilteringReturn } from "../compose/useFiltering.ts";
+import type { FilterState, UseFilteringReturn } from "../compose/useFiltering.ts";
 import type { CellChangePayload, UseTableChangesReturn } from "../compose/useTableChanges.ts";
 export interface BulkAction {
     /**
@@ -34,6 +34,11 @@ export interface BulkAction {
  *     objects to use, and `label` for the column header.
  *   - `sortable: true` makes the column sortable.
  *   - `filter` can be used to provide a `TableColumnFilter` configuration.
+ *     Filter state is keyed by `filter.key`, or by the column `key` when
+ *     `filter.key` is omitted. Pass a filter/request type as the third
+ *     `TableColumn` type argument to type-check `filter.key` and values, and
+ *     use `buildFilterRequest()` to convert filter state into request values
+ *     (for example `match: "contains"` produces `%text%`).
  *   - `display` accepts a custom render function for the column data.
  *   - `trClass` and `tdClass` can be used to provide custom classes for table rows and cells.
  * - `data` array with objects containing fields for the columns.
@@ -48,7 +53,7 @@ export interface BulkAction {
  */
 declare const _default: typeof __VLS_export;
 export default _default;
-declare const __VLS_export: <T extends TableRow, C extends TableColumn<T>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+declare const __VLS_export: <T extends TableRow, C extends TableColumn<T> = TableColumn<T>, F = AnyFilterRecord>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: import("vue").PublicProps & __VLS_PrettifyLocal<({
         /**
          * Accessible label
@@ -91,8 +96,11 @@ declare const __VLS_export: <T extends TableRow, C extends TableColumn<T>>(__VLS
         groupRender?: (groupValue: any, row: T) => VNode;
         /**
          * Filtering object created with useFiltering()
+         *
+         * Filter state is keyed by each column's filter key
+         * (`filter.key ?? key`).
          */
-        filtering?: UseFilteringReturn<any>;
+        filtering?: UseFilteringReturn<any, F>;
         /**
          * Make the table rows clickable
          */
@@ -142,7 +150,7 @@ declare const __VLS_export: <T extends TableRow, C extends TableColumn<T>>(__VLS
         resizableColumns?: boolean;
     } & {
         sort?: TableSort<T>[];
-        filter?: Partial<Record<keyof T, any>>;
+        filter?: FilterState<F>;
         columnState?: TableColumnState<T>;
         selectedRows?: string[];
     }) & {
@@ -150,7 +158,7 @@ declare const __VLS_export: <T extends TableRow, C extends TableColumn<T>>(__VLS
         "onCell-change"?: ((payload: CellChangePayload<T, Extract<keyof T, string>>) => any) | undefined;
         "onUpdate:pageSize"?: ((value: number) => any) | undefined;
         "onUpdate:sort"?: ((value: TableSort<T, Extract<keyof T, string>>[]) => any) | undefined;
-        "onUpdate:filter"?: ((value: Partial<Record<keyof T, any>>) => any) | undefined;
+        "onUpdate:filter"?: ((value: FilterState<F>) => any) | undefined;
         "onUpdate:columnState"?: ((value: Partial<Record<Extract<keyof T, string>, import("./table/TableColumn.ts").TableColumnStateValue>>) => any) | undefined;
         "onUpdate:selectedRows"?: ((value: string[]) => any) | undefined;
         "onUpdate:startIndex"?: ((value: number) => any) | undefined;
@@ -171,7 +179,7 @@ declare const __VLS_export: <T extends TableRow, C extends TableColumn<T>>(__VLS
         (e: "cell-change", payload: CellChangePayload<T>): void;
         (e: "update:startIndex", value: number): void;
         (e: "update:pageSize", value: number): void;
-    } & (((event: "update:sort", value: TableSort<T, Extract<keyof T, string>>[]) => void) & ((event: "update:filter", value: Partial<Record<keyof T, any>>) => void) & ((event: "update:columnState", value: Partial<Record<Extract<keyof T, string>, import("./table/TableColumn.ts").TableColumnStateValue>>) => void) & ((event: "update:selectedRows", value: string[]) => void));
+    } & (((event: "update:sort", value: TableSort<T, Extract<keyof T, string>>[]) => void) & ((event: "update:filter", value: FilterState<F>) => void) & ((event: "update:columnState", value: Partial<Record<Extract<keyof T, string>, import("./table/TableColumn.ts").TableColumnStateValue>>) => void) & ((event: "update:selectedRows", value: string[]) => void));
 }>) => import("vue").VNode & {
     __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };

package/dist/components/table/TableColumn.d.ts

@@ -1,12 +1,53 @@
 import { VNode } from "vue";
-export type TableColumnFilter = SelectColumnFilter | MultiSelectColumnFilter | ToggleColumnFilter | SearchColumnFilter;
-export interface SelectColumnFilter {
-    type: 'select';
-    options: Array<{
-        label: string;
-        value: any;
-        description?: string;
-    }>;
+/**
+ * Default filter/request type used when a column does not declare one.
+ */
+export type AnyFilterRecord = Record<string, any>;
+/**
+ * String keys of a filter/request type.
+ */
+export type FilterKey<F> = Extract<keyof F, string>;
+/**
+ * The non-null value type accepted by the request field `K` of `F`.
+ */
+export type FilterApiValue<F, K extends keyof F> = Exclude<F[K], null | undefined>;
+export type FilterPrimitive = string | number | boolean;
+/**
+ * How a search filter's text is converted for the request.
+ *
+ * - `exact` (default): the trimmed text is sent unchanged.
+ * - `contains`: `%text%`
+ * - `startsWith`: `text%`
+ * - `endsWith`: `%text`
+ */
+export type SearchFilterMatch = "exact" | "contains" | "startsWith" | "endsWith";
+export interface FilterOption<V = any> {
+    label: string;
+    value: V;
+    description?: string;
+}
+/**
+ * Converts a normalized UI value into the request value for `F[K]`.
+ * Returning `undefined` omits the field from the request.
+ */
+export type FilterTransform<In, F, K extends keyof F> = (value: In) => FilterApiValue<F, K> | undefined;
+type ArrayElement<V> = V extends readonly (infer E)[] ? E : never;
+interface SearchFilterBase {
+    type: "search";
+    /**
+     * Placeholder text shown in the search input.
+     */
+    placeholder?: string;
+}
+type SearchFilterMapping<F, K extends keyof F> = (string extends FilterApiValue<F, K> ? {
+    match?: SearchFilterMatch;
+    transform?: undefined;
+} : never) | {
+    match?: undefined;
+    transform: FilterTransform<string, F, K>;
+};
+interface SelectFilterBase {
+    type: "select";
     placeholder?: string;
     /**
      * Include the option `description` in the searchable text match.
@@ -14,20 +55,15 @@ export interface SelectColumnFilter {
      */
     searchDescription?: boolean;
 }
-export interface SearchColumnFilter {
-    type: 'search';
-    /**
-     * Placeholder text shown in the search input.
-     */
-    placeholder?: string;
-}
-export interface MultiSelectColumnFilter {
-    type: 'multi-select';
-    options: Array<{
-        label: string;
-        value: any;
-        description?: string;
-    }>;
+type SelectFilterMapping<F, K extends keyof F> = {
+    options: Array<FilterOption<FilterApiValue<F, K>>>;
+    transform?: undefined;
+} | {
+    options: Array<FilterOption<FilterPrimitive>>;
+    transform: FilterTransform<FilterPrimitive, F, K>;
+};
+interface MultiSelectFilterBase {
+    type: "multi-select";
     placeholder?: string;
     /**
      * When true, renders a searchable GMultiSelect combobox instead of a
@@ -41,11 +77,73 @@ export interface MultiSelectColumnFilter {
      */
     searchDescription?: boolean;
 }
-export interface ToggleColumnFilter {
-    type: 'toggle';
+type MultiSelectFilterMapping<F, K extends keyof F> = ([FilterApiValue<F, K>] extends [readonly unknown[]] ? {
+    options: Array<FilterOption<ArrayElement<FilterApiValue<F, K>>>>;
+    transform?: undefined;
+} : never) | {
+    options: Array<FilterOption<FilterPrimitive>>;
+    transform: FilterTransform<FilterPrimitive[], F, K>;
+};
+interface ToggleFilterBase {
+    type: "toggle";
     label: string;
     description?: string;
 }
+type ToggleFilterMapping<F, K extends keyof F> = (true extends FilterApiValue<F, K> ? {
+    transform?: undefined;
+} : never) | {
+    transform: FilterTransform<true, F, K>;
+};
+/**
+ * A search input filter.
+ *
+ * The UI value is the entered text. Without `transform`, the request field
+ * must accept a string; `match` controls wildcard wrapping. With
+ * `transform`, the trimmed text is converted to the request field's type.
+ */
+export type SearchColumnFilter<F = AnyFilterRecord, K extends FilterKey<F> = FilterKey<F>> = SearchFilterBase & {
+    key?: K;
+} & SearchFilterMapping<F, K>;
+/**
+ * A single-select filter. Without `transform`, option values must match the
+ * request field's type.
+ */
+export type SelectColumnFilter<F = AnyFilterRecord, K extends FilterKey<F> = FilterKey<F>> = SelectFilterBase & {
+    key?: K;
+} & SelectFilterMapping<F, K>;
+/**
+ * A multi-select filter. Without `transform`, the request field must be an
+ * array and option values must match its element type.
+ */
+export type MultiSelectColumnFilter<F = AnyFilterRecord, K extends FilterKey<F> = FilterKey<F>> = MultiSelectFilterBase & {
+    key?: K;
+} & MultiSelectFilterMapping<F, K>;
+/**
+ * A toggle filter. It is active only when on. Without `transform`, the
+ * request field must accept `true`.
+ */
+export type ToggleColumnFilter<F = AnyFilterRecord, K extends FilterKey<F> = FilterKey<F>> = ToggleFilterBase & {
+    key?: K;
+} & ToggleFilterMapping<F, K>;
+type ColumnFilterFor<F, K extends FilterKey<F>> = (SearchFilterBase & SearchFilterMapping<F, K>) | (SelectFilterBase & SelectFilterMapping<F, K>) | (MultiSelectFilterBase & MultiSelectFilterMapping<F, K>) | (ToggleFilterBase & ToggleFilterMapping<F, K>);
+type KeyedColumnFilter<F, K extends FilterKey<F>> = K extends unknown ? ColumnFilterFor<F, K> & {
+    /**
+     * The filter/request field this filter reads and writes. Defaults to
+     * the column key, which must then be a key of the filter type.
+     */
+    key: K;
+} : never;
+type DefaultKeyColumnFilter<F, K> = K extends FilterKey<F> ? ColumnFilterFor<F, K> & {
+    key?: undefined;
+} : never;
+/**
+ * Filter configuration for a column.
+ *
+ * `F` is the filter/request type (for example a generated API query type).
+ * `filter.key` must be a key of `F`. When `key` is omitted, the column key
+ * (`DefaultKey`) is used and must itself be a key of `F`.
+ */
+export type TableColumnFilter<F = AnyFilterRecord, DefaultKey extends string = FilterKey<F>> = KeyedColumnFilter<F, FilterKey<F>> | DefaultKeyColumnFilter<F, DefaultKey>;
 export interface EditableColumnConfig {
     /**
      * Type of editable control. Defaults to "input".
@@ -77,7 +175,7 @@ export interface EditableColumnConfig {
      */
     labelKey?: string;
 }
-type ColumnKey<T> = Extract<keyof T, string>;
+export type ColumnKey<T> = Extract<keyof T, string>;
 export interface TableColumnStateValue {
     visible?: boolean;
     width?: number;
@@ -87,11 +185,18 @@ export interface TableSort<T extends TableRow, K extends ColumnKey<T> = ColumnKe
     key: K;
     order: 1 | -1;
 }
-export interface TableColumn<T extends TableRow, K extends ColumnKey<T> = ColumnKey<T>> {
+export interface TableColumnConfig<T extends TableRow, K extends ColumnKey<T> = ColumnKey<T>, F = AnyFilterRecord> {
+    /**
+     * Row field used for display and sorting.
+     */
     key: K;
     label: string;
     sortable?: boolean;
-    filter?: TableColumnFilter;
+    /**
+     * Filter configuration. Use `filter.key` when the filter/request field
+     * differs from the column key.
+     */
+    filter?: TableColumnFilter<F, K>;
     /**
      * Custom render function for the column data.
      * Cannot be used with `editable`.
@@ -106,6 +211,14 @@ export interface TableColumn<T extends TableRow, K extends ColumnKey<T> = Column
      */
     editable?: EditableColumnConfig;
 }
+/**
+ * A table column for rows of type `T`.
+ *
+ * `F` is an independent filter/request type that column filters map to.
+ * This distributes over `K` so each column's default filter key is checked
+ * against its own row key.
+ */
+export type TableColumn<T extends TableRow, K extends ColumnKey<T> = ColumnKey<T>, F = AnyFilterRecord> = K extends ColumnKey<T> ? TableColumnConfig<T, K, F> : never;
 export interface TableRow extends Record<string, any> {
     key: string;
 }

package/dist/components/table/columnFilters.d.ts

@@ -0,0 +1,58 @@
+import type { FilterOption, FilterPrimitive, SearchFilterMatch } from "./TableColumn.ts";
+/**
+ * A raw filter value as stored in filter state and route queries.
+ *
+ * Values read back from a URL are strings, so column-aware helpers normalize
+ * them against the column filter configuration before use.
+ */
+export type FilterInputValue = FilterPrimitive | FilterPrimitive[] | null | undefined;
+/**
+ * Structural view of any `TableColumnFilter`, independent of its filter type.
+ */
+type AnyColumnFilter = {
+    type: "search";
+    match?: SearchFilterMatch;
+    transform?: (value: string) => unknown;
+} | {
+    type: "select";
+    options: readonly FilterOption<unknown>[];
+    transform?: (value: FilterPrimitive) => unknown;
+} | {
+    type: "multi-select";
+    options: readonly FilterOption<unknown>[];
+    transform?: (value: FilterPrimitive[]) => unknown;
+} | {
+    type: "toggle";
+    transform?: (value: true) => unknown;
+};
+interface FilterableColumn {
+    key: string;
+    filter?: {
+        key?: string;
+    };
+}
+/**
+ * The filter/request key a column filter reads and writes.
+ */
+export declare function columnFilterKey(column: FilterableColumn): string;
+/**
+ * Normalizes a raw state value into the value expected by the filter control.
+ */
+export declare function filterInputValue(filter: AnyColumnFilter, raw: FilterInputValue): FilterPrimitive | FilterPrimitive[] | undefined;
+/**
+ * Converts a value emitted by a filter control into a raw state value.
+ * Empty values (including an unchecked toggle) become `undefined`, except
+ * multi-select values, which stay arrays.
+ */
+export declare function filterStateValue(filter: AnyColumnFilter, input: unknown): FilterInputValue;
+/**
+ * Whether a raw state value represents an active filter for the column.
+ * `0` and `false` are meaningful select values; toggles are active only when on.
+ */
+export declare function isColumnFilterActive(filter: AnyColumnFilter, raw: FilterInputValue): boolean;
+/**
+ * Converts a raw state value into the request value for the column filter.
+ * Returns `undefined` when the filter is inactive.
+ */
+export declare function filterRequestValue(filter: AnyColumnFilter, raw: FilterInputValue): unknown;
+export {};

package/dist/compose/useFiltering.d.ts

@@ -1,4 +1,23 @@
 import { Reactive, type Ref } from "vue";
+import type { AnyFilterRecord, ColumnKey, FilterApiValue, FilterKey, TableColumn, TableRow } from "../components/table/TableColumn.ts";
+import { type FilterInputValue } from "../components/table/columnFilters.ts";
+export type { FilterInputValue } from "../components/table/columnFilters.ts";
+/**
+ * Raw UI filter state keyed by filter/request keys of `F`.
+ *
+ * Values are kept as entered (or as read from the URL) and are only
+ * converted to request values by `buildFilterRequest()`.
+ */
+export type FilterState<F> = {
+    [K in keyof F]?: FilterInputValue;
+};
+/**
+ * A request object built from filter state. Each value has the type of the
+ * corresponding field in `F`.
+ */
+export type FilterRequest<F> = {
+    [K in keyof F]?: FilterApiValue<F, K>;
+};
 export type FilterLocationQueryValueRaw = string | number;
 export type FilterRouteQueryValue = string | null;
 export type FilterRouteQuery = {
@@ -13,7 +32,7 @@ export type FilterLocationQuery = {
 export interface FilteringOptions {
     syncWith?: Ref<FilterRouteQuery>;
 }
-export interface QueryFilteringOptions<F extends Record<string, any> = Record<string, any>> {
+export interface QueryFilteringOptions<F = AnyFilterRecord> {
     route: {
         query: FilterRouteQuery;
     };
@@ -22,7 +41,7 @@ export interface QueryFilteringOptions<F extends Record<string, any> = Record<st
             query: FilterLocationQuery;
         }) => unknown;
     };
-    booleanArrayKeys?: readonly Extract<keyof F, string>[];
+    booleanArrayKeys?: readonly FilterKey<F>[];
 }
 /**
  * Represents a type that defines a set of filters for a given record type.
@@ -37,14 +56,15 @@ export type FiltersForRecord<T extends object, F extends {
 /**
  * Represents the return type of a composition function used for handling
  * filtering logic in a data structure.
+ *
+ * `T` is the row type and `F` is the independent filter/request type. Filter
+ * state and `filteredColumns` are keyed by filter keys of `F`.
  */
-export interface UseFilteringReturn<T extends Record<string, any> = Record<string, any>, F extends {
-    [K in keyof T]?: any;
-} = Record<keyof T, any>> {
-    filters: Reactive<F>;
+export interface UseFilteringReturn<T extends object = AnyFilterRecord, F = Partial<Record<keyof T, any>>> {
+    filters: Reactive<FilterState<F>>;
     isFiltered: Ref<boolean>;
     clearFilters: () => void;
-    filteredColumns: Ref<Partial<Record<keyof T, boolean>>>;
+    filteredColumns: Ref<Partial<Record<FilterKey<F>, boolean>>>;
 }
 /**
  * Returns the value if it's not empty, or undefined if it's empty.
@@ -63,6 +83,24 @@ export declare function asArray<T>(value: T | T[]): NonNullable<T>[] | undefined
  * values (`?tag=a,b`) and removes null entries from array values.
  */
 export declare function parseQueryArrayValue(value: FilterRouteQueryValue | FilterRouteQueryValue[] | readonly FilterRouteQueryValue[] | undefined): string[] | undefined;
+/**
+ * Builds a typed request object from column filter configuration and raw
+ * filter state.
+ *
+ * Each filtered column reads `filters[filter.key ?? column.key]` and applies
+ * its explicit transformation (`match` for search filters, or `transform`).
+ * Only keys produced by column filters are included.
+ *
+ * @example
+ * ```ts
+ * type Query = NonNullable<GetStudentsData["query"]>;
+ * const columns: TableColumn<StudentRow, ColumnKey<StudentRow>, Query>[] = [
+ *     { key: "major", label: "Major", filter: { type: "search", key: "major__like", match: "contains" } },
+ * ];
+ * const query: FilterRequest<Query> = buildFilterRequest(columns, filters);
+ * ```
+ */
+export declare function buildFilterRequest<T extends TableRow, F>(columns: readonly TableColumn<T, ColumnKey<T>, F>[], filters: FilterState<F>): FilterRequest<F>;
 /**
  * Converts filter criteria into a format suitable for use as a query object
  * in vue-router.
@@ -86,16 +124,16 @@ export declare function filtersToQueryParams<T extends Record<string, any>>(filt
  * be used for multi-value filters that should be converted to boolean values
  * inside the filter state.
  */
-export declare function useQueryFiltering<T extends Record<string, any>, F extends {
-    [K in keyof T]?: any;
-} = Record<keyof T, any>>(filters: F, options: QueryFilteringOptions<F>): UseFilteringReturn<T, F>;
+export declare function useQueryFiltering<T extends object = AnyFilterRecord, F = Partial<Record<keyof T, any>>>(filters: FilterState<F>, options: QueryFilteringOptions<F>): UseFilteringReturn<T, F>;
 /**
  * Provides a mechanism to manage and synchronize filterable data with given filters and options.
  *
+ * Filter state is keyed by filter/request keys (`filter.key ?? column.key`)
+ * and holds raw UI values. Use `buildFilterRequest()` to convert it into
+ * typed request values.
+ *
  * @param filters An object that defines the filters applicable to the data record.
  * @param options Configuration options for filtering, such as synchronization.
  * @return Returns an object that can be used with GTable.
  */
-export declare function useFiltering<T extends Record<string, any> = Record<string, any>, F extends {
-    [K in keyof T]?: any;
-} = Record<keyof T, any>>(filters: F, options?: FilteringOptions): UseFilteringReturn<T, F>;
+export declare function useFiltering<T extends object = AnyFilterRecord, F = Partial<Record<keyof T, any>>>(filters: FilterState<F>, options?: FilteringOptions): UseFilteringReturn<T, F>;

package/dist/compose/useTableChanges.d.ts

@@ -1,5 +1,5 @@
 import { ComputedRef } from "vue";
-import { TableColumn, TableRow } from "../components/table/TableColumn.ts";
+import { TableColumnConfig, TableRow } from "../components/table/TableColumn.ts";
 import { EventHookOn } from "@vueuse/core";
 export type ColumnKey<R extends TableRow> = Extract<keyof R, string>;
 /**
@@ -33,7 +33,7 @@ export interface CellChangeEvent<R extends TableRow = TableRow, K extends Column
  */
 export interface CellChangePayload<T extends TableRow = TableRow, K extends ColumnKey<T> = ColumnKey<T>> {
     row: T;
-    column: TableColumn<T, K>;
+    column: TableColumnConfig<T, K>;
     value: T[K];
     previousValue: T[K];
 }