@ufoui/core 0.0.88 → 0.0.124

package/package.json

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

package/types/color.d.ts

@@ -258,7 +258,7 @@ export type SemanticColor = SemanticBaseColor;
  *
  * @category Color
  */
-export type ExtendedColor = `${SemanticBaseColor}Container` | `${SemanticBaseColor}Fixed` | `${SemanticBaseColor}FixedDim`;
+export type ExtendedColor = `${SemanticBaseColor}Container` | `${SemanticBaseColor}Fixed`;
 /**
  * `on*` counterparts for extended colors.
  *
@@ -282,13 +282,55 @@ export type BaseColor = SemanticColor | SurfaceColor;
  *
  * @category Color
  */
-export type BorderColor = BaseColor | CoreBorderColor;
+export type BorderColor = BaseColor | CoreBorderColor | `${SemanticBaseColor}FixedDim`;
+/**
+ * Colors allowed for plain text content.
+ *
+ * @category Color
+ */
+export type TextColor = SemanticColor | 'onSurface' | 'onBackground' | 'onSurfaceVariant' | OnColor<`${SemanticBaseColor}Container`>;
 /**
  * Full theme color set.
  *
  * @category Color
  */
 export type ThemeColor = BorderColor | OnColor<SemanticBaseColor> | OnExtendedColor | CoreThemeColor;
+/**
+ * Value for a single color role — either a plain hex string or an explicit color/on pair.
+ *
+ * @category Theme
+ */
+export type ColorRoleValue = string | {
+    color: string;
+    on?: string;
+};
+/**
+ * Full configuration for a custom semantic color token.
+ *
+ * @remarks
+ * - **Plain string** — seed hex for standard MD3 tonal generation. All roles are MD3-computed.
+ * - **Object** — exact color overrides per mode:
+ *   - `main.light` / `main.dark` set the primary role token. `dark` defaults to `light` if omitted.
+ *   - Each value is either a plain hex string or `{ color, on? }`. When `on` is omitted,
+ *     the counterpart is derived from the overridden color's luminance (HCT tone < 50 → white, ≥ 50 → near-black).
+ *   - `fixed` controls the `Fixed` / `onFixed` tokens:
+ *     - omitted: inherited from the resolved `main` values
+ *     - `'preserve'`: keeps MD3-generated values unchanged
+ *     - object `{ light, dark? }`: explicit override, same rules as `main`
+ *   - `Container` roles are always MD3-generated and are not affected by this config.
+ *
+ * @category Theme
+ */
+export type CustomColorConfig = string | {
+    main: {
+        light: ColorRoleValue;
+        dark?: ColorRoleValue;
+    };
+    fixed?: 'preserve' | {
+        light: ColorRoleValue;
+        dark?: ColorRoleValue;
+    };
+};
 /**
  * Input color map used to seed/generate theme schemes.
  *
@@ -297,4 +339,4 @@ export type ThemeColor = BorderColor | OnColor<SemanticBaseColor> | OnExtendedCo
  *
  * @category Theme
  */
-export type ThemeCustomColors = Partial<Record<SemanticBaseColor, string>>;
+export type ThemeCustomColors = Partial<Record<SemanticBaseColor, CustomColorConfig>>;

package/types/motion.d.ts

@@ -37,6 +37,30 @@ export declare function getAnimationClass(animation?: MotionAnimation): string;
  */
 export declare function getAnimationList(): MotionAnimation[];
 export type MotionStyle = 'regular' | 'expressive';
+/**
+ * Motion configuration.
+ *
+ * Allows passing either:
+ * - animation preset name (`MotionAnimation`)
+ * - full config object with animation, duration and style
+ */
+export interface MotionConfig {
+    /** Motion animation preset. */
+    animation: MotionAnimation;
+    /** Animation duration in milliseconds. */
+    duration?: number;
+    /** Motion style variant. */
+    style?: MotionStyle;
+    /** First-render behaviour: `'animate'` plays the open transition on mount, `'skip'` shows the final state immediately. Defaults to the component's own UX default when omitted. */
+    initial?: 'animate' | 'skip';
+}
+/**
+ * Motion value.
+ *
+ * Can be provided as a shorthand animation preset name
+ * or as a full {@link MotionConfig} object.
+ */
+export type ElementAnimation = MotionAnimation | MotionConfig;
 /**
  * Returns CSS class name for motion style.
  * Expressive enables extended motion parameters.

package/utils/color.d.ts

@@ -1,5 +1,5 @@
-import { BaseColor, BorderColor, ExtendedColor, SemanticColor, SurfaceColor, ThemeColor } from '../types';
-export type { CoreSemanticColor, CoreSurfaceColor, CoreThemeColor, CustomColors, SemanticBaseColor, OnColor, SemanticColor, ExtendedColor, OnExtendedColor, SurfaceColor, BaseColor, ThemeColor, BorderColor, } from '../types';
+import { BaseColor, BorderColor, ExtendedColor, SemanticColor, SurfaceColor, TextColor, ThemeColor } from '../types';
+export type { CoreSemanticColor, CoreSurfaceColor, CoreThemeColor, CustomColors, SemanticBaseColor, OnColor, SemanticColor, ExtendedColor, OnExtendedColor, SurfaceColor, BaseColor, ThemeColor, BorderColor, TextColor, } from '../types';
 export declare function getOnColorName(colorName: ThemeColor): ThemeColor | undefined;
 /**
  * Returns all color names from the global registry for the selected type.
@@ -13,6 +13,7 @@ export declare function getColorNames(type: 'extended'): ExtendedColor[];
 export declare function getColorNames(type: 'surface'): SurfaceColor[];
 export declare function getColorNames(type: 'base'): BaseColor[];
 export declare function getColorNames(type: 'border'): BorderColor[];
+export declare function getColorNames(type: 'text'): TextColor[];
 export declare function getColorNames(type: 'theme'): ThemeColor[];
 /**
  * Returns basic CSS variable references for a **surface color**.

package/utils/colorRegistry.d.ts

@@ -3,7 +3,7 @@
  *
  * @category Theme
  */
