agy-superpowers 5.0.7 → 5.0.9

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>
+```

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

@@ -0,0 +1,228 @@
+---
+title: Suspense Component Best Practices
+impact: MEDIUM
+impactDescription: Suspense coordinates async dependencies with fallback UI; misconfiguration leads to missing loading states or confusing UX
+type: best-practice
+tags: [vue3, suspense, async-components, async-setup, loading, fallback, router, transition, keepalive]
+---
+
+# Suspense Component Best Practices
+
+**Impact: MEDIUM** - `<Suspense>` coordinates async dependencies (async components or async setup) and renders a fallback while they resolve. Misconfiguration leads to missing loading states, empty renders, or subtle UX bugs.
+
+## Task List
+
+- Wrap default and fallback slot content in a single root node
+- Use `timeout` when you need the fallback to appear on reverts
+- Force root replacement with `:key` when you need Suspense to re-trigger
+- Add `suspensible` to nested Suspense boundaries (Vue 3.3+)
+- Use `@pending`, `@resolve`, and `@fallback` for programmatic loading state
+- Nest `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` in that order
+- Keep Suspense usage centralized and documented in production
+
+## Single Root in Default and Fallback Slots
+
+Suspense tracks a single immediate child in both slots. Wrap multiple elements in a single element or component.
+
+**BAD:**
+```vue
+<template>
+  <Suspense>
+    <AsyncHeader />
+    <AsyncList />
+
+    <template #fallback>
+      <LoadingSpinner />
+      <LoadingHint />
+    </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Suspense>
+    <div>
+      <AsyncHeader />
+      <AsyncList />
+    </div>
+
+    <template #fallback>
+      <div>
+        <LoadingSpinner />
+        <LoadingHint />
+      </div>
+    </template>
+  </Suspense>
+</template>
+```
+
+## Fallback Timing on Reverts (`timeout`)
+
+When Suspense is already resolved and new async work starts, the previous content remains visible until the timeout elapses. Use `timeout="0"` for immediate fallback or a short delay to avoid flicker.
+
+**BAD:**
+```vue
+<template>
+  <Suspense>
+    <component :is="currentView" :key="viewKey" />
+
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Suspense :timeout="200">
+    <component :is="currentView" :key="viewKey" />
+
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+## Pending State Only Re-triggers on Root Replacement
+
+Once resolved, Suspense only re-enters pending when the root node of the default slot changes. If async work happens deeper in the tree, no fallback appears.
+
+**BAD:**
+```vue
+<template>
+  <Suspense>
+    <TabContainer>
+      <AsyncDashboard v-if="tab === 'dashboard'" />
+      <AsyncSettings v-else />
+    </TabContainer>
+
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Suspense>
+    <component :is="tabs[tab]" :key="tab" />
+
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+## Use `suspensible` for Nested Suspense (Vue 3.3+)
+
+Nested Suspense boundaries need `suspensible` on the inner boundary so the parent can coordinate loading state. Without it, inner async content may render empty nodes until resolved.
+
+**BAD:**
+```vue
+<template>
+  <Suspense>
+    <LayoutShell>
+      <Suspense>
+        <AsyncWidget />
+        <template #fallback>Loading widget...</template>
+      </Suspense>
+    </LayoutShell>
+
+    <template #fallback>Loading layout...</template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Suspense>
+    <LayoutShell>
+      <Suspense suspensible>
+        <AsyncWidget />
+        <template #fallback>Loading widget...</template>
+      </Suspense>
+    </LayoutShell>
+
+    <template #fallback>Loading layout...</template>
+  </Suspense>
+</template>
+```
+
+## Track Loading with Suspense Events
+
+Use `@pending`, `@resolve`, and `@fallback` for analytics, global loading indicators, or coordinating UI outside the Suspense boundary.
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const isLoading = ref(false)
+
+const onPending = () => {
+  isLoading.value = true
+}
+
+const onResolve = () => {
+  isLoading.value = false
+}
+</script>
+
+<template>
+  <LoadingBar v-if="isLoading" />
+
+  <Suspense @pending="onPending" @resolve="onResolve">
+    <AsyncPage />
+    <template #fallback>
+      <PageSkeleton />
+    </template>
+  </Suspense>
+</template>
+```
+
+## Recommended Nesting with RouterView, Transition, KeepAlive
+
+When combining these components, the nesting order should be `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` so each wrapper works correctly.
+
+**BAD:**
+```vue
+<template>
+  <RouterView v-slot="{ Component }">
+    <Suspense>
+      <KeepAlive>
+        <Transition mode="out-in">
+          <component :is="Component" />
+        </Transition>
+      </KeepAlive>
+    </Suspense>
+  </RouterView>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <RouterView v-slot="{ Component }">
+    <Transition mode="out-in">
+      <KeepAlive>
+        <Suspense>
+          <component :is="Component" />
+          <template #fallback>Loading...</template>
+        </Suspense>
+      </KeepAlive>
+    </Transition>
+  </RouterView>
+</template>
+```
+
+## Treat Suspense Cautiously in Production
+
+In production code, keep Suspense boundaries minimal, document where they are used, and have a fallback loading strategy if you ever need to replace or refactor them.

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

