@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.
- package/README.md +359 -4
- 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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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": "
|
|
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.
|
|
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.
|
|
69
|
-
"@molecule/app-ui": "1.
|
|
70
|
-
"@molecule/app-ui-svelte": "1.1
|
|
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",
|