@rio-cloud/uikit-mcp 1.1.9 → 1.1.11

package/dist/docs/start/guidelines/state-in-url.md

@@ -3,7 +3,7 @@
 *Category:* Getting started
 *Section:* Guidelines
 *Source:* https://uikit.developers.rio.cloud/#/start/guidelines/state-in-url
-*Captured:* 2026-03-06T10:39:53.019Z
+*Captured:* 2026-04-27T14:57:05.030Z
 
 Every service frontend should support deep linking and reflect meaningful UI state in the URL. This enables restoring state when links are shared, when they are stored as bookmarks, when users navigate with browser history, or when a service is opened from another app.
 
@@ -35,6 +35,20 @@ Before putting something in the URL, ask:
 - UI configuration that affects content (e.g. grouping, expanded views)
 - Feature variants (only if stable and safe to share)
 
+Search queries and filters
+
+Sorting and column visibility (when it changes what users see)
+
+View modes (list/grid/table/map)
+
+Date ranges and time periods
+
+Selected items or active tabs (focus)
+
+UI configuration that affects content (e.g. grouping, expanded views)
+
+Feature variants (only if stable and safe to share)
+
 ## Poor candidates
 
 - Sensitive information (passwords, tokens, PII) - NEVER!
@@ -44,6 +58,18 @@ Before putting something in the URL, ask:
 - Base64 encoded data
 - High-frequency transient state (mouse position, scroll)
 
+Sensitive information (passwords, tokens, PII) - NEVER!
+
+Temporary UI states (e.g. dropdown expanded, tooltip open)
+
+Form input in progress (unsaved changes)
+
+Very large or complex nested data
+
+Base64 encoded data
+
+High-frequency transient state (mouse position, scroll)
+
 ## Example deep links
 
 Prefer readable, self-describing URLs. Use consistent naming across services to make deep links easier to share and reason about.
@@ -70,6 +96,17 @@ Treat the URL as user input. Invalid or unknown params should not break renderin
 
 Use consistent, concise camelCase param names across services whenever possible. If URLs become verbose, prefer a well-known short form (e.g. q, lat / lng) and document it so other teams can align.
 
+| Name | Description |
+| --- | --- |
+| assetIds | Comma-separated list of selected assets (stable IDs). |
+| q | Search query (encode with encodeURIComponent). This short form is common in many search engines. No need to use verbose keys here. |
+| sort | Sort key; use key / -key for direction. Prefer stable keys over display labels. |
+| lat / lng | Latitude / longitude in decimal degrees. Avoid unnecessary precision. |
+| z | Zoom level (integer). |
+| startDate / endDate | Start and end timestamps. Prefer ISO formats and document timezone expectations (recommend UTC). |
+| selectedAssetId / selectedIssue | Focused item in list/detail context. Prefer explicit names over generic placeholders. |
+| viewType | Display mode (table/grid/map). Use a limited set of values. |
+
 ## URLs as contracts
 
 Well-designed URLs are more than a storage place for state. They become a contract between your app and its consumers, setting expectations for humans, developers, and machines.
