@papernote/ui 1.3.1 → 1.6.0

package/src/hooks/useResponsive.ts

@@ -0,0 +1,360 @@
+import { useState, useEffect, useCallback } from 'react';
+
+/**
+ * Tailwind breakpoint values in pixels
+ */
+export const BREAKPOINTS = {
+  xs: 0,
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  '2xl': 1536,
+} as const;
+
+export type Breakpoint = keyof typeof BREAKPOINTS;
+
+/**
+ * Viewport size state
+ */
+export interface ViewportSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Orientation type
+ */
+export type Orientation = 'portrait' | 'landscape';
+
+/**
+ * SSR-safe check for window availability
+ */
+const isBrowser = typeof window !== 'undefined';
+
+/**
+ * Get initial viewport size (SSR-safe)
+ */
+const getInitialViewportSize = (): ViewportSize => {
+  if (!isBrowser) {
+    return { width: 1024, height: 768 }; // Default to desktop for SSR
+  }
+  return {
+    width: window.innerWidth,
+    height: window.innerHeight,
+  };
+};
+
+/**
+ * useViewportSize - Returns current viewport dimensions
+ * 
+ * Updates on window resize with debouncing for performance.
+ * SSR-safe with sensible defaults.
+ * 
+ * @example
+ * const { width, height } = useViewportSize();
+ * console.log(`Viewport: ${width}x${height}`);
+ */
+export function useViewportSize(): ViewportSize {
+  const [size, setSize] = useState<ViewportSize>(getInitialViewportSize);
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    let timeoutId: ReturnType<typeof setTimeout>;
+
+    const handleResize = () => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => {
+        setSize({
+          width: window.innerWidth,
+          height: window.innerHeight,
+        });
+      }, 100); // Debounce 100ms
+    };
+
+    window.addEventListener('resize', handleResize);
+    
+    // Set initial size on mount (in case SSR default differs)
+    handleResize();
+
+    return () => {
+      clearTimeout(timeoutId);
+      window.removeEventListener('resize', handleResize);
+    };
+  }, []);
+
+  return size;
+}
+
+/**
+ * useBreakpoint - Returns the current Tailwind breakpoint
+ * 
+ * Automatically updates when viewport crosses breakpoint thresholds.
+ * 
+ * @example
+ * const breakpoint = useBreakpoint();
+ * // Returns: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+ */
+export function useBreakpoint(): Breakpoint {
+  const { width } = useViewportSize();
+
+  if (width >= BREAKPOINTS['2xl']) return '2xl';
+  if (width >= BREAKPOINTS.xl) return 'xl';
+  if (width >= BREAKPOINTS.lg) return 'lg';
+  if (width >= BREAKPOINTS.md) return 'md';
+  if (width >= BREAKPOINTS.sm) return 'sm';
+  return 'xs';
+}
+
+/**
+ * useMediaQuery - React hook for CSS media queries
+ * 
+ * SSR-safe implementation that returns false during SSR and
+ * updates reactively when media query match state changes.
+ * 
+ * @param query - CSS media query string (e.g., '(max-width: 768px)')
+ * @returns boolean indicating if the media query matches
+ * 
+ * @example
+ * const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
+ * const isReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+ * const isPortrait = useMediaQuery('(orientation: portrait)');
+ */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(() => {
+    if (!isBrowser) return false;
+    return window.matchMedia(query).matches;
+  });
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    const media = window.matchMedia(query);
+    
+    if (media.matches !== matches) {
+      setMatches(media.matches);
+    }
+
+    const listener = (event: MediaQueryListEvent) => {
+      setMatches(event.matches);
+    };
+
+    media.addEventListener('change', listener);
+    return () => media.removeEventListener('change', listener);
+  }, [query, matches]);
+
+  return matches;
+}
+
+/**
+ * useIsMobile - Returns true when viewport is mobile-sized (< 768px)
+ * 
+ * @example
+ * const isMobile = useIsMobile();
+ * return isMobile ? <MobileNav /> : <DesktopNav />;
+ */
+export function useIsMobile(): boolean {
+  return useMediaQuery(`(max-width: ${BREAKPOINTS.md - 1}px)`);
+}
+
+/**
+ * useIsTablet - Returns true when viewport is tablet-sized (768px - 1023px)
+ * 
+ * @example
+ * const isTablet = useIsTablet();
+ */
+export function useIsTablet(): boolean {
+  return useMediaQuery(`(min-width: ${BREAKPOINTS.md}px) and (max-width: ${BREAKPOINTS.lg - 1}px)`);
+}
+
+/**
+ * useIsDesktop - Returns true when viewport is desktop-sized (>= 1024px)
+ * 
+ * @example
+ * const isDesktop = useIsDesktop();
+ */
+export function useIsDesktop(): boolean {
+  return useMediaQuery(`(min-width: ${BREAKPOINTS.lg}px)`);
+}
+
+/**
+ * useIsTouchDevice - Detects if the device supports touch input
+ * 
+ * Uses multiple detection methods for reliability:
+ * - Touch event support
+ * - Pointer coarse media query
+ * - Max touch points
+ * 
+ * @example
+ * const isTouchDevice = useIsTouchDevice();
+ * // Show swipe hints on touch devices
+ */
+export function useIsTouchDevice(): boolean {
+  const [isTouch, setIsTouch] = useState(() => {
+    if (!isBrowser) return false;
+    return (
+      'ontouchstart' in window ||
+      navigator.maxTouchPoints > 0 ||
+      window.matchMedia('(pointer: coarse)').matches
+    );
+  });
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    // Re-check on mount for accuracy
+    const touchSupported =
+      'ontouchstart' in window ||
+      navigator.maxTouchPoints > 0 ||
+      window.matchMedia('(pointer: coarse)').matches;
+
+    setIsTouch(touchSupported);
+  }, []);
+
+  return isTouch;
+}
+
+/**
+ * useOrientation - Returns current screen orientation
+ * 
+ * @returns 'portrait' | 'landscape'
+ * 
+ * @example
+ * const orientation = useOrientation();
+ * // Adjust layout based on orientation
+ */
+export function useOrientation(): Orientation {
+  const { width, height } = useViewportSize();
+  return height > width ? 'portrait' : 'landscape';
+}
+
+/**
+ * useBreakpointValue - Returns different values based on breakpoint
+ * 
+ * Mobile-first: Returns the value for the current breakpoint or the
+ * closest smaller breakpoint that has a value defined.
+ * 
+ * @param values - Object mapping breakpoints to values
+ * @param defaultValue - Fallback value if no breakpoint matches
+ * 
+ * @example
+ * const columns = useBreakpointValue({ xs: 1, sm: 2, lg: 4 }, 1);
+ * // Returns 1 on xs, 2 on sm/md, 4 on lg/xl/2xl
+ * 
+ * const padding = useBreakpointValue({ xs: 'p-2', md: 'p-4', xl: 'p-8' });
+ */
+export function useBreakpointValue<T>(
+  values: Partial<Record<Breakpoint, T>>,
+  defaultValue?: T
+): T | undefined {
+  const breakpoint = useBreakpoint();
+  
+  // Breakpoints in order from largest to smallest
+  const breakpointOrder: Breakpoint[] = ['2xl', 'xl', 'lg', 'md', 'sm', 'xs'];
+  
+  // Find the current breakpoint index
+  const currentIndex = breakpointOrder.indexOf(breakpoint);
+  
+  // Look for value at current breakpoint or smaller (mobile-first)
+  for (let i = currentIndex; i < breakpointOrder.length; i++) {
+    const bp = breakpointOrder[i];
+    if (bp in values && values[bp] !== undefined) {
+      return values[bp];
+    }
+  }
+  
+  return defaultValue;
+}
+
+/**
+ * useResponsiveCallback - Returns a memoized callback that receives responsive info
+ * 
+ * Useful for callbacks that need to behave differently based on viewport.
+ * 
+ * @example
+ * const handleClick = useResponsiveCallback((isMobile) => {
+ *   if (isMobile) {
+ *     openBottomSheet();
+ *   } else {
+ *     openModal();
+ *   }
+ * });
+ */
+export function useResponsiveCallback<T extends (...args: any[]) => any>(
+  callback: (isMobile: boolean, isTablet: boolean, isDesktop: boolean) => T
+): T {
+  const isMobile = useIsMobile();
+  const isTablet = useIsTablet();
+  const isDesktop = useIsDesktop();
+
+  return useCallback(
+    (...args: Parameters<T>) => callback(isMobile, isTablet, isDesktop)(...args),
+    [callback, isMobile, isTablet, isDesktop]
+  ) as T;
+}
+
+/**
+ * useSafeAreaInsets - Returns safe area insets for notched devices
+ * 
+ * Uses CSS environment variables (env(safe-area-inset-*)) to get
+ * safe area dimensions for devices with notches or home indicators.
+ * 
+ * @example
+ * const { top, bottom } = useSafeAreaInsets();
+ * // Add padding-bottom for home indicator
+ */
+export function useSafeAreaInsets(): {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+} {
+  const [insets, setInsets] = useState({
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0,
+  });
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    // Create a temporary element to read CSS env() values
+    const el = document.createElement('div');
+    el.style.position = 'fixed';
+    el.style.top = 'env(safe-area-inset-top, 0px)';
+    el.style.right = 'env(safe-area-inset-right, 0px)';
+    el.style.bottom = 'env(safe-area-inset-bottom, 0px)';
+    el.style.left = 'env(safe-area-inset-left, 0px)';
+    el.style.visibility = 'hidden';
+    el.style.pointerEvents = 'none';
+    document.body.appendChild(el);
+
+    const computed = getComputedStyle(el);
+    setInsets({
+      top: parseInt(computed.top, 10) || 0,
+      right: parseInt(computed.right, 10) || 0,
+      bottom: parseInt(computed.bottom, 10) || 0,
+      left: parseInt(computed.left, 10) || 0,
+    });
+
+    document.body.removeChild(el);
+  }, []);
+
+  return insets;
+}
+
+/**
+ * usePrefersMobile - Checks if user prefers reduced data/animations (mobile-friendly)
+ * 
+ * Combines multiple preferences that might indicate mobile/low-power usage.
+ */
+export function usePrefersMobile(): boolean {
+  const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+  const prefersReducedData = useMediaQuery('(prefers-reduced-data: reduce)');
+  const isTouchDevice = useIsTouchDevice();
+  const isMobile = useIsMobile();
+
+  return isMobile || isTouchDevice || prefersReducedMotion || prefersReducedData;
+}

