@molecule/app-search-ui-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 +359 -4
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,11 +1,366 @@
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:14.597Z
7
+ -->
8
+
1
9
  # @molecule/app-search-ui-svelte
2
10
 
3
- Svelte search UI for @molecule/app-client-search — a search box with filter chips and tips, a ranked results list with matched terms marked, and a quick-search dialog; styled through the ClassMap
11
+ Svelte search UI for `@molecule/app-client-search`.
12
+
13
+ The Svelte counterpart of `@molecule/app-search-ui-react` — the same props
14
+ (React names) and the same DOM for the same input. Three pieces that fit a
15
+ `useSearchSession` from `@molecule/app-client-search-svelte`:
16
+ {@link SearchBox} (the field, its clear button and shortcut cap, a help icon
17
+ whose tooltip shows the search syntax, an `afterField` snippet for the
18
+ consumer's own tabs, the active filter chips and the hit count),
19
+ {@link SearchResults} (ranked rows with the matched terms marked, hover
20
+ prefetch, an optional action per row; the keyboard-active row is marked with
21
+ `aria-current` and announced through a polite status region), and
22
+ {@link QuickSearchDialog} (both in a `mod+k` dialog named for screen readers
23
+ by its `label`, "Search" by default). Every class comes from
24
+ the ClassMap's search tokens (`searchField`, `resultList`, …), so a UI bond
25
+ restyles all of it at once.
26
+
27
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
28
+ > It is written to be read by coding agents as much as by people, and is generated from this
29
+ > package's source — edit `src/index.ts` JSDoc, not this file.
30
+
31
+ ## Quick Start
32
+
33
+ ```svelte
34
+ <script lang="ts">
35
+ import { Link, useTranslation } from '@molecule/app-svelte'
36
+ import { useSearchSession } from '@molecule/app-client-search-svelte'
37
+ import { SearchBox, SearchResults } from '@molecule/app-search-ui-svelte'
38
+ import type { SearchResultLinkProps } from '@molecule/app-search-ui-svelte'
39
+
40
+ const { t } = useTranslation()
41
+ const session = useSearchSession({
42
+ docs: packages,
43
+ options: PACKAGE_INDEX_OPTIONS,
44
+ rememberKey: 'catalog.search',
45
+ onOpen: (p) => goto(`/packages/${p.name}`),
46
+ })
47
+
48
+ {#snippet renderLink(p: SearchResultLinkProps)}
49
+ <Link to={p.href} state={p.state} className={p.className} onClick={p.onClick} data-mol-id={p['data-mol-id']}>
50
+ <!-- the row's body -->
51
+ </Link>
52
+ {/snippet}
53
+ </script>
54
+
55
+ <SearchBox
56
+ value={session.query}
57
+ onChange={session.setQuery}
58
+ onKeyDown={session.onKeyDown}
59
+ inputRef={session.inputRef}
60
+ placeholder={t('catalog.search', undefined, { defaultValue: 'Search packages' })}
61
+ count={session.hits.length}
62
+ filters={session.parsed.filters}
63
+ onRemoveFilter={session.removeFilter}
64
+ onClear={session.clear}
65
+ examples={['category:auth', 'type:bond']}
66
+ />
67
+ <SearchResults
68
+ hits={session.hits}
69
+ view={(p) => ({
70
+ href: `/packages/${p.name}`,
71
+ title: `@molecule/${p.name}`,
72
+ description: p.description,
73
+ meta: [p.type, p.category],
74
+ mono: true,
75
+ })}
76
+ activeIndex={session.activeIndex}
77
+ onActivate={session.setActiveIndex}
78
+ onOpen={session.open}
79
+ onPrefetch={session.prefetch}
80
+ {renderLink}
81
+ emptyText={t('catalog.empty', undefined, { defaultValue: 'Nothing matches' })}
82
+ />
83
+ ```
84
+
85
+ (`searchPlaceholder` and `nothingMatches` are the app's own translated strings.)
86
+
87
+ ## Type
88
+
89
+ `feature`
4
90
 
91
+ ## Installation
92
+
93
+ ```bash
94
+ npm install @molecule/app-search-ui-svelte @molecule/app-client-search @molecule/app-client-search-svelte @molecule/app-svelte @molecule/app-ui @molecule/app-ui-svelte svelte
5
95
  ```
6
- npm install @molecule/app-search-ui-svelte
96
+
97
+ ## API
98
+
99
+ ### Interfaces
100
+
101
+ #### `KbdProps`
102
+
103
+ Props accepted by {@link Kbd}.
104
+
105
+ ```typescript
106
+ interface KbdProps {
107
+ /** The key or keys shown, e.g. `/`, `↵`, `esc`. */
108
+ children?: Snippet
109
+ /** Extra classes composed onto the cap. */
110
+ className?: string
111
+ }
7
112
  ```
8
113
 
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.
114
+ #### `HighlightProps`
115
+
116
+ Props for {@link Highlight}.
117
+
118
+ ```typescript
119
+ interface HighlightProps {
120
+ /** The text to show. */
121
+ text: string
122
+ /** The matched terms to mark (a hit's `terms`). */
123
+ terms: string[]
124
+ }
125
+ ```
126
+
127
+ #### `SearchBoxProps`
128
+
129
+ Props accepted by {@link SearchBox}.
130
+
131
+ ```typescript
132
+ interface SearchBoxProps {
133
+ /** The text. */
134
+ value: string
135
+ /** Called with the new text on every keystroke. */
136
+ onChange: (value: string) => void
137
+ /** Key handling for the input (arrows, Enter, Escape), usually a session's `onKeyDown`. */
138
+ onKeyDown?: (event: KeyboardEvent) => void
139
+ /** A ref to the input, so a shortcut can focus it. */
140
+ inputRef?: { current: HTMLInputElement | null }
141
+ /** Placeholder, already translated. Also the accessible name unless `label` is given. */
142
+ placeholder: string
143
+ /** Accessible name for the input, already translated. Defaults to `placeholder`. */
144
+ label?: string
145
+ /** How many hits the current text has. Omit to show no count. */
146
+ count?: number
147
+ /** Active `field:value` filters, shown as removable chips. */
148
+ filters?: ClientSearchFilter[]
149
+ /** Removes the i-th filter. */
150
+ onRemoveFilter?: (index: number) => void
151
+ /** Clears the text. Shown as an × while there is text. */
152
+ onClear?: () => void
153
+ /**
154
+ * Example tokens for the search tips, e.g. `['category:auth', 'type:bond']`.
155
+ * Given, a help icon sits inside the field and shows the syntax on hover or
156
+ * focus. Omit for no help icon.
157
+ */
158
+ examples?: string[]
159
+ /** The key that focuses the box, shown as a cap while it is empty. `null` hides it. Defaults to `/`. */
160
+ shortcut?: string | null
161
+ /** Focus the input on mount. */
162
+ autoFocus?: boolean
163
+ /**
164
+ * Rendered directly under the field, before the status row (chips and
165
+ * count), so a consumer can put its own controls — tabs, a scope switch —
166
+ * right below the input.
167
+ */
168
+ afterField?: Snippet
169
+ /** `data-mol-id` prefix: `<molId>-input`, `-clear`, `-help`, `-filter`, `-count`. */
170
+ molId?: string
171
+ /** Extra classes composed onto the field. */
172
+ className?: string
173
+ }
174
+ ```
175
+
176
+ #### `SearchResultHit`
177
+
178
+ What the list needs from a hit. A session's hits already have this shape.
179
+
180
+ ```typescript
181
+ interface SearchResultHit<T> {
182
+ id: string
183
+ doc: T
184
+ /** The matched terms, marked in the title and description. */
185
+ terms: string[]
186
+ /** Found by meaning rather than by the words typed. */
187
+ related?: boolean
188
+ }
189
+ ```
190
+
191
+ #### `SearchResultView`
192
+
193
+ How one hit renders.
194
+
195
+ ```typescript
196
+ interface SearchResultView {
197
+ /** Where the row goes. */
198
+ href: string
199
+ /** The row's title. */
200
+ title: string
201
+ /** Under the title, clamped to two lines. */
202
+ description?: string
203
+ /** Small facts after the title: type, category, source. */
204
+ meta?: string[]
205
+ /** Render the title in monospace (a package name). */
206
+ mono?: boolean
207
+ /** Opaque data handed to `renderLink` (router state). */
208
+ state?: unknown
209
+ }
210
+ ```
211
+
212
+ #### `SearchResultLinkProps`
213
+
214
+ Props the row's link gets; `renderLink` turns them into markup.
215
+
216
+ ```typescript
217
+ interface SearchResultLinkProps {
218
+ href: string
219
+ className: string
220
+ children: Snippet
221
+ onClick: (event: MouseEvent) => void
222
+ state?: unknown
223
+ 'data-mol-id': string
224
+ }
225
+ ```
226
+
227
+ #### `SearchResultsProps`
228
+
229
+ Props for {@link SearchResults}.
230
+
231
+ ```typescript
232
+ interface SearchResultsProps<T extends ClientSearchDocument> {
233
+ hits: SearchResultHit<T>[]
234
+ /** How a hit renders. */
235
+ view: (doc: T) => SearchResultView
236
+ /** The keyboard- or pointer-active row, or `-1`. */
237
+ activeIndex: number
238
+ /** The pointer moved onto a row. */
239
+ onActivate?: (index: number) => void
240
+ /** A row was chosen (a plain click, or Enter elsewhere). Navigation is the caller's. */
241
+ onOpen: (doc: T) => void
242
+ /** The person is about to open a row (hover, focus, touch): warm its page. */
243
+ onPrefetch?: (doc: T) => void
244
+ /**
245
+ * Renders the row's link. Defaults to a plain `<a>`; pass a router link to
246
+ * keep navigation client-side (spread `props` onto it; `state` is optional).
247
+ */
248
+ renderLink?: Snippet<[SearchResultLinkProps]>
249
+ /** Something at the row's end (an action button). */
250
+ action?: Snippet<[T]>
251
+ /** Shown when there are no hits. */
252
+ emptyText: string
253
+ /** `data-mol-id` prefix: `<molId>-results`, `-hit`, `-link`, `-related`, `-empty`, `-active`. */
254
+ molId?: string
255
+ /** Extra classes composed onto the list. */
256
+ className?: string
257
+ }
258
+ ```
259
+
260
+ #### `QuickSearchDialogProps`
261
+
262
+ Props for {@link QuickSearchDialog}.
263
+
264
+ ```typescript
265
+ interface QuickSearchDialogProps<T extends ClientSearchDocument> {
266
+ /** Whether the dialog is open. Rendered only while open. */
267
+ open: boolean
268
+ /** Close it (Escape with nothing typed, the overlay, or after opening a hit). */
269
+ onClose: () => void
270
+ /** The search session (from `useSearchSession`), created with `syncUrl: false` and `onEscape: onClose`. */
271
+ session: SearchSession<T>
272
+ /** How a hit renders. */
273
+ view: (doc: T) => SearchResultView
274
+ /** Placeholder for the box, already translated. */
275
+ placeholder: string
276
+ /** Example tokens for the tips line. */
277
+ examples?: string[]
278
+ /** Shown while the text matches nothing, already translated. */
279
+ emptyText: string
280
+ /** Shown before anything is typed, already translated. Defaults to the empty text. */
281
+ idleText?: string
282
+ /** Renders each row's link (a router link keeps navigation client-side). */
283
+ renderLink?: Snippet<[SearchResultLinkProps]>
284
+ /**
285
+ * The dialog's accessible name, already translated (like `placeholder`, it
286
+ * names nothing visible). Defaults to `t('searchUi.dialogLabel')`
287
+ * ("Search"); the field's placeholder already names the field.
288
+ */
289
+ label?: string
290
+ /** `data-mol-id` prefix. Defaults to `quick-search`. */
291
+ molId?: string
292
+ }
293
+ ```
294
+
295
+ ### Constants
296
+
297
+ #### `Highlight`
298
+
299
+ ```typescript
300
+ const Highlight: LegacyComponentType
301
+ ```
302
+
303
+ #### `Kbd`
304
+
305
+ ```typescript
306
+ const Kbd: LegacyComponentType
307
+ ```
308
+
309
+ #### `QuickSearchDialog`
310
+
311
+ ```typescript
312
+ const QuickSearchDialog: LegacyComponentType
313
+ ```
314
+
315
+ #### `SearchBox`
316
+
317
+ ```typescript
318
+ const SearchBox: LegacyComponentType
319
+ ```
320
+
321
+ #### `SearchResults`
322
+
323
+ ```typescript
324
+ const SearchResults: LegacyComponentType
325
+ ```
326
+
327
+ ## Injection Notes
328
+
329
+ ### Requirements
330
+
331
+ Peer dependencies:
332
+
333
+ - `@molecule/app-client-search` ^1.0.0
334
+ - `@molecule/app-client-search-svelte` ^1.0.0
335
+ - `@molecule/app-svelte` ^3.5.0
336
+ - `@molecule/app-ui` ^1.3.3
337
+ - `@molecule/app-ui-svelte` ^1.1.0
338
+ - `svelte` ^5.0.0
339
+
340
+ ### Runtime Dependencies
341
+
342
+ - `@molecule/app-client-search`
343
+ - `@molecule/app-client-search-svelte`
344
+ - `@molecule/app-svelte`
345
+ - `@molecule/app-ui`
346
+ - `@molecule/app-ui-svelte`
347
+ - `svelte`
348
+
349
+ - **Pass a router link through `renderLink`**, or every row is a full page
350
+ load: the list renders a plain `<a>` by default because it does not know
351
+ your router. A plain click calls `onOpen` (which the session turns into
352
+ navigation); a modified click is left to the browser so "open in new tab" works.
353
+ - The box does not own the text: bind `value`/`onChange` to a session (or
354
+ any state) and it stays mounted, with its text, across searches. Do not
355
+ remount it per search.
356
+ - `placeholder`, `emptyText` and the like are already-translated strings
357
+ from the app; the package translates only its own chrome ("Clear
358
+ search", "{{count}} results", "Search tips") through `@molecule/app-locales-search-ui`.
359
+ - The quick dialog needs a session created with `syncUrl: false` and
360
+ `onEscape: onClose`; the page's own session keeps the URL.
361
+ - React render props (`renderLink`, `action`) and node props (`afterField`,
362
+ `Kbd`'s `children`) are snippets.
363
+
364
+ ## Translations
10
365
 
11
- License: Apache-2.0
366
+ Translation strings are provided by `@molecule/app-locales-search-ui`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-search-ui-svelte",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Svelte search UI for @molecule/app-client-search — a search box with filter chips and tips, a ranked results list with matched terms marked, and a quick-search dialog; styled through the ClassMap",
5
5
  "homepage": "https://www.molecule.dev/packages/app-search-ui-svelte",
6
6
  "type": "module",
@@ -61,13 +61,13 @@
61
61
  "devDependencies": {
62
62
  "@molecule/app-client-search": "1.0.4",
63
63
  "@molecule/app-client-search-minisearch": "1.0.4",
64
- "@molecule/app-client-search-svelte": "1.0.0",
64
+ "@molecule/app-client-search-svelte": "1.1.0",
65
65
  "@molecule/app-framework-conformance": "0.0.0",
66
66
  "@molecule/app-i18n": "1.2.2",
67
67
  "@molecule/app-icons": "1.0.4",
68
- "@molecule/app-svelte": "3.7.2",
69
- "@molecule/app-ui": "1.4.0",
70
- "@molecule/app-ui-svelte": "1.1.7",
68
+ "@molecule/app-svelte": "3.9.0",
69
+ "@molecule/app-ui": "1.5.0",
70
+ "@molecule/app-ui-svelte": "1.2.1",
71
71
  "@sveltejs/package": "3.0.2",
72
72
  "@sveltejs/vite-plugin-svelte": "7.1.2",
73
73
  "@types/node": "26.6.5",