@gong-ym/ai-spec-auto 0.2.14 → 0.2.15

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

@@ -1,162 +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.
+---
+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.

package/.agents/skills/profiles/vue/vue-best-practices/references/perf-avoid-component-abstraction-in-lists.md

@@ -1,159 +1,159 @@
----
-title: Avoid Excessive Component Abstraction in Large Lists
-impact: MEDIUM
-impactDescription: Each component instance has memory and render overhead - abstractions multiply this in lists
-type: efficiency
-tags: [vue3, performance, components, abstraction, lists, optimization]
----
-
-# Avoid Excessive Component Abstraction in Large Lists
-
-**Impact: MEDIUM** - Component instances are more expensive than plain DOM nodes. While abstractions improve code organization, unnecessary nesting creates overhead. In large lists, this overhead multiplies - 100 items with 3 levels of abstraction means 300+ component instances instead of 100.
-
-Don't avoid abstraction entirely, but be mindful of component depth in frequently-rendered elements like list items.
-
-## Task List
-
-- Review list item components for unnecessary wrapper components
-- Consider flattening component hierarchies in hot paths
-- Use native elements when a component adds no value
-- Profile component counts using Vue DevTools
-- Focus optimization efforts on the most-rendered components
-
-**BAD:**
-```vue
-<!-- BAD: Deep abstraction in list items -->
-<template>
-  <div class="user-list">
-    <!-- For 100 users: Creates 400 component instances -->
-    <UserCard v-for="user in users" :key="user.id" :user="user" />
-  </div>
-</template>
-
-<!-- UserCard.vue -->
-<template>
-  <Card>  <!-- Wrapper component #1 -->
-    <CardHeader>  <!-- Wrapper component #2 -->
-      <UserAvatar :src="user.avatar" />  <!-- Wrapper component #3 -->
-    </CardHeader>
-    <CardBody>  <!-- Wrapper component #4 -->
-      <Text>{{ user.name }}</Text>
-    </CardBody>
-  </Card>
-</template>
-
-<!-- Each UserCard creates: Card + CardHeader + CardBody + UserAvatar + Text
-     100 users = 500+ component instances -->
-```
-
-**GOOD:**
-```vue
-<!-- GOOD: Flattened structure in list items -->
-<template>
-  <div class="user-list">
-    <!-- For 100 users: Creates 100 component instances -->
-    <UserCard v-for="user in users" :key="user.id" :user="user" />
-  </div>
-</template>
-
-<!-- UserCard.vue - Flattened, uses native elements -->
-<template>
-  <div class="card">
-    <div class="card-header">
-      <img :src="user.avatar" :alt="user.name" class="avatar" />
-    </div>
-    <div class="card-body">
-      <span class="user-name">{{ user.name }}</span>
-    </div>
-  </div>
-</template>
-
-<script setup>
-defineProps({
-  user: Object
-})
-</script>
-
-<style scoped>
-/* Styles that would have been in Card, CardHeader, etc. */
-.card { /* ... */ }
-.card-header { /* ... */ }
-.card-body { /* ... */ }
-.avatar { /* ... */ }
-</style>
-```
-
-## When Abstraction Is Still Worth It
-
-```vue
-<!-- Component abstraction is valuable when: -->
-
-<!-- 1. Complex behavior is encapsulated -->
-<UserStatusIndicator :user="user" />  <!-- Has logic, tooltips, etc. -->
-
-<!-- 2. Reused outside of the hot path -->
-<Card>  <!-- OK to use in one-off places, not in 100-item lists -->
-
-<!-- 3. The list itself is small -->
-<template v-if="items.length < 20">
-  <FancyItem v-for="item in items" :key="item.id" />
-</template>
-
-<!-- 4. Virtualization is used (only ~20 items rendered at once) -->
-<RecycleScroller :items="items">
-  <template #default="{ item }">
-    <ComplexItem :item="item" />  <!-- OK - only 20 instances exist -->
-  </template>
-</RecycleScroller>
-```
-
-## Measuring Component Overhead
-
-```javascript
-// In development, profile component counts
-import { onMounted, getCurrentInstance } from 'vue'
-
-onMounted(() => {
-  const instance = getCurrentInstance()
-  let count = 0
-
-  function countComponents(vnode) {
-    if (vnode.component) count++
-    if (vnode.children) {
-      vnode.children.forEach(child => {
-        if (child.component || child.children) countComponents(child)
-      })
-    }
-  }
-
-  // Use Vue DevTools instead for accurate counts
-  console.log('Check Vue DevTools Components tab for instance counts')
-})
-```
-
-## Alternatives to Wrapper Components
-
-```vue
-<!-- Instead of a <Button> component for styling: -->
-<button class="btn btn-primary">Click</button>
-
-<!-- Instead of a <Text> component: -->
-<span class="text-body">{{ content }}</span>
-
-<!-- Instead of layout wrapper components in lists: -->
-<div class="flex items-center gap-2">
-  <!-- content -->
-</div>
-
-<!-- Use CSS classes or Tailwind instead of component abstractions for styling -->
-```
-
-## Impact Calculation
-
-| List Size | Components per Item | Total Instances | Memory Impact |
-|-----------|---------------------|-----------------|---------------|
-| 100 items | 1 (flat) | 100 | Baseline |
-| 100 items | 3 (nested) | 300 | ~3x memory |
-| 100 items | 5 (deeply nested) | 500 | ~5x memory |
-| 1000 items | 1 (flat) | 1000 | High |
-| 1000 items | 5 (deeply nested) | 5000 | Very High |
+---
+title: Avoid Excessive Component Abstraction in Large Lists
+impact: MEDIUM
+impactDescription: Each component instance has memory and render overhead - abstractions multiply this in lists
+type: efficiency
+tags: [vue3, performance, components, abstraction, lists, optimization]
+---
+
+# Avoid Excessive Component Abstraction in Large Lists
+
+**Impact: MEDIUM** - Component instances are more expensive than plain DOM nodes. While abstractions improve code organization, unnecessary nesting creates overhead. In large lists, this overhead multiplies - 100 items with 3 levels of abstraction means 300+ component instances instead of 100.
+
+Don't avoid abstraction entirely, but be mindful of component depth in frequently-rendered elements like list items.
+
+## Task List
+
+- Review list item components for unnecessary wrapper components
+- Consider flattening component hierarchies in hot paths
+- Use native elements when a component adds no value
+- Profile component counts using Vue DevTools
+- Focus optimization efforts on the most-rendered components
+
+**BAD:**
+```vue
+<!-- BAD: Deep abstraction in list items -->
+<template>
+  <div class="user-list">
+    <!-- For 100 users: Creates 400 component instances -->
+    <UserCard v-for="user in users" :key="user.id" :user="user" />
+  </div>
+</template>
+
+<!-- UserCard.vue -->
+<template>
+  <Card>  <!-- Wrapper component #1 -->
+    <CardHeader>  <!-- Wrapper component #2 -->
+      <UserAvatar :src="user.avatar" />  <!-- Wrapper component #3 -->
+    </CardHeader>
+    <CardBody>  <!-- Wrapper component #4 -->
+      <Text>{{ user.name }}</Text>
+    </CardBody>
+  </Card>
+</template>
+
+<!-- Each UserCard creates: Card + CardHeader + CardBody + UserAvatar + Text
+     100 users = 500+ component instances -->
+```
+
+**GOOD:**
+```vue
+<!-- GOOD: Flattened structure in list items -->
+<template>
+  <div class="user-list">
+    <!-- For 100 users: Creates 100 component instances -->
+    <UserCard v-for="user in users" :key="user.id" :user="user" />
+  </div>
+</template>
+
+<!-- UserCard.vue - Flattened, uses native elements -->
+<template>
+  <div class="card">
+    <div class="card-header">
+      <img :src="user.avatar" :alt="user.name" class="avatar" />
+    </div>
+    <div class="card-body">
+      <span class="user-name">{{ user.name }}</span>
+    </div>
+  </div>
+</template>
+
+<script setup>
+defineProps({
+  user: Object
+})
+</script>
+
+<style scoped>
+/* Styles that would have been in Card, CardHeader, etc. */
+.card { /* ... */ }
+.card-header { /* ... */ }
+.card-body { /* ... */ }
+.avatar { /* ... */ }
+</style>
+```
+
+## When Abstraction Is Still Worth It
+
+```vue
+<!-- Component abstraction is valuable when: -->
+
+<!-- 1. Complex behavior is encapsulated -->
+<UserStatusIndicator :user="user" />  <!-- Has logic, tooltips, etc. -->
+
+<!-- 2. Reused outside of the hot path -->
+<Card>  <!-- OK to use in one-off places, not in 100-item lists -->
+
+<!-- 3. The list itself is small -->
+<template v-if="items.length < 20">
+  <FancyItem v-for="item in items" :key="item.id" />
+</template>
+
+<!-- 4. Virtualization is used (only ~20 items rendered at once) -->
+<RecycleScroller :items="items">
+  <template #default="{ item }">
+    <ComplexItem :item="item" />  <!-- OK - only 20 instances exist -->
+  </template>
+</RecycleScroller>
+```
+
+## Measuring Component Overhead
+
+```javascript
+// In development, profile component counts
+import { onMounted, getCurrentInstance } from 'vue'
+
+onMounted(() => {
+  const instance = getCurrentInstance()
+  let count = 0
+
+  function countComponents(vnode) {
+    if (vnode.component) count++
+    if (vnode.children) {
+      vnode.children.forEach(child => {
+        if (child.component || child.children) countComponents(child)
+      })
+    }
+  }
+
+  // Use Vue DevTools instead for accurate counts
+  console.log('Check Vue DevTools Components tab for instance counts')
+})
+```
+
+## Alternatives to Wrapper Components
+
+```vue
+<!-- Instead of a <Button> component for styling: -->
+<button class="btn btn-primary">Click</button>
+
+<!-- Instead of a <Text> component: -->
+<span class="text-body">{{ content }}</span>
+
+<!-- Instead of layout wrapper components in lists: -->
+<div class="flex items-center gap-2">
+  <!-- content -->
+</div>
+
+<!-- Use CSS classes or Tailwind instead of component abstractions for styling -->
+```
+
+## Impact Calculation
+
+| List Size | Components per Item | Total Instances | Memory Impact |
+|-----------|---------------------|-----------------|---------------|
+| 100 items | 1 (flat) | 100 | Baseline |
+| 100 items | 3 (nested) | 300 | ~3x memory |
+| 100 items | 5 (deeply nested) | 500 | ~5x memory |
+| 1000 items | 1 (flat) | 1000 | High |
+| 1000 items | 5 (deeply nested) | 5000 | Very High |