@molecule/app-query-react 1.6.2 → 1.7.1
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 +24 -2
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -0
- package/dist/query-content.d.ts +2 -1
- package/dist/query-content.d.ts.map +1 -1
- package/dist/query-content.js +8 -4
- package/dist/types.d.ts +11 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +4 -4
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-17T05:18:54.490Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/app-query-react
|
|
@@ -419,6 +419,8 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
|
|
|
419
419
|
/**
|
|
420
420
|
* `useQuery` options for the collection. `viewer` is who the answer is for (the signed-in id,
|
|
421
421
|
* or `'anonymous'`); a page or filter change keeps the rows on screen until the next answer.
|
|
422
|
+
* One record per URL identity, retaining the first occurrence. Equal values without an
|
|
423
|
+
* addressable id remain separate. Writes already refresh the collection.
|
|
422
424
|
*/
|
|
423
425
|
list(viewer: string, params?: Record<string, unknown>): QueryOptions<T[]>
|
|
424
426
|
/**
|
|
@@ -491,8 +493,19 @@ A loaded document owns its controls; absent documents expose only status content
|
|
|
491
493
|
|
|
492
494
|
```typescript
|
|
493
495
|
interface QueryContentProps<T> {
|
|
496
|
+
/**
|
|
497
|
+
* One optional empty branch, exclusive with children. The pure predicate reads the
|
|
498
|
+
* loaded document (an array or an application-owned envelope); render selects the
|
|
499
|
+
* current view's message and recovery action. A previous key's empty document uses
|
|
500
|
+
* pending/error instead. Omit it to keep empty arrays as data.
|
|
501
|
+
*/
|
|
502
|
+
empty?: {
|
|
503
|
+
when: (data: NonNullable<T>) => boolean
|
|
504
|
+
render: NonNullable<QueryContentProps<T>['children']>
|
|
505
|
+
}
|
|
506
|
+
|
|
494
507
|
/** State from useQuery, or any compatible query observer. */
|
|
495
|
-
query: Pick<QueryState<T>, 'data' | 'status' | 'error'>
|
|
508
|
+
query: Pick<QueryState<T>, 'data' | 'status' | 'error' | 'isPreviousData'>
|
|
496
509
|
/** Mounted only with a real document, including false, zero and an empty list. */
|
|
497
510
|
children: (data: NonNullable<T>) => ReactNode
|
|
498
511
|
/** Initial idle/loading content. Render a status node, never a fake item or action. */
|
|
@@ -572,6 +585,7 @@ missing records never mount that branch, so its actions cannot swallow an early
|
|
|
572
585
|
Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
|
|
573
586
|
belong outside the list or record container rendered by `children`, and so does a refresh
|
|
574
587
|
line; the default fallbacks render nothing.
|
|
588
|
+
A previous key's empty or missing document renders pending/error until the current key answers.
|
|
575
589
|
|
|
576
590
|
```typescript
|
|
577
591
|
function QueryContent<T>({
|
|
@@ -580,6 +594,7 @@ function QueryContent<T>({
|
|
|
580
594
|
pending = null,
|
|
581
595
|
missing = null,
|
|
582
596
|
error,
|
|
597
|
+
empty,
|
|
583
598
|
}: QueryContentProps<T>): ReactNode
|
|
584
599
|
```
|
|
585
600
|
|
|
@@ -763,3 +778,10 @@ a reader that finds the container and reads its paragraph must read the record,
|
|
|
763
778
|
Keep every resource identity in the query key. A boundary cannot correct a query that supplies
|
|
764
779
|
another record's cached data. For a list, map real rows inside the child; never style a status
|
|
765
780
|
placeholder as a row. QueryContent is headless and owns no translations or styling.
|
|
781
|
+
|
|
782
|
+
For a collection, `QueryContent` also accepts one `empty` branch:
|
|
783
|
+
`{ when: page => page.rows.length === 0, render: page => selectedEmptyState }`.
|
|
784
|
+
It is exclusive with loaded children, so a selected view chooses its message and
|
|
785
|
+
recovery action once rather than rendering a general empty message beside it.
|
|
786
|
+
`when` receives a loaded document; empty arrays remain data when this prop is omitted.
|
|
787
|
+
The render value uses this framework's existing children function, snippet or template.
|
package/dist/index.d.ts
CHANGED
|
@@ -384,6 +384,13 @@
|
|
|
384
384
|
* another record's cached data. For a list, map real rows inside the child; never style a status
|
|
385
385
|
* placeholder as a row. QueryContent is headless and owns no translations or styling.
|
|
386
386
|
*
|
|
387
|
+
* For a collection, `QueryContent` also accepts one `empty` branch:
|
|
388
|
+
* `{ when: page => page.rows.length === 0, render: page => selectedEmptyState }`.
|
|
389
|
+
* It is exclusive with loaded children, so a selected view chooses its message and
|
|
390
|
+
* recovery action once rather than rendering a general empty message beside it.
|
|
391
|
+
* `when` receives a loaded document; empty arrays remain data when this prop is omitted.
|
|
392
|
+
* The render value uses this framework's existing children function, snippet or template.
|
|
393
|
+
*
|
|
387
394
|
* @module
|
|
388
395
|
*/
|
|
389
396
|
export * from './query-content.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0YG;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
|
@@ -384,6 +384,13 @@
|
|
|
384
384
|
* another record's cached data. For a list, map real rows inside the child; never style a status
|
|
385
385
|
* placeholder as a row. QueryContent is headless and owns no translations or styling.
|
|
386
386
|
*
|
|
387
|
+
* For a collection, `QueryContent` also accepts one `empty` branch:
|
|
388
|
+
* `{ when: page => page.rows.length === 0, render: page => selectedEmptyState }`.
|
|
389
|
+
* It is exclusive with loaded children, so a selected view chooses its message and
|
|
390
|
+
* recovery action once rather than rendering a general empty message beside it.
|
|
391
|
+
* `when` receives a loaded document; empty arrays remain data when this prop is omitted.
|
|
392
|
+
* The render value uses this framework's existing children function, snippet or template.
|
|
393
|
+
*
|
|
387
394
|
* @module
|
|
388
395
|
*/
|
|
389
396
|
export * from './query-content.js';
|
package/dist/query-content.d.ts
CHANGED
|
@@ -10,9 +10,10 @@ import type { QueryContentProps } from './types.js';
|
|
|
10
10
|
* Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
|
|
11
11
|
* belong outside the list or record container rendered by `children`, and so does a refresh
|
|
12
12
|
* line; the default fallbacks render nothing.
|
|
13
|
+
* A previous key's empty or missing document renders pending/error until the current key answers.
|
|
13
14
|
*
|
|
14
15
|
* @param props - Query state, loaded content and optional status fallbacks.
|
|
15
16
|
* @returns Loaded content or the appropriate fallback.
|
|
16
17
|
*/
|
|
17
|
-
export declare function QueryContent<T>({ query, children, pending, missing, error, }: QueryContentProps<T>): ReactNode;
|
|
18
|
+
export declare function QueryContent<T>({ query, children, pending, missing, error, empty, }: QueryContentProps<T>): ReactNode;
|
|
18
19
|
//# sourceMappingURL=query-content.d.ts.map
|
|
@@ -1 +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
|
|
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;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAC9B,KAAK,EACL,QAAQ,EACR,OAAc,EACd,OAAc,EACd,KAAK,EACL,KAAK,GACN,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,CAQlC"}
|
package/dist/query-content.js
CHANGED
|
@@ -4,15 +4,19 @@
|
|
|
4
4
|
* Cached data remains mounted during refresh, including a failed refresh. Status fallbacks
|
|
5
5
|
* belong outside the list or record container rendered by `children`, and so does a refresh
|
|
6
6
|
* line; the default fallbacks render nothing.
|
|
7
|
+
* A previous key's empty or missing document renders pending/error until the current key answers.
|
|
7
8
|
*
|
|
8
9
|
* @param props - Query state, loaded content and optional status fallbacks.
|
|
9
10
|
* @returns Loaded content or the appropriate fallback.
|
|
10
11
|
*/
|
|
11
|
-
export function QueryContent({ query, children, pending = null, missing = null, error, }) {
|
|
12
|
-
|
|
12
|
+
export function QueryContent({ query, children, pending = null, missing = null, error, empty, }) {
|
|
13
|
+
const data = query.data;
|
|
14
|
+
if (data === undefined || (query.isPreviousData && (data === null || empty?.when(data)))) {
|
|
13
15
|
return query.status === 'error' && error ? error(query.error) : pending;
|
|
14
16
|
}
|
|
15
|
-
if (
|
|
17
|
+
if (data === null)
|
|
16
18
|
return missing;
|
|
17
|
-
|
|
19
|
+
if (empty?.when(data))
|
|
20
|
+
return empty.render(data);
|
|
21
|
+
return children(data);
|
|
18
22
|
}
|
package/dist/types.d.ts
CHANGED
|
@@ -25,8 +25,18 @@ export interface UseQueryResult<T> extends QueryState<T> {
|
|
|
25
25
|
}
|
|
26
26
|
/** A loaded document owns its controls; absent documents expose only status content. */
|
|
27
27
|
export interface QueryContentProps<T> {
|
|
28
|
+
/**
|
|
29
|
+
* One optional empty branch, exclusive with children. The pure predicate reads the
|
|
30
|
+
* loaded document (an array or an application-owned envelope); render selects the
|
|
31
|
+
* current view's message and recovery action. A previous key's empty document uses
|
|
32
|
+
* pending/error instead. Omit it to keep empty arrays as data.
|
|
33
|
+
*/
|
|
34
|
+
empty?: {
|
|
35
|
+
when: (data: NonNullable<T>) => boolean;
|
|
36
|
+
render: NonNullable<QueryContentProps<T>['children']>;
|
|
37
|
+
};
|
|
28
38
|
/** State from useQuery, or any compatible query observer. */
|
|
29
|
-
query: Pick<QueryState<T>, 'data' | 'status' | 'error'>;
|
|
39
|
+
query: Pick<QueryState<T>, 'data' | 'status' | 'error' | 'isPreviousData'>;
|
|
30
40
|
/** Mounted only with a real document, including false, zero and an empty list. */
|
|
31
41
|
children: (data: NonNullable<T>) => ReactNode;
|
|
32
42
|
/** Initial idle/loading content. Render a status node, never a fake item or action. */
|
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,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;
|
|
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;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,OAAO,CAAA;QACvC,MAAM,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;KACtD,CAAA;IAED,6DAA6D;IAC7D,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,gBAAgB,CAAC,CAAA;IAC1E,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.7.1",
|
|
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",
|
|
@@ -40,9 +40,9 @@
|
|
|
40
40
|
"react": "^18.0.0 || ^19.0.0"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
|
-
"@molecule/app-query": "1.2
|
|
44
|
-
"@molecule/app-query-memory": "1.0
|
|
45
|
-
"@molecule/app-query-tanstack": "1.0
|
|
43
|
+
"@molecule/app-query": "1.3.2",
|
|
44
|
+
"@molecule/app-query-memory": "1.1.0",
|
|
45
|
+
"@molecule/app-query-tanstack": "1.1.0",
|
|
46
46
|
"@types/node": "26.6.5",
|
|
47
47
|
"@types/react": "19.3.0",
|
|
48
48
|
"@types/react-dom": "19.3.0",
|