@cleen/ui-core 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cleen/ui-core",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./tailwind-preset": "./tailwind.preset.js",
+    "./tailwind-entry.css": "./tailwind-entry.css",
+    "./styles.css": "./dist/styles.css"
+  },
+  "scripts": {
+    "dev": "concurrently \"tsup --watch --onSuccess 'tsc'\" \"tailwindcss -w -c ./tailwind.config.js -i ./tailwind-entry.css -o ./dist/styles.css\"",
+    "build": "tsup && tailwindcss -m -c ./tailwind.config.js -i ./tailwind-entry.css -o ./dist/styles.css",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "color2k": "^2.0.3",
+    "tailwind-merge": "^2.6.0",
+    "zustand": "^5.0.8"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.10",
+    "concurrently": "^9.2.1",
+    "tailwindcss": "^3.4.17",
+    "tsup": "^8.5.1",
+    "typescript": "~5.8.3"
+  }
+}

package/src/hooks/useAnimateNumber.ts

@@ -0,0 +1,56 @@
+import { useEffect, useState } from 'react';
+
+interface UseAnimateNumberProps {
+  targetNumber: number;
+  defaultNumber?: number;
+  duration?: number;
+  disabled?: boolean;
+  easeOut?: boolean;
+}
+
+// Easing function for smooth deceleration
+const easeOutQuad = (progress: number): number => {
+  return 1 - (1 - progress) * (1 - progress);
+};
+
+export const useAnimateNumber = ({
+  targetNumber,
+  defaultNumber = 0,
+  duration = 1000,
+  disabled = false,
+  easeOut = true,
+}: UseAnimateNumberProps): number => {
+  const [animatedNumber, setAnimatedNumber] = useState(defaultNumber);
+
+  useEffect(() => {
+    if (disabled) {
+      return;
+    }
+
+    let start: number | null = null;
+
+    const animate = (timestamp: number) => {
+      if (!start) start = timestamp;
+      const progressTime = timestamp - start;
+      let progress = Math.min(progressTime / duration, 1);
+
+      if (easeOut) {
+        progress = easeOutQuad(progress);
+      }
+
+      const progressValue = progress * targetNumber;
+      setAnimatedNumber(progressValue);
+      if (progressValue < targetNumber) {
+        requestAnimationFrame(animate);
+      }
+    };
+
+    requestAnimationFrame(animate);
+  }, [targetNumber, duration, disabled, easeOut]);
+
+  if (disabled) {
+    return targetNumber;
+  }
+
+  return animatedNumber;
+};

package/src/hooks/useControlled.ts

@@ -0,0 +1,40 @@
+import { useEffect, useState } from 'react';
+
+interface UseControlledProps<T> {
+  value?: T;
+  defaultValue?: T;
+  onChange?: (value: T) => void;
+}
+
+export const useControlled = <T>({
+  value,
+  defaultValue,
+  onChange,
+}: UseControlledProps<T>) => {
+  const isControlled = value !== undefined;
+  const [internalValue, setInternalValue] = useState<T | undefined>(
+    defaultValue
+  );
+
+  const currentValue = isControlled ? value : internalValue;
+
+  const handleChange = (newValue: T) => {
+    if (!isControlled) {
+      setInternalValue(newValue);
+    }
+
+    onChange?.(newValue);
+  };
+
+  useEffect(() => {
+    if (!isControlled) {
+      setInternalValue(value ?? defaultValue ?? undefined);
+    }
+  }, [value, defaultValue, isControlled]);
+
+  return {
+    value: currentValue,
+    isControlled,
+    handleChange,
+  };
+};

package/src/hooks/useDebounce.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+
+export const useDebounce = <T>(value: T, delay: number): T => {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+};

package/src/hooks/useDisclosure.ts

