@ufoui/core 0.0.1

package/components/footer/footer.d.ts

@@ -0,0 +1,27 @@
+import { BoxBaseProps } from '../core';
+/**
+ * Props for {@link Footer}.
+ * Extends {@link BoxBaseProps} except for `elementClass` and `component`.
+ *
+ * @category Box
+ */
+export type FooterProps = Omit<BoxBaseProps, 'elementClass' | 'component'>;
+/**
+ * Semantic layout wrapper for the native `<footer>` element.
+ *
+ * Built on top of {@link BoxBase}, inheriting its layout and styling props.
+ * Defaults to a row layout (`direction="row"`) and applies
+ * the semantic UUI class `"uui-footer"`.
+ *
+ * Use for closing sections, legal notices, or persistent bottom content.
+ *
+ * @function
+ * @param props - All layout and style props inherited from {@link BoxBase}.
+ * @example
+ * <Footer elevation={1} shape="rounded">
+ *   © 2025 My Company
+ * </Footer>
+ *
+ * @category Box
+ */
+export declare const Footer: import('react').ForwardRefExoticComponent<FooterProps & import('react').RefAttributes<HTMLElement>>;

package/components/grid/grid.d.ts

@@ -0,0 +1,38 @@
+import { BoxBaseProps } from '../core';
+/**
+ * Props for the {@link Grid} component.
+ *
+ * Extends {@link BoxBaseProps} with flex-related props removed.
+ * Intended for CSS Grid–only layouts.
+ *
+ * @category Grid
+ */
+export type GridProps = Omit<BoxBaseProps, 'elementClass' | 'type' | 'direction' | 'wrap'>;
+/**
+ * Grid layout container.
+ *
+ * Explicit CSS Grid wrapper used for two-dimensional layouts.
+ * Use this component when working with grid semantics such as
+ * columns, rows, gaps, and auto-placement flow.
+ *
+ * Built on top of {@link BoxBase} and exposes only grid-relevant layout props.
+ *
+ * @category Grid
+ * @function
+ * @param props - Grid layout props inherited from {@link BoxBase}.
+ *
+ * @example
+ * <Grid cols={3} gap={16}>
+ *   <Item />
+ *   <Item />
+ *   <Item />
+ * </Grid>
+ *
+ * @example
+ * <Grid rows="auto 1fr auto" gapY={8}>
+ *   <Header />
+ *   <Content />
+ *   <Footer />
+ * </Grid>
+ */
+export declare const Grid: import('react').ForwardRefExoticComponent<GridProps & import('react').RefAttributes<HTMLDivElement>>;

package/components/header/header.d.ts

@@ -0,0 +1,27 @@
+import { BoxBaseProps } from '../core';
+/**
+ * Props for {@link Header}.
+ * Extends {@link BoxBaseProps} except for `elementClass` and `component`.
+ *
+ * @category Box
+ */
+export type HeaderProps = Omit<BoxBaseProps, 'elementClass' | 'component'>;
+/**
+ * Semantic layout wrapper for the native `<header>` element.
+ *
+ * Built on top of {@link BoxBase}, inheriting its layout and styling props.
+ * Defaults to a row layout (`direction="row"`) and applies
+ * the semantic UUI class `"uui-header"`.
+ *
+ * Use for introductory or navigational top-level content.
+ *
+ * @function
+ * @param props - All layout and style props inherited from {@link BoxBase}.
+ * @example
+ * <Header elevation={1} shape="rounded">
+ *   <Logo />
+ * </Header>
+ *
+ * @category Box
+ */
+export declare const Header: import('react').ForwardRefExoticComponent<HeaderProps & import('react').RefAttributes<HTMLElement>>;

package/components/iconButton/iconButton.d.ts

