@rio-cloud/uikit-mcp 1.1.9 → 1.1.10

package/dist/docs/utilities/useDraggableElement.md

@@ -0,0 +1,281 @@
+# useDraggableElement
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#/utilities/useDraggableElement
+*Captured:* 2026-04-20T12:55:53.921Z
+
+The useDraggableElement hook provides drag behavior for an element. It manages pointer events, viewport clamping and draggable position state for UI elements like floating panels or overlays. Viewport mode renders through the shared portal root, while container mode is intended for absolutely positioned elements that must stay aligned with a scrollable boundary. The hook can also apply an initial position, including centered placement. The renderElement helper is mainly relevant for viewport mode; in container mode it simply returns the element unchanged.
+
+## useDraggableElement
+
+### Example: Example 1
+
+Use the drag icon to move the fixed panel around the viewport. Viewport mode automatically renders through the shared portal root.
+Show draggable element Reset panel position
+
+#### React (tsx)
+
+```tsx
+import { useState, type CSSProperties } from 'react';
+
+import Button from '@rio-cloud/rio-uikit/Button';
+import useDraggableElement from '@rio-cloud/rio-uikit/hooks/useDraggableElement';
+import ButtonToolbar from '@rio-cloud/rio-uikit/ButtonToolbar';
+import classNames from '@rio-cloud/rio-uikit/classNames';
+
+const defaultPositionStyle: CSSProperties = {
+    top: '180px',
+    left: '50%',
+    transform: 'translateX(-50%)',
+};
+
+const DraggablePanel = () => {
+    const { draggableRef, isDragging, position, onDragHandleDown, renderElement } = useDraggableElement();
+
+    const positionStyle = position.hasDragged ? { ...position } : defaultPositionStyle;
+
+    return renderElement(
+        <div
+            ref={draggableRef}
+            className='position-fixed rounded bg-primary padding-left-10 padding-right-20 padding-y-10 shadow-focused z-index-max'
+            style={positionStyle}
+        >
+            <div className='display-flex align-items-center gap-10'>
+                <span
+                    role='button'
+                    aria-label='Drag panel'
+                    className={classNames(
+                        'rioglyph rioglyph-drag-n-drop text-size-20',
+                        isDragging ? 'cursor-grabbing' : 'cursor-grab'
+                    )}
+                    onPointerDown={onDragHandleDown}
+                />
+                <div className='display-flex flex-column line-height-14'>
+                    <b>Draggable demo panel</b>
+                    <span className='text-size-12'>Drag only with the icon on the left</span>
+                </div>
+            </div>
+        </div>
+    );
+};
+
+export default () => {
+    const [show, setShow] = useState(false);
+    const [instanceKey, setInstanceKey] = useState(0);
+
+    return (
+        <div>
+            <p>
+                Use the drag icon to move the fixed panel around the viewport. Viewport mode automatically renders
+                through the shared portal root.
+            </p>
+            <ButtonToolbar>
+                <Button onClick={() => setShow(!show)}>{show ? 'Hide' : 'Show'} draggable element</Button>
+                <Button onClick={() => setInstanceKey(previous => previous + 1)}>Reset panel position</Button>
+            </ButtonToolbar>
+            {show && <DraggablePanel key={instanceKey} />}
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <p>Use the drag icon to move the fixed panel around the viewport. Viewport mode automatically renders through the shared portal root.</p>
+    <div class="btn-toolbar">
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Show draggable element</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Reset panel position</button>
+    </div>
+</div>
+```
+
+#### Props: Options (UseDraggableElementOptions)
+
+### Options (UseDraggableElementOptions)
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| positioning | 'viewport' \| 'container' | — | Defines whether drag coordinates are resolved against the viewport or a collision container. Viewport mode also enables portal rendering via renderElement. |
+| initialPosition | 'center' \| Pick<DraggablePosition, 'top' \| 'left'> | — | Optional initial position for the draggable element. Use center to center the element inside the active positioning context on mount. |
+| collisionContainerRef | RefObject<HTMLElement \| null> | — | Optional container whose visible client rect is used as the drag boundary in container mode. |
+
+#### Props: Return value (UseDraggableResult)
+
+### Return value (UseDraggableResult)
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| draggableRef | MutableRefObject<T \| null> | — | Ref that must be attached to the draggable element container. |
+| isDragging | boolean | — | Indicates whether a drag interaction is currently active. |
+| position | DraggablePosition | — | Current draggable coordinates and drag-state metadata. |
+| onDragHandleDown | (event: ReactPointerEvent<HTMLElement>) => void | — | Pointer down handler for the dedicated drag handle element. |
+| renderElement | (element: ReactNode, target?: HTMLElement \| null) => ReactNode | — | Renders the provided element through the shared portal root in viewport mode. An optional custom target can be passed for specialized overlay hosts. In container mode, the element is returned unchanged and this helper is usually not needed. |
+
+#### Props: Position object (DraggablePosition)
+
+### Position object (DraggablePosition)
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| top | number | — | Top offset in pixels relative to the active positioning context. |
+| left | number | — | Left offset in pixels relative to the active positioning context. |
+| hasDragged | boolean | — | Indicates whether the element has been moved by dragging at least once. |
+
+## Draggable element inside container
+
+### Example: Example 2
+
+Use the drag icon to move the card inside the dashed boundary container.
+Show draggable card Reset card position
+Drag boundary container
+Container mode keeps the draggable element inside this box and aligned correctly while the page scrolls.
+
+#### React (tsx)
+
+```tsx
+import { useRef, useState, type RefObject } from 'react';
+
+import Button from '@rio-cloud/rio-uikit/Button';
+import ButtonToolbar from '@rio-cloud/rio-uikit/ButtonToolbar';
+import Card from '@rio-cloud/rio-uikit/Card';
+import useDraggableElement from '@rio-cloud/rio-uikit/hooks/useDraggableElement';
+
+type DraggableCardProps = {
+    onClose: () => void;
+    collisionContainerRef: RefObject<HTMLDivElement | null>;
+};
+
+const DraggableCard = (props: DraggableCardProps) => {
+    const { onClose, collisionContainerRef } = props;
+
+    const { draggableRef, isDragging, position, onDragHandleDown } = useDraggableElement<HTMLDivElement>({
+        positioning: 'container',
+        initialPosition: 'center',
+        collisionContainerRef,
+    });
+
+    return (
+        <div ref={draggableRef} className='position-absolute z-index-1' style={{ ...position }}>
+            <Card className='width-350 shadow-smooth' padding={20}>
+                <div className='display-flex align-items-center justify-content-between gap-10'>
+                    <div className='display-flex align-items-center gap-10'>
+                        <div className='margin-left--5'>
+                            <span
+                                role='button'
+                                aria-label='Drag card'
+                                className='rioglyph rioglyph-drag-n-drop text-size-20 text-color-dark hover-text-color-darker'
+                                style={{
+                                    cursor: isDragging ? 'grabbing' : 'grab',
+                                    touchAction: 'none',
+                                }}
+                                onPointerDown={onDragHandleDown}
+                            />
+                        </div>
+                        <div className='text-size-16 text-medium text-color-darker'>Draggable card</div>
+                    </div>
+                    <Button
+                        bsSize='xs'
+                        bsStyle='muted'
+                        onClick={onClose}
+                        iconName='rioglyph-remove'
+                        iconOnly
+                        className='position-absolute top-15 right-15 hover-bg-none'
+                    />
+                </div>
+
+                <div className='margin-top-15'>
+                    This card is absolutely positioned inside the dashed container, so scrolling keeps it in sync with
+                    its boundary.
+                </div>
+            </Card>
+        </div>
+    );
+};
+
+export default () => {
+    const [show, setShow] = useState(false);
+    const [instanceKey, setInstanceKey] = useState(0);
+
+    const collisionContainerRef = useRef<HTMLDivElement>(null);
+
+    const handleResetPosition = () => setInstanceKey(previous => previous + 1);
+
+    return (
+        <div>
+            <p>Use the drag icon to move the card inside the dashed boundary container.</p>
+            <ButtonToolbar>
+                <Button onClick={() => setShow(!show)}>{show ? 'Hide' : 'Show'} draggable card</Button>
+                <Button onClick={handleResetPosition}>Reset card position</Button>
+            </ButtonToolbar>
+            <div
+                ref={collisionContainerRef}
+                className='position-relative margin-top-20 min-height-300 rounded border border-style-dashed border-color-info bg-highlight-decent padding-20'
+            >
+                <div className='text-size-16 text-medium text-color-info'>Drag boundary container</div>
+                <div className='margin-top-10 max-width-450 text-size-13 text-color-darker'>
+                    Container mode keeps the draggable element inside this box and aligned correctly while the page
+                    scrolls.
+                </div>
+                {show && (
+                    <DraggableCard
+                        key={instanceKey}
+                        onClose={() => setShow(false)}
+                        collisionContainerRef={collisionContainerRef}
+                    />
+                )}
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <p>Use the drag icon to move the card inside the dashed boundary container.</p>
+    <div class="btn-toolbar">
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Show draggable card</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Reset card position</button>
+    </div>
+    <div class="position-relative margin-top-20 min-height-300 rounded border border-style-dashed border-color-info bg-highlight-decent padding-20">
+        <div class="text-size-16 text-medium text-color-info">Drag boundary container</div>
+        <div class="margin-top-10 max-width-450 text-size-13 text-color-darker">Container mode keeps the draggable element inside this box and aligned correctly while the page scrolls.</div>
+    </div>
+</div>
+```
+
+#### Props: Options (UseDraggableElementOptions)
+
+### Options (UseDraggableElementOptions)
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| positioning | 'viewport' \| 'container' | — | Defines whether drag coordinates are resolved against the viewport or a collision container. Viewport mode also enables portal rendering via renderElement. |
+| initialPosition | 'center' \| Pick<DraggablePosition, 'top' \| 'left'> | — | Optional initial position for the draggable element. Use center to center the element inside the active positioning context on mount. |
+| collisionContainerRef | RefObject<HTMLElement \| null> | — | Optional container whose visible client rect is used as the drag boundary in container mode. |
+
+#### Props: Return value (UseDraggableResult)
+
+### Return value (UseDraggableResult)
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| draggableRef | MutableRefObject<T \| null> | — | Ref that must be attached to the draggable element container. |
+| isDragging | boolean | — | Indicates whether a drag interaction is currently active. |
+| position | DraggablePosition | — | Current draggable coordinates and drag-state metadata. |
+| onDragHandleDown | (event: ReactPointerEvent<HTMLElement>) => void | — | Pointer down handler for the dedicated drag handle element. |
+| renderElement | (element: ReactNode, target?: HTMLElement \| null) => ReactNode | — | Renders the provided element through the shared portal root in viewport mode. An optional custom target can be passed for specialized overlay hosts. In container mode, the element is returned unchanged and this helper is usually not needed. |
+
+#### Props: Position object (DraggablePosition)
+
+### Position object (DraggablePosition)
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| top | number | — | Top offset in pixels relative to the active positioning context. |
+| left | number | — | Left offset in pixels relative to the active positioning context. |
+| hasDragged | boolean | — | Indicates whether the element has been moved by dragging at least once. |

