@gong-ym/ai-spec-auto 0.2.3

package/.agents/skills/profiles/vue/vue-best-practices/references/component-transition.md

@@ -0,0 +1,125 @@
+---
+title: Transition Component Best Practices
+impact: MEDIUM
+impactDescription: Transition animates a single element or component; incorrect structure or keys prevent animations
+type: best-practice
+tags: [vue3, transition, animation, performance, keys]
+---
+
+# Transition Component Best Practices
+
+**Impact: MEDIUM** - `<Transition>` animates entering/leaving of a single element or component. It is ideal for toggling UI states, swapping views, or animating one component at a time.
+
+## Task List
+
+- Wrap a single element or component inside `<Transition>`
+- Provide a `key` when switching between same element types
+- Use `mode="out-in"` when you need sequential swaps
+- Prefer `transform` and `opacity` for smooth animations
+
+## Use Transition for a Single Root Element
+
+`<Transition>` only supports one direct child. Wrap multiple nodes in a single element or component.
+
+**BAD:**
+```vue
+<template>
+  <Transition name="fade">
+    <h3>Title</h3>
+    <p>Description</p>
+  </Transition>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Transition name="fade">
+    <div>
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </Transition>
+</template>
+```
+
+## Force Transitions Between Same Element Types
+
+Vue reuses the same DOM element when the tag type does not change. Add `key` so Vue treats it as a new element and triggers enter/leave.
+
+**BAD:**
+```vue
+<template>
+  <Transition name="fade">
+    <p v-if="isActive">Active</p>
+    <p v-else>Inactive</p>
+  </Transition>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Transition name="fade" mode="out-in">
+    <p v-if="isActive" key="active">Active</p>
+    <p v-else key="inactive">Inactive</p>
+  </Transition>
+</template>
+```
+
+## Use `mode` to Avoid Overlap During Swaps
+
+When swapping components or views, use `mode="out-in"` to prevent both from being visible at the same time.
+
+**BAD:**
+```vue
+<template>
+  <Transition name="fade">
+    <component :is="currentView" />
+  </Transition>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Transition name="fade" mode="out-in">
+    <component :is="currentView" :key="currentView" />
+  </Transition>
+</template>
+```
+
+## Animate `transform` and `opacity` for Performance
+
+Avoid layout-triggering properties such as `height`, `margin`, or `top`. Use `transform` and `opacity` for smooth, GPU-friendly transitions.
+
+**BAD:**
+```css
+.slide-enter-active,
+.slide-leave-active {
+  transition: height 0.3s ease;
+}
+
+.slide-enter-from,
+.slide-leave-to {
+  height: 0;
+}
+```
+
+**GOOD:**
+```css
+.slide-enter-active,
+.slide-leave-active {
+  transition: transform 0.3s ease, opacity 0.3s ease;
+}
+
+.slide-enter-from {
+  transform: translateX(-12px);
+  opacity: 0;
+}
+
+.slide-leave-to {
+  transform: translateX(12px);
+  opacity: 0;
+}
+```

package/.agents/skills/profiles/vue/vue-best-practices/references/composables.md