@@ -0,0 +1,27 @@
+import { ButtonBaseProps } from '../core';
+/**
+ * Props for {@link IconButton}.
+ * Extends {@link ButtonBaseProps} except for text and trailing content.
+ *
+ * @category IconButton
+ */
+export type IconButtonProps = Omit<ButtonBaseProps, 'elementClass' | 'endIcon' | 'trailing'>;
+/**
+ * Icon-only button used for compact or secondary actions.
+ *
+ * Use when an action is represented by an icon instead of text.
+ * An accessible label (`aria-label` or `label`) is required.
+ *
+ * @category IconButton
+ * @function
+ * @param props - All icon button props inherited from {@link ButtonBase}.
+ *
+ * @example
+ * <IconButton label="Add" icon={<AddIcon />} />
+ *
+ * @example
+ * <IconButton aria-label="Close">
+ *   <CloseIcon />
+ * </IconButton>
+ */
+export declare const IconButton: import('react').ForwardRefExoticComponent<IconButtonProps & import('react').RefAttributes<HTMLButtonElement>>;

package/components/listItem/listItem.d.ts

@@ -0,0 +1,179 @@
+import { default as React, HTMLProps, ReactNode } from 'react';
+import { ElementDensity, ElementFocusEffect, ElementFont, ElementSelectedEffect, ElementShape, ElementTouchEffect } from '../utils';
+import { MenuVariant } from '../menu/menu';
+import { SurfaceColor } from '../../utils/color';
+/**
+ * Visual variant of a ListItem.
+ *
+ * Inherited from {@link MenuVariant}.
+ *
+ * @category ListItem
+ */
+export type ListItemVariant = MenuVariant;
+/**
+ * Defines the behavioral type of a ListItem.
+ *
+ * - `item` – simple action item
+ * - `checkbox` – toggleable multiple-selection item
+ * - `radio` – mutually exclusive selection item
+ * - `option` – selectable option item
+ *
+ * @category ListItem
+ */
+export type ListItemType = 'item' | 'checkbox' | 'radio' | 'option';
+/**
+ * Change event payload for selectable menu items
+ * (checkbox, radio and option).
+ *
+ * @category ListItem
+ */
+export interface ListItemChangeEvent {
+    /** Checkbox or radio checked state. */
+    checked?: boolean;
+    /** Item name identifier. */
+    name?: string;
+    /** Selection state for option items. */
+    selected?: boolean;
+    /** Item value identifier. */
+    value?: string;
+}
+/**
+ * Props for the {@link ListItem} component.
+ *
+ * @category ListItem
+ */
+export interface ListItemProps extends Omit<HTMLProps<HTMLDivElement>, 'ref' | 'onChange'> {
+    /** Marks item as active (roving focus). */
+    active?: boolean;
+    /** Badge content rendered at the end. */
+    badge?: ReactNode;
+    /** Checked state for checkbox or radio items. */
+    checked?: boolean;
+    /** Icon shown when item is checked. */
+    checkedIcon?: ReactNode;
+    /** Item content or nested submenu. */
+    children?: ReactNode;
+    /** Base surface color of the item. */
+    color?: SurfaceColor;
+    /** Density preset controlling spacing. */
+    density?: ElementDensity;
+    /** Secondary description text. */
+    description?: string;
+    /** Text color of the description. */
+    descriptionColor?: SurfaceColor;
+    /** Font token applied to the description text. */
+    descriptionFont?: ElementFont;
+    /** Disables interactions and focus. */
+    disabled?: boolean;
+    /** Icon rendered at the end (alias for `trailing`). */
+    endIcon?: ReactNode;
+    /** Whether a nested submenu is expanded. */
+    expanded?: boolean;
+    /** Reserves leading slot even without an icon. */
+    fixedLeading?: boolean;
+    /** Visual focus effects applied when active. */
+    focusEffects?: ElementFocusEffect[];
+    /** Forces focus-visible styling. */
+    focusVisible?: boolean;
+    /** Alias for labelFont. */
+    font?: ElementFont;
+    /** Enables horizontal layout mode. */
+    horizontal?: boolean;
+    /** Icon rendered at the start (alias for `leading`). */
+    icon?: ReactNode;
+    /** Primary label text. */
+    label?: string;
+    /** Text color of the label. */
+    labelColor?: SurfaceColor;
+    /** Font token applied to the label text. */
+    labelFont?: ElementFont;
+    /** Custom leading content. */
+    leading?: ReactNode;
+    /** Item name used in change events. */
+    name?: string;
+    /** Change handler for checkbox, radio and option items. */
+    onChange?: (e: ListItemChangeEvent) => void;
+    /** Click handler for action items. */
+    onClick?: React.MouseEventHandler<HTMLDivElement>;
+    /** Selected state for option items. */
+    selected?: boolean;
+    /** Background color used when selected. */
+    selectedColor?: SurfaceColor;
+    /** Visual effects applied when selected. */
+    selectedEffects?: ElementSelectedEffect[];
+    /** Shape token applied to the item. */
+    shape?: ElementShape;
+    /** Keyboard shortcut label. */
+    shortcut?: string;
+    /** Text color of the shortcut label. */
+    shortcutColor?: SurfaceColor;
+    /** Font token applied to the shortcut text. */
+    shortcutFont?: ElementFont;
+    /** Overrides automatic text color. */
+    textColor?: SurfaceColor;
+    /** Touch and click feedback effects. */
+    touchEffects?: ElementTouchEffect[];
+    /** Custom trailing content. */
+    trailing?: ReactNode;
+    /** Item behavior type. */
+    type?: ListItemType;
+    /** Icon shown when item is unchecked. */
+    uncheckedIcon?: ReactNode;
+    /** Item value used in change events. */
+    value?: string;
+    /** Visual variant inherited from Menu. */
+    variant?: ListItemVariant;
+}
+/**
+ * Internal props injected by Menu.
+ *
+ * @internal
+ * @category ListItem
+ */
+export interface ListItemInternalProps {
+    /** Disables pointer and keyboard interactions. */
+    __interactionsDisabled?: boolean;
+    /** Item index inside the parent menu. */
+    __index?: number;
+    /** Index exposed for DOM queries. */
+    'data-menu-index'?: number;
+    /** ARIA role family inherited from parent container. */
+    roleFamily?: 'menu' | 'listbox' | 'command' | 'toolbar';
+}
+/**
+ * **ListItem** - single interactive item inside a {@link Menu}.
+ *
+ * Represents an action, checkbox, radio item or selectable option.
+ * Supports icons, badges, shortcuts, descriptions and nested submenus.
+ *
+ * Keyboard interaction and focus are handled by the parent Menu.
+ *
+ * @param props
+ *
+ * @example
+ * ```tsx
+ * <ListItem label="Open" onClick={handleOpen} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ListItem
+ *   type="checkbox"
+ *   label="Show grid"
+ *   checked={enabled}
+ *   onChange={() => setEnabled(v => !v)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ListItem label="More">
+ *   <Menu>
+ *     <ListItem label="Sub item" />
+ *   </Menu>
+ * </ListItem>
+ * ```
+ * @function
+ * @category ListItem
+ */
+export declare const ListItem: React.ForwardRefExoticComponent<ListItemProps & ListItemInternalProps & React.RefAttributes<HTMLDivElement>>;

