@hunterchen/canvas 0.1.0

package/src/contexts/CanvasContext.tsx

@@ -0,0 +1,54 @@
+import React, { createContext, useContext, type ReactNode } from "react";
+import { type MotionValue } from "framer-motion";
+import { CanvasSection } from "../types";
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface CanvasContextState {
+  x: MotionValue<number>;
+  y: MotionValue<number>;
+  scale: MotionValue<number>;
+  isResetting: boolean;
+  maxZIndex: number;
+  setMaxZIndex: (zIndex: number) => void;
+  animationStage: number;
+  nextTargetSection: CanvasSection | null; // predictive pre-render target
+  setNextTargetSection: (section: CanvasSection | null) => void;
+}
+
+const defaultState = {
+  x: undefined as unknown as MotionValue<number>,
+  y: undefined as unknown as MotionValue<number>,
+  scale: 1 as unknown as MotionValue<number>,
+  isResetting: false,
+  maxZIndex: 1,
+  setMaxZIndex: () => {
+    console.log("setMaxZIndex not set");
+  },
+  animationStage: 0,
+  nextTargetSection: null,
+  setNextTargetSection: () => {
+    console.log("setNextTargetSection not set");
+  },
+} as const;
+
+export const CanvasContext = createContext<CanvasContextState>(defaultState);
+
+export const useCanvasContext = () => useContext(CanvasContext);
+
+interface CanvasProviderProps extends CanvasContextState {
+  children: ReactNode;
+}
+
+export const CanvasProvider: React.FC<CanvasProviderProps> = React.memo(
+  ({ children, ...value }) => (
+    <CanvasContext.Provider value={value as CanvasContextState}>
+      {children}
+    </CanvasContext.Provider>
+  ),
+);
+
+CanvasProvider.displayName = "CanvasProvider";

package/src/contexts/PerformanceContext.tsx

@@ -0,0 +1,81 @@
+import React, { createContext, useContext, useEffect, useState, type ReactNode } from "react";
+import useWindowDimensions from "../hooks/useWindowDimensions";
+import { isIOS, isMobile, prefersReducedMotion } from "../utils/performance";
+
+export type PerformanceMode = "high" | "medium" | "low";
+
+export interface PerformanceConfig {
+    mode: PerformanceMode;
+    isIOS: boolean;
+    isMobile: boolean;
+    prefersReducedMotion: boolean;
+    enableComplexShadows: boolean;
+}
+
+const defaultConfig: PerformanceConfig = {
+    mode: "high",
+    isIOS: false,
+    isMobile: false,
+    prefersReducedMotion: false,
+    enableComplexShadows: true,
+};
+
+const PerformanceContext = createContext<PerformanceConfig>(defaultConfig);
+
+export const usePerformance = () => useContext(PerformanceContext);
+
+// Backward compatibility alias
+export const usePerformanceMode = usePerformance;
+
+interface PerformanceProviderProps {
+    children: ReactNode;
+}
+
+/**
+ * Performance Provider - Centralized performance mode detection
+ * 
+ * Detects device capabilities and user preferences once at the top level,
+ * avoiding redundant device detection across multiple components.
+ * 
+ * Usage:
+ *   <PerformanceProvider>
+ *     <App />
+ *   </PerformanceProvider>
+ * 
+ * Then in components:
+ *   const { mode, isIOS, enableComplexShadows } = usePerformance();
+ */
+export const PerformanceProvider: React.FC<PerformanceProviderProps> = ({ children }) => {
+    const [config, setConfig] = useState<PerformanceConfig>(defaultConfig);
+    const { width } = useWindowDimensions();
+
+    useEffect(() => {
+        const isIOSDevice = isIOS();
+        const isMobileDevice = isMobile();
+        const reducedMotion = prefersReducedMotion();
+
+        let mode: PerformanceMode = "high";
+
+        // Determine performance mode based on device and screen size
+        if (isIOSDevice || reducedMotion || width < 768) {
+            mode = "low";
+        } else if (isMobileDevice || width < 1024) {
+            mode = "medium";
+        }
+
+        setConfig({
+            mode,
+            isIOS: isIOSDevice,
+            isMobile: isMobileDevice,
+            prefersReducedMotion: reducedMotion,
+            // Use simpler shadows on iOS and low-end devices for better performance
+            enableComplexShadows: mode !== "low",
+        });
+    }, [width]);
+
+    return (
+        <PerformanceContext.Provider value={config}>
+            {children}
+        </PerformanceContext.Provider>
+    );
+};

