@uniformdev/search 0.0.1 → 0.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Uniform
+Copyright (c) 2026 Uniform Systems, 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

package/README.md

@@ -0,0 +1,129 @@
+# @uniformdev/search
+
+A lightweight client for [Uniform Search](https://uniform.dev) with optional React bindings for building faceted search experiences (filters, sorting, pagination, and URL-synced state).
+
+The core client is framework-agnostic. The React bindings are exposed from a separate `@uniformdev/search/react` entry point and `react` is an optional peer dependency, so you only pull in React if you use them.
+
+## Installation
+
+```bash
+npm install @uniformdev/search
+# or
+pnpm add @uniformdev/search
+# or
+yarn add @uniformdev/search
+```
+
+To use the React bindings, make sure React 18+ is installed in your app:
+
+```bash
+npm install react
+```
+
+## Quick start
+
+### 1. Create a search client
+
+The client posts to `${apiUrl}/api/search` and (optionally) attaches an `x-api-key` header. Configure it with your Uniform Search service URL, API key, and project ID:
+
+```ts
+import { createSearchClient } from '@uniformdev/search';
+
+const client = createSearchClient({
+  apiUrl: process.env.NEXT_PUBLIC_UNIFORM_SEARCH_API_URL!, // https://<your-project>.search.uniform.app
+  apiKey: process.env.NEXT_PUBLIC_UNIFORM_SEARCH_API_KEY,
+  projectId: process.env.NEXT_PUBLIC_UNIFORM_PROJECT_ID,
+});
+
+const result = await client.performSearch({
+  search: 'hello world',
+  page: 0,
+  perPage: 10,
+});
+
+console.log(result.data.items, result.data.total, result.facets);
+```
+
+`performSearch` never throws — on a network or non-2xx error it logs and returns an empty result shape so your UI can render safely.
+
+### 2. (React) Wire up the provider
+
+```tsx
+import { SearchProvider, useSearch } from '@uniformdev/search/react';
+import { createSearchClient } from '@uniformdev/search';
+
+const client = createSearchClient({
+  apiUrl: process.env.NEXT_PUBLIC_UNIFORM_SEARCH_API_URL!,
+  apiKey: process.env.NEXT_PUBLIC_UNIFORM_SEARCH_API_KEY,
+  projectId: process.env.NEXT_PUBLIC_UNIFORM_PROJECT_ID,
+});
+
+export function SearchPage() {
+  return (
+    <SearchProvider performSearch={client.performSearch}>
+      <SearchBox />
+      <Results />
+    </SearchProvider>
+  );
+}
+
+function SearchBox() {
+  const { searchBoxValue, setSearchQuery } = useSearch();
+  return (
+    <input
+      value={searchBoxValue}
+      onChange={(e) => setSearchQuery(e.target.value)}
+      placeholder="Search…"
+    />
+  );
+}
+
+function Results() {
+  const { results, isLoading } = useSearch();
+  if (isLoading) return <p>Loading…</p>;
+  return (
+    <ul>
+      {results.items.map((item) => (
+        <li key={item.id}>{String(item.title ?? item.id)}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+The provider keeps search state (query, page, page size, sort, and selected filters) in sync with the URL query string and debounces text input.
+
+## API
+
+### Core (`@uniformdev/search`)
+
+| Export | Description |
+|---|---|
+| `createSearchClient(config)` | Creates a `SearchClient` with a `performSearch(params)` method. |
+| `getSearchParamsFromUrl(url)` | Parses a URL's query string into a params object. |
+| `buildOrderByQuery(orderBy)` | Builds an `orderBy` query string (e.g. `created_at_DESC`). |
+| `flattenBlockParams(value)` | Normalizes Uniform block parameter values into a flat array. |
+| Types | `SearchParams`, `SearchClient`, `CollectionResult`, `SearchHit`, `Pagination`, `Facets`, `FacetBy`, `OrderBy`, `PageSize`, and more. |
+
+### React (`@uniformdev/search/react`)
+
+| Export | Description |
+|---|---|
+| `SearchProvider` | Context provider that owns search state and runs queries. |
+| `useSearch()` | Hook returning results, facets, loading state, and state setters. Must be used inside a `SearchProvider`. |
+| `usePagination`, `useSearchPagination`, `DOTS` | Pagination helpers. |
+| `SearchItemUrlResolverProvider`, `useUrlResolver`, `createDefaultUrlResolver` | Resolve result items to URLs. |
+
+## Configuration
+
+`createSearchClient` accepts:
+
+| Option | Required | Description |
+|---|---|---|
+| `apiUrl` | yes | Base URL of your Uniform Search service. `/api/search` is appended automatically. |
+| `apiKey` | no | Sent as the `x-api-key` header. |
+| `projectId` | no | Default project ID, merged into each request body. |
+
+## License
+
+MIT

package/dist/{chunk-ZABEFR2D.mjs → chunk-RMUYFKZO.mjs}

@@ -8,7 +8,14 @@ var DEFAULT_PAGE_SIZE = 10;
 
 // src/utils.ts
 var buildOrderByQuery = (orderBy) => {
-  return `${orderBy.field}_${orderBy.direction}`;
+  var _a;
+  const field = orderBy.field;
+  if (field && typeof field === "object" && "field" in field) {
+    const sv = field;
+    return `${sv.field}_${sv.direction.toUpperCase()}`;
+  }
+  if (!field || field === "relevance") return "";
+  return `${field}_${(_a = orderBy.direction) != null ? _a : "ASC"}`;
 };
 var getSearchParamsFromUrl = (urlString) => {
   if (!urlString) {
@@ -28,13 +35,13 @@ var getSearchParamsFromUrl = (urlString) => {
 
 // src/flattenBlockParams.ts
 function resolveFieldValue(field, locale = "en-us") {
-  var _a, _b;
+  var _a;
   if (!field || typeof field !== "object") return field;
   if (field.type === "$block" && Array.isArray(field.value)) {
     return flattenBlockParams(field.value, locale);
   }
   if (field.locales && typeof field.locales === "object") {
-    return (_b = (_a = field.locales[locale]) != null ? _a : Object.values(field.locales)[0]) != null ? _b : field.value;
+    return (_a = field.locales[locale]) != null ? _a : field.value;
   }
   return field.value;
 }
@@ -63,4 +70,4 @@ export {
   getSearchParamsFromUrl,
   flattenBlockParams
 };
-//# sourceMappingURL=chunk-ZABEFR2D.mjs.map
+//# sourceMappingURL=chunk-RMUYFKZO.mjs.map

package/dist/chunk-RMUYFKZO.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/utils.ts","../src/flattenBlockParams.ts"],"sourcesContent":["export const UNIFORM_SEARCH_QUERY_KEY = 'search';\nexport const UNIFORM_SEARCH_PAGE_KEY = 'page';\nexport const UNIFORM_SEARCH_PAGE_SIZE_KEY = 'pageSize';\nexport const UNIFORM_SEARCH_ORDER_BY_KEY = 'orderBy';\nexport const FIRST_PAGE = 0;\nexport const DEFAULT_PAGE_SIZE = 10;\n","import type { OrderBy } from './types';\n\nexport const buildOrderByQuery = (orderBy: OrderBy) => {\n  const field = orderBy.field as unknown;\n  // sortByConfig produces an object value: { field: string; direction: 'asc' | 'desc' }\n  if (field && typeof field === 'object' && 'field' in (field as object)) {\n    const sv = field as { field: string; direction: string };\n    return `${sv.field}_${sv.direction.toUpperCase()}`;\n  }\n  // Plain string \"relevance\" or missing direction → no sort\n  if (!field || field === 'relevance') return '';\n  return `${field}_${orderBy.direction ?? 'ASC'}`;\n};\n\nexport const getSearchParamsFromUrl = (urlString: string): Record<string, string | string[]> => {\n  if (!urlString) {\n    return {};\n  }\n\n  const url = new URL(urlString);\n  const params: Record<string, string | string[]> = {};\n\n  url.searchParams.forEach((value, key) => {\n    if (params[key]) {\n      params[key] = Array.isArray(params[key])\n        ? [...(params[key] as string[]), value]\n        : [params[key] as string, value];\n    } else {\n      params[key] = value;\n    }\n  });\n\n  return params;\n};\n","type RawField = {\n  type?: string;\n  value?: unknown;\n  locales?: Record<string, unknown>;\n};\n\ntype RawBlockItem = {\n  type?: string;\n  fields?: Record<string, RawField>;\n};\n\nfunction resolveFieldValue(field: RawField, locale = 'en-us'): unknown {\n  if (!field || typeof field !== 'object') return field;\n\n  if (field.type === '$block' && Array.isArray(field.value)) {\n    return flattenBlockParams(field.value as RawBlockItem[], locale);\n  }\n\n  if (field.locales && typeof field.locales === 'object') {\n    return field.locales[locale] ?? field.value;\n  }\n\n  return field.value;\n}\n\nexport function flattenBlockParams<T = Record<string, unknown>>(\n  items: unknown,\n  locale = 'en-us'\n): T[] {\n  if (!Array.isArray(items)) return [];\n  return items.map(item => {\n    const result: Record<string, unknown> = {};\n    const blockItem = item as RawBlockItem;\n    if (blockItem.fields) {\n      for (const [key, field] of Object.entries(blockItem.fields)) {\n        result[key] = resolveFieldValue(field, locale);\n      }\n    }\n    return result as T;\n  });\n}\n"],"mappings":";AAAO,IAAM,2BAA2B;AACjC,IAAM,0BAA0B;AAChC,IAAM,+BAA+B;AACrC,IAAM,8BAA8B;AACpC,IAAM,aAAa;AACnB,IAAM,oBAAoB;;;ACH1B,IAAM,oBAAoB,CAAC,YAAqB;AAFvD;AAGE,QAAM,QAAQ,QAAQ;AAEtB,MAAI,SAAS,OAAO,UAAU,YAAY,WAAY,OAAkB;AACtE,UAAM,KAAK;AACX,WAAO,GAAG,GAAG,KAAK,IAAI,GAAG,UAAU,YAAY,CAAC;AAAA,EAClD;AAEA,MAAI,CAAC,SAAS,UAAU,YAAa,QAAO;AAC5C,SAAO,GAAG,KAAK,KAAI,aAAQ,cAAR,YAAqB,KAAK;AAC/C;AAEO,IAAM,yBAAyB,CAAC,cAAyD;AAC9F,MAAI,CAAC,WAAW;AACd,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,MAAM,IAAI,IAAI,SAAS;AAC7B,QAAM,SAA4C,CAAC;AAEnD,MAAI,aAAa,QAAQ,CAAC,OAAO,QAAQ;AACvC,QAAI,OAAO,GAAG,GAAG;AACf,aAAO,GAAG,IAAI,MAAM,QAAQ,OAAO,GAAG,CAAC,IACnC,CAAC,GAAI,OAAO,GAAG,GAAgB,KAAK,IACpC,CAAC,OAAO,GAAG,GAAa,KAAK;AAAA,IACnC,OAAO;AACL,aAAO,GAAG,IAAI;AAAA,IAChB;AAAA,EACF,CAAC;AAED,SAAO;AACT;;;ACtBA,SAAS,kBAAkB,OAAiB,SAAS,SAAkB;AAXvE;AAYE,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;AAEhD,MAAI,MAAM,SAAS,YAAY,MAAM,QAAQ,MAAM,KAAK,GAAG;AACzD,WAAO,mBAAmB,MAAM,OAAyB,MAAM;AAAA,EACjE;AAEA,MAAI,MAAM,WAAW,OAAO,MAAM,YAAY,UAAU;AACtD,YAAO,WAAM,QAAQ,MAAM,MAApB,YAAyB,MAAM;AAAA,EACxC;AAEA,SAAO,MAAM;AACf;AAEO,SAAS,mBACd,OACA,SAAS,SACJ;AACL,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACnC,SAAO,MAAM,IAAI,UAAQ;AACvB,UAAM,SAAkC,CAAC;AACzC,UAAM,YAAY;AAClB,QAAI,UAAU,QAAQ;AACpB,iBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,UAAU,MAAM,GAAG;AAC3D,eAAO,GAAG,IAAI,kBAAkB,OAAO,MAAM;AAAA,MAC/C;AAAA,IACF;AACA,WAAO;AAAA,EACT,CAAC;AACH;","names":[]}

package/dist/{client-DrL-8TfY.d.mts → client-CtTcEJUy.d.mts}

@@ -15,20 +15,14 @@ type CollectionResult = {
     data: Pagination<SearchHit>;
     facets: Facets;
 };
-type MultiSearchResult = {
-    [K in SearchCollection]?: CollectionResult;
-};
 type FilterByItem = {
     title: string;
     value: string;
 };
-type FilterBy = {
+type FacetBy = {
     type: 'select' | 'multiSelect' | 'range';
     title: string;
-    fieldId: string;
     fieldKey: string;
-    enableFaceting: boolean;
-    values: FilterByItem[];
 };
 type OrderBy = {
     title: string;
@@ -46,21 +40,29 @@ type Facets = {
 type FilterQuery = {
     [K: string]: string[];
 };
+type SearchItemConfig = {
+    source: string;
+    type: string;
+    nodeId?: string;
+    urlTemplate?: string;
+    tokenMapping?: Record<string, string>;
+};
 
 interface SearchParams {
     projectId?: string;
     page?: number;
     perPage?: number;
     filters?: Record<string, unknown>;
+    baseFilterBy?: string;
     facetBy?: string;
+    queryBy?: string;
     search?: string;
     orderBy?: string;
-    collections?: SearchCollection[];
+    locale?: string;
+    maxFacetValues?: number;
 }
 interface SearchClient {
-    performSearch(params: SearchParams): Promise<{
-        results: MultiSearchResult;
-    }>;
+    performSearch(params: SearchParams): Promise<CollectionResult>;
 }
 declare function createSearchClient(config: {
     apiUrl: string;
@@ -68,4 +70,4 @@ declare function createSearchClient(config: {
     projectId?: string;
 }): SearchClient;
 
-export { type CollectionResult as C, type Facets as F, type MultiSearchResult as M, type OrderBy as O, type PageSize as P, type SearchClient as S, type FilterBy as a, type FilterByItem as b, type FilterQuery as c, type Pagination as d, type SearchCollection as e, type SearchHit as f, type SearchParams as g, createSearchClient as h };
+export { type CollectionResult as C, type FacetBy as F, type OrderBy as O, type PageSize as P, type SearchClient as S, type Facets as a, type FilterByItem as b, type FilterQuery as c, type Pagination as d, type SearchCollection as e, type SearchHit as f, type SearchItemConfig as g, type SearchParams as h, createSearchClient as i };

package/dist/{client-DrL-8TfY.d.ts → client-CtTcEJUy.d.ts}

@@ -15,20 +15,14 @@ type CollectionResult = {
     data: Pagination<SearchHit>;
     facets: Facets;
 };
-type MultiSearchResult = {
-    [K in SearchCollection]?: CollectionResult;
-};
 type FilterByItem = {
     title: string;
     value: string;
 };
-type FilterBy = {
+type FacetBy = {
     type: 'select' | 'multiSelect' | 'range';
     title: string;
-    fieldId: string;
     fieldKey: string;
-    enableFaceting: boolean;
-    values: FilterByItem[];
 };
 type OrderBy = {
     title: string;
@@ -46,21 +40,29 @@ type Facets = {
 type FilterQuery = {
     [K: string]: string[];
 };
+type SearchItemConfig = {
+    source: string;
+    type: string;
+    nodeId?: string;
+    urlTemplate?: string;
+    tokenMapping?: Record<string, string>;
+};
 
 interface SearchParams {
     projectId?: string;
     page?: number;
     perPage?: number;
     filters?: Record<string, unknown>;
+    baseFilterBy?: string;
     facetBy?: string;
+    queryBy?: string;
     search?: string;
     orderBy?: string;
-    collections?: SearchCollection[];
+    locale?: string;
+    maxFacetValues?: number;
 }
 interface SearchClient {
-    performSearch(params: SearchParams): Promise<{
-        results: MultiSearchResult;
-    }>;
+    performSearch(params: SearchParams): Promise<CollectionResult>;
 }
 declare function createSearchClient(config: {
     apiUrl: string;
@@ -68,4 +70,4 @@ declare function createSearchClient(config: {
     projectId?: string;
 }): SearchClient;
 
-export { type CollectionResult as C, type Facets as F, type MultiSearchResult as M, type OrderBy as O, type PageSize as P, type SearchClient as S, type FilterBy as a, type FilterByItem as b, type FilterQuery as c, type Pagination as d, type SearchCollection as e, type SearchHit as f, type SearchParams as g, createSearchClient as h };
+export { type CollectionResult as C, type FacetBy as F, type OrderBy as O, type PageSize as P, type SearchClient as S, type Facets as a, type FilterByItem as b, type FilterQuery as c, type Pagination as d, type SearchCollection as e, type SearchHit as f, type SearchItemConfig as g, type SearchParams as h, createSearchClient as i };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { O as OrderBy } from './client-DrL-8TfY.mjs';
-export { C as CollectionResult, F as Facets, a as FilterBy, b as FilterByItem, c as FilterQuery, M as MultiSearchResult, P as PageSize, d as Pagination, S as SearchClient, e as SearchCollection, f as SearchHit, g as SearchParams, h as createSearchClient } from './client-DrL-8TfY.mjs';
+import { O as OrderBy } from './client-CtTcEJUy.mjs';
+export { C as CollectionResult, F as FacetBy, a as Facets, b as FilterByItem, c as FilterQuery, P as PageSize, d as Pagination, S as SearchClient, e as SearchCollection, f as SearchHit, g as SearchItemConfig, h as SearchParams, i as createSearchClient } from './client-CtTcEJUy.mjs';
 
 declare const UNIFORM_SEARCH_QUERY_KEY = "search";
 declare const UNIFORM_SEARCH_PAGE_KEY = "page";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { O as OrderBy } from './client-DrL-8TfY.js';
-export { C as CollectionResult, F as Facets, a as FilterBy, b as FilterByItem, c as FilterQuery, M as MultiSearchResult, P as PageSize, d as Pagination, S as SearchClient, e as SearchCollection, f as SearchHit, g as SearchParams, h as createSearchClient } from './client-DrL-8TfY.js';
+import { O as OrderBy } from './client-CtTcEJUy.js';
+export { C as CollectionResult, F as FacetBy, a as Facets, b as FilterByItem, c as FilterQuery, P as PageSize, d as Pagination, S as SearchClient, e as SearchCollection, f as SearchHit, g as SearchItemConfig, h as SearchParams, i as createSearchClient } from './client-CtTcEJUy.js';
 
 declare const UNIFORM_SEARCH_QUERY_KEY = "search";
 declare const UNIFORM_SEARCH_PAGE_KEY = "page";

package/dist/index.js

@@ -42,7 +42,12 @@ var FIRST_PAGE = 0;
 var DEFAULT_PAGE_SIZE = 10;
 
 // src/client.ts
+var emptyResult = () => ({
+  data: { items: [], total: 0, page: 0, perPage: 10, totalPages: 0 },
+  facets: {}
+});
 function createSearchClient(config) {
+  const baseUrl = config.apiUrl.replace(/\/+$/, "");
   return {
     async performSearch(params) {
       const headers = {
@@ -56,19 +61,19 @@ function createSearchClient(config) {
         projectId: params.projectId || config.projectId
       };
       try {
-        const response = await fetch(`${config.apiUrl}/api/search`, {
+        const response = await fetch(`${baseUrl}/api/search`, {
           method: "POST",
           headers,
           body: JSON.stringify(body)
         });
         if (!response.ok) {
           console.error(`[alex] Search API error: ${response.status}`);
-          return { results: {} };
+          return emptyResult();
         }
         return response.json();
       } catch (error) {
         console.error("[alex] Search fetch error:", error);
-        return { results: {} };
+        return emptyResult();
       }
     }
   };
@@ -76,7 +81,14 @@ function createSearchClient(config) {
 
 // src/utils.ts
 var buildOrderByQuery = (orderBy) => {
-  return `${orderBy.field}_${orderBy.direction}`;
+  var _a;
+  const field = orderBy.field;
+  if (field && typeof field === "object" && "field" in field) {
+    const sv = field;
+    return `${sv.field}_${sv.direction.toUpperCase()}`;
+  }
+  if (!field || field === "relevance") return "";
+  return `${field}_${(_a = orderBy.direction) != null ? _a : "ASC"}`;
 };
 var getSearchParamsFromUrl = (urlString) => {
   if (!urlString) {
@@ -96,13 +108,13 @@ var getSearchParamsFromUrl = (urlString) => {
 
 // src/flattenBlockParams.ts
 function resolveFieldValue(field, locale = "en-us") {
-  var _a, _b;
+  var _a;
   if (!field || typeof field !== "object") return field;
   if (field.type === "$block" && Array.isArray(field.value)) {
     return flattenBlockParams(field.value, locale);
   }
   if (field.locales && typeof field.locales === "object") {
-    return (_b = (_a = field.locales[locale]) != null ? _a : Object.values(field.locales)[0]) != null ? _b : field.value;
+    return (_a = field.locales[locale]) != null ? _a : field.value;
   }
   return field.value;
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/constants.ts","../src/client.ts","../src/utils.ts","../src/flattenBlockParams.ts"],"sourcesContent":["export * from './types';\nexport * from './constants';\nexport * from './client';\nexport * from './utils';\nexport * from './flattenBlockParams';\n","export const UNIFORM_SEARCH_QUERY_KEY = 'search';\nexport const UNIFORM_SEARCH_PAGE_KEY = 'page';\nexport const UNIFORM_SEARCH_PAGE_SIZE_KEY = 'pageSize';\nexport const UNIFORM_SEARCH_ORDER_BY_KEY = 'orderBy';\nexport const FIRST_PAGE = 0;\nexport const DEFAULT_PAGE_SIZE = 10;\n","import type { SearchCollection, MultiSearchResult } from './types';\n\nexport interface SearchParams {\n  projectId?: string;\n  page?: number;\n  perPage?: number;\n  filters?: Record<string, unknown>;\n  facetBy?: string;\n  search?: string;\n  orderBy?: string;\n  collections?: SearchCollection[];\n}\n\nexport interface SearchClient {\n  performSearch(params: SearchParams): Promise<{ results: MultiSearchResult }>;\n}\n\nexport function createSearchClient(config: {\n  apiUrl: string;\n  apiKey?: string;\n  projectId?: string;\n}): SearchClient {\n  return {\n    async performSearch(params) {\n      const headers: Record<string, string> = {\n        'Content-Type': 'application/json',\n      };\n      if (config.apiKey) {\n        headers['x-api-key'] = config.apiKey;\n      }\n\n      const body = {\n        ...params,\n        projectId: params.projectId || config.projectId,\n      };\n\n      try {\n        const response = await fetch(`${config.apiUrl}/api/search`, {\n          method: 'POST',\n          headers,\n          body: JSON.stringify(body),\n        });\n\n        if (!response.ok) {\n          console.error(`[alex] Search API error: ${response.status}`);\n          return { results: {} };\n        }\n\n        return response.json();\n      } catch (error) {\n        console.error('[alex] Search fetch error:', error);\n        return { results: {} };\n      }\n    },\n  };\n}\n","import type { OrderBy } from './types';\n\nexport const buildOrderByQuery = (orderBy: OrderBy) => {\n  return `${orderBy.field}_${orderBy.direction}`;\n};\n\nexport const getSearchParamsFromUrl = (urlString: string): Record<string, string | string[]> => {\n  if (!urlString) {\n    return {};\n  }\n\n  const url = new URL(urlString);\n  const params: Record<string, string | string[]> = {};\n\n  url.searchParams.forEach((value, key) => {\n    if (params[key]) {\n      params[key] = Array.isArray(params[key])\n        ? [...(params[key] as string[]), value]\n        : [params[key] as string, value];\n    } else {\n      params[key] = value;\n    }\n  });\n\n  return params;\n};\n","type RawField = {\n  type?: string;\n  value?: unknown;\n  locales?: Record<string, unknown>;\n};\n\ntype RawBlockItem = {\n  type?: string;\n  fields?: Record<string, RawField>;\n};\n\nfunction resolveFieldValue(field: RawField, locale = 'en-us'): unknown {\n  if (!field || typeof field !== 'object') return field;\n\n  if (field.type === '$block' && Array.isArray(field.value)) {\n    return flattenBlockParams(field.value as RawBlockItem[], locale);\n  }\n\n  if (field.locales && typeof field.locales === 'object') {\n    return field.locales[locale] ?? Object.values(field.locales)[0] ?? field.value;\n  }\n\n  return field.value;\n}\n\nexport function flattenBlockParams<T = Record<string, unknown>>(\n  items: unknown,\n  locale = 'en-us'\n): T[] {\n  if (!Array.isArray(items)) return [];\n  return items.map(item => {\n    const result: Record<string, unknown> = {};\n    const blockItem = item as RawBlockItem;\n    if (blockItem.fields) {\n      for (const [key, field] of Object.entries(blockItem.fields)) {\n        result[key] = resolveFieldValue(field, locale);\n      }\n    }\n    return result as T;\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAO,IAAM,2BAA2B;AACjC,IAAM,0BAA0B;AAChC,IAAM,+BAA+B;AACrC,IAAM,8BAA8B;AACpC,IAAM,aAAa;AACnB,IAAM,oBAAoB;;;ACY1B,SAAS,mBAAmB,QAIlB;AACf,SAAO;AAAA,IACL,MAAM,cAAc,QAAQ;AAC1B,YAAM,UAAkC;AAAA,QACtC,gBAAgB;AAAA,MAClB;AACA,UAAI,OAAO,QAAQ;AACjB,gBAAQ,WAAW,IAAI,OAAO;AAAA,MAChC;AAEA,YAAM,OAAO;AAAA,QACX,GAAG;AAAA,QACH,WAAW,OAAO,aAAa,OAAO;AAAA,MACxC;AAEA,UAAI;AACF,cAAM,WAAW,MAAM,MAAM,GAAG,OAAO,MAAM,eAAe;AAAA,UAC1D,QAAQ;AAAA,UACR;AAAA,UACA,MAAM,KAAK,UAAU,IAAI;AAAA,QAC3B,CAAC;AAED,YAAI,CAAC,SAAS,IAAI;AAChB,kBAAQ,MAAM,4BAA4B,SAAS,MAAM,EAAE;AAC3D,iBAAO,EAAE,SAAS,CAAC,EAAE;AAAA,QACvB;AAEA,eAAO,SAAS,KAAK;AAAA,MACvB,SAAS,OAAO;AACd,gBAAQ,MAAM,8BAA8B,KAAK;AACjD,eAAO,EAAE,SAAS,CAAC,EAAE;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AACF;;;ACrDO,IAAM,oBAAoB,CAAC,YAAqB;AACrD,SAAO,GAAG,QAAQ,KAAK,IAAI,QAAQ,SAAS;AAC9C;AAEO,IAAM,yBAAyB,CAAC,cAAyD;AAC9F,MAAI,CAAC,WAAW;AACd,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,MAAM,IAAI,IAAI,SAAS;AAC7B,QAAM,SAA4C,CAAC;AAEnD,MAAI,aAAa,QAAQ,CAAC,OAAO,QAAQ;AACvC,QAAI,OAAO,GAAG,GAAG;AACf,aAAO,GAAG,IAAI,MAAM,QAAQ,OAAO,GAAG,CAAC,IACnC,CAAC,GAAI,OAAO,GAAG,GAAgB,KAAK,IACpC,CAAC,OAAO,GAAG,GAAa,KAAK;AAAA,IACnC,OAAO;AACL,aAAO,GAAG,IAAI;AAAA,IAChB;AAAA,EACF,CAAC;AAED,SAAO;AACT;;;ACdA,SAAS,kBAAkB,OAAiB,SAAS,SAAkB;AAXvE;AAYE,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;AAEhD,MAAI,MAAM,SAAS,YAAY,MAAM,QAAQ,MAAM,KAAK,GAAG;AACzD,WAAO,mBAAmB,MAAM,OAAyB,MAAM;AAAA,EACjE;AAEA,MAAI,MAAM,WAAW,OAAO,MAAM,YAAY,UAAU;AACtD,YAAO,iBAAM,QAAQ,MAAM,MAApB,YAAyB,OAAO,OAAO,MAAM,OAAO,EAAE,CAAC,MAAvD,YAA4D,MAAM;AAAA,EAC3E;AAEA,SAAO,MAAM;AACf;AAEO,SAAS,mBACd,OACA,SAAS,SACJ;AACL,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACnC,SAAO,MAAM,IAAI,UAAQ;AACvB,UAAM,SAAkC,CAAC;AACzC,UAAM,YAAY;AAClB,QAAI,UAAU,QAAQ;AACpB,iBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,UAAU,MAAM,GAAG;AAC3D,eAAO,GAAG,IAAI,kBAAkB,OAAO,MAAM;AAAA,MAC/C;AAAA,IACF;AACA,WAAO;AAAA,EACT,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/constants.ts","../src/client.ts","../src/utils.ts","../src/flattenBlockParams.ts"],"sourcesContent":["export * from './types';\nexport * from './constants';\nexport * from './client';\nexport * from './utils';\nexport * from './flattenBlockParams';\n","export const UNIFORM_SEARCH_QUERY_KEY = 'search';\nexport const UNIFORM_SEARCH_PAGE_KEY = 'page';\nexport const UNIFORM_SEARCH_PAGE_SIZE_KEY = 'pageSize';\nexport const UNIFORM_SEARCH_ORDER_BY_KEY = 'orderBy';\nexport const FIRST_PAGE = 0;\nexport const DEFAULT_PAGE_SIZE = 10;\n","import type { CollectionResult } from './types';\n\nexport interface SearchParams {\n  projectId?: string;\n  page?: number;\n  perPage?: number;\n  filters?: Record<string, unknown>;\n  baseFilterBy?: string;\n  facetBy?: string;\n  queryBy?: string;\n  search?: string;\n  orderBy?: string;\n  locale?: string;\n  maxFacetValues?: number;\n}\n\nexport interface SearchClient {\n  performSearch(params: SearchParams): Promise<CollectionResult>;\n}\n\nconst emptyResult = (): CollectionResult => ({\n  data: { items: [], total: 0, page: 0, perPage: 10, totalPages: 0 },\n  facets: {},\n});\n\nexport function createSearchClient(config: { apiUrl: string; apiKey?: string; projectId?: string }): SearchClient {\n  const baseUrl = config.apiUrl.replace(/\\/+$/, '');\n  return {\n    async performSearch(params) {\n      const headers: Record<string, string> = {\n        'Content-Type': 'application/json',\n      };\n      if (config.apiKey) {\n        headers['x-api-key'] = config.apiKey;\n      }\n\n      const body = {\n        ...params,\n        projectId: params.projectId || config.projectId,\n      };\n\n      try {\n        const response = await fetch(`${baseUrl}/api/search`, {\n          method: 'POST',\n          headers,\n          body: JSON.stringify(body),\n        });\n\n        if (!response.ok) {\n          console.error(`[alex] Search API error: ${response.status}`);\n          return emptyResult();\n        }\n\n        return response.json();\n      } catch (error) {\n        console.error('[alex] Search fetch error:', error);\n        return emptyResult();\n      }\n    },\n  };\n}\n","import type { OrderBy } from './types';\n\nexport const buildOrderByQuery = (orderBy: OrderBy) => {\n  const field = orderBy.field as unknown;\n  // sortByConfig produces an object value: { field: string; direction: 'asc' | 'desc' }\n  if (field && typeof field === 'object' && 'field' in (field as object)) {\n    const sv = field as { field: string; direction: string };\n    return `${sv.field}_${sv.direction.toUpperCase()}`;\n  }\n  // Plain string \"relevance\" or missing direction → no sort\n  if (!field || field === 'relevance') return '';\n  return `${field}_${orderBy.direction ?? 'ASC'}`;\n};\n\nexport const getSearchParamsFromUrl = (urlString: string): Record<string, string | string[]> => {\n  if (!urlString) {\n    return {};\n  }\n\n  const url = new URL(urlString);\n  const params: Record<string, string | string[]> = {};\n\n  url.searchParams.forEach((value, key) => {\n    if (params[key]) {\n      params[key] = Array.isArray(params[key])\n        ? [...(params[key] as string[]), value]\n        : [params[key] as string, value];\n    } else {\n      params[key] = value;\n    }\n  });\n\n  return params;\n};\n","type RawField = {\n  type?: string;\n  value?: unknown;\n  locales?: Record<string, unknown>;\n};\n\ntype RawBlockItem = {\n  type?: string;\n  fields?: Record<string, RawField>;\n};\n\nfunction resolveFieldValue(field: RawField, locale = 'en-us'): unknown {\n  if (!field || typeof field !== 'object') return field;\n\n  if (field.type === '$block' && Array.isArray(field.value)) {\n    return flattenBlockParams(field.value as RawBlockItem[], locale);\n  }\n\n  if (field.locales && typeof field.locales === 'object') {\n    return field.locales[locale] ?? field.value;\n  }\n\n  return field.value;\n}\n\nexport function flattenBlockParams<T = Record<string, unknown>>(\n  items: unknown,\n  locale = 'en-us'\n): T[] {\n  if (!Array.isArray(items)) return [];\n  return items.map(item => {\n    const result: Record<string, unknown> = {};\n    const blockItem = item as RawBlockItem;\n    if (blockItem.fields) {\n      for (const [key, field] of Object.entries(blockItem.fields)) {\n        result[key] = resolveFieldValue(field, locale);\n      }\n    }\n    return result as T;\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -8,10 +8,15 @@ import {
   buildOrderByQuery,
   flattenBlockParams,
   getSearchParamsFromUrl
-} from "./chunk-ZABEFR2D.mjs";
+} from "./chunk-RMUYFKZO.mjs";
 
 // src/client.ts
+var emptyResult = () => ({
+  data: { items: [], total: 0, page: 0, perPage: 10, totalPages: 0 },
+  facets: {}
+});
 function createSearchClient(config) {
+  const baseUrl = config.apiUrl.replace(/\/+$/, "");
   return {
     async performSearch(params) {
       const headers = {
@@ -25,19 +30,19 @@ function createSearchClient(config) {
         projectId: params.projectId || config.projectId
       };
       try {
-        const response = await fetch(`${config.apiUrl}/api/search`, {
+        const response = await fetch(`${baseUrl}/api/search`, {
           method: "POST",
           headers,
           body: JSON.stringify(body)
         });
         if (!response.ok) {
           console.error(`[alex] Search API error: ${response.status}`);
-          return { results: {} };
+          return emptyResult();
         }
         return response.json();
       } catch (error) {
         console.error("[alex] Search fetch error:", error);
-        return { results: {} };
+        return emptyResult();
       }
     }
   };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type { SearchCollection, MultiSearchResult } from './types';\n\nexport interface SearchParams {\n  projectId?: string;\n  page?: number;\n  perPage?: number;\n  filters?: Record<string, unknown>;\n  facetBy?: string;\n  search?: string;\n  orderBy?: string;\n  collections?: SearchCollection[];\n}\n\nexport interface SearchClient {\n  performSearch(params: SearchParams): Promise<{ results: MultiSearchResult }>;\n}\n\nexport function createSearchClient(config: {\n  apiUrl: string;\n  apiKey?: string;\n  projectId?: string;\n}): SearchClient {\n  return {\n    async performSearch(params) {\n      const headers: Record<string, string> = {\n        'Content-Type': 'application/json',\n      };\n      if (config.apiKey) {\n        headers['x-api-key'] = config.apiKey;\n      }\n\n      const body = {\n        ...params,\n        projectId: params.projectId || config.projectId,\n      };\n\n      try {\n        const response = await fetch(`${config.apiUrl}/api/search`, {\n          method: 'POST',\n          headers,\n          body: JSON.stringify(body),\n        });\n\n        if (!response.ok) {\n          console.error(`[alex] Search API error: ${response.status}`);\n          return { results: {} };\n        }\n\n        return response.json();\n      } catch (error) {\n        console.error('[alex] Search fetch error:', error);\n        return { results: {} };\n      }\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AAiBO,SAAS,mBAAmB,QAIlB;AACf,SAAO;AAAA,IACL,MAAM,cAAc,QAAQ;AAC1B,YAAM,UAAkC;AAAA,QACtC,gBAAgB;AAAA,MAClB;AACA,UAAI,OAAO,QAAQ;AACjB,gBAAQ,WAAW,IAAI,OAAO;AAAA,MAChC;AAEA,YAAM,OAAO;AAAA,QACX,GAAG;AAAA,QACH,WAAW,OAAO,aAAa,OAAO;AAAA,MACxC;AAEA,UAAI;AACF,cAAM,WAAW,MAAM,MAAM,GAAG,OAAO,MAAM,eAAe;AAAA,UAC1D,QAAQ;AAAA,UACR;AAAA,UACA,MAAM,KAAK,UAAU,IAAI;AAAA,QAC3B,CAAC;AAED,YAAI,CAAC,SAAS,IAAI;AAChB,kBAAQ,MAAM,4BAA4B,SAAS,MAAM,EAAE;AAC3D,iBAAO,EAAE,SAAS,CAAC,EAAE;AAAA,QACvB;AAEA,eAAO,SAAS,KAAK;AAAA,MACvB,SAAS,OAAO;AACd,gBAAQ,MAAM,8BAA8B,KAAK;AACjD,eAAO,EAAE,SAAS,CAAC,EAAE;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type { CollectionResult } from './types';\n\nexport interface SearchParams {\n  projectId?: string;\n  page?: number;\n  perPage?: number;\n  filters?: Record<string, unknown>;\n  baseFilterBy?: string;\n  facetBy?: string;\n  queryBy?: string;\n  search?: string;\n  orderBy?: string;\n  locale?: string;\n  maxFacetValues?: number;\n}\n\nexport interface SearchClient {\n  performSearch(params: SearchParams): Promise<CollectionResult>;\n}\n\nconst emptyResult = (): CollectionResult => ({\n  data: { items: [], total: 0, page: 0, perPage: 10, totalPages: 0 },\n  facets: {},\n});\n\nexport function createSearchClient(config: { apiUrl: string; apiKey?: string; projectId?: string }): SearchClient {\n  const baseUrl = config.apiUrl.replace(/\\/+$/, '');\n  return {\n    async performSearch(params) {\n      const headers: Record<string, string> = {\n        'Content-Type': 'application/json',\n      };\n      if (config.apiKey) {\n        headers['x-api-key'] = config.apiKey;\n      }\n\n      const body = {\n        ...params,\n        projectId: params.projectId || config.projectId,\n      };\n\n      try {\n        const response = await fetch(`${baseUrl}/api/search`, {\n          method: 'POST',\n          headers,\n          body: JSON.stringify(body),\n        });\n\n        if (!response.ok) {\n          console.error(`[alex] Search API error: ${response.status}`);\n          return emptyResult();\n        }\n\n        return response.json();\n      } catch (error) {\n        console.error('[alex] Search fetch error:', error);\n        return emptyResult();\n      }\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AAoBA,IAAM,cAAc,OAAyB;AAAA,EAC3C,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,IAAI,YAAY,EAAE;AAAA,EACjE,QAAQ,CAAC;AACX;AAEO,SAAS,mBAAmB,QAA+E;AAChH,QAAM,UAAU,OAAO,OAAO,QAAQ,QAAQ,EAAE;AAChD,SAAO;AAAA,IACL,MAAM,cAAc,QAAQ;AAC1B,YAAM,UAAkC;AAAA,QACtC,gBAAgB;AAAA,MAClB;AACA,UAAI,OAAO,QAAQ;AACjB,gBAAQ,WAAW,IAAI,OAAO;AAAA,MAChC;AAEA,YAAM,OAAO;AAAA,QACX,GAAG;AAAA,QACH,WAAW,OAAO,aAAa,OAAO;AAAA,MACxC;AAEA,UAAI;AACF,cAAM,WAAW,MAAM,MAAM,GAAG,OAAO,eAAe;AAAA,UACpD,QAAQ;AAAA,UACR;AAAA,UACA,MAAM,KAAK,UAAU,IAAI;AAAA,QAC3B,CAAC;AAED,YAAI,CAAC,SAAS,IAAI;AAChB,kBAAQ,MAAM,4BAA4B,SAAS,MAAM,EAAE;AAC3D,iBAAO,YAAY;AAAA,QACrB;AAEA,eAAO,SAAS,KAAK;AAAA,MACvB,SAAS,OAAO;AACd,gBAAQ,MAAM,8BAA8B,KAAK;AACjD,eAAO,YAAY;AAAA,MACrB;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/react.d.mts

@@ -1,24 +1,22 @@
+import * as react from 'react';
 import { FC, ReactNode } from 'react';
-import { g as SearchParams, M as MultiSearchResult, d as Pagination, f as SearchHit, F as Facets, P as PageSize, a as FilterBy, e as SearchCollection } from './client-DrL-8TfY.mjs';
+import { d as Pagination, f as SearchHit, a as Facets, P as PageSize, F as FacetBy, h as SearchParams, C as CollectionResult, g as SearchItemConfig } from './client-CtTcEJUy.mjs';
 
 interface SearchProviderProps {
     children: ReactNode;
-    performSearch: (params: SearchParams) => Promise<{
-        results: MultiSearchResult;
-    }>;
-    contentType?: string;
-    filterBy?: unknown;
+    performSearch: (params: SearchParams) => Promise<CollectionResult>;
     orderBy?: unknown;
-    baseFilters?: unknown;
+    baseFilterString?: string;
     pageSizes?: unknown;
-    collections?: string | string[];
+    queryBy?: string[];
     searchDebounceMs?: number;
+    locale?: string;
+    maxFacetValues?: number;
 }
 interface UseSearchReturn {
     results: Pagination<SearchHit>;
     facets: Facets | null;
     isLoading: boolean;
-    collectionResults: MultiSearchResult;
     searchBoxValue: string;
     setSearchQuery: (value: string) => void;
     page: number;
@@ -32,14 +30,19 @@ interface UseSearchReturn {
     }>;
     selectedOrderBy: string;
     setOrderBy: (query: string) => void;
-    filterOptions: FilterBy[];
+    filterOptions: FacetBy[];
+    setFilterOptions: (filters: FacetBy[]) => void;
+    /** Additive registration of a single facet option (keyed by fieldKey). Used by facet
+     *  components that mount independently (e.g. App Router slots) rather than being
+     *  enumerated by a parent. */
+    registerFilterOption: (filter: FacetBy) => void;
+    unregisterFilterOption: (fieldKey: string) => void;
     selectedFilters: Record<string, string[]>;
     setSelectedFilters: (filters: Record<string, string[]>) => void;
     clearFilters: () => void;
-    selectedCollections: SearchCollection[];
-    setSelectedCollections: (collections: SearchCollection[]) => void;
     formatResultsSummary: (template: string) => string;
 }
+declare const SearchContext: react.Context<UseSearchReturn | null>;
 declare const SearchProvider: FC<SearchProviderProps>;
 
 declare function useSearch(): UseSearchReturn;
@@ -65,4 +68,28 @@ interface UseSearchPaginationReturn {
 }
 declare function useSearchPagination(siblingCount?: number): UseSearchPaginationReturn;
 
-export { DOTS, SearchProvider, type SearchProviderProps, type UseSearchPaginationReturn, type UseSearchReturn, usePagination, useSearch, useSearchPagination };
+type UrlResolver = (hit: SearchHit) => string | undefined;
+/** Wrap your search tree to override URL building for all hits. */
+declare const SearchItemUrlResolverProvider: FC<{
+    resolver: UrlResolver;
+    children: ReactNode;
+}>;
+/** Used internally by SearchList to register the Canvas-config-driven default. */
+declare const SearchItemDefaultUrlResolverProvider: FC<{
+    resolver: UrlResolver;
+    children: ReactNode;
+}>;
+/**
+ * Always returns a resolver. User-provided resolver (SearchItemUrlResolverProvider)
+ * takes priority over the default registered by SearchList.
+ */
+declare function useUrlResolver(): UrlResolver;
+interface UrlResolverOptions {
+    /** nodeId → resolved locale-specific path (from project map). */
+    pathsByNodeId?: Record<string, string>;
+    /** Current locale, used as fallback for legacy :locale token in urlTemplate. */
+    locale?: string;
+}
+declare function createDefaultUrlResolver(configs: SearchItemConfig[], options?: UrlResolverOptions): UrlResolver;
+
+export { DOTS, SearchContext, SearchItemDefaultUrlResolverProvider, SearchItemUrlResolverProvider, SearchProvider, type SearchProviderProps, type UrlResolver, type UseSearchPaginationReturn, type UseSearchReturn, createDefaultUrlResolver, usePagination, useSearch, useSearchPagination, useUrlResolver };

package/dist/react.d.ts

@@ -1,24 +1,22 @@
+import * as react from 'react';
 import { FC, ReactNode } from 'react';
-import { g as SearchParams, M as MultiSearchResult, d as Pagination, f as SearchHit, F as Facets, P as PageSize, a as FilterBy, e as SearchCollection } from './client-DrL-8TfY.js';
+import { d as Pagination, f as SearchHit, a as Facets, P as PageSize, F as FacetBy, h as SearchParams, C as CollectionResult, g as SearchItemConfig } from './client-CtTcEJUy.js';
 
 interface SearchProviderProps {
     children: ReactNode;
-    performSearch: (params: SearchParams) => Promise<{
-        results: MultiSearchResult;
-    }>;
-    contentType?: string;
-    filterBy?: unknown;
+    performSearch: (params: SearchParams) => Promise<CollectionResult>;
     orderBy?: unknown;
-    baseFilters?: unknown;
+    baseFilterString?: string;
     pageSizes?: unknown;
-    collections?: string | string[];
+    queryBy?: string[];
     searchDebounceMs?: number;
+    locale?: string;
+    maxFacetValues?: number;
 }
 interface UseSearchReturn {
     results: Pagination<SearchHit>;
     facets: Facets | null;
     isLoading: boolean;
-    collectionResults: MultiSearchResult;
     searchBoxValue: string;
     setSearchQuery: (value: string) => void;
     page: number;
@@ -32,14 +30,19 @@ interface UseSearchReturn {
     }>;
     selectedOrderBy: string;
     setOrderBy: (query: string) => void;
-    filterOptions: FilterBy[];
+    filterOptions: FacetBy[];
+    setFilterOptions: (filters: FacetBy[]) => void;
+    /** Additive registration of a single facet option (keyed by fieldKey). Used by facet
+     *  components that mount independently (e.g. App Router slots) rather than being
+     *  enumerated by a parent. */
+    registerFilterOption: (filter: FacetBy) => void;
+    unregisterFilterOption: (fieldKey: string) => void;
     selectedFilters: Record<string, string[]>;
     setSelectedFilters: (filters: Record<string, string[]>) => void;
     clearFilters: () => void;
-    selectedCollections: SearchCollection[];
-    setSelectedCollections: (collections: SearchCollection[]) => void;
     formatResultsSummary: (template: string) => string;
 }
+declare const SearchContext: react.Context<UseSearchReturn | null>;
 declare const SearchProvider: FC<SearchProviderProps>;
 
 declare function useSearch(): UseSearchReturn;
@@ -65,4 +68,28 @@ interface UseSearchPaginationReturn {
 }
 declare function useSearchPagination(siblingCount?: number): UseSearchPaginationReturn;
 
-export { DOTS, SearchProvider, type SearchProviderProps, type UseSearchPaginationReturn, type UseSearchReturn, usePagination, useSearch, useSearchPagination };
+type UrlResolver = (hit: SearchHit) => string | undefined;
+/** Wrap your search tree to override URL building for all hits. */
+declare const SearchItemUrlResolverProvider: FC<{
+    resolver: UrlResolver;
+    children: ReactNode;
+}>;
+/** Used internally by SearchList to register the Canvas-config-driven default. */
+declare const SearchItemDefaultUrlResolverProvider: FC<{
+    resolver: UrlResolver;
+    children: ReactNode;
+}>;
+/**
+ * Always returns a resolver. User-provided resolver (SearchItemUrlResolverProvider)
+ * takes priority over the default registered by SearchList.
+ */
+declare function useUrlResolver(): UrlResolver;
+interface UrlResolverOptions {
+    /** nodeId → resolved locale-specific path (from project map). */
+    pathsByNodeId?: Record<string, string>;
+    /** Current locale, used as fallback for legacy :locale token in urlTemplate. */
+    locale?: string;
+}
+declare function createDefaultUrlResolver(configs: SearchItemConfig[], options?: UrlResolverOptions): UrlResolver;
+
+export { DOTS, SearchContext, SearchItemDefaultUrlResolverProvider, SearchItemUrlResolverProvider, SearchProvider, type SearchProviderProps, type UrlResolver, type UseSearchPaginationReturn, type UseSearchReturn, createDefaultUrlResolver, usePagination, useSearch, useSearchPagination, useUrlResolver };