@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/dist/docs/templates/usage-cards.md

@@ -0,0 +1,227 @@
+# Data usage cards
+
+*Category:* Templates
+*Section:* Content
+*Source:* https://uikit.developers.rio.cloud/#templates/usage-cards
+*Captured:* 2025-12-12T12:39:29.731Z
+
+## Data usage cards
+
+### Example: Example 1
+
+Data used for shipment tracking
+
+The following data may be used to track shipments across carriers and systems:
+Vehicle ID
+Current location
+Shipment status
+Timestamps
+Driver ID
+Route info
+
+Edit shipment settings
+
+Data linked to your company profile
+
+This information may be associated with your identity or company profile:
+Customer ID
+Delivery address
+Shipping docs
+Usage metrics
+Freight costs
+Other data
+
+Edit profile settings
+
+#### Summary
+
+Data used for shipment tracking
+
+The following data may be used to track shipments across carriers and systems:
+Vehicle ID
+Current location
+Shipment status
+Timestamps
+Driver ID
+Route info
+
+Edit shipment settings
+
+Data linked to your company profile
+
+This information may be associated with your identity or company profile:
+Customer ID
+Delivery address
+Shipping docs
+Usage metrics
+Freight costs
+Other data
+
+Edit profile settings
+
+#### React (tsx)
+
+```tsx
+import Button from '@rio-cloud/rio-uikit/Button';
+
+export default () => {
+    return (
+        <div className='max-width-600 margin-auto'>
+            <div className='display-grid gap-20 grid-cols-1 grid-cols-2-md'>
+                <div className='bg-white rounded border padding-20 display-flex flex-column justify-content-between'>
+                    <div className='display-flex flex-column gap-5 justify-content-center text-color-darker margin-bottom-25'>
+                        <span className='rioglyph rioglyph-delivery text-size-h2' />
+                        <div className='text-size-18 text-bold text-center'>Data used for shipment tracking</div>
+                    </div>
+                    <div>
+                        <div className='text-color-darker text-center margin-bottom-15'>
+                            The following data may be used to track shipments across carriers and systems:
+                        </div>
+                        <div className='display-grid grid-cols-2 gap-10 text-size-14 text-color-darker'>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-truck' /> Vehicle ID
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-map-marker' /> Current location
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-archive' /> Shipment status
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-time' /> Timestamps
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-user' /> Driver ID
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-route' /> Route info
+                            </div>
+                        </div>
+                        <Button className='margin-top-25' variant='link' block>
+                            Edit shipment settings
+                        </Button>
+                    </div>
+                </div>
+
+                <div className='bg-white rounded border padding-20 display-flex flex-column justify-content-between'>
+                    <div className='display-flex flex-column gap-5 justify-content-center text-color-darker margin-bottom-25'>
+                        <span className='rioglyph rioglyph-user-sign text-size-h2' />
+                        <div className='text-size-18 text-bold text-center'>Data linked to your company profile</div>
+                    </div>
+                    <div>
+                        <div className='text-color-darker text-center margin-bottom-15'>
+                            This information may be associated with your identity or company profile:
+                        </div>
+                        <div className='display-grid grid-cols-2 gap-10 text-size-14 text-color-darker'>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-user-group' /> Customer ID
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-map' /> Delivery address
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-document' /> Shipping docs
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-stats' /> Usage metrics
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-cost-efficency' /> Freight costs
+                            </div>
+                            <div className='display-flex align-items-center gap-5'>
+                                <span className='rioglyph rioglyph-info-sign' /> Other data
+                            </div>
+                        </div>
+                        <Button className='margin-top-25' variant='link' block>
+                            Edit profile settings
+                        </Button>
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="max-width-600 margin-auto">
+    <div class="display-grid gap-20 grid-cols-1 grid-cols-2-md">
+        <div class="bg-white rounded border padding-20 display-flex flex-column justify-content-between">
+            <div class="display-flex flex-column gap-5 justify-content-center text-color-darker margin-bottom-25">
+                <span class="rioglyph rioglyph-delivery text-size-h2">
+                </span>
+                <div class="text-size-18 text-bold text-center">Data used for shipment tracking</div>
+            </div>
+            <div>
+                <div class="text-color-darker text-center margin-bottom-15">The following data may be used to track shipments across carriers and systems:</div>
+                <div class="display-grid grid-cols-2 gap-10 text-size-14 text-color-darker">
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-truck">
+                        </span> Vehicle ID
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-map-marker">
+                        </span> Current location
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-archive">
+                        </span> Shipment status
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-time">
+                        </span> Timestamps
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-user">
+                        </span> Driver ID
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-route">
+                        </span> Route info
+                    </div>
+                </div>
+                <button type="button" class="btn btn-default btn-link btn-block btn-component margin-top-25" tabindex="0">Edit shipment settings</button>
+            </div>
+        </div>
+        <div class="bg-white rounded border padding-20 display-flex flex-column justify-content-between">
+            <div class="display-flex flex-column gap-5 justify-content-center text-color-darker margin-bottom-25">
+                <span class="rioglyph rioglyph-user-sign text-size-h2">
+                </span>
+                <div class="text-size-18 text-bold text-center">Data linked to your company profile</div>
+            </div>
+            <div>
+                <div class="text-color-darker text-center margin-bottom-15">This information may be associated with your identity or company profile:</div>
+                <div class="display-grid grid-cols-2 gap-10 text-size-14 text-color-darker">
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-user-group">
+                        </span> Customer ID
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-map">
+                        </span> Delivery address
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-document">
+                        </span> Shipping docs
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-stats">
+                        </span> Usage metrics
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-cost-efficency">
+                        </span> Freight costs
+                    </div>
+                    <div class="display-flex align-items-center gap-5">
+                        <span class="rioglyph rioglyph-info-sign">
+                        </span> Other data
+                    </div>
+                </div>
+                <button type="button" class="btn btn-default btn-link btn-block btn-component margin-top-25" tabindex="0">Edit profile settings</button>
+            </div>
+        </div>
+    </div>
+</div>
+```

