vite-plugin-shopify-theme-islands 1.0.2 → 1.1.1

package/README.md

@@ -190,16 +190,51 @@ Loads the island after a fixed delay. The delay in milliseconds is read from the
 
 Unlike `client:idle`, which waits for genuine browser idle time, `client:defer` always waits exactly the specified number of milliseconds.
 
+### `client:interaction`
+
+Loads the island when the user interacts with the element. Listens for `mouseenter`, `touchstart`, and `focusin` by default — the module starts downloading the moment the user moves their cursor toward or focuses the element.
+
+```html
+<cart-flyout client:interaction>
+  <!-- ... -->
+</cart-flyout>
+```
+
+The attribute value overrides the events for that element only (space-separated MDN event names):
+
+```html
+<!-- only mouseenter — touchstart and focusin are excluded -->
+<cart-flyout client:interaction="mouseenter">
+  <!-- ... -->
+</cart-flyout>
+```
+
+Combine with `client:visible` to avoid attaching listeners to off-screen elements. Because directives resolve sequentially, interaction listeners are only registered once the element has entered the viewport:
+
+```html
+<mega-menu client:visible client:interaction>
+  <!-- loads when visible, then waits for hover/touch/focus -->
+</mega-menu>
+```
+
 ### Combining directives
 
-Directives can be combined — the element waits for all conditions to be met before loading:
+Directives can be combined — the element works through each condition in sequence before loading. The resolution order is: `visible` → `media` → `idle` → `defer` → `interaction` → custom directives.
 
 ```html
+<!-- must scroll into view, then wait for user interaction -->
+<product-recommendations client:visible client:interaction>
+  <!-- ... -->
+</product-recommendations>
+
+<!-- must scroll into view, then wait for idle time -->
 <heavy-widget client:visible client:idle>
   <!-- ... -->
 </heavy-widget>
 ```
 
+Because conditions resolve sequentially, each directive is only evaluated after the previous one has passed. Interaction listeners, for example, are never attached to an element that isn't yet visible.
+
 ### Custom directives
 
 Register your own loading conditions via `directives.custom`. A custom directive is a function that receives a `load` callback and decides when to call it.
@@ -207,24 +242,28 @@ Register your own loading conditions via `directives.custom`. A custom directive
 #### 1. Write the directive
 
 ```ts
-// src/directives/hover.ts
+// src/directives/hash.ts
 import type { ClientDirective } from "vite-plugin-shopify-theme-islands";
 
-const hoverDirective: ClientDirective = (load, _opts, el) => {
-  el.addEventListener("mouseenter", load, { once: true });
+const hashDirective: ClientDirective = (load, opts) => {
+  const target = opts.value;
+  if (location.hash === target) { load(); return; }
+  window.addEventListener("hashchange", () => {
+    if (location.hash === target) load();
+  });
 };
 
-export default hoverDirective;
+export default hashDirective;
 ```
 
-`mouseenter` fires before `click`, so the module starts downloading the moment the user moves their cursor toward the element — by the time they click it's already loaded.
+Useful for anchor-linked sections — `<product-reviews client:hash="#reviews">` loads only when the URL fragment matches, so deep-links like `/products/shirt#reviews` activate the island immediately while other visitors never load it.
 
 The function signature is `(load, options, el) => void | Promise<void>`:
 
 | Parameter       | Type                   | Description                                           |
 | --------------- | ---------------------- | ----------------------------------------------------- |
 | `load`          | `() => Promise<void>`  | Call this to trigger the island module load           |
-| `options.name`  | `string`               | The matched attribute name, e.g. `'client:hover'`     |
+| `options.name`  | `string`               | The matched attribute name, e.g. `'client:hash'`      |
 | `options.value` | `string`               | The attribute value; empty string if no value was set |
 | `el`            | `HTMLElement`          | The island element                                    |
 