package/dist/docs/utilities/useEffectOnce.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Lifecycle & execution hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useEffectOnce
-*Captured:* 2026-03-06T10:41:34.405Z
+*Captured:* 2026-04-20T12:55:50.223Z
 
 The useEffectOnce hook allows to use a side effect only once after the component has been mounted.
 

package/dist/docs/utilities/useElapsedTime.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Lifecycle & execution hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useElapsedTime
-*Captured:* 2026-03-06T10:41:35.679Z
+*Captured:* 2026-04-20T12:55:50.724Z
 
 ## useElapsedTime
 

package/dist/docs/utilities/useElementSize.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useElementSize
-*Captured:* 2026-03-06T10:41:38.089Z
+*Captured:* 2026-04-20T12:55:53.547Z
 
 The useElementSize hook allows to easily detect an elements dimension.
 

package/dist/docs/utilities/useEsc.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useEsc
-*Captured:* 2026-03-06T10:41:39.113Z
+*Captured:* 2026-04-20T12:55:54.488Z
 
 The useEsc hook allows to easily detect keydown events for escape key to to react on. This comes in handy when closing something or aborting some operation on esc.
 

package/dist/docs/utilities/useEvent.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* UI state & input hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useEvent
-*Captured:* 2026-03-06T10:41:51.160Z
+*Captured:* 2026-04-20T12:56:02.563Z
 
 The useEvent hook allows to easily detect given events registered on the document.
 

