mdk-skills 2.2.0 → 2.2.2

package/.claude/backups/20260510.145651/skills/v3-fe-biz-patterns/references/use-loading.md

@@ -0,0 +1,114 @@
+# 通用 Loading 管理方案
+
+## 概述
+
+异步操作的 loading 状态管理是前端最基础的需求之一。`useLoading` 是一个极简的通用 loading 包装器，用最小的代码量解决 loading 状态控制问题。
+
+## 源码
+
+```ts
+// src/hooks/useLoading.ts
+import { ref } from 'vue'
+
+export function useLoading(initial = false) {
+  const loading = ref(initial)
+
+  async function withLoading<T>(fn: () => Promise<T>): Promise<T> {
+    loading.value = true
+    try {
+      return await fn()
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { loading, withLoading }
+}
+```
+
+核心逻辑只有一行：执行前设 `true`，finally 中设回 `false`，保证无论成功还是失败 loading 都能复位。
+
+## 使用示例
+
+### 表单提交
+
+```vue
+<script setup lang="ts">
+const { loading, withLoading } = useLoading()
+
+const onSubmit = async () => {
+  await withLoading(() => updateUser(form.value))
+}
+</script>
+
+<template>
+  <van-button :loading="loading" @click="onSubmit">提交</van-button>
+</template>
+```
+
+### 初始数据加载
+
+```vue
+<script setup lang="ts">
+const { loading, withLoading } = useLoading(true)  // 初始就为 true
+
+onMounted(() => {
+  withLoading(async () => {
+    await fetchUserInfo()
+    await fetchPermissions()
+  })
+})
+</script>
+
+<template>
+  <BaseLoading :loading="loading" type="spinner" text="正在加载..." vertical />
+  <template v-if="!loading">
+    <!-- 主体内容 -->
+  </template>
+</template>
+```
+
+### 多个独立 loading（初始加载 + 加载更多）
+
+```vue
+<script setup lang="ts">
+// 首次加载
+const { loading: initLoading, withLoading: withInitLoading } = useLoading()
+// 加载更多
+const { loading: moreLoading, withLoading: withMoreLoading } = useLoading()
+
+const onLoadMore = () => {
+  withMoreLoading(() => fetchHouseList(page + 1))
+}
+
+onMounted(() => {
+  withInitLoading(async () => {
+    await fetchHotSuggests()
+    await fetchCategories()
+    await fetchHouseList()
+  })
+})
+</script>
+
+<template>
+  <!-- 首次加载用全屏 loading -->
+  <BaseLoading :loading="initLoading" type="spinner" vertical />
+  <!-- 加载更多只影响底部 -->
+  <div v-if="moreLoading">加载更多...</div>
+</template>
+```
+
+## 常见问题
+
+| 场景 | 处理方式 |
+|------|---------|
+| 重复点击提交 | `loading` 为 true 时按钮置灰 / `:loading` 属性，无需额外逻辑 |
+| 多个请求并行 | 需要分别管理 loading 时创建多个 `useLoading` 实例 |
+| 组件卸载 | 不影响，`withLoading` 的 finally 中赋值不会有问题（Vue 会处理） |
+| 需要 loading 之外的状态 | 搭配 `error`、`data` 等额外 ref 使用，`useLoading` 只负责 loading |
+
+## 注意事项
+
+1. **不要滥用**：简单的 Boolean 控制直接写模板里就行，不需要每个异步操作都抽成一个 hook
+2. **区分 loading 粒度**：页面级 loading 用一个实例，列表加载更多用另一个实例，互不干扰
+3. **`withLoading` 的返回值**：它返回的是 `fn()` 的 Promise 结果，可以用它链式处理后续逻辑

package/.claude/backups/20260510.145651/skills/vue/.meta.json

@@ -0,0 +1,6 @@
+{
+  "name": "vue",
+  "version": "1.0.0",
+  "description": "Vue 3 组件/组合式函数开发，Composition API 最佳实践",
+  "tags": ["vue", "frontend", "composition-api"]
+}

