@rio-cloud/uikit-mcp 1.1.9 → 1.1.11

package/dist/docs/utilities/routeUtils.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Helper
 *Source:* https://uikit.developers.rio.cloud/#/utilities/routeUtils
-*Captured:* 2026-03-06T10:41:32.343Z
+*Captured:* 2026-04-27T14:59:28.978Z
 
 Utility helpers for parsing and serializing URL state. These are low-level building blocks for service-specific mapping.
 
@@ -17,6 +17,19 @@ If you use UrlConfigItem with useUrlState, set an explicit defaultValue for ever
 
 ## Route utils overview
 
+| Export | Good for |
+| --- | --- |
+| getSortDirShort | Serialize sort direction into compact empty / - prefixes. |
+| serializeSorting | Serialize sort state into a compact URL value like -name. |
+| parseSorting | Parse +name / -name into sortBy and sortDir values. |
+| mapColumnsSettingsToStrings | Serialize table column order, visibility, and widths into compact strings. |
+| parseColumnsSettingsStrings | Parse compact column strings back into column settings with defaults. |
+| serializeValue | Serialize primitive/array/object values to URL-compatible strings. |
+| deserializeValue | Parse URL strings into typed values (number, boolean, arrays, object). |
+| toQueryString | Build readable query strings (keeps commas/colons readable for complex values). |
+| isEqual | Deep compare helper re-exported for state diffing in URL sync code. |
+| UrlTypeMap, UrlValueType, UrlConfigItem | Core typing primitives for typed URL config definitions, including mandatory defaults and history behavior. |
+
 ## Simple state in URL
 
 Example for manual parse/stringify helpers in a service file.
@@ -53,6 +66,107 @@ params . set ( 'tabId' , tabId ) ; } } const tags = serializeValue ( state . tag
 params . set ( 'tags' , tags ) ; } if ( state . showArchived ) { const archived = serializeValue ( state . showArchived , 'boolean' ) ; if ( archived ) {
 params . set ( 'archived' , archived ) ; } } const queryString = params . toString ( ) ; return ` ${ BASE_PATH } / ${ queryString ? ` ? ${ queryString } ` : '' } ` ; } ;
 
+#### Code (text)
+
+```text
+import { deserializeValue, serializeValue } from '@rio-cloud/rio-uikit/routeUtils';
+
+// Adapt to your configuration
+const BASE_PATH = 'my-service';
+const VIEW_OPTIONS = ['list', 'grid'] as const;
+
+type ViewType = (typeof VIEW_OPTIONS)[number];
+const DEFAULT_VIEW: ViewType = 'list';
+const DEFAULT_TAB_ID = 1;
+
+type RouterLike = { location?: Location };
+type RouteState = {
+    query: string;
+    view: ViewType;
+    tabId: number;
+    tags: string[];
+    showArchived: boolean;
+};
+
+const isViewType = (value: string): value is ViewType => (VIEW_OPTIONS as readonly string[]).includes(value);
+
+/**
+ * Reads URL state from a router-like object.
+ * Useful when you want a lightweight parser without a hook.
+ *
+ * Note: Optional service helper when you only need a one-off parse.
+ * For reactive state sync, use the `useUrlState` hook instead.
+ *
+ * @example
+ * const state = parseRoute({ location: window.location });
+ */
+export const parseRoute = (router: RouterLike): RouteState => {
+    const location = (router?.location ?? {}) as Location;
+    const params = new URLSearchParams(location.search || '');
+
+    const parsedView = deserializeValue(params.get('view'), 'string');
+    const parsedTabId = deserializeValue(params.get('tabId'), 'number');
+    const parsedTags = deserializeValue(params.get('tags'), 'array');
+    const parsedArchived = deserializeValue(params.get('archived'), 'boolean');
+
+    return {
+        query: deserializeValue(params.get('q'), 'string') ?? '',
+        view: parsedView && isViewType(parsedView) ? parsedView : DEFAULT_VIEW,
+        tabId: parsedTabId ?? DEFAULT_TAB_ID,
+        tags: parsedTags ?? [],
+        showArchived: parsedArchived ?? false,
+    };
+};
+
+/**
+ * Builds a deep-link URL for a given state.
+ * Useful for linking to a screen with preselected filters.
+ *
+ * Note: Optional service helper when you only need to build a link.
+ * For reactive state sync, use the `useUrlState` hook instead.
+ *
+ * @example
+ * const url = makeRoute({ query: 'rio', view: 'list', tabId: 2, tags: ['banana'], showArchived: false });
+ */
+export const makeRoute = (state: RouteState) => {
+    const params = new URLSearchParams();
+
+    const query = serializeValue(state.query, 'string');
+    if (query) {
+        params.set('q', query);
+    }
+
+    if (state.view !== DEFAULT_VIEW) {
+        const view = serializeValue(state.view, 'string');
+        if (view) {
+            params.set('view', view);
+        }
+    }
+
+    if (state.tabId !== DEFAULT_TAB_ID) {
+        const tabId = serializeValue(state.tabId, 'number');
+        if (tabId) {
+            params.set('tabId', tabId);
+        }
+    }
+
+    const tags = serializeValue(state.tags, 'array');
+    if (tags) {
+        params.set('tags', tags);
+    }
+
+    if (state.showArchived) {
+        const archived = serializeValue(state.showArchived, 'boolean');
+        if (archived) {
+            params.set('archived', archived);
+        }
+    }
+
+    const queryString = params.toString();
+    return `${BASE_PATH}/${queryString ? `?${queryString}` : ''}`;
+};
+```
+
 ## TableSettingsDialog state
 
 Example for compact sort + table settings mapping with dedicated helpers.
