@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/dist/docs/utilities/usePostMessageSender.md

@@ -0,0 +1,257 @@
+# usePostMessageSender
+
+*Category:* Utilities
+*Section:* Browser & device hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/usePostMessageSender
+*Captured:* 2025-12-12T12:39:46.089Z
+
+Helper hook to fire postMessage events to other windows: a specific target (including yourself), the parent or top window, or every iframe on the page. It uses the wildcard target origin (*) and no-ops when a target window is missing, so it is safe to call even when an iframe or parent is not present.
+
+## usePostMessageSender
+
+### Example: Example 1
+
+Use the buttons below to dispatch messages using usePostMessageSender. The gray box below is a real <iframe> that listens for your messages and sends an IFRAME_ECHO back.
+Send to Self (Window)Send to Iframe (Ref)Broadcast to All IframesSend to Parent
+Target Iframe
+This iframe acts as a separate window context. It runs a script to display what it receives.
+
+Activity Log
+Shows outgoing confirmations and incoming "Echos" from the iframe.
+
+#### Summary
+
+Use the buttons below to dispatch messages using usePostMessageSender. The gray box below is a real <iframe> that listens for your messages and sends an IFRAME_ECHO back.
+Send to Self (Window)Send to Iframe (Ref)Broadcast to All IframesSend to Parent
+Target Iframe
+This iframe acts as a separate window context. It runs a script to display what it receives.
+
+Activity Log
+Shows outgoing confirmations and incoming "Echos" from the iframe.
+
+#### 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 usePostMessageSender from '@rio-cloud/rio-uikit/usePostMessageSender';
+import useIncomingPostMessages from '@rio-cloud/rio-uikit/useIncomingPostMessages';
+
+export default () => {
+    const { sendMessage, sendMessageToAllIframes, sendMessageToParent } = usePostMessageSender();
+
+    const [logs, setLogs] = useState<string[]>([]);
+
+    // We use a ref to target a specific iframe for the "Single Target" test
+    const iframeRef = useRef<HTMLIFrameElement>(null);
+
+    // 1. LISTEN FOR REPLIES (ECHOS)
+    // We reuse the receiving hook to verify that our sent messages were actually processed
+    // by the target (the iframe or window) and replied to.
+    useIncomingPostMessages({
+        handlers: {
+            // The iframe in this demo is programmed to send this event back
+            IFRAME_ECHO: (payload: { type: string; payload: unknown }) => {
+                addLog(`Received ECHO from iframe: ${JSON.stringify(payload)}`);
+            },
+        },
+    });
+
+    // Also listen for raw messages to catch self-sent messages
+    useIncomingPostMessages(event => {
+        if (event.data === 'Hello Self!') {
+            addLog('Received self-sent message: "Hello Self!"');
+        }
+    });
+
+    const addLog = (msg: string) => setLogs(prev => [...prev, `[${new Date().toLocaleTimeString()}] ${msg}`]);
+
+    // 2. SENDING ACTIONS
+    const handleSendToSelf = () => {
+        // Sending to 'window' is useful for decoupling components on the same page
+        sendMessage('Hello Self!', window);
+        addLog('Sent "Hello Self!" to current window');
+    };
+
+    const handleSendToIframe = () => {
+        if (iframeRef.current?.contentWindow) {
+            // Target a specific window (the iframe)
+            const payload = { id: 123, text: 'Direct message' };
+            sendMessage({ type: 'UPDATE_DATA', payload }, iframeRef.current.contentWindow);
+            addLog('Sent UPDATE_DATA to specific iframe');
+        }
+    };
+
+    const handleBroadcast = () => {
+        // Useful if you have multiple widgets/iframes and want to notify all of them
+        sendMessageToAllIframes({ type: 'GLOBAL_RESET' });
+        addLog('Broadcasted GLOBAL_RESET to all iframes');
+    };
+
+    const handleSendToParent = () => {
+        // This might not do much if you are top-level, but won't crash
+        sendMessageToParent('Hello Parent!');
+        addLog('Sent message to parent window (check console if inside iframe)');
+    };
+
+    return (
+        <>
+            <p className='margin-bottom-20'>
+                Use the buttons below to dispatch messages using <code>usePostMessageSender</code>. The gray box below
+                is a real <code>&lt;iframe&gt;</code> that listens for your messages and sends an <b>IFRAME_ECHO</b>{' '}
+                back.
+            </p>
+
+            <ButtonToolbar>
+                <Button onClick={handleSendToSelf}>Send to Self (Window)</Button>
+                <Button onClick={handleSendToIframe}>Send to Iframe (Ref)</Button>
+                <Button onClick={handleBroadcast}>Broadcast to All Iframes</Button>
+                <Button onClick={handleSendToParent}>Send to Parent</Button>
+            </ButtonToolbar>
+
+            <div className='display-grid grid-cols-1 grid-cols-2-md margin-y-20 gap-25'>
+                <div>
+                    <h5>Target Iframe</h5>
+                    <p className='text-color-darker margin-y-10'>
+                        This iframe acts as a separate window context. It runs a script to display what it receives.
+                    </p>
+                    <iframe
+                        ref={iframeRef}
+                        title='Receiver demo'
+                        className='width-100pct height-200 border rounded'
+                        srcDoc={iframeScript} // See variable at bottom of file
+                    />
+                </div>
+
+                <div>
+                    <h5>Activity Log</h5>
+                    <p className='text-color-darker margin-y-10'>
+                        Shows outgoing confirmations and incoming "Echos" from the iframe.
+                    </p>
+                    <EventTextarea events={logs} />
+                </div>
+            </div>
+        </>
+    );
+};
+
+const EventTextarea = ({ events }: { events: string[] }) => {
+    const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+    useEffect(() => {
+        if (textareaRef.current) {
+            textareaRef.current.scrollTop = textareaRef.current.scrollHeight;
+        }
+    }, [events]);
+
+    return (
+        <textarea
+            ref={textareaRef}
+            readOnly
+            spellCheck={false}
+            value={events.join('\n')}
+            className='form-control width-100pct height-200 padding-15 font-size-12'
+        />
+    );
+};
+
+// This HTML/JS blob is injected into the iframe to simulate a receiving widget
+const iframeScript = `
+<!DOCTYPE html>
+<html>
+<body style="background-color: #f9f9f9; font-family: sans-serif; padding: 10px; margin: 0;">
+    <h4 style="margin-top: 0; color: #555;">Iframe Content</h4>
+    <div id="display" style="font-size: 13px; color: #333;">Waiting for messages...</div>
+    <script>
+        window.addEventListener('message', (event) => {
+            // Ignore react-devtools
+            if(typeof event.data === 'object' && event.data?.source?.startsWith('react-devtools')) return;
+
+            const display = document.getElementById('display');
+            const dataStr = typeof event.data === 'string' ? event.data : JSON.stringify(event.data);
+            
+            display.innerHTML = '<strong>Received:</strong><br/>' + dataStr;
+            display.style.backgroundColor = '#e6fffa';
+            setTimeout(() => display.style.backgroundColor = 'transparent', 500);
+
+            // Send an ECHO back to the parent to prove communication loop
+            if (event.data && typeof event.data === 'object') {
+                window.parent.postMessage({
+                    type: 'IFRAME_ECHO',
+                    payload: event.data
+                }, '*');
+            }
+        });
+    </script>
+</body>
+</html>
+`;
+```
+
+#### HTML (html)
+
+```html
+<p class="margin-bottom-20">Use the buttons below to dispatch messages using <code>usePostMessageSender</code>. The gray box below is a real <code>&lt;iframe&gt;</code> that listens for your messages and sends an <b>IFRAME_ECHO</b> back.</p>
+<div class="btn-toolbar">
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Send to Self (Window)</button>
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Send to Iframe (Ref)</button>
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Broadcast to All Iframes</button>
+    <button type="button" class="btn btn-default btn-component" tabindex="0">Send to Parent</button>
+</div>
+<div class="display-grid grid-cols-1 grid-cols-2-md margin-y-20 gap-25">
+    <div>
+        <h5>Target Iframe</h5>
+        <p class="text-color-darker margin-y-10">This iframe acts as a separate window context. It runs a script to display what it receives.</p>
+        <iframe title="Receiver demo" class="width-100pct height-200 border rounded" srcdoc="
+&lt;!DOCTYPE html&gt;
+&lt;html&gt;
+&lt;body style=&quot;background-color: #f9f9f9; font-family: sans-serif; padding: 10px; margin: 0;&quot;&gt;
+    &lt;h4 style=&quot;margin-top: 0; color: #555;&quot;&gt;Iframe Content&lt;/h4&gt;
+    &lt;div id=&quot;display&quot; style=&quot;font-size: 13px; color: #333;&quot;&gt;Waiting for messages...&lt;/div&gt;
+    &lt;script&gt;
+        window.addEventListener('message', (event) =&gt; {
+            // Ignore react-devtools
+            if(typeof event.data === 'object' &amp;&amp; event.data?.source?.startsWith('react-devtools')) return;
+
+            const display = document.getElementById('display');
+            const dataStr = typeof event.data === 'string' ? event.data : JSON.stringify(event.data);
+            
+            display.innerHTML = '&lt;strong&gt;Received:&lt;/strong&gt;&lt;br/&gt;' + dataStr;
+            display.style.backgroundColor = '#e6fffa';
+            setTimeout(() =&gt; display.style.backgroundColor = 'transparent', 500);
+
+            // Send an ECHO back to the parent to prove communication loop
+            if (event.data &amp;&amp; typeof event.data === 'object') {
+                window.parent.postMessage({
+                    type: 'IFRAME_ECHO',
+                    payload: event.data
+                }, '*');
+            }
+        });
+    &lt;/script&gt;
+&lt;/body&gt;
+&lt;/html&gt;
+">
+        </iframe>
+    </div>
+    <div>
+        <h5>Activity Log</h5>
+        <p class="text-color-darker margin-y-10">Shows outgoing confirmations and incoming "Echos" from the iframe.</p>
+        <textarea readonly="" spellcheck="false" class="form-control width-100pct height-200 padding-15 font-size-12">
+</textarea>
+    </div>
+</div>
+```
+
+#### Props: Returns
+
+### Returns
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| sendMessage | (message: unknown, targetWindow: WindowProxy \| null \| undefined) => void | — | Send a message to the provided window (or to yourself if you pass window). Does nothing if target is null/undefined. |
+| sendMessageToParent | (message: unknown) => void | — | Send a message to the parent window (no-op when already top-level). |
+| sendMessageToTop | (message: unknown) => void | — | Send a message to the top window (no-op when already top-level). |
+| sendMessageToAllIframes | (message: unknown) => void | — | Broadcast a message to every iframe found on the page. |

package/dist/docs/utilities/usePrevious.md

@@ -0,0 +1,101 @@
+# usePrevious
+
+*Category:* Utilities
+*Section:* Lifecycle & execution hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/usePrevious
+*Captured:* 2025-12-12T12:39:37.704Z
+
+The usePrevious hook allows to easily access state from previous component render. Instead of using a React.ref and a useEffect, this hook uses a useState internally to keep track of the previous state value.
+
+## usePrevious
+
+- If the value you need can be computed entirely from the current props or other state, remove that redundant state altogether. If you’re worried about recomputing too often, the useMemo Hook can help.
+- If you want to reset the entire component tree’s state, pass a different key to your component.
+- If you can, update all the relevant state in the event handlers.
+
+```jsx
+function List({ items }) {
+const [isReverse, setIsReverse] = useState(false);
+const [selection, setSelection] = useState(null);
+
+// Better: Adjust the state while rendering
+const [prevItems, setPrevItems] = useState(items);
+if (items !== prevItems) {
+setPrevItems(items);
+setSelection(null);
+}
+// ...
+}
+```
+
+> Note: If you want to use this to update the internal state due to a prop change, you might run into a loop. Therefore, use the following snippet suggested by the React team here: https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes
+
+### Example: Example 1
+
+{ count: 1, previousCount: 1 }
+
+#### Summary
+
+{ count: 1, previousCount: 1 }
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import usePrevious from '@rio-cloud/rio-uikit/usePrevious';
+import NumberControl from '@rio-cloud/rio-uikit/NumberControl';
+
+export default () => {
+    const [count, setCount] = useState<number | undefined>(1);
+
+    const previousCount = usePrevious(count);
+
+    return (
+        <div className='display-flex flex-wrap gap-20 align-items-center'>
+            <NumberControl
+                value={count}
+                onChange={(value?: number) => setCount(value)}
+                className='margin-0 width-100'
+            />
+            <div className='text-italic text-color-darker'>
+                {`{ count: ${count}, previousCount: ${previousCount} }`}
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="display-flex flex-wrap gap-20 align-items-center">
+    <div class="NumberControl margin-0 width-100">
+        <div class="input-group">
+            <div class="form-control-feedback-wrapper">
+                <input type="number" step="1" min="0" max="1.7976931348623157e+308" class="form-control no-controls" aria-label="number-input" value="1">
+            </div>
+            <div class="input-group-addon ">
+                <div class="display-flex padding-left-10">
+                    <div role="button" aria-label="decrement-button" class="decrementButton display-flex align-items-center text-color-gray hover-text-color-dark cursor-pointer">
+                        <div class="rioglyph rioglyph-minus scale-90">
+                        </div>
+                    </div>
+                    <div role="button" aria-label="increment-button" class="incrementButton display-flex align-items-center text-color-gray hover-text-color-dark cursor-pointer margin-left-5">
+                        <div class="rioglyph rioglyph-plus scale-90">
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="text-italic text-color-darker">{ count: 1, previousCount: 1 }</div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| state | any | — | The value of the current state to keep track of. |
+|  | any | — | Returns the previous value of the state to keep track of. |

package/dist/docs/utilities/useResizeObserver.md

@@ -0,0 +1,151 @@
+# useResizeObserver
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useResizeObserver
+*Captured:* 2025-12-12T12:39:43.338Z
+
+The useResizeObserver hook allows to react on resize changes of a given element.
+
+## useResizeObserver
+
+> Note: that is important to consider the padding of the element to observe and to take it into consideration when working with its width and height. When using the contentRect from the observerEntry, keep in mind that this will not include the paddings.
+
+To include the target elements padding, please use the borderBoxSize instead.
+
+### Example: Example 1
+
+Box with padding200x50
+
+#### Summary
+
+Box with padding200x50
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import Resizer from '@rio-cloud/rio-uikit/Resizer';
+import useResizeObserver from '@rio-cloud/rio-uikit/useResizeObserver';
+
+export default () => {
+    const [boxWidth, setBoxWidth] = useState(200);
+
+    // To include target elements padding, use "borderBoxSize" or for convenience
+    // purpose, use the dedicated return object already containing "inlineSize" and "blockSize".
+    // const [ref, { borderBox }] = useResizeObserver();
+    const [ref, _, { inlineSize, blockSize }] = useResizeObserver();
+
+    const handleResizeHorizontal = (diff: number) => setBoxWidth(previousValue => previousValue - diff);
+
+    return (
+        <>
+            <label>Box with padding</label>
+            <div
+                className={
+                    'height-50 bg-info position-relative display-flex align-items-center ' +
+                    'justify-content-center padding-5'
+                }
+                style={{ width: boxWidth }}
+                ref={ref}
+            >
+                <div className='text-color-white text-medium'>
+                    {inlineSize}x{blockSize}
+                </div>
+                <Resizer onResize={handleResizeHorizontal}>
+                    <div className='width-5 height-100pct bg-light' />
+                </Resizer>
+            </div>
+        </>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<label>Box with padding</label>
+<div class="height-50 bg-info position-relative display-flex align-items-center justify-content-center padding-5" style="width: 200px;">
+    <div class="text-color-white text-medium">200x50</div>
+    <div class="Resizer resize-horizontal resize-right">
+        <div class="width-5 height-100pct bg-light">
+        </div>
+    </div>
+</div>
+```
+
+#### Props (json)
+
+```json
+ref
+```
+
+### Example: Example 2
+
+Box without padding200x50
+
+#### Summary
+
+Box without padding200x50
+
+#### React (tsx)
+
+```tsx
+import { useState, useCallback } from 'react';
+
+import Resizer from '@rio-cloud/rio-uikit/Resizer';
+import useResizeObserver from '@rio-cloud/rio-uikit/useResizeObserver';
+
+export default () => {
+    const [boxWidth, setBoxWidth] = useState(200);
+
+    const [ref, observerEntry] = useResizeObserver();
+
+    const contentRect = observerEntry?.contentRect;
+
+    const getContentRect = useCallback(
+        (key: keyof DOMRectReadOnly) => Math.round(contentRect?.[key] as number),
+        [contentRect]
+    );
+
+    const handleResizeHorizontal = (diff: number) => setBoxWidth(previousValue => previousValue - diff);
+
+    return (
+        <>
+            <label>Box without padding</label>
+            <div
+                className='height-50 bg-info position-relative display-flex align-items-center justify-content-center'
+                style={{ width: boxWidth }}
+                ref={ref}
+            >
+                <div className='text-color-white text-medium'>
+                    {getContentRect('width')}x{getContentRect('height')}
+                </div>
+                <Resizer onResize={handleResizeHorizontal}>
+                    <div className='width-5 height-100pct bg-light' />
+                </Resizer>
+            </div>
+        </>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<label>Box without padding</label>
+<div class="height-50 bg-info position-relative display-flex align-items-center justify-content-center" style="width: 200px;">
+    <div class="text-color-white text-medium">200x50</div>
+    <div class="Resizer resize-horizontal resize-right">
+        <div class="width-5 height-100pct bg-light">
+        </div>
+    </div>
+</div>
+```
+
+#### Props (json)
+
+```json
+ref
+```