@@ -131,6 +168,470 @@ onNavigate: (search, mode) => navigate({ search }, { replace: mode === 'replace'
 });
 ```
 
+import
+
+{
+
+,
+
+,
+
+}
+
+from
+
+'react-router-dom'
+
+;
+
+import
+
+from
+
+'@rio-cloud/rio-uikit/useUrlState'
+
+;
+
+import
+
+type
+
+{
+
+}
+
+from
+
+'@rio-cloud/rio-uikit/routeUtils'
+
+;
+
+type
+
+ViewType
+
+=
+
+'list'
+
+|
+
+'grid'
+
+;
+
+type
+
+AppState
+
+=
+
+{
+
+:
+
+string
+
+;
+
+:
+
+;
+
+:
+
+string
+
+[
+
+]
+
+}
+
+;
+
+const
+
+=
+
+{
+
+setQuery
+
+:
+
+(
+
+:
+
+string
+
+)
+
+=>
+
+(
+
+{
+
+:
+
+'setQuery'
+
+as
+
+const
+
+,
+
+:
+
+}
+
+)
+
+,
+
+setViewType
+
+:
+
+(
+
+:
+
+)
+
+=>
+
+(
+
+{
+
+:
+
+'setViewType'
+
+as
+
+const
+
+,
+
+:
+
+}
+
+)
+
+,
+
+setTags
+
+:
+
+(
+
+:
+
+string
+
+[
+
+]
+
+)
+
+=>
+
+(
+
+{
+
+:
+
+'setTags'
+
+as
+
+const
+
+,
+
+:
+
+}
+
+)
+
+,
+
+}
+
+;
+
+const
+
+:
+
+readonly
+
+<
+
+,
+
+unknown
+
+>
+
+[
+
+]
+
+=
+
+[
+
+{
+
+:
+
+'q'
+
+,
+
+selector
+
+:
+
+=>
+
+.
+
+,
+
+:
+
+.
+
+,
+
+:
+
+''
+
+}
+
+,
+
+{
+
+:
+
+'viewType'
+
+,
+
+selector
+
+:
+
+=>
+
+.
+
+,
+
+:
+
+.
+
+,
+
+:
+
+'list'
+
+}
+
+,
+
+{
+
+:
+
+'tags'
+
+,
+
+selector
+
+:
+
+=>
+
+.
+
+,
+
+:
+
+.
+
+,
+
+:
+
+'array'
+
+,
+
+:
+
+[
+
+]
+
+}
+
+,
+
+]
+
+;
+
+const
+
+=
+
+useLocation
+
+(
+
+)
+
+;
+
+const
+
+=
+
+useNavigate
+
+(
+
+)
+
+;
+
+const
+
+=
+
+useNavigationType
+
+(
+
+)
+
+;
+
+useUrlState
+
+(
+
+{
+
+,
+
+:
+
+.
+
+,
+
+:
+
+{
+
+:
+
+.
+
+,
+
+:
+
+.
+
+,
+
+:
+
+.
+
+}
+
+,
+
+,
+
+onUpdateStore
+
+:
+
+=>
+
+dispatch
+
+(
+
+)
+
+,
+
+onNavigate
+
+:
+
+(
+
+,
+
+)
+
+=>
+
+navigate
+
+(
+
+{
+
+}
+
+,
+
+{
+
+:
+
+===
+
+'replace'
+
+}
+
+)
+
+,
+
+}
+
+)
+
+;
+
 > Implementation details: See useUrlState and route utils for details.
 
 ## Best practices
@@ -206,19 +707,387 @@ const onSearchChange = (q: string) => setUrlState({ q }, 'replace'); // typing/s
 const onViewTypeChange = (viewType: ViewType) => setUrlState({ viewType }, 'push'); // meaningful step
 ```
 
-**Redux as source of truth (more complex but recommend for more complex SPAs)**
+import
 
