@nifrajs/island-trigger 3.1.0

package/README.md

@@ -0,0 +1,25 @@
+# @nifrajs/island-trigger
+
+Framework-neutral, browser-side trigger scheduling shared by Nifra’s two island runtimes:
+`@nifrajs/web/islands` and `@nifrajs/islets`.
+
+It has no DOM or UI-framework dependency. The public contract is the small `scheduleTrigger`
+primitive with these strategies:
+
+```ts
+import { scheduleTrigger } from "@nifrajs/island-trigger"
+
+const dispose = scheduleTrigger({ media: "(min-width: 768px)" }, () => {
+  // Activate the island.
+})
+
+dispose() // cancel before the trigger fires
+```
+
+`load`, `idle`, `visible`, and media-query triggers are one-shot. Idle and visibility strategies
+fall back safely when the browser capability is unavailable; malformed or oversized media queries
+remain inert. The package only schedules the callback - each island runtime owns its own markers,
+registry, signals, and framework integration.
+
+For AI agents, see [`LLM.md`](./LLM.md). The wider reference is in
+[`llms-full.txt`](../../llms-full.txt).

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @nifrajs/island-trigger - the tiny browser-side trigger primitive shared by Nifra's two island
+ * runtimes. It knows scheduling and browser capability fallbacks, but it knows nothing about markers,
+ * registries, signals, or UI frameworks.
+ */
+/** When an island's enhancer runs. An object strategy is intentionally limited to media queries. */
+export type IslandStrategy = "load" | "idle" | "visible" | {
+    readonly media: string;
+};
+/** The maximum media-query length accepted from an HTML data attribute. */
+export declare const MAX_MEDIA_QUERY_LENGTH = 256;
+export interface TriggerOptions {
+    /** Target used by the `visible` strategy. Missing targets degrade to immediate activation. */
+    readonly target?: object;
+}
+/**
+ * Schedule an island trigger and return a disposer. Every successful trigger is one-shot: a late
+ * media/visibility/idle event cannot run an enhancer twice. Invalid media strategies remain inert,
+ * which keeps malformed untrusted HTML fail-closed while leaving its server-rendered content usable.
+ */
+export declare function scheduleTrigger(strategy: IslandStrategy, run: () => void, options?: TriggerOptions): () => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oGAAoG;AACpG,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAErF,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAEzC,MAAM,WAAW,cAAc;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAyCD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,GAAG,EAAE,MAAM,IAAI,EACf,OAAO,GAAE,cAAmB,GAC3B,MAAM,IAAI,CAwFZ"}

package/dist/index.js

