@harpercollins/harpercollins-design-system 1.33.0 → 1.35.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.
Files changed (34) hide show
  1. package/dist/cjs/components/data-display/DataGrid/DataGrid.cjs +1 -0
  2. package/dist/cjs/components/data-display/{Table → DataGrid}/TableToolbar.cjs +1 -1
  3. package/dist/cjs/components/data-display/DataGrid/hooks/useDataGrid.cjs +1 -0
  4. package/dist/cjs/components/data-display/DataGrid/tableUrlUtils.cjs +1 -0
  5. package/dist/cjs/components/data-display/Table/Table.cjs +1 -1
  6. package/dist/cjs/components/data-display/Table/Table.styles.cjs +2 -2
  7. package/dist/cjs/components/data-display/Table/TableHeader.cjs +1 -0
  8. package/dist/cjs/components/data-display/Table/TableLayout.cjs +1 -0
  9. package/dist/cjs/hooks/useServerSideTableState.cjs +1 -0
  10. package/dist/cjs/index.cjs +1 -1
  11. package/dist/esm/components/data-display/DataGrid/DataGrid.js +70 -0
  12. package/dist/esm/components/data-display/{Table → DataGrid}/TableToolbar.js +10 -8
  13. package/dist/esm/components/data-display/DataGrid/hooks/useDataGrid.js +189 -0
  14. package/dist/esm/components/data-display/DataGrid/tableUrlUtils.js +108 -0
  15. package/dist/esm/components/data-display/Table/Table.js +51 -346
  16. package/dist/esm/components/data-display/Table/Table.styles.js +4 -5
  17. package/dist/esm/components/data-display/Table/TableHeader.js +92 -0
  18. package/dist/esm/components/data-display/Table/TableLayout.js +112 -0
  19. package/dist/esm/hooks/useServerSideTableState.js +47 -0
  20. package/dist/esm/index.js +221 -210
  21. package/dist/index.d.ts +163 -12
  22. package/package.json +1 -1
  23. package/dist/cjs/components/data-display/Table/index.cjs +0 -1
  24. package/dist/esm/components/data-display/Table/index.js +0 -4
  25. /package/dist/cjs/components/data-display/{Table → DataGrid}/ExportToExcelButton.cjs +0 -0
  26. /package/dist/cjs/components/data-display/{Table → DataGrid}/FilterChipsSection.cjs +0 -0
  27. /package/dist/cjs/components/data-display/{Table → DataGrid}/filters/FilterComponents.cjs +0 -0
  28. /package/dist/cjs/components/data-display/{Table → DataGrid}/filters/filterFunctions.cjs +0 -0
  29. /package/dist/cjs/components/data-display/{Table → DataGrid}/hooks/useInfiniteScroll.cjs +0 -0
  30. /package/dist/esm/components/data-display/{Table → DataGrid}/ExportToExcelButton.js +0 -0
  31. /package/dist/esm/components/data-display/{Table → DataGrid}/FilterChipsSection.js +0 -0
  32. /package/dist/esm/components/data-display/{Table → DataGrid}/filters/FilterComponents.js +0 -0
  33. /package/dist/esm/components/data-display/{Table → DataGrid}/filters/filterFunctions.js +0 -0
  34. /package/dist/esm/components/data-display/{Table → DataGrid}/hooks/useInfiniteScroll.js +0 -0
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';
@@ -85,6 +89,7 @@ import { SwitchProps } from '@mui/joy';
85
89
  import { SyntheticEvent } from 'react';
86
90
  import { default as Tab } from '@mui/joy/Tab';
87
91
  import { tabClasses } from '@mui/joy/Tab';
92
+ import { Table as Table_2 } from '@tanstack/react-table';
88
93
  import { TableOptions } from '@tanstack/react-table';
89
94
  import { default as TabList } from '@mui/joy/TabList';
90
95
  import { tabListClasses } from '@mui/joy/TabList';
@@ -95,6 +100,7 @@ import { TextareaProps } from '@mui/joy';
95
100
  import { TextField } from '@mui/joy';
96
101
  import { TooltipProps as TooltipProps_2 } from '@mui/joy';
97
102
  import { TypographyProps } from '@mui/joy';
103
+ import { VirtualItem } from '@tanstack/react-virtual';
98
104
 
99
105
  export declare function Accordion(props: AccordionProps): JSX_2.Element;
100
106
 
@@ -212,6 +218,54 @@ export declare function CircularProgress(props: CircularProgressProps): JSX_2.El
212
218
 
213
219
  export declare function Container(props: ContainerProps): JSX_2.Element;
214
220
 
