@molecule/app-query-vue 0.0.0-stage → 0.0.1-stage

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/dist/index.js ADDED
@@ -0,0 +1,441 @@
1
+ /**
2
+ * Vue composables for `@molecule/app-query` — the Vue counterpart of
3
+ * `@molecule/app-query-react`, with the same exports, the same props, the same
4
+ * cache behavior and the same DOM for the same input.
5
+ *
6
+ * **Load page data with {@link useQuery}, not `fetch` inside a `watch`.** A hand-written load
7
+ * watcher that cancels its request on cleanup (a `cancelled` flag, or an `AbortController`)
8
+ * re-runs its cleanup on EVERY re-run whenever one of its sources is a function created inline
9
+ * each run — `const { setError } = useApiErrors()` returning arrow functions is the usual
10
+ * source. The watcher's own guard (`if (loaded === slug) return`) then returns without
11
+ * refetching, so the response is discarded whenever it arrives after a re-run: always on a
12
+ * remote server, never on localhost, which is why the page passes locally and fails on the
13
+ * live URL. `useQuery` subscribes once per key, keeps its request stable across re-renders,
14
+ * and aborts it only when the key changes or the component unmounts.
15
+ *
16
+ * {@link useQuery} observes one document from the app's shared cache and
17
+ * returns cached data on the first read; {@link usePrefetch} and
18
+ * {@link intentPrefetchProps} warm a document when a person is about to
19
+ * open it. Together they make a detail page open with no loading state.
20
+ *
21
+ * This package needs a bonded client: install `@molecule/app-query` with a bond
22
+ * (`@molecule/app-query-memory`, or `@molecule/app-query-tanstack`) and call the bond's
23
+ * `setProvider(provider)` once at startup (the scaffold's `app/src/bonds/` does this).
24
+ *
25
+ * **Keep displayed records on the query cache.** Render `query.value.data` directly. A custom
26
+ * mutation handler publishes its saved response with `query.setData(saved)`; every observer
27
+ * and the next visit receive it, and subsequent refreshes still update the view. A local
28
+ * `ref` copy hydrated only once per record hides later query answers. Editable form
29
+ * drafts remain local until saved. Prefer {@link createQueryResource} for a complete resource;
30
+ * its writes already publish the response and refresh its tracked collections.
31
+ *
32
+ * @example
33
+ * ```ts
34
+ * import { getClient, isHttpError } from '@molecule/app-http'
35
+ * import { useTranslation } from '@molecule/app-vue'
36
+ * import { defineComponent, h } from 'vue'
37
+ * import { intentPrefetchProps, useQuery } from '@molecule/app-query-vue'
38
+ *
39
+ * interface PackageDocument {
40
+ * name: string
41
+ * description: string
42
+ * }
43
+ *
44
+ * const packageQuery = (name: string) => ({
45
+ * key: ['package', name],
46
+ * fetch: async (signal: AbortSignal): Promise<PackageDocument | null> => {
47
+ * try {
48
+ * const response = await getClient().get<PackageDocument | null>(
49
+ * `/data/packages/${encodeURIComponent(name)}.json`,
50
+ * { signal },
51
+ * )
52
+ * return response.data
53
+ * } catch (error) {
54
+ * if (isHttpError(error) && error.status === 404) return null
55
+ * throw error
56
+ * }
57
+ * },
58
+ * })
59
+ *
60
+ * const PackageLink = defineComponent({
61
+ * props: { name: { type: String, required: true } },
62
+ * setup(props) {
63
+ * return () =>
64
+ * h(
65
+ * 'a',
66
+ * { href: `/packages/${props.name}`, ...intentPrefetchProps(packageQuery(props.name)) },
67
+ * props.name,
68
+ * )
69
+ * },
70
+ * })
71
+ *
72
+ * const PackagePage = defineComponent({
73
+ * props: { name: { type: String, required: true } },
74
+ * setup(props) {
75
+ * const { t } = useTranslation()
76
+ * // Options as a getter: a changed `name` (a new route param) moves this same
77
+ * // observer to the new key — React re-renders `useQuery` with new options instead.
78
+ * const query = useQuery<PackageDocument | null>(() => packageQuery(props.name))
79
+ * return () => {
80
+ * const { data, status } = query.value
81
+ * if (status === 'error') {
82
+ * return h('p', { role: 'alert' }, t('packages.loadFailed', undefined, { defaultValue: 'Unable to load package.' }))
83
+ * }
84
+ * if (status === 'idle' || status === 'loading') {
85
+ * return h('p', { role: 'status' }, t('common.loading', undefined, { defaultValue: 'Loading…' }))
86
+ * }
87
+ * if (data == null) {
88
+ * return h('p', {}, t('packages.notFound', undefined, { defaultValue: 'Package not found.' }))
89
+ * }
90
+ * return h('article', {}, [h('h1', {}, data.name), h('p', {}, data.description)])
91
+ * }
92
+ * },
93
+ * })
94
+ * ```
95
+ *
96
+ * @example
97
+ * A list whose page and filter live in the URL: derive the key from the route and pass
98
+ * `keepPreviousData` with a `principal`, so a page/filter change keeps the rows already on screen
99
+ * until the next page answers. The app's HTTP client sends the session, so the viewer is part of
100
+ * what the answer depends on: key on it and pass the same value as `principal` — an account
101
+ * switch then drops the previous account's rows at once. Pass `null` while the session is still
102
+ * being restored (`status === 'loading'`; the HTTP client holds the request until then anyway),
103
+ * so restoring a session never swaps a key that already rendered rows.
104
+ *
105
+ * ```ts
106
+ * import { unwrapList } from '@molecule/app-http'
107
+ * import { useAuth, useHttpClient, useTranslation } from '@molecule/app-vue'
108
+ * import { computed, defineComponent, h, type PropType } from 'vue'
109
+ * import { useQuery } from '@molecule/app-query-vue'
110
+ *
111
+ * interface Invoice {
112
+ * id: string
113
+ * number: string
114
+ * }
115
+ *
116
+ * export const InvoiceList = defineComponent({
117
+ * props: {
118
+ * page: { type: Number, default: 1 },
119
+ * statusFilter: { type: String as PropType<string>, default: '' },
120
+ * },
121
+ * setup(props) {
122
+ * const http = useHttpClient()
123
+ * const { t } = useTranslation()
124
+ * const { status: authStatus, user } = useAuth<{ id: string }>()
125
+ * const query = useQuery(
126
+ * computed(() => {
127
+ * const viewer = user.value ? String(user.value.id) : 'anonymous'
128
+ * return authStatus.value === 'loading'
129
+ * ? null
130
+ * : {
131
+ * key: ['invoices', viewer, props.statusFilter, props.page],
132
+ * principal: viewer,
133
+ * keepPreviousData: true,
134
+ * fetch: async (signal: AbortSignal) =>
135
+ * unwrapList<Invoice>(
136
+ * await http.get('/api/invoices', {
137
+ * signal,
138
+ * params: {
139
+ * status: props.statusFilter,
140
+ * limit: 20,
141
+ * offset: (props.page - 1) * 20,
142
+ * },
143
+ * }),
144
+ * ),
145
+ * }
146
+ * }),
147
+ * )
148
+ *
149
+ * // Status renders outside the item list (it is not an item), and the empty state
150
+ * // describes only the key on screen, never a retained previous page.
151
+ * return () => {
152
+ * const state = query.value
153
+ * return h('section', {}, [
154
+ * state.status === 'loading' || state.isFetching
155
+ * ? h('p', { role: 'status' }, t('common.loading', undefined, { defaultValue: 'Loading…' }))
156
+ * : null,
157
+ * state.status === 'error'
158
+ * ? h('p', { role: 'alert' }, t('invoices.loadFailed', undefined, { defaultValue: 'Unable to load invoices.' }))
159
+ * : null,
160
+ * h('ul', {}, (state.data ?? []).map((invoice) => h('li', { key: invoice.id }, [h('a', { href: `/invoices/${invoice.id}` }, invoice.number)]))),
161
+ * !state.isPreviousData && state.data?.length === 0
162
+ * ? h('p', {}, t('invoices.empty', undefined, { defaultValue: 'No invoices yet.' }))
163
+ * : null,
164
+ * ])
165
+ * }
166
+ * },
167
+ * })
168
+ * ```
169
+ *
170
+ * @example
171
+ * A mutation or a failed load has to change a page that is ALREADY mounted, and
172
+ * the cache never starts that request by itself: `set()` paints a mutation's own
173
+ * response, `invalidate()` marks what it affects for the next mount, and an
174
+ * explicit `fetch()` retries into the mounted page.
175
+ *
176
+ * ```ts
177
+ * import { getQueryClient } from '@molecule/app-query'
178
+ * import { getClient } from '@molecule/app-http'
179
+ * import { t } from '@molecule/app-i18n'
180
+ * import { defineComponent, h } from 'vue'
181
+ *
182
+ * // The key names what the document actually depends on — here the signed-in
183
+ * // principal, the filter and the page. Another principal's feed is a
184
+ * // different document, so an invalidation scoped to this one leaves it alone.
185
+ * const feedKey = (principal: string, filter: string, page: number) =>
186
+ * ['feed', principal, filter, page] as const
187
+ *
188
+ * const feedOptions = (principal: string, filter: string, page: number) => ({
189
+ * key: feedKey(principal, filter, page),
190
+ * fetch: async (signal: AbortSignal) =>
191
+ * (await getClient().get(`/api/feeds/${filter}`, { signal, params: { page } })).data,
192
+ * })
193
+ *
194
+ * async function setFollowing(principal: string, authorId: string, follow: boolean) {
195
+ * const client = getQueryClient()
196
+ * const http = getClient()
197
+ * const { data: body } = follow
198
+ * ? await http.post<{ feed: unknown }>(`/api/follows/${authorId}`)
199
+ * : await http.delete<{ feed: unknown }>(`/api/follows/${authorId}`)
200
+ * // The response IS the document: paint it now, with no second round trip.
201
+ * // (If it were only a count or a flag, skip set() and invalidate() instead.)
202
+ * client.set(feedKey(principal, 'following', 1), body.feed)
203
+ * // Future reads of every feed this principal owns are stale.
204
+ * client.invalidate(['feed', principal])
205
+ * }
206
+ *
207
+ * const Retry = defineComponent({
208
+ * props: { principal: { type: String, required: true } },
209
+ * setup(props) {
210
+ * return () =>
211
+ * h(
212
+ * 'button',
213
+ * {
214
+ * type: 'button',
215
+ * onClick: () => {
216
+ * // invalidate() alone would leave the mounted page on its error;
217
+ * // an explicit fetch retries into it. useQuery shows the outcome.
218
+ * void getQueryClient()
219
+ * .fetch(feedOptions(props.principal, 'following', 1))
220
+ * // The mounted useQuery observer presents this failure via status/error.
221
+ * .catch((_error) => {})
222
+ * },
223
+ * },
224
+ * t('common.retry', undefined, { defaultValue: 'Retry' }),
225
+ * )
226
+ * },
227
+ * })
228
+ * ```
229
+ *
230
+ * @example
231
+ * One API resource described once, for every page that reads or changes it.
232
+ * `createQueryResource` returns the list and detail reads as `useQuery` options and the writes
233
+ * as functions that put the server's record into the cache and fetch the lists on screen again,
234
+ * so a page never mirrors a response into a local `ref`. A flag the API models as a sub-path
235
+ * (`POST /invoices/:id/flag`, `DELETE` to clear it) is `toggle`, which resolves with the saved
236
+ * record and is the `commit` of `useOptimisticValue`.
237
+ *
238
+ * ```ts
239
+ * import { getClient, unwrapList, unwrapSingle } from '@molecule/app-http'
240
+ * import { useAuth, useOptimisticValue, useTranslation } from '@molecule/app-vue'
241
+ * import { defineComponent, h, type PropType } from 'vue'
242
+ * import { createQueryResource, QueryContent, useQuery } from '@molecule/app-query-vue'
243
+ *
244
+ * interface Invoice {
245
+ * id: string
246
+ * number: string
247
+ * flagged: boolean
248
+ * }
249
+ *
250
+ * export const invoices = createQueryResource<Invoice>({
251
+ * name: 'invoices',
252
+ * path: '/invoices',
253
+ * http: getClient,
254
+ * readList: (response) => unwrapList<Invoice>(response),
255
+ * readOne: (response) => unwrapSingle<Invoice>(response),
256
+ * })
257
+ *
258
+ * const InvoicePage = defineComponent({
259
+ * props: { id: { type: String as PropType<string>, required: true } },
260
+ * setup(props) {
261
+ * const { user } = useAuth<{ id: string }>()
262
+ * const { t } = useTranslation()
263
+ * const query = useQuery(() => invoices.detail(user.value ? String(user.value.id) : 'anonymous', props.id))
264
+ * return () => {
265
+ * const viewer = user.value ? String(user.value.id) : 'anonymous'
266
+ * return h(QueryContent<Invoice | null>, {
267
+ * query: query.value,
268
+ * pending: h('p', { role: 'status' }, t('common.loading', undefined, { defaultValue: 'Loading…' })),
269
+ * missing: h('p', { role: 'alert' }, t('invoice.missing', undefined, { defaultValue: 'Invoice not found.' })),
270
+ * error: () => h('p', { role: 'alert' }, t('invoice.failed', undefined, { defaultValue: 'Unable to load invoice.' })),
271
+ * children: (invoice) => h(FlagButton, { key: invoice.id, invoice, viewer }),
272
+ * })
273
+ * }
274
+ * },
275
+ * })
276
+ *
277
+ * const FlagButton = defineComponent({
278
+ * props: {
279
+ * invoice: { type: Object as PropType<Invoice>, required: true },
280
+ * viewer: { type: String, required: true },
281
+ * },
282
+ * setup(props) {
283
+ * const { t } = useTranslation()
284
+ * const flag = useOptimisticValue({
285
+ * value: props.invoice.flagged,
286
+ * commit: async (on) => (await invoices.toggle(props.viewer, props.invoice.id, 'flag', on)).flagged,
287
+ * })
288
+ * // While a save is pending the optimistic value leads; when it settles,
289
+ * // the saved record on the cache leads. That is the Vue composition of the
290
+ * // same behavior React gets by re-rendering `value: invoice.flagged` —
291
+ * // a failed save rolls back to the record the cache still holds.
292
+ * return () => {
293
+ * const flagged = flag.pending.value ? flag.value.value : props.invoice.flagged
294
+ * return h(
295
+ * 'button',
296
+ * {
297
+ * type: 'button',
298
+ * 'aria-pressed': flagged,
299
+ * onClick: () => flag.update((on) => !on),
300
+ * },
301
+ * [
302
+ * flagged
303
+ * ? t('invoice.unflag', undefined, { defaultValue: 'Unflag' })
304
+ * : t('invoice.flag', undefined, { defaultValue: 'Flag' }),
305
+ * ' ',
306
+ * props.invoice.number,
307
+ * ],
308
+ * )
309
+ * }
310
+ * },
311
+ * })
312
+ * ```
313
+ *
314
+ * @example
315
+ * A pager needs the whole response, including its total. Keep that read on the same resource
316
+ * as its mutations, including alternate list paths; a separate hand-written `QueryOptions`
317
+ * is outside the resource's refresh tracking.
318
+ *
319
+ * ```typescript
320
+ * import { getClient } from '@molecule/app-http'
321
+ * import { createQueryResource } from '@molecule/app-query-vue'
322
+ *
323
+ * interface TicketPage { tickets: { id: string; subject: string }[]; total: number }
324
+ * const tickets = createQueryResource<TicketPage['tickets'][number]>({
325
+ * name: 'tickets', path: '/tickets', http: getClient,
326
+ * readOne: (response) => response.data as TicketPage['tickets'][number],
327
+ * })
328
+ * const page = tickets.listPage('agent-1', { limit: 10, offset: 20 },
329
+ * (response) => response.data as TicketPage)
330
+ * // useQuery(page) observes both rows and total. tickets.create/update/remove/toggle
331
+ * // and tickets.refresh('agent-1') refresh this page too.
332
+ * // A second list can use tickets.listPage(viewer, params, readPage, '/tickets/open').
333
+ * // Use one canonical page reader per path; list() still returns only its own rows.
334
+ * // For immediate deletion from an opaque page, add a fifth argument:
335
+ * // (page, id) => {
336
+ * // const rows = page.tickets.filter((row) => String(row.id) !== id)
337
+ * // return { ...page, tickets: rows, total: page.total - (page.tickets.length - rows.length) }
338
+ * // }
339
+ * ```
340
+ * A resource mutation also waits out a pre-mutation list request before fetching again;
341
+ * joining that older in-flight read alone would leave the new record absent.
342
+ * Successful deletion removes a row immediately, including one just created through the
343
+ * resource. Stale reads cannot restore acknowledged deletions for that viewer; an explicit
344
+ * successful create can recreate the identity. Opaque listPage envelopes need their own
345
+ * removeFromPage adapter; no row or total property is guessed.
346
+ *
347
+ * @remarks
348
+ * - **`useQuery` reads the cache synchronously on the first read.** A
349
+ * document prefetched from a hovered link, or seeded with `client.set()`
350
+ * from a server-rendered JSON island, renders at once — no spinner, no
351
+ * layout shift. Render loading from `status === 'idle' || status === 'loading'`;
352
+ * `undefined` data can also accompany a completed error. A completed `null`
353
+ * response is missing, not pending. The detail example treats only HTTP 404
354
+ * or a successful null response as missing; other errors stay load failures.
355
+ * The app's bonded HTTP client rejects non-2xx responses. Native `fetch`
356
+ * resolves them, so a custom fetcher must check `response.ok` before JSON.
357
+ * - **Mount a detail region and its actions only after its initial document arrives.**
358
+ * A visible container is not a loaded document: a caller may wait for that container and
359
+ * read its text once, or click its button, while `data` is still undefined. Put the loading
360
+ * message outside the detail region, as in `PackagePage` above. Keep record-dependent
361
+ * controls absent or natively disabled until the record exists; returning early inside
362
+ * an enabled click handler loses that click. `client.set()` protects a cache mutation
363
+ * from an older read, but cannot recover a click whose handler never sent the mutation.
364
+ * - **The key is the identity.** Building `options` inline is fine; the
365
+ * composable resubscribes only when the key's value changes, not when the
366
+ * `fetch` closure does.
367
+ * - **A key change normally resets to the new key's state.** For a list's own
368
+ * page/filter/view change, opt into `keepPreviousData` with a `principal`;
369
+ * `isPreviousData` tells you the rows on screen belong to the key you just
370
+ * left. A completed response (including an empty list) replaces them, and a
371
+ * changed principal drops them, so an account switch never shows the previous
372
+ * account's rows. Do not emulate this with a local `ref` mirror of the
373
+ * query data — that mirror is what serves stale rows under a new page, or
374
+ * blanks the list on a re-render.
375
+ * - **The key names the viewer whenever the answer can depend on it.** The
376
+ * app's HTTP client sends the session, so the server may filter or
377
+ * personalize even a list that guests can see (a `favorited` or `following`
378
+ * flag), and the cache serves a key's document to whoever observes it,
379
+ * across sign-in and sign-out. Key such a list on the viewer
380
+ * (`user ? String(user.id) : 'anonymous'`), pass the same value as
381
+ * `principal`, and pass `null` while the session is still being restored
382
+ * (`status === 'loading'`; the HTTP client holds the request until then
383
+ * anyway), so restoring a session never swaps a key that already rendered
384
+ * rows. A viewer-free key with `principal: 'public'` is only for an endpoint
385
+ * that answers every viewer the same.
386
+ * - **Render loading, empty and error status outside the item list**, and never
387
+ * give a placeholder the item's own class or element shape: a list read by
388
+ * the item class (or by `:first-child`) must contain only real items. An
389
+ * empty array is a loaded empty state, not a missing response; render it
390
+ * only when `isPreviousData` is not set, because a retained document belongs
391
+ * to the key you just left.
392
+ * - `intentPrefetchProps` spreads three handlers onto a link. It is a plain
393
+ * function (not a composable), so it works inside `.map()` too. The names
394
+ * are Vue's listener spellings (`onPointerenter`, `onFocus`, `onTouchstart`).
395
+ * - Prefetching respects the browser's data-saver setting and skips 2G
396
+ * connections (`shouldPrefetch()` in the core) — do not bypass that for
397
+ * "important" links; the person can still click.
398
+ * - **Refresh a mounted document with `query.refetch()`.** It fetches even a fresh cache
399
+ * entry and updates every observer of that key. After a mutation whose response is not the
400
+ * whole document, `await query.refetch()` reloads the displayed list. It resolves with the
401
+ * resulting state (including `status: 'error'` on failure); a disabled query stays idle.
402
+ * Prefer `client.set(key, response)` when the mutation already returned the whole document.
403
+ * - Errors are not thrown from the composable; read `status === 'error'` and
404
+ * `error`. `client.invalidate()` does NOT refetch a mounted page — it only
405
+ * marks documents stale, so the page keeps its error (or its old document)
406
+ * until the app retries with `client.fetch(options)` or the page subscribes
407
+ * again (a key change or a re-mount).
408
+ * - After a mutation, `client.set(key, response)` paints the server's own
409
+ * answer at once and supersedes an older fetch already in flight for that
410
+ * key, so its response cannot undo the mutation. An existing `fetch()` caller
411
+ * still settles independently of the cache write; read `client.get(key)` for the newest document.
412
+ * `client.invalidate(prefix)` marks the affected reads stale for their next
413
+ * mount. Which key and which scope is the app's decision: the cache does not
414
+ * infer it from auth or form state.
415
+ *
416
+ * Render resource-dependent lists and controls through {@link QueryContent}. Its `children`
417
+ * function (or default slot) receives only loaded, non-null data; loading and error content
418
+ * never mount item actions.
419
+ * It renders cached content during refresh and treats an empty list, false and zero as data.
420
+ * Put the list, or the record's own container (its card, header or profile block), inside the
421
+ * `children` and every status line (loading, error, `isFetching` refresh) beside it, never inside it:
422
+ * a reader that finds the container and reads its paragraph must read the record, not "Loading…".
423
+ *
424
+ * ```ts
425
+ * h(QueryContent, { query: query.value, pending: h('p', { role: 'status' }, loadingLabel) },
426
+ * // missing: h('p', {}, missingLabel), error: () => h('p', { role: 'alert' }, errorLabel),
427
+ * { default: ({ data: record }) => [h(RecordActions, { record })] })
428
+ * ```
429
+ *
430
+ * Keep every resource identity in the query key. A boundary cannot correct a query that supplies
431
+ * another record's cached data. For a list, map real rows inside the child; never style a status
432
+ * placeholder as a row. QueryContent is headless and owns no translations or styling.
433
+ *
434
+ * @module
435
+ */
436
+ export * from './query-content.js';
437
+ export * from './resource.js';
438
+ export * from './types.js';
439
+ export * from './usePrefetch.js';
440
+ export * from './useQuery.js';
441
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkbG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA"}
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Render resource-dependent content only after its document exists.
3
+ * @module
4
+ */
5
+ import type { VNodeChild } from 'vue';
6
+ import type { QueryContentProps } from './types.js';
7
+ /**
8
+ * The slots {@link QueryContent} accepts alongside its props: every node-valued
9
+ * prop also arrives as a same-named slot, and `children` as the default slot.
10
+ */
11
+ export interface QueryContentSlots<T> {
12
+ /** The loaded-data branch, which receives `{ data }` (the document). */
13
+ default?: (slotProps: {
14
+ data: NonNullable<T>;
15
+ }) => VNodeChild;
16
+ /** Idle/loading content (the `pending` prop). */
17
+ pending?: () => VNodeChild;
18
+ /** Loaded-null content (the `missing` prop). */
19
+ missing?: () => VNodeChild;
20
+ }
21
+ /**
22
+ * The loaded-data branch receives a non-null document. Pending, failed initial
23
+ * reads and missing records never mount that branch, so its actions cannot
24
+ * swallow an early click. Cached data remains mounted during refresh, including
25
+ * a failed refresh. Status fallbacks belong outside the list or record
26
+ * container rendered by `children`, and so does a refresh line; the default
27
+ * fallbacks render nothing.
28
+ *
29
+ * The loaded branch is the `children` render function, or the default slot
30
+ * (which receives `{ data }`); `pending` and `missing` are node props or
31
+ * same-named slots. It is the Vue counterpart of `@molecule/app-query-react`'s
32
+ * `QueryContent`: the same props, the same branch rules, and the same DOM for
33
+ * the same input. Use it with `h(QueryContent, { query, children, … })` — the
34
+ * document's type flows from the `query` prop into `children`.
35
+ *
36
+ * @param props - Query state, loaded content and optional status fallbacks.
37
+ * @param ctx - The functional-component context; its slots carry the same-named
38
+ * alternatives to the node props and the default slot for `children`.
39
+ * @returns Loaded content or the appropriate fallback.
40
+ *
41
+ * @example
42
+ * ```ts
43
+ * import { defineComponent, h } from 'vue'
44
+ * import { QueryContent } from '@molecule/app-query-vue'
45
+ *
46
+ * export const RecordRegion = defineComponent({
47
+ * props: { query: { type: Object, required: true } },
48
+ * setup(props) {
49
+ * return () =>
50
+ * h(QueryContent, {
51
+ * query: props.query,
52
+ * pending: h('p', { role: 'status' }, 'Loading…'),
53
+ * missing: h('p', {}, 'Not found'),
54
+ * error: (cause) => h('p', { role: 'alert' }, `Failed: ${String(cause)}`),
55
+ * children: (record) => h('article', {}, record.name),
56
+ * })
57
+ * },
58
+ * })
59
+ * ```
60
+ */
61
+ export declare const QueryContent: (<T>(props: QueryContentProps<T>, ctx: {
62
+ slots: QueryContentSlots<T>;
63
+ }) => VNodeChild) & {
64
+ props: string[];
65
+ };
66
+ //# sourceMappingURL=query-content.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"query-content.d.ts","sourceRoot":"","sources":["../src/query-content.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;KAAE,KAAK,UAAU,CAAA;IAC7D,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,UAAU,CAAA;IAC1B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,UAAU,CAAA;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,YAAY,IACD,CAAC,SACd,iBAAiB,CAAC,CAAC,CAAC,OACtB;IAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAA;CAAE,KACnC,UAAU;;CAcd,CAAA"}
@@ -0,0 +1,58 @@
1
+ /**
2
+ * The loaded-data branch receives a non-null document. Pending, failed initial
3
+ * reads and missing records never mount that branch, so its actions cannot
4
+ * swallow an early click. Cached data remains mounted during refresh, including
5
+ * a failed refresh. Status fallbacks belong outside the list or record
6
+ * container rendered by `children`, and so does a refresh line; the default
7
+ * fallbacks render nothing.
8
+ *
9
+ * The loaded branch is the `children` render function, or the default slot
10
+ * (which receives `{ data }`); `pending` and `missing` are node props or
11
+ * same-named slots. It is the Vue counterpart of `@molecule/app-query-react`'s
12
+ * `QueryContent`: the same props, the same branch rules, and the same DOM for
13
+ * the same input. Use it with `h(QueryContent, { query, children, … })` — the
14
+ * document's type flows from the `query` prop into `children`.
15
+ *
16
+ * @param props - Query state, loaded content and optional status fallbacks.
17
+ * @param ctx - The functional-component context; its slots carry the same-named
18
+ * alternatives to the node props and the default slot for `children`.
19
+ * @returns Loaded content or the appropriate fallback.
20
+ *
21
+ * @example
22
+ * ```ts
23
+ * import { defineComponent, h } from 'vue'
24
+ * import { QueryContent } from '@molecule/app-query-vue'
25
+ *
26
+ * export const RecordRegion = defineComponent({
27
+ * props: { query: { type: Object, required: true } },
28
+ * setup(props) {
29
+ * return () =>
30
+ * h(QueryContent, {
31
+ * query: props.query,
32
+ * pending: h('p', { role: 'status' }, 'Loading…'),
33
+ * missing: h('p', {}, 'Not found'),
34
+ * error: (cause) => h('p', { role: 'alert' }, `Failed: ${String(cause)}`),
35
+ * children: (record) => h('article', {}, record.name),
36
+ * })
37
+ * },
38
+ * })
39
+ * ```
40
+ */
41
+ export const QueryContent = Object.assign(function QueryContent(props, ctx) {
42
+ const query = props.query;
43
+ const data = query.data;
44
+ if (data === undefined) {
45
+ if (query.status === 'error' && props.error)
46
+ return props.error(query.error);
47
+ return props.pending ?? ctx.slots.pending?.() ?? null;
48
+ }
49
+ if (data === null)
50
+ return props.missing ?? ctx.slots.missing?.() ?? null;
51
+ if (props.children)
52
+ return props.children(data);
53
+ return ctx.slots.default?.({ data }) ?? null;
54
+ },
55
+ // Declared so Vue extracts these from attrs instead of inheriting them onto
56
+ // whatever the branches render.
57
+ { props: ['query', 'children', 'pending', 'missing', 'error'] });
58
+ //# sourceMappingURL=query-content.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"query-content.js","sourceRoot":"","sources":["../src/query-content.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CACvC,SAAS,YAAY,CACnB,KAA2B,EAC3B,GAAoC;IAEpC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;IACzB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACvB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC5E,OAAO,KAAK,CAAC,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,IAAI,CAAA;IACvD,CAAC;IACD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,IAAI,CAAA;IACxE,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC/C,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,IAAI,CAAA;AAC9C,CAAC;AACD,4EAA4E;AAC5E,gCAAgC;AAChC,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAChE,CAAA"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * One API resource on the shared query cache. `createQueryResource` is
3
+ * framework-neutral, so it lives in `@molecule/app-query` (with its full
4
+ * documentation); this package re-exports it so Vue pages import it next to
5
+ * `useQuery` and `QueryContent`.
6
+ *
7
+ * @module
8
+ */
9
+ export type { QueryResource, QueryResourceConfig, ResourceHttp, ResourceResponse, } from '@molecule/app-query';
10
+ export { createQueryResource } from '@molecule/app-query';
11
+ //# sourceMappingURL=resource.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GACjB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * One API resource on the shared query cache. `createQueryResource` is
3
+ * framework-neutral, so it lives in `@molecule/app-query` (with its full
4
+ * documentation); this package re-exports it so Vue pages import it next to
5
+ * `useQuery` and `QueryContent`.
6
+ *
7
+ * @module
8
+ */
9
+ export { createQueryResource } from '@molecule/app-query';
10
+ //# sourceMappingURL=resource.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA"}