agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-fallthrough-attrs.md

@@ -0,0 +1,174 @@
+---
+title: Component Fallthrough Attributes Best Practices
+impact: MEDIUM
+impactDescription: Incorrect $attrs access and reactivity assumptions can cause undefined values and watchers that never run
+type: best-practice
+tags: [vue3, attrs, fallthrough-attributes, composition-api, reactivity]
+---
+
+# Component Fallthrough Attributes Best Practices
+
+**Impact: MEDIUM** - Fallthrough attributes are straightforward once you follow Vue's conventions: hyphenated names use bracket notation, listener keys are camelCase `onX`, and `useAttrs()` is current-but-not-reactive.
+
+## Task List
+
+- Access hyphenated attribute names with bracket notation (for example `attrs['data-testid']`)
+- Access event listeners with camelCase `onX` keys (for example `attrs.onClick`)
+- Do not `watch()` values returned from `useAttrs()`; those watchers do not trigger on attr changes
+- Use `onUpdated()` for attr-driven side effects
+- Promote frequently observed attrs to props when reactive observation is required
+
+## Access Attribute and Listener Keys Correctly
+
+Hyphenated attribute names preserve their original casing in JavaScript, so dot notation does not work for keys that include `-`.
+
+**BAD:**
+```vue
+<script setup>
+import { useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+console.log(attrs.data-testid)  // Syntax error
+console.log(attrs.dataTestid)   // undefined for data-testid
+console.log(attrs['on-click'])  // undefined
+console.log(attrs['@click'])    // undefined
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import { useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+console.log(attrs['data-testid'])
+console.log(attrs['aria-label'])
+console.log(attrs['foo-bar'])
+
+console.log(attrs.onClick)
+console.log(attrs.onCustomEvent)
+console.log(attrs.onMouseEnter)
+</script>
+```
+
+### Naming Reference
+
+| Parent Usage | Access in `attrs` |
+|--------------|-------------------|
+| `class="foo"` | `attrs.class` |
+| `data-id="123"` | `attrs['data-id']` |
+| `aria-label="..."` | `attrs['aria-label']` |
+| `foo-bar="baz"` | `attrs['foo-bar']` |
+| `@click="fn"` | `attrs.onClick` |
+| `@custom-event="fn"` | `attrs.onCustomEvent` |
+| `@update:modelValue="fn"` | `attrs['onUpdate:modelValue']` |
+
+## `useAttrs()` Is Not Reactive
+
+`useAttrs()` always reflects the latest values, but it is intentionally not reactive for watcher tracking.
+
+**BAD:**
+```vue
+<script setup>
+import { watch, watchEffect, useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+watch(
+  () => attrs.someAttr,
+  (newValue) => {
+    console.log('Changed:', newValue) // Never runs on attr changes
+  }
+)
+
+watchEffect(() => {
+  console.log(attrs.class) // Runs on setup, not on attr updates
+})
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import { onUpdated, useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+onUpdated(() => {
+  console.log('Latest attrs:', attrs)
+})
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import { watch } from 'vue'
+
+const props = defineProps({
+  someAttr: String
+})
+
+watch(
+  () => props.someAttr,
+  (newValue) => {
+    console.log('Changed:', newValue)
+  }
+)
+</script>
+```
+
+## Common Patterns
+
+### Check for optional attrs safely
+
+```vue
+<script setup>
+import { computed, useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+const hasTestId = computed(() => 'data-testid' in attrs)
+const ariaLabel = computed(() => attrs['aria-label'] ?? 'Default label')
+</script>
+```
+
+### Forward listeners after internal logic
+
+```vue
+<script setup>
+import { useAttrs } from 'vue'
+
+defineOptions({ inheritAttrs: false })
+
+const attrs = useAttrs()
+
+function handleClick(event) {
+  console.log('Internal handling first')
+  attrs.onClick?.(event)
+}
+</script>
+
+<template>
+  <button @click="handleClick">
+    <slot />
+  </button>
+</template>
+```
+
+## TypeScript Notes
+
+`useAttrs()` is typed as `Record<string, unknown>`, so cast individual keys when needed.
+
+```vue
+<script setup lang="ts">
+import { useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+const testId = attrs['data-testid'] as string | undefined
+const onClick = attrs.onClick as ((event: MouseEvent) => void) | undefined
+</script>
+```

package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-keep-alive.md

