@hunterchen/canvas 0.5.0 → 0.7.0

package/src/components/canvas/toolbar.tsx

@@ -1,19 +1,56 @@
 import { type Point, useTransform, motion } from "framer-motion";
-import { useEffect, useState } from "react";
+import { useEffect, useState, useMemo } from "react";
 import { useCanvasContext } from "../../contexts/CanvasContext";
 import {
   TOOLBAR_OPACITY_POS_EPS,
   TOOLBAR_OPACITY_SCALE_EPS,
 } from "../../lib/constants";
+import { cn } from "../../lib/utils";
+import type { ToolbarConfig, ToolbarPosition } from "../../types";
 
 type ToolbarProps = {
   homeCoordinates?: Point;
+  config?: ToolbarConfig;
 };
 
-const Toolbar = ({ homeCoordinates = { x: 0, y: 0 } }: ToolbarProps) => {
+const positionStyles: Record<ToolbarPosition, string> = {
+  "top-left": "left-4 top-6 sm:top-4",
+  "top-right": "right-4 top-6 sm:top-4",
+  "bottom-left": "left-4 bottom-6 sm:bottom-4",
+  "bottom-right": "right-4 bottom-6 sm:bottom-4",
+};
+
+const Toolbar = ({
+  homeCoordinates = { x: 0, y: 0 },
+  config = {},
+}: ToolbarProps) => {
   const { x, y, scale } = useCanvasContext();
   const [hasMounted, setHasMounted] = useState(false);
 
+  const {
+    display = "both",
+    position = "top-left",
+    disableAutoHide = false,
+    className,
+    coordinatesClassName,
+    scaleClassName,
+    separatorClassName,
+    style,
+    coordinatesStyle,
+    scaleStyle,
+    separator = "|",
+    separatorGap,
+    coordinatesFormat,
+    scaleFormat,
+  } = config;
+
+  const separatorStyle: React.CSSProperties | undefined = separatorGap
+    ? {
+        marginInline:
+          typeof separatorGap === "number" ? `${separatorGap}px` : separatorGap,
+      }
+    : undefined;
+
   useEffect(() => {
     setHasMounted(true);
   }, []);
@@ -21,44 +58,120 @@ const Toolbar = ({ homeCoordinates = { x: 0, y: 0 } }: ToolbarProps) => {
   // numeric MotionValues
   const rawDx = useTransform(
     [x, scale],
-    ([lx, ls]) => -((lx as number) / (ls as number)) + homeCoordinates.x,
+    ([lx, ls]) => -((lx as number) / (ls as number)) + homeCoordinates.x
   );
   const rawDy = useTransform(
     [y, scale],
-    ([ly, ls]) => -((ly as number) / (ls as number)) + homeCoordinates.y,
+    ([ly, ls]) => -((ly as number) / (ls as number)) + homeCoordinates.y
   );
 
-  // formatted MotionValues
+  // formatted MotionValues for default display
   const displayX = useTransform(rawDx, (v) => Math.round(v).toString());
   const displayY = useTransform(rawDy, (v) => Math.round(v).toString());
   const displayScale = useTransform(scale, (v) => v.toFixed(2));
 
-  const opacity = useTransform([rawDx, rawDy, scale], ([dx, dy, ls]) =>
-    Math.abs(dx as number) < TOOLBAR_OPACITY_POS_EPS &&
+  // For custom formatters, we need to use state to track values
+  const [currentX, setCurrentX] = useState(0);
+  const [currentY, setCurrentY] = useState(0);
+  const [currentScale, setCurrentScale] = useState(1);
+
+  useEffect(() => {
+    const unsubX = rawDx.on("change", (v) => setCurrentX(Math.round(v)));
+    const unsubY = rawDy.on("change", (v) => setCurrentY(Math.round(v)));
+    const unsubScale = scale.on("change", (v) => setCurrentScale(v));
+    return () => {
+      unsubX();
+      unsubY();
+      unsubScale();
+    };
+  }, [rawDx, rawDy, scale]);
+
+  const opacity = useTransform([rawDx, rawDy, scale], ([dx, dy, ls]) => {
+    if (disableAutoHide) return 1;
+    return Math.abs(dx as number) < TOOLBAR_OPACITY_POS_EPS &&
       Math.abs(dy as number) < TOOLBAR_OPACITY_POS_EPS &&
       Math.abs((ls as number) - 1) < TOOLBAR_OPACITY_SCALE_EPS
       ? 0
-      : 1,
-  );
+      : 1;
+  });
 
   const handlePointerDown = (e: React.PointerEvent) => e.stopPropagation();
 
+  const showCoordinates = display === "coordinates" || display === "both";
+  const showScale = display === "scale" || display === "both";
+  const showSeparator = display === "both";
+
+  // Compute formatted values
+  const formattedCoordinates = useMemo(() => {
+    if (coordinatesFormat) {
+      return coordinatesFormat(currentX, currentY);
+    }
+    return null; // Will use motion spans for default
+  }, [coordinatesFormat, currentX, currentY]);
+
+  const formattedScale = useMemo(() => {
+    if (scaleFormat) {
+      return scaleFormat(currentScale);
+    }
+    return null; // Will use motion span for default
+  }, [scaleFormat, currentScale]);
+
+  // Placeholder content for SSR/initial render
+  const placeholderContent = useMemo(() => {
+    const parts: string[] = [];
+    if (showCoordinates) parts.push("(0, 0)");
+    if (showSeparator) parts.push(separator);
+    if (showScale) parts.push("1.00x");
+    return parts.join("");
+  }, [showCoordinates, showScale, showSeparator, separator]);
+
   return (
     <motion.div
-      className="absolute left-4 top-6 z-[1000] cursor-default select-none rounded-[10px] border border-border bg-canvas-offwhite p-2 font-mono text-xs text-canvas-heavy shadow-[0_6px_12px_rgba(0,0,0,0.10)] sm:top-4 md:text-sm"
+      className={cn(
+        "absolute z-[1000] cursor-default select-none rounded-[10px] border border-border bg-canvas-offwhite p-2 font-mono text-xs text-canvas-heavy shadow-[0_6px_12px_rgba(0,0,0,0.10)] md:text-sm",
+        positionStyles[position],
+        className
+      )}
       onPointerDown={handlePointerDown}
       data-toolbar-button
-      style={{ opacity }}
+      style={{ opacity, ...style }}
     >
       {hasMounted ? (
         <>
-          (<motion.span>{displayX}</motion.span>,{" "}
-          <motion.span>{displayY}</motion.span>)
-          <span className="text-canvas-light"> |</span>{" "}
-          <motion.span>{displayScale}</motion.span>x
+          {showCoordinates && (
+            <span className={coordinatesClassName} style={coordinatesStyle}>
+              {formattedCoordinates !== null ? (
+                formattedCoordinates
+              ) : (
+                <>
+                  (<motion.span>{displayX}</motion.span>,{" "}
+                  <motion.span>{displayY}</motion.span>)
+                </>
+              )}
+            </span>
+          )}
+          {showSeparator && (
+            <span
+              className={cn("text-canvas-light", separatorClassName)}
+              style={separatorStyle}
+            >
+              {separator}
+            </span>
+          )}
+          {showScale && (
+            <span className={scaleClassName} style={scaleStyle}>
+              {formattedScale !== null ? (
+                formattedScale
+              ) : (
+                <>
+                  <motion.span>{displayScale}</motion.span>x
+                </>
+              )}
+            </span>
+          )}
         </>
       ) : (
-        <span style={{ opacity: 0 }}>(0, 0) | 1.00x</span>
+        <span style={{ opacity: 0 }}>{placeholderContent}</span>
       )}
     </motion.div>
   );

package/src/index.ts

@@ -1,41 +1,59 @@
 // Components
-export { default as Canvas } 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 CanvasToolbar } from './components/canvas/toolbar';
-export { default as CanvasNavbar } from './components/canvas/navbar';
+export { default as Canvas } 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 CanvasToolbar } from "./components/canvas/toolbar";
+export { default as CanvasNavbar } from "./components/canvas/navbar";
 
 // Background Components
 export {
-    DefaultCanvasBackground,
-    DefaultWrapperBackground,
-    DefaultIntroContent,
-    DEFAULT_CANVAS_GRADIENT,
-    DEFAULT_INTRO_GRADIENT,
-    DEFAULT_CANVAS_BOX_GRADIENT,
-} from './components/canvas/backgrounds';
+  DefaultCanvasBackground,
+  DefaultWrapperBackground,
+  DefaultIntroContent,
+  DEFAULT_CANVAS_GRADIENT,
+  DEFAULT_INTRO_GRADIENT,
+  DEFAULT_CANVAS_BOX_GRADIENT,
+} from "./components/canvas/backgrounds";
 export type {
-    DefaultCanvasBackgroundProps,
-    DefaultWrapperBackgroundProps,
-    DefaultIntroContentProps,
-} from './components/canvas/backgrounds';
+  DefaultCanvasBackgroundProps,
+  DefaultWrapperBackgroundProps,
+  DefaultIntroContentProps,
+} from "./components/canvas/backgrounds";
 
 // 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';
