@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/dist/docs/utilities/routeUtils.md

@@ -0,0 +1,138 @@
+# Route Utils
+
+*Category:* Utilities
+*Section:* Helper
+*Source:* https://uikit.developers.rio.cloud/#utilities/routeUtils
+*Captured:* 2025-12-12T12:39:34.850Z
+
+Set of utility functions which helps parsing and stringify state into and from the URL.
+
+## 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.
+
+Example: http:/my-url/#demoService/table?sort=+userNickName&columns=itemId,userImageStatus,userNickName:278,userFirstName,userLastName,userActivity,userJobTitle,userEmail,userPhoneNumber
+
+### Example: Example 1
+
+// Note: this sample uses the "qs" library to parse and stringify data
+
+import qs from 'qs';
+import { get } from 'es-toolkit/compat';
+
+import { tableConfig, BASE_PATH } from './yourTableConfig';
+
+import {
+parseColumnsSettingsStrings,
+mapColumnsSettingsToStrings,
+getSortDirShort,
+parseSorting,
+type ColumnsSettings,
+} from '@rio-cloud/rio-uikit/routeUtils';
+
+// Options for the "qs" library
+const OPTIONS = {
+comma: true, // required to parse comma separated string into array
+arrayFormat: 'comma', // 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
+export const parseRoute = (router: any) => {
+const location = get(router, 'location', {}) as Location;
+const searchParams = location.search ? location.search.replace('?', '') : location.search;
+
+const { sort, columns } = qs.parse(searchParams, OPTIONS);
+
+const sorting = sort && parseSorting(sort);
+
+return {
+sortBy: sorting?.sortBy,
+sortDir: sorting?.sortDir,
+columns: columns && parseColumnsSettingsStrings(columns, tableConfig.defaultColumnsDetails),
+};
+};
+
+type mapRouteProps = {
+sortBy: string;
+sortDir: string;
+columns: ColumnsSettings;
+};
+
+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}`;
+return `${BASE_PATH}/${searchFragment}`;
+};
+
+#### Summary
+
+// Note: this sample uses the "qs" library to parse and stringify data
+
+import qs from 'qs';
+import { get } from 'es-toolkit/compat';
+
+import { tableConfig, BASE_PATH } from './yourTableConfig';
+
+import {
+parseColumnsSettingsStrings,
+mapColumnsSettingsToStrings,
+getSortDirShort,
+parseSorting,
+type ColumnsSettings,
+} from '@rio-cloud/rio-uikit/routeUtils';
+
+// Options for the "qs" library
+const OPTIONS = {
+comma: true, // required to parse comma separated string into array
+arrayFormat: 'comma', // 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
+export const parseRoute = (router: any) => {
+const location = get(router, 'location', {}) as Location;
+const searchParams = location.search ? location.search.replace('?', '') : location.search;
+
+const { sort, columns } = qs.parse(searchParams, OPTIONS);
+
+const sorting = sort && parseSorting(sort);
+
+return {
+sortBy: sorting?.sortBy,
+sortDir: sorting?.sortDir,
+columns: columns && parseColumnsSettingsStrings(columns, tableConfig.defaultColumnsDetails),
+};
+};
+
+type mapRouteProps = {
+sortBy: string;
+sortDir: string;
+columns: ColumnsSettings;
+};
+
+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}`;
+return `${BASE_PATH}/${searchFragment}`;
+};

package/dist/docs/utilities/useAfterMount.md