221
+ /** Core data-management options shared by DataGrid and Table. */
222
+ declare interface DataGridCoreOptions<TData = unknown> {
223
+ id: string;
224
+ loading?: boolean;
225
+ reactTableOptions: Partial<TableOptions<TData>> & Pick<TableOptions<TData>, "data" | "columns">;
226
+ gridCheckboxes?: boolean;
227
+ allSelected?: boolean;
228
+ onSelectionChange?: (selection: RowSelectionState) => void;
229
+ infiniteScroll?: InfiniteScrollOptions;
230
+ syncUrl?: boolean;
231
+ urlParamPrefix?: string;
232
+ }
233
+
234
+ /**
235
+ * The context object passed to the `renderLayout` render prop.
236
+ * Contains everything a layout needs to render filtered/sorted data with
237
+ * infinite scroll support.
238
+ */
239
+ declare interface DataGridLayoutContext<TData = unknown> {
240
+ id: string;
241
+ table: Table_2<TData>;
242
+ rows: Row<TData>[];
243
+ isVirtual: boolean;
244
+ virtualItems: VirtualItem[];
245
+ paddingTop: number;
246
+ paddingBottom: number;
247
+ measureElement: (node: Element | null) => void;
248
+ /** Attach this ref to the layout's scroll container. */
249
+ wrapperRef: default_2.RefObject<HTMLDivElement>;
250
+ /** Attach this ref to the toolbar element (used for sticky-header calculations). */
251
+ toolbarRef: default_2.RefObject<HTMLDivElement>;
252
+ loading: boolean;
253
+ fetchMoreOnBottomReached: (container: HTMLDivElement | null) => void;
254
+ }
255
+
256
+ declare interface DataGridProps<TData = unknown> extends DataGridCoreOptions<TData> {
257
+ /**
258
+ * Render prop that receives the processed data context and returns the
259
+ * layout to display. Use the built-in `TableLayout` for a standard table,
260
+ * or supply your own (e.g. an image grid) to reuse all data-management
261
+ * features with a different visual layout.
262
+ */
263
+ renderLayout: (ctx: DataGridLayoutContext<TData>) => default_2.ReactNode;
264
+ toolbar?: TableToolbarOptions;
265
+ isError?: boolean;
266
+ errorMessage?: string | JSX.Element;
267
+ }
268
+
215
269
  declare type DateInputProps = ReactDatePickerProps;
216
270
 
217
271
  export declare const DatePicker: default_2.ForwardRefExoticComponent<DateInputProps & default_2.RefAttributes<default_3<undefined, undefined>>>;
@@ -236,6 +290,12 @@ export declare const Drawer: default_2.ForwardRefExoticComponent<Omit<default_2.
236
290
 
237
291
  export declare function Dropdown(props: DropdownProps): JSX_2.Element;
238
292
 
293
+ /**
294
+ * Derives a `columnFilterTypes` map from TanStack Table column definitions by
295
+ * reading each column's `meta.filterType`.
296
+ */
297
+ export declare function extractColumnFilterTypes(columns: ColumnDef<unknown, unknown>[]): Record<string, ServerSideFilterType>;
298
+
239
299
  /**
240
300
  * Format currency value to locale and currency
241
301
  * @param value - The value to format
@@ -483,6 +543,9 @@ declare interface RelativeTimeProps {
483
543
 
484
544
  export declare function Select<TValue extends object>(props: SelectProps<TValue, false>): JSX_2.Element;
485
545
 
546
+ /** Filter types that affect how URL params are serialized/deserialized. */
547
+ export declare type ServerSideFilterType = "text" | "select" | "multiselect" | "date" | "number";
548
+
486
549
  export declare function Sheet(props: SheetProps): JSX_2.Element;
487
550
 
488
551
  export declare function Skeleton(props: SkeletonProps): JSX_2.Element;
@@ -519,28 +582,18 @@ export { Tab }
519
582
 
520
583
  export { tabClasses }
521
584
 
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;
585
+ 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
586
 