+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 { default as useWindowDimensions } from "./hooks/useWindowDimensions";
+export { usePerformanceMode as usePerformanceModeLegacy } from "./hooks/usePerformanceMode";
 
 // Utilities
-export * from './lib/canvas';
-export * from './lib/constants';
-export * from './lib/utils';
-export * from './utils/performance';
+export * from "./lib/canvas";
+export * from "./lib/constants";
+export * from "./lib/utils";
+export * from "./utils/performance";
 
 // Types
-export type { SectionCoordinates, NavItem, CanvasSection } from './types';
+export type {
+  SectionCoordinates,
+  NavItem,
+  CanvasSection,
+  ToolbarConfig,
+  ToolbarPosition,
+  ToolbarDisplayMode,
+} from "./types";

package/src/lib/canvas.ts

@@ -1,16 +1,16 @@
 import { animate, type MotionValue, type Point } from "framer-motion";
 import { useMemo } from "react";
 import {
-  CANVAS_WIDTH,
-  CANVAS_HEIGHT,
+  DEFAULT_CANVAS_WIDTH,
+  DEFAULT_CANVAS_HEIGHT,
   MAX_DIM_RATIO,
   INTRO_ASPECT_RATIO,
   PAN_SPRING,
   ScreenSizeEnum,
 } from "./constants";
 
