@ufoui/core 0.0.40 → 0.0.58

package/utils/breakpoints/breakpoint.d.ts

@@ -0,0 +1,59 @@
+import { ThemeBreakpoints } from '../../types';
+/**
+ * Viewport snapshot used by the breakpoint store.
+ *
+ * @category Breakpoints
+ */
+export type ViewportSnapshot = {
+    width: number;
+    isPrint: boolean;
+};
+type BreakpointEntry = {
+    key: string;
+    minWidth: number;
+};
+/**
+ * Converts a CSS length value to pixels.
+ *
+ * Supports `px`, `rem`, and unitless numeric strings.
+ *
+ * @function
+ * @param value CSS length value to convert.
+ *
+ * @category Breakpoints
+ */
+export declare const toPx: (value: string) => number;
+/**
+ * Returns the ordered list of theme breakpoints sorted by width.
+ *
+ * @function
+ * @param breakpoints Breakpoint map from the active theme.
+ *
+ * @category Breakpoints
+ */
+export declare const getOrderedBreakpoints: (breakpoints: ThemeBreakpoints) => BreakpointEntry[];
+/**
+ * Resolves the active breakpoint key for a viewport width.
+ *
+ * @function
+ * @param breakpoints Ordered breakpoint entries.
+ * @param width Current viewport width.
+ *
+ * @category Breakpoints
+ */
+export declare const resolveBreakpoint: (breakpoints: BreakpointEntry[], width: number) => string;
+/**
+ * Resolves a responsive value map against the current viewport state.
+ *
+ * @function
+ * @param values Responsive values keyed by breakpoint.
+ * @param breakpoints Ordered breakpoint entries.
+ * @param snapshot Current viewport snapshot.
+ *
+ * @category Breakpoints
+ */
+export declare const resolveResponsiveValue: <T>(values: {
+    base?: T;
+    print?: T;
+} & Record<string, T | undefined>, breakpoints: BreakpointEntry[], snapshot: ViewportSnapshot) => T | undefined;
+export {};

package/utils/breakpoints/breakpointStore.d.ts

@@ -0,0 +1,32 @@
+import { ViewportSnapshot } from './breakpoint';
+/**
+ * Subscriber function used by the breakpoint store.
+ *
+ * @category Hooks
+ */
+export type BreakpointStoreSubscriber = () => void;
+/**
+ * Shared viewport store used by responsive hooks.
+ *
+ * @category Hooks
+ */
+export declare const breakpointStore: {
+    /**
+     * Subscribes to viewport state updates.
+     *
+     * @function
+     */
+    subscribe(listener: BreakpointStoreSubscriber): () => void;
+    /**
+     * Returns the current viewport snapshot.
+     *
+     * @function
+     */
+    getSnapshot(): ViewportSnapshot;
+    /**
+     * Returns the server-side fallback snapshot.
+     *
+     * @function
+     */
+    getServerSnapshot(): ViewportSnapshot;
+};

package/utils/breakpoints/index.d.ts

@@ -0,0 +1,2 @@
+export * from './breakpoint';
+export * from './breakpointStore';

package/utils/color.d.ts

@@ -1,91 +1,5 @@
-/**
- * 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';
-/** * Empty custom-color map used as the default generic parameter. * * @category Color */
-export type EmptyColors = Record<never, never>;
-/**
- * Augmentation point for custom semantic colors.
- *
- * @example
- * declare module '@ufoui/core' {
- *   interface CustomColors {
- *     myBlue: true;
- *   }
- * }
- *
- * @category Color
- */
-export interface CustomColors {
-}
-/**
- * Base semantic color (core + augmented).
- *
- * @category Color
- */
-export type SemanticBaseColor = CoreSemanticColor | keyof CustomColors;
-/**
- * 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;
+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';
 export declare function getOnColorName(colorName: ThemeColor): ThemeColor | undefined;
 /**
  * Returns all color names from the global registry for the selected type.

package/utils/colorRegistry.d.ts

@@ -35,10 +35,3 @@ export declare function setColorRegistry(registry: ColorRegistry): void;
  * @category Theme
  */
 export declare function getColorRegistry(): ColorRegistry;