package/src/types/index.ts

@@ -2,6 +2,8 @@
  * Core types for notebook-ui library
  */
 
+import type { QueryTransparencyInfo } from '../components/QueryTransparency';
+
 /**
  * Base interface for all data items that can be displayed in tables
  */
@@ -22,6 +24,8 @@ export interface PaginationResponse<T = BaseDataItem> {
   // Query transparency fields (optional)
   executedQuery?: string;
   executionTimeMs?: number;
+  // Full query transparency info for QueryTransparency component
+  queryInfo?: QueryTransparencyInfo;
 }
 
 /**

package/tailwind.config.js

@@ -175,6 +175,21 @@ export default {
         '33': '8.25rem',
         '34': '8.5rem',
         '35': '8.75rem',
+        // Touch target sizes (Apple HIG / Material Design)
+        'touch-sm': '2.25rem',   // 36px - minimum for secondary actions
+        'touch': '2.75rem',      // 44px - standard touch target (Apple HIG)
+        'touch-lg': '3rem',      // 48px - large touch target (Material Design)
+      },
+      // Minimum sizes for touch targets
+      minWidth: {
+        'touch-sm': '2.25rem',
+        'touch': '2.75rem',
+        'touch-lg': '3rem',
+      },
+      minHeight: {
+        'touch-sm': '2.25rem',
+        'touch': '2.75rem',
+        'touch-lg': '3rem',
       },
       borderRadius: {
         '4xl': '2rem',
@@ -196,11 +211,19 @@ export default {
         'fade-in-up': 'fadeInUp 0.5s ease-out',
         'slide-in': 'slideIn 0.3s ease-out',
         'slide-in-right': 'slideInRight 0.3s ease-out',
+        'slide-in-left': 'slideInLeft 0.3s ease-out',
+        'slide-in-bottom': 'slideInBottom 0.3s ease-out',
+        'slide-in-top': 'slideInTop 0.3s ease-out',
+        'slide-out-right': 'slideOutRight 0.3s ease-in',
+        'slide-out-left': 'slideOutLeft 0.3s ease-in',
+        'slide-out-bottom': 'slideOutBottom 0.3s ease-in',
+        'slide-out-top': 'slideOutTop 0.3s ease-in',
         'bounce-subtle': 'bounceSubtle 2s infinite',
         'pulse-slow': 'pulse 3s cubic-bezier(0.4, 0, 0.6, 1) infinite',
         'shimmer': 'shimmer 2s linear infinite',
         'float': 'float 6s ease-in-out infinite',
         'scale-in': 'scaleIn 0.2s ease-out',
+        'scale-out': 'scaleOut 0.2s ease-in',
       },
       keyframes: {
         fadeIn: {
@@ -216,9 +239,37 @@ export default {
           '100%': { transform: 'translateX(0)', opacity: '1' },
         },
         slideInRight: {
-          '0%': { transform: 'translateX(10px)', opacity: '0' },
+          '0%': { transform: 'translateX(100%)', opacity: '0' },
+          '100%': { transform: 'translateX(0)', opacity: '1' },
+        },
+        slideInLeft: {
+          '0%': { transform: 'translateX(-100%)', opacity: '0' },
           '100%': { transform: 'translateX(0)', opacity: '1' },
         },
+        slideInBottom: {
+          '0%': { transform: 'translateY(100%)', opacity: '0' },
+          '100%': { transform: 'translateY(0)', opacity: '1' },
+        },
+        slideInTop: {
+          '0%': { transform: 'translateY(-100%)', opacity: '0' },
+          '100%': { transform: 'translateY(0)', opacity: '1' },
+        },
+        slideOutRight: {
+          '0%': { transform: 'translateX(0)', opacity: '1' },
+          '100%': { transform: 'translateX(100%)', opacity: '0' },
+        },
+        slideOutLeft: {
+          '0%': { transform: 'translateX(0)', opacity: '1' },
+          '100%': { transform: 'translateX(-100%)', opacity: '0' },
+        },
+        slideOutBottom: {
+          '0%': { transform: 'translateY(0)', opacity: '1' },
+          '100%': { transform: 'translateY(100%)', opacity: '0' },
+        },
+        slideOutTop: {
+          '0%': { transform: 'translateY(0)', opacity: '1' },
+          '100%': { transform: 'translateY(-100%)', opacity: '0' },
+        },
         bounceSubtle: {
           '0%, 100%': { transform: 'translateY(0)' },
           '50%': { transform: 'translateY(-2px)' },
@@ -235,6 +286,10 @@ export default {
           '0%': { transform: 'scale(0.9)', opacity: '0' },
           '100%': { transform: 'scale(1)', opacity: '1' },
         },
+        scaleOut: {
+          '0%': { transform: 'scale(1)', opacity: '1' },
+          '100%': { transform: 'scale(0.9)', opacity: '0' },
+        },
       },
       backdropBlur: {
         'xs': '2px',