@hanzo/docs-core 16.2.5

package/dist/search/algolia.d.ts

@@ -0,0 +1,69 @@
+import { Algoliasearch } from 'algoliasearch';
+import { StructuredData } from '../mdx-plugins/remark-structure.js';
+import 'mdast';
+import 'unified';
+import 'mdast-util-mdx-jsx';
+
+interface DocumentRecord {
+    /**
+     * The ID of document, must be unique
+     */
+    _id: string;
+    title: string;
+    description?: string;
+    breadcrumbs?: string[];
+    /**
+     * URL to the page
+     */
+    url: string;
+    structured: StructuredData;
+    /**
+     * Tag to filter results
+     */
+    tag?: string;
+    /**
+     * Data to be added to each section index
+     */
+    extra_data?: object;
+}
+interface SyncOptions {
+    /**
+     * Index Name for documents.
+     */
+    indexName?: string;
+    /**
+     * Search indexes
+     */
+    documents: DocumentRecord[];
+}
+/**
+ * Update index settings and replace all objects
+ *
+ * @param client - Algolia Admin Client
+ * @param options - Index Options
+ */
+declare function sync(client: Algoliasearch, options: SyncOptions): Promise<void>;
+declare function setIndexSettings(client: Algoliasearch, indexName: string): Promise<void>;
+declare function updateDocuments(client: Algoliasearch, indexName: string, documents: DocumentRecord[]): Promise<void>;
+interface BaseIndex {
+    objectID: string;
+    title: string;
+    url: string;
+    tag?: string;
+    /**
+     * The id of page, used for distinct
+     */
+    page_id: string;
+    /**
+     * Heading content
+     */
+    section?: string;
+    /**
+     * Heading (anchor) id
+     */
+    section_id?: string;
+    breadcrumbs?: string[];
+    content: string;
+}
+
+export { type BaseIndex, type DocumentRecord, type SyncOptions, setIndexSettings, sync, updateDocuments };

package/dist/search/algolia.js

@@ -0,0 +1,71 @@
+import "../chunk-U67V476Y.js";
+
+// src/search/algolia.ts
+async function sync(client, options) {
+  const { indexName = "document", documents } = options;
+  await setIndexSettings(client, indexName);
+  await updateDocuments(client, indexName, documents);
+}
+async function setIndexSettings(client, indexName) {
+  await client.setSettings({
+    indexName,
+    indexSettings: {
+      attributeForDistinct: "page_id",
+      attributesToRetrieve: [
+        "title",
+        "section",
+        "content",
+        "url",
+        "section_id",
+        "breadcrumbs"
+      ],
+      searchableAttributes: ["title", "section", "content"],
+      attributesToSnippet: [],
+      attributesForFaceting: ["tag"]
+    }
+  });
+}
+function toIndex(page) {
+  let id = 0;
+  const indexes = [];
+  const scannedHeadings = /* @__PURE__ */ new Set();
+  function createIndex(section, sectionId, content) {
+    return {
+      objectID: `${page._id}-${(id++).toString()}`,
+      breadcrumbs: page.breadcrumbs,
+      title: page.title,
+      url: page.url,
+      page_id: page._id,
+      tag: page.tag,
+      section,
+      section_id: sectionId,
+      content,
+      ...page.extra_data
+    };
+  }
+  if (page.description)
+    indexes.push(createIndex(void 0, void 0, page.description));
+  const { headings, contents } = page.structured;
+  for (const p of contents) {
+    const heading = p.heading ? headings.find((h) => p.heading === h.id) : null;
+    const index = createIndex(heading?.content, heading?.id, p.content);
+    if (heading && !scannedHeadings.has(heading.id)) {
+      scannedHeadings.add(heading.id);
+      indexes.push(createIndex(heading.content, heading.id, heading.content));
+    }
+    indexes.push(index);
+  }
+  return indexes;
+}
+async function updateDocuments(client, indexName, documents) {
+  const objects = documents.flatMap(toIndex);
+  await client.replaceAllObjects({
+    indexName,
+    objects
+  });
+}
+export {
+  setIndexSettings,
+  sync,
+  updateDocuments
+};

package/dist/search/client.d.ts