@@ -0,0 +1,108 @@
+---
+title: Teleport Component Best Practices
+impact: MEDIUM
+impactDescription: Teleport renders content outside the component's DOM position, which is essential for overlays but affects styling and layout
+type: best-practice
+tags: [vue3, teleport, modal, overlay, positioning, responsive]
+---
+
+# Teleport Component Best Practices
+
+**Impact: MEDIUM** - `<Teleport>` renders part of a component's template in a different place in the DOM while preserving the Vue component hierarchy. Use it for overlays (modals, toasts, tooltips) or any UI that must escape stacking contexts, overflow, or fixed positioning constraints.
+
+## Task List
+
+- Teleport overlays to `body` or a dedicated container outside the app root
+- Keep a shared target for similar UI (`#modals`, `#notifications`) and control layering with order or z-index
+- Use `:disabled` for responsive layouts that should render inline on small screens
+- Remember props, emits, and provide/inject still work through teleport
+- Avoid relying on parent stacking contexts or transforms for teleported UI
+
+## Teleport Overlays Out of Transformed Containers
+
+When an ancestor has `transform`, `filter`, or `perspective`, fixed-position overlays can behave like they are locally positioned. Teleport escapes that context.
+
+**BAD:**
+```vue
+<template>
+  <div class="animated-container">
+    <button @click="open = true">Open</button>
+
+    <!-- Broken: fixed positioning is scoped to the transformed parent -->
+    <div v-if="open" class="modal">Modal</div>
+  </div>
+</template>
+
+<style>
+.animated-container {
+  transform: translateZ(0);
+}
+
+.modal {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+}
+</style>
+```
+
+**GOOD:**
+```vue
+<template>
+  <div class="animated-container">
+    <button @click="open = true">Open</button>
+
+    <Teleport to="body">
+      <div v-if="open" class="modal">Modal</div>
+    </Teleport>
+  </div>
+</template>
+```
+
+## Responsive Layouts with `disabled`
+
+Use `:disabled` to render inline on mobile and teleport on larger screens:
+
+```vue
+<script setup>
+import { useMediaQuery } from '@vueuse/core'
+
+const isMobile = useMediaQuery('(max-width: 768px)')
+</script>
+
+<template>
+  <Teleport to="body" :disabled="isMobile">
+    <nav class="sidebar">Navigation</nav>
+  </Teleport>
+</template>
+```
+
+## Logical Hierarchy Is Preserved
+
+Teleport changes DOM position, not the Vue component tree. Props, emits, slots, and provide/inject still work:
+
+```vue
+<template>
+  <Teleport to="body">
+    <ChildPanel :message="message" @close="open = false" />
+  </Teleport>
+</template>
+```
+
+## Multiple Teleports to the Same Target
+
+Teleports to the same target append in declaration order:
+
+```vue
+<template>
+  <Teleport to="#notifications">
+    <div>First</div>
+  </Teleport>
+
+  <Teleport to="#notifications">
+    <div>Second</div>
+  </Teleport>
+</template>
+```
+
+Use a shared container to keep stacking predictable, and apply z-index only when you need explicit layering.

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

@@ -0,0 +1,128 @@
+---
+title: TransitionGroup Component Best Practices
+impact: MEDIUM
+impactDescription: TransitionGroup animates list items; missing keys or misuse leads to broken list transitions
+type: best-practice
+tags: [vue3, transition-group, animation, lists, keys]
+---
+
+# TransitionGroup Component Best Practices
+
+**Impact: MEDIUM** - `<TransitionGroup>` animates lists of items entering, leaving, and moving. Use it for `v-for` lists or dynamic collections where individual items change over time.
+
+## Task List
+
+- Use `<TransitionGroup>` only for lists and repeated items
+- Provide unique, stable keys for every direct child
+- Use `tag` when you need semantic or layout wrappers
+- Avoid the `mode` prop (not supported)
+- Use JavaScript hooks for staggered effects
+
+## Use TransitionGroup for Lists
+
+`<TransitionGroup>` is designed for list items. Use `tag` to control the wrapper element when needed.
+
+**BAD:**
+```vue
+<template>
+  <TransitionGroup name="fade">
+    <ComponentA />
+    <ComponentB />
+  </TransitionGroup>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="item in items" :key="item.id">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+```
+
+## Always Provide Stable Keys
+
+Keys are required. Without stable keys, Vue cannot track item positions and animations break.
+
+**BAD:**
+```vue
+<template>
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="(item, index) in items" :key="index">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="item in items" :key="item.id">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+```
+
+## Do Not Use `mode` on TransitionGroup
+
+`mode` is only for `<Transition>` because it swaps a single element. Use `<Transition>` if you need in/out sequencing.
+
+**BAD:**
+```vue
+<template>
+  <TransitionGroup name="list" tag="div" mode="out-in">
+    <div v-for="item in items" :key="item.id">{{ item.name }}</div>
+  </TransitionGroup>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Transition name="fade" mode="out-in">
+    <component :is="currentView" :key="currentView" />
+  </Transition>
+</template>
+```
+
+## Stagger List Animations with Data Attributes
+
+For cascading list animations, pass the index to JavaScript hooks and compute delay per item.
+
+```vue
+<template>
+  <TransitionGroup
+    tag="ul"
+    :css="false"
+    @before-enter="onBeforeEnter"
+    @enter="onEnter"
+  >
+    <li v-for="(item, index) in items" :key="item.id" :data-index="index">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+
+<script setup>
+function onBeforeEnter(el) {
+  el.style.opacity = 0
+  el.style.transform = 'translateY(12px)'
+}
+
+function onEnter(el, done) {
+  const delay = Number(el.dataset.index) * 80
+  setTimeout(() => {
+    el.style.transition = 'all 0.25s ease'
+    el.style.opacity = 1
+    el.style.transform = 'translateY(0)'
+    setTimeout(done, 250)
+  }, delay)
+}
+</script>
+```