vite-plugin-shopify-theme-islands 1.1.0 → 1.2.0

package/README.md

@@ -306,6 +306,7 @@ Built-in directives always run first. A custom directive is only invoked after a
 ```
 
 The custom directive owns the `load()` call — the built-in chain never calls it directly when a custom directive is matched.
+If a custom directive throws or returns a rejected promise, the runtime dispatches `islands:error` and abandons that island activation attempt.
 
 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`:
 
@@ -316,14 +317,27 @@ Multiple custom directives on the same element use AND semantics — the island
 </product-reviews>
 ```
 
+#### Timeout guard
+
+By default, a custom directive that never calls `load()` silently keeps the island unloaded forever. Set `directiveTimeout` to fire `islands:error` and abandon the island if the directive hasn't resolved within the given window:
+
+```ts
+shopifyThemeIslands({
+  directiveTimeout: 5000, // abandon after 5 seconds
+});
+```
+
+This is useful during development to surface directives that hang due to bugs, or in production to ensure broken directives don't silently degrade the experience.
+
 ## Configuration
 
-| Option        | Type                 | Default                     | Description                                                                        |
-| ------------- | -------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
-| `directories` | `string \| string[]` | `['/frontend/js/islands/']` | Directories to scan for island files. Accepts Vite aliases.                        |
-| `directives`  | `object`             | see below                   | Per-directive configuration — attribute names, timing options, and custom entries. |
-| `retry`       | `object`             | —                           | Automatic retry behaviour for failed island loads. See [Retries](#retries).        |
-| `debug`       | `boolean`            | `false`                     | Log discovered islands at build time and directive events in the browser console.  |
+| Option             | Type                 | Default                     | Description                                                                        |
+| ------------------ | -------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
+| `directories`      | `string \| string[]` | `['/frontend/js/islands/']` | Directories to scan for island files. Accepts Vite aliases.                        |
+| `directives`       | `object`             | see below                   | Per-directive configuration — attribute names, timing options, and custom entries. |
+| `retry`            | `object`             | —                           | Automatic retry behaviour for failed island loads. See [Retries](#retries).        |
+| `debug`            | `boolean`            | `false`                     | Log discovered islands at build time and directive events in the browser console.  |
+| `directiveTimeout` | `number`             | `0` (disabled)              | Milliseconds before a custom directive that never calls `load()` is considered timed out. Fires `islands:error` and abandons the island. |
 
 ### Directive defaults
 
@@ -441,7 +455,7 @@ document.addEventListener("islands:load", (e) => {
 | 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` | `tag`, `error`, `attempt`      | Load fails, custom directive throws or rejects, or `directiveTimeout` expires (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,146 @@
+/**
+ * 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;
+    /**
+     * Milliseconds before a custom directive that never calls `load()` is considered timed out.
+     * When exceeded, `islands:error` is dispatched and the island is abandoned.
+     * Default: `0` (disabled).
+     */
+    directiveTimeout?: number;
+}
+/** 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;
+    };
+    directiveTimeout: 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,45 +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/hash.ts
- * import type { ClientDirective } from 'vite-plugin-shopify-theme-islands';
- *
- * 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 hashDirective;
- * ```
- *
- * Register it in `vite.config.ts`:
- * ```ts
- * shopifyThemeIslands({
- *   directives: {
- *     custom: [{ name: 'client:hash', entrypoint: './src/directives/hash.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'` */
@@ -87,41 +49,9 @@ export interface DirectivesConfig {
     /** 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;
-    /** 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 {
-        /** 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[];
@@ -131,12 +61,11 @@ export interface ShopifyThemeIslandsOptions {
     directives?: DirectivesConfig;
     /** 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;
+    /**
+     * Milliseconds before a custom directive that never calls `load()` is considered timed out.
+     * When exceeded, `islands:error` is dispatched and the island is abandoned.
+     * Default: `0` (disabled).
+     */
+    directiveTimeout?: number;
 }
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;