@ufoui/core 0.0.58 → 0.0.124

package/package.json

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

package/types/color.d.ts

@@ -207,13 +207,14 @@ export type CoreSemanticColor = 'primary' | 'secondary' | 'tertiary' | 'warning'
  *
  * @category Color
  */
-export type CoreSurfaceColor = 'surface' | 'surfaceVariant' | 'background' | 'inverseSurface' | 'outline' | 'outlineVariant' | 'surfaceContainerLowest' | 'surfaceContainerLow' | 'surfaceContainer' | 'surfaceContainerHigh' | 'surfaceContainerHighest' | 'surfaceBright' | 'surfaceDim';
+export type CoreSurfaceColor = 'surface' | 'surfaceVariant' | 'background' | 'inverseSurface' | 'surfaceContainerLowest' | 'surfaceContainerLow' | 'surfaceContainer' | 'surfaceContainerHigh' | 'surfaceContainerHighest' | 'surfaceBright' | 'surfaceDim' | 'black' | 'white';
+export type CoreBorderColor = 'outline' | 'outlineVariant';
 /**
  * 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';
+export type CoreThemeColor = 'onSurface' | 'onSurfaceVariant' | 'onBackground' | 'inverseOnSurface' | 'inversePrimary' | 'surfaceTint' | 'scrim' | 'shadow';
 /**
  * Augmentation point for custom semantic colors.
  *
@@ -257,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.
  *
@@ -277,17 +278,59 @@ export type SurfaceColor = CoreSurfaceColor | ExtendedColor;
  */
 export type BaseColor = SemanticColor | SurfaceColor;
 /**
- * Full theme color set.
+ * Border color.
  *
  * @category Color
  */
-export type ThemeColor = BaseColor | OnColor<SemanticBaseColor> | OnExtendedColor | CoreThemeColor;
+export type BorderColor = BaseColor | CoreBorderColor | `${SemanticBaseColor}FixedDim`;
 /**
- * Border color.
+ * Colors allowed for plain text content.
  *
  * @category Color
  */
-export type BorderColor = BaseColor;
+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.
  *
@@ -296,4 +339,4 @@ export type BorderColor = BaseColor;
  *
  * @category Theme
  */
-export type ThemeCustomColors = Partial<Record<SemanticBaseColor, string>>;
+export type ThemeCustomColors = Partial<Record<SemanticBaseColor, CustomColorConfig>>;

package/types/dialog.d.ts

@@ -1,4 +1,3 @@
-import { MotionAnimation } from './motion';
 /**
  * Layout mode for the DialogBase component.
  *
@@ -11,16 +10,6 @@ import { MotionAnimation } from './motion';
  * @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.
  *

package/types/motion.d.ts

@@ -1,15 +1,66 @@
-export type MotionAnimation = 'fade' | 'fadeBlur' | 'scale' | 'scaleBlur' | 'popup' | 'slideUp' | 'slideDown' | 'slideLeft' | 'slideRight' | 'slideUpBlur' | 'slideDownBlur' | 'slideLeftBlur' | 'slideRightBlur' | 'rotate' | 'rotateUpRight' | 'rotateUpLeft' | 'rollLeft' | 'rollRight' | 'flipX' | 'flipY' | 'bounce' | 'squish' | 'rubber' | 'popElastic' | 'jelly';
-export declare const motionClassMap: Record<MotionAnimation, string>;
+export declare const motionClassMap: {
+    fade: string;
+    fadeBlur: string;
+    scale: string;
+    scaleBlur: string;
+    popup: string;
+    slideUp: string;
+    slideDown: string;
+    slideLeft: string;
+    slideRight: string;
+    slideUpBlur: string;
+    slideDownBlur: string;
+    slideLeftBlur: string;
+    slideRightBlur: string;
+    rotate: string;
+    rotateUpRight: string;
+    rotateUpLeft: string;
+    rollLeft: string;
+    rollRight: string;
+    flipX: string;
+    flipY: string;
+    bounce: string;
+    squish: string;
+    rubber: string;
+    popElastic: string;
+    jelly: string;
+    none: string;
+};
+export type MotionAnimation = keyof typeof motionClassMap;
 /**
  * Returns CSS class name for given motion animation.
  * Returns empty string when animation is not defined or set to 'none'.
  */
-export declare function getAnimationClass(animation?: MotionAnimation | 'none'): string;
+export declare function getAnimationClass(animation?: MotionAnimation): string;
 /**
- * Returns list of available motion animation names.
+ * Returns list of available motion animation names, excluding `'none'`.
  */
 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.
@@ -11,9 +11,10 @@ export declare function getOnColorName(colorName: ThemeColor): ThemeColor | unde
 export declare function getColorNames(type: 'semantic'): SemanticColor[];
 export declare function getColorNames(type: 'extended'): ExtendedColor[];
 export declare function getColorNames(type: 'surface'): SurfaceColor[];
-export declare function getColorNames(type: 'theme'): ThemeColor[];
 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**.
  *
@@ -32,7 +33,7 @@ export declare function getColorNames(type: 'border'): BorderColor[];
  * ```
  * @category Color
  */
-export declare const getSurfaceColorVar: (color: BaseColor) => {
+export declare const getSurfaceColorVar: (color: ThemeColor) => {
     color: string;
     onColor: string;
 };

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/utils.d.ts

@@ -126,7 +126,7 @@ export declare const getShapeClass: (shape?: ElementShape) => string;
  * @param size Size token.
  * @returns CSS class for size variant.
  */
-export declare const getSizeClass: (size: ElementSize) => string;
+export declare const getSizeClass: (size?: ElementSize) => string;
 /**
  * Returns the appropriate CSS class for the given border size.
  *

package/components/dialogs/dialogActions.d.ts

@@ -1,26 +0,0 @@
-import { ReactNode } from 'react';
-/** Slot contract for components that can act as dialog actions. */
-export interface DialogActionProps {
-    label?: string;
-    'aria-label'?: string;
-    icon?: ReactNode;
-    leading?: ReactNode;
-    trailing?: ReactNode;
-    disabled?: boolean;
-}
-export interface DialogActionsProps {
-    actions?: ReactNode;
-    placement?: 'top' | 'subtitle' | 'bottom' | 'inline';
-    align?: 'start' | 'center' | 'end';
-    stack?: boolean;
-    className?: string;
-    /** Maximum number of visible actions before the rest collapse into an overflow menu. */
-    maxActions?: number;
-    /** Accessible label for the overflow actions button. Default: "More actions" */
-    moreLabel?: string;
-    moreIcon?: ReactNode;
-}
-export declare const DialogActions: {
-    ({ actions, className, placement, align, stack, maxActions, moreLabel, }: DialogActionsProps): import("react/jsx-runtime").JSX.Element | null;
-    displayName: string;
-};

package/components/dialogs/dialogActions.guards.d.ts

@@ -1,15 +0,0 @@
-import { ReactElement, ReactNode } from 'react';
-import { DialogActionProps } from './dialogActions';
-export declare const IS_DIALOG_ACTION: unique symbol;
-/**
- * Type guard that checks whether a React node is a dialog action component.
- *
- * Identifies dialog action elements by the internal {@link IS_DIALOG_ACTION} symbol
- * attached to the component type.
- *
- * @param el - React node to test.
- * @returns `true` if the node is a dialog action element.
- *
- * @internal
- */
-export declare function isDialogAction(el: ReactNode): el is ReactElement<DialogActionProps>;

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;