@mmmmzxe/react-360-viewer 0.1.0

package/src/components/ui/Label/index.tsx

@@ -0,0 +1,20 @@
+'use client';
+
+import * as React from 'react';
+
+import { cn } from '@/components/utils';
+
+function Label({ className, ...props }: React.ComponentProps<'label'>): React.ReactNode {
+    return (
+        <label
+            data-slot="label"
+            className={cn(
+                'gap-2 text-sm leading-none font-medium group-data-[disabled=true]:opacity-50 peer-disabled:opacity-50 flex items-center select-none group-data-[disabled=true]:pointer-events-none peer-disabled:cursor-not-allowed',
+                className
+            )}
+            {...props}
+        />
+    );
+}
+
+export { Label };

package/src/components/ui/Popover/index.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import * as React from 'react';
+import type { JSX } from 'react';
+
+import { Popover as PopoverPrimitive } from 'radix-ui';
+
+import { cn } from '@/components/utils';
+
+function Popover({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Root>): JSX.Element {
+    return <PopoverPrimitive.Root data-slot="popover" {...props} />;
+}
+
+function PopoverTrigger({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Trigger>): JSX.Element {
+    return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />;
+}
+
+function PopoverContent({
+    className,
+    align = 'center',
+    sideOffset = 4,
+    ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Content>): JSX.Element {
+    return (
+        <PopoverPrimitive.Portal>
+            <PopoverPrimitive.Content
+                data-slot="popover-content"
+                align={align}
+                sideOffset={sideOffset}
+                className={cn(
+                    'bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=start]:slide-in-from-end-2 data-[side=end]:slide-in-from-start-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 flex flex-col gap-4 rounded-md p-4 text-sm shadow-md ring-1 duration-100 z-50 w-72 origin-(--radix-popover-content-transform-origin) outline-hidden',
+                    className
+                )}
+                {...props}
+            />
+        </PopoverPrimitive.Portal>
+    );
+}
+
+function PopoverAnchor({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Anchor>): JSX.Element {
+    return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />;
+}
+
+function PopoverHeader({ className, ...props }: React.ComponentProps<'div'>): JSX.Element {
+    return <div data-slot="popover-header" className={cn('flex flex-col gap-1 text-sm', className)} {...props} />;
+}
+
+function PopoverTitle({ className, ...props }: React.ComponentProps<'h2'>): JSX.Element {
+    return <div data-slot="popover-title" className={cn('font-medium', className)} {...props} />;
+}
+
+function PopoverDescription({ className, ...props }: React.ComponentProps<'p'>): JSX.Element {
+    return <p data-slot="popover-description" className={cn('text-muted-foreground', className)} {...props} />;
+}
+
+export { Popover, PopoverAnchor, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger };

package/src/components/ui/Separator/index.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import * as React from 'react';
+import type { JSX } from 'react';
+
+import { Separator as SeparatorPrimitive } from 'radix-ui';
+
+import { cn } from '@/components/utils';
+
+function Separator({
+    className,
+    orientation = 'horizontal',
+    decorative = true,
+    ...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>): JSX.Element {
+    return (
+        <SeparatorPrimitive.Root
+            data-slot="separator"
+            decorative={decorative}
+            orientation={orientation}
+            className={cn(
+                'bg-border shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:w-px data-[orientation=vertical]:self-stretch',
+                className
+            )}
+            {...props}
+        />
+    );
+}
+
+export { Separator };

package/src/components/ui/Spinner/index.tsx

@@ -0,0 +1,11 @@
+import type { JSX } from 'react';
+
+import { Loader2Icon } from 'lucide-react';
+
+import { cn } from '@/components/utils';
+
+function Spinner({ className, ...props }: React.ComponentProps<'svg'>): JSX.Element {
+    return <Loader2Icon role="status" aria-label="Loading" className={cn('size-4 animate-spin', className)} {...props} />;
+}
+
+export { Spinner };

package/src/components/utils/index.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+}

package/src/constants/viewer360ClassNames.ts

@@ -0,0 +1,41 @@
+import type { Viewer360ClassNames } from '../types/Viewer360Props';
+import type { Viewer360MarkerPinClassNames } from '../types/Viewer360Marker';
+
+export const viewer360ClassNames: Required<Viewer360ClassNames> = {
+    root: 'overflow-hidden rounded-lg border bg-card text-card-foreground',
+    viewport: 'relative aspect-[16/10] w-full touch-none select-none bg-muted',
+    canvas: 'absolute inset-0 size-full',
+    overlay: 'pointer-events-none absolute inset-0 overflow-hidden',
+    loading: 'absolute inset-0 flex items-center justify-center bg-muted/80',
+    loadingText: 'text-sm text-muted-foreground',
+    frameIndicator:
+        'pointer-events-none absolute bottom-4 start-1/2 z-20 -translate-x-1/2 rounded-full border bg-background px-4 py-1.5 text-xs font-medium shadow-sm',
+    hotspotModeBanner:
+        'pointer-events-none absolute top-4 start-1/2 z-20 -translate-x-1/2 rounded-full border border-amber-200 bg-amber-50 px-4 py-1.5 text-xs font-medium text-amber-800 dark:border-amber-500/30 dark:bg-amber-500/10 dark:text-amber-400',
+    toolbar: 'flex flex-wrap items-center justify-between gap-2 border-t px-4 py-3',
+    dragHint: 'hidden text-xs text-muted-foreground sm:block',
+    controls: 'ms-auto flex items-center gap-1.5',
+    controlButton: '',
+    controlButtonActive: '',
+    controlButtonDisabled: '',
+    zoomDisplay: 'flex min-w-[3rem] items-center justify-center gap-1 rounded-md border bg-background px-2 py-1 text-xs font-medium',
+    divider: 'mx-1 h-6 w-px bg-border',
+};
+
+export const viewer360MarkerPinClassNames: Required<Viewer360MarkerPinClassNames> = {
+    root: 'pointer-events-auto absolute z-30 -translate-x-1/2 -translate-y-1/2',
+    ping: 'absolute inline-flex size-6 -translate-x-1/4 -translate-y-1/4 animate-ping rounded-full bg-destructive opacity-60',
+    dot: 'relative flex size-4 items-center justify-center rounded-full border-2 border-background bg-destructive shadow-md transition-transform duration-200 hover:scale-125 focus:outline-none',
+    tooltip: 'absolute bottom-6 left-1/2 z-40 w-64 -translate-x-1/2 rounded-lg border bg-popover p-3 text-popover-foreground shadow-md',
+    tooltipHeader: 'flex items-start justify-between gap-2',
+    tooltipBody: 'flex min-w-0 flex-col gap-1',
+    tooltipTitle: 'text-sm font-medium',
+    tooltipDescription: 'mt-2 line-clamp-3 text-xs text-muted-foreground',
+    deleteButton: '',
+};
+
+/** @deprecated Use `viewer360ClassNames` */
+export const defaultViewer360ClassNames = viewer360ClassNames;
+
+/** @deprecated Use `viewer360MarkerPinClassNames` */
+export const defaultViewer360MarkerPinClassNames = viewer360MarkerPinClassNames;

package/src/constants/viewer360Config.ts

@@ -0,0 +1,11 @@
+export const viewer360Config = {
+    minZoom: 1,
+    maxZoom: 3,
+    zoomStep: 0.15,
+    dragSensitivity: 8,
+    autoRotate: false,
+    autoRotateIntervalMs: 100,
+    autoRotateDirection: 'forward' as const,
+};
+
+export const defaultViewer360Config = viewer360Config;

package/src/constants/viewer360Labels.ts

@@ -0,0 +1,14 @@
+import type { Viewer360Labels } from '../types/Viewer360Props';
+
+export const defaultViewer360Labels: Required<Viewer360Labels> = {
+    loading: 'Loading images…',
+    dragHint: 'Drag to rotate • Scroll to zoom',
+    frameIndicator: ({ current, total, label }) => (label ? `${label} (${current}/${total})` : `${current} / ${total}`),
+    zoom: (percent) => `${percent}%`,
+    hotspotModeActive: 'Click on the image to place a hotspot',
+    addHotspot: 'Add hotspot',
+    zoomIn: 'Zoom in',
+    zoomOut: 'Zoom out',
+    resetView: 'Reset view',
+    deleteMarker: 'Remove marker',
+};

package/src/constants/viewer360MarkerLabels.ts

@@ -0,0 +1,3 @@
+export const defaultViewer360MarkerPinLabels = {
+    delete: 'Remove marker',
+} as const;

package/src/feature/Viewer360.test.tsx

@@ -0,0 +1,47 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { Viewer360 } from './Viewer360';
+import type { Viewer360Frame } from '../types';
+
+const frames: Viewer360Frame[] = [
+    { id: '1', src: 'https://example.com/1.jpg', label: 'Front' },
+    { id: '2', src: 'https://example.com/2.jpg', label: 'Side' },
+];
+
+describe('Viewer360', () => {
+    it('renders loading state and toolbar labels', () => {
+        render(
+            <Viewer360
+                frames={frames}
+                labels={{
+                    loading: 'Loading test frames',
+                    dragHint: 'Drag test hint',
+                }}
+            />
+        );
+
+        expect(screen.getByText('Loading test frames')).toBeInTheDocument();
+        expect(screen.getByText('Drag test hint')).toBeInTheDocument();
+    });
+
+    it('calls onFrameChange from auto-rotate when enabled', () => {
+        vi.useFakeTimers();
+
+        const onFrameChange = vi.fn();
+
+        render(
+            <Viewer360
+                frames={frames}
+                currentFrameIndex={0}
+                onFrameChange={onFrameChange}
+                config={{ autoRotate: true, autoRotateIntervalMs: 50 }}
+            />
+        );
+
+        vi.advanceTimersByTime(60);
+        expect(onFrameChange).toHaveBeenCalledWith(1);
+
+        vi.useRealTimers();
+    });
+});

package/src/feature/Viewer360.tsx

@@ -0,0 +1,218 @@
+import type { JSX } from 'react';
+import { useEffect, useMemo, useState } from 'react';
+
+import { buildViewer360ThemeStyle, mergeViewer360ClassNames, mergeViewer360Labels } from '../helpers/viewer360PropsHelpers';
+import { useViewer360 } from '../hooks/useViewer360';
+import type { Viewer360OverlayRenderProps, Viewer360Props, Viewer360ToolbarRenderProps } from '../types';
+import { Card } from '@/components/ui/Card';
+import { cn } from '@/components/utils';
+
+import { Viewer360AddModeBanner } from './Viewer360AddModeBanner';
+import { Viewer360FrameIndicator } from './Viewer360FrameIndicator';
+import { Viewer360HotspotOverlay } from './Viewer360HotspotOverlay';
+import { Viewer360LoadingOverlay } from './Viewer360LoadingOverlay';
+import { Viewer360Toolbar } from './Viewer360Toolbar';
+
+export function Viewer360<TData = unknown>({
+    frames,
+    currentFrameIndex: controlledFrameIndex,
+    defaultFrameIndex = 0,
+    onFrameChange,
+    config,
+    className,
+    classNames,
+    style,
+    theme,
+    labels,
+    aspectRatio = '16 / 10',
+    showZoomControls = true,
+    showResetControl = true,
+    showFrameIndicator = true,
+    showDragHint = true,
+    showHotspotModeControl = false,
+    hotspotPin,
+    hotspots = [],
+    renderHotspot,
+    renderLoading,
+    renderFrameIndicator,
+    renderHotspotModeBanner,
+    renderToolbar,
+    onHotspotClick,
+    hotspotMode: controlledHotspotMode,
+    defaultHotspotMode = false,
+    onHotspotModeChange,
+    onHotspotAdd,
+    children,
+}: Viewer360Props<TData>): JSX.Element {
+    // ----------------------------------------------------------------------------------------------------
+    // MARK: States & Constants
+    // ----------------------------------------------------------------------------------------------------
+    const mergedLabels = useMemo(() => mergeViewer360Labels(labels), [labels]);
+    const mergedClassNames = useMemo(() => mergeViewer360ClassNames(classNames), [classNames]);
+    const themeStyle = useMemo(() => buildViewer360ThemeStyle(theme), [theme]);
+
+    const [internalFrameIndex, setInternalFrameIndex] = useState(defaultFrameIndex);
+    const [internalHotspotMode, setInternalHotspotMode] = useState(defaultHotspotMode);
+
+    const currentFrameIndex = controlledFrameIndex ?? internalFrameIndex;
+    const hotspotMode = controlledHotspotMode ?? internalHotspotMode;
+
+    // ----------------------------------------------------------------------------------------------------
+    // MARK: Functions
+    // ----------------------------------------------------------------------------------------------------
+    function handleFrameChange(index: number): void {
+        if (controlledFrameIndex === undefined) {
+            setInternalFrameIndex(index);
+        }
+
+        onFrameChange?.(index);
+    }
+
+    function handleHotspotModeChange(active: boolean): void {
+        if (controlledHotspotMode === undefined) {
+            setInternalHotspotMode(active);
+        }
+
+        onHotspotModeChange?.(active);
+    }
+
+    const {
+        canvasRef,
+        containerRef,
+        currentFrame,
+        currentFrameHotspots,
+        imagesLoaded,
+        isHotspotMode,
+        isResetDisabled,
+        maxZoom,
+        minZoom,
+        viewerCursorClass,
+        zoom,
+        getHotspotScreenPosition,
+        handleCanvasClick,
+        handlePointerDown,
+        handlePointerMove,
+        handlePointerUp,
+        handleWheel,
+        handleResetView,
+        handleZoomIn,
+        handleZoomOut,
+    } = useViewer360<TData>({
+        frames,
+        hotspots,
+        currentFrameIndex,
+        onFrameChange: handleFrameChange,
+        config,
+        hotspotMode,
+        onHotspotAdd,
+    });
+
+    useEffect(() => {
+        if (controlledHotspotMode === undefined) return;
+        if (controlledHotspotMode !== internalHotspotMode) {
+            setInternalHotspotMode(controlledHotspotMode);
+        }
+    }, [controlledHotspotMode, internalHotspotMode]);
+
+    const frameLabel = currentFrame?.label ?? frames[currentFrameIndex]?.label;
+    const overlayProps: Viewer360OverlayRenderProps = {
+        currentFrameIndex,
+        frameCount: frames.length,
+        frameLabel,
+        isHotspotMode,
+        labels: mergedLabels,
+    };
+    const toolbarProps: Viewer360ToolbarRenderProps = {
+        zoom,
+        minZoom,
+        maxZoom,
+        isResetDisabled,
+        isHotspotMode,
+        showHotspotModeControl,
+        showZoomControls,
+        showResetControl,
+        showDragHint,
+        labels: mergedLabels,
+        onZoomIn: handleZoomIn,
+        onZoomOut: handleZoomOut,
+        onResetView: handleResetView,
+        onHotspotModeChange: handleHotspotModeChange,
+    };
+    const showDefaultToolbar = showZoomControls || showResetControl || showHotspotModeControl || showDragHint;
+
+    // ----------------------------------------------------------------------------------------------------
+    // MARK: Main Component UI
+    // ----------------------------------------------------------------------------------------------------
+    return (
+        <Card className={cn(mergedClassNames.root, 'gap-0 py-0 shadow-none ring-0', className)} style={{ ...themeStyle, ...style }}>
+            <div
+                ref={containerRef}
+                className={cn(mergedClassNames.viewport, viewerCursorClass)}
+                style={{ aspectRatio }}
+                onPointerDown={handlePointerDown}
+                onPointerMove={handlePointerMove}
+                onPointerUp={handlePointerUp}
+                onPointerLeave={handlePointerUp}
+                onWheel={handleWheel}
+                onClick={handleCanvasClick}
+            >
+                <canvas ref={canvasRef} className={mergedClassNames.canvas} />
+
+                <div className={mergedClassNames.overlay}>
+                    {currentFrameHotspots.map((hotspot) => {
+                        const position = getHotspotScreenPosition(hotspot);
+
+                        return (
+                            <Viewer360HotspotOverlay
+                                key={hotspot.id}
+                                hotspot={hotspot}
+                                leftPercent={position.leftPercent}
+                                topPercent={position.topPercent}
+                                hotspotPin={hotspotPin}
+                                renderHotspot={renderHotspot}
+                                onHotspotClick={onHotspotClick}
+                            />
+                        );
+                    })}
+                    {children}
+                </div>
+
+                {!imagesLoaded &&
+                    (renderLoading ? (
+                        renderLoading()
+                    ) : (
+                        <Viewer360LoadingOverlay
+                            className={mergedClassNames.loading}
+                            textClassName={mergedClassNames.loadingText}
+                            label={mergedLabels.loading}
+                        />
+                    ))}
+
+                {showFrameIndicator &&
+                    frames.length > 0 &&
+                    (renderFrameIndicator ? (
+                        renderFrameIndicator(overlayProps)
+                    ) : (
+                        <Viewer360FrameIndicator
+                            className={mergedClassNames.frameIndicator}
+                            label={mergedLabels.frameIndicator({
+                                current: currentFrameIndex + 1,
+                                total: frames.length,
+                                label: frameLabel,
+                            })}
+                        />
+                    ))}
+
+                {isHotspotMode &&
+                    onHotspotAdd &&
+                    (renderHotspotModeBanner ? (
+                        renderHotspotModeBanner({ labels: mergedLabels })
+                    ) : (
+                        <Viewer360AddModeBanner className={mergedClassNames.hotspotModeBanner} label={mergedLabels.hotspotModeActive} />
+                    ))}
+            </div>
+
+            {renderToolbar ? renderToolbar(toolbarProps) : showDefaultToolbar ? <Viewer360Toolbar {...toolbarProps} /> : null}
+        </Card>
+    );
+}

package/src/feature/Viewer360AddModeBanner.tsx

@@ -0,0 +1,20 @@
+import type { JSX } from 'react';
+
+import { Badge } from '@/components/ui/Badge';
+import { cn } from '@/components/utils';
+
+type Viewer360AddModeBannerProps = {
+    className?: string;
+    label: string;
+};
+
+export function Viewer360AddModeBanner({ className, label }: Viewer360AddModeBannerProps): JSX.Element {
+    // ----------------------------------------------------------------------------------------------------
+    // MARK: Main Component UI
+    // ----------------------------------------------------------------------------------------------------
+    return (
+        <Badge variant="outline" className={cn('pointer-events-none', className)}>
+            {label}
+        </Badge>
+    );
+}

package/src/feature/Viewer360FrameIndicator.tsx

@@ -0,0 +1,20 @@
+import type { JSX } from 'react';
+
+import { Badge } from '@/components/ui/Badge';
+import { cn } from '@/components/utils';
+
+type Viewer360FrameIndicatorProps = {
+    className?: string;
+    label: string;
+};
+
+export function Viewer360FrameIndicator({ className, label }: Viewer360FrameIndicatorProps): JSX.Element {
+    // ----------------------------------------------------------------------------------------------------
+    // MARK: Main Component UI
+    // ----------------------------------------------------------------------------------------------------
+    return (
+        <Badge variant="outline" className={cn('pointer-events-none shadow-sm', className)}>
+            {label}
+        </Badge>
+    );
+}

package/src/feature/Viewer360HotspotOverlay.tsx

@@ -0,0 +1,70 @@
+import type { JSX, MouseEvent, ReactNode } from 'react';
+
+import { hotspotToViewer360Marker } from '../helpers/markerHelpers';
+import type { Viewer360Hotspot, Viewer360HotspotPinOptions, Viewer360HotspotRenderProps } from '../types';
+import { Button } from '@/components/ui/Button';
+import { Item } from '@/components/ui/Item';
+import { cn } from '@/components/utils';
+
+import { Viewer360MarkerPin } from './Viewer360MarkerPin';
+
+type Viewer360HotspotOverlayProps<TData = unknown> = {
+    hotspot: Viewer360Hotspot<TData>;
+    leftPercent: number;
+    topPercent: number;
+    hotspotPin?: Viewer360HotspotPinOptions<TData>;
+    renderHotspot?: (props: Viewer360HotspotRenderProps<TData>) => ReactNode;
+    onHotspotClick?: (hotspot: Viewer360Hotspot<TData>, event: MouseEvent<HTMLDivElement>) => void;
+};
+
+export function Viewer360HotspotOverlay<TData = unknown>({
+    hotspot,
+    leftPercent,
+    topPercent,
+    hotspotPin,
+    renderHotspot,
+    onHotspotClick,
+}: Viewer360HotspotOverlayProps<TData>): JSX.Element {
+    // ----------------------------------------------------------------------------------------------------
+    // MARK: Main Component UI
+    // ----------------------------------------------------------------------------------------------------
+    if (renderHotspot) {
+        return (
+            <Item size="xs" variant="default" className="pointer-events-auto w-auto border-transparent p-0">
+                {renderHotspot({ hotspot, leftPercent, topPercent })}
+            </Item>
+        );
+    }
+
+    if (hotspotPin) {
+        const marker = hotspotPin.getMarker?.(hotspot) ?? hotspotToViewer360Marker(hotspot);
+
+        return (
+            <Viewer360MarkerPin
+                marker={marker}
+                hotspot={hotspot}
+                leftPercent={leftPercent}
+                topPercent={topPercent}
+                onDelete={hotspotPin.onDelete}
+                isDeletePending={hotspotPin.deletingMarkerId === hotspot.id}
+                renderTag={hotspotPin.renderTag}
+                classNames={hotspotPin.classNames}
+                labels={hotspotPin.labels}
+            />
+        );
+    }
+
+    return (
+        <Button
+            type="button"
+            variant="destructive"
+            size="icon-xs"
+            className={cn(
+                'pointer-events-auto absolute z-30 size-4 min-h-4 min-w-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-background bg-destructive p-0 shadow-md hover:bg-destructive'
+            )}
+            style={{ left: `${leftPercent}%`, top: `${topPercent}%` }}
+            aria-label={`Hotspot ${hotspot.id}`}
+            onClick={(event) => onHotspotClick?.(hotspot, event as unknown as MouseEvent<HTMLDivElement>)}
+        />
+    );
+}

package/src/feature/Viewer360LoadingOverlay.tsx

@@ -0,0 +1,28 @@
+import type { JSX } from 'react';
+
+import { Item } from '@/components/ui/Item';
+import { Label } from '@/components/ui/Label';
+import { Spinner } from '@/components/ui/Spinner';
+import { cn } from '@/components/utils';
+
+type Viewer360LoadingOverlayProps = {
+    className?: string;
+    textClassName?: string;
+    label: string;
+};
+
+export function Viewer360LoadingOverlay({ className, textClassName, label }: Viewer360LoadingOverlayProps): JSX.Element {
+    // ----------------------------------------------------------------------------------------------------
+    // MARK: Main Component UI
+    // ----------------------------------------------------------------------------------------------------
+    return (
+        <Item
+            size="sm"
+            variant="muted"
+            className={cn('pointer-events-none w-auto justify-center border-transparent bg-muted/80', className)}
+        >
+            <Spinner className="size-5 text-muted-foreground" />
+            <Label className={cn('font-normal text-muted-foreground', textClassName)}>{label}</Label>
+        </Item>
+    );
+}