524
- export declare interface TableProps<TData = unknown> {
525
- id: string;
526
- loading?: boolean;
587
+ export declare interface TableProps<TData = unknown> extends Omit<DataGridProps<TData>, "renderLayout"> {
527
588
  maxHeight?: boolean;
528
589
  wrapText?: boolean;
529
590
  rowRender?: (row: Row<TData>, props: {
530
591
  key: string;
531
592
  }) => JSX.Element;
532
- reactTableOptions: Partial<TableOptions<TData>> & Pick<TableOptions<TData>, "data" | "columns">;
533
- gridCheckboxes?: boolean;
534
- allSelected?: boolean;
535
- onSelectionChange?: (selection: RowSelectionState) => void;
536
593
  showStickyScrollbar?: boolean;
537
594
  enableStickyHeader?: boolean;
538
595
  stickyHeaderOffset?: number;
539
- infiniteScroll?: InfiniteScrollOptions;
540
- toolbar?: TableToolbarOptions;
541
596
  footer?: boolean;
542
- isError?: boolean;
543
- errorMessage?: string | JSX.Element;
544
597
  }
545
598
 
546
599
  export declare interface TableToolbarOptions {
@@ -694,6 +747,104 @@ export declare const useNavigationProgress: () => NavigationProgressContextType;
694
747
  */
695
748
  export declare function useSentryFeedbackOpen(): boolean;
696
749
 
750
+ /**
751
+ * Manages server-side sorting and filtering state for a TanStack Table.
752
+ *
753
+ * Returns TanStack-compatible state/callbacks plus pre-built query param
754
+ * strings (`sortParams`, `filterParams`) ready to append to API URLs.
755
+ *
756
+ * When `syncUrl` is `true` the current sort/filter state is reflected in the
757
+ * browser's address bar via `history.replaceState`, enabling deep-linkable
758
+ * tables without polluting the browser history stack.
759
+ *
760
+ * @example
761
+ * ```tsx
762
+ * const columns = useMemo(() => buildColumns(options), [options]);
763
+ *
764
+ * const { sorting, onSortingChange, columnFilters, onColumnFiltersChange, sortParams, filterParams } =
765
+ * useServerSideTableState({ syncUrl: true, columns });
766
+ *
767
+ * const { data } = useMyQuery(sortParams, filterParams);
768
+ *
769
+ * <Table
770
+ * reactTableOptions={{
771
+ * columns,
772
+ * manualSorting: true,
773
+ * manualFiltering: true,
774
+ * onSortingChange,
775
+ * onColumnFiltersChange,
776
+ * state: { sorting, columnFilters },
777
+ * }}
778
+ * />
779
+ * ```
780
+ */
781
+ export declare const useServerSideTableState: (options?: UseServerSideTableStateOptions) => UseServerSideTableStateResult;
782
+
783
+ export declare interface UseServerSideTableStateOptions {
784
+ /** Initial sort column ID. */
785
+ initialSortField?: string;
786
+ /** Initial sort direction. Defaults to "asc". */
787
+ initialSortDirection?: "asc" | "desc";
788
+ /**
789
+ * When true, sorting and filtering state is read from and written to the
790
+ * browser's URL query string via `window.history.replaceState`, enabling
791
+ * shareable deep-links to a pre-filtered table.
792
+ */
793
+ syncUrl?: boolean;
794
+ /**
795
+ * Namespace prefix for URL params. Required when more than one table on the
796
+ * same page needs URL sync to avoid key collisions.
797
+ * e.g. prefix "assets" turns "sortBy" → "assets_sortBy".
798
+ *
799
+ * Note: sortParams / filterParams returned by this hook are always
800
+ * unprefixed, regardless of the prefix used in the URL bar.
801
+ */
802
+ urlParamPrefix?: string;
803
+ /**
804
+ * The same column definitions passed to the Table component. Used to
805
+ * automatically derive filter type information (via `meta.filterType`) for
806
+ * correct URL param serialization and deserialization.
807
+ *
808
+ * When provided, takes precedence over `columnFilterTypes`.
809
+ */
810
+ columns?: ColumnDef<unknown, unknown>[];
811
+ /**
812
+ * Manual filter type map. Prefer passing `columns` instead — use this only
813
+ * when column definitions are not available.
814
+ *
815
+ * Maps column IDs to their filter type so URL params can be correctly
816
+ * deserialized back to TanStack Table filter state on page load.
817
+ * Columns not listed default to "text" (single string value).
818
+ * - "multiselect" → value serialized as comma-separated string, parsed back as string[]
819
+ * - "date" | "number" → value serialized as `<colId>_gte` / `<colId>_lte` pairs,
820
+ * parsed back as `{ min, max }` range object
821
+ */
822
+ columnFilterTypes?: Record<string, ServerSideFilterType>;
823
+ }
824
+
825
+ export declare interface UseServerSideTableStateResult {
826
+ /** Pass to `reactTableOptions.state.sorting`. */
827
+ sorting: SortingState;
828
+ /** Pass to `reactTableOptions.onSortingChange`. */
829
+ onSortingChange: OnChangeFn<SortingState>;
830
+ /** Pass to `reactTableOptions.state.columnFilters`. */
831
+ columnFilters: ColumnFiltersState;
832
+ /** Pass to `reactTableOptions.onColumnFiltersChange`. */
833
+ onColumnFiltersChange: OnChangeFn<ColumnFiltersState>;
834
+ /**
835
+ * Sort query string (always unprefixed).
836
+ * e.g. `"&sort_by=review_status&sort_order=asc"` or `""` when unsorted.
837
+ * Append directly to your API request URL.
838
+ */
839
+ sortParams: string;
840
+ /**
841
+ * Filter query string (always unprefixed).
842
+ * e.g. `"&review_status=approved&title=foo"` or `""` when unfiltered.
843
+ * Append directly to your API request URL.
844
+ */
845
+ filterParams: string;
846
+ }
847
+
697
848
  /**
698
849
  * A hook to toggle a boolean value.
699
850
  * @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.35.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git@ssh.dev.azure.com:v3/HarperCollinsUK/HCDesignSystem/HCDesignSystem"
@@ -1 +0,0 @@
1
- "use strict";const e=require("./Table.cjs");module.exports=e;
@@ -1,4 +0,0 @@
1
- import e from "./Table.js";
2
- export {
3
- e as default
4
- };