vite-plugin-shopify-theme-islands 1.2.1 → 1.3.0

package/dist/contract.d.ts

@@ -4,6 +4,7 @@
  * Single source of truth for the payload shape, key→tag derivation, and defaults.
  * Plugin and runtime both depend on this module in-process.
  */
+import type { InteractionEventName } from "./interaction-events.js";
 /** Loader function for one island chunk. */
 export type IslandLoader = () => Promise<unknown>;
 /** Directive config for the runtime (built-in + no plugin-only `custom` entrypoints). */
@@ -26,7 +27,7 @@ export interface RuntimeDirectivesConfig {
     };
     interaction?: {
         attribute?: string;
-        events?: string[];
+        events?: readonly InteractionEventName[];
     };
 }
 /** Retry configuration. */
@@ -111,7 +112,7 @@ export interface NormalizedReviveOptions {
         };
         interaction: {
             attribute: string;
-            events: string[];
+            events: readonly InteractionEventName[];
         };
     };
     debug: boolean;

package/dist/directive-orchestration.d.ts

@@ -0,0 +1,27 @@
+import type { ClientDirective, NormalizedReviveOptions } from "./contract.js";
+import type { RuntimeLogger } from "./runtime-surface.js";
+export interface DirectiveWaiters {
+    waitVisible(element: Element, rootMargin: string, threshold: number, watch: (el: Element, cancel: () => void) => () => void): Promise<void>;
+    waitMedia(query: string): Promise<void>;
+    waitIdle(timeout: number): Promise<void>;
+    waitDelay(ms: number): Promise<void>;
+    waitInteraction(element: Element, events: string[], watch: (el: Element, cancel: () => void) => () => void): Promise<void>;
+}
+export interface DirectiveRunContext {
+    tagName: string;
+    element: HTMLElement;
+    directives: NormalizedReviveOptions["directives"];
+    customDirectives?: Map<string, ClientDirective>;
+    directiveTimeout: number;
+    watchCancellable: (el: Element, cancel: () => void) => () => void;
+    log: RuntimeLogger;
+    run: () => Promise<void>;
+    onError(attrName: string, err: unknown): void;
+}
+export interface DirectiveOrchestrator {
+    run(ctx: DirectiveRunContext): Promise<boolean>;
+}
+export declare class DirectiveCancelledError extends Error {
+    constructor();
+}
+export declare function createDirectiveOrchestrator(waiters?: DirectiveWaiters): DirectiveOrchestrator;

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import type { IslandLoadDetail, IslandErrorDetail } from "./index.js";
+import type { IslandLoadDetail, IslandErrorDetail } from "./contract.js";
 /**
  * Listen for successful island module loads.
  *

package/dist/events.js

@@ -1,13 +1,74 @@
+// src/runtime-surface.ts
+var SILENT_LOGGER = {
+  note() {},
+  flush() {}
+};
+function addListener(target, name, handler) {
+  const listener = (event) => handler(event.detail);
+  target.addEventListener(name, listener);
+  return () => target.removeEventListener(name, listener);
+}
+function dispatch(target, name, detail) {
+  target.dispatchEvent(new CustomEvent(name, { detail }));
+}
+function createRuntimeSurface(deps) {
+  return {
+    dispatchLoad(detail) {
+      dispatch(deps.target, "islands:load", detail);
+    },
+    dispatchError(detail) {
+      dispatch(deps.target, "islands:error", detail);
+    },
+    onLoad(handler) {
+      return addListener(deps.target, "islands:load", handler);
+    },
+    onError(handler) {
+      return addListener(deps.target, "islands:error", handler);
+    },
+    createLogger(tagName, debug) {
+      if (!debug)
+        return SILENT_LOGGER;
+      const msgs = [];
+      return {
+        note(msg) {
+          msgs.push(msg);
+        },
+        flush(summary) {
+          if (msgs.length === 0) {
+            deps.console.log("[islands]", `<${tagName}> ${summary}`);
+          } else {
+            deps.console.groupCollapsed(`[islands] <${tagName}> ${summary}`);
+            for (const msg of msgs)
+              deps.console.log(msg);
+            deps.console.groupEnd();
+          }
+          msgs.length = 0;
+        }
+      };
+    },
+    beginReadyLog(islandCount, debug) {
+      if (!debug)
+        return () => {};
+      deps.console.groupCollapsed(`[islands] ready — ${islandCount} island(s)`);
+      return () => deps.console.groupEnd();
+    }
+  };
+}
+var runtimeSurface;
+function getRuntimeSurface() {
+  runtimeSurface ??= createRuntimeSurface({
+    target: document,
+    console
+  });
+  return runtimeSurface;
+}
+
 // src/events.ts
 function onIslandLoad(handler) {
-  const listener = (e) => handler(e.detail);
-  document.addEventListener("islands:load", listener);
-  return () => document.removeEventListener("islands:load", listener);
+  return getRuntimeSurface().onLoad(handler);
 }
 function onIslandError(handler) {
-  const listener = (e) => handler(e.detail);
-  document.addEventListener("islands:error", listener);
-  return () => document.removeEventListener("islands:error", listener);
+  return getRuntimeSurface().onError(handler);
 }
 export {
   onIslandLoad,

package/dist/index.d.ts

@@ -5,4 +5,6 @@ export type ClientDirectiveLoader = () => Promise<void>;
 export type { ClientDirective, ClientDirectiveOptions } from "./contract.js";
 export type { ClientDirectiveDefinition, DirectivesConfig, ShopifyThemeIslandsOptions, } from "./options.js";
 export type { IslandLoadDetail, IslandErrorDetail, ReviveOptions, RetryConfig, RuntimeDirectivesConfig, } from "./contract.js";
+export type { InteractionEventName } from "./interaction-events.js";
+export { DEFAULT_INTERACTION_EVENTS, INTERACTION_EVENT_NAMES, isInteractionEventName, } from "./interaction-events.js";
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;

package/dist/index.js

@@ -54,6 +54,26 @@ function collectTagNames(dir) {
   return names;
 }
 
+// src/interaction-events.ts
+var INTERACTION_EVENT_NAMES = ["mouseenter", "touchstart", "focusin"];
+var DEFAULT_INTERACTION_EVENTS = [...INTERACTION_EVENT_NAMES];
+var INTERACTION_EVENT_NAME_SET = new Set(INTERACTION_EVENT_NAMES);
+var PREFIX = "[vite-plugin-shopify-theme-islands]";
+function isInteractionEventName(value) {
+  return INTERACTION_EVENT_NAME_SET.has(value);
+}
+function validateInteractionEvents(events) {
+  if (events === undefined)
+    return;
+  if (events.length === 0) {
+    throw new Error(`${PREFIX} "directives.interaction.events" must not be empty`);
+  }
+  const invalidEvent = events.find((eventName) => !isInteractionEventName(eventName));
+  if (invalidEvent) {
+    throw new Error(`${PREFIX} "directives.interaction.events" contains unsupported event "${invalidEvent}"`);
+  }
+}
+
 // src/contract.ts
 var DEFAULT_DIRECTIVES = {
   visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
@@ -62,7 +82,7 @@ var DEFAULT_DIRECTIVES = {
   defer: { attribute: "client:defer", delay: 3000 },
   interaction: {
     attribute: "client:interaction",
-    events: ["mouseenter", "touchstart", "focusin"]
+    events: [...DEFAULT_INTERACTION_EVENTS]
   }
 };
 var DEFAULT_RETRY = { retries: 0, delay: 1000 };
@@ -70,6 +90,7 @@ function normalizeReviveOptions(options) {
   const d = DEFAULT_DIRECTIVES;
   const r = DEFAULT_RETRY;
   const dir = options?.directives;
+  validateInteractionEvents(dir?.interaction?.events);
   return {
     directives: {
       visible: { ...d.visible, ...dir?.visible },
@@ -105,7 +126,7 @@ function buildIslandMap(payload) {
 }
 
 // src/config-policy.ts
-var PREFIX = "[vite-plugin-shopify-theme-islands]";
+var PREFIX2 = "[vite-plugin-shopify-theme-islands]";
 function mergeDirectives(directives) {
   return {
     visible: { ...DEFAULT_DIRECTIVES.visible, ...directives?.visible },
@@ -118,19 +139,21 @@ function mergeDirectives(directives) {
 function validateOptions(options, directives) {
   const customDefs = options.directives?.custom ?? [];
   if (Array.isArray(options.directories) && options.directories.length === 0) {
-    throw new Error(`${PREFIX} "directories" must not be empty`);
+    throw new Error(`${PREFIX2} "directories" must not be empty`);
   }
   const threshold = options.directives?.visible?.threshold;
   if (threshold !== undefined && (threshold < 0 || threshold > 1)) {
-    throw new Error(`${PREFIX} "directives.visible.threshold" must be between 0 and 1, got ${threshold}`);
+    throw new Error(`${PREFIX2} "directives.visible.threshold" must be between 0 and 1, got ${threshold}`);
   }
+  const interactionEvents = options.directives?.interaction?.events;
+  validateInteractionEvents(interactionEvents);
   if (options.retry !== undefined) {
     const { retries, delay } = options.retry;
     if (retries !== undefined && retries < 0) {
-      throw new Error(`${PREFIX} "retry.retries" must be >= 0, got ${retries}`);
+      throw new Error(`${PREFIX2} "retry.retries" must be >= 0, got ${retries}`);
     }
     if (delay !== undefined && delay < 0) {
-      throw new Error(`${PREFIX} "retry.delay" must be >= 0, got ${delay}`);
+      throw new Error(`${PREFIX2} "retry.delay" must be >= 0, got ${delay}`);
     }
   }
   const builtinAttributes = new Set([
@@ -143,10 +166,10 @@ function validateOptions(options, directives) {
   const seen = new Set;
   for (const def of customDefs) {
     if (seen.has(def.name)) {
-      throw new Error(`${PREFIX} Duplicate custom directive name: "${def.name}"`);
+      throw new Error(`${PREFIX2} Duplicate custom directive name: "${def.name}"`);
     }
     if (builtinAttributes.has(def.name)) {
-      throw new Error(`${PREFIX} Custom directive "${def.name}" conflicts with a built-in directive`);
+      throw new Error(`${PREFIX2} Custom directive "${def.name}" conflicts with a built-in directive`);
     }
     seen.add(def.name);
   }
@@ -357,5 +380,8 @@ function shopifyThemeIslands(options = {}) {
   };
 }
 export {
-  shopifyThemeIslands as default
+  isInteractionEventName,
+  shopifyThemeIslands as default,
+  INTERACTION_EVENT_NAMES,
+  DEFAULT_INTERACTION_EVENTS
 };

package/dist/interaction-events.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Curated interaction events accepted by `client:interaction`.
+ *
+ * The list is intentionally narrow: these are the user-intent signals the
+ * plugin supports for now, and they are exposed as a package-owned union so
+ * config can be type-checked without relying on the DOM lib surface.
+ */
+export declare const INTERACTION_EVENT_NAMES: readonly ["mouseenter", "touchstart", "focusin"];
+export type InteractionEventName = (typeof INTERACTION_EVENT_NAMES)[number];
+export declare const DEFAULT_INTERACTION_EVENTS: readonly ["mouseenter", "touchstart", "focusin"];
+export declare function isInteractionEventName(value: string): value is InteractionEventName;
+export declare function validateInteractionEvents(events: readonly string[] | undefined): asserts events is readonly InteractionEventName[];

