@rio-cloud/uikit-mcp 1.1.4 → 1.1.6

package/dist/docs/utilities/routeUtils.md

@@ -2,30 +2,243 @@
 
 *Category:* Utilities
 *Section:* Helper
-*Source:* https://uikit.developers.rio.cloud/#utilities/routeUtils
-*Captured:* 2026-01-14T09:08:39.630Z
+*Source:* https://uikit.developers.rio.cloud/#/utilities/routeUtils
+*Captured:* 2026-02-23T13:48:46.337Z
 
-Set of utility functions which helps parsing and stringify state into and from the URL.
+Utility helpers for parsing and serializing URL state. These are low-level building blocks for service-specific mapping.
 
 ## Route Utils
 
-These functions will combine sort props like sort order and sort direction and map table settings into a compact comma separated list where hidden columns have a leading "-" and the width of a column will be attached to the column name if it it different from the default.
+For end-to-end URL sync (URL - store + store - URL), prefer the useUrlState hook. Use the route utils on this page when you need custom parse/serialize logic for specific values.
 
-Example: http:/my-url/#demoService/table?sort=+userNickName&columns=itemId,userImageStatus,userNickName:278,userFirstName,userLastName,userActivity,userJobTitle,userEmail,userPhoneNumber
+For history behavior guidance (pushState vs. replaceState), see the State in URL guideline .
+
+If you use UrlConfigItem with useUrlState, set an explicit defaultValue for every key so removed params can reliably reset state.
+
+## Route utils overview
+
+## Simple state in URL
+
+Example for manual parse/stringify helpers in a service file.
 
 ### Example: Example 1
 
