@umituz/web-design-system 5.3.0 → 6.0.0

package/src/infrastructure/constants/spacing.constants.ts

@@ -1,68 +1,45 @@
-/**
- * Spacing Constants
- * @description Tailwind CSS spacing scale values
- * @see https://tailwindcss.com/docs/customizing-spacing
- *
- * All spacing values used in the design system are defined here.
- * This provides a single source of truth for spacing scale.
- */
 
-/**
- * Tailwind CSS spacing scale
- * Each value represents a spacing unit that maps to a specific pixel value
- * Format: Key is the spacing class name, value is the unit number (as string for Tailwind class construction)
- */
 export const SPACING_SCALE = {
-  '0': '0',   // 0px
-  '0.5': '0.5', // 2px
-  '1': '1',   // 4px
-  '1.5': '1.5', // 6px
-  '2': '2',   // 8px
-  '2.5': '2.5', // 10px
-  '3': '3',   // 12px
-  '3.5': '3.5', // 14px
-  '4': '4',   // 16px
-  '5': '5',   // 20px
-  '6': '6',   // 24px
-  '7': '7',   // 28px
-  '8': '8',   // 32px
-  '9': '9',   // 36px
-  '10': '10', // 40px
-  '11': '11', // 44px
-  '12': '12', // 48px
-  '14': '14', // 56px
-  '16': '16', // 64px
-  '20': '20', // 80px
-  '24': '24', // 96px
-  '28': '28', // 112px
-  '32': '32', // 128px
-  '36': '36', // 144px
-  '40': '40', // 160px
-  '44': '44', // 176px
-  '48': '48', // 192px
-  '52': '52', // 208px
-  '56': '56', // 224px
-  '60': '60', // 240px
-  '64': '64', // 256px
-  '72': '72', // 288px
-  '80': '80', // 320px
-  '96': '96', // 384px
+  '0': '0',
+  '0.5': '0.5',
+  '1': '1',
+  '1.5': '1.5',
+  '2': '2',
+  '2.5': '2.5',
+  '3': '3',
+  '3.5': '3.5',
+  '4': '4',
+  '5': '5',
+  '6': '6',
+  '7': '7',
+  '8': '8',
+  '9': '9',
+  '10': '10',
+  '11': '11',
+  '12': '12',
+  '14': '14',
+  '16': '16',
+  '20': '20',
+  '24': '24',
+  '28': '28',
+  '32': '32',
+  '36': '36',
+  '40': '40',
+  '44': '44',
+  '48': '48',
+  '52': '52',
+  '56': '56',
+  '60': '60',
+  '64': '64',
+  '72': '72',
+  '80': '80',
+  '96': '96',
 } as const;
 
-/**
- * Type for spacing scale keys
- */
 export type SpacingScaleKey = keyof typeof SPACING_SCALE;
 
-/**
- * Type for spacing scale values (string format for Tailwind classes)
- */
 export type SpacingScale = `${SpacingScaleKey}`;
 
