@molecule/app-search-ui-solid 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 +419 -4
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,11 +1,426 @@
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.262Z
7
+ -->
8
+
1
9
  # @molecule/app-search-ui-solid
2
10
 
3
- Solid 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
+ Solid search UI for `@molecule/app-client-search`.
12
+
13
+ The Solid 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-solid`:
16
+ {@link SearchBox} (the field, its clear button and shortcut cap, a help icon
17
+ whose tooltip shows the search syntax, an `afterField` slot 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
+ ```tsx
34
+ import { Link, useTranslation } from '@molecule/app-solid'
35
+ import { useSearchSession } from '@molecule/app-client-search-solid'
36
+ import { SearchBox, SearchResults } from '@molecule/app-search-ui-solid'
37
+ import type { SearchResultLinkProps } from '@molecule/app-search-ui-solid'
38
+
39
+ function Catalog() {
40
+ const { t } = useTranslation()
41
+ const session = useSearchSession({
42
+ docs: packages,
43
+ options: PACKAGE_INDEX_OPTIONS,
44
+ rememberKey: 'catalog.search',
45
+ onOpen: (p) => navigate(`/packages/${p.name}`),
46
+ })
47
+ const renderLink = (p: SearchResultLinkProps) => (
48
+ <Link
49
+ to={p.href}
50
+ state={p.state}
51
+ className={p.className}
52
+ onClick={p.onClick}
53
+ data-mol-id={p['data-mol-id']}
54
+ >
55
+ {p.children}
56
+ </Link>
57
+ )
58
+ return (
59
+ <>
60
+ <SearchBox
61
+ value={session.query()}
62
+ onChange={session.setQuery}
63
+ onKeyDown={session.onKeyDown}
64
+ inputRef={session.inputRef}
65
+ placeholder={t('catalog.search', undefined, { defaultValue: 'Search packages' })}
66
+ count={session.hits().length}
67
+ filters={session.parsed().filters}
68
+ onRemoveFilter={session.removeFilter}
69
+ onClear={session.clear}
70
+ examples={['category:auth', 'type:bond']}
71
+ />
72
+ <SearchResults
73
+ hits={session.hits()}
74
+ view={(p) => ({
75
+ href: `/packages/${p.name}`,
76
+ title: `@molecule/${p.name}`,
77
+ description: p.description,
78
+ meta: [p.type, p.category],
79
+ mono: true,
80
+ })}
81
+ activeIndex={session.activeIndex()}
82
+ onActivate={session.setActiveIndex}
83
+ onOpen={session.open}
84
+ onPrefetch={session.prefetch}
85
+ renderLink={renderLink}
86
+ emptyText={t('catalog.empty', undefined, { defaultValue: 'Nothing matches' })}
87
+ />
88
+ </>
89
+ )
90
+ }
91
+ ```
92
+
93
+ (`searchPlaceholder` and `nothingMatches` are the app's own translated strings.)
94
+
95
+ ## Type
96
+
97
+ `feature`
98
+
99
+ ## Installation
100
+
101
+ ```bash
102
+ npm install @molecule/app-search-ui-solid @molecule/app-client-search @molecule/app-client-search-solid @molecule/app-solid @molecule/app-ui @molecule/app-ui-solid solid-js
103
+ ```
104
+
105
+ ## API
106
+
107
+ ### Interfaces
108
+
109
+ #### `KbdProps`
110
+
111
+ Props accepted by {@link Kbd}.
112
+
113
+ ```typescript
114
+ interface KbdProps {
115
+ /** The key or keys shown, e.g. `/`, `↵`, `esc`. */
116
+ children?: JSX.Element
117
+ /** Extra classes composed onto the cap. */
118
+ className?: string
119
+ }
120
+ ```
121
+
122
+ #### `HighlightProps`
123
+
124
+ Props for {@link Highlight}.
4
125
 
126
+ ```typescript
127
+ interface HighlightProps {
128
+ /** The text to show. */
129
+ text: string
130
+ /** The matched terms to mark (a hit's `terms`). */
131
+ terms: string[]
132
+ }
5
133
  ```
6
- npm install @molecule/app-search-ui-solid
134
+
135
+ #### `SearchBoxProps`
136
+
137
+ Props accepted by {@link SearchBox}.
138
+
139
+ ```typescript
140
+ interface SearchBoxProps {
141
+ /** The text. */
142
+ value: string
143
+ /** Called with the new text on every keystroke. */
144
+ onChange: (value: string) => void
145
+ /** Key handling for the input (arrows, Enter, Escape), usually a session's `onKeyDown`. */
146
+ onKeyDown?: (event: KeyboardEvent) => void
147
+ /** A ref to the input, so a shortcut can focus it. */
148
+ inputRef?: { current: HTMLInputElement | null }
149
+ /** Placeholder, already translated. Also the accessible name unless `label` is given. */
150
+ placeholder: string
151
+ /** Accessible name for the input, already translated. Defaults to `placeholder`. */
152
+ label?: string
153
+ /** How many hits the current text has. Omit to show no count. */
154
+ count?: number
155
+ /** Active `field:value` filters, shown as removable chips. */
156
+ filters?: ClientSearchFilter[]
157
+ /** Removes the i-th filter. */
158
+ onRemoveFilter?: (index: number) => void
159
+ /** Clears the text. Shown as an × while there is text. */
160
+ onClear?: () => void
161
+ /**
162
+ * Example tokens for the search tips, e.g. `['category:auth', 'type:bond']`.
163
+ * Given, a help icon sits inside the field and shows the syntax on hover or
164
+ * focus. Omit for no help icon.
165
+ */
166
+ examples?: string[]
167
+ /** The key that focuses the box, shown as a cap while it is empty. `null` hides it. Defaults to `/`. */
168
+ shortcut?: string | null
169
+ /** Focus the input on mount. */
170
+ autoFocus?: boolean
171
+ /**
172
+ * Rendered directly under the field, before the status row (chips and
173
+ * count), so a consumer can put its own controls — tabs, a scope switch —
174
+ * right below the input.
175
+ */
176
+ afterField?: JSX.Element
177
+ /** `data-mol-id` prefix: `<molId>-input`, `-clear`, `-help`, `-filter`, `-count`. */
178
+ molId?: string
179
+ /** Extra classes composed onto the field. */
180
+ className?: string
181
+ }
182
+ ```
183
+
184
+ #### `SearchResultHit`
185
+
186
+ What the list needs from a hit. A session's hits already have this shape.
187
+
188
+ ```typescript
189
+ interface SearchResultHit<T> {
190
+ id: string
191
+ doc: T
192
+ /** The matched terms, marked in the title and description. */
193
+ terms: string[]
194
+ /** Found by meaning rather than by the words typed. */
195
+ related?: boolean
196
+ }
197
+ ```
198
+
199
+ #### `SearchResultView`
200
+
201
+ How one hit renders.
202
+
203
+ ```typescript
204
+ interface SearchResultView {
205
+ /** Where the row goes. */
206
+ href: string
207
+ /** The row's title. */
208
+ title: string
209
+ /** Under the title, clamped to two lines. */
210
+ description?: string
211
+ /** Small facts after the title: type, category, source. */
212
+ meta?: string[]
213
+ /** Render the title in monospace (a package name). */
214
+ mono?: boolean
215
+ /** Opaque data handed to `renderLink` (router state). */
216
+ state?: unknown
217
+ }
7
218
  ```
8
219
 
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.
220
+ #### `SearchResultLinkProps`
221
+
222
+ Props the row's link gets; `renderLink` turns them into an element.
223
+
224
+ ```typescript
225
+ interface SearchResultLinkProps {
226
+ href: string
227
+ className: string
228
+ children: JSX.Element
229
+ onClick: (event: MouseEvent) => void
230
+ state?: unknown
231
+ 'data-mol-id': string
232
+ }
233
+ ```
234
+
235
+ #### `SearchResultsProps`
236
+
237
+ Props for {@link SearchResults}.
238
+
239
+ ```typescript
240
+ interface SearchResultsProps<T> {
241
+ hits: SearchResultHit<T>[]
242
+ /** How a hit renders. */
243
+ view: (doc: T) => SearchResultView
244
+ /** The keyboard- or pointer-active row, or `-1`. */
245
+ activeIndex: number
246
+ /** The pointer moved onto a row. */
247
+ onActivate?: (index: number) => void
248
+ /** A row was chosen (a plain click, or Enter elsewhere). Navigation is the caller's. */
249
+ onOpen: (doc: T) => void
250
+ /** The person is about to open a row (hover, focus, touch): warm its page. */
251
+ onPrefetch?: (doc: T) => void
252
+ /**
253
+ * Renders the row's link. Defaults to a plain `<a>`; pass a router link to
254
+ * keep navigation client-side (spread `props` onto it; `state` is optional).
255
+ */
256
+ renderLink?: (props: SearchResultLinkProps) => JSX.Element
257
+ /** Something at the row's end (an action button). */
258
+ action?: (doc: T) => JSX.Element
259
+ /** Shown when there are no hits. */
260
+ emptyText: string
261
+ /** `data-mol-id` prefix: `<molId>-results`, `-hit`, `-link`, `-related`, `-empty`, `-active`. */
262
+ molId?: string
263
+ /** Extra classes composed onto the list. */
264
+ className?: string
265
+ }
266
+ ```
267
+
268
+ #### `QuickSearchDialogProps`
269
+
270
+ Props for {@link QuickSearchDialog}.
271
+
272
+ ```typescript
273
+ interface QuickSearchDialogProps<T extends ClientSearchDocument> {
274
+ /** Whether the dialog is open. Rendered only while open. */
275
+ open: boolean
276
+ /** Close it (Escape with nothing typed, the overlay, or after opening a hit). */
277
+ onClose: () => void
278
+ /** The search session (from `useSearchSession`), created with `syncUrl: false` and `onEscape: onClose`. */
279
+ session: SearchSession<T>
280
+ /** How a hit renders. */
281
+ view: (doc: T) => SearchResultView
282
+ /** Placeholder for the box, already translated. */
283
+ placeholder: string
284
+ /** Example tokens for the tips line. */
285
+ examples?: string[]
286
+ /** Shown while the text matches nothing, already translated. */
287
+ emptyText: string
288
+ /** Shown before anything is typed, already translated. Defaults to the empty text. */
289
+ idleText?: string
290
+ /** Renders each row's link (a router link keeps navigation client-side). */
291
+ renderLink?: (props: SearchResultLinkProps) => JSX.Element
292
+ /**
293
+ * The dialog's accessible name, already translated (like `placeholder`, it
294
+ * names nothing visible). Defaults to `t('searchUi.dialogLabel')`
295
+ * ("Search"); the field's placeholder already names the field.
296
+ */
297
+ label?: string
298
+ /** `data-mol-id` prefix. Defaults to `quick-search`. */
299
+ molId?: string
300
+ }
301
+ ```
302
+
303
+ ### Functions
304
+
305
+ #### `Highlight(props)`
306
+
307
+ Text with the matched terms marked: each term is marked where it starts a
308
+ word, case-insensitively, through the ClassMap's `resultMark`.
309
+
310
+ ```typescript
311
+ function Highlight(props: HighlightProps): JSX.Element
312
+ ```
313
+
314
+ - `props` — See {@link HighlightProps}.
315
+
316
+ **Returns:** The text with `<mark>` around each match.
317
+
318
+ #### `Kbd(props)`
319
+
320
+ A key cap, for shortcut hints (`/` to focus, `↵` to open). The cap shows a
321
+ key name, not prose (a physical key such as `esc` reads the same in every
322
+ language), so it carries HTML's own `translate="no"`.
323
+
324
+ ```typescript
325
+ function Kbd(props: KbdProps): JSX.Element
326
+ ```
327
+
328
+ - `props` — See {@link KbdProps}.
329
+
330
+ **Returns:** A `<kbd>` styled by the ClassMap.
331
+
332
+ #### `QuickSearchDialog(props)`
333
+
334
+ A search dialog for `mod+k`: the box on top with focus, the hits below in
335
+ a scrolling pane, and the key hints in the footer. Before anything is
336
+ typed the pane shows `idleText` rather than a browse list. Enter opens the active
337
+ hit through the session (which closes the dialog by the caller's `onOpen`).
338
+ The dialog is named for screen readers through `label` (or the translated
339
+ "Search" default).
340
+
341
+ ```typescript
342
+ function QuickSearchDialog<T extends ClientSearchDocument>(
343
+ props: QuickSearchDialogProps<T>,
344
+ ): JSX.Element
345
+ ```
346
+
347
+ - `props` — See {@link QuickSearchDialogProps}.
348
+
349
+ **Returns:** The dialog, or nothing while closed.
350
+
351
+ #### `SearchBox(props)`
352
+
353
+ A search field: a leading icon, the input, a help icon that shows the
354
+ syntax on hover, an × to clear, and the shortcut cap; under it, whatever
355
+ `afterField` holds, then the active filters as removable chips and the
356
+ hit count. The field stays mounted, and its text with it, across searches.
357
+
358
+ ```typescript
359
+ function SearchBox(props: SearchBoxProps): JSX.Element
360
+ ```
361
+
362
+ - `props` — See {@link SearchBoxProps}.
363
+
364
+ **Returns:** The field and its status row.
365
+
366
+ #### `SearchResults(props)`
367
+
368
+ The ranked hits: title and description with the matched terms marked, the
369
+ meta line, hover making a row active and warming its page. The whole row is
370
+ the link, so the list is a plain list of links (no listbox roles: an
371
+ option's children are presentational and would hide the row's link and
372
+ action); the active row is marked with `aria-current` on its `<li>` and
373
+ announced through a polite, visually hidden status region after the list.
374
+
375
+ React keys each row by the hit's `id` value, so a re-passed or re-ordered
376
+ array keeps the rendered rows per id. Solid's `For` keys by reference, so
377
+ the rows are keyed through stable per-id records: the record for an id is
378
+ created once and reused, while the row's content reads the CURRENT hit for
379
+ that id reactively.
380
+
381
+ ```typescript
382
+ function SearchResults<T>(props: SearchResultsProps<T>): JSX.Element
383
+ ```
384
+
385
+ - `props` — See {@link SearchResultsProps}.
386
+
387
+ **Returns:** The list, or the empty state.
388
+
389
+ ## Injection Notes
390
+
391
+ ### Requirements
392
+
393
+ Peer dependencies:
394
+
395
+ - `@molecule/app-client-search` ^1.0.0
396
+ - `@molecule/app-client-search-solid` ^1.0.0
397
+ - `@molecule/app-solid` ^3.5.0
398
+ - `@molecule/app-ui` ^1.3.3
399
+ - `@molecule/app-ui-solid` ^1.1.0
400
+ - `solid-js` ^1.8.0
401
+
402
+ ### Runtime Dependencies
403
+
404
+ - `@molecule/app-client-search`
405
+ - `@molecule/app-client-search-solid`
406
+ - `@molecule/app-solid`
407
+ - `@molecule/app-ui`
408
+ - `@molecule/app-ui-solid`
409
+ - `solid-js`
410
+
411
+ - **Pass a router link through `renderLink`**, or every row is a full page
412
+ load: the list renders a plain `<a>` by default because it does not know
413
+ your router. A plain click calls `onOpen` (which the session turns into
414
+ navigation); a modified click is left to the browser so "open in new tab" works.
415
+ - The box does not own the text: bind `value`/`onChange` to a session (or
416
+ any state) and it stays mounted, with its text, across searches. Do not
417
+ remount it per search.
418
+ - `placeholder`, `emptyText` and the like are already-translated strings
419
+ from the app; the package translates only its own chrome ("Clear
420
+ search", "{{count}} results", "Search tips") through `@molecule/app-locales-search-ui`.
421
+ - The quick dialog needs a session created with `syncUrl: false` and
422
+ `onEscape: onClose`; the page's own session keeps the URL.
423
+
424
+ ## Translations
10
425
 
11
- License: Apache-2.0
426
+ 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-solid",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Solid 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-solid",
6
6
  "type": "module",
@@ -55,13 +55,13 @@
55
55
  "devDependencies": {
56
56
  "@molecule/app-client-search": "1.0.4",
57
57
  "@molecule/app-client-search-minisearch": "1.0.4",
58
- "@molecule/app-client-search-solid": "1.0.0",
58
+ "@molecule/app-client-search-solid": "1.1.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-solid": "3.7.2",
63
- "@molecule/app-ui": "1.4.0",
64
- "@molecule/app-ui-solid": "1.1.5",
62
+ "@molecule/app-solid": "3.9.0",
63
+ "@molecule/app-ui": "1.5.0",
64
+ "@molecule/app-ui-solid": "1.2.1",
65
65
  "@types/node": "26.6.5",
66
66
  "jsdom": "30.1.3",
67
67
  "solid-js": "1.9.17",