aigroup-workflow 2.1.2 → 2.2.1

package/skills/frontend/vue-expert-js/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: vue-expert-js
+description: Creates Vue 3 components, builds vanilla JS composables, configures Vite projects, and sets up routing and state management using JavaScript only — no TypeScript. Generates JSDoc-typed code with @typedef, @param, and @returns annotations for full type coverage without a TS compiler. Use when building Vue 3 applications with JavaScript only (no TypeScript), when projects require JSDoc-based type hints, when migrating from Vue 2 Options API to Composition API in JS, or when teams prefer vanilla JavaScript, .mjs modules, or need quick prototypes without TypeScript setup.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: frontend
+  triggers: Vue JavaScript, Vue without TypeScript, Vue JSDoc, Vue JS only, Vue vanilla JavaScript, .mjs Vue, Vue no TS
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: vue-expert, javascript-pro
+---
+
+# Vue Expert (JavaScript)
+
+Senior Vue specialist building Vue 3 applications with JavaScript and JSDoc typing instead of TypeScript.
+
+## Core Workflow
+
+1. **Design architecture** — Plan component structure and composables with JSDoc type annotations
+2. **Implement** — Build with `<script setup>` (no `lang="ts"`), `.mjs` modules where needed
+3. **Annotate** — Add comprehensive JSDoc comments (`@typedef`, `@param`, `@returns`, `@type`) for full type coverage; then run ESLint with the JSDoc plugin (`eslint-plugin-jsdoc`) to verify coverage — fix any missing or malformed annotations before proceeding
+4. **Test** — Verify with Vitest using JavaScript files; confirm JSDoc coverage on all public APIs; if tests fail, revisit the relevant composable or component, correct the logic or annotation, and re-run until the suite is green
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| JSDoc Typing | `references/jsdoc-typing.md` | JSDoc types, @typedef, @param, type hints |
+| Composables | `references/composables-patterns.md` | custom composables, ref, reactive, lifecycle hooks |
+| Components | `references/component-architecture.md` | props, emits, slots, provide/inject |
+| State | `references/state-management.md` | Pinia, stores, reactive state |
+| Testing | `references/testing-patterns.md` | Vitest, component testing, mocking |
+
+**For shared Vue concepts, defer to vue-expert:**
+- `vue-expert/references/composition-api.md` - Core reactivity patterns
+- `vue-expert/references/components.md` - Props, emits, slots
+- `vue-expert/references/state-management.md` - Pinia stores
+
+## Code Patterns
+
+### Component with JSDoc-typed props and emits
+
+```vue
+<script setup>
+/**
+ * @typedef {Object} UserCardProps
+ * @property {string} name - Display name of the user
+ * @property {number} age - User's age
+ * @property {boolean} [isAdmin=false] - Whether the user has admin rights
+ */
+
+/** @type {UserCardProps} */
+const props = defineProps({
+  name:    { type: String,  required: true },
+  age:     { type: Number,  required: true },
+  isAdmin: { type: Boolean, default: false },
+})
+
+/**
+ * @typedef {Object} UserCardEmits
+ * @property {(id: string) => void} select - Emitted when the card is selected
+ */
+const emit = defineEmits(['select'])
+
+/** @param {string} id */
+function handleSelect(id) {
+  emit('select', id)
+}
+</script>
+
+<template>
+  <div @click="handleSelect(props.name)">
+    {{ props.name }} ({{ props.age }})
+  </div>
+</template>
+```
+
+### Composable with @typedef, @param, and @returns
+
+```js
+// composables/useCounter.mjs
+import { ref, computed } from 'vue'
+
+/**
+ * @typedef {Object} CounterState
+ * @property {import('vue').Ref<number>} count - Reactive count value
+ * @property {import('vue').ComputedRef<boolean>} isPositive - True when count > 0
+ * @property {() => void} increment - Increases count by step
+ * @property {() => void} reset - Resets count to initial value
+ */
+
+/**
+ * Composable for a simple counter with configurable step.
+ * @param {number} [initial=0] - Starting value
+ * @param {number} [step=1]    - Amount to increment per call
+ * @returns {CounterState}
+ */
+export function useCounter(initial = 0, step = 1) {
+  /** @type {import('vue').Ref<number>} */
+  const count = ref(initial)
+
+  const isPositive = computed(() => count.value > 0)
+
+  function increment() {
+    count.value += step
+  }
+
+  function reset() {
+    count.value = initial
+  }
+
+  return { count, isPositive, increment, reset }
+}
+```
+
+### @typedef for a complex object used across files
+
+```js
+// types/user.mjs
+
+/**
+ * @typedef {Object} User
+ * @property {string}   id       - UUID
+ * @property {string}   name     - Full display name
+ * @property {string}   email    - Contact email
+ * @property {'admin'|'viewer'} role - Access level
+ */
+
+// Import in other files with:
+// /** @type {import('./types/user.mjs').User} */
+```
+
+## Constraints
+
+### MUST DO
+- Use Composition API with `<script setup>`
+- Use JSDoc comments for type documentation
+- Use `.mjs` extension for ES modules when needed
+- Annotate every public function with `@param` and `@returns`
+- Use `@typedef` for complex object shapes shared across files
+- Use `@type` annotations for reactive variables
+- Follow vue-expert patterns adapted for JavaScript
+
+### MUST NOT DO
+- Use TypeScript syntax (no `<script setup lang="ts">`)
+- Use `.ts` file extensions
+- Skip JSDoc types for public APIs
+- Use CommonJS `require()` in Vue files
+- Ignore type safety entirely
+- Mix TypeScript files with JavaScript in the same component
+
+## Output Templates
+
+When implementing Vue features in JavaScript:
+1. Component file with `<script setup>` (no lang attribute) and JSDoc-typed props/emits
+2. `@typedef` definitions for complex prop or state shapes
+3. Composable with `@param` and `@returns` annotations
+4. Brief note on type coverage
+
+## Knowledge Reference
+
+Vue 3 Composition API, JSDoc, ESM modules, Pinia, Vue Router 4, Vite, VueUse, Vitest, Vue Test Utils, JavaScript ES2022+

