agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/animation-state-driven-technique.md

@@ -0,0 +1,291 @@
+---
+title: State-driven Animations with CSS Transitions and Style Bindings
+impact: LOW
+impactDescription: Combining Vue's reactive style bindings with CSS transitions creates smooth, interactive animations
+type: best-practice
+tags: [vue3, animation, css, transition, style-binding, state, interactive]
+---
+
+# State-driven Animations with CSS Transitions and Style Bindings
+
+**Impact: LOW** - For responsive, interactive animations that react to user input or state changes, combine Vue's dynamic style bindings with CSS transitions. This creates smooth animations that interpolate values in real-time based on state.
+
+## Task List
+
+- Use `:style` binding for dynamic properties that change frequently
+- Add CSS `transition` property to smoothly animate between values
+- Consider using `transform` and `opacity` for GPU-accelerated animations
+- For complex value interpolation, use watchers with animation libraries
+
+## Basic Pattern
+
+```vue
+<template>
+  <div
+    @mousemove="onMousemove"
+    :style="{ backgroundColor: `hsl(${hue}, 80%, 50%)` }"
+    class="interactive-area"
+  >
+    <p>Move your mouse across this div...</p>
+    <p>Hue: {{ hue }}</p>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const hue = ref(0)
+
+function onMousemove(e) {
+  // Map mouse X position to hue (0-360)
+  const rect = e.currentTarget.getBoundingClientRect()
+  hue.value = Math.round((e.clientX - rect.left) / rect.width * 360)
+}
+</script>
+
+<style>
+.interactive-area {
+  transition: background-color 0.3s ease;
+  height: 200px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}
+</style>
+```
+
+## Common Use Cases
+
+### Following Mouse Position
+
+```vue
+<template>
+  <div
+    class="container"
+    @mousemove="onMousemove"
+  >
+    <div
+      class="follower"
+      :style="{
+        transform: `translate(${x}px, ${y}px)`
+      }"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const x = ref(0)
+const y = ref(0)
+
+function onMousemove(e) {
+  const rect = e.currentTarget.getBoundingClientRect()
+  x.value = e.clientX - rect.left
+  y.value = e.clientY - rect.top
+}
+</script>
+
+<style>
+.container {
+  position: relative;
+  height: 300px;
+}
+
+.follower {
+  position: absolute;
+  width: 20px;
+  height: 20px;
+  background: blue;
+  border-radius: 50%;
+  /* Smooth following with transition */
+  transition: transform 0.1s ease-out;
+  /* Prevent the follower from triggering mousemove */
+  pointer-events: none;
+}
+</style>
+```
+
+### Progress Animation
+
+```vue
+<template>
+  <div class="progress-container">
+    <div
+      class="progress-bar"
+      :style="{ width: `${progress}%` }"
+    />
+  </div>
+  <input
+    type="range"
+    v-model.number="progress"
+    min="0"
+    max="100"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const progress = ref(0)
+</script>
+
+<style>
+.progress-container {
+  height: 20px;
+  background: #e0e0e0;
+  border-radius: 10px;
+  overflow: hidden;
+}
+
+.progress-bar {
+  height: 100%;
+  background: linear-gradient(90deg, #4CAF50, #8BC34A);
+  transition: width 0.3s ease;
+}
+</style>
+```
+
+### Scroll-based Animation
+
+```vue
+<template>
+  <div
+    class="hero"
+    :style="{
+      opacity: heroOpacity,
+      transform: `translateY(${scrollOffset}px)`
+    }"
+  >
+    <h1>Scroll Down</h1>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+
+const scrollY = ref(0)
+
+const heroOpacity = computed(() => {
+  return Math.max(0, 1 - scrollY.value / 300)
+})
+
+const scrollOffset = computed(() => {
+  return scrollY.value * 0.5  // Parallax effect
+})
+
+function handleScroll() {
+  scrollY.value = window.scrollY
+}
+
+onMounted(() => {
+  window.addEventListener('scroll', handleScroll, { passive: true })
+})
+
+onUnmounted(() => {
+  window.removeEventListener('scroll', handleScroll)
+})
+</script>
+
+<style>
+.hero {
+  height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Note: No transition for scroll-based animations - they should be instant */
+}
+</style>
+```
+
+### Color Theme Transition
+
+```vue
+<template>
+  <div
+    class="app"
+    :style="themeStyles"
+  >
+    <button @click="toggleTheme">Toggle Theme</button>
+    <p>Current theme: {{ isDark ? 'Dark' : 'Light' }}</p>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const isDark = ref(false)
+
+const themeStyles = computed(() => ({
+  '--bg-color': isDark.value ? '#1a1a1a' : '#ffffff',
+  '--text-color': isDark.value ? '#ffffff' : '#1a1a1a',
+  backgroundColor: 'var(--bg-color)',
+  color: 'var(--text-color)'
+}))
+
+function toggleTheme() {
+  isDark.value = !isDark.value
+}
+</script>
+
+<style>
+.app {
+  min-height: 100vh;
+  transition: background-color 0.5s ease, color 0.5s ease;
+}
+</style>
+```
+
+## Advanced: Numerical Tweening with Watchers
+
+For smooth number animations (counters, stats), use watchers with animation libraries:
+
+```vue
+<template>
+  <div>
+    <input v-model.number="targetNumber" type="number" />
+    <p class="counter">{{ displayNumber.toFixed(0) }}</p>
+  </div>
+</template>
+
+<script setup>
+import { computed, ref, reactive, watch } from 'vue'
+import gsap from 'gsap'
+
+const targetNumber = ref(0)
+const tweened = reactive({ value: 0 })
+
+// Computed for display
+const displayNumber = computed(() => tweened.value)
+
+watch(targetNumber, (newValue) => {
+  gsap.to(tweened, {
+    duration: 0.5,
+    value: Number(newValue) || 0,
+    ease: 'power2.out'
+  })
+})
+</script>
+```
+
+## Performance Considerations
+
+```vue
+<style>
+/* GOOD: GPU-accelerated properties */
+.element {
+  transition: transform 0.3s ease, opacity 0.3s ease;
+}
+
+/* AVOID: Properties that trigger layout recalculation */
+.element {
+  transition: width 0.3s ease, height 0.3s ease, margin 0.3s ease;
+}
+
+/* For high-frequency updates, consider will-change */
+.frequently-animated {
+  will-change: transform;
+}
+</style>
+```

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

