nuxt-image-viewer 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ernest Manukyan
+
+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

@@ -1,3 +1,261 @@
-# Temporary Holding Version
+# nuxt-image-viewer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version][npm-version-src]][npm-version-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Full-screen image viewer (lightbox) for Nuxt. The image expands from its place on the page, scrolls with swipes, arrows and keys in an endless strip, zooms with a click, double tap, wheel or pinch, closes with a drag down — and flies back to its place. Springs, inertia and tuned gesture thresholds make it feel like a native photo app.
+
+- No dependencies besides Nuxt — plain Vue, plain CSS, inline SVG icons
+- Mark images with `<ZoomImage>` or a `data-image-viewer` attribute — no handlers in place
+- Open from code with `useImageViewer()` — with or without thumbnails on the page
+- Options in `nuxt.config` and per call, CSS variables, BEM classes, a cascade layer
+- Dialog semantics, keyboard, focus trap and return, reduced motion
+- Pointer events: the same gestures for mouse and touch, no empty frames at any swiping pace
+
+## Setup
+
+```bash
+npx nuxt module add nuxt-image-viewer
+```
+
+or install it yourself and add it to `modules`:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-image-viewer'],
+  imageViewer: {
+    // options, all optional — see below
+  },
+})
+```
+
+## Usage
+
+### `<ZoomImage>`
+
+```vue
+<template>
+  <article data-image-viewer-group>
+    <ZoomImage src="/photos/a.jpg" :width="2400" :height="1600" caption="Dawn" />
+    <ZoomImage src="/photos/b.jpg" :width="1600" :height="2400" alt="Dusk" />
+  </article>
+</template>
+```
+
+| Prop | Type | |
+| --- | --- | --- |
+| `src` | `string` | Full-size image. |
+| `width`, `height` | `number` | Natural size of `src` — the viewer fits and zooms by it. |
+| `caption` | `string?` | Shown under the image in the viewer; also the default `alt`. |
+| `alt` | `string?` | |
+
+Other attributes (`class`, `loading`, `sizes`, …) pass through to the `<img>`. With [`@nuxt/image`](https://image.nuxt.com) installed the component renders `<NuxtImg>`: the page shows an optimized copy, the viewer the full image (see `nuxtImage`).
+
+Click, Enter and Space open the viewer. It scrolls through the images of the closest `[data-image-viewer-group]`, without one — through every image of the page.
+
+### Plain `<img>`
+
+The component only sets attributes — any image can be marked:
+
+```html
+<img
+  src="/photos/a-small.jpg"
+  alt="Dawn"
+  tabindex="0"
+  data-image-viewer
+  data-image-viewer-src="/photos/a.jpg"
+  data-image-viewer-width="2400"
+  data-image-viewer-height="1600"
+  data-image-viewer-caption="Dawn over the ridges"
+>
+```
+
+| Attribute | |
+| --- | --- |
+| `data-image-viewer` | Opens the viewer. Only `<img>` elements. |
+| `data-image-viewer-src` | Full image. Defaults to the image on the page (`currentSrc`). |
+| `data-image-viewer-width` / `-height` | Natural size of the full image. Defaults to the page image's natural size. |
+| `data-image-viewer-caption` | Caption. |
+| `data-image-viewer-group` | On a container: scroll through its images only. |
+
+### `useImageViewer()`
+
+Open the viewer from code with your own list of images. A page element for an image is optional: with `element` the image flies out of it and back, without one the viewer fades in and out.
+
+```ts
+const viewer = useImageViewer()
+
+viewer.open(
+  [
+    { src: '/photos/a.jpg', width: 2400, height: 1600, caption: 'Dawn' },
+    { src: '/photos/b.jpg', width: 1600, height: 2400, element: thumbRef.value },
+  ],
+  1, // start index
+  { loop: false, bgOpacity: 1, ui: { fullscreen: false } }, // overrides for this call
+)
+
+watch(viewer.index, i => console.log('now at', i))
+```
+
+| Member | Type | |
+| --- | --- | --- |
+| `open(items, index?, options?)` | `Promise<void>` | Open. `items` is an array or a single item. Ignored while open. |
+| `close()` | `void` | Close with the animation. |
+| `next()`, `prev()`, `goTo(index)` | `void` | Scroll. `goTo` takes the shortest way round the endless strip. |
+| `isOpen` | `Readonly<Ref<boolean>>` | `true` from `open()` until closing starts. |
+| `index` | `Readonly<Ref<number>>` | Current image. |
+| `items` | `Readonly<Ref<ImageViewerSlide[]>>` | Images of the open viewer. |
+
+`ImageViewerItem`:
+
+| Field | Type | |
+| --- | --- | --- |
+| `src` | `string` | Full image. The only required field. |
+| `width`, `height` | `number?` | Natural size. Without it the image is loaded to measure it first, so the viewer opens a bit later. |
+| `thumb` | `string?` | Copy shown at once while `src` loads. Defaults to `element.currentSrc`, else `src`. |
+| `alt`, `caption` | `string?` | |
+| `element` | `HTMLElement?` | Page element to open from and close into. |
+
+On the server `useImageViewer()` returns a no-op (`isOpen` is `false`). All types are exported: `import type { ImageViewerItem, ImageViewerOpenOptions } from 'nuxt-image-viewer'`.
+
+## Options
+
+`nuxt.config` → `imageViewer`. Options marked *per call* can also be passed to `open()`.
+
+| Option | Default | |
+| --- | --- | --- |
+| `zIndex` | `1000` | z-index of the viewer layer. *Per call.* |
+| `bgOpacity` | `0.8` | Backdrop opacity, 0–1. *Per call.* |
+| `loop` | `true` | Endless strip. Needs at least 3 images. *Per call.* |
+| `spacing` | `0.1` | Gap between slides, share of the viewport width. *Per call.* |
+| `maxZoom` | `4` | Zoom limit relative to the fitted image. Images zoom up to their natural size but at least 2×. *Per call.* |
+| `closeOnVerticalDrag` | `true` | Close by dragging up or down. *Per call.* |
+| `closeOnBackdropClick` | `true` | Close by a click outside the image. *Per call.* |
+| `ui` | all `true` | `{ counter, zoom, fullscreen, close, arrows, caption }` — which controls to show. *Per call, partial.* |
+| `labels` | English | `{ dialog, close, zoomIn, zoomOut, fullscreen, exitFullscreen, prev, next }` — accessible names. *Per call, partial.* |
+| `openClass` | `'image-viewer-open'` | Class on `<html>` while open. |
+| `hide` | `[]` | Selectors hidden while open, e.g. `['jdiv', '#intercom-container']`. |
+| `autoOpen` | `true` | Open on click/Enter/Space on `img[data-image-viewer]`. `false` — only from code. |
+| `componentName` | `'ZoomImage'` | Name of the image component. `false` — don't register it. |
+| `nuxtImage` | `'auto'` | Render `<NuxtImg>` in the component. `'auto'` — when `@nuxt/image` is installed. |
+| `css` | `true` | Include the default styles. |
+
+Runtime options are also in `useRuntimeConfig().public.imageViewer`, so they can be overridden with `NUXT_PUBLIC_IMAGE_VIEWER_*` environment variables.
+
+## Styling
+
+### CSS variables
+
+Set them on `:root`, on `.image-viewer` or on any ancestor.
+
+| Variable | Default | |
+| --- | --- | --- |
+| `--image-viewer-bg` | `#000` | Backdrop colour (its opacity is `bgOpacity`). |
+| `--image-viewer-color` | `#fff` | Text and icons. |
+| `--image-viewer-font` | `inherit` | Font family. |
+| `--image-viewer-counter-color` | `--image-viewer-color` | |
+| `--image-viewer-button-bg` | `rgb(255 255 255 / 0.12)` | |
+| `--image-viewer-button-bg-hover` | `rgb(255 255 255 / 0.22)` | Also on press. |
+| `--image-viewer-button-color` | `--image-viewer-color` | |
+| `--image-viewer-button-size` | `44px` | |
+| `--image-viewer-button-radius` | `9999px` | |
+| `--image-viewer-icon-size` | `24px` | |
+| `--image-viewer-caption-bg` | `rgb(0 0 0 / 0.6)` | |
+| `--image-viewer-caption-color` | `--image-viewer-color` | |
+| `--image-viewer-caption-radius` | `8px` | |
+| `--image-viewer-caption-font-size` | `14px` | |
+| `--image-viewer-focus-color` | `#fff` in the viewer, `#2563eb` on page images | Focus ring. |
+
+```css
+:root {
+  --image-viewer-bg: #fff;
+  --image-viewer-color: #111827;
+  --image-viewer-button-bg: rgb(0 0 0 / 0.06);
+  --image-viewer-button-radius: 12px;
+}
+```
+
+### BEM classes
+
+The default styles live in the `image-viewer` cascade layer, so any unlayered rule of yours wins without `!important`. The layer is declared after `base`, so Tailwind's preflight doesn't break the viewer images. Or turn them off with `css: false` and style from scratch:
+
+| Class | |
+| --- | --- |
+| `.image-viewer` | Dialog layer, `100vw` × `100%`. Modifiers: `--zoomed`, `--closing`. |
+| `.image-viewer__backdrop` | Backdrop; its opacity is set inline. |
+| `.image-viewer__track` | Strip, moved by `transform`. |
+| `.image-viewer__slide` | One slide. Modifier: `--current`. |
+| `.image-viewer__frame` | Fitted image box; positioned inline. |
+| `.image-viewer__zoom` | Zoomed and panned layer. |
+| `.image-viewer__img` | Images. Modifiers: `--thumb` (page copy), `--full`, `--loaded`. |
+| `.image-viewer__ui` | Controls layer. |
+| `.image-viewer__toolbar` | Top bar. |
+| `.image-viewer__counter` | `2 / 5`. |
+| `.image-viewer__buttons` | Button group in the toolbar. |
+| `.image-viewer__button` | Every button. Modifiers: `--zoom`, `--fullscreen`, `--close`. |
+| `.image-viewer__arrow` | Prev / next (also `.image-viewer__button`). Modifiers: `--prev`, `--next`. Hidden on touch screens. |
+| `.image-viewer__icon` | SVG icon, `stroke: currentColor`. |
+| `.image-viewer__caption` | Caption container; `.image-viewer__caption-text` — its text. |
+
+Page images get `cursor: zoom-in` and a focus ring via `[data-image-viewer]`.
+
+## Gestures and keys
+
+| | Mouse | Touch | Keyboard |
+| --- | --- | --- | --- |
+| Next / previous | drag sideways, arrow buttons | swipe | `←` `→` |
+| Zoom | click, wheel, zoom button | double tap, pinch | — |
+| Pan when zoomed | drag | drag | — |
+| Close | click outside, drag up/down, close button | tap outside, drag up/down | `Esc` |
+
+## Accessibility
+
+- The viewer is a `role="dialog"` with `aria-modal` and a label; buttons have accessible names (`labels`).
+- Focus moves into the dialog, `Tab` stays inside it, and on close focus returns to the page image (or to the element focused before `open()`).
+- Page images are focusable (`tabindex="0"`) and open with Enter and Space; `alt` falls back to the caption.
+- The counter is a polite live region; slides other than the current one are `aria-hidden`.
+- With `prefers-reduced-motion: reduce` animations and springs are skipped.
+
+## How it works
+
+- The page is not edited: on the first open the plugin imports the viewer component and renders it into a container in `<body>` with the app context, and unmounts it after closing.
+- While open, page scroll is locked. If `<html>` has no `scrollbar-gutter: stable`, the scrollbar width is compensated with `padding-right` on `<body>`, so the page doesn't jump. Fixed elements of your own may still need the same.
+- Every slide is in the DOM: while the full image loads, the copy already loaded on the page is shown, so there are no empty frames.
+- While open, the page image of the current slide is `visibility: hidden` — the viewer image flies out of its place instead of doubling it.
+
+## For AI agents
+
+- Mark images: `<ZoomImage src width height caption?>`; group with `data-image-viewer-group` on a container. Width/height are of the **full** image.
+- Open from code: `useImageViewer().open(items, index?, options?)` — auto-imported, client-only, items need only `src`.
+- Configure globally in `nuxt.config` → `imageViewer` (`ModuleOptions`); per call with `ImageViewerOpenOptions` (behaviour, `ui`, `labels`).
+- Restyle with `--image-viewer-*` variables; deeper changes target `.image-viewer__*` classes (unlayered CSS wins), or `css: false`.
+- Types: `ModuleOptions`, `ImageViewerItem`, `ImageViewerOpenOptions`, `ImageViewerApi`, `ImageViewerSlide`, `ImageViewerUi`, `ImageViewerLabels` from `'nuxt-image-viewer'`.
+
+## Development
+
+```bash
+npm install
+npm run dev:prepare  # stub the module, generate types
+npm run dev          # playground on http://localhost:3000
+npm run docs:dev     # documentation site (Docus) in docs/
+npm run docs:build   # static documentation site in docs/.output/public
+npm run lint
+npm run test         # e2e: SSR + browser (local: system Edge, CI: Chromium)
+npm run test:types
+```
+
+## License
+
+[MIT](./LICENSE)
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-image-viewer/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-image-viewer
+
+[license-src]: https://img.shields.io/npm/l/nuxt-image-viewer.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-image-viewer
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,31 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { ImageViewerConfig } from '../dist/runtime/types.js';
+export * from '../dist/runtime/types.js';
+
+interface ModuleOptions extends ImageViewerConfig {
+    /**
+     * Name of the image component. `false` — don't register it and mark images with
+     * the `data-image-viewer*` attributes yourself.
+     * @default 'ZoomImage'
+     */
+    componentName: string | false;
+    /**
+     * Render `<NuxtImg>` inside the image component. `'auto'` — when `@nuxt/image` is installed.
+     * @default 'auto'
+     */
+    nuxtImage: boolean | 'auto';
+    /**
+     * Include the default styles. Turn off to style the BEM classes from scratch.
+     * @default true
+     */
+    css: boolean;
+}
+declare module '@nuxt/schema' {
+    interface PublicRuntimeConfig {
+        imageViewer: ImageViewerConfig;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-image-viewer",
+  "configKey": "imageViewer",
+  "compatibility": {
+    "nuxt": ">=3.13.0"
+  },
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,61 @@
+import { defineNuxtModule, createResolver, addPlugin, hasNuxtModule, addComponent, addImports } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-image-viewer",
+    configKey: "imageViewer",
+    compatibility: { nuxt: ">=3.13.0" }
+  },
+  defaults: {
+    zIndex: 1e3,
+    bgOpacity: 0.8,
+    loop: true,
+    spacing: 0.1,
+    maxZoom: 4,
+    closeOnVerticalDrag: true,
+    closeOnBackdropClick: true,
+    ui: {
+      counter: true,
+      zoom: true,
+      fullscreen: true,
+      close: true,
+      arrows: true,
+      caption: true
+    },
+    labels: {
+      dialog: "Image viewer",
+      close: "Close",
+      zoomIn: "Zoom in",
+      zoomOut: "Zoom out",
+      fullscreen: "Fullscreen",
+      exitFullscreen: "Exit fullscreen",
+      prev: "Previous",
+      next: "Next"
+    },
+    openClass: "image-viewer-open",
+    hide: [],
+    autoOpen: true,
+    componentName: "ZoomImage",
+    nuxtImage: "auto",
+    css: true
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const { componentName, nuxtImage, css, ...runtime } = options;
+    nuxt.options.runtimeConfig.public.imageViewer = defu(
+      nuxt.options.runtimeConfig.public.imageViewer,
+      runtime
+    );
+    if (css)
+      nuxt.options.css.push(resolver.resolve("./runtime/image-viewer.css"));
+    addPlugin({ src: resolver.resolve("./runtime/plugin.client"), mode: "client" });
+    if (componentName) {
+      const withNuxtImage = nuxtImage === "auto" ? hasNuxtModule("@nuxt/image", nuxt) : nuxtImage;
+      addComponent({ name: componentName, filePath: resolver.resolve(`./runtime/components/${withNuxtImage ? "ZoomNuxtImg" : "ZoomImage"}.vue`) });
+    }
+    addImports({ name: "useImageViewer", from: resolver.resolve("./runtime/composables/useImageViewer") });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/components/ImageViewer.d.vue.ts

@@ -0,0 +1,42 @@
+import type { ImageViewerBehavior, ImageViewerSlide } from '../types.js';
+/**
+ * Full-screen image viewer. Mounted by the plugin (plugin.client.ts) for one opening
+ * and unmounted after `closed` — it doesn't depend on Nuxt and gets everything in props.
+ *
+ * The strip is our own: every slide is in the DOM at once, so no pace of swiping shows
+ * an empty frame — while the full image loads, the copy already loaded on the page is
+ * visible. The image expands from its place on the page and collapses back into it.
+ *
+ * Motion is tuned to feel like a native photo app — the numbers below set the duration and
+ * curve of opening, closing and zoom, backdrop fade, strip and return springs, friction
+ * and gesture thresholds. Gestures run on pointer events, the same for mouse and finger:
+ *   - drag sideways — scroll, down or up — close (the backdrop fades along);
+ *   - pinch, wheel, mouse click or double tap — zoom, drag a zoomed image — pan;
+ *   - click outside the image, Esc and the close button — close, arrows and ←/→ — scroll.
+ */
+type __VLS_Props = {
+    items: ImageViewerSlide[];
+    /** Image to start from. */
+    index: number;
+    options: ImageViewerBehavior & {
+        openClass: string;
+    };
+};
+declare function goTo(i: number): void;
+declare function close(): Promise<void>;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    close: typeof close;
+    next: () => void;
+    prev: () => void;
+    goTo: typeof goTo;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    change: (index: number) => any;
+    close: () => any;
+    closed: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onChange?: ((index: number) => any) | undefined;
+    onClose?: (() => any) | undefined;
+    onClosed?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;