@rio-cloud/uikit-mcp 1.1.9 → 1.1.11

package/dist/docs/utilities/featureToggles.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Helper
 *Source:* https://uikit.developers.rio.cloud/#/utilities/featureToggles
-*Captured:* 2026-03-06T10:41:33.236Z
+*Captured:* 2026-04-27T14:59:29.244Z
 
 URL-based feature toggles (also known as feature flags) are a powerful development technique that allows you to enable or disable features in your application dynamically, without deploying new code.
 
@@ -16,6 +16,10 @@ The feature toggle detection system in your application is designed to handle th
 - URL Query Parameters Toggles can be passed through the URL as query parameters (e.g., ?ft_demo=true), allowing for easy testing or overriding of features without modifying code
 - LocalStorage If a toggle is not present in the URL, the system falls back to using stored values in the browser's localStorage, ensuring that user preferences or feature states are preserved across sessions
 
+Toggles can be passed through the URL as query parameters (e.g., ?ft_demo=true), allowing for easy testing or overriding of features without modifying code
+
+If a toggle is not present in the URL, the system falls back to using stored values in the browser's localStorage, ensuring that user preferences or feature states are preserved across sessions
+
 ## Defining feature toggles
 
 Feature toggles are defined in a centralized configuration map, with each toggle specifying its corresponding query parameter name, its data type (boolean, string, or number) and an optional default value. This allows you to easily configure new toggles.
@@ -47,6 +51,126 @@ oldToggles
 );
 ```
 
+import
+
+{
+
+,
+
+,
+
+,
+
+}
+
+from
+
+'@rio-cloud/rio-uikit/urlFeatureToggles'
+
+;
+
+// Define old toggles to clean up
+
+const
+
+=
+
+[
+
+'ft_eventTeaser'
+
+,
+
+'ft_survey'
+
+,
+
+'ft_menu'
+
+]
+
+;
+
+// Define toggle transformation functions with their respective names and
+
+// export the detected feature toggles as a singleton
+
+export
+
+const
+
+=
+
+detectFeatureToggles
+
+(
+
+{
+
+:
+
+asString
+
+(
+
+'ft_enforceLocale'
+
+)
+
+,
+
+:
+
+asBoolean
+
+(
+
+'ft_tracing'
+
+)
+
+,
+
+:
+
+asBooleanWithDefault
+
+(
+
+'ft_demo'
+
+,
+
+false
+
+)
+
+,
+
+:
+
+asNumberWithDefault
+
+(
+
+'ft_maxItems'
+
+,
+
+10
+
+)
+
+,
+
+}
+
+,
+
+)
+
+;
+
 **Default values**
 
 For each type of transformer there is a *WithDefault variant. This function accepts a default value as second parameter. The default value is only returned if neither the query parameter nor the local storage contain a value for the feature toggle. A feature toggle with a default value will never be null. This fact is also reflected in the type of the feature toggle properties in the object returned by detectFeatureToggles.
@@ -63,6 +187,40 @@ oldToggles,
 );
 ```
 
+export
+
+const
+
+=
+
+detectFeatureToggles
+
+(
+
+{
+
+:
+
+asBoolean
+
+(
+
+'ft_demo'
+
+)
+
+}
+
+,
+
+,
+
+'myCustomPrefix.'
+
+)
+
+;
+
 ## Usage
 
 Suppose you want to enable or disable a demo mode in your application. You can pass ?ft_demo=true in the URL or rely on the value previously stored in localStorage.