package/dist/docs/utilities/deviceUtils.md

@@ -0,0 +1,123 @@
+# Device Utils
+
+*Category:* Utilities
+*Section:* Helper
+*Source:* https://uikit.developers.rio.cloud/#utilities/deviceUtils
+*Captured:* 2025-12-12T12:39:34.926Z
+
+Set of utility functions which helps detecting certain devices or functionality.
+
+## Device Utils
+
+### Example: Example 1
+
+No touch support
+isMobileScreen: false
+isMobile: false
+isDesktop: true
+isRetinaDevice: false
+isMac: true
+Loaded in iFrame: false
+Zoom is: enabled
+Note
+Because Apple does not allow to disable zoom on touch devices, isZoomDisabled has no effect when using iOS.
+
+#### Summary
+
+No touch support
+isMobileScreen: false
+isMobile: false
+isDesktop: true
+isRetinaDevice: false
+isMac: true
+Loaded in iFrame: false
+Zoom is: enabled
+Note
+Because Apple does not allow to disable zoom on touch devices, isZoomDisabled has no effect when using iOS.
+
+#### React (tsx)
+
+```tsx
+import { useEffect, useState } from 'react';
+
+import { Note } from '../../../components/Note';
+
+import {
+    hasTouch,
+    isMobile,
+    isMobileScreen,
+    isDesktop,
+    isRetinaDevice,
+    toggleZoomOnMobile,
+    inIframe,
+    isMac,
+} from '@rio-cloud/rio-uikit/DeviceUtils';
+import useWindowResize from '@rio-cloud/rio-uikit/useWindowResize';
+
+export default () => {
+    const [isZoomDisabled, setIsZoomDisabled] = useState(false);
+    const [isMobileScreenSize, setIsMobileScreenSize] = useState(isMobileScreen());
+
+    useEffect(() => {
+        // Disables the Zoom for the mobile devices.
+        // This is not good for accessibility but makes the webpage
+        // feel more like a native app.
+        toggleZoomOnMobile();
+        setIsZoomDisabled(document.head.querySelector('[name="viewport"]')?.content.includes('user-scalable=0'));
+    }, []);
+
+    useWindowResize(() => setIsMobileScreenSize(isMobileScreen()));
+
+    return (
+        <div>
+            <p>{hasTouch() ? 'Device has touch. Treat it well!' : 'No touch support'}</p>
+            <hr />
+            <p>isMobileScreen: {`${isMobileScreenSize}`}</p>
+            <hr />
+            <p>isMobile: {`${isMobile()}`}</p>
+            <hr />
+            <p>isDesktop: {`${isDesktop()}`}</p>
+            <hr />
+            <p>isRetinaDevice: {`${isRetinaDevice()}`}</p>
+            <hr />
+            <p>isMac: {`${isMac()}`}</p>
+            <hr />
+            <p>Loaded in iFrame: {`${inIframe()}`}</p>
+            <hr />
+            <p>Zoom is: {isZoomDisabled ? 'disabled' : 'enabled'}</p>
+            <Note>
+                Because Apple does not allow to disable zoom on touch devices, <code>isZoomDisabled</code> has no effect
+                when using iOS.
+            </Note>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <p>No touch support</p>
+    <hr>
+    <p>isMobileScreen: false</p>
+    <hr>
+    <p>isMobile: false</p>
+    <hr>
+    <p>isDesktop: true</p>
+    <hr>
+    <p>isRetinaDevice: false</p>
+    <hr>
+    <p>isMac: true</p>
+    <hr>
+    <p>Loaded in iFrame: false</p>
+    <hr>
+    <p>Zoom is: enabled</p>
+    <div class="display-flex gap-10 max-width-1000 margin-bottom-10 last-child-margin-bottom-0" data-capture-callout="true">
+        <div>
+            <span class="label label-info label-condensed label-filled">Note</span>
+        </div>
+        <div class="width-100pct children-first-margin-top-0 children-last-margin-bottom-0 padding-top-1">Because Apple does not allow to disable zoom on touch devices, <code>isZoomDisabled</code> has no effect when using iOS.</div>
+    </div>
+</div>
+```

