@rio-cloud/uikit-mcp 1.1.9 → 1.1.10

package/dist/docs/utilities/getTrackingAttributes.md

@@ -0,0 +1,277 @@
+# Google Analytics Utils
+
+*Category:* Utilities
+*Section:* Helper
+*Source:* https://uikit.developers.rio.cloud/#/utilities/getTrackingAttributes
+*Captured:* 2026-04-20T12:55:49.976Z
+
+Utility helpers for Google Analytics integration, including attribute generation and push helpers.
+
+## Google Analytics Utils
+
+Use these helpers to create consistent tracking attributes, push events intowindow.dataLayer, and wrap business logic with tracking in one call.
+
+> Important: getTrackingAttributes is the preferred and required way to add GA tracking attributes to UI elements in this project. AnalyticsAnalysisOverlay only works when elements use thedata-track-ga-event-* attributes.
+
+## Available helpers
+
+## Tracking attributesRecommended
+
+**TRACKING_TRIGGER**
+
+TRACKING_TRIGGER defines the allowed values for trigger ingetTrackingAttributes.
+
+```typescript
+type TRACKING_TRIGGER = 'click' | 'visibility';
+```
+
+Hover is intentionally not part of TRACKING_TRIGGER. If you need to track hover interactions, send the event programmatically with gaPush or executeAndTrackfrom the relevant UI callback.
+
+**TRACKING_ACTIONS and TRACKING_LABELS**
+
+These exports are optional app-level maps that consuming applications can fill with shared action and label values. They are configuration points, not required runtime state.
+
+```typescript
+TRACKING_ACTIONS.dialogClose = 'dialog clicked';
+TRACKING_LABELS.dialogClose = 'Dialog closed via close button';
+```
+
+### Example: getTrackingAttributes()
+
+getTrackingAttributes()
+click visibility Disable value Tracked button {
+"data-track-ga-event-trigger": "click",
+"data-track-ga-event-category": "uikit demo",
+"data-track-ga-event-action": "button click",
+"data-track-ga-event-label": "utility_getTrackingAttributes_demo",
+"data-track-ga-event-value": "1"
+}
+
+#### React (tsx)
+
+```tsx
+import { useMemo, useState } from 'react';
+
+import Button from '@rio-cloud/rio-uikit/Button';
+import { getTrackingAttributes, type TRACKING_TRIGGER } from '@rio-cloud/rio-uikit/googleAnalyticsUtils';
+
+const triggerOptions: TRACKING_TRIGGER[] = ['click', 'visibility'];
+
+const GoogleAnalyticsUtilsExample = () => {
+    const [trigger, setTrigger] = useState<TRACKING_TRIGGER>('click');
+    const [includeValue, setIncludeValue] = useState(true);
+
+    const trackingAttributes = useMemo(
+        () =>
+            getTrackingAttributes({
+                trigger,
+                category: 'uikit demo',
+                action: `button ${trigger}`,
+                label: 'utility_getTrackingAttributes_demo',
+                value: includeValue ? '1' : undefined,
+            }),
+        [includeValue, trigger]
+    );
+
+    return (
+        <div className='bg-white border rounded padding-15'>
+            <h4 className='margin-top-0'>getTrackingAttributes()</h4>
+            <div className='display-flex gap-10 margin-bottom-15'>
+                {triggerOptions.map(option => (
+                    <Button
+                        key={option}
+                        bsSize='xs'
+                        bsStyle='default'
+                        className={option === trigger ? 'active' : ''}
+                        onClick={() => setTrigger(option)}
+                    >
+                        {option}
+                    </Button>
+                ))}
+                <Button bsSize='xs' bsStyle='default' onClick={() => setIncludeValue(previousValue => !previousValue)}>
+                    {includeValue ? 'Disable value' : 'Enable value'}
+                </Button>
+            </div>
+
+            <Button bsStyle='primary' {...trackingAttributes}>
+                Tracked button
+            </Button>
+
+            <pre className='margin-top-15 bg-white border rounded padding-10 text-size-12'>
+                {JSON.stringify(trackingAttributes, null, 2)}
+            </pre>
+        </div>
+    );
+};
+
+export default GoogleAnalyticsUtilsExample;
+```
+
+#### HTML (html)
+
+```html
+<div class="bg-white border rounded padding-15">
+    <h4 class="margin-top-0">getTrackingAttributes()</h4>
+    <div class="display-flex gap-10 margin-bottom-15">
+        <button type="button" class="btn btn-default btn-xs btn-component active" tabindex="0">click</button>
+        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">visibility</button>
+        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">Disable value</button>
+    </div>
+    <button type="button" data-track-ga-event-trigger="click" data-track-ga-event-category="uikit demo" data-track-ga-event-action="button click" data-track-ga-event-label="utility_getTrackingAttributes_demo" data-track-ga-event-value="1" class="btn btn-primary btn-component" tabindex="0">Tracked button</button>
+    <pre class="margin-top-15 bg-white border rounded padding-10 text-size-12">{
+  "data-track-ga-event-trigger": "click",
+  "data-track-ga-event-category": "uikit demo",
+  "data-track-ga-event-action": "button click",
+  "data-track-ga-event-label": "utility_getTrackingAttributes_demo",
+  "data-track-ga-event-value": "1"
+}</pre>
+</div>
+```
+
+## Imperative tracking
+
+### Example: gaPush() and executeAndTrack()
+
+gaPush() and executeAndTrack()
+Use gaPush for direct imperative tracking, including hover interactions. Use executeAndTrack when the event should always be emitted together with a function call.
+click visibility hover Disable value
+Push event with gaPush executeAndTrack counter: 0 Clear dataLayer
+[]
+
+#### React (tsx)
+
+```tsx
+import { useMemo, useState } from 'react';
+
+import Button from '@rio-cloud/rio-uikit/Button';
+import { executeAndTrack, gaPush } from '@rio-cloud/rio-uikit/googleAnalyticsUtils';
+
+type GaPushInteraction = 'click' | 'visibility' | 'hover';
+
+const interactionOptions: GaPushInteraction[] = ['click', 'visibility', 'hover'];
+
+const getDataLayer = () => {
+    if (typeof window === 'undefined') {
+        return [] as unknown[];
+    }
+
+    if (!Array.isArray(window.dataLayer)) {
+        window.dataLayer = [];
+    }
+
+    return window.dataLayer;
+};
+
+const GoogleAnalyticsUtilsGaPushExample = () => {
+    const [interaction, setInteraction] = useState<GaPushInteraction>('click');
+    const [includeValue, setIncludeValue] = useState(true);
+    const [dataLayerSnapshot, setDataLayerSnapshot] = useState<unknown[]>(() => [...getDataLayer()]);
+    const [trackedCounter, setTrackedCounter] = useState(0);
+
+    const refreshDataLayer = () => {
+        setDataLayerSnapshot([...getDataLayer()]);
+    };
+
+    const trackedIncrement = useMemo(
+        () =>
+            executeAndTrack((value: number) => value + 1, {
+                category: 'uikit demo',
+                action: 'button click',
+                label: 'utility_executeAndTrack_demo',
+                value: 1,
+            }),
+        []
+    );
+
+    const handleGaPush = () => {
+        gaPush({
+            category: 'uikit demo',
+            action: `manual ${interaction}`,
+            label: 'utility_gaPush_demo',
+            value: includeValue ? 1 : undefined,
+        });
+
+        refreshDataLayer();
+    };
+
+    const handleExecuteAndTrack = () => {
+        const nextValue = trackedIncrement(trackedCounter);
+        setTrackedCounter(nextValue);
+        refreshDataLayer();
+    };
+
+    const handleClearDataLayer = () => {
+        if (typeof window !== 'undefined') {
+            window.dataLayer = [];
+        }
+
+        refreshDataLayer();
+    };
+
+    return (
+        <div className='bg-white border rounded padding-15'>
+            <h4 className='margin-top-0'>gaPush() and executeAndTrack()</h4>
+            <p className='margin-bottom-15'>
+                Use <code>gaPush</code> for direct imperative tracking, including hover interactions. Use
+                <code>executeAndTrack</code> when the event should always be emitted together with a function call.
+            </p>
+
+            <div className='display-flex gap-10 margin-bottom-15'>
+                {interactionOptions.map(option => (
+                    <Button
+                        key={option}
+                        bsSize='xs'
+                        bsStyle='default'
+                        className={option === interaction ? 'active' : ''}
+                        onClick={() => setInteraction(option)}
+                    >
+                        {option}
+                    </Button>
+                ))}
+                <Button bsSize='xs' bsStyle='default' onClick={() => setIncludeValue(previousValue => !previousValue)}>
+                    {includeValue ? 'Disable value' : 'Enable value'}
+                </Button>
+            </div>
+
+            <div className='display-flex gap-10 margin-bottom-15'>
+                <Button bsStyle='default' onClick={handleGaPush}>
+                    Push event with gaPush
+                </Button>
+                <Button bsStyle='default' onClick={handleExecuteAndTrack}>
+                    executeAndTrack counter: {trackedCounter}
+                </Button>
+                <Button bsStyle='muted' onClick={handleClearDataLayer}>
+                    Clear dataLayer
+                </Button>
+            </div>
+
+            <pre className='bg-white border rounded padding-10 margin-bottom-0 text-size-12'>
+                {JSON.stringify(dataLayerSnapshot, null, 2)}
+            </pre>
+        </div>
+    );
+};
+
+export default GoogleAnalyticsUtilsGaPushExample;
+```
+
+#### HTML (html)
+
+```html
+<div class="bg-white border rounded padding-15">
+    <h4 class="margin-top-0">gaPush() and executeAndTrack()</h4>
+    <p class="margin-bottom-15">Use <code>gaPush</code> for direct imperative tracking, including hover interactions. Use<code>executeAndTrack</code> when the event should always be emitted together with a function call.</p>
+    <div class="display-flex gap-10 margin-bottom-15">
+        <button type="button" class="btn btn-default btn-xs btn-component active" tabindex="0">click</button>
+        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">visibility</button>
+        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">hover</button>
+        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">Disable value</button>
+    </div>
+    <div class="display-flex gap-10 margin-bottom-15">
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Push event with gaPush</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">executeAndTrack counter: 0</button>
+        <button type="button" class="btn btn-muted btn-component" tabindex="0">Clear dataLayer</button>
+    </div>
+    <pre class="bg-white border rounded padding-10 margin-bottom-0 text-size-12">[]</pre>
+</div>
+```

