@molecule/app-search-autocomplete-angular 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 +423 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,430 @@
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:12.604Z
7
+ -->
8
+
1
9
  # @molecule/app-search-autocomplete-angular
2
10
 
3
- Search input with typeahead suggestion popover
11
+ Search input with a typeahead suggestion popover.
12
+
13
+ Exports `<SearchAutocomplete>` (an attribute-selector component:
14
+ `div[mol-search-autocomplete]`, whose host is React's root `<div>`) and the
15
+ `SuggestionItem<T>` type (`{ id, label, meta?, data? }`). Two data modes —
16
+ pass ONE of: `onSearch(query)` (async fetch, debounced; default 200 ms) or
17
+ `suggestions` (caller-controlled list). Other props: `value` / `onChange`
18
+ (controlled input), `onSelect(item)`, `placeholder?` (defaults to the
19
+ translated `search.placeholder`), `debounceMs?`, `minChars?` (default 1),
20
+ `className?`.
21
+
22
+ Angular counterpart of `@molecule/app-search-autocomplete-react`: the same
23
+ exports, the same props (React names) and the same 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
30
+
31
+ ```ts
32
+ import { Component, signal } from '@angular/core'
33
+ import { SearchAutocomplete, type SuggestionItem } from '@molecule/app-search-autocomplete-angular'
34
+
35
+ @Component({
36
+ selector: 'app-user-search',
37
+ standalone: true,
38
+ imports: [SearchAutocomplete],
39
+ template: `
40
+ <div
41
+ mol-search-autocomplete
42
+ [value]="query()"
43
+ [onChange]="setQuery"
44
+ [onSearch]="fetchUsers"
45
+ [onSelect]="pick"
46
+ placeholder="Search users…"
47
+ ></div>
48
+ `,
49
+ })
50
+ export class UserSearch {
51
+ readonly query = signal('')
52
+ readonly setQuery = (next: string): void => this.query.set(next)
53
+ readonly fetchUsers = (q: string): Promise<SuggestionItem<{ id: string }>[]> =>
54
+ fetch(`/api/users?q=${encodeURIComponent(q)}`).then((r) => r.json())
55
+ readonly pick = (item: SuggestionItem<{ id: string }>): void => console.log(item.data?.id)
56
+ }
57
+ ```
58
+
59
+ ## Type
4
60
 
61
+ `feature`
62
+
63
+ ## Installation
64
+
65
+ ```bash
66
+ npm install @molecule/app-search-autocomplete-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular
5
67
  ```
6
- npm install @molecule/app-search-autocomplete-angular
68
+
69
+ ## API
70
+
71
+ ### Interfaces
72
+
73
+ #### `SuggestionItem`
74
+
75
+ A single suggestion entry returned by `onSearch` or passed via `suggestions`.
76
+
77
+ ```typescript
78
+ interface SuggestionItem<T = unknown> {
79
+ id: string
80
+ /** Display label: text, or a template rendering any node (`TemplateRef`). */
81
+ label: string | TemplateRef<unknown>
82
+ /** Optional secondary line / category: text, or a template rendering any node. */
83
+ meta?: string | TemplateRef<unknown>
84
+ /** Original payload for the selection callback. */
85
+ data?: T
86
+ }
87
+ ```
88
+
89
+ #### `SearchAutocompleteProps`
90
+
91
+ Props accepted by the {@link SearchAutocomplete} component.
92
+
93
+ ```typescript
94
+ interface SearchAutocompleteProps<T = unknown> {
95
+ /** Current input value. */
96
+ value: string
97
+ /** Called whenever the input changes (an input: pass a function, as React does). */
98
+ onChange: (value: string) => void
99
+ /** Async search function — receives the query, returns suggestions. */
100
+ onSearch?: (query: string) => Promise<SuggestionItem<T>[]> | SuggestionItem<T>[]
101
+ /** Optional pre-computed suggestion list (when caller controls fetching). */
102
+ suggestions?: SuggestionItem<T>[]
103
+ /** Called when the user picks a suggestion. */
104
+ onSelect: (item: SuggestionItem<T>) => void
105
+ /** Placeholder. */
106
+ placeholder?: string
107
+ /**
108
+ * Accessible name for the input, rendered as `aria-label`. Defaults to the
109
+ * translated `search.aria.label`: a placeholder is not a label, so an input
110
+ * named only by its placeholder (let alone an empty one) is nameless for
111
+ * assistive technology.
112
+ */
113
+ ariaLabel?: string
114
+ /** Debounce ms for `onSearch`. Defaults to 200. */
115
+ debounceMs?: number
116
+ /** Min chars before suggestions appear. Defaults to 1. */
117
+ minChars?: number
118
+ /** Extra classes on the wrapper. */
119
+ className?: string
120
+ }
7
121
  ```
8
122
 
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.
123
+ ### Classes
124
+
125
+ #### `SearchAutocomplete`
126
+
127
+ SearchAutocomplete component.
128
+
129
+ Search input with a typeahead suggestions popover. The host IS React's root
130
+ `<div>` (`div[mol-search-autocomplete]`), carrying React's class list; the
131
+ input surface reproduces `@molecule/app-ui-angular`'s `Input` DOM (the
132
+ wrapper, the inner row and the native `input`) so the combobox attributes
133
+ land on the input itself, exactly where React spreads them.
134
+
135
+ ```typescript
136
+ @Component({
137
+ selector: 'div[mol-search-autocomplete]',
138
+ standalone: true,
139
+ imports: [NgTemplateOutlet],
140
+ inputs: [
141
+ 'value',
142
+ 'onChange',
143
+ 'onSearch',
144
+ 'suggestions',
145
+ 'onSelect',
146
+ 'placeholder',
147
+ 'ariaLabel',
148
+ 'debounceMs',
149
+ 'minChars',
150
+ 'className',
151
+ ],
152
+ host: {
153
+ '[class]': 'classes()',
154
+ },
155
+ // prettier-ignore
156
+ template: `<div [class]="cm().inputWrapper"><div [class]="cm().inputInner"><input #inputEl type="search" [attr.id]="inputId" [attr.value]="value" [attr.placeholder]="placeholderText()" aria-invalid="false" [class]="inputClasses()" role="combobox" [attr.aria-label]="ariaLabelText()" aria-autocomplete="list" [attr.aria-expanded]="isExpanded() ? 'true' : 'false'" [attr.aria-controls]="listId" [attr.aria-activedescendant]="activeDescendant()" (input)="handleInput($event)" (focusin)="handleFocus()" (keydown)="handleKeydown($event)" /></div></div>@if (isExpanded()) {<ul role="listbox" [attr.id]="listId" [class]="listClasses()" [attr.style]="listStyle">@for (suggestion of list(); track suggestion.id) {<li [attr.id]="optionId($index)" role="option" [attr.aria-selected]="$index === active() ? 'true' : 'false'" tabindex="-1" data-mol-id="search-autocomplete-option" (mouseenter)="onOptionEnter($index)" (mousedown)="onOptionDown($event, suggestion)" [class]="optionClasses($index)"><div [class]="labelClasses()">@if (isTemplate(suggestion.label)) {<ng-container [ngTemplateOutlet]="asTemplate(suggestion.label)"></ng-container>}@else {{{ textOf(suggestion.label) }}}</div>@if (suggestion.meta) {<div [class]="metaClasses()">@if (isTemplate(suggestion.meta)) {<ng-container [ngTemplateOutlet]="asTemplate(suggestion.meta)"></ng-container>}@else {{{ textOf(suggestion.meta) }}}</div>}</li>}</ul>}`,
157
+ })
158
+ export class SearchAutocomplete implements OnInit, OnChanges, OnDestroy {
159
+ /** Current input value. */
160
+ value = ''
161
+ onChange?: (value: string) => void
162
+ onSearch?: (query: string) => Promise<SuggestionItem[]> | SuggestionItem[]
163
+ suggestions?: SuggestionItem[]
164
+ onSelect?: (item: SuggestionItem) => void
165
+ placeholder?: string
166
+ ariaLabel?: string
167
+ debounceMs?: number
168
+ minChars?: number
169
+ /** Extra classes on the wrapper. */
170
+ className?: string
171
+
172
+ @ViewChild('inputEl') private inputEl?: ElementRef<HTMLInputElement>
173
+
174
+ private readonly i18n = useTranslation()
175
+
176
+ private readonly cdr = inject(ChangeDetectorRef)
177
+ private readonly host = inject(ElementRef<HTMLElement>)
178
+
179
+ private readonly internal = signal<SuggestionItem[]>([])
180
+ private readonly open = signal(false)
181
+ private readonly activeIndex = signal(-1)
182
+ private request = 0
183
+ /** The pending debounce timer. */
184
+ private timer: ReturnType<typeof setTimeout> | undefined
185
+ private readonly baseId = `mol-search-autocomplete-${nextGeneratedId++}`
186
+
187
+ readonly listId = `${this.baseId}-listbox`
188
+
189
+ readonly listStyle = LIST_STYLE
190
+
191
+ ngOnInit(): void {
192
+ document.addEventListener('mousedown', this.onDoc)
193
+ }
194
+
195
+ ngOnChanges(changes: SimpleChanges): void {
196
+ if ('value' in changes) this.activeIndex.set(-1)
197
+ if (
198
+ 'value' in changes ||
199
+ 'onSearch' in changes ||
200
+ 'debounceMs' in changes ||
201
+ 'minChars' in changes
202
+ )
203
+ this.scheduleSearch()
204
+ }
205
+
206
+ ngOnDestroy(): void {
207
+ document.removeEventListener('mousedown', this.onDoc)
208
+ clearTimeout(this.timer)
209
+ }
210
+
211
+ /** The current class map. */
212
+ cm(): UIClassMap {
213
+ return getClassMap()
214
+ }
215
+
216
+ classes(): string {
217
+ return this.cm().cn(this.cm().position('relative'), this.className)
218
+ }
219
+
220
+ inputClasses(): string {
221
+ return this.cm().input({ error: false, size: 'md', align: undefined })
222
+ }
223
+
224
+ /** The listbox's class list. */
225
+ listClasses(): string {
226
+ return this.cm().cn(this.cm().stack(0), this.cm().sp('p', 1))
227
+ }
228
+
229
+ labelClasses(): string {
230
+ return this.cm().fontWeight('medium')
231
+ }
232
+
233
+ metaClasses(): string {
234
+ return this.cm().textSize('xs')
235
+ }
236
+
237
+ optionClasses(index: number): string {
238
+ return this.cm().cn(
239
+ this.cm().sp('px', 2),
240
+ this.cm().sp('py', 2),
241
+ this.cm().textSize('sm'),
242
+ this.cm().cursorPointer,
243
+ index === this.active() && this.cm().surfaceSecondary,
244
+ )
245
+ }
246
+
247
+ get inputId(): string {
248
+ return `${this.baseId}-input`
249
+ }
250
+
251
+ optionId(index: number): string {
252
+ return `${this.baseId}-option-${index}`
253
+ }
254
+
255
+ placeholderText(): string {
256
+ return this.placeholder ?? this.i18n.t('search.placeholder', {}, { defaultValue: 'Search…' })
257
+ }
258
+
259
+ ariaLabelText(): string {
260
+ return this.ariaLabel ?? this.i18n.t('search.aria.label', undefined, { defaultValue: 'Search' })
261
+ }
262
+
263
+ list(): SuggestionItem[] {
264
+ return this.suggestions ?? this.internal()
265
+ }
266
+
267
+ isExpanded(): boolean {
268
+ return this.open() && this.list().length > 0
269
+ }
270
+
271
+ active(): number {
272
+ const index = this.activeIndex()
273
+ return index < this.list().length ? index : -1
274
+ }
275
+
276
+ activeDescendant(): string | null {
277
+ return this.isExpanded() && this.active() >= 0 ? this.optionId(this.active()) : null
278
+ }
279
+
280
+ isTemplate(value: unknown): value is TemplateRef<unknown> {
281
+ return isTemplate(value)
282
+ }
283
+
284
+ asTemplate(value: unknown): TemplateRef<unknown> {
285
+ return value as TemplateRef<unknown>
286
+ }
287
+
288
+ textOf(value: unknown): string {
289
+ return textOf(value)
290
+ }
291
+
292
+ private debounce(): number {
293
+ return this.debounceMs ?? 200
294
+ }
295
+
296
+ private threshold(): number {
297
+ return this.minChars ?? 1
298
+ }
299
+
300
+ private scheduleSearch(): void {
301
+ clearTimeout(this.timer)
302
+ const search = this.onSearch
303
+ const query = this.value
304
+ if (!search || query.length < this.threshold()) {
305
+ this.internal.set([])
306
+ return
307
+ }
308
+ this.timer = setTimeout(() => {
309
+ const token = ++this.request
310
+ Promise.resolve(search(query))
311
+ .then((result) => {
312
+ if (token === this.request) this.internal.set(result)
313
+ this.cdr.markForCheck()
314
+ })
315
+ .catch((_error) => {
316
+ if (token === this.request) this.internal.set([])
317
+ this.cdr.markForCheck()
318
+ })
319
+ }, this.debounce())
320
+ }
321
+
322
+ handleInput(event: Event): void {
323
+ this.onChange?.((event.target as HTMLInputElement).value)
324
+ this.open.set(true)
325
+ const input = this.inputEl?.nativeElement
326
+ if (input && input.value !== String(this.value)) input.value = String(this.value)
327
+ }
328
+
329
+ handleFocus(): void {
330
+ if (this.value.length >= this.threshold()) this.open.set(true)
331
+ }
332
+
333
+ handleKeydown(event: KeyboardEvent): void {
334
+ const current = this.list()
335
+ if (event.key === 'ArrowDown') {
336
+ event.preventDefault()
337
+ if (!this.open()) {
338
+ if (current.length > 0) this.open.set(true)
339
+ return
340
+ }
341
+ if (current.length === 0) return
342
+ this.activeIndex.update((index) => (index + 1) % current.length)
343
+ } else if (event.key === 'ArrowUp') {
344
+ event.preventDefault()
345
+ if (!this.open()) {
346
+ if (current.length > 0) this.open.set(true)
347
+ return
348
+ }
349
+ if (current.length === 0) return
350
+ this.activeIndex.update((index) => (index <= 0 ? current.length - 1 : index - 1))
351
+ } else if (event.key === 'Enter') {
352
+ const index = this.active()
353
+ if (this.isExpanded() && index >= 0) {
354
+ event.preventDefault()
355
+ this.select(current[index] as SuggestionItem)
356
+ }
357
+ } else if (event.key === 'Escape') {
358
+ if (this.open()) {
359
+ event.preventDefault()
360
+ this.open.set(false)
361
+ this.activeIndex.set(-1)
362
+ }
363
+ }
364
+ }
365
+
366
+ onOptionEnter(index: number): void {
367
+ this.activeIndex.set(index)
368
+ }
369
+
370
+ onOptionDown(event: MouseEvent, suggestion: SuggestionItem): void {
371
+ event.preventDefault()
372
+ this.select(suggestion)
373
+ }
374
+
375
+ private select(item: SuggestionItem): void {
376
+ this.onSelect?.(item)
377
+ this.open.set(false)
378
+ this.activeIndex.set(-1)
379
+ }
380
+
381
+ private readonly onDoc = (event: MouseEvent): void => {
382
+ if (!this.open()) return
383
+ if (this.host.nativeElement.contains(event.target as Node)) return
384
+ this.open.set(false)
385
+ this.activeIndex.set(-1)
386
+ this.cdr.markForCheck()
387
+ }
388
+ }
389
+ ```
390
+
391
+ _(Member comments are shortened to their first sentence, and the 51 longest are left out to fit; the full declaration is in `node_modules/@molecule/app-search-autocomplete-angular/dist/search-autocomplete.component.d.ts`.)_
392
+
393
+ ## Injection Notes
394
+
395
+ ### Requirements
396
+
397
+ Peer dependencies:
398
+
399
+ - `@angular/common` ^22.0.0
400
+ - `@angular/core` ^22.0.0
401
+ - `@angular/platform-browser` ^22.0.0
402
+ - `@molecule/app-angular` ^3.5.0
403
+ - `@molecule/app-ui` ^1.0.1
404
+ - `@molecule/app-ui-angular` ^1.1.0
405
+
406
+ ### Runtime Dependencies
407
+
408
+ - `@angular/common`
409
+ - `@angular/core`
410
+ - `@angular/platform-browser`
411
+ - `@molecule/app-angular`
412
+ - `@molecule/app-ui`
413
+ - `@molecule/app-ui-angular`
414
+
415
+ - Throws unless provided the binding's molecule providers (`@molecule/app-angular`)
416
+ with a bonded ClassMap and i18n provider.
417
+ - Full keyboard support: it's an ARIA combobox — ArrowDown/ArrowUp move the
418
+ highlight (opening the popover), Enter selects the highlighted option, and
419
+ Escape closes. `aria-activedescendant` tracks the active `role="option"`.
420
+ - Stale-response safe: out-of-order `onSearch` responses are dropped (each
421
+ request carries a token; only the latest applies), so a slow earlier fetch
422
+ can't overwrite fresher results. `onSearch` needs no cancellation of its own.
423
+ - The popover surface uses `var(--color-surface)` with a WHITE fallback
424
+ and black-alpha borders — define `--color-surface` (dark themes) or the
425
+ dropdown stays light.
426
+ - Default placeholder translations: `@molecule/app-locales-search-autocomplete`.
427
+
428
+ ## Translations
10
429
 
11
- License: Apache-2.0
430
+ 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-angular",
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-angular",
6
6
  "type": "module",
@@ -55,12 +55,12 @@
55
55
  "@angular/compiler-cli": "22.2.3",
56
56
  "@angular/core": "22.2.3",
57
57
  "@angular/platform-browser": "22.2.3",
58
- "@molecule/app-angular": "3.7.2",
58
+ "@molecule/app-angular": "3.9.0",
59
59
  "@molecule/app-framework-conformance": "0.0.0",
60
60
  "@molecule/app-i18n": "1.2.2",
61
61
  "@molecule/app-icons": "1.0.4",
62
- "@molecule/app-ui": "1.4.0",
63
- "@molecule/app-ui-angular": "1.2.1",
62
+ "@molecule/app-ui": "1.5.0",
63
+ "@molecule/app-ui-angular": "1.3.1",
64
64
  "@types/node": "26.6.5",
65
65
  "jsdom": "30.1.3",
66
66
  "rxjs": "7.8.2",