@rio-cloud/uikit-mcp 1.0.1 → 1.1.1

package/dist/docs/utilities/useFocusTrap.md

@@ -0,0 +1,85 @@
+# useFocusTrap
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useFocusTrap
+*Captured:* 2025-12-12T14:21:44.774Z
+
+This custom hook allows to keep the focus inside a defined wrapper element. This might be a dialog or a custom overlay.
+
+## useFocusTrap
+
+- When you have a external component that will be re-rendered after the overlay opens, you can use the built-in ref. This ref will be returned from this hook and can be set on the respective wrapper element.
+- When you have an element that does not re-render, use a local state setter function to be set as the ref. This element can then be passed as a parameter to this hook and it will be used instead of the built-in ref.const [focusTrapRef, setFocusTrapRef] = useState<HTMLDivElement | null>(null); useFocusTrap(focusTrapRef); <div ref={setFocusTrapRef}>...</div>
+
+### Example: Example 1
+
+Open Dialog
+
+#### Summary
+
+Open Dialog
+
+#### React (tsx)
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+
+import Dialog from '@rio-cloud/rio-uikit/Dialog';
+import Button from '@rio-cloud/rio-uikit/Button';
+import useFocusTrap from '@rio-cloud/rio-uikit/useFocusTrap';
+
+const DemoBody = () => {
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const focusTrapRef = useFocusTrap();
+
+    useEffect(() => {
+        if (inputRef.current) {
+            inputRef.current.focus();
+        }
+    }, [inputRef.current]);
+
+    return (
+        <div ref={focusTrapRef} className='form-group display-flex gap-10'>
+            <input ref={inputRef} className='form-control' />
+            <div className='btn-toolbar flex-nowrap'>
+                <Button>Button 1</Button>
+                <Button>Button 2</Button>
+            </div>
+        </div>
+    );
+};
+
+export default () => {
+    const [showDialog, setShowDialog] = useState(false);
+
+    return (
+        <div>
+            <Dialog
+                show={showDialog}
+                onClose={() => setShowDialog(false)}
+                title='Demo Focus Trap'
+                showCloseButton
+                bsSize='sm'
+                body={<DemoBody />}
+            />
+            <Button onClick={() => setShowDialog(true)}>Open Dialog</Button>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Open Dialog</button>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| element | HTMLDivElement \| null | — | The wrapper element that traps the focus. Use this if your component does not rerender, otherwise use the internal ref that gets returned from the hook. |

package/dist/docs/utilities/useFullscreen.md

@@ -0,0 +1,198 @@
+# useFullscreen
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useFullscreen
+*Captured:* 2025-12-12T14:21:46.293Z
+
+The cross-browser useFullscreen hook allows to easily switch to fullscreen mode for the document or a dedicated element like a map or a certain part of a service.
+
+## useFullscreen
+
+**Fullscreen on dedicated element**
+
+### Example: Example 1
+
+Fullscreen enabled: false
+Is Fullscreen active: false
+Request Fullscreen
+Exit Fullscreen
+Toggle Fullscreen
+
+#### Summary
+
+Fullscreen enabled: false
+Is Fullscreen active: false
+Request Fullscreen
+Exit Fullscreen
+Toggle Fullscreen
+
+#### React (tsx)
+
+```tsx
+import useFullscreen from '@rio-cloud/rio-uikit/useFullscreen';
+
+export default () => {
+    const handleChange = (event: Event) => console.log(event);
+    const handleError = (event: Event) => console.log(event);
+
+    const { exitFullscreen, isEnabled, isFullscreen, requestFullscreen, toggleFullscreen } = useFullscreen({
+        onChange: handleChange,
+        onError: handleError,
+    });
+
+    return (
+        <div>
+            <div>
+                Fullscreen enabled: <span>{`${isEnabled}`}</span>
+            </div>
+            <hr />
+            <div>
+                Is Fullscreen active: <span>{`${isFullscreen}`}</span>
+            </div>
+            <hr />
+            <div className='btn-toolbar'>
+                <div className='btn btn-default' onClick={requestFullscreen}>
+                    Request Fullscreen
+                </div>
+                <div className='btn btn-default' onClick={exitFullscreen}>
+                    Exit Fullscreen
+                </div>
+                <div className='btn btn-default' onClick={toggleFullscreen}>
+                    Toggle Fullscreen
+                </div>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <div>Fullscreen enabled: <span>false</span>
+    </div>
+    <hr>
+    <div>Is Fullscreen active: <span>false</span>
+    </div>
+    <hr>
+    <div class="btn-toolbar">
+        <div class="btn btn-default">Request Fullscreen</div>
+        <div class="btn btn-default">Exit Fullscreen</div>
+        <div class="btn btn-default">Toggle Fullscreen</div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| element | HTMLElement | — | The target element other than document. Note, the element need to be existing in the DOM when initializing the hook. Otherwise pass the element as argument to the "requestFullscreen" function. |
+| onChange | (callback: OnChangeEventCallback) => void | () => {} | Custom callback function for acting on the fullscreen change. |
+| onError | (callback: EventCallback) => void | () => {} | Custom callback function for acting on an error when the fullscreen fails. |
+| requestFullscreenOptions | { navigationUI?: string \| "auto" \| "hide" \| "show" } | {} | Define additional options for requesting the fullscreen. |
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| requestFullscreen | (targetElement: HTMLElement) => void | — | This function requests the fullscreen to the browser. It takes an optional argument to define the target element later than on init. |
+| exitFullscreen | Function | — | This function exits the fullscreen. |
+| toggleFullscreen | Function | — | This function requests or exists the fullscreen depending on the fullscreen state. |
+| isFullscreen | Boolean | — | Defines whether the browser is in fullscreen mode. Note, the can only be on element in fullscreen at a time, either the document or a dedicated element. |
+| isEnabled | Boolean | — | Tells you if the browser allows the fullscreen mode. |
+
+### Example: Example 2
+
+Example - click on expand icon to use fullscreen
+
+Sample content.
+Here you can have arbitrary content like a map or charts etc.
+
+#### Summary
+
+Example - click on expand icon to use fullscreen
+
+Sample content.
+Here you can have arbitrary content like a map or charts etc.
+
+#### React (tsx)
+
+```tsx
+import { useRef } from 'react';
+
+import useFullscreen from '@rio-cloud/rio-uikit/useFullscreen';
+
+import { dummyTextLong } from '../../../utils/data';
+
+export default () => {
+    const wrapperRef = useRef<HTMLDivElement>(null);
+
+    const { toggleFullscreen, isFullscreen } = useFullscreen();
+
+    return (
+        <div className='example-wrapper bg-lighter display-grid' ref={wrapperRef}>
+            <div className={`panel panel-default shadow-default ${isFullscreen ? 'margin-25' : ''}`}>
+                <div className='panel-heading display-flex justify-content-between align-items-center'>
+                    <div className='text-medium text-color-darker'>
+                        Example - click on expand icon to use fullscreen
+                    </div>
+                    <div
+                        className='text-color-gray text-size-16 cursor-pointer'
+                        onClick={() => toggleFullscreen(wrapperRef.current)}
+                    >
+                        <span className='rioglyph rioglyph-fullscreen' />
+                    </div>
+                </div>
+                <div className='panel-body'>
+                    <p>
+                        Sample content. <br />
+                        Here you can have arbitrary content like a map or charts etc.
+                    </p>
+                    {isFullscreen && <p>{dummyTextLong}</p>}
+                </div>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="example-wrapper bg-lighter display-grid">
+    <div class="panel panel-default shadow-default ">
+        <div class="panel-heading display-flex justify-content-between align-items-center">
+            <div class="text-medium text-color-darker">Example - click on expand icon to use fullscreen</div>
+            <div class="text-color-gray text-size-16 cursor-pointer">
+                <span class="rioglyph rioglyph-fullscreen">
+                </span>
+            </div>
+        </div>
+        <div class="panel-body">
+            <p>Sample content. <br>Here you can have arbitrary content like a map or charts etc.</p>
+        </div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| element | HTMLElement | — | The target element other than document. Note, the element need to be existing in the DOM when initializing the hook. Otherwise pass the element as argument to the "requestFullscreen" function. |
+| onChange | (callback: OnChangeEventCallback) => void | () => {} | Custom callback function for acting on the fullscreen change. |
+| onError | (callback: EventCallback) => void | () => {} | Custom callback function for acting on an error when the fullscreen fails. |
+| requestFullscreenOptions | { navigationUI?: string \| "auto" \| "hide" \| "show" } | {} | Define additional options for requesting the fullscreen. |
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| requestFullscreen | (targetElement: HTMLElement) => void | — | This function requests the fullscreen to the browser. It takes an optional argument to define the target element later than on init. |
+| exitFullscreen | Function | — | This function exits the fullscreen. |
+| toggleFullscreen | Function | — | This function requests or exists the fullscreen depending on the fullscreen state. |
+| isFullscreen | Boolean | — | Defines whether the browser is in fullscreen mode. Note, the can only be on element in fullscreen at a time, either the document or a dedicated element. |
+| isEnabled | Boolean | — | Tells you if the browser allows the fullscreen mode. |

package/dist/docs/utilities/useHover.md

@@ -0,0 +1,55 @@
+# useHover
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useHover
+*Captured:* 2025-12-12T14:21:45.911Z
+
+## useHover
+
+### Example: Example 1
+
+Lorem ipsum dolor sit amet
+
+#### Summary
+
+Lorem ipsum dolor sit amet
+
+#### React (tsx)
+
+```tsx
+/* eslint-disable max-len */
+import { useRef } from 'react';
+
+import useHover from '@rio-cloud/rio-uikit/useHover';
+
+export default () => {
+    const ref = useRef<HTMLInputElement>(null);
+
+    const isHover = useHover(ref);
+
+    return (
+        <div
+            ref={ref}
+            className='well display-flex gap-10 align-items-center border hover-border-color-primary max-width-300 cursor-pointer'
+        >
+            <span className='text-color-darker text-size-16 text-medium'>Lorem ipsum dolor sit amet</span>
+            {isHover && <span className='rioglyph rioglyph-antenna text-size-20 text-color-primary' />}
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="well display-flex gap-10 align-items-center border hover-border-color-primary max-width-300 cursor-pointer">
+    <span class="text-color-darker text-size-16 text-medium">Lorem ipsum dolor sit amet</span>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ref | React.Ref | — | The reference to the element that shall be hovered. |

package/dist/docs/utilities/useIncomingPostMessages.md

@@ -0,0 +1,237 @@
+# useIncomingPostMessages
+
+*Category:* Utilities
+*Section:* Browser & device hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useIncomingPostMessages
+*Captured:* 2025-12-12T14:21:49.672Z
+
+For handling postMessage events in React components.
+
+## useIncomingPostMessages
+
+You can either handle "vanilla" events yourself or declaratively listen to "action-style" events. The latter are inspired by Redux actions, as the event data is an object with a type property and an optional payload.
+
+The payload does not have to be a simple string, but can be a complex object, as well.
+
+### Example: Example 1
+
+Send raw message ("hello, world")Send action: EVENT_WIDGET_READYSend action: EVENT_WIDGET_DATA
+Note that in this simple example, we're not really sending messages across windows. The origin-filtering handlers are in place, though. You can experiment by opening this page in an iframe inside a page with a different origin and try sending the same events as in the example code.
+Simple events
+Shows every incoming postMessage as-is (no origin filter or type parsing). Useful for quick debugging of any messages your page receives.
+
+Simple events with origin filter
+Same raw view, but driven by the origin+handler object form (instead of a single callback) and only for messages whose origin matches this page.
+
+Action events
+Only shows action-style messages (objects with a `type` field) and extracts their payload. Handy when you control the sender and use message types to route logic.
+
+Action events with origin filter
+Action messages constrained by origin. Use this to route typed messages while still protecting against unexpected origins.
+
+#### Summary
+
+Send raw message ("hello, world")Send action: EVENT_WIDGET_READYSend action: EVENT_WIDGET_DATA
+Note that in this simple example, we're not really sending messages across windows. The origin-filtering handlers are in place, though. You can experiment by opening this page in an iframe inside a page with a different origin and try sending the same events as in the example code.
+Simple events
+Shows every incoming postMessage as-is (no origin filter or type parsing). Useful for quick debugging of any messages your page receives.
+
+Simple events with origin filter
+Same raw view, but driven by the origin+handler object form (instead of a single callback) and only for messages whose origin matches this page.
+
+Action events
+Only shows action-style messages (objects with a `type` field) and extracts their payload. Handy when you control the sender and use message types to route logic.
+
+Action events with origin filter
+Action messages constrained by origin. Use this to route typed messages while still protecting against unexpected origins.
+
+#### React (tsx)
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+
+import ButtonToolbar from '@rio-cloud/rio-uikit/ButtonToolbar';
+import Button from '@rio-cloud/rio-uikit/components/button/Button';
+import useIncomingPostMessages from '@rio-cloud/rio-uikit/hooks/useIncomingPostMessages';
+
+export default () => {
+    const [simpleEvents, setSimpleEvents] = useState<string[]>([]);
+    const [filteredSimpleEvents, setFilteredSimpleEvents] = useState<string[]>([]);
+    const [actionEvents, setActionEvents] = useState<string[]>([]);
+    const [filteredActionEvents, setFilteredActionEvents] = useState<string[]>([]);
+
+    useIncomingPostMessages(event => {
+        // We're getting ALL kinds of events here, so we need to implement appropriate filters ourselves!
+        if (isReactDevtoolsEvent(event)) {
+            return;
+        }
+
+        setSimpleEvents([...simpleEvents, JSON.stringify(event.data)]);
+    });
+
+    useIncomingPostMessages({
+        // this will ignore all events not coming from a declared origin - in this simple example, we're just using the current page's origin itself
+        origin: window.origin,
+        handler: event => {
+            // We're getting ALL kinds of events here, so we need to implement appropriate filters ourselves!
+            if (isReactDevtoolsEvent(event)) {
+                return;
+            }
+
+            setFilteredSimpleEvents([...filteredSimpleEvents, JSON.stringify(event.data)]);
+        },
+    });
+
+    useIncomingPostMessages({
+        handlers: {
+            EVENT_WIDGET_READY: (payload: string) => {
+                setActionEvents([...actionEvents, payload]);
+            },
+            EVENT_WIDGET_DATA: (payload: unknown) => {
+                const message = typeof payload === 'string' ? payload : JSON.stringify(payload);
+                setActionEvents([...actionEvents, message]);
+            },
+        },
+    });
+
+    useIncomingPostMessages({
+        // this will ignore all events not coming from a declared origin - in this simple example, we're just using the current page's origin itself
+        origin: window.origin,
+        handlers: {
+            EVENT_WIDGET_READY: (payload: string) => {
+                setFilteredActionEvents([...filteredActionEvents, payload]);
+            },
+            EVENT_WIDGET_DATA: (payload: unknown) => {
+                const message = typeof payload === 'string' ? payload : JSON.stringify(payload);
+                setFilteredActionEvents([...filteredActionEvents, message]);
+            },
+        },
+    });
+
+    const sendSimpleEvent = () => {
+        window.postMessage('hello, world');
+    };
+
+    const sendActionEvent = (type: 'EVENT_WIDGET_READY' | 'EVENT_WIDGET_DATA') => {
+        const payload =
+            type === 'EVENT_WIDGET_READY'
+                ? 'Widget is ready to receive data'
+                : {
+                      widgetId: 'demo-widget',
+                      user: 'Jane Doe',
+                      shipment: { orderId: 'ORD-1001', status: 'ready', etaDays: 2 },
+                  };
+        window.postMessage({ type, payload });
+    };
+
+    return (
+        <>
+            <ButtonToolbar>
+                <Button onClick={() => sendSimpleEvent()}>Send raw message ("hello, world")</Button>
+                <Button onClick={() => sendActionEvent('EVENT_WIDGET_READY')}>Send action: EVENT_WIDGET_READY</Button>
+                <Button onClick={() => sendActionEvent('EVENT_WIDGET_DATA')}>Send action: EVENT_WIDGET_DATA</Button>
+            </ButtonToolbar>
+
+            <p>
+                Note that in this simple example, we're not really sending messages across windows. The origin-filtering
+                handlers are in place, though. You can experiment by opening this page in an iframe inside a page with a
+                different origin and try sending the same events as in the example code.
+            </p>
+
+            <div className='display-grid grid-cols-1 grid-cols-2-md margin-y-20 gap-25'>
+                <div>
+                    <h5>Simple events</h5>
+                    <p className='text-color-darker margin-y-10'>
+                        Shows every incoming postMessage as-is (no origin filter or type parsing). Useful for quick
+                        debugging of any messages your page receives.
+                    </p>
+                    <EventTextarea events={simpleEvents} />
+                </div>
+                <div>
+                    <h5>Simple events with origin filter</h5>
+                    <p className='text-color-darker margin-y-10'>
+                        Same raw view, but driven by the origin+handler object form (instead of a single callback) and
+                        only for messages whose origin matches this page.
+                    </p>
+                    <EventTextarea events={filteredSimpleEvents} />
+                </div>
+                <div>
+                    <h5>Action events</h5>
+                    <p className='text-color-darker margin-y-10'>
+                        Only shows action-style messages (objects with a `type` field) and extracts their payload. Handy
+                        when you control the sender and use message types to route logic.
+                    </p>
+                    <EventTextarea events={actionEvents} />
+                </div>
+                <div>
+                    <h5>Action events with origin filter</h5>
+                    <p className='text-color-darker margin-y-10'>
+                        Action messages constrained by origin. Use this to route typed messages while still protecting
+                        against unexpected origins.
+                    </p>
+                    <EventTextarea events={filteredActionEvents} />
+                </div>
+            </div>
+        </>
+    );
+};
+
+const EventTextarea = ({ events }: { events: string[] }) => {
+    const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+    useEffect(() => {
+        const element = textareaRef.current;
+        if (element) {
+            element.scrollTop = element.scrollHeight;
+        }
+    }, [events]);
+
+    return (
+        <div>
+            <textarea
+                ref={textareaRef}
+                readOnly
+                spellCheck={false}
+                value={events.join('\n')}
+                className='form-control width-100pct min-height-150 padding-15'
+            />
+        </div>
+    );
+};
+
+const isReactDevtoolsEvent = (event: MessageEvent<unknown>) => {
+    if (typeof event.data === 'object' && event.data !== null) {
+        const source = (event.data as Record<string, unknown>).source;
+        return typeof source === 'string' && source.startsWith('react-devtools-');
+    }
+    return false;
+};
+```
+
+#### Props: Simple event handler
+
+### Simple event handler
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| handler | (event: MessageEvent<unknown>) => void | — | A callback function triggered when a message is received. |
+
+#### Props: Simple handler with origin filtering
+
+### Simple handler with origin filtering
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | object | — | An object holding the handler and the expected event origin. |
+| └origin | string | — | The origin for which events are accepted. All other events are ignored. |
+| └handler | (event: MessageEvent<unknown>) => void | — | A callback function triggered when a message is received. |
+
+#### Props: Declarative, action-style handlers
+
+### Declarative, action-style handlers
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | object | — | An object holding the handlers and the expected event origin. |
+| └origin | string | "*" | The origin for which events are accepted. All other events are ignored. Optional; defaults to "*". |
+| └handlers | Record<string, (payload: unknown) => void> | — | Map of callbacks to be registered. Object keys describe the event action "type". The handler will be called with the payload. |

package/dist/docs/utilities/useInterval.md

@@ -0,0 +1,85 @@
+# useInterval
+
+*Category:* Utilities
+*Section:* Lifecycle & execution hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useInterval
+*Captured:* 2025-12-12T14:21:41.891Z
+
+The useInterval hook allows for executing some code after a specified amount of time.
+
+## useInterval
+
+### Example: Example 1
+
+Count:0
+
+Stop
+
+#### Summary
+
+Count:0
+
+Stop
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import useInterval from '@rio-cloud/rio-uikit/useInterval';
+
+export default () => {
+    const [count, setCount] = useState(0);
+    const [delay, setDelay] = useState(1000);
+    const [isRunning, setIsRunning] = useState(true);
+
+    useInterval(
+        () => {
+            // Your custom logic here
+            setCount(count + 1);
+        },
+        isRunning ? delay : null
+    );
+
+    return (
+        <div className='display-flex flex-column justify-content-center align-items-center'>
+            <div className='display-flex flex-column justify-content-center align-items-center margin-bottom-20'>
+                <label>Count:</label>
+                <div className='h2 margin-0'>{count}</div>
+            </div>
+            <div className='form-group display-flex gap-10'>
+                <input
+                    className='form-control'
+                    value={delay}
+                    onChange={event => setDelay(Number(event.target.value))}
+                />
+                <button className='btn btn-default' type='button' onClick={() => setIsRunning(!isRunning)}>
+                    {isRunning ? 'Stop' : 'Start'}
+                </button>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="display-flex flex-column justify-content-center align-items-center">
+    <div class="display-flex flex-column justify-content-center align-items-center margin-bottom-20">
+        <label>Count:</label>
+        <div class="h2 margin-0">0</div>
+    </div>
+    <div class="form-group display-flex gap-10">
+        <input class="form-control" value="1000">
+        <button class="btn btn-default" type="button">Stop</button>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| callback | Function | — | The callback function to be triggered. |
+| delay | Number | — | The time to wait until the callback function gets invoked. |