@harpercollins/harpercollins-design-system 1.33.0 → 1.34.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cjs/components/data-display/Table/Table.cjs +1 -1
- package/dist/cjs/components/data-display/Table/Table.styles.cjs +2 -2
- package/dist/cjs/components/data-display/Table/TableHeader.cjs +1 -0
- package/dist/cjs/components/data-display/Table/TableToolbar.cjs +1 -1
- package/dist/cjs/components/data-display/Table/tableUrlUtils.cjs +1 -0
- package/dist/cjs/hooks/useServerSideTableState.cjs +1 -0
- package/dist/cjs/index.cjs +1 -1
- package/dist/esm/components/data-display/Table/Table.js +225 -276
- package/dist/esm/components/data-display/Table/Table.styles.js +4 -5
- package/dist/esm/components/data-display/Table/TableHeader.js +92 -0
- package/dist/esm/components/data-display/Table/TableToolbar.js +10 -8
- package/dist/esm/components/data-display/Table/tableUrlUtils.js +108 -0
- package/dist/esm/hooks/useServerSideTableState.js +47 -0
- package/dist/esm/index.js +93 -89
- package/dist/index.d.ts +125 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -20,6 +20,8 @@ import { CheckboxProps } from '@mui/joy';
|
|
|
20
20
|
import { ChipProps } from '@mui/joy';
|
|
21
21
|
import { CircularProgressProps } from '@mui/joy';
|
|
22
22
|
import { ColorPaletteProp } from '@mui/joy';
|
|
23
|
+
import { ColumnDef } from '@tanstack/react-table';
|
|
24
|
+
import { ColumnFiltersState } from '@tanstack/react-table';
|
|
23
25
|
import { Component } from 'react';
|
|
24
26
|
import { ContainerProps } from '@mui/joy';
|
|
25
27
|
import { default as default_2 } from 'react';
|
|
@@ -63,6 +65,7 @@ import { ModalClose } from '@mui/joy';
|
|
|
63
65
|
import { ModalDialog } from '@mui/joy';
|
|
64
66
|
import { ModalOverflow } from '@mui/joy';
|
|
65
67
|
import { ModalProps } from '@mui/joy';
|
|
68
|
+
import { OnChangeFn } from '@tanstack/react-table';
|
|
66
69
|
import { Option as Option_2 } from '@mui/joy';
|
|
67
70
|
import { PropsWithChildren } from 'react';
|
|
68
71
|
import { RadioGroup } from '@mui/joy';
|
|
@@ -77,6 +80,7 @@ import { SelectProps } from '@mui/joy';
|
|
|
77
80
|
import { SheetProps } from '@mui/joy';
|
|
78
81
|
import { SkeletonProps } from '@mui/joy';
|
|
79
82
|
import { SliderProps } from '@mui/joy';
|
|
83
|
+
import { SortingState } from '@tanstack/react-table';
|
|
80
84
|
import { Step } from '@mui/joy';
|
|
81
85
|
import { StepButton } from '@mui/joy';
|
|
82
86
|
import { StepIndicator } from '@mui/joy';
|
|
@@ -236,6 +240,12 @@ export declare const Drawer: default_2.ForwardRefExoticComponent<Omit<default_2.
|
|
|
236
240
|
|
|
237
241
|
export declare function Dropdown(props: DropdownProps): JSX_2.Element;
|
|
238
242
|
|
|
243
|
+
/**
|
|
244
|
+
* Derives a `columnFilterTypes` map from TanStack Table column definitions by
|
|
245
|
+
* reading each column's `meta.filterType`.
|
|
246
|
+
*/
|
|
247
|
+
export declare function extractColumnFilterTypes(columns: ColumnDef<unknown, unknown>[]): Record<string, ServerSideFilterType>;
|
|
248
|
+
|
|
239
249
|
/**
|
|
240
250
|
* Format currency value to locale and currency
|
|
241
251
|
* @param value - The value to format
|
|
@@ -483,6 +493,9 @@ declare interface RelativeTimeProps {
|
|
|
483
493
|
|
|
484
494
|
export declare function Select<TValue extends object>(props: SelectProps<TValue, false>): JSX_2.Element;
|
|
485
495
|
|
|
496
|
+
/** Filter types that affect how URL params are serialized/deserialized. */
|
|
497
|
+
export declare type ServerSideFilterType = "text" | "select" | "multiselect" | "date" | "number";
|
|
498
|
+
|
|
486
499
|
export declare function Sheet(props: SheetProps): JSX_2.Element;
|
|
487
500
|
|
|
488
501
|
export declare function Skeleton(props: SkeletonProps): JSX_2.Element;
|
|
@@ -519,7 +532,7 @@ export { Tab }
|
|
|
519
532
|
|
|
520
533
|
export { tabClasses }
|
|
521
534
|
|
|
522
|
-
export declare function Table<TData = unknown>({ id, loading, maxHeight, wrapText, rowRender, reactTableOptions, gridCheckboxes, allSelected, onSelectionChange, showStickyScrollbar, enableStickyHeader, stickyHeaderOffset, infiniteScroll, toolbar, footer, isError, errorMessage, }: TableProps<TData>): JSX_2.Element;
|
|
535
|
+
export declare function Table<TData = unknown>({ id, loading, maxHeight, wrapText, rowRender, reactTableOptions, gridCheckboxes, allSelected, onSelectionChange, showStickyScrollbar, enableStickyHeader, stickyHeaderOffset, infiniteScroll, toolbar, footer, isError, errorMessage, syncUrl, urlParamPrefix, }: TableProps<TData>): JSX_2.Element;
|
|
523
536
|
|
|
524
537
|
export declare interface TableProps<TData = unknown> {
|
|
525
538
|
id: string;
|
|
@@ -541,6 +554,19 @@ export declare interface TableProps<TData = unknown> {
|
|
|
541
554
|
footer?: boolean;
|
|
542
555
|
isError?: boolean;
|
|
543
556
|
errorMessage?: string | JSX.Element;
|
|
557
|
+
/**
|
|
558
|
+
* When true, the table's sort and filter state is read from and written to
|
|
559
|
+
* the browser's URL query string via `window.history.replaceState`.
|
|
560
|
+
* Intended for client-side tables — for server-side tables use
|
|
561
|
+
* `useServerSideTableState({ syncUrl: true })` instead.
|
|
562
|
+
*/
|
|
563
|
+
syncUrl?: boolean;
|
|
564
|
+
/**
|
|
565
|
+
* Namespace prefix for URL params when `syncUrl` is true. Required when
|
|
566
|
+
* more than one table on the same page needs URL sync to avoid key
|
|
567
|
+
* collisions. e.g. prefix "products" turns "sort_by" → "products_sort_by".
|
|
568
|
+
*/
|
|
569
|
+
urlParamPrefix?: string;
|
|
544
570
|
}
|
|
545
571
|
|
|
546
572
|
export declare interface TableToolbarOptions {
|
|
@@ -694,6 +720,104 @@ export declare const useNavigationProgress: () => NavigationProgressContextType;
|
|
|
694
720
|
*/
|
|
695
721
|
export declare function useSentryFeedbackOpen(): boolean;
|
|
696
722
|
|
|
723
|
+
/**
|
|
724
|
+
* Manages server-side sorting and filtering state for a TanStack Table.
|
|
725
|
+
*
|
|
726
|
+
* Returns TanStack-compatible state/callbacks plus pre-built query param
|
|
727
|
+
* strings (`sortParams`, `filterParams`) ready to append to API URLs.
|
|
728
|
+
*
|
|
729
|
+
* When `syncUrl` is `true` the current sort/filter state is reflected in the
|
|
730
|
+
* browser's address bar via `history.replaceState`, enabling deep-linkable
|
|
731
|
+
* tables without polluting the browser history stack.
|
|
732
|
+
*
|
|
733
|
+
* @example
|
|
734
|
+
* ```tsx
|
|
735
|
+
* const columns = useMemo(() => buildColumns(options), [options]);
|
|
736
|
+
*
|
|
737
|
+
* const { sorting, onSortingChange, columnFilters, onColumnFiltersChange, sortParams, filterParams } =
|
|
738
|
+
* useServerSideTableState({ syncUrl: true, columns });
|
|
739
|
+
*
|
|
740
|
+
* const { data } = useMyQuery(sortParams, filterParams);
|
|
741
|
+
*
|
|
742
|
+
* <Table
|
|
743
|
+
* reactTableOptions={{
|
|
744
|
+
* columns,
|
|
745
|
+
* manualSorting: true,
|
|
746
|
+
* manualFiltering: true,
|
|
747
|
+
* onSortingChange,
|
|
748
|
+
* onColumnFiltersChange,
|
|
749
|
+
* state: { sorting, columnFilters },
|
|
750
|
+
* }}
|
|
751
|
+
* />
|
|
752
|
+
* ```
|
|
753
|
+
*/
|
|
754
|
+
export declare const useServerSideTableState: (options?: UseServerSideTableStateOptions) => UseServerSideTableStateResult;
|
|
755
|
+
|
|
756
|
+
export declare interface UseServerSideTableStateOptions {
|
|
757
|
+
/** Initial sort column ID. */
|
|
758
|
+
initialSortField?: string;
|
|
759
|
+
/** Initial sort direction. Defaults to "asc". */
|
|
760
|
+
initialSortDirection?: "asc" | "desc";
|
|
761
|
+
/**
|
|
762
|
+
* When true, sorting and filtering state is read from and written to the
|
|
763
|
+
* browser's URL query string via `window.history.replaceState`, enabling
|
|
764
|
+
* shareable deep-links to a pre-filtered table.
|
|
765
|
+
*/
|
|
766
|
+
syncUrl?: boolean;
|
|
767
|
+
/**
|
|
768
|
+
* Namespace prefix for URL params. Required when more than one table on the
|
|
769
|
+
* same page needs URL sync to avoid key collisions.
|
|
770
|
+
* e.g. prefix "assets" turns "sortBy" → "assets_sortBy".
|
|
771
|
+
*
|
|
772
|
+
* Note: sortParams / filterParams returned by this hook are always
|
|
773
|
+
* unprefixed, regardless of the prefix used in the URL bar.
|
|
774
|
+
*/
|
|
775
|
+
urlParamPrefix?: string;
|
|
776
|
+
/**
|
|
777
|
+
* The same column definitions passed to the Table component. Used to
|
|
778
|
+
* automatically derive filter type information (via `meta.filterType`) for
|
|
779
|
+
* correct URL param serialization and deserialization.
|
|
780
|
+
*
|
|
781
|
+
* When provided, takes precedence over `columnFilterTypes`.
|
|
782
|
+
*/
|
|
783
|
+
columns?: ColumnDef<unknown, unknown>[];
|
|
784
|
+
/**
|
|
785
|
+
* Manual filter type map. Prefer passing `columns` instead — use this only
|
|
786
|
+
* when column definitions are not available.
|
|
787
|
+
*
|
|
788
|
+
* Maps column IDs to their filter type so URL params can be correctly
|
|
789
|
+
* deserialized back to TanStack Table filter state on page load.
|
|
790
|
+
* Columns not listed default to "text" (single string value).
|
|
791
|
+
* - "multiselect" → value serialized as comma-separated string, parsed back as string[]
|
|
792
|
+
* - "date" | "number" → value serialized as `<colId>_gte` / `<colId>_lte` pairs,
|
|
793
|
+
* parsed back as `{ min, max }` range object
|
|
794
|
+
*/
|
|
795
|
+
columnFilterTypes?: Record<string, ServerSideFilterType>;
|
|
796
|
+
}
|
|
797
|
+
|
|
798
|
+
export declare interface UseServerSideTableStateResult {
|
|
799
|
+
/** Pass to `reactTableOptions.state.sorting`. */
|
|
800
|
+
sorting: SortingState;
|
|
801
|
+
/** Pass to `reactTableOptions.onSortingChange`. */
|
|
802
|
+
onSortingChange: OnChangeFn<SortingState>;
|
|
803
|
+
/** Pass to `reactTableOptions.state.columnFilters`. */
|
|
804
|
+
columnFilters: ColumnFiltersState;
|
|
805
|
+
/** Pass to `reactTableOptions.onColumnFiltersChange`. */
|
|
806
|
+
onColumnFiltersChange: OnChangeFn<ColumnFiltersState>;
|
|
807
|
+
/**
|
|
808
|
+
* Sort query string (always unprefixed).
|
|
809
|
+
* e.g. `"&sort_by=review_status&sort_order=asc"` or `""` when unsorted.
|
|
810
|
+
* Append directly to your API request URL.
|
|
811
|
+
*/
|
|
812
|
+
sortParams: string;
|
|
813
|
+
/**
|
|
814
|
+
* Filter query string (always unprefixed).
|
|
815
|
+
* e.g. `"&review_status=approved&title=foo"` or `""` when unfiltered.
|
|
816
|
+
* Append directly to your API request URL.
|
|
817
|
+
*/
|
|
818
|
+
filterParams: string;
|
|
819
|
+
}
|
|
820
|
+
|
|
697
821
|
/**
|
|
698
822
|
* A hook to toggle a boolean value.
|
|
699
823
|
* @param initialState The initial state of the toggle.
|