-/**
- * Resolves the paired contrast color from the global color registry.
- *
- * @param colorName - Base color name from the registry.
- * @returns Linked `onColor` value if present.
- * @category Theme
- */

package/utils/createRipple.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+/**
+ * Creates a material-style ripple effect inside the given element.
+ *
+ * @param el - Target element that receives the ripple.
+ * @param event - Mouse event used to determine the ripple origin.
+ * @param host - Optional host element that receives the ripple container instead of `el`.
+ *
+ * @remarks
+ * - Automatically clears previous ripples.
+ * - Injects a `.ripple-container` and `.ripple` element.
+ * - Uses the element's client size and border radius.
+ * - Safe for buttons, icon buttons, list items, etc.
+ *
+ * @category Utils
+ */
+export declare const createRipple: (el: HTMLElement, event: React.MouseEvent<HTMLElement>, host?: HTMLElement) => void;

package/utils/fontRegistry.d.ts

@@ -0,0 +1,29 @@
+import { ElementFont, PartialThemeFonts, ThemeFont } from '../types';
+/**
+ * Built-in font names available in the default font registry.
+ *
+ * @category Theme
+ */
+export declare const coreFonts: readonly ["displayLarge", "displayMedium", "displaySmall", "headlineLarge", "headlineMedium", "headlineSmall", "titleLarge", "titleMedium", "titleSmall", "labelLarge", "labelMedium", "labelSmall", "bodyLarge", "bodyMedium", "bodySmall", "caption", "overline"];
+/**
+ * Replaces the runtime font registry with core fonts plus provided overrides.
+ *
+ * @param fonts - Optional font class overrides keyed by font name.
+ * @category Theme
+ */
+export declare const setFontRegistry: (fonts?: PartialThemeFonts) => void;
+/**
+ * Returns all font names currently registered at runtime.
+ *
+ * @returns List of registered font names.
+ * @category Theme
+ */
+export declare const getFontNames: () => ThemeFont[];
+/**
+ * Returns the CSS class registered for the given font name.
+ *
+ * @param font - Font name key.
+ * @returns Registered CSS class or empty string when key is not registered.
+ * @category Theme
+ */
+export declare const getFontClass: (font: ElementFont) => string;

package/utils/generateMaterialColors.d.ts

@@ -1,8 +1,7 @@
-import { PartialThemeSchemes, ThemeSchemes } from '../types';
-export type UserColors = Record<string, string>;
+import { ThemeColorSchemes, ThemeCustomColors } from '../types';
 /**
- * Generates a full ThemeSchemes object (light and dark modes) based on a seed color,
- * optional token overrides, and custom semantic colors (info, warning, success).
+ * Generates a full ThemeColorSchemes object (light and dark modes) based on a seed color,
+ * and optional semantic seed colors.
  *
  * Internally uses the Material Design 3 `themeFromSourceColor()` generator and applies
  * full resolution of all MD3 roles as defined in ThemeSchemeKeys.
@@ -12,20 +11,18 @@ export type UserColors = Record<string, string>;
  *
  * @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 custom base colors. Defaults include `info`, `warning`, and `success`.
- *                 Any key can be provided (e.g. `brand`, `neutralStrong`, `secondary`).
- * @param customSchemes - Optional skin overrides for schemes (e.g. light/dark/high-contrast).
- *                        Applied as the final merge step.
+ * @param colors - Optional map of semantic base colors (core + augmented).
+ *                 Defaults include `info`, `warning`, and `success`.
  *
- * @returns A fully resolved ThemeSchemes object with all required color roles populated for light and dark modes.
+ * @returns A fully resolved ThemeColorSchemes object with all required color roles populated 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' });
  * const primary = schemes.light.primary;
  * ```
  *
  * @category Theme
  */