-import qs from 'qs';
-import { get } from 'es-toolkit/compat';
+import { deserializeValue, serializeValue } from '@rio-cloud/rio-uikit/routeUtils';
+
+// Adapt to your configuration
+const BASE_PATH = 'my-service';
+const VIEW_OPTIONS = ['list', 'grid'] as const;
+
+type ViewType = (typeof VIEW_OPTIONS)[number];
+const DEFAULT_VIEW: ViewType = 'list';
+const DEFAULT_TAB_ID = 1;
+
+type RouterLike = { location?: Location };
+type RouteState = {
+query: string;
+view: ViewType;
+tabId: number;
+tags: string[];
+showArchived: boolean;
+};
+
+const isViewType = (value: string): value is ViewType => (VIEW_OPTIONS as readonly string[]).includes(value);
+
+/**
+* Reads URL state from a router-like object.
+* Useful when you want a lightweight parser without a hook.
+*
+* Note: Optional service helper when you only need a one-off parse.
+* For reactive state sync, use the `useUrlState` hook instead.
+*
+* @example
+* const state = parseRoute({ location: window.location });
+*/
+export const parseRoute = (router: RouterLike): RouteState => {
+const location = (router?.location ?? {}) as Location;
+const params = new URLSearchParams(location.search || '');
+
+const parsedView = deserializeValue(params.get('view'), 'string');
+const parsedTabId = deserializeValue(params.get('tabId'), 'number');
+const parsedTags = deserializeValue(params.get('tags'), 'array');
+const parsedArchived = deserializeValue(params.get('archived'), 'boolean');
+
+return {
+query: deserializeValue(params.get('q'), 'string') ?? '',
+view: parsedView && isViewType(parsedView) ? parsedView : DEFAULT_VIEW,
+tabId: parsedTabId ?? DEFAULT_TAB_ID,
+tags: parsedTags ?? [],
+showArchived: parsedArchived ?? false,
+};
+};
+
+/**
+* Builds a deep-link URL for a given state.
+* Useful for linking to a screen with preselected filters.
+*
+* Note: Optional service helper when you only need to build a link.
+* For reactive state sync, use the `useUrlState` hook instead.
+*
+* @example
+* const url = makeRoute({ query: 'rio', view: 'list', tabId: 2, tags: ['banana'], showArchived: false });
+*/
+export const makeRoute = (state: RouteState) => {
+const params = new URLSearchParams();
+
+const query = serializeValue(state.query, 'string');
+if (query) {
+params.set('q', query);
+}
+
+if (state.view !== DEFAULT_VIEW) {
+const view = serializeValue(state.view, 'string');
+if (view) {
+params.set('view', view);
+}
+}
+
+if (state.tabId !== DEFAULT_TAB_ID) {
+const tabId = serializeValue(state.tabId, 'number');
+if (tabId) {
+params.set('tabId', tabId);
+}
+}
+
+const tags = serializeValue(state.tags, 'array');
+if (tags) {
+params.set('tags', tags);
+}
+
+if (state.showArchived) {
+const archived = serializeValue(state.showArchived, 'boolean');
+if (archived) {
+params.set('archived', archived);
+}
+}
+
+const queryString = params.toString();
+return `${BASE_PATH}/${queryString ? `?${queryString}` : ''}`;
+};
+
+#### Summary
+
+import { deserializeValue, serializeValue } from '@rio-cloud/rio-uikit/routeUtils';
+
+// Adapt to your configuration
+const BASE_PATH = 'my-service';
+const VIEW_OPTIONS = ['list', 'grid'] as const;
+
+type ViewType = (typeof VIEW_OPTIONS)[number];
+const DEFAULT_VIEW: ViewType = 'list';
+const DEFAULT_TAB_ID = 1;
+
+type RouterLike = { location?: Location };
+type RouteState = {
+query: string;
+view: ViewType;
+tabId: number;
+tags: string[];
+showArchived: boolean;
+};
+
+const isViewType = (value: string): value is ViewType => (VIEW_OPTIONS as readonly string[]).includes(value);
+
+/**
+* Reads URL state from a router-like object.
+* Useful when you want a lightweight parser without a hook.
+*
+* Note: Optional service helper when you only need a one-off parse.
+* For reactive state sync, use the `useUrlState` hook instead.
+*
+* @example
+* const state = parseRoute({ location: window.location });
+*/
+export const parseRoute = (router: RouterLike): RouteState => {
+const location = (router?.location ?? {}) as Location;
+const params = new URLSearchParams(location.search || '');
+
+const parsedView = deserializeValue(params.get('view'), 'string');
+const parsedTabId = deserializeValue(params.get('tabId'), 'number');
+const parsedTags = deserializeValue(params.get('tags'), 'array');
+const parsedArchived = deserializeValue(params.get('archived'), 'boolean');
+
+return {
+query: deserializeValue(params.get('q'), 'string') ?? '',
+view: parsedView && isViewType(parsedView) ? parsedView : DEFAULT_VIEW,
+tabId: parsedTabId ?? DEFAULT_TAB_ID,
+tags: parsedTags ?? [],
+showArchived: parsedArchived ?? false,
+};
+};
+
+/**
+* Builds a deep-link URL for a given state.
+* Useful for linking to a screen with preselected filters.
+*
+* Note: Optional service helper when you only need to build a link.
+* For reactive state sync, use the `useUrlState` hook instead.
+*
+* @example
+* const url = makeRoute({ query: 'rio', view: 'list', tabId: 2, tags: ['banana'], showArchived: false });
+*/
+export const makeRoute = (state: RouteState) => {
+const params = new URLSearchParams();
+
+const query = serializeValue(state.query, 'string');
+if (query) {
+params.set('q', query);
+}
+
+if (state.view !== DEFAULT_VIEW) {
+const view = serializeValue(state.view, 'string');
+if (view) {
+params.set('view', view);
+}
+}
+
+if (state.tabId !== DEFAULT_TAB_ID) {
+const tabId = serializeValue(state.tabId, 'number');
+if (tabId) {
+params.set('tabId', tabId);
+}
+}
+
+const tags = serializeValue(state.tags, 'array');
+if (tags) {
+params.set('tags', tags);
+}
+
+if (state.showArchived) {
+const archived = serializeValue(state.showArchived, 'boolean');
+if (archived) {
+params.set('archived', archived);
+}
+}
+
+const queryString = params.toString();
+return `${BASE_PATH}/${queryString ? `?${queryString}` : ''}`;
+};
+
+## TableSettingsDialog state
+
+Example for compact sort + table settings mapping with dedicated helpers.
+
+Example: http://my-url/#demoService/table?sort=userNickName&columns=itemId,userImageStatus,userNickName:278,userFirstName,userLastName,userActivity,userJobTitle,userEmail,userPhoneNumber
+
+### Example: Example 2
 
 import {
-parseColumnsSettingsStrings,
+deserializeValue,
 mapColumnsSettingsToStrings,
-getSortDirShort,
+parseColumnsSettingsStrings,
 parseSorting,
-type ColumnsSettings,
+serializeSorting,
+serializeValue,
 } from '@rio-cloud/rio-uikit/routeUtils';