@@ -0,0 +1,137 @@
+---
+title: KeepAlive Component Best Practices
+impact: HIGH
+impactDescription: KeepAlive caches component instances; misuse causes stale data, memory growth, or unexpected lifecycle behavior
+type: best-practice
+tags: [vue3, keepalive, cache, performance, router, dynamic-components]
+---
+
+# KeepAlive Component Best Practices
+
+**Impact: HIGH** - `<KeepAlive>` caches component instances instead of destroying them. Use it to preserve state across switches, but manage cache size and freshness explicitly to avoid memory growth or stale UI.
+
+## Task List
+
+- Use KeepAlive only where state preservation improves UX
+- Set a reasonable `max` to cap cache size
+- Declare component names for include/exclude matching
+- Use `onActivated`/`onDeactivated` for cache-aware logic
+- Decide how and when cached views refresh their data
+- Avoid caching memory-heavy or security-sensitive views
+
+## When to Use KeepAlive
+
+Use KeepAlive when switching between views where state should persist (tabs, multi-step forms, dashboards). Avoid it when each visit should start fresh.
+
+**BAD:**
+```vue
+<template>
+  <!-- State resets on every switch -->
+  <component :is="currentTab" />
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <!-- State preserved between switches -->
+  <KeepAlive>
+    <component :is="currentTab" />
+  </KeepAlive>
+</template>
+```
+
+## When NOT to Use KeepAlive
+
+- Search or filter pages where users expect fresh results
+- Memory-heavy components (maps, large tables, media players)
+- Sensitive flows where data must be cleared on exit
+- Components with heavy background activity you cannot pause
+
+## Limit and Control the Cache
+
+Always cap cache size with `max` and restrict caching to specific components when possible.
+
+```vue
+<template>
+  <KeepAlive :max="5" include="Dashboard,Settings">
+    <component :is="currentView" />
+  </KeepAlive>
+</template>
+```
+
+## Ensure Component Names Match include/exclude
+
+`include` and `exclude` match the component `name` option. Explicitly set names for reliable caching.
+
+```vue
+<!-- TabA.vue -->
+<script setup>
+defineOptions({ name: 'TabA' })
+</script>
+```
+
+```vue
+<template>
+  <KeepAlive include="TabA,TabB">
+    <component :is="currentTab" />
+  </KeepAlive>
+</template>
+```
+
+## Cache Invalidation Strategies
+
+Vue 3 has no direct API to remove a specific cached instance. Use keys or dynamic include/exclude to force refreshes.
+
+```vue
+<script setup>
+import { ref, reactive } from 'vue'
+
+const currentView = ref('Dashboard')
+const viewKeys = reactive({ Dashboard: 0, Settings: 0 })
+
+function invalidateCache(view) {
+  viewKeys[view]++
+}
+</script>
+
+<template>
+  <KeepAlive>
+    <component :is="currentView" :key="`${currentView}-${viewKeys[currentView]}`" />
+  </KeepAlive>
+</template>
+```
+
+## Lifecycle Hooks for Cached Components
+
+Cached components are not destroyed on switch. Use activation hooks for refresh and cleanup.
+
+```vue
+<script setup>
+import { onActivated, onDeactivated } from 'vue'
+
+onActivated(() => {
+  refreshData()
+})
+
+onDeactivated(() => {
+  pauseTimers()
+})
+</script>
+```
+
+## Router Caching and Freshness
+
+Decide whether navigation should show cached state or a fresh view. A common pattern is to key by route when params change.
+
+```vue
+<template>
+  <router-view v-slot="{ Component, route }">
+    <KeepAlive>
+      <component :is="Component" :key="route.fullPath" />
+    </KeepAlive>
+  </router-view>
+</template>
+```
+
+If you want cache reuse but fresh data, refresh in `onActivated` and compare query/params before fetching.

package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-slots.md

