@ufoui/core 0.0.1

package/LICENSE

@@ -0,0 +1,150 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+   Subject to the terms and conditions of this License, each Contributor
+   hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+   royalty-free, irrevocable copyright license to reproduce, prepare
+   Derivative Works of, publicly display, publicly perform, sublicense,
+   and distribute the Work and such Derivative Works in Source or Object
+   form.
+
+3. Grant of Patent License.
+   Subject to the terms and conditions of this License, each Contributor
+   hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+   royalty-free, irrevocable (except as stated in this section) patent
+   license to make, have made, use, offer to sell, sell, import, and
+   otherwise transfer the Work, where such license applies only to those
+   patent claims licensable by such Contributor that are necessarily
+   infringed by their Contribution(s) alone or by combination of their
+   Contribution(s) with the Work to which such Contribution(s) was
+   submitted.
+
+4. Redistribution.
+   You may reproduce and distribute copies of the Work or Derivative
+   Works thereof in any medium, with or without modifications, and in
+   Source or Object form, provided that You meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+   Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+   stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+   that You distribute, all copyright, patent, trademark, and
+   attribution notices from the Source form of the Work,
+   excluding those notices that do not pertain to any part of
+   the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+   distribution, then any Derivative Works that You distribute must
+   include a readable copy of the attribution notices contained
+   within such NOTICE file, excluding those notices that do not
+   pertain to any part of the Derivative Works, in at least one
+   of the following places: within a NOTICE text file distributed
+   as part of the Derivative Works; within the Source form or
+   documentation, if provided along with the Derivative Works; or,
+   within a display generated by the Derivative Works, if and
+   wherever such third-party notices normally appear. The contents
+   of the NOTICE file are for informational purposes only and
+   do not modify the License. You may add Your own attribution
+   notices within Derivative Works that You distribute, alongside
+   or as an addendum to the NOTICE text from the Work, provided
+   that such additional attribution notices cannot be construed
+   as modifying the License.
+
+5. Submission of Contributions.
+   Unless You explicitly state otherwise, any Contribution intentionally
+   submitted for inclusion in the Work by You to the Licensor shall be
+   under the terms and conditions of this License, without any additional
+   terms or conditions.
+
+6. Trademarks.
+   This License does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+   Unless required by applicable law or agreed to in writing, Licensor
+   provides the Work (and each Contributor provides its Contributions)
+   on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+   either express or implied.
+
+8. Limitation of Liability.
+   In no event and under no legal theory, whether in tort (including
+   negligence), contract, or otherwise, unless required by applicable
+   law (such as deliberate and grossly negligent acts) or agreed to in
+   writing, shall any Contributor be liable to You for damages.
+
+9. Accepting Warranty or Additional Liability.
+   While redistributing the Work or Derivative Works thereof, You may
+   choose to offer, and charge a fee for, acceptance of support,
+   warranty, indemnity, or other liability obligations and/or rights
+   consistent with this License.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 UFOUI Project

package/README.md

@@ -0,0 +1,37 @@
+# UFOUI
+
+UFOUI is a React UI component library implementing Material Design 3.
+It focuses on simplicity, low dependency count, and small bundle size.
+
+The library is designed to be used as a single import, without additional required packages beyond React.
+
+## Goals
+- Full Material Design 3 implementation
+- Minimal bundle size
+- No heavy runtime dependencies
+- Suitable for both open-source and commercial products
+
+## Status
+This project is currently in early development (v0.x).
+The API may change.
+
+## Installation
+```bash
+pnpm add @ufoui/core
+```
+
+## Usage
+```ts
+import { Button } from '@ufoui/core';
+```
+
+```ts
+import '@ufoui/core/style.css';
+```
+
+## License
+Apache License 2.0
+
+## Trademark
+“UFOUI” and the UFOUI logo are trademarks of the UFOUI project.
+Use of the name or logo requires permission.

package/TRADEMARK.md

