@umituz/web-design-system 2.6.4 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "2.6.4",
+  "version": "2.7.0",
   "private": false,
   "description": "Web Design System - Atomic Design components (Atoms, Molecules, Organisms, Templates) for React applications",
   "main": "./src/index.ts",

package/src/domain/types/breakpoint.types.ts

@@ -0,0 +1,53 @@
+/**
+ * Responsive System Type Definitions
+ * @description Centralized breakpoint types for responsive design
+ */
+
+export type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+export type ScreenSize = Breakpoint;
+
+export interface BreakpointValue {
+  min: number;
+  max?: number;
+}
+
+export interface ResponsiveProps {
+  xs?: boolean;
+  sm?: boolean;
+  md?: boolean;
+  lg?: boolean;
+  xl?: boolean;
+  '2xl'?: boolean;
+}
+
+export interface ShowProps {
+  above?: Breakpoint;  // Show on larger screens (min-width)
+  below?: Breakpoint;  // Show on smaller screens (max-width)
+  at?: Breakpoint;     // Show only at this breakpoint
+}
+
+export interface HideProps {
+  above?: Breakpoint;  // Hide on larger screens
+  below?: Breakpoint;  // Hide on smaller screens
+  at?: Breakpoint;     // Hide only at this breakpoint
+}
+
+export interface BreakpointState {
+  currentBreakpoint: Breakpoint;
+  isXs: boolean;
+  isSm: boolean;
+  isMd: boolean;
+  isLg: boolean;
+  isXl: boolean;
+  is2Xl: boolean;
+  isMobile: boolean;    // xs, sm
+  isTablet: boolean;    // md, lg
+  isDesktop: boolean;   // xl, 2xl
+}
+
+export interface UseBreakpointReturn extends BreakpointState {
+  matches: (breakpoint: Breakpoint | Breakpoint[]) => boolean;
+  isGreaterThan: (breakpoint: Breakpoint) => boolean;
+  isLessThan: (breakpoint: Breakpoint) => boolean;
+}

package/src/domain/types/index.ts

@@ -12,3 +12,14 @@ export type {
   ChildrenProps,
   PolymorphicProps,
 } from './component.types';
+
+export type {
+  Breakpoint,
+  ScreenSize,
+  BreakpointValue,
+  ResponsiveProps,
+  ShowProps,
+  HideProps,
+  BreakpointState,
+  UseBreakpointReturn,
+} from './breakpoint.types';

package/src/infrastructure/constants/breakpoint.constants.ts

@@ -0,0 +1,72 @@
+/**
+ * Responsive System Constants
+ * @description Centralized breakpoint values matching Tailwind CSS defaults
+ */
+
+import type { Breakpoint, BreakpointValue } from '../../domain/types/breakpoint.types';
+
+/**
+ * Breakpoint values matching Tailwind CSS default breakpoints
+ * https://tailwindcss.com/docs/screens
+ */
+export const BREAKPOINTS: Record<Breakpoint, BreakpointValue> = {
+  xs: { min: 0 },
+  sm: { min: 640 },
+  md: { min: 768 },
+  lg: { min: 1024 },
+  xl: { min: 1280 },
+  '2xl': { min: 1536 },
+};
+
+/**
+ * Create a media query string for a given breakpoint
+ * @param breakpoint - The breakpoint to create a query for
+ * @returns CSS media query string (e.g., "(min-width: 640px)")
+ */
+export const createMediaQuery = (breakpoint: Breakpoint): string => {
+  const bp = BREAKPOINTS[breakpoint];
+  if (bp.max) {
+    return `(min-width: ${bp.min}px) and (max-width: ${bp.max}px)`;
+  }
+  return `(min-width: ${bp.min}px)`;
+};
+
+/**
+ * Create a max-width media query
+ * @param breakpoint - The breakpoint to create a max query for
+ * @returns CSS media query string (e.g., "(max-width: 639px)")
+ */
+export const createMaxMediaQuery = (breakpoint: Breakpoint): string => {
+  const bp = BREAKPOINTS[breakpoint];
+  const maxValue = bp.min - 1;
+  return `(max-width: ${maxValue}px)`;
+};
+
+/**
+ * Breakpoint order for comparison operations
+ */
+export const BREAKPOINT_ORDER: Breakpoint[] = ['xs', 'sm', 'md', 'lg', 'xl', '2xl'];
+
+/**
+ * Compare two breakpoints
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+export const compareBreakpoints = (a: Breakpoint, b: Breakpoint): number => {
+  const indexA = BREAKPOINT_ORDER.indexOf(a);
+  const indexB = BREAKPOINT_ORDER.indexOf(b);
+  return indexA - indexB;
+};
+
+/**
+ * Check if breakpoint A is greater than breakpoint B
+ */
+export const isBreakpointGreaterThan = (a: Breakpoint, b: Breakpoint): boolean => {
+  return compareBreakpoints(a, b) > 0;
+};
+
+/**
+ * Check if breakpoint A is less than breakpoint B
+ */
+export const isBreakpointLessThan = (a: Breakpoint, b: Breakpoint): boolean => {
+  return compareBreakpoints(a, b) < 0;
+};