package/src/hooks/use-mobile.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+const MOBILE_BREAKPOINT = 768;
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(
+    undefined,
+  );
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener("change", onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener("change", onChange);
+  }, []);
+
+  return !!isMobile;
+}

package/src/hooks/use-toast.ts

@@ -0,0 +1,186 @@
+import * as React from "react";
+
+import type { ToastActionElement, ToastProps } from "../components/ui/toast";
+
+const TOAST_LIMIT = 1;
+const TOAST_REMOVE_DELAY = 5000;
+
+type ToasterToast = ToastProps & {
+  id: string;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  action?: ToastActionElement;
+};
+
+const actionTypes = {
+  ADD_TOAST: "ADD_TOAST",
+  UPDATE_TOAST: "UPDATE_TOAST",
+  DISMISS_TOAST: "DISMISS_TOAST",
+  REMOVE_TOAST: "REMOVE_TOAST",
+} as const;
+
+let count = 0;
+
+function genId() {
+  count = (count + 1) % Number.MAX_SAFE_INTEGER;
+  return count.toString();
+}
+
+type ActionType = typeof actionTypes;
+
+type Action =
+  | {
+      type: ActionType["ADD_TOAST"];
+      toast: ToasterToast;
+    }
+  | {
+      type: ActionType["UPDATE_TOAST"];
+      toast: Partial<ToasterToast>;
+    }
+  | {
+      type: ActionType["DISMISS_TOAST"];
+      toastId?: ToasterToast["id"];
+    }
+  | {
+      type: ActionType["REMOVE_TOAST"];
+      toastId?: ToasterToast["id"];
+    };
+
+interface State {
+  toasts: ToasterToast[];
+}
+
+const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+
+const addToRemoveQueue = (toastId: string) => {
+  if (toastTimeouts.has(toastId)) {
+    return;
+  }
+
+  const timeout = setTimeout(() => {
+    toastTimeouts.delete(toastId);
+    dispatch({
+      type: "REMOVE_TOAST",
+      toastId: toastId,
+    });
+  }, TOAST_REMOVE_DELAY);
+
+  toastTimeouts.set(toastId, timeout);
+};
+
+export const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case "ADD_TOAST":
+      return {
+        ...state,
+        toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
+      };
+
+    case "UPDATE_TOAST":
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === action.toast.id ? { ...t, ...action.toast } : t,
+        ),
+      };
+
+    case "DISMISS_TOAST": {
+      const { toastId } = action;
+
+      // ! Side effects ! - This could be extracted into a dismissToast() action,
+      // but I'll keep it here for simplicity
+      if (toastId) {
+        addToRemoveQueue(toastId);
+      } else {
+        state.toasts.forEach((toast) => {
+          addToRemoveQueue(toast.id);
+        });
+      }
+
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === toastId || toastId === undefined
+            ? {
+                ...t,
+                open: false,
+              }
+            : t,
+        ),
+      };
+    }
+    case "REMOVE_TOAST":
+      if (action.toastId === undefined) {
+        return {
+          ...state,
+          toasts: [],
+        };
+      }
+      return {
+        ...state,
+        toasts: state.toasts.filter((t) => t.id !== action.toastId),
+      };
+  }
+};
+
+const listeners: Array<(state: State) => void> = [];
+
+let memoryState: State = { toasts: [] };
+
+function dispatch(action: Action) {
+  memoryState = reducer(memoryState, action);
+  listeners.forEach((listener) => {
+    listener(memoryState);
+  });
+}
+
+type Toast = Omit<ToasterToast, "id">;
+
+export function toast({ ...props }: Toast) {
+  const id = genId();
+
+  const update = (props: ToasterToast) =>
+    dispatch({
+      type: "UPDATE_TOAST",
+      toast: { ...props, id },
+    });
+  const dismiss = () => dispatch({ type: "DISMISS_TOAST", toastId: id });
+
+  dispatch({
+    type: "ADD_TOAST",
+    toast: {
+      ...props,
+      id,
+      open: true,
+      onOpenChange: (open) => {
+        if (!open) dismiss();
+      },
+    },
+  });
+
+  return {
+    id: id,
+    dismiss,
+    update,
+  };
+}
+
+export function useToast() {
+  const [state, setState] = React.useState<State>(memoryState);
+
+  React.useEffect(() => {
+    listeners.push(setState);
+    return () => {
+      const index = listeners.indexOf(setState);
+      if (index > -1) {
+        listeners.splice(index, 1);
+      }
+    };
+  }, [state]);
+
+  return {
+    ...state,
+    toast,
+    dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
+  };
+}

