@tangible/ui 0.0.8 → 0.0.10

package/components/Avatar/Avatar.d.ts

@@ -8,4 +8,4 @@ import type { AvatarProps } from './types';
  * - Shows placeholder icon if neither `src` nor `name` provided
  * - Colors for initials are derived from the name hash for consistency
  */
-export declare const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLSpanElement>>;
+export declare const Avatar: React.NamedExoticComponent<AvatarProps & React.RefAttributes<HTMLSpanElement>>;

package/components/Avatar/Avatar.js

@@ -46,7 +46,7 @@ function getColorFromName(name, colors) {
  * - Shows placeholder icon if neither `src` nor `name` provided
  * - Colors for initials are derived from the name hash for consistency
  */
-export const Avatar = React.forwardRef(({ src, name, size = 'md', shape = 'circle', color, indicator, indicatorLabel, indicatorPosition = 'bottom-right', tooltip, labels: labelsProp, className, }, ref) => {
+export const Avatar = React.memo(React.forwardRef(({ src, name, size = 'md', shape = 'circle', color, indicator, indicatorLabel, indicatorPosition = 'bottom-right', tooltip, labels: labelsProp, className, }, ref) => {
     const [imgError, setImgError] = useState(false);
     // Reset error state when src changes
     React.useEffect(() => {
@@ -73,5 +73,5 @@ export const Avatar = React.forwardRef(({ src, name, size = 'md', shape = 'circl
         return (_jsxs(Tooltip, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: avatarElement }), _jsx(Tooltip.Content, { "aria-hidden": "true", children: name })] }));
     }
     return avatarElement;
-});
+}));
 Avatar.displayName = 'Avatar';

package/components/Combobox/Combobox.js

@@ -43,6 +43,9 @@ function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inp
     // Option registration
     const optionsRef = useRef(new Map());
     const [registryVersion, setRegistryVersion] = useState(0);
+    // Track open state via ref so unregisterOption can check synchronously
+    const openRef = useRef(false);
+    openRef.current = open;
     // IDs
     const baseId = useId();
     const inputId = `${baseId}-input`;
@@ -149,12 +152,27 @@ function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inp
         role,
         listNavigation,
     ]);
+    // Flag: first registerOption call after open clears stale entries.
+    const prevOpenForFlush = useRef(open);
+    const needsFlushRef = useRef(false);
+    if (open && !prevOpenForFlush.current)
+        needsFlushRef.current = true;
+    prevOpenForFlush.current = open;
     // Register option
     const registerOption = useCallback((option) => {
+        if (needsFlushRef.current) {
+            optionsRef.current.clear();
+            needsFlushRef.current = false;
+        }
         optionsRef.current.set(toKey(option.value), option);
         setRegistryVersion((v) => v + 1);
     }, []);
     const unregisterOption = useCallback((optionValue) => {
+        // When the dropdown closes, options unmount and call unregister in cleanup.
+        // Skip the delete to preserve the registry — filtering and input display
+        // depend on it while closed. Options re-register on next open (same keys).
+        if (!openRef.current)
+            return;
         optionsRef.current.delete(toKey(optionValue));
         setRegistryVersion((v) => v + 1);
     }, []);
@@ -368,7 +386,7 @@ function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inp
     return (_jsx(ComboboxActionsContext.Provider, { value: actionsValue, children: _jsx(ComboboxStateContext.Provider, { value: stateValue, children: _jsxs("div", { className: "tui-combobox", children: [_jsxs("div", { className: "tui-combobox__input-wrapper", children: [_jsx("input", { ref: (node) => {
                                     inputRef.current = node;
                                     refs.setReference(node);
-                                }, type: "text", id: inputId, className: cx('tui-combobox__input', size !== 'md' && `is-size-${size}`, inputClassName), role: "combobox", "aria-expanded": open, "aria-controls": listboxId, "aria-autocomplete": "list", "aria-activedescendant": activeOptionId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, placeholder: placeholder, value: inputValue, autoComplete: "off", ...referenceProps, onChange: handleInputChange }), clearable && inputValue && !disabled && (_jsx("button", { type: "button", className: "tui-combobox__clear", onClick: handleClear, onMouseDown: (e) => e.preventDefault(), "aria-label": labels.clear, tabIndex: -1, children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx("span", { className: "tui-combobox__icon", "aria-hidden": "true", children: _jsx(Icon, { name: "system/chevron-down", size: "sm" }) })] }), children] }) }) }));
+                                }, type: "text", id: inputId, className: cx('tui-combobox__input', size !== 'md' && `is-size-${size}`, inputClassName), role: "combobox", "aria-expanded": open, "aria-controls": open ? listboxId : undefined, "aria-autocomplete": "list", "aria-activedescendant": activeOptionId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, placeholder: placeholder, value: inputValue, autoComplete: "off", ...referenceProps, onChange: handleInputChange }), clearable && inputValue && !disabled && (_jsx("button", { type: "button", className: "tui-combobox__clear", onClick: handleClear, onMouseDown: (e) => e.preventDefault(), "aria-label": labels.clear, tabIndex: -1, children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx("span", { className: "tui-combobox__icon", "aria-hidden": "true", children: _jsx(Icon, { name: "system/chevron-down", size: "sm" }) })] }), children] }) }) }));
 }
 ComboboxRoot.displayName = 'Combobox';
 // =============================================================================
