dst-rg 1.0.0

package/src/components/ImageMagnify/_.stories.tsx

@@ -0,0 +1,226 @@
+import type { ComponentProps } from "react";
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { ImageMagnify } from "./index";
+
+type LayoutOption = "centered" | "left" | "right";
+type ImageMagnifyStoryArgs = ComponentProps<typeof ImageMagnify> & {
+  layout: LayoutOption;
+};
+
+const withDynamicLayout: Decorator = (Story, context) => {
+  const layout = context.args?.layout ?? "centered";
+  const justifyContent =
+    layout === "left"
+      ? "flex-start"
+      : layout === "right"
+      ? "flex-end"
+      : "center";
+
+  return (
+    <div style={{ display: "flex", justifyContent, width: "100%" }}>
+      <div style={{ maxWidth: 420 }}>
+        <Story />
+      </div>
+    </div>
+  );
+};
+
+const meta: Meta<ImageMagnifyStoryArgs> = {
+  title: "Components/ImageMagnify",
+  component: ImageMagnify,
+  tags: ["autodocs"],
+  decorators: [withDynamicLayout],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A magnifying glass component that allows users to zoom in on images with mouse hover or touch interactions.",
+      },
+    },
+  },
+  argTypes: {
+    src: {
+      control: "text",
+      description: "Image source URL",
+    },
+    alt: {
+      control: "text",
+      description: "Alt text for the image",
+    },
+    zoom: {
+      control: { type: "range", min: 1, max: 5, step: 0.5 },
+      description: "Zoom level multiplier",
+    },
+    layout: {
+      control: "inline-radio",
+      options: ["centered", "left", "right"],
+      description: "Horizontal alignment of the story canvas",
+    },
+    lensSize: {
+      control: { type: "range", min: 50, max: 300, step: 10 },
+      description: "Size of the magnifying lens in pixels",
+    },
+    zoomPanePosition: {
+      control: "inline-radio",
+      options: ["right", "left"],
+      description: "Position of the zoom pane relative to the source image",
+    },
+    zoomMode: {
+      control: "inline-radio",
+      options: ["pane", "inline"],
+      description: "Display mode: standalone zoom pane or inline lens",
+    },
+    touchToggle: {
+      control: "boolean",
+      description: "Enable touch toggle on mobile",
+    },
+    zoomPaneSize: {
+      control: { type: "range", min: 100, max: 800, step: 50 },
+      description: "Custom zoom pane size in pixels",
+    },
+    className: {
+      control: "text",
+      description: "Additional CSS class name",
+    },
+  },
+  args: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<ImageMagnifyStoryArgs>;
+
+// Sample images for stories
+const sampleImage =
+  "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=300&fit=crop";
+
+export const Default: Story = {
+  args: {
+    src: sampleImage,
+    alt: "Sample image for magnification",
+    zoom: 2,
+    lensSize: 140,
+    touchToggle: true,
+    zoomMode: "pane",
+    zoomPanePosition: "right",
+  },
+};
+
+export const HighZoom: Story = {
+  args: {
+    src: sampleImage,
+    alt: "High zoom magnification",
+    zoom: 3,
+    lensSize: 120,
+    touchToggle: true,
+    zoomMode: "pane",
+    zoomPanePosition: "right",
+  },
+};
+
+export const LargeLens: Story = {
+  args: {
+    src: sampleImage,
+    alt: "Large lens magnification",
+    zoom: 2,
+    lensSize: 200,
+    touchToggle: true,
+    zoomMode: "pane",
+    zoomPanePosition: "right",
+  },
+};
+
+export const LeftPosition: Story = {
+  args: {
+    src: sampleImage,
+    alt: "Zoom pane on the left",
+    zoom: 2,
+    lensSize: 140,
+    touchToggle: true,
+    zoomMode: "pane",
+    zoomPanePosition: "left",
+  },
+};
+
+export const CustomZoomPaneSize: Story = {
+  args: {
+    src: sampleImage,
+    alt: "Custom zoom pane size",
+    zoom: 2.5,
+    lensSize: 140,
+    touchToggle: true,
+    zoomPaneSize: 300,
+    zoomMode: "pane",
+    zoomPanePosition: "right",
+  },
+};
+
+export const InlineLens: Story = {
+  args: {
+    src: sampleImage,
+    alt: "Inline lens magnification",
+    zoom: 2.5,
+    lensSize: 160,
+    touchToggle: true,
+    zoomMode: "inline",
+    zoomPanePosition: "right",
+  },
+};
+
+export const NoTouchToggle: Story = {
+  args: {
+    src: sampleImage,
+    alt: "No touch toggle",
+    zoom: 2,
+    lensSize: 140,
+    touchToggle: false,
+    zoomMode: "pane",
+    zoomPanePosition: "right",
+  },
+};
+
+export const SmallLens: Story = {
+  args: {
+    src: sampleImage,
+    alt: "Small lens for precision",
+    zoom: 3,
+    lensSize: 80,
+    touchToggle: true,
+    zoomMode: "pane",
+    zoomPanePosition: "right",
+  },
+};
+
+export const WithCustomClass: Story = {
+  args: {
+    src: sampleImage,
+    alt: "With custom styling",
+    zoom: 2,
+    lensSize: 140,
+    touchToggle: true,
+    className: "border-2 border-blue-500 rounded-lg p-4",
+    zoomMode: "pane",
+    zoomPanePosition: "right",
+  },
+};
+
+export const Interactive: Story = {
+  args: {
+    src: sampleImage,
+    alt: "Interactive magnification",
+    zoom: 2,
+    lensSize: 140,
+    touchToggle: true,
+    zoomMode: "pane",
+    zoomPanePosition: "right",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Hover over the image to see the magnification effect. On mobile devices, tap to toggle the zoom.",
+      },
+    },
+  },
+};