package/src/infrastructure/constants/index.ts

@@ -11,3 +11,13 @@ export {
   SIZE_MAP,
   COLOR_MAP,
 } from './component.constants';
+
+export {
+  BREAKPOINTS,
+  createMediaQuery,
+  createMaxMediaQuery,
+  BREAKPOINT_ORDER,
+  compareBreakpoints,
+  isBreakpointGreaterThan,
+  isBreakpointLessThan,
+} from './breakpoint.constants';

package/src/presentation/atoms/Hide.tsx

@@ -0,0 +1,58 @@
+/**
+ * Hide Component (Atom)
+ * @description Conditionally hide content based on screen breakpoint
+ */
+
+import { useBreakpoint } from '../hooks/useMediaQuery';
+import type { Breakpoint, HideProps } from '../../domain/types/breakpoint.types';
+import type { BaseProps } from '../../domain/types';
+
+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) {
+    shouldHide = shouldHide || isGreaterThan(above);
+  }
+
+  if (below) {
+    shouldHide = shouldHide || isLessThan(below);
+  }
+
+  if (at) {
+    shouldHide = shouldHide || matches(at);
+  }
+
+  if (shouldHide) {
+    return null;
+  }
+
+  return <div className={className || ''}>{children}</div>;
+};
+
+Hide.displayName = 'Hide';

package/src/presentation/atoms/Show.tsx

@@ -0,0 +1,58 @@
+/**
+ * Show Component (Atom)
+ * @description Conditionally render content based on screen breakpoint
+ */
+
+import { useBreakpoint } from '../hooks/useMediaQuery';
+import type { Breakpoint, ShowProps } from '../../domain/types/breakpoint.types';
+import type { BaseProps } from '../../domain/types';
+
+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) {
+    shouldShow = shouldShow && isGreaterThan(above);
+  }
+
+  if (below) {
+    shouldShow = shouldShow && isLessThan(below);
+  }
+
+  if (at) {
+    shouldShow = shouldShow && matches(at);
+  }
+
+  if (!shouldShow) {
+    return null;
+  }
+
+  return <div className={className || ''}>{children}</div>;
+};
+
+Show.displayName = 'Show';

package/src/presentation/atoms/index.ts

@@ -57,3 +57,9 @@ export type { SwitchProps } from './Switch';
 export { Separator } from './Separator';
 
 export { Toggle, toggleVariants } from './Toggle';
+
+export { Show } from './Show';
+export type { ShowComponentProps } from './Show';
+
+export { Hide } from './Hide';
+export type { HideComponentProps } from './Hide';

package/src/presentation/hooks/index.ts

@@ -8,7 +8,7 @@ export { useTheme } from './useTheme';
 export type { Theme, UseThemeReturn } from './useTheme';
 
 export { useMediaQuery, useBreakpoint } from './useMediaQuery';
-export type { Breakpoint } from './useMediaQuery';
+export type { Breakpoint, UseBreakpointReturn } from '../../domain/types/breakpoint.types';
 
 export { useLocalStorage } from './useLocalStorage';
 

package/src/presentation/hooks/useMediaQuery.ts

@@ -1,28 +1,39 @@
 /**
- * useMediaQuery Hook
- * @description Responsive breakpoint detection
+ * useMediaQuery & useBreakpoint Hooks
+ * @description Enhanced responsive breakpoint detection with helper functions
  */
 
-import { useEffect, useState } from 'react';
-
-export type Breakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
-
-const breakpointValues: Record<Breakpoint, number> = {
-  sm: 640,
-  md: 768,
-  lg: 1024,
-  xl: 1280,
-  '2xl': 1536,
-};
+import { useEffect, useState, useCallback } from 'react';
+import type {
+  Breakpoint,
+  UseBreakpointReturn,
+} from '../../domain/types/breakpoint.types';
+import {
+  BREAKPOINTS,
+  createMediaQuery,
+  isBreakpointGreaterThan,
+  isBreakpointLessThan,
+} from '../../infrastructure/constants/breakpoint.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 [matches, setMatches] = useState(false);
 
   useEffect(() => {
-    const media = window.matchMedia(`(min-width: ${breakpointValues[breakpoint]}px)`);
+    const query = createMediaQuery(breakpoint);
+    const media = window.matchMedia(query);
     setMatches(media.matches);
 
-    const listener = () => setMatches(media.matches);
+    const listener = (e: MediaQueryListEvent) => setMatches(e.matches);
     media.addEventListener('change', listener);
     return () => media.removeEventListener('change', listener);
   }, [breakpoint]);