-export declare function generateMaterialColors(seedColor?: string, colors?: UserColors, customSchemes?: PartialThemeSchemes): ThemeSchemes;
+export declare function generateMaterialColors(seedColor?: string, colors?: ThemeCustomColors): ThemeColorSchemes;

package/utils/index.d.ts

@@ -1,9 +1,12 @@
 export * from './color';
+export { getFontNames, getFontClass, setFontRegistry } from './fontRegistry';
+export type { ElementFont } from '../types/fonts';
 export * from './utils';
 export * from './calculateFloatingPosition';
 export * from './interactionMode';
 export * from './generateMaterialColors';
-export * from './applyThemeTokens';
+export * from './applyThemeColors';
+export * from './breakpoints';
 export * from './toasts';
 export * from './uniqueID';
 export * from './controlStyle';
@@ -11,3 +14,5 @@ export * from './getWrapperStyle';
 export * from './flatChildren';
 export * from './renderPortal';
 export * from './colorRegistry';
+export * from './mergeOverrides';
+export { createRipple } from './createRipple';

package/utils/mergeOverrides.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Merges override values into a base string map, skipping `undefined` entries.
+ *
+ * @typeParam TBase - Base map type to preserve in the merged result.
+ * @param base - Base key/value map.
+ * @param overrides - Optional override map where `undefined` means "no change".
+ * @returns Object with merged map and list of keys that were actually applied.
+ * @category Theme
+ */
+export declare function mergeOverrides<TBase extends Record<string, string>>(base: TBase, overrides?: Record<string, string | undefined>): {
+    merged: TBase;
+    appliedKeys: string[];
+};

package/utils/utils.d.ts

@@ -1,3 +1,4 @@
+import { default as React } from 'react';
 export type ElementSize = 'extraSmall' | 'small' | 'medium' | 'large' | 'extraLarge';
 export type ElementInset = 'none' | 'left' | 'right' | 'top' | 'bottom' | 'middle';
 export type ElementShape = 'square' | 'smooth' | 'rounded' | 'round';
@@ -81,7 +82,6 @@ export type ElementPressedEffect = 'elevate' | 'overlay' | 'scale';
 export type ElementHoverEffect = 'elevate' | 'overlay' | 'color';
 export type ElementSelectedEffect = 'color' | 'morph' | 'border' | 'overlay';
 export type ElementTouchEffect = 'ripple';
-export type ElementFont = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall' | 'caption' | 'overline';
 export type ElementTextPlacement = 'start' | 'end' | 'top' | 'bottom';
 /**
  * Converts a camelCase, PascalCase, or acronym-based string into kebab-case.
@@ -148,13 +148,6 @@ export declare const getElevationClass: (elevation?: ElementElevation) => string
  * @returns CSS class for density variant.
  */
 export declare const getDensityClass: (density?: ElementDensity) => string;
-/**
- * Returns the CSS class for the given typography token.
- *
- * @param font Typography token.
- * @returns CSS class in the form uui-font-<token>.
- */
-export declare const getFontClass: (font: ElementFont) => string;
 /**
  * Merges multiple React refs into a single ref callback.
  *
@@ -174,21 +167,6 @@ export declare const getFontClass: (font: ElementFont) => string;
  * @category Utils
  */
 export declare function mergeRefs<T>(...refs: React.Ref<T>[]): React.RefCallback<T>;
-/**
- * Creates a material-style ripple effect inside the given element.
- *
- * @param el - Target element that receives the ripple.
- * @param event - Mouse event used to determine the ripple origin.
- *
- * @remarks
- * - Automatically clears previous ripples.
- * - Injects a `.ripple-container` and `.ripple` element.
- * - Uses the element's client size and border radius.
- * - Safe for buttons, icon buttons, list items, etc.
- *
- * @category Utils
- */
-export declare const createRipple: (el: HTMLElement, event: React.MouseEvent<HTMLElement>, host?: HTMLElement) => void;
 /**
  * Joins class names into a single string.
  *