@@ -0,0 +1,10 @@
+# Trademark
+
+“UFOUI” and the UFOUI logo are trademarks of the UFOUI Project.
+
+The Apache License 2.0 applies to the source code only.
+This license does not grant permission to use the UFOUI name,
+logo, or branding for commercial products, forks, or derivative works
+without prior written permission.
+
+

package/components/article/article.d.ts

@@ -0,0 +1,25 @@
+import { BoxBaseProps } from '../core';
+/**
+ * Props for {@link Article}.
+ * Extends {@link BoxBaseProps} except for `elementClass` and `component`.
+ *
+ * @category Box
+ */
+export type ArticleProps = Omit<BoxBaseProps, 'elementClass' | 'component'>;
+/**
+ * Semantic layout wrapper for the native `<article>` element.
+ * Intended for self-contained content units composed of Sections and optional Aside.
+ *
+ * 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-article"`.
+ *
+ * @function
+ * @example
+ * <Article elevation={1} shape="rounded">
+ *   <Section />
+ * </Article>
+ *
+ * @category Box
+ */
+export declare const Article: import('react').ForwardRefExoticComponent<ArticleProps & import('react').RefAttributes<HTMLElement>>;

package/components/aside/aside.d.ts

@@ -0,0 +1,27 @@
+import { BoxBaseProps } from '../core';
+/**
+ * Props for {@link Aside}.
+ * Extends {@link BoxBaseProps} except for `elementClass` and `component`.
+ *
+ * @category Box
+ */
+export type AsideProps = Omit<BoxBaseProps, 'elementClass' | 'component'>;
+/**
+ * Semantic layout wrapper for the native `<aside>` 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-aside"`.
+ *
+ * Use for complementary or contextual content adjacent to the main content.
+ *
+ * @function
+ * @param props - All layout and style props inherited from {@link BoxBase}.
+ * @example
+ * <Aside elevation={1} shape="rounded">
+ *   <SidebarContent />
+ * </Aside>
+ *
+ * @category Box
+ */
+export declare const Aside: import('react').ForwardRefExoticComponent<AsideProps & import('react').RefAttributes<HTMLElement>>;

package/components/avatar/avatar.d.ts

@@ -0,0 +1,35 @@
+import { HTMLProps } from 'react';
+import { ElementBorder, ElementElevation, ElementShape, ElementSize } from '../utils';
+import { BorderColor, SemanticColor } from '../../utils/color';
+/**
+ * Props for the {@link Badge} component.
+ *
+ * @remarks
+ * Badge displays a status or value in a small decorative label.
+ * Supports customization of color, border, elevation, shape, size, and position.
+ *
+ * @category Component properties
+ */
+export interface AvatarProps extends Omit<HTMLProps<HTMLDivElement>, 'ref' | 'size'> {
+    /** The value displayed inside the badge (e.g. a number or label). */
+    label: string;
+    /** Semantic color of the badge background (e.g. `'error'`, `'info'`). */
+    color?: SemanticColor;
+    /** Border width, e.g. `1` or `2`. Ignored if `outlined` is not set.
+     * @default 1
+     * */
+    border?: ElementBorder;
+    /** Color of the border when `outlined` is true. */
+    borderColor?: BorderColor;
+    /** Elevation depth if `raised` is true. */
+    elevation?: ElementElevation;
+    /** Size of the badge (`small`, `medium`, `large`). */
+    size?: ElementSize;
+    /** Shape of the badge, e.g. `'round'`, `'square'`. */
+    shape?: ElementShape;
+    /** If true, adds elevation shadow. */
+    raised?: boolean;
+    /** If true, renders the badge as outlined. */
+    outlined?: boolean;
+}
+export declare const Avatar: import('react').ForwardRefExoticComponent<AvatarProps & import('react').RefAttributes<HTMLDivElement>>;

package/components/badge/badge.d.ts