package/skills/frontend/vue-expert-js/references/component-architecture.md

@@ -0,0 +1,219 @@
+# Component Architecture
+
+---
+
+## Props
+
+```vue
+<script setup>
+/**
+ * @typedef {Object} Props
+ * @property {string} title - Required
+ * @property {string} [subtitle] - Optional
+ * @property {number} [count=0] - With default
+ */
+
+const props = defineProps({
+  title: { type: String, required: true },
+  subtitle: { type: String, default: '' },
+  count: { type: Number, default: 0 },
+  // Complex types
+  items: { type: Array, default: () => [] },
+  user: { type: Object, required: true },
+  // Validator
+  size: {
+    type: String,
+    default: 'medium',
+    validator: (v) => ['small', 'medium', 'large'].includes(v)
+  }
+})
+</script>
+```
+
+---
+
+## Emits
+
+```vue
+<script setup>
+const emit = defineEmits(['update', 'delete', 'close'])
+
+// With validation
+const emit = defineEmits({
+  /** @param {string} value */
+  update: (value) => typeof value === 'string',
+  /** @param {{ id: number }} payload */
+  delete: (payload) => typeof payload?.id === 'number',
+  close: null
+})
+
+// Usage
+emit('update', 'new value')
+emit('delete', { id: 1 })
+</script>
+```
+
+---
+
+## v-model
+
+```vue
+<!-- Single v-model -->
+<script setup>
+const props = defineProps({ modelValue: { type: String, required: true } })
+const emit = defineEmits(['update:modelValue'])
+</script>
+
+<template>
+  <input :value="modelValue" @input="emit('update:modelValue', $event.target.value)" />
+</template>
+```
+
+```vue
+<!-- Multiple v-models: v-model:firstName, v-model:lastName -->
+<script setup>
+defineProps({ firstName: String, lastName: String })
+defineEmits(['update:firstName', 'update:lastName'])
+</script>
+```
+
+---
+
+## Slots
+
+```vue
+<!-- Card.vue -->
+<template>
+  <div class="card">
+    <header v-if="$slots.header"><slot name="header" /></header>
+    <div class="card-body"><slot /></div>
+    <footer v-if="$slots.footer"><slot name="footer" /></footer>
+  </div>
+</template>
+```
+
+```vue
+<!-- Scoped slot -->
+<template>
+  <ul>
+    <li v-for="(item, index) in items" :key="item.id">
+      <slot name="item" :item="item" :index="index">
+        {{ item.name }}
+      </slot>
+    </li>
+  </ul>
+</template>
+
+<!-- Usage -->
+<DataList :items="users">
+  <template #item="{ item, index }">
+    {{ index + 1 }}. {{ item.name }}
+  </template>
+</DataList>
+```
+
+---
+
+## Provide / Inject
+
+```vue
+<!-- Provider.vue -->
+<script setup>
+import { provide, ref, readonly } from 'vue'
+
+const theme = ref('light')
+provide('theme', readonly(theme))
+provide('setTheme', (t) => { theme.value = t })
+</script>
+```
+
+```vue
+<!-- Consumer.vue -->
+<script setup>
+import { inject, ref } from 'vue'
+
+const theme = inject('theme', ref('light'))
+const setTheme = inject('setTheme', () => {})
+</script>
+```
+
+```javascript
+// Composable pattern
+// composables/useTheme.js
+import { ref, provide, inject, readonly, computed } from 'vue'
+
+const ThemeSymbol = Symbol('theme')
+
+export function provideTheme(initial = 'light') {
+  const theme = ref(initial)
+  const isDark = computed(() => theme.value === 'dark')
+  const toggle = () => { theme.value = theme.value === 'light' ? 'dark' : 'light' }
+
+  provide(ThemeSymbol, { theme: readonly(theme), isDark, toggle })
+  return { theme, isDark, toggle }
+}
+
+export function useTheme() {
+  const ctx = inject(ThemeSymbol)
+  if (!ctx) throw new Error('useTheme requires ThemeProvider')
+  return ctx
+}
+```
+
+---
+
+## Dynamic Components
+
+```vue
+<script setup>
+import { shallowRef, markRaw } from 'vue'
+import TabHome from './TabHome.vue'
+import TabProfile from './TabProfile.vue'
+
+const tabs = [
+  { name: 'Home', component: markRaw(TabHome) },
+  { name: 'Profile', component: markRaw(TabProfile) }
+]
+
+const currentTab = shallowRef(tabs[0].component)
+</script>
+
+<template>
+  <button v-for="tab in tabs" :key="tab.name" @click="currentTab = tab.component">
+    {{ tab.name }}
+  </button>
+  <KeepAlive>
+    <component :is="currentTab" />
+  </KeepAlive>
+</template>
+```
+
+```javascript
+// Async component
+import { defineAsyncComponent } from 'vue'
+
+const AsyncModal = defineAsyncComponent({
+  loader: () => import('./Modal.vue'),
+  delay: 200,
+  timeout: 10000
+})
+```
+
+---
+
+## Quick Reference
+
+| Feature | Syntax |
+|---------|--------|
+| Required prop | `{ type: String, required: true }` |
+| Default prop | `{ type: Number, default: 0 }` |
+| Array/Object default | `{ type: Array, default: () => [] }` |
+| Emit event | `emit('eventName', payload)` |
+| v-model | `modelValue` prop + `update:modelValue` emit |
+| Named v-model | `v-model:name` → `name` prop + `update:name` emit |
+| Default slot | `<slot />` |
+| Named slot | `<slot name="header" />` → `#header` |
+| Scoped slot | `<slot :item="item" />` → `#default="{ item }"` |
+| Provide | `provide('key', value)` |
+| Inject | `inject('key', defaultValue)` |
+| Dynamic component | `<component :is="comp" />` |