package/dist/docs/utilities/featureToggles.md

@@ -0,0 +1,90 @@
+# URL feature toggles
+
+*Category:* Utilities
+*Section:* Helper
+*Source:* https://uikit.developers.rio.cloud/#utilities/featureToggles
+*Captured:* 2025-12-12T12:39:35.555Z
+
+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.
+
+## URL feature toggles
+
+## Feature toggles detection
+
+The feature toggle detection system in your application is designed to handle the dynamic activation and retrieval of feature toggles from two primary sources:
+
+- 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
+
+## 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.
+
+**Type transformers**
+
+- asBoolean and asBooleanWithDefault: Interprets the parameter as a boolean (e.g., true, false, 1, 0)
+- asString and asStringWithDefault: Treats the parameter as a string
+- asNumber and asNumberWithDefault: Converts the parameter into a number
+
+The detectFeatureToggles function first checks if the specified toggle exists in the URL by extracting and parsing the query string (i.e., everything after the ? in the URL). If the parameter is found, its value is transformed using the appropriate type transformer (boolean, string, number), saved in localStorage, and returned.
+
+```typescript
+import { detectFeatureToggles, asString, asBoolean, asNumber } from '@rio-cloud/rio-uikit/urlFeatureToggles';
+
+// Define old toggles to clean up
+const oldToggles = ['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 featureToggles = detectFeatureToggles(
+{
+enforcedLocale: asString('ft_enforceLocale'),
+tracing: asBoolean('ft_tracing'),
+demo: asBooleanWithDefault('ft_demo', false),
+maxItems: asNumberWithDefault('ft_maxItems', 10),
+},
+oldToggles
+);
+```
+
+**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.
+
+**Customizable prefix**
+
+Feature toggles are stored in localStorage with a predefined prefix (default: featureToggle.), which can be customized as needed. This prefix helps to avoid naming collisions with other items stored in localStorage and makes it clear which items are related to feature toggles.
+
+```typescript
+export const featureToggles = detectFeatureToggles(
+{ demo: asBoolean('ft_demo') },
+oldToggles,
+'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.
+
+- URL: http://example.com/#?ft_demo=true&ft_enforceLocale=de-DE
+- Expected behavior: The system detects the ft_demo parameter and interprets it as true (boolean) The ft_enforceLocale is stored as a string ("de-DE") If a value like ft_maxItems is not provided in the URL, the system will try to fetch it from localStorage
+
+- The system detects the ft_demo parameter and interprets it as true (boolean)
+- The ft_enforceLocale is stored as a string ("de-DE")
+- If a value like ft_maxItems is not provided in the URL, the system will try to fetch it from localStorage
+
+To use a feature toggle, simply reference it in your code
+
+```typescript
+if (featureToggles.demo) {
+// 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

package/dist/docs/utilities/fuelTypeUtils.md

@@ -0,0 +1,186 @@
+# Fuel type utils
+
+*Category:* Utilities
+*Section:* Helper
+*Source:* https://uikit.developers.rio.cloud/#utilities/fuelTypeUtils
+*Captured:* 2025-12-12T12:39:35.305Z
+
+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.
+
+## Fuel type utils
+
+In this mapping, multiple values may point to the same icon when they represent equivalent or very similar fuel types. This guarantees that the UI remains consistent across the application and that users always see the correct symbol, regardless of the data source.
+
+## getFuelIcon
+
+The getFuelIcon function offers a single, reliable way to retrieve the correct icon:
+
+- It accepts any known fuel type value.
+- It returns the corresponding Rioglyph icon.
+- Unknown or unsupported values automatically fall back to the unknown icon, preventing broken or missing visuals.
+
+This approach ensures that developers don’t need to decide individually which icon to use. Instead, all mappings are maintained in one place, making the system easier to understand, maintain, and extend. Adding new fuel types or adjusting existing mappings can be done centrally without requiring changes throughout the codebase.
+
+## Fuel type utils
+
+These utilities help group, filter, and render fuel types based on predefined semantic categories such as liquid, gas, electric, hydrogen, or hybrid.
+
+- you need to filter items by fuel type group,
+- show fuel group filter buttons with icons and counters,
+- or render the appropriate icon for a specific fuel type or group.
+
+**Overview**
+
+- fuelTypeGroupIcons Maps each fuel type group to its representative icon (e.g. for use in UI filter buttons or legends).
+- fuelTypeGroups List of all defined fuel type groups (excluding unknown). Useful to iterate over filterable groups.
+- getFuelTypeGroupIcon(fuelTypeGroup) Returns the icon associated with a given fuel group.
+- filterByFuelTypeGroup(items, groups, getFuelType) Filters a list of items by their fuel group, using a custom fuel type extractor function.
+- countFuelTypeGroups(items, getFuelType) Counts how many items belong to each fuel group, useful for showing badge counters on group filter buttons.
+
+### Example: Example 1
+
+Single rioglyph fuel iconThis is a diesel truck
+This is a gasoline truck
+This is an electric bus
+
+Paired rioglyph fuel icon
+
+Unknown paired fuel icon
+
+#### Summary
+
+Single rioglyph fuel iconThis is a diesel truck
+This is a gasoline truck
+This is an electric bus
+
+Paired rioglyph fuel icon
+
+Unknown paired fuel icon
+
+#### React (tsx)
+
+```tsx
+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>
+            </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)
+
+```html
+<div class="display-flex flex-column gap-15">
+    <div>
+        <label>Single rioglyph fuel icon</label>
+        <div class="display-flex gap-5 align-items-center text-size-20">This is a diesel truck <span class="rioglyph rioglyph-fuel-liquid">
+            </span>
+        </div>
+        <div class="display-flex gap-5 align-items-center text-size-20">This is a gasoline truck <span class="rioglyph rioglyph-fuel-liquid">
+            </span>
+        </div>
+        <div class="display-flex gap-5 align-items-center text-size-20">This is an electric bus <span class="rioglyph rioglyph-fuel-electric">
+            </span>
+        </div>
+    </div>
+    <div>
+        <label>Paired rioglyph fuel icon</label>
+        <div class="display-flex gap-10">
+            <span class="rioglyph-icon-pair text-size-h1">
+                <span class="rioglyph rioglyph-truck">
+                </span>
+                <span class="rioglyph rioglyph-fuel-liquid">
+                </span>
+            </span>
+            <span class="rioglyph-icon-pair text-size-h1">
+                <span class="rioglyph rioglyph-truck">
+                </span>
+                <span class="rioglyph rioglyph-fuel-liquid">
+                </span>
+            </span>
+            <span class="rioglyph-icon-pair text-size-h1">
+                <span class="rioglyph rioglyph-bus">
+                </span>
+                <span class="rioglyph rioglyph-fuel-electric">
+                </span>
+            </span>
+        </div>
+    </div>
+    <div>
+        <label>Unknown paired fuel icon</label>
+        <div class="display-flex gap-10">
+            <span class="rioglyph-icon-pair text-size-h1">
+                <span class="rioglyph rioglyph-truck">
+                </span>
+                <span class="rioglyph rioglyph-question">
+                </span>
+            </span>
+        </div>
+    </div>
+</div>
+```
+
+#### Props: getFuelIcon
+
+### getFuelIcon
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| fuelType | FuelType | unknown | The specific fuel type of the item. This will be resolved to a fuel group icon. Supported values include: gas, diesel, electric, hydrogen, cng, and more. |
+
+#### Props: getFuelTypeGroupIcon
+
+### getFuelTypeGroupIcon
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| fuelTypeGroup | FuelTypeGroup | — | The fuel group identifier used to resolve the corresponding icon. |
+
+#### Props: filterByFuelTypeGroup
+
+### filterByFuelTypeGroup
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | T[] | — | The list of items to filter by fuel type group. |
+| activeGroups | FuelTypeGroup[] | — | Array of selected fuel groups to include in the filtered result. |
+| getFuelType | (item: T) => FuelType \| undefined | — | Function used to extract the fuel type from each item. |
+
+#### Props: countFuelTypeGroups
+
+### countFuelTypeGroups
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | T[] | — | The list of items to count by fuel group. |
+| getFuelType | (item: T) => FuelType \| undefined | — | Function used to extract the fuel type from each item. |