@illinois-grad/grad-vue 5.0.3 → 6.0.0

package/custom-elements.json

@@ -2218,7 +2218,7 @@
             },
             {
               "kind": "field",
-              "name": "sorts",
+              "name": "sort",
               "type": {
                 "text": "TableSort<TableRow>[]"
               },

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

@@ -141,7 +141,7 @@ declare const __VLS_export: <T extends TableRow, C extends TableColumn<T>>(__VLS
          */
         resizableColumns?: boolean;
     } & {
-        sorts?: TableSort<T>[];
+        sort?: TableSort<T>[];
         filter?: Partial<Record<keyof T, any>>;
         columnState?: TableColumnState<T>;
         selectedRows?: string[];
@@ -149,7 +149,7 @@ declare const __VLS_export: <T extends TableRow, C extends TableColumn<T>>(__VLS
         "onRow-click"?: ((link: string) => any) | undefined;
         "onCell-change"?: ((payload: CellChangePayload<T, Extract<keyof T, string>>) => any) | undefined;
         "onUpdate:pageSize"?: ((value: number) => any) | undefined;
-        "onUpdate:sorts"?: ((value: TableSort<T, Extract<keyof T, string>>[]) => any) | undefined;
+        "onUpdate:sort"?: ((value: TableSort<T, Extract<keyof T, string>>[]) => any) | undefined;
         "onUpdate:filter"?: ((value: Partial<Record<keyof T, any>>) => any) | undefined;
         "onUpdate:columnState"?: ((value: Partial<Record<Extract<keyof T, string>, import("./table/TableColumn.ts").TableColumnStateValue>>) => any) | undefined;
         "onUpdate:selectedRows"?: ((value: string[]) => any) | undefined;
@@ -170,7 +170,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:sorts", 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: 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));
 }>) => import("vue").VNode & {
     __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };

package/dist/compose/useFiltering.d.ts

@@ -1,15 +1,28 @@
 import { Reactive, type Ref } from "vue";
 export type FilterLocationQueryValueRaw = string | number;
+export type FilterRouteQueryValue = string | null;
+export type FilterRouteQuery = {
+    [p: string]: FilterRouteQueryValue | undefined | FilterRouteQueryValue[];
+};
 /**
  * Query representation for filtering, compatible with vue-router
  */
 export type FilterLocationQuery = {
-    [p: string]: string | null | number | undefined | FilterLocationQueryValueRaw[];
+    [p: string]: string | null | number | undefined | (FilterLocationQueryValueRaw | null)[];
 };
 export interface FilteringOptions {
-    syncWith?: Ref<{
-        [p: string]: string | null | (string | null)[] | undefined;
-    }>;
+    syncWith?: Ref<FilterRouteQuery>;
+}
+export interface QueryFilteringOptions<F extends Record<string, any> = Record<string, any>> {
+    route: {
+        query: FilterRouteQuery;
+    };
+    router: {
+        replace: (location: {
+            query: FilterLocationQuery;
+        }) => unknown;
+    };
+    booleanArrayKeys?: readonly Extract<keyof F, string>[];
 }
 /**
  * Represents a type that defines a set of filters for a given record type.
@@ -43,6 +56,13 @@ export declare function filterOmitEmpty<T extends object>(value: T): Partial<T>;
  * undefined if it's undefined.
  */
 export declare function asArray<T>(value: T | T[]): NonNullable<T>[] | undefined;
+/**
+ * Normalizes a route query value into a string array.
+ *
+ * Accepts either repeated query params (`?tag=a&tag=b`) or comma-separated
+ * values (`?tag=a,b`) and removes null entries from array values.
+ */
+export declare function parseQueryArrayValue(value: FilterRouteQueryValue | FilterRouteQueryValue[] | readonly FilterRouteQueryValue[] | undefined): string[] | undefined;
 /**
  * Converts filter criteria into a format suitable for use as a query object
  * in vue-router.
@@ -57,6 +77,18 @@ export declare function filterAsQuery<T extends Record<string, any>, F extends {
  * null, empty string, or false values. Supports single values and arrays.
  */
 export declare function filtersToQueryParams<T extends Record<string, any>>(filters: T): Record<keyof T, string | string[]>;
+/**
+ * Provides a router-agnostic wrapper for syncing filter state with route query params.
+ *
+ * Pass in `route` and `router` objects from your app so grad-vue does not need
+ * a direct dependency on vue-router. Filters whose defaults are arrays are
+ * read from and written to query params as arrays, and `booleanArrayKeys` can
+ * 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>;
 /**
  * Provides a mechanism to manage and synchronize filterable data with given filters and options.
  *

package/dist/compose/usePaging.d.ts

@@ -0,0 +1,60 @@
+import { type Ref } from "vue";
+import type { TableSort } from "../components/table/TableColumn";
+import type { FilterLocationQuery, FilterRouteQuery, FilterRouteQueryValue } from "./useFiltering";
+type SortKey = string;
+type SortableRow = {
+    key: string;
+} & Record<string, any>;
+export type RawSortQuery = FilterRouteQueryValue | FilterRouteQueryValue[] | readonly FilterRouteQueryValue[] | undefined;
+export type PagingSort<K extends SortKey = SortKey> = TableSort<SortableRow, K>;
+export interface UsePagingOptions {
+    route?: {
+        query: FilterRouteQuery;
+    };
+    router?: {
+        replace: (location: {
+            query: FilterLocationQuery;
+        }) => unknown;
+    };
+    sortKey?: string;
+    pageSizeKey?: string;
+    pageOffsetKey?: string;
+    defaultPageSize?: number;
+    defaultPageOffset?: number;
+}
+export interface UsePagingReturn<K extends SortKey = SortKey> {
+    sort: Ref<PagingSort<K>[]>;
+    pageSize: Ref<number>;
+    pageOffset: Ref<number>;
+}
+/**
+ * Removes duplicate or invalid sort entries while keeping the original order.
+ */
+export declare function normalizeSorts<K extends SortKey>(sorts: readonly PagingSort<K>[] | undefined): PagingSort<K>[];
+/**
+ * Parses the route query representation of sorts into table sort objects.
+ *
+ * Supports either repeated query params (`["name", "-status"]`) or a single
+ * comma-separated string (`"name,-status"`).
+ */
+export declare function parseSortQueryValue<K extends SortKey>(value: RawSortQuery): PagingSort<K>[];
+/**
+ * Serializes table sort objects into the query-param form used by the apps.
+ */
+export declare function serializeSortQueryValue<K extends SortKey>(sorts: readonly PagingSort<K>[] | undefined): string[] | undefined;
+/**
+ * Builds the API `sortBy` string from the current sorts and optional tie-breakers.
+ *
+ * When the only explicit sort is descending, tie-breakers inherit that same
+ * descending direction.
+ */
+export declare function buildSortBy<K extends SortKey>(sorts: readonly PagingSort<K>[] | undefined, tieBreakers?: readonly string[]): string | undefined;
+/**
+ * Manages table sorts and pagination state, optionally syncing it with route query params.
+ *
+ * Pass `route` and `router` objects to share query-backed paging state across apps
+ * without adding a direct vue-router dependency to grad-vue. If they are
+ * omitted, the composable still works as local reactive state.
+ */
+export declare function usePaging<K extends SortKey = SortKey>(options?: UsePagingOptions): UsePagingReturn<K>;
+export {};