@webority/ui-react 0.22.0 → 0.23.0

package/dist/types/lib/listQuery.d.ts

@@ -0,0 +1,69 @@
+export declare const RESERVED_LIST_QUERY_KEYS: string[];
+/**
+ * Builds the flat query string for one page of a list.
+ *
+ * A filter value is a scalar, an array (one param per item) or a date range `{ from, to }`
+ * (written as `<name>From` / `<name>To`). Empty values are left out. A `Date` is written as
+ * yyyy-MM-dd.
+ *
+ * @param {object} [query]
+ * @param {number} [query.page] 1-based.
+ * @param {number} [query.pageSize]
+ * @param {string} [query.sortBy]
+ * @param {'asc'|'desc'} [query.sortOrder='asc'] Written only with `sortBy`.
+ * @param {Record<string, string|number|boolean|Date|Array<string|number|boolean|Date>|{ from?: string|Date, to?: string|Date }>} [query.filters]
+ * @returns {URLSearchParams}
+ * @throws {Error} When a filter is named page, pageSize, sortBy or sortOrder, or `sortOrder` is not asc or desc.
+ */
+export declare function buildListQuery({ page, pageSize, sortBy, sortOrder, filters }?: {
+    page?: number;
+    pageSize?: number;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+    filters?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date> | {
+        from?: string | Date;
+        to?: string | Date;
+    }>;
+}): URLSearchParams;
+/** The empty value of a facet: "" (enum, text), [] (multiEnum) or { from: "", to: "" } (dateRange). */
+export declare function emptyFacetValue(facet: any): "" | any[] | {
+    from: string;
+    to: string;
+};
+/** True when a facet's value narrows the list. */
+export declare function isFacetActive(facet: any, value: any): boolean;
+/** Every query param name a list owns: the reserved four plus each facet's own (`<key>From`/`<key>To` for a date range). */
+export declare function listQueryParamNames(facets?: any[]): Set<string>;
+/**
+ * Reads a list query back out of the URL's search params: the inverse of `buildListQuery`.
+ * Anything missing or invalid falls back to `defaults`. Every facet gets a value, empty when the
+ * URL has none, so the result is always safe to render.
+ *
+ * `defaults.filters` apply only when the URL carries no list param at all (the first landing on
+ * the page). After that the URL is the truth, so clearing a filter that has a default stays cleared.
+ *
+ * @param {URLSearchParams|string} searchParams
+ * @param {object} [options]
+ * @param {{ key: string, type: 'enum'|'multiEnum'|'dateRange'|'text' }[]} [options.facets]
+ * @param {{ page?: number, pageSize?: number, sortBy?: string, sortOrder?: 'asc'|'desc', filters?: object }} [options.defaults]
+ * @returns {{ page: number, pageSize: number, sortBy: string|undefined, sortOrder: 'asc'|'desc', filters: object }}
+ */
+export declare function parseListQuery(searchParams: URLSearchParams | string, { facets, defaults }?: {
+    facets?: {
+        key: string;
+        type: 'enum' | 'multiEnum' | 'dateRange' | 'text';
+    }[];
+    defaults?: {
+        page?: number;
+        pageSize?: number;
+        sortBy?: string;
+        sortOrder?: 'asc' | 'desc';
+        filters?: object;
+    };
+}): {
+    page: number;
+    pageSize: number;
+    sortBy: string | undefined;
+    sortOrder: 'asc' | 'desc';
+    filters: object;
+};

package/dist/types/lib/useListQuery.d.ts