@@ -0,0 +1,57 @@
+import { HTMLAttributes } from 'react';
+import { ElementAlign, ElementBorder, ElementElevation, ElementFont, ElementShape, ElementSize } from '../utils';
+import { BorderColor, SemanticColor } from '../../utils/color';
+/**
+ * Props for the Badge component.
+ *
+ * Small visual indicator used to display a value or status.
+ *
+ * @category Badge
+ */
+export interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'ref' | 'size'> {
+    /** Position relative to the parent element. */
+    align?: ElementAlign;
+    /** Accessible label for screen readers when badge conveys information. */
+    ariaLabel?: string;
+    /** Border width when outlined. */
+    border?: ElementBorder;
+    /** Border color when outlined. */
+    borderColor?: BorderColor;
+    /** Semantic background color. */
+    color?: SemanticColor;
+    /** Elevation level for raised appearance. */
+    elevation?: ElementElevation;
+    /** Font token applied to the badge text. */
+    font?: ElementFont;
+    /** Visual offset applied to the badge position. */
+    offset?: number;
+    /** Shape of the badge. */
+    shape?: ElementShape;
+    /** Visual size of the badge. */
+    size?: ElementSize;
+    /** Value displayed inside the badge. */
+    value: string | number;
+}
+/**
+ * Displays a small badge with a value or indicator.
+ *
+ * Can be rendered standalone or attached to a child element.
+ * When size is small or extraSmall, the value is hidden.
+ *
+ * @function Badge
+ * @param props Component properties.
+ *
+ * @example
+ * <Badge value={3} color="info" />
+ *
+ * @example
+ * <Badge value={5} color="warning">
+ *   <Button />
+ * </Badge>
+ *
+ * @category Badge
+ */
+export declare const Badge: {
+    (props: BadgeProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/components/base/boxBase/boxBase.d.ts

@@ -0,0 +1,126 @@
+import { default as React, HTMLAttributes, ReactNode } from 'react';
+import { ElementBorder, ElementElevation, ElementShape } from '../../utils';
+import { BorderColor, SurfaceColor } from '../../../utils/color';
+/**
+ * Layout mode for {@link BoxBase}.
+ *
+ * @remarks
+ * Determines how children are arranged:
+ * - `'flex'` — flex container
+ * - `'grid'` — grid container
+ * - `'block'` — block or inline-block element
+ *
+ * @category Box
+ */
+export type BoxType = 'flex' | 'grid' | 'block';
+/**
+ * Direction value used by layout-related props.
+ *
+ * @category Box
+ */
+export type BoxDirection = 'row' | 'col';
+/**
+ * Props for {@link BoxBase}.
+ *
+ * @remarks
+ * Provides full control over layout, spacing, shape, elevation,
+ * borders and flex/grid behaviour. All props are optional.
+ *
+ * @category Box
+ */
+export interface BoxBaseProps extends Omit<HTMLAttributes<HTMLElement>, 'color'> {
+    /** Maps to `align-content` (grid/flex-wrap content alignment). */
+    alignContent?: React.CSSProperties['alignContent'];
+    /** Maps to `align-items` (cross-axis alignment). */
+    alignItems?: React.CSSProperties['alignItems'];
+    /** Border width (0–5). */
+    border?: ElementBorder;
+    /** Border color token. */
+    borderColor?: BorderColor;
+    /** React children inside the box. */
+    children?: ReactNode;
+    /** Layout direction shortcut. Same as `direction="col"`. */
+    col?: boolean;
+    /** Surface background token. Default: `'surface'`. */
+    color?: SurfaceColor;
+    /** Grid template columns (`3` → `repeat(3, 1fr)`). */
+    cols?: number | string;
+    /** Custom HTML element/component. Default: `div`. */
+    component?: React.ElementType;
+    /** Layout direction (`row` or `col`) for flex. Ignored if `row` or `col` is set. */
+    direction?: BoxDirection;
+    /** Native disabled attribute. Applied when supported by the rendered element. */
+    disabled?: boolean;
+    /** Semantic UUI element class (e.g. 'uui-section', 'uui-footer'). */
+    elementClass?: string;
+    /** Elevation level (0–5). */
+    elevation?: ElementElevation;
+    /** Auto-placement flow direction for grid layouts. */
+    flow?: BoxDirection;
+    /** Forces full width (100%). */
+    fullWidth?: boolean;
+    /** Gap between children (flex/grid). */
+    gap?: number | string;
+    /** Horizontal gap (`column-gap`). */
+    gapX?: number | string;
+    /** Vertical gap (`row-gap`). */
+    gapY?: number | string;
+    /** Enables flex-grow (fills remaining space). */
+    grow?: boolean;
+    /** Renders as `inline-flex`, `inline-grid` or `inline-block`. */
+    inline?: boolean;
+    /** Maps to `justify-content` (main-axis alignment). */
+    justifyContent?: React.CSSProperties['justifyContent'];
+    /** Padding (all sides). */
+    p?: number | string;
+    /** Padding bottom. */
+    pb?: number | string;
+    /** Padding left. */
+    pl?: number | string;
+    /** Maps to `place-items` (grid shortcut for align+justify items). */
+    placeItems?: React.CSSProperties['placeItems'];
+    /** Padding right. */
+    pr?: number | string;
+    /** Padding top. */
+    pt?: number | string;
+    /** Horizontal padding (`padding-left` + `padding-right`). */
+    px?: number | string;
+    /** Vertical padding (`padding-top` + `padding-bottom`). */
+    py?: number | string;
+    /** Layout direction shortcut. Same as `direction="row"`. */
+    row?: boolean;
+    /** Grid template rows (`2` → `repeat(2, 1fr)`). */
+    rows?: number | string;
+    /** Shape/border-radius token (round, rounded, smooth, square). */
+    shape?: ElementShape;
+    /** Layout mode (`flex`, `grid`, `block`). Default: `flex`. */
+    type?: BoxType;
+    /** Enables wrapping (`flex-wrap: wrap`). */
+    wrap?: boolean;
+}
+/**
+ * `BoxBase` — core layout primitive powering all semantic containers
+ * (`Box`, `Section`, `Article`, `Aside`, `Header`, `Footer`, `Nav`).
+ *
+ * Provides low-level control over layout (flex, grid, block),
+ * spacing, alignment, wrapping, elevation, borders, shape, and surface color.
+ * This component does **not** impose visual design — higher-level
+ * components add semantics, but rely on `BoxBase` for structure.
+ *
+ * Accepts both semantic styling props (color, shape, elevation)
+ * and layout utilities (padding, gap, direction, wrap, justify, align).
+ *
+ * @function
+ * @param props - Component properties.
+ *
+ * @example
+ * ```tsx
+ * <BoxBase p={16} gap={8} direction="col" elevation={2}>
+ *   <Item />
+ *   <Item />
+ * </BoxBase>
+ * ```
+ *
+ * @category Box
+ */
+export declare const BoxBase: React.ForwardRefExoticComponent<BoxBaseProps & React.RefAttributes<HTMLElement>>;

package/components/base/buttonBase/buttonBase.d.ts

@@ -0,0 +1,126 @@
+import { default as React, ReactNode } from 'react';
+import { ElementAlign, ElementDensity, ElementElevation, ElementFocusEffect, ElementFont, ElementHoverEffect, ElementOutline, ElementPressedEffect, ElementSelectedEffect, ElementShape, ElementSize, ElementTouchEffect } from '../../utils';
+import { BorderColor, SemanticColor, SurfaceColor } from '../../../utils/color';
+/**
+ * Props for the ButtonBase component.
+ *
+ * @category Base components
+ */
+export interface ButtonBaseProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'size'> {
+    /** Outline thickness when outlined. Default: 1 */
+    border?: ElementOutline;
+    /** Border color when outlined. */
+    borderColor?: BorderColor;
+    /** Custom content. Overrides label, icons, and layout. */
+    children?: ReactNode;
+    /** Semantic color theme. Default: primary */
+    color?: SemanticColor;
+    /** Initial selected state for uncontrolled toggle buttons. */
+    defaultSelected?: boolean;
+    /** Visual density of the button. */
+    density?: ElementDensity;
+    /** Disables the button. */
+    disabled?: boolean;
+    /** Required root class name. */
+    elementClass: string;
+    /** Enables elevated style. */
+    elevated?: boolean;
+    /** Explicit elevation level. */
+    elevation?: ElementElevation;
+    /** Icon rendered at the end of the button. */
+    endIcon?: React.ReactElement;
+    /** Enables filled style. */
+    filled?: boolean;
+    /** Disables elevation and elevation effects. */
+    flat?: boolean;
+    /** Focus visual effects. */
+    focusEffects?: ElementFocusEffect[];
+    /** Font token for label and content. */
+    font?: ElementFont;
+    /** Expands button to full width. */
+    fullWidth?: boolean;
+    /** Hover visual effects. */
+    hoverEffects?: ElementHoverEffect[];
+    /** Icon rendered at the start of the button. */
+    icon?: React.ReactElement;
+    /** DOM id. Auto-generated if not provided. */
+    id?: string;
+    /** Text label for the button. */
+    label?: string;
+    /** Custom leading content. */
+    leading?: ReactNode;
+    /** Imperative link trigger element. */
+    link?: React.ReactElement;
+    /** Shows loading spinner and disables interaction. */
+    loading?: boolean;
+    /** DOM name attribute. */
+    name?: string;
+    /** Blur event handler. */
+    onBlur?: React.FocusEventHandler<HTMLButtonElement>;
+    /** Change event handler (toggle buttons). */
+    onChange?: React.ChangeEventHandler<HTMLButtonElement>;
+    /** Click event handler. */
+    onClick?: React.MouseEventHandler<HTMLButtonElement>;
+    /** Change handler for file upload input. */
+    onUploadChange?: React.ChangeEventHandler<HTMLInputElement>;
+    /** Enables outlined style. */
+    outlined?: boolean;
+    /** Pressed visual effects. */
+    pressedEffects?: ElementPressedEffect[];
+    /** Controlled selected state for toggle buttons. */
+    selected?: boolean;
+    /** Semantic color override when selected. */
+    selectedColor?: SemanticColor;
+    /** Visual effects applied when selected. */
+    selectedEffects?: ElementSelectedEffect[];
+    /** Icon displayed when selected. */
+    selectedIcon?: React.ReactElement;
+    /** Shape override when selected. */
+    selectedShape?: ElementShape;
+    /** Text color override when selected. */
+    selectedTextColor?: SurfaceColor;
+    /** Shape of the button. */
+    shape?: ElementShape;
+    /** Predefined button size. Default: medium */
+    size?: ElementSize;
+    /** Text color override. */
+    textColor?: SurfaceColor;
+    /** Tooltip text and accessibility label fallback. */
+    title?: string;
+    /** Enables toggle button behavior. */
+    toggle?: boolean;
+    /** Enables tonal style. */
+    tonal?: boolean;
+    /** Tooltip alignment relative to the button. */
+    tooltipAlign?: ElementAlign;
+    /** Touch and click visual effects. */
+    touchEffects?: ElementTouchEffect[];
+    /** Custom trailing content. */
+    trailing?: ReactNode;
+    /** Native button type. Default: button */
+    type?: 'submit' | 'reset' | 'button';
+    /** Enables file upload trigger behavior. */
+    upload?: boolean;
+    /** Accepted MIME types for file upload. */
+    uploadAccept?: string;
+    /** Enables multi-file upload. */
+    uploadMultiple?: boolean;
+}
+/**
+ * Low-level base component for all button variants.
+ *
+ * Supports Material Design 3 styles, toggle behavior, loading state,
+ * file upload trigger, icons, and semantic colors.
+ *
+ * @param props - Component properties.
+ * @function
+ *
+ * @example
+ * <ButtonBase label="Save" filled icon={<SaveIcon />} />
+ *
+ * @example
+ * <ButtonBase upload label="Upload" onUploadChange={handleUpload} />
+ *
+ * @category Base components
+ */
+export declare const ButtonBase: React.ForwardRefExoticComponent<ButtonBaseProps & React.RefAttributes<HTMLButtonElement>>;