@@ -0,0 +1,33 @@
+import { useState } from 'react';
+
+interface UseDisclosureProps {
+  value?: boolean;
+  setValue?: (value: boolean) => void;
+}
+
+export const useDisclosure = (props?: UseDisclosureProps) => {
+  const [isOpenInternal, setIsOpenInternal] = useState(false);
+  const isOpen = props?.value !== undefined ? props.value : isOpenInternal;
+
+  const open = () => {
+    setIsOpenInternal(true);
+    props?.setValue?.(true);
+  };
+
+  const close = () => {
+    setIsOpenInternal(false);
+    props?.setValue?.(false);
+  };
+
+  const toggle = () => {
+    setIsOpenInternal(prev => !prev);
+    props?.setValue?.(!isOpen);
+  };
+
+  return {
+    isOpen,
+    open,
+    close,
+    toggle,
+  };
+};

package/src/hooks/useForm.ts

@@ -0,0 +1,38 @@
+import { useEffect, useMemo, useState } from 'react';
+
+interface UseFormProps<T> {
+  defaultValue: T | null;
+  resetOnDefaultValueChange?: boolean;
+}
+
+export const useForm = <T extends Record<string, unknown>>({
+  defaultValue,
+  resetOnDefaultValueChange = true,
+}: UseFormProps<T>) => {
+  const [form, setForm] = useState<T | null>(defaultValue);
+
+  const reset = () => setForm(defaultValue);
+
+  const setField = (field: keyof T, value: T[keyof T]) => {
+    setForm(prev => ({ ...prev, [field]: value }) as T);
+  };
+
+  const isDirty = useMemo(
+    () => JSON.stringify(form) !== JSON.stringify(defaultValue),
+    [form, defaultValue]
+  );
+
+  useEffect(() => {
+    if (defaultValue && resetOnDefaultValueChange) {
+      setForm(defaultValue);
+    }
+  }, [defaultValue, resetOnDefaultValueChange]);
+
+  return {
+    form,
+    isDirty,
+    setForm,
+    setField,
+    reset,
+  };
+};

package/src/hooks/useOutsideClick.ts

@@ -0,0 +1,42 @@
+import { useEffect, type RefObject } from 'react';
+
+interface UseOutsideClickProps {
+  refs: RefObject<HTMLElement | null>[];
+  handler: (event: MouseEvent | TouchEvent) => void;
+  enabled?: boolean;
+}
+
+export function useOutsideClick({
+  refs,
+  handler,
+  enabled = true,
+}: UseOutsideClickProps) {
+  useEffect(() => {
+    if (!enabled) return;
+
+    const listener = (event: MouseEvent | TouchEvent) => {
+      // Check if click is inside any of the referenced elements
+      const clickedInside = refs.some(ref => {
+        const el = ref.current;
+        if (!el) return false;
+        return el.contains(event.target as Node);
+      });
+
+      // If click is inside at least one element — ignore
+      if (clickedInside) return;
+
+      // Defer handler to next tick to allow all listeners to evaluate
+      // before any DOM mutations occur (prevents conflicts when multiple
+      // components use this hook simultaneously)
+      setTimeout(() => handler(event), 0);
+    };
+
+    document.addEventListener('mousedown', listener);
+    document.addEventListener('touchstart', listener);
+
+    return () => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    };
+  }, [refs, handler, enabled]);
+}

package/src/hooks/usePaginationState.ts

@@ -0,0 +1,39 @@
+import { useState } from 'react';
+
+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;
+}
+
+export function usePaginationState(
+  options: PaginationOptions = {}
+): PaginationState {
+  const { initialPage = 1, initialPageSize = 10 } = options;
+
+  const [page, setPage] = useState<number>(initialPage);
+  const [pageSize, setPageSize] = useState<number>(initialPageSize);
+
+  const handleNextPage = (nextPage: number) => setPage(nextPage);
+  const handlePreviousPage = (prevPage: number) => setPage(prevPage);
+  const handlePageChange = (newPage: number) => setPage(newPage);
+
+  return {
+    page,
+    setPage,
+    pageSize,
+    setPageSize,
+    handleNextPage,
+    handlePreviousPage,
+    handlePageChange,
+  };
+}

package/src/hooks/usePositionClose.ts

