@umituz/web-design-system 5.3.0 → 5.3.1

package/src/presentation/atoms/Show.tsx

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

package/src/presentation/atoms/Skeleton.tsx

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

package/src/presentation/atoms/Slider.tsx

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

package/src/presentation/atoms/Sparkline.tsx

@@ -1,7 +1,3 @@
-/**
- * Sparkline Component (Atom)
- * @description Minimal inline line chart for compact trends
- */
 
 import { forwardRef, type SVGAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/Spinner.tsx

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

package/src/presentation/atoms/Switch.tsx

@@ -1,7 +1,3 @@
-/**
- * Switch Component (Atom) - Shadcn/ui format
- * @description Toggle switch component using class-variance-authority
- */
 
 import * as React from 'react';
 import * as SwitchPrimitives from '@radix-ui/react-switch';

package/src/presentation/atoms/Text.tsx

@@ -1,7 +1,3 @@
-/**
- * Text Component (Atom)
- * @description Styled text element with polymorphic rendering
- */
 
 import { forwardRef, memo, type ElementType, type ComponentPropsWithoutRef } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/Textarea.tsx

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

package/src/presentation/atoms/Toggle.tsx

@@ -1,7 +1,3 @@
-/**
- * Toggle Component (Atom) - Shadcn/ui format
- * @description Toggle button component with variants
- */
 
 import * as React from 'react';
 import * as TogglePrimitive from '@radix-ui/react-toggle';

package/src/presentation/atoms/Tooltip.tsx

@@ -1,7 +1,3 @@
-/**
- * Tooltip Component (Atom)
- * @description Popup with additional information
- */
 
 import { forwardRef, type HTMLAttributes, type ReactNode, useState, useRef, useEffect } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/atoms/index.ts

@@ -1,8 +1,3 @@
-/**
- * Atoms Export
- * @description Atomic components - smallest UI elements
- * Subpath: @umituz/web-design-system/atoms
- */
 
 export { Button } from './Button';
 export type { ButtonProps } from './Button';

package/src/presentation/hooks/index.ts

@@ -1,8 +1,3 @@
-/**
- * Presentation Hooks Export
- * @description React hooks
- * Subpath: @umituz/web-design-system/hooks
- */
 
 export { useTheme } from './useTheme';
 export type { Theme, UseThemeReturn } from './useTheme';

package/src/presentation/hooks/useClickOutside.ts

@@ -1,7 +1,3 @@
-/**
- * useClickOutside Hook
- * @description Detect clicks outside an element
- */
 
 import { useEffect, useRef } from 'react';
 
@@ -10,8 +6,6 @@ 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);
   useEffect(() => {
     callbackRef.current = callback;

package/src/presentation/hooks/useClipboard.ts

@@ -1,7 +1,3 @@
-/**
- * useClipboard Hook
- * @description Clipboard operations with proper cleanup
- */
 
 import { useState, useCallback, useEffect, useRef } from 'react';
 import { TIMING } from '../../infrastructure/constants/timing.constants';

package/src/presentation/hooks/useDebounce.ts

@@ -1,7 +1,3 @@
-/**
- * useDebounce Hook
- * @description Debounce a value with optimized performance
- */
 
 import { useState, useEffect, useRef, useCallback } from 'react';
 import { TIMING } from '../../infrastructure/constants/timing.constants';
@@ -30,10 +26,6 @@ export function useDebounce<T>(value: T, delay: number = TIMING.DEBOUNCE_DEFAULT
   return debouncedValue;
 }
 
-/**
- * useThrottle Hook
- * @description Throttle a function to limit execution rate
- */
 export function useThrottle<T extends (...args: unknown[]) => unknown>(
   func: T,
   delay: number = TIMING.THROTTLE_DEFAULT_MS

package/src/presentation/hooks/useKeyboard.ts

@@ -1,7 +1,3 @@
-/**
- * useKeyboard Hook
- * @description Keyboard event handling
- */
 
 import { useEffect, useCallback } from 'react';
 
@@ -16,7 +12,6 @@ export interface KeyboardOptions {
   enabled?: boolean;
 }
 
-// Helper function to check if modifiers match
 const checkModifiers = (event: KeyboardEvent, modifiers: KeyboardModifier[]): boolean => {
   return modifiers.every((mod) => {
     switch (mod) {
@@ -41,7 +36,6 @@ export function useKeyboard({
   onKeyUp,
   enabled = true,
 }: KeyboardOptions) {
-  // FIX: Create handlers once and reuse to prevent duplicate logic
   const handleKeyDown = useCallback((event: KeyboardEvent) => {
     const keyMatches = event.key.toLowerCase() === key.toLowerCase();
     const modifiersMatch = checkModifiers(event, modifiers);

package/src/presentation/hooks/useLocalStorage.ts

@@ -1,7 +1,3 @@
-/**
- * useLocalStorage Hook
- * @description LocalStorage state management with safe error surfacing
- */
 
 import { useCallback, useEffect, useState, useRef } from 'react';
 

package/src/presentation/hooks/useMediaQuery.ts

@@ -1,7 +1,3 @@
-/**
- * useMediaQuery & useBreakpoint Hooks
- * @description Enhanced responsive breakpoint detection with helper functions
- */
 
 import { useEffect, useState, useCallback, useRef, useMemo, useSyncExternalStore } from 'react';
 import type {
@@ -16,16 +12,6 @@ import {
 } from '../../infrastructure/constants/breakpoint.constants';
 import { TIMING } from '../../infrastructure/constants/timing.constants';
 
-/**
- * Simple media query hook for a single breakpoint
- * @param breakpoint - The breakpoint to check
- * @returns Whether the media query matches
- *
- * @example
- * ```tsx
- * const isDesktop = useMediaQuery('lg') // true on lg screens and above
- * ```
- */
 export function useMediaQuery(breakpoint: Breakpoint): boolean {
   const query = useMemo(() => createMediaQuery(breakpoint), [breakpoint]);
 
@@ -49,24 +35,7 @@ export function useMediaQuery(breakpoint: Breakpoint): boolean {
   return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 
-/**
- * Enhanced breakpoint hook with helper functions
- * @returns Object containing current breakpoint and helper functions
- *
- * @example
- * ```tsx
- * const { currentBreakpoint, isMobile, isDesktop } = useBreakpoint()
- *
- * return (
- *   <div>
- *     {isMobile && <MobileNav />}
- *     {isDesktop && <DesktopNav />}
- *   </div>
- * )
- * ```
- */
 export function useBreakpoint(): UseBreakpointReturn {
-  // FIX: Sort breakpoints once and memoize
   const sortedBreakpoints = useMemo(() => {
     return Object.entries(BREAKPOINTS).sort(
       ([, a], [, b]) => b.min - a.min
@@ -74,7 +43,6 @@ export function useBreakpoint(): UseBreakpointReturn {
   }, []);
 
   const [currentBreakpoint, setCurrentBreakpoint] = useState<Breakpoint>(() => {
-    // FIX: SSR-safe initialization
     if (typeof window === 'undefined') return 'lg';
 
     const width = window.innerWidth;
@@ -84,7 +52,6 @@ export function useBreakpoint(): UseBreakpointReturn {
     return 'xs';
   });
 
-  // FIX: Use useRef for resize timer to prevent timer issues
   const resizeTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
 
   useEffect(() => {
@@ -99,10 +66,8 @@ export function useBreakpoint(): UseBreakpointReturn {
       }
     };
 
-    // Initial check
     updateBreakpoint();
 
-    // Debounced resize listener
     const handleResize = () => {
       if (resizeTimerRef.current) {
         clearTimeout(resizeTimerRef.current);
@@ -120,7 +85,6 @@ export function useBreakpoint(): UseBreakpointReturn {
     };
   }, [sortedBreakpoints]);
 
-  // Helper functions
   const matches = useCallback(
     (breakpoint: Breakpoint | Breakpoint[]): boolean => {
       if (Array.isArray(breakpoint)) {
@@ -145,7 +109,6 @@ export function useBreakpoint(): UseBreakpointReturn {
     [currentBreakpoint]
   );
 
-  // Computed values
   const isXs = currentBreakpoint === 'xs';
   const isSm = currentBreakpoint === 'sm';
   const isMd = currentBreakpoint === 'md';

package/src/presentation/hooks/useScrollLock.ts

@@ -1,11 +1,6 @@
-/**
- * useScrollLock Hook
- * @description Lock/unlock body scroll while preserving scrollbar gutter
- */
 
 import { useEffect } from 'react';
 
-/** 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);

package/src/presentation/hooks/useTheme.ts

@@ -1,7 +1,3 @@
-/**
- * useTheme Hook
- * @description Theme toggle functionality with SSR support and system preference detection
- */
 
 import { useEffect, useState, useCallback } from 'react';
 
@@ -25,9 +21,16 @@ const getSystemTheme = (): 'light' | 'dark' => {
   return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 };
 
+const writeThemeStorage = (theme: Theme): void => {
+  try {
+    localStorage.setItem(THEME_STORAGE_KEY, theme);
+  } catch {
+    return;
+  }
+};
+
 export function useTheme(): UseThemeReturn {
   const [theme, setThemeState] = useState<Theme>(() => {
-    // FIX: SSR-safe initialization
     if (typeof window === 'undefined') return 'system';
 
     try {
@@ -47,7 +50,6 @@ export function useTheme(): UseThemeReturn {
     return theme;
   });
 
-  // Listen for system theme changes
   useEffect(() => {
     if (theme !== 'system') return;
 
@@ -66,15 +68,9 @@ export function useTheme(): UseThemeReturn {
 
     root.classList.remove('light', 'dark');
     root.classList.add(themeToApply);
-
-    try {
-      localStorage.setItem(THEME_STORAGE_KEY, theme);
-    } catch {
-      // Ignore storage errors
-    }
+    writeThemeStorage(theme);
   }, [theme]);
 
-  // FIX: Memoize callbacks to prevent unnecessary re-renders
   const toggleTheme = useCallback(() => {
     setThemeState((prev) => {
       if (prev === 'light') return 'dark';

package/src/presentation/hooks/useToggle.ts

@@ -1,7 +1,3 @@
-/**
- * useToggle Hook
- * @description Toggle boolean state with explicit setValue
- */
 
 import { useCallback, useState, useMemo } from 'react';
 

package/src/presentation/molecules/ActiveFilterTags.tsx

@@ -1,7 +1,3 @@
-/**
- * ActiveFilterTags Component (Molecule)
- * @description Display active filters with remove buttons
- */
 
 import { X } from 'lucide-react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/molecules/Avatar.tsx

@@ -1,7 +1,3 @@
-/**
- * Avatar Component (Molecule)
- * @description User avatar with image and fallback (shadcn/ui compatible)
- */
 
 import { forwardRef, type HTMLAttributes, type ComponentPropsWithoutRef } from 'react';
 import { cn } from '../../infrastructure/utils';
@@ -11,7 +7,6 @@ import type { ExtendedSizes } from '../../infrastructure/constants';
 export interface AvatarProps extends HTMLAttributes<HTMLDivElement>, BaseProps {
   name?: string;
   size?: ExtendedSizes;
-  /** Accent hue (0-360) for the initials fallback, overriding the name-hash tone. */
   hue?: number;
 }
 

package/src/presentation/molecules/BookmarkButton.tsx

@@ -1,8 +1,3 @@
-/**
- * BookmarkButton Component (Molecule)
- * @description Accessible toggleable button for saving, bookmarking, or favoriting items.
- * Supports pill (icon + label) and icon-only variants, multiple sizes, semantic tones, and custom icons.
- */
 
 import React, { forwardRef } from 'react';
 import { Star } from 'lucide-react';
@@ -15,25 +10,15 @@ export type BookmarkTone = 'warning' | 'primary' | 'success' | 'default';
 export interface BookmarkButtonProps
   extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onChange' | 'onToggle'>,
     BaseProps {
-  /** Whether the item is currently saved / bookmarked / active. */
   active?: boolean;
-  /** Callback fired when clicked or toggled. Passes the inverted active state. */
   onToggle?: (nextActive: boolean) => void;
-  /** Display variant: 'pill' shows icon + label, 'icon' renders a square/round icon-only button. */
   variant?: 'pill' | 'icon';
-  /** Size variant */
   size?: 'xs' | 'sm' | 'md' | 'lg';
-  /** Inactive label (default: "Save"). Used as text in pill mode and aria-label in icon mode. */
   label?: string;
-  /** Active label (default: "Saved"). */
   activeLabel?: string;
-  /** Custom icon when inactive. Defaults to a Star outline. */
   icon?: React.ReactNode;
-  /** Custom icon when active. Defaults to a filled Star. */
   activeIcon?: React.ReactNode;
-  /** Color theme tone when active (default: 'warning' for warm bookmark gold). */
   tone?: BookmarkTone;
-  /** Loading indicator */
   loading?: boolean;
 }
 

package/src/presentation/molecules/CheckboxGroup.tsx

@@ -1,7 +1,3 @@
-/**
- * CheckboxGroup Component (Molecule)
- * @description Group of checkboxes
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/molecules/Chip.tsx

@@ -1,7 +1,3 @@
-/**
- * Chip Component (Molecule)
- * @description Selectable/removable tag
- */
 
 import { forwardRef } from 'react';
 import { cn } from '../../infrastructure/utils';
@@ -15,7 +11,6 @@ export interface ChipProps extends BaseProps {
   onRemove?: () => void;
   onClick?: () => void;
   removable?: boolean;
-  /** Toggle state for filter chips — renders as a pressed button when set. */
   selected?: boolean;
 }
 

package/src/presentation/molecules/CodeBlock.tsx

@@ -1,7 +1,3 @@
-/**
- * CodeBlock Component (Molecule)
- * @description Syntax-highlighted code block with copy button and expand/collapse
- */
 
 import { useState, useEffect } from 'react';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
@@ -15,7 +11,6 @@ export interface CodeBlockProps extends BaseProps {
   language?: string;
   filename?: string;
   showLineNumbers?: boolean;
-  /** Lines threshold to enable collapse/expand. */
   collapseThreshold?: number;
 }
 

package/src/presentation/molecules/Field.tsx

@@ -13,18 +13,11 @@ export interface FieldProps {
   error?: ReactNode;
   required?: boolean;
   htmlFor?: string;
-  /** Keep the label in the accessibility tree while hiding it visually. */
   hideLabel?: boolean;
   className?: string;
   children: ReactNode;
 }
 
-/**
- * Label + hint/error wrapper for a single form control. When the child is a
- * valid element, the control id (existing id wins, then htmlFor, then a
- * generated one) and the aria wiring for hint/error are injected into it so
- * the label association is automatic.
- */
 export function Field({ label, hint, error, required, htmlFor, hideLabel = false, className, children }: FieldProps) {
   const autoId = useId();
   const childId = isValidElement(children) ? (children as ReactElement<FieldControlProps>).props.id : undefined;

package/src/presentation/molecules/FormField.tsx

@@ -1,7 +1,3 @@
-/**
- * FormField Component (Molecule)
- * @description Label + Input combination (Responsive)
- */
 
 import { forwardRef, useId } from 'react';
 import { cn, getSpaceY } from '../../infrastructure/utils';
@@ -16,7 +12,7 @@ export interface FormFieldProps extends BaseProps {
   required?: boolean;
   id?: string;
   inputProps?: React.ComponentProps<typeof Input>;
-  fullWidth?: boolean; // Enable responsive full width
+  fullWidth?: boolean;
 }
 
 export const FormField = forwardRef<HTMLInputElement, FormFieldProps>(

package/src/presentation/molecules/InputGroup.tsx

@@ -1,7 +1,3 @@
-/**
- * InputGroup Component (Molecule)
- * @description Input with prefix/suffix elements
- */
 
 import { forwardRef, type ReactNode, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/molecules/ListItem.tsx

@@ -1,7 +1,3 @@
-/**
- * ListItem Component (Molecule)
- * @description Reusable list item with icon, content, and actions
- */
 
 import { forwardRef, type ReactNode, type MouseEvent } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/molecules/OptionTile.tsx

@@ -1,9 +1,3 @@
-/**
- * OptionTile Component (Molecule)
- * @description Graded answer tile for exercises — a native input (radio or
- * checkbox) wrapped in its label, with an optional A/B/C/D key badge and
- * reveal states (correct / wrong / missed) for post-submission feedback.
- */
 
 import { forwardRef } from 'react';
 import { Check, X } from 'lucide-react';
@@ -14,15 +8,11 @@ export type OptionTileState = 'correct' | 'wrong' | 'missed';
 
 export interface OptionTileProps extends BaseProps {
   label: React.ReactNode;
-  /** Key badge rendered before the label (A, B, C…). */
   keyBadge?: string;
-  /** Native input type — radio (single) or checkbox (multi-select). */
   type?: 'radio' | 'checkbox';
   checked?: boolean;
-  /** Reveal semantics — overrides selection styling after grading. */
   state?: OptionTileState;
   disabled?: boolean;
-  /** Group name for radio inputs. */
   name?: string;
   onChange: (checked: boolean) => void;
 }

package/src/presentation/molecules/RadioGroup.tsx

@@ -1,7 +1,3 @@
-/**
- * RadioGroup Component (Molecule)
- * @description Group of radio buttons
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/molecules/RatingStars.tsx

@@ -1,18 +1,10 @@
-/**
- * RatingStars Component (Molecule)
- * @description 0–5 rating with visual half-star precision, numeric value and
- *   optional review count
- */
 
 import { cn } from '../../infrastructure/utils';
 import type { BaseProps } from '../../domain/types';
 
 export interface RatingStarsProps extends BaseProps {
-  /** 0–5 rating; halves render as partial star fills. */
   value: number;
-  /** Optional review count rendered in parentheses. */
   count?: number;
-  /** Locale-formatted count override (e.g. 1,204). */
   formatCount?: (count: number) => string;
   size?: 'sm' | 'md';
 }

package/src/presentation/molecules/ScrollArea.tsx

@@ -1,7 +1,3 @@
-/**
- * ScrollArea Component (Molecule)
- * @description Custom scrollable area (Shadcn/ui compatible)
- */
 
 import * as React from 'react';
 import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';

package/src/presentation/molecules/SearchBox.tsx

@@ -1,7 +1,3 @@
-/**
- * SearchBox Component (Molecule)
- * @description Input with search icon
- */
 
 import { forwardRef } from 'react';
 import { X } from 'lucide-react';

package/src/presentation/molecules/Select.tsx

@@ -1,7 +1,3 @@
-/**
- * Select Component (Molecule)
- * @description Dropdown select (Shadcn/Radix UI compatible)
- */
 
 import * as React from 'react';
 import * as SelectPrimitive from '@radix-ui/react-select';

package/src/presentation/molecules/StatPill.tsx

@@ -1,8 +1,3 @@
-/**
- * StatPill Component (Molecule)
- * @description Compact inline stat — bold value over a muted label, for
- *   dense rows and summary strips where a stat card is too heavy.
- */
 
 import { forwardRef } from 'react';
 import type { ReactNode } from 'react';

package/src/presentation/molecules/TagInput.tsx

@@ -1,9 +1,3 @@
-/**
- * TagInput Component (Molecule)
- * @description Controlled free-form tag entry rendered as removable chips.
- * Type and press Enter (or comma) to commit, Backspace on an empty draft removes the last tag,
- * duplicates are ignored, and blur commits by default.
- */
 
 import { forwardRef, useState } from 'react';
 import type { InputHTMLAttributes } from 'react';
@@ -16,7 +10,6 @@ export interface TagInputProps
     BaseProps {
   tags: string[];
   onTagsChange: (tags: string[]) => void;
-  /** Commit the draft on blur (default true). */
   commitOnBlur?: boolean;
 }
 

package/src/presentation/molecules/Textarea.tsx

@@ -1,7 +1,3 @@
-/**
- * Textarea Component (Molecule)
- * @description Multi-line text input with optional label and helper text
- */
 
 import { forwardRef, useId, type ReactNode, type TextareaHTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';