@@ -238,7 +277,7 @@ export default defineConfig({
   plugins: [
     shopifyThemeIslands({
       directives: {
-        custom: [{ name: "client:hover", entrypoint: "./src/directives/hover.ts" }],
+        custom: [{ name: "client:hash", entrypoint: "./src/directives/hash.ts" }],
       },
     }),
   ],
@@ -250,9 +289,9 @@ The `entrypoint` supports Vite aliases.
 #### 3. Use it in Liquid
 
 ```html
-<quick-add client:hover>
+<product-reviews client:hash="#reviews">
   <!-- ... -->
-</quick-add>
+</product-reviews>
 ```
 
 #### Ordering
@@ -260,21 +299,21 @@ The `entrypoint` supports Vite aliases.
 Built-in directives always run first. A custom directive is only invoked after all built-in conditions on the element have been met. This means you can gate a custom directive behind `client:visible` to avoid wiring event listeners for off-screen elements:
 
 ```html
-<!-- element must enter the viewport before the hover handler is registered -->
-<quick-add client:visible client:hover>
+<!-- element must enter the viewport before the hash handler is registered -->
+<product-reviews client:visible client:hash="#reviews">
   <!-- ... -->
-</quick-add>
+</product-reviews>
 ```
 
 The custom directive owns the `load()` call — the built-in chain never calls it directly when a custom directive is matched.
 
-Multiple custom directives on the same element use AND semantics — the island loads only once all matched directives have called `load()`. For example, given two registered custom directives `client:hover` and `client:focus`:
+Multiple custom directives on the same element use AND semantics — the island loads only once all matched directives have called `load()`. For example, given two registered custom directives `client:hash` and `client:network`:
 
 ```html
-<!-- client:visible runs first (built-in); then both client:hover and client:focus must fire -->
-<quick-add client:visible client:hover client:focus>
+<!-- client:visible runs first (built-in); then both client:hash and client:network must fire -->
+<product-reviews client:visible client:hash="#reviews" client:network="4g">
   <!-- ... -->
-</quick-add>
+</product-reviews>
 ```
 
 ## Configuration
@@ -307,6 +346,10 @@ shopifyThemeIslands({
       attribute: "client:defer", // HTML attribute name
       delay: 3000, // fallback delay (ms) when the attribute has no value
     },
+    interaction: {
+      attribute: "client:interaction", // HTML attribute name
+      events: ["mouseenter", "touchstart", "focusin"], // DOM events that trigger load
+    },
     custom: [], // custom directives — see Custom directives above
   },
 });
@@ -372,12 +415,12 @@ The `/events` entry point provides typed helpers that unwrap `e.detail` for you
 ```ts
 import { onIslandLoad, onIslandError } from "vite-plugin-shopify-theme-islands/events";
 
-const offLoad = onIslandLoad(({ tag }) => {
-  analytics.track("island_loaded", { tag });
+const offLoad = onIslandLoad(({ tag, duration, attempt }) => {
+  analytics.track("island_loaded", { tag, duration, attempt });
 });
 
-const offError = onIslandError(({ tag, error }) => {
-  errorReporter.capture(error, { context: tag });
+const offError = onIslandError(({ tag, error, attempt }) => {
+  errorReporter.capture(error, { context: tag, attempt });
 });
 
 // Remove listeners when no longer needed (e.g. SPA teardown)
@@ -395,10 +438,10 @@ document.addEventListener("islands:load", (e) => {
 });
 ```
 
-| Event           | Detail properties | When it fires                                              |
-| --------------- | ----------------- | ---------------------------------------------------------- |
-| `islands:load`  | `tag`             | Island module resolves successfully                        |
-| `islands:error` | `tag`, `error`    | Load or custom directive fails (alongside `console.error`) |
+| Event           | Detail properties              | When it fires                                              |
+| --------------- | ------------------------------ | ---------------------------------------------------------- |
+| `islands:load`  | `tag`, `duration`, `attempt`   | Island module resolves successfully                        |
+| `islands:error` | `tag`, `error`, `attempt`      | Load or custom directive fails (alongside `console.error`) |
 
 `islands:error` fires on each retry attempt, not just the final failure. Multiple independent listeners are supported — each receives its own event.
 