+import type { SortDirectionType } from '@rio-cloud/rio-uikit/SortUtils';
+import type { TableColumnsSettings } from '@rio-cloud/rio-uikit/TableSettingsDialog';
 
+// TableSettingsDialog state example.
 // Adapt to your configuration
 const BASE_PATH = 'my-service';
 const defaultColumnsDetails: Record<string, { width: number; defaultWidth?: number }> = {
@@ -35,77 +248,89 @@ defaultWidth: 250,
 },
 };
 
-// Options for the "qs" library
-const OPTIONS = {
-comma: true, // required to parse comma separated string into array
-arrayFormat: 'comma' as const, // required to stringify arrays into comma separated strings
-indices: false, // don't use array indices
-encode: false, // don't encode the entire string as it will be done individually for certain params
-decode: false,
-skipNulls: true, // required to remove empty params
-};
-
 // Sample code for parsing the route just for illustration how to use the utils functions
 // Feel free to modify this to your needs.
 // Note: the "parseRoute" and "makeRoute" functions may contain more props which are left out in this demo
 type RouterLike = { location?: Location };
 
+/**
+* Reads table settings state from a router-like object.
+*
+* Note: Optional service helper when you only need a one-off parse.
+* For reactive state sync, use the `useUrlState` hook instead.
+*
+* @example
+* const state = parseRoute({ location: window.location });
+*/
 export const parseRoute = (router: RouterLike) => {
-const location = get(router, 'location', {}) as Location;
-const searchParams = location.search ? location.search.replace('?', '') : location.search;
+const location = (router?.location ?? {}) as Location;
+const params = new URLSearchParams(location.search || '');
 
-const { sort, columns } = qs.parse(searchParams, OPTIONS) as {
-sort?: string;
-columns?: string[] | Record<string, string>;
-};
-
-const sorting = sort ? parseSorting(sort) : undefined;
+const sortValue = deserializeValue(params.get('sort'), 'string');
+const sorting = sortValue ? parseSorting(sortValue) : undefined;
 
-const sortBy = sorting && typeof sorting !== 'string' ? sorting.sortBy : undefined;
-const sortDir = sorting && typeof sorting !== 'string' ? sorting.sortDir : undefined;
+const columnsList = deserializeValue(params.get('columns'), 'array');
+const columns = columnsList ? parseColumnsSettingsStrings(columnsList, defaultColumnsDetails) : undefined;
 
 return {
-sortBy,
-sortDir,
-columns:
-columns &&
-parseColumnsSettingsStrings(
-Array.isArray(columns) ? columns : Object.values(columns || {}),
-defaultColumnsDetails
-),
+sortBy: sorting?.sortBy,
+sortDir: sorting?.sortDir,
+columns,
 };
 };
 
 type mapRouteProps = {
 sortBy: string;
-sortDir: string;
-columns: ColumnsSettings;
+sortDir: SortDirectionType;
+columns: TableColumnsSettings;
 };
 
+/**
+* Builds a deep-link URL for a given table settings state.
+*
+* Note: Optional service helper when you only need to build a link.
+* For reactive state sync, use the `useUrlState` hook instead.
+*
+* @example
+* const url = makeRoute({ sortBy: 'name', sortDir: 'ASCENDING', columns });
+*/
 export const makeRoute = ({ sortBy, sortDir, columns }: mapRouteProps) => {
-// Set props to undefined or null in order to remove it from the URL when not defined
-const params = {
-sort: sortBy && `${getSortDirShort(sortDir)}${sortBy}`,
-columns: columns && mapColumnsSettingsToStrings(columns),
-};
-const queryParams = qs.stringify(params, OPTIONS);
-const searchFragment = queryParams && `?${queryParams}`;
+const params = new URLSearchParams();
+
+if (sortBy) {
+// Use serializeSorting for compact empty / - prefix behavior.
+const serializedSort = serializeSorting({ sortBy, sortDir });
+if (serializedSort) {
+params.set('sort', serializedSort);
+}
+}
+
+const mappedColumns = mapColumnsSettingsToStrings(columns);
+const serializedColumns = serializeValue(mappedColumns, 'array');
+if (serializedColumns) {
+params.set('columns', serializedColumns);
+}
+
+const queryString = params.toString();
+const searchFragment = queryString ? `?${queryString}` : '';
+
 return `${BASE_PATH}/${searchFragment}`;
 };
 
 #### Summary
 
