aico-cli 2.1.7 → 2.1.23

package/templates/skills/vue/references/features-template-refs.md

@@ -0,0 +1,212 @@
+---
+name: template-refs
+description: Access DOM elements and child component instances directly
+---
+
+# Template Refs
+
+Template refs provide direct access to DOM elements and child component instances.
+
+## Basic Usage (3.5+)
+
+Use `useTemplateRef()` for type-safe refs:
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef, onMounted } from 'vue'
+
+const inputRef = useTemplateRef<HTMLInputElement>('input')
+
+onMounted(() => {
+  inputRef.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="input" />
+</template>
+```
+
+## Legacy Approach (Pre-3.5)
+
+Use a ref with matching name:
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const inputRef = ref<HTMLInputElement | null>(null)
+
+onMounted(() => {
+  inputRef.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="inputRef" />
+</template>
+```
+
+## Refs in v-for
+
+Collect multiple refs into an array:
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const items = ref([1, 2, 3])
+const itemRefs = ref<HTMLLIElement[]>([])
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in items" ref="itemRefs">
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+> Note: ref array order is not guaranteed to match source array order.
+
+## Function Refs
+
+Use a function for full control:
+
+```vue
+<script setup lang="ts">
+const elements = new Map<number, HTMLElement>()
+
+function setItemRef(el: HTMLElement | null, id: number) {
+  if (el) {
+    elements.set(id, el)
+  } else {
+    elements.delete(id)
+  }
+}
+</script>
+
+<template>
+  <div v-for="item in items" :ref="(el) => setItemRef(el, item.id)">
+    {{ item.name }}
+  </div>
+</template>
+```
+
+## Component Refs
+
+Access child component instance:
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef, onMounted } from 'vue'
+import Child from './Child.vue'
+
+type ChildInstance = InstanceType<typeof Child>
+const childRef = useTemplateRef<ChildInstance>('child')
+
+onMounted(() => {
+  // Access exposed properties/methods
+  childRef.value?.someMethod()
+})
+</script>
+
+<template>
+  <Child ref="child" />
+</template>
+```
+
+### Exposing Component Properties
+
+By default, `<script setup>` components are closed. Use `defineExpose`:
+
+```vue
+<!-- Child.vue -->
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const count = ref(0)
+const increment = () => count.value++
+
+// Only these are accessible via ref
+defineExpose({
+  count,
+  increment
+})
+</script>
+```
+
+## Common Use Cases
+
+### Focus Management
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from 'vue'
+
+const inputRef = useTemplateRef<HTMLInputElement>('input')
+
+function focusInput() {
+  inputRef.value?.focus()
+}
+</script>
+```
+
+### Scroll Control
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from 'vue'
+
+const containerRef = useTemplateRef<HTMLDivElement>('container')
+
+function scrollToBottom() {
+  const el = containerRef.value
+  if (el) {
+    el.scrollTop = el.scrollHeight
+  }
+}
+</script>
+```
+
+### Third-Party Library Integration
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef, onMounted, onUnmounted } from 'vue'
+import Chart from 'chart.js'
+
+const canvasRef = useTemplateRef<HTMLCanvasElement>('canvas')
+let chart: Chart | null = null
+
+onMounted(() => {
+  if (canvasRef.value) {
+    chart = new Chart(canvasRef.value, {
+      // options
+    })
+  }
+})
+
+onUnmounted(() => {
+  chart?.destroy()
+})
+</script>
+
+<template>
+  <canvas ref="canvas"></canvas>
+</template>
+```
+
+## Important Notes
+
+1. **Refs are null before mount** - access in `onMounted` or later
+2. **Conditional refs can be null** - elements with `v-if` may not exist
+3. **Use optional chaining** - `ref.value?.method()` for safety
+4. **Avoid overusing** - prefer declarative approaches when possible
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/essentials/template-refs.html
+- https://vuejs.org/guide/typescript/composition-api.html#typing-template-refs
+-->

package/templates/skills/vue/references/features-typescript.md

@@ -0,0 +1,274 @@
+---
+name: typescript-integration
+description: Type Vue components with TypeScript in Composition API
+---
+
+# TypeScript with Vue
+
+Vue provides excellent TypeScript support in Composition API.
+
+## Typing Props
+
+### Type-based declaration (recommended)
+
+```vue
+<script setup lang="ts">
+interface Props {
+  title: string
+  count?: number
+  items: string[]
+  user: { name: string; age: number }
+}
+
+const props = defineProps<Props>()
+```
+
+### With defaults (3.5+)
+
+```vue
+<script setup lang="ts">
+interface Props {
+  msg?: string
+  labels?: string[]
+}
+
+const { msg = 'hello', labels = ['one'] } = defineProps<Props>()
+```
+
+### With withDefaults (3.4 and below)
+
+```vue
+<script setup lang="ts">
+interface Props {
+  msg?: string
+  labels?: string[]
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  msg: 'hello',
+  labels: () => ['one', 'two']
+})
+```
+
+### Complex prop types
+
+```vue
+<script setup lang="ts">
+interface Book {
+  title: string
+  author: string
+  year: number
+}
+
+const props = defineProps<{
+  book: Book
+  callback: (id: number) => void
+}>()
+```
+
+## Typing Emits
+
+```vue
+<script setup lang="ts">
+// Call signature syntax
+const emit = defineEmits<{
+  (e: 'change', id: number): void
+  (e: 'update', value: string): void
+}>()
+
+// Named tuple syntax (3.3+, more concise)
+const emit = defineEmits<{
+  change: [id: number]
+  update: [value: string]
+}>()
+</script>
+```
+
+## Typing ref()
+
+```ts
+import { ref } from 'vue'
+import type { Ref } from 'vue'
+
+// Inferred
+const count = ref(0) // Ref<number>
+
+// Explicit generic
+const name = ref<string>() // Ref<string | undefined>
+
+// Type annotation
+const id: Ref<string | number> = ref('abc')
+```
+
+## Typing reactive()
+
+```ts
+import { reactive } from 'vue'
+
+interface State {
+  count: number
+  name: string
+}
+
+// Use interface on variable
+const state: State = reactive({
+  count: 0,
+  name: 'Vue'
+})
+```
+
+## Typing computed()
+
+```ts
+import { computed } from 'vue'
+
+// Inferred from getter
+const double = computed(() => count.value * 2) // ComputedRef<number>
+
+// Explicit generic
+const result = computed<string>(() => {
+  return String(value.value)
+})
+```
+
+## Typing Event Handlers
+
+```vue
+<script setup lang="ts">
+function handleChange(event: Event) {
+  const target = event.target as HTMLInputElement
+  console.log(target.value)
+}
+</script>
+
+<template>
+  <input @change="handleChange" />
+</template>
+```
+
+## Typing Template Refs
+
+### useTemplateRef (3.5+)
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef, onMounted } from 'vue'
+
+const inputRef = useTemplateRef<HTMLInputElement>('input')
+
+onMounted(() => {
+  inputRef.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="input" />
+</template>
+```
+
+### Legacy ref approach
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const inputRef = ref<HTMLInputElement | null>(null)
+
+onMounted(() => {
+  inputRef.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="inputRef" />
+</template>
+```
+
+## Typing Component Refs
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from 'vue'
+import MyComponent from './MyComponent.vue'
+
+type MyComponentInstance = InstanceType<typeof MyComponent>
+const compRef = useTemplateRef<MyComponentInstance>('comp')
+</script>
+
+<template>
+  <MyComponent ref="comp" />
+</template>
+```
+
+## Typing Provide/Inject
+
+```ts
+import { provide, inject } from 'vue'
+import type { InjectionKey, Ref } from 'vue'
+
+// Define typed key
+const countKey = Symbol() as InjectionKey<Ref<number>>
+
+// Provider
+provide(countKey, ref(0))
+
+// Injector
+const count = inject(countKey) // Ref<number> | undefined
+
+// With default
+const count = inject(countKey, ref(0)) // Ref<number>
+
+// String key with explicit type
+const foo = inject<string>('foo')
+```
+
+## Typing defineModel (3.4+)
+
+```ts
+// Basic
+const model = defineModel<string>()
+//    ^? Ref<string | undefined>
+
+// Required
+const model = defineModel<string>({ required: true })
+//    ^? Ref<string>
+
+// With modifiers
+const [model, modifiers] = defineModel<string, 'trim' | 'uppercase'>()
+//                ^? Record<'trim' | 'uppercase', true | undefined>
+```
+
+## Global Custom Properties
+
+Extend `ComponentCustomProperties` for global properties:
+
+```ts
+// types/vue.d.ts
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $http: typeof axios
+    $translate: (key: string) => string
+  }
+}
+```
+
+## Generic Components
+
+```vue
+<script setup lang="ts" generic="T">
+defineProps<{
+  items: T[]
+  selected: T
+}>()
+
+defineEmits<{
+  select: [item: T]
+}>()
+</script>
+```
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/typescript/composition-api.html
+- https://vuejs.org/guide/typescript/overview.html
+-->

package/templates/skills/vue-best-practices/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hyf0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/skills/vue-best-practices/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: vue-best-practices
+description: Vue 3 and Vue.js best practices for TypeScript, vue-tsc, and Volar. This skill should be used when writing, reviewing, or refactoring Vue components to ensure correct typing patterns. Triggers on tasks involving Vue components, props extraction, wrapper components, template type checking, or Volar configuration.
+license: MIT
+metadata:
+  author: hyf0
+  version: "8.0.0"
+---
+
+## Capability Rules
+
+| Rule | Keywords | Description |
+|------|----------|-------------|
+| [extract-component-props](rules/extract-component-props.md) | get props type, wrapper component, extend props, inherit props, ComponentProps | Extract types from .vue components |
+| [vue-tsc-strict-templates](rules/vue-tsc-strict-templates.md) | undefined component, template error, strictTemplates | Catch undefined components in templates |
+| [fallthrough-attributes](rules/fallthrough-attributes.md) | fallthrough, $attrs, wrapper component | Type-check fallthrough attributes |
+| [strict-css-modules](rules/strict-css-modules.md) | css modules, $style, typo | Catch CSS module class typos |
+| [data-attributes-config](rules/data-attributes-config.md) | data-*, strictTemplates, attribute | Allow data-* attributes |
+| [volar-3-breaking-changes](rules/volar-3-breaking-changes.md) | volar, vue-language-server, editor | Fix Volar 3.0 upgrade issues |
+| [module-resolution-bundler](rules/module-resolution-bundler.md) | cannot find module, @vue/tsconfig, moduleResolution | Fix module resolution errors |
+| [define-model-update-event](rules/define-model-update-event.md) | defineModel, update event, undefined | Fix model update errors |
+| [with-defaults-union-types](rules/with-defaults-union-types.md) | withDefaults, union type, default | Fix union type defaults |
+| [deep-watch-numeric](rules/deep-watch-numeric.md) | watch, deep, array, Vue 3.5 | Efficient array watching |
+| [vue-directive-comments](rules/vue-directive-comments.md) | @vue-ignore, @vue-skip, template | Control template type checking |
+| [vue-router-typed-params](rules/vue-router-typed-params.md) | route params, typed router, unplugin | Fix route params typing |
+
+## Efficiency Rules
+
+| Rule | Keywords | Description |
+|------|----------|-------------|
+| [hmr-vue-ssr](rules/hmr-vue-ssr.md) | hmr, ssr, hot reload | Fix HMR in SSR apps |
+| [pinia-store-mocking](rules/pinia-store-mocking.md) | pinia, mock, vitest, store | Mock Pinia stores |
+
+## Reference
+
+- [Vue Language Tools](https://github.com/vuejs/language-tools)
+- [vue-component-type-helpers](https://github.com/vuejs/language-tools/tree/master/packages/component-type-helpers)
+- [Vue 3 Documentation](https://vuejs.org/)

package/templates/skills/vue-best-practices/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/vue-best-practices/skills/vue-best-practices`
+- **Git SHA:** `ee0ceda40b7fabeb0713caf8b4db5ea438069fb5`
+- **Synced:** 2026-01-28

