@jxsuite/search 0.4.2 → 0.5.0

package/README.md

@@ -57,13 +57,13 @@ Localized collections are indexed per locale. Each entry is indexed at the URL i
 }
 ```
 
-`query` takes a literal string or a `$ref` into page state (`#/state/ui/q` compiles to `state.ui.q`; a `$ref` outside `#/state/` degrades to `""`). Other parameters: `limit` (8), `group` (true), `index` (index-URL override), `locale`. The index URL resolves def `index` → `search.output` → `/search-index.json`.
+`query` takes a literal string or a `$ref` into page state (`#/state/ui/q` compiles to `state.ui.q`; a `$ref` outside `#/state/` degrades to `""`). Other parameters: `limit` (8), `group` (true), `index` (index-URL override), `locale`, `scope`. `scope` takes a literal or a `$ref` the same way; a literal is baked into the query options, a `$ref` is read from state on every run. The index URL resolves def `index` → `search.output` → `/search-index.json`.
 
 `lower` emits `{ $bundle: ["npm:@jxsuite/search/client"], $prototype: "Function", timing: "client", body }`. The body lazy-imports the client once per page onto `globalThis.__jxSearch`, preloads the index, flips `state.__jxSearchReady`, and returns results only once `isReady()`. Reading that flag is what makes the computed re-run when the client finishes loading. The bundle URL is the deterministic, hash-free `/assets/jxsuite-search-client.js`, derived from `sidecarAssetPath("npm:@jxsuite/search/client")` in `@jxsuite/schema/asset-paths`, the same mapping the compiler's sidecar bundler uses, so neither side depends on the other.
 
 ## The client (`@jxsuite/search/client`)
 
-MiniSearch inside (`fuzzy: 0.2`, `prefix: true`), no UI. Core API: `preload(indexUrl?)`, `isReady()`, and a synchronous `query(q, { limit, group, pageCap, locale })` with defaults `limit` 8, `group` true, `pageCap` 3 (flat mode). That `limit` default governs a direct `query()` call only: the `$src` helper `runSearch` below always passes a fixed `UI_LIMIT` of 20. Grouped mode returns `SearchResultGroup[]`: a page with its matching sections, sorted by best score. Flat mode returns presentation-ready `SearchResult[]` carrying `crumbs` (title-cased slug ancestors, plus the page title on a section row), `titleTokens` and `excerptTokens`. Those two are arrays of `{ t, m }` runs where `m: true` marks a match, so renderers highlight without injecting HTML.
+MiniSearch inside (`fuzzy: 0.2`, `prefix: true`), no UI. Core API: `preload(indexUrl?)`, `isReady()`, and a synchronous `query(q, { limit, group, pageCap, locale, scope })` with defaults `limit` 8, `group` true, `pageCap` 3 (flat mode). That `limit` default governs a direct `query()` call only: the `$src` helper `runSearch` below always passes a fixed `UI_LIMIT` of 20. Grouped mode returns `SearchResultGroup[]`: a page with its matching sections, sorted by best score. Flat mode returns presentation-ready `SearchResult[]` carrying `crumbs` (title-cased slug ancestors, plus the page title on a section row), `titleTokens` and `excerptTokens`. Those two are arrays of `{ t, m }` runs where `m: true` marks a match, so renderers highlight without injecting HTML.
 
 Compiled components do not go through lowering, so inside a component you use the `$src` state conventions instead of the `Search` prototype (`sites/jxsuite.com/components/site-search.json` is the working example):
 
