@ufoui/core 0.0.12 → 0.0.58

package/internal/icon/icon.d.ts

@@ -0,0 +1,28 @@
+import { ReactNode } from 'react';
+import { SurfaceColor } from '../../utils';
+/**
+ * Props for the {@link Icon} wrapper.
+ *
+ * @category Internal components
+ */
+export interface IconProps {
+    /** Icon graphic or element rendered inside the wrapper. */
+    icon: ReactNode;
+    /** Additional class names merged with the base `uui-icon` token. */
+    className?: string;
+    /** Theme surface token as CSS `color` (for `currentColor` SVG). */
+    color?: SurfaceColor;
+}
+/**
+ * Renders icon content with the shared `uui-icon` layout class.
+ *
+ *
+ * @function
+ * @param props Component properties.
+ *
+ * @category Internal components
+ */
+export declare const Icon: {
+    ({ icon, className, color }: IconProps): import("react/jsx-runtime").JSX.Element | null;
+    displayName: string;
+};

package/internal/index.d.ts

@@ -4,3 +4,4 @@ export * from './stateLayer/stateLayer';
 export * from './controlGrid/controlGrid';
 export * from './controlLabel/controlLabel';
 export * from './description/description';
+export * from './icon/icon';

package/internal/inlineTooltip/inlineTooltipManager.d.ts

@@ -1,12 +1,12 @@
 import { default as React, HTMLProps, ReactElement } from 'react';
-import { ElementAlign } from '../../utils';
+import { ElementPlacement } from '../../utils';
 interface InlineTooltipManagerProps extends HTMLProps<HTMLSpanElement> {
     triggerRef: React.RefObject<HTMLElement>;
     tooltip: ReactElement;
-    align: ElementAlign;
+    align: ElementPlacement;
 }
 export declare const InlineTooltipManager: {
-    ({ tooltip, align, triggerRef }: InlineTooltipManagerProps): React.ReactPortal;
+    ({ tooltip, align, triggerRef }: InlineTooltipManagerProps): React.ReactPortal | null;
     displayName: string;
 };
 export {};

package/internal/slots/slot.d.ts

