@reactberry/system 2.0.0-beta

package/src/hooks/useAnimatedText.ts

@@ -0,0 +1,32 @@
+"use client";
+
+import { animate } from "motion/react";
+import { useEffect, useState } from "react";
+
+const delimiter = ""; // or " " to split by word
+
+export function useAnimatedText(text: string) {
+  const [cursor, setCursor] = useState(0);
+  const [startingCursor, setStartingCursor] = useState(0);
+  const [prevText, setPrevText] = useState(text);
+
+  if (prevText !== text) {
+    setPrevText(text);
+    setStartingCursor(text.startsWith(prevText) ? cursor : 0);
+  }
+
+  useEffect(() => {
+    const controls = animate(startingCursor, text.split(delimiter).length, {
+      // Tweak the animation here
+      duration: 4,
+      ease: "easeOut",
+      onUpdate(latest) {
+        setCursor(Math.floor(latest));
+      },
+    });
+
+    return () => controls.stop();
+  }, [startingCursor, text]);
+
+  return text.split(delimiter).slice(0, cursor).join(delimiter);
+}

package/src/hooks/useAutosizeTextArea.ts

@@ -0,0 +1,45 @@
+import { useEffect } from "react";
+
+interface UseAutosizeTextAreaOptions {
+  minRows?: number;
+  maxRows?: number;
+}
+
+/**
+ * Hook that automatically adjusts textarea height based on content
+ * @param textareaRef - Reference to the textarea element
+ * @param value - Current value of the textarea
+ * @param minRows - Minimum number of rows (default: 1)
+ * @param maxRows - Maximum number of rows (default: 10)
+ */
+export function useAutosizeTextArea(
+  textareaRef: HTMLTextAreaElement | null,
+  value: string,
+  options: UseAutosizeTextAreaOptions = {}
+): void {
+  const { minRows = 1, maxRows = 10 } = options;
+
+  useEffect(() => {
+    if (!textareaRef) return;
+
+    // Reset height to auto to get the correct scrollHeight
+    textareaRef.style.height = "auto";
+
+    // Get the line height
+    const lineHeight = parseInt(
+      window.getComputedStyle(textareaRef).lineHeight,
+      10
+    );
+
+    // Calculate the number of rows needed
+    const scrollHeight = textareaRef.scrollHeight;
+    const currentRows = Math.ceil(scrollHeight / lineHeight);
+
+    // Constrain between min and max rows
+    const rowsToShow = Math.max(minRows, Math.min(currentRows, maxRows));
+
+    // Set the height based on rows
+    textareaRef.style.height = `${rowsToShow * lineHeight}px`;
+  }, [textareaRef, value, minRows, maxRows]);
+}
+

package/src/hooks/useBreakpoint.tsx