package/templates/skills/vue-best-practices/rules/codeactions-save-performance.md

@@ -0,0 +1,79 @@
+---
+title: Fix Slow Save Times with Code Actions Setting
+impact: HIGH
+impactDescription: fixes 30-60 second save delays in large Vue projects
+type: capability
+tags: performance, save-time, vscode, code-actions, volar
+---
+
+# Fix Slow Save Times with Code Actions Setting
+
+**Impact: HIGH** - fixes 30-60 second save delays in large Vue projects
+
+In large Vue projects, saving files can take 30-60+ seconds due to VSCode's code actions triggering expensive TypeScript state synchronization.
+
+## Problem
+
+Symptoms:
+- Save operation takes 30+ seconds
+- Editor becomes unresponsive during save
+- CPU spikes when saving Vue files
+- Happens more in larger projects
+
+## Root Cause
+
+VSCode emits document change events multiple times during save cycles. Each event triggers Volar to synchronize with TypeScript, causing expensive re-computation.
+
+## Solution
+
+Disable code actions or limit their timeout:
+
+**Option 1: Disable code actions (fastest)**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": false
+}
+```
+
+**Option 2: Limit code action time**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.savingTimeLimit": 1000
+}
+```
+
+**Option 3: Disable specific code actions**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "never"
+  }
+}
+```
+
+## VSCode Version Requirement
+
+VSCode 1.81.0+ includes fixes that reduce save time issues. Upgrade if using an older version.
+
+## Additional Optimizations
+
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": false,
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {},
+  "[vue]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "Vue.volar"
+  }
+}
+```
+
+## Reference
+
+- [Vue Language Tools Discussion #2740](https://github.com/vuejs/language-tools/discussions/2740)

package/templates/skills/vue-best-practices/rules/data-attributes-config.md

@@ -0,0 +1,74 @@
+---
+title: Allow Data Attributes with Strict Templates
+impact: MEDIUM
+impactDescription: fixes data-testid and data-* attribute errors in strict mode
+type: capability
+tags: dataAttributes, vueCompilerOptions, strictTemplates, data-testid, testing
+---
+
+# Allow Data Attributes with Strict Templates
+
+**Impact: MEDIUM** - fixes data-testid and data-* attribute errors in strict mode
+
+With `strictTemplates` enabled, `data-*` attributes on components cause type errors. Use the `dataAttributes` option to allow specific patterns.
+
+## Problem
+
+```vue
+<template>
+  <!-- Error: Property 'data-testid' does not exist on type... -->
+  <MyComponent data-testid="submit-button" />
+
+  <!-- Error: Property 'data-cy' does not exist on type... -->
+  <MyComponent data-cy="login-form" />
+</template>
+```
+
+## Solution
+
+Configure `dataAttributes` to allow specific patterns:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "strictTemplates": true,
+    "dataAttributes": ["data-*"]
+  }
+}
+```
+
+Now all `data-*` attributes are allowed on any component.
+
+## Specific Patterns
+
+You can be more selective:
+
+```json
+{
+  "vueCompilerOptions": {
+    "dataAttributes": [
+      "data-testid",
+      "data-cy",
+      "data-test-*"
+    ]
+  }
+}
+```
+
+This only allows the specified patterns, not all data attributes.
+
+## Common Testing Attributes
+
+For testing libraries, allow their specific attributes:
+
+| Library | Attribute | Pattern |
+|---------|-----------|---------|
+| Testing Library | `data-testid` | `"data-testid"` |
+| Cypress | `data-cy` | `"data-cy"` |
+| Playwright | `data-testid` | `"data-testid"` |
+| Generic | All data attributes | `"data-*"` |
+
+## Reference
+
+- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)