@ufoui/core 0.0.1

package/utils/color.d.ts

@@ -0,0 +1,415 @@
+import { default as React } from 'react';
+import { ThemeExtendedColorKeys, ThemeSchemeKeys, ThemeSemanticColorKeys, ThemeSurfaceColorKeys } from '../components/types';
+/**
+ * Represents a high-level semantic color token (e.g. `primary`, `error`, `success`).
+ * Derived from {@link ThemeSemanticColorKeys}.
+ * @category Color
+ */
+export type SemanticColor = (typeof ThemeSemanticColorKeys)[number];
+/**
+ * Represents tokens extending the {@link SemanticColor} set
+ * with additional container and fixed variants.
+ * Derived from {@link ThemeExtendedColorKeys}.
+ * @category Color
+ */
+export type ExtendedColor = (typeof ThemeExtendedColorKeys)[number];
+/**
+ * Represents surface-related color tokens extending {@link ExtendedColor},
+ * including background, outline, and container surface roles.
+ * Derived from {@link ThemeSurfaceColorKeys}.
+ * @category Color
+ */
+export type SurfaceColor = (typeof ThemeSurfaceColorKeys)[number];
+/**
+ * Represents any valid color token defined in the theme,
+ * including semantic, extended, and surface roles.
+ * Derived from {@link ThemeSchemeKeys}.
+ * @category Color
+ */
+export type ThemeColor = (typeof ThemeSchemeKeys)[number];
+/**
+ * Generates utility class names (`uui-*`) for a given **semantic color** and its variants.
+ *
+ * @remarks
+ * Produces `text`, `border`, and `background` class names for a semantic color and its
+ * derived tokens (`on`, `container`, `fixed`, `fixedDim`, etc.).
+ * If the provided key is invalid, `'primary'` is used as fallback.
+ *
+ * All class names follow the pattern `uui-{type}-{kebab-case-color}`.
+ *
+ * @param color - Semantic color name (e.g. `'primary'`, `'error'`, `'success'`).
+ * @returns Object with `uui-text-*`, `uui-border-*`, and `uui-bg-*` class names for all variants.
+ *
+ * @example
+ * ```ts
+ * getSemanticColorClasses('primary');
+ * // → { textColor: 'uui-text-primary', bgOnColor: 'uui-bg-on-primary', ... }
+ * ```
+ * @category Color
+ */
+export declare const getSemanticColorClasses: (color: SemanticColor) => {
+    textColor: string;
+    borderColor: string;
+    bgColor: string;
+    textOnColor: string;
+    borderOnColor: string;
+    bgOnColor: string;
+    textContainer: string;
+    borderContainer: string;
+    bgContainer: string;
+    textOnContainer: string;
+    borderOnContainer: string;
+    bgOnContainer: string;
+    textFixed: string;
+    borderFixed: string;
+    bgFixed: string;
+    textOnFixed: string;
+    borderOnFixed: string;
+    bgOnFixed: string;
+    textFixedDim: string;
+    borderFixedDim: string;
+    bgFixedDim: string;
+    textOnFixedVariant: string;
+    borderOnFixedVariant: string;
+    bgOnFixedVariant: string;
+};
+/**
+ * Bidirectional mapping between theme colors and their “on” counterparts.
+ *
+ * @remarks
+ * Provides both directions — e.g. `'surface' → 'onSurface'` and `'onSurface' → 'surface'` —
+ * for all semantic, extended, and surface tokens defined in {@link ThemeColor}.
+ * Enables consistent inverse lookups for text/background pairings.
+ *
+ * Commonly used by {@link getSurfaceColorClasses}.
+ *
+ * @category Color
+ */
+export declare const inverseColorMap: {
+    readonly surface: "onSurface";
+    readonly surfaceVariant: "onSurfaceVariant";
+    readonly surfaceContainerLowest: "onSurface";
+    readonly surfaceContainerLow: "onSurface";
+    readonly surfaceContainer: "onSurface";
+    readonly surfaceContainerHigh: "onSurface";
+    readonly surfaceContainerHighest: "onSurface";
+    readonly surfaceDim: "onSurface";
+    readonly surfaceBright: "onSurface";
+    readonly background: "onBackground";
+    readonly inverseSurface: "inverseOnSurface";
+    readonly primary: "onPrimary";
+    readonly secondary: "onSecondary";
+    readonly tertiary: "onTertiary";
+    readonly warning: "onWarning";
+    readonly info: "onInfo";
+    readonly success: "onSuccess";
+    readonly error: "onError";
+    readonly primaryContainer: "onPrimaryContainer";
+    readonly primaryFixed: "onPrimaryFixed";
+    readonly primaryFixedDim: "onPrimaryFixedVariant";
+    readonly secondaryContainer: "onSecondaryContainer";
+    readonly secondaryFixed: "onSecondaryFixed";
+    readonly secondaryFixedDim: "onSecondaryFixedVariant";
+    readonly tertiaryContainer: "onTertiaryContainer";
+    readonly tertiaryFixed: "onTertiaryFixed";
+    readonly tertiaryFixedDim: "onTertiaryFixedVariant";
+    readonly warningContainer: "onWarningContainer";
+    readonly warningFixed: "onWarningFixed";
+    readonly warningFixedDim: "onWarningFixedVariant";
+    readonly infoContainer: "onInfoContainer";
+    readonly infoFixed: "onInfoFixed";
+    readonly infoFixedDim: "onInfoFixedVariant";
+    readonly successContainer: "onSuccessContainer";
+    readonly successFixed: "onSuccessFixed";
+    readonly successFixedDim: "onSuccessFixedVariant";
+    readonly errorContainer: "onErrorContainer";
+    readonly errorFixed: "onErrorFixed";
+    readonly errorFixedDim: "onErrorFixedVariant";
+    readonly outline: "surface";
+    readonly outlineVariant: "inverseSurface";
+    readonly inversePrimary: "onPrimaryContainer";
+    readonly black: "white";
+    readonly white: "black";
+    readonly onSurface: "surface";
+    readonly onSurfaceVariant: "surfaceVariant";
+    readonly onBackground: "background";
+    readonly inverseOnSurface: "inverseSurface";
+    readonly onPrimary: "primary";
+    readonly onSecondary: "secondary";
+    readonly onTertiary: "tertiary";
+    readonly onWarning: "warning";
+    readonly onInfo: "info";
+    readonly onSuccess: "success";
+    readonly onError: "error";
+    readonly onPrimaryContainer: "primaryContainer";
+    readonly onSecondaryContainer: "secondaryContainer";
+    readonly onTertiaryContainer: "tertiaryContainer";
+    readonly onWarningContainer: "warningContainer";
+    readonly onInfoContainer: "infoContainer";
+    readonly onSuccessContainer: "successContainer";
+    readonly onErrorContainer: "errorContainer";
+};
+/**
+ * Returns utility class names (`uui-*`) for a given surface color and its mapped “on” color.
+ *
+ * @remarks
+ * Uses the {@link inverseColorMap} to find the related “on” color
+ * (e.g. `'surfaceContainer'` → `'onSurface'`).
+ * Produces `text`, `border`, and `background` variants for both.
+ * All names are kebab-cased (e.g. `'surfaceContainerHigh'` → `'surface-container-high'`).
+ *
+ * @param color - Surface color key (e.g. `'surfaceContainerHigh'`).
+ * @returns Object with `uui-text-*`, `uui-border-*`, and `uui-bg-*` class names for base and on-color.
+ *
+ * @example
+ * ```ts
+ * getSurfaceColorClasses('surfaceContainer');
+ * // → { textColor: 'uui-text-surface-container', textOnColor: 'uui-text-on-surface', ... }
+ * ```
+ * @category Color
+ */
+export declare const getSurfaceColorClasses: (color: SurfaceColor) => {
+    readonly textColor: `uui-text-${string}`;
+    readonly textOnColor: `uui-text-${string}`;
+    readonly borderColor: `uui-border-${string}`;
+    readonly borderOnColor: `uui-border-${string}`;
+    readonly bgColor: `uui-bg-${string}`;
+    readonly bgOnColor: `uui-bg-${string}`;
+};
+/**
+ * Returns utility class names (`uui-*`) for any theme color token.
+ *
+ * @remarks
+ * Generates `text`, `border`, and `background` class names based on the provided
+ * {@link ThemeColor}. If the color key is invalid, `'primary'` is used as fallback.
+ *
+ * @param color - Theme color token (e.g. `'primary'`, `'surfaceContainerHigh'`, `'error'`).
+ * @returns An object with `uui-text-*`, `uui-border-*`, and `uui-bg-*` class names.
+ *
+ * @example
+ * ```ts
+ * getColorClasses('error');
+ * // → { textColor: 'uui-text-error', borderColor: 'uui-border-error', bgColor: 'uui-bg-error' }
+ * ```
+ * @category Color
+ */
+export declare const getColorClasses: (color: ThemeColor) => {
+    readonly textColor: `uui-text-${string}`;
+    readonly borderColor: `uui-border-${string}`;
+    readonly bgColor: `uui-bg-${string}`;
+};
+/**
+ * Represents the available border color options.
+ *
+ * @category Color
+ */
+export type BorderColor = SurfaceColor;
+/**
+ * Returns the appropriate border color class for a given configuration.
+ *
+ * @remarks
+ * Typical border colors are `'outline'` and `'outlineVariant'`, matching MD3 tokens.
+ * @param borderColor - Border color keyword or surface color token.
+ * @returns The resolved border color class (e.g. `'uui-border-surface-container-high'`).
+ *
+ * @example
+ * ```ts
+ * getBorderColorClass('surfaceContainer'); // → 'uui-border-surface-container'
+ * ```
+ * @category Color
+ */
+export declare function getBorderColorClass(borderColor: BorderColor): `uui-border-${string}`;
+/**
+ * Returns all CSS variable references for a **semantic color**.
+ *
+ * @remarks
+ * Generates `var(--uui-color-*)` tokens only for semantic colors
+ * defined in {@link SemanticColor} (e.g. `primary`, `error`, `success`).
+ * Useful for dynamic component theming and inline styles.
+ *
+ * @param color - Semantic color key (e.g. `'primary'`, `'error'`, `'info'`).
+ * @returns Object containing `var(--uui-color-...)` references for all variants.
+ *
+ * @example
+ * ```ts
+ * const vars = getSemanticColorVar('primary');
+ * // → "var(--uui-color-primary)", "var(--uui-color-on-primary)"
+ * ```
+ * @category Color
+ */
+export declare const getSemanticColorVar: (color: SemanticColor) => {
+    color: string;
+    onColor: string;
+    container: string;
+    onContainer: string;
+    fixed: string;
+    fixedDim: string;
+    onFixed: string;
+    onFixedVariant: string;
+};
+/**
+ * Returns basic CSS variable references for a **surface color**.
+ *
+ * @remarks
+ * Generates `var(--uui-color-*)` tokens for surface-related colors
+ * defined in {@link SurfaceColor} (e.g. `surface`, `surfaceContainer`, `background`).
+ * Intended for quick surface/background styling.
+ *
+ * @param color - Surface color key (e.g. `'surface'`, `'background'`, `'surfaceContainerHigh'`).
+ * @returns Object containing `{ color, onColor }` variable references.
+ *
+ * @example
+ * ```ts
+ * const vars = getSurfaceColorVar('surfaceContainer');
+ * // → { color: "var(--uui-color-surface-container)", onColor: "var(--uui-color-on-surface)" }
+ * ```
+ * @category Color
+ */
+export declare const getSurfaceColorVar: (color: SurfaceColor) => {
+    color: string;
+    onColor: string;
+};
+/**
+ * Converts a HEX color string into an RGB tuple.
+ *
+ * @param hex - HEX color string (e.g. `#ff8800`).
+ * @returns RGB tuple as `[r, g, b]` numeric values.
+ *
+ * @example
+ * ```ts
+ * hexToRgbValues('#ff8800');
+ * // → [255, 136, 0]
+ * ```
+ * @category Color
+ */
+export declare const hexToRgbValues: (hex: string) => [number, number, number];
+/**
+ * Converts a HEX color string to an RGB string format.
+ *
+ * @param colorValue - HEX color string (e.g. `#ff8800`).
+ * @returns Comma-separated RGB string (e.g. `"255,136,0"`).
+ *
+ * @example
+ * ```ts
+ * hexToRgb('#ff8800');
+ * // → "255,136,0"
+ * ```
+ * @category Color
+ */
+export declare const hexToRgb: (colorValue: string) => string;
+/**
+ * Calculates the Material Design 3 surface tint overlay color
+ * for a given elevation level and base tint color.
+ *
+ * @param elevation - Elevation level between 0–5.
+ * @param tintColor - Base tint color in HEX format (e.g. `#ffcc00`).
+ * @returns CSS color string in `rgba(r, g, b, a)` format with correct alpha applied.
+ *
+ * @example
+ * ```ts
+ * getTintOverlayColor(3, '#ffcc00');
+ * // → "rgba(255, 204, 0, 0.11)"
+ * ```
+ * @category Color
+ */
+export declare function getTintOverlayColor(elevation: number, tintColor: string): string;
+/**
+ * Returns a set of predefined utility class names for fixed theme colors.
+ *
+ * Each entry maps text, border, outline, and background variants like:
+ * `textSurface`, `bgOnSurface`, `borderOutlineVariant`, etc.
+ *
+ * @returns Object with fixed color class mappings.
+ */
+export declare const getFixedColorClasses: () => Record<string, string>;
+/**
+ * Returns a map of `uui-current-*` classes for the given element color.
+ *
+ * @param color - The base color name (e.g. 'primary', 'error', etc.)
+ * @returns An object with `uui-current-*` class names for various variants.
+ */
+export declare const getCurrentColorClasses: (color: SemanticColor) => {
+    [k: string]: `uui-current-${string}` | `uui-current-on-${string}` | `uui-current-${string}-container` | `uui-current-on-${string}-container` | `uui-current-${string}-fixed` | `uui-current-on-${string}-fixed` | `uui-current-${string}-fixed-dim` | `uui-current-on-${string}-fixed-variant`;
+};
+/**
+ * Creates a style builder for MD3 color tokens.
+ *
+ * @remarks
+ * The builder provides typed functions for applying theme color tokens
+ * to background, text, border, and outline properties using CSS variables.
+ *
+ * - `bg(color)` — sets background from any ThemeColor
+ * - `bg.on(surfaceColor)` — sets background from corresponding `on-*` surface color
+ * - `bg.container(semanticColor)` — sets semantic `*-container` background
+ * - `bg.onContainer(semanticColor)` — sets semantic `on-*-container` background
+ * - `bg.fixed(semanticColor)` — semantic `*-fixed` background
+ * - `bg.fixedDim(semanticColor)` — semantic `*-fixed-dim` background
+ *
+ * - `text(color)` — sets text color from any ThemeColor
+ * - `text.on(surfaceColor)` — sets text from `on-*` surface colors
+ * - `text.onContainer(semanticColor)` — sets text from semantic `on-*-container`
+ *
+ * - `border(color)` — sets border-color from any ThemeColor
+ * - `outline(color)` — sets outline-color from any ThemeColor
+ *
+ * The builder accumulates all style operations internally
+ * and exposes them via `.get()` as a final React.CSSProperties object.
+ *
+ * @example
+ * const style = ColorStyle();
+ * style.bg('surfaceContainerLow');
+ * style.text.on('surface');
+ * return <button style={style.get()}>Press</button>;
+ */
+/**
+ * Creates a strictly typed style builder for MD3 color tokens.
+ *
+ * @category Color
+ */
+type CSSPropertyKey = Extract<keyof React.CSSProperties, string>;
+type CSSVar = `--${string}`;
+export declare function ControlStyle(initial?: React.CSSProperties): {
+    bg: ((color?: ThemeColor) => void) & {
+        on(color?: SurfaceColor): void;
+        container(color?: SemanticColor): void;
+        onContainer(color?: SemanticColor): void;
+        fixed(color?: SemanticColor): void;
+        fixedDim(color?: SemanticColor): void;
+    };
+    text: ((color?: ThemeColor) => void) & {
+        on(color?: SurfaceColor): void;
+        container(color?: SemanticColor): void;
+        onContainer(color?: SemanticColor): void;
+        fixed(color?: SemanticColor): void;
+        fixedDim(color?: SemanticColor): void;
+    };
+    border: ((color?: ThemeColor) => void) & {
+        on(color?: SurfaceColor): void;
+        container(color?: SemanticColor): void;
+        onContainer(color?: SemanticColor): void;
+        fixed(color?: SemanticColor): void;
+        fixedDim(color?: SemanticColor): void;
+    };
+    outline: ((color?: ThemeColor) => void) & {
+        on(color?: SurfaceColor): void;
+        container(color?: SemanticColor): void;
+        onContainer(color?: SemanticColor): void;
+        fixed(color?: SemanticColor): void;
+        fixedDim(color?: SemanticColor): void;
+    };
+    current: ((color?: ThemeColor) => void) & {
+        on(color?: SurfaceColor): void;
+        container(color?: SemanticColor): void;
+        onContainer(color?: SemanticColor): void;
+        fixed(color?: SemanticColor): void;
+        fixedDim(color?: SemanticColor): void;
+    };
+    set: {
+        <K extends CSSPropertyKey>(key: K, value: React.CSSProperties[K]): void;
+        (key: CSSVar, value: string): void;
+    };
+    get(): React.CSSProperties;
+    merge(styles?: React.CSSProperties): void;
+};
+export declare function getBorderColor(borderColor?: BorderColor): BorderColor;
+export {};

