aico-cli 2.1.7 → 2.1.23

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

@@ -0,0 +1,262 @@
+---
+name: composables
+description: Encapsulate and reuse stateful logic with the Composition API
+---
+
+# Composables
+
+Composables are functions that encapsulate and reuse stateful logic using Composition API.
+
+## What is a Composable?
+
+A composable is a function that:
+- Uses Composition API functions (ref, computed, onMounted, etc.)
+- Manages reactive state
+- Returns reactive state and/or functions
+- Name starts with "use" by convention
+
+## Basic Example
+
+```ts
+// composables/useMouse.ts
+import { ref, onMounted, onUnmounted } from 'vue'
+
+export function useMouse() {
+  const x = ref(0)
+  const y = ref(0)
+
+  function update(event: MouseEvent) {
+    x.value = event.pageX
+    y.value = event.pageY
+  }
+
+  onMounted(() => window.addEventListener('mousemove', update))
+  onUnmounted(() => window.removeEventListener('mousemove', update))
+
+  return { x, y }
+}
+```
+
+Usage:
+
+```vue
+<script setup lang="ts">
+import { useMouse } from '@/composables/useMouse'
+
+const { x, y } = useMouse()
+</script>
+
+<template>
+  Mouse: {{ x }}, {{ y }}
+</template>
+```
+
+## Async Composable
+
+Handle async data fetching:
+
+```ts
+// composables/useFetch.ts
+import { ref, watchEffect, toValue, type MaybeRefOrGetter } from 'vue'
+
+export function useFetch<T>(url: MaybeRefOrGetter<string>) {
+  const data = ref<T | null>(null)
+  const error = ref<Error | null>(null)
+  const isLoading = ref(false)
+
+  watchEffect(async () => {
+    data.value = null
+    error.value = null
+    isLoading.value = true
+
+    try {
+      const response = await fetch(toValue(url))
+      data.value = await response.json()
+    } catch (e) {
+      error.value = e as Error
+    } finally {
+      isLoading.value = false
+    }
+  })
+
+  return { data, error, isLoading }
+}
+```
+
+Usage with reactive URL:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useFetch } from '@/composables/useFetch'
+
+const userId = ref(1)
+const { data, error, isLoading } = useFetch(() => `/api/users/${userId.value}`)
+
+// Changing userId triggers refetch
+function nextUser() {
+  userId.value++
+}
+</script>
+```
+
+## Composable Conventions
+
+### Naming
+
+- Always start with `use` (useMouse, useFetch, useCounter)
+- Use camelCase
+
+### Input Arguments
+
+Accept refs or getters for reactivity:
+
+```ts
+import { toValue, type MaybeRefOrGetter } from 'vue'
+
+function useFeature(input: MaybeRefOrGetter<string>) {
+  // toValue handles ref, getter, or plain value
+  const value = toValue(input)
+  
+  // For reactive tracking, call toValue inside watchEffect/computed
+  watchEffect(() => {
+    console.log(toValue(input))
+  })
+}
+```
+
+### Return Values
+
+Return a plain object with refs (not reactive):
+
+```ts
+// ✅ Good - refs can be destructured
+export function useCounter() {
+  const count = ref(0)
+  const increment = () => count.value++
+  
+  return { count, increment }
+}
+
+// Usage - maintains reactivity
+const { count, increment } = useCounter()
+```
+
+```ts
+// ❌ Avoid - reactive loses connection on destructure
+export function useCounter() {
+  const state = reactive({ count: 0 })
+  return state
+}
+
+// Loses reactivity
+const { count } = useCounter()
+```
+
+## Composing Composables
+
+Composables can use other composables:
+
+```ts
+// composables/useEventListener.ts
+import { onMounted, onUnmounted, type MaybeRefOrGetter, toValue } from 'vue'
+
+export function useEventListener(
+  target: MaybeRefOrGetter<EventTarget>,
+  event: string,
+  callback: EventListener
+) {
+  onMounted(() => toValue(target).addEventListener(event, callback))
+  onUnmounted(() => toValue(target).removeEventListener(event, callback))
+}
+```
+
+```ts
+// composables/useMouse.ts - using useEventListener
+import { ref } from 'vue'
+import { useEventListener } from './useEventListener'
+
+export function useMouse() {
+  const x = ref(0)
+  const y = ref(0)
+
+  useEventListener(window, 'mousemove', (event) => {
+    x.value = (event as MouseEvent).pageX
+    y.value = (event as MouseEvent).pageY
+  })
+
+  return { x, y }
+}
+```
+
+## Side Effects
+
+### SSR Considerations
+
+Run DOM-specific code only in browser:
+
+```ts
+export function useWindowSize() {
+  const width = ref(0)
+  const height = ref(0)
+
+  onMounted(() => {
+    // Only runs in browser
+    width.value = window.innerWidth
+    height.value = window.innerHeight
+  })
+  
+  return { width, height }
+}
+```
+
+### Cleanup
+
+Always clean up side effects:
+
+```ts
+export function useInterval(callback: () => void, delay: number) {
+  const id = ref<number | undefined>()
+
+  onMounted(() => {
+    id.value = setInterval(callback, delay)
+  })
+
+  onUnmounted(() => {
+    if (id.value) clearInterval(id.value)
+  })
+}
+```
+
+## Usage Restrictions
+
+Composables must be called:
+- Synchronously in `<script setup>` or `setup()`
+- Can be called in lifecycle hooks like `onMounted()`
+
+```ts
+// ✅ Works
+<script setup>
+const { x, y } = useMouse()
+</script>
+
+// ❌ Won't work
+setTimeout(() => {
+  const { x, y } = useMouse() // No active component
+}, 100)
+```
+
+Exception: `<script setup>` allows composables after `await`.
+
+## vs Other Patterns
+
+**vs Mixins**: Composables are explicit (no naming collisions, clear source)
+
+**vs Renderless Components**: Composables have no component overhead
+
+**vs React Hooks**: Similar concept, but Vue's reactivity is different - no rules about hook order or dependency arrays
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/reusability/composables.html
+-->

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

@@ -0,0 +1,224 @@
+---
+name: custom-directives
+description: Create reusable directives for low-level DOM manipulation
+---
+
+# Custom Directives
+
+Custom directives provide low-level DOM access for reusable behavior.
+
+## When to Use
+
+Use custom directives when:
+- You need direct DOM manipulation
+- The behavior can't be achieved with components or composables
+- You need to apply behavior to native elements
+
+## Basic Example
+
+```vue
+<script setup lang="ts">
+// v-focus directive
+const vFocus = {
+  mounted: (el: HTMLElement) => el.focus()
+}
+</script>
+
+<template>
+  <input v-focus />
+</template>
+```
+
+## Directive Hooks
+
+```ts
+const myDirective = {
+  // Before element attributes/listeners are applied
+  created(el, binding, vnode) {},
+  
+  // Before element is inserted into DOM
+  beforeMount(el, binding, vnode) {},
+  
+  // After element and children are mounted
+  mounted(el, binding, vnode) {},
+  
+  // Before parent component updates
+  beforeUpdate(el, binding, vnode, prevVnode) {},
+  
+  // After parent component updates
+  updated(el, binding, vnode, prevVnode) {},
+  
+  // Before parent component unmounts
+  beforeUnmount(el, binding, vnode) {},
+  
+  // After parent component unmounts
+  unmounted(el, binding, vnode) {}
+}
+```
+
+## Hook Arguments
+
+```ts
+interface DirectiveBinding<T = any> {
+  value: T           // v-my-dir="value"
+  oldValue: T        // Previous value (beforeUpdate/updated only)
+  arg?: string       // v-my-dir:arg
+  modifiers: Record<string, boolean>  // v-my-dir.foo.bar → { foo: true, bar: true }
+  instance: ComponentPublicInstance   // Component using the directive
+  dir: ObjectDirective               // Directive definition object
+}
+```
+
+Example usage:
+
+```vue-html
+<div v-example:foo.bar="baz">
+```
+
+```ts
+// binding object:
+{
+  arg: 'foo',
+  modifiers: { bar: true },
+  value: /* value of baz */,
+  oldValue: /* previous value */
+}
+```
+
+## Function Shorthand
+
+When you only need `mounted` and `updated` with same behavior:
+
+```ts
+// Full form
+const vColor = {
+  mounted(el, binding) {
+    el.style.color = binding.value
+  },
+  updated(el, binding) {
+    el.style.color = binding.value
+  }
+}
+
+// Shorthand (same behavior)
+const vColor = (el: HTMLElement, binding: DirectiveBinding<string>) => {
+  el.style.color = binding.value
+}
+```
+
+## Global Registration
+
+```ts
+// main.ts
+const app = createApp(App)
+
+app.directive('focus', {
+  mounted: (el) => el.focus()
+})
+
+// Shorthand
+app.directive('color', (el, binding) => {
+  el.style.color = binding.value
+})
+```
+
+## Object Literals
+
+Pass multiple values:
+
+```vue-html
+<div v-demo="{ color: 'white', text: 'hello' }">
+```
+
+```ts
+const vDemo = (el: HTMLElement, binding: DirectiveBinding<{ color: string; text: string }>) => {
+  console.log(binding.value.color) // 'white'
+  console.log(binding.value.text)  // 'hello'
+}
+```
+
+## Dynamic Arguments
+
+```vue-html
+<div v-my-directive:[dynamicArg]="value">
+```
+
+## Practical Examples
+
+### v-click-outside
+
+```ts
+const vClickOutside = {
+  mounted(el: HTMLElement, binding: DirectiveBinding<() => void>) {
+    el._clickOutside = (event: MouseEvent) => {
+      if (!el.contains(event.target as Node)) {
+        binding.value()
+      }
+    }
+    document.addEventListener('click', el._clickOutside)
+  },
+  unmounted(el: HTMLElement) {
+    document.removeEventListener('click', el._clickOutside)
+  }
+}
+```
+
+### v-tooltip
+
+```ts
+const vTooltip = {
+  mounted(el: HTMLElement, binding: DirectiveBinding<string>) {
+    el.setAttribute('title', binding.value)
+  },
+  updated(el: HTMLElement, binding: DirectiveBinding<string>) {
+    el.setAttribute('title', binding.value)
+  }
+}
+```
+
+### v-permission
+
+```ts
+const vPermission = {
+  mounted(el: HTMLElement, binding: DirectiveBinding<string>) {
+    if (!hasPermission(binding.value)) {
+      el.parentNode?.removeChild(el)
+    }
+  }
+}
+```
+
+## TypeScript: Global Directives
+
+```ts
+// directives/highlight.ts
+import type { Directive } from 'vue'
+
+export type HighlightDirective = Directive<HTMLElement, string>
+
+declare module 'vue' {
+  export interface ComponentCustomProperties {
+    vHighlight: HighlightDirective
+  }
+}
+
+export default {
+  mounted: (el, binding) => {
+    el.style.backgroundColor = binding.value
+  }
+} satisfies HighlightDirective
+```
+
+## Usage on Components
+
+⚠️ **Not recommended** - directives apply to root element, which can be unpredictable with multi-root components.
+
+```vue-html
+<!-- Applies to MyComponent's root element -->
+<MyComponent v-my-directive />
+```
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/reusability/custom-directives.html
+-->

package/templates/skills/vue/references/features-script-setup.md

@@ -0,0 +1,247 @@
+---
+name: script-setup
+description: Compile-time syntactic sugar for Composition API in SFCs
+---
+
+# Script Setup
+
+`<script setup>` is the recommended syntax for Composition API in Single-File Components.
+
+## Basic Syntax
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const count = ref(0)
+
+function increment() {
+  count.value++
+}
+</script>
+
+<template>
+  <button @click="increment">{{ count }}</button>
+</template>
+```
+
+## Benefits
+
+- Less boilerplate (no `export default`, no `return`)
+- TypeScript type inference
+- Better runtime performance
+- Better IDE support
+
+## Top-Level Bindings
+
+All top-level bindings are automatically available in template:
+
+```vue
+<script setup lang="ts">
+// Variables
+const msg = 'Hello'
+
+// Imports
+import { capitalize } from './helpers'
+import MyComponent from './MyComponent.vue'
+
+// Functions
+function greet() {
+  console.log(msg)
+}
+</script>
+
+<template>
+  <MyComponent />
+  <p>{{ capitalize(msg) }}</p>
+  <button @click="greet">Greet</button>
+</template>
+```
+
+## Compiler Macros
+
+These are available without import:
+
+- `defineProps()` - declare props
+- `defineEmits()` - declare emits
+- `defineModel()` - declare v-model (3.4+)
+- `defineExpose()` - expose public instance properties
+- `defineOptions()` - declare component options (3.3+)
+- `defineSlots()` - type slot props (3.3+)
+- `withDefaults()` - provide prop defaults
+
+## Using Components
+
+Import and use directly without registration:
+
+```vue
+<script setup lang="ts">
+import MyComponent from './MyComponent.vue'
+import { MyButton } from './components'
+</script>
+
+<template>
+  <MyComponent />
+  <MyButton />
+</template>
+```
+
+### Dynamic Components
+
+```vue
+<script setup lang="ts">
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
+</script>
+
+<template>
+  <component :is="condition ? Foo : Bar" />
+</template>
+```
+
+### Recursive Components
+
+SFCs can reference themselves by filename:
+
+```vue
+<!-- FooBar.vue can use <FooBar/> in its template -->
+```
+
+## Custom Directives
+
+Variables starting with `v` are available as directives:
+
+```vue
+<script setup lang="ts">
+const vFocus = {
+  mounted: (el: HTMLElement) => el.focus()
+}
+</script>
+
+<template>
+  <input v-focus />
+</template>
+```
+
+## defineExpose()
+
+Components are closed by default. Use `defineExpose` to expose properties:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const count = ref(0)
+const publicMethod = () => console.log('called')
+
+defineExpose({
+  count,
+  publicMethod
+})
+</script>
+```
+
+Parent can access via template ref:
+
+```ts
+const childRef = ref()
+childRef.value.count // accessible
+childRef.value.publicMethod() // accessible
+```
+
+## defineOptions() (3.3+)
+
+Declare component options without separate `<script>` block:
+
+```vue
+<script setup lang="ts">
+defineOptions({
+  inheritAttrs: false,
+  name: 'CustomName'
+})
+</script>
+```
+
+## defineSlots() (3.3+)
+
+Type slot props for IDE support:
+
+```vue
+<script setup lang="ts">
+const slots = defineSlots<{
+  default(props: { msg: string }): any
+  header(props: { title: string }): any
+}>()
+</script>
+```
+
+## useSlots() & useAttrs()
+
+Access slots and attrs in script:
+
+```vue
+<script setup lang="ts">
+import { useSlots, useAttrs } from 'vue'
+
+const slots = useSlots()
+const attrs = useAttrs()
+</script>
+```
+
+## Top-Level await
+
+Async setup with Suspense:
+
+```vue
+<script setup lang="ts">
+const data = await fetch('/api/data').then(r => r.json())
+</script>
+```
+
+> Note: Requires `<Suspense>` boundary in parent.
+
+## Generic Components (TypeScript)
+
+```vue
+<script setup lang="ts" generic="T extends string | number">
+defineProps<{
+  items: T[]
+  selected: T
+}>()
+</script>
+```
+
+Multiple generics with constraints:
+
+```vue
+<script setup lang="ts" generic="T extends Item, U extends string">
+import type { Item } from './types'
+
+defineProps<{
+  item: T
+  label: U
+}>()
+</script>
+```
+
+## Alongside Normal Script
+
+For advanced cases like named exports or one-time side effects:
+
+```vue
+<script lang="ts">
+// Runs once when module is imported
+runSideEffect()
+
+export const exportedValue = 'hello'
+</script>
+
+<script setup lang="ts">
+// Runs for each component instance
+</script>
+```
+
+<!-- 
+Source references:
+- https://vuejs.org/api/sfc-script-setup.html
+-->