@@ -0,0 +1,140 @@
+import { DependencyList } from 'react';
+import { AnyOrama } from '@orama/orama';
+import '../mdx-plugins/remark-structure.js';
+import { BaseIndex } from './algolia.js';
+import { LiteClient, SearchResponse } from 'algoliasearch/lite';
+import { OramaCloud, OramaCloudSearchParams } from '@orama/core';
+import Mixedbread from '@mixedbread/sdk';
+import { SortedResult } from './index.js';
+import 'mdast';
+import 'unified';
+import 'mdast-util-mdx-jsx';
+import 'algoliasearch';
+
+interface FetchOptions {
+    /**
+     * API route for search endpoint, support absolute URLs.
+     *
+     * @defaultValue '/api/search'
+     */
+    api?: string;
+    /**
+     * Filter results with specific tag(s).
+     */
+    tag?: string | string[];
+    /**
+     * Filter by locale
+     */
+    locale?: string;
+}
+
+interface StaticOptions {
+    /**
+     * Where to download exported search indexes (URL)
+     *
+     * @defaultValue '/api/search'
+     */
+    from?: string;
+    initOrama?: (locale?: string) => AnyOrama | Promise<AnyOrama>;
+    /**
+     * Filter results with specific tag(s).
+     */
+    tag?: string | string[];
+    /**
+     * Filter by locale (unsupported at the moment)
+     */
+    locale?: string;
+}
+
+interface AlgoliaOptions {
+    indexName: string;
+    client: LiteClient;
+    /**
+     * Filter results with specific tag.
+     */
+    tag?: string;
+    locale?: string;
+    onSearch?: (query: string, tag?: string, locale?: string) => Promise<{
+        results: SearchResponse<BaseIndex>[];
+    }>;
+}
+
+interface OramaCloudOptions {
+    client: OramaCloud;
+    /**
+     * The type of your index.
+     *
+     * You can set it to `crawler` if you use crawler instead of the JSON index with schema provided by Fumadocs
+     */
+    index?: 'default' | 'crawler';
+    params?: Partial<OramaCloudSearchParams>;
+    /**
+     * Filter results with specific tag.
+     */
+    tag?: string;
+    /**
+     * Filter by locale (unsupported at the moment)
+     */
+    locale?: string;
+}
+
+interface MixedbreadOptions {
+    /**
+     * The ID of the vector store to search in
+     */
+    vectorStoreId: string;
+    /**
+     * The Mixedbread SDK client instance
+     */
+    client: Mixedbread;
+    /**
+     * Filter results with specific tag.
+     */
+    tag?: string;
+    /**
+     * Filter by locale (unsupported at the moment)
+     */
+    locale?: string;
+}
+
+interface UseDocsSearch {
+    search: string;
+    setSearch: (v: string) => void;
+    query: {
+        isLoading: boolean;
+        data?: SortedResult[] | 'empty';
+        error?: Error;
+    };
+}
+type Client = ({
+    type: 'fetch';
+} & FetchOptions) | ({
+    type: 'static';
+} & StaticOptions) | ({
+    type: 'algolia';
+} & AlgoliaOptions) | ({
+    type: 'orama-cloud';
+} & OramaCloudOptions) | ({
+    type: 'mixedbread';
+} & MixedbreadOptions);
+/**
+ * Provide a hook to query different official search clients.
+ *
+ * Note: it will re-query when its parameters changed, make sure to use `useMemo()` on `clientOptions` or define `deps` array.
+ */
+declare function useDocsSearch(clientOptions: Client & {
+    /**
+     * The debounced delay for performing a search (in ms).
+     * .
+     * @defaultValue 100
+     */
+    delayMs?: number;
+    /**
+     * still perform search even if query is empty.
+     *
+     * @defaultValue false
+     */
+    allowEmpty?: boolean;
+}, deps?: DependencyList): UseDocsSearch;
+
+export { type AlgoliaOptions, type Client, type FetchOptions, type OramaCloudOptions, type StaticOptions, useDocsSearch };

package/dist/search/client.js

