aico-cli 2.1.7 → 2.1.23

package/templates/skills/vue/references/components-emits.md

@@ -0,0 +1,139 @@
+---
+name: component-events-emits
+description: Emit and handle custom events from child to parent components
+---
+
+# Component Events
+
+Components emit custom events to communicate with parent components.
+
+## Emitting Events
+
+Use `$emit` in templates or `defineEmits` in script:
+
+```vue
+<script setup lang="ts">
+const emit = defineEmits(['inFocus', 'submit'])
+
+function handleClick() {
+  emit('submit')
+}
+</script>
+
+<template>
+  <button @click="$emit('inFocus')">Focus</button>
+  <button @click="handleClick">Submit</button>
+</template>
+```
+
+## Type-Based Declaration (Recommended)
+
+```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]
+}>()
+
+// Usage
+emit('change', 123)
+emit('update', 'hello')
+</script>
+```
+
+## Event Arguments
+
+Pass additional arguments to events:
+
+```vue
+<script setup lang="ts">
+const emit = defineEmits<{
+  increaseBy: [amount: number]
+}>()
+
+function increase() {
+  emit('increaseBy', 5)
+}
+</script>
+```
+
+Parent receives arguments:
+
+```vue-html
+<!-- Inline handler -->
+<MyButton @increase-by="(n) => count += n" />
+
+<!-- Method handler -->
+<MyButton @increase-by="increaseCount" />
+```
+
+```ts
+function increaseCount(n: number) {
+  count.value += n
+}
+```
+
+## Event Validation
+
+Validate event payloads with object syntax:
+
+```vue
+<script setup lang="ts">
+const emit = defineEmits({
+  // No validation
+  click: null,
+  
+  // Validate submit event
+  submit: ({ email, password }: { email: string; password: string }) => {
+    if (email && password) {
+      return true
+    }
+    console.warn('Invalid submit payload!')
+    return false
+  }
+})
+</script>
+```
+
+## Listening to Events
+
+Use `v-on` or `@` shorthand:
+
+```vue-html
+<MyComponent @some-event="handleEvent" />
+
+<!-- With .once modifier -->
+<MyComponent @some-event.once="handleOnce" />
+```
+
+## Event Name Casing
+
+- Emit in camelCase
+- Listen in kebab-case
+
+```ts
+emit('someEvent')
+```
+
+```vue-html
+<MyComponent @some-event="handler" />
+```
+
+## Important Notes
+
+- Component events do NOT bubble (unlike DOM events)
+- Only direct child events can be listened to
+- For sibling/deeply nested communication, use provide/inject or state management
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/components/events.html
+- https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits
+-->

package/templates/skills/vue/references/components-lifecycle.md

@@ -0,0 +1,192 @@
+---
+name: lifecycle-hooks
+description: Run code at specific stages of component lifecycle
+---
+
+# Lifecycle Hooks
+
+Execute code at specific stages of a component's lifecycle.
+
+## Common Lifecycle Hooks
+
+```vue
+<script setup lang="ts">
+import {
+  onBeforeMount,
+  onMounted,
+  onBeforeUpdate,
+  onUpdated,
+  onBeforeUnmount,
+  onUnmounted
+} from 'vue'
+
+// Before DOM is mounted
+onBeforeMount(() => {
+  console.log('before mount')
+})
+
+// After DOM is mounted (most common)
+onMounted(() => {
+  console.log('mounted')
+  // Safe to access DOM, make API calls, start timers
+})
+
+// Before reactive state change causes re-render
+onBeforeUpdate(() => {
+  console.log('before update')
+})
+
+// After DOM re-render
+onUpdated(() => {
+  console.log('updated')
+})
+
+// Before component unmounts
+onBeforeUnmount(() => {
+  console.log('before unmount')
+})
+
+// After component unmounts
+onUnmounted(() => {
+  console.log('unmounted')
+  // Cleanup: remove listeners, cancel timers, etc.
+})
+</script>
+```
+
+## Lifecycle Diagram
+
+```
+Creation:
+  setup() → onBeforeMount → onMounted
+
+Updates:
+  onBeforeUpdate → onUpdated
+
+Destruction:
+  onBeforeUnmount → onUnmounted
+```
+
+## Common Patterns
+
+### DOM Access
+
+```ts
+import { ref, onMounted } from 'vue'
+
+const inputRef = ref<HTMLInputElement | null>(null)
+
+onMounted(() => {
+  // DOM is available
+  inputRef.value?.focus()
+})
+```
+
+### API Calls
+
+```ts
+import { ref, onMounted } from 'vue'
+
+const data = ref(null)
+
+onMounted(async () => {
+  const response = await fetch('/api/data')
+  data.value = await response.json()
+})
+```
+
+### Cleanup
+
+```ts
+import { onMounted, onUnmounted } from 'vue'
+
+onMounted(() => {
+  window.addEventListener('resize', handleResize)
+})
+
+onUnmounted(() => {
+  window.removeEventListener('resize', handleResize)
+})
+```
+
+### Timer Cleanup
+
+```ts
+import { onMounted, onUnmounted } from 'vue'
+
+let timer: ReturnType<typeof setInterval>
+
+onMounted(() => {
+  timer = setInterval(() => {
+    // ...
+  }, 1000)
+})
+
+onUnmounted(() => {
+  clearInterval(timer)
+})
+```
+
+## Less Common Hooks
+
+```ts
+import {
+  onActivated,      // Component kept alive is activated
+  onDeactivated,    // Component kept alive is deactivated
+  onErrorCaptured,  // Error from descendant captured
+  onRenderTracked,  // Debug: reactive dependency tracked
+  onRenderTriggered // Debug: re-render triggered
+} from 'vue'
+```
+
+## SSR Hooks
+
+```ts
+import { onServerPrefetch } from 'vue'
+
+// Only runs during server-side rendering
+onServerPrefetch(async () => {
+  data.value = await fetchData()
+})
+```
+
+## Important Notes
+
+1. **Hooks must be called synchronously** during `setup()`:
+
+```ts
+// ❌ Won't work
+setTimeout(() => {
+  onMounted(() => {})
+}, 100)
+
+// ✅ Works
+onMounted(() => {
+  setTimeout(() => {}, 100)
+})
+```
+
+2. **Can call from external functions** if called synchronously from setup:
+
+```ts
+// composable.ts
+export function useFeature() {
+  onMounted(() => {
+    // This works if useFeature is called synchronously in setup
+  })
+}
+```
+
+3. **Multiple calls are allowed** - all callbacks will be invoked:
+
+```ts
+onMounted(() => console.log('first'))
+onMounted(() => console.log('second'))
+// Both will run
+```
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/essentials/lifecycle.html
+- https://vuejs.org/api/composition-api-lifecycle.html
+-->

