@dianzhong/create-harness-app 0.1.2 → 0.1.3

package/templates/harness/full/.agents/skills/vue-best-practices/references/component-data-flow.md

@@ -1,313 +0,0 @@
----
-title: Component Data Flow Best Practices
-impact: HIGH
-impactDescription: Clear data flow between components prevents state bugs, stale UI, and brittle coupling
-type: best-practice
-tags: [vue3, props, emits, v-model, provide-inject, data-flow, typescript]
----
-
-# Component Data Flow Best Practices
-
-**Impact: HIGH** - Vue components stay reliable when data flow is explicit: props go down, events go up, `v-model` handles two-way bindings, and provide/inject supports cross-tree dependencies. Blurring these boundaries leads to stale state, hidden coupling, and hard-to-debug UI.
-
-The main principle of data flow in Vue.js is **Props Down / Events Up**. This is the most maintainable default, and one-way flow scales well.
-
-## Task List
-
-- Treat props as read-only inputs
-- Use props/emit for component communication; reserve refs for imperative actions
-- When refs are required for imperative APIs, type them with template refs
-- Emit events instead of mutating parent state directly
-- Use `defineModel` for v-model in modern Vue (3.4+)
-- Handle v-model modifiers deliberately in child components
-- Use symbols for provide/inject keys to avoid props drilling (over ~3 layers)
-- Keep mutations in the provider or expose explicit actions
-- In TypeScript projects, prefer type-based `defineProps`, `defineEmits`, and `InjectionKey`
-
-## Props: One-Way Data Down
-
-Props are inputs. Do not mutate them in the child.
-
-**BAD:**
-
-```vue
-<script setup>
-const props = defineProps({ count: Number })
-
-function increment() {
-  props.count++
-}
-</script>
-```
-
-**GOOD:**
-
-If state needs to change, emit an event, use `v-model` or create a local copy.
-
-## Prefer props/emit over component refs
-
-**BAD:**
-
-```vue
-<script setup>
-import { ref } from 'vue'
-
-import UserForm from './UserForm.vue'
-
-const formRef = ref(null)
-
-function submitForm() {
-  if (formRef.value.isValid) {
-    formRef.value.submit()
-  }
-}
-</script>
-
-<template>
-  <UserForm ref="formRef" />
-  <button @click="submitForm">Submit</button>
-</template>
-```
-
-**GOOD:**
-
-```vue
-<script setup>
-import UserForm from './UserForm.vue'
-
-function handleSubmit(formData) {
-  api.submit(formData)
-}
-</script>
-
-<template>
-  <UserForm @submit="handleSubmit" />
-</template>
-```
-
-## Type component refs when imperative access is required
-
-Prefer props/emits by default. When a parent must call an exposed child method, type the ref explicitly and expose only the intended API from the child with `defineExpose`.
-
-**BAD:**
-
-```vue
-<script setup lang="ts">
-import { onMounted, ref } from 'vue'
-
-import DialogPanel from './DialogPanel.vue'
-
-const panelRef = ref(null)
-
-onMounted(() => {
-  panelRef.value.open()
-})
-</script>
-
-<template>
-  <DialogPanel ref="panelRef" />
-</template>
-```
-
-**GOOD:**
-
-```vue
-<!-- DialogPanel.vue -->
-<script setup lang="ts">
-function open() {}
-
-defineExpose({ open })
-</script>
-```
-
-```vue
-<!-- Parent.vue -->
-<script setup lang="ts">
-import { onMounted, useTemplateRef } from 'vue'
-
-import DialogPanel from './DialogPanel.vue'
-
-// Vue 3.5+ with useTemplateRef
-const panelRef = useTemplateRef('panelRef')
-
-// Before Vue 3.5 with manual typing and ref
-// const panelRef = ref<InstanceType<typeof DialogPanel> | null>(null)
-
-onMounted(() => {
-  panelRef.value?.open()
-})
-</script>
-
-<template>
-  <DialogPanel ref="panelRef" />
-</template>
-```
-
-## Emits: Explicit Events Up
-
-Component events do not bubble. If a parent needs to know about an event, re-emit it explicitly.
-
-**BAD:**
-
-```vue
-<!-- Parent expects "saved" from grandchild, but it won't bubble -->
-<Child @saved="onSaved" />
-```
-
-**GOOD:**
-
-```vue
-<!-- Child.vue -->
-<script setup>
-const emit = defineEmits(['saved'])
-
-function onGrandchildSaved(payload) {
-  emit('saved', payload)
-}
-</script>
-
-<template>
-  <Grandchild @saved="onGrandchildSaved" />
-</template>
-```
-
-**Event naming:** use kebab-case in templates and camelCase in script:
-
-```vue
-<script setup>
-const emit = defineEmits(['updateUser'])
-</script>
-
-<template>
-  <ProfileForm @update-user="emit('updateUser', $event)" />
-</template>
-```
-
-## `v-model`: Predictable Two-Way Bindings
-
-Use `defineModel` by default for component bindings and emit updates on input. Only use the `modelValue` + `update:modelValue` pattern if you are on Vue < 3.4.
-
-**BAD:**
-
-```vue
-<script setup>
-const props = defineProps({ value: String })
-</script>
-
-<template>
-  <input :value="props.value" @input="$emit('input', $event.target.value)" />
-</template>
-```
-
-**GOOD (Vue 3.4+):**
-
-```vue
-<script setup>
-const model = defineModel({ type: String })
-</script>
-
-<template>
-  <input v-model="model" />
-</template>
-```
-
-**GOOD (Vue < 3.4):**
-
-```vue
-<script setup>
-const props = defineProps({ modelValue: String })
-const emit = defineEmits(['update:modelValue'])
-</script>
-
-<template>
-  <input :value="props.modelValue" @input="emit('update:modelValue', $event.target.value)" />
-</template>
-```
-
-If you need the updated value immediately after a change, use the input event value or `nextTick` in the parent.
-
-## Provide/Inject: Shared Context Without Prop Drilling
-
-Use provide/inject for cross-tree state, but keep mutations centralized in the provider and expose explicit actions.
-
-**BAD:**
-
-```vue
-// Provider.vue provide('theme', reactive({ dark: false })) // Consumer.vue const theme =
-inject('theme') // Mutating shared state from any depth becomes hard to track theme.dark = true
-```
-
-**GOOD:**
-
-```vue
-// Provider.vue const theme = reactive({ dark: false }) const toggleTheme = () => { theme.dark =
-!theme.dark } provide(themeKey, readonly(theme)) provide(themeActionsKey, { toggleTheme }) //
-Consumer.vue const theme = inject(themeKey) const { toggleTheme } = inject(themeActionsKey)
-```
-
-Use symbols for keys to avoid collisions in large apps:
-
-```ts
-export const themeKey = Symbol('theme')
-export const themeActionsKey = Symbol('theme-actions')
-```
-
-## Use TypeScript Contracts for Public Component APIs
-
-In TypeScript projects, type component boundaries directly with `defineProps`, `defineEmits`, and `InjectionKey` so invalid payloads and mismatched injections fail at compile time.
-
-**BAD:**
-
-```vue
-<script setup lang="ts">
-import { inject } from 'vue'
-
-const props = defineProps({
-  userId: String,
-})
-
-const emit = defineEmits(['save'])
-const settings = inject('settings')
-
-// Payload shape is not checked here
-emit('save', 123)
-
-// Key is string-based and not type-safe
-settings?.theme = 'dark'
-</script>
-```
-
-**GOOD:**
-
-```vue
-<script setup lang="ts">
-import type { InjectionKey } from 'vue'
-
-import { inject, provide } from 'vue'
-
-interface Props {
-  userId: string
-}
-
-interface Emits {
-  save: [payload: { id: string; draft: boolean }]
-}
-
-interface Settings {
-  theme: 'light' | 'dark'
-}
-
-const props = defineProps<Props>()
-
-const emit = defineEmits<Emits>()
-
-const settingsKey: InjectionKey<Settings> = Symbol('settings')
-
-provide(settingsKey, { theme: 'light' })
-
-const settings = inject(settingsKey)
-if (settings) {
-  emit('save', { id: props.userId, draft: false })
-}
-</script>
-```

