@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 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-13T01:18:38.398Z
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';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoWG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
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
@@ -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.5.0",
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.4",
45
- "@molecule/app-query-tanstack": "1.0.4",
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",