@molecule/app-search-autocomplete-vue 0.0.1-stage → 1.1.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/README.md +228 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,235 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-11-21T12:47:13.298Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-search-autocomplete-vue
|
|
2
10
|
|
|
3
|
-
Search input with typeahead suggestion popover
|
|
11
|
+
Search input with a typeahead suggestion popover.
|
|
12
|
+
|
|
13
|
+
Exports `<SearchAutocomplete>` and the `SuggestionItem<T>` type
|
|
14
|
+
(`{ id, label, meta?, data? }`). Two data modes — pass ONE of:
|
|
15
|
+
`onSearch(query)` (async fetch, debounced; default 200 ms) or
|
|
16
|
+
`suggestions` (caller-controlled list). Other props: `value` / `onChange`
|
|
17
|
+
(controlled input), `onSelect(item)`, `placeholder?` (defaults to the
|
|
18
|
+
translated `search.placeholder`), `debounceMs?`, `minChars?` (default 1),
|
|
19
|
+
`className?`.
|
|
20
|
+
|
|
21
|
+
Vue counterpart of `@molecule/app-search-autocomplete-react`: the same
|
|
22
|
+
exports, the same props (React names), the same ClassMap tokens and the same
|
|
23
|
+
DOM for the same input.
|
|
24
|
+
|
|
25
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
26
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
27
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
28
|
+
|
|
29
|
+
## Quick Start
|
|
4
30
|
|
|
31
|
+
```ts
|
|
32
|
+
import { createApp, defineComponent, h, ref } from 'vue'
|
|
33
|
+
import { moleculePlugin } from '@molecule/app-vue'
|
|
34
|
+
import { SearchAutocomplete } from '@molecule/app-search-autocomplete-vue'
|
|
35
|
+
import type { SuggestionItem } from '@molecule/app-search-autocomplete-vue'
|
|
36
|
+
|
|
37
|
+
const UserSearch = defineComponent({
|
|
38
|
+
setup() {
|
|
39
|
+
const query = ref('')
|
|
40
|
+
const fetchUsers = (q: string): Promise<SuggestionItem<{ id: string }>[]> =>
|
|
41
|
+
fetch(`/api/users?q=${encodeURIComponent(q)}`).then((r) => r.json())
|
|
42
|
+
|
|
43
|
+
return () =>
|
|
44
|
+
h(SearchAutocomplete, {
|
|
45
|
+
value: query.value,
|
|
46
|
+
onChange: (next: string) => {
|
|
47
|
+
query.value = next
|
|
48
|
+
},
|
|
49
|
+
onSearch: fetchUsers,
|
|
50
|
+
onSelect: (item) => console.log(item.data?.id),
|
|
51
|
+
placeholder: 'Search users…',
|
|
52
|
+
})
|
|
53
|
+
},
|
|
54
|
+
})
|
|
55
|
+
|
|
56
|
+
const app = createApp(UserSearch)
|
|
57
|
+
app.use(moleculePlugin, { i18n: i18nProvider })
|
|
58
|
+
app.mount('#app')
|
|
5
59
|
```
|
|
6
|
-
|
|
60
|
+
|
|
61
|
+
## Type
|
|
62
|
+
|
|
63
|
+
`feature`
|
|
64
|
+
|
|
65
|
+
## Installation
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npm install @molecule/app-search-autocomplete-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
|
|
7
69
|
```
|
|
8
70
|
|
|
9
|
-
|
|
71
|
+
## API
|
|
72
|
+
|
|
73
|
+
### Interfaces
|
|
74
|
+
|
|
75
|
+
#### `SuggestionItem`
|
|
76
|
+
|
|
77
|
+
A single suggestion entry returned by `onSearch` or passed via `suggestions`.
|
|
78
|
+
|
|
79
|
+
```typescript
|
|
80
|
+
interface SuggestionItem<T = unknown> {
|
|
81
|
+
id: string
|
|
82
|
+
label: VNodeChild
|
|
83
|
+
/** Optional secondary line / category. */
|
|
84
|
+
meta?: VNodeChild
|
|
85
|
+
/** Original payload for the selection callback. */
|
|
86
|
+
data?: T
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
#### `SearchAutocompleteProps`
|
|
91
|
+
|
|
92
|
+
Props accepted by the {@link SearchAutocomplete} component.
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
interface SearchAutocompleteProps<T = unknown> {
|
|
96
|
+
/** Current input value. */
|
|
97
|
+
value: string
|
|
98
|
+
/** Called whenever the input changes. */
|
|
99
|
+
onChange: (value: string) => void
|
|
100
|
+
/** Async search function — receives the query, returns suggestions. */
|
|
101
|
+
onSearch?: (query: string) => Promise<SuggestionItem<T>[]> | SuggestionItem<T>[]
|
|
102
|
+
/** Optional pre-computed suggestion list (when caller controls fetching). */
|
|
103
|
+
suggestions?: SuggestionItem<T>[]
|
|
104
|
+
/** Called when the user picks a suggestion. */
|
|
105
|
+
onSelect: (item: SuggestionItem<T>) => void
|
|
106
|
+
/** Placeholder. */
|
|
107
|
+
placeholder?: string
|
|
108
|
+
/**
|
|
109
|
+
* Accessible name for the input, rendered as `aria-label`. Defaults to the
|
|
110
|
+
* translated `search.aria.label`: a placeholder is not a label, so an input
|
|
111
|
+
* named only by its placeholder (let alone an empty one) is nameless for
|
|
112
|
+
* assistive technology.
|
|
113
|
+
*/
|
|
114
|
+
ariaLabel?: string
|
|
115
|
+
/** Debounce ms for `onSearch`. Defaults to 200. */
|
|
116
|
+
debounceMs?: number
|
|
117
|
+
/** Min chars before suggestions appear. Defaults to 1. */
|
|
118
|
+
minChars?: number
|
|
119
|
+
/** Extra classes on the wrapper. */
|
|
120
|
+
className?: string
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Constants
|
|
125
|
+
|
|
126
|
+
#### `SearchAutocomplete`
|
|
127
|
+
|
|
128
|
+
Search input with a typeahead suggestions popover. Pass either
|
|
129
|
+
`onSearch` (async fetch with debounce) or `suggestions` (controlled).
|
|
130
|
+
|
|
131
|
+
Vue counterpart of `@molecule/app-search-autocomplete-react`'s
|
|
132
|
+
`SearchAutocomplete` — the same props (React names), the same ClassMap
|
|
133
|
+
tokens, the same DOM for the same input, and the same callback calls.
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
const SearchAutocomplete: DefineComponent<
|
|
137
|
+
ExtractPropTypes<{
|
|
138
|
+
value: { type: StringConstructor; required: true }
|
|
139
|
+
onChange: { type: PropType<(value: string) => void>; default: undefined }
|
|
140
|
+
onSearch: {
|
|
141
|
+
type: PropType<(query: string) => Promise<SuggestionItem[]> | SuggestionItem[]>
|
|
142
|
+
default: undefined
|
|
143
|
+
}
|
|
144
|
+
suggestions: { type: PropType<SuggestionInput[]>; default: undefined }
|
|
145
|
+
onSelect: { type: PropType<(item: SuggestionItem<unknown>) => void>; default: undefined }
|
|
146
|
+
placeholder: StringConstructor
|
|
147
|
+
ariaLabel: StringConstructor
|
|
148
|
+
debounceMs: { type: NumberConstructor; default: number }
|
|
149
|
+
minChars: { type: NumberConstructor; default: number }
|
|
150
|
+
className: StringConstructor
|
|
151
|
+
}>,
|
|
152
|
+
() => VNode,
|
|
153
|
+
{},
|
|
154
|
+
{},
|
|
155
|
+
{},
|
|
156
|
+
ComponentOptionsMixin,
|
|
157
|
+
ComponentOptionsMixin,
|
|
158
|
+
{},
|
|
159
|
+
string,
|
|
160
|
+
PublicProps,
|
|
161
|
+
Readonly<
|
|
162
|
+
ExtractPropTypes<{
|
|
163
|
+
value: { type: StringConstructor; required: true }
|
|
164
|
+
onChange: { type: PropType<(value: string) => void>; default: undefined }
|
|
165
|
+
onSearch: {
|
|
166
|
+
type: PropType<(query: string) => Promise<SuggestionItem[]> | SuggestionItem[]>
|
|
167
|
+
default: undefined
|
|
168
|
+
}
|
|
169
|
+
suggestions: { type: PropType<SuggestionInput[]>; default: undefined }
|
|
170
|
+
onSelect: { type: PropType<(item: SuggestionItem<unknown>) => void>; default: undefined }
|
|
171
|
+
placeholder: StringConstructor
|
|
172
|
+
ariaLabel: StringConstructor
|
|
173
|
+
debounceMs: { type: NumberConstructor; default: number }
|
|
174
|
+
minChars: { type: NumberConstructor; default: number }
|
|
175
|
+
className: StringConstructor
|
|
176
|
+
}>
|
|
177
|
+
> &
|
|
178
|
+
Readonly<{}>,
|
|
179
|
+
{
|
|
180
|
+
onChange: (value: string) => void
|
|
181
|
+
onSearch: (query: string) => Promise<SuggestionItem[]> | SuggestionItem[]
|
|
182
|
+
suggestions: SuggestionInput[]
|
|
183
|
+
onSelect: (item: SuggestionItem<unknown>) => void
|
|
184
|
+
debounceMs: number
|
|
185
|
+
minChars: number
|
|
186
|
+
},
|
|
187
|
+
{},
|
|
188
|
+
{},
|
|
189
|
+
{},
|
|
190
|
+
string,
|
|
191
|
+
ComponentProvideOptions,
|
|
192
|
+
true,
|
|
193
|
+
{},
|
|
194
|
+
any
|
|
195
|
+
>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
- `props` — Component props (see {@link SearchAutocompleteProps}).
|
|
199
|
+
|
|
200
|
+
**Returns:** The search-autocomplete component.
|
|
201
|
+
|
|
202
|
+
## Injection Notes
|
|
203
|
+
|
|
204
|
+
### Requirements
|
|
205
|
+
|
|
206
|
+
Peer dependencies:
|
|
207
|
+
|
|
208
|
+
- `@molecule/app-ui` ^1.0.1
|
|
209
|
+
- `@molecule/app-ui-vue` ^1.1.0
|
|
210
|
+
- `@molecule/app-vue` ^3.5.0
|
|
211
|
+
- `vue` ^3.4.0
|
|
212
|
+
|
|
213
|
+
### Runtime Dependencies
|
|
214
|
+
|
|
215
|
+
- `@molecule/app-ui`
|
|
216
|
+
- `@molecule/app-ui-vue`
|
|
217
|
+
- `@molecule/app-vue`
|
|
218
|
+
- `vue`
|
|
219
|
+
|
|
220
|
+
- Throws unless mounted under `moleculePlugin` (from `@molecule/app-vue`)
|
|
221
|
+
with a bonded ClassMap.
|
|
222
|
+
- Full keyboard support: it's an ARIA combobox — ArrowDown/ArrowUp move the
|
|
223
|
+
highlight (opening the popover), Enter selects the highlighted option, and
|
|
224
|
+
Escape closes. `aria-activedescendant` tracks the active `role="option"`.
|
|
225
|
+
- Stale-response safe: out-of-order `onSearch` responses are dropped (each
|
|
226
|
+
request carries a token; only the latest applies), so a slow earlier fetch
|
|
227
|
+
can't overwrite fresher results. `onSearch` needs no cancellation of its own.
|
|
228
|
+
- The popover surface uses `var(--color-surface)` with a WHITE fallback
|
|
229
|
+
and black-alpha borders — define `--color-surface` (dark themes) or the
|
|
230
|
+
dropdown stays light.
|
|
231
|
+
- Default placeholder translations: `@molecule/app-locales-search-autocomplete`.
|
|
232
|
+
|
|
233
|
+
## Translations
|
|
10
234
|
|
|
11
|
-
|
|
235
|
+
Translation strings are provided by `@molecule/app-locales-search-autocomplete`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-search-autocomplete-vue",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Search input with typeahead suggestion popover",
|
|
5
5
|
"homepage": "https://www.molecule.dev/packages/app-search-autocomplete-vue",
|
|
6
6
|
"type": "module",
|
|
@@ -51,9 +51,9 @@
|
|
|
51
51
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
52
52
|
"@molecule/app-i18n": "1.2.2",
|
|
53
53
|
"@molecule/app-icons": "1.0.4",
|
|
54
|
-
"@molecule/app-ui": "1.
|
|
55
|
-
"@molecule/app-ui-vue": "1.1
|
|
56
|
-
"@molecule/app-vue": "3.
|
|
54
|
+
"@molecule/app-ui": "1.5.0",
|
|
55
|
+
"@molecule/app-ui-vue": "1.2.1",
|
|
56
|
+
"@molecule/app-vue": "3.9.0",
|
|
57
57
|
"@types/node": "26.6.5",
|
|
58
58
|
"jsdom": "30.1.3",
|
|
59
59
|
"typescript": "6.0.3",
|