@uibit/360-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 UIBit Contributors
+
+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,22 @@
+# 360 Viewer
+
+[Interactive Demonstration](https://rawlings.github.io/uibit/viewer-360)
+
+The 360 Viewer allows customers to explore products with tactile, interactive control. By converting a series of static images into an immersive, rotatable object, it provides a comprehensive look at physical products, building customer confidence and increasing conversion rates.
+
+## Value Delivery
+
+- **Purchase Confidence** – Customers can inspect details from any angle, simulating an in-store physical experience.
+- **Enhanced Engagement** – Interactive product exploration increases session times and strengthens user connection to products.
+- **Reduced Return Rates** – Detailed, multi-angle visual inspection ensures buyer expectations align with reality.
+- **Tactile Responsiveness** – Supports smooth drag-to-rotate interactions on desktop and natural touch controls on mobile devices.
+
+## Ideal Applications
+
+- **E-Commerce Showcases** – Premium product displays for retail, luxury goods, and consumer electronics.
+- **Interactive Catalogs** – Highlighting product features, textures, and craftsmanship.
+- **Product Portfolios** – Clean, minimal galleries for designers and manufacturers.
+
+## Further Information
+
+Detailed design guidelines, customizable attributes, and integration examples are available on our documentation site.

package/custom-elements.json

@@ -0,0 +1,461 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/360-viewer.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "360° product viewer driven by an array of sequential images.\nSupports drag, touch, auto-rotation, and keyboard controls.",
+          "name": "Viewer360",
+          "cssProperties": [
+            {
+              "description": "Background color of the viewer container",
+              "name": "--uibit-360-viewer-bg",
+              "default": "#f9fafb"
+            },
+            {
+              "description": "Border color of the viewer container",
+              "name": "--uibit-360-viewer-border",
+              "default": "#e5e7eb"
+            },
+            {
+              "description": "Background of control buttons",
+              "name": "--uibit-360-viewer-button-bg",
+              "default": "rgba(255,255,255,0.75)"
+            },
+            {
+              "description": "Hover background of control buttons",
+              "name": "--uibit-360-viewer-button-bg-hover",
+              "default": "rgba(255,255,255,0.95)"
+            },
+            {
+              "description": "Icon/text color of control buttons",
+              "name": "--uibit-360-viewer-button-color",
+              "default": "#374151"
+            },
+            {
+              "description": "Focus outline color for interactive elements",
+              "name": "--uibit-360-viewer-focus-color",
+              "default": "#000000"
+            },
+            {
+              "description": "Background of the progress bar track",
+              "name": "--uibit-360-viewer-progress-track-bg",
+              "default": "rgba(0,0,0,0.08)"
+            },
+            {
+              "description": "Background of the drag hint overlay",
+              "name": "--uibit-360-viewer-hint-bg",
+              "default": "rgba(17,24,39,0.65)"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "images",
+              "type": {
+                "text": "string[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "autoRotate",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Automatically rotate through frames when no user interaction is occurring.",
+              "attribute": "auto-rotate"
+            },
+            {
+              "kind": "field",
+              "name": "rotationSpeed",
+              "type": {
+                "text": "number"
+              },
+              "default": "150",
+              "description": "Milliseconds between frames during auto-rotation. Lower values spin faster.",
+              "attribute": "rotation-speed"
+            },
+            {
+              "kind": "field",
+              "name": "dragSensitivity",
+              "type": {
+                "text": "number"
+              },
+              "default": "15",
+              "description": "Horizontal pixel distance a drag must travel before advancing one frame.",
+              "attribute": "drag-sensitivity"
+            },
+            {
+              "kind": "field",
+              "name": "showControls",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Show the play/pause and directional control buttons.",
+              "attribute": "show-controls"
+            },
+            {
+              "kind": "field",
+              "name": "showProgressBar",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Show the frame progress bar at the bottom of the viewer.",
+              "attribute": "show-progress-bar"
+            },
+            {
+              "kind": "field",
+              "name": "currentIndex",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "isDragging",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "firstFrameReady",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "aspectRatio",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "'16 / 9'"
+            },
+            {
+              "kind": "field",
+              "name": "autoRotateTimer",
+              "type": {
+                "text": "number | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "resumeTimer",
+              "type": {
+                "text": "number | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "startX",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "startImageIndex",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "method",
+              "name": "startAutoRotate",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "stopAutoRotate",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "scheduleAutoRotateResume",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "clearResumeTimer",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "handleFrameLoad",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                },
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "next"
+            },
+            {
+              "kind": "method",
+              "name": "prev"
+            },
+            {
+              "kind": "method",
+              "name": "emitChange",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "handlePointerDown",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "PointerEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "handlePointerMove",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "PointerEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "handlePointerUp",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "PointerEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "handleKeyDown",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "handleSlotChange",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
+            }
+          ],
+          "events": [
+            {
+              "type": {
+                "text": "{ index: number, total: number }"
+              },
+              "description": "Fired each time the displayed frame changes",
+              "name": "change"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "auto-rotate",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Automatically rotate through frames when no user interaction is occurring.",
+              "fieldName": "autoRotate"
+            },
+            {
+              "name": "rotation-speed",
+              "type": {
+                "text": "number"
+              },
+              "default": "150",
+              "description": "Milliseconds between frames during auto-rotation. Lower values spin faster.",
+              "fieldName": "rotationSpeed"
+            },
+            {
+              "name": "drag-sensitivity",
+              "type": {
+                "text": "number"
+              },
+              "default": "15",
+              "description": "Horizontal pixel distance a drag must travel before advancing one frame.",
+              "fieldName": "dragSensitivity"
+            },
+            {
+              "name": "show-controls",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Show the play/pause and directional control buttons.",
+              "fieldName": "showControls"
+            },
+            {
+              "name": "show-progress-bar",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Show the frame progress bar at the bottom of the viewer.",
+              "fieldName": "showProgressBar"
+            }
+          ],
+          "superclass": {
+            "name": "UIBitElement",
+            "package": "@uibit/core"
+          },
+          "tagName": "uibit-360-viewer",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "Viewer360",
+          "declaration": {
+            "name": "Viewer360",
+            "module": "src/360-viewer.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "uibit-360-viewer",
+          "declaration": {
+            "name": "Viewer360",
+            "module": "src/360-viewer.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "Viewer360",
+            "module": "src/360-viewer.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "default",
+            "module": "./360-viewer"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "Viewer360",
+          "declaration": {
+            "name": "Viewer360",
+            "module": "./360-viewer"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "Viewer360Config",
+          "declaration": {
+            "name": "Viewer360Config",
+            "module": "./types"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "Hotspot360",
+          "declaration": {
+            "name": "Hotspot360",
+            "module": "./types"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/styles.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "styles",
+          "default": "css` :host { --uibit-360-viewer-bg: #f9fafb; --uibit-360-viewer-border: #e5e7eb; --uibit-360-viewer-button-bg: rgba(255, 255, 255, 0.75); --uibit-360-viewer-button-bg-hover: rgba(255, 255, 255, 0.95); --uibit-360-viewer-button-color: #374151; --uibit-360-viewer-focus-color: #000000; --uibit-360-viewer-progress-track-bg: rgba(0, 0, 0, 0.08); --uibit-360-viewer-hint-bg: rgba(17, 24, 39, 0.65); display: block; width: 100%; } .viewer { position: relative; width: 100%; overflow: hidden; background: var(--uibit-360-viewer-bg); border: 0.0625rem solid var(--uibit-360-viewer-border); touch-action: none; user-select: none; -webkit-user-drag: none; outline: none; min-height: 4rem; } .viewer:focus-visible { box-shadow: 0 0 0 0.125rem var(--uibit-360-viewer-focus-color); } .frames { position: relative; width: 100%; overflow: hidden; } .frames:not(.ready) { visibility: hidden; } .frame { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; pointer-events: none; user-select: none; -webkit-user-drag: none; opacity: 0; will-change: opacity; } .frame-active { opacity: 1; } @keyframes shimmer { 0% { background-position: -200% 0; } 100% { background-position: 200% 0; } } .skeleton { position: absolute; inset: 0; background: linear-gradient( 90deg, var(--uibit-360-viewer-bg) 25%, rgba(0, 0, 0, 0.06) 50%, var(--uibit-360-viewer-bg) 75% ); background-size: 200% 100%; animation: shimmer 1.4s ease infinite; aspect-ratio: inherit; } .nav-button { position: absolute; top: 50%; transform: translateY(-50%); background: var(--uibit-360-viewer-button-bg, rgba(255, 255, 255, 0.75)); backdrop-filter: blur(0.5rem); -webkit-backdrop-filter: blur(0.5rem); border: none; color: var(--uibit-360-viewer-button-color, #111827); width: 2.25rem; height: 2.25rem; border-radius: 9999rem; display: flex; align-items: center; justify-content: center; cursor: pointer; opacity: 0; z-index: 10; box-shadow: none; transition: opacity 250ms ease, background-color 150ms ease, color 150ms ease, transform 150ms ease; } .viewer:hover .nav-button, .nav-button:focus-visible { opacity: 1; } .nav-button:focus-visible { outline: 0.125rem solid var(--uibit-360-viewer-focus-color, #000000); outline-offset: 0.125rem; } .nav-button:hover { background: var(--uibit-360-viewer-button-bg-hover, rgba(255, 255, 255, 0.95)); color: #000000; box-shadow: none; } .nav-button-prev:hover { transform: translateY(-50%) translateX(-0.125rem) scale(1.05); } .nav-button-next:hover { transform: translateY(-50%) translateX(0.125rem) scale(1.05); } .nav-button:active { transform: translateY(-50%) scale(0.95); } .nav-button-prev { left: 0.75rem; } .nav-button-next { right: 0.75rem; } .nav-button svg { width: 1.125rem; height: 1.125rem; } .drag-hint { position: absolute; bottom: 0.75rem; left: 50%; transform: translateX(-50%); background: var(--uibit-360-viewer-hint-bg, rgba(17, 24, 39, 0.65)); color: #ffffff; padding: 0.375rem 0.75rem; border-radius: 9999rem; font-size: 0.75rem; pointer-events: none; opacity: 0.85; transition: opacity 300ms ease; display: flex; align-items: center; gap: 0.375rem; backdrop-filter: blur(0.25rem); -webkit-backdrop-filter: blur(0.25rem); z-index: 5; } .viewer.dragging .drag-hint { opacity: 0; } .progress-track { position: absolute; bottom: 0; left: 0; width: 100%; height: 0.1875rem; background: var(--uibit-360-viewer-progress-track-bg, rgba(0, 0, 0, 0.08)); z-index: 5; } .progress-bar { height: 100%; background: var(--uibit-360-viewer-focus-color, #000000); transition: width 100ms ease; } .sr-only { position: absolute; width: 0.0625rem; height: 0.0625rem; padding: 0; margin: -0.0625rem; overflow: hidden; clip: rect(0, 0, 0, 0); border: 0; } `"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "styles",
+          "declaration": {
+            "name": "styles",
+            "module": "src/styles.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/types.ts",
+      "declarations": [],
+      "exports": []
+    }
+  ]
+}

package/dist/360-viewer.d.ts

@@ -0,0 +1,57 @@
+import { UIBitElement } from '@uibit/core';
+/**
+ * 360° product viewer driven by an array of sequential images.
+ * Supports drag, touch, auto-rotation, and keyboard controls.
+ *
+ * @fires {{ index: number, total: number }} change - Fired each time the displayed frame changes
+ *
+ * @cssprop [--uibit-360-viewer-bg=#f9fafb] - Background color of the viewer container
+ * @cssprop [--uibit-360-viewer-border=#e5e7eb] - Border color of the viewer container
+ * @cssprop [--uibit-360-viewer-button-bg=rgba(255,255,255,0.75)] - Background of control buttons
+ * @cssprop [--uibit-360-viewer-button-bg-hover=rgba(255,255,255,0.95)] - Hover background of control buttons
+ * @cssprop [--uibit-360-viewer-button-color=#374151] - Icon/text color of control buttons
+ * @cssprop [--uibit-360-viewer-focus-color=#000000] - Focus outline color for interactive elements
+ * @cssprop [--uibit-360-viewer-progress-track-bg=rgba(0,0,0,0.08)] - Background of the progress bar track
+ * @cssprop [--uibit-360-viewer-hint-bg=rgba(17,24,39,0.65)] - Background of the drag hint overlay
+ */
+export declare class Viewer360 extends UIBitElement {
+    static styles: import("lit").CSSResult;
+    private images;
+    /** Automatically rotate through frames when no user interaction is occurring. */
+    autoRotate: boolean;
+    /** Milliseconds between frames during auto-rotation. Lower values spin faster. */
+    rotationSpeed: number;
+    /** Horizontal pixel distance a drag must travel before advancing one frame. */
+    dragSensitivity: number;
+    /** Show the play/pause and directional control buttons. */
+    showControls: boolean;
+    /** Show the frame progress bar at the bottom of the viewer. */
+    showProgressBar: boolean;
+    private currentIndex;
+    private isDragging;
+    private firstFrameReady;
+    private aspectRatio;
+    private autoRotateTimer?;
+    private resumeTimer?;
+    private startX;
+    private startImageIndex;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changedProperties: Map<string, unknown>): void;
+    private startAutoRotate;
+    private stopAutoRotate;
+    private scheduleAutoRotateResume;
+    private clearResumeTimer;
+    private handleFrameLoad;
+    next(): void;
+    prev(): void;
+    private emitChange;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handleKeyDown;
+    private handleSlotChange;
+    render(): import("lit").TemplateResult<1>;
+}
+export default Viewer360;
+//# sourceMappingURL=360-viewer.d.ts.map

package/dist/360-viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"360-viewer.d.ts","sourceRoot":"","sources":["../src/360-viewer.ts"],"names":[],"mappings":"AACA,OAAO,EAA2C,YAAY,EAAE,MAAM,aAAa,CAAC;AAKpF;;;;;;;;;;;;;;GAcG;AACH,qBACa,SAAU,SAAQ,YAAY;IACzC,MAAM,CAAC,MAAM,0BAAU;IAEd,OAAO,CAAC,MAAM,CAAgB;IACvC,iFAAiF;IAC1B,UAAU,UAAS;IAC1E,kFAAkF;IACzB,aAAa,SAAO;IAC7E,+EAA+E;IACpB,eAAe,SAAM;IAChF,2DAA2D;IACF,YAAY,UAAQ;IAC7E,+DAA+D;IACF,eAAe,UAAQ;IAE3E,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,WAAW,CAAY;IAExC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,eAAe,CAAK;IAE5B,iBAAiB,SAEhB;IAED,oBAAoB,SAInB;IAED,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,QAa9C;IAED,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,eAAe;IAWvB,IAAI,SAIH;IAED,IAAI,SAIH;IAED,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,gBAAgB;IAUxB,MAAM,oCA4FL;CACF;eAEc,SAAS"}