@tangible/ui 0.0.3 → 0.0.5

package/components/Chip/Chip.d.ts

@@ -5,6 +5,15 @@ type Size = SizeCompact;
 type Theme = ThemeFull;
 type Variant = 'default' | 'outline' | 'ghost' | 'solid' | 'flush';
 export type ChipProps = {
+    /**
+     * HTML element to render.
+     * - `'span'` (default): Inline element. Use for chips within text flow,
+     *   inline lists, or inside `<p>`/`<li>` elements.
+     * - `'div'`: Block element. Use when the chip contains block-level content
+     *   or needs to be a flex/grid child without inline constraints.
+     * - `'a'`: Anchor element. Use for navigational chips with an `href`.
+     * @default 'span'
+     */
     as?: 'span' | 'div' | 'a';
     href?: string;
     target?: React.HTMLAttributeAnchorTarget;
@@ -23,5 +32,32 @@ export type ChipProps = {
     /** When inside ChipGroup, identifies this chip for selection tracking */
     value?: OptionValue;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, 'onClick'>;
-export declare function Chip({ as, href, target, rel, children, size, theme, variant, selected: selectedProp, disabled: disabledProp, interactive, className, leftIcon, rightIcon, onClick: onClickProp, value, ...rest }: ChipProps): import("react/jsx-runtime").JSX.Element;
+export declare const Chip: React.ForwardRefExoticComponent<{
+    /**
+     * HTML element to render.
+     * - `'span'` (default): Inline element. Use for chips within text flow,
+     *   inline lists, or inside `<p>`/`<li>` elements.
+     * - `'div'`: Block element. Use when the chip contains block-level content
+     *   or needs to be a flex/grid child without inline constraints.
+     * - `'a'`: Anchor element. Use for navigational chips with an `href`.
+     * @default 'span'
+     */
+    as?: "span" | "div" | "a";
+    href?: string;
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    children: React.ReactNode;
+    size?: Size;
+    theme?: Theme;
+    variant?: Variant;
+    selected?: boolean;
+    disabled?: boolean;
+    interactive?: boolean;
+    className?: string;
+    leftIcon?: React.ReactNode;
+    rightIcon?: React.ReactNode;
+    onClick?: React.MouseEventHandler<HTMLElement>;
+    /** When inside ChipGroup, identifies this chip for selection tracking */
+    value?: OptionValue;
+} & Omit<React.HTMLAttributes<HTMLSpanElement>, "onClick"> & React.RefAttributes<HTMLElement>>;
 export {};

package/components/Chip/Chip.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
-import { useCallback, useEffect } from 'react';
+import { useCallback, useEffect, forwardRef } from 'react';
 import { cx } from '../../utils/cx.js';
 import { toKey } from '../../utils/value-key.js';
 import { isDev } from '../../utils/is-dev.js';
 import { useChipGroupContext } from '../ChipGroup/ChipGroupContext.js';
-export function Chip({ as = 'span', href, target, rel, children, size = 'md', theme = 'secondary', variant = 'default', selected: selectedProp, disabled: disabledProp, interactive, className, leftIcon, rightIcon, onClick: onClickProp, value, ...rest }) {
+export const Chip = forwardRef(function Chip({ as = 'span', href, target, rel, children, size = 'md', theme = 'secondary', variant = 'default', selected: selectedProp, disabled: disabledProp, interactive, className, leftIcon, rightIcon, onClick: onClickProp, value, ...rest }, ref) {
     const groupContext = useChipGroupContext();
     // Dev warning: inside ChipGroup without value
     useEffect(() => {
@@ -25,7 +25,7 @@ export function Chip({ as = 'span', href, target, rel, children, size = 'md', th
     const onClick = isManaged ? managedClick : onClickProp;
     const Tag = (as === 'a' ? 'a' : as);
     // Determine if this chip is clickable (needs button semantics)
-    const isClickable = (interactive || onClick || isManaged) && !disabled;
+    const isClickable = (!!onClick || isManaged) && !disabled;
     // Keyboard handler for interactive chips
     const handleKeyDown = useCallback((e) => {
         if (!isClickable || !onClick)
@@ -38,7 +38,7 @@ export function Chip({ as = 'span', href, target, rel, children, size = 'md', th
     const classes = cx('tui-chip', size && `is-size-${size}`, theme && `is-theme-${theme}`, variant !== 'default' && `is-style-${variant}`, selected && 'is-selected', (interactive || isManaged) && 'is-interactive', className);
     const anchorProps = as === 'a'
         ? {
-            href: disabled ? undefined : href ?? '#',
+            href: disabled || isManaged ? undefined : href ?? '#',
             target,
             rel,
             'aria-disabled': disabled || undefined,
@@ -49,14 +49,16 @@ export function Chip({ as = 'span', href, target, rel, children, size = 'md', th
     // Non-anchor clickable chips always need role="button".
     // Managed anchor chips also get role="button" — toggle semantics
     // take priority over link semantics inside a ChipGroup.
-    const needsButtonRole = isClickable && (as !== 'a' || isManaged);
+    // Disabled managed chips keep role="button" so they remain visible to AT.
+    const needsButtonRole = (isClickable || (isManaged && disabled)) && (as !== 'a' || isManaged);
     const buttonProps = needsButtonRole
         ? {
             role: 'button',
-            tabIndex: as !== 'a' ? 0 : undefined, // anchors are natively focusable
+            tabIndex: disabled ? -1 : (as !== 'a' ? 0 : undefined),
             onKeyDown: handleKeyDown,
             'aria-pressed': isManaged ? (selected ?? false) : undefined,
+            'aria-disabled': disabled || undefined,
         }
         : {};
-    return (_jsxs(Tag, { className: classes, ...anchorProps, ...buttonProps, onClick: disabled ? undefined : onClick, ...rest, children: [leftIcon && leftIcon, _jsx("span", { className: "tui-chip__text", children: children }), rightIcon && rightIcon] }));
-}
+    return (_jsxs(Tag, { ref: ref, className: classes, ...anchorProps, ...buttonProps, onClick: disabled ? undefined : onClick, ...rest, children: [leftIcon && leftIcon, _jsx("span", { className: "tui-chip__text", children: children }), rightIcon && rightIcon] }));
+});

package/components/ChipGroup/ChipGroup.js

@@ -1,5 +1,5 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo } from 'react';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useMemo } from 'react';
 import { cx } from '../../utils/cx.js';
 import { useControllableState } from '../../utils/use-controllable-state.js';
 import { toKey } from '../../utils/value-key.js';
@@ -17,7 +17,7 @@ import { isDev } from '../../utils/is-dev.js';
 //
 // =============================================================================
 export function ChipGroup(props) {
-    const { multiple = false, disabled = false, density = 'sm', direction = 'inline', alignment, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, } = props;
+    const { multiple = false, disabled = false, density = 'sm', direction = 'inline', alignment, multipleLabel = 'Multiple selections allowed', 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, } = props;
     // --- Single mode ---
     // isControlled override: 'value' in props detects explicit value={undefined}
     // (deselection) vs prop not passed at all (uncontrolled).
@@ -57,12 +57,13 @@ export function ChipGroup(props) {
         }
     }, [multiple, setSingleValue, setMultiValue]);
     const contextValue = useMemo(() => ({ selectedValues, multiple, disabled, onSelect }), [selectedValues, multiple, disabled, onSelect]);
+    const descriptionId = useId();
     // Dev-only: warn if group has no accessible name
     useEffect(() => {
         if (isDev() && !ariaLabel && !ariaLabelledBy) {
             console.warn('ChipGroup: Missing accessible name. Provide aria-label or aria-labelledby.');
         }
     }, [ariaLabel, ariaLabelledBy]);
-    return (_jsx(ChipGroupContext.Provider, { value: contextValue, children: _jsx("div", { role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className: cx('tui-chip-group', `is-density-${density}`, direction === 'stack' && 'is-direction-stack', alignment && `is-align-${alignment}`, className), children: children }) }));
+    return (_jsx(ChipGroupContext.Provider, { value: contextValue, children: _jsxs("div", { role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-disabled": disabled || undefined, "aria-describedby": multiple ? descriptionId : undefined, className: cx('tui-chip-group', `is-density-${density}`, direction === 'stack' && 'is-direction-stack', alignment && `is-align-${alignment}`, className), children: [children, multiple && (_jsx("span", { id: descriptionId, className: "tui-visually-hidden", children: multipleLabel }))] }) }));
 }
 ChipGroup.displayName = 'ChipGroup';

package/components/ChipGroup/types.d.ts

@@ -8,6 +8,9 @@ type ChipGroupBaseProps = {
     direction?: 'inline' | 'stack';
     /** Alignment along main axis. */
     alignment?: 'start' | 'center' | 'end';
+    /** Visually hidden label describing multi-select behaviour. For i18n support.
+     *  @default 'Multiple selections allowed' */
+    multipleLabel?: string;
     'aria-label'?: string;
     'aria-labelledby'?: string;
     className?: string;

package/components/Dropdown/Dropdown.d.ts

@@ -1,4 +1,4 @@
-import type { DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps } from './types';
+import type { DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps, DropdownSeparatorProps, DropdownHeaderProps } from './types';
 declare function DropdownRoot({ open: controlledOpen, onOpenChange, defaultOpen, children, }: DropdownProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownRoot {
     var displayName: string;
@@ -19,13 +19,31 @@ declare function DropdownItemComponent({ onSelect, href, target, disabled, keepO
 declare namespace DropdownItemComponent {
     var displayName: string;
 }
+/**
+ * Non-interactive separator for visually grouping menu items.
+ */
+declare function DropdownSeparatorComponent({ className }: DropdownSeparatorProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownSeparatorComponent {
+    var displayName: string;
+}
+/**
+ * Non-interactive section label for grouping menu items.
+ */
+declare function DropdownHeaderComponent({ className, children }: DropdownHeaderProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownHeaderComponent {
+    var displayName: string;
+}
 type DropdownCompound = typeof DropdownRoot & {
     Trigger: typeof DropdownTriggerComponent;
     Content: typeof DropdownContentComponent;
     Item: typeof DropdownItemComponent;
+    Separator: typeof DropdownSeparatorComponent;
+    Header: typeof DropdownHeaderComponent;
 };
 export declare const Dropdown: DropdownCompound;
 export declare const DropdownTrigger: typeof DropdownTriggerComponent;
 export declare const DropdownContent: typeof DropdownContentComponent;
 export declare const DropdownItem: typeof DropdownItemComponent;
+export declare const DropdownSeparator: typeof DropdownSeparatorComponent;
+export declare const DropdownHeader: typeof DropdownHeaderComponent;
 export { useDropdownContext as useDropdown } from './DropdownContext';

package/components/Dropdown/Dropdown.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { useCallback, useEffect, useId, useMemo, useRef, useState, cloneElement, isValidElement, Children, } from 'react';
+import React, { useCallback, useEffect, useLayoutEffect, useId, useMemo, useRef, useState, cloneElement, isValidElement, Children, } from 'react';
 import { useFloating, offset, flip, shift, autoUpdate, FloatingPortal, useDismiss, useInteractions, useListNavigation, useRole, FloatingFocusManager, } from '@floating-ui/react';
 import { cx } from '../../utils/cx.js';
 import { getPortalRootFor } from '../../utils/portal.js';
@@ -25,6 +25,7 @@ function DropdownRoot({ open: controlledOpen, onOpenChange, defaultOpen = false,
     }, [isControlled, onOpenChange]);
     const triggerRef = useRef(null);
     const contentId = useId();
+    const openedVia = useRef(null);
     // Focus restoration: track if we need to restore focus on close
     const shouldRestoreFocus = useRef(false);
     const prevOpen = useRef(open);
@@ -47,6 +48,7 @@ function DropdownRoot({ open: controlledOpen, onOpenChange, defaultOpen = false,
         contentId,
         activeIndex,
         setActiveIndex,
+        openedVia,
     }), [open, setOpen, contentId, activeIndex]);
     return (_jsx(DropdownContext.Provider, { value: contextValue, children: children }));
 }
@@ -55,24 +57,28 @@ DropdownRoot.displayName = 'Dropdown';
 // DropdownTrigger
 // =============================================================================
 function DropdownTriggerComponent({ asChild = false, children }) {
-    const { open, setOpen, triggerRef, contentId } = useDropdownContext();
+    const { open, setOpen, triggerRef, openedVia } = useDropdownContext();
     const handleClick = useCallback(() => {
+        openedVia.current = 'click';
         setOpen(!open);
-    }, [open, setOpen]);
+    }, [open, setOpen, openedVia]);
     const handleKeyDown = useCallback((e) => {
         if (e.key === 'Enter' || e.key === ' ') {
             e.preventDefault();
+            openedVia.current = 'click';
             setOpen(!open);
         }
         else if (e.key === 'ArrowDown') {
             e.preventDefault();
+            openedVia.current = 'ArrowDown';
             setOpen(true);
         }
         else if (e.key === 'ArrowUp') {
             e.preventDefault();
+            openedVia.current = 'ArrowUp';
             setOpen(true);
         }
-    }, [open, setOpen]);
+    }, [open, setOpen, openedVia]);
     // Merge child ref with our triggerRef
     const setRefs = useCallback((node) => {
         triggerRef.current = node;
@@ -91,7 +97,6 @@ function DropdownTriggerComponent({ asChild = false, children }) {
         onKeyDown: handleKeyDown,
         'aria-haspopup': 'menu',
         'aria-expanded': open,
-        'aria-controls': open ? contentId : undefined,
         'data-dropdown-open': open || undefined,
     };
     if (asChild && isValidElement(children)) {
@@ -108,7 +113,7 @@ DropdownTriggerComponent.displayName = 'Dropdown.Trigger';
 // DropdownContent
 // =============================================================================
 function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset = 4, className, style, children, }) {
-    const { open, setOpen, triggerRef, contentId, activeIndex, setActiveIndex } = useDropdownContext();
+    const { open, setOpen, triggerRef, contentId, activeIndex, setActiveIndex, openedVia } = useDropdownContext();
     const listRef = useRef([]);
     const { refs, floatingStyles, context } = useFloating({
         placement: toPlacement(side, align),
@@ -123,19 +128,41 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
             refs.setReference(triggerRef.current);
         }
     }, [triggerRef, refs]);
-    // Collect disabled indices from children for keyboard navigation
-    const disabledIndices = useMemo(() => {
-        const indices = [];
-        Children.forEach(children, (child, index) => {
-            if (isValidElement(child)) {
-                const props = child.props;
-                if (props.disabled) {
-                    indices.push(index);
-                }
+    // Classify children: count navigable items and collect disabled indices.
+    // Separator and Header sub-components are non-navigable.
+    const { disabledIndices, totalItemCount } = useMemo(() => {
+        const disabled = [];
+        let itemIdx = 0;
+        Children.forEach(children, (child) => {
+            if (!isValidElement(child))
+                return;
+            // Skip non-navigable sub-components
+            const childType = child.type;
+            if (childType === DropdownSeparatorComponent ||
+                childType === DropdownHeaderComponent) {
+                return;
             }
+            const props = child.props;
+            if (props.disabled) {
+                disabled.push(itemIdx);
+            }
+            itemIdx++;
         });
-        return indices;
+        return { disabledIndices: disabled, totalItemCount: itemIdx };
     }, [children]);
+    // ArrowUp focus-last: set activeIndex to last valid item before paint
+    useLayoutEffect(() => {
+        if (open && openedVia.current === 'ArrowUp') {
+            let lastValid = totalItemCount - 1;
+            while (lastValid >= 0 && disabledIndices.includes(lastValid)) {
+                lastValid--;
+            }
+            if (lastValid >= 0) {
+                setActiveIndex(lastValid);
+            }
+            openedVia.current = null;
+        }
+    }, [open, openedVia, totalItemCount, disabledIndices, setActiveIndex]);
     const dismiss = useDismiss(context);
     const role = useRole(context, { role: 'menu' });
     const listNavigation = useListNavigation(context, {
@@ -155,25 +182,34 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
     const portalRoot = getPortalRootFor(triggerRef.current);
     if (!open)
         return null;
-    // Clone children to inject item props and role
-    const items = Children.map(children, (child, index) => {
+    // Clone children to inject item props and role.
+    // Non-navigable children (Separator, Header) are rendered as-is.
+    let itemIndex = 0;
+    const items = Children.map(children, (child) => {
         if (!isValidElement(child))
             return child;
+        // Non-navigable sub-components — render without list navigation props
+        const childType = child.type;
+        if (childType === DropdownSeparatorComponent ||
+            childType === DropdownHeaderComponent) {
+            return child;
+        }
+        const currentIndex = itemIndex++;
         const childProps = child.props;
         const isDisabled = childProps.disabled === true;
         const existingRole = childProps.role;
         return cloneElement(child, {
             ...getItemProps({
                 ref: (node) => {
-                    listRef.current[index] = node;
+                    listRef.current[currentIndex] = node;
                 },
                 // Disabled items get tabIndex -1 always
-                tabIndex: isDisabled ? -1 : (activeIndex === index ? 0 : -1),
+                tabIndex: isDisabled ? -1 : (activeIndex === currentIndex ? 0 : -1),
             }),
             // Add menuitem role if not already specified
             role: existingRole || 'menuitem',
             'aria-disabled': isDisabled || undefined,
-            'data-active': activeIndex === index || undefined,
+            'data-active': activeIndex === currentIndex || undefined,
         });
     });
     return (_jsx(FloatingPortal, { root: portalRoot, children: _jsx(FloatingFocusManager, { context: context, modal: false, initialFocus: -1, children: _jsx("div", { ref: refs.setFloating, id: contentId, className: cx('tui-dropdown', className), style: {
@@ -190,31 +226,51 @@ DropdownContentComponent.displayName = 'Dropdown.Content';
  * When href is provided, renders as an anchor.
  */
 function DropdownItemComponent({ onSelect, href, target = '_self', disabled = false, keepOpen = false, className, children, ...props }) {
-    const { setOpen, triggerRef } = useDropdownContext();
+    const { setOpen } = useDropdownContext();
     const handleClick = useCallback(() => {
         if (disabled)
             return;
         onSelect?.();
         if (!keepOpen) {
+            // Focus restoration is handled by DropdownRoot's useEffect on `open`
             setOpen(false);
-            // Explicitly restore focus after programmatic close
-            // Small delay to let the dropdown unmount first
-            requestAnimationFrame(() => {
-                triggerRef.current?.focus();
-            });
         }
-    }, [disabled, onSelect, keepOpen, setOpen, triggerRef]);
+    }, [disabled, onSelect, keepOpen, setOpen]);
     return (_jsx(Button, { ...props, variant: "ghost", href: disabled ? undefined : href, target: href ? target : undefined, disabled: disabled, onClick: handleClick, className: cx('tui-dropdown__item', className), children: children }));
 }
 DropdownItemComponent.displayName = 'Dropdown.Item';
+// =============================================================================
+// DropdownSeparator
+// =============================================================================
+/**
+ * Non-interactive separator for visually grouping menu items.
+ */
+function DropdownSeparatorComponent({ className }) {
+    return (_jsx("hr", { role: "separator", className: cx('tui-dropdown__separator', className) }));
+}
+DropdownSeparatorComponent.displayName = 'Dropdown.Separator';
+// =============================================================================
+// DropdownHeader
+// =============================================================================
+/**
+ * Non-interactive section label for grouping menu items.
+ */
+function DropdownHeaderComponent({ className, children }) {
+    return (_jsx("div", { role: "presentation", className: cx('tui-dropdown__header', className), children: children }));
+}
+DropdownHeaderComponent.displayName = 'Dropdown.Header';
 export const Dropdown = DropdownRoot;
 Dropdown.Trigger = DropdownTriggerComponent;
 Dropdown.Content = DropdownContentComponent;
 Dropdown.Item = DropdownItemComponent;
+Dropdown.Separator = DropdownSeparatorComponent;
+Dropdown.Header = DropdownHeaderComponent;
 // Named exports for direct imports
 export const DropdownTrigger = DropdownTriggerComponent;
 export const DropdownContent = DropdownContentComponent;
 export const DropdownItem = DropdownItemComponent;
+export const DropdownSeparator = DropdownSeparatorComponent;
+export const DropdownHeader = DropdownHeaderComponent;
 // Hook for advanced use cases (custom items that need to close the dropdown)
 // eslint-disable-next-line react-refresh/only-export-components
 export { useDropdownContext as useDropdown } from './DropdownContext.js';

package/components/Dropdown/index.d.ts

@@ -1,2 +1,2 @@
-export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, useDropdown, } from './Dropdown';
-export type { DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps, } from './types';
+export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownSeparator, DropdownHeader, useDropdown, } from './Dropdown';
+export type { DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps, DropdownSeparatorProps, DropdownHeaderProps, } from './types';

package/components/Dropdown/index.js

@@ -1 +1 @@
-export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, useDropdown, } from './Dropdown.js';
+export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownSeparator, DropdownHeader, useDropdown, } from './Dropdown.js';

package/components/Dropdown/types.d.ts

@@ -88,6 +88,19 @@ export type DropdownItemProps = {
     className?: string;
     children: React.ReactNode;
 };
+export type DropdownSeparatorProps = {
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+};
+export type DropdownHeaderProps = {
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    children: React.ReactNode;
+};
 export type DropdownContextValue = {
     open: boolean;
     setOpen: (open: boolean) => void;
@@ -95,6 +108,8 @@ export type DropdownContextValue = {
     contentId: string;
     activeIndex: number | null;
     setActiveIndex: (index: number | null) => void;
+    /** Tracks how the dropdown was opened (e.g. 'ArrowUp') for initial focus. */
+    openedVia: React.MutableRefObject<string | null>;
 };
 /**
  * Convert side + align to Floating UI placement.

package/components/IconButton/IconButton.js

@@ -17,10 +17,11 @@ import { getSafeRel } from '../../utils/polymorphic.js';
 //
 // =============================================================================
 export const IconButton = forwardRef((props, ref) => {
-    const { icon, label, size = 'sm', theme = 'secondary', variant = 'ghost', disabled = false, loading = false, pressed, showTooltip = false, tooltipSide = 'top', className, ...rest } = props;
+    const { icon, label, size = 'sm', theme = 'secondary', variant = 'ghost', disabled = false, loading = false, loadingLabel: loadingLabelProp, pressed, shape = 'square', showTooltip = false, tooltipSide = 'top', className, ...rest } = props;
     const isLink = typeof rest.href === 'string';
     const isDisabled = disabled || loading;
-    const classes = cx('tui-icon-button', `is-size-${size}`, `is-theme-${theme}`, `is-style-${variant}`, isDisabled && 'is-disabled', className);
+    const resolvedLabel = loading ? (loadingLabelProp ?? `${label}, loading`) : label;
+    const classes = cx('tui-icon-button', `is-size-${size}`, `is-theme-${theme}`, `is-style-${variant}`, isDisabled && 'is-disabled', shape === 'circle' && 'is-shape-circle', className);
     const iconContent = (_jsxs(_Fragment, { children: [_jsx(Icon, { name: icon }), loading && _jsx("span", { className: "tui-icon-button__spinner", "aria-hidden": "true" })] }));
     // Render the base element (button or anchor)
     let element;
@@ -35,11 +36,11 @@ export const IconButton = forwardRef((props, ref) => {
             }
             onClick?.(e);
         };
-        element = (_jsx("a", { ref: ref, href: isDisabled ? undefined : href, className: classes, "aria-label": label, "aria-disabled": isDisabled || undefined, "aria-busy": loading || undefined, tabIndex: isDisabled ? -1 : tabIndex, onClick: handleClick, target: target, rel: safeRel, ...anchorRest, children: iconContent }));
+        element = (_jsx("a", { ref: ref, href: isDisabled ? undefined : href, className: classes, "aria-label": resolvedLabel, "aria-disabled": isDisabled || undefined, "aria-busy": loading || undefined, tabIndex: isDisabled ? -1 : tabIndex, onClick: handleClick, target: target, rel: safeRel, ...anchorRest, children: iconContent }));
     }
     else {
         const buttonRest = rest;
-        element = (_jsx("button", { ref: ref, type: buttonRest.type ?? 'button', className: classes, "aria-label": label, disabled: isDisabled, "aria-busy": loading || undefined, "aria-pressed": pressed, ...buttonRest, children: iconContent }));
+        element = (_jsx("button", { ref: ref, type: buttonRest.type ?? 'button', className: classes, "aria-label": resolvedLabel, disabled: isDisabled, "aria-busy": loading || undefined, "aria-pressed": pressed, ...buttonRest, children: iconContent }));
     }
     // Wrap in tooltip if requested
     if (showTooltip) {

package/components/IconButton/index.d.ts

@@ -1,2 +1,2 @@
 export { IconButton } from './IconButton';
-export type { IconButtonProps, Size, Theme, Variant } from './types';
+export type { IconButtonProps, Shape, Size, Theme, Variant } from './types';

package/components/IconButton/types.d.ts

@@ -3,6 +3,7 @@ import type { Size, ThemeIntent } from '../../types';
 export type { Size };
 export type Theme = ThemeIntent;
 export type Variant = 'solid' | 'outline' | 'ghost';
+export type Shape = 'square' | 'circle';
 type IconButtonBaseProps = {
     /**
      * Icon to display. Required — this is the button's visual content.
@@ -17,7 +18,10 @@ type IconButtonBaseProps = {
     label: string;
     /**
      * Size of the button.
-     * - `'xs'`: 24px
+     * - `'xs'`: 24px — below WCAG 2.5.8 minimum target size (24×24 CSS px).
+     *   Use only in dense, mouse-first UIs (toolbars, table rows) where touch
+     *   is not expected. Consider pairing with adequate spacing or a larger
+     *   touch target via padding/margin.
      * - `'sm'`: 32px (default)
      * - `'md'`: 40px
      * - `'lg'`: 48px
@@ -35,7 +39,9 @@ type IconButtonBaseProps = {
      * Visual style variant.
      * - `'solid'`: Filled background
      * - `'outline'`: Border only, transparent background
-     * - `'ghost'`: No border or background, icon only
+     * - `'ghost'`: No border or background, icon only — has no at-rest visual
+     *   affordance. Best suited for toolbar groups, icon bars, or other contexts
+     *   where surrounding UI makes the interactive nature obvious.
      * @default 'ghost'
      */
     variant?: Variant;
@@ -47,6 +53,11 @@ type IconButtonBaseProps = {
      * Loading state — shows spinner, disables interaction.
      */
     loading?: boolean;
+    /**
+     * Accessible label override during loading state. For i18n support.
+     * @default `${label}, loading` (English)
+     */
+    loadingLabel?: string;
     /**
      * Pressed state for toggle buttons.
      * When true, applies aria-pressed="true" and active styling.
@@ -55,8 +66,11 @@ type IconButtonBaseProps = {
     pressed?: boolean;
     /**
      * Show the label as a tooltip on hover.
-     * Since icon-only buttons have no visible text, this helps sighted
-     * users discover what the button does.
+     * Since icon-only buttons have no visible text, enabling this helps
+     * sighted users discover what the button does. Recommended for most
+     * standalone icon buttons. Can be omitted in toolbars where a shared
+     * Tooltip provider handles it, or where adjacent visible text already
+     * communicates the action.
      * @default false
      */
     showTooltip?: boolean;
@@ -65,6 +79,12 @@ type IconButtonBaseProps = {
      * @default 'top'
      */
     tooltipSide?: 'top' | 'right' | 'bottom' | 'left';
+    /**
+     * Button shape. Use `'circle'` for avatar-adjacent actions, FABs,
+     * or anywhere a round affordance is expected.
+     * @default 'square'
+     */
+    shape?: Shape;
     /**
      * Additional CSS class names.
      */

package/components/Modal/Modal.d.ts

@@ -7,6 +7,8 @@ export type ModalProps = {
     size?: Size;
     stickyHead?: boolean;
     stickyFoot?: boolean;
+    /** ID of the element that labels this dialog. Omitting this leaves the dialog
+     *  without an accessible name, which violates WCAG 4.1.2 (Name, Role, Value). */
     'aria-labelledby'?: string;
     'aria-describedby'?: string;
     initialFocusSelector?: string;
@@ -30,11 +32,23 @@ type ModalSlotProps = {
     className?: string;
     children?: React.ReactNode;
 } & React.HTMLAttributes<HTMLDivElement>;
-declare function ModalHead({ className, children, ...rest }: ModalSlotProps): import("react/jsx-runtime").JSX.Element;
+type ModalHeadProps = ModalSlotProps & {
+    /** Optional subtitle displayed below the title in smaller, muted text. */
+    subtitle?: React.ReactNode;
+    /** Optional icon displayed to the left of the title/subtitle block. */
+    icon?: React.ReactNode;
+};
+declare function ModalHead({ className, children, subtitle, icon, ...rest }: ModalHeadProps): import("react/jsx-runtime").JSX.Element;
 declare namespace ModalHead {
     var displayName: string;
 }
-declare function ModalBody({ className, children, ...rest }: ModalSlotProps): import("react/jsx-runtime").JSX.Element;
+type ModalBodyProps = ModalSlotProps & {
+    /** Accessible label for the scrollable region. Passed to the inner scroll container.
+     *  When the body content overflows, screen readers announce this as the region name.
+     *  Omitting this on a scrollable modal body leaves the scroll region unlabelled. */
+    scrollLabel?: string;
+};
+declare function ModalBody({ className, children, scrollLabel, ...rest }: ModalBodyProps): import("react/jsx-runtime").JSX.Element;
 declare namespace ModalBody {
     var displayName: string;
 }