package/dist/contract.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Plugin ↔ Runtime contract (deep module).
+ *
+ * Single source of truth for the payload shape, key→tag derivation, and defaults.
+ * Plugin and runtime both depend on this module in-process.
+ */
+/** Loader function for one island chunk. */
+export type IslandLoader = () => Promise<unknown>;
+/** Directive config for the runtime (built-in + no plugin-only `custom` entrypoints). */
+export interface RuntimeDirectivesConfig {
+    visible?: {
+        attribute?: string;
+        rootMargin?: string;
+        threshold?: number;
+    };
+    idle?: {
+        attribute?: string;
+        timeout?: number;
+    };
+    media?: {
+        attribute?: string;
+    };
+    defer?: {
+        attribute?: string;
+        delay?: number;
+    };
+    interaction?: {
+        attribute?: string;
+        events?: string[];
+    };
+}
+/** Retry configuration. */
+export interface RetryConfig {
+    retries?: number;
+    delay?: number;
+}
+/** Options passed from plugin to runtime (subset of plugin options). */
+export interface ReviveOptions {
+    directives?: RuntimeDirectivesConfig;
+    debug?: boolean;
+    retry?: RetryConfig;
+}
+/** Options passed to a custom client directive function. */
+export interface ClientDirectiveOptions {
+    /** The matched attribute name, e.g. `'client:on-click'` */
+    name: string;
+    /** The attribute value; empty string if no value was set */
+    value: string;
+}
+/** Custom directive function at runtime (load, opts, element). */
+export type ClientDirective = (load: () => Promise<void>, options: ClientDirectiveOptions, el: HTMLElement) => void | Promise<void>;
+/** Event detail for the `islands:load` DOM event. */
+export interface IslandLoadDetail {
+    /** The custom element tag name, e.g. `'product-form'` */
+    tag: string;
+    /** Milliseconds from directive resolution to successful module load (chunk fetch time). */
+    duration: number;
+    /** Which attempt succeeded. 1 = first try, 2 = first retry, etc. */
+    attempt: number;
+}
+/** Event detail for the `islands:error` DOM event. */
+export interface IslandErrorDetail {
+    /** The custom element tag name, e.g. `'product-form'` */
+    tag: string;
+    /** The error thrown by the loader or custom directive */
+    error: unknown;
+    /** Which attempt failed. 1 = initial attempt, 2 = first retry, etc. */
+    attempt: number;
+}
+declare global {
+    interface DocumentEventMap {
+        "islands:load": CustomEvent<IslandLoadDetail>;
+        "islands:error": CustomEvent<IslandErrorDetail>;
+    }
+}
+/**
+ * Payload the plugin emits and the runtime consumes.
+ * Islands: glob key → loader (e.g. "/frontend/js/islands/product-form.ts" → loader).
+ * Custom directives: attribute name → directive implementation (resolved at build).
+ * Options may be partial; runtime uses normalizeReviveOptions() to fill defaults.
+ */
+export interface RevivePayload {
+    islands: Record<string, IslandLoader>;
+    options?: ReviveOptions;
+    customDirectives?: Map<string, ClientDirective>;
+}
+/** Fully resolved options; all directive and retry fields have defaults applied. */
+export interface NormalizedReviveOptions {
+    directives: {
+        visible: {
+            attribute: string;
+            rootMargin: string;
+            threshold: number;
+        };
+        idle: {
+            attribute: string;
+            timeout: number;
+        };
+        media: {
+            attribute: string;
+        };
+        defer: {
+            attribute: string;
+            delay: number;
+        };
+        interaction: {
+            attribute: string;
+            events: string[];
+        };
+    };
+    debug: boolean;
+    retry: {
+        retries: number;
+        delay: number;
+    };
+}
+/** Default directive config. Single source of truth for plugin merge and runtime normalization. */
+export declare const DEFAULT_DIRECTIVES: NormalizedReviveOptions["directives"];
+/**
+ * Applies default values for all runtime options.
+ * Single source of truth so plugin and runtime do not duplicate defaults.
+ */
+export declare function normalizeReviveOptions(options?: ReviveOptions): NormalizedReviveOptions;
+export type KeyToTagResult = {
+    tag: string;
+    skip?: boolean;
+};
+/**
+ * Maps a glob key (e.g. "/frontend/js/islands/product-form.ts") to a custom element tag.
+ * Return { tag, skip: true } to exclude this entry from the island map.
+ */
+export type KeyToTagFn = (key: string) => KeyToTagResult;
+/** Default: last path segment, extension stripped; skip (and warn) when tag has no hyphen. */
+export declare function defaultKeyToTag(key: string): KeyToTagResult;
+/**
+ * Builds tag → loader map from payload.
+ * Applies the default key→tag derivation and deduplicates by tag (first wins).
+ */
+export declare function buildIslandMap(payload: RevivePayload): Map<string, IslandLoader>;

package/dist/discovery.d.ts

@@ -0,0 +1,12 @@
+/** Matches .ts or .js extension. Exported for plugin transform/watch filters. */
+export declare const TS_JS_RE: RegExp;
+/** Matches the island mixin import. Exported for plugin transform/watch detection. */
+export declare const ISLAND_IMPORT_RE: RegExp;
+/** True if file is under any of the given absolute directory paths. */
+export declare function inDirectory(file: string, absDirs: string[]): boolean;
+/** Paths for load() virtual module: "/relative/to/root" form, forward slashes. */
+export declare function getIslandPathsForLoad(islandFiles: Set<string>, root: string): string[];
+/** Scan from root for files containing the island import; returns paths (not in absDirs). */
+export declare function discoverIslandFiles(root: string, absDirs: string[]): Set<string>;
+/** Tag names (filename without extension) for TS/JS files in a directory. Used for debug logging. */
+export declare function collectTagNames(dir: string): string[];

