@exelalfanso/puppets-orchestration 0.1.0

package/skills/vue/vue-best-practices/references/animation-class-based-technique.md

@@ -0,0 +1,254 @@
+---
+title: Use Class-based Animations for Non-Enter/Leave Effects
+impact: LOW
+impactDescription: Class-based animations are simpler and more performant for elements that remain in the DOM
+type: best-practice
+tags: [vue3, animation, css, class-binding, state]
+---
+
+# Use Class-based Animations for Non-Enter/Leave Effects
+
+**Impact: LOW** - For animations on elements that are not entering or leaving the DOM, use CSS class-based animations triggered by Vue's reactive state. This is simpler than `<Transition>` and more appropriate for feedback animations like shake, pulse, or highlight effects.
+
+## Task List
+
+- Use class-based animations for elements staying in the DOM
+- Use `<Transition>` only for enter/leave animations
+- Combine CSS animations with Vue's class bindings (`:class`)
+- Consider using `setTimeout` to auto-remove animation classes
+
+**When to Use Class-based Animations:**
+- User feedback (shake on error, pulse on success)
+- Attention-grabbing effects (highlight changes)
+- Hover/focus states that need more than CSS transitions
+- Any animation where the element stays mounted
+
+**When to Use Transition Component:**
+- Elements entering/leaving the DOM (v-if/v-show)
+- Route transitions
+- List item additions/removals
+
+## Basic Pattern
+
+```vue
+<template>
+  <div :class="{ shake: showError }">
+    <button @click="submitForm">Submit</button>
+    <span v-if="showError">This feature is disabled!</span>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const showError = ref(false)
+
+function submitForm() {
+  if (!isValid()) {
+    // Trigger shake animation
+    showError.value = true
+
+    // Auto-remove class after animation completes
+    setTimeout(() => {
+      showError.value = false
+    }, 820)  // Match animation duration
+  }
+}
+</script>
+
+<style>
+.shake {
+  animation: shake 0.82s cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
+  transform: translate3d(0, 0, 0);  /* Enable GPU acceleration */
+}
+
+@keyframes shake {
+  10%, 90% { transform: translate3d(-1px, 0, 0); }
+  20%, 80% { transform: translate3d(2px, 0, 0); }
+  30%, 50%, 70% { transform: translate3d(-4px, 0, 0); }
+  40%, 60% { transform: translate3d(4px, 0, 0); }
+}
+</style>
+```
+
+## Common Animation Patterns
+
+### Pulse on Success
+
+```vue
+<template>
+  <button
+    @click="save"
+    :class="{ pulse: saved }"
+  >
+    {{ saved ? 'Saved!' : 'Save' }}
+  </button>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const saved = ref(false)
+
+async function save() {
+  await saveData()
+  saved.value = true
+  setTimeout(() => saved.value = false, 1000)
+}
+</script>
+
+<style>
+.pulse {
+  animation: pulse 0.5s ease-in-out;
+}
+
+@keyframes pulse {
+  0%, 100% { transform: scale(1); }
+  50% { transform: scale(1.05); }
+}
+</style>
+```
+
+### Highlight on Change
+
+```vue
+<template>
+  <div
+    :class="{ highlight: justUpdated }"
+  >
+    Value: {{ value }}
+  </div>
+</template>
+
+<script setup>
+import { ref, watch } from 'vue'
+
+const value = ref(0)
+const justUpdated = ref(false)
+
+watch(value, () => {
+  justUpdated.value = true
+  setTimeout(() => justUpdated.value = false, 1000)
+})
+</script>
+
+<style>
+.highlight {
+  animation: highlight 1s ease-out;
+}
+
+@keyframes highlight {
+  0% { background-color: yellow; }
+  100% { background-color: transparent; }
+}
+</style>
+```
+
+### Bounce Attention
+
+```vue
+<template>
+  <div
+    :class="{ bounce: needsAttention }"
+    @animationend="needsAttention = false"
+  >
+    <BellIcon />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const needsAttention = ref(false)
+
+function notifyUser() {
+  needsAttention.value = true
+  // No setTimeout needed - using animationend event
+}
+</script>
+
+<style>
+.bounce {
+  animation: bounce 0.5s ease;
+}
+
+@keyframes bounce {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-10px); }
+}
+</style>
+```
+
+## Using animationend Event
+
+Instead of `setTimeout`, use the `animationend` event for cleaner code:
+
+```vue
+<template>
+  <div
+    :class="{ animate: isAnimating }"
+    @animationend="isAnimating = false"
+  >
+    Content
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const isAnimating = ref(false)
+
+function triggerAnimation() {
+  isAnimating.value = true
+  // Class is automatically removed when animation ends
+}
+</script>
+```
+
+## Composable for Reusable Animations
+
+```javascript
+// composables/useAnimation.js
+import { ref } from 'vue'
+
+export function useAnimation(duration = 500) {
+  const isAnimating = ref(false)
+
+  function trigger() {
+    isAnimating.value = true
+    setTimeout(() => {
+      isAnimating.value = false
+    }, duration)
+  }
+
+  return {
+    isAnimating,
+    trigger
+  }
+}
+```
+
+```vue
+<script setup>
+import { useAnimation } from '@/composables/useAnimation'
+
+const shake = useAnimation(820)
+const pulse = useAnimation(500)
+</script>
+
+<template>
+  <button
+    :class="{ shake: shake.isAnimating.value }"
+    @click="shake.trigger()"
+  >
+    Shake me
+  </button>
+
+  <button
+    :class="{ pulse: pulse.isAnimating.value }"
+    @click="pulse.trigger()"
+  >
+    Pulse me
+  </button>
+</template>
+```

package/skills/vue/vue-best-practices/references/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/skills/vue/vue-best-practices/references/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` |