@gallopsystems/agent-skills 1.32.0 → 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.
Files changed (35) hide show
  1. package/README.md +11 -0
  2. package/package.json +1 -1
  3. package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
  4. package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
  5. package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
  6. package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
  7. package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
  8. package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
  9. package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
  10. package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
  11. package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
  12. package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
  13. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
  14. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
  15. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
  16. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
  17. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
  18. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
  19. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
  20. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
  21. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
  22. package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
  23. package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
  24. package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
  25. package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
  26. package/plugins/pr-review/skills/pr-review/judge.md +29 -0
  27. package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
  28. package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
  29. package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
  30. package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
  31. package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
  32. package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
  33. package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
  34. package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
  35. 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, (r) => { if (r) form.value = structuredClone(toRaw(r)) }, { immediate: true })`.
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