@tangible/ui 0.0.1

package/components/Dropdown/Dropdown.js

@@ -0,0 +1,219 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { useCallback, useEffect, 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';
+import { Button } from '../Button/index.js';
+import { DropdownContext, useDropdownContext } from './DropdownContext.js';
+import { toPlacement } from './types.js';
+// =============================================================================
+// Dropdown Root
+// =============================================================================
+function DropdownRoot({ open: controlledOpen, onOpenChange, defaultOpen = false, children, }) {
+    const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+    const [activeIndex, setActiveIndex] = useState(null);
+    const isControlled = controlledOpen !== undefined;
+    const open = isControlled ? controlledOpen : uncontrolledOpen;
+    const setOpen = useCallback((nextOpen) => {
+        if (!isControlled) {
+            setUncontrolledOpen(nextOpen);
+        }
+        onOpenChange?.(nextOpen);
+        if (!nextOpen) {
+            setActiveIndex(null);
+        }
+    }, [isControlled, onOpenChange]);
+    const triggerRef = useRef(null);
+    const contentId = useId();
+    // Focus restoration: track if we need to restore focus on close
+    const shouldRestoreFocus = useRef(false);
+    const prevOpen = useRef(open);
+    useEffect(() => {
+        // When opening, mark that we should restore focus on close
+        if (open && !prevOpen.current) {
+            shouldRestoreFocus.current = true;
+        }
+        // When closing, restore focus to trigger
+        if (!open && prevOpen.current && shouldRestoreFocus.current) {
+            triggerRef.current?.focus();
+            shouldRestoreFocus.current = false;
+        }
+        prevOpen.current = open;
+    }, [open]);
+    const contextValue = useMemo(() => ({
+        open,
+        setOpen,
+        triggerRef,
+        contentId,
+        activeIndex,
+        setActiveIndex,
+    }), [open, setOpen, contentId, activeIndex]);
+    return (_jsx(DropdownContext.Provider, { value: contextValue, children: children }));
+}
+DropdownRoot.displayName = 'Dropdown';
+// =============================================================================
+// DropdownTrigger
+// =============================================================================
+function DropdownTriggerComponent({ asChild = false, children }) {
+    const { open, setOpen, triggerRef, contentId } = useDropdownContext();
+    const handleClick = useCallback(() => {
+        setOpen(!open);
+    }, [open, setOpen]);
+    const handleKeyDown = useCallback((e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            setOpen(!open);
+        }
+        else if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            setOpen(true);
+        }
+        else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            setOpen(true);
+        }
+    }, [open, setOpen]);
+    // Merge child ref with our triggerRef
+    const setRefs = useCallback((node) => {
+        triggerRef.current = node;
+        if (asChild && isValidElement(children)) {
+            const childRef = children.ref;
+            if (typeof childRef === 'function') {
+                childRef(node);
+            }
+            else if (childRef && typeof childRef === 'object') {
+                childRef.current = node;
+            }
+        }
+    }, [asChild, children, triggerRef]);
+    const triggerProps = {
+        onClick: handleClick,
+        onKeyDown: handleKeyDown,
+        'aria-haspopup': 'menu',
+        'aria-expanded': open,
+        'aria-controls': open ? contentId : undefined,
+        'data-dropdown-open': open || undefined,
+    };
+    if (asChild && isValidElement(children)) {
+        return cloneElement(children, {
+            ...triggerProps,
+            ref: setRefs,
+        });
+    }
+    // Non-asChild wrapper needs proper button semantics
+    return (_jsx("span", { ref: setRefs, role: "button", tabIndex: 0, ...triggerProps, style: { display: 'inline-flex' }, children: children }));
+}
+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 listRef = useRef([]);
+    const { refs, floatingStyles, context } = useFloating({
+        placement: toPlacement(side, align),
+        open,
+        onOpenChange: setOpen,
+        middleware: [offset(sideOffset), flip(), shift({ padding: 8 })],
+        whileElementsMounted: autoUpdate,
+    });
+    // Sync reference element
+    useEffect(() => {
+        if (triggerRef.current) {
+            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);
+                }
+            }
+        });
+        return indices;
+    }, [children]);
+    const dismiss = useDismiss(context);
+    const role = useRole(context, { role: 'menu' });
+    const listNavigation = useListNavigation(context, {
+        listRef,
+        activeIndex,
+        onNavigate: setActiveIndex,
+        loop: true,
+        disabledIndices,
+        focusItemOnOpen: true,
+    });
+    const { getFloatingProps, getItemProps } = useInteractions([
+        dismiss,
+        role,
+        listNavigation,
+    ]);
+    // Get portal root inside .tui-interface
+    const portalRoot = getPortalRootFor(triggerRef.current);
+    if (!open)
+        return null;
+    // Clone children to inject item props and role
+    const items = Children.map(children, (child, index) => {
+        if (!isValidElement(child))
+            return child;
+        const childProps = child.props;
+        const isDisabled = childProps.disabled === true;
+        const existingRole = childProps.role;
+        return cloneElement(child, {
+            ...getItemProps({
+                ref: (node) => {
+                    listRef.current[index] = node;
+                },
+                // Disabled items get tabIndex -1 always
+                tabIndex: isDisabled ? -1 : (activeIndex === index ? 0 : -1),
+            }),
+            // Add menuitem role if not already specified
+            role: existingRole || 'menuitem',
+            'aria-disabled': isDisabled || undefined,
+            'data-active': activeIndex === index || 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: {
+                    ...floatingStyles,
+                    ...style,
+                }, ...getFloatingProps(), children: items }) }) }));
+}
+DropdownContentComponent.displayName = 'Dropdown.Content';
+// =============================================================================
+// DropdownItem
+// =============================================================================
+/**
+ * Dropdown menu item. Renders a Button internally with ghost variant.
+ * 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 handleClick = useCallback(() => {
+        if (disabled)
+            return;
+        onSelect?.();
+        if (!keepOpen) {
+            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]);
+    return (_jsx(Button, { variant: "ghost", href: disabled ? undefined : href, target: href ? target : undefined, disabled: disabled, onClick: handleClick, className: cx('tui-dropdown__item', className), ...props, children: children }));
+}
+DropdownItemComponent.displayName = 'Dropdown.Item';
+export const Dropdown = DropdownRoot;
+Dropdown.Trigger = DropdownTriggerComponent;
+Dropdown.Content = DropdownContentComponent;
+Dropdown.Item = DropdownItemComponent;
+// Named exports for direct imports
+export const DropdownTrigger = DropdownTriggerComponent;
+export const DropdownContent = DropdownContentComponent;
+export const DropdownItem = DropdownItemComponent;
+// Hook for advanced use cases (custom items that need to close the dropdown)
+export { useDropdownContext as useDropdown } from './DropdownContext.js';

package/components/Dropdown/DropdownContext.d.ts

@@ -0,0 +1,3 @@
+import type { DropdownContextValue } from './types';
+export declare const DropdownContext: import("react").Context<DropdownContextValue | null>;
+export declare function useDropdownContext(): DropdownContextValue;

package/components/Dropdown/DropdownContext.js

@@ -0,0 +1,9 @@
+import { createContext, useContext } from 'react';
+export const DropdownContext = createContext(null);
+export function useDropdownContext() {
+    const context = useContext(DropdownContext);
+    if (!context) {
+        throw new Error('Dropdown components must be used within a Dropdown');
+    }
+    return context;
+}

package/components/Dropdown/index.d.ts

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

package/components/Dropdown/index.js

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

package/components/Dropdown/types.d.ts

@@ -0,0 +1,102 @@
+import type { Placement } from '@floating-ui/react';
+/**
+ * Dropdown placement sides.
+ */
+export type Side = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Dropdown alignment relative to trigger.
+ */
+export type Align = 'start' | 'center' | 'end';
+export type DropdownProps = {
+    /**
+     * Controlled open state.
+     */
+    open?: boolean;
+    /**
+     * Callback when open state changes.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Default open state for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    children: React.ReactNode;
+};
+export type DropdownTriggerProps = {
+    /**
+     * When true, merges props onto the child element instead of wrapping in a span.
+     * Child must be a single React element that accepts ref and event handlers.
+     * @default false
+     */
+    asChild?: boolean;
+    children: React.ReactNode;
+};
+export type DropdownContentProps = {
+    /**
+     * Preferred side of the trigger to place the dropdown.
+     * @default 'bottom'
+     */
+    side?: Side;
+    /**
+     * Alignment along the side.
+     * @default 'start'
+     */
+    align?: Align;
+    /**
+     * Distance from the trigger in pixels.
+     * @default 4
+     */
+    sideOffset?: number;
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    /**
+     * Inline styles (use sparingly, prefer className).
+     */
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+};
+export type DropdownItemProps = {
+    /**
+     * Click handler for the item.
+     */
+    onSelect?: () => void;
+    /**
+     * URL to navigate to. When provided, renders as an anchor.
+     */
+    href?: string;
+    /**
+     * Link target (only applies when href is provided).
+     * @default '_self'
+     */
+    target?: string;
+    /**
+     * Whether the item is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * When true, keeps the dropdown open after selection.
+     * @default false
+     */
+    keepOpen?: boolean;
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    children: React.ReactNode;
+};
+export type DropdownContextValue = {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    triggerRef: React.RefObject<HTMLElement | null>;
+    contentId: string;
+    activeIndex: number | null;
+    setActiveIndex: (index: number | null) => void;
+};
+/**
+ * Convert side + align to Floating UI placement.
+ */
+export declare function toPlacement(side: Side, align: Align): Placement;