package/templates/harness/full/.agents/skills/vue-best-practices/references/component-fallthrough-attrs.md

@@ -1,179 +0,0 @@
----
-title: Component Fallthrough Attributes Best Practices
-impact: MEDIUM
-impactDescription: Incorrect $attrs access and reactivity assumptions can cause undefined values and watchers that never run
-type: best-practice
-tags: [vue3, attrs, fallthrough-attributes, composition-api, reactivity]
----
-
-# Component Fallthrough Attributes Best Practices
-
-**Impact: MEDIUM** - Fallthrough attributes are straightforward once you follow Vue's conventions: hyphenated names use bracket notation, listener keys are camelCase `onX`, and `useAttrs()` is current-but-not-reactive.
-
-## Task List
-
-- Access hyphenated attribute names with bracket notation (for example `attrs['data-testid']`)
-- Access event listeners with camelCase `onX` keys (for example `attrs.onClick`)
-- Do not `watch()` values returned from `useAttrs()`; those watchers do not trigger on attr changes
-- Use `onUpdated()` for attr-driven side effects
-- Promote frequently observed attrs to props when reactive observation is required
-
-## Access Attribute and Listener Keys Correctly
-
-Hyphenated attribute names preserve their original casing in JavaScript, so dot notation does not work for keys that include `-`.
-
-**BAD:**
-
-```vue
-<script setup>
-import { useAttrs } from 'vue'
-
-const attrs = useAttrs()
-
-console.log(attrs.data - testid) // Syntax error
-console.log(attrs.dataTestid) // undefined for data-testid
-console.log(attrs['on-click']) // undefined
-console.log(attrs['@click']) // undefined
-</script>
-```
-
-**GOOD:**
-
-```vue
-<script setup>
-import { useAttrs } from 'vue'
-
-const attrs = useAttrs()
-
-console.log(attrs['data-testid'])
-console.log(attrs['aria-label'])
-console.log(attrs['foo-bar'])
-
-console.log(attrs.onClick)
-console.log(attrs.onCustomEvent)
-console.log(attrs.onMouseEnter)
-</script>
-```
-
-### Naming Reference
-
-| Parent Usage              | Access in `attrs`              |
-| ------------------------- | ------------------------------ |
-| `class="foo"`             | `attrs.class`                  |
-| `data-id="123"`           | `attrs['data-id']`             |
-| `aria-label="..."`        | `attrs['aria-label']`          |
-| `foo-bar="baz"`           | `attrs['foo-bar']`             |
-| `@click="fn"`             | `attrs.onClick`                |
-| `@custom-event="fn"`      | `attrs.onCustomEvent`          |
-| `@update:modelValue="fn"` | `attrs['onUpdate:modelValue']` |
-
-## `useAttrs()` Is Not Reactive
-
-`useAttrs()` always reflects the latest values, but it is intentionally not reactive for watcher tracking.
-
-**BAD:**
-
-```vue
-<script setup>
-import { useAttrs, watch, watchEffect } from 'vue'
-
-const attrs = useAttrs()
-
-watch(
-  () => attrs.someAttr,
-  (newValue) => {
-    console.log('Changed:', newValue) // Never runs on attr changes
-  },
-)
-
-watchEffect(() => {
-  console.log(attrs.class) // Runs on setup, not on attr updates
-})
-</script>
-```
-
-**GOOD:**
-
-```vue
-<script setup>
-import { onUpdated, useAttrs } from 'vue'
-
-const attrs = useAttrs()
-
-onUpdated(() => {
-  console.log('Latest attrs:', attrs)
-})
-</script>
-```
-
-**GOOD:**
-
-```vue
-<script setup>
-import { watch } from 'vue'
-
-const props = defineProps({
-  someAttr: String,
-})
-
-watch(
-  () => props.someAttr,
-  (newValue) => {
-    console.log('Changed:', newValue)
-  },
-)
-</script>
-```
-
-## Common Patterns
-
-### Check for optional attrs safely
-
-```vue
-<script setup>
-import { computed, useAttrs } from 'vue'
-
-const attrs = useAttrs()
-
-const hasTestId = computed(() => 'data-testid' in attrs)
-const ariaLabel = computed(() => attrs['aria-label'] ?? 'Default label')
-</script>
-```
-
-### Forward listeners after internal logic
-
-```vue
-<script setup>
-import { useAttrs } from 'vue'
-
-defineOptions({ inheritAttrs: false })
-
-const attrs = useAttrs()
-
-function handleClick(event) {
-  console.log('Internal handling first')
-  attrs.onClick?.(event)
-}
-</script>
-
-<template>
-  <button @click="handleClick">
-    <slot />
-  </button>
-</template>
-```
-
-## TypeScript Notes
-
-`useAttrs()` is typed as `Record<string, unknown>`, so cast individual keys when needed.
-
-```vue
-<script setup lang="ts">
-import { useAttrs } from 'vue'
-
-const attrs = useAttrs()
-
-const testId = attrs['data-testid'] as string | undefined
-const onClick = attrs.onClick as ((event: MouseEvent) => void) | undefined
-</script>
-```