package/dist/docs/utilities/useFocusTrap.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useFocusTrap
-*Captured:* 2026-03-06T10:41:39.661Z
+*Captured:* 2026-04-20T12:55:54.488Z
 
 This custom hook allows to keep the focus inside a defined wrapper element. This might be a dialog or a custom overlay.
 

package/dist/docs/utilities/useFullscreen.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useFullscreen
-*Captured:* 2026-03-06T10:41:43.215Z
+*Captured:* 2026-04-20T12:55:55.657Z
 
 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.
 

package/dist/docs/utilities/useHover.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useHover
-*Captured:* 2026-03-06T10:41:40.955Z
+*Captured:* 2026-04-20T12:55:55.343Z
 
 ## useHover
 

package/dist/docs/utilities/useIncomingPostMessages.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useIncomingPostMessages
-*Captured:* 2026-03-06T10:41:47.230Z
+*Captured:* 2026-04-20T12:55:59.869Z
 
 For handling postMessage events in React components.
 

package/dist/docs/utilities/useInterval.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Lifecycle & execution hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useInterval
-*Captured:* 2026-03-06T10:41:35.430Z
+*Captured:* 2026-04-20T12:55:51.405Z
 
 The useInterval hook allows for executing some code after a specified amount of time.
 

package/dist/docs/utilities/useIsFocusWithin.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useIsFocusWithin
-*Captured:* 2026-03-06T10:41:40.739Z
+*Captured:* 2026-04-20T12:55:55.909Z
 
 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.
 

