@up42/up-components 8.2.0 → 8.3.0

package/dist/esm/types/index.d.ts

@@ -77,3 +77,4 @@ export { useCursorPagination, type CursorPaginatedResponse } from './utils/hooks
 export { useToggle, type UseToggleResult } from './utils/hooks/useToggle';
 export { useDebounce } from './utils/hooks/useDebounce';
 export { useAlert, type CreateAlertProps, type CreateSnackbarProps, } from './global/providers/AlertProvider/AlertProvider';
+export { useUrlParams, searchParamsToObject, objectToSearchParams, valueToString, type ParamsObject, type RemoveParamRules, type SearchParamObject, } from './utils/hooks/useUrlParams';

package/dist/esm/types/utils/hooks/useUrlParams/index.d.ts

@@ -0,0 +1,3 @@
+export * from './useUrlParams';
+export * from './types';
+export * from './utils';

package/dist/esm/types/utils/hooks/useUrlParams/types.d.ts

@@ -0,0 +1,22 @@
+export type SearchParamObject = Record<string, string>;
+export type ParamsObject = Record<string, unknown>;
+export type RemoveParamRules<T extends ParamsObject = ParamsObject> = {
+    [K in keyof T]?: (value: T[K]) => boolean;
+};
+export type Options<T extends ParamsObject> = {
+    cast: (search: SearchParamObject) => T;
+    parse: (searchParam: URLSearchParams) => SearchParamObject;
+    stringify: (searchParamsObject: T) => ReturnType<URLSearchParams['toString']>;
+    removeParams: RemoveParamRules<T>;
+};
+export type PartialOptions<T extends ParamsObject> = Partial<Options<T>>;
+export type UseUrlParamsReturn<T extends ParamsObject> = {
+    /** Search params object literal. */
+    params: T;
+    /** Navigate using given search params object literal. */
+    setParams: (params: ParamsObject) => void;
+    /** Stringified search params for use when navigating to other paths. */
+    stringParams: string;
+    /** Default params obtained by running the cast function with an empty object. Useful for resetting filters to their initial state. */
+    defaultParams: T;
+};

package/dist/esm/types/utils/hooks/useUrlParams/useUrlParams.d.ts

@@ -0,0 +1,11 @@
+import type { ParamsObject, PartialOptions, UseUrlParamsReturn } from './types';
+/**
+ * Parses URLSearchParams into an object and supports navigating with updated search params.
+ * Supports custom parsing (e.g. arrays, dates) and serialization back to a search string.
+ *
+ * @param options.cast - How to turn Record<string, string> into the params object (required when using typed params).
+ * @param options.parse - How to turn URLSearchParams into Record<string, string>. Default: entries as-is.
+ * @param options.stringify - How to stringify the params object. Default: arrays as comma-separated, dates as YYYY-MM-DD.
+ * @param options.removeParams - Map of param keys to predicate functions; when setParams runs, params whose predicate returns true are removed from the URL.
+ */
+export declare function useUrlParams<TParams extends ParamsObject>(options?: PartialOptions<TParams>): UseUrlParamsReturn<TParams>;

package/dist/esm/types/utils/hooks/useUrlParams/useUrlParams.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/utils/hooks/useUrlParams/utils.d.ts

@@ -0,0 +1,19 @@
+import { ParamsObject, SearchParamObject } from './types';
+/**
+ * There could be many ways to parse URLSearchParams to an object.
+ * For example, how should `a` be treated in `a=1&b=2&a=3`?
+ * This implementation is a choice.
+ */
+export declare function searchParamsToObject(searchParam: URLSearchParams): SearchParamObject;
+/**
+ * Stringify a value to a string.
+ * @param value - The value to stringify.
+ * @returns The stringified value.
+ */
+export declare function valueToString(value: unknown): string;
+/**
+ * There could be many ways to serialize an object to URLSearchParams.
+ * For example, how should `d` be treated in `{ d: new Date() }`? How should arrays behave?
+ * This implementation is a choice.
+ */
+export declare function objectToSearchParams<T extends ParamsObject = ParamsObject>(object: T): string;

