@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.
Files changed (2) hide show
  1. package/README.md +228 -4
  2. 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
- npm install @molecule/app-search-autocomplete-vue
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
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
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
- License: Apache-2.0
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": "0.0.1-stage",
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.4.0",
55
- "@molecule/app-ui-vue": "1.1.5",
56
- "@molecule/app-vue": "3.7.2",
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",