@umituz/web-design-system 3.1.22 → 4.0.0

package/src/infrastructure/utils/calculation.utils.ts

@@ -0,0 +1,74 @@
+/**
+ * Calculation Utils
+ * @description Small numeric helpers used by presentation components
+ * (progress percentage, pagination bounds, trend formatting, clamping)
+ */
+
+// --- Clamping ---
+
+export const clampToRange = (value: number, min: number, max: number): number => {
+  if (Number.isNaN(value)) return min;
+  if (min > max) [min, max] = [max, min];
+  if (value < min) return min;
+  if (value > max) return max;
+  return value;
+};
+
+export const clampToNonNegative = (value: number): number =>
+  value < 0 || Number.isNaN(value) ? 0 : value;
+
+export const clampToPositive = (value: number, fallback: number = 1): number =>
+  value <= 0 || Number.isNaN(value) ? fallback : value;
+
+// --- Percentage ---
+
+const PERCENT_MIN = 0;
+const PERCENT_MAX = 100;
+
+export const percentOfMax = (value: number, max: number): number => {
+  if (max <= 0) return PERCENT_MIN;
+  return clampToRange((value / max) * PERCENT_MAX, PERCENT_MIN, PERCENT_MAX);
+};
+
+// --- Trend formatting ---
+
+const PERCENT_FRACTION_DIGITS = 1;
+const SIGN_THRESHOLD = 0;
+const POSITIVE_SIGN = '+';
+const NEGATIVE_SIGN = '-';
+
+export const formatTrendMagnitude = (value: number, fractionDigits: number = PERCENT_FRACTION_DIGITS): string => {
+  if (Number.isNaN(value)) return '0%';
+  const sign = value > SIGN_THRESHOLD ? POSITIVE_SIGN : value < SIGN_THRESHOLD ? NEGATIVE_SIGN : '';
+  return `${sign}${Math.abs(value).toFixed(fractionDigits)}%`;
+};
+
+// --- Pagination bounds ---
+
+export interface PageBounds {
+  totalPages: number;
+  startIndex: number;
+  endIndex: number;
+}
+
+export const computeTotalPages = (totalItems: number, pageSize: number): number => {
+  if (pageSize <= 0) return 0;
+  return Math.ceil(totalItems / pageSize);
+};
+
+export const clampPageNumber = (
+  page: number,
+  totalPages: number
+): number => clampToRange(page, 1, Math.max(totalPages, 1));
+
+export const computePageBounds = (
+  currentPage: number,
+  pageSize: number,
+  totalItems: number
+): PageBounds => {
+  const totalPages = computeTotalPages(totalItems, pageSize);
+  const safePage = clampPageNumber(currentPage, totalPages);
+  const startIndex = (safePage - 1) * pageSize + 1;
+  const endIndex = Math.min(safePage * pageSize, totalItems);
+  return { totalPages, startIndex, endIndex };
+};

package/src/infrastructure/utils/index.ts

@@ -18,3 +18,15 @@ export {
   getSpaceY,
   getResponsiveStyles,
 } from './responsive.utils';
+
+export {
+  clampToRange,
+  clampToNonNegative,
+  clampToPositive,
+  percentOfMax,
+  formatTrendMagnitude,
+  computeTotalPages,
+  clampPageNumber,
+  computePageBounds,
+} from './calculation.utils';
+export type { PageBounds } from './calculation.utils';

package/src/presentation/atoms/IconButton.tsx

