@gong-ym/ai-spec-auto 0.2.13 → 0.2.15

package/.agents/skills/profiles/vue/vue-best-practices/references/component-suspense.md

@@ -1,228 +1,228 @@
----
-title: Suspense Component Best Practices
-impact: MEDIUM
-impactDescription: Suspense coordinates async dependencies with fallback UI; misconfiguration leads to missing loading states or confusing UX
-type: best-practice
-tags: [vue3, suspense, async-components, async-setup, loading, fallback, router, transition, keepalive]
----
-
-# Suspense Component Best Practices
-
-**Impact: MEDIUM** - `<Suspense>` coordinates async dependencies (async components or async setup) and renders a fallback while they resolve. Misconfiguration leads to missing loading states, empty renders, or subtle UX bugs.
-
-## Task List
-
-- Wrap default and fallback slot content in a single root node
-- Use `timeout` when you need the fallback to appear on reverts
-- Force root replacement with `:key` when you need Suspense to re-trigger
-- Add `suspensible` to nested Suspense boundaries (Vue 3.3+)
-- Use `@pending`, `@resolve`, and `@fallback` for programmatic loading state
-- Nest `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` in that order
-- Keep Suspense usage centralized and documented in production
-
-## Single Root in Default and Fallback Slots
-
-Suspense tracks a single immediate child in both slots. Wrap multiple elements in a single element or component.
-
-**BAD:**
-```vue
-<template>
-  <Suspense>
-    <AsyncHeader />
-    <AsyncList />
-
-    <template #fallback>
-      <LoadingSpinner />
-      <LoadingHint />
-    </template>
-  </Suspense>
-</template>
-```
-
-**GOOD:**
-```vue
-<template>
-  <Suspense>
-    <div>
-      <AsyncHeader />
-      <AsyncList />
-    </div>
-
-    <template #fallback>
-      <div>
-        <LoadingSpinner />
-        <LoadingHint />
-      </div>
-    </template>
-  </Suspense>
-</template>
-```
-
-## Fallback Timing on Reverts (`timeout`)
-
-When Suspense is already resolved and new async work starts, the previous content remains visible until the timeout elapses. Use `timeout="0"` for immediate fallback or a short delay to avoid flicker.
-
-**BAD:**
-```vue
-<template>
-  <Suspense>
-    <component :is="currentView" :key="viewKey" />
-
-    <template #fallback>
-      Loading...
-    </template>
-  </Suspense>
-</template>
-```
-
-**GOOD:**
-```vue
-<template>
-  <Suspense :timeout="200">
-    <component :is="currentView" :key="viewKey" />
-
-    <template #fallback>
-      Loading...
-    </template>
-  </Suspense>
-</template>
-```
-
-## Pending State Only Re-triggers on Root Replacement
-
-Once resolved, Suspense only re-enters pending when the root node of the default slot changes. If async work happens deeper in the tree, no fallback appears.
-
-**BAD:**
-```vue
-<template>
-  <Suspense>
-    <TabContainer>
-      <AsyncDashboard v-if="tab === 'dashboard'" />
-      <AsyncSettings v-else />
-    </TabContainer>
-
-    <template #fallback>
-      Loading...
-    </template>
-  </Suspense>
-</template>
-```
-
-**GOOD:**
-```vue
-<template>
-  <Suspense>
-    <component :is="tabs[tab]" :key="tab" />
-
-    <template #fallback>
-      Loading...
-    </template>
-  </Suspense>
-</template>
-```
-
-## Use `suspensible` for Nested Suspense (Vue 3.3+)
-
-Nested Suspense boundaries need `suspensible` on the inner boundary so the parent can coordinate loading state. Without it, inner async content may render empty nodes until resolved.
-
-**BAD:**
-```vue
-<template>
-  <Suspense>
-    <LayoutShell>
-      <Suspense>
-        <AsyncWidget />
-        <template #fallback>Loading widget...</template>
-      </Suspense>
-    </LayoutShell>
-
-    <template #fallback>Loading layout...</template>
-  </Suspense>
-</template>
-```
-
-**GOOD:**
-```vue
-<template>
-  <Suspense>
-    <LayoutShell>
-      <Suspense suspensible>
-        <AsyncWidget />
-        <template #fallback>Loading widget...</template>
-      </Suspense>
-    </LayoutShell>
-
-    <template #fallback>Loading layout...</template>
-  </Suspense>
-</template>
-```
-
-## Track Loading with Suspense Events
-
-Use `@pending`, `@resolve`, and `@fallback` for analytics, global loading indicators, or coordinating UI outside the Suspense boundary.
-
-```vue
-<script setup>
-import { ref } from 'vue'
-
-const isLoading = ref(false)
-
-const onPending = () => {
-  isLoading.value = true
-}
-
-const onResolve = () => {
-  isLoading.value = false
-}
-</script>
-
-<template>
-  <LoadingBar v-if="isLoading" />
-
-  <Suspense @pending="onPending" @resolve="onResolve">
-    <AsyncPage />
-    <template #fallback>
-      <PageSkeleton />
-    </template>
-  </Suspense>
-</template>
-```
-
-## Recommended Nesting with RouterView, Transition, KeepAlive
-
-When combining these components, the nesting order should be `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` so each wrapper works correctly.
-
-**BAD:**
-```vue
-<template>
-  <RouterView v-slot="{ Component }">
-    <Suspense>
-      <KeepAlive>
-        <Transition mode="out-in">
-          <component :is="Component" />
-        </Transition>
-      </KeepAlive>
-    </Suspense>
-  </RouterView>
-</template>
-```
-
-**GOOD:**
-```vue
-<template>
-  <RouterView v-slot="{ Component }">
-    <Transition mode="out-in">
-      <KeepAlive>
-        <Suspense>
-          <component :is="Component" />
-          <template #fallback>Loading...</template>
-        </Suspense>
-      </KeepAlive>
-    </Transition>
-  </RouterView>
-</template>
-```
-
-## Treat Suspense Cautiously in Production
-
-In production code, keep Suspense boundaries minimal, document where they are used, and have a fallback loading strategy if you ever need to replace or refactor them.
+---
+title: Suspense Component Best Practices
+impact: MEDIUM
+impactDescription: Suspense coordinates async dependencies with fallback UI; misconfiguration leads to missing loading states or confusing UX
+type: best-practice
+tags: [vue3, suspense, async-components, async-setup, loading, fallback, router, transition, keepalive]
+---
+
+# Suspense Component Best Practices
+
+**Impact: MEDIUM** - `<Suspense>` coordinates async dependencies (async components or async setup) and renders a fallback while they resolve. Misconfiguration leads to missing loading states, empty renders, or subtle UX bugs.
+
+## Task List
+
+- Wrap default and fallback slot content in a single root node
+- Use `timeout` when you need the fallback to appear on reverts
+- Force root replacement with `:key` when you need Suspense to re-trigger
+- Add `suspensible` to nested Suspense boundaries (Vue 3.3+)
+- Use `@pending`, `@resolve`, and `@fallback` for programmatic loading state
+- Nest `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` in that order
+- Keep Suspense usage centralized and documented in production
+
+## Single Root in Default and Fallback Slots
+
+Suspense tracks a single immediate child in both slots. Wrap multiple elements in a single element or component.
+
+**BAD:**
+```vue
+<template>
+  <Suspense>
+    <AsyncHeader />
+    <AsyncList />
+
+    <template #fallback>
+      <LoadingSpinner />
+      <LoadingHint />
+    </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Suspense>
+    <div>
+      <AsyncHeader />
+      <AsyncList />
+    </div>
+
+    <template #fallback>
+      <div>
+        <LoadingSpinner />
+        <LoadingHint />
+      </div>
+    </template>
+  </Suspense>
+</template>
+```
+
+## Fallback Timing on Reverts (`timeout`)
+
+When Suspense is already resolved and new async work starts, the previous content remains visible until the timeout elapses. Use `timeout="0"` for immediate fallback or a short delay to avoid flicker.
+
+**BAD:**
+```vue
+<template>
+  <Suspense>
+    <component :is="currentView" :key="viewKey" />
+
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Suspense :timeout="200">
+    <component :is="currentView" :key="viewKey" />
+
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+## Pending State Only Re-triggers on Root Replacement
+
+Once resolved, Suspense only re-enters pending when the root node of the default slot changes. If async work happens deeper in the tree, no fallback appears.
+
+**BAD:**
+```vue
+<template>
+  <Suspense>
+    <TabContainer>
+      <AsyncDashboard v-if="tab === 'dashboard'" />
+      <AsyncSettings v-else />
+    </TabContainer>
+
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Suspense>
+    <component :is="tabs[tab]" :key="tab" />
+
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+## Use `suspensible` for Nested Suspense (Vue 3.3+)
+
+Nested Suspense boundaries need `suspensible` on the inner boundary so the parent can coordinate loading state. Without it, inner async content may render empty nodes until resolved.
+
+**BAD:**
+```vue
+<template>
+  <Suspense>
+    <LayoutShell>
+      <Suspense>
+        <AsyncWidget />
+        <template #fallback>Loading widget...</template>
+      </Suspense>
+    </LayoutShell>
+
+    <template #fallback>Loading layout...</template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <Suspense>
+    <LayoutShell>
+      <Suspense suspensible>
+        <AsyncWidget />
+        <template #fallback>Loading widget...</template>
+      </Suspense>
+    </LayoutShell>
+
+    <template #fallback>Loading layout...</template>
+  </Suspense>
+</template>
+```
+
+## Track Loading with Suspense Events
+
+Use `@pending`, `@resolve`, and `@fallback` for analytics, global loading indicators, or coordinating UI outside the Suspense boundary.
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const isLoading = ref(false)
+
+const onPending = () => {
+  isLoading.value = true
+}
+
+const onResolve = () => {
+  isLoading.value = false
+}
+</script>
+
+<template>
+  <LoadingBar v-if="isLoading" />
+
+  <Suspense @pending="onPending" @resolve="onResolve">
+    <AsyncPage />
+    <template #fallback>
+      <PageSkeleton />
+    </template>
+  </Suspense>
+</template>
+```
+
+## Recommended Nesting with RouterView, Transition, KeepAlive
+
+When combining these components, the nesting order should be `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` so each wrapper works correctly.
+
+**BAD:**
+```vue
+<template>
+  <RouterView v-slot="{ Component }">
+    <Suspense>
+      <KeepAlive>
+        <Transition mode="out-in">
+          <component :is="Component" />
+        </Transition>
+      </KeepAlive>
+    </Suspense>
+  </RouterView>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <RouterView v-slot="{ Component }">
+    <Transition mode="out-in">
+      <KeepAlive>
+        <Suspense>
+          <component :is="Component" />
+          <template #fallback>Loading...</template>
+        </Suspense>
+      </KeepAlive>
+    </Transition>
+  </RouterView>
+</template>
+```
+
+## Treat Suspense Cautiously in Production
+
+In production code, keep Suspense boundaries minimal, document where they are used, and have a fallback loading strategy if you ever need to replace or refactor them.

package/.agents/skills/profiles/vue/vue-best-practices/references/component-teleport.md

@@ -1,108 +1,108 @@
----
-title: Teleport Component Best Practices
-impact: MEDIUM
-impactDescription: Teleport renders content outside the component's DOM position, which is essential for overlays but affects styling and layout
-type: best-practice
-tags: [vue3, teleport, modal, overlay, positioning, responsive]
----
-
-# Teleport Component Best Practices
-
-**Impact: MEDIUM** - `<Teleport>` renders part of a component's template in a different place in the DOM while preserving the Vue component hierarchy. Use it for overlays (modals, toasts, tooltips) or any UI that must escape stacking contexts, overflow, or fixed positioning constraints.
-
-## Task List
-
-- Teleport overlays to `body` or a dedicated container outside the app root
-- Keep a shared target for similar UI (`#modals`, `#notifications`) and control layering with order or z-index
-- Use `:disabled` for responsive layouts that should render inline on small screens
-- Remember props, emits, and provide/inject still work through teleport
-- Avoid relying on parent stacking contexts or transforms for teleported UI
-
-## Teleport Overlays Out of Transformed Containers
-
-When an ancestor has `transform`, `filter`, or `perspective`, fixed-position overlays can behave like they are locally positioned. Teleport escapes that context.
-
-**BAD:**
-```vue
-<template>
-  <div class="animated-container">
-    <button @click="open = true">Open</button>
-
-    <!-- Broken: fixed positioning is scoped to the transformed parent -->
-    <div v-if="open" class="modal">Modal</div>
-  </div>
-</template>
-
-<style>
-.animated-container {
-  transform: translateZ(0);
-}
-
-.modal {
-  position: fixed;
-  inset: 0;
-  z-index: 9999;
-}
-</style>
-```
-
-**GOOD:**
-```vue
-<template>
-  <div class="animated-container">
-    <button @click="open = true">Open</button>
-
-    <Teleport to="body">
-      <div v-if="open" class="modal">Modal</div>
-    </Teleport>
-  </div>
-</template>
-```
-
-## Responsive Layouts with `disabled`
-
-Use `:disabled` to render inline on mobile and teleport on larger screens:
-
-```vue
-<script setup>
-import { useMediaQuery } from '@vueuse/core'
-
-const isMobile = useMediaQuery('(max-width: 768px)')
-</script>
-
-<template>
-  <Teleport to="body" :disabled="isMobile">
-    <nav class="sidebar">Navigation</nav>
-  </Teleport>
-</template>
-```
-
-## Logical Hierarchy Is Preserved
-
-Teleport changes DOM position, not the Vue component tree. Props, emits, slots, and provide/inject still work:
-
-```vue
-<template>
-  <Teleport to="body">
-    <ChildPanel :message="message" @close="open = false" />
-  </Teleport>
-</template>
-```
-
-## Multiple Teleports to the Same Target
-
-Teleports to the same target append in declaration order:
-
-```vue
-<template>
-  <Teleport to="#notifications">
-    <div>First</div>
-  </Teleport>
-
-  <Teleport to="#notifications">
-    <div>Second</div>
-  </Teleport>
-</template>
-```
-
-Use a shared container to keep stacking predictable, and apply z-index only when you need explicit layering.
+---
+title: Teleport Component Best Practices
+impact: MEDIUM
+impactDescription: Teleport renders content outside the component's DOM position, which is essential for overlays but affects styling and layout
+type: best-practice
+tags: [vue3, teleport, modal, overlay, positioning, responsive]
+---
+
+# Teleport Component Best Practices
+
+**Impact: MEDIUM** - `<Teleport>` renders part of a component's template in a different place in the DOM while preserving the Vue component hierarchy. Use it for overlays (modals, toasts, tooltips) or any UI that must escape stacking contexts, overflow, or fixed positioning constraints.
+
+## Task List
+
+- Teleport overlays to `body` or a dedicated container outside the app root
+- Keep a shared target for similar UI (`#modals`, `#notifications`) and control layering with order or z-index
+- Use `:disabled` for responsive layouts that should render inline on small screens
+- Remember props, emits, and provide/inject still work through teleport
+- Avoid relying on parent stacking contexts or transforms for teleported UI
+
+## Teleport Overlays Out of Transformed Containers
+
+When an ancestor has `transform`, `filter`, or `perspective`, fixed-position overlays can behave like they are locally positioned. Teleport escapes that context.
+
+**BAD:**
+```vue
+<template>
+  <div class="animated-container">
+    <button @click="open = true">Open</button>
+
+    <!-- Broken: fixed positioning is scoped to the transformed parent -->
+    <div v-if="open" class="modal">Modal</div>
+  </div>
+</template>
+
+<style>
+.animated-container {
+  transform: translateZ(0);
+}
+
+.modal {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+}
+</style>
+```
+
+**GOOD:**
+```vue
+<template>
+  <div class="animated-container">
+    <button @click="open = true">Open</button>
+
+    <Teleport to="body">
+      <div v-if="open" class="modal">Modal</div>
+    </Teleport>
+  </div>
+</template>
+```
+
+## Responsive Layouts with `disabled`
+
+Use `:disabled` to render inline on mobile and teleport on larger screens:
+
+```vue
+<script setup>
+import { useMediaQuery } from '@vueuse/core'
+
+const isMobile = useMediaQuery('(max-width: 768px)')
+</script>
+
+<template>
+  <Teleport to="body" :disabled="isMobile">
+    <nav class="sidebar">Navigation</nav>
+  </Teleport>
+</template>
+```
+
+## Logical Hierarchy Is Preserved
+
+Teleport changes DOM position, not the Vue component tree. Props, emits, slots, and provide/inject still work:
+
+```vue
+<template>
+  <Teleport to="body">
+    <ChildPanel :message="message" @close="open = false" />
+  </Teleport>
+</template>
+```
+
+## Multiple Teleports to the Same Target
+
+Teleports to the same target append in declaration order:
+
+```vue
+<template>
+  <Teleport to="#notifications">
+    <div>First</div>
+  </Teleport>
+
+  <Teleport to="#notifications">
+    <div>Second</div>
+  </Teleport>
+</template>
+```
+
+Use a shared container to keep stacking predictable, and apply z-index only when you need explicit layering.