package/components/listItem/listItem.guards.d.ts

@@ -0,0 +1,15 @@
+import { default as React, ReactElement } from 'react';
+import { ListItemInternalProps, ListItemProps } from './listItem';
+export declare const IS_LIST_ITEM: unique symbol;
+/**
+ * Type guard that checks whether a React node is a MenuItem component.
+ *
+ * Identifies MenuItem elements by the internal {@link IS_LIST_ITEM} symbol
+ * attached to the component type.
+ *
+ * @param el - React node to test.
+ * @returns `true` if the node is a MenuItem element.
+ *
+ * @internal
+ */
+export declare function isListItem(el: React.ReactNode): el is ReactElement<ListItemProps & ListItemInternalProps>;

package/components/main/main.d.ts

@@ -0,0 +1,27 @@
+import { BoxBaseProps } from '../core';
+/**
+ * Props for {@link Main}.
+ * Extends {@link BoxBaseProps} except for `elementClass` and `component`.
+ *
+ * @category Box
+ */
+export type MainProps = Omit<BoxBaseProps, 'elementClass' | 'component'>;
+/**
+ * Semantic layout wrapper for the native `<main>` element.
+ *
+ * Built on top of {@link BoxBase}, inheriting its layout and styling props.
+ * Defaults to a column layout (`direction="col"`) and applies
+ * the semantic UUI class `"uui-main"`.
+ *
+ * Use for the primary content region of an application or document.
+ *
+ * @function
+ * @param props - All layout and style props inherited from {@link BoxBase}.
+ * @example
+ * <Main elevation={1} shape="rounded">
+ *   <Section />
+ * </Main>
+ *
+ * @category Box
+ */
+export declare const Main: import('react').ForwardRefExoticComponent<MainProps & import('react').RefAttributes<HTMLElement>>;