@@ -0,0 +1,123 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  ReactNode,
+} from "react";
+
+type Breakpoint = "_" | "xs" | "sm" | "md" | "lg" | "xl";
+
+interface BreakpointContextType {
+  breakpoint: Breakpoint;
+}
+
+const BreakpointContext = createContext<BreakpointContextType | undefined>(
+  undefined,
+);
+
+// Hardcoded order - design system breakpoints are stable
+const BREAKPOINT_ORDER: Breakpoint[] = ["_", "xs", "sm", "md", "lg", "xl"];
+const BREAKPOINT_KEYS = ["xl", "lg", "md", "sm", "xs"] as const;
+
+// Type-safe breakpoint mapping - derived from design system tokens
+const BREAKPOINT_VALUES: Record<Exclude<Breakpoint, "_">, string> = {
+  xs: "32rem",
+  sm: "48rem",
+  md: "64rem",
+  lg: "80rem",
+  xl: "96rem",
+};
+
+/**
+ * Provider to wrap your app - add to root layout
+ * Only ONE set of listeners for the entire app
+ */
+export function BreakpointProvider({ children }: { children: ReactNode }) {
+  const [breakpoint, setBreakpoint] = useState<Breakpoint>("_");
+
+  useEffect(() => {
+    const queries: Record<string, MediaQueryList> = {};
+
+    BREAKPOINT_KEYS.forEach((key) => {
+      queries[key] = window.matchMedia(
+        `(min-width: ${BREAKPOINT_VALUES[key]})`,
+      );
+    });
+
+    const updateBreakpoint = (): void => {
+      for (const key of BREAKPOINT_KEYS) {
+        if (queries[key]?.matches) {
+          setBreakpoint(key as Breakpoint);
+          return;
+        }
+      }
+      setBreakpoint("_");
+    };
+
+    updateBreakpoint();
+
+    const handleChange = (): void => updateBreakpoint();
+
+    BREAKPOINT_KEYS.forEach((key) => {
+      queries[key]?.addEventListener("change", handleChange);
+    });
+
+    return () => {
+      BREAKPOINT_KEYS.forEach((key) => {
+        queries[key]?.removeEventListener("change", handleChange);
+      });
+    };
+  }, []);
+
+  return (
+    <BreakpointContext.Provider value={{ breakpoint }}>
+      {children}
+    </BreakpointContext.Provider>
+  );
+}
+
+/**
+ * Hook to check if current width is at or above a specific breakpoint
+ * @param targetBreakpoint Breakpoint to check against
+ * @returns boolean - true if current width >= breakpoint
+ *
+ * @example
+ * const isMd = useBreakpoint("md");      // true if md and above
+ * const isDesktop = useBreakpoint("lg"); // true if lg and above
+ */
+export function useBreakpoint(targetBreakpoint: Breakpoint): boolean {
+  const context = useContext(BreakpointContext);
+
+  if (!context) {
+    throw new Error("useBreakpoint must be used within BreakpointProvider");
+  }
+
+  const currentIndex = BREAKPOINT_ORDER.indexOf(context.breakpoint);
+  const targetIndex = BREAKPOINT_ORDER.indexOf(targetBreakpoint);
+
+  return currentIndex >= targetIndex;
+}
+
+/**
+ * Hook to check if current breakpoint matches exactly a specific breakpoint
+ * @param targetBreakpoint Breakpoint to match
+ * @returns boolean - true if current breakpoint === targetBreakpoint
+ *
+ * @example
+ * const isMobileOnly = useShowOnBreakpoint("_");     // true only on mobile
+ * const isTabletOnly = useShowOnBreakpoint("sm");    // true only on tablet
+ */
+export function useShowOnBreakpoint(targetBreakpoint: Breakpoint): boolean {
+  const context = useContext(BreakpointContext);
+
+  if (!context) {
+    throw new Error(
+      "useShowOnBreakpoint must be used within BreakpointProvider",
+    );
+  }
+
+  return context.breakpoint === targetBreakpoint;
+}

package/src/hooks/useClickOutside.tsx

@@ -0,0 +1,38 @@
+import { useEffect, type RefObject } from "react";
+
+/**
+ * Call `handler` when a mouse or touch event occurs outside the given ref.
+ *
+ * Usage:
+ *   const ref = useRef<HTMLDivElement | null>(null);
+ *   useClickOutside(ref, () => setOpen(false), open);
+ */
+export function useClickOutside<T extends HTMLElement = HTMLElement>(
+	  ref: RefObject<T | null>,
+  handler: (event: MouseEvent | TouchEvent) => void,
+  enabled: boolean = true,
+): void {
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleEvent = (event: MouseEvent | TouchEvent) => {
+      const node = ref.current;
+      if (!node) return;
+
+      if (node.contains(event.target as Node)) {
+        return;
+      }
+
+      handler(event);
+    };
+
+    document.addEventListener("mousedown", handleEvent);
+    document.addEventListener("touchstart", handleEvent);
+
+    return () => {
+      document.removeEventListener("mousedown", handleEvent);
+      document.removeEventListener("touchstart", handleEvent);
+    };
+  }, [ref, handler, enabled]);
+}
+

package/src/hooks/useHover.tsx

@@ -0,0 +1,33 @@
+import {
+  useRef,
+  useState,
+  useEffect,
+  useCallback,
+  type MutableRefObject,
+} from "react";
+
+export function useHover<T extends HTMLElement = HTMLDivElement>(): [
+  MutableRefObject<T | null>,
+  boolean
+] {
+  const [hovered, setHovered] = useState(false);
+  const ref = useRef<T>(null);
+
+  const handleMouseOver = useCallback(() => setHovered(true), []);
+  const handleMouseOut = useCallback(() => setHovered(false), []);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+
+    node.addEventListener("mouseenter", handleMouseOver);
+    node.addEventListener("mouseleave", handleMouseOut);
+
+    return () => {
+      node.removeEventListener("mouseenter", handleMouseOver);
+      node.removeEventListener("mouseleave", handleMouseOut);
+    };
+  }, [handleMouseOver, handleMouseOut]);
+
+  return [ref, hovered];
+}