package/.claude/backups/20260510.145651/skills/vue/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: vue
+description: Use when editing .vue files, creating Vue 3 components, writing composables, or testing Vue code - provides Composition API patterns, props/emits best practices, VueUse integration, and reactive destructuring guidance
+license: MIT
+---
+
+# Vue 3 Development
+
+Reference for Vue 3 Composition API patterns, component architecture, and testing practices.
+
+**Current stable:** Vue 3.5+ with enhanced reactivity performance (-56% memory, 10x faster array tracking), new SSR features, and improved developer experience.
+
+## Overview
+
+Progressive reference system for Vue 3 projects. Load only files relevant to current task to minimize context usage (~250 tokens base, 500-1500 per sub-file).
+
+## When to Use
+
+**Use this skill when:**
+
+- Writing `.vue` components
+- Creating composables (`use*` functions)
+- Building client-side utilities
+- Testing Vue components/composables
+
+**Use `nuxt` skill instead for:**
+
+- Server routes, API endpoints
+- File-based routing, middleware
+- Nuxt-specific patterns
+
+**For styled UI components:** use `nuxt-ui` skill
+**For headless accessible components:** use `reka-ui` skill
+**For VueUse composables:** use `vueuse` skill
+
+## Quick Reference
+
+| Working on...            | Load file                    |
+| ------------------------ | ---------------------------- |
+| `.vue` in `components/`  | references/components.md     |
+| File in `composables/`   | references/composables.md    |
+| File in `utils/`         | references/utils-client.md   |
+| `.spec.ts` or `.test.ts` | references/testing.md        |
+| TypeScript patterns      | references/typescript.md     |
+| Vue Router typing        | references/router.md         |
+| Reactivity (ref, watch)  | references/reactivity.md     |
+| Custom directives        | references/directives.md     |
+| Provide/inject           | references/provide-inject.md |
+| Edge cases, vue-tsc      | references/gotchas.md        |
+
+## Loading Files
+
+**Consider loading these reference files based on your task:**
+
+- [ ] [references/components.md](references/components.md) - if working in `components/` or writing `.vue` files
+- [ ] [references/composables.md](references/composables.md) - if creating composables (`use*` functions)
+- [ ] [references/utils-client.md](references/utils-client.md) - if working in `utils/` or writing client utilities
+- [ ] [references/testing.md](references/testing.md) - if writing `.spec.ts` or `.test.ts` files
+- [ ] [references/typescript.md](references/typescript.md) - if working with Vue TypeScript patterns or generics
+- [ ] [references/router.md](references/router.md) - if working with Vue Router or route typing
+- [ ] [references/reactivity.md](references/reactivity.md) - if using ref, reactive, computed, watch, or watchEffect
+- [ ] [references/directives.md](references/directives.md) - if creating or using custom directives
+- [ ] [references/provide-inject.md](references/provide-inject.md) - if using provide/inject patterns
+- [ ] [references/gotchas.md](references/gotchas.md) - if debugging edge cases or hydration issues
+
+**DO NOT load all files at once.** Load only what's relevant to your current task.
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+const { count = 0 } = defineProps<{ count?: number }>()
+const emit = defineEmits<{ update: [value: number] }>()
+</script>
+
+<template>
+  <button @click="emit('update', count + 1)">
+    Count: {{ count }}
+  </button>
+</template>
+```
+
+## Available Guidance
+
+**[references/components.md](references/components.md)** - Props with reactive destructuring, emits patterns, defineModel for v-model, slots shorthand
+
+**[references/composables.md](references/composables.md)** - Composition API structure, VueUse integration, lifecycle hooks, async patterns, reactivity gotchas
+
+**[references/utils-client.md](references/utils-client.md)** - Pure functions, formatters, validators, transformers, when NOT to use utils
+
+**[references/testing.md](references/testing.md)** - Vitest + @vue/test-utils, component testing, composable testing, router mocking
+
+**[references/typescript.md](references/typescript.md)** - InjectionKey for provide/inject, vue-tsc strict templates, tsconfig settings, generic components
+
+**[references/router.md](references/router.md)** - Route meta types, typed params with unplugin-vue-router, scroll behavior, navigation guards
+
+**[references/reactivity.md](references/reactivity.md)** - ref, reactive, computed, watch, watchEffect, reactivity fundamentals
+
+**[references/directives.md](references/directives.md)** - Custom directive hooks, v-focus, v-click-outside, v-tooltip patterns
+
+**[references/provide-inject.md](references/provide-inject.md)** - InjectionKey typing, app-level provide, readonly patterns
+
+**[references/gotchas.md](references/gotchas.md)** - Common gotchas, vue-tsc edge cases, hydration issues, race conditions (from vuejs-ai/skills)

package/.claude/backups/20260510.145651/skills/vue/references/components.md

@@ -0,0 +1,323 @@
+# Vue Components
+
+Patterns for Vue 3 components using Composition API with `<script setup>`.
+
+## Quick Reference
+
+| Pattern               | Syntax                                                          |
+| --------------------- | --------------------------------------------------------------- |
+| Props (destructured)  | `const { name = 'default' } = defineProps<{ name?: string }>()` |
+| Props (template-only) | `defineProps<{ name: string }>()`                               |
+| Emits                 | `const emit = defineEmits<{ click: [id: number] }>()`           |
+| Two-way binding       | `const model = defineModel<string>()`                           |
+| Slots shorthand       | `<template #header>` not `<template v-slot:header>`             |
+
+## Naming
+
+**Files:** PascalCase (`UserProfile.vue`) OR kebab-case (`user-profile.vue`) - be consistent
+
+**Component names in code:** Always PascalCase
+
+**Composition:** General → Specific: `SearchButtonClear.vue` not `ClearSearchButton.vue`
+
+## Props
+
+**Destructure with defaults (Vue 3.5+)** when used in script or need defaults:
+
+```ts
+const { count = 0, message = 'Hello' } = defineProps<{
+  count?: number
+  message?: string
+  required: boolean
+}>()
+
+// Use directly - maintains reactivity
+console.log(count + 1)
+
+// ⚠️ When passing to watchers/functions, wrap in getter:
+watch(() => count, (newVal) => { ... }) // ✅ Correct
+watch(count, (newVal) => { ... })        // ❌ Won't work
+```
+
+**Non-destructured** only if props ONLY used in template:
+
+```ts
+defineProps<{ count: number }>()
+// Template: {{ count }}
+```
+
+**Same-name shorthand (Vue 3.4+):** `:count` instead of `:count="count"`
+
+```vue
+<MyComponent :count :user :items />
+<!-- Same as: :count="count" :user="user" :items="items" -->
+```
+
+[Reactive destructuring docs](https://vuejs.org/guide/components/props#reactive-props-destructure)
+
+## Emits
+
+Type-safe event definitions:
+
+```ts
+const emit = defineEmits<{
+  update: [id: number, value: string] // multiple args
+  close: [] // no args
+}>()
+
+// Usage
+emit('update', 123, 'new value')
+emit('close')
+```
+
+**Template syntax:** kebab-case (`@update-item`) vs camelCase in script (`updateItem`)
+
+## Slots
+
+**Always use shorthand:** `<template #header>` not `<template v-slot:header>`
+
+**Always explicit `<template>` tags** for all slots
+
+```vue
+<template>
+  <Card>
+    <template #header>
+      <h2>Title</h2>
+    </template>
+    <template #default>
+      Content
+    </template>
+  </Card>
+</template>
+```
+
+## defineModel() - Two-Way Binding
+
+Replaces manual `modelValue` prop + `update:modelValue` emit.
+
+### Basic
+
+```vue
+<script setup lang="ts">
+const title = defineModel<string>()
+</script>
+
+<template>
+  <input v-model="title">
+</template>
+```
+
+### With Options
+
+```vue
+<script setup lang="ts">
+const [title, modifiers] = defineModel<string>({
+  default: 'default value',
+  required: true,
+  get: (value) => value.trim(),
+  set: (value) => {
+    if (modifiers.capitalize) {
+      return value.charAt(0).toUpperCase() + value.slice(1)
+    }
+    return value
+  },
+})
+</script>
+```
+
+**⚠️ Warning:** When using `default` without parent providing a value, parent and child can de-sync (parent `undefined`, child has default). Always provide matching defaults in parent or make prop required.
+
+**Prevent double-emit with `required: true`:**
+
+```ts
+// ❌ Without required - emits twice (undefined then value)
+const model = defineModel<Item>()
+
+// ✅ With required - single emit
+const model = defineModel<Item>({ required: true })
+```
+
+Use `required: true` when the model should always have a value to avoid the double-emit issue during initialization.
+
+### Multiple Models
+
+Default assumes `modelValue` prop. For multiple bindings, use explicit names:
+
+```vue
+<script setup lang="ts">
+const firstName = defineModel<string>('firstName')
+const age = defineModel<number>('age')
+</script>
+
+<!-- Usage -->
+<UserForm v-model:first-name="user.firstName" v-model:age="user.age" />
+```
+
+[v-model modifiers docs](https://vuejs.org/guide/components/v-model#handling-v-model-modifiers)
+
+## Reusable Templates
+
+For typed, scoped template snippets within a component:
+
+```vue
+<script setup lang="ts">
+import { createReusableTemplate } from '@vueuse/core'
+
+const [DefineItem, UseItem] = createReusableTemplate<{
+  item: SearchItem
+  icon: string
+  color?: 'red' | 'green' | 'blue'
+}>()
+</script>
+
+<template>
+  <DefineItem v-slot="{ item, icon, color }">
+    <div :class="color">
+      <Icon :name="icon" />
+      {{ item.name }}
+    </div>
+  </DefineItem>
+
+  <!-- Reuse multiple times -->
+  <UseItem v-for="item in items" :key="item.id" :item :icon="getIcon(item)" />
+</template>
+```
+
+## Template Refs (Vue 3.5+)
+
+Use `useTemplateRef()` for type-safe template references with IDE support:
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef, onMounted } from 'vue'
+
+const input = useTemplateRef<HTMLInputElement>('my-input')
+
+onMounted(() => {
+  input.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="my-input">
+</template>
+```
+
+**Benefits over `ref()`:**
+
+- Type-safe with generics
+- Better IDE autocomplete and refactoring
+- Explicit ref name as string literal
+
+**Dynamic refs:**
+
+```vue
+<script setup lang="ts">
+const items = ref(['a', 'b', 'c'])
+const itemRefs = useTemplateRef<HTMLElement>('item')
+
+// Access refs after mount
+onMounted(() => {
+  console.log(itemRefs.value) // Array of elements
+})
+</script>
+
+<template>
+  <div v-for="item in items" :key="item" ref="item">
+    {{ item }}
+  </div>
+</template>
+```
+
+**Component refs with generics:**
+
+For generic components, use `ComponentExposed` from `vue-component-type-helpers`:
+
+```ts
+import type { ComponentExposed } from 'vue-component-type-helpers'
+import MyGenericComponent from './MyGenericComponent.vue'
+
+// Get exposed methods/properties with correct generic types
+const compRef = useTemplateRef<ComponentExposed<typeof MyGenericComponent>>('comp')
+
+onMounted(() => {
+  compRef.value?.someExposedMethod() // Typed!
+})
+```
+
+Install: `pnpm add -D vue-component-type-helpers`
+
+## SSR Hydration (Vue 3.5+)
+
+**Suppress hydration mismatches** for values that differ between server/client:
+
+```vue
+<template>
+  <!-- Client-side only values -->
+  <span data-allow-mismatch>{{ new Date().toLocaleString() }}</span>
+
+  <!-- Specific mismatch types -->
+  <span data-allow-mismatch="text">{{ timestamp }}</span>
+  <span data-allow-mismatch="children">
+    <ClientOnly>...</ClientOnly>
+  </span>
+  <span data-allow-mismatch="style">...</span>
+  <span data-allow-mismatch="class">...</span>
+  <span data-allow-mismatch="attribute">...</span>
+</template>
+```
+
+**Generate SSR-stable IDs:**
+
+```vue
+<script setup lang="ts">
+import { useId } from 'vue'
+
+const id = useId() // Stable across server/client renders
+</script>
+
+<template>
+  <label :for="id">Name</label>
+  <input :id="id">
+</template>
+```
+
+## Deferred Teleport (Vue 3.5+)
+
+Teleport to elements rendered later in the same cycle:
+
+```vue
+<template>
+  <!-- This renders first -->
+  <Teleport defer to="#late-div">
+    <span>Deferred content</span>
+  </Teleport>
+
+  <!-- This renders after, but Teleport waits -->
+  <div id="late-div"></div>
+</template>
+```
+
+Without `defer`, teleport to `#late-div` would fail since it doesn't exist yet.
+
+## Common Mistakes
+
+**Using `const props =` with destructured values:**
+
+```ts
+// ❌ Wrong
+const props = defineProps<{ count: number }>()
+const { count } = props // Loses reactivity
+```
+
+**Forgetting TypeScript types:**
+
+```ts
+// ❌ Wrong
+const emit = defineEmits(['update'])
+
+// ✅ Correct
+const emit = defineEmits<{ update: [id: number] }>()
+```
+
+**Components >300 lines:** Split into smaller components or extract logic to composables