package/components/menu/menu.d.ts

@@ -0,0 +1,177 @@
+import { default as React, HTMLAttributes, ReactNode, RefObject } from 'react';
+import { ElementAlign, ElementBorder, ElementDensity, ElementElevation, ElementFocusEffect, ElementFont, ElementSelectedEffect, ElementShape, ElementTouchEffect } from '../utils';
+import { MotionAnimation, MotionStyle } from '../types';
+import { BorderColor, SurfaceColor } from '../../utils/color';
+import { ElementFloatingMode } from '../../utils/calculateFloatingPosition';
+/**
+ * Visual style preset for the Menu component.
+ *
+ * - `modern` – MD3 menu (expressive).
+ * - `classic` – MD3 menu (baseline).
+ *
+ * @category Menu
+ */
+export type MenuVariant = 'modern' | 'classic';
+/**
+ * Animation setting for the Menu component.
+ *
+ * - `auto` – resolves to the default animation (`"scale"`).
+ * - `none` – disables all animations.
+ * - `MotionAnimation` – any supported motion animation type.
+ *
+ * @category Menu
+ */
+export type MenuAnimation = 'auto' | 'none' | MotionAnimation;
+/**
+ * Props for the {@link Menu} component.
+ *
+ * @category Menu
+ */
+export interface MenuProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
+    /** Reference to the trigger element used for positioning. */
+    anchorRef?: RefObject<HTMLElement> | null;
+    /** Animation setting (`auto`, `none`, or motion animation type). */
+    animation?: MenuAnimation;
+    /** Border width (0–4). */
+    border?: ElementBorder;
+    /** Border color token. */
+    borderColor?: BorderColor;
+    /** Icon used for checked checkbox items. */
+    checkedIcon?: ReactNode;
+    /** Menu items. Must be `MenuItem` or compatible custom nodes. */
+    children?: ReactNode;
+    /** Whether menu closes automatically on item change. */
+    closeOnChange?: boolean;
+    /** Surface background token for the menu container. */
+    color?: SurfaceColor;
+    /** Density preset (`comfortable`, `compact`, `dense`). */
+    density?: ElementDensity;
+    /** Text color for item descriptions. */
+    descriptionColor?: SurfaceColor;
+    /** Font token applied to menu item descriptions. */
+    descriptionFont?: ElementFont;
+    /** Enables docked positioning mode. */
+    docked?: boolean;
+    /** Elevation level of the menu surface when docked. */
+    dockedElevation?: ElementElevation;
+    /** Duration (ms) of open/close animation. Default: 250 */
+    duration?: number;
+    /** Elevation level of the menu surface. */
+    elevation?: ElementElevation;
+    /** Reserves leading slot for all menu items. */
+    fixedLeading?: boolean;
+    /** Floating behaviour mode (`menu`, `submenu`, `dropdown`, `tooltip`). */
+    floatingMode?: ElementFloatingMode;
+    /** Alias for labelFont */
+    font?: ElementFont;
+    /** Enables horizontal menu layout. */
+    horizontal?: boolean;
+    /** Focus effects applied to menu items. */
+    itemFocusEffects?: ElementFocusEffect[];
+    /** Selected state effects applied to menu items. */
+    itemSelectedEffects?: ElementSelectedEffect[];
+    /** Touch and click feedback effects for menu items. */
+    itemTouchEffects?: ElementTouchEffect[];
+    /** Text color for item labels. */
+    labelColor?: SurfaceColor;
+    /** Font token applied to menu item primary labels. */
+    labelFont?: ElementFont;
+    /** Motion style variant (expressive or regular). */
+    motionStyle?: MotionStyle;
+    /** Offset (px) between menu and anchor. @default 4 */
+    offset?: number;
+    /** Callback fired when the menu requests to close. */
+    onClose?: () => void;
+    /** Controls visibility of the menu. */
+    open?: boolean;
+    /** Opens the menu on pointer hover. */
+    openOnHover?: boolean;
+    /** Preferred placement relative to the anchor. */
+    placement?: ElementAlign;
+    /** Icon used for checked radio items. */
+    radioCheckedIcon?: ReactNode;
+    /** Icon used for unchecked radio items. */
+    radioUncheckedIcon?: ReactNode;
+    /** Background color used for selected items. */
+    selectedColor?: SurfaceColor;
+    /** Shape token controlling menu corner rounding. */
+    shape?: ElementShape;
+    /** Text color for shortcut labels. */
+    shortcutColor?: SurfaceColor;
+    /** Font token applied to menu item shortcut labels. */
+    shortcutFont?: ElementFont;
+    /** Overrides automatic text color. */
+    textColor?: SurfaceColor;
+    /** Icon used for unchecked checkbox items. */
+    uncheckedIcon?: ReactNode;
+    /** Visual preset (`modern` = MD3 expressive, `classic` = MD3 baseline). */
+    variant?: MenuVariant;
+}
+/**
+ * Internal props used for nested and recursive menu rendering.
+ *
+ * These props are injected automatically by the Menu system
+ * and must not be provided manually.
+ *
+ * @category Menu
+ * @internal
+ */
+export interface MenuInternalProps {
+    /** Closes the root menu instance. */
+    __closeRootMenu?: () => void;
+    /** Shared group identifier for nested menus. */
+    __groupId?: string;
+    /** Horizontal nesting depth for keyboard navigation. */
+    __horizontalDepth?: number;
+    /** Nesting depth of the menu tree (0 = root). */
+    __level?: number;
+    /** Handles horizontal navigation between sibling menus. */
+    __navigateHorizontal?: (goNext: boolean) => void;
+}
+/**
+ * **Menu** - menu component with optional docking and multi-level submenus.
+ *
+ * Renders a menu component following the MD3 specification.
+ * The menu can be positioned relative to an anchor element using floating
+ * layout logic or rendered in a docked mode without floating positioning.
+ *
+ * Supports nested submenus, keyboard navigation,
+ * motion configuration, density presets, elevation, shape, borders
+ * and two MD3 visual variants (`modern`, `classic`).
+ *
+ *
+ * @param props
+ *
+ * @example
+ * ```tsx
+ * <Menu open anchorRef={buttonRef}>
+ *   <MenuItem label="Open" />
+ *   <Divider/>
+ *   <MenuItem label="Save" />
+ * </Menu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Menu open docked>
+ *   <MenuItem label="Settings" />
+ *   <MenuItem label="Logout" />
+ * </Menu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Menu open>
+ *   <MenuItem label="View">
+ *     <Menu>
+ *       <MenuItem label="Zoom in" />
+ *       <MenuItem label="Zoom out" />
+ *     </Menu>
+ *   </MenuItem>
+ * </Menu>
+ * ```
+ *
+ * @category Menu
+ * @function
+ */
+export declare const Menu: React.ForwardRefExoticComponent<MenuProps & MenuInternalProps & React.RefAttributes<HTMLDivElement>>;

package/components/menu/menu.guards.d.ts

@@ -0,0 +1,15 @@
+import { default as React, ReactElement } from 'react';
+import { MenuInternalProps, MenuProps } from '../core';
+export declare const IS_MENU: unique symbol;
+/**
+ * Type guard that checks whether a React node is a Menu component.
+ *
+ * Identifies Menu elements by the internal {@link IS_MENU} symbol
+ * attached to the component type.
+ *
+ * @param el - React node to test.
+ * @returns `true` if the node is a Menu element.
+ *
+ * @internal
+ */
+export declare function isMenu(el: React.ReactNode): el is ReactElement<MenuProps & MenuInternalProps>;