package/src/hooks/useHoverList.tsx

@@ -0,0 +1,17 @@
+import { useState, type MouseEventHandler } from "react";
+
+export type HoverProps = {
+  onMouseEnter: MouseEventHandler<HTMLElement>;
+  onMouseLeave: MouseEventHandler<HTMLElement>;
+};
+
+export function useHoverList() {
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
+
+  const getHoverProps = (index: number): HoverProps => ({
+    onMouseEnter: () => setHoveredIndex(index),
+    onMouseLeave: () => setHoveredIndex(null),
+  });
+
+  return { hoveredIndex, getHoverProps };
+}

package/src/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,91 @@
+import { useEffect, useCallback } from 'react';
+
+interface KeyboardShortcuts {
+  onSend?: () => void;
+  onSaveDraft?: () => void;
+  onPreview?: () => void;
+  onSchedule?: () => void;
+  onAddAttachment?: () => void;
+  onToggleMode?: () => void;
+}
+
+export function useKeyboardShortcuts({
+  onSend,
+  onSaveDraft,
+  onPreview,
+  onSchedule,
+  onAddAttachment,
+  onToggleMode
+}: KeyboardShortcuts) {
+  const handleKeyDown = useCallback((event: KeyboardEvent) => {
+    const { key, metaKey, ctrlKey, shiftKey } = event;
+    const cmdOrCtrl = metaKey || ctrlKey;
+
+    // Cmd/Ctrl + Enter: Send email
+    if (cmdOrCtrl && key === 'Enter' && onSend) {
+      event.preventDefault();
+      onSend();
+      return;
+    }
+
+    // Cmd/Ctrl + S: Save draft
+    if (cmdOrCtrl && key === 's' && onSaveDraft) {
+      event.preventDefault();
+      onSaveDraft();
+      return;
+    }
+
+    // Cmd/Ctrl + P: Preview
+    if (cmdOrCtrl && key === 'p' && onPreview) {
+      event.preventDefault();
+      onPreview();
+      return;
+    }
+
+    // Cmd/Ctrl + Shift + S: Schedule
+    if (cmdOrCtrl && shiftKey && key === 'S' && onSchedule) {
+      event.preventDefault();
+      onSchedule();
+      return;
+    }
+
+    // Cmd/Ctrl + U: Add attachment
+    if (cmdOrCtrl && key === 'u' && onAddAttachment) {
+      event.preventDefault();
+      onAddAttachment();
+      return;
+    }
+
+    // Cmd/Ctrl + M: Toggle between editor and preview mode
+    if (cmdOrCtrl && key === 'm' && onToggleMode) {
+      event.preventDefault();
+      onToggleMode();
+      return;
+    }
+
+    // Escape: Close any open dialogs (handled by parent component)
+    if (key === 'Escape') {
+      event.preventDefault();
+      // Let parent component handle this
+      return;
+    }
+  }, [onSend, onSaveDraft, onPreview, onSchedule, onAddAttachment, onToggleMode]);
+
+  useEffect(() => {
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [handleKeyDown]);
+
+  return {
+    shortcuts: {
+      send: '⌘+Enter',
+      saveDraft: '⌘+S',
+      preview: '⌘+P',
+      schedule: '⌘+⇧+S',
+      addAttachment: '⌘+U',
+      toggleMode: '⌘+M'
+    }
+  };
+}

package/src/hooks/useKeypress.ts

@@ -0,0 +1,27 @@
+import { useEffect, useCallback } from "react";
+
+/**
+ * Custom hook to handle keyboard events
+ * @param targetKey - The key to listen for (e.g., "ArrowRight", "ArrowLeft")
+ * @param callback - The function to execute when the key is pressed
+ */
+export const useKeypress = (targetKey: string, callback: () => void) => {
+  const handleKeyPress = useCallback(
+    (event: KeyboardEvent) => {
+      if (event.key === targetKey) {
+        callback();
+      }
+    },
+    [targetKey, callback]
+  );
+
+  useEffect(() => {
+    // Add event listener when component mounts
+    window.addEventListener("keydown", handleKeyPress);
+
+    // Remove event listener when component unmounts
+    return () => {
+      window.removeEventListener("keydown", handleKeyPress);
+    };
+  }, [handleKeyPress]);
+};

package/src/hooks/useOverlay.ts

@@ -0,0 +1,32 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { pushThemeColor, popThemeColor } from "@/design-system/utils/overlayTheme";
+import { useStandaloneMode } from "@/design-system/hooks/useStandaloneMode";
+
+/**
+ * Shared behavioral hook for overlay components (Modal, Drawer, etc.).
+ *
+ * Handles three concerns:
+ * 1. SSR-safe mounting (portal rendering requires `document.body`)
+ * 2. Ref-counted theme-color tinting + body scroll lock
+ * 3. PWA standalone-mode detection for safe-area padding
+ *
+ * @param isOpen Whether the overlay is currently visible. Defaults to `true`
+ *   (Modal is always open when mounted; Drawer passes `isSidebarOpen`).
+ */
+export function useOverlay(isOpen: boolean = true) {
+  const [mounted, setMounted] = useState(false);
+  const isStandalone = useStandaloneMode();
+
+  useEffect(() => setMounted(true), []);
+
+  useEffect(() => {
+    if (isOpen) {
+      pushThemeColor();
+      return () => popThemeColor();
+    }
+  }, [isOpen]);
+
+  return { mounted, isStandalone };
+}

package/src/hooks/useReducedMotion.ts

@@ -0,0 +1,25 @@
+"use client";
+
+import { useState, useEffect } from "react";
+
+/**
+ * Hook to detect user's reduced motion preference.
+ * Returns true if the user prefers reduced motion.
+ */
+export function useReducedMotion(): boolean {
+  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+    setPrefersReducedMotion(mediaQuery.matches);
+
+    const handler = (event: MediaQueryListEvent) => {
+      setPrefersReducedMotion(event.matches);
+    };
+
+    mediaQuery.addEventListener("change", handler);
+    return () => mediaQuery.removeEventListener("change", handler);
+  }, []);
+
+  return prefersReducedMotion;
+}