package/src/components/ImageMagnify/_.style.ts

@@ -0,0 +1,109 @@
+// Tailwind CSS classes for ImageMagnify component
+
+export const imageMagnifyClasses = {
+  // Main container
+  container: 'flex items-start gap-3',
+  
+  // Image container
+  imageContainer: 'relative select-none touch-none',
+  
+  // Image element
+  image: 'block max-w-full h-auto select-none',
+  
+  // Lens styles
+  lens: 'pointer-events-none absolute rounded-full border-2 border-white shadow-lg bg-transparent z-10',
+  lensAnimated: 'pointer-events-none absolute rounded-full border-2 border-white shadow-lg bg-transparent z-10 transition-opacity duration-200 ease-in-out',
+  
+  // Lens variants
+  lensGlow: 'pointer-events-none absolute rounded-full border-2 border-white shadow-lg bg-transparent z-10 shadow-[0_0_0_2px_white,0_0_20px_rgba(59,130,246,0.5),0_4px_6px_-1px_rgba(0,0,0,0.1)]',
+  lensDashed: 'pointer-events-none absolute rounded-full border-2 border-dashed border-white bg-white/10 z-10',
+  
+  // Zoom pane
+  zoomPane: 'overflow-hidden rounded-lg border border-slate-200 shadow-sm relative flex-shrink-0',
+  zoomPaneAnimated: 'overflow-hidden rounded-lg border border-slate-200 shadow-sm relative flex-shrink-0 transition-opacity duration-200 ease-in-out',
+  
+  // Zoom pane variants
+  zoomPaneRounded: 'overflow-hidden rounded-2xl border border-slate-200 shadow-sm relative flex-shrink-0',
+  zoomPaneSharp: 'overflow-hidden border border-slate-200 shadow-sm relative flex-shrink-0',
+  zoomPaneGlow: 'overflow-hidden rounded-lg border border-slate-200 shadow-sm relative flex-shrink-0 shadow-[0_4px_6px_-1px_rgba(0,0,0,0.1),0_2px_4px_-1px_rgba(0,0,0,0.06),0_0_0_1px_rgba(59,130,246,0.2)]',
+  
+  // Responsive container
+  responsiveContainer: 'flex items-start gap-3 md:flex-row flex-col md:items-start items-center gap-4',
+  
+  // Hidden/visible states
+  hidden: 'hidden',
+  visible: 'block',
+  
+  // Touch action
+  touchNone: 'touch-none',
+  
+  // Image drag prevention
+  noDrag: 'select-none',
+  
+  // Lens positioning utilities
+  lensPosition: (x: number, y: number, size: number) => ({
+    left: Math.max(0, x - size / 2),
+    top: Math.max(0, y - size / 2),
+    width: size,
+    height: size,
+  }),
+  
+  // Zoom pane background utilities
+  zoomPaneBackground: (imageUrl: string, size: string, position: string) => ({
+    backgroundImage: `url(${imageUrl})`,
+    backgroundRepeat: 'no-repeat',
+    backgroundSize: size,
+    backgroundPosition: position,
+  }),
+};
+
+// Utility functions for dynamic styles
+export const getLensStyle = (
+  lensSize: number,
+  lensPos: { x: number; y: number },
+  visible: boolean
+) => ({
+  width: lensSize,
+  height: lensSize,
+  left: Math.max(0, lensPos.x - lensSize / 2),
+  top: Math.max(0, lensPos.y - lensSize / 2),
+  display: visible ? 'block' : 'none',
+});
+
+export const getZoomPaneStyle = (
+  width: number,
+  height: number,
+  backgroundImage: string,
+  backgroundSize: string,
+  backgroundPosition: string,
+  visible: boolean
+) => ({
+  width,
+  height,
+  backgroundImage: `url(${backgroundImage})`,
+  backgroundRepeat: 'no-repeat',
+  backgroundSize,
+  backgroundPosition,
+  display: visible ? 'block' : 'none',
+});
+
+// Predefined class combinations for common use cases
+export const lensVariants = {
+  default: imageMagnifyClasses.lens,
+  animated: imageMagnifyClasses.lensAnimated,
+  glow: imageMagnifyClasses.lensGlow,
+  dashed: imageMagnifyClasses.lensDashed,
+};
+
+export const zoomPaneVariants = {
+  default: imageMagnifyClasses.zoomPane,
+  animated: imageMagnifyClasses.zoomPaneAnimated,
+  rounded: imageMagnifyClasses.zoomPaneRounded,
+  sharp: imageMagnifyClasses.zoomPaneSharp,
+  glow: imageMagnifyClasses.zoomPaneGlow,
+};
+
+export const containerVariants = {
+  default: imageMagnifyClasses.container,
+  responsive: imageMagnifyClasses.responsiveContainer,
+};