package/dist/esm/types/utils/hooks/useUrlParams/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -11761,5 +11761,58 @@ type ContextState = {
  */
 declare const useAlert: () => ContextState;
 
-export { ActionToolbar, Alert, Avatar, Badge, Banner, Button, Checkbox, CodeBlock, CodeInline, CodeSnippet, ContactBox, ControlButton, CopyButton, DataGrid, DateTime, Divider, DocumentationPopover, EditTagsButton, EmptyState, FeatureCard, FeatureCardHeader, FeatureCardHeaderActions, FeatureFlagCheckbox, FilterPopover, FindUsersButton, FormCheckbox, FormDatePicker, FormDateRangePicker, FormDateRangePickerList, FormDateTimePicker, FormInput, FormRadio, FormSelect, FormSwitch, GridContainer, GridItem, Icon, Illustration, InfoCard, InfoModal, InfoPopover, Input, LearnMoreButton, Link, Loading, Logo, NotFound, PageContainer, PageHeader, PageHeaderV2, Popover, Radio, RoleBanner, Select, Slider, StatusLight, Switch, Tab, TabGroup, Table, TableBody, TableCell, TableContainer, TableFooter, TableHead, TablePagination, TableRow, TableSortLabel, Tabs, Tag, TagsList, ToggleButton, Typography, UpComponentsProvider, analytics, capitalize, copyToClipboard, formatDate, formatFileSize, formatNumber, generateQueryKey, theme, useAlert, useCursorPagination, useDebounce, useQueryParams, useRemotePagination, useToggle };
-export type { ActionToolbarProps, AlertProps, AnalyticsConfig, AvatarProps, BadgeProps, BannerProps, ButtonProps, CheckboxProps, CodeBlockProps, CodeInlineProps, CodeSnippetItemProps, CodeSnippetProps, ContactBoxProps, ControlButtonProps, CopyButtonProps, CreateAlertProps, CreateSnackbarProps, CursorPaginatedResponse, DateRange, DateTimeProps, DividerProps, DocumentationPopoverProps, EditTagsButtonProps, EmptyStateProps, FeatureCardHeaderActionsProps, FeatureCardHeaderProps, FeatureCardProps, FeatureFlagCheckboxProps, FilterPopoverProps, FindUsersButtonProps, FormCheckboxProps, FormDatePickerDateType, FormDatePickerProps, FormDateRangePickerListProps, FormDateRangePickerProps, FormDateTimePickerProps, FormInputProps, FormRadioProps, FormSelectProps, FormSwitchProps, GridContainerProps, GridItemProps, IconAction, IconProps$1 as IconProps, IllustrationProps, InfoCardProps, InfoModalProps, InfoPopoverProps, InputProps, LearnMoreButtonProps, LinkProps, LoadingProps, LogoProps, MenuAction, NotFoundProps, PageContainerProps, PageHeaderProps, PageHeaderV2Props, PaginatedResponse, PopoverProps, RadioProps, RoleBannerProps, SelectProps, SliderProps, StatusLightProps, SwitchProps, TabGroupProps, TabProps, TableBodyProps, TableCellProps, TableContainerProps, TableFooterProps, TableHeadProps, TablePaginationProps, TableProps, TableRowProps, TableSortLabelProps, TabsProps, TagItem, TagProps, TagsListProps, ToggleButtonProps, TypographyProps, UseToggleResult };
+type SearchParamObject = Record<string, string>;
+type ParamsObject = Record<string, unknown>;
+type RemoveParamRules<T extends ParamsObject = ParamsObject> = {
+    [K in keyof T]?: (value: T[K]) => boolean;
+};
+type Options<T extends ParamsObject> = {
+    cast: (search: SearchParamObject) => T;
+    parse: (searchParam: URLSearchParams) => SearchParamObject;
+    stringify: (searchParamsObject: T) => ReturnType<URLSearchParams['toString']>;
+    removeParams: RemoveParamRules<T>;
+};
+type PartialOptions<T extends ParamsObject> = Partial<Options<T>>;
+type UseUrlParamsReturn<T extends ParamsObject> = {
+    /** Search params object literal. */
+    params: T;
+    /** Navigate using given search params object literal. */
+    setParams: (params: ParamsObject) => void;
+    /** Stringified search params for use when navigating to other paths. */
+    stringParams: string;
+    /** Default params obtained by running the cast function with an empty object. Useful for resetting filters to their initial state. */
+    defaultParams: T;
+};
+
+/**
+ * Parses URLSearchParams into an object and supports navigating with updated search params.
+ * Supports custom parsing (e.g. arrays, dates) and serialization back to a search string.
+ *
+ * @param options.cast - How to turn Record<string, string> into the params object (required when using typed params).
+ * @param options.parse - How to turn URLSearchParams into Record<string, string>. Default: entries as-is.
+ * @param options.stringify - How to stringify the params object. Default: arrays as comma-separated, dates as YYYY-MM-DD.
+ * @param options.removeParams - Map of param keys to predicate functions; when setParams runs, params whose predicate returns true are removed from the URL.
+ */
+declare function useUrlParams<TParams extends ParamsObject>(options?: PartialOptions<TParams>): UseUrlParamsReturn<TParams>;
+
+/**
+ * There could be many ways to parse URLSearchParams to an object.
+ * For example, how should `a` be treated in `a=1&b=2&a=3`?
+ * This implementation is a choice.
+ */
+declare function searchParamsToObject(searchParam: URLSearchParams): SearchParamObject;
+/**
+ * Stringify a value to a string.
+ * @param value - The value to stringify.
+ * @returns The stringified value.
+ */
+declare function valueToString(value: unknown): string;
+/**
+ * There could be many ways to serialize an object to URLSearchParams.
+ * For example, how should `d` be treated in `{ d: new Date() }`? How should arrays behave?
+ * This implementation is a choice.
+ */
+declare function objectToSearchParams<T extends ParamsObject = ParamsObject>(object: T): string;
+
+export { ActionToolbar, Alert, Avatar, Badge, Banner, Button, Checkbox, CodeBlock, CodeInline, CodeSnippet, ContactBox, ControlButton, CopyButton, DataGrid, DateTime, Divider, DocumentationPopover, EditTagsButton, EmptyState, FeatureCard, FeatureCardHeader, FeatureCardHeaderActions, FeatureFlagCheckbox, FilterPopover, FindUsersButton, FormCheckbox, FormDatePicker, FormDateRangePicker, FormDateRangePickerList, FormDateTimePicker, FormInput, FormRadio, FormSelect, FormSwitch, GridContainer, GridItem, Icon, Illustration, InfoCard, InfoModal, InfoPopover, Input, LearnMoreButton, Link, Loading, Logo, NotFound, PageContainer, PageHeader, PageHeaderV2, Popover, Radio, RoleBanner, Select, Slider, StatusLight, Switch, Tab, TabGroup, Table, TableBody, TableCell, TableContainer, TableFooter, TableHead, TablePagination, TableRow, TableSortLabel, Tabs, Tag, TagsList, ToggleButton, Typography, UpComponentsProvider, analytics, capitalize, copyToClipboard, formatDate, formatFileSize, formatNumber, generateQueryKey, objectToSearchParams, searchParamsToObject, theme, useAlert, useCursorPagination, useDebounce, useQueryParams, useRemotePagination, useToggle, useUrlParams, valueToString };
+export type { ActionToolbarProps, AlertProps, AnalyticsConfig, AvatarProps, BadgeProps, BannerProps, ButtonProps, CheckboxProps, CodeBlockProps, CodeInlineProps, CodeSnippetItemProps, CodeSnippetProps, ContactBoxProps, ControlButtonProps, CopyButtonProps, CreateAlertProps, CreateSnackbarProps, CursorPaginatedResponse, DateRange, DateTimeProps, DividerProps, DocumentationPopoverProps, EditTagsButtonProps, EmptyStateProps, FeatureCardHeaderActionsProps, FeatureCardHeaderProps, FeatureCardProps, FeatureFlagCheckboxProps, FilterPopoverProps, FindUsersButtonProps, FormCheckboxProps, FormDatePickerDateType, FormDatePickerProps, FormDateRangePickerListProps, FormDateRangePickerProps, FormDateTimePickerProps, FormInputProps, FormRadioProps, FormSelectProps, FormSwitchProps, GridContainerProps, GridItemProps, IconAction, IconProps$1 as IconProps, IllustrationProps, InfoCardProps, InfoModalProps, InfoPopoverProps, InputProps, LearnMoreButtonProps, LinkProps, LoadingProps, LogoProps, MenuAction, NotFoundProps, PageContainerProps, PageHeaderProps, PageHeaderV2Props, PaginatedResponse, ParamsObject, PopoverProps, RadioProps, RemoveParamRules, RoleBannerProps, SearchParamObject, SelectProps, SliderProps, StatusLightProps, SwitchProps, TabGroupProps, TabProps, TableBodyProps, TableCellProps, TableContainerProps, TableFooterProps, TableHeadProps, TablePaginationProps, TableProps, TableRowProps, TableSortLabelProps, TabsProps, TagItem, TagProps, TagsListProps, ToggleButtonProps, TypographyProps, UseToggleResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@up42/up-components",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "description": "UP42 Component Library",
   "author": "Axel Fuhrmann axel.fuhrmann@up42.com",
   "license": "ISC",
@@ -78,7 +78,6 @@
     "lint-staged": "^12.3.1",
     "prettier": "^2.5.1",
     "react": "^18.3.1",
-    "react-router": "^7.12.0",
     "rimraf": "^6.1.2",
     "rollup": "^4.59.0",
     "rollup-plugin-dts": "^6.1.0",
@@ -99,7 +98,8 @@
     "@mui/x-data-grid-premium": "^6.8.0",
     "@mui/x-date-pickers-pro": "^6.8.0",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "react-router": "^7.12.0"
   },
   "lint-staged": {
     "*.{js,tsx,ts}": "eslint --cache --fix",