@tangible/ui 0.0.2 → 0.0.4

package/components/MoveHandle/types.d.ts

@@ -0,0 +1,53 @@
+import type { HTMLAttributes } from 'react';
+export type MoveHandleSize = 'sm' | 'md';
+export type MoveHandleMode = 'full' | 'handle';
+export interface MoveHandleLabels {
+    /** Label for the move-up button. Include item name for clear AT context, e.g. "Move Introduction up". Default: "Move up" */
+    moveUp?: string;
+    /** Label for the move-down button. Include item name for clear AT context, e.g. "Move Introduction down". Default: "Move down" */
+    moveDown?: string;
+    /**
+     * Label for the drag handle button. Default: "Drag to reorder".
+     * Consumers add position info if needed. dragHandleProps['aria-label'] takes precedence.
+     */
+    drag?: string;
+    /** Descriptive text announced when locked (via aria-describedby). Default: "This item is locked and cannot be reordered". */
+    locked?: string;
+}
+export interface MoveHandleProps {
+    /** Structural mode. 'full' (default) shows background panel with arrows/index. 'handle' shows only the bare drag icon button. */
+    mode?: MoveHandleMode;
+    /** Component scale. sm = 32px, md = 40px. Ignored when mode is 'handle'. */
+    size?: MoveHandleSize;
+    /** Position index. When provided, shows number at rest, drag handle on hover. */
+    index?: number;
+    /** When true, shows lock icon and disables all interaction. */
+    locked?: boolean;
+    /**
+     * Called when the "move up" button is clicked. Button not rendered when omitted.
+     *
+     * Consumers should announce the result via a live region (e.g. "Item moved to position 2 of 5")
+     * since the DOM reorder is not conveyed to screen readers automatically.
+     */
+    onMoveUp?: () => void;
+    /**
+     * Called when the "move down" button is clicked. Button not rendered when omitted.
+     *
+     * Consumers should announce the result via a live region (e.g. "Item moved to position 4 of 5")
+     * since the DOM reorder is not conveyed to screen readers automatically.
+     */
+    onMoveDown?: () => void;
+    /** When false, disables the move-up button without hiding it. Default: true. */
+    canMoveUp?: boolean;
+    /** When false, disables the move-down button without hiding it. Default: true. */
+    canMoveDown?: boolean;
+    /** Override internal button labels for i18n. */
+    labels?: MoveHandleLabels;
+    /** Props to spread on the drag handle button (e.g., from dnd-kit useSortable). */
+    dragHandleProps?: HTMLAttributes<HTMLButtonElement>;
+    /** Accessible label for the control group. Required if aria-labelledby is not set. */
+    'aria-label'?: string;
+    /** ID of element labelling this group. Required if aria-label is not set. */
+    'aria-labelledby'?: string;
+    className?: string;
+}

package/components/MoveHandle/types.js

@@ -0,0 +1 @@
+export {};

package/components/Notice/Notice.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { forwardRef, useId, useMemo, useState, useRef, useImperativeHandle, useCallback, useEffect, useContext, createContext } from 'react';
+import React, { forwardRef, useId, useMemo, useState, useRef, useImperativeHandle, useCallback, useEffect, useLayoutEffect, useContext, createContext } from 'react';
 import { cx } from '../../utils/cx.js';
 import { IconButton } from '../IconButton/index.js';
 const NoticeContext = createContext(null);
