@tuqulore-inc/eleventy-plugin-preact-island 0.0.1 → 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) tuqulore inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,86 @@
 # @tuqulore-inc/eleventy-plugin-preact-island
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Eleventy plugin for Preact partial hydration with is-land.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+This plugin automatically injects the necessary scripts for Preact hydration into all HTML pages.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Installation
 
-## Purpose
+```bash
+npm install -D @11ty/eleventy @tuqulore-inc/eleventy-plugin-preact-island
+```
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@tuqulore-inc/eleventy-plugin-preact-island`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Usage
 
-## What is OIDC Trusted Publishing?
+```javascript
+// eleventy.config.mjs
+import preactIsland from "@tuqulore-inc/eleventy-plugin-preact-island";
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+export default function (eleventyConfig) {
+  eleventyConfig.addPlugin(preactIsland);
+}
+```
 
-## Setup Instructions
+## What it does
 
-To properly configure OIDC trusted publishing for this package:
+1. **Copies `is-land.js`** from `@11ty/is-land` to the output directory
+2. **Injects scripts** before `</head>`:
+   - Import map for is-land and Preact (from esm.sh CDN)
+   - Development-only WebSocket hook for rehydration after hot reload
+   - is-land setup script with `Island.addInitType("preact", mount)`
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+## Options
 
-## DO NOT USE THIS PACKAGE
+### `preactVersion`
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+- Type: `string`
+- Default: `""` (latest)
 
-## More Information
+Specify the Preact version to use from esm.sh CDN.
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```javascript
+eleventyConfig.addPlugin(preactIsland, {
+  preactVersion: "10.26.4",
+});
+```
 
----
+## Partial Hydration
 
-**Maintained for OIDC setup purposes only**
+To hydrate a component, use the `<is-land>` web component with `type="preact"`.
+
+```mdx
+import Component from "./component.hydrate.jsx";
+
+<is-land
+land-on:visible
+type="preact"
+import="./component.hydrate.js"
+props='{ "someProp": "value" }'
+
+>
+
+  <Component someProp="value" />
+</is-land>
+```
+
+- The inner `<Component />` is rendered at build time (SSR)
+- The component is hydrated in the browser when the `<is-land>` becomes visible
+
+> **Note:** The `on:*` attribute prefix is changed to `land-on:*` to avoid conflicts with JSX syntax.
+
+### `<is-land>` Attributes
+
+| Attribute   | Description                                                                                                                      |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `type`      | Hydration runtime. Set to `"preact"`.                                                                                            |
+| `import`    | Path to the hydration script (e.g., `./component.hydrate.js`).                                                                   |
+| `props`     | JSON-stringified props to pass to the component.                                                                                 |
+| `land-on:*` | [Initialization conditions](https://github.com/11ty/is-land?tab=readme-ov-file#usage) (e.g., `land-on:visible`, `land-on:idle`). |
+
+## Requirements
+
+- Eleventy 3.0 or higher
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,19 @@
+import type { UserConfig } from "@11ty/eleventy";
+
+export interface PluginOptions {
+  /**
+   * Preact version for esm.sh CDN (e.g., "10.26.4").
+   * If not specified, the latest version will be used.
+   */
+  preactVersion?: string;
+}
+
+/**
+ * Eleventy plugin for Preact partial hydration with is-land
+ */
+declare function preactIslandPlugin(
+  eleventyConfig: UserConfig,
+  pluginOptions?: PluginOptions,
+): void;
+
+export default preactIslandPlugin;

package/index.mjs

@@ -0,0 +1,126 @@
+import url from "node:url";
+
+/**
+ * Eleventy plugin for Preact partial hydration with is-land
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} pluginOptions
+ * @param {string} [pluginOptions.preactVersion] - Preact version for esm.sh CDN
+ */
+export default function (eleventyConfig, pluginOptions = {}) {
+  try {
+    eleventyConfig.versionCheck(">=3.0");
+  } catch (e) {
+    console.log(`[eleventy-plugin-preact-island] WARN: ${e.message}`);
+  }
+
+  const { preactVersion = "" } = pluginOptions;
+
+  // Copy is-land.js to output directory
+  eleventyConfig.addPassthroughCopy({
+    [url.fileURLToPath(import.meta.resolve("@11ty/is-land/is-land.js"))]: "/",
+  });
+  const preactSuffix = preactVersion ? `@${preactVersion}` : "";
+
+  const generateImportMap = () => `<script type="importmap">
+{
+  "imports": {
+    "is-land": "/is-land.js",
+    "preact": "https://esm.sh/preact${preactSuffix}",
+    "preact/hooks": "https://esm.sh/preact${preactSuffix}/hooks?external=preact",
+    "preact/jsx-runtime": "https://esm.sh/preact${preactSuffix}/jsx-runtime?external=preact"
+  }
+}
+</script>`;
+
+  const generateDevScript = () =>
+    process.env.NODE_ENV === "development"
+      ? `<script>
+(function() {
+  const OriginalWebSocket = window.WebSocket;
+  window.WebSocket = function(url, protocols) {
+    const ws = new OriginalWebSocket(url, protocols);
+    ws.addEventListener("message", (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        if (data.type === "eleventy.reload") {
+          requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+              window.__eleventyRehydrate?.();
+            });
+          });
+        }
+      } catch (e) {
+        console.error("Failed to parse WebSocket message:", e);
+      }
+    });
+    return ws;
+  };
+  window.WebSocket.prototype = OriginalWebSocket.prototype;
+  window.WebSocket.CONNECTING = OriginalWebSocket.CONNECTING;
+  window.WebSocket.OPEN = OriginalWebSocket.OPEN;
+  window.WebSocket.CLOSING = OriginalWebSocket.CLOSING;
+  window.WebSocket.CLOSED = OriginalWebSocket.CLOSED;
+})();
+</script>`
+      : "";
+
+  const generateIslandSetup = () => {
+    const rehydrateScript =
+      process.env.NODE_ENV === "development"
+        ? `
+window.__eleventyRehydrate = () => {
+  document.querySelectorAll('is-land[type="preact"]').forEach(el => {
+    if (el.hasAttribute("import")) {
+      mount(el);
+    }
+  });
+};`
+        : "";
+
+    return `<script type="module">
+import { Island } from "is-land";
+import { h, hydrate } from "preact";
+Island.attributePrefix = "land-on:";
+
+const mount = async (target) => {
+  try {
+    const component = await import(target.getAttribute("import"));
+    const propsAttr = target.getAttribute("props");
+    const props = propsAttr ? JSON.parse(propsAttr) : {};
+    hydrate(h(component.default, props), target);
+  } catch (e) {
+    console.error("Failed to mount component:", e);
+  }
+};
+
+Island.addInitType("preact", mount);
+${rehydrateScript}
+</script>`;
+  };
+
+  eleventyConfig.addTransform(
+    "preact-island-inject",
+    function (content, outputPath) {
+      if (!outputPath?.endsWith?.(".html")) {
+        return content;
+      }
+
+      if (!content.includes("</head>")) {
+        console.warn(
+          `[eleventy-plugin-preact-island] WARN: No </head> tag found in ${outputPath}. Scripts not injected.`,
+        );
+        return content;
+      }
+
+      const scripts = [
+        generateImportMap(),
+        generateDevScript(),
+        generateIslandSetup(),
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      return content.replace("</head>", `${scripts}\n</head>`);
+    },
+  );
+}

package/package.json

@@ -1,10 +1,48 @@
 {
   "name": "@tuqulore-inc/eleventy-plugin-preact-island",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @tuqulore-inc/eleventy-plugin-preact-island",
+  "version": "4.0.0",
+  "description": "Eleventy plugin for Preact partial hydration with is-land",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "eleventy",
+    "eleventy-plugin",
+    "preact",
+    "is-land",
+    "partial-hydration"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tuqulore/website-boilerplate.git",
+    "directory": "packages/eleventy-plugin-preact-island"
+  },
+  "license": "MIT",
+  "author": "tuqulore inc.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    }
+  },
+  "main": "./index.mjs",
+  "files": [
+    "README.md",
+    "index.d.ts",
+    "index.mjs"
+  ],
+  "dependencies": {
+    "@11ty/is-land": "^5.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.2",
+    "@tuqulore-inc/eslint-config": "4.0.0"
+  },
+  "peerDependencies": {
+    "@11ty/eleventy": ">=3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "lint": "eslint --fix ."
+  }
+}