package/src/hooks/useStandaloneMode.ts

@@ -0,0 +1,35 @@
+"use client";
+
+import { useState, useEffect } from "react";
+
+/**
+ * Detects whether the app is running in standalone (PWA) mode.
+ *
+ * Checks two signals:
+ * 1. The standard `(display-mode: standalone)` media query (Chrome, Edge, Firefox).
+ * 2. The iOS-specific `navigator.standalone` boolean (Safari on iOS).
+ *
+ * Listens for media-query changes so the value updates dynamically,
+ * though in practice display-mode rarely changes during a session.
+ */
+export function useStandaloneMode(): boolean {
+  const [isStandalone, setIsStandalone] = useState(false);
+
+  useEffect(() => {
+    const iosStandalone =
+      "standalone" in navigator && (navigator as any).standalone === true;
+
+    const displayModeQuery = window.matchMedia("(display-mode: standalone)");
+
+    const update = () => {
+      setIsStandalone(iosStandalone || displayModeQuery.matches);
+    };
+
+    update();
+
+    displayModeQuery.addEventListener("change", update);
+    return () => displayModeQuery.removeEventListener("change", update);
+  }, []);
+
+  return isStandalone;
+}

package/src/hooks/useTouchDevice.ts

@@ -0,0 +1,34 @@
+"use client";
+
+import { useState, useEffect } from "react";
+
+/**
+ * Detects whether the current device uses touch as its primary input.
+ *
+ * Combines hardware capability (maxTouchPoints) with the CSS pointer: coarse
+ * media query so that hybrid devices (e.g. Surface Pro with trackpad) return
+ * false when a fine pointer is the primary input.
+ *
+ * Listens for media-query changes so the value updates if the user detaches
+ * a keyboard / mouse mid-session.
+ */
+export function useTouchDevice(): boolean {
+  const [isTouchDevice, setIsTouchDevice] = useState(false);
+
+  useEffect(() => {
+    const hasTouchCapability =
+      "ontouchstart" in window || navigator.maxTouchPoints > 0;
+    const coarsePointerQuery = window.matchMedia("(pointer: coarse)");
+
+    const update = () => {
+      setIsTouchDevice(hasTouchCapability && coarsePointerQuery.matches);
+    };
+
+    update();
+
+    coarsePointerQuery.addEventListener("change", update);
+    return () => coarsePointerQuery.removeEventListener("change", update);
+  }, []);
+
+  return isTouchDevice;
+}