package/dist/lifecycle.d.ts

@@ -0,0 +1,27 @@
+import type { IslandLoader } from "./contract.js";
+export interface IslandLifecycleStartInput {
+    getRoot(): HTMLElement | null;
+    islandMap: Map<string, IslandLoader>;
+    onActivate(tagName: string, el: HTMLElement, loader: () => Promise<unknown>): void;
+    onBeforeInitialWalk?: () => void;
+    onInitialWalkComplete?: () => void;
+}
+export interface IslandLifecycle {
+    settleSuccess(tag: string): number;
+    settleFailure(tag: string): {
+        retryDelayMs: number | null;
+        attempt: number;
+    };
+    evict(tag: string): void;
+    isQueued(tag: string): boolean;
+    readonly initialWalkComplete: boolean;
+    watchCancellable(el: Element, cancel: () => void): () => void;
+    walk(root: HTMLElement): void;
+    start(input: IslandLifecycleStartInput): {
+        disconnect: () => void;
+    };
+}
+export declare function createIslandLifecycleCoordinator(opts: {
+    retries: number;
+    retryDelay: number;
+}): IslandLifecycle;

package/dist/options.d.ts

@@ -1,4 +1,5 @@
 import type { RetryConfig } from "./contract.js";
+import type { InteractionEventName } from "./interaction-events.js";
 /** Plugin option entry for registering a custom client directive. */
 export interface ClientDirectiveDefinition {
     /** HTML attribute name, e.g. `'client:on-click'` */
@@ -40,8 +41,8 @@ export interface DirectivesConfig {
     interaction?: {
         /** HTML attribute name. Default: `'client:interaction'` */
         attribute?: string;
-        /** DOM event names to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
-        events?: string[];
+        /** Curated intent events to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
+        events?: readonly InteractionEventName[];
     };
     /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
     custom?: ClientDirectiveDefinition[];

package/dist/runtime-surface.d.ts

@@ -0,0 +1,20 @@
+import type { IslandErrorDetail, IslandLoadDetail } from "./contract.js";
+export interface RuntimeLogger {
+    note(msg: string): void;
+    flush(summary: string): void;
+}
+export interface RuntimeSurface {
+    dispatchLoad(detail: IslandLoadDetail): void;
+    dispatchError(detail: IslandErrorDetail): void;
+    onLoad(handler: (detail: IslandLoadDetail) => void): () => void;
+    onError(handler: (detail: IslandErrorDetail) => void): () => void;
+    createLogger(tagName: string, debug: boolean): RuntimeLogger;
+    beginReadyLog(islandCount: number, debug: boolean): () => void;
+}
+interface RuntimeSurfaceDeps {
+    target: Document;
+    console: Pick<Console, "log" | "groupCollapsed" | "groupEnd">;
+}
+export declare function createRuntimeSurface(deps: RuntimeSurfaceDeps): RuntimeSurface;
+export declare function getRuntimeSurface(): RuntimeSurface;
+export {};