@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/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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@harpercollins/harpercollins-design-system",
3
- "version": "1.33.0",
3
+ "version": "1.34.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git@ssh.dev.azure.com:v3/HarperCollinsUK/HCDesignSystem/HCDesignSystem"