@illinois-grad/grad-vue 5.0.2 → 5.0.4

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

@@ -162,6 +162,7 @@ declare const __VLS_export: <T extends TableRow, C extends TableColumn<T>>(__VLS
     attrs: any;
     slots: {
         controls?: () => any;
+        "right-controls"?: () => any;
     };
     emit: {
         (e: "row-click", link: string): void;

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;
+    };
+    sortsKey?: string;
+    pageSizeKey?: string;
+    pageOffsetKey?: string;
+    defaultPageSize?: number;
+    defaultPageOffset?: number;
+}
+export interface UsePagingReturn<K extends SortKey = SortKey> {
+    sorts: 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 {};