@kawapress/plugin-algolia-search 0.0.0-stage → 0.4.0
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 +21 -0
- package/README-zh-CN.md +70 -0
- package/README.md +69 -2
- package/package.json +52 -3
- package/src/algolia-search.css +143 -0
- package/src/components/AlgoliaSearch.vue +154 -0
- package/src/docsearch-config.ts +61 -0
- package/src/docsearch-vendor.css +5 -0
- package/src/hit-url.ts +44 -0
- package/src/index.ts +42 -0
- package/src/options.ts +234 -0
- package/src/runtime-options.ts +10 -0
- package/src/runtime-plugin.ts +13 -0
- package/src/translations.ts +22 -0
- package/src/virtual-modules.d.ts +4 -0
- package/src/vite-plugin.ts +31 -0
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.
|
package/README-zh-CN.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# @kawapress/plugin-algolia-search
|
|
2
|
+
|
|
3
|
+
为 KawaPress 站点接入 Algolia DocSearch 搜索。
|
|
4
|
+
|
|
5
|
+
[](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
|
-
#
|
|
1
|
+
# @kawapress/plugin-algolia-search
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Algolia DocSearch for KawaPress sites.
|
|
4
|
+
|
|
5
|
+
[](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
|
-
"
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
3
|
+
"type": "module",
|
|
4
|
+
"version": "0.4.0",
|
|
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.4.0"
|
|
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.4.0"
|
|
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
|
+
}
|
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,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
|
+
}
|