package/src/components/ImageMagnify/_.types.ts

@@ -0,0 +1,44 @@
+export interface ImageMagnifyProps {
+  /** Image source URL */
+  src: string;
+  /** Alt text for the image */
+  alt?: string;
+  /** Zoom level multiplier (e.g., 2 = 200% zoom) */
+  zoom?: number;
+  /** Size of the magnifying lens in pixels (square) */
+  lensSize?: number;
+  /** Additional CSS class name */
+  className?: string;
+  /** Tailwind classes applied when lens is visible */
+  lensVisibleClassName?: string;
+  /** Tailwind classes applied when zoom pane is visible */
+  zoomPaneVisibleClassName?: string;
+  /** Position of the zoom pane relative to the image */
+  zoomPanePosition?: 'right' | 'left';
+  /** Enable touch toggle functionality on mobile devices */
+  touchToggle?: boolean;
+  /** Custom zoom pane size in pixels (optional) */
+  zoomPaneSize?: number;
+  /** Zoom mode: 'pane' for separate zoom pane, 'inline' for zoom directly on image */
+  zoomMode?: 'pane' | 'inline';
+}
+
+export interface LensPosition {
+  x: number;
+  y: number;
+}
+
+export interface ImageSize {
+  w: number;
+  h: number;
+}
+
+export interface ImageMagnifyState {
+  visible: boolean;
+  lensPos: LensPosition;
+  imgSize: ImageSize;
+  isTouchZoom: boolean;
+}
+
+export type ZoomPanePosition = 'right' | 'left';
+export type ZoomMode = 'pane' | 'inline';

package/src/components/ImageMagnify/index.tsx