package/dist/docs/utilities/useKey.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useKey
-*Captured:* 2026-03-06T10:41:41.456Z
+*Captured:* 2026-04-20T12:55:55.969Z
 
 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.
 
@@ -94,15 +94,13 @@ const Usage3 = () => {
     );
 };
 
-const UseKeyExample = () => {
-    return (
-        <div className='display-flex flex-column justify-content-center align-items-center'>
-            <Usage1 />
-            <Usage2 />
-            <Usage3 />
-        </div>
-    );
-};
+const UseKeyExample = () => (
+    <div className='display-flex flex-column justify-content-center align-items-center'>
+        <Usage1 />
+        <Usage2 />
+        <Usage3 />
+    </div>
+);
 
 export default UseKeyExample;
 ```

package/dist/docs/utilities/useLocalStorage.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useLocalStorage
-*Captured:* 2026-03-06T10:41:50.097Z
+*Captured:* 2026-04-20T12:56:01.143Z
 
 The useLocalStorage and the useSessionStorage hook allows to save custom data in the respective storage locations.
 

package/dist/docs/utilities/useLocationSuggestions.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* UI state & input hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useLocationSuggestions
-*Captured:* 2026-03-06T10:41:51.833Z
+*Captured:* 2026-04-20T12:56:02.807Z
 
 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.
 

package/dist/docs/utilities/useMax.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Data aggregation hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useMax
-*Captured:* 2026-03-06T10:41:56.465Z
+*Captured:* 2026-04-20T12:56:05.504Z
 
 Returns the largest valid numeric value found at the specified path within a list of objects. Supports localized formats and gracefully skips unparsable values.
 

package/dist/docs/utilities/useMin.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Data aggregation hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useMin
-*Captured:* 2026-03-06T10:41:56.398Z
+*Captured:* 2026-04-20T12:56:05.919Z
 
 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.
 

package/dist/docs/utilities/useMutationObserver.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useMutationObserver
-*Captured:* 2026-03-06T10:41:42.777Z
+*Captured:* 2026-04-20T12:55:56.718Z
 
 The useMutationObserver hook enables you to listen for changes on the given element or on its children. For more details, check out https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver
 

package/dist/docs/utilities/useOnScreen.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useOnScreen
-*Captured:* 2026-03-06T10:41:43.357Z
+*Captured:* 2026-04-20T12:55:57.126Z
 
 The useOnScreen hook tells you when an element is visible on screen.
 

package/dist/docs/utilities/useOnlineStatus.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useOnlineStatus
-*Captured:* 2026-03-06T10:41:49.569Z
+*Captured:* 2026-04-20T12:56:01.076Z
 
 The useOnlineStatus hook tells you when there is a network connection or not.
 

package/dist/docs/utilities/usePostMessage.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/usePostMessage
-*Captured:* 2026-03-06T10:41:49.551Z
+*Captured:* 2026-04-20T12:56:01.271Z
 
 The usePostMessage hook allows to easily exchange events and data between the parent window and embedded iframes.
 
@@ -88,7 +88,7 @@ export default () => {
         </div>
     </div>
     <div class="iframe-wrapper">
-        <iframe title="iframe" id="postMessageExample" src="/#postMessageExample" class="unstyled width-100pct" style="width: 1px; min-width: 100%; overflow: hidden; height: 150px;" scrolling="no">
+        <iframe title="iframe" id="postMessageExample" src="/#postMessageExample" class="unstyled width-100pct" style="width: 1px; min-width: 100%; overflow: hidden; height: 200px;" scrolling="no">
         </iframe>
     </div>
 </div>

package/dist/docs/utilities/usePostMessageSender.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/usePostMessageSender
-*Captured:* 2026-03-06T10:41:50.191Z
+*Captured:* 2026-04-20T12:56:01.294Z
 
 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.
 

package/dist/docs/utilities/usePrevious.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Lifecycle & execution hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/usePrevious
-*Captured:* 2026-03-06T10:41:36.456Z
+*Captured:* 2026-04-20T12:55:51.620Z
 
 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.
 
@@ -28,8 +28,6 @@ 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 }
@@ -69,7 +67,7 @@ export default () => {
     <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">
+                <input type="number" step="1" min="0" max="1.7976931348623157e+308" class="form-control no-controls padding-right-5" aria-label="number-input" value="1">
             </div>
             <div class="input-group-addon ">
                 <div class="display-flex padding-left-10">

package/dist/docs/utilities/useResizeObserver.md

@@ -3,15 +3,17 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useResizeObserver
-*Captured:* 2026-03-06T10:41:44.548Z
+*Captured:* 2026-04-20T12:55:58.056Z
 
 The useResizeObserver hook allows to react on resize changes of a given element.
 
 ## useResizeObserver
 
+You can either attach the returned ref to the observed element or pass an existing DOM element directly as the optional first argument.
+
 > 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.
+To include the target element padding, use the third return value with inlineSize and blockSize, or read borderBoxSize from the observer entry directly.
 
 ### Example: Example 1
 
@@ -28,9 +30,7 @@ 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();
+    // The third tuple item already exposes border-box based inline/block size values.
     const [ref, _, { inlineSize, blockSize }] = useResizeObserver();
 
     const handleResizeHorizontal = (diff: number) => setBoxWidth(previousValue => previousValue - diff);
@@ -47,7 +47,7 @@ export default () => {
                 ref={ref}
             >
                 <div className='text-color-white text-medium'>
-                    {inlineSize}x{blockSize}
+                    {inlineSize ?? 0}x{blockSize ?? 0}
                 </div>
                 <Resizer onResize={handleResizeHorizontal}>
                     <div className='width-5 height-100pct bg-light' />
@@ -71,11 +71,19 @@ export default () => {
 </div>
 ```
 