@@ -0,0 +1,108 @@
+/**
+ * @nifrajs/island-trigger - the tiny browser-side trigger primitive shared by Nifra's two island
+ * runtimes. It knows scheduling and browser capability fallbacks, but it knows nothing about markers,
+ * registries, signals, or UI frameworks.
+ */
+/** The maximum media-query length accepted from an HTML data attribute. */
+export const MAX_MEDIA_QUERY_LENGTH = 256;
+const NOOP = () => { };
+const mediaQuery = (strategy) => {
+    if (typeof strategy !== "object" || strategy === null)
+        return undefined;
+    const query = strategy.media;
+    return query.length > 0 && query.length <= MAX_MEDIA_QUERY_LENGTH ? query : undefined;
+};
+/**
+ * Schedule an island trigger and return a disposer. Every successful trigger is one-shot: a late
+ * media/visibility/idle event cannot run an enhancer twice. Invalid media strategies remain inert,
+ * which keeps malformed untrusted HTML fail-closed while leaving its server-rendered content usable.
+ */
+export function scheduleTrigger(strategy, run, options = {}) {
+    // Cast through unknown so a consumer's DOM lib cannot merge its stricter Element signatures into
+    // this structural, DOM-free contract.
+    const browser = globalThis;
+    let fired = false;
+    let disposed = false;
+    let cleanup;
+    const fire = () => {
+        if (fired || disposed)
+            return;
+        fired = true;
+        cleanup?.();
+        cleanup = undefined;
+        run();
+    };
+    if (strategy === "load") {
+        fire();
+        return NOOP;
+    }
+    if (strategy === "idle") {
+        const ric = browser.requestIdleCallback;
+        if (ric === undefined) {
+            const handle = globalThis.setTimeout(fire, 1);
+            return () => {
+                disposed = true;
+                globalThis.clearTimeout(handle);
+            };
+        }
+        const handle = ric(fire);
+        return () => {
+            disposed = true;
+            browser.cancelIdleCallback?.(handle);
+        };
+    }
+    if (strategy === "visible") {
+        const Observer = browser.IntersectionObserver;
+        if (options.target === undefined || Observer === undefined) {
+            fire();
+            return NOOP;
+        }
+        const observer = new Observer((entries) => {
+            if (entries.some((entry) => entry.isIntersecting))
+                fire();
+        });
+        observer.observe(options.target);
+        cleanup = () => observer.disconnect();
+        return () => {
+            disposed = true;
+            cleanup?.();
+            cleanup = undefined;
+        };
+    }
+    const query = mediaQuery(strategy);
+    const matchMedia = browser.matchMedia;
+    if (query === undefined)
+        return NOOP;
+    if (matchMedia === undefined) {
+        // No matchMedia means the browser cannot honor a conditional trigger. Immediate activation is
+        // the availability fallback; malformed/oversized queries remain inert above.
+        fire();
+        return NOOP;
+    }
+    const list = matchMedia(query);
+    if (list.matches) {
+        fire();
+        return NOOP;
+    }
+    const onChange = (event) => {
+        if (event.matches)
+            fire();
+    };
+    if (list.addEventListener !== undefined) {
+        list.addEventListener("change", onChange);
+        cleanup = () => list.removeEventListener?.("change", onChange);
+    }
+    else if (list.addListener !== undefined) {
+        list.addListener(onChange);
+        cleanup = () => list.removeListener?.(onChange);
+    }
+    else {
+        return NOOP;
+    }
+    return () => {
+        disposed = true;
+        cleanup?.();
+        cleanup = undefined;
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nifrajs/island-trigger",
+  "version": "3.1.0",
+  "description": "Tiny, framework-neutral island trigger scheduler for nifra.",
+  "keywords": [
+    "nifra",
+    "islands",
+    "triggers",
+    "browser"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/island-trigger"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/index.ts

@@ -0,0 +1,154 @@
+/**
+ * @nifrajs/island-trigger - the tiny browser-side trigger primitive shared by Nifra's two island
+ * runtimes. It knows scheduling and browser capability fallbacks, but it knows nothing about markers,
+ * registries, signals, or UI frameworks.
+ */
+
+/** When an island's enhancer runs. An object strategy is intentionally limited to media queries. */
+export type IslandStrategy = "load" | "idle" | "visible" | { readonly media: string }
+
+/** The maximum media-query length accepted from an HTML data attribute. */
+export const MAX_MEDIA_QUERY_LENGTH = 256
+
+export interface TriggerOptions {
+  /** Target used by the `visible` strategy. Missing targets degrade to immediate activation. */
+  readonly target?: object
+}
+
+const NOOP = (): void => {}
+
+/** Structural event shape used instead of a DOM lib type so this package stays runtime-neutral. */
+interface MediaQueryChangeEvent {
+  readonly matches: boolean
+}
+
+interface IntersectionEntryLike {
+  readonly isIntersecting: boolean
+}
+
+interface IntersectionObserverLike {
+  observe(target: object): void
+  disconnect(): void
+}
+
+interface BrowserCapabilities {
+  readonly requestIdleCallback?: (callback: () => void) => number
+  readonly cancelIdleCallback?: (handle: number) => void
+  readonly matchMedia?: (query: string) => MediaQueryListLike
+  readonly IntersectionObserver?: new (
+    callback: (entries: readonly IntersectionEntryLike[]) => void,
+  ) => IntersectionObserverLike
+}
+
+type MediaQueryListLike = {
+  readonly matches: boolean
+  addEventListener?: (type: "change", listener: (event: MediaQueryChangeEvent) => void) => void
+  removeEventListener?: (type: "change", listener: (event: MediaQueryChangeEvent) => void) => void
+  addListener?: (listener: (event: MediaQueryChangeEvent) => void) => void
+  removeListener?: (listener: (event: MediaQueryChangeEvent) => void) => void
+}
+
+const mediaQuery = (strategy: IslandStrategy): string | undefined => {
+  if (typeof strategy !== "object" || strategy === null) return undefined
+  const query = strategy.media
+  return query.length > 0 && query.length <= MAX_MEDIA_QUERY_LENGTH ? query : undefined
+}
+
+/**
+ * Schedule an island trigger and return a disposer. Every successful trigger is one-shot: a late
+ * media/visibility/idle event cannot run an enhancer twice. Invalid media strategies remain inert,
+ * which keeps malformed untrusted HTML fail-closed while leaving its server-rendered content usable.
+ */
+export function scheduleTrigger(
+  strategy: IslandStrategy,
+  run: () => void,
+  options: TriggerOptions = {},
+): () => void {
+  // Cast through unknown so a consumer's DOM lib cannot merge its stricter Element signatures into
+  // this structural, DOM-free contract.
+  const browser = globalThis as unknown as BrowserCapabilities
+  let fired = false
+  let disposed = false
+  let cleanup: (() => void) | undefined
+
+  const fire = (): void => {
+    if (fired || disposed) return
+    fired = true
+    cleanup?.()
+    cleanup = undefined
+    run()
+  }
+
+  if (strategy === "load") {
+    fire()
+    return NOOP
+  }
+
+  if (strategy === "idle") {
+    const ric = browser.requestIdleCallback
+    if (ric === undefined) {
+      const handle = globalThis.setTimeout(fire, 1)
+      return () => {
+        disposed = true
+        globalThis.clearTimeout(handle)
+      }
+    }
+    const handle = ric(fire)
+    return () => {
+      disposed = true
+      browser.cancelIdleCallback?.(handle)
+    }
+  }
+
+  if (strategy === "visible") {
+    const Observer = browser.IntersectionObserver
+    if (options.target === undefined || Observer === undefined) {
+      fire()
+      return NOOP
+    }
+    const observer = new Observer((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) fire()
+    })
+    observer.observe(options.target)
+    cleanup = () => observer.disconnect()
+    return () => {
+      disposed = true
+      cleanup?.()
+      cleanup = undefined
+    }
+  }
+
+  const query = mediaQuery(strategy)
+  const matchMedia = browser.matchMedia
+  if (query === undefined) return NOOP
+  if (matchMedia === undefined) {
+    // No matchMedia means the browser cannot honor a conditional trigger. Immediate activation is
+    // the availability fallback; malformed/oversized queries remain inert above.
+    fire()
+    return NOOP
+  }
+
+  const list = matchMedia(query)
+  if (list.matches) {
+    fire()
+    return NOOP
+  }
+
+  const onChange = (event: MediaQueryChangeEvent): void => {
+    if (event.matches) fire()
+  }
+  if (list.addEventListener !== undefined) {
+    list.addEventListener("change", onChange)
+    cleanup = () => list.removeEventListener?.("change", onChange)
+  } else if (list.addListener !== undefined) {
+    list.addListener(onChange)
+    cleanup = () => list.removeListener?.(onChange)
+  } else {
+    return NOOP
+  }
+  return () => {
+    disposed = true
+    cleanup?.()
+    cleanup = undefined
+  }
+}