lite-image-preview 1.0.0

package/src/types.ts

@@ -0,0 +1,98 @@
+/**
+ * A 2D point in viewport/client coordinates.
+ */
+export type Point = {
+    x: number
+    y: number
+}
+
+/**
+ * A simple transform state used by the default transform-based adapter.
+ */
+export type TransformState = {
+    scale: number
+    x: number
+    y: number
+}
+
+/**
+ * An SVG viewBox rectangle.
+ */
+export type ViewBox = {
+    x: number
+    y: number
+    w: number
+    h: number
+}
+
+/**
+ * A function that closes an opened preview dialog.
+ */
+export type PreviewCloseHandle = () => void
+
+/**
+ * The minimum controller interface used by the preview container.
+ * Custom adapters may extend this behavior, but these methods are required.
+ */
+export interface PreviewController {
+    /**
+     * Zoom in or out using a wheel event.
+     * Implementations should call preventDefault() when appropriate.
+     */
+    zoomWithWheel: (e: WheelEvent) => void
+
+    /**
+     * Release listeners and internal state created by the adapter.
+     */
+    destroy: () => void
+
+    /**
+     * Restore the element's inline styles or attributes back to the pre-preview state.
+     */
+    resetStyle: () => void
+}
+
+/**
+ * The public adapter interface used by createPreview.
+ *
+ * The preview container handles dialog lifecycle and gesture routing,
+ * while the adapter owns the actual rendering backend.
+ * For example:
+ * - image previews can use CSS transform
+ * - SVG previews can use viewBox
+ */
+export interface PreviewAdapter extends PreviewController {
+    /**
+     * Reset the visual state to the initial "fit to stage" layout.
+     */
+    fitToStage: (stage: HTMLElement) => void
+
+    /**
+     * Move the content by a delta measured in client pixels.
+     */
+    panBy: (dx: number, dy: number) => void
+
+    /**
+     * Zoom around a specific client coordinate.
+     *
+     * @param clientX - Client X coordinate.
+     * @param clientY - Client Y coordinate.
+     * @param factor - Multiplicative zoom factor.
+     */
+    zoomAt: (clientX: number, clientY: number, factor: number) => void
+
+    /**
+     * Start a pinch gesture using two points in client coordinates.
+     */
+    beginPinch: (points: [Point, Point]) => void
+
+    /**
+     * Update an active pinch gesture using two points in client coordinates.
+     */
+    updatePinch: (points: [Point, Point]) => void
+}
+
+/**
+ * Factory function used by createPreview to initialize a rendering adapter.
+ */
+export type PreviewAdapterFactory = (stage: HTMLElement) => PreviewAdapter

package/src/util.ts

@@ -0,0 +1,102 @@
+import type { Point, ViewBox } from './types'
+
+/**
+ * Clamp a number into the given range.
+ */
+export function clamp(n: number, min: number, max: number) {
+    return Math.min(max, Math.max(min, n))
+}
+
+/**
+ * Return whether a value is a finite number.
+ */
+export function isFiniteNumber(n: number) {
+    return Number.isFinite(n)
+}
+
+/**
+ * Compute the Euclidean distance between two points.
+ */
+export function dist(a: Point, b: Point) {
+    return Math.hypot(a.x - b.x, a.y - b.y)
+}
+
+/**
+ * Compute the midpoint between two points.
+ */
+export function mid(a: Point, b: Point) {
+    return { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }
+}
+
+/**
+ * Read a safe client rect. Width and height are never returned as zero.
+ */
+export function safeRect(el: Element) {
+    const rect = el.getBoundingClientRect()
+    return {
+        left: rect.left,
+        top: rect.top,
+        width: rect.width || 1,
+        height: rect.height || 1,
+    }
+}
+
+/**
+ * Parse a numeric SVG/CSS length value.
+ * Returns null when the value is missing or invalid.
+ */
+export function parseLength(value: string | null): number | null {
+    if (!value) return null
+    const n = Number.parseFloat(value)
+    return Number.isFinite(n) && n > 0 ? n : null
+}
+
+/**
+ * Measure the base SVG size used to initialize the preview viewBox.
+ */
+export function measureSvgBaseViewBox(svg: SVGSVGElement): ViewBox {
+    const vb = svg.viewBox.baseVal
+    if (vb && vb.width > 0 && vb.height > 0) {
+        return { x: vb.x, y: vb.y, w: vb.width, h: vb.height }
+    }
+
+    const attrW = parseLength(svg.getAttribute('width'))
+    const attrH = parseLength(svg.getAttribute('height'))
+    if (attrW && attrH) {
+        return { x: 0, y: 0, w: attrW, h: attrH }
+    }
+
+    try {
+        const bbox = svg.getBBox()
+        if (bbox.width > 0 && bbox.height > 0) {
+            return { x: bbox.x, y: bbox.y, w: bbox.width, h: bbox.height }
+        }
+    } catch {
+        // Some SVGs may fail getBBox() before they are fully laid out.
+    }
+
+    return { x: 0, y: 0, w: 100, h: 100 }
+}
+
+/**
+ * Wait until an HTML image is fully loaded.
+ */
+export function waitForImageLoad(img: HTMLImageElement): Promise<void> {
+    return new Promise((resolve, reject) => {
+        if (img.complete) {
+            if (img.naturalWidth > 0) {
+                resolve()
+            } else {
+                reject(new Error(`Image failed to load: ${img.currentSrc || img.src}`))
+            }
+            return
+        }
+
+        img.addEventListener('load', () => resolve(), { once: true })
+        img.addEventListener(
+            'error',
+            () => reject(new Error(`Image failed to load: ${img.currentSrc || img.src}`)),
+            { once: true }
+        )
+    })
+}

package/tsconfig.app.json

@@ -0,0 +1,47 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    "rootDir": "./src",
+    "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "ESNext",
+    "target": "es2022",
+    "lib": ["ES2022", "DOM"],
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.node.json"
+    },
+    {
+      "path": "./tsconfig.app.json"
+    }
+  ]
+}

package/tsconfig.node.json

@@ -0,0 +1,24 @@
+{
+  "extends": "@tsconfig/node24/tsconfig.json",
+  "include": [
+    "rolldown.config.*",
+    "vite.config.*",
+    "vitest.config.*",
+    "cypress.config.*",
+    "nightwatch.conf.*",
+    "playwright.config.*",
+    "eslint.config.*"
+  ],
+  "compilerOptions": {
+    "noEmit": true,
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+
+    "allowJs": true,
+    "checkJs": true,
+    "strict": false,
+
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "types": ["node"]
+  }
+}