package/templates/skills/vue/references/components-props.md

@@ -0,0 +1,211 @@
+---
+name: component-props
+description: Declare and use props with type safety and validation
+---
+
+# Component Props
+
+Props are custom attributes for passing data from parent to child components.
+
+## Type-Based Declaration (Recommended)
+
+Use TypeScript interfaces with `defineProps`:
+
+```vue
+<script setup lang="ts">
+interface Props {
+  title: string
+  count?: number
+  items: string[]
+}
+
+const props = defineProps<Props>()
+</script>
+```
+
+## Reactive Props Destructure (3.5+)
+
+Destructure props while keeping reactivity:
+
+```vue
+<script setup lang="ts">
+interface Props {
+  msg?: string
+  count?: number
+}
+
+const { msg = 'hello', count = 0 } = defineProps<Props>()
+
+// Both msg and count are reactive
+watchEffect(() => {
+  console.log(msg, count)
+})
+</script>
+```
+
+### Passing destructured props to functions
+
+```ts
+const { foo } = defineProps(['foo'])
+
+// ❌ Won't work - passes value not reactive source
+watch(foo, /* ... */)
+
+// ✅ Wrap in getter
+watch(() => foo, /* ... */)
+
+// ✅ For composables
+useComposable(() => foo)
+```
+
+## Default Values 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'] // Factory function for objects/arrays
+})
+</script>
+```
+
+## Runtime Declaration
+
+For runtime validation without TypeScript:
+
+```vue
+<script setup lang="ts">
+const props = defineProps({
+  // Basic type check
+  propA: Number,
+  // Multiple types
+  propB: [String, Number],
+  // Required
+  propC: { type: String, required: true },
+  // With default
+  propD: { type: Number, default: 100 },
+  // Object with factory default
+  propE: {
+    type: Object,
+    default: () => ({ message: 'hello' })
+  },
+  // Custom validator
+  propF: {
+    validator(value: string) {
+      return ['success', 'warning', 'danger'].includes(value)
+    }
+  }
+})
+</script>
+```
+
+## Prop Types
+
+Supported `type` values:
+- `String`, `Number`, `Boolean`, `Array`, `Object`
+- `Date`, `Function`, `Symbol`, `Error`
+- Custom classes (uses `instanceof`)
+
+```ts
+class Person {
+  constructor(public name: string) {}
+}
+
+defineProps({
+  author: Person // instanceof check
+})
+```
+
+## Nullable Props
+
+```ts
+defineProps({
+  id: {
+    type: [String, null],
+    required: true
+  }
+})
+```
+
+## Boolean Casting
+
+Boolean props have special casting rules:
+
+```vue
+<script setup lang="ts">
+defineProps({
+  disabled: Boolean
+})
+</script>
+
+<!-- equivalent to :disabled="true" -->
+<MyComponent disabled />
+
+<!-- equivalent to :disabled="false" -->
+<MyComponent />
+```
+
+## One-Way Data Flow
+
+Props form a one-way binding: parent → child. Never mutate props directly.
+
+```ts
+const props = defineProps(['initialCounter'])
+
+// ❌ Don't mutate props
+props.initialCounter = 5
+
+// ✅ Use local state initialized from prop
+const counter = ref(props.initialCounter)
+
+// ✅ Or use computed for transformations
+const normalizedSize = computed(() => props.size.trim().toLowerCase())
+```
+
+## Passing Props
+
+```vue-html
+<!-- Static -->
+<BlogPost title="My Post" />
+
+<!-- Dynamic -->
+<BlogPost :title="post.title" />
+
+<!-- Number (requires v-bind) -->
+<BlogPost :likes="42" />
+
+<!-- Boolean -->
+<BlogPost is-published />
+<BlogPost :is-published="false" />
+
+<!-- Object spread -->
+<BlogPost v-bind="post" />
+<!-- equivalent to -->
+<BlogPost :id="post.id" :title="post.title" />
+```
+
+## Prop Name Casing
+
+- Declare with camelCase in JavaScript
+- Use kebab-case in templates
+
+```ts
+defineProps({
+  greetingMessage: String
+})
+```
+
+```vue-html
+<MyComponent greeting-message="hello" />
+```
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/components/props.html
+- https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits
+-->