eleventy-plugin-rangefind 0.3.0

package/README.md

@@ -0,0 +1,141 @@
+# eleventy-plugin-rangefind
+
+Add fast, framework-free search to any [Eleventy](https://www.11ty.dev/) site
+with [Rangefind](https://github.com/xjodoin/rangefind) — a static search engine
+that ships a **packed static index** and fetches only the byte ranges it needs
+via **HTTP Range requests**. No search server, no third-party service, no
+runtime index download.
+
+The plugin:
+
+1. Crawls your built site's HTML on `eleventy.after` and writes a Rangefind
+   index into your output directory.
+2. Copies the drop-in `<rangefind-search>` Web Component (JS + optional CSS
+   theme) alongside it.
+3. Registers a universal `{% rangefindSearch %}` shortcode that mounts the
+   component.
+
+## Install
+
+```bash
+npm install eleventy-plugin-rangefind rangefind
+```
+
+`rangefind` is a peer of this plugin — install it in your project too.
+
+## Register
+
+Eleventy configs are ESM-friendly. In `eleventy.config.js`:
+
+```js
+import rangefindPlugin from "eleventy-plugin-rangefind";
+
+export default function (eleventyConfig) {
+  eleventyConfig.addPlugin(rangefindPlugin, {
+    baseUrl: "/"          // URL prefix baked into result URLs
+  });
+}
+```
+
+CommonJS projects (`.eleventy.js`) can use dynamic import:
+
+```js
+module.exports = async function (eleventyConfig) {
+  const { default: rangefindPlugin } = await import("eleventy-plugin-rangefind");
+  eleventyConfig.addPlugin(rangefindPlugin);
+};
+```
+
+## Use in templates
+
+Drop the shortcode anywhere — it works in Nunjucks, Liquid, Markdown, and
+11ty.js templates:
+
+```njk
+{% rangefindSearch %}
+```
+
+With options (Nunjucks / 11ty.js object-argument form):
+
+```njk
+{% rangefindSearch {
+  placeholder: "Search the docs",
+  theme: true,
+  pageSize: 5,
+  inputClass: "w-full border rounded px-3 py-2",
+  markClass: "bg-yellow-200"
+} %}
+```
+
+The shortcode renders:
+
+```html
+<link rel="stylesheet" href="/_rangefind/rangefind-search.css">   <!-- only when theme: true -->
+<script type="module" src="/_rangefind/rangefind-search.js"></script>
+<rangefind-search src="/rangefind/"
+  placeholder="Search the docs" page-size="5"
+  input-class="w-full border rounded px-3 py-2"
+  mark-class="bg-yellow-200"></rangefind-search>
+```
+
+## Plugin options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Set `false` to skip indexing and shortcode registration entirely. |
+| `outputDir` | `"rangefind"` | Index directory, relative to Eleventy's output dir. |
+| `assetsDir` | `"_rangefind"` | Directory the client JS/CSS are copied into, relative to output. |
+| `baseUrl` | `"/"` | URL prefix or origin baked into indexed result URLs. A path like `/blog/` prefixes every URL; an absolute origin like `https://example.com/` produces absolute URLs. |
+| `src` | `"/rangefind/"` | Default `src` (index base URL) for the shortcode's element. |
+| `assetsBase` | `"/_rangefind"` | Default URL base the shortcode points `<script>`/`<link>` at. |
+| `theme` | `false` | Default for whether the shortcode emits the optional CSS theme link. |
+| `shortcodeName` | `"rangefindSearch"` | Name to register the shortcode under. |
+
+> `outputDir`/`assetsDir` are filesystem paths inside your output folder;
+> `src`/`assetsBase` are the **URLs** the browser uses. They are separate so you
+> can deploy under a subpath or CDN without changing where files are written.
+
+## Shortcode arguments
+
+All are optional. Control keys shape the markup; every other key becomes an
+attribute on `<rangefind-search>`.
+
+| Argument | Effect |
+| --- | --- |
+| `src` | Override the index base URL for this element (defaults to plugin `src`). |
+| `assetsBase` | Override the asset URL base for this call (defaults to plugin `assetsBase`). |
+| `theme` | `true` to emit the optional stylesheet link for this call. |
+| *any element attribute* | Passed through to the element, normalized to kebab-case. `pageSize` → `page-size`, `inputClass` → `input-class`. |
+
+Recognized element attributes (from the underlying Web Component): `placeholder`,
+`label`, `page-size`, `debounce`, `min-length`, `highlight`, `suggest`,
+`router`, `open-on-focus`, `hotkey`, `empty-text`, `loading-text`, `error-text`,
+plus the per-part class hooks `root-class`, `input-class`, `panel-class`,
+`list-class`, `option-class`, `option-title-class`, `option-snippet-class`,
+`option-url-class`, `empty-class`, `status-class`, `suggest-class`,
+`suggest-item-class`, `mark-class`. Unrecognized names are dropped with a
+warning rather than rendered.
+
+Boolean arguments follow the component's semantics: `router: true` renders a
+bare `router` attribute; `highlight: false` renders `highlight="false"` to turn
+a default-on feature off.
+
+## Zero framework required, any CSS
+
+`<rangefind-search>` renders into its **light DOM** and ships **no styling of
+its own** — the host page's CSS applies directly. Style it with your own CSS
+targeting the `rf-search__*` class hooks, with Tailwind (or any utility CSS) via
+the `*-class` attributes shown above, or opt into the bundled theme with
+`theme: true`. See the [Rangefind component docs](https://github.com/xjodoin/rangefind/blob/main/docs/reference.md#search-ui-component)
+for the full attribute, class-hook, and event reference.
+
+## How it works
+
+- **Indexing** runs on Eleventy's official `eleventy.after` event, so the crawl
+  sees the final built HTML. Extraction rules (title, headings, body,
+  `data-rangefind-*` attributes) are documented in the
+  [Rangefind crawler reference](https://github.com/xjodoin/rangefind/blob/main/docs/reference.md#crawling-a-static-site).
+- **Assets** are resolved from the installed `rangefind` package via
+  `import.meta.resolve("rangefind/element")` and
+  `import.meta.resolve("rangefind/element.css")`, so they always match the
+  installed Rangefind version.

package/index.js

@@ -0,0 +1,80 @@
+// eleventy-plugin-rangefind — index a built Eleventy site with Rangefind and
+// drop in the <rangefind-search> Web Component.
+//
+// Rangefind is a static search engine: the build step crawls the already-built
+// HTML into a packed static index, and the client fetches only the byte ranges
+// it needs via HTTP Range requests — no search server. This plugin wires that
+// into Eleventy's real build lifecycle:
+//
+//   1. On `eleventy.after` (the official post-build hook), crawl the output
+//      directory into `<output>/<outputDir>` and copy the two client assets
+//      into `<output>/<assetsDir>`.
+//   2. A universal `rangefindSearch` shortcode renders the markup that mounts
+//      the component.
+
+import { copyFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildFromCrawl } from "rangefind/crawler";
+import { renderSearchMarkup } from "./src/render_markup.js";
+
+// Resolve the real on-disk path of a Rangefind subpath export. Both
+// `rangefind/element` and `rangefind/element.css` are declared in Rangefind's
+// package.json `exports`; import.meta.resolve returns a file:// URL we convert
+// to a path. Resolution is relative to THIS module, so it follows the plugin's
+// own dependency tree regardless of the consumer's cwd.
+function resolveAsset(specifier) {
+  return fileURLToPath(import.meta.resolve(specifier));
+}
+
+export default function rangefindPlugin(eleventyConfig, options = {}) {
+  const {
+    enabled = true,
+    // Rangefind index directory, relative to Eleventy's output dir.
+    outputDir = "rangefind",
+    // Client asset directory (JS + optional CSS), relative to the output dir.
+    assetsDir = "_rangefind",
+    // URL prefix/origin baked into indexed result URLs.
+    baseUrl = "/",
+    // Shortcode defaults (overridable per call site).
+    src = "/rangefind/",
+    assetsBase = "/_rangefind",
+    theme = false,
+    shortcodeName = "rangefindSearch"
+  } = options;
+
+  if (enabled === false) return;
+
+  // Universal shortcode: addShortcode registers across Nunjucks, Liquid,
+  // Markdown (via its template engine), Handlebars, and 11ty.js — the widest
+  // coverage for a simple options-object shortcode.
+  eleventyConfig.addShortcode(shortcodeName, (args = {}) =>
+    renderSearchMarkup(args, { src, assetsBase, theme })
+  );
+
+  // eleventy.after fires once the whole site is written. The event object is
+  // `{ directories, dir, results, runMode, outputMode }`. `directories.output`
+  // is the normalized project output dir (Eleventy 3); `dir.output` is the
+  // legacy, un-normalized fallback (Eleventy 2). We prefer the former.
+  eleventyConfig.on("eleventy.after", async ({ directories, dir } = {}) => {
+    const outputRoot = directories?.output || dir?.output;
+    if (!outputRoot) {
+      throw new Error("eleventy-plugin-rangefind: could not determine Eleventy output directory from the eleventy.after event.");
+    }
+
+    // 1. Crawl the built HTML into the static index. The crawler prunes the
+    //    nested index dir from its own scan automatically.
+    await buildFromCrawl({
+      root: outputRoot,
+      scanDir: outputRoot,
+      output: join(outputRoot, outputDir),
+      baseUrl
+    });
+
+    // 2. Copy the client assets next to the site.
+    const assetDirAbs = join(outputRoot, assetsDir);
+    await mkdir(assetDirAbs, { recursive: true });
+    await copyFile(resolveAsset("rangefind/element"), join(assetDirAbs, "rangefind-search.js"));
+    await copyFile(resolveAsset("rangefind/element.css"), join(assetDirAbs, "rangefind-search.css"));
+  });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "eleventy-plugin-rangefind",
+  "version": "0.3.0",
+  "description": "Eleventy plugin that indexes your built site with Rangefind (static index + HTTP Range requests, no search server) and drops in the search Web Component.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Xavier Jodoin <xavier@jodoin.me>",
+  "keywords": [
+    "eleventy",
+    "eleventy-plugin",
+    "search",
+    "static-search",
+    "rangefind",
+    "range-requests"
+  ],
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "for f in index.js src/*.js test/*.js test/fixture/*.js test/fixture/src/_includes/*.njk; do case \"$f\" in *.js) node --check \"$f\";; esac; done",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "rangefind": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@11ty/eleventy": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@11ty/eleventy": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xjodoin/rangefind.git",
+    "directory": "packages/eleventy-plugin-rangefind"
+  },
+  "homepage": "https://github.com/xjodoin/rangefind/tree/main/packages/eleventy-plugin-rangefind#readme",
+  "bugs": {
+    "url": "https://github.com/xjodoin/rangefind/issues"
+  }
+}

package/src/render_markup.js

@@ -0,0 +1,115 @@
+// Pure, Eleventy-free markup builder for the `rangefindSearch` shortcode. Kept
+// separate from the plugin registration so the branching logic (attribute
+// normalization, boolean handling, escaping, asset-base normalization) is
+// unit-testable under plain `node --test` without booting Eleventy.
+
+// The real attribute vocabulary understood by <rangefind-search>, mirrored from
+// src/element_util.js in the Rangefind monorepo (CONFIG_ATTRS +
+// PART_CLASS_ATTRS). These are the only names the element observes; anything
+// else is ignored by the component. We keep the list here so callers get a
+// warning when they pass an unrecognized name rather than silently rendering a
+// dead attribute — we do not invent new names.
+export const CONFIG_ATTRS = [
+  "src", "placeholder", "page-size", "debounce", "min-length", "highlight",
+  "suggest", "router", "open-on-focus", "hotkey", "label", "empty-text",
+  "loading-text", "error-text"
+];
+
+export const PART_CLASS_ATTRS = [
+  "root-class", "input-class", "panel-class", "list-class", "option-class",
+  "option-title-class", "option-snippet-class", "option-url-class",
+  "empty-class", "status-class", "suggest-class", "suggest-item-class",
+  "mark-class"
+];
+
+export const KNOWN_ATTRS = new Set([...CONFIG_ATTRS, ...PART_CLASS_ATTRS]);
+
+// Keys that control markup structure rather than element attributes.
+const CONTROL_KEYS = new Set(["src", "assetsBase", "theme"]);
+
+// camelCase / snake_case -> kebab-case, so `pageSize`, `page_size`, and
+// `page-size` all resolve to the `page-size` attribute the element observes.
+export function toKebab(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/_/g, "-")
+    .toLowerCase();
+}
+
+// Escape a value for use inside a double-quoted HTML attribute.
+export function escapeAttr(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+// Escape a value for use in an unquoted URL-ish attribute (src/href). Same as
+// attribute escaping — the element re-resolves `src` against document.baseURI.
+export function escapeUrl(value) {
+  return escapeAttr(value);
+}
+
+// Trailing-slash-trim an assets base URL so we can join a filename with a
+// single "/". A bare "" or "/" both normalize to "" -> "/rangefind-search.js".
+function normalizeBase(base) {
+  return String(base ?? "").replace(/\/+$/, "");
+}
+
+// Render one attribute token from a normalized (kebab) name + value.
+//   true            -> bare attribute (e.g. `router`)
+//   false / null    -> `name="false"` (turns a default-on boolean off, matching
+//                       the element's parseBoolAttr semantics; the element reads
+//                       `highlight="false"` etc.)
+//   string / number -> `name="escaped-value"`
+function renderAttr(name, value) {
+  if (value === true) return name;
+  if (value === false || value === null) return `${name}="false"`;
+  return `${name}="${escapeAttr(value)}"`;
+}
+
+// Build the full markup fragment for a search box.
+//
+// `args`     — the shortcode's argument object (per call site).
+// `defaults` — plugin-level defaults for `src`, `assetsBase`, `theme`.
+//
+// Returns a string:
+//   [<link rel="stylesheet"> if theme]
+//   <script type="module" src="<assetsBase>/rangefind-search.js"></script>
+//   <rangefind-search src="..." ...attrs></rangefind-search>
+export function renderSearchMarkup(args = {}, defaults = {}) {
+  const opts = args && typeof args === "object" ? args : {};
+
+  const src = opts.src ?? defaults.src ?? "/rangefind/";
+  const assetsBase = normalizeBase(opts.assetsBase ?? defaults.assetsBase ?? "/_rangefind");
+  const theme = (opts.theme ?? defaults.theme ?? false) === true
+    || (opts.theme ?? defaults.theme) === "true";
+
+  // Collect element attributes from every non-control key, normalized to kebab.
+  const attrs = [];
+  for (const [rawKey, value] of Object.entries(opts)) {
+    if (CONTROL_KEYS.has(rawKey)) continue;
+    if (value === undefined) continue;
+    const name = toKebab(rawKey);
+    if (name === "src") continue; // src is handled explicitly above
+    if (!KNOWN_ATTRS.has(name)) {
+      // Unknown to the element — skip it rather than invent a new attribute.
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(`eleventy-plugin-rangefind: ignoring unknown rangefindSearch attribute "${rawKey}".`);
+      }
+      continue;
+    }
+    attrs.push(renderAttr(name, value));
+  }
+
+  const jsHref = `${assetsBase}/rangefind-search.js`;
+  const cssHref = `${assetsBase}/rangefind-search.css`;
+
+  const lines = [];
+  if (theme) lines.push(`<link rel="stylesheet" href="${escapeUrl(cssHref)}">`);
+  lines.push(`<script type="module" src="${escapeUrl(jsHref)}"></script>`);
+  const attrString = attrs.length ? ` ${attrs.join(" ")}` : "";
+  lines.push(`<rangefind-search src="${escapeUrl(src)}"${attrString}></rangefind-search>`);
+  return lines.join("\n");
+}