package/components/Dropdown/types.js

@@ -0,0 +1,8 @@
+/**
+ * Convert side + align to Floating UI placement.
+ */
+export function toPlacement(side, align) {
+    if (align === 'center')
+        return side;
+    return `${side}-${align}`;
+}

package/components/Icon/Icon.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import type { IconName } from '../../icons/registry';
+import type { SizeExtended } from '../../types';
+export interface IconProps {
+    /** Icon name from registry (e.g., "system/check") */
+    name?: IconName;
+    /** Emoji or unicode character (alternative to name) */
+    emoji?: string;
+    /** Accessible label for informative icons. Required if icon conveys meaning. */
+    label?: string;
+    /** Icon size. Defaults to inherit from parent font-size. */
+    size?: SizeExtended;
+    className?: string;
+}
+/**
+ * Icon component for SVG icons from the registry or emoji characters.
+ *
+ * Accessibility:
+ * - 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>>;

package/components/Icon/Icon.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { cx } from '../../utils/cx.js';
+import { iconRegistry } from '../../icons/registry.js';
+/**
+ * Icon component for SVG icons from the registry or emoji characters.
+ *
+ * Accessibility:
+ * - 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) => {
+    const SvgIcon = name ? iconRegistry[name] : null;
+    // Dev warning for invalid icon name
+    if (import.meta.env.DEV && name && !SvgIcon) {
+        console.warn(`[Icon] Unknown icon name: "${name}". Check the registry.`);
+    }
+    // Decorative if no label provided
+    const isDecorative = !label;
+    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/Icon/index.d.ts

@@ -0,0 +1,2 @@
+export { Icon } from './Icon';
+export type { IconProps } from './Icon';

package/components/Icon/index.js

@@ -0,0 +1 @@
+export { Icon } from './Icon.js';

package/components/IconButton/IconButton.d.ts

@@ -0,0 +1,2 @@
+import type { IconButtonProps } from './types';
+export declare const IconButton: import("react").ForwardRefExoticComponent<IconButtonProps & import("react").RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;

package/components/IconButton/IconButton.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { cx } from '../../utils/cx.js';
+import { Icon } from '../Icon/index.js';
+import { Tooltip } from '../Tooltip/index.js';
+import { getSafeRel } from '../../utils/polymorphic.js';
+// =============================================================================
+// IconButton Component
+// =============================================================================
+//
+// Square button containing only an icon. Requires an accessible label since
+// there's no visible text. Use for toolbar actions, close buttons, navigation
+// controls, etc.
+//
+// Renders as <button> by default, or <a> when href is provided.
+// Set showTooltip to display the label on hover for sighted users.
+//
+// =============================================================================
+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 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 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;
+    if (isLink) {
+        const { href, target, rel, tabIndex, onClick, ...anchorRest } = rest;
+        const safeRel = getSafeRel(target, rel);
+        const handleClick = (e) => {
+            if (isDisabled) {
+                e.preventDefault();
+                e.stopPropagation();
+                return;
+            }
+            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 }));
+    }
+    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 }));
+    }
+    // Wrap in tooltip if requested
+    if (showTooltip) {
+        return (_jsxs(Tooltip, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: element }), _jsx(Tooltip.Content, { side: tooltipSide, children: label })] }));
+    }
+    return element;
+});
+IconButton.displayName = 'IconButton';

package/components/IconButton/index.d.ts

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

package/components/IconButton/index.js

@@ -0,0 +1 @@
+export { IconButton } from './IconButton.js';

package/components/IconButton/types.d.ts

@@ -0,0 +1,79 @@
+import type { IconName } from '../../icons/registry';
+import type { Size, ThemeIntent } from '../../types';
+export type { Size };
+export type Theme = ThemeIntent;
+export type Variant = 'solid' | 'outline' | 'ghost';
+type IconButtonBaseProps = {
+    /**
+     * Icon to display. Required — this is the button's visual content.
+     * @example icon="system/close"
+     */
+    icon: IconName;
+    /**
+     * Accessible label. Required — icon-only buttons must have a label
+     * for screen readers since there's no visible text.
+     * @example label="Close modal"
+     */
+    label: string;
+    /**
+     * Size of the button.
+     * - `'xs'`: 24px
+     * - `'sm'`: 32px (default)
+     * - `'md'`: 40px
+     * - `'lg'`: 48px
+     * @default 'sm'
+     */
+    size?: Size;
+    /**
+     * Semantic color theme.
+     * Note: Defaults to 'secondary' (unlike Button which defaults to 'primary')
+     * because IconButtons are typically used for toolbar/utility actions.
+     * @default 'secondary'
+     */
+    theme?: Theme;
+    /**
+     * Visual style variant.
+     * - `'solid'`: Filled background
+     * - `'outline'`: Border only, transparent background
+     * - `'ghost'`: No border or background, icon only
+     * @default 'ghost'
+     */
+    variant?: Variant;
+    /**
+     * Disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * Loading state — shows spinner, disables interaction.
+     */
+    loading?: boolean;
+    /**
+     * Pressed state for toggle buttons.
+     * When true, applies aria-pressed="true" and active styling.
+     * @example pressed={isMuted}
+     */
+    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.
+     * @default false
+     */
+    showTooltip?: boolean;
+    /**
+     * Tooltip placement side.
+     * @default 'top'
+     */
+    tooltipSide?: 'top' | 'right' | 'bottom' | 'left';
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+};
+export type IconButtonAsButton = IconButtonBaseProps & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'aria-label'> & {
+    href?: undefined;
+};
+export type IconButtonAsAnchor = IconButtonBaseProps & Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'children' | 'aria-label'> & {
+    href: string;
+};
+export type IconButtonProps = IconButtonAsButton | IconButtonAsAnchor;

