@molecule/app-query-solid 0.0.1-stage → 1.2.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 +97 -8
- package/dist/index.d.ts +12 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +12 -6
- package/dist/index.js.map +1 -1
- package/dist/list-query.d.ts +56 -0
- package/dist/list-query.d.ts.map +1 -0
- package/dist/list-query.js +33 -0
- package/dist/list-query.js.map +1 -0
- package/dist/query-content.d.ts +6 -0
- package/dist/query-content.d.ts.map +1 -1
- package/dist/query-content.jsx +22 -11
- package/dist/query-content.jsx.map +1 -1
- package/dist/types.d.ts +7 -3
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
|
3
3
|
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
4
|
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
5
|
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
-
Generated: 2026-11-
|
|
6
|
+
Generated: 2026-11-14T22:00:52.564Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/app-query-solid
|
|
@@ -289,18 +289,19 @@ function InvoicePage(props: { id: string }) {
|
|
|
289
289
|
</p>
|
|
290
290
|
)}
|
|
291
291
|
>
|
|
292
|
-
{(invoice) => <FlagButton invoice={invoice} viewer={viewer()} />}
|
|
292
|
+
{(invoice) => <FlagButton invoice={invoice()} viewer={viewer()} />}
|
|
293
293
|
</QueryContent>
|
|
294
294
|
)
|
|
295
295
|
}
|
|
296
296
|
|
|
297
297
|
function FlagButton(props: { invoice: Invoice; viewer: string }) {
|
|
298
298
|
const { t } = useTranslation()
|
|
299
|
-
|
|
299
|
+
// An accessor, so each saved or refreshed invoice syncs into the same controller.
|
|
300
|
+
const flag = useOptimisticValue(() => ({
|
|
300
301
|
value: props.invoice.flagged,
|
|
301
|
-
commit: async (on) =>
|
|
302
|
+
commit: async (on: boolean) =>
|
|
302
303
|
(await invoices.toggle(props.viewer, props.invoice.id, 'flag', on)).flagged,
|
|
303
|
-
})
|
|
304
|
+
}))
|
|
304
305
|
return (
|
|
305
306
|
<button type="button" aria-pressed={flag.value()} onClick={() => flag.update((on) => !on)}>
|
|
306
307
|
{flag.value()
|
|
@@ -474,6 +475,39 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
|
|
|
474
475
|
}
|
|
475
476
|
```
|
|
476
477
|
|
|
478
|
+
#### `ListQueryRoute`
|
|
479
|
+
|
|
480
|
+
The list route a list query reads: `useListRoute` from `@molecule/app-solid` returns these
|
|
481
|
+
accessors (and more), so its result is passed as it is.
|
|
482
|
+
|
|
483
|
+
```typescript
|
|
484
|
+
interface ListQueryRoute<Filter extends string = string> {
|
|
485
|
+
/** False while a protected view waits for auth, is signed out, or is unavailable. */
|
|
486
|
+
readonly canLoad: Accessor<boolean>
|
|
487
|
+
/** The current URL filter values. */
|
|
488
|
+
readonly filters: Accessor<Readonly<Record<Filter, string | undefined>>>
|
|
489
|
+
/** The configured items per page. */
|
|
490
|
+
readonly pageSize: Accessor<number>
|
|
491
|
+
/** The zero-indexed item offset for the API request. */
|
|
492
|
+
readonly offset: Accessor<number>
|
|
493
|
+
}
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
#### `ListQueryState`
|
|
497
|
+
|
|
498
|
+
The route's current values, as `read` receives them.
|
|
499
|
+
|
|
500
|
+
```typescript
|
|
501
|
+
interface ListQueryState<Filter extends string = string> {
|
|
502
|
+
/** The current URL filter values. */
|
|
503
|
+
readonly filters: Readonly<Record<Filter, string | undefined>>
|
|
504
|
+
/** The configured items per page. */
|
|
505
|
+
readonly pageSize: number
|
|
506
|
+
/** The zero-indexed item offset for the API request. */
|
|
507
|
+
readonly offset: number
|
|
508
|
+
}
|
|
509
|
+
```
|
|
510
|
+
|
|
477
511
|
#### `UseQueryResult`
|
|
478
512
|
|
|
479
513
|
A mounted query's state and its explicit cache and refresh actions. The state
|
|
@@ -512,8 +546,12 @@ A loaded document owns its controls; absent documents expose only status content
|
|
|
512
546
|
interface QueryContentProps<T> {
|
|
513
547
|
/** State from useQuery, or any compatible query observer. */
|
|
514
548
|
query: Pick<QueryState<T>, 'data' | 'status' | 'error'>
|
|
515
|
-
/**
|
|
516
|
-
|
|
549
|
+
/**
|
|
550
|
+
* Mounted only with a real document, including false, zero and an empty list. Runs once
|
|
551
|
+
* per loaded stretch with the document as an accessor (Solid's `<Show>` idiom): a new
|
|
552
|
+
* document reaches the same mounted content, so read it where it is used (`data()`).
|
|
553
|
+
*/
|
|
554
|
+
children: (data: Accessor<NonNullable<T>>) => JSX.Element
|
|
517
555
|
/** Initial idle/loading content. Render a status node, never a fake item or action. */
|
|
518
556
|
pending?: JSX.Element
|
|
519
557
|
/** Content for a loaded null record. Null is distinct from an unfinished request. */
|
|
@@ -535,6 +573,26 @@ interface IntentPrefetchProps {
|
|
|
535
573
|
}
|
|
536
574
|
```
|
|
537
575
|
|
|
576
|
+
### Types
|
|
577
|
+
|
|
578
|
+
#### `ListQuerySource`
|
|
579
|
+
|
|
580
|
+
A plain value or an accessor: each input {@link useListQuery} reads reactively.
|
|
581
|
+
|
|
582
|
+
```typescript
|
|
583
|
+
type ListQuerySource<T> = T | Accessor<T>
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
#### `ListQueryInputs`
|
|
587
|
+
|
|
588
|
+
Each input of {@link useListQuery} as a {@link ListQuerySource}.
|
|
589
|
+
|
|
590
|
+
```typescript
|
|
591
|
+
type ListQueryInputs<Values> = {
|
|
592
|
+
readonly [Key in keyof Values]: ListQuerySource<Values[Key]>
|
|
593
|
+
}
|
|
594
|
+
```
|
|
595
|
+
|
|
538
596
|
### Functions
|
|
539
597
|
|
|
540
598
|
#### `prefetchQuery(options)`
|
|
@@ -584,6 +642,28 @@ function createQueryResource<T, Create = Partial<T>, Update = Partial<T>>(
|
|
|
584
642
|
|
|
585
643
|
**Returns:** List and detail query options, and create, update, remove, toggle and refresh.
|
|
586
644
|
|
|
645
|
+
#### `useListQuery(route, inputs, read)`
|
|
646
|
+
|
|
647
|
+
Observe the page a URL list route points at. `read` builds the query from the current value of
|
|
648
|
+
each input (the signed-in `viewer`, request params, a parent record's id) and the route's
|
|
649
|
+
filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
|
|
650
|
+
null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
|
|
651
|
+
the same observer to the new page.
|
|
652
|
+
|
|
653
|
+
```typescript
|
|
654
|
+
function useListQuery<T, Values extends { viewer: string | null }, Filter extends string = string>(
|
|
655
|
+
route: ListQueryRoute<Filter>,
|
|
656
|
+
inputs: ListQueryInputs<Values>,
|
|
657
|
+
read: (values: Values & { viewer: string }, list: ListQueryState<Filter>) => QueryOptions<T>,
|
|
658
|
+
): UseQueryResult<T>
|
|
659
|
+
```
|
|
660
|
+
|
|
661
|
+
- `route` — The list route, usually `useListRoute(...)` from `@molecule/app-solid`.
|
|
662
|
+
- `inputs` — Plain values or accessors; `viewer` is the signed-in user's id, 'anonymous', or null while auth is restoring.
|
|
663
|
+
- `read` — Builds the page's query options, e.g. a generated `articlesPage(...)`.
|
|
664
|
+
|
|
665
|
+
**Returns:** The query state, as {@link useQuery} returns it.
|
|
666
|
+
|
|
587
667
|
#### `QueryContent(props)`
|
|
588
668
|
|
|
589
669
|
The loaded-data branch receives a non-null document. Pending, failed initial reads and
|
|
@@ -592,6 +672,12 @@ Cached data remains mounted during refresh, including a failed refresh. Status f
|
|
|
592
672
|
belong outside the list or record container rendered by `children`, and so does a refresh
|
|
593
673
|
line; the default fallbacks render nothing.
|
|
594
674
|
|
|
675
|
+
`children` runs ONCE per loaded stretch and receives the document as an accessor (Solid's
|
|
676
|
+
`<Show>` idiom), so a new document — a cache publication, a refresh, another key's record —
|
|
677
|
+
reaches the SAME mounted content, the way React re-renders the same components with it:
|
|
678
|
+
their local state (an optimistic toggle's pending save, an open menu) survives. Read the
|
|
679
|
+
accessor where the value is used: `{(invoice) => <FlagButton invoice={invoice()} />}`.
|
|
680
|
+
|
|
595
681
|
```typescript
|
|
596
682
|
function QueryContent<T>(props: QueryContentProps<T>): JSX.Element
|
|
597
683
|
```
|
|
@@ -768,6 +854,9 @@ Peer dependencies:
|
|
|
768
854
|
Render resource-dependent lists and controls through {@link QueryContent}. Its child function
|
|
769
855
|
receives only loaded, non-null data; loading and error content never mount item actions.
|
|
770
856
|
It renders cached content during refresh and treats an empty list, false and zero as data.
|
|
857
|
+
The child runs once per loaded stretch and receives the document as an ACCESSOR (Solid's
|
|
858
|
+
`<Show>` idiom), so a saved or refreshed document reaches the same mounted controls, as React
|
|
859
|
+
re-renders them: call it where the value is read (`record()`), never once into a constant.
|
|
771
860
|
Put the list, or the record's own container (its card, header or profile block), inside the
|
|
772
861
|
child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
|
|
773
862
|
a reader that finds the container and reads its paragraph must read the record, not "Loading…".
|
|
@@ -779,7 +868,7 @@ a reader that finds the container and reads its paragraph must read the record,
|
|
|
779
868
|
missing={<p>{missingLabel}</p>}
|
|
780
869
|
error={() => <p role="alert">{errorLabel}</p>}
|
|
781
870
|
>
|
|
782
|
-
{(record) => <RecordActions record={record} />}
|
|
871
|
+
{(record) => <RecordActions record={record()} />}
|
|
783
872
|
</QueryContent>
|
|
784
873
|
```
|
|
785
874
|
|
package/dist/index.d.ts
CHANGED
|
@@ -271,17 +271,19 @@
|
|
|
271
271
|
* missing={<p role="alert">{t('invoice.missing', undefined, { defaultValue: 'Invoice not found.' })}</p>}
|
|
272
272
|
* error={() => <p role="alert">{t('invoice.failed', undefined, { defaultValue: 'Unable to load invoice.' })}</p>}
|
|
273
273
|
* >
|
|
274
|
-
* {(invoice) => <FlagButton invoice={invoice} viewer={viewer()} />}
|
|
274
|
+
* {(invoice) => <FlagButton invoice={invoice()} viewer={viewer()} />}
|
|
275
275
|
* </QueryContent>
|
|
276
276
|
* )
|
|
277
277
|
* }
|
|
278
278
|
*
|
|
279
279
|
* function FlagButton(props: { invoice: Invoice; viewer: string }) {
|
|
280
280
|
* const { t } = useTranslation()
|
|
281
|
-
*
|
|
281
|
+
* // An accessor, so each saved or refreshed invoice syncs into the same controller.
|
|
282
|
+
* const flag = useOptimisticValue(() => ({
|
|
282
283
|
* value: props.invoice.flagged,
|
|
283
|
-
* commit: async (on) =>
|
|
284
|
-
*
|
|
284
|
+
* commit: async (on: boolean) =>
|
|
285
|
+
* (await invoices.toggle(props.viewer, props.invoice.id, 'flag', on)).flagged,
|
|
286
|
+
* }))
|
|
285
287
|
* return (
|
|
286
288
|
* <button type="button" aria-pressed={flag.value()} onClick={() => flag.update((on) => !on)}>
|
|
287
289
|
* {flag.value()
|
|
@@ -402,6 +404,9 @@
|
|
|
402
404
|
* Render resource-dependent lists and controls through {@link QueryContent}. Its child function
|
|
403
405
|
* receives only loaded, non-null data; loading and error content never mount item actions.
|
|
404
406
|
* It renders cached content during refresh and treats an empty list, false and zero as data.
|
|
407
|
+
* The child runs once per loaded stretch and receives the document as an ACCESSOR (Solid's
|
|
408
|
+
* `<Show>` idiom), so a saved or refreshed document reaches the same mounted controls, as React
|
|
409
|
+
* re-renders them: call it where the value is read (`record()`), never once into a constant.
|
|
405
410
|
* Put the list, or the record's own container (its card, header or profile block), inside the
|
|
406
411
|
* child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
|
|
407
412
|
* a reader that finds the container and reads its paragraph must read the record, not "Loading…".
|
|
@@ -409,7 +414,7 @@
|
|
|
409
414
|
* ```tsx
|
|
410
415
|
* <QueryContent query={query} pending={<p role="status">{loadingLabel}</p>}
|
|
411
416
|
* missing={<p>{missingLabel}</p>} error={() => <p role="alert">{errorLabel}</p>}>
|
|
412
|
-
* {(record) => <RecordActions record={record} />}
|
|
417
|
+
* {(record) => <RecordActions record={record()} />}
|
|
413
418
|
* </QueryContent>
|
|
414
419
|
* ```
|
|
415
420
|
*
|
|
@@ -419,7 +424,8 @@
|
|
|
419
424
|
*
|
|
420
425
|
* @module
|
|
421
426
|
*/
|
|
422
|
-
export * from './query
|
|
427
|
+
export * from './list-query.js';
|
|
428
|
+
export * from './query-content.jsx';
|
|
423
429
|
export * from './resource.js';
|
|
424
430
|
export * from './types.js';
|
|
425
431
|
export * from './use-prefetch.js';
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyaG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -271,17 +271,19 @@
|
|
|
271
271
|
* missing={<p role="alert">{t('invoice.missing', undefined, { defaultValue: 'Invoice not found.' })}</p>}
|
|
272
272
|
* error={() => <p role="alert">{t('invoice.failed', undefined, { defaultValue: 'Unable to load invoice.' })}</p>}
|
|
273
273
|
* >
|
|
274
|
-
* {(invoice) => <FlagButton invoice={invoice} viewer={viewer()} />}
|
|
274
|
+
* {(invoice) => <FlagButton invoice={invoice()} viewer={viewer()} />}
|
|
275
275
|
* </QueryContent>
|
|
276
276
|
* )
|
|
277
277
|
* }
|
|
278
278
|
*
|
|
279
279
|
* function FlagButton(props: { invoice: Invoice; viewer: string }) {
|
|
280
280
|
* const { t } = useTranslation()
|
|
281
|
-
*
|
|
281
|
+
* // An accessor, so each saved or refreshed invoice syncs into the same controller.
|
|
282
|
+
* const flag = useOptimisticValue(() => ({
|
|
282
283
|
* value: props.invoice.flagged,
|
|
283
|
-
* commit: async (on) =>
|
|
284
|
-
*
|
|
284
|
+
* commit: async (on: boolean) =>
|
|
285
|
+
* (await invoices.toggle(props.viewer, props.invoice.id, 'flag', on)).flagged,
|
|
286
|
+
* }))
|
|
285
287
|
* return (
|
|
286
288
|
* <button type="button" aria-pressed={flag.value()} onClick={() => flag.update((on) => !on)}>
|
|
287
289
|
* {flag.value()
|
|
@@ -402,6 +404,9 @@
|
|
|
402
404
|
* Render resource-dependent lists and controls through {@link QueryContent}. Its child function
|
|
403
405
|
* receives only loaded, non-null data; loading and error content never mount item actions.
|
|
404
406
|
* It renders cached content during refresh and treats an empty list, false and zero as data.
|
|
407
|
+
* The child runs once per loaded stretch and receives the document as an ACCESSOR (Solid's
|
|
408
|
+
* `<Show>` idiom), so a saved or refreshed document reaches the same mounted controls, as React
|
|
409
|
+
* re-renders them: call it where the value is read (`record()`), never once into a constant.
|
|
405
410
|
* Put the list, or the record's own container (its card, header or profile block), inside the
|
|
406
411
|
* child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
|
|
407
412
|
* a reader that finds the container and reads its paragraph must read the record, not "Loading…".
|
|
@@ -409,7 +414,7 @@
|
|
|
409
414
|
* ```tsx
|
|
410
415
|
* <QueryContent query={query} pending={<p role="status">{loadingLabel}</p>}
|
|
411
416
|
* missing={<p>{missingLabel}</p>} error={() => <p role="alert">{errorLabel}</p>}>
|
|
412
|
-
* {(record) => <RecordActions record={record} />}
|
|
417
|
+
* {(record) => <RecordActions record={record()} />}
|
|
413
418
|
* </QueryContent>
|
|
414
419
|
* ```
|
|
415
420
|
*
|
|
@@ -419,7 +424,8 @@
|
|
|
419
424
|
*
|
|
420
425
|
* @module
|
|
421
426
|
*/
|
|
422
|
-
export * from './query
|
|
427
|
+
export * from './list-query.js';
|
|
428
|
+
export * from './query-content.jsx';
|
|
423
429
|
export * from './resource.js';
|
|
424
430
|
export * from './types.js';
|
|
425
431
|
export * from './use-prefetch.js';
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyaG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `useListQuery`: one cached read driven by a URL list route.
|
|
3
|
+
*
|
|
4
|
+
* @module
|
|
5
|
+
*/
|
|
6
|
+
import type { Accessor } from 'solid-js';
|
|
7
|
+
import type { QueryOptions } from '@molecule/app-query';
|
|
8
|
+
import type { UseQueryResult } from './types.js';
|
|
9
|
+
/** A plain value or an accessor: each input {@link useListQuery} reads reactively. */
|
|
10
|
+
export type ListQuerySource<T> = T | Accessor<T>;
|
|
11
|
+
/** Each input of {@link useListQuery} as a {@link ListQuerySource}. */
|
|
12
|
+
export type ListQueryInputs<Values> = {
|
|
13
|
+
readonly [Key in keyof Values]: ListQuerySource<Values[Key]>;
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* The list route a list query reads: `useListRoute` from `@molecule/app-solid` returns these
|
|
17
|
+
* accessors (and more), so its result is passed as it is.
|
|
18
|
+
*/
|
|
19
|
+
export interface ListQueryRoute<Filter extends string = string> {
|
|
20
|
+
/** False while a protected view waits for auth, is signed out, or is unavailable. */
|
|
21
|
+
readonly canLoad: Accessor<boolean>;
|
|
22
|
+
/** The current URL filter values. */
|
|
23
|
+
readonly filters: Accessor<Readonly<Record<Filter, string | undefined>>>;
|
|
24
|
+
/** The configured items per page. */
|
|
25
|
+
readonly pageSize: Accessor<number>;
|
|
26
|
+
/** The zero-indexed item offset for the API request. */
|
|
27
|
+
readonly offset: Accessor<number>;
|
|
28
|
+
}
|
|
29
|
+
/** The route's current values, as `read` receives them. */
|
|
30
|
+
export interface ListQueryState<Filter extends string = string> {
|
|
31
|
+
/** The current URL filter values. */
|
|
32
|
+
readonly filters: Readonly<Record<Filter, string | undefined>>;
|
|
33
|
+
/** The configured items per page. */
|
|
34
|
+
readonly pageSize: number;
|
|
35
|
+
/** The zero-indexed item offset for the API request. */
|
|
36
|
+
readonly offset: number;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Observe the page a URL list route points at. `read` builds the query from the current value of
|
|
40
|
+
* each input (the signed-in `viewer`, request params, a parent record's id) and the route's
|
|
41
|
+
* filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
|
|
42
|
+
* null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
|
|
43
|
+
* the same observer to the new page.
|
|
44
|
+
*
|
|
45
|
+
* @param route - The list route, usually `useListRoute(...)` from `@molecule/app-solid`.
|
|
46
|
+
* @param inputs - Plain values or accessors; `viewer` is the signed-in user's id, 'anonymous',
|
|
47
|
+
* or null while auth is restoring.
|
|
48
|
+
* @param read - Builds the page's query options, e.g. a generated `articlesPage(...)`.
|
|
49
|
+
* @returns The query state, as {@link useQuery} returns it.
|
|
50
|
+
*/
|
|
51
|
+
export declare function useListQuery<T, Values extends {
|
|
52
|
+
viewer: string | null;
|
|
53
|
+
}, Filter extends string = string>(route: ListQueryRoute<Filter>, inputs: ListQueryInputs<Values>, read: (values: Values & {
|
|
54
|
+
viewer: string;
|
|
55
|
+
}, list: ListQueryState<Filter>) => QueryOptions<T>): UseQueryResult<T>;
|
|
56
|
+
//# sourceMappingURL=list-query.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"list-query.d.ts","sourceRoot":"","sources":["../src/list-query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD,sFAAsF;AACtF,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;AAEhD,uEAAuE;AACvE,MAAM,MAAM,eAAe,CAAC,MAAM,IAAI;IACpC,QAAQ,EAAE,GAAG,IAAI,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;CAC7D,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IAC5D,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IACnC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;IACxE,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACnC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;CAClC;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IAC5D,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC9D,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EACD,MAAM,SAAS;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACxC,MAAM,SAAS,MAAM,GAAG,MAAM,EAE9B,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,EAC7B,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,EAC/B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,GAC3F,cAAc,CAAC,CAAC,CAAC,CAYnB"}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { useQuery } from './use-query.js';
|
|
2
|
+
/**
|
|
3
|
+
* Reads a plain value or an accessor; inside the query's options accessor the read is tracked.
|
|
4
|
+
*
|
|
5
|
+
* @param source - The argument as the caller passed it.
|
|
6
|
+
* @returns Its current value.
|
|
7
|
+
*/
|
|
8
|
+
const access = (source) => typeof source === 'function' ? source() : source;
|
|
9
|
+
/**
|
|
10
|
+
* Observe the page a URL list route points at. `read` builds the query from the current value of
|
|
11
|
+
* each input (the signed-in `viewer`, request params, a parent record's id) and the route's
|
|
12
|
+
* filters, page size and offset. The query is disabled (`null`, no request) while `viewer` is
|
|
13
|
+
* null (auth is still being restored) or the route cannot load yet; a changed input or URL moves
|
|
14
|
+
* the same observer to the new page.
|
|
15
|
+
*
|
|
16
|
+
* @param route - The list route, usually `useListRoute(...)` from `@molecule/app-solid`.
|
|
17
|
+
* @param inputs - Plain values or accessors; `viewer` is the signed-in user's id, 'anonymous',
|
|
18
|
+
* or null while auth is restoring.
|
|
19
|
+
* @param read - Builds the page's query options, e.g. a generated `articlesPage(...)`.
|
|
20
|
+
* @returns The query state, as {@link useQuery} returns it.
|
|
21
|
+
*/
|
|
22
|
+
export function useListQuery(route, inputs, read) {
|
|
23
|
+
return useQuery(() => {
|
|
24
|
+
const values = {};
|
|
25
|
+
for (const key of Object.keys(inputs))
|
|
26
|
+
values[key] = access(inputs[key]);
|
|
27
|
+
const { viewer } = values;
|
|
28
|
+
if (viewer === null || !route.canLoad())
|
|
29
|
+
return null;
|
|
30
|
+
return read({ ...values, viewer }, { filters: route.filters(), pageSize: route.pageSize(), offset: route.offset() });
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
//# sourceMappingURL=list-query.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"list-query.js","sourceRoot":"","sources":["../src/list-query.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAmCzC;;;;;GAKG;AACH,MAAM,MAAM,GAAG,CAAI,MAA0B,EAAK,EAAE,CAClD,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAE,MAAsB,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;AAEnE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAK1B,KAA6B,EAC7B,MAA+B,EAC/B,IAA4F;IAE5F,OAAO,QAAQ,CAAI,GAAG,EAAE;QACtB,MAAM,MAAM,GAAoB,EAAE,CAAA;QAClC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAqB;YACvD,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAuB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QACzD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAgB,CAAA;QACnC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;YAAE,OAAO,IAAI,CAAA;QACpD,OAAO,IAAI,CACT,EAAE,GAAI,MAAiB,EAAE,MAAM,EAAE,EACjC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,CACjF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}
|
package/dist/query-content.d.ts
CHANGED
|
@@ -14,6 +14,12 @@ import type { QueryContentProps } from './types.js';
|
|
|
14
14
|
* belong outside the list or record container rendered by `children`, and so does a refresh
|
|
15
15
|
* line; the default fallbacks render nothing.
|
|
16
16
|
*
|
|
17
|
+
* `children` runs ONCE per loaded stretch and receives the document as an accessor (Solid's
|
|
18
|
+
* `<Show>` idiom), so a new document — a cache publication, a refresh, another key's record —
|
|
19
|
+
* reaches the SAME mounted content, the way React re-renders the same components with it:
|
|
20
|
+
* their local state (an optimistic toggle's pending save, an open menu) survives. Read the
|
|
21
|
+
* accessor where the value is used: `{(invoice) => <FlagButton invoice={invoice()} />}`.
|
|
22
|
+
*
|
|
17
23
|
* @param props - Query state, loaded content and optional status fallbacks.
|
|
18
24
|
* @returns Loaded content or the appropriate fallback, switching as the state changes.
|
|
19
25
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-content.d.ts","sourceRoot":"","sources":["../src/query-content.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAc,KAAK,GAAG,
|
|
1
|
+
{"version":3,"file":"query-content.d.ts","sourceRoot":"","sources":["../src/query-content.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAc,KAAK,GAAG,EAAQ,MAAM,UAAU,CAAA;AAErD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAqBxE"}
|
package/dist/query-content.jsx
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* and no styling, and renders exactly the chosen branch.
|
|
6
6
|
* @module
|
|
7
7
|
*/
|
|
8
|
-
import { createMemo } from 'solid-js';
|
|
8
|
+
import { createMemo, Show } from 'solid-js';
|
|
9
9
|
/**
|
|
10
10
|
* The loaded-data branch receives a non-null document. Pending, failed initial reads and
|
|
11
11
|
* missing records never mount that branch, so its actions cannot swallow an early click.
|
|
@@ -13,24 +13,35 @@ import { createMemo } from 'solid-js';
|
|
|
13
13
|
* belong outside the list or record container rendered by `children`, and so does a refresh
|
|
14
14
|
* line; the default fallbacks render nothing.
|
|
15
15
|
*
|
|
16
|
+
* `children` runs ONCE per loaded stretch and receives the document as an accessor (Solid's
|
|
17
|
+
* `<Show>` idiom), so a new document — a cache publication, a refresh, another key's record —
|
|
18
|
+
* reaches the SAME mounted content, the way React re-renders the same components with it:
|
|
19
|
+
* their local state (an optimistic toggle's pending save, an open menu) survives. Read the
|
|
20
|
+
* accessor where the value is used: `{(invoice) => <FlagButton invoice={invoice()} />}`.
|
|
21
|
+
*
|
|
16
22
|
* @param props - Query state, loaded content and optional status fallbacks.
|
|
17
23
|
* @returns Loaded content or the appropriate fallback, switching as the state changes.
|
|
18
24
|
*/
|
|
19
25
|
export function QueryContent(props) {
|
|
20
|
-
//
|
|
21
|
-
|
|
22
|
-
|
|
26
|
+
// Boxed, so a loaded `false`, `0` or `''` is still a truthy `when` for <Show>.
|
|
27
|
+
const loaded = createMemo(() => {
|
|
28
|
+
const data = props.query.data;
|
|
29
|
+
return data === undefined || data === null ? undefined : { data };
|
|
30
|
+
});
|
|
31
|
+
// Rendered only while nothing is loaded: a failed REFRESH of cached data never calls `error`.
|
|
32
|
+
const fallback = createMemo(() => {
|
|
23
33
|
const query = props.query;
|
|
24
34
|
const data = query.data;
|
|
25
|
-
if (data === undefined) {
|
|
26
|
-
return query.status === 'error' && props.error
|
|
27
|
-
? props.error(query.error)
|
|
28
|
-
: (props.pending ?? null);
|
|
29
|
-
}
|
|
30
35
|
if (data === null)
|
|
31
36
|
return props.missing ?? null;
|
|
32
|
-
|
|
37
|
+
if (data !== undefined)
|
|
38
|
+
return null;
|
|
39
|
+
return query.status === 'error' && props.error
|
|
40
|
+
? props.error(query.error)
|
|
41
|
+
: (props.pending ?? null);
|
|
33
42
|
});
|
|
34
|
-
return
|
|
43
|
+
return (<Show when={loaded()} fallback={fallback()}>
|
|
44
|
+
{(box) => props.children(() => box().data)}
|
|
45
|
+
</Show>);
|
|
35
46
|
}
|
|
36
47
|
//# sourceMappingURL=query-content.jsx.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-content.jsx","sourceRoot":"","sources":["../src/query-content.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAY,MAAM,UAAU,CAAA;
|
|
1
|
+
{"version":3,"file":"query-content.jsx","sourceRoot":"","sources":["../src/query-content.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAY,IAAI,EAAE,MAAM,UAAU,CAAA;AAIrD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAI,KAA2B;IACzD,+EAA+E;IAC/E,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE;QAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAA;QAC7B,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAA;IACnE,CAAC,CAAC,CAAA;IACF,8FAA8F;IAC9F,MAAM,QAAQ,GAAG,UAAU,CAAc,GAAG,EAAE;QAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;QACvB,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,OAAO,IAAI,IAAI,CAAA;QAC/C,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACnC,OAAO,KAAK,CAAC,MAAM,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK;YAC5C,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;YAC1B,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAA;IAC7B,CAAC,CAAC,CAAA;IACF,OAAO,CACL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC,CACzC;MAAA,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAC5C;IAAA,EAAE,IAAI,CAAC,CACR,CAAA;AACH,CAAC"}
|
package/dist/types.d.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* Solid `JSX`.
|
|
5
5
|
* @module
|
|
6
6
|
*/
|
|
7
|
-
import type { JSX } from 'solid-js';
|
|
7
|
+
import type { Accessor, JSX } from 'solid-js';
|
|
8
8
|
import type { QueryState } from '@molecule/app-query';
|
|
9
9
|
/**
|
|
10
10
|
* A mounted query's state and its explicit cache and refresh actions. The state
|
|
@@ -36,8 +36,12 @@ export interface UseQueryResult<T> extends QueryState<T> {
|
|
|
36
36
|
export interface QueryContentProps<T> {
|
|
37
37
|
/** State from useQuery, or any compatible query observer. */
|
|
38
38
|
query: Pick<QueryState<T>, 'data' | 'status' | 'error'>;
|
|
39
|
-
/**
|
|
40
|
-
|
|
39
|
+
/**
|
|
40
|
+
* Mounted only with a real document, including false, zero and an empty list. Runs once
|
|
41
|
+
* per loaded stretch with the document as an accessor (Solid's `<Show>` idiom): a new
|
|
42
|
+
* document reaches the same mounted content, so read it where it is used (`data()`).
|
|
43
|
+
*/
|
|
44
|
+
children: (data: Accessor<NonNullable<T>>) => JSX.Element;
|
|
41
45
|
/** Initial idle/loading content. Render a status node, never a fake item or action. */
|
|
42
46
|
pending?: JSX.Element;
|
|
43
47
|
/** Content for a loaded null record. Null is distinct from an unfinished request. */
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD;;;;;;;;;OASG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IAC1E;;;;;OAKG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;CACtC;AAED,wFAAwF;AACxF,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,6DAA6D;IAC7D,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAA;IACvD;;;;OAIG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,CAAA;IACzD,uFAAuF;IACvF,OAAO,CAAC,EAAE,GAAG,CAAC,OAAO,CAAA;IACrB,qFAAqF;IACrF,OAAO,CAAC,EAAE,GAAG,CAAC,OAAO,CAAA;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,GAAG,CAAC,OAAO,CAAA;CACxC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-query-solid",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "Solid hooks for @molecule/app-query — read a cached document synchronously, observe it, and prefetch on intent",
|
|
5
5
|
"homepage": "https://www.molecule.dev/packages/app-query-solid",
|
|
6
6
|
"type": "module",
|
|
@@ -55,9 +55,9 @@
|
|
|
55
55
|
"@molecule/app-query": "1.2.0",
|
|
56
56
|
"@molecule/app-query-memory": "1.0.5",
|
|
57
57
|
"@molecule/app-query-tanstack": "1.0.5",
|
|
58
|
-
"@molecule/app-solid": "3.
|
|
58
|
+
"@molecule/app-solid": "3.6.0",
|
|
59
59
|
"@molecule/app-ui": "1.3.11",
|
|
60
|
-
"@molecule/app-ui-solid": "1.1.
|
|
60
|
+
"@molecule/app-ui-solid": "1.1.2",
|
|
61
61
|
"@types/node": "26.6.5",
|
|
62
62
|
"jsdom": "30.1.3",
|
|
63
63
|
"solid-js": "1.9.17",
|