@dianzhong/create-harness-app 0.1.0

package/templates/harness/full/.claude/skills/vue-best-practices/references/component-transition-group.md

@@ -0,0 +1,131 @@
+---
+title: TransitionGroup Component Best Practices
+impact: MEDIUM
+impactDescription: TransitionGroup animates list items; missing keys or misuse leads to broken list transitions
+type: best-practice
+tags: [vue3, transition-group, animation, lists, keys]
+---
+
+# TransitionGroup Component Best Practices
+
+**Impact: MEDIUM** - `<TransitionGroup>` animates lists of items entering, leaving, and moving. Use it for `v-for` lists or dynamic collections where individual items change over time.
+
+## Task List
+
+- Use `<TransitionGroup>` only for lists and repeated items
+- Provide unique, stable keys for every direct child
+- Use `tag` when you need semantic or layout wrappers
+- Avoid the `mode` prop (not supported)
+- Use JavaScript hooks for staggered effects
+
+## Use TransitionGroup for Lists
+
+`<TransitionGroup>` is designed for list items. Use `tag` to control the wrapper element when needed.
+
+**BAD:**
+
+```vue
+<template>
+  <TransitionGroup name="fade">
+    <ComponentA />
+    <ComponentB />
+  </TransitionGroup>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="item in items" :key="item.id">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+```
+
+## Always Provide Stable Keys
+
+Keys are required. Without stable keys, Vue cannot track item positions and animations break.
+
+**BAD:**
+
+```vue
+<template>
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="(item, index) in items" :key="index">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="item in items" :key="item.id">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+```
+
+## Do Not Use `mode` on TransitionGroup
+
+`mode` is only for `<Transition>` because it swaps a single element. Use `<Transition>` if you need in/out sequencing.
+
+**BAD:**
+
+```vue
+<template>
+  <TransitionGroup name="list" tag="div" mode="out-in">
+    <div v-for="item in items" :key="item.id">
+      {{ item.name }}
+    </div>
+  </TransitionGroup>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <Transition name="fade" mode="out-in">
+    <component :is="currentView" :key="currentView" />
+  </Transition>
+</template>
+```
+
+## Stagger List Animations with Data Attributes
+
+For cascading list animations, pass the index to JavaScript hooks and compute delay per item.
+
+```vue
+<script setup>
+function onBeforeEnter(el) {
+  el.style.opacity = 0
+  el.style.transform = 'translateY(12px)'
+}
+
+function onEnter(el, done) {
+  const delay = Number(el.dataset.index) * 80
+  setTimeout(() => {
+    el.style.transition = 'all 0.25s ease'
+    el.style.opacity = 1
+    el.style.transform = 'translateY(0)'
+    setTimeout(done, 250)
+  }, delay)
+}
+</script>
+
+<template>
+  <TransitionGroup tag="ul" :css="false" @before-enter="onBeforeEnter" @enter="onEnter">
+    <li v-for="(item, index) in items" :key="item.id" :data-index="index">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+```

package/templates/harness/full/.claude/skills/vue-best-practices/references/component-transition.md

@@ -0,0 +1,135 @@
+---
+title: Transition Component Best Practices
+impact: MEDIUM
+impactDescription: Transition animates a single element or component; incorrect structure or keys prevent animations
+type: best-practice
+tags: [vue3, transition, animation, performance, keys]
+---
+
+# Transition Component Best Practices
+
+**Impact: MEDIUM** - `<Transition>` animates entering/leaving of a single element or component. It is ideal for toggling UI states, swapping views, or animating one component at a time.
+
+## Task List
+
+- Wrap a single element or component inside `<Transition>`
+- Provide a `key` when switching between same element types
+- Use `mode="out-in"` when you need sequential swaps
+- Prefer `transform` and `opacity` for smooth animations
+
+## Use Transition for a Single Root Element
+
+`<Transition>` only supports one direct child. Wrap multiple nodes in a single element or component.
+
+**BAD:**
+
+```vue
+<template>
+  <Transition name="fade">
+    <h3>Title</h3>
+    <p>Description</p>
+  </Transition>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <Transition name="fade">
+    <div>
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </Transition>
+</template>
+```
+
+## Force Transitions Between Same Element Types
+
+Vue reuses the same DOM element when the tag type does not change. Add `key` so Vue treats it as a new element and triggers enter/leave.
+
+**BAD:**
+
+```vue
+<template>
+  <Transition name="fade">
+    <p v-if="isActive">Active</p>
+    <p v-else>Inactive</p>
+  </Transition>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <Transition name="fade" mode="out-in">
+    <p v-if="isActive" key="active">Active</p>
+    <p v-else key="inactive">Inactive</p>
+  </Transition>
+</template>
+```
+
+## Use `mode` to Avoid Overlap During Swaps
+
+When swapping components or views, use `mode="out-in"` to prevent both from being visible at the same time.
+
+**BAD:**
+
+```vue
+<template>
+  <Transition name="fade">
+    <component :is="currentView" />
+  </Transition>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <Transition name="fade" mode="out-in">
+    <component :is="currentView" :key="currentView" />
+  </Transition>
+</template>
+```
+
+## Animate `transform` and `opacity` for Performance
+
+Avoid layout-triggering properties such as `height`, `margin`, or `top`. Use `transform` and `opacity` for smooth, GPU-friendly transitions.
+
+**BAD:**
+
+```css
+.slide-enter-active,
+.slide-leave-active {
+  transition: height 0.3s ease;
+}
+
+.slide-enter-from,
+.slide-leave-to {
+  height: 0;
+}
+```
+
+**GOOD:**
+
+```css
+.slide-enter-active,
+.slide-leave-active {
+  transition:
+    transform 0.3s ease,
+    opacity 0.3s ease;
+}
+
+.slide-enter-from {
+  transform: translateX(-12px);
+  opacity: 0;
+}
+
+.slide-leave-to {
+  transform: translateX(12px);
+  opacity: 0;
+}
+```