@@ -0,0 +1,204 @@
+import React, { useEffect, useRef, useState } from "react";
+import type { ImageMagnifyProps, LensPosition } from "./_.types";
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), max);
+
+const defaultLensPosition: LensPosition = { x: 0, y: 0 };
+
+export function ImageMagnify({
+  src,
+  alt = "",
+  zoom = 2,
+  lensSize = 140,
+  className = "",
+  lensVisibleClassName = "hidden md:block",
+  zoomPaneVisibleClassName = "hidden md:block",
+  touchToggle = true,
+  zoomPaneSize,
+  zoomPanePosition = "right",
+  zoomMode = "pane",
+}: ImageMagnifyProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const imgRef = useRef<HTMLImageElement | null>(null);
+
+  const [visible, setVisible] = useState(false);
+  const [lensPos, setLensPos] = useState<LensPosition>(defaultLensPosition);
+  const [imgSize, setImgSize] = useState({ w: 0, h: 0 });
+  const [isTouchZoom, setIsTouchZoom] = useState(false);
+
+  useEffect(() => {
+    const update = () => {
+      const img = imgRef.current;
+      if (!img) return;
+      setImgSize({ w: img.width, h: img.height });
+    };
+
+    const img = imgRef.current;
+    if (!img) return;
+
+    if (img.complete) update();
+    img.addEventListener("load", update);
+    window.addEventListener("resize", update);
+
+    return () => {
+      img.removeEventListener("load", update);
+      window.removeEventListener("resize", update);
+    };
+  }, [src]);
+
+  const getRelativePosition = (
+    clientX: number,
+    clientY: number
+  ): LensPosition => {
+    const img = imgRef.current;
+    if (!img) return defaultLensPosition;
+
+    const rect = img.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return defaultLensPosition;
+
+    const x = clamp(clientX - rect.left, 0, rect.width);
+    const y = clamp(clientY - rect.top, 0, rect.height);
+
+    return { x, y };
+  };
+
+  const updateLensFromEvent = (event: React.MouseEvent | React.TouchEvent) => {
+    const nativeEvent =
+      "nativeEvent" in event ? (event.nativeEvent as any) : (event as any);
+
+    if ("touches" in nativeEvent && nativeEvent.touches?.length > 0) {
+      const touch = nativeEvent.touches[0];
+      setLensPos(getRelativePosition(touch.clientX, touch.clientY));
+      return;
+    }
+
+    if (typeof nativeEvent.clientX === "number") {
+      setLensPos(getRelativePosition(nativeEvent.clientX, nativeEvent.clientY));
+    }
+  };
+
+  const handleMove = (event: React.MouseEvent<HTMLDivElement>) => {
+    updateLensFromEvent(event);
+  };
+
+  const handleEnter = () => {
+    setVisible(true);
+  };
+
+  const handleLeave = () => {
+    setVisible(false);
+    if (isTouchZoom) setIsTouchZoom(false);
+  };
+
+  const handleTouchStart = (event: React.TouchEvent<HTMLDivElement>) => {
+    if (!touchToggle) return;
+
+    event.preventDefault();
+
+    if (!isTouchZoom) {
+      setIsTouchZoom(true);
+      setVisible(true);
+      updateLensFromEvent(event);
+    } else {
+      setIsTouchZoom(false);
+      setVisible(false);
+    }
+  };
+
+  const handleTouchMove = (event: React.TouchEvent<HTMLDivElement>) => {
+    if (!isTouchZoom) return;
+    event.preventDefault();
+    updateLensFromEvent(event);
+  };
+
+  const currentRect = imgRef.current?.getBoundingClientRect();
+  const displayW = currentRect?.width ?? imgSize.w;
+  const displayH = currentRect?.height ?? imgSize.h;
+  const safeDisplayW = displayW || 1;
+  const safeDisplayH = displayH || 1;
+
+  const backgroundSize = `${safeDisplayW * zoom}px ${safeDisplayH * zoom}px`;
+  const backgroundPosition = `${(lensPos.x / safeDisplayW) * 100}% ${
+    (lensPos.y / safeDisplayH) * 100
+  }%`;
+
+  const paneWidth = zoomPaneSize ?? safeDisplayW;
+  const paneHeight = zoomPaneSize ?? safeDisplayH;
+
+  const lensStyle: React.CSSProperties = {
+    width: lensSize,
+    height: lensSize,
+    left: clamp(
+      lensPos.x - lensSize / 2,
+      0,
+      Math.max(safeDisplayW - lensSize, 0)
+    ),
+    top: clamp(
+      lensPos.y - lensSize / 2,
+      0,
+      Math.max(safeDisplayH - lensSize, 0)
+    ),
+    backgroundImage: zoomMode === "inline" ? `url(${src})` : "none",
+    backgroundRepeat: "no-repeat",
+    backgroundSize: zoomMode === "inline" ? backgroundSize : undefined,
+    backgroundPosition: zoomMode === "inline" ? backgroundPosition : undefined,
+  };
+
+  const zoomPaneStyle: React.CSSProperties = {
+    width: paneWidth,
+    height: paneHeight,
+    backgroundImage: `url(${src})`,
+    backgroundRepeat: "no-repeat",
+    backgroundSize,
+    backgroundPosition,
+  };
+
+  const isPaneLeft = zoomPanePosition === "left";
+  const lensVisibilityClass = visible ? lensVisibleClassName : "hidden";
+  const zoomPaneVisibilityClass =
+    zoomMode === "pane" && visible ? zoomPaneVisibleClassName : "hidden";
+
+  return (
+    <div className={`relative w-fit inline-block align-top ${className}`}>
+      <div
+        ref={containerRef}
+        className="relative select-none touch-none"
+        onMouseMove={handleMove}
+        onMouseEnter={handleEnter}
+        onMouseLeave={handleLeave}
+        onTouchStart={handleTouchStart}
+        onTouchMove={handleTouchMove}
+        onTouchEnd={handleLeave}
+      >
+        <img
+          ref={imgRef}
+          src={src}
+          alt={alt}
+          className="block max-w-full h-auto select-none"
+          draggable={false}
+          onDragStart={(event) => event.preventDefault()}
+        />
+
+        <div
+          className={`pointer-events-none absolute rounded-full border-2 border-white shadow-lg ${lensVisibilityClass} ${
+            zoomMode === "inline"
+              ? "bg-white/10 backdrop-blur"
+              : "bg-transparent"
+          }`}
+          style={lensStyle}
+        />
+      </div>
+
+      {/* {zoomMode === "pane" && ( */}
+      <div
+        // aria-hidden={!visible}
+        className={`${zoomPaneVisibilityClass} absolute top-1/2 -translate-y-1/2 overflow-hidden rounded-lg border border-slate-200 shadow-sm 
+         ${isPaneLeft ? "right-full mr-3" : "left-full ml-3"}
+            `}
+        style={zoomPaneStyle}
+      />
+      {/* )} */}
+    </div>
+  );
+}