package/templates/harness/full/.agents/skills/vue-best-practices/references/component-keep-alive.md

@@ -1,139 +0,0 @@
----
-title: KeepAlive Component Best Practices
-impact: HIGH
-impactDescription: KeepAlive caches component instances; misuse causes stale data, memory growth, or unexpected lifecycle behavior
-type: best-practice
-tags: [vue3, keepalive, cache, performance, router, dynamic-components]
----
-
-# KeepAlive Component Best Practices
-
-**Impact: HIGH** - `<KeepAlive>` caches component instances instead of destroying them. Use it to preserve state across switches, but manage cache size and freshness explicitly to avoid memory growth or stale UI.
-
-## Task List
-
-- Use KeepAlive only where state preservation improves UX
-- Set a reasonable `max` to cap cache size
-- Declare component names for include/exclude matching
-- Use `onActivated`/`onDeactivated` for cache-aware logic
-- Decide how and when cached views refresh their data
-- Avoid caching memory-heavy or security-sensitive views
-
-## When to Use KeepAlive
-
-Use KeepAlive when switching between views where state should persist (tabs, multi-step forms, dashboards). Avoid it when each visit should start fresh.
-
-**BAD:**
-
-```vue
-<template>
-  <!-- State resets on every switch -->
-  <component :is="currentTab" />
-</template>
-```
-
-**GOOD:**
-
-```vue
-<template>
-  <!-- State preserved between switches -->
-  <KeepAlive>
-    <component :is="currentTab" />
-  </KeepAlive>
-</template>
-```
-
-## When NOT to Use KeepAlive
-
-- Search or filter pages where users expect fresh results
-- Memory-heavy components (maps, large tables, media players)
-- Sensitive flows where data must be cleared on exit
-- Components with heavy background activity you cannot pause
-
-## Limit and Control the Cache
-
-Always cap cache size with `max` and restrict caching to specific components when possible.
-
-```vue
-<template>
-  <KeepAlive :max="5" include="Dashboard,Settings">
-    <component :is="currentView" />
-  </KeepAlive>
-</template>
-```
-
-## Ensure Component Names Match include/exclude
-
-`include` and `exclude` match the component `name` option. Explicitly set names for reliable caching.
-
-```vue
-<!-- TabA.vue -->
-<script setup>
-defineOptions({ name: 'TabA' })
-</script>
-```
-
-```vue
-<template>
-  <KeepAlive include="TabA,TabB">
-    <component :is="currentTab" />
-  </KeepAlive>
-</template>
-```
-
-## Cache Invalidation Strategies
-
-Vue 3 has no direct API to remove a specific cached instance. Use keys or dynamic include/exclude to force refreshes.
-
-```vue
-<script setup>
-import { reactive, ref } from 'vue'
-
-const currentView = ref('Dashboard')
-const viewKeys = reactive({ Dashboard: 0, Settings: 0 })
-
-function invalidateCache(view) {
-  viewKeys[view]++
-}
-</script>
-
-<template>
-  <KeepAlive>
-    <component :is="currentView" :key="`${currentView}-${viewKeys[currentView]}`" />
-  </KeepAlive>
-</template>
-```
-
-## Lifecycle Hooks for Cached Components
-
-Cached components are not destroyed on switch. Use activation hooks for refresh and cleanup.
-
-```vue
-<script setup>
-import { onActivated, onDeactivated } from 'vue'
-
-onActivated(() => {
-  refreshData()
-})
-
-onDeactivated(() => {
-  pauseTimers()
-})
-</script>
-```
-
-## Router Caching and Freshness
-
-Decide whether navigation should show cached state or a fresh view. A common pattern is to key by route when params change.
-
-```vue
-<template>
-  <router-view v-slot="{ Component, route }">
-    <KeepAlive>
-      <component :is="Component" :key="route.fullPath" />
-    </KeepAlive>
-  </router-view>
-</template>
-```
-
-If you want cache reuse but fresh data, refresh in `onActivated` and compare query/params before fetching.