package/utils/generateMaterialColors.d.ts

@@ -0,0 +1,31 @@
+import { PartialThemeSchemes, ThemeSchemes } from '../components/types';
+export type ExtraColorOverrides = Partial<Record<'info' | 'warning' | 'success', string>>;
+/**
+ * Generates a full ThemeSchemes object (light and dark modes) based on a seed color,
+ * optional token overrides, and custom semantic colors (info, warning, success).
+ *
+ * Internally uses the Material Design 3 `themeFromSourceColor()` generator and applies
+ * full resolution of all MD3 roles as defined in ThemeSchemeKeys.
+ *
+ * Custom semantic colors (e.g. `info`, `warning`, `success`) are blended into the palette
+ * and expanded to support `Container`, `Fixed`, `Dim`, and `on*` roles.
+ *
+ * @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 customSchemes - Optional overrides for light and dark color values.
+ *                        Partial values will be merged with generated ones.
+ * @param extraColors - Optional custom base colors for `info`, `warning`, and `success`.
+ *                      These will override the default values (`#03a9f4`, `#ffd600`, `#689f38`).
+ *
+ * @returns A fully resolved ThemeSchemes object with all required color roles populated for light and dark modes.
+ *
+ * @example
+ * ```ts
+ * const schemes = generateMaterialColors('#6200ee', { info: '#2196f3' }, {});
+ * const primary = schemes.light.primary;
+ * const infoContainer = schemes.dark.infoContainer;
+ * ```
+ *
+ * @category Theme
+ */
+export declare function generateMaterialColors(seedColor?: string, extraColors?: ExtraColorOverrides, customSchemes?: PartialThemeSchemes): ThemeSchemes;