@@ -86,7 +200,101 @@ type mapRouteProps = { sortBy : string ; sortDir : SortDirectionType ; columns :
 * For reactive state sync, use the `useUrlState` hook instead.
 *
 * @example
-* const url = makeRoute({ sortBy: 'name', sortDir: 'ASCENDING', columns });
+* const url = makeRoute({ sortBy: 'name', sortDir: 'asc', columns });
 */ export const makeRoute = ( { sortBy , sortDir , columns } : mapRouteProps ) => { const params = new URLSearchParams ( ) ; if ( sortBy ) { // Use serializeSorting for compact empty / - prefix behavior. const serializedSort = serializeSorting ( { sortBy , sortDir } ) ; if ( serializedSort ) {
 params . set ( 'sort' , serializedSort ) ; } } const mappedColumns = mapColumnsSettingsToStrings ( columns ) ; const serializedColumns = serializeValue ( mappedColumns , 'array' ) ; if ( serializedColumns ) {
-params . set ( 'columns' , serializedColumns ) ; } const queryString = params . toString ( ) ; const searchFragment = queryString ? ` ? ${ queryString } ` : '' ; return ` ${ BASE_PATH } / ${ searchFragment } ` ; } ;
+params . set ( 'columns' , serializedColumns ) ; } const queryString = params . toString ( ) ; const searchFragment = queryString ? ` ? ${ queryString } ` : '' ; return ` ${ BASE_PATH } / ${ searchFragment } ` ; } ;
+
+#### Code (text)
+
+```text
+import {
+    deserializeValue,
+    mapColumnsSettingsToStrings,
+    parseColumnsSettingsStrings,
+    parseSorting,
+    serializeSorting,
+    serializeValue,
+} from '@rio-cloud/rio-uikit/routeUtils';
+import type { SortDirectionType } from '@rio-cloud/rio-uikit/SortUtils';
+import type { TableColumnsSettings } from '@rio-cloud/rio-uikit/TableSettingsDialog';
+
+// TableSettingsDialog state example.
+// Adapt to your configuration
+const BASE_PATH = 'my-service';
+const defaultColumnsDetails: Record<string, { width: number; defaultWidth?: number }> = {
+    name: {
+        width: 250,
+        defaultWidth: 250,
+    },
+};
+
+// Sample code for parsing the route just for illustration how to use the utils functions
+// Feel free to modify this to your needs.
+// Note: the "parseRoute" and "makeRoute" functions may contain more props which are left out in this demo
+type RouterLike = { location?: Location };
+
+/**
+ * Reads table settings state from a router-like object.
+ *
+ * Note: Optional service helper when you only need a one-off parse.
+ * For reactive state sync, use the `useUrlState` hook instead.
+ *
+ * @example
+ * const state = parseRoute({ location: window.location });
+ */
+export const parseRoute = (router: RouterLike) => {
+    const location = (router?.location ?? {}) as Location;
+    const params = new URLSearchParams(location.search || '');
+
+    const sortValue = deserializeValue(params.get('sort'), 'string');
+    const sorting = sortValue ? parseSorting(sortValue) : undefined;
+
+    const columnsList = deserializeValue(params.get('columns'), 'array');
+    const columns = columnsList ? parseColumnsSettingsStrings(columnsList, defaultColumnsDetails) : undefined;
+
+    return {
+        sortBy: sorting?.sortBy,
+        sortDir: sorting?.sortDir,
+        columns,
+    };
+};
+
+type mapRouteProps = {
+    sortBy: string;
+    sortDir: SortDirectionType;
+    columns: TableColumnsSettings;
+};
+
+/**
+ * Builds a deep-link URL for a given table settings state.
+ *
+ * Note: Optional service helper when you only need to build a link.
+ * For reactive state sync, use the `useUrlState` hook instead.
+ *
+ * @example
+ * const url = makeRoute({ sortBy: 'name', sortDir: 'asc', columns });
+ */
+export const makeRoute = ({ sortBy, sortDir, columns }: mapRouteProps) => {
+    const params = new URLSearchParams();
+
+    if (sortBy) {
+        // Use serializeSorting for compact empty / - prefix behavior.
+        const serializedSort = serializeSorting({ sortBy, sortDir });
+        if (serializedSort) {
+            params.set('sort', serializedSort);
+        }
+    }
+
+    const mappedColumns = mapColumnsSettingsToStrings(columns);
+    const serializedColumns = serializeValue(mappedColumns, 'array');
+    if (serializedColumns) {
+        params.set('columns', serializedColumns);
+    }
+
+    const queryString = params.toString();
+    const searchFragment = queryString ? `?${queryString}` : '';
+
+    return `${BASE_PATH}/${searchFragment}`;
+};
+```

