@molecule/app-search-autocomplete-svelte 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 +154 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,161 @@
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.998Z
7
+ -->
8
+
1
9
  # @molecule/app-search-autocomplete-svelte
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
+ Svelte 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
+ ```svelte
32
+ <script lang="ts">
33
+ import { SearchAutocomplete } from '@molecule/app-search-autocomplete-svelte'
34
+ import type { SuggestionItem } from '@molecule/app-search-autocomplete-svelte'
35
+
36
+ let {
37
+ fetchUsers,
38
+ onPick,
39
+ }: {
40
+ fetchUsers: (q: string) => Promise<SuggestionItem<{ id: string }>[]>
41
+ onPick: (id: string) => void
42
+ } = $props()
43
+
44
+ let query = $state('')
45
+ </script>
46
+
47
+ <SearchAutocomplete
48
+ value={query}
49
+ onChange={(next) => (query = next)}
50
+ onSearch={fetchUsers}
51
+ onSelect={(item) => (item.data ? onPick(item.data.id) : undefined)}
52
+ placeholder="Search users…"
53
+ />
5
54
  ```
6
- npm install @molecule/app-search-autocomplete-svelte
55
+
56
+ ## Type
57
+
58
+ `feature`
59
+
60
+ ## Installation
61
+
62
+ ```bash
63
+ npm install @molecule/app-search-autocomplete-svelte @molecule/app-svelte @molecule/app-ui @molecule/app-ui-svelte svelte
7
64
  ```
8
65
 
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.
66
+ ## API
67
+
68
+ ### Interfaces
69
+
70
+ #### `SuggestionItem`
71
+
72
+ A single suggestion entry returned by `onSearch` or passed via `suggestions`.
73
+
74
+ ```typescript
75
+ interface SuggestionItem<T = unknown> {
76
+ id: string
77
+ /** Display label: text, or a snippet rendering any node. */
78
+ label: string | Snippet
79
+ /** Optional secondary line / category: text, or a snippet rendering any node. */
80
+ meta?: string | Snippet
81
+ /** Original payload for the selection callback. */
82
+ data?: T
83
+ }
84
+ ```
85
+
86
+ #### `SearchAutocompleteProps`
87
+
88
+ Props accepted by the {@link SearchAutocomplete} component.
89
+
90
+ ```typescript
91
+ interface SearchAutocompleteProps<T = unknown> {
92
+ /** Current input value. */
93
+ value: string
94
+ /** Called whenever the input changes. */
95
+ onChange: (value: string) => void
96
+ /** Async search function — receives the query, returns suggestions. */
97
+ onSearch?: (query: string) => Promise<SuggestionItem<T>[]> | SuggestionItem<T>[]
98
+ /** Optional pre-computed suggestion list (when caller controls fetching). */
99
+ suggestions?: SuggestionItem<T>[]
100
+ /** Called when the user picks a suggestion. */
101
+ onSelect: (item: SuggestionItem<T>) => void
102
+ /** Placeholder. */
103
+ placeholder?: string
104
+ /**
105
+ * Accessible name for the input, rendered as `aria-label`. Defaults to the
106
+ * translated `search.aria.label`: a placeholder is not a label, so an input
107
+ * named only by its placeholder (let alone an empty one) is nameless for
108
+ * assistive technology.
109
+ */
110
+ ariaLabel?: string
111
+ /** Debounce ms for `onSearch`. Defaults to 200. */
112
+ debounceMs?: number
113
+ /** Min chars before suggestions appear. Defaults to 1. */
114
+ minChars?: number
115
+ /** Extra classes on the wrapper. */
116
+ className?: string
117
+ }
118
+ ```
119
+
120
+ ### Constants
121
+
122
+ #### `SearchAutocomplete`
123
+
124
+ ```typescript
125
+ const SearchAutocomplete: LegacyComponentType
126
+ ```
127
+
128
+ ## Injection Notes
129
+
130
+ ### Requirements
131
+
132
+ Peer dependencies:
133
+
134
+ - `@molecule/app-svelte` ^3.5.0
135
+ - `@molecule/app-ui` ^1.0.1
136
+ - `@molecule/app-ui-svelte` ^1.1.0
137
+ - `svelte` ^5.0.0
138
+
139
+ ### Runtime Dependencies
140
+
141
+ - `@molecule/app-svelte`
142
+ - `@molecule/app-ui`
143
+ - `@molecule/app-ui-svelte`
144
+ - `svelte`
145
+
146
+ - Throws unless rendered under the Svelte binding's molecule context
147
+ (from `@molecule/app-svelte`) with a bonded ClassMap.
148
+ - Full keyboard support: it's an ARIA combobox — ArrowDown/ArrowUp move the
149
+ highlight (opening the popover), Enter selects the highlighted option, and
150
+ Escape closes. `aria-activedescendant` tracks the active `role="option"`.
151
+ - Stale-response safe: out-of-order `onSearch` responses are dropped (each
152
+ request carries a token; only the latest applies), so a slow earlier fetch
153
+ can't overwrite fresher results. `onSearch` needs no cancellation of its own.
154
+ - The popover surface uses `var(--color-surface)` with a WHITE fallback
155
+ and black-alpha borders — define `--color-surface` (dark themes) or the
156
+ dropdown stays light.
157
+ - Default placeholder translations: `@molecule/app-locales-search-autocomplete`.
158
+
159
+ ## Translations
10
160
 
11
- License: Apache-2.0
161
+ 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-svelte",
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-svelte",
6
6
  "type": "module",
@@ -57,9 +57,9 @@
57
57
  "@molecule/app-framework-conformance": "0.0.0",
58
58
  "@molecule/app-i18n": "1.2.2",
59
59
  "@molecule/app-icons": "1.0.4",
60
- "@molecule/app-svelte": "3.7.2",
61
- "@molecule/app-ui": "1.4.0",
62
- "@molecule/app-ui-svelte": "1.1.7",
60
+ "@molecule/app-svelte": "3.9.0",
61
+ "@molecule/app-ui": "1.5.0",
62
+ "@molecule/app-ui-svelte": "1.2.1",
63
63
  "@sveltejs/package": "3.0.2",
64
64
  "@sveltejs/vite-plugin-svelte": "7.1.2",
65
65
  "@types/node": "26.6.5",