-#### Props (json)
+#### Props
 
-```json
-ref
-```
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| observedElement | HTMLElement \| null | — | Optional existing DOM element to observe directly instead of attaching the returned ref. |
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ref | MutableRefObject<T \| null> | — | Ref object for the observed element. When you pass observedElement directly, this ref can be ignored. |
+| observerEntry | ResizeObserverEntry \| null | — | The latest ResizeObserverEntry or null until the first observation. See https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry |
+| size | { inlineSize: number \| undefined; blockSize: number \| undefined } | — | Convenience object that prefers borderBoxSize and falls back to contentRect. |
 
 ### Example: Example 2
 
@@ -97,7 +105,11 @@ export default () => {
     const contentRect = observerEntry?.contentRect;
 
     const getContentRect = useCallback(
-        (key: keyof DOMRectReadOnly) => Math.round(contentRect?.[key] as number),
+        (key: keyof DOMRectReadOnly) => {
+            const value = contentRect?.[key];
+
+            return typeof value === 'number' ? Math.round(value) : 0;
+        },
         [contentRect]
     );
 
@@ -136,8 +148,16 @@ export default () => {
 </div>
 ```
 
-#### Props (json)
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| observedElement | HTMLElement \| null | — | Optional existing DOM element to observe directly instead of attaching the returned ref. |
+
+#### Props
 
-```json
-ref
-```
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ref | MutableRefObject<T \| null> | — | Ref object for the observed element. When you pass observedElement directly, this ref can be ignored. |
+| observerEntry | ResizeObserverEntry \| null | — | The latest ResizeObserverEntry or null until the first observation. See https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry |
+| size | { inlineSize: number \| undefined; blockSize: number \| undefined } | — | Convenience object that prefers borderBoxSize and falls back to contentRect. |