-/**
- * Common spacing values used throughout the design system
- * These are frequently used spacing values
- */
 export const COMMON_SPACING = {
   xs: SPACING_SCALE['1'],
   sm: SPACING_SCALE['2'],
@@ -72,9 +49,6 @@ export const COMMON_SPACING = {
   '2xl': SPACING_SCALE['12'],
 } as const;
 
-/**
- * Spacing scale for component sizing
- */
 export const SIZE_SPACING = {
   xs: SPACING_SCALE['3'],
   sm: SPACING_SCALE['4'],
@@ -84,9 +58,6 @@ export const SIZE_SPACING = {
   '2xl': SPACING_SCALE['10'],
 } as const;
 
-/**
- * Validate if a value is a valid spacing scale
- */
 export function isValidSpacing(value: string): value is SpacingScale {
   return Object.keys(SPACING_SCALE).includes(value);
 }

package/src/infrastructure/constants/timing.constants.ts

@@ -1,45 +1,27 @@
-/**
- * Timing Constants
- * @description Centralized timing values for debouncing, throttling, transitions, and async operations
- *
- * All durations are in milliseconds unless suffixed with `_MS` (also ms) or `_SECONDS`.
- */
 
 export const TIMING = {
-  /** Default debounce window for value-driven hooks */
   DEBOUNCE_DEFAULT_MS: 500,
 
-  /** Default throttle window for rate-limited functions */
   THROTTLE_DEFAULT_MS: 300,
 
-  /** Default throttle for resize-driven breakpoint detection */
   RESIZE_DEBOUNCE_MS: 100,
 
-  /** Tooltip open/close transition delay */
   TOOLTIP_DEFAULT_DELAY_MS: 200,
 
-  /** Reset window after clipboard copy success */
   CLIPBOARD_RESET_MS: 2000,
 
-  /** Modal fade-out duration before unmounting */
   MODAL_FADE_OUT_MS: 200,
 
-  /** CodeBlock "Copied!" indicator reset window */
   CODE_BLOCK_COPY_RESET_MS: 2000,
 
-  /** CodeBlock collapse threshold (line count) */
   CODE_BLOCK_COLLAPSE_THRESHOLD: 10,
 
-  /** Newsletter submission simulated network round-trip */
   NEWSLETTER_SUBMIT_DELAY_MS: 1000,
 
-  /** Memory-leak detector lifespan polling cadence */
   MEMORY_LEAK_POLL_MS: 1000,
 
-  /** Max render-time samples kept in monitor ring buffer */
   PERFORMANCE_RENDER_TIME_SAMPLES: 50,
 
-  /** Slow-render threshold for warnings (ms, 1 frame at 60fps) */
   SLOW_RENDER_THRESHOLD_MS: 16,
 } as const;
 

package/src/infrastructure/constants/typography.constants.ts

@@ -1,68 +1,40 @@
-/**
- * Typography Constants
- * @description Typography scale values for the design system
- *
- * All font size and text utility values are defined here.
- * This provides consistency with Tailwind's default typography scale.
- */
 
-/**
- * Text size utilities (Tailwind text classes)
- */
 export const TEXT_SIZES = {
-  xs: 'text-xs',       // 0.75rem (12px)
-  sm: 'text-sm',       // 0.875rem (14px)
-  base: 'text-base',   // 1rem (16px)
-  lg: 'text-lg',       // 1.125rem (18px)
-  xl: 'text-xl',       // 1.25rem (20px)
-  '2xl': 'text-2xl',   // 1.5rem (24px)
-  '3xl': 'text-3xl',   // 1.875rem (30px)
-  '4xl': 'text-4xl',   // 2.25rem (36px)
-  '5xl': 'text-5xl',   // 3rem (48px)
-  '6xl': 'text-6xl',   // 3.75rem (60px)
-  '7xl': 'text-7xl',   // 4.5rem (72px)
-  '8xl': 'text-8xl',   // 6rem (96px)
-  '9xl': 'text-9xl',   // 8rem (128px)
+  xs: 'text-xs',
+  sm: 'text-sm',
+  base: 'text-base',
+  lg: 'text-lg',
+  xl: 'text-xl',
+  '2xl': 'text-2xl',
+  '3xl': 'text-3xl',
+  '4xl': 'text-4xl',
+  '5xl': 'text-5xl',
+  '6xl': 'text-6xl',
+  '7xl': 'text-7xl',
+  '8xl': 'text-8xl',
+  '9xl': 'text-9xl',
 } as const;
 
-/**
- * Type for text size keys
- */
 export type TextSizeKey = keyof typeof TEXT_SIZES;
 
-/**
- * Type for text size values
- */
 export type TextSize = typeof TEXT_SIZES[TextSizeKey];
 
-/**
- * Font weight utilities
- */
 export const FONT_WEIGHTS = {
-  thin: 'font-thin',       // 100
-  extralight: 'font-extralight', // 200
-  light: 'font-light',     // 300
-  normal: 'font-normal',   // 400
-  medium: 'font-medium',   // 500
-  semibold: 'font-semibold', // 600
-  bold: 'font-bold',       // 700
-  extrabold: 'font-extrabold', // 800
-  black: 'font-black',     // 900
+  thin: 'font-thin',
+  extralight: 'font-extralight',
+  light: 'font-light',
+  normal: 'font-normal',
+  medium: 'font-medium',
+  semibold: 'font-semibold',
+  bold: 'font-bold',
+  extrabold: 'font-extrabold',
+  black: 'font-black',
 } as const;
 
-/**
- * Type for font weight keys
- */
 export type FontWeightKey = keyof typeof FONT_WEIGHTS;
 
-/**
- * Type for font weight values
- */
 export type FontWeight = typeof FONT_WEIGHTS[FontWeightKey];
 
-/**
- * Common text sizes for different element types
- */
 export const COMMON_TEXT_SIZES = {
   caption: TEXT_SIZES.xs,
   small: TEXT_SIZES.sm,
@@ -73,10 +45,6 @@ export const COMMON_TEXT_SIZES = {
   display: TEXT_SIZES['4xl'],
 } as const;
 
-/**
- * Text sizes by size variant
- * Maps size variants to appropriate text sizes
- */
 export const TEXT_SIZE_BY_VARIANT = {
   xs: {
     mobile: TEXT_SIZES.xs,

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

@@ -1,10 +1,4 @@
-/**
- * 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;
@@ -20,7 +14,6 @@ export const clampToNonNegative = (value: number): number =>
 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;
@@ -30,7 +23,6 @@ export const percentOfMax = (value: number, max: number): number => {
   return clampToRange((value / max) * PERCENT_MAX, PERCENT_MIN, PERCENT_MAX);
 };
 
-// --- Trend formatting ---
 
 const PERCENT_FRACTION_DIGITS = 1;
 const SIGN_THRESHOLD = 0;
@@ -43,7 +35,6 @@ export const formatTrendMagnitude = (value: number, fractionDigits: number = PER
   return `${sign}${Math.abs(value).toFixed(fractionDigits)}%`;
 };
 
-// --- Pagination bounds ---
 
 export interface PageBounds {
   totalPages: number;

package/src/infrastructure/utils/cn.util.ts

@@ -1,14 +1,9 @@
-/**
- * cn Utility
- * @description Conditional className utility using clsx + tailwind-merge for proper Tailwind class merging with LRU cache for performance
- */
 
 import { clsx, type ClassValue } from 'clsx';
 import { twMerge } from 'tailwind-merge';
 
 export type { ClassValue };
 
-// Simple LRU Cache implementation for className caching
 class LRUCache<K, V> {
   private cache: Map<K, V>;
   private maxSize: number;
@@ -21,7 +16,6 @@ class LRUCache<K, V> {
   get(key: K): V | undefined {
     const value = this.cache.get(key);
     if (value !== undefined) {
-      // Move to end (most recently used)
       this.cache.delete(key);
       this.cache.set(key, value);
     }
@@ -29,14 +23,11 @@ class LRUCache<K, V> {
   }
 
   set(key: K, value: V): void {
-    // Remove existing entry to update position
     if (this.cache.has(key)) {
       this.cache.delete(key);
     }
-    // Remove oldest entry if at capacity
     else if (this.cache.size >= this.maxSize) {
       const firstKey = this.cache.keys().next().value;
-      // FIX: Check if firstKey exists before deleting
       if (firstKey !== undefined) {
         this.cache.delete(firstKey);
       }
@@ -49,23 +40,18 @@ class LRUCache<K, V> {
   }
 }
 
-// Create cache instance
 const classNameCache = new LRUCache<string, string>(256);
 
-// FIX: Better cache key generator that handles functions and undefined
 function generateCacheKey(inputs: ClassValue[]): string {
   try {
-    // Convert inputs to a cacheable string representation
     const normalized = inputs.map((input) => {
       if (input === null || input === undefined) {
         return 'null';
       }
       if (typeof input === 'function') {
-        // For functions, use a placeholder since functions can't be reliably serialized
         return 'function';
       }
       if (typeof input === 'object') {
-        // Handle objects (like conditional objects in clsx)
         return JSON.stringify(
           Object.entries(input)
             .filter(([, value]) => Boolean(value))
@@ -78,13 +64,11 @@ function generateCacheKey(inputs: ClassValue[]): string {
 
     return normalized.join('|');
   } catch {
-    // Fallback if anything goes wrong with serialization
     return inputs.join('|');
   }
 }
 
 export function cn(...inputs: ClassValue[]): string {
-  // Skip cache for dynamic inputs that might contain functions
   const hasFunction = inputs.some((input) => typeof input === 'function');
 
   if (!hasFunction) {
@@ -101,9 +85,7 @@ export function cn(...inputs: ClassValue[]): string {
     return result;
   }
 
-  // For inputs with functions, skip cache and compute directly
   return twMerge(clsx(inputs));
 }
 
-// Export cache for manual clearing if needed
 export { classNameCache };

package/src/infrastructure/utils/hash.util.ts

@@ -1,8 +1,3 @@
-/**
- * Hash Utils
- * @description Deterministic string hashing — the same seed always maps to
- * the same number, powering stable generated artwork variants
- */
 
 export const hashSeed = (input: string): number => {
   let hash = 2166136261;

package/src/infrastructure/utils/index.ts

@@ -1,8 +1,3 @@
-/**
- * Infrastructure Utils
- * @description Utility function exports
- * Subpath: @umituz/web-design-system/utils
- */
 
 export {
   cn,

package/src/infrastructure/utils/money.utils.ts

@@ -1,9 +1,4 @@
-/**
- * Money Utils
- * @description Minor-unit money math and locale-aware formatting (ISO 4217)
- */
 
-/** Currencies that don't use 2 decimal places. Everything else defaults to 2. */
 const FRACTION_DIGITS: Record<string, number> = {
   BHD: 3,
   IQD: 3,
@@ -58,7 +53,6 @@ export function toMinor(amount: number, currency: string): number {
   return Math.round(amount * 10 ** currencyFractionDigits(currency));
 }
 
-/** Parses user input like '12.50' into minor units for the currency. Null when invalid. */
 export function parseAmountToMinor(input: string, currency: string): number | null {
   const digits = currencyFractionDigits(currency);
   const trimmed = input.trim().replace(',', '.');
@@ -69,7 +63,6 @@ export function parseAmountToMinor(input: string, currency: string): number | nu
   return Number.isSafeInteger(minor) ? minor : null;
 }
 
-/** Percentage of an amount, rounded half-up to whole minor units. */
 export function pctOfMinor(amountMinor: number, pct: number): number {
   return Math.round((amountMinor * pct) / 100);
 }

package/src/infrastructure/utils/responsive.utils.ts

@@ -1,8 +1,3 @@
-/**
- * Responsive Utility Functions
- * @description Centralized functions for building responsive Tailwind classes
- * All responsive class construction logic lives here - components should only call these functions
- */
 
 import { cn } from './cn.util';
 import type { SizeVariant, Breakpoint } from '../../domain/types';
@@ -13,25 +8,14 @@ import {
   RESPONSIVE_TEXT_SIZE,
 } from '../../domain/tokens/responsive-map.tokens';
 
-/**
- * Build responsive padding/margin/gap classes
- * @param property - Tailwind spacing property ('p', 'm', 'px', 'py', 'gap', 'space-y', 'space-x')
- * @param size - Size variant (sm, md, lg, xl)
- * @returns Complete responsive class string
- *
- * @example
- * getSpacing('p', 'md') // "p-4 sm:p-5 md:p-5 lg:p-6 xl:p-8 2xl:p-10"
- */
 export function getSpacing(
   property: 'p' | 'm' | 'px' | 'py' | 'pt' | 'pb' | 'pl' | 'pr' | 'gap' | 'space-y' | 'space-x',
   size: SizeVariant
 ): string {
   const token = RESPONSIVE_SPACING[size];
 
-  // Start with base (xs/mobile) value
   const classes: string[] = [`${property}-${token.xs}`];
 
-  // Add breakpoint-specific classes
   const breakpoints: Breakpoint[] = ['sm', 'md', 'lg', 'xl', '2xl'];
   breakpoints.forEach((bp) => {
     if (token[bp] !== token.xs) {
@@ -42,14 +26,6 @@ export function getSpacing(
   return classes.join(' ');
 }
 
-/**
- * Build responsive icon size classes (height + width)
- * @param size - Size variant
- * @returns Combined height and width classes
- *
- * @example
- * getIconSize('md') // "h-5 w-5 sm:h-6 sm:w-6 md:h-7 md:w-7 lg:h-8 lg:w-8 xl:h-9 xl:w-9 2xl:h-10 2xl:w-10"
- */
 export function getIconSize(size: SizeVariant): string {
   const token = RESPONSIVE_ICON_SIZE[size];
   const classes: string[] = [`h-${token.xs}`, `w-${token.xs}`];
@@ -64,14 +40,6 @@ export function getIconSize(size: SizeVariant): string {
   return classes.join(' ');
 }
 
-/**
- * Build responsive container size classes (for icon wrappers)
- * @param size - Size variant
- * @returns Combined height, width, and flex center classes
- *
- * @example
- * getContainerSize('md') // "w-10 h-10 sm:w-12 sm:h-12 md:w-12 md:h-12..."
- */
 export function getContainerSize(size: SizeVariant): string {
   const token = RESPONSIVE_CONTAINER_SIZE[size];
   const classes: string[] = [`w-${token.xs}`, `h-${token.xs}`];
@@ -86,53 +54,19 @@ export function getContainerSize(size: SizeVariant): string {
   return classes.join(' ');
 }
 
-/**
- * Get responsive text size classes
- * @param size - Size variant
- * @returns Text size class string
- *
- * @example
- * getTextSize('md') // "text-sm sm:text-base"
- */
 export function getTextSize(size: SizeVariant): string {
   const token = RESPONSIVE_TEXT_SIZE[size];
   return cn(token.mobile, token.tablet);
 }
 
-/**
- * Build responsive gap/spacing classes for layout
- * @param size - Size variant
- * @returns Gap class string
- *
- * @example
- * getGap('md') // "gap-3 sm:gap-4 md:gap-4 lg:gap-5 xl:gap-5 2xl:gap-6"
- */
 export function getGap(size: SizeVariant): string {
   return getSpacing('gap', size);
 }
 
-/**
- * Build responsive space-y classes for vertical stacking
- * @param size - Size variant
- * @returns Space-y class string
- *
- * @example
- * getSpaceY('md') // "space-y-3 sm:space-y-4 md:space-y-4 lg:space-y-5..."
- */
 export function getSpaceY(size: SizeVariant): string {
   return getSpacing('space-y', size);
 }
 
-/**
- * Get complete responsive styles for common component patterns
- * @param size - Size variant
- * @param options - Which styles to include
- * @returns Combined class string
- *
- * @example
- * getResponsiveStyles('md', { padding: true, gap: true })
- * // "p-4 sm:p-5 md:p-5 lg:p-6 xl:p-8 2xl:p-10 gap-3 sm:gap-4..."
- */
 export function getResponsiveStyles(
   size: SizeVariant,
   options: {

package/src/presentation/atoms/AspectRatio.tsx

@@ -1,13 +1,3 @@
-/**
- * AspectRatio Component
- * @description Aspect ratio container component
- * @example
- * import { AspectRatio } from '@umituz/web-design-system/atoms';
- *
- * <AspectRatio ratio={16 / 9}>
- *   <img src="..." alt="..." className="object-cover w-full h-full" />
- * </AspectRatio>
- */
 
 import * as React from "react";
 

package/src/presentation/atoms/Badge.tsx

@@ -1,7 +1,3 @@
-/**
- * Badge Component (Atom)
- * @description Small status or label indicator
- */
 
 import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
 import { cn } from '../../infrastructure/utils';
@@ -13,7 +9,6 @@ export type BadgeVariant = ColorVariant | 'info' | 'danger' | 'neutral' | 'accen
 export interface BadgeProps extends HTMLAttributes<HTMLDivElement>, BaseProps {
   variant?: BadgeVariant;
   tone?: BadgeVariant;
-  /** Icon rendered before the label; svgs are sized to the badge text. */
   icon?: ReactNode;
   size?: MediumSizes;
   small?: boolean;

package/src/presentation/atoms/BatteryPill.tsx

@@ -1,14 +1,9 @@
-/**
- * BatteryPill Component (Atom)
- * @description Battery charge indicator: outline cell with fill level and percentage
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';
 import type { BaseProps } from '../../domain/types';
 
 export interface BatteryPillProps extends HTMLAttributes<HTMLSpanElement>, BaseProps {
-  /** Charge percentage, clamped to 0-100. */
   pct: number;
 }
 

package/src/presentation/atoms/Button.tsx

@@ -46,7 +46,6 @@ export interface ButtonProps
   icon?: React.ReactNode;
   iconRight?: React.ReactNode;
   loading?: boolean;
-  /** Renders the button as a client-side navigation link (`react-router`). */
   to?: string;
 }
 
@@ -60,7 +59,6 @@ const Button = React.memo(React.forwardRef<HTMLButtonElement, ButtonProps>(
           className={cn(block && 'w-full', buttonVariants({ variant, size, className }))}
           ref={ref as React.Ref<HTMLAnchorElement>}
           aria-disabled={disabled || loading || undefined}
-          // Button-typed DOM props (onClick, aria-*, …) flow straight onto the anchor.
           {...(props as unknown as React.AnchorHTMLAttributes<HTMLAnchorElement>)}
         >
           {loading ? <Spinner size="sm" /> : icon}

package/src/presentation/atoms/Checkbox.tsx

@@ -1,7 +1,3 @@
-/**
- * Checkbox Component (Atom)
- * @description Checkbox input element with optional label
- */
 
 import {
   forwardRef,