@molecule/app-query-react 1.6.1 → 1.7.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 +25 -3
- package/dist/index.d.ts +11 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +11 -2
- package/dist/query-content.d.ts +1 -1
- package/dist/query-content.d.ts.map +1 -1
- package/dist/query-content.js +3 -1
- package/dist/types.d.ts +9 -0
- 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-16T21:21:11.635Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/app-query-react
|
|
@@ -45,8 +45,8 @@ its writes already publish the response and refresh its tracked collections.
|
|
|
45
45
|
```tsx
|
|
46
46
|
import { Link } from 'react-router'
|
|
47
47
|
import { getClient, isHttpError } from '@molecule/app-http'
|
|
48
|
-
import { t } from '@molecule/app-i18n'
|
|
49
48
|
import { intentPrefetchProps, useQuery } from '@molecule/app-query-react'
|
|
49
|
+
import { useTranslation } from '@molecule/app-react'
|
|
50
50
|
|
|
51
51
|
interface PackageDocument {
|
|
52
52
|
name: string
|
|
@@ -78,6 +78,7 @@ function PackageLink({ name }: { name: string }) {
|
|
|
78
78
|
}
|
|
79
79
|
|
|
80
80
|
function PackagePage({ name }: { name: string }) {
|
|
81
|
+
const { t } = useTranslation()
|
|
81
82
|
const { data, status } = useQuery(packageQuery(name))
|
|
82
83
|
if (status === 'error') {
|
|
83
84
|
return (
|
|
@@ -181,8 +182,8 @@ explicit `fetch()` retries into the mounted page.
|
|
|
181
182
|
|
|
182
183
|
```tsx
|
|
183
184
|
import { getClient } from '@molecule/app-http'
|
|
184
|
-
import { t } from '@molecule/app-i18n'
|
|
185
185
|
import { getQueryClient } from '@molecule/app-query'
|
|
186
|
+
import { useTranslation } from '@molecule/app-react'
|
|
186
187
|
|
|
187
188
|
// The key names what the document actually depends on — here the signed-in
|
|
188
189
|
// principal, the filter and the page. Another principal's feed is a
|
|
@@ -210,6 +211,7 @@ async function setFollowing(principal: string, authorId: string, follow: boolean
|
|
|
210
211
|
}
|
|
211
212
|
|
|
212
213
|
function Retry({ principal }: { principal: string }) {
|
|
214
|
+
const { t } = useTranslation()
|
|
213
215
|
return (
|
|
214
216
|
<button
|
|
215
217
|
onClick={() => {
|
|
@@ -417,6 +419,8 @@ interface QueryResource<T, Create = Partial<T>, Update = Partial<T>> {
|
|
|
417
419
|
/**
|
|
418
420
|
* `useQuery` options for the collection. `viewer` is who the answer is for (the signed-in id,
|
|
419
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.
|
|
420
424
|
*/
|
|
421
425
|
list(viewer: string, params?: Record<string, unknown>): QueryOptions<T[]>
|
|
422
426
|
/**
|
|
@@ -489,6 +493,16 @@ A loaded document owns its controls; absent documents expose only status content
|
|
|
489
493
|
|
|
490
494
|
```typescript
|
|
491
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. Omit it to keep empty arrays as data.
|
|
500
|
+
*/
|
|
501
|
+
empty?: {
|
|
502
|
+
when: (data: NonNullable<T>) => boolean
|
|
503
|
+
render: NonNullable<QueryContentProps<T>['children']>
|
|
504
|
+
}
|
|
505
|
+
|
|
492
506
|
/** State from useQuery, or any compatible query observer. */
|
|
493
507
|
query: Pick<QueryState<T>, 'data' | 'status' | 'error'>
|
|
494
508
|
/** Mounted only with a real document, including false, zero and an empty list. */
|
|
@@ -578,6 +592,7 @@ function QueryContent<T>({
|
|
|
578
592
|
pending = null,
|
|
579
593
|
missing = null,
|
|
580
594
|
error,
|
|
595
|
+
empty,
|
|
581
596
|
}: QueryContentProps<T>): ReactNode
|
|
582
597
|
```
|
|
583
598
|
|
|
@@ -761,3 +776,10 @@ a reader that finds the container and reads its paragraph must read the record,
|
|
|
761
776
|
Keep every resource identity in the query key. A boundary cannot correct a query that supplies
|
|
762
777
|
another record's cached data. For a list, map real rows inside the child; never style a status
|
|
763
778
|
placeholder as a row. QueryContent is headless and owns no translations or styling.
|
|
779
|
+
|
|
780
|
+
For a collection, `QueryContent` also accepts one `empty` branch:
|
|
781
|
+
`{ when: page => page.rows.length === 0, render: page => selectedEmptyState }`.
|
|
782
|
+
It is exclusive with loaded children, so a selected view chooses its message and
|
|
783
|
+
recovery action once rather than rendering a general empty message beside it.
|
|
784
|
+
`when` receives a loaded document; empty arrays remain data when this prop is omitted.
|
|
785
|
+
The render value uses this framework's existing children function, snippet or template.
|
package/dist/index.d.ts
CHANGED
|
@@ -31,8 +31,8 @@
|
|
|
31
31
|
* ```tsx
|
|
32
32
|
* import { Link } from 'react-router'
|
|
33
33
|
* import { getClient, isHttpError } from '@molecule/app-http'
|
|
34
|
-
* import { t } from '@molecule/app-i18n'
|
|
35
34
|
* import { intentPrefetchProps, useQuery } from '@molecule/app-query-react'
|
|
35
|
+
* import { useTranslation } from '@molecule/app-react'
|
|
36
36
|
*
|
|
37
37
|
* interface PackageDocument {
|
|
38
38
|
* name: string
|
|
@@ -60,6 +60,7 @@
|
|
|
60
60
|
* }
|
|
61
61
|
*
|
|
62
62
|
* function PackagePage({ name }: { name: string }) {
|
|
63
|
+
* const { t } = useTranslation()
|
|
63
64
|
* const { data, status } = useQuery(packageQuery(name))
|
|
64
65
|
* if (status === 'error') {
|
|
65
66
|
* return <p role="alert">{t('packages.loadFailed', undefined, { defaultValue: 'Unable to load package.' })}</p>
|
|
@@ -156,8 +157,8 @@
|
|
|
156
157
|
*
|
|
157
158
|
* ```tsx
|
|
158
159
|
* import { getClient } from '@molecule/app-http'
|
|
159
|
-
* import { t } from '@molecule/app-i18n'
|
|
160
160
|
* import { getQueryClient } from '@molecule/app-query'
|
|
161
|
+
* import { useTranslation } from '@molecule/app-react'
|
|
161
162
|
*
|
|
162
163
|
* // The key names what the document actually depends on — here the signed-in
|
|
163
164
|
* // principal, the filter and the page. Another principal's feed is a
|
|
@@ -185,6 +186,7 @@
|
|
|
185
186
|
* }
|
|
186
187
|
*
|
|
187
188
|
* function Retry({ principal }: { principal: string }) {
|
|
189
|
+
* const { t } = useTranslation()
|
|
188
190
|
* return (
|
|
189
191
|
* <button
|
|
190
192
|
* onClick={() => {
|
|
@@ -382,6 +384,13 @@
|
|
|
382
384
|
* another record's cached data. For a list, map real rows inside the child; never style a status
|
|
383
385
|
* placeholder as a row. QueryContent is headless and owns no translations or styling.
|
|
384
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
|
+
*
|
|
385
394
|
* @module
|
|
386
395
|
*/
|
|
387
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
|
@@ -31,8 +31,8 @@
|
|
|
31
31
|
* ```tsx
|
|
32
32
|
* import { Link } from 'react-router'
|
|
33
33
|
* import { getClient, isHttpError } from '@molecule/app-http'
|
|
34
|
-
* import { t } from '@molecule/app-i18n'
|
|
35
34
|
* import { intentPrefetchProps, useQuery } from '@molecule/app-query-react'
|
|
35
|
+
* import { useTranslation } from '@molecule/app-react'
|
|
36
36
|
*
|
|
37
37
|
* interface PackageDocument {
|
|
38
38
|
* name: string
|
|
@@ -60,6 +60,7 @@
|
|
|
60
60
|
* }
|
|
61
61
|
*
|
|
62
62
|
* function PackagePage({ name }: { name: string }) {
|
|
63
|
+
* const { t } = useTranslation()
|
|
63
64
|
* const { data, status } = useQuery(packageQuery(name))
|
|
64
65
|
* if (status === 'error') {
|
|
65
66
|
* return <p role="alert">{t('packages.loadFailed', undefined, { defaultValue: 'Unable to load package.' })}</p>
|
|
@@ -156,8 +157,8 @@
|
|
|
156
157
|
*
|
|
157
158
|
* ```tsx
|
|
158
159
|
* import { getClient } from '@molecule/app-http'
|
|
159
|
-
* import { t } from '@molecule/app-i18n'
|
|
160
160
|
* import { getQueryClient } from '@molecule/app-query'
|
|
161
|
+
* import { useTranslation } from '@molecule/app-react'
|
|
161
162
|
*
|
|
162
163
|
* // The key names what the document actually depends on — here the signed-in
|
|
163
164
|
* // principal, the filter and the page. Another principal's feed is a
|
|
@@ -185,6 +186,7 @@
|
|
|
185
186
|
* }
|
|
186
187
|
*
|
|
187
188
|
* function Retry({ principal }: { principal: string }) {
|
|
189
|
+
* const { t } = useTranslation()
|
|
188
190
|
* return (
|
|
189
191
|
* <button
|
|
190
192
|
* onClick={() => {
|
|
@@ -382,6 +384,13 @@
|
|
|
382
384
|
* another record's cached data. For a list, map real rows inside the child; never style a status
|
|
383
385
|
* placeholder as a row. QueryContent is headless and owns no translations or styling.
|
|
384
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
|
+
*
|
|
385
394
|
* @module
|
|
386
395
|
*/
|
|
387
396
|
export * from './query-content.js';
|
package/dist/query-content.d.ts
CHANGED
|
@@ -14,5 +14,5 @@ import type { QueryContentProps } from './types.js';
|
|
|
14
14
|
* @param props - Query state, loaded content and optional status fallbacks.
|
|
15
15
|
* @returns Loaded content or the appropriate fallback.
|
|
16
16
|
*/
|
|
17
|
-
export declare function QueryContent<T>({ query, children, pending, missing, error, }: QueryContentProps<T>): ReactNode;
|
|
17
|
+
export declare function QueryContent<T>({ query, children, pending, missing, error, empty, }: QueryContentProps<T>): ReactNode;
|
|
18
18
|
//# 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;;;;;;;;;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,
|
|
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,EACL,KAAK,GACN,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,CAOlC"}
|
package/dist/query-content.js
CHANGED
|
@@ -8,11 +8,13 @@
|
|
|
8
8
|
* @param props - Query state, loaded content and optional status fallbacks.
|
|
9
9
|
* @returns Loaded content or the appropriate fallback.
|
|
10
10
|
*/
|
|
11
|
-
export function QueryContent({ query, children, pending = null, missing = null, error, }) {
|
|
11
|
+
export function QueryContent({ query, children, pending = null, missing = null, error, empty, }) {
|
|
12
12
|
if (query.data === undefined) {
|
|
13
13
|
return query.status === 'error' && error ? error(query.error) : pending;
|
|
14
14
|
}
|
|
15
15
|
if (query.data === null)
|
|
16
16
|
return missing;
|
|
17
|
+
if (empty?.when(query.data))
|
|
18
|
+
return empty.render(query.data);
|
|
17
19
|
return children(query.data);
|
|
18
20
|
}
|
package/dist/types.d.ts
CHANGED
|
@@ -25,6 +25,15 @@ 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. Omit it to keep empty arrays as data.
|
|
32
|
+
*/
|
|
33
|
+
empty?: {
|
|
34
|
+
when: (data: NonNullable<T>) => boolean;
|
|
35
|
+
render: NonNullable<QueryContentProps<T>['children']>;
|
|
36
|
+
};
|
|
28
37
|
/** State from useQuery, or any compatible query observer. */
|
|
29
38
|
query: Pick<QueryState<T>, 'data' | 'status' | 'error'>;
|
|
30
39
|
/** Mounted only with a real document, including false, zero and an empty list. */
|
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;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"}
|
|
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;;;;OAIG;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,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.7.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",
|
|
@@ -40,9 +40,9 @@
|
|
|
40
40
|
"react": "^18.0.0 || ^19.0.0"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
|
-
"@molecule/app-query": "1.
|
|
44
|
-
"@molecule/app-query-memory": "1.0
|
|
45
|
-
"@molecule/app-query-tanstack": "1.0
|
|
43
|
+
"@molecule/app-query": "1.3.1",
|
|
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",
|