@@ -30,17 +41,118 @@ export function useMediaQuery(breakpoint: Breakpoint): boolean {
   return matches;
 }
 
-export function useBreakpoint(): Breakpoint | null {
-  const isSm = useMediaQuery('sm');
-  const isMd = useMediaQuery('md');
-  const isLg = useMediaQuery('lg');
-  const isXl = useMediaQuery('xl');
-  const is2xl = useMediaQuery('2xl');
-
-  if (is2xl) return '2xl';
-  if (isXl) return 'xl';
-  if (isLg) return 'lg';
-  if (isMd) return 'md';
-  if (isSm) return 'sm';
-  return null;
+/**
+ * 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 {
+  const [currentBreakpoint, setCurrentBreakpoint] = useState<Breakpoint>(() => {
+    // Initialize with current window size
+    if (typeof window === 'undefined') return 'lg';
+
+    const width = window.innerWidth;
+    for (const [bp, value] of Object.entries(BREAKPOINTS).reverse()) {
+      if (width >= value.min) return bp as Breakpoint;
+    }
+    return 'xs';
+  });
+
+  useEffect(() => {
+    // More efficient: track window resize with debounce
+    const updateBreakpoint = () => {
+      const width = window.innerWidth;
+      const sortedBreakpoints = Object.entries(BREAKPOINTS).sort(
+        ([, a], [, b]) => b.min - a.min
+      );
+
+      for (const [bp, value] of sortedBreakpoints) {
+        if (width >= value.min) {
+          setCurrentBreakpoint(bp as Breakpoint);
+          break;
+        }
+      }
+    };
+
+    // Initial check
+    updateBreakpoint();
+
+    // Debounced resize listener
+    let resizeTimer: ReturnType<typeof setTimeout>;
+    const handleResize = () => {
+      clearTimeout(resizeTimer);
+      resizeTimer = setTimeout(updateBreakpoint, 100);
+    };
+
+    window.addEventListener('resize', handleResize);
+
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      clearTimeout(resizeTimer);
+    };
+  }, []);
+
+  // Helper functions
+  const matches = useCallback(
+    (breakpoint: Breakpoint | Breakpoint[]): boolean => {
+      if (Array.isArray(breakpoint)) {
+        return breakpoint.includes(currentBreakpoint);
+      }
+      return currentBreakpoint === breakpoint;
+    },
+    [currentBreakpoint]
+  );
+
+  const isGreaterThan = useCallback(
+    (breakpoint: Breakpoint): boolean => {
+      return isBreakpointGreaterThan(currentBreakpoint, breakpoint);
+    },
+    [currentBreakpoint]
+  );
+
+  const isLessThan = useCallback(
+    (breakpoint: Breakpoint): boolean => {
+      return isBreakpointLessThan(currentBreakpoint, breakpoint);
+    },
+    [currentBreakpoint]
+  );
+
+  // Computed values
+  const isXs = currentBreakpoint === 'xs';
+  const isSm = currentBreakpoint === 'sm';
+  const isMd = currentBreakpoint === 'md';
+  const isLg = currentBreakpoint === 'lg';
+  const isXl = currentBreakpoint === 'xl';
+  const is2Xl = currentBreakpoint === '2xl';
+
+  const isMobile = isXs || isSm;
+  const isTablet = isMd || isLg;
+  const isDesktop = isXl || is2Xl;
+
+  return {
+    currentBreakpoint,
+    isXs,
+    isSm,
+    isMd,
+    isLg,
+    isXl,
+    is2Xl,
+    isMobile,
+    isTablet,
+    isDesktop,
+    matches,
+    isGreaterThan,
+    isLessThan,
+  };
 }

package/src/presentation/templates/ResponsiveContainer.tsx

@@ -98,7 +98,7 @@ export const ResponsiveContainer = forwardRef<
     },
     ref
   ) => {
-    const breakpoint = useBreakpoint();
+    const { currentBreakpoint: breakpoint } = useBreakpoint();
 
     // Determine current max width based on breakpoint
     const getCurrentMaxWidth = (): string => {