vite-plugin-shopify-theme-islands 0.6.1 → 0.7.1

package/README.md

@@ -36,6 +36,14 @@ import "vite-plugin-shopify-theme-islands/revive";
 
 That's it. The plugin automatically scans your islands directory and wires everything up.
 
+For SPA navigation teardown, import `disconnect` to stop the MutationObserver:
+
+```ts
+import { disconnect } from "vite-plugin-shopify-theme-islands/revive";
+// Call during SPA teardown:
+disconnect();
+```
+
 ## Writing islands
 
 Two approaches — use either or both.
@@ -100,6 +108,17 @@ The plugin detects the mixin import at build time and includes the file as a laz
 
 Both can be used together — directory scanning for new islands, the mixin for existing components you want to adopt without moving.
 
+### Child island cascade
+
+Child islands nested inside a parent island are automatically held until the parent's module has loaded. The runtime re-walks the parent's subtree on success, so child islands activate with their normal directives intact — no extra configuration needed.
+
+```html
+<product-form client:visible>
+  <!-- tab-switcher will not load until product-form has loaded -->
+  <tab-switcher client:idle></tab-switcher>
+</product-form>
+```
+
 ## Directives
 
 Add these attributes to your custom elements in Liquid to control when the JavaScript loads. Without a directive, the island loads immediately.
@@ -133,6 +152,8 @@ Loads the island when a CSS media query matches.
 </mobile-menu>
 ```
 
+An empty attribute (`client:media=""`) logs a console warning and skips the media check — the island still loads.
+
 ### `client:idle`
 
 Loads the island once the browser is idle (uses `requestIdleCallback` with a 500ms deadline, falls back to `setTimeout`).

package/dist/index.js

@@ -34,7 +34,7 @@ function resolveAliases(dirs, config) {
     return dir;
   });
 }
-function collectTagNames(dir, names) {
+function walkDir(dir, visitor) {
   let entries;
   try {
     entries = readdirSync(dir, { withFileTypes: true });
@@ -44,34 +44,23 @@ function collectTagNames(dir, names) {
   for (const entry of entries) {
     if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name))
       continue;
-    if (entry.isDirectory()) {
-      collectTagNames(join(dir, entry.name), names);
-    } else if (TS_JS_RE.test(entry.name)) {
-      names.push(entry.name.replace(/\.(ts|js)$/, ""));
-    }
+    const full = join(dir, entry.name);
+    if (entry.isDirectory())
+      walkDir(full, visitor);
+    else if (TS_JS_RE.test(entry.name))
+      visitor(entry.name, full);
   }
 }
+function collectTagNames(dir, names) {
+  walkDir(dir, (name) => names.push(name.replace(TS_JS_RE, "")));
+}
 function scanForIslandFiles(dir, found) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name))
-      continue;
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      scanForIslandFiles(full, found);
-    } else if (TS_JS_RE.test(entry.name)) {
-      try {
-        const content = readFileSync(full, "utf-8");
-        if (ISLAND_IMPORT_RE.test(content))
-          found.add(full);
-      } catch {}
-    }
-  }
+  walkDir(dir, (_, full) => {
+    try {
+      if (ISLAND_IMPORT_RE.test(readFileSync(full, "utf-8")))
+        found.add(full);
+    } catch {}
+  });
 }
 function shopifyThemeIslands(options = {}) {
   const rawDirs = (Array.isArray(options.directories) ? options.directories : [options.directories ?? defaults.directories[0]]).map(normalizeDir);
@@ -189,10 +178,8 @@ function shopifyThemeIslands(options = {}) {
 ${mapEntries.join(`,
 `)}
 ]);`);
-        lines.push(`_islands(islands, options, customDirectives);`);
-      } else {
-        lines.push(`_islands(islands, options);`);
       }
+      lines.push(`export const disconnect = _islands(islands, options${mapEntries.length ? ", customDirectives" : ""});`);
       return lines.join(`
 `);
     }

package/dist/runtime.d.ts

@@ -13,4 +13,4 @@
  * A MutationObserver re-runs the same logic for elements added dynamically.
  */
 import type { ClientDirective, ReviveOptions } from "./index.js";