package/templates/harness/full/.claude/skills/vue-best-practices/references/composables.md

@@ -0,0 +1,303 @@
+---
+title: Composable Organization Patterns
+impact: MEDIUM
+impactDescription: Well-structured composables improve maintainability, reusability, and update performance
+type: best-practice
+tags: [vue3, composables, composition-api, code-organization, api-design, readonly, utilities]
+---
+
+# Composable Organization Patterns
+
+**Impact: MEDIUM** - Treat composables as reusable, stateful building blocks and keep their code organized by feature concern. This keeps large components maintainable and prevents hard-to-debug mutation and API design issues.
+
+## Task List
+
+- Compose complex behavior from small, focused composables
+- Use options objects for composables with multiple optional parameters
+- Return readonly state when updates must flow through explicit actions
+- Keep pure utility functions as plain utilities, not composables
+- Organize composable and component code by feature concern, and extract composables when components grow
+
+## Compose Composables from Smaller Primitives
+
+**BAD:**
+
+```vue
+<script setup>
+import { computed, onMounted, onUnmounted, ref } from 'vue'
+
+const x = ref(0)
+const y = ref(0)
+const inside = ref(false)
+const el = ref(null)
+
+function onMove(e) {
+  x.value = e.pageX
+  y.value = e.pageY
+  if (!el.value) return
+  const r = el.value.getBoundingClientRect()
+  inside.value = x.value >= r.left && x.value <= r.right && y.value >= r.top && y.value <= r.bottom
+}
+
+onMounted(() => window.addEventListener('mousemove', onMove))
+onUnmounted(() => window.removeEventListener('mousemove', onMove))
+</script>
+```
+
+**GOOD:**
+
+```javascript
+// composables/useEventListener.js
+import { onMounted, onUnmounted, toValue } from 'vue'
+
+export function useEventListener(target, event, callback) {
+  onMounted(() => toValue(target).addEventListener(event, callback))
+  onUnmounted(() => toValue(target).removeEventListener(event, callback))
+}
+```
+
+```javascript
+// composables/useMouse.js
+import { ref } from 'vue'
+
+import { useEventListener } from './useEventListener'
+
+export function useMouse() {
+  const x = ref(0)
+  const y = ref(0)
+
+  useEventListener(window, 'mousemove', (e) => {
+    x.value = e.pageX
+    y.value = e.pageY
+  })
+
+  return { x, y }
+}
+```
+
+```javascript
+// composables/useMouseInElement.js
+import { computed } from 'vue'
+
+import { useMouse } from './useMouse'
+
+export function useMouseInElement(elementRef) {
+  const { x, y } = useMouse()
+
+  const isOutside = computed(() => {
+    if (!elementRef.value) return true
+    const rect = elementRef.value.getBoundingClientRect()
+    return (
+      x.value < rect.left || x.value > rect.right || y.value < rect.top || y.value > rect.bottom
+    )
+  })
+
+  return { x, y, isOutside }
+}
+```
+
+## Use Options Object Pattern for Composable Parameters
+
+**BAD:**
+
+```javascript
+export function useFetch(url, method, headers, timeout, retries, immediate) {
+  // hard to read and easy to misorder
+}
+
+useFetch('/api/users', 'GET', null, 5000, 3, true)
+```
+
+**GOOD:**
+
+```javascript
+export function useFetch(url, options = {}) {
+  const { method = 'GET', headers = {}, timeout = 30000, retries = 0, immediate = true } = options
+
+  // implementation
+  return { method, headers, timeout, retries, immediate }
+}
+
+useFetch('/api/users', {
+  method: 'POST',
+  timeout: 5000,
+  retries: 3,
+})
+```
+
+```typescript
+interface UseCounterOptions {
+  initial?: number
+  min?: number
+  max?: number
+  step?: number
+}
+
+export function useCounter(options: UseCounterOptions = {}) {
+  const { initial = 0, min = -Infinity, max = Infinity, step = 1 } = options
+  // implementation
+}
+```
+
+## Return Readonly State with Explicit Actions
+
+**BAD:**
+
+```javascript
+export function useCart() {
+  const items = ref([])
+  const total = computed(() => items.value.reduce((sum, item) => sum + item.price, 0))
+  return { items, total } // any consumer can mutate directly
+}
+
+const { items } = useCart()
+items.value.push({ id: 1, price: 10 })
+```
+
+**GOOD:**
+
+```javascript
+import { computed, readonly, ref } from 'vue'
+
+export function useCart() {
+  const _items = ref([])
+
+  const total = computed(() =>
+    _items.value.reduce((sum, item) => sum + item.price * item.quantity, 0),
+  )
+
+  function addItem(product, quantity = 1) {
+    const existing = _items.value.find((item) => item.id === product.id)
+    if (existing) {
+      existing.quantity += quantity
+      return
+    }
+    _items.value.push({ ...product, quantity })
+  }
+
+  function removeItem(productId) {
+    _items.value = _items.value.filter((item) => item.id !== productId)
+  }
+
+  return {
+    items: readonly(_items),
+    total,
+    addItem,
+    removeItem,
+  }
+}
+```
+
+## Keep Utilities as Utilities
+
+**BAD:**
+
+```javascript
+export function useFormatters() {
+  const formatDate = (date) => new Intl.DateTimeFormat('en-US').format(date)
+  const formatCurrency = (amount) =>
+    new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount)
+  return { formatDate, formatCurrency }
+}
+
+const { formatDate } = useFormatters()
+```
+
+**GOOD:**
+
+```javascript
+// utils/formatters.js
+export function formatDate(date) {
+  return new Intl.DateTimeFormat('en-US').format(date)
+}
+
+export function formatCurrency(amount) {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+  }).format(amount)
+}
+```
+
+```javascript
+// composables/useInvoiceSummary.js
+import { computed } from 'vue'
+
+import { formatCurrency } from '@/utils/formatters'
+
+export function useInvoiceSummary(invoiceRef) {
+  const totalLabel = computed(() => formatCurrency(invoiceRef.value.total))
+  return { totalLabel }
+}
+```
+
+## Organize Composable and Component Code by Feature Concern
+
+**BAD:**
+
+```vue
+<script setup>
+import { computed, onMounted, ref, watch } from 'vue'
+
+const searchQuery = ref('')
+const items = ref([])
+const selected = ref(null)
+const showModal = ref(false)
+const sortBy = ref('name')
+const filter = ref('all')
+const loading = ref(false)
+
+const filtered = computed(() => items.value.filter((i) => i.category === filter.value))
+function openModal() {
+  showModal.value = true
+}
+const sorted = computed(() => [...filtered.value].sort(/* ... */))
+watch(searchQuery, () => {
+  /* ... */
+})
+onMounted(() => {
+  /* ... */
+})
+</script>
+```
+
+**GOOD:**
+
+```vue
+<script setup>
+import { useItems } from '@/composables/useItems'
+import { useSearch } from '@/composables/useSearch'
+import { useSelectionModal } from '@/composables/useSelectionModal'
+
+// Data
+const { items, loading, fetchItems } = useItems()
+
+// Search/filter/sort
+const { query, visibleItems } = useSearch(items)
+
+// Selection + modal
+const { selectedItem, isModalOpen, selectItem, closeModal } = useSelectionModal()
+</script>
+```
+
+```javascript
+// composables/useItems.js
+import { onMounted, ref } from 'vue'
+
+export function useItems() {
+  const items = ref([])
+  const loading = ref(false)
+
+  async function fetchItems() {
+    loading.value = true
+    try {
+      items.value = await api.getItems()
+    } finally {
+      loading.value = false
+    }
+  }
+
+  onMounted(fetchItems)
+  return { items, loading, fetchItems }
+}
+```