package/dist/index.d.ts

@@ -1,41 +1,7 @@
 import type { Plugin } from "vite";
 /** A function that triggers the load of an island module. */
 export type ClientDirectiveLoader = () => Promise<void>;
-/** Options passed to a custom client directive function. */
-export interface ClientDirectiveOptions {
-    /** The matched attribute name, e.g. `'client:on-click'` */
-    name: string;
-    /** The attribute value; empty string if no value was set */
-    value: string;
-}
-/**
- * A custom client directive function.
- *
- * Called by the runtime when a matching attribute is found on an island element.
- * The function is responsible for calling `load()` when the desired condition is met.
- *
- * @example
- * ```ts
- * // src/directives/hover.ts
- * import type { ClientDirective } from 'vite-plugin-shopify-theme-islands';
- *
- * const hoverDirective: ClientDirective = (load, _opts, el) => {
- *   el.addEventListener('mouseenter', load, { once: true });
- * };
- *
- * export default hoverDirective;
- * ```
- *
- * Register it in `vite.config.ts`:
- * ```ts
- * shopifyThemeIslands({
- *   directives: {
- *     custom: [{ name: 'client:hover', entrypoint: './src/directives/hover.ts' }],
- *   },
- * })
- * ```
- */
-export type ClientDirective = (load: ClientDirectiveLoader, options: ClientDirectiveOptions, el: HTMLElement) => void | Promise<void>;
+export type { ClientDirective, ClientDirectiveOptions } from "./contract.js";
 /** Plugin option entry for registering a custom client directive. */
 export interface ClientDirectiveDefinition {
     /** HTML attribute name, e.g. `'client:on-click'` */
@@ -73,38 +39,19 @@ export interface DirectivesConfig {
         /** Fallback delay (ms) when the attribute has no value. Default: `3000` */
         delay?: number;
     };
+    /** Configuration for the `client:interaction` directive (mouseenter/touchstart/focusin). */
+    interaction?: {
+        /** HTML attribute name. Default: `'client:interaction'` */
+        attribute?: string;
+        /** DOM event names to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
+        events?: string[];
+    };
     /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
     custom?: ClientDirectiveDefinition[];
 }
-/** Runtime-facing directive configuration — omits plugin-only `custom` directives. */
-export type RuntimeDirectivesConfig = Omit<DirectivesConfig, "custom">;
-/** Retry configuration for failed island loads. */
-export interface RetryConfig {
-    /** Number of times to retry after the initial failure. Default: `0` (no auto-retry) */
-    retries?: number;
-    /** Base delay in ms between retries; doubles each attempt. Default: `1000` */
-    delay?: number;
-}
-/** Event detail for the `islands:load` DOM event. */
-export interface IslandLoadDetail {
-    /** The custom element tag name, e.g. `'product-form'` */
-    tag: string;
-}
-/** Event detail for the `islands:error` DOM event. */
-export interface IslandErrorDetail {
-    /** The custom element tag name, e.g. `'product-form'` */
-    tag: string;
-    /** The error thrown by the loader or custom directive */
-    error: unknown;
-}
-declare global {
-    interface DocumentEventMap {
-        /** Fired after an island module resolves successfully. */
-        "islands:load": CustomEvent<IslandLoadDetail>;
-        /** Fired when an island load or custom directive fails. Fired on each retry attempt. */
-        "islands:error": CustomEvent<IslandErrorDetail>;
-    }
-}
+/** Event detail and runtime options (single source of truth in contract). */
+import type { RetryConfig } from "./contract.js";
+export type { IslandLoadDetail, IslandErrorDetail, ReviveOptions, RetryConfig, RuntimeDirectivesConfig, } from "./contract.js";
 export interface ShopifyThemeIslandsOptions {
     /** Directories to scan for island files. Accepts paths or Vite aliases. Default: `['/frontend/js/islands/']` */
     directories?: string | string[];
@@ -115,11 +62,4 @@ export interface ShopifyThemeIslandsOptions {
     /** Automatic retry behaviour for failed island loads. */
     retry?: RetryConfig;
 }
-export interface ReviveOptions {
-    directives?: RuntimeDirectivesConfig;
-    /** Log island activation and directive events to the console. Default: `false` */
-    debug?: boolean;
-    /** Automatic retry behaviour for failed island loads. */
-    retry?: RetryConfig;
-}
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;