package/dist/docs/utilities/useAfterMount.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Lifecycle & execution hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useAfterMount
-*Captured:* 2026-03-06T10:41:34.448Z
+*Captured:* 2026-04-27T14:59:30.051Z
 
 The useAfterMount 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/useAutoAnimate.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useAutoAnimate
-*Captured:* 2026-03-06T10:41:37.681Z
+*Captured:* 2026-04-27T14:59:33.149Z
 
 The useAutoAnimate hook is a thin re-export of the @formkit/auto-animate utility to quickly add enter/leave animations to a container. This page shows a simple example; for full configuration options, check the official documentation.
 

package/dist/docs/utilities/useAverage.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Data aggregation hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useAverage
-*Captured:* 2026-03-06T10:41:55.332Z
+*Captured:* 2026-04-27T14:59:45.572Z
 
 Calculates the arithmetic mean of numeric values extracted from a list of objects using a dot-separated path. Supports localized number formats through optional locale configuration.
 

package/dist/docs/utilities/useClickOutside.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* DOM behavior hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useClickOutside
-*Captured:* 2026-03-06T10:41:38.063Z
+*Captured:* 2026-04-27T14:59:33.323Z
 
 The useClickOutside hook allows to easily detect events outside a referenced element.
 

package/dist/docs/utilities/useClipboard.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useClipboard
-*Captured:* 2026-03-06T10:41:45.450Z
+*Captured:* 2026-04-27T14:59:38.703Z
 
 The useClipboard hook allows to easily copy something to the browsers clipboard.
 
@@ -71,7 +71,7 @@ export default () => {
         <span>Random UUID</span>
     </label>
     <div class="input-group">
-        <input id="random-uuid" class="form-control" type="text" value="789340f8-0a4f-4b14-a203-8cd08f761b5e">
+        <input id="random-uuid" class="form-control" type="text" value="6e2d4717-221f-4475-864f-973f1cb5f24e">
         <div class="input-group-addon">
             <button type="button" class="btn btn-muted btn-sm btn-icon-only btn-component position-absolute top-1 right-1" tabindex="0">
                 <span class="rioglyph rioglyph-duplicate">

package/dist/docs/utilities/useCookies.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useCookies
-*Captured:* 2026-03-06T10:41:47.226Z
+*Captured:* 2026-04-27T14:59:39.991Z
 
 The useCookies hook allows you to set cookies, delete cookies and check whether a cookie exists in the browser.
 

package/dist/docs/utilities/useCount.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Data aggregation hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useCount
-*Captured:* 2026-03-06T10:41:55.383Z
+*Captured:* 2026-04-27T14:59:46.251Z
 
 useCount is a utility hook for counting how many objects in a list contain a specific value or match a custom condition at a given property path. It supports exact value matching (e.g. true, 0, 'PENDING') or predicate-based logic using a match function. By default, all values that are not null or undefined are counted.
 

package/dist/docs/utilities/useDarkMode.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* Browser & device hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useDarkMode
-*Captured:* 2026-03-06T10:41:47.248Z
+*Captured:* 2026-04-27T14:59:40.173Z
 
 The useDarkMode hook enables you to listen for the color scheme change and react accordingly.
 
@@ -39,7 +39,8 @@ export default () => {
 </div>
 ```
 
-#### Props
+#### Props (json)
 
-| Name | Type | Default | Description |
-| --- | --- | --- | --- |
+```json
+isDarkMode
+```

package/dist/docs/utilities/useDebugInfo.md

@@ -3,7 +3,7 @@
 *Category:* Utilities
 *Section:* UI state & input hooks
 *Source:* https://uikit.developers.rio.cloud/#/utilities/useDebugInfo
-*Captured:* 2026-03-06T10:41:51.188Z
+*Captured:* 2026-04-27T14:59:43.208Z
 
 The useDebugInfo hook allows to return detailed information about render count, render time and changed component props and also to print these information to the console.
 
@@ -18,7 +18,7 @@ Debug Info: {
 "renderCount": 1,
 "changedProps": {},
 "timeSinceLastRender": 0,
-"lastRenderTimestamp": 1772793710502
+"lastRenderTimestamp": 1777301982498
 }
 
 Toggle Increment
@@ -93,7 +93,7 @@ export default () => {
  "renderCount": 1,
  "changedProps": {},
  "timeSinceLastRender": 0,
- "lastRenderTimestamp": 1772793710502
+ "lastRenderTimestamp": 1777301982498
 }</pre>
         </div>
     </div>

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-27T14:59:34.226Z
+
+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-27T14:59:30.393Z
 
 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-27T14:59:30.727Z
 
 ## useElapsedTime