@@ -0,0 +1,55 @@
+/**
+ * IconButton Component (Atom)
+ * @description Round button optimized for icon-only usage with consistent sizing
+ */
+
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
+import { cn } from '../../infrastructure/utils';
+import type { BaseProps } from '../../domain/types';
+import type { SmallSizes, MediumSizes } from '../../infrastructure/constants';
+
+export interface IconButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'>,
+    BaseProps {
+  icon: ReactNode;
+  label: string;
+  size?: SmallSizes | MediumSizes;
+  variant?: 'default' | 'ghost' | 'outline';
+}
+
+const sizeStyles: Record<SmallSizes | MediumSizes, string> = {
+  xs: 'h-7 w-7',
+  sm: 'h-8 w-8',
+  md: 'h-10 w-10',
+  lg: 'h-12 w-12',
+};
+
+const variantStyles: Record<'default' | 'ghost' | 'outline', string> = {
+  default: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+  ghost: 'text-muted-foreground hover:bg-muted hover:text-foreground',
+  outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+};
+
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
+  ({ className, icon, label, size = 'md', variant = 'ghost', type = 'button', ...props }, ref) => (
+    <button
+      ref={ref}
+      type={type}
+      aria-label={label}
+      title={label}
+      className={cn(
+        'inline-flex shrink-0 items-center justify-center rounded-md transition-colors',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+        'disabled:pointer-events-none disabled:opacity-50',
+        sizeStyles[size],
+        variantStyles[variant],
+        className
+      )}
+      {...props}
+    >
+      {icon}
+    </button>
+  )
+);
+
+IconButton.displayName = 'IconButton';

package/src/presentation/atoms/Progress.tsx