package/src/hooks/usePerformanceMode.ts

@@ -0,0 +1,5 @@
+/**
+ * @deprecated Import from ~/contexts/PerformanceContext instead
+ * This file is kept for backward compatibility
+ */
+export { usePerformance, usePerformanceMode, type PerformanceMode, type PerformanceConfig } from "../contexts/PerformanceContext";

package/src/hooks/useWindowDimensions.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react";
+
+type WindowDimentions = {
+  width: number;
+  height: number;
+};
+
+const useWindowDimensions = (): WindowDimentions => {
+  const [windowDimensions, setWindowDimensions] = useState<WindowDimentions>({
+    width: typeof window !== "undefined" ? window.innerWidth : 1200,
+    height: typeof window !== "undefined" ? window.innerHeight : 800,
+  });
+
+  useEffect(() => {
+    function handleResize(): void {
+      setWindowDimensions({
+        width: window.innerWidth,
+        height: window.innerHeight,
+      });
+    }
+
+    // Set initial dimensions on mount
+    handleResize();
+
+    window.addEventListener("resize", handleResize);
+    return (): void => window.removeEventListener("resize", handleResize);
+  }, []); // Empty array ensures that effect is only run on mount
+
+  return windowDimensions;
+};
+
+export default useWindowDimensions;

package/src/index.ts

@@ -0,0 +1,36 @@
+// Components
+export { default as Canvas, gradientBgImage } from './components/canvas/canvas';
+export { CanvasComponent } from './components/canvas/component';
+export { Draggable, DraggableImage } from './components/canvas/draggable';
+export { CanvasWrapper, growTransition } from './components/canvas/wrapper';
+export { default as CanvasCursor } from './components/canvas/cursor';
+export { default as CanvasToolbar } from './components/canvas/toolbar';
+export { default as CanvasNavbar } from './components/canvas/navbar';
+
+// UI Components
+export { Button } from './components/ui/button';
+export { Label } from './components/ui/label';
+export { default as FolderIcon } from './components/ui/FolderIcon';
+export { Toaster } from './components/ui/toaster';
+export { Toast, ToastAction, ToastClose, ToastTitle, ToastDescription, ToastViewport } from './components/ui/toast';
+
+// Contexts
+export { CanvasContext, CanvasProvider, useCanvasContext } from './contexts/CanvasContext';
+export type { CanvasContextState } from './contexts/CanvasContext';
+export { PerformanceProvider, usePerformanceMode, usePerformance } from './contexts/PerformanceContext';
+export type { PerformanceMode, PerformanceConfig } from './contexts/PerformanceContext';
+
+// Hooks
+export { default as useWindowDimensions } from './hooks/useWindowDimensions';
+export { usePerformanceMode as usePerformanceModeLegacy } from './hooks/usePerformanceMode';
+export { useToast, toast } from './hooks/use-toast';
+
+// Utilities
+export * from './lib/canvas';
+export * from './lib/constants';
+export * from './utils/performance';
+export { copyText } from './lib/copy';
+
+// Types
+export type { SectionCoordinates } from './types';
+export { CanvasSection } from './types';

package/src/lib/canvas.ts