@@ -0,0 +1,66 @@
+# useAfterMount
+
+*Category:* Utilities
+*Section:* Lifecycle & execution hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useAfterMount
+*Captured:* 2025-12-12T12:39:36.322Z
+
+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.
+
+## useAfterMount
+
+### Example: Example 1
+
+Count: 0
+Increment
+
+#### Summary
+
+Count: 0
+Increment
+
+#### React (tsx)
+
+```tsx
+import { useState, useEffect } from 'react';
+
+import Button from '@rio-cloud/rio-uikit/Button';
+import useAfterMount from '@rio-cloud/rio-uikit/useAfterMount';
+
+export default () => {
+    const [count, setCount] = useState(0);
+
+    // This will run on initial mount and whenever 'count' changes
+    useEffect(() => {
+        console.log('useEffect: Component mounted or count changed:', count);
+    }, [count]);
+
+    // This will run only after the initial mount when 'count' changes
+    useAfterMount(() => {
+        console.log('useAfterMount: Count changed:', count);
+    }, [count]);
+
+    return (
+        <div>
+            <p>Count: {count}</p>
+            <Button onClick={() => setCount(count + 1)}>Increment</Button>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <p>Count: 0</p>
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Increment</button>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| callback | Function | — | The effect callback function to be used after the component has been mounted. |
+| deps | Array | — | The effect dependencies that trigger the effect. |

package/dist/docs/utilities/useAutoAnimate.md

@@ -0,0 +1,193 @@
+# useAutoAnimate
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useAutoAnimate
+*Captured:* 2025-12-12T12:39:38.370Z
+
+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.
+
+## useAutoAnimate
+
+### Example: Ready for pickup
+
+Add shipmentChange layoutDisable animation
+
+Shipment #1001
+Ready for pickup
+
+Shipment #1002
+In transit
+
+Shipment #1003
+Delivered
+
+#### Summary
+
+Add shipmentChange layoutDisable animation
+
+Shipment #1001
+Ready for pickup
+
+Shipment #1002
+In transit
+
+Shipment #1003
+Delivered
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import Avatar from '@rio-cloud/rio-uikit/Avatar';
+import Button from '@rio-cloud/rio-uikit/Button';
+import ButtonToolbar from '@rio-cloud/rio-uikit/ButtonToolbar';
+import useAutoAnimate from '@rio-cloud/rio-uikit/useAutoAnimate';
+import useToggle from '@rio-cloud/rio-uikit/useToggle';
+
+export default () => {
+    const { isToggled: isVertical, toggle: toggleLayout } = useToggle();
+
+    const [shipments, setShipments] = useState([
+        { id: 1001, title: 'Shipment #1001', status: 'Ready for pickup', icon: 'rioglyph-cube' },
+        { id: 1002, title: 'Shipment #1002', status: 'In transit', icon: 'rioglyph-delivery' },
+        { id: 1003, title: 'Shipment #1003', status: 'Delivered', icon: 'rioglyph-handshake' },
+    ]);
+
+    const [parent, enableAnimations] = useAutoAnimate();
+
+    const addShipment = () => {
+        const nextId = shipments.length ? Math.max(...shipments.map(shipment => shipment.id)) + 1 : 1001;
+        setShipments([
+            ...shipments,
+            {
+                id: nextId,
+                title: `Shipment #${nextId}`,
+                status: 'Created (awaiting carrier)',
+                icon: 'rioglyph-cube-dashed',
+            },
+        ]);
+    };
+
+    const removeShipment = (id: number) => {
+        setShipments(shipments.filter(shipment => shipment.id !== id));
+    };
+
+    return (
+        <>
+            <ButtonToolbar>
+                <Button onClick={addShipment}>Add shipment</Button>
+                <Button onClick={toggleLayout}>Change layout</Button>
+                <Button onClick={() => enableAnimations(false)}>Disable animation</Button>
+            </ButtonToolbar>
+            <div
+                ref={parent}
+                className={`margin-top-15 max-width-300- display-flex flex-wrap gap-10 ${isVertical ? 'flex-row' : 'flex-column'}`}
+            >
+                {shipments.map(shipment => (
+                    <div
+                        key={shipment.id}
+                        className='width-300 height-70 bg-white shadow-subtle display-flex gap-10 align-items-center justify-content-between border rounded padding-x-10 padding-y-15'
+                    >
+                        <div>
+                            <Avatar
+                                className='text-color-darker text-size-16 bg-lightest scale-90'
+                                iconName={`rioglyph ${shipment.icon}`}
+                            />
+                        </div>
+                        <div className='flex-1-1'>
+                            <div className='text-medium'>{shipment.title}</div>
+                            <div className='text-color-dark'>{shipment.status}</div>
+                        </div>
+                        <Button
+                            bsSize='xs'
+                            bsStyle='muted'
+                            iconOnly
+                            iconName='rioglyph-remove'
+                            onClick={() => removeShipment(shipment.id)}
+                        />
+                    </div>
+                ))}
+            </div>
+        </>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="btn-toolbar">
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Add shipment</button>
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Change layout</button>
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Disable animation</button>
+</div>
+<div class="margin-top-15 max-width-300- display-flex flex-wrap gap-10 flex-column" style="position: relative;">
+    <div class="width-300 height-70 bg-white shadow-subtle display-flex gap-10 align-items-center justify-content-between border rounded padding-x-10 padding-y-15">
+        <div>
+            <div class="Avatar bg-lighter text-color-darker text-size-16 bg-lightest scale-90" style="height: 40px;">
+                <span class="Avatar-icon rioglyph rioglyph-rioglyph rioglyph-cube ">
+                </span>
+            </div>
+        </div>
+        <div class="flex-1-1">
+            <div class="text-medium">Shipment #1001</div>
+            <div class="text-color-dark">Ready for pickup</div>
+        </div>
+        <button type="button" class="btn btn-muted btn-xs btn-icon-only btn-component" tabindex="0">
+            <span class="rioglyph rioglyph-remove">
+            </span>
+        </button>
+    </div>
+    <div class="width-300 height-70 bg-white shadow-subtle display-flex gap-10 align-items-center justify-content-between border rounded padding-x-10 padding-y-15">
+        <div>
+            <div class="Avatar bg-lighter text-color-darker text-size-16 bg-lightest scale-90" style="height: 40px;">
+                <span class="Avatar-icon rioglyph rioglyph-rioglyph rioglyph-delivery ">
+                </span>
+            </div>
+        </div>
+        <div class="flex-1-1">
+            <div class="text-medium">Shipment #1002</div>
+            <div class="text-color-dark">In transit</div>
+        </div>
+        <button type="button" class="btn btn-muted btn-xs btn-icon-only btn-component" tabindex="0">
+            <span class="rioglyph rioglyph-remove">
+            </span>
+        </button>
+    </div>
+    <div class="width-300 height-70 bg-white shadow-subtle display-flex gap-10 align-items-center justify-content-between border rounded padding-x-10 padding-y-15">
+        <div>
+            <div class="Avatar bg-lighter text-color-darker text-size-16 bg-lightest scale-90" style="height: 40px;">
+                <span class="Avatar-icon rioglyph rioglyph-rioglyph rioglyph-handshake ">
+                </span>
+            </div>
+        </div>
+        <div class="flex-1-1">
+            <div class="text-medium">Shipment #1003</div>
+            <div class="text-color-dark">Delivered</div>
+        </div>
+        <button type="button" class="btn btn-muted btn-xs btn-icon-only btn-component" tabindex="0">
+            <span class="rioglyph rioglyph-remove">
+            </span>
+        </button>
+    </div>
+</div>
+```
+
+#### Props: Parameters
+
+### Parameters
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | AutoAnimateOptions (optional) | — | Forwarded to @formkit/auto-animate to configure duration, easing, animations, etc. |
+
+#### Props: Returns
+
+### Returns
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| parent | RefCallback<HTMLElement> | — | Attach to the container whose children should animate. |
+| enableAnimations | (enabled?: boolean) => void | — | Toggle animations on or off; pass false to disable temporarily. |

package/dist/docs/utilities/useAverage.md

@@ -0,0 +1,95 @@
+# useAverage
+
+*Category:* Utilities
+*Section:* Data aggregation hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useAverage
+*Captured:* 2025-12-12T12:39:48.194Z
+
+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.
+
+## useAverage
+
+### Example: Example 1
+
+Average weight deliveries 1: 982,69 kg
+Average weight deliveries 2: 982,69 kg
+
+#### Summary
+
+Average weight deliveries 1: 982,69 kg
+Average weight deliveries 2: 982,69 kg
+
+#### React (tsx)
+
+```tsx
+import { IntlProvider, FormattedNumber } from 'react-intl';
+
+import useAverage from '@rio-cloud/rio-uikit/useAverage';
+
+const deliveries1 = [
+    { shipment: { weight: '1.200,5 kg' } },
+    { shipment: { weight: '980,25 kg' } },
+    { shipment: { weight: '750 kg' } },
+    { shipment: { weight: '1.000 kg' } },
+];
+
+const deliveries2 = [
+    { shipment: { weight: 1200.5 } },
+    { shipment: { weight: 980.25 } },
+    { shipment: { weight: 750 } },
+    { shipment: { weight: 1_000 } },
+];
+
+export default () => {
+    const averageWeight1 = useAverage(deliveries1, 'shipment.weight', {
+        locale: 'de-DE',
+    });
+
+    const averageWeight2 = useAverage(deliveries2, 'shipment.weight');
+
+    return (
+        <IntlProvider locale='de-DE'>
+            <div>
+                Average weight deliveries 1:{' '}
+                <b>
+                    <FormattedNumber value={averageWeight1} style='unit' unit='kilogram' maximumFractionDigits={2} />
+                </b>
+            </div>
+            <div>
+                Average weight deliveries 2:{' '}
+                <b>
+                    <FormattedNumber value={averageWeight2} style='unit' unit='kilogram' maximumFractionDigits={2} />
+                </b>
+            </div>
+        </IntlProvider>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>Average weight deliveries 1: <b>982,69 kg</b>
+</div>
+<div>Average weight deliveries 2: <b>982,69 kg</b>
+</div>
+```
+
+#### Props: Options for the `useAverage` hook
+
+### Options for the `useAverage` hook
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | unknown[] | — | The array of objects to extract numeric values from. |
+| path | string | — | Dot-separated path to the numeric value inside each object. |
+| options | object | — | Optional configuration for number parsing. |
+| └locale | string | "en-GB" | Locale string used for parsing localized number formats. Affects grouping and decimal separator interpretation. |
+
+#### Props: Return value of the `useAverage` hook
+
+### Return value of the `useAverage` hook
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | number | — | The average of all valid numeric values found at the given path in the item list. |

package/dist/docs/utilities/useClickOutside.md

@@ -0,0 +1,61 @@
+# useClickOutside
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useClickOutside
+*Captured:* 2025-12-12T12:39:39.138Z
+
+The useClickOutside hook allows to easily detect events outside a referenced element.
+
+## useClickOutside
+
+### Example: Example 1
+
+Click outside the box
+
+#### Summary
+
+Click outside the box
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import useClickOutside from '@rio-cloud/rio-uikit/useClickOutside';
+
+export default () => {
+    const [background, setBackground] = useState('bg-highlight');
+
+    const ref = useClickOutside(() => setBackground('bg-light'));
+
+    return (
+        <div className='display-flex flex-column justify-content-center align-items-center height-100'>
+            <label className='margin-bottom-10'>Click outside the box</label>
+            <div
+                ref={ref}
+                className={`width-100 height-100 cursor-pointer rounded ${background}`}
+                onClick={() => setBackground('bg-highlight')}
+            />
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="display-flex flex-column justify-content-center align-items-center height-100">
+    <label class="margin-bottom-10">Click outside the box</label>
+    <div class="width-100 height-100 cursor-pointer rounded bg-light">
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| callback | (event: MouseEvent \| TouchEvent) => void | — | The callback function to be triggered when click or touch events happen outside the referenced element. |
+| eventTypes | keyof DocumentEventMap | ['mousedown', 'touchstart'] | Customize list of events to listen on. |
+| isActive | boolean | true | Flag to only listen for clicks when target element active. This comes in handy for dropdowns where the event can be registered only when the dropdown is open. |

package/dist/docs/utilities/useClipboard.md

@@ -0,0 +1,93 @@
+# useClipboard
+
+*Category:* Utilities
+*Section:* Browser & device hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useClipboard
+*Captured:* 2025-12-12T12:39:43.688Z
+
+The useClipboard hook allows to easily copy something to the browsers clipboard.
+
+## useClipboard
+
+### Example: Example 1
+
+Random UUID
+
+#### Summary
+
+Random UUID
+
+#### React (tsx)
+
+```tsx
+import { useEffect, useState } from 'react';
+
+import useClipboard from '@rio-cloud/rio-uikit/useClipboard';
+import Notification from '@rio-cloud/rio-uikit/Notification';
+import Button from '@rio-cloud/rio-uikit/Button';
+import FormLabel from '@rio-cloud/rio-uikit/FormLabel';
+
+export default () => {
+    const [inputValue, setInputValue] = useState<string>(crypto.randomUUID());
+
+    const clipboard = useClipboard();
+
+    useEffect(() => {
+        clipboard.copied && Notification.default('Text copied to clipboard');
+    }, [clipboard.copied]);
+
+    const handleCopyButtonClick = () => {
+        clipboard.copy(inputValue);
+    };
+
+    return (
+        <div className='form-group max-width-500 margin-auto padding-25'>
+            <FormLabel htmlFor='random-uuid'>Random UUID</FormLabel>
+            <div className='input-group'>
+                <input
+                    id='random-uuid'
+                    className='form-control'
+                    type='text'
+                    value={inputValue}
+                    onChange={event => setInputValue(event.currentTarget.value)}
+                />
+                <div className='input-group-addon'>
+                    <Button
+                        bsStyle='muted'
+                        bsSize='sm'
+                        className='position-absolute top-1 right-1'
+                        onClick={handleCopyButtonClick}
+                        iconName='rioglyph-duplicate'
+                        iconOnly
+                    />
+                </div>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="form-group max-width-500 margin-auto padding-25">
+    <label for="random-uuid" class="display-inline-block">
+        <span>Random UUID</span>
+    </label>
+    <div class="input-group">
+        <input id="random-uuid" class="form-control" type="text" value="ac85dc43-adb9-4276-9145-7d6c80c4c6eb">
+        <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">
+                </span>
+            </button>
+        </div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| options.timeout | Number | 2000 | The copied status timeout duration in milliseconds. |