@@ -0,0 +1,216 @@
+---
+title: Component Slots Best Practices
+impact: MEDIUM
+impactDescription: Poor slot API design causes empty DOM wrappers, weak TypeScript safety, brittle defaults, and unnecessary component overhead
+type: best-practice
+tags: [vue3, slots, components, typescript, composables]
+---
+
+# Component Slots Best Practices
+
+**Impact: MEDIUM** - Slots are a core component API surface in Vue. Structure them intentionally so templates stay predictable, typed, and performant.
+
+## Task List
+
+- Use shorthand syntax for named slots (`#` instead of `v-slot:`)
+- Render optional slot wrapper elements only when slot content exists (`$slots` checks)
+- Type scoped slot contracts with `defineSlots` in TypeScript components
+- Provide fallback content for optional slots
+- Prefer composables over renderless components for pure logic reuse
+
+## Shorthand syntax for named slots
+
+**BAD:**
+```vue
+<MyComponent>
+  <template v-slot:header> ... </template>
+</MyComponent>
+```
+
+**GOOD:**
+```vue
+<MyComponent>
+  <template #header> ... </template>
+</MyComponent>
+```
+
+## Conditionally Render Optional Slot Wrappers
+
+Use `$slots` checks when wrapper elements add spacing, borders, or layout constraints.
+
+**BAD:**
+```vue
+<!-- Card.vue -->
+<template>
+  <article class="card">
+    <header class="card-header">
+      <slot name="header" />
+    </header>
+
+    <section class="card-body">
+      <slot />
+    </section>
+
+    <footer class="card-footer">
+      <slot name="footer" />
+    </footer>
+  </article>
+</template>
+```
+
+**GOOD:**
+```vue
+<!-- Card.vue -->
+<template>
+  <article class="card">
+    <header v-if="$slots.header" class="card-header">
+      <slot name="header" />
+    </header>
+
+    <section v-if="$slots.default" class="card-body">
+      <slot />
+    </section>
+
+    <footer v-if="$slots.footer" class="card-footer">
+      <slot name="footer" />
+    </footer>
+  </article>
+</template>
+```
+
+## Type Scoped Slot Props with defineSlots
+
+In `<script setup lang="ts">`, use `defineSlots` so slot consumers get autocomplete and static checks.
+
+**BAD:**
+```vue
+<!-- ProductList.vue -->
+<script setup lang="ts">
+interface Product {
+  id: number
+  name: string
+}
+
+defineProps<{ products: Product[] }>()
+</script>
+
+<template>
+  <ul>
+    <li v-for="(product, index) in products" :key="product.id">
+      <slot :product="product" :index="index" />
+    </li>
+  </ul>
+</template>
+```
+
+**GOOD:**
+```vue
+<!-- ProductList.vue -->
+<script setup lang="ts">
+interface Product {
+  id: number
+  name: string
+}
+
+defineProps<{ products: Product[] }>()
+
+defineSlots<{
+  default(props: { product: Product; index: number }): any
+  empty(): any
+}>()
+</script>
+
+<template>
+  <ul v-if="products.length">
+    <li v-for="(product, index) in products" :key="product.id">
+      <slot :product="product" :index="index" />
+    </li>
+  </ul>
+  <slot v-else name="empty" />
+</template>
+```
+
+## Provide Slot Fallback Content
+
+Fallback content makes components resilient when parents omit optional slots.
+
+**BAD:**
+```vue
+<!-- SubmitButton.vue -->
+<template>
+  <button type="submit" class="btn-primary">
+    <slot />
+  </button>
+</template>
+```
+
+**GOOD:**
+```vue
+<!-- SubmitButton.vue -->
+<template>
+  <button type="submit" class="btn-primary">
+    <slot>Submit</slot>
+  </button>
+</template>
+```
+
+## Prefer Composables for Pure Logic Reuse
+
+Renderless components are still useful for slot-driven composition, but composables are usually cleaner for logic-only reuse.
+
+**BAD:**
+```vue
+<!-- MouseTracker.vue -->
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const x = ref(0)
+const y = ref(0)
+
+function onMove(event: MouseEvent) {
+  x.value = event.pageX
+  y.value = event.pageY
+}
+
+onMounted(() => window.addEventListener('mousemove', onMove))
+onUnmounted(() => window.removeEventListener('mousemove', onMove))
+</script>
+
+<template>
+  <slot :x="x" :y="y" />
+</template>
+```
+
+**GOOD:**
+```ts
+// composables/useMouse.ts
+import { ref, onMounted, onUnmounted } from 'vue'
+
+export function useMouse() {
+  const x = ref(0)
+  const y = ref(0)
+
+  function onMove(event: MouseEvent) {
+    x.value = event.pageX
+    y.value = event.pageY
+  }
+
+  onMounted(() => window.addEventListener('mousemove', onMove))
+  onUnmounted(() => window.removeEventListener('mousemove', onMove))
+
+  return { x, y }
+}
+```
+
+```vue
+<!-- MousePosition.vue -->
+<script setup lang="ts">
+import { useMouse } from '@/composables/useMouse'
+
+const { x, y } = useMouse()
+</script>
+
+<template>
+  <p>{{ x }}, {{ y }}</p>
+</template>
+```