@kawapress/plugin-algolia-search 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) KawaPress contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,70 @@
1
+ # @kawapress/plugin-algolia-search
2
+
3
+ 为 KawaPress 站点接入 Algolia DocSearch 搜索。
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@kawapress/plugin-algolia-search?label=npm&color=42b883)](https://www.npmjs.com/package/@kawapress/plugin-algolia-search) · [English](https://github.com/kawapress/kawapress/blob/main/packages/plugin-algolia-search/README.md)
6
+
7
+ `@kawapress/plugin-algolia-search` 是 [KawaPress](https://github.com/kawapress/kawapress) 的一部分。KawaPress 是一个以 Vue 为核心的静态站点生成器。
8
+
9
+ ## 特性
10
+
11
+ - 把轻量搜索按钮放进 `layout.header.end` 插座,并提前连接 Algolia。
12
+ - 只在读者点击按钮或按下 `Ctrl/⌘ + K`、`/` 时才加载 `@docsearch/js` 和样式。
13
+ - 自动按当前语言的 `lang:<lang>` 过滤每个索引的结果。
14
+ - 将搜索结果的链接转为站点路由,通过 KawaPress 站内路由无刷新跳转。
15
+ - 把 `--docsearch-*` 变量映射到公共 `--kawa-*` Token,自动适配浅色与深色外观。
16
+
17
+ ## 安装
18
+
19
+ ```sh
20
+ npm install --save-dev @kawapress/plugin-algolia-search
21
+ ```
22
+
23
+ 也可以用 `pnpm add --save-dev @kawapress/plugin-algolia-search` 或 `yarn add --dev @kawapress/plugin-algolia-search`。
24
+
25
+ ## 使用
26
+
27
+ 在 `nagi()` 中写 `search: false` 关掉内置本地搜索,再把 `algoliaSearchPlugin()` 加进 `plugins`:
28
+
29
+ ```ts
30
+ import algoliaSearchPlugin from '@kawapress/plugin-algolia-search'
31
+ import { nagi } from 'kawapress/nagi'
32
+
33
+ export default nagi({
34
+ search: false,
35
+ plugins: [
36
+ algoliaSearchPlugin({
37
+ appId: 'YOUR_APP_ID',
38
+ apiKey: 'YOUR_SEARCH_API_KEY',
39
+ indexName: 'your_index_name',
40
+ }),
41
+ ],
42
+ })
43
+ ```
44
+
45
+ ## 配置项
46
+
47
+ | 选项 | 说明 |
48
+ | --- | --- |
49
+ | `appId` | Algolia 应用 ID,必填。 |
50
+ | `apiKey` | Algolia 只读搜索 API Key,必填。 |
51
+ | `indexName` | 要搜索的索引名(`indices: [indexName]` 的简写)。 |
52
+ | `indices` | 索引列表,每项为索引名或 `{ name, searchParameters }`。 |
53
+ | `searchParameters` | 应用到所有索引的附加 Algolia 查询参数。 |
54
+ | `placeholder` | 搜索框占位文字。 |
55
+ | `translations` | 按钮和弹窗文字,格式与 `@docsearch/js` 相同。 |
56
+ | `maxResultsPerGroup` | 每个分组最多显示的结果条数。 |
57
+ | `disableUserPersonalization` | 关闭浏览器保存的最近搜索与收藏记录。 |
58
+ | `insights` | 向 Algolia Insights 发送点击与转化事件。 |
59
+ | `facets` | 显示在搜索结果上方的 `{ key, label? }[]` 筛选标签。 |
60
+ | `resultBadgeKey` | 在每条结果旁作为徽标显示的字段名。 |
61
+ | `keyboardShortcuts` | 开启或关闭 `'Ctrl/Cmd+K'` 与 `'/'` 快捷键,默认都开启。 |
62
+ | `locales` | 按 KawaPress 语言键覆盖各语言的搜索选项。 |
63
+
64
+ ## 文档
65
+
66
+ [文档](https://kawapress.dev/plugins/algolia-search) · [反馈问题](https://github.com/kawapress/kawapress/issues)
67
+
68
+ ## 许可证
69
+
70
+ [MIT](https://github.com/kawapress/kawapress/blob/main/LICENSE) © KawaPress contributors
package/README.md CHANGED
@@ -1,3 +1,70 @@
1
- # Temporary Holding Version
1
+ # @kawapress/plugin-algolia-search
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Algolia DocSearch for KawaPress sites.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@kawapress/plugin-algolia-search?label=npm&color=42b883)](https://www.npmjs.com/package/@kawapress/plugin-algolia-search) · [简体中文](https://github.com/kawapress/kawapress/blob/main/packages/plugin-algolia-search/README-zh-CN.md)
6
+
7
+ `@kawapress/plugin-algolia-search` is part of [KawaPress](https://github.com/kawapress/kawapress), a Vue-first static site generator.
8
+
9
+ ## Features
10
+
11
+ - Places a lightweight search button in the `layout.header.end` outlet and preconnects to Algolia.
12
+ - Loads `@docsearch/js` and its CSS only when a reader clicks the button or presses `Ctrl/⌘ + K` or `/`.
13
+ - Automatically filters every index by `lang:<lang>` for the current locale.
14
+ - Normalizes hit URLs to site routes and navigates through the KawaPress router.
15
+ - Maps `--docsearch-*` variables to the shared `--kawa-*` tokens so light and dark themes match out of the box.
16
+
17
+ ## Install
18
+
19
+ ```sh
20
+ npm install --save-dev @kawapress/plugin-algolia-search
21
+ ```
22
+
23
+ `pnpm add --save-dev @kawapress/plugin-algolia-search` and `yarn add --dev @kawapress/plugin-algolia-search` work too.
24
+
25
+ ## Usage
26
+
27
+ Set `search: false` on `nagi()` to disable the built-in local search, then add `algoliaSearchPlugin()` to `plugins`:
28
+
29
+ ```ts
30
+ import algoliaSearchPlugin from '@kawapress/plugin-algolia-search'
31
+ import { nagi } from 'kawapress/nagi'
32
+
33
+ export default nagi({
34
+ search: false,
35
+ plugins: [
36
+ algoliaSearchPlugin({
37
+ appId: 'YOUR_APP_ID',
38
+ apiKey: 'YOUR_SEARCH_API_KEY',
39
+ indexName: 'your_index_name',
40
+ }),
41
+ ],
42
+ })
43
+ ```
44
+
45
+ ## Options
46
+
47
+ | Option | Description |
48
+ | --- | --- |
49
+ | `appId` | Application ID from the Algolia dashboard. Required. |
50
+ | `apiKey` | Search-only API key from the Algolia dashboard. Required. |
51
+ | `indexName` | Index name to search (shorthand for `indices: [indexName]`). |
52
+ | `indices` | List of index names or `{ name, searchParameters }` objects. |
53
+ | `searchParameters` | Extra Algolia search parameters applied to every index. |
54
+ | `placeholder` | Search input placeholder text. |
55
+ | `translations` | Button and modal texts in the `@docsearch/js` shape. |
56
+ | `maxResultsPerGroup` | Maximum hits shown per group. |
57
+ | `disableUserPersonalization` | Disable recent and favorite searches stored in the browser. |
58
+ | `insights` | Send click and conversion events to Algolia Insights. |
59
+ | `facets` | Facet filters `{ key, label? }[]` shown above the results. |
60
+ | `resultBadgeKey` | Hit attribute shown as a badge next to each result. |
61
+ | `keyboardShortcuts` | Turn `'Ctrl/Cmd+K'` and `'/'` shortcuts on or off. Both default to `true`. |
62
+ | `locales` | Per-locale overrides keyed by KawaPress locale key. |
63
+
64
+ ## Documentation
65
+
66
+ [Documentation](https://kawapress.dev/en/plugins/algolia-search) · [Report a problem](https://github.com/kawapress/kawapress/issues)
67
+
68
+ ## License
69
+
70
+ [MIT](https://github.com/kawapress/kawapress/blob/main/LICENSE) © KawaPress contributors
package/package.json CHANGED
@@ -1,6 +1,55 @@
1
1
  {
2
2
  "name": "@kawapress/plugin-algolia-search",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "type": "module",
4
+ "version": "0.0.1",
5
+ "description": "Algolia DocSearch for KawaPress sites",
6
+ "license": "MIT",
7
+ "homepage": "https://kawapress.dev/",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/kawapress/kawapress.git",
11
+ "directory": "packages/plugin-algolia-search"
12
+ },
13
+ "bugs": {
14
+ "url": "https://github.com/kawapress/kawapress/issues"
15
+ },
16
+ "exports": {
17
+ ".": {
18
+ "types": "./src/index.ts",
19
+ "import": "./src/index.ts",
20
+ "default": "./src/index.ts"
21
+ },
22
+ "./runtime-plugin": {
23
+ "types": "./src/runtime-plugin.ts",
24
+ "import": "./src/runtime-plugin.ts",
25
+ "default": "./src/runtime-plugin.ts"
26
+ },
27
+ "./package.json": "./package.json"
28
+ },
29
+ "files": [
30
+ "README-zh-CN.md",
31
+ "src/**/!(*.test.*)"
32
+ ],
33
+ "engines": {
34
+ "node": ">=22.12.0"
35
+ },
36
+ "publishConfig": {
37
+ "access": "public",
38
+ "registry": "https://registry.npmjs.org/"
39
+ },
40
+ "peerDependencies": {
41
+ "vue": "^3.5.41",
42
+ "kawapress": "^0.0.1"
43
+ },
44
+ "dependencies": {
45
+ "@docsearch/css": "^5.2.0",
46
+ "@docsearch/js": "^5.2.0",
47
+ "@unhead/vue": "^3.3.2"
48
+ },
49
+ "devDependencies": {
50
+ "happy-dom": "^20.11.6",
51
+ "vite": "^8.2.2",
52
+ "vue": "^3.5.41",
53
+ "kawapress": "0.0.1"
54
+ }
6
55
  }
@@ -0,0 +1,143 @@
1
+ @layer kawa.plugin {
2
+ /*
3
+ * DocSearch reads its colors from --docsearch-* variables that it declares on
4
+ * :root. Declaring them on its own elements wins regardless of load order,
5
+ * and the shared tokens already follow the light and dark appearance.
6
+ */
7
+ .DocSearch {
8
+ --docsearch-font-family: var(--kawa-font-sans);
9
+ --docsearch-primary-color: var(--kawa-c-brand);
10
+ --docsearch-primary-dark-color: var(--kawa-c-brand);
11
+ --docsearch-highlight-color: var(--kawa-c-brand);
12
+ --docsearch-focus-color: var(--kawa-c-brand);
13
+ --docsearch-soft-primary-color: color-mix(in oklab, var(--kawa-c-brand) 14%, transparent);
14
+ --docsearch-text-color: var(--kawa-c-text-1);
15
+ --docsearch-secondary-text-color: var(--kawa-c-text-2);
16
+ --docsearch-muted-color: var(--kawa-c-text-3);
17
+ --docsearch-muted-color-darker: color-mix(in oklab, var(--kawa-c-text-3) 25%, transparent);
18
+ --docsearch-icon-color: var(--kawa-c-text-2);
19
+ --docsearch-logo-color: var(--kawa-c-text-2);
20
+ --docsearch-subtle-color: var(--kawa-c-divider);
21
+ --docsearch-error-color: var(--kawa-c-danger);
22
+ --docsearch-background-color: var(--kawa-c-bg-soft);
23
+ --docsearch-container-background: oklch(0.12 0.01 286 / 58%);
24
+ --docsearch-modal-background: var(--kawa-c-bg-elv);
25
+ --docsearch-modal-shadow: var(--kawa-shadow-overlay);
26
+ --docsearch-searchbox-background: var(--kawa-c-bg-soft);
27
+ --docsearch-searchbox-focus-background: var(--kawa-c-bg-soft);
28
+ --docsearch-hit-color: var(--kawa-c-text-1);
29
+ --docsearch-hit-background: var(--kawa-c-bg);
30
+ --docsearch-hit-focus-background: color-mix(in oklab, var(--kawa-c-brand) 12%, var(--kawa-c-bg));
31
+ --docsearch-hit-highlight-color: color-mix(in oklab, var(--kawa-c-brand) 18%, transparent);
32
+ --docsearch-hit-shadow: none;
33
+ --docsearch-key-background: var(--kawa-c-bg-soft);
34
+ --docsearch-key-color: var(--kawa-c-text-2);
35
+ --docsearch-key-pressed-shadow: none;
36
+ --docsearch-footer-background: var(--kawa-c-bg-elv);
37
+ --docsearch-footer-shadow: 0 -1px 0 0 var(--kawa-c-divider);
38
+ --docsearch-dropdown-menu-background: var(--kawa-c-bg-elv);
39
+ --docsearch-dropdown-menu-item-hover-background: var(--kawa-c-bg-soft);
40
+ --docsearch-popover-background: var(--kawa-c-bg-elv);
41
+ --docsearch-chip-background: color-mix(in oklab, var(--kawa-c-brand) 14%, transparent);
42
+ --docsearch-chip-text-color: var(--kawa-c-brand);
43
+ --docsearch-menu-trigger-active-background: color-mix(in oklab, var(--kawa-c-brand) 14%, transparent);
44
+ --docsearch-menu-trigger-active-text-color: var(--kawa-c-brand);
45
+ --docsearch-code-block-background: var(--kawa-c-bg-soft);
46
+ }
47
+
48
+ .kawa-algolia-search {
49
+ display: grid;
50
+ flex: none;
51
+ box-sizing: border-box;
52
+ place-items: center;
53
+ width: 2.25rem;
54
+ height: 2.25rem;
55
+ padding: 0;
56
+ color: var(--kawa-c-text-2);
57
+ font: inherit;
58
+ background: transparent;
59
+ border: 0;
60
+ border-radius: 0.5rem;
61
+ cursor: pointer;
62
+ transition:
63
+ color 180ms cubic-bezier(0.22, 1, 0.36, 1),
64
+ background-color 180ms cubic-bezier(0.22, 1, 0.36, 1);
65
+ }
66
+
67
+ .kawa-algolia-search:hover {
68
+ color: var(--kawa-c-text-1);
69
+ background: var(--kawa-c-bg-soft);
70
+ }
71
+
72
+ .kawa-algolia-search:focus-visible {
73
+ outline: 2px solid var(--kawa-c-brand);
74
+ outline-offset: 2px;
75
+ }
76
+
77
+ .kawa-algolia-search svg {
78
+ width: 1.125rem;
79
+ height: 1.125rem;
80
+ fill: none;
81
+ stroke: currentcolor;
82
+ stroke-linecap: round;
83
+ stroke-linejoin: round;
84
+ stroke-width: 1.75;
85
+ }
86
+
87
+ .kawa-algolia-search__text,
88
+ .kawa-algolia-search__keys {
89
+ display: none;
90
+ }
91
+
92
+ .kawa-algolia-search__keys kbd {
93
+ display: inline-grid;
94
+ min-width: 1.25rem;
95
+ min-height: 1.25rem;
96
+ place-items: center;
97
+ padding: 0 0.25rem;
98
+ color: inherit;
99
+ font: inherit;
100
+ line-height: 1;
101
+ background: color-mix(in oklab, currentcolor 8%, transparent);
102
+ border: 1px solid var(--kawa-c-divider);
103
+ border-radius: 0.25rem;
104
+ }
105
+
106
+ .kawa-algolia-search__command,
107
+ :root[data-kawa-platform='apple'] .kawa-algolia-search__control {
108
+ display: none;
109
+ }
110
+
111
+ :root[data-kawa-platform='apple'] .kawa-algolia-search__command {
112
+ display: inline;
113
+ }
114
+
115
+ @media (min-width: 48rem) {
116
+ .kawa-algolia-search {
117
+ display: flex;
118
+ width: auto;
119
+ gap: 0.625rem;
120
+ padding: 0 0.625rem;
121
+ background: var(--kawa-c-bg-soft);
122
+ }
123
+
124
+ .kawa-algolia-search__text {
125
+ display: inline;
126
+ font-size: 0.8125rem;
127
+ font-weight: 500;
128
+ }
129
+
130
+ .kawa-algolia-search__keys {
131
+ display: flex;
132
+ align-items: center;
133
+ gap: 0.125rem;
134
+ color: var(--kawa-c-text-3);
135
+ }
136
+ }
137
+
138
+ @media (prefers-reduced-motion: reduce) {
139
+ .kawa-algolia-search {
140
+ transition: none;
141
+ }
142
+ }
143
+ }
@@ -0,0 +1,154 @@
1
+ <script setup lang="ts">
2
+ import type { DocSearchInstance } from '@docsearch/js/docsearch'
3
+ import { useHead } from '@unhead/vue'
4
+ import { usePlatformAttribute, useRouter, useSite } from 'kawapress/client'
5
+ import { computed, onBeforeUnmount, onMounted, useTemplateRef, watch } from 'vue'
6
+ import { createDocSearchConfig } from '../docsearch-config'
7
+ import { toRouterLocation, toSiteHref } from '../hit-url'
8
+ import algoliaOptions from '../runtime-options'
9
+ import { resolveButtonText } from '../translations'
10
+
11
+ const site = useSite()
12
+ const router = useRouter()
13
+ const host = useTemplateRef<HTMLElement>('host')
14
+ const trigger = useTemplateRef<HTMLButtonElement>('trigger')
15
+
16
+ const config = computed(() => createDocSearchConfig(
17
+ algoliaOptions,
18
+ site.value.localeIndex,
19
+ site.value.lang,
20
+ ))
21
+ const buttonText = computed(() => resolveButtonText(config.value.translations, site.value.lang))
22
+ const shortcuts = algoliaOptions.keyboardShortcuts
23
+
24
+ usePlatformAttribute()
25
+ useHead({
26
+ link: [{
27
+ rel: 'preconnect',
28
+ href: `https://${algoliaOptions.appId}-dsn.algolia.net`,
29
+ crossorigin: '',
30
+ }],
31
+ })
32
+
33
+ /** The DocSearch instance, created on the first open and rebuilt per locale. */
34
+ let instance: DocSearchInstance | undefined
35
+ let loading: Promise<DocSearchInstance> | undefined
36
+
37
+ onMounted(() => {
38
+ window.addEventListener('keydown', handleShortcut)
39
+ })
40
+
41
+ onBeforeUnmount(() => {
42
+ window.removeEventListener('keydown', handleShortcut)
43
+ dispose()
44
+ })
45
+
46
+ // The index and the language filter depend on the locale, so another locale
47
+ // gets a fresh instance on its next open.
48
+ watch(() => `${site.value.localeIndex}:${site.value.lang}`, dispose)
49
+
50
+ /**
51
+ * Opens DocSearch, loading it first. The library is about a third of the
52
+ * payload of a page, so nobody downloads it until they ask for search.
53
+ */
54
+ async function open(): Promise<void> {
55
+ const ready = instance ?? await (loading ??= load())
56
+ ready.open()
57
+ }
58
+
59
+ async function load(): Promise<DocSearchInstance> {
60
+ try {
61
+ const [{ default: docsearch }] = await Promise.all([
62
+ import('@docsearch/js/docsearch'),
63
+ import('../docsearch-vendor.css'),
64
+ ])
65
+ instance = docsearch({
66
+ ...config.value,
67
+ container: host.value!,
68
+ transformItems: items => items.map(item => ({
69
+ ...item,
70
+ url: toSiteHref(item.url, site.value.base),
71
+ })),
72
+ navigator: {
73
+ navigate: ({ itemUrl }) => navigate(itemUrl),
74
+ },
75
+ // DocSearch would focus its own button, which stays hidden in the host.
76
+ onClose: () => trigger.value?.focus(),
77
+ })
78
+ return instance
79
+ }
80
+ finally {
81
+ loading = undefined
82
+ }
83
+ }
84
+
85
+ /** Enter on a hit. A click on a hit is a plain link, which the router handles. */
86
+ function navigate(itemUrl: string): void {
87
+ const location = toRouterLocation(itemUrl, site.value.base)
88
+ if (location === undefined) {
89
+ window.location.assign(itemUrl)
90
+ return
91
+ }
92
+ void router.push(location).catch((error: unknown) => {
93
+ console.error('[KawaPress Algolia search] Navigation failed:', error)
94
+ })
95
+ }
96
+
97
+ /** Until DocSearch is loaded, the shortcuts are this button's to answer. */
98
+ function handleShortcut(event: KeyboardEvent): void {
99
+ if (instance || event.defaultPrevented || event.isComposing) {
100
+ return
101
+ }
102
+ const commandK = shortcuts['Ctrl/Cmd+K']
103
+ && event.key.toLowerCase() === 'k'
104
+ && (event.metaKey || event.ctrlKey)
105
+ && !event.altKey
106
+ const slash = shortcuts['/']
107
+ && event.key === '/'
108
+ && !event.metaKey
109
+ && !event.ctrlKey
110
+ && !event.altKey
111
+ && !isEditing(event.target)
112
+
113
+ if (commandK || slash) {
114
+ event.preventDefault()
115
+ void open()
116
+ }
117
+ }
118
+
119
+ function isEditing(target: EventTarget | null): boolean {
120
+ return target instanceof HTMLElement && Boolean(target.closest(
121
+ 'input, textarea, select, [contenteditable]:not([contenteditable="false"])',
122
+ ))
123
+ }
124
+
125
+ function dispose(): void {
126
+ instance?.destroy()
127
+ instance = undefined
128
+ }
129
+ </script>
130
+
131
+ <template>
132
+ <button
133
+ ref="trigger"
134
+ type="button"
135
+ class="kawa-algolia-search"
136
+ :aria-label="buttonText"
137
+ :aria-keyshortcuts="shortcuts['Ctrl/Cmd+K'] ? 'Control+K Meta+K' : undefined"
138
+ @click="open"
139
+ >
140
+ <svg viewBox="0 0 24 24" aria-hidden="true">
141
+ <circle cx="11" cy="11" r="6.5" />
142
+ <path d="m16 16 4 4" />
143
+ </svg>
144
+ <span class="kawa-algolia-search__text">{{ buttonText }}</span>
145
+ <span v-if="shortcuts['Ctrl/Cmd+K']" class="kawa-algolia-search__keys" aria-hidden="true">
146
+ <kbd>
147
+ <span class="kawa-algolia-search__command">⌘</span>
148
+ <span class="kawa-algolia-search__control">Ctrl</span>
149
+ </kbd>
150
+ <kbd>K</kbd>
151
+ </span>
152
+ </button>
153
+ <div ref="host" class="kawa-algolia-search__host" hidden />
154
+ </template>
@@ -0,0 +1,61 @@
1
+ import type { AlgoliaIndex, AlgoliaSearchParameters, ResolvedAlgoliaSearchOptions } from './options'
2
+ import { mergeLocaleOptions } from './options'
3
+
4
+ /** The JSON part of the `@docsearch/js` props for one locale. */
5
+ export interface DocSearchConfig {
6
+ appId: string
7
+ apiKey: string
8
+ indices: Required<AlgoliaIndex>[]
9
+ keyboardShortcuts: ResolvedAlgoliaSearchOptions['keyboardShortcuts']
10
+ placeholder?: string
11
+ translations?: Record<string, unknown>
12
+ maxResultsPerGroup?: number
13
+ disableUserPersonalization?: boolean
14
+ insights?: boolean
15
+ facets?: { key: string, label?: string }[]
16
+ resultBadgeKey?: string
17
+ }
18
+
19
+ /**
20
+ * DocSearch props for the current locale. Every index gets the shared search
21
+ * parameters and a `lang:<lang>` facet filter, so a multilingual index only
22
+ * answers in the language of the page, the same way VitePress does it.
23
+ */
24
+ export function createDocSearchConfig(
25
+ options: ResolvedAlgoliaSearchOptions,
26
+ localeIndex: string,
27
+ lang: string | undefined,
28
+ ): DocSearchConfig {
29
+ const { indices, searchParameters, ...locale } = mergeLocaleOptions(options, localeIndex)
30
+ return {
31
+ ...locale,
32
+ appId: options.appId,
33
+ apiKey: options.apiKey,
34
+ keyboardShortcuts: options.keyboardShortcuts,
35
+ indices: indices.map((index) => {
36
+ const { name, searchParameters: own } = typeof index === 'string' ? { name: index } : index
37
+ return {
38
+ name,
39
+ searchParameters: withLanguageFilter({ ...searchParameters, ...own }, lang),
40
+ }
41
+ }),
42
+ }
43
+ }
44
+
45
+ function withLanguageFilter(
46
+ parameters: AlgoliaSearchParameters,
47
+ lang: string | undefined,
48
+ ): AlgoliaSearchParameters {
49
+ if (!lang) {
50
+ return parameters
51
+ }
52
+ const raw = parameters.facetFilters
53
+ const existing = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw]
54
+ return {
55
+ ...parameters,
56
+ facetFilters: [
57
+ ...existing.filter(filter => typeof filter !== 'string' || !filter.startsWith('lang:')),
58
+ `lang:${lang}`,
59
+ ],
60
+ }
61
+ }
@@ -0,0 +1,5 @@
1
+ /*
2
+ * The DocSearch modal styles. They load together with the library on the first
3
+ * search and must name a layer, otherwise they outrank the site theme.
4
+ */
5
+ @import url('@docsearch/css/dist/style.css') layer(kawa.plugin);
package/src/hit-url.ts ADDED
@@ -0,0 +1,44 @@
1
+ import { withoutBase } from 'kawapress/client'
2
+
3
+ const HTML_EXTENSION_RE = /\.html$/i
4
+ const INDEX_PAGE_RE = /\/index$/i
5
+ const URL_PARSE_ORIGIN = 'https://kawapress.invalid'
6
+
7
+ /**
8
+ * Link of a search hit inside this site: the path, query, and hash of the URL
9
+ * the crawler stored, with `.html` and `/index` removed so it names the route
10
+ * of the page. The origin is dropped on purpose, because the index usually
11
+ * holds the production domain while the site may run anywhere.
12
+ */
13
+ export function toSiteHref(url: string, base: string): string {
14
+ const { pathname, search, hash } = new URL(url, URL_PARSE_ORIGIN)
15
+ let path = pathname.replace(HTML_EXTENSION_RE, '').replace(INDEX_PAGE_RE, '/')
16
+ if (path.length > 1 && path.endsWith('/') && path !== siteRoot(base)) {
17
+ path = path.slice(0, -1)
18
+ }
19
+ return `${path}${search}${hash}`
20
+ }
21
+
22
+ /**
23
+ * Router location of a site href, or `undefined` when the href points outside
24
+ * the site base.
25
+ */
26
+ export function toRouterLocation(href: string, base: string): string | undefined {
27
+ const { pathname, search, hash } = new URL(href, URL_PARSE_ORIGIN)
28
+ const path = withoutBase(decodePathname(pathname), base)
29
+ return path === undefined ? undefined : `${path}${search}${hash}`
30
+ }
31
+
32
+ function siteRoot(base: string): string {
33
+ const trimmed = base.split('/').filter(Boolean).join('/')
34
+ return trimmed ? `/${trimmed}/` : '/'
35
+ }
36
+
37
+ function decodePathname(pathname: string): string {
38
+ try {
39
+ return decodeURI(pathname)
40
+ }
41
+ catch {
42
+ return pathname
43
+ }
44
+ }
package/src/index.ts ADDED
@@ -0,0 +1,42 @@
1
+ import type { KawaPressPlugin } from 'kawapress'
2
+ import type { AlgoliaSearchPluginOptions } from './options'
3
+ import { definePlugin } from 'kawapress'
4
+ import { useRuntimeDependencies } from 'kawapress/generator'
5
+ import { resolveAlgoliaSearchOptions } from './options'
6
+ import { algoliaOptionsPlugin } from './vite-plugin'
7
+
8
+ export const ALGOLIA_SEARCH_PLUGIN_NAME = '@kawapress/plugin-algolia-search'
9
+
10
+ const RUNTIME_DEPENDENCIES = ['@docsearch/js/docsearch']
11
+
12
+ /**
13
+ * Searches the site through Algolia DocSearch. The options are validated here,
14
+ * at config time, and handed to the runtime as plain JSON; the DocSearch
15
+ * library itself is only downloaded when a reader opens the search.
16
+ */
17
+ export function algoliaSearchPlugin(options: AlgoliaSearchPluginOptions): KawaPressPlugin {
18
+ const resolved = resolveAlgoliaSearchOptions(options)
19
+
20
+ return definePlugin({
21
+ name: ALGOLIA_SEARCH_PLUGIN_NAME,
22
+ setup(api) {
23
+ api.vite((config) => {
24
+ useRuntimeDependencies(config, ALGOLIA_SEARCH_PLUGIN_NAME, RUNTIME_DEPENDENCIES)
25
+ config.plugins ??= []
26
+ config.plugins.push(algoliaOptionsPlugin(resolved))
27
+ })
28
+ },
29
+ })
30
+ }
31
+
32
+ export default algoliaSearchPlugin
33
+
34
+ export type {
35
+ AlgoliaIndex,
36
+ AlgoliaLocaleOptions,
37
+ AlgoliaSearchParameters,
38
+ AlgoliaSearchPluginOptions,
39
+ AlgoliaTranslations,
40
+ ResolvedAlgoliaLocaleOptions,
41
+ ResolvedAlgoliaSearchOptions,
42
+ } from './options'
package/src/options.ts ADDED
@@ -0,0 +1,234 @@
1
+ /** An index to search, with optional Algolia search parameters of its own. */
2
+ export interface AlgoliaIndex {
3
+ name: string
4
+ searchParameters?: AlgoliaSearchParameters
5
+ }
6
+
7
+ /**
8
+ * Algolia search parameters, for example `{ facetFilters: ['version:v2'] }`.
9
+ * They are sent to Algolia as written.
10
+ */
11
+ export type AlgoliaSearchParameters = Record<string, unknown>
12
+
13
+ /**
14
+ * Texts of the DocSearch modal, in the shape `@docsearch/js` documents:
15
+ * https://docsearch.algolia.com/docs/api#translations
16
+ */
17
+ export type AlgoliaTranslations = Record<string, unknown> & {
18
+ button?: {
19
+ buttonText?: string
20
+ buttonAriaLabel?: string
21
+ }
22
+ }
23
+
24
+ /** Options that can differ per locale. */
25
+ export interface AlgoliaLocaleOptions {
26
+ /** Index to search; a shorthand for `indices: [indexName]`. */
27
+ indexName?: string
28
+ /** Indices to search, used instead of `indexName`. */
29
+ indices?: (string | AlgoliaIndex)[]
30
+ /** Search parameters applied to every index. */
31
+ searchParameters?: AlgoliaSearchParameters
32
+ placeholder?: string
33
+ translations?: AlgoliaTranslations
34
+ maxResultsPerGroup?: number
35
+ /** Turns off the recent and favorite searches DocSearch keeps in the browser. */
36
+ disableUserPersonalization?: boolean
37
+ /** Sends click and conversion events to Algolia Insights. */
38
+ insights?: boolean
39
+ /** Facets shown as filters above the results. */
40
+ facets?: { key: string, label?: string }[]
41
+ /** Hit attribute shown as a badge next to each result. */
42
+ resultBadgeKey?: string
43
+ }
44
+
45
+ export interface AlgoliaSearchPluginOptions extends AlgoliaLocaleOptions {
46
+ /** Application ID from the Algolia dashboard. */
47
+ appId: string
48
+ /** Search-only API key. It is public; never use an admin key here. */
49
+ apiKey: string
50
+ /** Turns the Ctrl/Cmd+K and `/` shortcuts on or off. Both are on by default. */
51
+ keyboardShortcuts?: {
52
+ 'Ctrl/Cmd+K'?: boolean
53
+ '/'?: boolean
54
+ }
55
+ /** Overrides per locale key, merged over the options above. */
56
+ locales?: Record<string, AlgoliaLocaleOptions>
57
+ }
58
+
59
+ /** Options of one locale, ready for `@docsearch/js`. */
60
+ export interface ResolvedAlgoliaLocaleOptions extends Omit<AlgoliaLocaleOptions, 'indexName'> {
61
+ indices: (string | AlgoliaIndex)[]
62
+ }
63
+
64
+ /** What the runtime receives through the virtual module. */
65
+ export interface ResolvedAlgoliaSearchOptions extends ResolvedAlgoliaLocaleOptions {
66
+ appId: string
67
+ apiKey: string
68
+ keyboardShortcuts: {
69
+ 'Ctrl/Cmd+K': boolean
70
+ '/': boolean
71
+ }
72
+ locales: Record<string, AlgoliaLocaleOptions>
73
+ }
74
+
75
+ const OPTION_PATH = 'plugins: [algoliaSearchPlugin({ ... })]'
76
+
77
+ const LOCALE_KEYS = [
78
+ 'indexName',
79
+ 'indices',
80
+ 'searchParameters',
81
+ 'placeholder',
82
+ 'translations',
83
+ 'maxResultsPerGroup',
84
+ 'disableUserPersonalization',
85
+ 'insights',
86
+ 'facets',
87
+ 'resultBadgeKey',
88
+ ] as const
89
+
90
+ const SITE_KEYS = [...LOCALE_KEYS, 'appId', 'apiKey', 'keyboardShortcuts', 'locales'] as const
91
+
92
+ /**
93
+ * Validates the plugin options at config time, so a typo fails the build with a
94
+ * clear message instead of an empty search box in the browser.
95
+ */
96
+ export function resolveAlgoliaSearchOptions(
97
+ options: AlgoliaSearchPluginOptions | undefined,
98
+ ): ResolvedAlgoliaSearchOptions {
99
+ if (!isRecord(options)) {
100
+ throw new Error(
101
+ `KawaPress Algolia search: ${OPTION_PATH} is missing its options. `
102
+ + 'Pass the appId, apiKey, and indexName that Algolia gave you for DocSearch.',
103
+ )
104
+ }
105
+ rejectUnknownKeys(options, SITE_KEYS, 'options')
106
+
107
+ const appId = requireText(options.appId, 'appId', 'Copy the Application ID from the Algolia dashboard.')
108
+ const apiKey = requireText(
109
+ options.apiKey,
110
+ 'apiKey',
111
+ 'Use the search-only API key from the Algolia dashboard, never an admin key.',
112
+ )
113
+
114
+ const locales: Record<string, AlgoliaLocaleOptions> = {}
115
+ for (const [localeIndex, localeOptions] of Object.entries(options.locales ?? {})) {
116
+ const path = `locales.${localeIndex}`
117
+ if (!isRecord(localeOptions)) {
118
+ throw new TypeError(`KawaPress Algolia search: "${path}" must be an object.`)
119
+ }
120
+ rejectUnknownKeys(localeOptions, LOCALE_KEYS, path)
121
+ // A locale may change only what it needs; the merged result must still name an index.
122
+ resolveLocaleOptions(overrideLocale(options, localeOptions), path)
123
+ locales[localeIndex] = localeOptions
124
+ }
125
+
126
+ return {
127
+ ...resolveLocaleOptions(options, 'options'),
128
+ appId,
129
+ apiKey,
130
+ keyboardShortcuts: {
131
+ 'Ctrl/Cmd+K': options.keyboardShortcuts?.['Ctrl/Cmd+K'] ?? true,
132
+ '/': options.keyboardShortcuts?.['/'] ?? true,
133
+ },
134
+ locales,
135
+ }
136
+ }
137
+
138
+ /**
139
+ * The options of one locale: the site options with the locale overrides on top,
140
+ * and `indexName` folded into `indices`.
141
+ */
142
+ export function mergeLocaleOptions(
143
+ options: ResolvedAlgoliaSearchOptions,
144
+ localeIndex: string,
145
+ ): ResolvedAlgoliaLocaleOptions {
146
+ const overrides = options.locales[localeIndex]
147
+ return overrides
148
+ ? resolveLocaleOptions(overrideLocale(options, overrides), `locales.${localeIndex}`)
149
+ : resolveLocaleOptions(options, 'options')
150
+ }
151
+
152
+ /**
153
+ * Site options with locale overrides on top. A locale that names an index, in
154
+ * either form, replaces the site's indices instead of adding to them.
155
+ */
156
+ function overrideLocale(
157
+ site: AlgoliaLocaleOptions,
158
+ overrides: AlgoliaLocaleOptions,
159
+ ): AlgoliaLocaleOptions {
160
+ const merged = { ...pickLocaleOptions(site), ...pickLocaleOptions(overrides) }
161
+ if (overrides.indexName !== undefined && overrides.indices === undefined) {
162
+ delete merged.indices
163
+ }
164
+ return merged
165
+ }
166
+
167
+ function resolveLocaleOptions(
168
+ options: AlgoliaLocaleOptions,
169
+ path: string,
170
+ ): ResolvedAlgoliaLocaleOptions {
171
+ const { indexName, indices, ...rest } = pickLocaleOptions(options)
172
+ // An explicit `indices` wins, so a locale can replace the site's `indexName`.
173
+ const resolvedIndices = indices ?? (indexName === undefined ? undefined : [indexName])
174
+ if (!Array.isArray(resolvedIndices) || resolvedIndices.length === 0) {
175
+ throw new Error(
176
+ `KawaPress Algolia search: "${path}" needs "indexName" or a non-empty "indices" list. `
177
+ + 'Use the index name from your DocSearch crawler, for example indexName: "my-docs".',
178
+ )
179
+ }
180
+ resolvedIndices.forEach((index, position) => assertIndex(index, `${path}.indices[${position}]`))
181
+ return { ...rest, indices: resolvedIndices }
182
+ }
183
+
184
+ /** Only the options a locale may change, without the keys that are not set. */
185
+ function pickLocaleOptions(options: AlgoliaLocaleOptions): AlgoliaLocaleOptions {
186
+ return Object.fromEntries(
187
+ LOCALE_KEYS
188
+ .filter(key => options[key] !== undefined)
189
+ .map(key => [key, options[key]]),
190
+ ) as AlgoliaLocaleOptions
191
+ }
192
+
193
+ function assertIndex(index: unknown, path: string): void {
194
+ if (typeof index === 'string' && index.trim() !== '') {
195
+ return
196
+ }
197
+ if (isRecord(index) && typeof index.name === 'string' && index.name.trim() !== '') {
198
+ return
199
+ }
200
+ throw new Error(
201
+ `KawaPress Algolia search: "${path}" must be an index name or { name, searchParameters }, `
202
+ + `received ${JSON.stringify(index)}.`,
203
+ )
204
+ }
205
+
206
+ function rejectUnknownKeys(
207
+ value: Record<string, unknown>,
208
+ allowed: readonly string[],
209
+ path: string,
210
+ ): void {
211
+ const unknown = Object.keys(value).filter(key => !allowed.includes(key))
212
+ if (unknown.length > 0) {
213
+ throw new Error(
214
+ `KawaPress Algolia search: "${path}" has unsupported ${unknown.length === 1 ? 'option' : 'options'} `
215
+ + `${unknown.map(key => JSON.stringify(key)).join(', ')}. `
216
+ + `Supported options are ${allowed.join(', ')}. Options that take a function cannot be `
217
+ + 'passed from kawapress.config.ts, because they have to reach the browser as JSON.',
218
+ )
219
+ }
220
+ }
221
+
222
+ function requireText(value: unknown, path: string, hint: string): string {
223
+ if (typeof value !== 'string' || value.trim() === '') {
224
+ throw new Error(
225
+ `KawaPress Algolia search: ${OPTION_PATH} needs a non-empty string at "${path}", `
226
+ + `received ${JSON.stringify(value)}. ${hint}`,
227
+ )
228
+ }
229
+ return value.trim()
230
+ }
231
+
232
+ function isRecord(value: unknown): value is Record<string, unknown> {
233
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
234
+ }
@@ -0,0 +1,10 @@
1
+ import type { ResolvedAlgoliaSearchOptions } from './options'
2
+ import options from 'virtual:kawapress-algolia-search-options'
3
+
4
+ /**
5
+ * Site options as the generator published them. The runtime reads them here so
6
+ * no module on the browser side imports the generator half of this package.
7
+ */
8
+ const resolvedOptions: ResolvedAlgoliaSearchOptions = options
9
+
10
+ export default resolvedOptions
@@ -0,0 +1,13 @@
1
+ import { defineRuntimePlugin } from 'kawapress'
2
+ import AlgoliaSearch from './components/AlgoliaSearch.vue'
3
+ import './algolia-search.css'
4
+
5
+ export default defineRuntimePlugin({
6
+ name: '@kawapress/plugin-algolia-search',
7
+ setup(api) {
8
+ api.prependToOutlet('layout.header.end', { id: 'trigger', component: AlgoliaSearch })
9
+ api.vueApp((app) => {
10
+ app.component('KawaAlgoliaSearch', AlgoliaSearch)
11
+ })
12
+ },
13
+ })
@@ -0,0 +1,22 @@
1
+ const BUTTON_TEXT = {
2
+ en: 'Search',
3
+ zh: '搜索',
4
+ } as const
5
+
6
+ /**
7
+ * Text of the search button: the `translations.button.buttonText` the site
8
+ * author wrote, otherwise a built-in label in the language of the page.
9
+ */
10
+ export function resolveButtonText(
11
+ translations: Record<string, unknown> | undefined,
12
+ lang: string | undefined,
13
+ ): string {
14
+ const button = translations?.button
15
+ const text = typeof button === 'object' && button !== null
16
+ ? (button as { buttonText?: unknown }).buttonText
17
+ : undefined
18
+ if (typeof text === 'string' && text.trim() !== '') {
19
+ return text
20
+ }
21
+ return (lang ?? '').toLowerCase().startsWith('zh') ? BUTTON_TEXT.zh : BUTTON_TEXT.en
22
+ }
@@ -0,0 +1,4 @@
1
+ declare module 'virtual:kawapress-algolia-search-options' {
2
+ const options: import('./options').ResolvedAlgoliaSearchOptions
3
+ export default options
4
+ }
@@ -0,0 +1,31 @@
1
+ import type { Plugin } from 'vite'
2
+ import type { ResolvedAlgoliaSearchOptions } from './options'
3
+ import { stringifyJson } from 'kawapress'
4
+
5
+ export const ALGOLIA_OPTIONS_MODULE_ID = 'virtual:kawapress-algolia-search-options'
6
+
7
+ const RESOLVED_MODULE_ID = `\0${ALGOLIA_OPTIONS_MODULE_ID}`
8
+
9
+ /**
10
+ * Publishes the plugin options to the browser as plain JSON. The runtime half of
11
+ * the plugin must never import this package's generator half.
12
+ */
13
+ export function algoliaOptionsPlugin(options: ResolvedAlgoliaSearchOptions): Plugin {
14
+ return {
15
+ name: 'kawapress:algolia-search-options',
16
+ resolveId(id) {
17
+ if (id === ALGOLIA_OPTIONS_MODULE_ID) {
18
+ return RESOLVED_MODULE_ID
19
+ }
20
+ },
21
+ load(id) {
22
+ if (id !== RESOLVED_MODULE_ID) {
23
+ return
24
+ }
25
+ return `export default ${stringifyJson(options, {
26
+ label: 'options of @kawapress/plugin-algolia-search',
27
+ path: 'algoliaSearchPlugin',
28
+ })}`
29
+ },
30
+ }
31
+ }