@uniformdev/search 0.0.1 → 0.0.3

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,23 +30,67 @@ 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: {} };
+          console.error(`Search API error: ${response.status}`);
+          return emptyResult();
         }
         return response.json();
       } catch (error) {
-        console.error("[alex] Search fetch error:", error);
-        return { results: {} };
+        console.error("Search fetch error:", error);
+        return emptyResult();
       }
     }
   };
 }
+
+// src/highlights.ts
+var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isHighlightLeaf = (value) => isPlainObject(value) && ("snippet" in value || "snippets" in value || "value" in value || "values" in value);
+var unknownToString = (value) => {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value);
+  } catch (e) {
+    return "";
+  }
+};
+var getHighlightMatch = (hit, fieldPath, fieldValue) => {
+  const fieldHighlight = Array.isArray(hit._highlights) ? hit._highlights.find((highlight) => isPlainObject(highlight) && highlight.field === fieldPath) : void 0;
+  if (isPlainObject(fieldHighlight)) {
+    const snippets = fieldHighlight.snippets;
+    if (Array.isArray(snippets)) return { html: snippets.map(unknownToString).join(", ") };
+    const snippet = unknownToString(fieldHighlight.snippet);
+    if (snippet) return { html: snippet };
+    const value = unknownToString(fieldHighlight.value);
+    if (value) return { html: value };
+  }
+  const highlightValue = fieldPath.split(".").reduce((current, pathPart) => {
+    if (!isPlainObject(current)) return void 0;
+    return current[pathPart];
+  }, hit._highlight);
+  if (isHighlightLeaf(highlightValue)) {
+    if (Array.isArray(highlightValue.snippets)) {
+      return { html: highlightValue.snippets.map(unknownToString).join(", ") };
+    }
+    const snippet = unknownToString(highlightValue.snippet);
+    if (snippet) return { html: snippet };
+    if (Array.isArray(highlightValue.values)) return { values: highlightValue.values };
+    if ("value" in highlightValue) return { html: unknownToString(highlightValue.value) };
+  }
+  if (Array.isArray(fieldValue) && Array.isArray(highlightValue)) {
+    return { values: highlightValue };
+  }
+  return void 0;
+};
 export {
   DEFAULT_PAGE_SIZE,
   FIRST_PAGE,
@@ -52,6 +101,7 @@ export {
   buildOrderByQuery,
   createSearchClient,
   flattenBlockParams,
+  getHighlightMatch,
   getSearchParamsFromUrl
 };
 //# sourceMappingURL=index.mjs.map

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","../src/highlights.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  // ── Typo tolerance (all optional; omitted → the search engine's defaults apply) ──\n  /** Max typos tolerated per word: 0, 1, or 2. (Typesense `num_typos`.) */\n  maxTypos?: number;\n  /** Minimum word length before a single typo is allowed. (Typesense `min_len_1typo`.) */\n  minLengthFor1Typo?: number;\n  /** Minimum word length before two typos are allowed. (Typesense `min_len_2typo`.) */\n  minLengthFor2Typos?: number;\n  /** If a query returns fewer than this many results, retry with more typos. (Typesense `typo_tokens_threshold`.) */\n  typoFallbackThreshold?: number;\n  /** Rank exact matches above typo-corrected ones. (Typesense `prioritize_exact_match`.) */\n  prioritizeExactMatch?: boolean;\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(`Search API error: ${response.status}`);\n          return emptyResult();\n        }\n\n        return response.json();\n      } catch (error) {\n        console.error('Search fetch error:', error);\n        return emptyResult();\n      }\n    },\n  };\n}\n","import type { SearchHit, SearchResponseHighlightObject } from './types';\n\n// Helpers for rendering search highlights returned by `performSearch`. A hit carries\n// highlight data in `_highlight` (nested by field) and/or `_highlights` (array form);\n// `getHighlightMatch` resolves the highlight for a given field into a simple shape the\n// UI can render — `html` (a snippet with the matched terms wrapped in highlight tags,\n// for `dangerouslySetInnerHTML`) or `values` (per-item highlights for array fields).\n\nexport type HighlightMatch = {\n  html?: string;\n  values?: unknown[];\n};\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\nconst isHighlightLeaf = (value: unknown): value is SearchResponseHighlightObject =>\n  isPlainObject(value) &&\n  ('snippet' in value || 'snippets' in value || 'value' in value || 'values' in value);\n\nconst unknownToString = (value: unknown): string => {\n  if (value === null || value === undefined) return '';\n  if (typeof value === 'string') return value;\n  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {\n    return String(value);\n  }\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return '';\n  }\n};\n\n/**\n * Resolve the highlight (if any) for a field on a search hit.\n *\n * @param hit        A hit returned by `performSearch`.\n * @param fieldPath  The field name (dot-path for nested fields, e.g. `author.name`).\n * @param fieldValue The hit's raw value for the field (used to align array highlights).\n * @returns `{ html }` for a highlighted snippet, `{ values }` for per-item array\n *          highlights, or `undefined` when the field wasn't matched.\n */\nexport const getHighlightMatch = (\n  hit: SearchHit,\n  fieldPath: string,\n  fieldValue?: unknown\n): HighlightMatch | undefined => {\n  const fieldHighlight = Array.isArray(hit._highlights)\n    ? hit._highlights.find((highlight) => isPlainObject(highlight) && highlight.field === fieldPath)\n    : undefined;\n\n  if (isPlainObject(fieldHighlight)) {\n    const snippets = fieldHighlight.snippets;\n    if (Array.isArray(snippets)) return { html: snippets.map(unknownToString).join(', ') };\n    const snippet = unknownToString(fieldHighlight.snippet);\n    if (snippet) return { html: snippet };\n    const value = unknownToString(fieldHighlight.value);\n    if (value) return { html: value };\n  }\n\n  const highlightValue = fieldPath.split('.').reduce<unknown>((current, pathPart) => {\n    if (!isPlainObject(current)) return undefined;\n    return current[pathPart];\n  }, hit._highlight);\n\n  if (isHighlightLeaf(highlightValue)) {\n    if (Array.isArray(highlightValue.snippets)) {\n      return { html: highlightValue.snippets.map(unknownToString).join(', ') };\n    }\n    const snippet = unknownToString(highlightValue.snippet);\n    if (snippet) return { html: snippet };\n    if (Array.isArray(highlightValue.values)) return { values: highlightValue.values };\n    if ('value' in highlightValue) return { html: unknownToString(highlightValue.value) };\n  }\n\n  if (Array.isArray(fieldValue) && Array.isArray(highlightValue)) {\n    return { values: highlightValue };\n  }\n\n  return undefined;\n};\n"],"mappings":"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","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, S as SearchHit, a as Facets, P as PageSize, F as FacetBy, h as SearchParams, C as CollectionResult, g as SearchItemConfig } from './client-DOew5kqb.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;
@@ -26,20 +24,34 @@ interface UseSearchReturn {
     pageSize: number;
     setPageSize: (size: number) => void;
     pageSizes: PageSize[];
+    /** Register a component's page-size config (last registration wins). `id` should be
+     *  stable per instance. Used by pagination components that own their config. */
+    registerPageSizes: (id: string, pageSizes: unknown) => void;
+    unregisterPageSizes: (id: string) => void;
     orderByOptions: Array<{
         title: string;
         value: string;
     }>;
     selectedOrderBy: string;
     setOrderBy: (query: string) => void;
-    filterOptions: FilterBy[];
+    /** Register a sort component's order-by config (last registration wins). `id` should
+     *  be stable per component instance. Used by sort components that own their config
+     *  (App Router slots) instead of it being passed to the provider. */
+    registerOrderBy: (id: string, orderBy: unknown) => void;
+    unregisterOrderBy: (id: string) => void;
+    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 +77,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, S as SearchHit, a as Facets, P as PageSize, F as FacetBy, h as SearchParams, C as CollectionResult, g as SearchItemConfig } from './client-DOew5kqb.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;
@@ -26,20 +24,34 @@ interface UseSearchReturn {
     pageSize: number;
     setPageSize: (size: number) => void;
     pageSizes: PageSize[];
+    /** Register a component's page-size config (last registration wins). `id` should be
+     *  stable per instance. Used by pagination components that own their config. */
+    registerPageSizes: (id: string, pageSizes: unknown) => void;
+    unregisterPageSizes: (id: string) => void;
     orderByOptions: Array<{
         title: string;
         value: string;
     }>;
     selectedOrderBy: string;
     setOrderBy: (query: string) => void;
-    filterOptions: FilterBy[];
+    /** Register a sort component's order-by config (last registration wins). `id` should
+     *  be stable per component instance. Used by sort components that own their config
+     *  (App Router slots) instead of it being passed to the provider. */
+    registerOrderBy: (id: string, orderBy: unknown) => void;
+    unregisterOrderBy: (id: string) => void;
+    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 +77,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 };