npm - @gallopsystems/agent-skills - Versions diffs - 1.4.0 → 1.6.0 - Mend

@gallopsystems/agent-skills 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md ADDED Viewed

@@ -0,0 +1,142 @@
+# Template & vue-tsc idioms
+Smaller Vue-shaped template patterns and the compile errors they prevent.
+## Never two handlers of the same event on one element
+Two `@keyup.*` (or two `@keydown.*`) modifier handlers on one element both compile
+to a single `onKeyup` object property → vue-tsc fails with **TS1117 "duplicate
+property"**, and only one wires up at runtime. Use a single handler and branch:
+```vue
+<!-- ❌ <input @keyup.enter="submit" @keyup.esc="cancel" /> -->
+<input @keyup="onKey" />
+<!-- function onKey(e) { if (e.key === 'Enter') submit(); else if (e.key === 'Escape') cancel() } -->
+```
+## Scoped-CSS reach: `:deep()`, `:slotted()`, `:global()`
+Scoped CSS adds a data attribute that only matches the component's own elements.
+Three pseudo-selectors reach past that boundary:
+```vue
+<style scoped>
+.prose :deep(table) { @apply w-full; } /* child/3rd-party-rendered HTML (markdown, rich text) */
+:slotted(p) { @apply mt-2; }            /* content the PARENT passed into a <slot> */
+:global(body) { @apply antialiased; }   /* escape scope to a global rule */
+</style>
+```
+`:deep()` for descendants the component renders dynamically, `:slotted()` for
+slot content the caller supplied (scoped styles don't reach it by default), and
+`:global()` for the occasional global rule without a second `<style>` block.
+## Click-outside: match a unique marker class
+Scope document click-outside detection to a **purpose-named marker class** added
+solely for it — never `target.closest('.relative.flex')` or other structural
+Tailwind selectors that silently match unrelated elements:
+```vue
+<div class="send-menu relative …">
+<!-- if (!e.target.closest('.send-menu')) close() -->
+```
+## `<NuxtLink>` and a thin `app.vue`
+Use `<NuxtLink to="…">` for internal navigation (client routing + prefetch), not a
+raw `<a>`. Keep `app.vue` a thin shell — `<NuxtLayout><NuxtPage /></NuxtLayout>`
+plus app-global hosts (a `<Toast />`, a confirm dialog). `NuxtLink`/`NuxtLayout`/
+`NuxtPage` are auto-imported.
+## Per-page `<head>` with `useHead`
+Set the document title/head reactively and SSR-safely with `useHead` in
+`<script setup>` — never `document.title`. Set a default in `app.vue` and override
+per page:
+```ts
+useHead({ title: 'Invoices' })            // page
+// app.vue: useHead({ titleTemplate: (t) => (t ? `${t} · Acme` : 'Acme') })
+```
+## Reset a file input after reading it
+`<input type="file">` won't re-fire `change` for the same file twice — clear it
+after handling so re-selecting the same file works:
+```ts
+function onFile(e: Event) { const t = e.target as HTMLInputElement; /* …read t.files… */ t.value = '' }
+```
+## Status → label/severity lookup
+Map enums to labels/severities with a small `Record` lookup + `||` fallback,
+called as a plain function (functions, not `computed`, when they take a per-row
+argument):
+```ts
+const SEV: Record<Status, string> = { paid: 'success', overdue: 'danger' }
+const sev = (s: Status) => SEV[s] || 'secondary'
+```
+## `v-bind` same-name shorthand
+When a bound attribute matches the variable name (Vue 3.4+), drop the value —
+`:src` expands to `:src="src"`. Terser, and worth recognizing when reading code:
+```vue
+<img :src :alt />   <!-- ≡ :src="src" :alt="alt" -->
+```
+## `useId()` for stable, SSR-safe element IDs
+Wiring `<label for>` / `aria-describedby` needs an ID that's stable across SSR and
+hydration — a hand-rolled counter or `Math.random()` causes a hydration mismatch.
+`useId()` (Vue 3.5, auto-imported) gives an app-unique, hydration-stable ID:
+```ts
+const id = useId()   // <label :for="id">Email</label> <input :id :aria-describedby="`${id}-help`">
+```
+## `<Teleport>` overlays out to `body`
+Render modals/dropdowns/toasts to `<body>` so they escape a parent's
+`overflow: hidden`, `z-index`, or `transform` stacking context (the usual cause of
+a dialog clipped inside a scrolling panel):
+```vue
+<Teleport to="body"><div class="modal">…</div></Teleport>
+```
+`<Teleport>` is auto-imported. (Volt/PrimeVue overlays already teleport
+internally; this is for your own hand-rolled overlays.)
+## `<KeepAlive>` caches toggled-component state
+Wrap a dynamic `<component>`/`v-if` swap in `<KeepAlive>` to preserve a toggled
+child's state (a half-filled form, scroll position) instead of remounting it.
+Teardown gotcha: a cached component fires `onActivated`/`onDeactivated`, **not**
+`onMounted`/`onUnmounted` — put pause/resume logic there, not in the mount hooks:
+```vue
+<KeepAlive :include="['EditForm']"><component :is="currentTab" /></KeepAlive>
+```
+## `v-memo` / `v-once` for expensive render subtrees
+Declarative render-skipping for big lists/tables. `v-once` renders a subtree once
+and never updates it; `v-memo="[deps]"` skips a `v-for` row's re-render unless a
+dep changes. Reach for these only when a large grid actually shows up in a profile
+— not by default.
+```vue
+<div v-for="row in rows" :key="row.id" v-memo="[row.id === selectedId]">…</div>
+```
+## One-off caveats (not general conventions)
+These surfaced once each — apply only if they bite, don't treat as rules:
+- **Confirm which motion library is installed** before animating: `motion-v` uses the component API (`<motion.div :initial :animate>`), while `@vueuse/motion` uses the `v-motion` directive (`:visible-once`). They're different packages.
+- **A parent's `whitespace-nowrap`** (common on table `th`/`td`) is inherited by a child tooltip/popover and forces it onto one overflowing line — reset with `whitespace-normal break-words` on the bubble.

package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md ADDED Viewed

@@ -0,0 +1,106 @@
+# `v-model` on components
+Two sanctioned patterns for two-way binding. Default to `defineModel` for new
+code; the computed-proxy is for forwarding an existing component's model.
+## `defineModel` — preferred (Vue 3.4+ / Nuxt 4)
+```ts
+const model = defineModel<boolean>()                              // parent: v-model
+const visible = defineModel<boolean>('visible', { required: true }) // parent: v-model:visible
+```
+Read/write `model.value` directly — no `props` + `emit` boilerplate. Give
+non-primitive models a factory default like any prop.
+**Named models** give one component multiple independent two-way bindings:
+```ts
+const years = defineModel<string>('years')
+const months = defineModel<string>('months')
+// parent: <DurationInput v-model:years="y" v-model:months="m" />
+```
+**Transform on the boundary with `get`/`set`.** For a component's *own* model,
+`defineModel` takes `get`/`set` transformers directly — no separate writable
+`computed` needed (reserve that for forwarding *someone else's* model, below):
+```ts
+const model = defineModel<string>({ get: (v) => v.toUpperCase(), set: (v) => v.trim() })
+```
+**Custom `v-model` modifiers** (`v-model.capitalize`) arrive via the
+`[model, modifiers]` tuple:
+```ts
+const [model, modifiers] = defineModel<string>({
+  set: (v) => (modifiers.capitalize ? v[0].toUpperCase() + v.slice(1) : v),
+})
+```
+## The computed-proxy — for forwarding an existing model
+When you wrap a component that already has its own `v-model` (a Volt/PrimeVue
+`Dialog`'s `visible`, say), or you need a named local handle or a value
+transform, use a writable `computed` over `props` + `emit`:
+```ts
+const props = defineProps<{ visible: boolean }>()
+const emit = defineEmits<{ 'update:visible': [v: boolean] }>()
+const visible = computed({ get: () => props.visible, set: (v) => emit('update:visible', v) })
+//   <Dialog v-model:visible="visible" />
+```
+A `computed({ get, set })` transforms a *forwarded* value shape (date string ↔
+`Date`) before writing back — for a component's **own** model, prefer
+`defineModel`'s `get`/`set` (above) over a separate computed. Either way, do NOT
+reach for two mirror `watch`es to do this; that's the `prop-sync` smell (see
+[watch.md](./watch.md)).
+## Mutually-exclusive paired fields
+When setting one field must clear its sibling, expose **two** typed `update:`
+events and bind the inner widget with `:modelValue` + `@update:modelValue` (NOT
+`v-model`) so your handler can emit one update and null the other in the same tick:
+```ts
+const emit = defineEmits<{ 'update:years': [v: string | null]; 'update:months': [v: string | null] }>()
+function setYears(v: string) { emit('update:years', v); emit('update:months', null) }
+```
+A single `v-model` can't express "set A, clear B" atomically.
+## Controlled / uncontrolled: work standalone OR be parent-driven
+For a component that should manage its own state **unless** a parent supplies the
+value (a toggle that works alone but a parent can override), detect whether the
+control prop was passed and fall back to internal state per render:
+```ts
+const props = defineProps<{ open?: boolean }>()        // undefined ⇒ uncontrolled
+const emit = defineEmits<{ 'update:open': [v: boolean] }>()
+const internal = ref(false)
+const controlled = computed(() => props.open !== undefined)
+const open = computed(() => (controlled.value ? props.open! : internal.value))
+function toggle() {
+  if (controlled.value) emit('update:open', !props.open)
+  else internal.value = !internal.value
+}
+```
+This relies on `undefined` meaning "unset", so the control prop must **not** be a
+bare `boolean` (the Boolean-casting trap coerces absent → `false`; see
+[component-authoring.md](./component-authoring.md)) — type it `boolean | undefined`
+and give it no `withDefaults` default.
+## Reset / lazy-load on open
+To reset transient state or lazy-load when a dialog opens, **watch the bound
+flag** (it covers every close path — overlay click, ESC, programmatic) — see the
+"re-seed local state on dialog open" case in [watch.md](./watch.md).
+## Consistency caveat
+A repo with hundreds of `props`+`emit`+`computed` `v-model`s and zero
+`defineModel` means matching the manual pattern in that file. Introduce
+`defineModel` deliberately, not as a drive-by in an otherwise-consistent file.

package/plugins/vue-nuxt/skills/vue-nuxt/watch.md ADDED Viewed

@@ -0,0 +1,194 @@
+# `watch` — the escape hatch, not the default
+`watch` reactively performs **side effects**. It is not for deriving values —
+that's `computed`. Heavy `watch` use is usually a `computed`, a *writable*
+`computed`, a `defineModel`, or an event handler in disguise.
+**Rule of thumb:** read the watcher body. If it ends by assigning one reactive
+value from others and nothing leaves Vue's world (no fetch, DOM, third-party lib,
+storage, URL), delete it and write a `computed`.
+> Grounded in a 159-watcher audit across 7 Nuxt apps: **77% were legitimate, ~9%
+> clear smells, ~14% borderline.** The smells clustered into the four shapes
+> below; over half the *borderline* cases were one pattern ("reset a field in a
+> watcher"). The legit cases are real — the trap is using `watch` for what the
+> framework already does declaratively.
+## Writing a value back? Use a writable `computed`, not a watch
+The most common reason people reach for `watch` is to *write a value back* —
+mirror a prop, transform a bound value, proxy a child's `v-model`. A `computed`
+can have a setter; use it.
+```ts
+// ❌ two watches mirroring a prop both ways — desyncs, pure boilerplate
+const visible = ref(props.visible)
+watch(() => props.visible, (v) => (visible.value = v))
+watch(visible, (v) => emit('update:visible', v))
+// ✅ writable computed — one source of truth, genuinely two-way
+const visible = computed({
+  get: () => props.visible,
+  set: (v) => emit('update:visible', v),
+})
+// ✅ or, for a component's OWN model: const visible = defineModel<boolean>('visible')
+```
+A writable `computed` also transforms a value across the boundary (string ↔ Date):
+```ts
+const date = computed({
+  get: () => parseISO(model.value),
+  set: (d) => (model.value = d.toISOString()),
+})
+```
+(Both getter and setter receive the previous value as their first argument if you
+need it.)
+Two rules from the Vue docs that keep this correct:
+- **Getters must be side-effect-free.** A `computed` getter only derives and
+  returns — no mutating other state, no async, no DOM. Side effects *in reaction
+  to* a change are what `watch` is for.
+- **A computed value is a read-only snapshot.** Never mutate what a `computed`
+  returns; update the *source* state it derives from and let a new snapshot be
+  produced.
+## When `watch` IS the right tool
+Only when the effect crosses **out of** the reactive graph:
+- **Fetch on a changing key** — prefer a reactive `useFetch` `query`/key (it
+  auto-refetches; see `nuxt-nitro-api/fetch-patterns.md`). Reach for `watch` only
+  for imperative `$fetch` keyed off a single id.
+- **Drive a non-Vue library** — Tiptap, a Leaflet/Google map, a signature canvas,
+  a PrimeVue popover you `.hide()` imperatively.
+- **DOM / timers** — `document.body.style.overflow`, a debounce `setTimeout`, a
+  polling `setInterval` (clear it in `onUnmounted`).
+- **Persist** — a `localStorage`/`useCookie` write, debounced auto-save of a
+  deep-watched form.
+- **URL sync** — `router.replace({ query: { ...route.query, tab } })`.
+- **Re-seed local state on dialog open** — `watch(visible, (v) => { if (v) initForm() })`.
+  The single most common legit pattern.
+- **Clone a server prop into a locally-editable draft** —
+  `watch(() => props.record, (r) => { if (r) form.value = structuredClone(toRaw(r)) }, { immediate: true })`.
+### Cancel stale work with `onWatcherCleanup`
+A watcher that starts async work (a keyed `$fetch`, a timer) must cancel the
+previous run, or out-of-order responses clobber state — the #1 correctness bug in
+keyed-fetch watchers. Vue 3.5's `onWatcherCleanup(fn)` registers teardown that
+runs before the next fire and on stop:
+```ts
+import { onWatcherCleanup } from 'vue'
+watch(query, async (q) => {
+  const ctrl = new AbortController()
+  onWatcherCleanup(() => ctrl.abort())   // abort the in-flight request if q changes again
+  results.value = await $fetch('/api/search', { query: { q }, signal: ctrl.signal })
+})
+```
+Gotcha: `onWatcherCleanup` only registers **synchronously, before the first
+`await`**. For teardown decided after an await, use the callback's third arg
+instead — `watch(src, (v, _old, onCleanup) => { … onCleanup(fn) })`.
+### `flush: 'post'` runs the callback after the DOM patches
+When a watcher reacts to a change by reading/scrolling the **updated** DOM, give
+it `{ flush: 'post' }` so it runs after Vue patches — no manual `await nextTick()`.
+They're ~one microtask apart and interchangeable; pick by clarity (prefer
+`flush: 'post'` for an effect that *reacts to reactive change*, `nextTick` for a
+one-shot after an imperative toggle).
+```ts
+watch(activeId, () => scrollActiveIntoView(), { flush: 'post' })  // DOM already updated
+```
+## Smell catalog (with refactors)
+| Smell | Tell | Reach for |
+|---|---|---|
+| **derive-state** | body assigns a filtered/mapped view into another ref | `computed` |
+| **prop-sync** | local `ref(props.x)` kept in sync by a watch (often + a 2nd watch emitting back) | `defineModel` or a writable `computed` |
+| **side-effect-in-handler** | watching a value that only changes via one control, to clear a dependent field | that control's `@update:model-value` handler |
+| **manual-refetch** | watching filter refs to call a function that calls `useFetch` | a `computed` `query` passed to `useFetch` |
+The biggest real cluster was **side-effect-in-handler** — resetting dependent
+fields when a Select changed. In a watcher it hides cause/effect and re-fires on
+programmatic form reseeds; the colocated handler is direct and only fires on the
+user action:
+```ts
+// ❌ watch(() => form.entityType, () => { form.eventType = ''; form.conditionValue = null })
+// ✅
+function onEntityType(v) { form.entityType = v; form.eventType = ''; form.conditionValue = null }
+//   <Select v-model="form.entityType" @update:model-value="onEntityType" />
+```
+Watch for **cascades** — a chain of watches each resetting the next (entityType →
+eventType → conditionProperty) is just a chain of handlers, far harder to follow.
+**Borderline tell — `seed-via-immediate`:** `watch(asyncList, (l) => { if (!local.value) local.value = pick(l) }, { immediate: true })` to default a *user-mutable* ref from fetched data is defensible (a pure `computed` can't be user-overridden) — but keep the `!local.value` guard so a refetch doesn't clobber an in-progress edit.
+## `deep: true` is expensive — use it sparingly
+A deep watch traverses **every** nested property of the watched object on each
+check, so it gets costly on large structures. Before reaching for it:
+- **Watch a getter of the specific field** instead of the whole object:
+  `watch(() => form.address.zip, ...)` rather than `watch(form, ..., { deep: true })`.
+- If you genuinely need to react to *any* field of a form (e.g. debounced
+  auto-save), a deep watch is legitimate — but scope it as tightly as you can.
+- For deriving from a few keys of a nested object, a `computed` (or `watchEffect`)
+  tracks **only the keys actually read**, avoiding the full traversal a deep watch
+  pays for.
+**Deep-watch aliasing trap:** in a deep watch the callback's `oldValue` and
+`newValue` are the **same reference** (Vue mutated the object in place), so you
+*cannot* diff old-vs-new inside the callback — `if (next.x !== prev.x)` is always
+false. Watch a derived getter instead, so old/new are distinct primitives:
+```ts
+// ❌ watch(items, (next, prev) => { if (next.length !== prev.length) … }, { deep: true })  // never fires
+// ✅ watch(() => items.value.length, (next, prev) => { if (next > prev) onAdded() })
+```
+## `watch` vs `watchEffect`
+Both run side effects reactively; they differ in how they **track dependencies**:
+- **`watch(source, cb)`** tracks ONLY the explicit source, fires lazily and only
+  when it *actually changed*, and hands you **old + new** values. Use it when you
+  want precise control over what fires the effect, need the previous value, or
+  want it lazy.
+- **`watchEffect(cb)`** runs immediately and auto-tracks every reactive property
+  read during its **synchronous** execution. Terser, and it removes the burden of
+  maintaining a source list — genuinely better for a side effect with **several**
+  dependencies, or one reading a few keys of a nested object (it tracks only
+  what's used, unlike a `deep` watch).
+```ts
+// watch: todoId named twice (source + inside callback)
+watch(todoId, async () => { data.value = await $fetch(`/api/todos/${todoId.value}`) }, { immediate: true })
+// watchEffect: todoId.value is both the read and the tracked dep — no immediate flag, no repeated source
+watchEffect(async () => { data.value = await $fetch(`/api/todos/${todoId.value}`) })
+```
+Two cautions on `watchEffect`:
+- **Async tracking gotcha:** it only tracks deps accessed **before the first
+  `await`**. Read a ref *after* an `await` and it silently won't re-trigger on
+  that ref. With multiple async deps, read them all up front or use an explicit
+  `watch`.
+- **It tempts the derive-state smell.** Because it runs immediately and
+  auto-tracks, `watchEffect` is the most common home for "compute and assign" —
+  which is a `computed`. The *only* `watchEffect` smell in the audit was exactly
+  this: `watchEffect(() => { orgField.options = organizations.value })` → should
+  be a `computed` that maps the field list.
+Default: **`computed` for derivation, `watch` for a precise single-source effect,
+`watchEffect` for a genuine multi-dependency side effect** whose deps are all read
+synchronously.