@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/dist/docs/utilities/useIsFocusWithin.md

@@ -0,0 +1,114 @@
+# useIsFocusWithin
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useIsFocusWithin
+*Captured:* 2025-12-12T12:39:40.989Z
+
+The useIsFocusWithin hook allows you to detect whether the focus is currently within a specific element or any of its children. This is useful for managing focus-based behavior like showing or hiding UI elements, styling active areas, or triggering accessibility behavior.
+
+## useIsFocusWithin
+
+It provides a boolean flag isFocusedWithin and a ref you can attach to any container. Optionally, you can provide callbacks for when focus enters or leaves the container, and configure a delay for blur detection.
+
+### Example: Example 1
+
+Click inside or outside
+Simple input 1
+
+Simple input 2
+
+Focus is outside the block
+
+#### Summary
+
+Click inside or outside
+Simple input 1
+
+Simple input 2
+
+Focus is outside the block
+
+#### React (tsx)
+
+```tsx
+import ClearableInput from '@rio-cloud/rio-uikit/ClearableInput';
+import FormLabel from '@rio-cloud/rio-uikit/FormLabel';
+import useIsFocusWithin from '@rio-cloud/rio-uikit/useIsFocusWithin';
+
+export default () => {
+    const { ref, isFocusedWithin } = useIsFocusWithin<HTMLDivElement>({
+        onFocusWithin: () => console.log('Entered component'),
+        onBlurWithin: () => console.log('Left component'),
+        delay: 100, // optional
+    });
+
+    return (
+        <div>
+            <div
+                ref={ref}
+                className={`max-width-400 padding-20 border ${isFocusedWithin ? 'border-color-primary' : 'border-color-lighter'} rounded bg-lightest`}
+            >
+                <div className='text-medium text-size-16 text-color-darker margin-bottom-15'>
+                    Click inside or outside
+                </div>
+                <div>
+                    <FormLabel htmlFor='simpleInput1'>Simple input 1</FormLabel>
+                    <ClearableInput id='simpleInput1' />
+                </div>
+                <div>
+                    <FormLabel htmlFor='simpleInput2'>Simple input 2</FormLabel>
+                    <ClearableInput id='simpleInput2' />
+                </div>
+            </div>
+            <div className='margin-top-15 text-size-16 text-italic text-color-darker'>
+                {isFocusedWithin ? 'Focus is within the block' : 'Focus is outside the block'}
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <div class="max-width-400 padding-20 border border-color-lighter rounded bg-lightest">
+        <div class="text-medium text-size-16 text-color-darker margin-bottom-15">Click inside or outside</div>
+        <div>
+            <label for="simpleInput1" class="display-inline-block">
+                <span>Simple input 1</span>
+            </label>
+            <div class="ClearableInput input-group">
+                <input id="simpleInput1" class="form-control" type="text" tabindex="0" value="">
+                <span class="clearButton hide">
+                    <span class="clearButtonIcon rioglyph rioglyph-remove-sign">
+                    </span>
+                </span>
+            </div>
+        </div>
+        <div>
+            <label for="simpleInput2" class="display-inline-block">
+                <span>Simple input 2</span>
+            </label>
+            <div class="ClearableInput input-group">
+                <input id="simpleInput2" class="form-control" type="text" tabindex="0" value="">
+                <span class="clearButton hide">
+                    <span class="clearButtonIcon rioglyph rioglyph-remove-sign">
+                    </span>
+                </span>
+            </div>
+        </div>
+    </div>
+    <div class="margin-top-15 text-size-16 text-italic text-color-darker">Focus is outside the block</div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ref | React.RefObject<HTMLElement> | — | Optional ref to an existing DOM element. If not provided, the hook will return its own ref. |
+| onFocusWithin | Function | — | Callback triggered when focus enters the target element or any of its children. |
+| onBlurWithin | Function | — | Callback triggered when focus leaves the target element and all of its children. |
+| delay | number | — | Optional delay in milliseconds before calling onBlurWithin. Useful when focus quickly shifts inside the container. |

package/dist/docs/utilities/useKey.md

@@ -0,0 +1,151 @@
+# useKey
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useKey
+*Captured:* 2025-12-12T12:39:41.372Z
+
+The useKey hook allows to easily detect key events. It can be used in two ways, either to specify a specific key to listen for or with a callback to listen for all keys.
+
+## useKey
+
+### Example: Example 1
+
+Key
+
+pressed
+
+Key
+
+pressed
+
+Key
+
+pressed
+
+#### Summary
+
+Key
+
+pressed
+
+Key
+
+pressed
+
+Key
+
+pressed
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import useKey from '@rio-cloud/rio-uikit/useKey';
+
+const Usage1 = () => {
+    const [pressedKey, setPressedKey] = useState(' ');
+
+    // Use the useKey hook to listen for any key presses
+    useKey(event => {
+        console.log(event);
+        event.key === ' ' ? setPressedKey(event.code) : setPressedKey(event.key);
+    });
+
+    return (
+        <div className='display-flex justify-content-center align-items-center height-50'>
+            <div className='margin-right-10'>Key</div>
+            <div className='label label-default'>{pressedKey}</div>
+            <div className='margin-left-10'>pressed</div>
+        </div>
+    );
+};
+
+const Usage2 = () => {
+    const [pressedKey, setPressedKey] = useState(' ');
+
+    // Use the useKey hook to listen for any key presses with optional event types
+    useKey(
+        event => {
+            if (event.shiftKey) {
+                setPressedKey(`Shift + ${event.key}`);
+            } else if (event.metaKey) {
+                setPressedKey(`Cmd + ${event.key}`);
+            } else if (event.key === ' ') {
+                setPressedKey(event.code);
+            } else {
+                setPressedKey(event.key);
+            }
+        },
+        ['keyup'] // Listens for the 'keyup' event
+    );
+
+    return (
+        <div className='display-flex justify-content-center align-items-center height-50'>
+            <div className='margin-right-10'>Key</div>
+            <div className='label label-default'>{pressedKey}</div>
+            <div className='margin-left-10'>pressed</div>
+        </div>
+    );
+};
+
+const Usage3 = () => {
+    const [pressedKey, setPressedKey] = useState(' ');
+
+    // Use the useKey hook to listen for the Enter key press
+    useKey('Enter', event => {
+        console.log('Enter key pressed');
+        setPressedKey('Enter');
+    });
+
+    return (
+        <div className='display-flex justify-content-center align-items-center height-50'>
+            <div className='margin-right-10'>Key</div>
+            <div className='label label-default'>{pressedKey}</div>
+            <div className='margin-left-10'>pressed</div>
+        </div>
+    );
+};
+
+export default () => {
+    return (
+        <div className='display-flex flex-column justify-content-center align-items-center'>
+            <Usage1 />
+            <Usage2 />
+            <Usage3 />
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="display-flex flex-column justify-content-center align-items-center">
+    <div class="display-flex justify-content-center align-items-center height-50">
+        <div class="margin-right-10">Key</div>
+        <div class="label label-default"> </div>
+        <div class="margin-left-10">pressed</div>
+    </div>
+    <div class="display-flex justify-content-center align-items-center height-50">
+        <div class="margin-right-10">Key</div>
+        <div class="label label-default"> </div>
+        <div class="margin-left-10">pressed</div>
+    </div>
+    <div class="display-flex justify-content-center align-items-center height-50">
+        <div class="margin-right-10">Key</div>
+        <div class="label label-default"> </div>
+        <div class="margin-left-10">pressed</div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| keyOrCallback | string \| ((event: KeyboardEvent) => void) | — | Either a key string (e.g., "Enter") or a callback function |
+| callbackOrEventTypes | (event: KeyboardEvent) => void \| KeyboardEventType[] | — | If the first argument is a key, this should be the callback function. If the first argument is a callback, this is an optional array of event types. |
+| eventTypesOrNode | KeyboardEventType[] \| Document | [keydown] | If the first argument is a key, this should be an array of event types. If the first argument is a callback, this is the node (defaults to document). |
+| node | Node | document | Optional DOM node to attach the event listener to (defaults to document). |

package/dist/docs/utilities/useLocalStorage.md

@@ -0,0 +1,91 @@
+# useLocalStorage / useSessionStorage
+
+*Category:* Utilities
+*Section:* Browser & device hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useLocalStorage
+*Captured:* 2025-12-12T12:39:44.986Z
+
+The useLocalStorage and the useSessionStorage hook allows to save custom data in the respective storage locations.
+
+## useLocalStorage / useSessionStorage
+
+### Example: Example 1
+
+Tom - 26
+{
+"enableBuyOption": true
+}
+
+Set NameSet AgeRemove NameRemove AgeToggle Settings
+
+#### Summary
+
+Tom - 26
+{
+"enableBuyOption": true
+}
+
+Set NameSet AgeRemove NameRemove AgeToggle Settings
+
+#### React (tsx)
+
+```tsx
+import Button from '@rio-cloud/rio-uikit/Button';
+import useLocalStorage from '@rio-cloud/rio-uikit/useLocalStorage';
+import useSessionStorage from '@rio-cloud/rio-uikit/useSessionStorage';
+
+export default () => {
+    const [name, setName, removeName] = useSessionStorage('name', 'Tom');
+
+    const [age, setAge, removeAge] = useLocalStorage('age', 26);
+    const [settings, setSettings] = useLocalStorage('uikit.demo.settings', { enableBuyOption: true });
+
+    return (
+        <div>
+            <div className='margin-bottom-15'>
+                <div>
+                    {name} - {age}
+                </div>
+                <div>{JSON.stringify(settings, null, 1)}</div>
+            </div>
+            <div className='btn-toolbar'>
+                <Button onClick={() => setName('John')}>Set Name</Button>
+                <Button onClick={() => setAge(40)}>Set Age</Button>
+                <Button onClick={removeName}>Remove Name</Button>
+                <Button onClick={removeAge}>Remove Age</Button>
+                <Button onClick={() => setSettings({ ...settings, enableBuyOption: !settings?.enableBuyOption })}>
+                    Toggle Settings
+                </Button>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <div class="margin-bottom-15">
+        <div>Tom - 26</div>
+        <div>{
+            "enableBuyOption": true
+            }</div>
+    </div>
+    <div class="btn-toolbar">
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Set Name</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Set Age</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Remove Name</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Remove Age</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Toggle Settings</button>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| key | string | — | The key used for storing and retrieving values from the storage. |
+| defaultValue | any | — | The initial default value to be stored. If passed a function, it gets executed. |
+| [value, setValue, removeValue] | [any, Function, Function] | — | Returns the stored value and two functions for setting and removing the value from the storage. |

package/dist/docs/utilities/useLocationSuggestions.md

@@ -0,0 +1,114 @@
+# useLocationSuggestions
+
+*Category:* Utilities
+*Section:* UI state & input hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useLocationSuggestions
+*Captured:* 2025-12-12T12:39:47.391Z
+
+The useLocationSuggestions 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.
+
+## useLocationSuggestions
+
+### Example: Example 1
+
+Here map location search
+
+#### Summary
+
+Here map location search
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import { UIKIT_DEMO_CREDENTIALS_ARE_NOT_ALLOWED_IN_PROD_ENVIRONMENT } from '../../components/map/uikit_demo_credentials';
+import AutoSuggest, { type AutoSuggestSuggestion } from '@rio-cloud/rio-uikit/AutoSuggest';
+import FormLabel from '@rio-cloud/rio-uikit/FormLabel';
+import useLocationSuggestions from '@rio-cloud/rio-uikit/useLocationSuggestions';
+
+export default () => {
+    const [searchValue, setSearchValue] = useState('');
+
+    const { suggestions, loading, error } = useLocationSuggestions(searchValue, {
+        apiKey: UIKIT_DEMO_CREDENTIALS_ARE_NOT_ALLOWED_IN_PROD_ENVIRONMENT.apikey,
+        limit: 20, // optional, but has to be between 5...20
+        lang: 'de-DE', // optional
+        // ... Add any additional options dynamically. See API documentation - https://www.here.com/docs/bundle/geocoding-and-search-api-v7-api-reference/page/index.html#/paths/~1autocomplete/get
+    });
+
+    const handleSuggestionsFetchRequested = (result: { value: string }) => {
+        setSearchValue(result.value);
+    };
+
+    const renderSuggestion = (suggestion: AutoSuggestSuggestion) => <span>{suggestion.label}</span>;
+
+    const inputProps = {
+        icon: 'rioglyph rioglyph-search',
+        placeholder: 'Search for location',
+        value: searchValue,
+    };
+
+    return (
+        <div className='max-width-600'>
+            <FormLabel htmlFor='locationAutosuggest'>Here map location search</FormLabel>
+            <AutoSuggest
+                id='locationAutosuggest'
+                inputProps={inputProps}
+                suggestions={suggestions}
+                onSuggestionsFetchRequested={handleSuggestionsFetchRequested}
+                renderSuggestion={renderSuggestion}
+                isLoading={loading}
+                openOnFocus={false}
+            />
+            {error && <div>{error.message}</div>}
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="max-width-600">
+    <label for="locationAutosuggest" class="display-inline-block">
+        <span>Here map location search</span>
+    </label>
+    <div class="AutoSuggest dropdown">
+        <div class="input-group width-100pct">
+            <span class="input-group-addon">
+                <span class="rioglyph rioglyph rioglyph-search" aria-hidden="true">
+                </span>
+            </span>
+            <div class="ClearableInput input-group">
+                <input id="locationAutosuggest" placeholder="Search for location" class="form-control" autocomplete="off" type="text" tabindex="0" value="">
+                <span class="clearButton hide">
+                    <span class="clearButtonIcon rioglyph rioglyph-remove-sign">
+                    </span>
+                </span>
+            </div>
+        </div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| query | string | — | The user input string to search for location suggestions. |
+| options | object | — | Optional configuration for the hook. |
+| └apiKey | string | — | Your HERE Maps API key. Defaults to "YOUR_API_KEY" if not provided. |
+| └fetchUrl | string | — | Optional override for the autocomplete endpoint URL. Defaults to HERE Maps API URL. |
+| └limit | number | 5 | Optional value to define the result limit (between 5 and 20). |
+| └...additionalOptions | unknown | — | Pass in any additional option for the fetch API. |
+
+#### Props: Returns
+
+### Returns
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| suggestions | LocationSuggestion[] | — | An array of suggestion objects containing an id and label. |
+| loading | boolean | — | Indicates whether the suggestions are currently being fetched. |
+| error | Error \| null | — | Error object if the fetch fails, otherwise null. |

package/dist/docs/utilities/useMax.md

@@ -0,0 +1,62 @@
+# useMax
+
+*Category:* Utilities
+*Section:* Data aggregation hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useMax
+*Captured:* 2025-12-12T12:39:49.073Z
+
+Returns the largest valid numeric value found at the specified path within a list of objects. Supports localized formats and gracefully skips unparsable values.
+
+## useMax
+
+### Example: Example 1
+
+Longest duration: 1440 min
+
+#### Summary
+
+Longest duration: 1440 min
+
+#### React (tsx)
+
+```tsx
+import useMax from '@rio-cloud/rio-uikit/useMax';
+
+const deliveries = [
+    { shipment: { duration: 90 } }, // in minutes
+    { shipment: { duration: 150 } },
+    { shipment: { duration: 1440 } },
+    { shipment: { duration: 180 } },
+];
+
+export default () => {
+    const maxDuration = useMax(deliveries, 'shipment.duration');
+
+    return <div>Longest duration: {maxDuration} min</div>;
+};
+```
+
+#### HTML (html)
+
+```html
+<div>Longest duration: 1440 min</div>
+```
+
+#### Props: Options for the `useMax` hook
+
+### Options for the `useMax` hook
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | unknown[] | — | The array of objects to evaluate. |
+| 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 `useMax` hook
+
+### Return value of the `useMax` hook
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | number | — | The largest valid numeric value found at the given path, or 0 if none could be parsed. |

package/dist/docs/utilities/useMin.md

@@ -0,0 +1,78 @@
+# useMin
+
+*Category:* Utilities
+*Section:* Data aggregation hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useMin
+*Captured:* 2025-12-12T12:39:49.637Z
+
+Returns the smallest valid numeric value found at the specified path within a list of objects. Handles localized number strings and safely ignores invalid values.
+
+## useMin
+
+### Example: Example 1
+
+Lowest shipment value: 850 €
+
+#### Summary
+
+Lowest shipment value: 850 €
+
+#### React (tsx)
+
+```tsx
+import { FormattedNumber, IntlProvider } from 'react-intl';
+import useMin from '@rio-cloud/rio-uikit/useMin';
+
+const deliveries = [
+    { shipment: { value: '2.345,50 €' } },
+    { shipment: { value: '1.000,75 €' } },
+    { shipment: { value: 850 } },
+    { shipment: { value: '2.000' } },
+];
+
+export default () => {
+    const minValue = useMin(deliveries, 'shipment.value', {
+        locale: 'de-DE',
+    });
+
+    return (
+        <IntlProvider locale='de-DE'>
+            <div>
+                Lowest shipment value:{' '}
+                <FormattedNumber
+                    value={minValue}
+                    style='currency'
+                    currency='EUR'
+                    minimumFractionDigits={0}
+                    maximumFractionDigits={0}
+                />
+            </div>
+        </IntlProvider>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>Lowest shipment value: 850&nbsp;€</div>
+```
+
+#### Props: Options for the `useMin` hook
+
+### Options for the `useMin` hook
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | unknown[] | — | The array of objects to evaluate. |
+| 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 `useMin` hook
+
+### Return value of the `useMin` hook
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | number | — | The smallest valid numeric value found at the given path, or 0 if none could be parsed. |