@ufoui/core 0.0.1

package/utils/utils.d.ts

@@ -0,0 +1,202 @@
+import { default as React, ReactNode } 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';
+/**
+ * Border width levels used across UUI components (0–4).
+ *
+ * @remarks
+ * Numeric scale mapped to design-token border thickness:
+ * - **0** – no border
+ * - **1** – thin (default)
+ * - **2–3** – medium / strong emphasis
+ * - **4** – maximum emphasis
+ *
+ * Used by inputs, buttons, menus, cards and other surface components.
+ *
+ * @category Utils
+ */
+export type ElementBorder = 0 | 1 | 2 | 3 | 4;
+export type ElementOutline = 0 | 1 | 2 | 3 | 4;
+/**
+ * Elevation (shadow depth) levels used across UUI surfaces.
+ *
+ * @remarks
+ * Maps numeric values **0–5** to predefined shadow tokens (`--uui-elevation-*`):
+ * - **0** — no shadow
+ * - **1–2** — low elevation (small ambient + subtle directional shadow)
+ * - **3–4** — medium elevation (stronger spread, more depth)
+ * - **5** — highest elevation (max separation from background)
+ *
+ * Each level resolves to a CSS `box-shadow` defined in theme tokens.
+ * Supports hover/pressed elevation transitions via utility classes:
+ * - `.uui-hover-elevate`
+ * - `.uui-pressed-elevate`
+ *
+ * Used by menus, cards, buttons, popovers and all floating surfaces.
+ *
+ * @category Utils
+ */
+export type ElementElevation = 0 | 1 | 2 | 3 | 4 | 5;
+/**
+ * Alignment positions for floating and anchored UI components.
+ *
+ * @remarks
+ * Defines all relative placements between a reference element and its
+ * floating content (menus, tooltips, dropdowns, submenus).
+ *
+ * Standard positions:
+ * - **topLeft**, **topCenter**, **topRight**
+ * - **centerLeft**, **center**, **centerRight**
+ * - **bottomLeft**, **bottomCenter**, **bottomRight**
+ *
+ * Extended positions (used mainly for submenus):
+ * - **topRightOut** – flush to the right, outside the reference element.
+ * - **topLeftOut** – flush to the left, outside the reference element.
+ *
+ * Special:
+ * - **auto** – automatically selects the best fitting placement.
+ *
+ * @category Utils
+ */
+export type ElementAlign = 'topLeft' | 'topCenter' | 'topRight' | 'centerLeft' | 'center' | 'centerRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight' | 'topRightOut' | 'topLeftOut' | 'auto';
+export type ElementDensity = 'comfortable' | 'compact' | 'dense';
+export type ElementFocusEffect = 'ring' | 'overlay';
+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';
+export declare const getAlignClass: (position: ElementAlign) => string;
+export declare const getShapeClass: (shape: ElementShape) => "uui-square" | "uui-smooth" | "uui-rounded" | "uui-round" | "";
+export declare const getBodySizeClass: (size: ElementSize) => "uui-font-body-large" | "uui-font-body-medium" | "uui-font-body-small";
+export declare const getSizeClass: (size: ElementSize) => "uui-extra-small" | "uui-small" | "uui-medium" | "uui-large" | "uui-extra-large";
+/**
+ * Returns the appropriate CSS class for the given border size.
+ *
+ * @param border - Border size (0 to 4)
+ * @returns A class name like 'uui-border-2'
+ */
+export declare const getBorderClass: (border?: ElementBorder) => string;
+/**
+ * Returns the appropriate CSS class for the given outline size.
+ *
+ * @param size - Outline size (0 to 4)
+ * @returns A class name like 'uui-outline-2'
+ */
+export declare const getOutlineClass: (size: ElementBorder) => string;
+export declare const getElevationClass: (elevation?: ElementElevation) => "" | "uui-elevation-0" | "uui-elevation-1" | "uui-elevation-2" | "uui-elevation-3" | "uui-elevation-4" | "uui-elevation-5";
+export declare const getDensityClass: (density?: ElementDensity) => "" | "uui-compact" | "uui-dense";
+export declare const getFontClass: (font: ElementFont) => string;
+/**
+ * Merges multiple React refs into a single ref callback.
+ *
+ * @param refs - List of refs (callback refs or `MutableRefObject`s) to update.
+ * @returns A ref callback that assigns the same value to all provided refs.
+ *
+ * @remarks
+ * - Supports both function refs and object refs.
+ * - Commonly used when forwarding a ref while also keeping a local one.
+ *
+ * @example
+ * const innerRef = useRef<HTMLDivElement>(null);
+ * const merged = mergeRefs(ref, innerRef);
+ *
+ * <div ref={merged} />
+ *
+ * @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;
+/**
+ * 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;
+/**
+ * Converts a camelCase, PascalCase, or acronym-based string into kebab-case.
+ *
+ * @param str - Input string to convert.
+ * @returns The kebab-case version of the string.
+ *
+ * @example
+ * toKebabCase("myVariableName"); // "my-variable-name"
+ * toKebabCase("URLParser"); // "url-parser"
+ *
+ * @category Utils
+ */
+export declare function toKebabCase(str: string): string;
+/**
+ * Returns the `displayName` of a React element if available.
+ *
+ * @param el - A React node to inspect.
+ * @returns The component's display name, or `undefined` if not found.
+ *
+ * @remarks
+ * - Works with function components, `memo()`, and `forwardRef()`.
+ * - Safe for any `ReactNode` (`string`, `null`, DOM elements, fragments, etc.).
+ *
+ * @category Utils
+ */
+export declare function getElementDisplayName(el: ReactNode): string | undefined;
+/**
+ * Forces focus to behave like :focus-visible on all browsers,
+ * including Safari which loses :focus-visible heuristics when
+ * focus is set programmatically (e.g., in menus or lists).
+ *
+ * Adds `.uui-focus-visible` to the element on focus, and
+ * removes it automatically on blur.
+ *
+ * Chrome/Firefox:
+ *   - still rely on native :focus-visible
+ *   - fallback class is ignored (lower specificity)
+ *
+ * Safari:
+ *   - native :focus-visible is unreliable
+ *   - fallback `.uui-focus-visible` replaces it
+ *
+ * @param el - HTMLElement to focus with visible highlighting.
+ *
+ * @category Utils
+ */
+export declare function setFocusVisible(el: HTMLElement | null): void;
+/**
+ * Clamps a numeric value to an integer range with a fallback.
+ *
+ * Converts the input to a number, rounds it to an integer,
+ * then clamps it between `min` and `max`.
+ * If the value is not a finite number, returns `fallback`.
+ *
+ * @param min - Minimum allowed value.
+ * @param max - Maximum allowed value.
+ * @param value - Input value to clamp. Can be any type.
+ * @param fallback - Value returned when input is invalid.
+ * @returns A clamped integer within the given range.
+ *
+ * @category Utils
+ */
+export declare function clampInt(min: number, max: number, value: unknown, fallback?: number): number | undefined;