@molecule/app-query-react 1.5.0 → 1.6.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 +64 -1
- package/dist/index.d.ts +19 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +19 -0
- package/dist/query-content.d.ts +18 -0
- package/dist/query-content.d.ts.map +1 -0
- package/dist/query-content.js +18 -0
- package/dist/types.d.ts +14 -0
- 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-14T04:22:15.656Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/app-query-react
|
|
@@ -460,6 +460,25 @@ interface UseQueryResult<T> extends QueryState<T> {
|
|
|
460
460
|
}
|
|
461
461
|
```
|
|
462
462
|
|
|
463
|
+
#### `QueryContentProps`
|
|
464
|
+
|
|
465
|
+
A loaded document owns its controls; absent documents expose only status content.
|
|
466
|
+
|
|
467
|
+
```typescript
|
|
468
|
+
interface QueryContentProps<T> {
|
|
469
|
+
/** State from useQuery, or any compatible query observer. */
|
|
470
|
+
query: Pick<QueryState<T>, 'data' | 'status' | 'error'>
|
|
471
|
+
/** Mounted only with a real document, including false, zero and an empty list. */
|
|
472
|
+
children: (data: NonNullable<T>) => ReactNode
|
|
473
|
+
/** Initial idle/loading content. Render a status node, never a fake item or action. */
|
|
474
|
+
pending?: ReactNode
|
|
475
|
+
/** Content for a loaded null record. Null is distinct from an unfinished request. */
|
|
476
|
+
missing?: ReactNode
|
|
477
|
+
/** A failed initial read. Cached data stays visible if its refresh fails. */
|
|
478
|
+
error?: (error: unknown) => ReactNode
|
|
479
|
+
}
|
|
480
|
+
```
|
|
481
|
+
|
|
463
482
|
#### `IntentPrefetchProps`
|
|
464
483
|
|
|
465
484
|
The handlers {@link intentPrefetchProps} returns.
|
|
@@ -474,6 +493,28 @@ interface IntentPrefetchProps {
|
|
|
474
493
|
|
|
475
494
|
### Functions
|
|
476
495
|
|
|
496
|
+
#### `QueryContent(props)`
|
|
497
|
+
|
|
498
|
+
The loaded-data branch receives a non-null document. Pending, failed initial reads and
|
|
499
|
+
missing records never mount that branch, so its actions cannot swallow an early click.
|
|
500
|
+
Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
|
|
501
|
+
belong outside the list or record container rendered by `children`, and so does a refresh
|
|
502
|
+
line; the default fallbacks render nothing.
|
|
503
|
+
|
|
504
|
+
```typescript
|
|
505
|
+
function QueryContent<T>({
|
|
506
|
+
query,
|
|
507
|
+
children,
|
|
508
|
+
pending = null,
|
|
509
|
+
missing = null,
|
|
510
|
+
error,
|
|
511
|
+
}: QueryContentProps<T>): ReactNode
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
- `props` — Query state, loaded content and optional status fallbacks.
|
|
515
|
+
|
|
516
|
+
**Returns:** Loaded content or the appropriate fallback.
|
|
517
|
+
|
|
477
518
|
#### `createQueryResource(config)`
|
|
478
519
|
|
|
479
520
|
Describe one API resource once and get its reads and writes on the shared cache.
|
|
@@ -659,3 +700,25 @@ Peer dependencies:
|
|
|
659
700
|
`client.invalidate(prefix)` marks the affected reads stale for their next
|
|
660
701
|
mount. Which key and which scope is the app's decision: the cache does not
|
|
661
702
|
infer it from auth or form state.
|
|
703
|
+
|
|
704
|
+
Render resource-dependent lists and controls through {@link QueryContent}. Its child function
|
|
705
|
+
receives only loaded, non-null data; loading and error content never mount item actions.
|
|
706
|
+
It renders cached content during refresh and treats an empty list, false and zero as data.
|
|
707
|
+
Put the list, or the record's own container (its card, header or profile block), inside the
|
|
708
|
+
child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
|
|
709
|
+
a reader that finds the container and reads its paragraph must read the record, not "Loading…".
|
|
710
|
+
|
|
711
|
+
```tsx
|
|
712
|
+
<QueryContent
|
|
713
|
+
query={query}
|
|
714
|
+
pending={<p role="status">{loadingLabel}</p>}
|
|
715
|
+
missing={<p>{missingLabel}</p>}
|
|
716
|
+
error={() => <p role="alert">{errorLabel}</p>}
|
|
717
|
+
>
|
|
718
|
+
{(record) => <RecordActions record={record} />}
|
|
719
|
+
</QueryContent>
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
Keep every resource identity in the query key. A boundary cannot correct a query that supplies
|
|
723
|
+
another record's cached data. For a list, map real rows inside the child; never style a status
|
|
724
|
+
placeholder as a row. QueryContent is headless and owns no translations or styling.
|
package/dist/index.d.ts
CHANGED
|
@@ -353,8 +353,27 @@
|
|
|
353
353
|
* mount. Which key and which scope is the app's decision: the cache does not
|
|
354
354
|
* infer it from auth or form state.
|
|
355
355
|
*
|
|
356
|
+
* Render resource-dependent lists and controls through {@link QueryContent}. Its child function
|
|
357
|
+
* receives only loaded, non-null data; loading and error content never mount item actions.
|
|
358
|
+
* It renders cached content during refresh and treats an empty list, false and zero as data.
|
|
359
|
+
* Put the list, or the record's own container (its card, header or profile block), inside the
|
|
360
|
+
* child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
|
|
361
|
+
* a reader that finds the container and reads its paragraph must read the record, not "Loading…".
|
|
362
|
+
*
|
|
363
|
+
* ```tsx
|
|
364
|
+
* <QueryContent query={query} pending={<p role="status">{loadingLabel}</p>}
|
|
365
|
+
* missing={<p>{missingLabel}</p>} error={() => <p role="alert">{errorLabel}</p>}>
|
|
366
|
+
* {(record) => <RecordActions record={record} />}
|
|
367
|
+
* </QueryContent>
|
|
368
|
+
* ```
|
|
369
|
+
*
|
|
370
|
+
* Keep every resource identity in the query key. A boundary cannot correct a query that supplies
|
|
371
|
+
* another record's cached data. For a list, map real rows inside the child; never style a status
|
|
372
|
+
* placeholder as a row. QueryContent is headless and owns no translations or styling.
|
|
373
|
+
*
|
|
356
374
|
* @module
|
|
357
375
|
*/
|
|
376
|
+
export * from './query-content.js';
|
|
358
377
|
export * from './resource.js';
|
|
359
378
|
export * from './types.js';
|
|
360
379
|
export * from './usePrefetch.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsXG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -353,8 +353,27 @@
|
|
|
353
353
|
* mount. Which key and which scope is the app's decision: the cache does not
|
|
354
354
|
* infer it from auth or form state.
|
|
355
355
|
*
|
|
356
|
+
* Render resource-dependent lists and controls through {@link QueryContent}. Its child function
|
|
357
|
+
* receives only loaded, non-null data; loading and error content never mount item actions.
|
|
358
|
+
* It renders cached content during refresh and treats an empty list, false and zero as data.
|
|
359
|
+
* Put the list, or the record's own container (its card, header or profile block), inside the
|
|
360
|
+
* child and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
|
|
361
|
+
* a reader that finds the container and reads its paragraph must read the record, not "Loading…".
|
|
362
|
+
*
|
|
363
|
+
* ```tsx
|
|
364
|
+
* <QueryContent query={query} pending={<p role="status">{loadingLabel}</p>}
|
|
365
|
+
* missing={<p>{missingLabel}</p>} error={() => <p role="alert">{errorLabel}</p>}>
|
|
366
|
+
* {(record) => <RecordActions record={record} />}
|
|
367
|
+
* </QueryContent>
|
|
368
|
+
* ```
|
|
369
|
+
*
|
|
370
|
+
* Keep every resource identity in the query key. A boundary cannot correct a query that supplies
|
|
371
|
+
* another record's cached data. For a list, map real rows inside the child; never style a status
|
|
372
|
+
* placeholder as a row. QueryContent is headless and owns no translations or styling.
|
|
373
|
+
*
|
|
356
374
|
* @module
|
|
357
375
|
*/
|
|
376
|
+
export * from './query-content.js';
|
|
358
377
|
export * from './resource.js';
|
|
359
378
|
export * from './types.js';
|
|
360
379
|
export * from './usePrefetch.js';
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Render resource-dependent content only after its document exists.
|
|
3
|
+
* @module
|
|
4
|
+
*/
|
|
5
|
+
import type { ReactNode } from 'react';
|
|
6
|
+
import type { QueryContentProps } from './types.js';
|
|
7
|
+
/**
|
|
8
|
+
* The loaded-data branch receives a non-null document. Pending, failed initial reads and
|
|
9
|
+
* missing records never mount that branch, so its actions cannot swallow an early click.
|
|
10
|
+
* Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
|
|
11
|
+
* belong outside the list or record container rendered by `children`, and so does a refresh
|
|
12
|
+
* line; the default fallbacks render nothing.
|
|
13
|
+
*
|
|
14
|
+
* @param props - Query state, loaded content and optional status fallbacks.
|
|
15
|
+
* @returns Loaded content or the appropriate fallback.
|
|
16
|
+
*/
|
|
17
|
+
export declare function QueryContent<T>({ query, children, pending, missing, error, }: QueryContentProps<T>): ReactNode;
|
|
18
|
+
//# sourceMappingURL=query-content.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"query-content.d.ts","sourceRoot":"","sources":["../src/query-content.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAC9B,KAAK,EACL,QAAQ,EACR,OAAc,EACd,OAAc,EACd,KAAK,GACN,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,CAMlC"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The loaded-data branch receives a non-null document. Pending, failed initial reads and
|
|
3
|
+
* missing records never mount that branch, so its actions cannot swallow an early click.
|
|
4
|
+
* Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
|
|
5
|
+
* belong outside the list or record container rendered by `children`, and so does a refresh
|
|
6
|
+
* line; the default fallbacks render nothing.
|
|
7
|
+
*
|
|
8
|
+
* @param props - Query state, loaded content and optional status fallbacks.
|
|
9
|
+
* @returns Loaded content or the appropriate fallback.
|
|
10
|
+
*/
|
|
11
|
+
export function QueryContent({ query, children, pending = null, missing = null, error, }) {
|
|
12
|
+
if (query.data === undefined) {
|
|
13
|
+
return query.status === 'error' && error ? error(query.error) : pending;
|
|
14
|
+
}
|
|
15
|
+
if (query.data === null)
|
|
16
|
+
return missing;
|
|
17
|
+
return children(query.data);
|
|
18
|
+
}
|
package/dist/types.d.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
* React query observer contracts.
|
|
3
3
|
* @module
|
|
4
4
|
*/
|
|
5
|
+
import type { ReactNode } from 'react';
|
|
5
6
|
import type { QueryState } from '@molecule/app-query';
|
|
6
7
|
/** A mounted query's state and its explicit cache and refresh actions. */
|
|
7
8
|
export interface UseQueryResult<T> extends QueryState<T> {
|
|
@@ -22,4 +23,17 @@ export interface UseQueryResult<T> extends QueryState<T> {
|
|
|
22
23
|
*/
|
|
23
24
|
refetch: () => Promise<QueryState<T>>;
|
|
24
25
|
}
|
|
26
|
+
/** A loaded document owns its controls; absent documents expose only status content. */
|
|
27
|
+
export interface QueryContentProps<T> {
|
|
28
|
+
/** State from useQuery, or any compatible query observer. */
|
|
29
|
+
query: Pick<QueryState<T>, 'data' | 'status' | 'error'>;
|
|
30
|
+
/** Mounted only with a real document, including false, zero and an empty list. */
|
|
31
|
+
children: (data: NonNullable<T>) => ReactNode;
|
|
32
|
+
/** Initial idle/loading content. Render a status node, never a fake item or action. */
|
|
33
|
+
pending?: ReactNode;
|
|
34
|
+
/** Content for a loaded null record. Null is distinct from an unfinished request. */
|
|
35
|
+
missing?: ReactNode;
|
|
36
|
+
/** A failed initial read. Cached data stays visible if its refresh fails. */
|
|
37
|
+
error?: (error: unknown) => ReactNode;
|
|
38
|
+
}
|
|
25
39
|
//# sourceMappingURL=types.d.ts.map
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,0EAA0E;AAC1E,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD;;;;;;;;OAQG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IAC1E;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;CACtC"}
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,0EAA0E;AAC1E,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD;;;;;;;;OAQG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IAC1E;;;;OAIG;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,SAAS,CAAA;IAC7C,uFAAuF;IACvF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qFAAqF;IACrF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,CAAA;CACtC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-query-react",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.0",
|
|
4
4
|
"description": "React 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-react",
|
|
6
6
|
"type": "module",
|
|
@@ -41,8 +41,8 @@
|
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
43
|
"@molecule/app-query": "1.1.3",
|
|
44
|
-
"@molecule/app-query-memory": "1.0.
|
|
45
|
-
"@molecule/app-query-tanstack": "1.0.
|
|
44
|
+
"@molecule/app-query-memory": "1.0.5",
|
|
45
|
+
"@molecule/app-query-tanstack": "1.0.5",
|
|
46
46
|
"@types/node": "26.6.5",
|
|
47
47
|
"@types/react": "19.3.0",
|
|
48
48
|
"@types/react-dom": "19.3.0",
|