@michaelyagi/shoji 0.1.0-alpha.6 → 0.1.0-alpha.7

package/README.md

@@ -1,6 +1,7 @@
 # Shoji
 
 [![CI](https://github.com/MichaelYagi/shoji/actions/workflows/ci.yml/badge.svg)](https://github.com/MichaelYagi/shoji/actions/workflows/ci.yml)
+[![npm (alpha)](https://img.shields.io/npm/v/%40michaelyagi%2Fshoji/alpha.svg)](https://www.npmjs.com/package/@michaelyagi/shoji)
 
 A zero-dependency, plugin-first TypeScript lightbox/gallery. Drop in two `<script>`/`<link>` tags, or install from npm — everything beyond the minimal lightbox, including every official plugin, is opt-in.
 
@@ -27,12 +28,12 @@ A zero-dependency, plugin-first TypeScript lightbox/gallery. Drop in two `<scrip
 ```
 
 ```bash
-npm install shoji
+npm install @michaelyagi/shoji@alpha
 ```
 
 ```js
-import Shoji from 'shoji';
-import 'shoji/style.css';
+import Shoji from '@michaelyagi/shoji';
+import '@michaelyagi/shoji/style.css';
 
 new Shoji('#gallery', { plugins: [Shoji.Zoom] });
 ```
@@ -55,6 +56,7 @@ No items array, no options object, no plugins — every default is chosen so thi
 ## Docs
 
 - **[michaelyagi.github.io/shoji](https://michaelyagi.github.io/shoji)** — the published docs site, auto-deployed from `main` (see `.github/workflows/ci.yml`'s `publish-docs` job).
+- **[npmjs.com/package/@michaelyagi/shoji](https://www.npmjs.com/package/@michaelyagi/shoji)** — the published package, auto-published on tagged releases (see `.github/workflows/ci.yml`'s `publish-npm` job).
 - [`docs/index.html`](docs/index.html) — the same guides/examples/API reference, as local static HTML (open directly, or run `npm run docs` first to regenerate the API reference from source).
 - [`docs/examples/`](docs/examples/) — real, runnable, self-contained example pages (copy one wholesale into your own project).
 - [`DESIGN.md`](DESIGN.md) — the living architecture/spec document this project is built from.

package/dist/esm/core/Gallery.d.ts

@@ -1,5 +1,5 @@
 import { Unsubscribe } from './EventBus';
-import { GalleryEvents, GalleryItem, GalleryOptions } from './types';
+import { GalleryEvents, GalleryItem, GalleryItemInput, GalleryOptions } from './types';
 /**
  * Core lifecycle (DESIGN.md §2.2), item model / DOM scanning (§2.1), and the
  * lightbox itself: pooled slides (§2.3), dialog semantics/focus trap/live
@@ -183,7 +183,7 @@ export declare class Gallery {
      */
     private finishClose;
     /** DESIGN.md §2.1 — diffs by id (fallback src), preserving the active slide. */
-    updateSlides(items: GalleryItem[], currentIndex?: number): void;
+    updateSlides(items: GalleryItemInput[], currentIndex?: number): void;
     /**
      * Sugar over `updateSlides()` for the common "insert some items" case —
      * splices `items` into a copy of the current list at `atIndex` (default:
@@ -193,7 +193,7 @@ export declare class Gallery {
      * own semantics (negative counts from the end, out-of-range clamps) —
      * no extra validation on top of that.
      */
-    addSlides(items: GalleryItem[], atIndex?: number): void;
+    addSlides(items: GalleryItemInput[], atIndex?: number): void;
     /**
      * Sugar over `updateSlides()` for the common "remove some items" case.
      * Accepts a single id/index or an array mixing both: a `string` matches

package/dist/esm/core/GestureController.d.ts

@@ -1,5 +1,12 @@
 import { GestureEngineOptions } from '../gestures/GestureEngine';
 import { SlideManager } from './SlideManager';
+/**
+ * A real interactive control. Also used by `Gallery.ts`'s `isBackdropClick`,
+ * which used to have its own narrower list (missing select/input/textarea/
+ * a[href]) — a plugin-mounted non-button control got misread as a backdrop
+ * click and closed the gallery. One shared selector so that can't recur.
+ */
+export declare const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag]";
 /** What `GestureController` needs from `Gallery` — narrow on purpose, so this module never reaches into Gallery internals beyond this contract. */
 export interface GestureControllerHost {
     dialog: HTMLElement;

package/dist/esm/core/SlideManager.d.ts

@@ -7,11 +7,14 @@ export interface SlideManagerOptions {
     videoProviders: Map<string, VideoProviderRenderer>;
 }
 /**
- * DESIGN.md §2.3 — only `currentIndex ± preload` exist in the DOM. Rather
- * than diffing which physical node maps to which item, each pool slot has a
- * fixed structural offset (-preload…+preload) and its *content* is what gets
- * reassigned on navigation — same pattern most virtualized carousels use,
- * and it keeps re-render cost O(preload), never O(item count).
+ * DESIGN.md §2.3 — only `currentIndex ± preload` exist in the DOM. Content
+ * already resident and ready is never moved between slots — the slot that
+ * already holds it just gets its own `offset` relabeled to its new pool
+ * position; only content resident nowhere yet gets built fresh into
+ * whatever's left over. O(preload) re-render cost either way, but never a
+ * DOM reparent — which matters for a provider video's `<iframe>` (§4.3):
+ * most browsers reload an iframe moved to a new parent, so a live embed can
+ * only safely change position by relabeling, never by being moved.
  */
 export declare class SlideManager {
     readonly element: HTMLElement;
@@ -20,15 +23,7 @@ export declare class SlideManager {
     private readonly playVideoLabel;
     private readonly videoProviders;
     private dragOffsetPx;
-    /**
-     * Ready nodes keyed by item index, not slot offset — a `Slot` only
-     * remembers its *own* previous index, so it can't tell that some *other*
-     * slot already decoded the exact index it's now asked to show (the
-     * routine case: stepping forward moves the +1 slot's content into the 0
-     * slot). Without this, already-decoded content is thrown away and
-     * redecoded on every step. Trimmed to `centerIndex ± preload` each
-     * `render()`, same window the slots cover.
-     */
+    /** Ready nodes keyed by item index — trimmed to `centerIndex ± preload` each `render()`, same window the slots cover, so an evicted entry's video/iframe resources get released even if no slot ever reclaims it. */
     private readonly cache;
     /**
      * Image decodes in flight, keyed by item index, not by whichever slot
@@ -63,10 +58,10 @@ export declare class SlideManager {
     /** Releases the slot's old content and swaps the new node in, caching it. `extra` rides as a second child. `ensureImageDecoding` goes through `moveIn` instead. */
     private swapIn;
     /**
-     * Moves an already-cached, ready node into `slot` — skips `releaseVideo`,
-     * unlike `swapIn`: what `slot` holds might be a live cache entry another
-     * slot reclaims this same `render()` pass (Phase 1). Reparenting is
-     * always safe; only the later fresh/clear pass releases stale content.
+     * Inserts a just-decoded node into the slot waiting on it — skips
+     * `releaseVideo`, unlike `swapIn`: this is its first insertion anywhere,
+     * nothing outgoing to release. `render()`'s claim pass (Phase 1) never
+     * calls this — it reuses `ready` content in place, no DOM touch at all.
      */
     private moveIn;
     /** Starts decoding `item` for `index`, only if nothing already is (see `pending`). Resolves by looking up whichever slot currently wants this index, not the one active when the decode started. */

package/dist/esm/core/index.js

@@ -162,7 +162,7 @@ class FocusTrap {
     var _a;
     document.removeEventListener("keydown", this.onKeydown, true);
     this.container = null;
-    (_a = this.previouslyFocused) == null ? void 0 : _a.focus();
+    (_a = this.previouslyFocused) == null ? void 0 : _a.focus({ preventScroll: true });
     this.previouslyFocused = null;
   }
 }
@@ -335,10 +335,9 @@ function centerOf(a, b) {
 const DRAG_SETTLE_TRANSITION = "transform var(--shoji-duration) var(--shoji-momentum-easing)";
 const DRAG_FEEDBACK_TRANSITION = "transform var(--shoji-duration) var(--shoji-momentum-easing), opacity var(--shoji-duration) var(--shoji-momentum-easing)";
 const VERTICAL_FEEDBACK_DISTANCE = 160;
+const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag]";
 function shouldIgnoreGesture(event) {
-  return event.composedPath().some(
-    (node) => node instanceof Element && node.matches("button, video, input, select, textarea, a[href], [data-shoji-no-drag]")
-  );
+  return event.composedPath().some((node) => node instanceof Element && node.matches(INTERACTIVE_CONTROL_SELECTOR));
 }
 class GestureController {
   constructor(host, relay, options) {
@@ -464,6 +463,7 @@ function numAttr(el, name) {
   const n = Number(raw);
   return Number.isFinite(n) ? n : void 0;
 }
+const NO_OWN_DATA_FIELD = /* @__PURE__ */ new Set(["no-drag", "video-id", "video-provider"]);
 function applyCommon(element, item, src) {
   const caption = attr(element, "data-shoji-caption");
   if (caption) item.caption = caption;
@@ -472,7 +472,7 @@ function applyCommon(element, item, src) {
   for (const a of element.attributes) {
     if (!a.name.startsWith("data-shoji-")) continue;
     const key = a.name.slice(11);
-    if (key !== "no-drag" && !(key in item)) (data ?? (data = {}))[key] = a.value;
+    if (!NO_OWN_DATA_FIELD.has(key) && !(key in item)) (data ?? (data = {}))[key] = a.value;
   }
   if (data) item.data = data;
 }
@@ -498,8 +498,14 @@ function scanImage(element) {
 }
 function scanVideo(element) {
   var _a;
+  const videoIdAttr = attr(element, "data-shoji-video-id");
   const videoEl = element.querySelector("video");
   if (videoEl) {
+    if (videoIdAttr) {
+      console.warn(
+        `Shoji: data-shoji-video-id="${videoIdAttr}" ignored — no effect on a nested <video> (always html5).`
+      );
+    }
     const sources = Array.from(videoEl.querySelectorAll("source")).map((s) => ({ src: s.getAttribute("src") ?? "", type: s.getAttribute("type") ?? "" })).filter((s) => s.src);
     const src = videoEl.getAttribute("src") ?? ((_a = sources[0]) == null ? void 0 : _a.src);
     if (!src) return void 0;
@@ -512,19 +518,75 @@ function scanVideo(element) {
   }
   const videoUrl = attr(element, "data-shoji-video");
   if (videoUrl) {
-    const youtubeId = detectYouTubeId(videoUrl);
-    const item = youtubeId ? { src: videoUrl, video: { provider: "youtube", id: youtubeId, url: videoUrl } } : {
-      src: videoUrl,
-      video: { provider: "html5" },
-      sources: [{ src: videoUrl, type: guessVideoType(videoUrl) }]
-    };
+    const providerAttr = attr(element, "data-shoji-video-provider");
+    const resolved = resolveExplicitVideo(videoUrl, providerAttr, videoIdAttr);
+    const item = { src: videoUrl, video: resolved.video };
+    if (resolved.sources) item.sources = resolved.sources;
     const poster = attr(element, "data-shoji-poster");
     if (poster) item.poster = poster;
     applyCommon(element, item, videoUrl);
     return item;
   }
+  if (videoIdAttr) {
+    console.warn(
+      `Shoji: data-shoji-video-id="${videoIdAttr}" ignored — requires a data-shoji-video URL.`
+    );
+  }
   return void 0;
 }
+const KNOWN_VIDEO_PROVIDERS = /* @__PURE__ */ new Set(["youtube", "vimeo", "wistia", "html5"]);
+function html5Fallback(url) {
+  return { video: { provider: "html5" }, sources: [{ src: url, type: guessVideoType(url) }] };
+}
+function resolveExplicitVideo(url, providerAttr, idAttr) {
+  if (providerAttr && !KNOWN_VIDEO_PROVIDERS.has(providerAttr)) {
+    console.warn(`Shoji: data-shoji-video-provider="${providerAttr}" isn't recognized — ignored.`);
+    providerAttr = void 0;
+  }
+  if (providerAttr === "html5") {
+    if (idAttr)
+      console.warn(`Shoji: data-shoji-video-id="${idAttr}" ignored — provider html5 has no id.`);
+    return html5Fallback(url);
+  }
+  if (providerAttr === "vimeo" || providerAttr === "wistia") {
+    if (!idAttr) {
+      console.warn(
+        `Shoji: data-shoji-video-provider="${providerAttr}" needs a data-shoji-video-id — falling back to html5.`
+      );
+      return html5Fallback(url);
+    }
+    return { video: { provider: providerAttr, id: idAttr, url } };
+  }
+  const explicitYouTube = providerAttr === "youtube";
+  const isYouTube = explicitYouTube || isYouTubeUrl(url);
+  if (!isYouTube) {
+    if (idAttr) {
+      console.warn(
+        `Shoji: data-shoji-video-id="${idAttr}" ignored — data-shoji-video="${url}" isn't a recognized YouTube URL; falling back to html5.`
+      );
+    }
+    return html5Fallback(url);
+  }
+  const id = idAttr ?? detectYouTubeId(url);
+  if (!id) {
+    if (!explicitYouTube) return html5Fallback(url);
+    console.warn(
+      `Shoji: data-shoji-video-provider="youtube" but no id could be parsed from "${url}".`
+    );
+  }
+  return { video: { provider: "youtube", id, url } };
+}
+const YOUTUBE_HOSTS = /* @__PURE__ */ new Set(["youtu.be", "youtube.com", "youtube-nocookie.com"]);
+function normalizeVideoHost(hostname) {
+  return hostname.replace(/^(www|m|music)\./, "");
+}
+function isYouTubeUrl(url) {
+  try {
+    return YOUTUBE_HOSTS.has(normalizeVideoHost(new URL(url, window.location.href).hostname));
+  } catch {
+    return false;
+  }
+}
 function detectYouTubeId(url) {
   let parsed;
   try {
@@ -532,13 +594,37 @@ function detectYouTubeId(url) {
   } catch {
     return void 0;
   }
-  const host = parsed.hostname.replace(/^(www|m)\./, "");
+  const host = normalizeVideoHost(parsed.hostname);
   if (host === "youtu.be") return parsed.pathname.slice(1).split("/")[0] || void 0;
-  if (host !== "youtube.com") return void 0;
+  if (!YOUTUBE_HOSTS.has(host)) return void 0;
   if (parsed.pathname === "/watch") return parsed.searchParams.get("v") ?? void 0;
-  const match = parsed.pathname.match(/^\/(?:embed|shorts)\/([^/?]+)/);
+  const match = parsed.pathname.match(/^\/(?:embed|shorts|live|v)\/([^/?]+)/);
   return match == null ? void 0 : match[1];
 }
+function resolveDynamicVideoItems(items) {
+  return items.map((item) => {
+    var _a;
+    if (item.video === true) {
+      const video = isYouTubeUrl(item.src) ? { provider: "youtube", id: detectYouTubeId(item.src) } : { provider: "html5" };
+      if (video.provider === "youtube" && !video.id) {
+        console.warn(
+          `Shoji: item "${item.id ?? item.src}" has video: true, but no id could be parsed from src ("${item.src}") — the embed won't load. Use an explicit video.id instead.`
+        );
+      }
+      return { ...item, video };
+    }
+    const resolved = item;
+    if (((_a = resolved.video) == null ? void 0 : _a.provider) !== "youtube" || resolved.video.id) return resolved;
+    const id = detectYouTubeId(resolved.src);
+    if (!id) {
+      console.warn(
+        `Shoji: item "${resolved.id ?? resolved.src}" has video.provider: 'youtube' with no id, and src ("${resolved.src}") isn't a recognized YouTube URL — the embed won't load. Set video.id explicitly.`
+      );
+      return resolved;
+    }
+    return { ...resolved, video: { ...resolved.video, id } };
+  });
+}
 function guessVideoType(url) {
   const clean = url.split(/[?#]/)[0] ?? url;
   const ext = clean.slice(clean.lastIndexOf(".") + 1).toLowerCase();
@@ -555,15 +641,7 @@ class SlideManager {
     __publicField(this, "playVideoLabel");
     __publicField(this, "videoProviders");
     __publicField(this, "dragOffsetPx", 0);
-    /**
-     * Ready nodes keyed by item index, not slot offset — a `Slot` only
-     * remembers its *own* previous index, so it can't tell that some *other*
-     * slot already decoded the exact index it's now asked to show (the
-     * routine case: stepping forward moves the +1 slot's content into the 0
-     * slot). Without this, already-decoded content is thrown away and
-     * redecoded on every step. Trimmed to `centerIndex ± preload` each
-     * `render()`, same window the slots cover.
-     */
+    /** Ready nodes keyed by item index — trimmed to `centerIndex ± preload` each `render()`, same window the slots cover, so an evicted entry's video/iframe resources get released even if no slot ever reclaims it. */
     __publicField(this, "cache", /* @__PURE__ */ new Map());
     /**
      * Image decodes in flight, keyed by item index, not by whichever slot
@@ -628,36 +706,45 @@ class SlideManager {
   }
   /** Re-renders whichever slots need a different item; `onLoad` fires per index once its media settles. `openPlaceholderSrc` (only from `Gallery.open()`) swaps the centerIndex slot's spinner for a low-res placeholder once it decodes, if not already ready. */
   render(items, centerIndex, onLoad, openPlaceholderSrc) {
-    var _a;
     for (const [index, entry] of this.cache) {
       if (index < centerIndex - this.preload || index > centerIndex + this.preload) {
         releaseVideoNode(entry.node);
         this.cache.delete(index);
       }
     }
-    const targets = this.slots.map((slot) => {
-      const index = centerIndex + slot.offset;
+    const targets = this.slots.map((_, i) => {
+      const offset = i - this.preload;
+      const index = centerIndex + offset;
       const item = index >= 0 && index < items.length ? items[index] : void 0;
-      return { slot, index, item };
+      return { offset, index, item };
     });
-    for (const { slot, index, item } of targets) {
-      if (!item || slot.assignedIndex === index) continue;
-      const cached = this.cache.get(index);
-      if (!cached) continue;
-      if (cached.node.classList.contains("shoji-slide-provider-video")) continue;
-      slot.assignedIndex = index;
-      this.moveIn(slot, cached, index);
-      onLoad(index);
+    const claimedIndices = /* @__PURE__ */ new Set();
+    const claimedSlots = /* @__PURE__ */ new Set();
+    for (const target of targets) {
+      if (!target.item) continue;
+      const owner = this.slots.find((s) => s.assignedIndex === target.index && s.ready);
+      if (!owner) continue;
+      claimedIndices.add(target.index);
+      claimedSlots.add(owner);
+      if (owner.offset === target.offset) continue;
+      owner.offset = target.offset;
+      onLoad(target.index);
     }
-    for (const { slot, index, item } of targets) {
+    const freeSlots = this.slots.filter((s) => !claimedSlots.has(s));
+    const freeTargets = targets.filter((t) => !t.item || !claimedIndices.has(t.index));
+    freeTargets.forEach((target, i) => {
+      var _a;
+      const slot = freeSlots[i];
+      slot.offset = target.offset;
+      const { index, item } = target;
       if (!item) {
         slot.assignedIndex = null;
         slot.ready = false;
         releaseVideo(slot.media);
         slot.media.replaceChildren();
-        continue;
+        return;
       }
-      if (slot.assignedIndex === index) continue;
+      if (slot.assignedIndex === index) return;
       slot.assignedIndex = index;
       slot.ready = false;
       releaseVideo(slot.media);
@@ -672,7 +759,8 @@ class SlideManager {
       } else {
         this.ensureImageDecoding(item, index, onLoad);
       }
-    }
+    });
+    this.applyTransforms(null);
   }
   applyAspect(slot, item) {
     if (item.width && item.height) {
@@ -691,10 +779,10 @@ class SlideManager {
     this.cache.set(index, { node, item, extra });
   }
   /**
-   * Moves an already-cached, ready node into `slot` — skips `releaseVideo`,
-   * unlike `swapIn`: what `slot` holds might be a live cache entry another
-   * slot reclaims this same `render()` pass (Phase 1). Reparenting is
-   * always safe; only the later fresh/clear pass releases stale content.
+   * Inserts a just-decoded node into the slot waiting on it — skips
+   * `releaseVideo`, unlike `swapIn`: this is its first insertion anywhere,
+   * nothing outgoing to release. `render()`'s claim pass (Phase 1) never
+   * calls this — it reuses `ready` content in place, no DOM touch at all.
    */
   moveIn(slot, entry, index) {
     this.applyAspect(slot, entry.item);
@@ -1172,7 +1260,9 @@ const DEFAULT_LOCALE = {
 };
 function isBackdropClick(event) {
   return !event.composedPath().some(
-    (node) => node instanceof Element && node.matches(".shoji-slide-img, button, video, .shoji-counter, .shoji-caption")
+    (node) => node instanceof Element && node.matches(
+      `.shoji-slide-img, .shoji-counter, .shoji-caption, ${INTERACTIVE_CONTROL_SELECTOR}`
+    )
   );
 }
 function isDangerousHtmlCaption(value) {
@@ -1297,7 +1387,7 @@ class Gallery {
     this.activeIndex = 0;
     this.scannedElements = [];
     if (this.isDynamicMode) {
-      this.itemList = options.items ?? [];
+      this.itemList = resolveDynamicVideoItems(options.items ?? []);
     } else {
       const scanned = scanContainer(this.element, this.selector);
       this.itemList = scanned.map((s) => s.item);
@@ -1855,7 +1945,7 @@ class Gallery {
     if (this.destroyed) return;
     const activeItem = this.itemList[this.activeIndex];
     const activeKey = activeItem ? itemKey(activeItem) : void 0;
-    this.itemList = items;
+    this.itemList = resolveDynamicVideoItems(items);
     let nextIndex = currentIndex;
     if (nextIndex === void 0 && activeKey !== void 0) {
       const preserved = items.findIndex((item) => itemKey(item) === activeKey);