@dianzhong/create-harness-app 0.1.1 → 0.1.3

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

@@ -1,131 +0,0 @@
----
-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/.agents/skills/vue-best-practices/references/component-transition.md

@@ -1,135 +0,0 @@
----
-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/.agents/skills/vue-best-practices/references/composables.md

@@ -1,303 +0,0 @@
----
-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 }
-}
-```