@dianzhong/create-harness-app 0.1.2 → 0.1.3

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 }
-}
-```

package/templates/harness/full/.agents/skills/vue-best-practices/references/directives.md

@@ -1,168 +0,0 @@
----
-title: Directive Best Practices
-impact: MEDIUM
-impactDescription: Custom directives are powerful but easy to misuse; following patterns prevents leaks, invalid usage, and unclear abstractions
-type: best-practice
-tags: [vue3, directives, custom-directives, composition, typescript]
----
-
-# Directive Best Practices
-
-**Impact: MEDIUM** - Directives are for low-level DOM access. Use them sparingly, keep them side-effect safe, and prefer components or composables when you need stateful or reusable UI behavior.
-
-## Task List
-
-- Use directives only when you need direct DOM access
-- Do not mutate directive arguments or binding objects
-- Clean up timers, listeners, and observers in `unmounted`
-- Register directives in `<script setup>` with the `v-` prefix
-- In TypeScript projects, type directive values and augment template directive types
-- Prefer components or composables for complex behavior
-
-## Treat Directive Arguments as Read-Only
-
-Directive bindings are not reactive storage. Don’t write to them.
-
-```ts
-const vFocus = {
-  mounted(el, binding) {
-    // binding.value is read-only
-    el.focus()
-  },
-}
-```
-
-## Avoid Directives on Components
-
-Directives apply to DOM elements. When used on components, they attach to the root element and can break if the root changes.
-
-**BAD:**
-
-```vue
-<MyInput v-focus />
-```
-
-**GOOD:**
-
-```vue
-<!-- MyInput.vue -->
-<script setup>
-const vFocus = (el) => el.focus()
-</script>
-
-<template>
-  <input v-focus />
-</template>
-```
-
-## Clean Up Side Effects in `unmounted`
-
-Any timers, listeners, or observers must be removed to avoid leaks.
-
-```ts
-const vResize = {
-  mounted(el) {
-    const observer = new ResizeObserver(() => {})
-    observer.observe(el)
-    el._observer = observer
-  },
-  unmounted(el) {
-    el._observer?.disconnect()
-  },
-}
-```
-
-## Prefer Function Shorthand for Single-Hook Directives
-
-If you only need `mounted`/`updated`, use the function form.
-
-```ts
-const vAutofocus = (el) => el.focus()
-```
-
-## Use the `v-` Prefix and Script Setup Registration
-
-```vue
-<script setup>
-const vFocus = (el) => el.focus()
-</script>
-
-<template>
-  <input v-focus />
-</template>
-```
-
-## Type Custom Directives in TypeScript Projects
-
-Use `Directive<Element, ValueType>` so `binding.value` is typed, and augment Vue's template types so directives are recognized in SFC templates.
-
-**BAD:**
-
-```ts
-// Untyped directive value and no template type augmentation
-export const vHighlight = {
-  mounted(el, binding) {
-    el.style.backgroundColor = binding.value
-  },
-}
-```
-
-**GOOD:**
-
-```ts
-import type { Directive } from 'vue'
-
-type HighlightValue = string
-
-export const vHighlight = {
-  mounted(el, binding) {
-    el.style.backgroundColor = binding.value
-  },
-} satisfies Directive<HTMLElement, HighlightValue>
-
-declare module 'vue' {
-  interface ComponentCustomProperties {
-    vHighlight: typeof vHighlight
-  }
-}
-```
-
-## Handle SSR with `getSSRProps`
-
-Directive hooks such as `mounted` and `updated` do not run during SSR. If a directive sets attributes/classes that affect rendered HTML, provide an SSR equivalent via `getSSRProps` to avoid hydration mismatches.
-
-**BAD:**
-
-```ts
-const vTooltip = {
-  mounted(el, binding) {
-    el.setAttribute('data-tooltip', binding.value)
-    el.classList.add('has-tooltip')
-  },
-}
-```
-
-**GOOD:**
-
-```ts
-const vTooltip = {
-  mounted(el, binding) {
-    el.setAttribute('data-tooltip', binding.value)
-    el.classList.add('has-tooltip')
-  },
-  getSSRProps(binding) {
-    return {
-      'data-tooltip': binding.value,
-      class: 'has-tooltip',
-    }
-  },
-}
-```
-
-## Prefer Declarative Templates When Possible
-
-If a standard attribute or binding works, use it instead of a directive.
-
-## Decide Between Directives and Components
-
-Use a directive for DOM-level behavior. Use a component when behavior affects structure, state, or rendering.