@@ -84,7 +84,7 @@ Compiled components do not go through lowering, so inside a component you use th
 }
 ```
 
-`searchInit(state)` returns `true` immediately, preloads (honouring `state.searchIndexUrl`), then sets `state.searchReady` and re-runs a pending `state.searchQuery`. `runSearch(state, event?)` reads the query from `event.target.value` (else `state.searchQuery`) and publishes `state.searchResults`, `state.searchCount` and `state.searchActive`. `$src` parameters bind **by name, not position** (spec.md §5.3): a parameter literally named `state` gets reactive state, any other name gets the event.
+`searchInit(state)` returns `true` immediately, preloads (honouring `state.searchIndexUrl`), then sets `state.searchReady` and re-runs a pending `state.searchQuery`. `runSearch(state, event?)` reads the query from `event.target.value` (else `state.searchQuery`), searches within `state.searchScope` when it is a non-empty string, and publishes `state.searchResults`, `state.searchCount` and `state.searchActive`. `$src` parameters bind **by name, not position** (spec.md §5.3): a parameter literally named `state` gets reactive state, any other name gets the event.
 
 ## Surprises
 
@@ -93,8 +93,9 @@ Compiled components do not go through lowering, so inside a component you use th
 - **`emit` only runs when the project declares a non-empty `search` section**, because the compiler skips section-owner emitters whose value is `null` or `{}` (specs/extensions.md §8.4, "Gating").
 - **The `public/` copy runs after `emit`**, so a file in `public/` at the same path shadows the emitted index (the same semantics as `sitemap.xml`).
 - **Omitting `locale` is not the same as `locale: null`.** Omitted means the page's own language, read from `<html lang>`; `null` searches every language. Both `lower` and `resolve` drop the key rather than serialize `undefined`. A document with no `locale` answers every search, and region is ignored when tags differ only there (`fr` matches `fr-CA`).
+- **`scope` is a URL prefix, tested the way the Web App Manifest tests "within scope"**: same origin, and the result's path starts with the scope's path, with query and fragment ignored. It is a string prefix, so `/docs` also holds `/docs-old/`; end a folder scope with `/`. A relative scope resolves against `document.baseURI`, a scope that is not a URL holds nothing, and the filter runs before `limit`, so a scoped search still fills its rows.
 - **`Search.resolve()` returns `[]` outside the browser**, with a warning. Search is a client-side interaction, so compiler-timing bakes and dev-server resolve proxying degrade rather than fail.
-- **The index is one file per site and the client is a module-level singleton**, so the first `preload` wins. Multiple collections share the one index; results carry their `collection` name. A failed load clears the memo so a later call can retry.
+- **The index is one file per site and the client is a module-level singleton**, so the first `preload` wins. Multiple collections share the one index; results carry their `collection` name. To search one part of a site, pass a `scope` rather than splitting the index. A failed load clears the memo so a later call can retry.
 - **First-party (`@jxsuite/*`) schema fragments are read from the host, not the project's `node_modules`**: schema composition routes every `@jxsuite/*` `.json` ref through host resolution and throws when the host cannot resolve it, so installing this package into a project alone does not make its `search` section validate. A third-party extension's fragment still resolves project-first.
 - **Class names are global across extensions.** `Search` and `SearchIndex` occupy the `$prototype`-visible namespace, not a package-scoped one.
 - **`bun run build` bundles only `search-index.ts` and `search-state.ts` into `dist/`.** The client is deliberately not built here, because the site build bundles it from source through the sidecar bundler.

package/dist/search-state.js

@@ -84,14 +84,17 @@ var CLIENT_SPECIFIER = "npm:@jxsuite/search/client";
 function inBrowser() {
   return typeof document !== "undefined" && isFunction(globalThis.fetch);
 }
-function queryExpression(query) {
-  if (isNonNullObject(query) && isString(query.$ref)) {
-    const path = query.$ref.replace(/^#\//, "").split("/");
+function stateExpression(value) {
+  if (isNonNullObject(value) && isString(value.$ref)) {
+    const path = value.$ref.replace(/^#\//, "").split("/");
     if (path[0] === "state" && path.length > 1) {
       return ["state", ...path.slice(1)].join(".");
     }
   }
-  return JSON.stringify(isString(query) ? query : "");
+  return null;
+}
+function queryExpression(query) {
+  return stateExpression(query) ?? JSON.stringify(isString(query) ? query : "");
 }
 
 class Search {
@@ -115,6 +118,9 @@ class Search {
     if (this.config.locale !== undefined) {
       opts.locale = this.config.locale;
     }
+    if (isString(this.config.scope)) {
+      opts.scope = this.config.scope;
+    }
     return client.query(query, opts);
   }
   indexUrl() {
@@ -127,7 +133,11 @@ class Search {
     if (def.locale !== undefined) {
       queryOptions.locale = def.locale;
     }
-    const opts = JSON.stringify(queryOptions);
+    if (isString(def.scope)) {
+      queryOptions.scope = def.scope;
+    }
+    const scopeRef = stateExpression(def.scope);
+    const opts = scopeRef ? `Object.assign(${JSON.stringify(queryOptions)}, { scope: ${scopeRef} })` : JSON.stringify(queryOptions);
     const body = [
       "void state.__jxSearchReady;",
       "if (!globalThis.__jxSearch) {",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/search",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Static site search for Jx: build-time index emission from content collections and a headless MiniSearch browser client",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^4.1.0",
+    "@jxsuite/schema": "^5.0.0",
     "minisearch": "^7.2.0"
   },
   "devDependencies": {

package/src/Search.class.json

@@ -37,6 +37,11 @@
         "identifier": "locale",
         "type": { "type": ["string", "null"] },
         "description": "Language to search in \u2014 omitted, the page's own (<html lang>); null searches every language"
+      },
+      "scope": {
+        "identifier": "scope",
+        "type": { "type": "string" },
+        "description": "URL prefix a result must fall within (e.g. /example/docs/): a literal or a $ref into page state; omitted, the whole index"
       }
     },
     "constructor": {
@@ -46,7 +51,8 @@
         { "$ref": "#/$defs/parameters/limit" },
         { "$ref": "#/$defs/parameters/group" },
         { "$ref": "#/$defs/parameters/index" },
-        { "$ref": "#/$defs/parameters/locale" }
+        { "$ref": "#/$defs/parameters/locale" },
+        { "$ref": "#/$defs/parameters/scope" }
       ],
       "body": ["this.config = config;"]
     },

package/src/client.ts

@@ -92,6 +92,14 @@ export interface QueryOptions {
    * `null` searches every language.
    */
   locale?: string | null;
