feat(docusaurus-adapter): support docsearch key and adapter docs

adapters/docusaurus-theme-search-algolia/.gitignore

@@ -0,0 +1,3 @@
+lib
+libtmp
+*.tsbuildinfo

adapters/docusaurus-theme-search-algolia/.npmignore

@@ -0,0 +1,3 @@
+.tsbuildinfo*
+tsconfig*
+__tests__

adapters/docusaurus-theme-search-algolia/README.md

@@ -0,0 +1,27 @@
+# `@docsearch/docusaurus-adapter`
+
+Algolia search component for Docusaurus.
+
+## Usage
+
+Prefer configuring the adapter with `themeConfig.docsearch`:
+
+```js
+// docusaurus.config.js
+export default {
+  // ...
+  themeConfig: {
+    docsearch: {
+      appId: 'APP_ID',
+      apiKey: 'SEARCH_API_KEY',
+      indexName: 'INDEX_NAME',
+      askAi: {
+        assistantId: 'ASSISTANT_ID',
+        sidePanel: true,
+      },
+    },
+  },
+};
+```
+
+`themeConfig.algolia` is still supported as a backward-compatible alias.

adapters/docusaurus-theme-search-algolia/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@docsearch/docusaurus-adapter",
+  "version": "4.5.4",
+  "description": "Algolia search component for Docusaurus.",
+  "main": "lib/index.js",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    "./client": {
+      "types": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    ".": {
+      "types": "./src/theme-search-algolia.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "types": "src/theme-search-algolia.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/algolia/docsearch.git",
+    "directory": "adapters/docusaurus-theme-search-algolia"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "yarn exec tsc --build --force && node ./scripts/copy-assets.mjs && node ./scripts/format-theme.mjs",
+    "build:clean": "yarn clean && yarn build",
+    "clean": "rm -rf lib tsconfig.*.tsbuildinfo",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "yarn exec tsc --build --watch",
+    "copy:watch": "node ./scripts/copy-assets.mjs --watch"
+  },
+  "dependencies": {
+    "@docsearch/react": "^4.5.3",
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/plugin-content-docs": "^3.9.2",
+    "@docusaurus/theme-common": "^3.9.2",
+    "@docusaurus/theme-translations": "^3.9.2",
+    "algoliasearch": "^5.37.0",
+    "algoliasearch-helper": "^3.26.0",
+    "clsx": "^2.0.0",
+    "eta": "^2.2.0",
+    "fs-extra": "^11.1.1",
+    "joi": "^17.9.2",
+    "lodash": "^4.17.21",
+    "tslib": "^2.6.0",
+    "utility-types": "^3.10.0"
+  },
+  "devDependencies": {
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/theme-classic": "3.9.2",
+    "@types/fs-extra": "^11.0.4",
+    "@types/lodash": "^4.17.10",
+    "typescript": "5.7.3"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=20.0"
+  }
+}

adapters/docusaurus-theme-search-algolia/scripts/copy-assets.mjs

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import fse from 'fs-extra';
+
+const WATCH_FLAG = '--watch';
+const ASSET_EXTENSIONS = new Set(['.css']);
+const IGNORED_EXTENSIONS = new Set(['.ts', '.tsx', '.d.ts']);
+
+const cwd = process.cwd();
+const srcRoot = path.join(cwd, 'src', 'theme');
+const destRoot = path.join(cwd, 'lib', 'theme');
+
+async function copyAssetFile(filePath) {
+  const relativePath = path.relative(srcRoot, filePath);
+  const destPath = path.join(destRoot, relativePath);
+
+  await fse.ensureDir(path.dirname(destPath));
+  await fse.copyFile(filePath, destPath);
+}
+
+async function copyAssetsOnce() {
+  if (!(await fse.pathExists(srcRoot))) {
+    return;
+  }
+
+  const entries = await fse.readdir(srcRoot, { recursive: true });
+  const filePaths = entries
+    .filter((entry) => typeof entry === 'string')
+    .map((entry) => path.join(srcRoot, entry))
+    .filter((entryPath) => fs.statSync(entryPath).isFile());
+
+  await Promise.all(
+    filePaths
+      .filter((filePath) => {
+        const extension = path.extname(filePath);
+        if (IGNORED_EXTENSIONS.has(extension)) {
+          return false;
+        }
+        return ASSET_EXTENSIONS.has(extension);
+      })
+      .map((filePath) => copyAssetFile(filePath)),
+  );
+}
+
+function watchAssets() {
+  if (!fs.existsSync(srcRoot)) {
+    return;
+  }
+
+  copyAssetsOnce();
+
+  fs.watch(
+    srcRoot,
+    { recursive: true },
+    (_eventType, filename) => {
+      if (!filename) {
+        return;
+      }
+      const filePath = path.join(srcRoot, filename);
+      const extension = path.extname(filePath);
+      if (IGNORED_EXTENSIONS.has(extension) || !ASSET_EXTENSIONS.has(extension)) {
+        return;
+      }
+      if (!fs.existsSync(filePath)) {
+        return;
+      }
+      copyAssetFile(filePath);
+    },
+  );
+}
+
+if (process.argv.includes(WATCH_FLAG)) {
+  watchAssets();
+} else {
+  copyAssetsOnce();
+}

adapters/docusaurus-theme-search-algolia/scripts/format-theme.mjs

@@ -0,0 +1,17 @@
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { glob } from 'glob';
+
+const pattern = 'lib/theme/**/*.js';
+const files = glob.sync(pattern);
+
+if (files.length > 0) {
+  try {
+    execSync(`prettier --config ../../.prettierrc --write "${pattern}"`, {
+      stdio: 'inherit',
+    });
+  } catch (error) {
+    console.error('Prettier failed:', error.message);
+    process.exit(1);
+  }
+}

adapters/docusaurus-theme-search-algolia/src/__tests__/utils.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {mergeFacetFilters} from '../client/utils';
+
+describe('mergeFacetFilters', () => {
+  it('merges [string,string]', () => {
+    expect(mergeFacetFilters('f1', 'f2')).toEqual(['f1', 'f2']);
+  });
+
+  it('merges [string,array]', () => {
+    // TODO this looks wrong to me, should be ['f1', ['f2', 'f3']] ?
+    expect(mergeFacetFilters('f1', ['f2', 'f3'])).toEqual(['f1', 'f2', 'f3']);
+  });
+
+  it('merges [string,undefined]', () => {
+    expect(mergeFacetFilters('f1', undefined)).toEqual('f1');
+  });
+
+  it('merges [undefined,string]', () => {
+    expect(mergeFacetFilters(undefined, 'f1')).toEqual('f1');
+  });
+
+  it('merges [array,undefined]', () => {
+    expect(mergeFacetFilters(['f1', 'f2'], undefined)).toEqual(['f1', 'f2']);
+  });
+
+  it('merges [undefined,array]', () => {
+    expect(mergeFacetFilters(undefined, ['f1', 'f2'])).toEqual(['f1', 'f2']);
+  });
+
+  it('merges [array,array]', () => {
+    expect(mergeFacetFilters(['f1'], ['f2'])).toEqual(['f1', 'f2']);
+
+    // TODO this looks wrong to me, should be [['f1', 'f2'], ['f3', 'f4']] ?
+    expect(mergeFacetFilters(['f1', 'f2'], ['f3', 'f4'])).toEqual([
+      'f1',
+      'f2',
+      'f3',
+      'f4',
+    ]);
+  });
+});