@@ -0,0 +1,97 @@
+---
+title: Async Component Best Practices
+impact: MEDIUM
+impactDescription: Poor async component strategy can delay interactivity in SSR apps and create loading UI flicker
+type: best-practice
+tags: [vue3, async-components, ssr, hydration, performance, ux]
+---
+
+# Async Component Best Practices
+
+**Impact: MEDIUM** - Async components should reduce JavaScript cost without degrading perceived performance. Focus on hydration timing in SSR and stable loading UX.
+
+## Task List
+
+- Use lazy hydration strategies for non-critical SSR component trees
+- Import only the hydration helpers you actually use
+- Keep `loadingComponent` delay near the default `200ms` unless real UX data suggests otherwise
+- Configure `delay` and `timeout` together for predictable loading behavior
+
+## Use Lazy Hydration Strategies in SSR
+
+In Vue 3.5+, async components can delay hydration until idle time, visibility, media query match, or user interaction.
+
+**BAD:**
+```vue
+<script setup lang="ts">
+import { defineAsyncComponent } from 'vue'
+
+const AsyncComments = defineAsyncComponent({
+  loader: () => import('./Comments.vue')
+})
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup lang="ts">
+import {
+  defineAsyncComponent,
+  hydrateOnVisible,
+  hydrateOnIdle
+} from 'vue'
+
+const AsyncComments = defineAsyncComponent({
+  loader: () => import('./Comments.vue'),
+  hydrate: hydrateOnVisible({ rootMargin: '100px' })
+})
+
+const AsyncFooter = defineAsyncComponent({
+  loader: () => import('./Footer.vue'),
+  hydrate: hydrateOnIdle(5000)
+})
+</script>
+```
+
+## Prevent Loading Spinner Flicker
+
+Avoid showing loading UI immediately for components that usually resolve quickly.
+
+**BAD:**
+```vue
+<script setup lang="ts">
+import { defineAsyncComponent } from 'vue'
+import LoadingSpinner from './LoadingSpinner.vue'
+
+const AsyncDashboard = defineAsyncComponent({
+  loader: () => import('./Dashboard.vue'),
+  loadingComponent: LoadingSpinner,
+  delay: 0
+})
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup lang="ts">
+import { defineAsyncComponent } from 'vue'
+import LoadingSpinner from './LoadingSpinner.vue'
+import ErrorDisplay from './ErrorDisplay.vue'
+
+const AsyncDashboard = defineAsyncComponent({
+  loader: () => import('./Dashboard.vue'),
+  loadingComponent: LoadingSpinner,
+  errorComponent: ErrorDisplay,
+  delay: 200,
+  timeout: 30000
+})
+</script>
+```
+
+## Delay Guidelines
+
+| Scenario | Recommended Delay |
+|----------|-------------------|
+| Small component, fast network | `200ms` |
+| Known heavy component | `100ms` |
+| Background or non-critical UI | `300-500ms` |

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

