@umituz/web-design-system 5.2.0 → 5.3.1

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/format.util.ts

@@ -0,0 +1 @@
+export const formatCount = (value: number, locale: string): string => new Intl.NumberFormat(locale).format(value);

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/id.util.ts

@@ -0,0 +1,2 @@
+export const uniqueId = (prefix: string): string =>
+  `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`;

package/src/infrastructure/utils/index.ts

@@ -1,8 +1,3 @@
-/**
- * Infrastructure Utils
- * @description Utility function exports
- * Subpath: @umituz/web-design-system/utils
- */
 
 export {
   cn,
@@ -33,6 +28,10 @@ export type { PageBounds } from './calculation.utils';
 
 export { hashSeed } from './hash.util';
 
+export { formatCount } from './format.util';
+
+export { uniqueId } from './id.util';
+
 export {
   currencyFractionDigits,
   formatMoney,

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,

package/src/presentation/atoms/Divider.tsx

@@ -1,7 +1,3 @@
-/**
- * Divider Component (Atom)
- * @description Visual separator line
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/HeatmapStrip.tsx

@@ -1,28 +1,18 @@
-/**
- * HeatmapStrip Component (Atom)
- * @description Compact threshold-toned strip of cells — percent-driven color
- * and opacity ramps (skill coverage, streak calendars, activity strips).
- */
 
 import { forwardRef } from 'react';
 import { cn } from '../../infrastructure/utils';
 import type { BaseProps } from '../../domain/types';
 
 export interface HeatmapCell {
-  /** 0–100, or null for "no data". */
   percent: number | null;
-  /** Tooltip text for the cell. */
   label?: string;
 }
 
 export interface HeatmapStripProps extends BaseProps {
   cells: readonly HeatmapCell[];
-  /** >= goodAt renders success; >= lowAt renders primary; below renders destructive. */
   goodAt?: number;
   lowAt?: number;
-  /** Cell height in px. */
   height?: number;
-  /** Accessible name for the whole strip. */
   label?: string;
 }
 

package/src/presentation/atoms/Hide.tsx

@@ -1,7 +1,3 @@
-/**
- * Hide Component (Atom)
- * @description Conditionally hide content based on screen breakpoint
- */
 
 import { useBreakpoint } from '../hooks/useMediaQuery';
 import type { HideProps } from '../../domain/types/breakpoint.types';
@@ -11,29 +7,9 @@ export interface HideComponentProps extends BaseProps, HideProps {
   children: React.ReactNode;
 }
 
-/**
- * Conditionally hide content based on breakpoint
- * @param above - Hide on screens larger than this breakpoint
- * @param below - Hide on screens smaller than this breakpoint
- * @param at - Hide only on this specific breakpoint
- * @param children - Content to hide
- *
- * @example
- * ```tsx
- * // Hide on mobile (md and below)
- * <Hide below="md"><DesktopNav /></Hide>
- *
- * // Hide on desktop (lg and above)
- * <Hide above="lg"><MobileNav /></Hide>
- *
- * // Hide only on tablet
- * <Hide at="md"><TabletContent /></Hide>
- * ```
- */
 export const Hide = ({ above, below, at, children, className }: HideComponentProps) => {
   const { matches, isGreaterThan, isLessThan } = useBreakpoint();
 
-  // Determine if content should be hidden
   let shouldHide = false;
 
   if (above) {

package/src/presentation/atoms/Icon.tsx

@@ -1,7 +1,3 @@
-/**
- * Icon Component (Atom)
- * @description Wrapper for SVG icons
- */
 
 import { forwardRef, type SVGAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/IconButton.tsx

@@ -1,7 +1,3 @@
-/**
- * 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';

package/src/presentation/atoms/Input.tsx

@@ -1,7 +1,3 @@
-/**
- * Input Component (Atom)
- * @description Text input field with optional label and helper text
- */
 
 import { forwardRef, useId, type InputHTMLAttributes, type ReactNode } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/Kbd.tsx

@@ -1,7 +1,3 @@
-/**
- * Kbd Component (Atom)
- * @description Keyboard key cap, e.g. for shortcut hints
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/Label.tsx

@@ -1,7 +1,3 @@
-/**
- * Label Component (Atom)
- * @description Form label (Shadcn/ui compatible)
- */
 
 import * as React from 'react';
 import * as LabelPrimitive from '@radix-ui/react-label';

package/src/presentation/atoms/Link.tsx

@@ -1,7 +1,3 @@
-/**
- * Link Component (Atom)
- * @description Styled anchor/link element
- */
 
 import { forwardRef, type AnchorHTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/Money.tsx

@@ -1,7 +1,3 @@
-/**
- * Money Component (Atom)
- * @description Locale-aware currency amount from minor units, tabular digits
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { formatMoney } from '../../infrastructure/utils';
@@ -9,9 +5,7 @@ import { cn } from '../../infrastructure/utils';
 import type { BaseProps } from '../../domain/types';
 
 export interface MoneyProps extends HTMLAttributes<HTMLSpanElement>, BaseProps {
-  /** Integer amount in minor units (e.g. cents) — never floating point. */
   amountMinor: number;
-  /** ISO 4217 currency code; drives the fraction digits. */
   currency: string;
   locale?: string;
 }

package/src/presentation/atoms/Progress.tsx

@@ -1,8 +1,3 @@
-/**
- * Progress Component (Atom)
- * @description Progress indicator bar with optional percent readout and
- *   threshold-driven auto tone (>=95 success, >=70 primary, below muted)
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';
@@ -15,7 +10,6 @@ export interface ProgressProps extends HTMLAttributes<HTMLDivElement>, BaseProps
   size?: 'sm' | 'md' | 'lg';
   tone?: 'primary' | 'success' | 'warning' | 'destructive' | 'info' | 'auto';
   label?: string;
-  /** Render the rounded percentage next to the bar. */
   showValue?: boolean;
 }
 

package/src/presentation/atoms/Radio.tsx

@@ -1,7 +1,3 @@
-/**
- * Radio Component (Atom)
- * @description Radio input element
- */
 
 import { forwardRef, type InputHTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/Separator.tsx

@@ -1,7 +1,3 @@
-/**
- * Separator Component (Atom) - Shadcn/ui format
- * @description Visual separator/divider component
- */
 
 import * as React from 'react';
 import * as SeparatorPrimitive from '@radix-ui/react-separator';