@@ -15,9 +15,11 @@ export const Notice = forwardRef(function Notice({ as = 'section', inline, eleva
     const [isExiting, setIsExiting] = useState(false);
     const [exitType, setExitType] = useState(null);
     const exitResolveRef = useRef(null);
-    // Track titleId from Notice.Head for aria-labelledby coordination
-    const [titleId, setTitleId] = useState(null);
-    const contextValue = useMemo(() => ({ setTitleId }), []);
+    // Pre-compute a stable title ID so aria-labelledby is wired on first render
+    const titleId = useId();
+    // Track whether Notice.Head has a title (for role="region" on non-section elements)
+    const [hasTitle, setHasTitle] = useState(false);
+    const contextValue = useMemo(() => ({ titleId, setHasTitle }), [titleId]);
     // Cleanup on unmount - resolve any pending exit promise
     useEffect(() => {
         return () => {
@@ -72,6 +74,16 @@ export const Notice = forwardRef(function Notice({ as = 'section', inline, eleva
             setIsExiting(true);
         });
     }, [exitAnimation]);
+    // Announce dismiss to screen readers via a short-lived live region
+    const announceDismiss = useCallback(() => {
+        const el = document.createElement('div');
+        el.setAttribute('role', 'status');
+        el.setAttribute('aria-live', 'polite');
+        el.className = 'tui-visually-hidden';
+        el.textContent = 'Notification dismissed';
+        document.body.appendChild(el);
+        setTimeout(() => el.remove(), 1000);
+    }, []);
     // Handle dismiss button click
     const handleDismiss = useCallback(async () => {
         if (disabled)
@@ -79,8 +91,9 @@ export const Notice = forwardRef(function Notice({ as = 'section', inline, eleva
         if (exitAnimation !== 'none') {
             await exit(exitAnimation);
         }
+        announceDismiss();
         onDismiss?.();
-    }, [disabled, exitAnimation, exit, onDismiss]);
+    }, [disabled, exitAnimation, exit, onDismiss, announceDismiss]);
     // Expose imperative handle as plain object (not mutating DOM element)
     useImperativeHandle(ref, () => ({
         element: innerRef.current,
@@ -97,15 +110,15 @@ export const Notice = forwardRef(function Notice({ as = 'section', inline, eleva
     }, [interactive, onClick, disabled]);
     // A11y role mapping
     const liveRole = announce === 'assertive' ? 'alert' : announce === 'polite' ? 'status' : undefined;
-    // Use titleId from Notice.Head if available, otherwise check ariaLabel
-    const isNamed = Boolean(titleId) || Boolean(ariaLabel);
+    const isNamed = hasTitle || Boolean(ariaLabel);
     const regionRole = !liveRole && isNamed ? 'region' : undefined;
     // If interactive + onClick, behave as button
     const isClickable = interactive && onClick && !disabled;
     const computedRole = isClickable ? 'button' : (liveRole ?? regionRole);
-    // aria-labelledby takes precedence over aria-label when titleId exists
-    const computedLabelledBy = titleId || undefined;
-    const computedAriaLabel = titleId ? undefined : ariaLabel;
+    // aria-labelledby uses pre-computed ID, gated on hasTitle to prevent landmark pollution.
+    // useLayoutEffect in NoticeHead ensures hasTitle is set before first paint.
+    const computedLabelledBy = hasTitle ? titleId : undefined;
+    const computedAriaLabel = hasTitle ? undefined : (ariaLabel || undefined);
     const classes = cx('tui-notice', `is-theme-${theme}`, inline && 'is-layout-inline', elevated && 'is-style-elevated', interactive && 'has-interaction', disabled && 'is-disabled', stripe && 'has-stripe', dismissible && 'is-dismissible', focusable && 'is-focusable', isExiting && exitType && `is-exiting-${exitType}`, className);
     // Dismiss button component
     const dismissButton = dismissible && (_jsx(IconButton, { icon: "system/close", label: dismissLabel, size: "sm", variant: "ghost", className: "tui-notice__dismiss", onClick: (e) => {
@@ -119,16 +132,16 @@ export const Notice = forwardRef(function Notice({ as = 'section', inline, eleva
 // Notice.Head renders icon and title (consumers can add custom actions via children)
 function NoticeHead({ className, icon, title, titleAs = 'h3', children, ...rest }) {
     const context = useContext(NoticeContext);
-    const reactId = useId();
-    const titleId = useMemo(() => title ? `tui-notice-title-${reactId}` : null, [title, reactId]);
-    // Register titleId with parent Notice for aria-labelledby coordination
-    useEffect(() => {
-        if (context && titleId) {
-            context.setTitleId(titleId);
-            return () => context.setTitleId(null);
+    // Tell parent whether a title is present — useLayoutEffect ensures
+    // aria-labelledby and role="region" are set before the first paint.
+    const hasTitle = Boolean(title);
+    useLayoutEffect(() => {
+        if (context && hasTitle) {
+            context.setHasTitle(true);
+            return () => context.setHasTitle(false);
         }
-    }, [context, titleId]);
-    return (_jsxs("div", { className: cx('tui-notice__head', className), ...rest, children: [icon && _jsx("div", { className: "tui-notice__icon", children: icon }), title && React.createElement(titleAs, { id: titleId, className: 'tui-notice__title' }, title), children] }));
+    }, [context, hasTitle]);
+    return (_jsxs("div", { className: cx('tui-notice__head', className), ...rest, children: [icon && _jsx("div", { className: "tui-notice__icon", children: icon }), title && React.createElement(titleAs, { id: context?.titleId, className: 'tui-notice__title' }, title), children] }));
 }
 NoticeHead.displayName = 'Notice.Head';
 function NoticeBody({ className, children, ...rest }) {

package/components/Select/Select.js

@@ -306,13 +306,17 @@ function SelectTriggerComponent({ asChild = false, className, children, }) {
             refs.reference.current.focus();
         }
     }, [open, refs.reference]);
-    // Handle Enter/Space for selection when open
+    // Handle Enter/Space for selection when open, Delete/Backspace to clear when closed
     const handleKeyDown = useCallback((e) => {
         if (open && (e.key === 'Enter' || e.key === ' ')) {
             e.preventDefault();
             handleSelect(activeIndex);
         }
-    }, [open, activeIndex, handleSelect]);
+        if (!open && clearable && hasValue && (e.key === 'Delete' || e.key === 'Backspace')) {
+            e.preventDefault();
+            setValue(undefined);
+        }
+    }, [open, activeIndex, handleSelect, clearable, hasValue, setValue]);
     // Close dropdown when focus leaves trigger
     // Uses blur guard pattern: only close if focus moved outside controlled elements
     const handleBlur = useCallback((e) => {

package/components/Sidebar/Sidebar.d.ts

@@ -1,8 +1,12 @@
-import type { SidebarProps, SidebarHeaderProps, SidebarNavProps } from './types';
+import type { SidebarProps, SidebarHeaderProps, SidebarFooterProps, SidebarNavProps } from './types';
 declare function SidebarHeader(props: SidebarHeaderProps): import("react/jsx-runtime").JSX.Element;
 declare namespace SidebarHeader {
     var displayName: string;
 }
+declare function SidebarFooter(props: SidebarFooterProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SidebarFooter {
+    var displayName: string;
+}
 declare function SidebarNav(props: SidebarNavProps): import("react/jsx-runtime").JSX.Element;
 declare namespace SidebarNav {
     var displayName: string;
@@ -11,6 +15,7 @@ type SidebarCompound = {
     (props: SidebarProps): React.JSX.Element | null;
     displayName?: string;
     Header: typeof SidebarHeader;
+    Footer: typeof SidebarFooter;
     Nav: typeof SidebarNav;
 };
 export declare const Sidebar: SidebarCompound;

package/components/Sidebar/Sidebar.js

@@ -1,14 +1,50 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { useFocusTrap, getInitialFocus } from '../../utils/focus-trap.js';
+import { isDev } from '../../utils/is-dev.js';
 const isBrowser = typeof document !== 'undefined';
 // =============================================================================
 // Sidebar (Root)
 // =============================================================================
 function SidebarRoot(props) {
-    const { position = 'left', drawer = false, open = false, onClose, 'aria-label': ariaLabel, children, className, } = props;
+    const { position = 'left', 'aria-label': ariaLabel, children, className, } = props;
+    // Drawer-specific props — narrowed via discriminant property access
+    const drawer = props.drawer === true;
+    const open = props.drawer ? (props.open ?? false) : false;
+    const onClose = props.drawer ? props.onClose : undefined;
     const sidebarRef = useRef(null);
     const restoreRef = useRef(null);
+    // Exit animation: keep DOM mounted until slide-out animation completes.
+    // `visible` stays true after `open` goes false, until animationend fires.
+    const [visible, setVisible] = useState(open);
+    const panelRef = useRef(null);
+    // When open becomes true, immediately make visible
+    useEffect(() => {
+        if (open)
+            setVisible(true);
+    }, [open]);
+    const isClosing = drawer && !open && visible;
+    const shouldRender = drawer && (open || visible);
+    // When closing, check if animation will actually play (reduced motion).
+    // If not, unmount immediately to avoid getting stuck.
+    useLayoutEffect(() => {
+        if (!isClosing)
+            return;
+        const panel = panelRef.current;
+        if (!panel) {
+            setVisible(false);
+            return;
+        }
+        const style = getComputedStyle(panel);
+        if (!style.animationName || style.animationName === 'none') {
+            setVisible(false);
+        }
+    }, [isClosing]);
+    const handleAnimationEnd = useCallback((e) => {
+        if (e.target === panelRef.current) {
+            setVisible(false);
+        }
+    }, []);
     const rootClassName = ['tui-sidebar', className].filter(Boolean).join(' ');
     // ---------------------------------------------------------------------------
     // Drawer mode: capture trigger for focus restoration
@@ -21,9 +57,9 @@ function SidebarRoot(props) {
             restoreRef.current = document.activeElement;
         }
         else {
-            // Restore focus when closing
+            // Restore focus when closing (with DOM containment guard)
             const el = restoreRef.current;
-            if (el && typeof el.focus === 'function') {
+            if (el && typeof el.focus === 'function' && document.contains(el)) {
                 el.focus();
             }
             restoreRef.current = null;
@@ -48,9 +84,9 @@ function SidebarRoot(props) {
         onEscape: onClose,
     });
     // ---------------------------------------------------------------------------
-    // Drawer mode: initial focus
+    // Drawer mode: initial focus (useLayoutEffect to avoid flash/race)
     // ---------------------------------------------------------------------------
-    useEffect(() => {
+    useLayoutEffect(() => {
         if (!drawer || !open)
             return;
         const sidebar = sidebarRef.current;
@@ -60,28 +96,36 @@ function SidebarRoot(props) {
         target.focus({ preventScroll: true });
     }, [drawer, open]);
     // ---------------------------------------------------------------------------
-    // Sidebar content (shared between static and drawer modes)
+    // Dev warning: drawer without accessible name
     // ---------------------------------------------------------------------------
-    const sidebarContent = (_jsx("aside", { ref: sidebarRef, className: rootClassName, "data-position": position, "aria-label": ariaLabel, "aria-modal": drawer && open ? 'true' : undefined, tabIndex: drawer ? -1 : undefined, children: children }));
+    const hasWarnedRef = useRef(false);
+    useEffect(() => {
+        if (isDev() && drawer && open && !ariaLabel && !hasWarnedRef.current) {
+            console.warn('[TUI Sidebar] Drawer mode is missing aria-label. ' +
+                'The dialog role requires an accessible name (WCAG 4.1.2).');
+            hasWarnedRef.current = true;
+        }
+    }, [drawer, open, ariaLabel]);
     // ---------------------------------------------------------------------------
     // Static mode: render directly
     // ---------------------------------------------------------------------------
     if (!drawer) {
-        return sidebarContent;
+        return (_jsx("aside", { ref: sidebarRef, className: rootClassName, "data-position": position, "aria-label": ariaLabel, children: children }));
     }
     // ---------------------------------------------------------------------------
     // Drawer mode: render inline with fixed positioning (no portal needed)
     // ---------------------------------------------------------------------------
-    if (!open) {
+    if (!shouldRender) {
         return null;
     }
+    const drawerState = isClosing ? 'closing' : 'open';
     const drawerClassName = [
         'tui-sidebar-drawer',
         position === 'right' && 'is-position-right',
     ]
         .filter(Boolean)
         .join(' ');
-    return (_jsxs("div", { className: drawerClassName, "data-position": position, "data-state": "open", children: [_jsx("div", { className: "tui-sidebar-drawer__backdrop", onClick: onClose, "aria-hidden": "true" }), _jsx("div", { className: "tui-sidebar-drawer__panel", children: sidebarContent })] }));
+    return (_jsxs("div", { className: drawerClassName, "data-position": position, "data-state": drawerState, children: [_jsx("div", { className: "tui-sidebar-drawer__backdrop", onClick: onClose, "aria-hidden": "true" }), _jsx("div", { ref: panelRef, className: "tui-sidebar-drawer__panel", role: "dialog", "aria-modal": "true", "aria-label": ariaLabel, onAnimationEnd: handleAnimationEnd, children: _jsx("aside", { ref: sidebarRef, className: rootClassName, "data-position": position, tabIndex: -1, children: children }) })] }));
 }
 // =============================================================================
 // Sidebar.Header
@@ -92,6 +136,14 @@ function SidebarHeader(props) {
     return _jsx("header", { className: headerClassName, children: children });
 }
 // =============================================================================
+// Sidebar.Footer
+// =============================================================================
+function SidebarFooter(props) {
+    const { children, className } = props;
+    const footerClassName = ['tui-sidebar__footer', className].filter(Boolean).join(' ');
+    return _jsx("footer", { className: footerClassName, children: children });
+}
+// =============================================================================
 // Sidebar.Nav
 // =============================================================================
 function SidebarNav(props) {
@@ -100,8 +152,10 @@ function SidebarNav(props) {
     return (_jsx("nav", { className: navClassName, "aria-label": navAriaLabel, "aria-labelledby": navAriaLabelledBy, children: children }));
 }
 SidebarHeader.displayName = 'Sidebar.Header';
+SidebarFooter.displayName = 'Sidebar.Footer';
 SidebarNav.displayName = 'Sidebar.Nav';
 export const Sidebar = SidebarRoot;
 Sidebar.displayName = 'Sidebar';
 Sidebar.Header = SidebarHeader;
+Sidebar.Footer = SidebarFooter;
 Sidebar.Nav = SidebarNav;

package/components/Sidebar/index.d.ts

@@ -1,2 +1,2 @@
 export { Sidebar } from './Sidebar';
-export type { SidebarProps, SidebarHeaderProps, SidebarNavProps, } from './types';
+export type { SidebarProps, SidebarHeaderProps, SidebarFooterProps, SidebarNavProps, } from './types';

package/components/Sidebar/types.d.ts

@@ -1,32 +1,55 @@
 import type { ReactNode } from 'react';
-export type SidebarProps = {
+type SidebarBaseProps = {
     /**
      * Sidebar position. Affects border placement and drawer slide direction.
      * @default 'left'
      */
     position?: 'left' | 'right';
+    /**
+     * Accessible label for the sidebar landmark (static) or dialog (drawer).
+     * When a page has multiple sidebars, each must have a unique label so
+     * screen reader users can distinguish between landmarks
+     * (e.g. "Course navigation", "Lesson settings").
+     */
+    'aria-label'?: string;
+    /**
+     * Sidebar content (Header, Nav, etc.).
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+};
+type SidebarStaticProps = SidebarBaseProps & {
     /**
      * Enable drawer mode (mobile overlay).
-     * When true, sidebar renders via portal with backdrop and focus trap.
      * @default false
      */
-    drawer?: boolean;
+    drawer?: false;
+};
+type SidebarDrawerProps = SidebarBaseProps & {
     /**
-     * Drawer open state. Required when `drawer={true}`.
+     * Enable drawer mode (mobile overlay).
+     * When true, sidebar renders with backdrop, focus trap, and dialog semantics.
      */
-    open?: boolean;
+    drawer: true;
     /**
-     * Callback to close the drawer.
-     * Called when ESC is pressed or backdrop is clicked.
+     * Drawer open state.
      */
-    onClose?: () => void;
+    open?: boolean;
     /**
-     * Accessible label for the aside landmark.
-     * Typically omit this if using `aria-label` on `Sidebar.Nav` instead.
+     * Callback to close the drawer. Required when `drawer={true}`.
+     * Called when ESC is pressed or backdrop is clicked.
+     * Omitting this in drawer mode means the user cannot dismiss the overlay,
+     * which is a WCAG 2.1.1 (Keyboard) failure.
      */
-    'aria-label'?: string;
+    onClose: () => void;
+};
+export type SidebarProps = SidebarStaticProps | SidebarDrawerProps;
+export type SidebarHeaderProps = {
     /**
-     * Sidebar content (Header, Nav, etc.).
+     * Header content (back button, title, progress, CTAs).
      */
     children: ReactNode;
     /**
@@ -34,9 +57,10 @@ export type SidebarProps = {
      */
     className?: string;
 };
-export type SidebarHeaderProps = {
+export type SidebarFooterProps = {
     /**
-     * Header content (back button, title, progress, CTAs).
+     * Footer content (CTAs, user info, etc.).
+     * Sticks to the bottom of the sidebar.
      */
     children: ReactNode;
     /**
@@ -63,3 +87,4 @@ export type SidebarNavProps = {
      */
     className?: string;
 };
+export {};

package/components/Tabs/Tabs.d.ts

@@ -11,7 +11,7 @@ declare function TabsList({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabe
 declare namespace TabsList {
     var displayName: string;
 }
-declare function Tab({ value, icon, disabled, className, children }: TabProps): import("react/jsx-runtime").JSX.Element;
+declare function Tab({ value, icon, 'aria-label': ariaLabel, disabled, className, children }: TabProps): import("react/jsx-runtime").JSX.Element;
 declare namespace Tab {
     var displayName: string;
 }

package/components/Tabs/Tabs.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 import { cx } from '../../utils/cx.js';
+import { isDev } from '../../utils/is-dev.js';
 import { Icon } from '../Icon/index.js';
 import { TabsContext, useTabsContext } from './TabsContext.js';
 // =============================================================================
@@ -243,11 +244,19 @@ function TabsList({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy,
 // =============================================================================
 // Tabs.Tab
 // =============================================================================
-function Tab({ value, icon, disabled = false, className, children }) {
+function Tab({ value, icon, 'aria-label': ariaLabel, disabled = false, className, children }) {
     const { activationMode, activeValue, focusedValue, registerTab, unregisterTab, onSelect, getTabId, getPanelId, } = useTabsContext();
     const tabId = getTabId(value);
     const panelId = getPanelId(value);
     const isActive = activeValue === value;
+    // Dev-only: Warn if icon-only tab has no accessible name
+    const warnedRef = useRef(false);
+    useEffect(() => {
+        if (isDev() && !warnedRef.current && icon && !children && !ariaLabel) {
+            console.warn(`Tabs.Tab "${value}": Icon-only tab without aria-label. Provide aria-label for an accessible name.`);
+            warnedRef.current = true;
+        }
+    }, [icon, children, ariaLabel, value]);
     // Determine which tab gets tabIndex={0}
     const getFocusableValue = () => {
         if (activationMode === 'auto') {
@@ -275,7 +284,7 @@ function Tab({ value, icon, disabled = false, className, children }) {
             onSelect(value);
         }
     };
-    return (_jsxs("button", { ref: callbackRef, type: "button", role: "tab", id: tabId, className: cx('tui-tabs__tab', className), "data-tui-tab-value": value, "data-state": isActive ? 'active' : 'inactive', "aria-selected": isActive, "aria-controls": panelId, tabIndex: disabled ? -1 : isFocusable ? 0 : -1, disabled: disabled, onClick: handleClick, children: [icon && _jsx(Icon, { name: icon, size: "sm", "aria-hidden": "true" }), children && _jsx("span", { className: "tui-tabs__tab-label", children: children })] }));
+    return (_jsxs("button", { ref: callbackRef, type: "button", role: "tab", id: tabId, className: cx('tui-tabs__tab', className), "data-tui-tab-value": value, "data-state": isActive ? 'active' : 'inactive', "aria-selected": isActive, "aria-controls": panelId, "aria-label": ariaLabel, "aria-disabled": disabled || undefined, tabIndex: disabled ? -1 : isFocusable ? 0 : -1, "data-disabled": disabled || undefined, onClick: handleClick, children: [icon && _jsx(Icon, { name: icon, size: "md", "aria-hidden": "true" }), children && _jsx("span", { className: "tui-tabs__tab-label", children: children })] }));
 }
 // =============================================================================
 // Tabs.Panel
@@ -290,7 +299,7 @@ function TabPanel({ value, className, children }) {
         registerPanel(value);
         return () => unregisterPanel(value);
     }, [value, registerPanel, unregisterPanel]);
-    return (_jsx("div", { role: "tabpanel", id: panelId, className: cx('tui-tabs__panel', className), "data-state": isActive ? 'active' : 'inactive', "aria-labelledby": tabId, "aria-hidden": !isActive, 
+    return (_jsx("div", { role: "tabpanel", id: panelId, className: cx('tui-tabs__panel', className), "data-state": isActive ? 'active' : 'inactive', "aria-labelledby": tabId, "aria-hidden": isActive ? undefined : true, 
         // tabIndex={0} allows direct focus on panel for screen reader navigation
         tabIndex: isActive ? 0 : undefined, 
         // inert prevents Tab navigation into hidden panel content

package/components/Tabs/types.d.ts

@@ -20,20 +20,34 @@ export type TabsProps = {
     className?: string;
     children: ReactNode;
 };
-export type TabsListProps = {
-    /** Accessible label (required) */
-    'aria-label'?: string;
-    /** Alternative to aria-label */
-    'aria-labelledby'?: string;
+type TabsListBaseProps = {
     /** Additional classes */
     className?: string;
     children: ReactNode;
 };
+/**
+ * Tabs.List requires an accessible name via either `aria-label` or `aria-labelledby`.
+ * Omitting both leaves the tablist unnamed, which makes it difficult for screen reader
+ * users to identify the purpose of the tab group.
+ */
+export type TabsListProps = TabsListBaseProps & ({
+    'aria-label': string;
+    'aria-labelledby'?: string;
+} | {
+    'aria-label'?: string; /** ID of a visible heading that labels the tablist */
+    'aria-labelledby': string;
+});
 export type TabProps = {
     /** Unique identifier, must match a Panel */
     value: string;
     /** Icon name from registry */
     icon?: IconName;
+    /**
+     * Accessible label for the tab button. Required for icon-only tabs
+     * (no `children`). Omitting this on an icon-only tab leaves the button
+     * without an accessible name, making it invisible to screen readers.
+     */
+    'aria-label'?: string;
     /** Disable tab (skipped in keyboard nav) */
     disabled?: boolean;
     /** Additional classes */
@@ -73,3 +87,4 @@ export type TabsContextValue = {
     getPanelId: (value: string) => string;
     tabsRef: React.MutableRefObject<Map<string, TabRecord>>;
 };
+export {};

package/components/TextInput/TextInput.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef } from 'react';
+import { forwardRef, useCallback } from 'react';
 import { cx } from '../../utils/cx.js';
 // =============================================================================
 // TextInput Component
@@ -17,9 +17,17 @@ import { cx } from '../../utils/cx.js';
 //   --tui-input-radius        Border radius
 //
 // =============================================================================
+/** String or number content gets the `.is-text` visual treatment. */
+const isTextContent = (node) => typeof node === 'string' || typeof node === 'number';
 export const TextInput = forwardRef(function TextInput({ type = 'text', size = 'md', prefix, suffix, className, inputClassName, disabled, ...rest }, ref) {
     const sizeClass = size !== 'md' ? `is-size-${size}` : undefined;
+    const handleGroupClick = useCallback((e) => {
+        const target = e.target;
+        if (target.closest('button, a, [role="button"], input'))
+            return;
+        e.currentTarget.querySelector('input')?.focus();
+    }, []);
     // Always wrap in tui-input-group so className consistently targets the root.
     // ARIA/form props from Field.Control reach the <input> via ...rest.
-    return (_jsxs("div", { className: cx('tui-input-group', sizeClass, disabled && 'is-disabled', className), children: [prefix && _jsx("span", { className: "tui-input-group__prefix", children: prefix }), _jsx("input", { ref: ref, type: type, disabled: disabled, className: cx('tui-input', inputClassName), ...rest }), suffix && _jsx("span", { className: "tui-input-group__suffix", children: suffix })] }));
+    return (_jsxs("div", { className: cx('tui-input-group', sizeClass, disabled && 'is-disabled', className), onClick: handleGroupClick, children: [prefix && (_jsx("span", { className: cx('tui-input-group__prefix', isTextContent(prefix) && 'is-text'), children: prefix })), _jsx("input", { ref: ref, type: type, disabled: disabled, className: cx('tui-input', inputClassName), ...rest }), suffix && (_jsx("span", { className: cx('tui-input-group__suffix', isTextContent(suffix) && 'is-text'), children: suffix }))] }));
 });

package/components/Tooltip/Tooltip.d.ts

@@ -1,8 +1,8 @@
 import type { TooltipProviderProps, TooltipProps, TooltipTriggerProps, TooltipContentProps } from './types';
 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, children }: TooltipTriggerProps): import("react/jsx-runtime").JSX.Element;
-declare function TooltipContentComponent({ side, align, sideOffset, className, children, }: TooltipContentProps): import("react/jsx-runtime").JSX.Element | null;
+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;
 type TooltipCompound = typeof TooltipRoot & {
     Provider: typeof TooltipProviderComponent;
     Trigger: typeof TooltipTriggerComponent;