@@ -0,0 +1,307 @@
+---
+title: Component Data Flow Best Practices
+impact: HIGH
+impactDescription: Clear data flow between components prevents state bugs, stale UI, and brittle coupling
+type: best-practice
+tags: [vue3, props, emits, v-model, provide-inject, data-flow, typescript]
+---
+
+# Component Data Flow Best Practices
+
+**Impact: HIGH** - Vue components stay reliable when data flow is explicit: props go down, events go up, `v-model` handles two-way bindings, and provide/inject supports cross-tree dependencies. Blurring these boundaries leads to stale state, hidden coupling, and hard-to-debug UI.
+
+The main principle of data flow in Vue.js is **Props Down / Events Up**. This is the most maintainable default, and one-way flow scales well.
+
+## Task List
+
+- Treat props as read-only inputs
+- Use props/emit for component communication; reserve refs for imperative actions
+- When refs are required for imperative APIs, type them with template refs
+- Emit events instead of mutating parent state directly
+- Use `defineModel` for v-model in modern Vue (3.4+)
+- Handle v-model modifiers deliberately in child components
+- Use symbols for provide/inject keys to avoid props drilling (over ~3 layers)
+- Keep mutations in the provider or expose explicit actions
+- In TypeScript projects, prefer type-based `defineProps`, `defineEmits`, and `InjectionKey`
+
+## Props: One-Way Data Down
+
+Props are inputs. Do not mutate them in the child.
+
+**BAD:**
+```vue
+<script setup>
+const props = defineProps({ count: Number })
+
+function increment() {
+  props.count++
+}
+</script>
+```
+
+**GOOD:**
+
+If state needs to change, emit an event, use `v-model` or create a local copy.
+
+## Prefer props/emit over component refs
+
+**BAD:**
+```vue
+<script setup>
+import { ref } from 'vue'
+import UserForm from './UserForm.vue'
+
+const formRef = ref(null)
+
+function submitForm() {
+  if (formRef.value.isValid) {
+    formRef.value.submit()
+  }
+}
+</script>
+
+<template>
+  <UserForm ref="formRef" />
+  <button @click="submitForm">Submit</button>
+</template>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import UserForm from './UserForm.vue'
+
+function handleSubmit(formData) {
+  api.submit(formData)
+}
+</script>
+
+<template>
+  <UserForm @submit="handleSubmit" />
+</template>
+```
+
+## Type component refs when imperative access is required
+
+Prefer props/emits by default. When a parent must call an exposed child method, type the ref explicitly and expose only the intended API from the child with `defineExpose`.
+
+**BAD:**
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import DialogPanel from './DialogPanel.vue'
+
+const panelRef = ref(null)
+
+onMounted(() => {
+  panelRef.value.open()
+})
+</script>
+
+<template>
+  <DialogPanel ref="panelRef" />
+</template>
+```
+
+**GOOD:**
+```vue
+<!-- DialogPanel.vue -->
+<script setup lang="ts">
+function open() {}
+
+defineExpose({ open })
+</script>
+```
+
+```vue
+<!-- Parent.vue -->
+<script setup lang="ts">
+import { onMounted, useTemplateRef } from 'vue'
+import DialogPanel from './DialogPanel.vue'
+
+// Vue 3.5+ with useTemplateRef
+const panelRef = useTemplateRef('panelRef')
+
+// Before Vue 3.5 with manual typing and ref
+// const panelRef = ref<InstanceType<typeof DialogPanel> | null>(null)
+
+onMounted(() => {
+  panelRef.value?.open()
+})
+</script>
+
+<template>
+  <DialogPanel ref="panelRef" />
+</template>
+```
+
+## Emits: Explicit Events Up
+
+Component events do not bubble. If a parent needs to know about an event, re-emit it explicitly.
+
+**BAD:**
+```vue
+<!-- Parent expects "saved" from grandchild, but it won't bubble -->
+<Child @saved="onSaved" />
+```
+
+**GOOD:**
+```vue
+<!-- Child.vue -->
+<script setup>
+const emit = defineEmits(['saved'])
+
+function onGrandchildSaved(payload) {
+  emit('saved', payload)
+}
+</script>
+
+<template>
+  <Grandchild @saved="onGrandchildSaved" />
+</template>
+```
+
+**Event naming:** use kebab-case in templates and camelCase in script:
+```vue
+<script setup>
+const emit = defineEmits(['updateUser'])
+</script>
+
+<template>
+  <ProfileForm @update-user="emit('updateUser', $event)" />
+</template>
+```
+
+## `v-model`: Predictable Two-Way Bindings
+
+Use `defineModel` by default for component bindings and emit updates on input. Only use the `modelValue` + `update:modelValue` pattern if you are on Vue < 3.4.
+
+**BAD:**
+```vue
+<script setup>
+const props = defineProps({ value: String })
+</script>
+
+<template>
+  <input :value="props.value" @input="$emit('input', $event.target.value)" />
+</template>
+```
+
+**GOOD (Vue 3.4+):**
+```vue
+<script setup>
+const model = defineModel({ type: String })
+</script>
+
+<template>
+  <input v-model="model" />
+</template>
+```
+
+**GOOD (Vue < 3.4):**
+```vue
+<script setup>
+const props = defineProps({ modelValue: String })
+const emit = defineEmits(['update:modelValue'])
+</script>
+
+<template>
+  <input
+    :value="props.modelValue"
+    @input="emit('update:modelValue', $event.target.value)"
+  />
+</template>
+```
+
+If you need the updated value immediately after a change, use the input event value or `nextTick` in the parent.
+
+## Provide/Inject: Shared Context Without Prop Drilling
+
+Use provide/inject for cross-tree state, but keep mutations centralized in the provider and expose explicit actions.
+
+**BAD:**
+```vue
+// Provider.vue
+provide('theme', reactive({ dark: false }))
+
+// Consumer.vue
+const theme = inject('theme')
+// Mutating shared state from any depth becomes hard to track
+theme.dark = true
+```
+
+**GOOD:**
+```vue
+// Provider.vue
+const theme = reactive({ dark: false })
+const toggleTheme = () => { theme.dark = !theme.dark }
+
+provide(themeKey, readonly(theme))
+provide(themeActionsKey, { toggleTheme })
+
+// Consumer.vue
+const theme = inject(themeKey)
+const { toggleTheme } = inject(themeActionsKey)
+```
+
+Use symbols for keys to avoid collisions in large apps:
+```ts
+export const themeKey = Symbol('theme')
+export const themeActionsKey = Symbol('theme-actions')
+```
+
+## Use TypeScript Contracts for Public Component APIs
+
+In TypeScript projects, type component boundaries directly with `defineProps`, `defineEmits`, and `InjectionKey` so invalid payloads and mismatched injections fail at compile time.
+
+**BAD:**
+```vue
+<script setup lang="ts">
+import { inject } from 'vue'
+
+const props = defineProps({
+  userId: String
+})
+
+const emit = defineEmits(['save'])
+const settings = inject('settings')
+
+// Payload shape is not checked here
+emit('save', 123)
+
+// Key is string-based and not type-safe
+settings?.theme = 'dark'
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup lang="ts">
+import { inject, provide } from 'vue'
+import type { InjectionKey } from 'vue'
+
+interface Props {
+  userId: string
+}
+
+interface Emits {
+  save: [payload: { id: string; draft: boolean }]
+}
+
+interface Settings {
+  theme: 'light' | 'dark'
+}
+
+const settingsKey: InjectionKey<Settings> = Symbol('settings')
+
+const props = defineProps<Props>()
+const emit = defineEmits<Emits>()
+
+provide(settingsKey, { theme: 'light' })
+
+const settings = inject(settingsKey)
+if (settings) {
+  emit('save', { id: props.userId, draft: false })
+}
+</script>
+```