-export declare function revive(islands: Record<string, () => Promise<unknown>>, options?: ReviveOptions, customDirectives?: Map<string, ClientDirective>): void;
+export declare function revive(islands: Record<string, () => Promise<unknown>>, options?: ReviveOptions, customDirectives?: Map<string, ClientDirective>): () => void;

package/dist/runtime.js

@@ -10,14 +10,11 @@ function media(query) {
 }
 function visible(element, rootMargin, threshold, pending) {
   return new Promise((resolve, reject) => {
-    const io = new IntersectionObserver((entries) => {
-      for (const entry of entries) {
-        if (entry.isIntersecting) {
-          io.disconnect();
-          pending.delete(element);
-          resolve();
-          return;
-        }
+    const io = new IntersectionObserver(([entry]) => {
+      if (entry.isIntersecting) {
+        io.disconnect();
+        pending.delete(element);
+        resolve();
       }
     }, { rootMargin, threshold });
     io.observe(element);
@@ -38,9 +35,6 @@ function idle(timeout) {
       setTimeout(resolve, timeout);
   });
 }
-var customElementFilter = {
-  acceptNode: (node) => node.tagName.includes("-") ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP
-};
 function revive(islands, options, customDirectives) {
   const attrVisible = options?.directives?.visible?.attribute ?? "client:visible";
   const attrMedia = options?.directives?.media?.attribute ?? "client:media";
@@ -51,52 +45,87 @@ function revive(islands, options, customDirectives) {
   const idleTimeout = options?.directives?.idle?.timeout ?? 500;
   const deferDelay = options?.directives?.defer?.delay ?? 3000;
   const debug = options?.debug ?? false;
-  const log = debug ? (...args) => console.log("[islands]", ...args) : () => {};
   const islandMap = new Map;
   for (const [key, loader] of Object.entries(islands)) {
-    const tagName = key.split("/").pop().replace(/\.(ts|js)$/, "");
+    const filename = key.split("/").pop();
+    const tagName = filename.replace(/\.(ts|js)$/, "");
     if (!tagName.includes("-")) {
-      console.warn(`[islands] Skipping "${key.split("/").pop()}" — filename must contain a hyphen to match a valid custom element tag name (e.g. rename to "${tagName}-island.ts")`);
+      console.warn(`[islands] Skipping "${filename}" — filename must contain a hyphen to match a valid custom element tag name (e.g. rename to "${tagName}-island.ts")`);
       continue;
     }
     if (!islandMap.has(tagName))
       islandMap.set(tagName, loader);
   }
-  log(`revive() ready — ${islandMap.size} island(s)`);
   const queued = new Set;
+  let initDone = false;
+  const loaded = new Set;
   const pendingVisible = new Map;
+  const isUnloadedIsland = (tag) => queued.has(tag) && !loaded.has(tag);
+  const customElementFilter = {
+    acceptNode: (node) => {
+      const tag = node.tagName;
+      if (!tag.includes("-"))
+        return NodeFilter.FILTER_SKIP;
+      const lowerTag = tag.toLowerCase();
+      if (isUnloadedIsland(lowerTag))
+        return NodeFilter.FILTER_REJECT;
+      return NodeFilter.FILTER_ACCEPT;
+    }
+  };
   async function loadIsland(tagName, el, loader) {
-    log(`<${tagName}> activating`);
+    if (debug && !initDone) {
+      const parts = [];
+      const visibleVal = el.getAttribute(attrVisible);
+      if (visibleVal !== null)
+        parts.push(visibleVal ? `${attrVisible}="${visibleVal}"` : attrVisible);
+      const mediaVal = el.getAttribute(attrMedia);
+      if (mediaVal)
+        parts.push(`${attrMedia}="${mediaVal}"`);
+      const idleVal = el.getAttribute(attrIdle);
+      if (idleVal !== null)
+        parts.push(idleVal ? `${attrIdle}="${idleVal}"` : attrIdle);
+      const deferVal = el.getAttribute(attrDefer);
+      if (deferVal !== null)
+        parts.push(deferVal ? `${attrDefer}="${deferVal}"` : attrDefer);
+      if (customDirectives?.size) {
+        for (const a of customDirectives.keys()) {
+          if (el.hasAttribute(a))
+            parts.push(a);
+        }
+      }
+      if (parts.length > 0)
+        console.log("[islands]", `<${tagName}> waiting · ${parts.join(", ")}`);
+    }
     const msgs = [];
-    const note = debug ? (msg) => {
-      msgs.push(msg);
-    } : () => {};
+    const note = debug ? (msg) => msgs.push(msg) : () => {};
     const flush = debug ? (final) => {
       if (msgs.length === 0) {
         console.log("[islands]", `<${tagName}> ${final}`);
       } else {
-        console.groupCollapsed(`[islands] <${tagName}>`);
+        console.groupCollapsed(`[islands] <${tagName}> ${final}`);
         for (const m of msgs)
           console.log(m);
-        console.log(final);
         console.groupEnd();
       }
     } : () => {};
     try {
-      if (el.hasAttribute(attrVisible)) {
-        const elRootMargin = el.getAttribute(attrVisible) || rootMargin;
+      const visibleAttr = el.getAttribute(attrVisible);
+      if (visibleAttr !== null) {
         note(`waiting for ${attrVisible}`);
-        await visible(el, elRootMargin, threshold, pendingVisible);
+        await visible(el, visibleAttr || rootMargin, threshold, pendingVisible);
       }
       const query = el.getAttribute(attrMedia);
-      if (query) {
+      if (query === "") {
+        console.warn(`[islands] <${tagName}> ${attrMedia} has no value — skipping media check`);
+      } else if (query) {
         note(`waiting for ${attrMedia}="${query}"`);
         await media(query);
       }
-      if (el.hasAttribute(attrIdle)) {
-        const rawIdle = parseInt(el.getAttribute(attrIdle), 10);
-        const elTimeout = Number.isNaN(rawIdle) ? idleTimeout : rawIdle;
-        note(`waiting for ${attrIdle} (timeout: ${elTimeout}ms)`);
+      const idleAttr = el.getAttribute(attrIdle);
+      if (idleAttr !== null) {
+        const raw = parseInt(idleAttr, 10);
+        const elTimeout = Number.isNaN(raw) ? idleTimeout : raw;
+        note(`waiting for ${attrIdle} (${elTimeout}ms)`);
         await idle(elTimeout);
       }
       const d = el.getAttribute(attrDefer);
@@ -113,7 +142,11 @@ function revive(islands, options, customDirectives) {
       flush("aborted (element removed)");
       return;
     }
-    const run = () => loader().catch((err) => {
+    const run = () => loader().then(() => {
+      loaded.add(tagName);
+      if (el.children.length)
+        walk(el);
+    }).catch((err) => {
       console.error(`[islands] Failed to load <${tagName}>:`, err);
       queued.delete(tagName);
     });
@@ -141,10 +174,16 @@ function revive(islands, options, customDirectives) {
     if (queued.has(tagName))
       return;
     const loader = islandMap.get(tagName);
-    if (loader) {
-      queued.add(tagName);
-      loadIsland(tagName, el, loader);
+    if (!loader)
+      return;
+    let ancestor = el.parentElement;
+    while (ancestor) {
+      if (isUnloadedIsland(ancestor.tagName.toLowerCase()))
+        return;
+      ancestor = ancestor.parentElement;
     }
+    queued.add(tagName);
+    loadIsland(tagName, el, loader);
   }
   function walk(el) {
     activate(el);
@@ -168,7 +207,12 @@ function revive(islands, options, customDirectives) {
     }
   });
   function init() {
+    if (debug)
+      console.groupCollapsed(`[islands] ready — ${islandMap.size} island(s)`);
     walk(document.body);
+    initDone = true;
+    if (debug)
+      console.groupEnd();
     observer.observe(document.body, { childList: true, subtree: true });
   }
   if (document.readyState === "loading") {
@@ -176,6 +220,7 @@ function revive(islands, options, customDirectives) {
   } else {
     init();
   }
+  return () => observer.disconnect();
 }
 export {
   revive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-shopify-theme-islands",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Vite plugin for island architecture in Shopify themes",
   "type": "module",
   "packageManager": "bun@1.3.10",

package/revive.d.ts

@@ -1 +1,4 @@
-declare module "vite-plugin-shopify-theme-islands/revive" {}
+declare module "vite-plugin-shopify-theme-islands/revive" {
+  /** Stops the island MutationObserver. Call during SPA navigation teardown. */
+  export const disconnect: () => void;
+}