@@ -376,6 +394,12 @@ ComboboxRoot.displayName = 'Combobox';
 // =============================================================================
 function ComboboxContentComponent({ className, children }) {
     const { open, listboxId, inputId, refs, floatingStyles, getFloatingProps, listRef, activeIndex, orderedOptions, } = useComboboxContext();
+    // Track whether dropdown has ever been opened. Before first open, mount
+    // children in a hidden div for option registration (defaultValue resolution).
+    // After first open, only mount children when open (in portal).
+    const hasEverOpened = useRef(false);
+    if (open)
+        hasEverOpened.current = true;
     const portalRoot = getPortalRootFor(refs.reference.current);
     const contentContext = useMemo(() => ({
         listRef,
@@ -383,7 +407,7 @@ function ComboboxContentComponent({ className, children }) {
         orderedOptions,
     }), [listRef, activeIndex, orderedOptions]);
     // Always render for option registration
-    return (_jsxs(_Fragment, { children: [!open && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(ComboboxContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": inputId, className: cx('tui-combobox__content', className), style: {
+    return (_jsxs(_Fragment, { children: [!open && !hasEverOpened.current && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(ComboboxContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": inputId, className: cx('tui-combobox__content', className), style: {
                         ...floatingStyles,
                         minWidth: refs.reference.current?.offsetWidth,
                         pointerEvents: 'auto',

package/components/Dropdown/Dropdown.d.ts

@@ -7,7 +7,7 @@ declare function DropdownTriggerComponent({ asChild, children }: DropdownTrigger
 declare namespace DropdownTriggerComponent {
     var displayName: string;
 }
-declare function DropdownContentComponent({ side, align, sideOffset, className, style, children, }: DropdownContentProps): import("react/jsx-runtime").JSX.Element | null;
+declare function DropdownContentComponent(props: DropdownContentProps): import("react/jsx-runtime").JSX.Element | null;
 declare namespace DropdownContentComponent {
     var displayName: string;
 }

package/components/Dropdown/Dropdown.js

@@ -112,12 +112,23 @@ DropdownTriggerComponent.displayName = 'Dropdown.Trigger';
 // =============================================================================
 // DropdownContent
 // =============================================================================
-function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset = 4, className, style, children, }) {
-    const { open, setOpen, triggerRef, contentId, activeIndex, setActiveIndex, openedVia } = useDropdownContext();
+// Gate component: reads context to decide whether to mount the real content.
+// This ensures useFloating and all Floating UI hooks in DropdownContentInner
+// only run when the dropdown is actually open — not on every render cycle.
+function DropdownContentComponent(props) {
+    const { open } = useDropdownContext();
+    if (!open)
+        return null;
+    return _jsx(DropdownContentInner, { ...props });
+}
+DropdownContentComponent.displayName = 'Dropdown.Content';
+// Inner component: only mounted when open. All Floating UI hooks live here.
+function DropdownContentInner({ side = 'bottom', align = 'start', sideOffset = 4, className, style, children, }) {
+    const { setOpen, triggerRef, contentId, activeIndex, setActiveIndex, openedVia } = useDropdownContext();
     const listRef = useRef([]);
     const { refs, floatingStyles, context } = useFloating({
         placement: toPlacement(side, align),
-        open,
+        open: true, // Always true when mounted (gate handles the conditional)
         onOpenChange: setOpen,
         middleware: [offset(sideOffset), flip(), shift({ padding: 8 })],
         whileElementsMounted: autoUpdate,
@@ -156,7 +167,7 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
     }, [children]);
     // ArrowUp focus-last: set activeIndex to last valid item before paint
     useLayoutEffect(() => {
-        if (open && openedVia.current === 'ArrowUp') {
+        if (openedVia.current === 'ArrowUp') {
             let lastValid = totalItemCount - 1;
             while (lastValid >= 0 && disabledIndices.includes(lastValid)) {
                 lastValid--;
@@ -166,7 +177,7 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
             }
             openedVia.current = null;
         }
-    }, [open, openedVia, totalItemCount, disabledIndices, setActiveIndex]);
+    }, [openedVia, totalItemCount, disabledIndices, setActiveIndex]);
     const dismiss = useDismiss(context);
     const role = useRole(context, { role: 'menu' });
     const listNavigation = useListNavigation(context, {
@@ -184,8 +195,6 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
     ]);
     // Get portal root inside .tui-interface
     const portalRoot = getPortalRootFor(triggerRef.current);
-    if (!open)
-        return null;
     // Clone children to inject item props and role.
     // Non-navigable children (Separator, Header) are rendered as-is.
     let itemIndex = 0;
@@ -229,7 +238,6 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
                     ...style,
                 }, ...getFloatingProps(), children: items }) }) }));
 }
-DropdownContentComponent.displayName = 'Dropdown.Content';
 // =============================================================================
 // DropdownItem
 // =============================================================================

package/components/Icon/Icon.d.ts

@@ -19,4 +19,4 @@ export interface IconProps {
  * - Decorative icons (no label): automatically hidden from screen readers
  * - Informative icons: provide a `label` prop for screen reader announcement
  */
-export declare const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<HTMLSpanElement>>;
+export declare const Icon: React.NamedExoticComponent<IconProps & React.RefAttributes<HTMLSpanElement>>;

package/components/Icon/Icon.js

@@ -10,7 +10,7 @@ import { iconRegistry } from '../../icons/registry.js';
  * - Decorative icons (no label): automatically hidden from screen readers
  * - Informative icons: provide a `label` prop for screen reader announcement
  */
-export const Icon = React.forwardRef(({ name, emoji, label, size, className }, ref) => {
+export const Icon = React.memo(React.forwardRef(({ name, emoji, label, size, className }, ref) => {
     const SvgIcon = name ? iconRegistry[name] : null;
     // Dev warning for invalid icon name
     if (isDev() && name && !SvgIcon) {
@@ -21,5 +21,5 @@ export const Icon = React.forwardRef(({ name, emoji, label, size, className }, r
     return (_jsxs("span", { ref: ref, className: cx('tui-icon', size && `is-size-${size}`, className), ...(isDecorative
             ? { 'aria-hidden': true }
             : { role: 'img', 'aria-label': label }), children: [SvgIcon && _jsx(SvgIcon, { "aria-hidden": "true", focusable: "false" }), !SvgIcon && emoji] }));
-});
+}));
 Icon.displayName = 'Icon';

package/components/Modal/Modal.d.ts

@@ -17,9 +17,13 @@ export type ModalProps = {
     closeLabel?: string;
     closeOnBackdropClick?: boolean;
     closeOnEscape?: boolean;
+    /** When true, prevents the browser from scrolling to the trigger element
+     *  when focus is restored on close. Useful when the trigger may be off-screen
+     *  inside a scrollable container. Default: false. */
+    preventScrollOnRestore?: boolean;
     children?: React.ReactNode;
 };
-declare function ModalRoot({ open, onClose, size, stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel, closeOnBackdropClick, closeOnEscape, children, }: ModalProps): React.ReactPortal | null;
+declare function ModalRoot({ open, onClose, size, stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel, closeOnBackdropClick, closeOnEscape, preventScrollOnRestore, children, }: ModalProps): React.ReactPortal | null;
 type ModalCloseProps = {
     label?: string;
     className?: string;

package/components/Modal/Modal.js

@@ -8,7 +8,7 @@ import { useFocusTrap, getInitialFocus } from '../../utils/focus-trap.js';
 import { ModalContext, useModalContext } from './context.js';
 import { IconButton } from '../IconButton/index.js';
 const isBrowser = typeof document !== 'undefined';
-function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel = 'Close', closeOnBackdropClick = true, closeOnEscape = true, children, }) {
+function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel = 'Close', closeOnBackdropClick = true, closeOnEscape = true, preventScrollOnRestore = false, children, }) {
     const dialogRef = useRef(null);
     const restoreRef = useRef(null);
     const warnedRef = useRef(false);
@@ -45,7 +45,7 @@ function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-l
             return;
         const el = restoreRef.current;
         if (el && typeof el.focus === 'function') {
-            el.focus();
+            el.focus({ preventScroll: preventScrollOnRestore });
         }
         restoreRef.current = null;
         setMount(null);

package/components/MoveHandle/MoveHandle.d.ts

@@ -1,2 +1,2 @@
 import type { MoveHandleProps } from './types';
-export declare const MoveHandle: import("react").ForwardRefExoticComponent<MoveHandleProps & import("react").RefAttributes<HTMLElement>>;
+export declare const MoveHandle: import("react").NamedExoticComponent<MoveHandleProps & import("react").RefAttributes<HTMLElement>>;

package/components/MoveHandle/MoveHandle.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useId, useRef, useState } from 'react';
+import { forwardRef, memo, useCallback, useEffect, useId, useRef, useState } from 'react';
 import { cx } from '../../utils/cx.js';
 import { isDev } from '../../utils/is-dev.js';
 import { Icon } from '../Icon/index.js';
@@ -24,7 +24,7 @@ import { Icon } from '../Icon/index.js';
 //   --tui-move-handle-icon-size  Override icon size
 //
 // =============================================================================
-export const MoveHandle = forwardRef(function MoveHandle({ mode = 'full', size = 'md', index, locked = false, onMoveUp, onMoveDown, canMoveUp = true, canMoveDown = true, labels, dragHandleProps, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, }, ref) {
+export const MoveHandle = memo(forwardRef(function MoveHandle({ mode = 'full', size = 'md', index, locked = false, onMoveUp, onMoveDown, canMoveUp = true, canMoveDown = true, labels, dragHandleProps, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, }, ref) {
     // All hooks must be called unconditionally (rules of hooks)
     const innerRef = useRef(null);
     const mergedRef = useCallback((node) => {
@@ -92,4 +92,4 @@ export const MoveHandle = forwardRef(function MoveHandle({ mode = 'full', size =
         ? (labels?.locked ?? 'This item is locked and cannot be reordered')
         : undefined;
     return (_jsxs("div", { ref: mergedRef, role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": locked ? lockedDescId : undefined, "aria-disabled": locked || undefined, className: cx('tui-move-handle', `is-size-${size}`, locked && 'is-locked', hasIndex && 'has-index', className), children: [locked && (_jsx("span", { id: lockedDescId, className: "tui-visually-hidden", children: resolvedLockedDesc })), onMoveUp && (_jsx("button", { type: "button", className: "tui-move-handle__up", "data-direction": "up", "aria-label": labels?.moveUp ?? 'Move up', disabled: locked || !canMoveUp, onClick: onMoveUp, children: _jsx(Icon, { name: "system/chevron-up" }) })), _jsx("div", { className: "tui-move-handle__center", children: showLockIcon ? (_jsx("span", { className: "tui-move-handle__lock", "aria-hidden": "true", children: _jsx(Icon, { name: "system/lock" }) })) : (_jsxs(_Fragment, { children: [hasIndex && (_jsx("span", { className: "tui-move-handle__index", "aria-hidden": "true", children: index })), _jsx("button", { type: "button", className: "tui-move-handle__handle", "data-role": "drag-handle", "aria-label": resolvedDragLabel, tabIndex: hasArrows ? -1 : 0, ...restDragProps, children: _jsx(Icon, { name: "system/handle-alt" }) })] })) }), onMoveDown && (_jsx("button", { type: "button", className: "tui-move-handle__down", "data-direction": "down", "aria-label": labels?.moveDown ?? 'Move down', disabled: locked || !canMoveDown, onClick: onMoveDown, children: _jsx(Icon, { name: "system/chevron-down" }) }))] }));
-});
+}));

package/components/MultiSelect/MultiSelect.js

@@ -22,6 +22,8 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
     // Option registration
     const optionsRef = useRef(new Map());
     const [registryVersion, setRegistryVersion] = useState(0);
+    // Track open state via ref so unregisterOption can check synchronously
+    const openRef = useRef(false);
     // Is selected helper
     const isSelected = useCallback((optionValue) => {
         const key = toKey(optionValue);
@@ -106,6 +108,7 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
     const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen ?? false);
     const isOpenControlled = controlledOpen !== undefined;
     const open = isOpenControlled ? controlledOpen : uncontrolledOpen;
+    openRef.current = open;
     const setOpen = useCallback((nextOpen) => {
         if (disabled)
             return;
@@ -210,11 +213,25 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
         typeahead,
     ]);
     // Register option
+    // Flag: first registerOption call after open clears stale entries.
+    const prevOpenForFlush = useRef(open);
+    const needsFlushRef = useRef(false);
+    if (open && !prevOpenForFlush.current)
+        needsFlushRef.current = true;
+    prevOpenForFlush.current = open;
     const registerOption = useCallback((option) => {
+        if (needsFlushRef.current) {
+            optionsRef.current.clear();
+            needsFlushRef.current = false;
+        }
         optionsRef.current.set(toKey(option.value), option);
         setRegistryVersion((v) => v + 1);
     }, []);
     const unregisterOption = useCallback((optionValue) => {
+        // Skip when closing — preserve registry for chip display text.
+        // Options re-register on next open (same keys).
+        if (!openRef.current)
+            return;
         optionsRef.current.delete(toKey(optionValue));
         setRegistryVersion((v) => v + 1);
     }, []);
@@ -447,7 +464,7 @@ function MultiSelectTriggerComponent({ asChild = false, className, children, })
         'aria-describedby': ariaDescribedBy,
         'aria-haspopup': 'listbox',
         'aria-expanded': open,
-        'aria-controls': listboxId,
+        'aria-controls': open ? listboxId : undefined,
         'aria-keyshortcuts': hasSelection && !open ? 'Delete' : undefined,
         'data-state': open ? 'open' : 'closed',
         ...floatingProps,
@@ -479,7 +496,7 @@ function MultiSelectTriggerComponent({ asChild = false, className, children, })
                     ref: refs.setReference,
                     'aria-haspopup': 'listbox',
                     'aria-expanded': open,
-                    'aria-controls': listboxId,
+                    'aria-controls': open ? listboxId : undefined,
                     'aria-activedescendant': floatingProps['aria-activedescendant'],
                     'aria-describedby': ariaDescribedBy,
                     // asChild: use aria-disabled + data-disabled since element may not support native disabled
@@ -507,7 +524,7 @@ function MultiSelectTriggerComponent({ asChild = false, className, children, })
     }
     // Default: render button with optional custom content
     const triggerContent = children ?? defaultTriggerContent;
-    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: refs.setReference, type: "button", id: triggerId, className: cx('tui-multiselect__trigger', sizeClass, className), disabled: disabled, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": listboxId, "data-state": open ? 'open' : 'closed', ...floatingProps, 
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: refs.setReference, type: "button", id: triggerId, className: cx('tui-multiselect__trigger', sizeClass, className), disabled: disabled, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? listboxId : undefined, "data-state": open ? 'open' : 'closed', ...floatingProps, 
                 // Handle Backspace/Delete AFTER floatingProps to ensure we catch it
                 // (typeahead may intercept these for its buffer)
                 onKeyDown: (e) => {
@@ -528,13 +545,19 @@ MultiSelectTriggerComponent.displayName = 'MultiSelect.Trigger';
 function MultiSelectContentComponent({ className, children }) {
     const { open, listboxId, triggerId, refs, floatingStyles, getFloatingProps, listRef, activeIndex, orderedOptions, } = useMultiSelectContext();
     const portalRoot = getPortalRootFor(refs.reference.current);
+    // Track whether dropdown has ever been opened. Before first open, mount
+    // children in a hidden div for option registration. After first open,
+    // only mount children when open (in portal).
+    const hasEverOpened = useRef(false);
+    if (open)
+        hasEverOpened.current = true;
     // Memoized context for options
     const contentContext = useMemo(() => ({
         listRef,
         activeIndex,
         orderedOptions,
     }), [listRef, activeIndex, orderedOptions]);
-    return (_jsxs(_Fragment, { children: [!open && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(MultiSelectContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": triggerId, "aria-multiselectable": "true", className: cx('tui-multiselect__content', className), style: {
+    return (_jsxs(_Fragment, { children: [!open && !hasEverOpened.current && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(MultiSelectContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": triggerId, "aria-multiselectable": "true", className: cx('tui-multiselect__content', className), style: {
                         ...floatingStyles,
                         minWidth: refs.reference.current?.offsetWidth,
                         pointerEvents: 'auto',

package/components/Progress/Progress.d.ts

@@ -1,2 +1,3 @@
+import React from 'react';
 import type { ProgressProps } from './types';
-export declare function Progress(props: ProgressProps): import("react/jsx-runtime").JSX.Element;
+export declare const Progress: React.NamedExoticComponent<ProgressProps>;

package/components/Progress/Progress.js

@@ -1,12 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import React from 'react';
+import React, { memo } from 'react';
 import { useProgressSegments } from './useProgressSegments.js';
 import { cx } from '../../utils/cx.js';
 import { isDev } from '../../utils/is-dev.js';
 // =============================================================================
 // COMPONENT
 // =============================================================================
-export function Progress(props) {
+export const Progress = memo(function Progress(props) {
     const { children, mode = 'line', size = 'md', max = 100, showLabels = true, 'aria-labelledby': labelledBy, 'aria-label': ariaLabel, defaultLabel, className, } = props;
     // Determine mode
     const isSegmented = 'segments' in props && Array.isArray(props.segments);
@@ -98,4 +98,4 @@ export function Progress(props) {
     // Above/below/inline positions: render labels outside the track
     const labelRow = (_jsxs("div", { className: "tui-progress__labels", children: [labelStart && _jsx("span", { className: "tui-progress__label is-start", children: labelStart }), labelEnd && _jsx("span", { className: "tui-progress__label is-end", children: labelEnd })] }));
     return (_jsxs("div", { ...rootProps, children: [labelPosition === 'above' && labelRow, labelPosition === 'inline' ? (_jsxs("div", { className: "tui-progress__inline", children: [labelStart && _jsx("span", { className: "tui-progress__label is-start", children: labelStart }), trackContent, labelEnd && _jsx("span", { className: "tui-progress__label is-end", children: labelEnd })] })) : (trackContent), labelPosition === 'below' && labelRow, !labelledBy && !ariaLabel && defaultLabel && (_jsx("span", { className: "visually-hidden", children: defaultLabel }))] }));
-}
+});

package/components/Select/Select.js

@@ -22,6 +22,8 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
     // Option registration
     const optionsRef = useRef(new Map());
     const [registryVersion, setRegistryVersion] = useState(0);
+    // Track open state via ref so unregisterOption can check synchronously
+    const openRef = useRef(false);
     const setValue = useCallback((newValue, textValue) => {
         if (!isValueControlled) {
             setUncontrolledValue(newValue);
@@ -55,6 +57,7 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
     const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen ?? false);
     const isOpenControlled = controlledOpen !== undefined;
     const open = isOpenControlled ? controlledOpen : uncontrolledOpen;
+    openRef.current = open;
     // Guard flag: when Backspace/Delete clears a closed Select, Floating UI's
     // composed handlers (useTypeahead/useListNavigation) also fire and call
     // setOpen(true). This ref rejects that open request within the same microtask.
@@ -182,12 +185,30 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
         listNavigation,
         typeahead,
     ]);
+    // Flag: when the dropdown opens, the first registerOption call clears the
+    // registry before adding. This ensures stale entries from options that changed
+    // while closed don't persist — and avoids a useLayoutEffect ordering issue
+    // where a parent clear would run after children register.
+    const prevOpenForFlush = useRef(open);
+    const needsFlushRef = useRef(false);
+    if (open && !prevOpenForFlush.current)
+        needsFlushRef.current = true;
+    prevOpenForFlush.current = open;
     // Register option (stable callback - no value/displayText deps)
     const registerOption = useCallback((option) => {
+        if (needsFlushRef.current) {
+            optionsRef.current.clear();
+            needsFlushRef.current = false;
+        }
         optionsRef.current.set(toKey(option.value), option);
         setRegistryVersion((v) => v + 1);
     }, []);
     const unregisterOption = useCallback((optionValue) => {
+        // When the dropdown closes, options unmount and call unregister in cleanup.
+        // Skip the delete to preserve the registry — displayText and typeahead
+        // depend on it while closed. Options re-register on next open (same keys).
+        if (!openRef.current)
+            return;
         optionsRef.current.delete(toKey(optionValue));
         setRegistryVersion((v) => v + 1);
     }, []);
@@ -355,6 +376,10 @@ function SelectTriggerComponent({ asChild = false, className, children, }) {
         'aria-keyshortcuts': clearable && hasValue ? 'Delete' : undefined,
         'data-state': open ? 'open' : 'closed',
         ...floatingProps,
+        // Override Floating UI's aria-controls — only reference the listbox when
+        // it's actually in the DOM. After first open, the listbox unmounts when
+        // closed to save hooks. A phantom aria-controls violates ARIA 1.2.
+        'aria-controls': open ? floatingProps['aria-controls'] : undefined,
     };
     if (asChild && isValidElement(children)) {
         const childProps = children.props;
@@ -382,7 +407,7 @@ function SelectTriggerComponent({ asChild = false, className, children, }) {
             ref: refs.setReference,
             'aria-haspopup': floatingProps['aria-haspopup'],
             'aria-expanded': floatingProps['aria-expanded'],
-            'aria-controls': floatingProps['aria-controls'],
+            'aria-controls': open ? floatingProps['aria-controls'] : undefined,
             'aria-activedescendant': floatingProps['aria-activedescendant'],
             'aria-describedby': ariaDescribedBy,
             // asChild: use aria-disabled + data-disabled since element may not support native disabled
@@ -411,6 +436,12 @@ SelectTriggerComponent.displayName = 'Select.Trigger';
 function SelectContentComponent({ className, children, }) {
     const { open, listboxId, triggerId, refs, floatingStyles, getFloatingProps, listRef, activeIndex, handleSelect, orderedOptions, optionIndexMap, } = useSelectContext();
     const portalRoot = getPortalRootFor(refs.reference.current);
+    // Track whether dropdown has ever been opened. Before first open, mount
+    // children in a hidden div for option registration (defaultValue resolution).
+    // After first open, only mount children when open (in portal).
+    const hasEverOpened = useRef(false);
+    if (open)
+        hasEverOpened.current = true;
     // Memoized context for options
     const contentContext = useMemo(() => ({
         listRef,
@@ -419,7 +450,7 @@ function SelectContentComponent({ className, children, }) {
         orderedOptions,
         optionIndexMap,
     }), [listRef, activeIndex, handleSelect, orderedOptions, optionIndexMap]);
-    return (_jsxs(_Fragment, { children: [!open && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(SelectContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": triggerId, className: cx('tui-select__content', className), style: {
+    return (_jsxs(_Fragment, { children: [!open && !hasEverOpened.current && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(SelectContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": triggerId, className: cx('tui-select__content', className), style: {
                         ...floatingStyles,
                         minWidth: refs.reference.current?.offsetWidth,
                         pointerEvents: 'auto',

package/components/StepIndicator/StepIndicator.d.ts

@@ -1,2 +1,2 @@
 import type { StepIndicatorProps } from './types';
-export declare function StepIndicator(props: StepIndicatorProps): import("react/jsx-runtime").JSX.Element;
+export declare const StepIndicator: import("react").NamedExoticComponent<StepIndicatorProps>;

package/components/StepIndicator/StepIndicator.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo } from 'react';
 import { defaultStepIndicatorLabels } from './types.js';
 import { Progress } from '../Progress/index.js';
 import { Icon } from '../Icon/index.js';
@@ -22,7 +23,7 @@ function inferStatus(value) {
 // =============================================================================
 // Component
 // =============================================================================
-export function StepIndicator(props) {
+export const StepIndicator = memo(function StepIndicator(props) {
     const { value = 0, status: statusOverride, icon: customIcon, size = 'sm', showValue = false, label, className, labels: labelsProp, } = props;
     const labels = { ...defaultStepIndicatorLabels, ...labelsProp };
     // Infer status from value, allow override
@@ -64,4 +65,4 @@ export function StepIndicator(props) {
         .filter(Boolean)
         .join(' ');
     return (_jsx("div", { className: rootClassName, children: _jsxs(Progress, { mode: "circle", variant: variant, size: size, value: displayValue, showLabels: showValue || hasIcon, labelPosition: "inside", "aria-label": ariaLabel, children: [hasIcon && iconName && (_jsx(Icon, { name: iconName })), showValue && status === 'in-progress' && (_jsxs("span", { className: "tui-step-indicator__value", children: [Math.round(displayValue), "%"] }))] }) }));
-}
+});

package/components/Tooltip/Tooltip.d.ts

@@ -2,7 +2,7 @@ import type { TooltipProviderProps, TooltipProps, TooltipTriggerProps, TooltipCo
 declare function TooltipProviderComponent({ delayDuration, closeDelayDuration, children, }: TooltipProviderProps): import("react/jsx-runtime").JSX.Element;
 declare function TooltipRoot({ open: controlledOpen, onOpenChange, defaultOpen, delayDuration: localDelay, children, }: TooltipProps): import("react/jsx-runtime").JSX.Element;
 declare function TooltipTriggerComponent({ asChild, 'aria-label': ariaLabel, children, }: TooltipTriggerProps): import("react/jsx-runtime").JSX.Element;
-declare function TooltipContentComponent({ side, align, sideOffset, theme, className, children, }: TooltipContentProps): import("react/jsx-runtime").JSX.Element | null;
+declare function TooltipContentComponent(props: TooltipContentProps): import("react/jsx-runtime").JSX.Element | null;
 type TooltipCompound = typeof TooltipRoot & {
     Provider: typeof TooltipProviderComponent;
     Trigger: typeof TooltipTriggerComponent;

package/components/Tooltip/Tooltip.js

@@ -120,12 +120,22 @@ function TooltipTriggerComponent({ asChild = false, 'aria-label': ariaLabel, chi
 // =============================================================================
 // TooltipContent
 // =============================================================================
-function TooltipContentComponent({ side = 'top', align = 'center', sideOffset = 8, theme = 'dark', className, children, }) {
-    const { open, setOpen, triggerRef, contentId, cancelClose, handleClose } = useTooltipContext();
+// Gate component: reads context to decide whether to mount the real content.
+// This ensures useFloating and all other hooks in TooltipContentInner only
+// run when the tooltip is actually open — not on every render cycle.
+function TooltipContentComponent(props) {
+    const { open } = useTooltipContext();
+    if (!open)
+        return null;
+    return _jsx(TooltipContentInner, { ...props });
+}
+// Inner component: only mounted when open. All Floating UI hooks live here.
+function TooltipContentInner({ side = 'top', align = 'center', sideOffset = 8, theme = 'dark', className, children, }) {
+    const { setOpen, triggerRef, contentId, cancelClose, handleClose } = useTooltipContext();
     const arrowRef = useRef(null);
     const { refs, floatingStyles, context } = useFloating({
         placement: toPlacement(side, align),
-        open,
+        open: true, // Always true when mounted (gate handles the conditional)
         middleware: [
             offset(sideOffset),
             flip(),
@@ -145,8 +155,6 @@ function TooltipContentComponent({ side = 'top', align = 'center', sideOffset =
     // - Focus on trigger: close + stopPropagation (avoid closing parent modal)
     // - Hover-only (focus elsewhere): close without stopPropagation
     useEffect(() => {
-        if (!open)
-            return;
         const handleKeyDown = (e) => {
             if (e.key === 'Escape') {
                 const activeEl = document.activeElement;
@@ -160,22 +168,20 @@ function TooltipContentComponent({ side = 'top', align = 'center', sideOffset =
         };
         document.addEventListener('keydown', handleKeyDown);
         return () => document.removeEventListener('keydown', handleKeyDown);
-    }, [open, setOpen, triggerRef]);
+    }, [setOpen, triggerRef]);
     // Get portal root inside .tui-interface
     const portalRoot = getPortalRootFor(triggerRef.current);
     // Dev warning: tooltips should not contain interactive content (WCAG 1.4.13)
     // Use Popover for interactive overlays instead
     useEffect(() => {
-        if (isDev() && open && refs.floating.current) {
+        if (isDev() && refs.floating.current) {
             const interactive = refs.floating.current.querySelectorAll('a, button, input, select, textarea, [tabindex]:not([tabindex="-1"])');
             if (interactive.length > 0) {
                 console.warn('[Tooltip] Contains interactive elements which violates WCAG 1.4.13. ' +
                     'Tooltips should only contain plain text. Use Popover for interactive content.');
             }
         }
-    }, [open, refs.floating]);
-    if (!open)
-        return null;
+    }, [refs.floating]);
     return (_jsx(FloatingPortal, { root: portalRoot, children: _jsxs("div", { ref: refs.setFloating, id: contentId, role: "tooltip", className: cx('tui-tooltip', theme === 'light' && 'is-theme-light', className), style: floatingStyles, onMouseEnter: cancelClose, onMouseLeave: handleClose, children: [children, _jsx(FloatingArrow, { ref: arrowRef, context: context, className: "tui-tooltip__arrow" })] }) }));
 }
 export const Tooltip = TooltipRoot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangible/ui",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Tangible Design System",
   "type": "module",
   "main": "./components/index.js",

package/tui-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.0.8",
-  "generated": "2026-03-17T20:49:24.034Z",
+  "version": "0.0.10",
+  "generated": "2026-03-19T23:08:17.377Z",
   "components": {
     "Accordion": {
       "props": {
@@ -110,13 +110,11 @@
         "size": {
           "type": "\"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\" | \"xxl\"",
           "required": false,
-          "defaultValue": "md",
           "description": "Size of the avatar"
         },
         "shape": {
           "type": "\"circle\" | \"square\"",
           "required": false,
-          "defaultValue": "circle",
           "description": "Shape of the avatar"
         },
         "indicator": {
@@ -132,7 +130,6 @@
         "indicatorPosition": {
           "type": "\"top-left\" | \"top-right\" | \"bottom-left\" | \"bottom-right\"",
           "required": false,
-          "defaultValue": "bottom-right",
           "description": "Position of the indicator"
         },
         "tooltip": {
@@ -1208,6 +1205,11 @@
         "size": {
           "type": "\"sm\" | \"md\" | \"lg\"",
           "required": false
+        },
+        "preventScrollOnRestore": {
+          "type": "boolean",
+          "required": false,
+          "description": "When true, prevents the browser from scrolling to the trigger element\nwhen focus is restored on close. Useful when the trigger may be off-screen\ninside a scrollable container. Default: false."
         }
       },
       "cssTokens": [
@@ -1277,13 +1279,11 @@
         "mode": {
           "type": "\"full\" | \"handle\"",
           "required": false,
-          "defaultValue": "full",
           "description": "Structural mode. 'full' (default) shows background panel with arrows/index. 'handle' shows only the bare drag icon button."
         },
         "size": {
           "type": "\"sm\" | \"md\"",
           "required": false,
-          "defaultValue": "md",
           "description": "Component scale. Full mode: sm = 32px, md = 40px. Handle mode: sm = 24px, md = 32px."
         },
         "index": {
@@ -1294,19 +1294,16 @@
         "locked": {
           "type": "boolean",
           "required": false,
-          "defaultValue": "false",
           "description": "When true, shows lock icon and disables all interaction."
         },
         "canMoveUp": {
           "type": "boolean",
           "required": false,
-          "defaultValue": "true",
           "description": "When false, disables the move-up button without hiding it. Default: true."
         },
         "canMoveDown": {
           "type": "boolean",
           "required": false,
-          "defaultValue": "true",
           "description": "When false, disables the move-down button without hiding it. Default: true."
         },
         "labels": {