@@ -0,0 +1,290 @@
+---
+title: Composable Organization Patterns
+impact: MEDIUM
+impactDescription: Well-structured composables improve maintainability, reusability, and update performance
+type: best-practice
+tags: [vue3, composables, composition-api, code-organization, api-design, readonly, utilities]
+---
+
+# Composable Organization Patterns
+
+**Impact: MEDIUM** - Treat composables as reusable, stateful building blocks and keep their code organized by feature concern. This keeps large components maintainable and prevents hard-to-debug mutation and API design issues.
+
+## Task List
+
+- Compose complex behavior from small, focused composables
+- Use options objects for composables with multiple optional parameters
+- Return readonly state when updates must flow through explicit actions
+- Keep pure utility functions as plain utilities, not composables
+- Organize composable and component code by feature concern, and extract composables when components grow
+
+## Compose Composables from Smaller Primitives
+
+**BAD:**
+```vue
+<script setup>
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+
+const x = ref(0)
+const y = ref(0)
+const inside = ref(false)
+const el = ref(null)
+
+function onMove(e) {
+  x.value = e.pageX
+  y.value = e.pageY
+  if (!el.value) return
+  const r = el.value.getBoundingClientRect()
+  inside.value = x.value >= r.left && x.value <= r.right &&
+    y.value >= r.top && y.value <= r.bottom
+}
+
+onMounted(() => window.addEventListener('mousemove', onMove))
+onUnmounted(() => window.removeEventListener('mousemove', onMove))
+</script>
+```
+
+**GOOD:**
+```javascript
+// composables/useEventListener.js
+import { onMounted, onUnmounted, toValue } from 'vue'
+
+export function useEventListener(target, event, callback) {
+  onMounted(() => toValue(target).addEventListener(event, callback))
+  onUnmounted(() => toValue(target).removeEventListener(event, callback))
+}
+```
+
+```javascript
+// composables/useMouse.js
+import { ref } from 'vue'
+import { useEventListener } from './useEventListener'
+
+export function useMouse() {
+  const x = ref(0)
+  const y = ref(0)
+
+  useEventListener(window, 'mousemove', (e) => {
+    x.value = e.pageX
+    y.value = e.pageY
+  })
+
+  return { x, y }
+}
+```
+
+```javascript
+// composables/useMouseInElement.js
+import { computed } from 'vue'
+import { useMouse } from './useMouse'
+
+export function useMouseInElement(elementRef) {
+  const { x, y } = useMouse()
+
+  const isOutside = computed(() => {
+    if (!elementRef.value) return true
+    const rect = elementRef.value.getBoundingClientRect()
+    return x.value < rect.left || x.value > rect.right ||
+      y.value < rect.top || y.value > rect.bottom
+  })
+
+  return { x, y, isOutside }
+}
+```
+
+## Use Options Object Pattern for Composable Parameters
+
+**BAD:**
+```javascript
+export function useFetch(url, method, headers, timeout, retries, immediate) {
+  // hard to read and easy to misorder
+}
+
+useFetch('/api/users', 'GET', null, 5000, 3, true)
+```
+
+**GOOD:**
+```javascript
+export function useFetch(url, options = {}) {
+  const {
+    method = 'GET',
+    headers = {},
+    timeout = 30000,
+    retries = 0,
+    immediate = true
+  } = options
+
+  // implementation
+  return { method, headers, timeout, retries, immediate }
+}
+
+useFetch('/api/users', {
+  method: 'POST',
+  timeout: 5000,
+  retries: 3
+})
+```
+
+```typescript
+interface UseCounterOptions {
+  initial?: number
+  min?: number
+  max?: number
+  step?: number
+}
+
+export function useCounter(options: UseCounterOptions = {}) {
+  const { initial = 0, min = -Infinity, max = Infinity, step = 1 } = options
+  // implementation
+}
+```
+
+## Return Readonly State with Explicit Actions
+
+**BAD:**
+```javascript
+export function useCart() {
+  const items = ref([])
+  const total = computed(() => items.value.reduce((sum, item) => sum + item.price, 0))
+  return { items, total } // any consumer can mutate directly
+}
+
+const { items } = useCart()
+items.value.push({ id: 1, price: 10 })
+```
+
+**GOOD:**
+```javascript
+import { ref, computed, readonly } from 'vue'
+
+export function useCart() {
+  const _items = ref([])
+
+  const total = computed(() =>
+    _items.value.reduce((sum, item) => sum + item.price * item.quantity, 0)
+  )
+
+  function addItem(product, quantity = 1) {
+    const existing = _items.value.find(item => item.id === product.id)
+    if (existing) {
+      existing.quantity += quantity
+      return
+    }
+    _items.value.push({ ...product, quantity })
+  }
+
+  function removeItem(productId) {
+    _items.value = _items.value.filter(item => item.id !== productId)
+  }
+
+  return {
+    items: readonly(_items),
+    total,
+    addItem,
+    removeItem
+  }
+}
+```
+
+## Keep Utilities as Utilities
+
+**BAD:**
+```javascript
+export function useFormatters() {
+  const formatDate = (date) => new Intl.DateTimeFormat('en-US').format(date)
+  const formatCurrency = (amount) =>
+    new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount)
+  return { formatDate, formatCurrency }
+}
+
+const { formatDate } = useFormatters()
+```
+
+**GOOD:**
+```javascript
+// utils/formatters.js
+export function formatDate(date) {
+  return new Intl.DateTimeFormat('en-US').format(date)
+}
+
+export function formatCurrency(amount) {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD'
+  }).format(amount)
+}
+```
+
+```javascript
+// composables/useInvoiceSummary.js
+import { computed } from 'vue'
+import { formatCurrency } from '@/utils/formatters'
+
+export function useInvoiceSummary(invoiceRef) {
+  const totalLabel = computed(() => formatCurrency(invoiceRef.value.total))
+  return { totalLabel }
+}
+```
+
+## Organize Composable and Component Code by Feature Concern
+
+**BAD:**
+```vue
+<script setup>
+import { ref, computed, watch, onMounted } from 'vue'
+
+const searchQuery = ref('')
+const items = ref([])
+const selected = ref(null)
+const showModal = ref(false)
+const sortBy = ref('name')
+const filter = ref('all')
+const loading = ref(false)
+
+const filtered = computed(() => items.value.filter(i => i.category === filter.value))
+function openModal() { showModal.value = true }
+const sorted = computed(() => [...filtered.value].sort(/* ... */))
+watch(searchQuery, () => { /* ... */ })
+onMounted(() => { /* ... */ })
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import { useItems } from '@/composables/useItems'
+import { useSearch } from '@/composables/useSearch'
+import { useSelectionModal } from '@/composables/useSelectionModal'
+
+// Data
+const { items, loading, fetchItems } = useItems()
+
+// Search/filter/sort
+const { query, visibleItems } = useSearch(items)
+
+// Selection + modal
+const { selectedItem, isModalOpen, selectItem, closeModal } = useSelectionModal()
+</script>
+```
+
+```javascript
+// composables/useItems.js
+import { ref, onMounted } from 'vue'
+
+export function useItems() {
+  const items = ref([])
+  const loading = ref(false)
+
+  async function fetchItems() {
+    loading.value = true
+    try {
+      items.value = await api.getItems()
+    } finally {
+      loading.value = false
+    }
+  }
+
+  onMounted(fetchItems)
+  return { items, loading, fetchItems }
+}
+```

