@gallopsystems/agent-skills 1.31.2 → 1.33.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 +24 -0
- package/package.json +1 -1
- package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +1 -1
- package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +5 -2
- package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +5 -0
- package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +5 -0
- package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +14 -3
- package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +15 -0
- package/plugins/generate-documentation/.claude-plugin/plugin.json +8 -0
- package/plugins/generate-documentation/skills/generate-documentation/SKILL.md +186 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/capture-example.mjs +53 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/render.mjs +82 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/shots.mjs +139 -0
- package/plugins/generate-documentation/skills/generate-documentation/formats.md +71 -0
- package/plugins/generate-documentation/skills/generate-documentation/templates/guide.html +116 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
- package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
- package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
- package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
- package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
- package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
- package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
- package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
- package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
- package/plugins/pr-review/skills/pr-review/judge.md +29 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
- package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +5 -1
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# Async UI state: loading, errors, stale responses, double submit
|
|
2
|
+
|
|
3
|
+
Every request a component makes has four outcomes the template must show
|
|
4
|
+
differently, can finish after the user has moved on, and can be fired twice. These
|
|
5
|
+
are the mistakes reviewers flag most often in component code. The fetch APIs
|
|
6
|
+
themselves (`useFetch` options, keys, SSR) are in `nuxt-nitro-api`'s
|
|
7
|
+
`fetch-patterns.md`; this file is about what the **component** does with them.
|
|
8
|
+
|
|
9
|
+
## Render four states, not two
|
|
10
|
+
|
|
11
|
+
`pending`, `error`, empty and data are four different screens. The common bug is
|
|
12
|
+
an `error` that falls through to the empty state, so a failed load reads as
|
|
13
|
+
"nothing here" (no invoices, no contacts, nothing scheduled). That is a false
|
|
14
|
+
statement, not a missing nicety.
|
|
15
|
+
|
|
16
|
+
```vue
|
|
17
|
+
<script setup lang="ts">
|
|
18
|
+
const { data: contacts, status, error, refresh } = await useFetch('/api/contacts')
|
|
19
|
+
</script>
|
|
20
|
+
|
|
21
|
+
<template>
|
|
22
|
+
<Skeleton v-if="status === 'idle' || status === 'pending'" />
|
|
23
|
+
<div v-else-if="error">
|
|
24
|
+
Couldn't load contacts. <button @click="refresh()">Retry</button>
|
|
25
|
+
</div>
|
|
26
|
+
<EmptyState v-else-if="!contacts?.length" title="No contacts yet" />
|
|
27
|
+
<ContactList v-else :contacts />
|
|
28
|
+
</template>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- **Check `error` before the empty branch**, and give it a Retry that calls `refresh()`.
|
|
32
|
+
- **`idle` comes before `pending`.** With `server: false` (or `immediate: false`)
|
|
33
|
+
the status is `'idle'` during the server render and until the request starts, so
|
|
34
|
+
a skeleton gated on `pending` alone doesn't appear on first render.
|
|
35
|
+
- **Unknown is not "no".** Don't derive a permission, a view or a "not found" from
|
|
36
|
+
data that is `undefined` because it is loading or failed. Treat that as unknown:
|
|
37
|
+
show loading or an error with Retry, never "access denied" or "not a member".
|
|
38
|
+
- **Unknown is not zero.** Pass `undefined` (and render a placeholder) to totals
|
|
39
|
+
and counters until their data has loaded; `data?.total ?? 0` shows a loading
|
|
40
|
+
screen as a real `$0.00`.
|
|
41
|
+
- **Load optional data separately.** If a secondary panel's request fails, show
|
|
42
|
+
its own error; don't let it blank the primary data (separate `useFetch` calls,
|
|
43
|
+
not one `Promise.all` that rejects as a whole).
|
|
44
|
+
- **Don't unmount the fetching component while it is pending.** A parent `v-if`
|
|
45
|
+
on the child's own loading state unmounts it, the remount refetches, and a
|
|
46
|
+
failing request loops. Keep the component mounted and let it show its own
|
|
47
|
+
loading and error states.
|
|
48
|
+
|
|
49
|
+
## `refresh()` does not throw: check `error` after awaiting it
|
|
50
|
+
|
|
51
|
+
`useFetch`/`useAsyncData`'s `refresh()`/`execute()` return `Promise<void>` and
|
|
52
|
+
**resolve even when the request fails**: the failure lands in `error`, `status`
|
|
53
|
+
becomes `'error'`, and `data` is reset to its default (`undefined` unless you
|
|
54
|
+
passed `default`). A `try/catch` around `await refresh()` never catches anything.
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
// ❌ proceeds with a failed (now undefined) invoice, or reports success
|
|
58
|
+
await refresh()
|
|
59
|
+
send(invoice.value!)
|
|
60
|
+
|
|
61
|
+
// ✅ (check status too: a refresh superseded by a newer one resolves with no error)
|
|
62
|
+
const id = props.invoiceId
|
|
63
|
+
await refresh()
|
|
64
|
+
if (error.value || status.value !== 'success' || id !== props.invoiceId) {
|
|
65
|
+
return toast({ title: "Couldn't reload the invoice", color: 'error' })
|
|
66
|
+
}
|
|
67
|
+
send(invoice.value!)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Same rule for anything that advances state after a refresh ("as of" timestamps,
|
|
71
|
+
step counters, polling cursors): only advance when `status.value === 'success'`.
|
|
72
|
+
|
|
73
|
+
## After a mutation: success only on success, refresh outside the try
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
const { toast } = useToast() // stands for your app's notifier; the call shape differs per UI library
|
|
77
|
+
async function save() {
|
|
78
|
+
if (saving.value) return // in-flight guard (see Double submit)
|
|
79
|
+
saving.value = true
|
|
80
|
+
try {
|
|
81
|
+
await $fetch(`/api/projects/${id}`, { method: 'PATCH', body: draft.value })
|
|
82
|
+
} catch (err: any) {
|
|
83
|
+
// keep the dialog open and the user's input; show the server's message
|
|
84
|
+
toast({ title: 'Save failed', description: err?.data?.message ?? 'Please try again.', color: 'error' })
|
|
85
|
+
return
|
|
86
|
+
} finally {
|
|
87
|
+
saving.value = false // always reset the loading flag
|
|
88
|
+
}
|
|
89
|
+
emit('saved') // only after the request succeeded
|
|
90
|
+
open.value = false
|
|
91
|
+
await refresh() // its failure is a refresh error, not a save error
|
|
92
|
+
if (error.value) toast({ title: 'Saved, but the list could not reload', color: 'error' })
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
- **Emit `saved`/close the dialog only on success.** On failure keep the editor
|
|
97
|
+
open with the unsaved input intact.
|
|
98
|
+
- **Reset loading flags in `finally`**, so an exception can't leave a spinner (and
|
|
99
|
+
a disabled button) on forever.
|
|
100
|
+
- **Surface the server's error message** (`err.data?.message` for a `$fetch`
|
|
101
|
+
`FetchError`) instead of replacing it with generic text; a conflict or validation
|
|
102
|
+
message is what the user needs.
|
|
103
|
+
- **Keep the follow-up `refresh()` outside the mutation's `try`.** Otherwise a
|
|
104
|
+
reload failure is reported as "save failed" and the user saves again.
|
|
105
|
+
- **Pick the success copy from the response.** If the endpoint can return a
|
|
106
|
+
partial or queued result, say so; don't print "Done" for every non-error.
|
|
107
|
+
For several requests in one save, report which part succeeded and refresh
|
|
108
|
+
anyway.
|
|
109
|
+
|
|
110
|
+
## Refresh every view of the data you changed
|
|
111
|
+
|
|
112
|
+
A mutation that only refreshes the list it started from leaves other components
|
|
113
|
+
showing the old value. Two ways to keep them in sync:
|
|
114
|
+
|
|
115
|
+
- **Share one keyed fetch.** `useFetch`/`useAsyncData` calls with the **same
|
|
116
|
+
explicit `key`** share the same `data`, `error` and `status` refs (Nuxt 4), so
|
|
117
|
+
one `refresh()` updates every component using that key. (Without an explicit
|
|
118
|
+
`key`, `useFetch` derives one from the URL and options, so only identical calls
|
|
119
|
+
share, and `useAsyncData` is keyed per call site. Name the key when sharing is
|
|
120
|
+
the intent.)
|
|
121
|
+
- **Or refresh by key from anywhere:** `await refreshNuxtData('price-list')`.
|
|
122
|
+
- **Or emit up:** a child that mutates emits `saved`/`updated`, and the parent
|
|
123
|
+
that owns the fetch handles it with `refresh()` for every list that shows the
|
|
124
|
+
changed data, not only the one the action came from.
|
|
125
|
+
|
|
126
|
+
Also: when a component receives a job or record through props that is still
|
|
127
|
+
running, start polling it there too, not only when the component started the job
|
|
128
|
+
itself.
|
|
129
|
+
|
|
130
|
+
## Stale responses: an older request must not overwrite newer state
|
|
131
|
+
|
|
132
|
+
The user switches records, reopens a dialog, types another search term or leaves
|
|
133
|
+
the page while a request is in flight. When it lands it writes to state that now
|
|
134
|
+
belongs to something else.
|
|
135
|
+
|
|
136
|
+
**Prefer `useFetch` with a reactive key or `query`.** Nuxt discards a superseded
|
|
137
|
+
response for the same key and, with the default `dedupe: 'cancel'`, aborts it. The
|
|
138
|
+
hand-rolled `$fetch` in a handler or watcher is where the bug lives.
|
|
139
|
+
|
|
140
|
+
For a watcher, abort the previous run with `onWatcherCleanup` (see
|
|
141
|
+
[watch.md](./watch.md#cancel-stale-work-with-onwatchercleanup)). For handlers,
|
|
142
|
+
dialogs and polling, use a **request token**: bump a counter on every start *and*
|
|
143
|
+
on every reset, close or unmount, and drop any response whose token is old.
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
let seq = 0
|
|
147
|
+
const results = ref<Result[]>([])
|
|
148
|
+
const loading = ref(false)
|
|
149
|
+
|
|
150
|
+
async function search(q: string) {
|
|
151
|
+
const mine = ++seq
|
|
152
|
+
loading.value = true
|
|
153
|
+
try {
|
|
154
|
+
const r = await $fetch('/api/search', { query: { q } })
|
|
155
|
+
if (mine !== seq) return // a newer search, a reset or a close happened
|
|
156
|
+
results.value = r
|
|
157
|
+
} finally {
|
|
158
|
+
if (mine === seq) loading.value = false // don't clear a newer run's flag
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
function reset() { seq++; results.value = []; loading.value = false }
|
|
162
|
+
onScopeDispose(() => seq++) // unmount invalidates in-flight work
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
- **Compare a token, not just the id.** Checking `id === props.id` after the await
|
|
166
|
+
misses A → B → A: the first A's response arrives after you are back on A and
|
|
167
|
+
overwrites the second.
|
|
168
|
+
- **Guard every write**, not only `data`: `status`, `error`, `loading`, toast and
|
|
169
|
+
"next poll" scheduling all go behind the same check.
|
|
170
|
+
- **Early-return paths that clear state must bump the token too**, or a request
|
|
171
|
+
started before the clear repopulates it.
|
|
172
|
+
- **Polling:** after each `await`, check you are still mounted and still following
|
|
173
|
+
the same job before scheduling the next tick. `useTimeoutPoll`/`useIntervalFn`
|
|
174
|
+
(VueUse) stop on unmount for you; the identity check is still yours. Bound the
|
|
175
|
+
number of failed polls before reporting the job as unknown, and treat a 401 as
|
|
176
|
+
"session ended", not "try again".
|
|
177
|
+
- **Key replays and pending sets by row id, never array index**; earlier
|
|
178
|
+
operations shift positions.
|
|
179
|
+
|
|
180
|
+
### Previous data stays visible while the next key loads
|
|
181
|
+
|
|
182
|
+
When a reactive key changes (a new month, a new record id), Nuxt 4 seeds the new
|
|
183
|
+
key's `data` with the **previous key's** value until the new request finishes, and
|
|
184
|
+
a plain `refresh()` keeps the current `data` until it is replaced. So `data` can
|
|
185
|
+
belong to the last selection. Hide it, or disable actions that act on it, until
|
|
186
|
+
`status.value === 'success'`:
|
|
187
|
+
|
|
188
|
+
```vue
|
|
189
|
+
<Button label="Close month" :disabled="status !== 'success'" @click="closeMonth" />
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### One `router.replace` per change
|
|
193
|
+
|
|
194
|
+
`useRoute()` updates only after a navigation finishes, so two
|
|
195
|
+
`router.replace({ query: { ...route.query, x } })` calls in a row both spread the
|
|
196
|
+
*old* query and the second overwrites the first. Merge every change into one call:
|
|
197
|
+
|
|
198
|
+
```ts
|
|
199
|
+
// ❌ clearFilter('customer'); clearFilter('property') — the second replace drops the first
|
|
200
|
+
router.replace({ query: { ...route.query, customer: undefined, property: undefined } })
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Double submit
|
|
204
|
+
|
|
205
|
+
Enter pressed twice, a double click or a slow network sends the same mutation
|
|
206
|
+
twice. Every mutating handler needs an in-flight guard, and its button is disabled
|
|
207
|
+
while it runs:
|
|
208
|
+
|
|
209
|
+
```ts
|
|
210
|
+
const saving = ref(false)
|
|
211
|
+
async function add() {
|
|
212
|
+
if (saving.value) return
|
|
213
|
+
saving.value = true
|
|
214
|
+
try { await $fetch('/api/items', { method: 'POST', body: { name: name.value } }) }
|
|
215
|
+
finally { saving.value = false }
|
|
216
|
+
}
|
|
217
|
+
// <Button :loading="saving" :disabled="saving" @click="add" />
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
- **The guard is in the handler**, not only `:disabled`: an Enter-key handler or a
|
|
221
|
+
second caller bypasses the button.
|
|
222
|
+
- **Track pending per item** with a `Set` of ids when each row has its own action;
|
|
223
|
+
a single shared `pendingId` lets a second row's click clear the first row's state.
|
|
224
|
+
- **IME:** the Enter that confirms an IME composition (Chinese, Japanese, Korean
|
|
225
|
+
input) also fires `keydown`. Ignore it in commit-on-Enter handlers:
|
|
226
|
+
`if (e.isComposing) return`.
|
|
227
|
+
- **Don't lose input typed during a save.** If the field stays editable, clear it
|
|
228
|
+
after the save only if it still holds the submitted value, or disable it while
|
|
229
|
+
the save runs.
|
|
@@ -136,6 +136,51 @@ and "or paste text" affordance. If you find yourself adding props just to toggle
|
|
|
136
136
|
caller-specific chrome inside the shared component, that chrome belongs in the
|
|
137
137
|
caller.
|
|
138
138
|
|
|
139
|
+
## One rule, one helper
|
|
140
|
+
|
|
141
|
+
When two places decide the same thing, they must call the same code. Reviewers
|
|
142
|
+
keep finding pairs that were written separately and drifted:
|
|
143
|
+
|
|
144
|
+
- a filter chip, its count and the status pill computed from **different fields**,
|
|
145
|
+
so the chips stop matching the rows;
|
|
146
|
+
- a status check re-implemented inline in one branch of a template while the
|
|
147
|
+
others use the shared `isCompleted(status)` helper;
|
|
148
|
+
- a preview ("this will send 4 lines") that subtracts different items than the
|
|
149
|
+
action that actually sends them;
|
|
150
|
+
- a confirm button's `:disabled` and the warning text beside it using two
|
|
151
|
+
different preconditions;
|
|
152
|
+
- a "Clear all" that resets a different list of filters than the "filters active"
|
|
153
|
+
check reads;
|
|
154
|
+
- a local fallback search that matches fewer fields than the remote search it
|
|
155
|
+
stands in for.
|
|
156
|
+
|
|
157
|
+
Put the rule in one `computed` or one function (in `app/utils` if several
|
|
158
|
+
components need it) and have every consumer read it:
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
const FILTERS = ['status', 'customer', 'sku'] as const
|
|
162
|
+
const hasActiveFilters = computed(() => FILTERS.some((k) => filters.value[k] != null))
|
|
163
|
+
function clearAll() { for (const k of FILTERS) filters.value[k] = null }
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Likewise, when a control claims to act on a group (a merged row, "select all"),
|
|
167
|
+
apply the action to every member, not just the first.
|
|
168
|
+
|
|
169
|
+
## Handle every shape of the data
|
|
170
|
+
|
|
171
|
+
- **Nullable fields:** filters, sorts and display guards must handle `null`
|
|
172
|
+
(a missing name, an absent city in an address, a range with only one end).
|
|
173
|
+
- **Exhaustive grouping:** when grouping rows by a parent (driver, owner, stage),
|
|
174
|
+
add a bucket for rows whose parent is missing or filtered out, or they vanish
|
|
175
|
+
from every group.
|
|
176
|
+
- **Stale page numbers:** a `?page=7` from the URL that is past the end after a
|
|
177
|
+
delete shows an empty page; clamp to the last page when `rows` is empty but
|
|
178
|
+
`total > 0`.
|
|
179
|
+
- **Fallback when the new shape is absent:** while migrating from a single field to
|
|
180
|
+
a list, fall back to the old field only when the list was never written
|
|
181
|
+
(`null`/`undefined`). An empty list means the user cleared it; falling back
|
|
182
|
+
there brings the old value back.
|
|
183
|
+
|
|
139
184
|
## Type off the server contract, don't hand-write DTOs
|
|
140
185
|
|
|
141
186
|
Derive prop/state types from the data you fetch rather than redeclaring an
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Forms, dialogs and drawers that edit a record
|
|
2
|
+
|
|
3
|
+
A component that edits a record holds a **local draft** copied from data it does
|
|
4
|
+
not own. Most review findings on these components are the same bug: the draft (or
|
|
5
|
+
something derived from it) still belongs to the *previous* record, the previous
|
|
6
|
+
opening, or the previous version of the data. This file is the rules for when to
|
|
7
|
+
seed, reset and re-sync that local state. For the request side (errors, stale
|
|
8
|
+
responses, double submit) see [async-state.md](./async-state.md).
|
|
9
|
+
|
|
10
|
+
## Seed when the identity changes, not once at setup
|
|
11
|
+
|
|
12
|
+
`setup` runs once. A dialog or drawer that stays mounted and is reopened for
|
|
13
|
+
another record, or a detail panel whose `id` prop changes, keeps the old draft
|
|
14
|
+
unless you re-seed. Two correct shapes:
|
|
15
|
+
|
|
16
|
+
**1. Remount per record (simplest).** Mount the form only while open, keyed by the
|
|
17
|
+
record id, so every opening starts from a clean `setup`:
|
|
18
|
+
|
|
19
|
+
```vue
|
|
20
|
+
<Drawer v-model:open="open">
|
|
21
|
+
<ProjectForm v-if="open && project" :key="project.id" :project @saved="onSaved" />
|
|
22
|
+
</Drawer>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
**2. Re-seed on open and on id change** when the component must stay mounted:
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
const draft = ref<Draft>(emptyDraft())
|
|
29
|
+
let seededFor: number | null = null // which record this opening was seeded from
|
|
30
|
+
watch(
|
|
31
|
+
[open, () => props.record?.id],
|
|
32
|
+
([isOpen]) => {
|
|
33
|
+
if (!isOpen) { seededFor = null; return }
|
|
34
|
+
// a refetch can drop the record and bring the same one back: don't re-seed then
|
|
35
|
+
if (!props.record || props.record.id === seededFor) return
|
|
36
|
+
seededFor = props.record.id
|
|
37
|
+
draft.value = toDraft(props.record) // every editable field, from the current record
|
|
38
|
+
previewResult.value = null // and every transient: preview, error, job, notice
|
|
39
|
+
},
|
|
40
|
+
{ immediate: true },
|
|
41
|
+
)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
- **Reset everything derived from the old record**, not only the form fields:
|
|
45
|
+
previews, generated output, validation errors, "copied" notices, an in-flight job
|
|
46
|
+
or poll, the selected tab. And invalidate requests still in flight for it (the
|
|
47
|
+
request-token pattern in [async-state.md](./async-state.md)).
|
|
48
|
+
- **Reset on close too** when a field is prefilled by the opener (a default date,
|
|
49
|
+
a pre-selected option), so the next opening doesn't reuse it.
|
|
50
|
+
- **Capture what the save needs at open time.** If the save sends an expected
|
|
51
|
+
version (optimistic concurrency), take it from the record when the editor opens,
|
|
52
|
+
not from the prop at submit time: a background refresh would otherwise update it
|
|
53
|
+
and silently overwrite someone else's change.
|
|
54
|
+
|
|
55
|
+
## Don't re-seed on every refetch of the source data
|
|
56
|
+
|
|
57
|
+
The opposite trap: a watcher on the fetched list or record that re-applies
|
|
58
|
+
defaults whenever the data reloads wipes what the user is typing. Seed on
|
|
59
|
+
**open** or **id change**. When the same record reloads while the user is
|
|
60
|
+
editing, keep their dirty fields and update only the untouched ones (or show a
|
|
61
|
+
"changed elsewhere" notice).
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
// ❌ re-picks the default whenever the list reloads, clobbering the user's choice
|
|
65
|
+
watch(agencies, (list) => { selected.value = list[0]?.id })
|
|
66
|
+
// ✅ default once per opening, as soon as the options exist; cleared on close
|
|
67
|
+
watch([open, agencies], ([isOpen, list]) => {
|
|
68
|
+
if (!isOpen) { selected.value = undefined; return }
|
|
69
|
+
selected.value ??= list?.[0]?.id
|
|
70
|
+
}, { immediate: true })
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Seed every field; send what changed
|
|
74
|
+
|
|
75
|
+
- **Seed the draft from all of the record's current values.** A form that starts
|
|
76
|
+
from an empty object and is saved with `PUT`/full-object `PATCH` clears every
|
|
77
|
+
field it didn't show.
|
|
78
|
+
- **Send only the fields the user edited** when other people (or other tabs) can
|
|
79
|
+
edit the same record, so stale values in untouched fields don't overwrite their
|
|
80
|
+
changes. Diff the draft against the snapshot you seeded from.
|
|
81
|
+
- **Compute dirty state the same way:** compare editable fields to the seeded
|
|
82
|
+
snapshot, not "the update payload is valid" or "a field was focused".
|
|
83
|
+
- **While the form is dirty, disable actions that read the saved record** (create
|
|
84
|
+
something from it, send it, export it); a notice alone isn't enough.
|
|
85
|
+
- **Enforce required fields in the handler or `:disabled`**, not only with a
|
|
86
|
+
required marker on the label.
|
|
87
|
+
|
|
88
|
+
## Local copies of props must follow the prop
|
|
89
|
+
|
|
90
|
+
A `const isAdmin = ref(props.user.is_admin)` is a snapshot: it never sees the
|
|
91
|
+
refreshed user. Derive it with `computed(() => props.user.is_admin)`, or, when it
|
|
92
|
+
is a user-editable draft, re-seed it as above. See the `prop-sync` smell in
|
|
93
|
+
[watch.md](./watch.md).
|
|
94
|
+
|
|
95
|
+
An input component that keeps its own text buffer (to allow partial typing like
|
|
96
|
+
`"1."`) must reset that buffer when the parent sets the model to `null` or a new
|
|
97
|
+
value from outside; otherwise it shows text that no longer matches the model.
|
|
98
|
+
|
|
99
|
+
## Options that disappear, URLs that change
|
|
100
|
+
|
|
101
|
+
- **A selection must survive its options changing.** When the selected tab, filter
|
|
102
|
+
value or option is no longer in the available list (permissions, a reload, a
|
|
103
|
+
deep link to a hidden tab), fall back to the first valid one instead of rendering
|
|
104
|
+
an empty or misleading view:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
const activeTab = computed(() =>
|
|
108
|
+
tabs.value.some((t) => t.id === requested.value) ? requested.value : tabs.value[0]?.id)
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
- **State mirrored in the URL must follow the URL both ways.** A search box seeded
|
|
112
|
+
once from `route.query.q` drifts when the user navigates back. Bind it with
|
|
113
|
+
`useRouteQuery` or a writable computed over the query (see [vueuse.md](./vueuse.md)),
|
|
114
|
+
and write restored state (saved columns, a restored tab) back to the URL so a
|
|
115
|
+
shared link shows the same thing.
|
|
116
|
+
- **"Clear filters" resets every filter**, including ones that live in the parent
|
|
117
|
+
or the URL. Build the clear action and the "filters active" check from the same
|
|
118
|
+
list of filter sources (see "One rule, one helper" in
|
|
119
|
+
[component-authoring.md](./component-authoring.md)).
|
|
120
|
+
- **Dependent defaults follow their source.** When a mode, period or type changes,
|
|
121
|
+
re-apply the defaults and bounds that depend on it (date bounds for a school
|
|
122
|
+
year, defaults for an entry type) in that control's change handler, keeping
|
|
123
|
+
unrelated input.
|
|
124
|
+
|
|
125
|
+
## Per-item drafts that must survive switching
|
|
126
|
+
|
|
127
|
+
If the user switches between items (cases, conversations) and expects an
|
|
128
|
+
unfinished draft to still be there, keep a draft per item id (a `Map` keyed by id,
|
|
129
|
+
or one composer per item under `<KeepAlive>` keyed by id) instead of one shared
|
|
130
|
+
draft that the next item overwrites.
|
|
131
|
+
|
|
132
|
+
## Time is not reactive
|
|
133
|
+
|
|
134
|
+
`new Date()` in a `computed` is evaluated once and never again, so "today",
|
|
135
|
+
"overdue" or "starts in 5 min" stays frozen on a page left open. Derive from a
|
|
136
|
+
reactive clock: `const now = useNow({ interval: 60_000 })` (VueUse) and read
|
|
137
|
+
`now.value` in the computed.
|
|
@@ -82,6 +82,14 @@ renders as the *previous day* in any negative-offset timezone. Format date-only
|
|
|
82
82
|
strings with `parseISO` (which treats them as local), never `new Date`, and don't
|
|
83
83
|
let a blanket "convert all date fields to Date" transform touch DATE columns.
|
|
84
84
|
|
|
85
|
+
**Today as a date-only string is a local date.** `new Date().toISOString().slice(0, 10)`
|
|
86
|
+
is the **UTC** date, which is tomorrow for an evening user west of UTC. Use
|
|
87
|
+
`format(new Date(), 'yyyy-MM-dd')` (date-fns formats in local time), or your
|
|
88
|
+
app's time-zone-aware formatter. During SSR "local" is the **server's** zone, so a
|
|
89
|
+
date computed there can differ from the browser's and mismatch on hydration: use an
|
|
90
|
+
explicit time zone on both sides, or compute it after mount. Likewise, convert a UTC timestamp to the display
|
|
91
|
+
time zone *before* taking its calendar day.
|
|
92
|
+
|
|
85
93
|
## Where to put the formatters
|
|
86
94
|
|
|
87
95
|
Pick the location by what the formatter needs (the composable-vs-util decision
|
|
@@ -104,6 +104,22 @@ iterating, state) while the caller decides *presentation*.
|
|
|
104
104
|
(In a template you can also test `$slots.footer` directly.) Without the guard
|
|
105
105
|
you ship an empty `<footer>` whose padding/border still affects layout.
|
|
106
106
|
|
|
107
|
+
## Conditions go on the content, not the slot
|
|
108
|
+
|
|
109
|
+
Put `v-if` on the elements **inside** one `<template #actions>`, not on the
|
|
110
|
+
`<template>` itself. A `v-if` on the slot template removes the whole slot
|
|
111
|
+
(everything else you meant to put in it disappears too), and a slot name can have
|
|
112
|
+
only one `<template>` (except as a `v-if`/`v-else` chain), so a second
|
|
113
|
+
conditional `<template #actions>` is not a way to add one more button.
|
|
114
|
+
|
|
115
|
+
```vue
|
|
116
|
+
<!-- ❌ <template v-if="canEdit" #actions><EditButton /></template> — help button lost when !canEdit -->
|
|
117
|
+
<template #actions>
|
|
118
|
+
<EditButton v-if="canEdit" />
|
|
119
|
+
<HelpButton />
|
|
120
|
+
</template>
|
|
121
|
+
```
|
|
122
|
+
|
|
107
123
|
## Forwarding & splitting slots
|
|
108
124
|
|
|
109
125
|
- **Forward** a slot through a wrapper so the inner component receives it:
|
|
@@ -60,6 +60,50 @@ useHead({ title: 'Invoices' }) // page
|
|
|
60
60
|
// app.vue: useHead({ titleTemplate: (t) => (t ? `${t} · Acme` : 'Acme') })
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
+
**A title that depends on fetched data needs a getter.** A plain value is read once
|
|
64
|
+
at setup, so it shows the fallback (or the previous record's name) and never
|
|
65
|
+
updates when the data arrives or the route param changes:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
const { data: project } = await useFetch(() => `/api/projects/${route.params.id}`)
|
|
69
|
+
useHead({ title: () => project.value?.name ?? 'Project' }) // not: title: project.value?.name
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Keyboard and screen-reader access for custom controls
|
|
73
|
+
|
|
74
|
+
Native `<button>`, `<a href>` and form controls are focusable and keyboard-operable
|
|
75
|
+
for free. Anything else you make clickable is not. The recurring review findings:
|
|
76
|
+
|
|
77
|
+
- **A clickable `<div>`/`<td>`/chart mark** (a calendar day, a row, a bar) needs a
|
|
78
|
+
keyboard path. Prefer a real `<button>` or `<NuxtLink>` inside it; otherwise add
|
|
79
|
+
`role="button"`, `tabindex="0"` and `@keydown.enter`/`@keydown.space.prevent`.
|
|
80
|
+
If a mouse click navigates, keyboard users need the same link.
|
|
81
|
+
- **Tooltip triggers** on non-focusable elements (a truncated `<span>`, an icon)
|
|
82
|
+
need `tabindex="0"`, or keyboard users never see the tooltip.
|
|
83
|
+
- **Icon-only buttons** need an accessible name: `aria-label="Refresh"`.
|
|
84
|
+
- **Never remove the focus outline** (`outline-none`) without a
|
|
85
|
+
`focus-visible:` replacement, including on panels you focus programmatically.
|
|
86
|
+
- **Don't cancel a popover's or dialog's initial focus** (e.g. `@open-auto-focus.prevent`)
|
|
87
|
+
without moving focus into the panel yourself.
|
|
88
|
+
- **Visually hidden links** (skip links, `sr-only` lists) must become visible on
|
|
89
|
+
focus: `sr-only focus:not-sr-only`.
|
|
90
|
+
- **Global keyboard shortcuts must ignore typing.** Return early when the event
|
|
91
|
+
comes from an input, textarea, select or contenteditable element:
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
function onKey(e: KeyboardEvent) {
|
|
95
|
+
const t = e.target as HTMLElement
|
|
96
|
+
if (t.isContentEditable || t.closest('input, textarea, select')) return
|
|
97
|
+
// …handle the shortcut
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Copy that adapts to the data: hide or pluralize count sentences for 0 and 1
|
|
102
|
+
("All 0 other charges…" is a bug); when a list is capped, say how many were
|
|
103
|
+
omitted; truncate only the variable text and keep qualifiers (a note, a badge) in a
|
|
104
|
+
non-shrinking element (`shrink-0`) beside it; let filter rows wrap (`flex-wrap
|
|
105
|
+
min-w-0`) instead of forcing `whitespace-nowrap` that overflows.
|
|
106
|
+
|
|
63
107
|
## Reset a file input after reading it
|
|
64
108
|
|
|
65
109
|
`<input type="file">` won't re-fire `change` for the same file twice — clear it
|
|
@@ -80,6 +124,14 @@ const SEV: Record<Status, string> = { paid: 'success', overdue: 'danger' }
|
|
|
80
124
|
const sev = (s: Status) => SEV[s] || 'secondary'
|
|
81
125
|
```
|
|
82
126
|
|
|
127
|
+
## `v-if` on a derived value doesn't narrow the original
|
|
128
|
+
|
|
129
|
+
vue-tsc narrows `user.email` inside `v-if="user.email"`, but not inside
|
|
130
|
+
`v-if="hasEmail"` where `hasEmail` is a `computed` over it: TypeScript can't see
|
|
131
|
+
the link. Test the nullable value itself in the template (or use `?.`/`??`), and
|
|
132
|
+
annotate computed object literals with their declared type so literal fields
|
|
133
|
+
aren't widened to `string`.
|
|
134
|
+
|
|
83
135
|
## `v-bind` same-name shorthand
|
|
84
136
|
|
|
85
137
|
When a bound attribute matches the variable name (Vue 3.4+), drop the value —
|
|
@@ -97,7 +97,8 @@ and give it no `withDefaults` default.
|
|
|
97
97
|
|
|
98
98
|
To reset transient state or lazy-load when a dialog opens, **watch the bound
|
|
99
99
|
flag** (it covers every close path — overlay click, ESC, programmatic) — see the
|
|
100
|
-
"re-seed local state on dialog open" case in [watch.md](./watch.md).
|
|
100
|
+
"re-seed local state on dialog open" case in [watch.md](./watch.md). For what to reset and when
|
|
101
|
+
not to re-seed, see [editing-forms.md](./editing-forms.md).
|
|
101
102
|
|
|
102
103
|
## Consistency caveat
|
|
103
104
|
|
|
@@ -80,8 +80,12 @@ Only when the effect crosses **out of** the reactive graph:
|
|
|
80
80
|
(see `vueuse.md`); a compound guard keeps its inner half —
|
|
81
81
|
`watch(visible, (v) => { if (v && !props.x) reset() })` →
|
|
82
82
|
`whenever(visible, () => { if (!props.x) reset() })`.
|
|
83
|
+
Key it on the record id too (`watch([visible, () => props.record?.id], …)`) and
|
|
84
|
+
reset every transient, not only the fields: see [editing-forms.md](./editing-forms.md).
|
|
83
85
|
- **Clone a server prop into a locally-editable draft** —
|
|
84
|
-
`watch(() => props.record, (
|
|
86
|
+
`watch(() => props.record?.id, () => { if (props.record) form.value = structuredClone(toRaw(props.record)) }, { immediate: true })`.
|
|
87
|
+
Watch the **id**, not the record: a refetch replaces the object for the same id and
|
|
88
|
+
would clone it over unsaved edits (see [editing-forms.md](./editing-forms.md)).
|
|
85
89
|
|
|
86
90
|
> **Before hand-rolling the external-world cases, check VueUse.** Most of the
|
|
87
91
|
> bullets above (DOM, timers, persist, URL) are exactly what VueUse wraps — and a
|