@@ -22,7 +22,7 @@ interface SlotProps {
  *
  * @category Slot
  */
-export declare const Slot: ({ start, end, content, className }: SlotProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Slot: ({ start, end, content, className }: SlotProps) => import("react/jsx-runtime").JSX.Element | null;
 /**
  * Slot wrapper for leading content.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ufoui/core",
-  "version": "0.0.12",
+  "version": "0.0.58",
   "description": "Lightweight Material Design 3 UI components for React",
   "type": "module",
   "main": "./index.mjs",

package/types/breakpoints.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Defines responsive breakpoints used by the design system.
+ *
+ * @category Theme
+ */
+export type ThemeBreakpointKey = 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/**
+ * Optional custom breakpoint names added via module augmentation.
+ *
+ * @example
+ * declare module '@ufoui/core' {
+ *   interface CustomBreakpoints {
+ *     ufo: true;
+ *   }
+ * }
+ *
+ * @category Theme
+ */
+export interface CustomBreakpoints {
+}
+/**
+ * Custom breakpoint keys registered via {@link CustomBreakpoints}.
+ *
+ * @category Theme
+ */
+export type CustomBreakpointKey = Extract<keyof CustomBreakpoints, string>;
+/**
+ * Defines the canonical responsive breakpoints used by the design system.
+ *
+ * @category Theme
+ */
+export type ThemeBreakpoints = Record<ThemeBreakpointKey, string> & Partial<Record<CustomBreakpointKey, string>> & Record<string, string>;
+/**
+ * Partial variant of {@link ThemeBreakpoints}, allowing selective overrides.
+ *
+ * @category Theme
+ */
+export type PartialThemeBreakpoints = Partial<Record<ThemeBreakpointKey | CustomBreakpointKey, string>> & Record<string, string | undefined>;

package/types/color.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Defines all color roles used in a single theme color scheme (e.g. light or dark).
+ *
+ * Based on the Material Design 3 palette structure with custom extensions
+ * for semantic and system colors (e.g. info, success, warning).
+ *
+ * @remarks
+ * Provides the canonical source for all `--uui-color-*` tokens in both light and dark modes.
+ *
+ * @category Theme
+ */
+export interface ThemeColorScheme {
+    /** Primary brand color used for main UI elements. */
+    primary: string;
+    /** Foreground color displayed on primary. */
+    onPrimary: string;
+    /** Container background for primary content. */
+    primaryContainer: string;
+    /** Foreground color on primary container. */
+    onPrimaryContainer: string;
+    /** Fixed version of primary for consistent tone. */
+    primaryFixed: string;
+    /** Foreground color on primaryFixed. */
+    onPrimaryFixed: string;
+    /** Dimmed tone of primaryFixed. */
+    primaryFixedDim: string;
+    /** Variant tone for content on primaryFixedDim. */
+    onPrimaryFixedVariant: string;
+    /** Secondary color for less prominent accents. */
+    secondary: string;
+    /** Foreground color on secondary. */
+    onSecondary: string;
+    /** Background container using secondary tone. */
+    secondaryContainer: string;
+    /** Foreground color on secondary container. */
+    onSecondaryContainer: string;
+    /** Fixed version of secondary tone. */
+    secondaryFixed: string;
+    /** Foreground color on secondaryFixed. */
+    onSecondaryFixed: string;
+    /** Dimmed version of secondaryFixed. */
+    secondaryFixedDim: string;
+    /** Variant tone for content on secondaryFixedDim. */
+    onSecondaryFixedVariant: string;
+    /** Tertiary color for decorative or alternative accents. */
+    tertiary: string;
+    /** Foreground color on tertiary. */
+    onTertiary: string;
+    /** Background container using tertiary tone. */
+    tertiaryContainer: string;
+    /** Foreground color on tertiary container. */
+    onTertiaryContainer: string;
+    /** Fixed version of tertiary tone. */
+    tertiaryFixed: string;
+    /** Foreground color on tertiaryFixed. */
+    onTertiaryFixed: string;
+    /** Dimmed version of tertiaryFixed. */
+    tertiaryFixedDim: string;
+    /** Variant tone for content on tertiaryFixedDim. */
+    onTertiaryFixedVariant: string;
+    /** Warning tone for alerts or cautions. */
+    warning: string;
+    /** Foreground color on warning. */
+    onWarning: string;
+    /** Container color for warning messages. */
+    warningContainer: string;
+    /** Foreground color on warning container. */
+    onWarningContainer: string;
+    /** Fixed warning tone. */
+    warningFixed: string;
+    /** Foreground color on warningFixed. */
+    onWarningFixed: string;
+    /** Dimmed warningFixed variant. */
+    warningFixedDim: string;
+    /** Variant foreground color for dimmed warning. */
+    onWarningFixedVariant: string;
+    /** Informational tone for neutral messages. */
+    info: string;
+    /** Foreground color on info. */
+    onInfo: string;
+    /** Container background for info tone. */
+    infoContainer: string;
+    /** Foreground color on info container. */
+    onInfoContainer: string;
+    /** Fixed tone for info. */
+    infoFixed: string;
+    /** Foreground color on infoFixed. */
+    onInfoFixed: string;
+    /** Dimmed infoFixed variant. */
+    infoFixedDim: string;
+    /** Variant foreground color for dimmed info. */
+    onInfoFixedVariant: string;
+    /** Success tone for positive feedback. */
+    success: string;
+    /** Foreground color on success. */
+    onSuccess: string;
+    /** Container background for success tone. */
+    successContainer: string;
+    /** Foreground color on success container. */
+    onSuccessContainer: string;
+    /** Fixed success tone. */
+    successFixed: string;
+    /** Foreground color on successFixed. */
+    onSuccessFixed: string;
+    /** Dimmed successFixed variant. */
+    successFixedDim: string;
+    /** Variant foreground color for dimmed success. */
+    onSuccessFixedVariant: string;
+    /** Error tone for destructive actions or validation. */
+    error: string;
+    /** Foreground color on error. */
+    onError: string;
+    /** Container background for error tone. */
+    errorContainer: string;
+    /** Foreground color on error container. */
+    onErrorContainer: string;
+    /** Fixed error tone. */
+    errorFixed: string;
+    /** Foreground color on errorFixed. */
+    onErrorFixed: string;
+    /** Dimmed errorFixed variant. */
+    errorFixedDim: string;
+    /** Variant foreground color for dimmed error. */
+    onErrorFixedVariant: string;
+    /** Border and divider color. */
+    outline: string;
+    /** Secondary outline tone. */
+    outlineVariant: string;
+    /** Default surface background color. */
+    surface: string;
+    /** Foreground color on surface. */
+    onSurface: string;
+    /** Variant background tone for surfaces. */
+    surfaceVariant: string;
+    /** Foreground color on surfaceVariant. */
+    onSurfaceVariant: string;
+    /** UI background color. */
+    background: string;
+    /** Foreground color on background. */
+    onBackground: string;
+    /** Inverse surface tone (e.g. for bottom navs). */
+    inverseSurface: string;
+    /** Foreground color on inverse surface. */
+    inverseOnSurface: string;
+    /** Primary accent used on inverse surfaces. */
+    inversePrimary: string;
+    /** Color used for shadows and elevation. */
+    shadow: string;
+    /** Tint overlay for elevated components. */
+    surfaceTint: string;
+    /** Overlay color for modals, drawers, etc. */
+    scrim: string;
+    /** Surface tone for highest-level containers. */
+    surfaceContainerHighest: string;
+    /** Surface tone for high elevation containers. */
+    surfaceContainerHigh: string;
+    /** Base tone for standard surface containers. */
+    surfaceContainer: string;
+    /** Surface tone for low elevation containers. */
+    surfaceContainerLow: string;
+    /** Surface tone for lowest elevation containers. */
+    surfaceContainerLowest: string;
+    /** Brightest surface tone variant. */
+    surfaceBright: string;
+    /** Dimmed surface tone variant. */
+    surfaceDim: string;
+    /** Pure black color used for contrast or background. */
+    black: string;
+    /** Pure white color used for contrast or foreground. */
+    white: string;
+    /** Allows for additional custom tokens. */
+    [key: string]: string;
+}
+/**
+ * A partial version of {@link ThemeColorScheme}, used for theme overrides
+ * or gradual, progressive theming updates.
+ *
+ * @remarks
+ * Useful when defining incomplete color sets (e.g. custom brand palettes).
+ * Also permits additional custom token keys with optional values.
+ *
+ * @category Theme
+ */
+export type PartialThemeColorScheme = Partial<ThemeColorScheme> & Record<string, string | undefined>;
+/**
+ * Collection of named color schemes (e.g. light, dark, high-contrast).
+ * Used to organize multiple theme modes within a design system.
+ *
+ * @category Theme
+ */
+export interface ThemeColorSchemes {
+    /** Light mode color scheme. */
+    light: PartialThemeColorScheme;
+    /** Dark mode color scheme. */
+    dark: PartialThemeColorScheme;
+    /** Additional custom schemes such as high-contrast or sepia. */
+    [key: string]: PartialThemeColorScheme;
+}
+/**
+ * Built-in semantic color names available in every theme.
+ *
+ * @category Color
+ */
+export type CoreSemanticColor = 'primary' | 'secondary' | 'tertiary' | 'warning' | 'info' | 'success' | 'error';
+/**
+ * Built-in surface color names intended for backgrounds, layers, and outlines.
+ *
+ * @category Color
+ */
+export type CoreSurfaceColor = 'surface' | 'surfaceVariant' | 'background' | 'inverseSurface' | 'outline' | 'outlineVariant' | 'surfaceContainerLowest' | 'surfaceContainerLow' | 'surfaceContainer' | 'surfaceContainerHigh' | 'surfaceContainerHighest' | 'surfaceBright' | 'surfaceDim';
+/**
+ * Built-in technical color names not intended for direct usage.
+ *
+ * @category Color
+ */
+export type CoreThemeColor = 'onSurface' | 'onSurfaceVariant' | 'onBackground' | 'inverseOnSurface' | 'inversePrimary' | 'surfaceTint' | 'scrim' | 'shadow' | 'black' | 'white';
+/**
+ * Augmentation point for custom semantic colors.
+ *
+ * @example
+ * declare module '@ufoui/core' {
+ *   interface CustomColors {
+ *     myBlue: true;
+ *   }
+ * }
+ *
+ * @category Color
+ */
+export interface CustomColors {
+}
+/**
+ * Custom semantic color token keys registered via {@link CustomColors}.
+ *
+ * @category Color
+ */
+export type CustomColorKey = Extract<keyof CustomColors, string>;
+/**
+ * Base semantic color (core + augmented).
+ *
+ * @category Color
+ */
+export type SemanticBaseColor = CoreSemanticColor | CustomColorKey;
+/**
+ * Builds `on*` color name.
+ *
+ * @category Color
+ */
+export type OnColor<T extends string> = `on${Capitalize<T>}`;
+/**
+ * Semantic color used in component APIs.
+ *
+ * @category Color
+ */
+export type SemanticColor = SemanticBaseColor;
+/**
+ * Extended semantic colors.
+ *
+ * @category Color
+ */
+export type ExtendedColor = `${SemanticBaseColor}Container` | `${SemanticBaseColor}Fixed` | `${SemanticBaseColor}FixedDim`;
+/**
+ * `on*` counterparts for extended colors.
+ *
+ * @category Color
+ */
+export type OnExtendedColor = OnColor<`${SemanticBaseColor}Container`> | OnColor<`${SemanticBaseColor}Fixed`> | OnColor<`${SemanticBaseColor}FixedVariant`>;
+/**
+ * Surface colors.
+ *
+ * @category Color
+ */
+export type SurfaceColor = CoreSurfaceColor | ExtendedColor;
+/**
+ * Colors allowed in component props.
+ *
+ * @category Color
+ */
+export type BaseColor = SemanticColor | SurfaceColor;
+/**
+ * Full theme color set.
+ *
+ * @category Color
+ */
+export type ThemeColor = BaseColor | OnColor<SemanticBaseColor> | OnExtendedColor | CoreThemeColor;
+/**
+ * Border color.
+ *
+ * @category Color
+ */
+export type BorderColor = BaseColor;
+/**
+ * Input color map used to seed/generate theme schemes.
+ *
+ * @remarks
+ * Accepts only semantic base color keys (core + augmented via {@link CustomColors}).
+ *
+ * @category Theme
+ */
+export type ThemeCustomColors = Partial<Record<SemanticBaseColor, string>>;

package/types/dialog.d.ts

@@ -0,0 +1,37 @@
+import { MotionAnimation } from './motion';
+/**
+ * Layout mode for the DialogBase component.
+ *
+ * @remarks
+ * Determines dialog placement and sizing:
+ * - `'basic'` - centered dialog
+ * - `'fullscreen'` - full viewport
+ * - `'dockLeft'` / `'dockRight'` / `'dockTop'` / `'dockBottom'` -  edge-docked panels
+ *
+ * @category Dialog
+ */
+export type DialogType = 'basic' | 'fullscreen' | 'dockRight' | 'dockLeft' | 'dockTop' | 'dockBottom';
+/**
+ * Animation preset for open and close transitions.
+ *
+ * @remarks
+ * Use `'none'` to disable motion. Otherwise uses a {@link MotionAnimation} value.
+ * When omitted, a default animation is chosen for the current layout mode.
+ *
+ * @category Dialog
+ */
+export type DialogAnimation = 'none' | MotionAnimation;
+/**
+ * Icon slot within dialog layout.
+ *
+ * Defines where the icon is rendered inside the dialog structure.
+ *
+ * Slots:
+ * - **leading** – inline with the title
+ * - **top** – placed above the title in the header
+ * - **contentLeft** – placed on the left side of the content area
+ * - **contentRight** – placed on the right side of the content area
+ *
+ * @category Dialog
+ */
+export type DialogIconSlot = 'leading' | 'top' | 'contentLeft' | 'contentRight';

package/types/fonts.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Defines built-in typography tokens available in the design system.
+ *
+ * @category Theme
+ */
+export type CoreFont = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall' | 'caption' | 'overline';
+/**
+ * Optional custom typography tokens added via module augmentation.
+ *
+ * @example
+ * declare module '@ufoui/core' {
+ *   interface CustomFonts {
+ *     promoFont: true;
+ *   }
+ * }
+ *
+ * @category Theme
+ */
+export interface CustomFonts {
+}
+/**
+ * Custom typography token keys registered via {@link CustomFonts}.
+ *
+ * @category Theme
+ */
+export type CustomFontKey = Extract<keyof CustomFonts, string>;
+/**
+ * All theme typography tokens (core + custom).
+ *
+ * @category Theme
+ */
+export type ThemeFont = CoreFont | CustomFontKey;
+/**
+ * Typography token accepted by component-level `font` props.
+ *
+ * @category Theme
+ */
+export type ElementFont = ThemeFont;
+/**
+ * Full font class map keyed by typography token names.
+ *
+ * @remarks
+ * Includes core and custom typography keys, while also allowing additional string keys.
+ *
+ * @category Theme
+ */
+export type ThemeFonts = Partial<Record<ThemeFont, string>> & Record<string, string>;
+/**
+ * Partial variant of {@link ThemeFonts}, allowing selective overrides.
+ *
+ * @category Theme
+ */
+export type PartialThemeFonts = Partial<Record<ThemeFont, string>> & Record<string, string | undefined>;

package/types/index.d.ts

@@ -1,2 +1,6 @@
+export * from './breakpoints';
+export * from './fonts';
+export * from './color';
 export * from './theme';
 export * from './motion';
+export * from './dialog';

package/types/motion.d.ts

@@ -2,9 +2,9 @@ export type MotionAnimation = 'fade' | 'fadeBlur' | 'scale' | 'scaleBlur' | 'pop
 export declare const motionClassMap: Record<MotionAnimation, string>;
 /**
  * Returns CSS class name for given motion animation.
- * Returns empty string when animation is not defined.
+ * Returns empty string when animation is not defined or set to 'none'.
  */
-export declare function getAnimationClass(animation?: MotionAnimation): string;
+export declare function getAnimationClass(animation?: MotionAnimation | 'none'): string;
 /**
  * Returns list of available motion animation names.
  */