package/.agents/skills/profiles/vue/vue-best-practices/references/directives.md

@@ -0,0 +1,162 @@
+---
+title: Directive Best Practices
+impact: MEDIUM
+impactDescription: Custom directives are powerful but easy to misuse; following patterns prevents leaks, invalid usage, and unclear abstractions
+type: best-practice
+tags: [vue3, directives, custom-directives, composition, typescript]
+---
+
+# Directive Best Practices
+
+**Impact: MEDIUM** - Directives are for low-level DOM access. Use them sparingly, keep them side-effect safe, and prefer components or composables when you need stateful or reusable UI behavior.
+
+## Task List
+
+- Use directives only when you need direct DOM access
+- Do not mutate directive arguments or binding objects
+- Clean up timers, listeners, and observers in `unmounted`
+- Register directives in `<script setup>` with the `v-` prefix
+- In TypeScript projects, type directive values and augment template directive types
+- Prefer components or composables for complex behavior
+
+## Treat Directive Arguments as Read-Only
+
+Directive bindings are not reactive storage. Don’t write to them.
+
+```ts
+const vFocus = {
+  mounted(el, binding) {
+    // binding.value is read-only
+    el.focus()
+  }
+}
+```
+
+## Avoid Directives on Components
+
+Directives apply to DOM elements. When used on components, they attach to the root element and can break if the root changes.
+
+**BAD:**
+```vue
+<MyInput v-focus />
+```
+
+**GOOD:**
+```vue
+<!-- MyInput.vue -->
+<script setup>
+const vFocus = (el) => el.focus()
+</script>
+
+<template>
+  <input v-focus />
+</template>
+```
+
+## Clean Up Side Effects in `unmounted`
+
+Any timers, listeners, or observers must be removed to avoid leaks.
+
+```ts
+const vResize = {
+  mounted(el) {
+    const observer = new ResizeObserver(() => {})
+    observer.observe(el)
+    el._observer = observer
+  },
+  unmounted(el) {
+    el._observer?.disconnect()
+  }
+}
+```
+
+## Prefer Function Shorthand for Single-Hook Directives
+
+If you only need `mounted`/`updated`, use the function form.
+
+```ts
+const vAutofocus = (el) => el.focus()
+```
+
+## Use the `v-` Prefix and Script Setup Registration
+
+```vue
+<script setup>
+const vFocus = (el) => el.focus()
+</script>
+
+<template>
+  <input v-focus />
+</template>
+```
+
+## Type Custom Directives in TypeScript Projects
+
+Use `Directive<Element, ValueType>` so `binding.value` is typed, and augment Vue's template types so directives are recognized in SFC templates.
+
+**BAD:**
+```ts
+// Untyped directive value and no template type augmentation
+export const vHighlight = {
+  mounted(el, binding) {
+    el.style.backgroundColor = binding.value
+  }
+}
+```
+
+**GOOD:**
+```ts
+import type { Directive } from 'vue'
+
+type HighlightValue = string
+
+export const vHighlight = {
+  mounted(el, binding) {
+    el.style.backgroundColor = binding.value
+  }
+} satisfies Directive<HTMLElement, HighlightValue>
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    vHighlight: typeof vHighlight
+  }
+}
+```
+
+## Handle SSR with `getSSRProps`
+
+Directive hooks such as `mounted` and `updated` do not run during SSR. If a directive sets attributes/classes that affect rendered HTML, provide an SSR equivalent via `getSSRProps` to avoid hydration mismatches.
+
+**BAD:**
+```ts
+const vTooltip = {
+  mounted(el, binding) {
+    el.setAttribute('data-tooltip', binding.value)
+    el.classList.add('has-tooltip')
+  }
+}
+```
+
+**GOOD:**
+```ts
+const vTooltip = {
+  mounted(el, binding) {
+    el.setAttribute('data-tooltip', binding.value)
+    el.classList.add('has-tooltip')
+  },
+  getSSRProps(binding) {
+    return {
+      'data-tooltip': binding.value,
+      class: 'has-tooltip'
+    }
+  }
+}
+```
+
+## Prefer Declarative Templates When Possible
+
+If a standard attribute or binding works, use it instead of a directive.
+
+## Decide Between Directives and Components
+
+Use a directive for DOM-level behavior. Use a component when behavior affects structure, state, or rendering.