package/utils/generateSchemes.d.ts

@@ -0,0 +1,32 @@
+import { PartialThemeSchemes, ThemeSchemes } from '../components/types';
+import { ExtraColorOverrides } from './generateMaterialColors';
+/**
+ * Generates and injects CSS custom properties for Material Design 3 theme colors.
+ *
+ * This function calls `generateMaterialColors()` to resolve a complete light/dark
+ * `ThemeSchemes` object based on a seed color, optional extra semantic colors
+ * (`info`, `warning`, `success`), and optional overrides for individual color tokens.
+ *
+ * All resolved tokens are converted to CSS variables using kebab-case, e.g.:
+ *   `--uui-color-primary`, `--uui-color-on-surface`, etc.
+ *
+ * Light mode tokens are injected into `:root`, dark mode tokens into `.dark`.
+ * Variables are injected once into a single `<style>` tag with ID `ufo-ui-theme`.
+ *
+ * @param seedColor - The base seed color used to generate MD3 tonal palettes.
+ *                    Defaults to `#6750A4` if not provided.
+ * @param extraColors - Optional map of base semantic colors for `info`, `warning`, and `success`.
+ *                      These override the default values.
+ * @param schemes - Optional overrides for light and dark color tokens.
+ *                  Partial values will be merged with the generated ones.
+ *
+ * @returns A fully resolved `ThemeSchemes` object containing all tokens for light and dark modes.
+ *
+ * @example
+ * ```ts
+ * const schemes = generateSchemes('#6200ee', { info: '#0288d1' }, { light: { primary: '#ff5722' } });
+ * ```
+ *
+ * @category Theme
+ */
+export declare function generateSchemes(seedColor?: string, extraColors?: ExtraColorOverrides, schemes?: PartialThemeSchemes): ThemeSchemes;

package/utils/inputhMethod.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Initializes global listeners that track the user's last interaction method.
+ *
+ * The setup runs once per runtime and updates the internal interaction
+ * modality based on keyboard or pointer input.
+ *
+ * @internal
+ */
+export declare function ensureInputMethod(): void;
+/**
+ * Returns the last detected interaction method.
+ *
+ * Possible values are `'keyboard'` or `'pointer'`.
+ *
+ * @internal
+ */
+export declare function getInputMethod(): "pointer" | "keyboard";