-- Parse the URL once to seed initial Redux state.
-- Subscribe to Redux and update the URL (debounced).
-- Listen for URL changes and dispatch to Redux with guards to avoid loops and no-op updates.
+{
 
-```ts
-import useUrlState from '@rio-cloud/rio-uikit/useUrlState';
-import { useDispatch, useSelector } from 'react-redux';
-import { useLocation, useNavigate, useNavigationType } from 'react-router-dom';
-import type { AppDispatch } from '../../../../setup/store';
+}
 
-// Redux as source of truth (recommended for larger SPAs)
+from
+
+'react'
+
+;
+
+import
+
+{
+
+}
+
+from
+
+'react-router-dom'
+
+;
+
+type
+
+ViewType
+
+=
+
+'list'
+
+|
+
+'grid'
+
+;
+
+// URL as source of truth (simple screens, no centralized store sync)
+
+const
+
+[
+
+,
+
+]
+
+=
+
+useSearchParams
+
+(
+
+)
+
+;
+
+const
+
+=
+
+useMemo
+
+(
+
+(
+
+)
+
+=>
+
+(
+
+{
+
+:
+
+.
+
+get
+
+(
+
+'q'
+
+)
+
+??
+
+''
+
+,
+
+:
+
+(
+
+.
+
+get
+
+(
+
+'viewType'
+
+)
+
+as
+
+)
+
+??
+
+'list'
+
+,
+
+}
+
+)
+
+,
+
+[
+
+]
+
+)
+
+;
+
+const
+
+=
+
+(
+
+:
+
+<
+
+typeof
+
+>
+
+,
+
+:
+
+'push'
+
+|
+
+'replace'
+
+=
+
+'push'
+
+)
+
+=>
+
+{
+
+const
+
+=
+
+new
+
+URLSearchParams
+
+(
+
+)
+
+;
+
+const
+
+=
+
+{
+
+...
+
+,
+
+...
+
+}
+
+;
+
+if
+
+(
+
+.
+
+)
+
+.
+
+set
+
+(
+
+'q'
+
+,
+
+.
+
+)
+
+;
+
+else
+
+.
+
+delete
+
+(
+
+'q'
+
+)
+
+;
+
+if
+
+(
+
+.
+
+===
+
+'list'
+
+)
+
+.
+
+delete
+
+(
+
+'viewType'
+
+)
+
+;
+
+else
+
+.
+
+set
+
+(
+
+'viewType'
+
+,
+
+.
+
+)
+
+;
+
+setSearchParams
+
+(
+
+,
+
+{
+
+:
+
+===
+
+'replace'
+
+}
+
+)
+
+;
+
+}
+
+;
+
+// Typical usage:
+
+const
+
+onSearchChange
+
+=
+
+(
+
+:
+
+string
+
+)
+
+=>
+
+setUrlState
+
+(
+
+{
+
+}
+
+,
+
+'replace'
+
+)
+
+;
+
+// typing/search refinement
+
+const
+
+onViewTypeChange
+
+=
+
+(
+
+:
+
+)
+
+=>
+
+setUrlState
+
+(
+
+{
+
+}
+
+,
+
+'push'
+
+)
+
+;
+
+// meaningful step
+
+**Redux as source of truth (more complex but recommend for more complex SPAs)**
+
+- Parse the URL once to seed initial Redux state.
+- Subscribe to Redux and update the URL (debounced).
+- Listen for URL changes and dispatch to Redux with guards to avoid loops and no-op updates.
+
+```ts
+import useUrlState from '@rio-cloud/rio-uikit/useUrlState';
+import { useDispatch, useSelector } from 'react-redux';
+import { useLocation, useNavigate, useNavigationType } from 'react-router-dom';
+import type { AppDispatch } from '../../../../setup/store';
+
+// Redux as source of truth (recommended for larger SPAs)
 // 1) Parse URL and dispatch updates on URL changes (including browser POP).
 // 2) Observe store values and write URL changes via push/replace rules.
 // 3) Keep this logic centralized in one component near the router.
@@ -245,6 +1114,264 @@ onNavigate: (search, mode) => navigate({ search }, { replace: mode === 'replace'
 });
 ```
 
+import
+
+from
+
+'@rio-cloud/rio-uikit/useUrlState'
+
+;
+
+import
+
+{
+
+,
+
+}
+
+from
+
+'react-redux'
+
+;
+
+import
+
+{
+
+,
+
+,
+
+}
+
+from
+
+'react-router-dom'
+
+;
+
+import
+
+type
+
+{
+
+}
+
+from
+
+'../../../../setup/store'
+
+;
+
+// Redux as source of truth (recommended for larger SPAs)
+
+// 1) Parse URL and dispatch updates on URL changes (including browser POP).
+
+// 2) Observe store values and write URL changes via push/replace rules.
+
+// 3) Keep this logic centralized in one component near the router.
+
+const
+
+=
+
+useDispatch<AppDispatch>
+
+(
+
+)
+
+;
+
+const
+
+=
+
+useLocation
+
+(
+
+)
+
+;
+
+const
+
+=
+
+useNavigate
+
+(
+
+)
+
+;
+
+const
+
+=
+
+useNavigationType
+
+(
+
+)
+
+;
+
+const
+
+=
+
+useSelector
+
+(
+
+=>
+
+(
+
+{
+
+:
+
+getSearchValue
+
+(
+
+)
+
+,
+
+:
+
+{
+
+:
+
+getSortBy
+
+(
+
+)
+
+,
+
+:
+
+getSortDir
+
+(
+
+)
+
+}
+
+,
+
+:
+
+getActivityFilter
+
+(
+
+)
+
+,
+
+}
+
+)
+
+)
+
+;
+
+useUrlState
+
+(
+
+{
+
+:
+
+,
+
+:
+
+.
+
+,
+
+,
+
+:
+
+'service.ui.state'
+
+,
+
+,
+
+onUpdateStore
+
+:
+
+=>
+
+dispatch
+
+(
+
+)
+
+,
+
+onNavigate
+
+:
+
+(
+
+,
+
+)
+
+=>
+
+navigate
+
+(
+
+{
+
+}
+
+,
+
+{
+
+:
+
+===
+
+'replace'
+
+}
+
+)
+
+,
+
+}
+
+)
+
+;
+
 useUrlState supports this second model: centralized store-url synchronization. If you still use template helpers like routeHelper with qs, replace them with a centralized config + useUrlState synchronizer and define per-field history behavior with history: 'push' | 'replace'.
 
 ## Things to consider