@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/dist/docs/utilities/useSorting.md

@@ -0,0 +1,389 @@
+# useSorting
+
+*Category:* Utilities
+*Section:* Table & data hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useSorting
+*Captured:* 2025-12-12T12:39:50.836Z
+
+The useSorting hook provides an easy way to sort any list by a specified key using natural sort order. It offers flexible control over sorting direction and key selection, making it ideal for dynamic sorting use cases.
+
+## useSorting
+
+### Example: Example 1
+
+NameQuantity
+
+Box20
+Container1
+Crate15
+Drum12
+Pallet10
+Parcel8
+
+#### Summary
+
+NameQuantity
+
+Box20
+Container1
+Crate15
+Drum12
+Pallet10
+Parcel8
+
+#### React (tsx)
+
+```tsx
+import SortArrows from '@rio-cloud/rio-uikit/SortArrows';
+import useSorting from '@rio-cloud/rio-uikit/useSorting';
+
+type Item = {
+    name: string;
+    quantity: number;
+};
+
+const items: Item[] = [
+    { name: 'Pallet', quantity: 10 },
+    { name: 'Container', quantity: 1 },
+    { name: 'Crate', quantity: 15 },
+    { name: 'Parcel', quantity: 8 },
+    { name: 'Drum', quantity: 12 },
+    { name: 'Box', quantity: 20 },
+];
+
+export default () => {
+    const { sortedItems, sortKey, sortDirection, setSortKey, toggleDirection } = useSorting(items, 'name');
+
+    const handleSortByColumn = (column: keyof Item) => {
+        setSortKey(column);
+        if (column === sortKey) {
+            toggleDirection();
+        }
+    };
+
+    return (
+        <div className='table-responsive'>
+            <table className='table table-head-filled'>
+                <thead>
+                    <tr>
+                        <th className='user-select-none sort-column' onClick={() => handleSortByColumn('name')}>
+                            <span>
+                                {sortKey === 'name' ? <SortArrows direction={sortDirection} /> : <SortArrows />}
+                                <span>Name</span>
+                            </span>
+                        </th>
+                        <th className='user-select-none sort-column' onClick={() => handleSortByColumn('quantity')}>
+                            <span>
+                                {sortKey === 'quantity' ? <SortArrows direction={sortDirection} /> : <SortArrows />}
+                                <span>Quantity</span>
+                            </span>
+                        </th>
+                    </tr>
+                </thead>
+                <tbody>
+                    {sortedItems.map(({ name, quantity }) => (
+                        <tr key={name}>
+                            <td key={name}>{name}</td>
+                            <td key={quantity}>{quantity}</td>
+                        </tr>
+                    ))}
+                </tbody>
+            </table>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="table-responsive">
+    <table class="table table-head-filled">
+        <thead>
+            <tr>
+                <th class="user-select-none sort-column">
+                    <span>
+                        <span class="sort-arrows sort-asc">
+                        </span>
+                        <span>Name</span>
+                    </span>
+                </th>
+                <th class="user-select-none sort-column">
+                    <span>
+                        <span class="sort-arrows ">
+                        </span>
+                        <span>Quantity</span>
+                    </span>
+                </th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>Box</td>
+                <td>20</td>
+            </tr>
+            <tr>
+                <td>Container</td>
+                <td>1</td>
+            </tr>
+            <tr>
+                <td>Crate</td>
+                <td>15</td>
+            </tr>
+            <tr>
+                <td>Drum</td>
+                <td>12</td>
+            </tr>
+            <tr>
+                <td>Pallet</td>
+                <td>10</td>
+            </tr>
+            <tr>
+                <td>Parcel</td>
+                <td>8</td>
+            </tr>
+        </tbody>
+    </table>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | T[] | — | The array of items to be sorted. |
+| initialKey | SortKey<T> = keyof T \| [keyof T, keyof T] | — | The initial key or keys to sort by. Must be a property of the items in the array. It can be either a single string or a tuple like ['name', 'date'] |
+| initialDirection | SortDirectionType | SortDirection.ASCENDING | The initial sort direction. Can be SortDirection.ASCENDING or SortDirection.DESCENDING. |
+| enableNaturalSort | boolean | true | Whether to use natural sort order. Defaults to false. |
+| { sortedItems, sortKey, sortDirection, setSortKey, setSortDirection, toggleDirection } | Object | — | Returns an object containing: "sortedItems" - the sorted array "sortKey" - the key(s) to sort the data for "sortDirection" - the current direction that the data is sorted "setSortKey" - function to change the sorting key(s) afterwards "setSortDirection" - function to change the sorting order afterwards "toggleDirection" - function to toggle sort direction |
+
+### Example: Example 2
+
+Sort by a primary column. Hold shift key to sort by a secondary column
+CategoryNameQuantity
+
+ShippingParcel8
+ShippingBox20
+ShippingEnvelope50
+ShippingBag30
+StoragePallet10
+StorageContainer1
+StorageCrate15
+StorageDrum12
+
+#### Summary
+
+Sort by a primary column. Hold shift key to sort by a secondary column
+CategoryNameQuantity
+
+ShippingParcel8
+ShippingBox20
+ShippingEnvelope50
+ShippingBag30
+StoragePallet10
+StorageContainer1
+StorageCrate15
+StorageDrum12
+
+#### React (tsx)
+
+```tsx
+import SortArrows from '@rio-cloud/rio-uikit/SortArrows';
+import useSorting from '@rio-cloud/rio-uikit/useSorting';
+
+type Item = {
+    name: string;
+    category: string;
+    quantity: number;
+};
+
+const items: Item[] = [
+    { name: 'Pallet', category: 'Storage', quantity: 10 },
+    { name: 'Container', category: 'Storage', quantity: 1 },
+    { name: 'Crate', category: 'Storage', quantity: 15 },
+    { name: 'Parcel', category: 'Shipping', quantity: 8 },
+    { name: 'Drum', category: 'Storage', quantity: 12 },
+    { name: 'Box', category: 'Shipping', quantity: 20 },
+    { name: 'Envelope', category: 'Shipping', quantity: 50 },
+    { name: 'Bag', category: 'Shipping', quantity: 30 },
+];
+
+export default () => {
+    const { sortedItems, sortKey, sortDirection, setSortKey, toggleDirection } = useSorting(items, 'category');
+
+    const handleSortByColumn = (column: keyof Item, event: React.MouseEvent) => {
+        if (event.shiftKey) {
+            // Secondary sort
+            if (Array.isArray(sortKey) && sortKey[1] === column) {
+                // If already secondary, toggle direction
+                toggleDirection();
+            } else if (Array.isArray(sortKey)) {
+                // If already using secondary sort, update secondary key
+                setSortKey([sortKey[0], column]);
+            } else {
+                // If not using secondary sort, add secondary key
+                setSortKey([sortKey, column]);
+            }
+        } else {
+            // Primary sort
+            if (sortKey === column || (Array.isArray(sortKey) && sortKey[0] === column)) {
+                // If already primary, toggle direction
+                toggleDirection();
+            } else {
+                // Set new primary key
+                setSortKey(column);
+            }
+        }
+    };
+
+    const renderSortArrows = (column: keyof Item) => {
+        if (sortKey === column || (Array.isArray(sortKey) && sortKey[0] === column)) {
+            return <SortArrows direction={sortDirection} />;
+        }
+        if (Array.isArray(sortKey) && sortKey[1] === column) {
+            return <SortArrows direction={sortDirection} />;
+        }
+        return <SortArrows />;
+    };
+
+    return (
+        <>
+            <p>
+                Sort by a primary column. Hold <kbd className='text-normal'>shift</kbd> key to sort by a secondary
+                column
+            </p>
+            <div className='table-responsive'>
+                <table className='table table-head-filled'>
+                    <thead>
+                        <tr>
+                            <th
+                                className='user-select-none sort-column'
+                                onClick={event => handleSortByColumn('category', event)}
+                            >
+                                <span>
+                                    {renderSortArrows('category')}
+                                    <span>Category</span>
+                                </span>
+                            </th>
+                            <th
+                                className='user-select-none sort-column'
+                                onClick={event => handleSortByColumn('name', event)}
+                            >
+                                <span>
+                                    {renderSortArrows('name')}
+                                    <span>Name</span>
+                                </span>
+                            </th>
+                            <th
+                                className='user-select-none sort-column'
+                                onClick={event => handleSortByColumn('quantity', event)}
+                            >
+                                <span>
+                                    {renderSortArrows('quantity')}
+                                    <span>Quantity</span>
+                                </span>
+                            </th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {sortedItems.map(item => (
+                            <tr key={item.name}>
+                                <td>{item.category}</td>
+                                <td>{item.name}</td>
+                                <td>{item.quantity}</td>
+                            </tr>
+                        ))}
+                    </tbody>
+                </table>
+            </div>
+        </>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<p>Sort by a primary column. Hold <kbd class="text-normal">shift</kbd> key to sort by a secondary column</p>
+<div class="table-responsive">
+    <table class="table table-head-filled">
+        <thead>
+            <tr>
+                <th class="user-select-none sort-column">
+                    <span>
+                        <span class="sort-arrows sort-asc">
+                        </span>
+                        <span>Category</span>
+                    </span>
+                </th>
+                <th class="user-select-none sort-column">
+                    <span>
+                        <span class="sort-arrows ">
+                        </span>
+                        <span>Name</span>
+                    </span>
+                </th>
+                <th class="user-select-none sort-column">
+                    <span>
+                        <span class="sort-arrows ">
+                        </span>
+                        <span>Quantity</span>
+                    </span>
+                </th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>Shipping</td>
+                <td>Parcel</td>
+                <td>8</td>
+            </tr>
+            <tr>
+                <td>Shipping</td>
+                <td>Box</td>
+                <td>20</td>
+            </tr>
+            <tr>
+                <td>Shipping</td>
+                <td>Envelope</td>
+                <td>50</td>
+            </tr>
+            <tr>
+                <td>Shipping</td>
+                <td>Bag</td>
+                <td>30</td>
+            </tr>
+            <tr>
+                <td>Storage</td>
+                <td>Pallet</td>
+                <td>10</td>
+            </tr>
+            <tr>
+                <td>Storage</td>
+                <td>Container</td>
+                <td>1</td>
+            </tr>
+            <tr>
+                <td>Storage</td>
+                <td>Crate</td>
+                <td>15</td>
+            </tr>
+            <tr>
+                <td>Storage</td>
+                <td>Drum</td>
+                <td>12</td>
+            </tr>
+        </tbody>
+    </table>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | T[] | — | The array of items to be sorted. |
+| initialKey | SortKey<T> = keyof T \| [keyof T, keyof T] | — | The initial key or keys to sort by. Must be a property of the items in the array. It can be either a single string or a tuple like ['name', 'date'] |
+| initialDirection | SortDirectionType | SortDirection.ASCENDING | The initial sort direction. Can be SortDirection.ASCENDING or SortDirection.DESCENDING. |
+| enableNaturalSort | boolean | true | Whether to use natural sort order. Defaults to false. |
+| { sortedItems, sortKey, sortDirection, setSortKey, setSortDirection, toggleDirection } | Object | — | Returns an object containing: "sortedItems" - the sorted array "sortKey" - the key(s) to sort the data for "sortDirection" - the current direction that the data is sorted "setSortKey" - function to change the sorting key(s) afterwards "setSortDirection" - function to change the sorting order afterwards "toggleDirection" - function to toggle sort direction |

package/dist/docs/utilities/useStateWithValidation.md

@@ -0,0 +1,83 @@
+# useStateWithValidation
+
+*Category:* Utilities
+*Section:* UI state & input hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useStateWithValidation
+*Captured:* 2025-12-12T12:39:47.737Z
+
+The useStateWithValidation hook allows to easily validate state. This comes in handy when validating form inputs.
+
+## useStateWithValidation
+
+### Example: Example 1
+
+Username
+
+#### Summary
+
+Username
+
+#### React (tsx)
+
+```tsx
+import useStateWithValidation from '@rio-cloud/rio-uikit/useStateWithValidation';
+
+export default () => {
+    const validationFn = (name: string) => name.length > 5;
+
+    const [username, setUsername, isValid] = useStateWithValidation<string>(validationFn, '');
+
+    const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+        setUsername(event.target.value);
+    };
+
+    const showError = username.length > 0 && !isValid;
+
+    return (
+        <div className='display-flex flex-column max-width-400'>
+            <div className={`form-group ${showError ? 'has-error has-feedback' : ''}`}>
+                <label htmlFor='inputUsername'>Username</label>
+                <div className='form-control-feedback-wrapper'>
+                    <input
+                        id='inputUsername'
+                        type='text'
+                        className='form-control'
+                        placeholder='Please enter your username'
+                        value={username}
+                        onChange={handleInputChange}
+                    />
+                    {showError && (
+                        <>
+                            <span className='form-control-feedback rioglyph rioglyph-error-sign' />
+                            <span className='help-block'>
+                                <span>Username is to short. Please enter at least 5 characters.</span>
+                            </span>
+                        </>
+                    )}
+                </div>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="display-flex flex-column max-width-400">
+    <div class="form-group ">
+        <label for="inputUsername">Username</label>
+        <div class="form-control-feedback-wrapper">
+            <input id="inputUsername" type="text" class="form-control" placeholder="Please enter your username" value="">
+        </div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| validationFn | Function | — | The validation function that gets invoked when the passed state changes. |
+| initialValue | Any | — | The initial state value. |
+| [state, onChange, isValid] | Array | — | Returns the actual "state", the "onChange" function that will be invoked when the state changes, and the "isValid" flag. |

package/dist/docs/utilities/useSum.md

@@ -0,0 +1,155 @@
+# useSum
+
+*Category:* Utilities
+*Section:* Data aggregation hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useSum
+*Captured:* 2025-12-12T12:39:49.571Z
+
+The useSum hook is a versatile utility for calculating the total of numeric, localized values within a list of objects—particularly useful for rendering totals in table footers, dashboards, or KPIs.
+
+## useSum
+
+It supports locale-aware number parsing (e.g. 1.234,50 € or 2 500,75 kg)
+
+### Example: Example 1
+
+3.930,75 km
+5.197 €
+1860min
+31h
+185 km
+
+#### Summary
+
+3.930,75 km
+5.197 €
+1860min
+31h
+185 km
+
+#### React (tsx)
+
+```tsx
+import { FormattedNumber, IntlProvider } from 'react-intl';
+
+import useSum from '@rio-cloud/rio-uikit/useSum';
+
+export default () => {
+    const weightSum = useSum(deliveries, 'shipment.weight', { locale: 'de-DE' });
+    const valueSum = useSum(deliveries, 'shipment.value', { locale: 'de-DE' });
+
+    const durationSum = useSum(deliveries, 'shipment.duration');
+
+    const mileage = useSum(deliveries, 'vehicle.mileage');
+
+    return (
+        <IntlProvider locale='de-DE'>
+            <ul>
+                <li>
+                    <FormattedNumber
+                        value={weightSum}
+                        minimumFractionDigits={0}
+                        maximumFractionDigits={2}
+                        style='unit'
+                        unit='kilometer'
+                    />
+                </li>
+                <li>
+                    <FormattedNumber
+                        value={valueSum}
+                        style='currency'
+                        currency='EUR'
+                        minimumFractionDigits={0}
+                        maximumFractionDigits={0}
+                    />
+                </li>
+                <li>{durationSum}min</li>
+                <li>
+                    <FormattedNumber value={durationSum / 60} maximumFractionDigits={1} />h
+                </li>
+                <li>
+                    <FormattedNumber value={mileage} maximumFractionDigits={0} style='unit' unit='kilometer' />
+                </li>
+            </ul>
+        </IntlProvider>
+    );
+};
+
+const deliveries = [
+    {
+        id: 'D-1001',
+        vehicle: {
+            mileage: 97.5,
+        },
+        shipment: {
+            weight: '1.200,5 kg',
+            value: '2.345,50 €',
+            duration: 90, // raw minutes
+        },
+    },
+    {
+        id: 'D-1002',
+        vehicle: {
+            mileage: 10,
+        },
+        shipment: {
+            weight: '980,25 kg',
+            value: '1,000.75€',
+            duration: 150, // raw minutes
+        },
+    },
+    {
+        id: 'D-1003',
+        vehicle: {
+            mileage: 56,
+        },
+        shipment: {
+            weight: '750kg',
+            value: 850,
+            duration: 1440, // raw minutes
+        },
+    },
+    {
+        id: 'D-1004',
+        vehicle: {
+            mileage: 21,
+        },
+        shipment: {
+            weight: '1.000 kg',
+            value: '2.000,00 €',
+            duration: 180, // raw minutes
+        },
+    },
+];
+```
+
+#### HTML (html)
+
+```html
+<ul>
+    <li>3.930,75 km</li>
+    <li>5.197&nbsp;€</li>
+    <li>1860min</li>
+    <li>31h</li>
+    <li>185 km</li>
+</ul>
+```
+
+#### Props: Options for the `useSum` hook
+
+### Options for the `useSum` hook
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | unknown[] | — | The array of objects to aggregate values from. |
+| path | string | — | Dot-separated path to the numeric value in each object. |
+| options | object | — | Optional configuration for parsing behavior. |
+| └locale | string | "en-GB" | Locale string used to parse localized number formats. Affects how grouping and decimal separators are interpreted. |
+
+#### Props: Return value of the `useSum` hook
+
+### Return value of the `useSum` hook
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| sum | number | — | The total sum of all parsed values from the provided path in the given item list. |