@ufoui/core 0.0.40 → 0.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ufoui/core",
-  "version": "0.0.40",
+  "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/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,3 +1,6 @@
+export * from './breakpoints';
+export * from './fonts';
+export * from './color';
 export * from './theme';
 export * from './motion';
 export * from './dialog';

package/types/theme.d.ts

@@ -1,207 +1,6 @@
-/**
- * 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 ThemeScheme {
-    /** 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 ThemeScheme}, used for theme overrides
- * or gradual, progressive theming updates.
- *
- * @remarks
- * Useful when defining incomplete color sets (e.g. custom brand palettes).
- *
- * @category Theme
- */
-export type PartialThemeScheme = Partial<ThemeScheme>;
-/**
- * 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 ThemeSchemes {
-    /** Light mode color scheme. */
-    light: PartialThemeScheme;
-    /** Dark mode color scheme. */
-    dark: PartialThemeScheme;
-    /** Additional custom schemes such as high-contrast or sepia. */
-    [key: string]: PartialThemeScheme;
-}
-/**
- * Partial variant of {@link ThemeSchemes}, allowing selective definition
- * of available color modes.
- *
- * @category Theme
- */
-export type PartialThemeSchemes = Partial<ThemeSchemes>;
+import { ThemeBreakpoints } from './breakpoints';
+import { ThemeFonts } from './fonts';
+import { ThemeColorSchemes } from './color';
 /**
  * Defines the overall theme configuration, including
  * the active mode and all available color schemes.
@@ -212,5 +11,9 @@ export interface Theme {
     /** Indicates whether dark mode is currently active. */
     darkMode: boolean;
     /** Collection of all available color schemes. */
-    schemes: ThemeSchemes;
+    schemes: ThemeColorSchemes;
+    /** Responsive breakpoint tokens. */
+    breakpoints: ThemeBreakpoints;
+    /** Font class map keyed by theme font token name. */
+    fonts: ThemeFonts;
 }

package/utils/{applyThemeTokens.d.ts → applyThemeColors.d.ts}

@@ -1,4 +1,4 @@
-import { ThemeSchemes } from '../types';
+import { ThemeColorSchemes } from '../types';
 /**
  * Applies resolved theme tokens as CSS custom properties.
  *
@@ -7,4 +7,4 @@ import { ThemeSchemes } from '../types';
  *
  * @category Theme
  */
-export declare function applyThemeTokens(schemes: ThemeSchemes): ThemeSchemes;
+export declare function applyThemeColors(schemes: ThemeColorSchemes): ThemeColorSchemes;