package/components/IconButton/types.js

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

package/components/Modal/Modal.d.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+import type { SizeStandard } from '../../types';
+type Size = SizeStandard;
+export type ModalProps = {
+    isOpen: boolean;
+    onClose: () => void;
+    size?: Size;
+    stickyHead?: boolean;
+    stickyFoot?: boolean;
+    labelledBy?: string;
+    describedBy?: string;
+    initialFocusSelector?: string;
+    container?: Element | null;
+    showCloseButton?: boolean;
+    closeLabel?: string;
+    closeOnBackdropClick?: boolean;
+    closeOnEscape?: boolean;
+    children?: React.ReactNode;
+};
+declare function ModalRoot({ isOpen, onClose, size, stickyHead, stickyFoot, labelledBy, describedBy, initialFocusSelector, container, showCloseButton, closeLabel, closeOnBackdropClick, closeOnEscape, children, }: ModalProps): React.ReactPortal | null;
+type ModalCloseProps = {
+    label?: string;
+    className?: string;
+};
+declare function ModalClose({ label, className }: ModalCloseProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ModalClose {
+    var displayName: string;
+}
+type ModalSlotProps = {
+    className?: string;
+    children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+declare function ModalHead({ className, children, ...rest }: ModalSlotProps): 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;
+declare namespace ModalBody {
+    var displayName: string;
+}
+declare function ModalFoot({ className, children, ...rest }: ModalSlotProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ModalFoot {
+    var displayName: string;
+}
+type ModalCompound = typeof ModalRoot & {
+    Head: typeof ModalHead;
+    Body: typeof ModalBody;
+    Foot: typeof ModalFoot;
+    Close: typeof ModalClose;
+};
+export declare const Modal: ModalCompound;
+export {};