rangefind-astro 0.3.0

package/README.md

@@ -0,0 +1,108 @@
+# rangefind-astro
+
+An [Astro](https://astro.build) integration for
+[Rangefind](https://github.com/xjodoin/rangefind) — build a static search index
+from your site at `astro build` time and drop an accessible search box into any
+page. No search server: the index is static files served with HTTP `Range`
+requests.
+
+## How it works
+
+On the `astro:build:done` hook the integration:
+
+1. Crawls your built static output with Rangefind's crawler, indexing every
+   `.html` page's title, headings, and body.
+2. Writes the index into your build output (default `dist/rangefind/`) so it
+   deploys alongside the rest of your site.
+3. Copies the drop-in `<rangefind-search>` web component and its optional theme
+   into `dist/_rangefind/` for the `RangefindSearch` component to load.
+
+## Install
+
+```bash
+npm install rangefind-astro
+```
+
+`astro` and `rangefind` are the only requirements — no framework (React/Vue/…)
+is needed; the search UI is a framework-free web component.
+
+## Add the integration
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import rangefind from "rangefind-astro";
+
+export default defineConfig({
+  integrations: [rangefind()]
+});
+```
+
+## Add the search box
+
+Drop the component into any `.astro` page or layout:
+
+```astro
+---
+import RangefindSearch from "rangefind-astro/RangefindSearch.astro";
+---
+<RangefindSearch placeholder="Search the docs…" />
+```
+
+That renders the `<rangefind-search>` element and a module script that loads it
+from the copied assets. It is **headless by default** — no styling of its own —
+so your CSS (Tailwind utilities, global stylesheets) applies directly. Pass
+`theme` to also link Rangefind's optional stylesheet.
+
+## Integration options
+
+`rangefind(options)`:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `enabled` | `true` | Set `false` to skip index building (per-environment opt-out). |
+| `baseUrl` | `"/"` | URL prefix/origin for result URLs. A path like `/docs/` prefixes every URL; an absolute origin like `https://example.com/` produces absolute URLs. Match your Astro `base`/`site` if you deploy under a subpath. |
+| `outputDir` | `"rangefind"` | Where the index is written, relative to the build output (or an absolute path). Nested under the site output by default so it deploys with everything else. |
+| `assetsDir` | `"_rangefind"` | Where the client component assets are copied, relative to the build output (or absolute). |
+
+If you change `outputDir` / `assetsDir`, point the component's `src` /
+`assetsBase` props at the matching URLs.
+
+## `<RangefindSearch />` props
+
+| Prop | Default | Purpose |
+| --- | --- | --- |
+| `src` | `"/rangefind/"` | Index base URL (passed to `createSearch({ baseUrl })`). Set to match `outputDir` / your deploy base. |
+| `assetsBase` | `"/_rangefind/"` | URL directory the component `.js`/`.css` were copied to. |
+| `theme` | `false` | When truthy, link Rangefind's optional theme stylesheet. Leave off to style it yourself. |
+| `placeholder` | `Search` | Input placeholder. |
+
+Every other attribute of the underlying `<rangefind-search>` web component
+passes straight through. Config attributes: `label`, `page-size`, `debounce`,
+`min-length`, `highlight`, `suggest`, `router`, `open-on-focus`, `hotkey`,
+`empty-text`, `loading-text`, `error-text`. Per-part class hooks (anything
+matching `*-class`, e.g. `input-class`, `option-class`, `mark-class`) also pass
+through — ideal for Tailwind:
+
+```astro
+<RangefindSearch
+  placeholder="Search…"
+  hotkey
+  input-class="w-full border rounded px-3 py-2"
+  mark-class="bg-yellow-200"
+/>
+```
+
+Boolean props map faithfully: `highlight={false}` renders `highlight="false"`
+(disabling it), while an unset prop keeps the component's own default.
+
+For the full attribute, class-hook, event, and accessibility reference, see the
+Rangefind docs' **Search UI component** section:
+[`docs/reference.md`](https://github.com/xjodoin/rangefind/blob/main/docs/reference.md).
+
+## Notes
+
+- The `astro:build:done` hook only runs on `astro build`, so `astro dev` is
+  unaffected (there is no index during dev).
+- The build fails loudly if Rangefind finds no indexable HTML — the integration
+  was added on purpose, so an empty index is treated as an error.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "rangefind-astro",
+  "version": "0.3.0",
+  "description": "Astro integration for Rangefind — builds a static search index at `astro build` time and ships a drop-in search component.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Xavier Jodoin <xavier@jodoin.me>",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "astro-component",
+    "search",
+    "static-search",
+    "rangefind"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./RangefindSearch.astro": "./src/RangefindSearch.astro",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/build.test.js"
+  },
+  "dependencies": {
+    "rangefind": "^0.3.0"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "astro": "^5.13.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xjodoin/rangefind.git",
+    "directory": "packages/rangefind-astro"
+  },
+  "homepage": "https://github.com/xjodoin/rangefind/tree/main/packages/rangefind-astro#readme",
+  "bugs": {
+    "url": "https://github.com/xjodoin/rangefind/issues"
+  }
+}

package/src/RangefindSearch.astro

@@ -0,0 +1,45 @@
+---
+// Thin, faithful passthrough to the `<rangefind-search>` web component. All
+// behavior lives in the component itself; this only wires up the client asset
+// URLs and maps props onto the element's real attributes (see the monorepo's
+// docs/reference.md "Search UI component" section for every attribute + class
+// hook). Headless by default — the optional theme stylesheet is linked only
+// when `theme` is truthy.
+
+// The web component's real config attributes (from src/rangefind_search_element.js
+// CONFIG_ATTRS). `src` is handled explicitly below.
+const CONFIG_ATTRS = [
+  "placeholder", "page-size", "debounce", "min-length", "highlight",
+  "suggest", "router", "open-on-focus", "hotkey", "label", "empty-text",
+  "loading-text", "error-text"
+];
+
+const {
+  src = "/rangefind/",
+  assetsBase = "/_rangefind/",
+  theme = false,
+  placeholder,
+  ...rest
+} = Astro.props;
+
+// Build the attribute map for the custom element. Only known config attributes
+// and per-part `*-class` attributes pass through — nothing is invented.
+const attrs = { src };
+if (placeholder !== undefined && placeholder !== null) attrs.placeholder = placeholder;
+for (const [key, value] of Object.entries(rest)) {
+  if (value === undefined || value === null) continue;
+  if (!CONFIG_ATTRS.includes(key) && !/-class$/.test(key)) continue;
+  // Faithful boolean mapping: `true` -> bare attribute, `false` -> "false"
+  // (so e.g. highlight={false} actually disables it), else the string value.
+  if (value === true) attrs[key] = "";
+  else if (value === false) attrs[key] = "false";
+  else attrs[key] = String(value);
+}
+
+const base = String(assetsBase).endsWith("/") ? assetsBase : `${assetsBase}/`;
+const scriptSrc = `${base}rangefind-search.js`;
+const styleHref = `${base}rangefind-search.css`;
+---
+{theme && <link rel="stylesheet" href={styleHref} />}
+<script is:inline type="module" src={scriptSrc}></script>
+<rangefind-search {...attrs}></rangefind-search>

package/src/index.js

@@ -0,0 +1,96 @@
+// Astro integration for Rangefind.
+//
+// At `astro build` time (the `astro:build:done` hook) this crawls the built
+// static output with Rangefind's own crawler, writes the search index nested
+// under the site output so it deploys with everything else, and copies the
+// drop-in `<rangefind-search>` web component + optional theme into a public
+// assets directory. Pair it with the `RangefindSearch.astro` component.
+
+import { mkdir, copyFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { join, isAbsolute } from "node:path";
+import { buildFromCrawl } from "rangefind/crawler";
+
+const NAME = "rangefind";
+
+// Resolve a client asset shipped by the `rangefind` package to a real file
+// path. `import.meta.resolve` returns a `file://` URL for a package export.
+function resolveAsset(specifier) {
+  return fileURLToPath(import.meta.resolve(specifier));
+}
+
+// Join a configured sub-path onto the build output directory. Absolute paths
+// are honored as-is; relative paths (the default) stay nested under the site.
+function resolveUnderOut(outDir, subPath) {
+  return isAbsolute(subPath) ? subPath : join(outDir, subPath);
+}
+
+/**
+ * @param {object} [options]
+ * @param {boolean} [options.enabled=true] Set false to skip indexing entirely.
+ * @param {string} [options.baseUrl="/"] URL prefix/origin for result URLs.
+ * @param {string} [options.outputDir="rangefind"] Index output dir, relative to the build output (or absolute).
+ * @param {string} [options.assetsDir="_rangefind"] Client-asset dir, relative to the build output (or absolute).
+ * @returns {import("astro").AstroIntegration}
+ */
+export default function rangefindAstro(options = {}) {
+  const {
+    enabled = true,
+    baseUrl = "/",
+    outputDir = "rangefind",
+    assetsDir = "_rangefind"
+  } = options;
+
+  return {
+    name: NAME,
+    hooks: {
+      "astro:build:done": async ({ dir, logger }) => {
+        // `astro:build:done` only fires for `astro build`, so there is no dev
+        // mode to guard against — the `enabled` flag is the per-env opt-out.
+        if (enabled === false) {
+          logger.info("disabled (options.enabled === false); skipping index build");
+          return;
+        }
+        // `dir` may be missing on server/adapter builds that emit no static
+        // HTML output directory; skip cleanly rather than crash.
+        if (!dir) {
+          logger.warn("no static output directory for this build; skipping index build");
+          return;
+        }
+
+        const outDir = fileURLToPath(dir);
+        const indexOut = resolveUnderOut(outDir, outputDir);
+        const assetsOut = resolveUnderOut(outDir, assetsDir);
+
+        try {
+          const result = await buildFromCrawl({
+            root: outDir,
+            scanDir: outDir,
+            output: indexOut,
+            baseUrl
+          });
+          logger.info(
+            `indexed ${result.docs} doc(s) from ${result.files} file(s) -> ${indexOut}`
+          );
+        } catch (error) {
+          // A site with no indexable HTML (e.g. crawler throws) should fail the
+          // build loudly — the developer added this integration on purpose.
+          logger.error(`index build failed: ${error?.message || error}`);
+          throw error;
+        }
+
+        // Copy the client assets so `<rangefind-search>` can load them.
+        await mkdir(assetsOut, { recursive: true });
+        await copyFile(
+          resolveAsset("rangefind/element"),
+          join(assetsOut, "rangefind-search.js")
+        );
+        await copyFile(
+          resolveAsset("rangefind/element.css"),
+          join(assetsOut, "rangefind-search.css")
+        );
+        logger.info(`copied search component assets -> ${assetsOut}`);
+      }
+    }
+  };
+}