-import qs from 'qs';
-import { get } from 'es-toolkit/compat';
-
 import {
-parseColumnsSettingsStrings,
+deserializeValue,
 mapColumnsSettingsToStrings,
-getSortDirShort,
+parseColumnsSettingsStrings,
 parseSorting,
-type ColumnsSettings,
+serializeSorting,
+serializeValue,
 } from '@rio-cloud/rio-uikit/routeUtils';
+import type { SortDirectionType } from '@rio-cloud/rio-uikit/SortUtils';
+import type { TableColumnsSettings } from '@rio-cloud/rio-uikit/TableSettingsDialog';
 
+// TableSettingsDialog state example.
 // Adapt to your configuration
 const BASE_PATH = 'my-service';
 const defaultColumnsDetails: Record<string, { width: number; defaultWidth?: number }> = {
@@ -115,60 +340,71 @@ defaultWidth: 250,
 },
 };
 
-// Options for the "qs" library
-const OPTIONS = {
-comma: true, // required to parse comma separated string into array
-arrayFormat: 'comma' as const, // required to stringify arrays into comma separated strings
-indices: false, // don't use array indices
-encode: false, // don't encode the entire string as it will be done individually for certain params
-decode: false,
-skipNulls: true, // required to remove empty params
-};
-
 // Sample code for parsing the route just for illustration how to use the utils functions
 // Feel free to modify this to your needs.
 // Note: the "parseRoute" and "makeRoute" functions may contain more props which are left out in this demo
 type RouterLike = { location?: Location };
 
+/**
+* Reads table settings state from a router-like object.
+*
+* Note: Optional service helper when you only need a one-off parse.
+* For reactive state sync, use the `useUrlState` hook instead.
+*
+* @example
+* const state = parseRoute({ location: window.location });
+*/
 export const parseRoute = (router: RouterLike) => {
-const location = get(router, 'location', {}) as Location;
-const searchParams = location.search ? location.search.replace('?', '') : location.search;
+const location = (router?.location ?? {}) as Location;
+const params = new URLSearchParams(location.search || '');
 
-const { sort, columns } = qs.parse(searchParams, OPTIONS) as {
-sort?: string;
-columns?: string[] | Record<string, string>;
-};
+const sortValue = deserializeValue(params.get('sort'), 'string');
+const sorting = sortValue ? parseSorting(sortValue) : undefined;
 
-const sorting = sort ? parseSorting(sort) : undefined;
-
-const sortBy = sorting && typeof sorting !== 'string' ? sorting.sortBy : undefined;
-const sortDir = sorting && typeof sorting !== 'string' ? sorting.sortDir : undefined;
+const columnsList = deserializeValue(params.get('columns'), 'array');
+const columns = columnsList ? parseColumnsSettingsStrings(columnsList, defaultColumnsDetails) : undefined;
 
 return {
-sortBy,
-sortDir,
-columns:
-columns &&
-parseColumnsSettingsStrings(
-Array.isArray(columns) ? columns : Object.values(columns || {}),
-defaultColumnsDetails
-),
+sortBy: sorting?.sortBy,
+sortDir: sorting?.sortDir,
+columns,
 };
 };
 
 type mapRouteProps = {
 sortBy: string;
-sortDir: string;
-columns: ColumnsSettings;
+sortDir: SortDirectionType;
+columns: TableColumnsSettings;
 };
 