@@ -0,0 +1,69 @@
+import type { Position } from '@/types/position';
+import {
+  calculateOptimalPosition,
+  calculatePositionValues,
+} from '@/utils/position';
+import type { RefObject } from 'react';
+import { useEffect, useMemo, useState } from 'react';
+
+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.
+ */
+export const usePositionClose = ({
+  triggerRef,
+  targetRef,
+  position = 'bottom-left',
+  offset = 8,
+  isOpen,
+}: UsePositionCloseProps) => {
+  const [isMounted, setIsMounted] = useState(false);
+
+  // Calculate optimal position based on viewport constraints
+  const { positionStyles, optimalPosition } = useMemo(() => {
+    if (isMounted && targetRef.current && triggerRef.current) {
+      const overlayRect = targetRef.current.getBoundingClientRect();
+      const triggerRect = triggerRef.current.getBoundingClientRect();
+
+      // Find the best position to avoid viewport overflow
+      const optimalPosition = calculateOptimalPosition(
+        overlayRect,
+        triggerRect,
+        position
+      );
+
+      const coords = calculatePositionValues(
+        overlayRect,
+        triggerRect,
+        optimalPosition,
+        offset
+      );
+
+      return { positionStyles: coords, optimalPosition };
+    }
+    return { positionStyles: { top: 0, left: 0 }, optimal: position };
+  }, [triggerRef, targetRef, position, offset, isMounted]);
+
+  // Track mounting state for smooth positioning
+  useEffect(() => {
+    if (isOpen) {
+      setIsMounted(true);
+    } else {
+      setIsMounted(false);
+    }
+  }, [isOpen]);
+
+  return {
+    positionStyles,
+    optimalPosition,
+    isMounted,
+  };
+};

package/src/hooks/useValidation.ts

@@ -0,0 +1,33 @@
+import { useCallback, useState } from 'react';
+
+export const useValidation = <T>(defaultValue: Partial<T>) => {
+  const [errors, setErrors] = useState<Partial<T>>(defaultValue);
+
+  const setError = useCallback((field: keyof T, value: Partial<T>[keyof T]) => {
+    setErrors(prev => {
+      prev[field] = value;
+
+      return { ...prev };
+    });
+  }, []);
+
+  const clearErrors = useCallback(() => {
+    setErrors(defaultValue);
+  }, [defaultValue]);
+
+  const clearError = useCallback((field: keyof T) => {
+    setErrors(prev => {
+      delete prev[field];
+
+      return { ...prev };
+    });
+  }, []);
+
+  return {
+    errors,
+    setError,
+    setErrors,
+    clearError,
+    clearErrors,
+  };
+};

package/src/hooks/useWatchResize.ts

@@ -0,0 +1,52 @@
+import { useEffect, type RefObject } from 'react';
+
+interface UseWidthDynamicResizeParams<T> {
+  ref: RefObject<T>;
+  skip?: boolean;
+}
+
+export const useWidthDynamicResize = <T extends HTMLElement | null>(
+  { ref, skip }: UseWidthDynamicResizeParams<T>,
+  deps: unknown[]
+) => {
+  useEffect(() => {
+    const node = ref.current;
+
+    if (!node || skip) {
+      return;
+    }
+
+    // Capture current width before content changes
+    const currentWidth = node.offsetWidth;
+
+    // Set explicit width to enable smooth transitions
+    node.style.width = `${currentWidth}px`;
+
+    // Use requestAnimationFrame to allow DOM to update with new content
+    requestAnimationFrame(() => {
+      // Measure the natural width with new content
+      node.style.width = 'auto';
+      const newWidth = node.offsetWidth;
+
+      // Set back to old width momentarily
+      node.style.width = `${currentWidth}px`;
+
+      // Force reflow
+      void node.offsetHeight;
+
+      // Transition to new width
+      node.style.width = `${newWidth}px`;
+
+      // After transition, set to auto for flexibility
+      const handleTransitionEnd = () => {
+        if (node) {
+          node.style.width = 'auto';
+        }
+
+        node?.removeEventListener('transitionend', handleTransitionEnd);
+      };
+
+      node.addEventListener('transitionend', handleTransitionEnd);
+    });
+  }, deps);
+};