@@ -0,0 +1,99 @@
+import {
+  useOnChange
+} from "../chunk-EMWGTXSW.js";
+import "../chunk-U67V476Y.js";
+
+// src/search/client.ts
+import { useRef, useState as useState2 } from "react";
+
+// src/utils/use-debounce.ts
+import { useEffect, useState } from "react";
+function useDebounce(value, delayMs = 1e3) {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+  useEffect(() => {
+    if (delayMs === 0) return;
+    const handler = window.setTimeout(() => {
+      setDebouncedValue(value);
+    }, delayMs);
+    return () => clearTimeout(handler);
+  }, [delayMs, value]);
+  if (delayMs === 0) return value;
+  return debouncedValue;
+}
+
+// src/search/client.ts
+function isDeepEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return b.length === a.length && a.every((v, i) => isDeepEqual(v, b[i]));
+  }
+  if (typeof a === "object" && a && typeof b === "object" && b) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    return aKeys.length === bKeys.length && aKeys.every(
+      (key) => Object.hasOwn(b, key) && isDeepEqual(a[key], b[key])
+    );
+  }
+  return false;
+}
+function useDocsSearch(clientOptions, deps) {
+  const { delayMs = 100, allowEmpty = false, ...client } = clientOptions;
+  const [search, setSearch] = useState2("");
+  const [results, setResults] = useState2("empty");
+  const [error, setError] = useState2();
+  const [isLoading, setIsLoading] = useState2(false);
+  const debouncedValue = useDebounce(search, delayMs);
+  const onStart = useRef(void 0);
+  useOnChange(
+    [deps ?? clientOptions, debouncedValue],
+    () => {
+      if (onStart.current) {
+        onStart.current();
+        onStart.current = void 0;
+      }
+      setIsLoading(true);
+      let interrupt = false;
+      onStart.current = () => {
+        interrupt = true;
+      };
+      async function run() {
+        if (debouncedValue.length === 0 && !allowEmpty) return "empty";
+        if (client.type === "fetch") {
+          const { fetchDocs } = await import("../fetch-IBTWQCJR.js");
+          return fetchDocs(debouncedValue, client);
+        }
+        if (client.type === "algolia") {
+          const { searchDocs } = await import("../algolia-IZEDLPHE.js");
+          return searchDocs(debouncedValue, client);
+        }
+        if (client.type === "orama-cloud") {
+          const { searchDocs } = await import("../orama-cloud-UZAPMPFV.js");
+          return searchDocs(debouncedValue, client);
+        }
+        if (client.type === "static") {
+          const { search: search2 } = await import("../static-A2YJ5TXV.js");
+          return search2(debouncedValue, client);
+        }
+        if (client.type === "mixedbread") {
+          const { search: search2 } = await import("../mixedbread-RAHDVXGJ.js");
+          return search2(debouncedValue, client);
+        }
+        throw new Error("unknown search client");
+      }
+      void run().then((res) => {
+        if (interrupt) return;
+        setError(void 0);
+        setResults(res);
+      }).catch((err) => {
+        setError(err);
+      }).finally(() => {
+        setIsLoading(false);
+      });
+    },
+    deps ? void 0 : (a, b) => !isDeepEqual(a, b)
+  );
+  return { search, setSearch, query: { isLoading, data: results, error } };
+}
+export {
+  useDocsSearch
+};

package/dist/search/index.d.ts

@@ -0,0 +1,26 @@
+import { ReactNode } from 'react';
+
+interface SortedResult<Content = string> {
+    id: string;
+    url: string;
+    type: 'page' | 'heading' | 'text';
+    content: Content;
+    /**
+     * breadcrumbs to be displayed on UI
+     */
+    breadcrumbs?: Content[];
+    contentWithHighlights?: HighlightedText<Content>[];
+}
+type ReactSortedResult = SortedResult<ReactNode>;
+interface HighlightedText<Content = string> {
+    type: 'text';
+    content: Content;
+    styles?: {
+        highlight?: boolean;
+    };
+}
+declare function createContentHighlighter(query: string | RegExp): {
+    highlight(content: string): HighlightedText[];
+};
+
+export { type HighlightedText, type ReactSortedResult, type SortedResult, createContentHighlighter };

package/dist/search/index.js

@@ -0,0 +1,7 @@
+import {
+  createContentHighlighter
+} from "../chunk-OTD7MV33.js";
+import "../chunk-U67V476Y.js";
+export {
+  createContentHighlighter
+};

package/dist/search/orama-cloud.d.ts