@@ -5,6 +5,7 @@
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';
+import { percentOfMax } from '../../infrastructure/utils/calculation.utils';
 import type { BaseProps } from '../../domain/types';
 
 export interface ProgressProps extends HTMLAttributes<HTMLDivElement>, BaseProps {
@@ -21,7 +22,7 @@ const sizeStyles: Record<'sm' | 'md' | 'lg', string> = {
 
 export const Progress = forwardRef<HTMLDivElement, ProgressProps>(
   ({ className, value = 0, max = 100, size = 'md', ...props }, ref) => {
-    const percentage = Math.min(Math.max((value / max) * 100, 0), 100);
+    const percentage = percentOfMax(value, max);
 
     return (
       <div

package/src/presentation/atoms/Spinner.tsx

@@ -15,7 +15,7 @@ export interface SpinnerProps extends HTMLAttributes<HTMLDivElement>, BaseProps
 const sizeStyles: Record<RegularSizes, string> = {
   sm: 'h-4 w-4 border-2',
   md: 'h-6 w-6 border-2',
-  lg: 'h-8 w-8 border-3',
+  lg: 'h-8 w-8 border-[3px]',
   xl: 'h-12 w-12 border-4',
 };
 

package/src/presentation/atoms/Switch.tsx

@@ -16,7 +16,7 @@ const switchVariants = cva(
       size: {
         default: 'h-6 w-11',
         sm: 'h-5 w-9',
-        lg: 'h-7 w-13',
+        lg: 'h-7 w-14',
       },
     },
     defaultVariants: {
@@ -32,7 +32,7 @@ const switchThumbVariants = cva(
       size: {
         default: 'h-5 w-5 data-[state=checked]:translate-x-5',
         sm: 'h-4 w-4 data-[state=checked]:translate-x-4',
-        lg: 'h-6 w-6 data-[state=checked]:translate-x-6',
+        lg: 'h-6 w-6 data-[state=checked]:translate-x-7',
       },
     },
     defaultVariants: {

package/src/presentation/atoms/Text.tsx

@@ -1,23 +1,27 @@
 /**
  * Text Component (Atom)
- * @description Styled text element
+ * @description Styled text element with polymorphic rendering
  */
 
-import { forwardRef, type HTMLAttributes } from 'react';
-import React from 'react';
+import { forwardRef, memo, type ElementType, type ComponentPropsWithoutRef } from 'react';
 import { cn } from '../../infrastructure/utils';
 import type { BaseProps } from '../../domain/types';
 
 export type TextElement = 'p' | 'span' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'label';
 export type TextVariant = 'body' | 'heading' | 'label' | 'caption';
 export type TextSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
+export type TextWeight = 'normal' | 'medium' | 'semibold' | 'bold';
 
-export interface TextProps extends HTMLAttributes<HTMLElement>, BaseProps {
+type TextComponentProps = {
   as?: TextElement;
   variant?: TextVariant;
   size?: TextSize;
-  weight?: 'normal' | 'medium' | 'semibold' | 'bold';
-}
+  weight?: TextWeight;
+};
+
+export type TextProps = TextComponentProps &
+  Omit<ComponentPropsWithoutRef<'p'>, keyof TextComponentProps> &
+  BaseProps;
 
 const variantStyles: Record<TextVariant, string> = {
   body: 'text-foreground',
@@ -37,20 +41,18 @@ const sizeStyles: Record<TextSize, string> = {
   '4xl': 'text-4xl',
 };
 
-const weightStyles: Record<'normal' | 'medium' | 'semibold' | 'bold', string> = {
+const weightStyles: Record<TextWeight, string> = {
   normal: 'font-normal',
   medium: 'font-medium',
   semibold: 'font-semibold',
   bold: 'font-bold',
 };
 
-// NOTE: "as any" is used here for the polymorphic ref, which is a necessary workaround
-// for TypeScript's limitations in typing polymorphic components properly.
-export const Text = React.memo(forwardRef<HTMLElement, TextProps>(
-  ({ className, as = 'p', variant = 'body', size = 'md', weight = 'normal', ...props }, ref) => {
-    const Tag = as as any;
+export const Text = memo(forwardRef<HTMLElement, TextProps>(
+  ({ className, as: Tag = 'p', variant = 'body', size = 'md', weight = 'normal', ...props }, ref) => {
+    const Element = Tag as ElementType;
     return (
-      <Tag
+      <Element
         ref={ref}
         className={cn(
           variantStyles[variant],

package/src/presentation/atoms/Tooltip.tsx

@@ -5,6 +5,7 @@
 
 import { forwardRef, type HTMLAttributes, type ReactNode, useState, useRef, useEffect } from 'react';
 import { cn } from '../../infrastructure/utils';
+import { TIMING } from '../../infrastructure/constants/timing.constants';
 import type { BaseProps } from '../../domain/types';
 
 export interface TooltipProps extends Omit<HTMLAttributes<HTMLDivElement>, 'content'>, BaseProps {
@@ -21,7 +22,7 @@ const placementStyles: Record<'top' | 'bottom' | 'left' | 'right', string> = {
 };
 
 export const Tooltip = forwardRef<HTMLDivElement, TooltipProps>(
-  ({ className, children, content, placement = 'top', delay = 200, ...props }, ref) => {
+  ({ className, children, content, placement = 'top', delay = TIMING.TOOLTIP_DEFAULT_DELAY_MS, ...props }, ref) => {
     const [isOpen, setIsOpen] = useState(false);
     const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
 

package/src/presentation/atoms/index.ts

@@ -63,3 +63,6 @@ export type { ShowComponentProps } from './Show';
 
 export { Hide } from './Hide';
 export type { HideComponentProps } from './Hide';
+
+export { IconButton } from './IconButton';
+export type { IconButtonProps } from './IconButton';

package/src/presentation/hooks/index.ts

@@ -25,6 +25,3 @@ export type { UseClipboardReturn } from './useClipboard';
 export { useToggle } from './useToggle';
 
 export { useScrollLock } from './useScrollLock';
-
-export { useLanguage } from './useLanguage';
-export type { Language, SupportedLanguage, UseLanguageReturn } from './useLanguage';

package/src/presentation/hooks/useClickOutside.ts

@@ -10,26 +10,30 @@ export function useClickOutside<T extends HTMLElement>(
   enabled: boolean = true
 ) {
   const ref = useRef<T>(null);
+  // Use a ref to keep the latest callback without retriggering the effect
+  // on every render — callers commonly pass inline functions.
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
 
   useEffect(() => {
     if (!enabled) return;
 
-    const handleClick = (event: Event) => {
-      // FIX: Safe null check and type guard
-      const target = event.target as Node;
-      if (ref.current && target && !ref.current.contains(target)) {
-        callback();
+    const handlePointerDown = (event: Event) => {
+      const target = event.target;
+      if (!(target instanceof Node)) return;
+      if (ref.current && !ref.current.contains(target)) {
+        callbackRef.current();
       }
     };
 
-    document.addEventListener('mousedown', handleClick);
-    document.addEventListener('touchstart', handleClick);
+    document.addEventListener('mousedown', handlePointerDown);
+    document.addEventListener('touchstart', handlePointerDown);
 
     return () => {
-      document.removeEventListener('mousedown', handleClick);
-      document.removeEventListener('touchstart', handleClick);
+      document.removeEventListener('mousedown', handlePointerDown);
+      document.removeEventListener('touchstart', handlePointerDown);
     };
-  }, [callback, enabled]);
+  }, [enabled]);
 
   return ref;
 }

package/src/presentation/hooks/useClipboard.ts

@@ -1,38 +1,56 @@
 /**
  * useClipboard Hook
- * @description Clipboard operations
+ * @description Clipboard operations with proper cleanup
  */
 
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { TIMING } from '../../infrastructure/constants/timing.constants';
 
 export interface UseClipboardReturn {
   value: string;
   copied: boolean;
-  copy: (text: string) => Promise<void>;
+  copy: (text: string) => Promise<boolean>;
 }
 
 export function useClipboard(): UseClipboardReturn {
   const [value, setValue] = useState<string>('');
   const [copied, setCopied] = useState<boolean>(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  const copy = useCallback(async (text: string): Promise<boolean> => {
+    if (typeof navigator === 'undefined' || !navigator.clipboard) {
+      console.error('[useClipboard] Clipboard API is not available in this environment.');
+      return false;
+    }
 
-  const copy = useCallback(async (text: string) => {
     try {
       await navigator.clipboard.writeText(text);
       setValue(text);
       setCopied(true);
 
-      setTimeout(() => {
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+      }
+      timeoutRef.current = setTimeout(() => {
         setCopied(false);
-      }, 2000);
+        timeoutRef.current = null;
+      }, TIMING.CLIPBOARD_RESET_MS);
+
+      return true;
     } catch (error) {
-      console.error('Failed to copy:', error);
+      console.error('[useClipboard] Failed to copy text:', error);
       setCopied(false);
+      return false;
     }
   }, []);
 
-  return {
-    value,
-    copied,
-    copy,
-  };
+  return { value, copied, copy };
 }

package/src/presentation/hooks/useDebounce.ts

@@ -4,25 +4,24 @@
  */
 
 import { useState, useEffect, useRef, useCallback } from 'react';
+import { TIMING } from '../../infrastructure/constants/timing.constants';
+import { clampToNonNegative } from '../../infrastructure/utils/calculation.utils';
 
-export function useDebounce<T>(value: T, delay: number = 500): T {
+export function useDebounce<T>(value: T, delay: number = TIMING.DEBOUNCE_DEFAULT_MS): T {
   const [debouncedValue, setDebouncedValue] = useState<T>(value);
   const timeoutRef = useRef<number | null>(null);
 
   useEffect(() => {
-    // Clear previous timeout
-    if (timeoutRef.current) {
+    if (timeoutRef.current !== null) {
       clearTimeout(timeoutRef.current);
     }
 
-    // Set new timeout
     timeoutRef.current = window.setTimeout(() => {
       setDebouncedValue(value);
     }, delay);
 
-    // Cleanup
     return () => {
-      if (timeoutRef.current) {
+      if (timeoutRef.current !== null) {
         clearTimeout(timeoutRef.current);
       }
     };
@@ -37,7 +36,7 @@ export function useDebounce<T>(value: T, delay: number = 500): T {
  */
 export function useThrottle<T extends (...args: any[]) => any>(
   func: T,
-  delay: number = 300
+  delay: number = TIMING.THROTTLE_DEFAULT_MS
 ): T {
   const lastRun = useRef<Date>(new Date());
   const timeoutRef = useRef<number | null>(null);
@@ -51,12 +50,11 @@ export function useThrottle<T extends (...args: any[]) => any>(
       return func(...args);
     }
 
-    if (timeoutRef.current) {
+    if (timeoutRef.current !== null) {
       clearTimeout(timeoutRef.current);
     }
 
-    // FIX: Ensure delay is never negative
-    const delayUntilNextExecution = Math.max(0, delay - timeSinceLastRun);
+    const delayUntilNextExecution = clampToNonNegative(delay - timeSinceLastRun);
     timeoutRef.current = window.setTimeout(() => {
       lastRun.current = new Date();
       func(...args);

package/src/presentation/hooks/useLocalStorage.ts

@@ -1,47 +1,57 @@
 /**
  * useLocalStorage Hook
- * @description LocalStorage state management with optimized re-renders
+ * @description LocalStorage state management with safe error surfacing
  */
 
 import { useCallback, useState, useRef } from 'react';
 
+const isBrowser = (): boolean =>
+  typeof window !== 'undefined' && typeof window.localStorage !== 'undefined';
+
+const readInitial = <T,>(key: string, initialValue: T): T => {
+  if (!isBrowser()) return initialValue;
+  try {
+    const raw = window.localStorage.getItem(key);
+    return raw === null ? initialValue : (JSON.parse(raw) as T);
+  } catch (error) {
+    console.error(`[useLocalStorage] Failed to read key "${key}":`, error);
+    return initialValue;
+  }
+};
+
 export function useLocalStorage<T>(
   key: string,
   initialValue: T
 ): [T, (value: T | ((prev: T) => T)) => void, () => void] {
-  const [storedValue, setStoredValue] = useState<T>(() => {
-    try {
-      const item = window.localStorage.getItem(key);
-      return item ? JSON.parse(item) : initialValue;
-    } catch {
-      return initialValue;
-    }
-  });
+  const [storedValue, setStoredValue] = useState<T>(() => readInitial(key, initialValue));
 
-  // Use ref to track latest value without causing re-renders
   const valueRef = useRef(storedValue);
   valueRef.current = storedValue;
 
   const setValue = useCallback(
     (value: T | ((prev: T) => T)) => {
+      const next =
+        typeof value === 'function' ? (value as (prev: T) => T)(valueRef.current) : value;
+
+      setStoredValue(next);
+
+      if (!isBrowser()) return;
       try {
-        // FIX: Use typeof instead of instanceof for better React functional update support
-        const valueToStore = typeof value === 'function' ? (value as (prev: T) => T)(valueRef.current) : value;
-        setStoredValue(valueToStore);
-        window.localStorage.setItem(key, JSON.stringify(valueToStore));
+        window.localStorage.setItem(key, JSON.stringify(next));
       } catch (error) {
-        console.error(`Error setting localStorage key "${key}":`, error);
+        console.error(`[useLocalStorage] Failed to write key "${key}":`, error);
       }
     },
-    [key] // Remove storedValue dependency
+    [key]
   );
 
   const removeValue = useCallback(() => {
+    setStoredValue(initialValue);
+    if (!isBrowser()) return;
     try {
       window.localStorage.removeItem(key);
-      setStoredValue(initialValue);
     } catch (error) {
-      console.error(`Error removing localStorage key "${key}":`, error);
+      console.error(`[useLocalStorage] Failed to remove key "${key}":`, error);
     }
   }, [key, initialValue]);
 

package/src/presentation/hooks/useMediaQuery.ts

@@ -14,6 +14,7 @@ import {
   isBreakpointGreaterThan,
   isBreakpointLessThan,
 } from '../../infrastructure/constants/breakpoint.constants';
+import { TIMING } from '../../infrastructure/constants/timing.constants';
 
 /**
  * Simple media query hook for a single breakpoint
@@ -102,7 +103,7 @@ export function useBreakpoint(): UseBreakpointReturn {
       if (resizeTimerRef.current) {
         clearTimeout(resizeTimerRef.current);
       }
-      resizeTimerRef.current = setTimeout(updateBreakpoint, 100);
+      resizeTimerRef.current = setTimeout(updateBreakpoint, TIMING.RESIZE_DEBOUNCE_MS);
     };
 
     window.addEventListener('resize', handleResize);

package/src/presentation/hooks/useScrollLock.ts

@@ -1,26 +1,54 @@
 /**
  * useScrollLock Hook
- * @description Lock/unlock body scroll
+ * @description Lock/unlock body scroll while preserving scrollbar gutter
  */
 
 import { useEffect } from 'react';
 
-export function useScrollLock(enabled: boolean = true) {
+/** Width of the vertical scrollbar, so locking scroll doesn't shift layout. */
+const measureScrollbarWidth = (): number => {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return 0;
+  return Math.max(0, window.innerWidth - document.documentElement.clientWidth);
+};
+
+const SCROLLBAR_GUTTER_STYLE_ID = 'use-scroll-lock-gutter-style';
+
+const ensureScrollbarGutterStyle = () => {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(SCROLLBAR_GUTTER_STYLE_ID)) return;
+
+  const style = document.createElement('style');
+  style.id = SCROLLBAR_GUTTER_STYLE_ID;
+  style.textContent = `
+    html.use-scroll-lock-active body {
+      overflow: hidden;
+    }
+  `;
+  document.head.appendChild(style);
+};
+
+export const useScrollLock = (enabled: boolean = true): void => {
   useEffect(() => {
-    if (!enabled) return;
+    if (!enabled || typeof document === 'undefined') return;
 
-    const originalStyle = window.getComputedStyle(document.body).overflow;
-    const originalPaddingRight = window.getComputedStyle(document.body).paddingRight;
+    ensureScrollbarGutterStyle();
+    const html = document.documentElement;
+    const body = document.body;
 
-    // FIX: Ensure scrollbar width is never negative
-    const scrollbarWidth = Math.max(0, window.innerWidth - document.documentElement.clientWidth);
+    const previousOverflow = body.style.overflow;
+    const previousPaddingRight = body.style.paddingRight;
+    const scrollbarWidth = measureScrollbarWidth();
 
-    document.body.style.overflow = 'hidden';
-    document.body.style.paddingRight = `${scrollbarWidth}px`;
+    body.style.overflow = 'hidden';
+    if (scrollbarWidth > 0) {
+      body.style.paddingRight = `${scrollbarWidth}px`;
+    }
+    html.classList.add('use-scroll-lock-active');
 
     return () => {
-      document.body.style.overflow = originalStyle;
-      document.body.style.paddingRight = originalPaddingRight;
+      body.style.overflow = previousOverflow;
+      body.style.paddingRight = previousPaddingRight;
+      html.classList.remove('use-scroll-lock-active');
     };
   }, [enabled]);
-}
+};

package/src/presentation/hooks/useToggle.ts

@@ -1,16 +1,18 @@
 /**
  * useToggle Hook
- * @description Toggle boolean state
+ * @description Toggle boolean state with explicit setValue
  */
 
-import { useCallback, useState } from 'react';
+import { useCallback, useState, useMemo } from 'react';
 
-export function useToggle(initialValue: boolean = false): [boolean, () => void, (value: boolean) => void] {
-  const [value, setValue] = useState(initialValue);
+export type UseToggleReturn = [boolean, () => void, (value: boolean) => void];
+
+export function useToggle(initialValue: boolean = false): UseToggleReturn {
+  const [value, setValue] = useState<boolean>(initialValue);
 
   const toggle = useCallback(() => {
-    setValue((v) => !v);
+    setValue((prev) => !prev);
   }, []);
 
-  return [value, toggle, setValue];
+  return useMemo<UseToggleReturn>(() => [value, toggle, setValue], [value, toggle]);
 }