+/**
+* Builds a deep-link URL for a given table settings state.
+*
+* Note: Optional service helper when you only need to build a link.
+* For reactive state sync, use the `useUrlState` hook instead.
+*
+* @example
+* const url = makeRoute({ sortBy: 'name', sortDir: 'ASCENDING', columns });
+*/
 export const makeRoute = ({ sortBy, sortDir, columns }: mapRouteProps) => {
-// Set props to undefined or null in order to remove it from the URL when not defined
-const params = {
-sort: sortBy && `${getSortDirShort(sortDir)}${sortBy}`,
-columns: columns && mapColumnsSettingsToStrings(columns),
-};
-const queryParams = qs.stringify(params, OPTIONS);
-const searchFragment = queryParams && `?${queryParams}`;
+const params = new URLSearchParams();
+
+if (sortBy) {
+// Use serializeSorting for compact empty / - prefix behavior.
+const serializedSort = serializeSorting({ sortBy, sortDir });
+if (serializedSort) {
+params.set('sort', serializedSort);
+}
+}
+
+const mappedColumns = mapColumnsSettingsToStrings(columns);
+const serializedColumns = serializeValue(mappedColumns, 'array');
+if (serializedColumns) {
+params.set('columns', serializedColumns);
+}
+
+const queryString = params.toString();
+const searchFragment = queryString ? `?${queryString}` : '';
+
 return `${BASE_PATH}/${searchFragment}`;
 };

package/dist/docs/utilities/useAfterMount.md

@@ -2,8 +2,8 @@
 
 *Category:* Utilities
 *Section:* Lifecycle & execution hooks
-*Source:* https://uikit.developers.rio.cloud/#utilities/useAfterMount
-*Captured:* 2026-01-14T09:08:40.804Z
+*Source:* https://uikit.developers.rio.cloud/#/utilities/useAfterMount
+*Captured:* 2026-02-23T13:48:47.599Z
 
 The useAfterMount hook allows to use a side effect after the component has been mounted and rendered. The effect will not be triggered on mount and only when the dependencies change.
 

package/dist/docs/utilities/useAutoAnimate.md

@@ -2,8 +2,8 @@
 
 *Category:* Utilities
 *Section:* DOM behavior hooks
-*Source:* https://uikit.developers.rio.cloud/#utilities/useAutoAnimate
-*Captured:* 2026-01-14T09:08:44.490Z
+*Source:* https://uikit.developers.rio.cloud/#/utilities/useAutoAnimate
+*Captured:* 2026-02-23T13:48:49.836Z
 
 The useAutoAnimate hook is a thin re-export of the @formkit/auto-animate utility to quickly add enter/leave animations to a container. This page shows a simple example; for full configuration options, check the official documentation.
 

package/dist/docs/utilities/useAverage.md

@@ -2,8 +2,8 @@
 
 *Category:* Utilities
 *Section:* Data aggregation hooks
-*Source:* https://uikit.developers.rio.cloud/#utilities/useAverage
-*Captured:* 2026-01-14T09:08:55.831Z
+*Source:* https://uikit.developers.rio.cloud/#/utilities/useAverage
+*Captured:* 2026-02-23T13:49:02.789Z
 
 Calculates the arithmetic mean of numeric values extracted from a list of objects using a dot-separated path. Supports localized number formats through optional locale configuration.
 

package/dist/docs/utilities/useClickOutside.md

@@ -2,8 +2,8 @@
 
 *Category:* Utilities
 *Section:* DOM behavior hooks
-*Source:* https://uikit.developers.rio.cloud/#utilities/useClickOutside
-*Captured:* 2026-01-14T09:08:45.071Z
+*Source:* https://uikit.developers.rio.cloud/#/utilities/useClickOutside
+*Captured:* 2026-02-23T13:48:50.513Z
 
 The useClickOutside hook allows to easily detect events outside a referenced element.
 

package/dist/docs/utilities/useClipboard.md

@@ -2,8 +2,8 @@
 
 *Category:* Utilities
 *Section:* Browser & device hooks
-*Source:* https://uikit.developers.rio.cloud/#utilities/useClipboard
-*Captured:* 2026-01-14T09:08:50.131Z
+*Source:* https://uikit.developers.rio.cloud/#/utilities/useClipboard
+*Captured:* 2026-02-23T13:48:55.827Z
 
 The useClipboard hook allows to easily copy something to the browsers clipboard.
 
@@ -75,7 +75,7 @@ export default () => {
         <span>Random UUID</span>
     </label>
     <div class="input-group">
-        <input id="random-uuid" class="form-control" type="text" value="8e3f7b8e-1a78-4e17-bc38-059ed6370843">
+        <input id="random-uuid" class="form-control" type="text" value="b8885748-6f29-46ff-b3de-a5eb3fe7ece8">
         <div class="input-group-addon">
             <button type="button" class="btn btn-muted btn-sm btn-icon-only btn-component position-absolute top-1 right-1" tabindex="0">
                 <span class="rioglyph rioglyph-duplicate">