@mmmmzxe/react-360-view 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maryemmostafa24
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @mmmmzxe/react-360-viewer
+
+A standalone, configurable 360° image viewer for React with drag rotation, zoom, hotspots, and auto-rotate support.
+
+## Features
+
+* Drag-to-rotate frame navigation
+* Zoom with mouse wheel and toolbar controls
+* Pan when zoomed
+* Optional auto-rotate
+* Interactive hotspots with tooltips
+* Hotspot add mode
+* TypeScript support
+* Tailwind + shadcn compatible
+* Headless hook support
+
+## Installation
+
+```bash
+npm install @mmmmzxe/react-360-viewer
+```
+
+### Peer Dependencies
+
+```bash
+npm install react react-dom lucide-react
+```
+
+### Styles
+
+Import the stylesheet once in your app (e.g. in your root layout or entry file):
+
+```tsx
+import '@mmmmzxe/react-360-viewer/styles.css';
+```
+
+Styles are scoped to `[data-viewer-360]` via CSS `@scope` and will not override your app's global theme or Tailwind classes. Requires a **client component** in Next.js App Router (`'use client'`).
+
+Wrap the viewer in a sized container if needed:
+
+```tsx
+<div className="w-full max-w-3xl">
+  <Viewer360 frames={frames} />
+</div>
+```
+
+If styles don't appear after updating, delete `.next` and restart the dev server.
+
+---
+
+## Quick Start
+
+```tsx
+'use client';
+
+import '@mmmmzxe/react-360-viewer/styles.css';
+import { useState } from "react";
+import {
+  Viewer360,
+  type Viewer360Frame,
+} from "@mmmmzxe/react-360-viewer";
+
+const frames: Viewer360Frame[] = [
+  { id: "1", src: "/images/frame-01.jpg", label: "Front" },
+  { id: "2", src: "/images/frame-02.jpg", label: "Side" },
+  { id: "3", src: "/images/frame-03.jpg", label: "Rear" },
+];
+
+export default function ProductViewer() {
+  const [frameIndex, setFrameIndex] = useState(0);
+
+  return (
+    <Viewer360
+      frames={frames}
+      currentFrameIndex={frameIndex}
+      onFrameChange={setFrameIndex}
+    />
+  );
+}
+```
+
+## Hotspots
+
+```tsx
+<Viewer360
+  frames={frames}
+  hotspots={[
+    {
+      id: "1",
+      frameIndex: 0,
+      positionX: 50,
+      positionY: 40,
+      data: {
+        title: "Scratch",
+        description: "Front bumper",
+      },
+    },
+  ]}
+/>
+```
+
+### Add Hotspots
+
+```tsx
+<Viewer360
+  frames={frames}
+  hotspots={hotspots}
+  showHotspotModeControl
+  onHotspotAdd={(position) => {
+    console.log(position);
+  }}
+/>
+```
+
+## Configuration
+
+```tsx
+<Viewer360
+  config={{
+    minZoom: 1,
+    maxZoom: 4,
+    zoomStep: 0.2,
+    dragSensitivity: 8,
+    autoRotate: true,
+    autoRotateIntervalMs: 150,
+  }}
+/>
+```
+
+## Main Props
+
+| Prop                   | Type               | Description               |
+| ---------------------- | ------------------ | ------------------------- |
+| frames                 | Viewer360Frame[]   | Required image frames     |
+| hotspots               | Viewer360Hotspot[] | Hotspots to display       |
+| currentFrameIndex      | number             | Controlled frame          |
+| onFrameChange          | function           | Frame change callback     |
+| config                 | Viewer360Config    | Viewer settings           |
+| showFrameIndicator     | boolean            | Show frame counter        |
+| showHotspotModeControl | boolean            | Enable add hotspot button |
+| onHotspotAdd           | function           | Add hotspot callback      |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev
+npm run test-run
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+import * as React$1 from 'react';
+import { ReactNode, MouseEvent, CSSProperties, JSX, RefObject, PointerEvent, WheelEvent } from 'react';
+import { ClassValue } from 'clsx';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+
+declare const defaultViewer360Config: {
+    minZoom: number;
+    maxZoom: number;
+    zoomStep: number;
+    dragSensitivity: number;
+    autoRotate: boolean;
+    autoRotateIntervalMs: number;
+    autoRotateDirection: "forward";
+};
+
+type Viewer360Frame = {
+    id: string;
+    src: string;
+    label?: string;
+};
+type Viewer360PanOffset = {
+    panX: number;
+    panY: number;
+};
+type Viewer360Config = {
+    minZoom?: number;
+    maxZoom?: number;
+    zoomStep?: number;
+    dragSensitivity?: number;
+    autoRotate?: boolean;
+    autoRotateIntervalMs?: number;
+    autoRotateDirection?: 'forward' | 'backward';
+};
+type Viewer360Hotspot<TData = unknown> = {
+    id: string;
+    frameIndex: number;
+    positionX: number;
+    positionY: number;
+    data?: TData;
+};
+type Viewer360HotspotPosition = {
+    frameIndex: number;
+    frameId: string;
+    positionX: number;
+    positionY: number;
+};
+type Viewer360HotspotRenderProps<TData = unknown> = {
+    hotspot: Viewer360Hotspot<TData>;
+    leftPercent: number;
+    topPercent: number;
+};
+type Viewer360OverlayRenderProps = {
+    currentFrameIndex: number;
+    frameCount: number;
+    frameLabel?: string;
+    isHotspotMode: boolean;
+    labels: Required<Viewer360Labels>;
+    frameIndicatorClassName: string;
+};
+type Viewer360ToolbarRenderProps = {
+    zoom: number;
+    minZoom: number;
+    maxZoom: number;
+    isResetDisabled: boolean;
+    isHotspotMode: boolean;
+    showHotspotModeControl: boolean;
+    showZoomControls: boolean;
+    showResetControl: boolean;
+    showDragHint: boolean;
+    labels: Required<Viewer360Labels>;
+    onZoomIn: () => void;
+    onZoomOut: () => void;
+    onResetView: () => void;
+    onHotspotModeChange: (active: boolean) => void;
+};
+
+type Viewer360Marker = {
+    id: string;
+    title: string;
+    description?: string;
+};
+type Viewer360MarkerPinClassNames = {
+    root?: string;
+    ping?: string;
+    dot?: string;
+    tooltip?: string;
+    tooltipHeader?: string;
+    tooltipBody?: string;
+    tooltipTitle?: string;
+    tooltipDescription?: string;
+    deleteButton?: string;
+};
+type Viewer360MarkerPinLabels = {
+    delete?: string;
+};
+type Viewer360MarkerPinRenderProps<TData = unknown> = {
+    marker: Viewer360Marker;
+    hotspot?: Viewer360Hotspot<TData>;
+};
+type Viewer360MarkerPinProps<TData = unknown> = {
+    marker: Viewer360Marker;
+    hotspot?: Viewer360Hotspot<TData>;
+    leftPercent: number;
+    topPercent: number;
+    onDelete?: (id: string) => void;
+    isDeletePending?: boolean;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    renderTag?: (props: Viewer360MarkerPinRenderProps<TData>) => ReactNode;
+    classNames?: Viewer360MarkerPinClassNames;
+    labels?: Viewer360MarkerPinLabels;
+};
+type Viewer360HotspotPinOptions<TData = unknown> = {
+    onDelete?: (id: string) => void;
+    deletingMarkerId?: string | null;
+    getMarker?: (hotspot: Viewer360Hotspot<TData>) => Viewer360Marker;
+    renderTag?: (props: Viewer360MarkerPinRenderProps<TData>) => ReactNode;
+    classNames?: Viewer360MarkerPinClassNames;
+    labels?: Viewer360MarkerPinLabels;
+};
+
+type Viewer360ClassNames = {
+    root?: string;
+    viewport?: string;
+    canvas?: string;
+    overlay?: string;
+    loading?: string;
+    loadingText?: string;
+    frameIndicator?: string;
+    hotspotModeBanner?: string;
+    toolbar?: string;
+    dragHint?: string;
+    controls?: string;
+    controlButton?: string;
+    controlButtonActive?: string;
+    controlButtonDisabled?: string;
+    zoomDisplay?: string;
+    divider?: string;
+};
+type Viewer360Labels = {
+    loading?: string;
+    dragHint?: string;
+    frameIndicator?: (params: {
+        current: number;
+        total: number;
+        label?: string;
+    }) => string;
+    zoom?: (percent: number) => string;
+    hotspotModeActive?: string;
+    addHotspot?: string;
+    zoomIn?: string;
+    zoomOut?: string;
+    resetView?: string;
+    deleteMarker?: string;
+};
+type Viewer360Theme = {
+    '--viewer-bg'?: string;
+    '--viewer-border'?: string;
+    '--viewer-text'?: string;
+    '--viewer-muted'?: string;
+    '--viewer-accent'?: string;
+    '--viewer-accent-foreground'?: string;
+    '--viewer-control-bg'?: string;
+    '--viewer-control-border'?: string;
+    '--viewer-hotspot-banner-bg'?: string;
+    '--viewer-hotspot-banner-border'?: string;
+    '--viewer-hotspot-banner-text'?: string;
+};
+type Viewer360Props<TData = unknown> = {
+    frames: Viewer360Frame[];
+    currentFrameIndex?: number;
+    defaultFrameIndex?: number;
+    onFrameChange?: (index: number) => void;
+    config?: Viewer360Config;
+    className?: string;
+    classNames?: Viewer360ClassNames;
+    style?: CSSProperties;
+    theme?: Viewer360Theme;
+    labels?: Viewer360Labels;
+    aspectRatio?: string;
+    showZoomControls?: boolean;
+    showResetControl?: boolean;
+    showFrameIndicator?: boolean;
+    showDragHint?: boolean;
+    showHotspotModeControl?: boolean;
+    hotspotPin?: Viewer360HotspotPinOptions<TData>;
+    hotspots?: Viewer360Hotspot<TData>[];
+    renderHotspot?: (props: Viewer360HotspotRenderProps<TData>) => ReactNode;
+    renderLoading?: () => ReactNode;
+    renderFrameIndicator?: (props: Viewer360OverlayRenderProps) => ReactNode;
+    renderHotspotModeBanner?: (props: Pick<Viewer360OverlayRenderProps, 'labels'>) => ReactNode;
+    renderToolbar?: (props: Viewer360ToolbarRenderProps) => ReactNode;
+    onHotspotClick?: (hotspot: Viewer360Hotspot<TData>, event: MouseEvent<HTMLDivElement>) => void;
+    hotspotMode?: boolean;
+    defaultHotspotMode?: boolean;
+    onHotspotModeChange?: (active: boolean) => void;
+    onHotspotAdd?: (position: Viewer360HotspotPosition) => void;
+    children?: ReactNode;
+};
+
+declare const defaultViewer360Labels: Required<Viewer360Labels>;
+
+declare const defaultViewer360MarkerPinLabels: {
+    readonly delete: "Remove marker";
+};
+
+declare const viewer360ClassNames: Required<Viewer360ClassNames>;
+declare const viewer360MarkerPinClassNames: Required<Viewer360MarkerPinClassNames>;
+/** @deprecated Use `viewer360ClassNames` */
+declare const defaultViewer360ClassNames: Required<Viewer360ClassNames>;
+/** @deprecated Use `viewer360MarkerPinClassNames` */
+declare const defaultViewer360MarkerPinClassNames: Required<Viewer360MarkerPinClassNames>;
+
+declare function Viewer360<TData = unknown>({ frames, currentFrameIndex: controlledFrameIndex, defaultFrameIndex, onFrameChange, config, className, classNames, style, theme, labels, aspectRatio, showZoomControls, showResetControl, showFrameIndicator, showDragHint, showHotspotModeControl, hotspotPin, hotspots, renderHotspot, renderLoading, renderFrameIndicator, renderHotspotModeBanner, renderToolbar, onHotspotClick, hotspotMode: controlledHotspotMode, defaultHotspotMode, onHotspotModeChange, onHotspotAdd, children, }: Viewer360Props<TData>): JSX.Element;
+
+type Viewer360AddModeBannerProps = {
+    className?: string;
+    label: string;
+};
+declare function Viewer360AddModeBanner({ className, label }: Viewer360AddModeBannerProps): JSX.Element;
+
+type Viewer360FrameIndicatorProps = {
+    className?: string;
+    label: string;
+};
+declare function Viewer360FrameIndicator({ className, label }: Viewer360FrameIndicatorProps): JSX.Element;
+
+type Viewer360LoadingOverlayProps = {
+    className?: string;
+    textClassName?: string;
+    label: string;
+};
+declare function Viewer360LoadingOverlay({ className, textClassName, label }: Viewer360LoadingOverlayProps): JSX.Element;
+
+declare function Viewer360MarkerPin<TData = unknown>({ marker, hotspot, leftPercent, topPercent, onDelete, isDeletePending, onClick, renderTag, classNames, labels, }: Viewer360MarkerPinProps<TData>): JSX.Element;
+
+type Viewer360ToolbarProps = Viewer360ToolbarRenderProps;
+declare function Viewer360Toolbar({ showDragHint, showHotspotModeControl, showZoomControls, showResetControl, labels, isHotspotMode, zoom, minZoom, maxZoom, isResetDisabled, onHotspotModeChange, onZoomIn, onZoomOut, onResetView, }: Viewer360ToolbarProps): JSX.Element;
+
+type ViewerImageLayout = {
+    width: number;
+    height: number;
+    centerX: number;
+    centerY: number;
+    drawWidth: number;
+    drawHeight: number;
+    offsetX: number;
+    offsetY: number;
+};
+type PanOffset = {
+    panX: number;
+    panY: number;
+};
+type ComputeViewerImageLayoutParams = {
+    containerWidth: number;
+    containerHeight: number;
+    imageWidth: number;
+    imageHeight: number;
+    pan?: PanOffset;
+};
+declare function computeViewerImageLayout({ containerWidth, containerHeight, imageWidth, imageHeight, pan, }: ComputeViewerImageLayoutParams): ViewerImageLayout;
+declare function computeHotspotScreenPosition(hotspotX: number, hotspotY: number, layout: ViewerImageLayout, zoom: number): {
+    leftPercent: number;
+    topPercent: number;
+};
+declare function computeHotspotPositionFromClick(clientX: number, clientY: number, containerRect: DOMRect, layout: ViewerImageLayout, zoom: number): {
+    positionX: number;
+    positionY: number;
+};
+
+type UseViewer360Params<TData> = {
+    frames: Viewer360Frame[];
+    currentFrameIndex: number;
+    onFrameChange: (index: number) => void;
+    hotspots?: Viewer360Hotspot<TData>[];
+    config?: Viewer360Config;
+    hotspotMode?: boolean;
+    onHotspotAdd?: (position: Viewer360HotspotPosition) => void;
+};
+type UseViewer360Return<TData> = {
+    canvasRef: RefObject<HTMLCanvasElement | null>;
+    containerRef: RefObject<HTMLDivElement | null>;
+    currentFrame: Viewer360Frame | undefined;
+    currentFrameHotspots: Viewer360Hotspot<TData>[];
+    imagesLoaded: boolean;
+    isHotspotMode: boolean;
+    isResetDisabled: boolean;
+    maxZoom: number;
+    minZoom: number;
+    viewerCursorClass: string;
+    zoom: number;
+    getCurrentImageLayout: () => ViewerImageLayout | null;
+    getHotspotScreenPosition: (hotspot: Viewer360Hotspot<TData>) => {
+        leftPercent: number;
+        topPercent: number;
+    };
+    handleCanvasClick: (event: React.MouseEvent<HTMLDivElement>) => void;
+    handlePointerDown: (event: PointerEvent<HTMLDivElement>) => void;
+    handlePointerMove: (event: PointerEvent<HTMLDivElement>) => void;
+    handlePointerUp: (event: PointerEvent<HTMLDivElement>) => void;
+    handleResetView: () => void;
+    handleWheel: (event: WheelEvent<HTMLDivElement>) => void;
+    handleZoomIn: () => void;
+    handleZoomOut: () => void;
+};
+declare function useViewer360<TData = unknown>({ frames, hotspots, currentFrameIndex, onFrameChange, config, hotspotMode: hotspotModeProp, onHotspotAdd, }: UseViewer360Params<TData>): UseViewer360Return<TData>;
+
+type ResolvedViewer360Config = Required<Viewer360Config>;
+declare function resolveViewer360Config(config?: Viewer360Config): ResolvedViewer360Config;
+declare function clampZoom(zoom: number, config: ResolvedViewer360Config): number;
+declare function applyWheelZoom(currentZoom: number, deltaY: number, currentPan: PanOffset, config: ResolvedViewer360Config): {
+    zoom: number;
+    pan: PanOffset;
+};
+declare function stepZoomIn(currentZoom: number, config: ResolvedViewer360Config): number;
+declare function stepZoomOut(currentZoom: number, currentPan: PanOffset, config: ResolvedViewer360Config): {
+    zoom: number;
+    pan: PanOffset;
+};
+declare function isResetDisabled(zoom: number, pan: PanOffset, config: ResolvedViewer360Config): boolean;
+declare function getViewerCursorClass(isHotspotMode: boolean, zoom: number, isDragging: boolean, minZoom: number): string;
+
+declare function clampFrameIndex(index: number, frameCount: number): number;
+type DragStart = {
+    pointerX: number;
+    frameIndex: number;
+};
+declare function computeDragFrameIndex(dragStart: DragStart, clientX: number, frameCount: number, dragSensitivity: number): number | null;
+
+type PanStart = {
+    pointerX: number;
+    pointerY: number;
+    panX: number;
+    panY: number;
+};
+declare function computeViewerPanOffset(panStart: PanStart, clientX: number, clientY: number): PanOffset;
+
+declare function hotspotToViewer360Marker<TData>(hotspot: Viewer360Hotspot<TData>): Viewer360Marker;
+declare function toViewer360Hotspots<TData extends Viewer360Marker>(markers: Array<Viewer360Marker & {
+    frameIndex: number;
+    positionX: number;
+    positionY: number;
+}>, mapData?: (marker: Viewer360Marker & {
+    frameIndex: number;
+    positionX: number;
+    positionY: number;
+}) => TData): Viewer360Hotspot<TData>[];
+
+type DrawFrameOnCanvasParams = {
+    canvas: HTMLCanvasElement;
+    container: HTMLDivElement;
+    image: HTMLImageElement;
+    zoom: number;
+    pan: PanOffset;
+};
+declare function drawFrameOnCanvas({ canvas, container, image, zoom, pan }: DrawFrameOnCanvasParams): void;
+declare function getFramesSignature(frames: Viewer360Frame[]): string;
+declare function preloadFrameImage(frame: Viewer360Frame): Promise<HTMLImageElement>;
+declare function preloadViewerFrames(frames: Viewer360Frame[]): Promise<HTMLImageElement[]>;
+declare function hasLoadedViewerFrame(images: HTMLImageElement[]): boolean;
+declare function filterHotspotsByFrame<TData>(hotspots: Array<{
+    frameIndex: number;
+    data?: TData;
+}>, frameIndex: number): Array<{
+    frameIndex: number;
+    data?: TData;
+}>;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "link" | "secondary" | "destructive" | "outline" | "ghost" | null | undefined;
+    size?: "default" | "icon" | "sm" | "xs" | "lg" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ...props }: React$1.ComponentProps<'button'> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): JSX.Element;
+
+export { Button, Viewer360, Viewer360AddModeBanner, type Viewer360ClassNames, type Viewer360Config, type Viewer360Frame, Viewer360FrameIndicator, type Viewer360Hotspot, type Viewer360HotspotPinOptions, type Viewer360HotspotPosition, type Viewer360HotspotRenderProps, type Viewer360Labels, Viewer360LoadingOverlay, type Viewer360Marker, Viewer360MarkerPin, type Viewer360MarkerPinClassNames, type Viewer360MarkerPinLabels, type Viewer360MarkerPinProps, type Viewer360MarkerPinRenderProps, type Viewer360OverlayRenderProps, type Viewer360PanOffset, type Viewer360Props, type Viewer360Theme, Viewer360Toolbar, type Viewer360ToolbarRenderProps, type ViewerImageLayout, applyWheelZoom, buttonVariants, clampFrameIndex, clampZoom, cn, computeDragFrameIndex, computeHotspotPositionFromClick, computeHotspotScreenPosition, computeViewerImageLayout, computeViewerPanOffset, defaultViewer360ClassNames, defaultViewer360Config, defaultViewer360Labels, defaultViewer360MarkerPinClassNames, defaultViewer360MarkerPinLabels, drawFrameOnCanvas, filterHotspotsByFrame, getFramesSignature, getViewerCursorClass, hasLoadedViewerFrame, hotspotToViewer360Marker, isResetDisabled, preloadFrameImage, preloadViewerFrames, resolveViewer360Config, stepZoomIn, stepZoomOut, toViewer360Hotspots, useViewer360, viewer360ClassNames, viewer360MarkerPinClassNames };