-export const canvasWidth = CANVAS_WIDTH;
-export const canvasHeight = CANVAS_HEIGHT;
+export const canvasWidth = DEFAULT_CANVAS_WIDTH;
+export const canvasHeight = DEFAULT_CANVAS_HEIGHT;
 
 // Re-export ScreenSizeEnum for backward compatibility
 export { ScreenSizeEnum } from "./constants";

package/src/lib/constants.ts

@@ -24,10 +24,10 @@ export enum ScreenSizeEnum {
 // ============================================================================
 
 /** Default canvas width in pixels */
-export const CANVAS_WIDTH = 6000;
+export const DEFAULT_CANVAS_WIDTH = 6000;
 
 /** Default canvas height in pixels */
-export const CANVAS_HEIGHT = 4000;
+export const DEFAULT_CANVAS_HEIGHT = 4000;
 
 // ============================================================================
 // INTRO ANIMATION

package/src/types/index.ts

@@ -38,3 +38,62 @@ export interface NavItem {
   /** If true, clicking this section triggers the reset/home behavior */
   isHome?: boolean;
 }
+
+/**
+ * Preset positions for the toolbar
+ */
+export type ToolbarPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+/**
+ * What to display in the toolbar
+ */
+export type ToolbarDisplayMode = 'coordinates' | 'scale' | 'both';
+
+/**
+ * Configuration options for the canvas toolbar
+ */
+export interface ToolbarConfig {
+  // === Visibility ===
+  /** Hide the toolbar entirely. Default: false */
+  hidden?: boolean;
+
+  // === Display Mode ===
+  /** What to show: 'coordinates', 'scale', or 'both'. Default: 'both' */
+  display?: ToolbarDisplayMode;
+
+  // === Positioning ===
+  /** Preset position. Default: 'top-left' */
+  position?: ToolbarPosition;
+
+  // === Auto-hide Behavior ===
+  /** Disable auto-hide when at home position. Default: false */
+  disableAutoHide?: boolean;
+
+  // === Styling (Tailwind-friendly) ===
+  /** Additional className for the container */
+  className?: string;
+  /** Additional className for the coordinates text */
+  coordinatesClassName?: string;
+  /** Additional className for the scale text */
+  scaleClassName?: string;
+  /** Additional className for the separator */
+  separatorClassName?: string;
+
+  // === Styling (non-Tailwind / inline styles) ===
+  /** Inline styles for the container */
+  style?: React.CSSProperties;
+  /** Inline styles for the coordinates */
+  coordinatesStyle?: React.CSSProperties;
+  /** Inline styles for the scale */
+  scaleStyle?: React.CSSProperties;
+
+  // === Content Customization ===
+  /** Custom separator between coordinates and scale. Default: ' | ' */
+  separator?: string;
+  /** Gap around the separator in pixels or CSS value. Default: undefined (uses inline spacing) */
+  separatorGap?: number | string;
+  /** Format for coordinates. Default: '(x, y)' */
+  coordinatesFormat?: (x: number, y: number) => string;
+  /** Format for scale. Default: '1.00x' */
+  scaleFormat?: (scale: number) => string;
+}