package/skills/frontend/vue-expert-js/references/composables-patterns.md

@@ -0,0 +1,183 @@
+# Composables Patterns
+
+---
+
+## Basic Composable Structure
+
+```javascript
+// composables/useToggle.js
+import { ref } from 'vue'
+
+/**
+ * @typedef {Object} UseToggleReturn
+ * @property {import('vue').Ref<boolean>} value
+ * @property {() => void} toggle
+ */
+
+/**
+ * @param {boolean} [initialValue=false]
+ * @returns {UseToggleReturn}
+ */
+export function useToggle(initialValue = false) {
+  const value = ref(initialValue)
+  const toggle = () => { value.value = !value.value }
+  return { value, toggle }
+}
+```
+
+---
+
+## Ref vs Reactive
+
+```javascript
+import { ref, reactive, toRefs, toValue } from 'vue'
+
+// Use ref for: primitives, reassignable values, composable returns
+/** @type {import('vue').Ref<number>} */
+const count = ref(0)
+
+// Use reactive for: complex objects with nested properties
+/** @type {{ email: string, password: string }} */
+const form = reactive({ email: '', password: '' })
+
+// Convert reactive to refs for destructuring
+const { email, password } = toRefs(form)
+
+// Unwrap ref or return plain value
+/** @param {number | import('vue').Ref<number>} maybeRef */
+function double(maybeRef) {
+  return toValue(maybeRef) * 2
+}
+```
+
+---
+
+## Lifecycle Hooks
+
+```javascript
+// composables/useEventListener.js
+import { onMounted, onUnmounted, toValue } from 'vue'
+
+/**
+ * @template {keyof WindowEventMap} K
+ * @param {K} event
+ * @param {(ev: WindowEventMap[K]) => void} handler
+ * @param {EventTarget | import('vue').Ref<EventTarget>} [target=window]
+ */
+export function useEventListener(event, handler, target = window) {
+  onMounted(() => toValue(target).addEventListener(event, handler))
+  onUnmounted(() => toValue(target).removeEventListener(event, handler))
+}
+```
+
+```javascript
+// Lifecycle-aware async (prevents state updates after unmount)
+import { ref, onUnmounted } from 'vue'
+
+export function useAsyncState(fn) {
+  const data = ref(null)
+  const loading = ref(false)
+  let isMounted = true
+
+  onUnmounted(() => { isMounted = false })
+
+  async function execute() {
+    loading.value = true
+    try {
+      const result = await fn()
+      if (isMounted) data.value = result
+    } finally {
+      if (isMounted) loading.value = false
+    }
+  }
+
+  return { data, loading, execute }
+}
+```
+
+---
+
+## Shared State (Singleton)
+
+```javascript
+// composables/useNotifications.js
+import { ref, readonly } from 'vue'
+
+// Module-level state = singleton shared across all components
+/** @type {import('vue').Ref<Array<{id: string, message: string}>>} */
+const notifications = ref([])
+
+export function useNotifications() {
+  /** @param {string} message */
+  function notify(message) {
+    const id = Date.now().toString()
+    notifications.value.push({ id, message })
+    setTimeout(() => dismiss(id), 5000)
+  }
+
+  /** @param {string} id */
+  function dismiss(id) {
+    notifications.value = notifications.value.filter(n => n.id !== id)
+  }
+
+  return {
+    notifications: readonly(notifications),
+    notify,
+    dismiss
+  }
+}
+```
+
+---
+
+## Async with Cancellation
+
+```javascript
+// composables/useCancellableFetch.js
+import { ref, onUnmounted } from 'vue'
+
+export function useCancellableFetch() {
+  const data = ref(null)
+  const error = ref(null)
+  const loading = ref(false)
+  /** @type {AbortController | null} */
+  let controller = null
+
+  /** @param {string} url */
+  async function execute(url) {
+    controller?.abort()
+    controller = new AbortController()
+    loading.value = true
+    error.value = null
+
+    try {
+      const res = await fetch(url, { signal: controller.signal })
+      data.value = await res.json()
+    } catch (e) {
+      if (/** @type {Error} */ (e).name !== 'AbortError') {
+        error.value = /** @type {Error} */ (e)
+      }
+    } finally {
+      loading.value = false
+    }
+  }
+
+  onUnmounted(() => controller?.abort())
+
+  return { data, error, loading, execute }
+}
+```
+
+---
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `ref()` | Primitives, values passed to/from composables |
+| `reactive()` | Objects with nested reactivity |
+| `toRefs()` | Destructure reactive while keeping reactivity |
+| `toValue()` | Unwrap ref or return plain value |
+| Module-level ref | Singleton shared state |
+| Factory function | New instance per component |
+| `onUnmounted` | Cleanup timers, listeners, abort controllers |