@@ -0,0 +1,79 @@
+import { StructuredData } from '../mdx-plugins/remark-structure.js';
+import '../mdx-plugins/remark-heading.js';
+import '../mdx-plugins/remark-code-tab.js';
+import { OramaCloud } from '@orama/core';
+import 'mdast';
+import 'unified';
+import 'mdast-util-mdx-jsx';
+
+interface SyncOptions {
+    /**
+     * Index name to sync
+     */
+    index: string;
+    documents: OramaDocument[];
+    /**
+     * Deploy changes
+     *
+     * @defaultValue true
+     */
+    autoDeploy?: boolean;
+}
+type I18nSyncOptions = Omit<SyncOptions, 'index' | 'documents'> & {
+    /**
+     * Indexes to sync.
+     *
+     * Pairs of `locale`-`index`.
+     **/
+    indexes: Record<string, string>;
+    documents: {
+        locale: string;
+        items: OramaDocument[];
+    }[];
+};
+interface OramaDocument {
+    /**
+     * The ID of document, must be unique
+     */
+    id: string;
+    title: string;
+    description?: string;
+    /**
+     * URL to the page
+     */
+    url: string;
+    structured: StructuredData;
+    /**
+     * Tag to filter results
+     */
+    tag?: string;
+    /**
+     * Data to be added to each section index
+     */
+    extra_data?: object;
+    breadcrumbs?: string[];
+}
+interface OramaIndex {
+    id: string;
+    title: string;
+    url: string;
+    tag?: string;
+    /**
+     * The id of page, used for `group by`
+     */
+    page_id: string;
+    /**
+     * Heading content
+     */
+    section?: string;
+    breadcrumbs?: string[];
+    /**
+     * Heading (anchor) id
+     */
+    section_id?: string;
+    content: string;
+}
+declare function sync(orama: OramaCloud, options: SyncOptions): Promise<void>;
+declare function syncI18n(orama: OramaCloud, options: I18nSyncOptions): Promise<void>;
+
+export { type I18nSyncOptions, type OramaDocument, type OramaIndex, type SyncOptions, sync, syncI18n };

package/dist/search/orama-cloud.js

@@ -0,0 +1,60 @@
+import "../chunk-U67V476Y.js";
+
+// src/search/orama-cloud.ts
+async function sync(orama, options) {
+  const { autoDeploy = true } = options;
+  const index = orama.index.set(options.index);
+  await index.transaction.open();
+  await index.transaction.insertDocuments(
+    options.documents.flatMap(toIndex)
+  );
+  if (autoDeploy) await index.transaction.commit();
+}
+async function syncI18n(orama, options) {
+  const { autoDeploy = true, indexes } = options;
+  const tasks = options.documents.map(async (document) => {
+    const index = orama.index.set(indexes[document.locale]);
+    await index.transaction.open();
+    await index.transaction.insertDocuments(
+      document.items.flatMap(toIndex)
+    );
+    if (autoDeploy) await index.transaction.commit();
+  });
+  await Promise.all(tasks);
+}
+function toIndex(page) {
+  let id = 0;
+  const indexes = [];
+  const scannedHeadings = /* @__PURE__ */ new Set();
+  function createIndex(section, sectionId, content) {
+    return {
+      id: `${page.id}-${(id++).toString()}`,
+      title: page.title,
+      url: page.url,
+      // TODO: explicit declare enums
+      page_id: page.id,
+      tag: page.tag,
+      section,
+      section_id: sectionId,
+      content,
+      breadcrumbs: page.breadcrumbs,
+      ...page.extra_data
+    };
+  }
+  if (page.description)
+    indexes.push(createIndex(void 0, void 0, page.description));
+  page.structured.contents.forEach((p) => {
+    const heading = p.heading ? page.structured.headings.find((h) => p.heading === h.id) : null;
+    const index = createIndex(heading?.content, heading?.id, p.content);
+    if (heading && !scannedHeadings.has(heading.id)) {
+      scannedHeadings.add(heading.id);
+      indexes.push(createIndex(heading.content, heading.id, heading.content));
+    }
+    indexes.push(index);
+  });
+  return indexes;
+}
+export {
+  sync,
+  syncI18n
+};

package/dist/search/server.d.ts