-export type ColorType = 'semantic' | 'surface' | 'extended' | 'base' | 'border' | 'theme';
+export type ColorType = 'semantic' | 'surface' | 'extended' | 'base' | 'border' | 'text' | 'theme';
 /**
  * Metadata entry describing how a color name should be used.
  *

package/utils/generateMaterialColors.d.ts

@@ -1,26 +1,52 @@
 import { ThemeColorSchemes, ThemeCustomColors } from '../types';
 /**
- * Generates a full ThemeColorSchemes object (light and dark modes) based on a seed color,
- * and optional semantic seed colors.
+ * Generates a full ThemeColorSchemes object (light and dark modes) based on a seed color
+ * and optional custom semantic colors.
  *
- * Internally uses the Material Design 3 `themeFromSourceColor()` generator and applies
- * full resolution of all MD3 roles as defined in ThemeSchemeKeys.
+ * Internally uses the Material Design 3 `themeFromSourceColor()` generator. Each color is blended
+ * toward the source hue and expanded into a full set of roles: main, `on*`, `Container`,
+ * `onContainer`, `Fixed`, `onFixed`, `FixedDim`, and `onFixedVariant`.
  *
- * Custom semantic colors (e.g. `info`, `warning`, `success`) are blended into the palette
- * and expanded to support `Container`, `Fixed`, `Dim`, and `on*` roles.
+ * Built-in defaults (`info`, `warning`, `success`) are always included unless overridden.
  *
- * @param seedColor - Optional seed color in hex (e.g. "#6200ee"). Used as the base for the primary palette.
- *                    Defaults to `#6750A4` if not provided.
- * @param colors - Optional map of semantic base colors (core + augmented).
- *                 Defaults include `info`, `warning`, and `success`.
+ * @remarks
+ * Each entry in `colors` accepts two forms:
  *
- * @returns A fully resolved ThemeColorSchemes object with all required color roles populated for light and dark modes.
+ * - **String** — seed hex used to generate the full MD3 tonal palette. All roles are MD3-computed.
+ *   ```ts
+ *   { info: '#2196f3' }
+ *   ```
+ *
+ * - **Object** — allows exact color overrides per mode:
+ *   - `main.light` / `main.dark` — overrides the primary role token. `dark` defaults to `light` if omitted.
+ *   - `on` color is derived automatically from the overridden color's luminance (HCT tone < 50 → white, ≥ 50 → near-black)
+ *     unless provided explicitly via `{ color, on }`.
+ *   - `fixed` — controls the `Fixed` / `onFixed` tokens:
+ *     - omitted: inherited from `main` override
+ *     - `'preserve'`: keeps the MD3-generated values
+ *     - object `{ light, dark? }`: explicit override, same rules as `main`
+ *   - `Container` roles are always MD3-generated and cannot be overridden here.
+ *   ```ts
+ *   { brandBlue: { main: { light: '#0057FF' }, fixed: 'preserve' } }
+ *   { brandBlue: { main: { light: { color: '#0057FF', on: '#FFD600' } } } }
+ *   ```
+ *
+ * @param seedColor - Hex string used as the MD3 source color for the primary palette. Defaults to `#6750A4`.
+ * @param colors - Optional map of semantic color configs (core + augmented via `CustomColors`).
+ *
+ * @returns A fully resolved `ThemeColorSchemes` object for light and dark modes.
  *          Also updates the global color registry via `setColorRegistry()`.
  *
  * @example
  * ```ts
- * const schemes = generateMaterialColors('#6200ee', { info: '#2196f3' });
+ * const schemes = generateMaterialColors('#6200ee', {
+ *     info: '#2196f3',
+ *     brandBlue: { main: { light: '#0057FF', dark: '#0057FF' } },
+ *     brandBlueYellow: { main: { light: { color: '#0057FF', on: '#FFD600' } } },
+ * });
  * const primary = schemes.light.primary;
+ * const brandBlue = schemes.dark.brandBlue;
+ * const onBrandBlueYellow = schemes.light.onBrandBlueYellow; // '#FFD600'
  * ```
  *
  * @category Theme

package/utils/index.d.ts

@@ -8,7 +8,7 @@ export * from './generateMaterialColors';
 export * from './applyThemeColors';
 export * from './breakpoints';
 export * from './toasts';
-export * from './uniqueID';
+export * from './useUniqueId';
 export * from './controlStyle';
 export * from './getWrapperStyle';
 export * from './flatChildren';

package/utils/useUniqueId.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generates a stable React component ID safe for SSR and hydration.
+ *
+ * @param prefix - String prepended to the generated ID.
+ * @returns A unique ID in the form `${prefix}_xxxx`.
+ *
+ * @category Utils
+ */
+export declare const useUniqueId: (prefix: string) => string;

package/utils/uniqueID.d.ts

@@ -1,14 +0,0 @@
-/**
- * Generates a fast, pseudo-random unique ID.
- *
- * @param prefix - String prepended to the generated ID.
- * @returns A unique ID in the form `${prefix}_xxxx`.
- *
- * @remarks
- * - Uses `Math.random()` → extremely fast, ideal for UI/runtime IDs.
- * - Not cryptographically secure.
- * - Suitable for components, form fields, ripple effects, etc.
- *
- * @category Utils
- */
-export declare const uniqueID: (prefix: string) => string;