@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 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-14T15:07:26.678Z
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
- const flag = useOptimisticValue({
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
- /** Mounted only with a real document, including false, zero and an empty list. */
516
- children: (data: NonNullable<T>) => JSX.Element
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
- * const flag = useOptimisticValue({
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) => (await invoices.toggle(props.viewer, props.invoice.id, 'flag', on)).flagged,
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-content.js';
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';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoaG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
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
- * const flag = useOptimisticValue({
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) => (await invoices.toggle(props.viewer, props.invoice.id, 'flag', on)).flagged,
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-content.js';
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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoaG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
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"}
@@ -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,EAAE,MAAM,UAAU,CAAA;AAE/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAexE"}
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"}
@@ -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
- // The branch accessor returns the rendered branch (a node, `null`, or what a
21
- // render-function prop returned); Solid re-reads it as the state changes.
22
- const branch = createMemo(() => {
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
- return props.children(data);
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 <>{branch}</>;
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;AAI/C;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAI,KAA2B;IACzD,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,MAAM,GAAG,UAAU,CAAc,GAAG,EAAE;QAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;QACvB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,KAAK,CAAC,MAAM,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK;gBAC5C,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;gBAC1B,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAA;QAC7B,CAAC;QACD,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,OAAO,IAAI,IAAI,CAAA;QAC/C,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC7B,CAAC,CAAC,CAAA;IACF,OAAO,EAAE,CAAC,MAAM,CAAC,GAAG,CAAA;AACtB,CAAC"}
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
- /** Mounted only with a real document, including false, zero and an empty list. */
40
- children: (data: NonNullable<T>) => JSX.Element;
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. */
@@ -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;AAEnC,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,kFAAkF;IAClF,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,CAAA;IAC/C,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"}
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": "0.0.1-stage",
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.5.0",
58
+ "@molecule/app-solid": "3.6.0",
59
59
  "@molecule/app-ui": "1.3.11",
60
- "@molecule/app-ui-solid": "1.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",