@cleen/ui-core 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,40 @@
+# @cleen/ui-core
+
+Shared foundation for the Cleen UI library — Tailwind CSS configuration, custom hooks, utilities, and theming primitives used by `@cleen/ui` and `@cleen/ui-pro`.
+
+## Installation
+
+```bash
+npm install @cleen/ui-core
+```
+
+## Tailwind Setup
+
+Extend your Tailwind config with the Cleen preset and import the CSS:
+
+```js
+// tailwind.config.js
+import cleenPreset from '@cleen/ui-core/tailwind-preset';
+
+export default {
+  presets: [cleenPreset],
+};
+```
+
+```css
+/* your entry CSS */
+@import '@cleen/ui-core/tailwind-entry.css';
+```
+
+Or import the pre-built stylesheet directly:
+
+```js
+import '@cleen/ui-core/styles.css';
+```
+
+> **Note:** All Tailwind classes use the `cleen-` prefix. Components must be wrapped in a `.cleen` element for styles to apply.
+
+## Peer Dependencies
+
+- `react` ^18.3.1
+- `react-dom` ^18.3.1

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+import * as react from 'react';
+import { RefObject, CSSProperties } from 'react';
+import * as zustand_middleware from 'zustand/middleware';
+import * as zustand from 'zustand';
+import { ClassValue } from 'clsx';
+
+interface UseAnimateNumberProps {
+    targetNumber: number;
+    defaultNumber?: number;
+    duration?: number;
+    disabled?: boolean;
+    easeOut?: boolean;
+}
+declare const useAnimateNumber: ({ targetNumber, defaultNumber, duration, disabled, easeOut, }: UseAnimateNumberProps) => number;
+
+interface UseControlledProps<T> {
+    value?: T;
+    defaultValue?: T;
+    onChange?: (value: T) => void;
+}
+declare const useControlled: <T>({ value, defaultValue, onChange, }: UseControlledProps<T>) => {
+    value: T | undefined;
+    isControlled: boolean;
+    handleChange: (newValue: T) => void;
+};
+
+declare const useDebounce: <T>(value: T, delay: number) => T;
+
+interface UseDisclosureProps {
+    value?: boolean;
+    setValue?: (value: boolean) => void;
+}
+declare const useDisclosure: (props?: UseDisclosureProps) => {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+};
+
+interface UseFormProps<T> {
+    defaultValue: T | null;
+    resetOnDefaultValueChange?: boolean;
+}
+declare const useForm: <T extends Record<string, unknown>>({ defaultValue, resetOnDefaultValueChange, }: UseFormProps<T>) => {
+    form: T | null;
+    isDirty: boolean;
+    setForm: react.Dispatch<react.SetStateAction<T | null>>;
+    setField: (field: keyof T, value: T[keyof T]) => void;
+    reset: () => void;
+};
+
+interface UseOutsideClickProps {
+    refs: RefObject<HTMLElement | null>[];
+    handler: (event: MouseEvent | TouchEvent) => void;
+    enabled?: boolean;
+}
+declare function useOutsideClick({ refs, handler, enabled, }: UseOutsideClickProps): void;
+
+interface PaginationOptions {
+    initialPage?: number;
+    initialPageSize?: number;
+}
+interface PaginationState {
+    page: number;
+    setPage: (page: number) => void;
+    pageSize: number;
+    setPageSize: (size: number) => void;
+    handleNextPage: (page: number) => void;
+    handlePreviousPage: (page: number) => void;
+    handlePageChange: (page: number) => void;
+}
+declare function usePaginationState(options?: PaginationOptions): PaginationState;
+
+type Position = 'bottom-left' | 'bottom-right' | 'bottom' | 'top-left' | 'top-right' | 'top' | 'left' | 'right';
+
+interface UsePositionCloseProps {
+    triggerRef: RefObject<HTMLElement | null>;
+    targetRef: RefObject<HTMLElement | null>;
+    position?: Position;
+    offset?: number;
+    isOpen: boolean;
+}
+/**
+ * Hook to calculate fixed positioning for overlays relative to trigger elements.
+ * Handles viewport-aware position optimization and click-outside detection.
+ */
+declare const usePositionClose: ({ triggerRef, targetRef, position, offset, isOpen, }: UsePositionCloseProps) => {
+    positionStyles: {
+        top: number;
+        left: number;
+    } | {
+        top: number;
+        left: number;
+    };
+    optimalPosition: Position | undefined;
+    isMounted: boolean;
+};
+
+declare const useValidation: <T>(defaultValue: Partial<T>) => {
+    errors: Partial<T>;
+    setError: (field: keyof T, value: Partial<T>[keyof T]) => void;
+    setErrors: react.Dispatch<react.SetStateAction<Partial<T>>>;
+    clearError: (field: keyof T) => void;
+    clearErrors: () => void;
+};
+
+interface UseWidthDynamicResizeParams<T> {
+    ref: RefObject<T>;
+    skip?: boolean;
+}
+declare const useWidthDynamicResize: <T extends HTMLElement | null>({ ref, skip }: UseWidthDynamicResizeParams<T>, deps: unknown[]) => void;
+
+declare const colorVars: readonly ["white", "black", "gray", "pink", "purple", "indigo", "blue", "primary", "success", "warning", "error", "brand", "sidebar", "background"];
+type ColorVar = (typeof colorVars)[number];
+interface UseCleenColorsStore {
+    colors: Partial<Record<ColorVar, string>>;
+    getColors: () => Partial<Record<ColorVar, string>>;
+    getColor: (color: ColorVar) => string;
+    setColor: (colorVar: ColorVar, value: string) => void;
+    setColors: (colors: Partial<Record<ColorVar, string>>) => void;
+    resetColors: () => void;
+    resetColor: (color: ColorVar) => void;
+}
+declare const useCleenColors: zustand.UseBoundStore<Omit<zustand.StoreApi<UseCleenColorsStore>, "setState" | "persist"> & {
+    setState(partial: UseCleenColorsStore | Partial<UseCleenColorsStore> | ((state: UseCleenColorsStore) => UseCleenColorsStore | Partial<UseCleenColorsStore>), replace?: false | undefined): unknown;
+    setState(state: UseCleenColorsStore | ((state: UseCleenColorsStore) => UseCleenColorsStore), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<zustand_middleware.PersistOptions<UseCleenColorsStore, UseCleenColorsStore, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: UseCleenColorsStore) => void) => () => void;
+        onFinishHydration: (fn: (state: UseCleenColorsStore) => void) => () => void;
+        getOptions: () => Partial<zustand_middleware.PersistOptions<UseCleenColorsStore, UseCleenColorsStore, unknown>>;
+    };
+}>;
+
+interface UseCleenOverlays {
+    overlays: string[];
+    addOverlay: (id: string) => void;
+    removeOverlay: (id: string) => void;
+    clearOverlays: () => void;
+}
+declare const useCleenOverlays: zustand.UseBoundStore<Omit<zustand.StoreApi<UseCleenOverlays>, "setState" | "persist"> & {
+    setState(partial: UseCleenOverlays | Partial<UseCleenOverlays> | ((state: UseCleenOverlays) => UseCleenOverlays | Partial<UseCleenOverlays>), replace?: false | undefined): unknown;
+    setState(state: UseCleenOverlays | ((state: UseCleenOverlays) => UseCleenOverlays), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<zustand_middleware.PersistOptions<UseCleenOverlays, UseCleenOverlays, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: UseCleenOverlays) => void) => () => void;
+        onFinishHydration: (fn: (state: UseCleenOverlays) => void) => () => void;
+        getOptions: () => Partial<zustand_middleware.PersistOptions<UseCleenOverlays, UseCleenOverlays, unknown>>;
+    };
+}>;
+
+interface ComponentClassnames<T extends {
+    classNames?: {
+        [key: string]: string | object;
+    };
+}> {
+    className?: string;
+    classNames?: T['classNames'];
+}
+interface ComponentStyles<T extends {
+    styles?: {
+        [key: string]: CSSProperties | object;
+    };
+}> {
+    style?: CSSProperties;
+    styles?: T['styles'];
+}
+
+type HintedString<KnownValues extends string> = (string & {}) | KnownValues;
+type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
+
+/** Minimal synchronous PCM WAV encoder – no extra deps needed =w= */
+declare const encodeWav: (buffer: AudioBuffer) => Blob;
+declare const trimBlob: (blob: Blob, startSec: number, endSec: number) => Promise<Blob>;
+
+declare const cn: (...inputs: ClassValue[]) => string;
+
+type RGBA = [number, number, number, number];
+declare class ColorHelpers {
+    /**
+     * Calculates the Delta E (CIE94) between two RGB colors.
+     *
+     * Delta E is a metric for color difference. Based on the value, we can describe how different the colors are:
+     *
+     * Perception Levels:
+     * - Delta E <= 1.0: Not perceptible by human eyes.
+     * - Delta E between 1-2: Perceptible through close observation.
+     * - Delta E between 2-10: Perceptible at a glance.
+     * - Delta E between 11-49: Colors are more similar than opposite.
+     * - Delta E = 100: Colors are exact opposites.
+     *
+     * @param {Array<number>} rgb1 - The first RGB color as an array [R, G, B].
+     * @param {Array<number>} rgb2 - The second RGB color as an array [R, G, B].
+     * @returns {number} The Delta E value representing the difference between the two colors.
+     *
+     * @example
+     * deltaE([128, 0, 255], [128, 0, 255]); // 0
+     * deltaE([128, 0, 255], [128, 0, 230]); // 3.175
+     * deltaE([128, 0, 255], [255, 0, 0]);   // 61.24
+     */
+    static deltaE(rgbA: RGBA, rgbB: RGBA): number;
+    static rgb2lab(rgb: RGBA): number[];
+    static isSimilar(color1: string, color2: string, defaultDeltaE?: number): boolean;
+    static adjustColorForContrast(hexColor: string, amount?: number): string;
+    static getComputedColor(color?: string): string | undefined;
+    static getComputedRgb(color?: string): string | undefined;
+    static trasparentize(color?: string, value?: number): string;
+}
+
+interface PicsumOptions {
+    width: number;
+    height?: number;
+    grayscale?: boolean;
+    blur?: number;
+    seed?: string;
+}
+declare const getRandomImageUrl: (options: PicsumOptions) => string;
+
+/**
+ * Deep partial type — makes all properties optional recursively.
+ */
+type PartialDeep<T> = T extends (...args: unknown[]) => unknown ? T : T extends Array<infer U> ? Array<PartialDeep<U>> : T extends object ? {
+    [K in keyof T]?: PartialDeep<T[K]>;
+} : T | undefined;
+/**
+ * Recursively apply values on top of default values.
+ *
+ * Rules / assumptions:
+ * - Plain objects are merged recursively.
+ * - Arrays are replaced entirely by provided values (not concatenated).
+ * - If a provided value is `undefined`, the default is kept.
+ * - If a provided value is `null`, it overrides the default.
+ * - Non-plain objects (Date, RegExp, Map, Set, class instances) are replaced by the provided value when present.
+ *
+ * Example:
+ *   const defaults = { a: 1, b: { c: 2, d: [1] } };
+ *   const vals = { b: { c: 3 } };
+ *   applyDefaults(defaults, vals) // => { a: 1, b: { c: 3, d: [1] } }
+ */
+declare function applyDefaults<T>(defaults: T, values?: PartialDeep<T>): T;
+
+declare const calculateOptimalPosition: (overlayRect: DOMRect, triggerRect: DOMRect, preferredPosition: Position) => Position;
+declare const calculatePositionValues: (overlayRect: DOMRect, triggerRect: DOMRect, position: Position, offset?: number) => {
+    top: number;
+    left: number;
+};
+
+declare const formatFileSize: (bytes?: number) => string;
+declare const formatAudioTime: (seconds: number) => string;
+declare const getCreatedDate: (date: string) => string;
+
+export { type ArrayElement, ColorHelpers, type ColorVar, type ComponentClassnames, type ComponentStyles, type HintedString, type PartialDeep, type Position, applyDefaults, calculateOptimalPosition, calculatePositionValues, cn, encodeWav, formatAudioTime, formatFileSize, getCreatedDate, getRandomImageUrl, trimBlob, useAnimateNumber, useCleenColors, useCleenOverlays, useControlled, useDebounce, useDisclosure, useForm, useOutsideClick, usePaginationState, usePositionClose, useValidation, useWidthDynamicResize };