+  /**
+   * The part of the site to search: a URL that a result's URL must be within, by the Web App
+   * Manifest's "within scope" test (same origin, and the result's path starts with the scope's).
+   * Relative values resolve against the document's base URL, so `/example/docs/` keeps a project's
+   * pages to that project's documentation while one index serves the whole site. Omitted or `""`
+   * searches everything; a value that is not a URL holds nothing.
+   */
+  scope?: string;
 }
 
 interface ClientState {
@@ -155,6 +163,48 @@ function pageKey(hit: RawHit): string {
   return `${hit.collection}:${hit.locale ?? ""}:${hit.slug}`;
 }
 
+/**
+ * The base relative URLs resolve against off a document — any absolute URL serves, it is never
+ * shown.
+ */
+const NO_DOCUMENT_BASE = "https://jx.invalid/";
+
+/**
+ * `url` resolved against `base`, or null when it is not a URL. `URL.parse` says the same thing, but
+ * a visitor's browser older than 2024 does not have it, and this module runs in that browser.
+ */
+function parseUrl(url: string, base: string): URL | null {
+  try {
+    return new URL(url, base);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A test for "is this result's URL within `scope`", the Web App Manifest's algorithm: same origin,
+ * and the result's path starts with the scope's path. Query and fragment are ignored on both sides,
+ * so a section hit (`/docs/page/#heading`) is within the scope its page is.
+ *
+ * The comparison is a string prefix, as the manifest's is: `/docs` also holds `/docs-old/`, and a
+ * scope meant to stop at a folder ends in `/`.
+ */
+function scopeTest(scope: string): (url: string) => boolean {
+  const base = typeof document === "undefined" ? NO_DOCUMENT_BASE : document.baseURI;
+  const within = parseUrl(scope, base);
+  if (!within) {
+    return () => false;
+  }
+  return (url) => {
+    const target = parseUrl(url, base);
+    return (
+      target !== null &&
+      target.origin === within.origin &&
+      target.pathname.startsWith(within.pathname)
+    );
+  };
+}
+
 function localeAnswers(docLocale: string | undefined, want: string): boolean {
   if (docLocale === undefined || want === "") {
     return true;
@@ -389,6 +439,12 @@ export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] |
    * copy of the page they are already on — ranked first, because it matched the same words.
    */
   const want = opts.locale === undefined ? pageLocale() : (opts.locale ?? "");
+  /*
+   * Scoped to a URL only when the caller names one. Filtering here, before `limit` is applied, is
+   * what makes one index serve many parts of a site: a scope cut after the limit would hand back
+   * whatever few rows of the top results happened to fall inside it.
+   */
+  const inScope = isString(opts.scope) && opts.scope ? scopeTest(opts.scope) : () => true;
   /*
    * SAFETY: MiniSearch copies every name in STORE_FIELDS from the indexed document onto its hit,
    * and every document came from the emitted envelope, whose SearchDocuments carry collection,
@@ -396,8 +452,8 @@ export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] |
    * are optional in RawHit). MiniSearch types the hit's `id` as `any`; it is the document's own
    * `id`, which SearchDocument declares a string.
    */
-  const raw = (state.mini.search(text) as RawHit[]).filter((hit) =>
-    localeAnswers(hit.locale, want),
+  const raw = (state.mini.search(text) as RawHit[]).filter(
+    (hit) => localeAnswers(hit.locale, want) && inScope(hit.url),
   );
   if (!group) {
     const pageCap = opts.pageCap ?? PAGE_CAP;
@@ -449,6 +505,8 @@ export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] |
 export interface SearchComponentState {
   /** Index URL override for `preload`. */
   searchIndexUrl?: JsonValue | undefined;
+  /** The part of the site to search (`QueryOptions.scope`); `""` or absent searches everything. */
+  searchScope?: JsonValue | undefined;
   /** The query text; `runSearch` writes back the query it ran. */
   searchQuery?: JsonValue | undefined;
   /** Set true once the index is loaded. */
@@ -482,8 +540,9 @@ const UI_LIMIT = 20;
 
 /**
  * State-convention query handler for `$src` component use: reads the query from the input event (or
- * `state.searchQuery`), stores flat highlighted rows on `state.searchResults`, publishes the row
- * count as `state.searchCount`, and resets the active-row index.
+ * `state.searchQuery`), searches within `state.searchScope` when it is a non-empty string, stores
+ * flat highlighted rows on `state.searchResults`, publishes the row count as `state.searchCount`,
+ * and resets the active-row index.
  */
 export function runSearch(
   componentState: SearchComponentState,
@@ -492,7 +551,11 @@ export function runSearch(
   const fromEvent = event?.target && isString(event.target.value) ? event.target.value : null;
   const q = fromEvent ?? (isString(componentState.searchQuery) ? componentState.searchQuery : "");
   componentState.searchQuery = q;
-  const results = query(q, { group: false, limit: UI_LIMIT });
+  const opts: QueryOptions & { group: false } = { group: false, limit: UI_LIMIT };
+  if (isString(componentState.searchScope)) {
+    opts.scope = componentState.searchScope;
+  }
+  const results = query(q, opts);
   componentState.searchResults = results;
   componentState.searchCount = results.length;
   componentState.searchActive = 0;

package/src/search-state.ts

@@ -42,6 +42,12 @@ export interface SearchDef {
    * reader the English copy of the page they are on. `null` searches every language.
    */
   locale?: string | null;
+  /**
+   * The part of the site to search: a URL prefix a result's URL must fall within (the client's
+   * `QueryOptions.scope`). A literal string or a `$ref` into page state, so a layout can scope each
+   * page to its own section of the site. Omitted, the whole index is searched.
+   */
+  scope?: string | { $ref: string };
   default?: JsonValue;
   /** Any other key an author wrote on the def: document JSON this class does not read. */
   [key: string]: JsonValue | undefined;
@@ -74,15 +80,20 @@ function inBrowser(): boolean {
   return typeof document !== "undefined" && isFunction(globalThis.fetch);
 }
 
-/** Compile a def's `query` into a client JS expression (`$ref` → state path, literal → string). */
-function queryExpression(query: SearchDef["query"]): string {
-  if (isNonNullObject(query) && isString(query.$ref)) {
-    const path = query.$ref.replace(/^#\//, "").split("/");
+/** A `$ref` into page state as a client JS expression (`#/state/a/b` → `state.a.b`), else null. */
+function stateExpression(value: SearchDef["query"] | SearchDef["scope"]): string | null {
+  if (isNonNullObject(value) && isString(value.$ref)) {
+    const path = value.$ref.replace(/^#\//, "").split("/");
     if (path[0] === "state" && path.length > 1) {
       return ["state", ...path.slice(1)].join(".");
     }
   }
-  return JSON.stringify(isString(query) ? query : "");
+  return null;
+}
+
+/** Compile a def's `query` into a client JS expression (`$ref` → state path, literal → string). */
+function queryExpression(query: SearchDef["query"]): string {
+  return stateExpression(query) ?? JSON.stringify(isString(query) ? query : "");
 }
 
 export class Search {
@@ -114,6 +125,9 @@ export class Search {
     if (this.config.locale !== undefined) {
       opts.locale = this.config.locale;
     }
+    if (isString(this.config.scope)) {
+      opts.scope = this.config.scope;
+    }
     return client.query(query, opts);
   }
 
@@ -139,7 +153,17 @@ export class Search {
     if (def.locale !== undefined) {
       queryOptions.locale = def.locale;
     }
-    const opts = JSON.stringify(queryOptions);
+    if (isString(def.scope)) {
+      queryOptions.scope = def.scope;
+    }
+    /*
+     * A `$ref` scope is read when the query runs, not baked in: the options literal is extended with
+     * the state path, so the computed re-runs when the scope changes, as it does for the query.
+     */
+    const scopeRef = stateExpression(def.scope);
+    const opts = scopeRef
+      ? `Object.assign(${JSON.stringify(queryOptions)}, { scope: ${scopeRef} })`
+      : JSON.stringify(queryOptions);
     const body = [
       // Reading the ready flag makes the computed re-run when the client finishes loading.
       "void state.__jxSearchReady;",