package/src/index.ts

@@ -0,0 +1,21 @@
+export * from './hooks/useAnimateNumber';
+export * from './hooks/useControlled';
+export * from './hooks/useDebounce';
+export * from './hooks/useDisclosure';
+export * from './hooks/useForm';
+export * from './hooks/useOutsideClick';
+export * from './hooks/usePaginationState';
+export * from './hooks/usePositionClose';
+export * from './hooks/useValidation';
+export * from './hooks/useWatchResize';
+export * from './store/colors';
+export * from './types/position';
+export * from './types/styles';
+export * from './types/utils';
+export * from './utils/audio';
+export * from './utils/cn';
+export * from './utils/colors';
+export * from './utils/images';
+export * from './utils/object';
+export * from './utils/position';
+export * from './utils/string';

package/src/store/colors.ts

@@ -0,0 +1,98 @@
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+const PREFIX = '--cleen-';
+
+const colorVars = [
+  'white',
+  'black',
+  'gray',
+  'pink',
+  'purple',
+  'indigo',
+  'blue',
+  'primary',
+  'success',
+  'warning',
+  'error',
+  'brand',
+  'sidebar',
+  'background',
+] as const;
+
+export 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;
+}
+
+export const useCleenColors = create<UseCleenColorsStore>()(
+  persist(
+    (set, get) => ({
+      colors: {},
+      getColors: () => {
+        const colors = get().colors;
+
+        return colorVars.reduce<Partial<Record<ColorVar, string>>>(
+          (prev, colorVar) => {
+            if (colors[colorVar]) {
+              prev[colorVar] = colors[colorVar];
+            } else {
+              prev[colorVar] = getComputedStyle(
+                document.documentElement
+              ).getPropertyValue(`${PREFIX}${colorVar}`);
+            }
+
+            return prev;
+          },
+          {}
+        );
+      },
+      getColor: (color: ColorVar) => {
+        const colors = get().colors;
+
+        if (colors[color]) {
+          return colors[color];
+        } else {
+          return getComputedStyle(document.documentElement).getPropertyValue(
+            `${PREFIX}${color}`
+          );
+        }
+      },
+      setColors: (colors: Partial<Record<ColorVar, string>>) =>
+        Object.entries(colors).map(([colorVar, value]) =>
+          set(state => ({
+            colors: {
+              ...state.colors,
+              [colorVar]: value,
+            },
+          }))
+        ),
+      setColor: (colorVar: ColorVar, value: string) => {
+        set(state => ({
+          colors: {
+            ...state.colors,
+            [colorVar]: value,
+          },
+        }));
+      },
+      resetColors: () => {
+        set({ colors: {} });
+      },
+      resetColor: (colorVar: ColorVar) => {
+        const colors = get().colors;
+        delete colors[colorVar];
+        set({ colors });
+      },
+    }),
+    {
+      name: 'cleen-colors',
+    }
+  )
+);

package/src/types/position.ts

@@ -0,0 +1,9 @@
+export type Position =
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'bottom'
+  | 'top-left'
+  | 'top-right'
+  | 'top'
+  | 'left'
+  | 'right';

package/src/types/styles.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties } from 'react';
+
+// Helper interfaces to extract types of the classNames or styles props and pass in additional reserved class/style for className/style prop
+export interface ComponentClassnames<
+  T extends {
+    classNames?: {
+      [key: string]: string | object;
+    };
+  },
+> {
+  className?: string;
+  classNames?: T['classNames'];
+}
+
+export interface ComponentStyles<
+  T extends {
+    styles?: {
+      [key: string]: CSSProperties | object;
+    };
+  },
+> {
+  style?: CSSProperties;
+  styles?: T['styles'];
+}

package/src/types/utils.ts

@@ -0,0 +1,6 @@
+export type HintedString<KnownValues extends string> =
+  | (string & {})
+  | KnownValues;
+
+export type ArrayElement<ArrayType extends readonly unknown[]> =
+  ArrayType extends readonly (infer ElementType)[] ? ElementType : never;