@@ -0,0 +1,136 @@
+import { TypedDocument, Orama, Language, RawData, create, SearchParams } from '@orama/orama';
+import { StructuredData } from '../mdx-plugins/remark-structure.js';
+import { SortedResult } from './index.js';
+export { HighlightedText, ReactSortedResult, createContentHighlighter } from './index.js';
+import { I18nConfig } from '../i18n/index.js';
+import { f as LoaderOutput, b as LoaderConfig, I as InferPageType } from '../loader-BvlPPJX0.js';
+import 'mdast';
+import 'unified';
+import 'mdast-util-mdx-jsx';
+import 'react';
+import '../definitions-pJ7PybYY.js';
+
+type SimpleDocument = TypedDocument<Orama<typeof simpleSchema>>;
+declare const simpleSchema: {
+    readonly url: "string";
+    readonly title: "string";
+    readonly breadcrumbs: "string[]";
+    readonly description: "string";
+    readonly content: "string";
+    readonly keywords: "string";
+};
+type AdvancedDocument = TypedDocument<Orama<typeof advancedSchema>>;
+declare const advancedSchema: {
+    readonly content: "string";
+    readonly page_id: "string";
+    readonly type: "string";
+    readonly breadcrumbs: "string[]";
+    readonly tags: "enum[]";
+    readonly url: "string";
+    readonly embeddings: "vector[512]";
+};
+
+type Awaitable<T> = T | Promise<T>;
+interface Options<S extends LoaderOutput<LoaderConfig>> extends Omit<AdvancedOptions, 'indexes'> {
+    localeMap?: {
+        [K in S extends LoaderOutput<infer C> ? C['i18n'] extends I18nConfig<infer Languages> ? Languages : string : string]?: Partial<AdvancedOptions> | Language;
+    };
+    buildIndex?: (page: InferPageType<S>) => Awaitable<AdvancedIndex>;
+}
+declare function createFromSource<S extends LoaderOutput<LoaderConfig>>(source: S, options?: Options<S>): SearchAPI;
+
+type I18nOptions<O extends SimpleOptions | AdvancedOptions, Idx> = Omit<O, 'language' | 'indexes'> & {
+    i18n: I18nConfig;
+    /**
+     * Map locale name from i18n config to Orama compatible `language` or options
+     */
+    localeMap?: Record<string, Language | Partial<O> | undefined>;
+    indexes: WithLocale<Idx>[] | Dynamic<WithLocale<Idx>>;
+};
+type I18nSimpleOptions = I18nOptions<SimpleOptions, Index>;
+type I18nAdvancedOptions = I18nOptions<AdvancedOptions, AdvancedIndex>;
+type WithLocale<T> = T & {
+    locale: string;
+};
+declare function createI18nSearchAPI<T extends 'simple' | 'advanced'>(type: T, options: T extends 'simple' ? I18nSimpleOptions : I18nAdvancedOptions): SearchAPI;
+
+type SearchType = 'simple' | 'advanced';
+type ExportedData = (RawData & {
+    type: SearchType;
+}) | {
+    type: 'i18n';
+    data: Record<string, RawData & {
+        type: SearchType;
+    }>;
+};
+interface SearchServer {
+    search: (query: string, options?: {
+        locale?: string;
+        tag?: string | string[];
+        mode?: 'vector' | 'full';
+    }) => Promise<SortedResult[]>;
+    /**
+     * Export the database
+     *
+     * You can reference the exported database to implement client-side search
+     */
+    export: () => Promise<ExportedData>;
+}
+interface SearchAPI extends SearchServer {
+    GET: (request: Request) => Promise<Response>;
+    /**
+     * `GET` route handler that exports search indexes for static search.
+     */
+    staticGET: () => Promise<Response>;
+}
+/**
+ * Resolve indexes dynamically
+ */
+type Dynamic<T> = () => T[] | Promise<T[]>;
+type OramaInput = Parameters<typeof create>[0];
+type SharedOptions = Pick<OramaInput, 'sort' | 'components' | 'plugins'> & {
+    language?: string;
+    tokenizer?: Required<OramaInput>['components']['tokenizer'];
+};
+interface SimpleOptions extends SharedOptions {
+    indexes: Index[] | Dynamic<Index>;
+    /**
+     * Customise search options on server
+     */
+    search?: Partial<SearchParams<Orama<typeof simpleSchema>, SimpleDocument>>;
+}
+interface AdvancedOptions extends SharedOptions {
+    indexes: AdvancedIndex[] | Dynamic<AdvancedIndex>;
+    /**
+     * Customise search options on server
+     */
+    search?: Partial<SearchParams<Orama<typeof advancedSchema>, AdvancedDocument>>;
+}
+declare function createSearchAPI<T extends SearchType>(type: T, options: T extends 'simple' ? SimpleOptions : AdvancedOptions): SearchAPI;
+interface Index {
+    title: string;
+    description?: string;
+    breadcrumbs?: string[];
+    content: string;
+    url: string;
+    keywords?: string;
+}
+declare function initSimpleSearch(options: SimpleOptions): SearchServer;
+interface AdvancedIndex {
+    id: string;
+    title: string;
+    description?: string;
+    breadcrumbs?: string[];
+    /**
+     * Required if tag filter is enabled
+     */
+    tag?: string | string[];
+    /**
+     * preprocess mdx content with `structure`
+     */
+    structuredData: StructuredData;
+    url: string;
+}
+declare function initAdvancedSearch(options: AdvancedOptions): SearchServer;
+
+export { type AdvancedIndex, type AdvancedOptions, type Dynamic, type ExportedData, type Index, type SearchAPI, type SearchServer, type SimpleOptions, SortedResult, createFromSource, createI18nSearchAPI, createSearchAPI, initAdvancedSearch, initSimpleSearch };