package/dist/docs/utilities/routeUtils.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Helper
 *Source:* https://uikit.developers.rio.cloud/#/utilities/routeUtils
-*Captured:* 2026-03-06T10:41:32.343Z
+*Captured:* 2026-04-20T12:55:48.564Z
 
 Utility helpers for parsing and serializing URL state. These are low-level building blocks for service-specific mapping.
 
@@ -86,7 +86,7 @@ type mapRouteProps = { sortBy : string ; sortDir : SortDirectionType ; columns :
 * For reactive state sync, use the `useUrlState` hook instead.
 *
 * @example
-* const url = makeRoute({ sortBy: 'name', sortDir: 'ASCENDING', columns });
+* const url = makeRoute({ sortBy: 'name', sortDir: 'asc', columns });
 */ export const makeRoute = ( { sortBy , sortDir , columns } : mapRouteProps ) => { 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

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Lifecycle & execution hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useAfterMount
-*Captured:* 2026-03-06T10:41:34.448Z
+*Captured:* 2026-04-20T12:55:50.203Z
 
 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

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useAutoAnimate
-*Captured:* 2026-03-06T10:41:37.681Z
+*Captured:* 2026-04-20T12:55:52.817Z
 
 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

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Data aggregation hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useAverage
-*Captured:* 2026-03-06T10:41:55.332Z
+*Captured:* 2026-04-20T12:56:05.114Z
 
 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

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useClickOutside
-*Captured:* 2026-03-06T10:41:38.063Z
+*Captured:* 2026-04-20T12:55:53.014Z
 
 The useClickOutside hook allows to easily detect events outside a referenced element.
 

package/dist/docs/utilities/useClipboard.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useClipboard
-*Captured:* 2026-03-06T10:41:45.450Z
+*Captured:* 2026-04-20T12:55:58.502Z
 
 The useClipboard hook allows to easily copy something to the browsers clipboard.
 
@@ -71,7 +71,7 @@ export default () => {
         <span>Random UUID</span>
     </label>
     <div class="input-group">
-        <input id="random-uuid" class="form-control" type="text" value="789340f8-0a4f-4b14-a203-8cd08f761b5e">
+        <input id="random-uuid" class="form-control" type="text" value="d002291b-7767-46e3-84f1-1fae4388f99c">
         <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">

package/dist/docs/utilities/useCookies.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useCookies
-*Captured:* 2026-03-06T10:41:47.226Z
+*Captured:* 2026-04-20T12:55:59.614Z
 
 The useCookies hook allows you to set cookies, delete cookies and check whether a cookie exists in the browser.
 

package/dist/docs/utilities/useCount.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Data aggregation hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useCount
-*Captured:* 2026-03-06T10:41:55.383Z
+*Captured:* 2026-04-20T12:56:05.038Z
 
 useCount is a utility hook for counting how many objects in a list contain a specific value or match a custom condition at a given property path. It supports exact value matching (e.g. true, 0, 'PENDING') or predicate-based logic using a match function. By default, all values that are not null or undefined are counted.
 

package/dist/docs/utilities/useDarkMode.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useDarkMode
-*Captured:* 2026-03-06T10:41:47.248Z
+*Captured:* 2026-04-20T12:55:59.717Z
 
 The useDarkMode hook enables you to listen for the color scheme change and react accordingly.
 
@@ -39,7 +39,8 @@ export default () => {
 </div>
 ```
 
-#### Props
+#### Props (json)
 
-| Name | Type | Default | Description |
-| --- | --- | --- | --- |
+```json
+isDarkMode
+```

package/dist/docs/utilities/useDebugInfo.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* UI state & input hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useDebugInfo
-*Captured:* 2026-03-06T10:41:51.188Z
+*Captured:* 2026-04-20T12:56:02.519Z
 
 The useDebugInfo hook allows to return detailed information about render count, render time and changed component props and also to print these information to the console.
 
@@ -18,7 +18,7 @@ Debug Info: {
 "renderCount": 1,
 "changedProps": {},
 "timeSinceLastRender": 0,
-"lastRenderTimestamp": 1772793710502
+"lastRenderTimestamp": 1776689761830
 }
 
 Toggle Increment
@@ -93,7 +93,7 @@ export default () => {
  "renderCount": 1,
  "changedProps": {},
  "timeSinceLastRender": 0,
- "lastRenderTimestamp": 1772793710502
+ "lastRenderTimestamp": 1776689761830
 }</pre>
         </div>
     </div>