@@ -0,0 +1,132 @@
+import { animate, type MotionValue, type Point } from "framer-motion";
+import { useMemo } from "react";
+import {
+  CANVAS_WIDTH,
+  CANVAS_HEIGHT,
+  MAX_DIM_RATIO,
+  INTRO_ASPECT_RATIO,
+  PAN_SPRING,
+  ScreenSizeEnum,
+} from "./constants";
+
+export const canvasWidth = CANVAS_WIDTH;
+export const canvasHeight = CANVAS_HEIGHT;
+
+// Re-export ScreenSizeEnum for backward compatibility
+export { ScreenSizeEnum } from "./constants";
+
+export const useMemoPoint = (x: number, y: number): Point => {
+  return useMemo(() => ({ x, y }), [x, y]);
+};
+
+export interface MinimalPointerInput {
+  clientX: number;
+  clientY: number;
+}
+
+export const getDistance = (
+  p1: MinimalPointerInput,
+  p2: MinimalPointerInput,
+) => {
+  const dx = p1.clientX - p2.clientX;
+  const dy = p1.clientY - p2.clientY;
+  return Math.sqrt(dx ** 2 + dy ** 2);
+};
+
+export const getMidpoint = (
+  p1: MinimalPointerInput,
+  p2: MinimalPointerInput,
+): Point => {
+  return {
+    x: (p1.clientX + p2.clientX) / 2,
+    y: (p1.clientY + p2.clientY) / 2,
+  };
+};
+
+export const getScreenSizeEnum = (width: number): ScreenSizeEnum => {
+  // iphone 12 pro is 390px, iphone 14 pro max is 430px, SE 3rd gen is 375px
+  if (width < 400) return ScreenSizeEnum.SMALL_MOBILE;
+  if (width < 768) return ScreenSizeEnum.MOBILE;
+  if (width < 1440) return ScreenSizeEnum.TABLET;
+  if (width < 1920) return ScreenSizeEnum.SMALL_DESKTOP;
+  if (width < 2560) return ScreenSizeEnum.MEDIUM_DESKTOP;
+  if (width <= 3440) return ScreenSizeEnum.LARGE_DESKTOP;
+  return ScreenSizeEnum.HUGE_DESKTOP;
+};
+
+export function getSectionPanCoordinates({
+  windowDimensions,
+  coords,
+  targetZoom,
+  negative,
+}: {
+  windowDimensions: { width: number; height: number };
+  coords: { x: number; y: number; width: number; height: number };
+  targetZoom: number;
+  negative?: boolean;
+}) {
+  const { width, height } = windowDimensions;
+  // Calculate the center of the section
+  const sectionCenterX = coords.x + coords.width / 2;
+  const sectionCenterY = coords.y + coords.height / 2;
+
+  // Calculate the required pan offset to center the section in the viewport
+  const targetX = width / 2 - sectionCenterX * targetZoom;
+  const targetY = height / 2 - sectionCenterY * targetZoom;
+
+  if (negative) {
+    return {
+      x: -targetX,
+      y: -targetY,
+    };
+  }
+
+  return {
+    x: targetX,
+    y: targetY,
+  };
+}
+
+export async function panToOffsetScene(
+  offset: Point,
+  x: MotionValue<number>,
+  y: MotionValue<number>,
+  scale: MotionValue<number>,
+  newZoom?: number,
+): Promise<void> {
+  const animX = animate(x, offset.x, PAN_SPRING);
+  const animY = animate(y, offset.y, PAN_SPRING);
+  const animScale = animate(scale, newZoom ?? 1, PAN_SPRING);
+  await Promise.all([animScale, animX, animY]);
+}
+
+export const calcInitialBoxWidth = (
+  windowWidth: number,
+  windowHeight: number,
+) => {
+  // math CanvasWrapper's bounding box size and compute scale s.t. canvas fits entirely within
+  const maxWidth = windowWidth * MAX_DIM_RATIO.width;
+  const maxHeight = windowHeight * MAX_DIM_RATIO.height;
+
+  let boxWidth, boxHeight;
+
+  if (maxWidth / INTRO_ASPECT_RATIO <= maxHeight) {
+    boxWidth = maxWidth;
+    boxHeight = boxWidth / INTRO_ASPECT_RATIO;
+  } else {
+    boxHeight = maxHeight;
+    boxWidth = boxHeight * INTRO_ASPECT_RATIO;
+  }
+
+  // scale so the canvas fits inside the computed 3:2 box
+  return Math.min(boxWidth / canvasWidth, boxHeight / canvasHeight);
+};
+
+// Re-export commonly used constants for backward compatibility
+export { MAX_DIM_RATIO } from "./constants";
+export {
+  INTERACTIVE_SELECTOR,
+  ZOOM_BOUND,
+  MAX_ZOOM,
+  MIN_ZOOMS,
+} from "./constants";

package/src/lib/constants.ts