@@ -82,9 +240,31 @@ if (featureToggles.demo) {
 }
 ```
 
+if
+
+(
+
+.
+
+)
+
+{
+
+// Render demo feature
+
+}
+
 ## Benefits
 
 - Flexibility This approach allows toggles to be easily overridden via URL for testing or debugging purposes without changing the codebase
 - Persistence By leveraging localStorage, feature toggles persist across browser sessions, ensuring a consistent experience for users
 - Type safety Type transformation functions (asBoolean, asString, asNumber) ensure that toggles are correctly interpreted based on the expected data type
-- Clean state management Unused toggles can be cleaned up from localStorage, ensuring there is no unnecessary buildup of outdated data
+- Clean state management Unused toggles can be cleaned up from localStorage, ensuring there is no unnecessary buildup of outdated data
+
+This approach allows toggles to be easily overridden via URL for testing or debugging purposes without changing the codebase
+
+By leveraging localStorage, feature toggles persist across browser sessions, ensuring a consistent experience for users
+
+Type transformation functions (asBoolean, asString, asNumber) ensure that toggles are correctly interpreted based on the expected data type
+
+Unused toggles can be cleaned up from localStorage, ensuring there is no unnecessary buildup of outdated data

package/dist/docs/utilities/fuelTypeUtils.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Helper
 *Source:* https://uikit.developers.rio.cloud/#/utilities/fuelTypeUtils
-*Captured:* 2026-03-06T10:41:32.458Z
+*Captured:* 2026-04-27T14:59:28.552Z
 
 There is a wide variety of standardized fuel types, and on top of that, some projects or systems introduce their own custom definitions. While the naming can differ, many of these values carry the same semantic meaning. To avoid confusion and ensure consistent visual representation, we provide a centralized mapping of fuel types to icons.
 
@@ -53,38 +53,36 @@ Unknown paired fuel icon
 import Rioglyph from '@rio-cloud/rio-uikit/Rioglyph';
 import { getFuelIcon } from '@rio-cloud/rio-uikit/fuelTypeUtils';
 
-export default () => {
-    return (
-        <div className='display-flex flex-column gap-15'>
-            <div>
-                <label>Single rioglyph fuel icon</label>
-                <div className='display-flex gap-5 align-items-center text-size-20'>
-                    This is a diesel truck <span className={`rioglyph ${getFuelIcon('diesel')}`} />
-                </div>
-                <div className='display-flex gap-5 align-items-center text-size-20'>
-                    This is a gasoline truck <span className={`rioglyph ${getFuelIcon('gas')}`} />
-                </div>
-                <div className='display-flex gap-5 align-items-center text-size-20'>
-                    This is an electric bus <span className={`rioglyph ${getFuelIcon('electric')}`} />
-                </div>
+export default () => (
+    <div className='display-flex flex-column gap-15'>
+        <div>
+            <label>Single rioglyph fuel icon</label>
+            <div className='display-flex gap-5 align-items-center text-size-20'>
+                This is a diesel truck <span className={`rioglyph ${getFuelIcon('diesel')}`} />
             </div>
-            <div>
-                <label>Paired rioglyph fuel icon</label>
-                <div className='display-flex gap-10'>
-                    <Rioglyph size='h1' icon={'rioglyph-truck'} pairIcon={getFuelIcon('diesel')} />
-                    <Rioglyph size='h1' icon={'rioglyph-truck'} pairIcon={getFuelIcon('gas')} />
-                    <Rioglyph size='h1' icon={'rioglyph-bus'} pairIcon={getFuelIcon('electric')} />
-                </div>
+            <div className='display-flex gap-5 align-items-center text-size-20'>
+                This is a gasoline truck <span className={`rioglyph ${getFuelIcon('gas')}`} />
             </div>
-            <div>
-                <label>Unknown paired fuel icon</label>
-                <div className='display-flex gap-10'>
-                    <Rioglyph size='h1' icon={'rioglyph-truck'} pairIcon={getFuelIcon('whatever')} />
-                </div>
+            <div className='display-flex gap-5 align-items-center text-size-20'>
+                This is an electric bus <span className={`rioglyph ${getFuelIcon('electric')}`} />
             </div>
         </div>
-    );
-};
+        <div>
+            <label>Paired rioglyph fuel icon</label>
+            <div className='display-flex gap-10'>
+                <Rioglyph size='h1' icon={'rioglyph-truck'} pairIcon={getFuelIcon('diesel')} />
+                <Rioglyph size='h1' icon={'rioglyph-truck'} pairIcon={getFuelIcon('gas')} />
+                <Rioglyph size='h1' icon={'rioglyph-bus'} pairIcon={getFuelIcon('electric')} />
+            </div>
+        </div>
+        <div>
+            <label>Unknown paired fuel icon</label>
+            <div className='display-flex gap-10'>
+                <Rioglyph size='h1' icon={'rioglyph-truck'} pairIcon={getFuelIcon('whatever')} />
+            </div>
+        </div>
+    </div>
+);
 ```
 
 #### HTML (html)

package/dist/docs/utilities/getTrackingAttributes.md

@@ -0,0 +1,322 @@
+# Google Analytics Utils
+
+*Category:* Utilities
+*Section:* Helper
+*Source:* https://uikit.developers.rio.cloud/#/utilities/getTrackingAttributes
+*Captured:* 2026-04-27T14:59:29.682Z
+
+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
+
+NameExampleDescriptiongetTrackingAttributes(...)getTrackingAttributes({ trigger: 'click', category: 'demo' })Creates the data-track-ga-event-* attributes for declarative tracking on DOM elements. This is the preferred approach for UI elements.gaPush(...)gaPush({ category: 'demo', action: 'click', label: 'cta' })Pushes an event into window.dataLayer programmatically. Use this when tracking should happen from imperative code, including hover interactions.executeAndTrack(...)executeAndTrack(myFn, { category: 'demo', action: 'run', label: 'myFn' })Wraps a function so it still runs normally and also sends a GA event afterward. Useful when you want tracking and business logic wired together in one call.
+
+## Tracking attributesRecommended
+
+Tracking attributes
+
+> Recommended
+
+**TRACKING_TRIGGER**
+
+TRACKING_TRIGGER defines the allowed values for trigger ingetTrackingAttributes.
+
+```typescript
+type TRACKING_TRIGGER = 'click' | 'visibility';
+```
+
+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.
+
+| Trigger | Use for |
+| --- | --- |
+| click | User actively clicks an element (buttons, links, controls). |
+| visibility | Element becomes visible in the viewport. |
+
+**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';
+```
+
+TRACKING_ACTIONS
+
+.
+
+=
+
+'dialog clicked'
+
+;
+
+TRACKING_LABELS
+
+.
+
+=
+
+'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>
+```