@@ -0,0 +1,96 @@
+/**
+ * One server-paged list: its query lives in the URL, every change refetches, and the result
+ * maps straight onto `AppDataTable`, `AppTablePagination` and `AppFilterBar`.
+ *
+ * The URL holds the flat list query (`?page=2&pageSize=25&sortBy=dueDate&sortOrder=desc&status=Open`,
+ * see `buildListQuery`), written with `history.replaceState` and read back on first render and on
+ * back/forward, so a list reloads, bookmarks and shares as it was. Other params in the URL are kept.
+ * No router is needed.
+ *
+ * A filter or sort change goes back to page 1, and a new request aborts the one still in flight.
+ * Typing in a `text` facet refetches after `debounceMs`; every other change refetches at once.
+ *
+ * @param {object} options
+ * @param {(query: { page: number, pageSize: number, sortBy?: string, sortOrder: 'asc'|'desc', filters: object },
+ *   options: { signal: AbortSignal }) => Promise<{ items: object[], page: number, pageSize: number, totalCount: number, totalPages: number }>} options.fetchPage
+ *   Fetches one page. Pass `query` to `buildListQuery` for the request's query string and `signal` to the HTTP client.
+ * @param {{ key: string, label: string, type: 'enum'|'multiEnum'|'dateRange'|'text', options?: { value: string, label: string }[] }[]} [options.facets]
+ *   The filters, the same list `AppFilterBar` takes. Keep it stable across renders.
+ * @param {{ page?: number, pageSize?: number, sortBy?: string, sortOrder?: 'asc'|'desc', filters?: object }} [options.defaults]
+ *   Where a list starts when the URL says nothing. Keep it stable across renders.
+ * @param {number} [options.debounceMs=250] Wait before refetching while the user types in a `text` facet.
+ * @returns {{
+ *   query: { page: number, pageSize: number, sortBy?: string, sortOrder: 'asc'|'desc', filters: object },
+ *   rows: object[],
+ *   loading: boolean,
+ *   error: unknown,
+ *   totalCount: number,
+ *   totalPages: number,
+ *   setFilter: (key: string, value: string|string[]|{ from: string, to: string }) => void,
+ *   setSort: (sortBy: string, sortOrder?: 'asc'|'desc') => void,
+ *   setPage: (page: number) => void,
+ *   setPageSize: (pageSize: number) => void,
+ *   reset: () => void,
+ *   tableProps: object,
+ *   paginationProps: object,
+ * }} `setSort` without `sortOrder` flips the order on the column already sorted and starts a new
+ *   column ascending. `tableProps` spreads onto `AppDataTable` (`rows`, `sort`, `onSort`, `loading`, and
+ *   the filtered-empty message while a filter is active); `paginationProps` spreads onto `AppTablePagination`.
+ */
+export declare function useListQuery({ fetchPage, facets, defaults, debounceMs }: {
+    fetchPage: (query: {
+        page: number;
+        pageSize: number;
+        sortBy?: string;
+        sortOrder: 'asc' | 'desc';
+        filters: object;
+    }, options: {
+        signal: AbortSignal;
+    }) => Promise<{
+        items: object[];
+        page: number;
+        pageSize: number;
+        totalCount: number;
+        totalPages: number;
+    }>;
+    facets?: {
+        key: string;
+        label: string;
+        type: 'enum' | 'multiEnum' | 'dateRange' | 'text';
+        options?: {
+            value: string;
+            label: string;
+        }[];
+    }[];
+    defaults?: {
+        page?: number;
+        pageSize?: number;
+        sortBy?: string;
+        sortOrder?: 'asc' | 'desc';
+        filters?: object;
+    };
+    debounceMs?: number;
+}): {
+    query: {
+        page: number;
+        pageSize: number;
+        sortBy?: string;
+        sortOrder: 'asc' | 'desc';
+        filters: object;
+    };
+    rows: object[];
+    loading: boolean;
+    error: unknown;
+    totalCount: number;
+    totalPages: number;
+    setFilter: (key: string, value: string | string[] | {
+        from: string;
+        to: string;
+    }) => void;
+    setSort: (sortBy: string, sortOrder?: 'asc' | 'desc') => void;
+    setPage: (page: number) => void;
+    setPageSize: (pageSize: number) => void;
+    reset: () => void;
+    tableProps: object;
+    paginationProps: object;
+};