@@ -0,0 +1,153 @@
+import { type Easing } from "framer-motion";
+
+/**
+ * Canvas Library Constants
+ * All configurable constants consolidated in one place
+ */
+
+// ============================================================================
+// SCREEN SIZE BREAKPOINTS
+// ============================================================================
+
+export enum ScreenSizeEnum {
+    SMALL_MOBILE = "small-mobile",
+    MOBILE = "mobile",
+    TABLET = "tablet",
+    SMALL_DESKTOP = "small-desktop",
+    MEDIUM_DESKTOP = "medium-desktop",
+    LARGE_DESKTOP = "large-desktop",
+    HUGE_DESKTOP = "huge-desktop",
+}
+
+// ============================================================================
+// CANVAS DIMENSIONS
+// ============================================================================
+
+/** Default canvas width in pixels */
+export const CANVAS_WIDTH = 6000;
+
+/** Default canvas height in pixels */
+export const CANVAS_HEIGHT = 4000;
+
+// ============================================================================
+// INTRO ANIMATION
+// ============================================================================
+
+/** Maximum dimensions ratio for the intro box relative to viewport */
+export const MAX_DIM_RATIO = {
+    width: 0.8,
+    height: 0.5,
+} as const;
+
+/** Intro box aspect ratio (width:height) */
+export const INTRO_ASPECT_RATIO = 3 / 2;
+
+/** Grow animation transition config */
+export const GROW_TRANSITION = {
+    duration: 0.96,
+    delay: 3.14,
+    ease: [0.35, 0.1, 0.8, 1] as Easing,
+} as const;
+
+/** Blur mask animation transition config */
+export const BLUR_TRANSITION = {
+    duration: 0.85,
+    delay: 1.25,
+    ease: "easeIn" as Easing,
+} as const;
+
+/** Stage 2 pan-to-home transition config */
+export const STAGE2_TRANSITION = {
+    duration: 0.96,
+    ease: [0.37, 0.1, 0.6, 1],
+} as const;
+
+// ============================================================================
+// ZOOM & PAN
+// ============================================================================
+
+/** Maximum zoom level */
+export const MAX_ZOOM = 3;
+
+/** Minimum zoom bound multiplier to prevent zooming out past canvas edges */
+export const ZOOM_BOUND = 1.05;
+
+/** Minimum zoom levels per screen size */
+export const MIN_ZOOMS: Record<ScreenSizeEnum, number> = {
+    [ScreenSizeEnum.SMALL_MOBILE]: 0.3,
+    [ScreenSizeEnum.MOBILE]: 0.35,
+    [ScreenSizeEnum.TABLET]: 0.25,
+    [ScreenSizeEnum.SMALL_DESKTOP]: 0.15,
+    [ScreenSizeEnum.MEDIUM_DESKTOP]: 0.1,
+    [ScreenSizeEnum.LARGE_DESKTOP]: 0.1,
+    [ScreenSizeEnum.HUGE_DESKTOP]: 0.1,
+} as const;
+
+/** Pan animation spring config */
+export const PAN_SPRING = {
+    visualDuration: 0.34,
+    type: "spring",
+    stiffness: 200,
+    damping: 25,
+} as const;
+
+/** Wheel zoom sensitivity for mouse wheel */
+export const MOUSE_WHEEL_ZOOM_SENSITIVITY = 0.0015;
+
+/** Wheel zoom sensitivity for trackpad */
+export const TRACKPAD_ZOOM_SENSITIVITY = 0.015;
+
+// ============================================================================
+// INTERACTIONS
+// ============================================================================
+
+/** CSS selector for interactive elements that should not trigger pan */
+export const INTERACTIVE_SELECTOR =
+    "button,[role='button'],input,textarea,[contenteditable='true']," +
+    "[data-toolbar-button],[data-navbar-button]";
+
+// ============================================================================
+// VIEWPORT CULLING
+// ============================================================================
+
+/** Buffer zone in pixels for hysteresis visibility detection */
+export const VIEWPORT_HYSTERESIS_BUFFER = 120;
+
+/** Threshold for showing image fallback on smaller screens */
+export const IMAGE_FALLBACK_WIDTH_THRESHOLD = 2000;
+
+// ============================================================================
+// NAVBAR
+// ============================================================================
+
+/** Responsive zoom levels for navbar navigation per screen size */
+export const RESPONSIVE_ZOOM_MAP: Record<ScreenSizeEnum, number> = {
+    [ScreenSizeEnum.SMALL_MOBILE]: 0.5,
+    [ScreenSizeEnum.MOBILE]: 0.6,
+    [ScreenSizeEnum.TABLET]: 0.8,
+    [ScreenSizeEnum.SMALL_DESKTOP]: 0.9,
+    [ScreenSizeEnum.MEDIUM_DESKTOP]: 1,
+    [ScreenSizeEnum.LARGE_DESKTOP]: 1.25,
+    [ScreenSizeEnum.HUGE_DESKTOP]: 1.5,
+} as const;
+
+// ============================================================================
+// PERFORMANCE
+// ============================================================================
+
+/** Debounce duration in ms for navbar clicks based on performance mode */
+export const NAVBAR_DEBOUNCE_MS = {
+    high: 0,
+    medium: 100,
+    low: 400,
+} as const;
+
+// ============================================================================
+// TOOLBAR
+// ============================================================================
+
+/** Epsilon for position comparison to hide toolbar when at home */
+export const TOOLBAR_OPACITY_POS_EPS = 1; // px
+
+/** Epsilon for scale comparison to hide toolbar when at 1x */
+export const TOOLBAR_OPACITY_SCALE_EPS = 0.01; // scale delta