@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/skills/fec-vue3-project-standard/references/vue3-composables-routing.md

@@ -0,0 +1,163 @@
+# Vue 3 composables and routing patterns
+
+## Composables specification
+
+### Design principles
+
+- Named with `use` prefix
+- Use objects as return values and clearly mark the type
+- Internal processing loading / error / data tri-state
+-Support parameter responsiveness (accepts `Ref` or getter)
+- Library level composable to clarify whether the parameter supports normal values, `Ref`, `computed` or getter, and parse the latest value inside the side effect
+
+```typescript
+export function useUserList(params: MaybeRef<QueryParams>) {
+  const data = ref<User[]>([]);
+  const loading = ref(false);
+  const error = ref<Error | null>(null);
+
+  async function fetch() {
+    loading.value = true;
+    error.value = null;
+    try {
+      const res = await getUserList(toValue(params));
+      data.value = res.list;
+    } catch (e) {
+      error.value = e as Error;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  watchEffect(() => {
+    fetch();
+  });
+
+  return {
+    data: readonly(data),
+    loading: readonly(loading),
+    error: readonly(error),
+    refetch: fetch,
+  };
+}
+```
+
+### Composable usage principles
+
+- Return a `readonly` reference to prevent accidental modification by outsiders
+- In data request scenarios, libraries such as VueQuery / VueUse are preferred (if the project has been introduced)
+- Clean up timers, event listeners and other side effects in `onUnmounted`
+- Avoid directly manipulating DOM in composable
+- Read-only inputs accept normal values, refs, computed or getters; inputs that require bidirectional writing only accept writable refs or explicit setters.
+- If the parameter itself is a callback, comparator or predicate, do not design it as a getter type input, otherwise the business function may be mistakenly called during parsing.
+
+### Vue Router / Pinia / Test common boundaries
+
+- Changes in routing parameters will not recreate the same routing component; data that relies on `route.params` must watch clear fields and handle cancellation and race conditions.
+- Avoid old-style `next()` multi-branch repeated calls in navigation guards; give priority to returning `false`, redirecting objects or throwing handleable errors.
+- Use `storeToRefs` when destructuring the Pinia store will lose responsiveness; the setup store must return state, getters and actions that need to be tracked externally.
+- UI temporary status, form input, and pop-up window switches do not enter the global store; URL query, server-side cache, and local component status are returned to their respective places first.
+- Vue Test Utils tests prioritize user-visible behavior and do not use snapshots as the only proof; asynchronous updates use `await`, `flushPromises` or the waiting method recommended by the framework.
+- When testing using Pinia, Router, Teleport, Suspense, async setup or `defineAsyncComponent`, explicitly install the plugin in the test fixture, mount the target container and wait for async to stabilize.
+
+## Slots and Provide/Inject
+
+### Slots
+
+- Use `<slot>` to achieve component composition instead of too many props
+- Named slots are used for explicit layout areas
+- Scope slot passes data to parent component for custom rendering
+
+```vue
+<template>
+  <div class="card">
+    <div class="card-header">
+      <slot name="header">{{ title }}</slot>
+    </div>
+    <div class="card-body">
+      <slot :data="processedData" :loading="loading" />
+    </div>
+  </div>
+</template>
+```
+
+### Provide/Inject
+
+- For context sharing across multiple levels (topics, configurations, permissions)
+- Provide InjectionKey to ensure type safety
+- Do not use provide/inject instead of props to pass direct parent-child data
+
+```typescript
+// keys.ts
+export const ThemeKey: InjectionKey<Ref<Theme>> = Symbol("theme");
+
+// Provider.vue
+provide(ThemeKey, theme);
+
+// Consumer.vue
+const theme = inject(ThemeKey);
+```
+
+## Routing specifications
+
+### Routing organization
+
+```typescript
+// app/router.ts
+const routes: RouteRecordRaw[] = [
+  {
+    path: "/",
+    component: MainLayout,
+    children: [
+      {
+        path: "",
+        name: "Dashboard",
+        component: () => import("@/pages/Dashboard/DashboardPage.vue"),
+      },
+      {
+        path: "users",
+        name: "UserList",
+        component: () => import("@/pages/UserList/UserListPage.vue"),
+      },
+      {
+        path: "users/:id",
+        name: "UserDetail",
+        component: () => import("@/pages/UserDetail/UserDetailPage.vue"),
+      },
+      {
+        path: "settings",
+        name: "Settings",
+        component: () => import("@/pages/Settings/SettingsPage.vue"),
+      },
+    ],
+  },
+  {
+    path: "/login",
+    name: "Login",
+    component: () => import("@/pages/Login/LoginPage.vue"),
+  },
+  {
+    path: "/:pathMatch(.*)*",
+    name: "NotFound",
+    component: () => import("@/pages/NotFound.vue"),
+  },
+];
+```
+
+### Routing principles
+
+- Centralized management of routing configuration, each route must have a `name`
+- Page components are loaded on demand using dynamic `import()`
+- Permission control uses route guard (`beforeEach`) instead of judging within each page
+- URL parameters (pagination, filtering, sorting) and routing status are synchronized
+
+```typescript
+// Navigation guard
+router.beforeEach((to) => {
+  const authStore = useAuthStore();
+  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
+    return { name: "Login", query: { redirect: to.fullPath } };
+  }
+});
+```
+

package/skills/fec-vue3-project-standard/references/vue3-performance-patterns.md

@@ -0,0 +1,13 @@
+# Vue 3 performance patterns
+
+This file keeps lightweight Vue project-standard performance guidance. Use the frontend performance workflow when the task needs metrics, traces, profiles, bundle analysis, network evidence, or a formal performance report.
+
+## Performance
+
+- Use `shallowRef` / `shallowReactive` to optimize large objects
+- Use virtual scrolling for large lists
+- Avoid using `v-if` in `v-for` (extract to computed filtering)
+- Use `defineAsyncComponent` to lazily load heavy components
+- `v-for` must have a stable `:key`
+- Routing components are loaded on demand using dynamic `import()`
+

package/skills/fec-vue3-project-standard/references/vue3-project-structure.md

@@ -0,0 +1,177 @@
+# Vue 3 project structure and component standards
+
+## Project structure
+
+The following is the industry's best practice structure for medium and large Vue 3 projects, tailored according to the actual situation of the project:
+
+```
+src/
+├── app/ # Application entry and global configuration
+│ ├── App.vue # Root component
+│ ├── main.ts # Application startup entrance
+│ └── router.ts # Routing instance and configuration
+│
+├── pages/ # Page components (one-to-one correspondence with routing)
+│   ├── Dashboard/
+│   │   ├── DashboardPage.vue
+│ │ ├── components/ # Page private components
+│ │ └── composables/ # Page private composables
+│   ├── UserList/
+│   └── Settings/
+│
+├── layouts/ # Layout component
+│ ├── MainLayout.vue # Main layout (sidebar + top bar + content area)
+│ ├── AuthLayout.vue # Login/registration page layout
+│ └── BlankLayout.vue # Blank layout (error page, etc.)
+│
+├── features/ # Function modules (divided by business areas)
+│   ├── auth/
+│ │ ├── components/ # Module components
+│ │ ├── composables/ # module composables
+│ │ ├── api.ts # Module API call
+│ │ ├── types.ts # Module type definition
+│ │ ├── constants.ts # Module constants
+│ │ └── index.ts # Module publicly exported
+│   └── order/
+│
+├── components/ # Globally shared UI components
+│   ├── AppButton/
+│   │   ├── AppButton.vue
+│   │   └── __tests__/
+│   ├── AppModal/
+│   ├── AppForm/
+│   └── AppErrorBoundary/
+│
+├── composables/ # Global shared composables
+│   ├── useAuth.ts
+│   ├── useDebounce.ts
+│   └── useMediaQuery.ts
+│
+├── services/ # API base layer
+│ ├── request.ts # Axios/fetch instance and interceptor
+│ └── endpoints/ # API endpoint definition (such as split by field)
+│
+├── stores/ # Pinia status management
+│   ├── authStore.ts
+│   └── uiStore.ts
+│
+├── locales/ # International language pack
+│ ├── zh-CN.json # Simplified Chinese
+│ ├── en-US.json # English
+│ └── index.ts # i18n instance initialization (vue-i18n)
+│
+├── assets/ # Static resources
+│ ├── images/ # Pictures (PNG, JPG, WebP)
+│ ├── icons/ # SVG icon
+│ └── fonts/ # Custom fonts
+│
+├── config/ # Application configuration
+│ ├── env.ts # Typed encapsulation of environment variables
+│ └── features.ts # Feature Flags Management
+│
+├── types/ # Global shared types
+│ ├── api.ts # API response/request common type
+│ ├── models.ts #Business entity type
+│ └── global.d.ts # Global type extension (component type, module declaration, etc.)
+│
+├── utils/ # Pure utility function
+│ ├── format.ts # Date, number, currency formatting
+│ ├── validators.ts # Form validation rules
+│ └── storage.ts # LocalStorage / SessionStorage package
+│
+├── directives/ # Custom directives
+│ ├── vPermission.ts # Permission command
+│ └── vClickOutside.ts # Click outside to close
+│
+├── plugins/ # Vue plug-in registration
+│ ├── i18n.ts # vue-i18n plug-in configuration
+│ └── index.ts # Plug-in unified registration entrance
+│
+├── styles/ # Global styles and themes
+│ ├── global.css # Global basic style (reset/normalize)
+│ ├── variables.css # CSS variables (color, spacing, font size)
+│ ├── breakpoints.ts # Responsive breakpoint constants
+│ └── themes/ # theme definition
+│ ├── light.css # Light theme variable
+│ ├── dark.css # Dark theme variable
+│ └── index.ts # theme switching logic
+│
+└── constants/ # Global constants
+    ├── routes.ts #Routing path constants
+    └── config.ts #Business constants (paging size, timeout, etc.)
+```
+
+### Key Principles
+
+- `pages/` does route mapping and layout combination without putting business logic
+- `layouts/` defines the page skeleton (sidebar, top bar, breadcrumbs), referenced by the `component` of the routing configuration
+- `features/` is divided by business areas, self-contained within the module (components + composables + api + types)
+- `components/` only contains common components without business coupling and can be reused across projects
+- `composables/` only places common logic (anti-shake, media query, etc.), and business composables are placed in the corresponding feature
+- `locales/` stores language pack JSON files, use `$t('key')` in the template instead of hard-coded copy
+- `assets/` stores static resources, SVG is preferred for icons, and WebP/AVIF is preferred for images.
+- `config/` encapsulates environment variables and Feature Flags, prohibiting direct reading of `import.meta.env` in components
+- `styles/themes/` implements theme switching through CSS variables. Variables are referenced in components instead of hard-coded colors.
+- Each module controls the public API through `index.ts` to avoid deep path imports
+
+## Component design specifications
+
+- Use `<script setup lang="ts">`
+- Explicitly use `defineProps` / `defineEmits` with accompanying types
+- Reusable logic is first extracted to composables
+- Keep the template readable and avoid too deep nesting of conditions
+- Prefer using computed properties instead of repeatedly maintaining state
+- Avoid building large single components; **single file size** see `templates/shared/rules/fec-vue.md` "**component file size**" (approximately 300 lines or less, more than 500 lines or too complex to separate sub-components and Composables)
+- Prioritize the use of strongly typed props, emits and exposed methods
+- Follow the file and directory naming conventions of the warehouse
+- Prioritize reuse of existing UI components and tokens
+
+### Component layering
+
+```
+Pages → Route mapping, layout combination
+  └── Container components (Containers) → Data acquisition, status orchestration
+       └── Business components (Features) → Domain logic display
+            └── Universal Component (UI) → Pure display, no business coupling
+```
+
+## Comment specifications
+
+- **Prefer using Chinese**: When explaining "why this is done", business constraints, boundary conditions, and non-obvious trade-offs, give priority to writing comments in Chinese to make it easier for the team and business parties to read.
+- **Exception when consistent with the code language**: When connecting third-party protocol field names, HTTP headers, and English terms in specifications, English proper nouns can be retained in the comments, and Chinese and English descriptions can be given when necessary.
+- **Less but more precise**: Can express clear logic through clear naming and types without writing nonsense comments; complex branches, temporary compatibility, and performance trade-offs must be clearly stated.
+- **Public API**: Composable or module external contracts can use JSDoc (`@param` / `@returns` / `@example`). The instructions can be in Chinese, unless the warehouse requires English.
+
+## TypeScript Specification
+
+Common TypeScript project rules are taken care of by `fec-typescript-project-standard`, including `tsconfig`, strictness, DTO / view model boundaries, `unknown` narrowing, public API types, declared artifacts, and type tests.
+
+The Vue specification only supplements SFC, Props / Emits, exposed methods, Provide / Inject and composable reactive types; complex type modeling or cross-framework type contracts are first offloaded to `fec-typescript-project-standard`.
+
+### Vue 3 project supplementary conventions
+
+```vue
+<script setup lang="ts">
+interface Props {
+  title: string;
+  items: Item[];
+  loading?: boolean;
+}
+
+interface Emits {
+  (e: "select", item: Item): void;
+  (e: "delete", id: string): void;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  loading: false,
+});
+
+const emit = defineEmits<Emits>();
+</script>
+```
+
+- Props and Emits are defined using the TypeScript interface
+- Use `withDefaults` to set default values
+- `defineExpose` exposed methods must have type constraints
+

package/skills/fec-vue3-project-standard/references/vue3-state-api-quality.md

@@ -0,0 +1,216 @@
+# Vue 3 state, API, and quality patterns
+
+## Status Management (Pinia)
+
+| Status type | Recommended solution |
+| ------------------ | ----------------------------- |
+| Temporary UI state within the component | `ref` / `reactive` |
+| Sharing business status across components | Pinia store |
+| Server-side data cache | VueQuery / Custom composable |
+| URL driver status | Route parameters / `useRoute().query` |
+| Form Status | VeeValidate / FormKit |
+
+### Pinia Store Specifications
+
+Using Composition API style (`setup store`):
+
+```typescript
+// stores/authStore.ts
+export const useAuthStore = defineStore("auth", () => {
+  const user = ref<User | null>(null);
+  const token = ref<string | null>(localStorage.getItem("token"));
+
+  const isLoggedIn = computed(() => !!token.value);
+
+  async function login(credentials: LoginParams) {
+    const res = await authApi.login(credentials);
+    user.value = res.user;
+    token.value = res.token;
+    localStorage.setItem("token", res.token);
+  }
+
+  function logout() {
+    user.value = null;
+    token.value = null;
+    localStorage.removeItem("token");
+  }
+
+  return { user: readonly(user), isLoggedIn, login, logout };
+});
+```
+
+### Store Principles
+
+- Each store has a single responsibility and is split by area.
+- Expose the status of `readonly` to the outside world and modify it through action
+- Do not store UI temporary states (modal switches, form inputs, etc.) in the store
+- Server-side data is first managed by the request library rather than manually stored in the store
+
+## API layer specification
+
+### Request instance
+
+```typescript
+// services/request.ts
+const request = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  timeout: 10000,
+});
+
+request.interceptors.request.use((config) => {
+  const authStore = useAuthStore();
+  if (authStore.token) {
+    config.headers.Authorization = `Bearer ${authStore.token}`;
+  }
+  return config;
+});
+
+request.interceptors.response.use(
+  (res) => res.data,
+  (error) => {
+    if (error.response?.status === 401) {
+      const authStore = useAuthStore();
+      authStore.logout();
+      router.push({ name: "Login" });
+    }
+    return Promise.reject(normalizeError(error));
+  },
+);
+```
+
+### API functions
+
+```typescript
+// features/user/api.ts
+export function getUserList(
+  params: UserQueryParams,
+): Promise<PageResult<User>> {
+  return request.get("/users", { params });
+}
+
+export function updateUser(id: string, data: UpdateUserDTO): Promise<User> {
+  return request.put(`/users/${id}`, data);
+}
+```
+
+- API functions are organized by feature instead of all being piled in one file
+- Request parameters and responses have type constraints
+- The interceptor handles authentication and error formatting uniformly
+
+## Error handling
+
+### Global error capture
+
+```typescript
+// main.ts
+app.config.errorHandler = (err, instance, info) => {
+  reportError(err, { component: instance?.$options.name, info });
+};
+```
+
+### Component level errors
+
+- Use `onErrorCaptured` to capture child component errors in the parent component
+- Failed data requests must have user-visible prompts and retry mechanisms
+- Don't swallow errors (empty catch block)
+
+## Custom directive
+
+```typescript
+// directives/vPermission.ts
+export const vPermission: Directive<HTMLElement, string> = {
+  mounted(el, binding) {
+    const authStore = useAuthStore();
+    if (!authStore.hasPermission(binding.value)) {
+      el.parentNode?.removeChild(el);
+    }
+  },
+};
+```
+
+- The directive only handles operations at the DOM level
+- Do not put business logic in instructions
+- Implement the `updated` hook when responsive updates are required
+
+## Style specification
+
+- Use `<style scoped>` to isolate styles
+- Depth selector uses `:deep()` instead of the deprecated `::v-deep`
+- Be consistent with the existing style system of the project
+- Dynamic styles preferentially use `:class` / `:style` binding
+- Complex theme switching using CSS variables
+- Theme/global variables are managed through CSS variables or Token
+
+## Test specifications
+
+### Must be tested
+
+- Core interaction behaviors (click, input, submit)
+- Conditional rendering (loading/error/empty/data)
+- Emits trigger and payload
+- Return value of key composables
+- Pinia store actions and getters
+
+### Test style
+
+```typescript
+describe("UserForm", () => {
+  it("should emit submit with valid data", async () => {
+    const wrapper = mount(UserForm);
+
+    await wrapper.find('[data-testid="username"]').setValue("test");
+    await wrapper.find("form").trigger("submit");
+
+    expect(wrapper.emitted("submit")?.[0]).toEqual([{ username: "test" }]);
+  });
+
+  it("should show validation error on empty submit", async () => {
+    const wrapper = mount(UserForm);
+    await wrapper.find("form").trigger("submit");
+    expect(wrapper.text()).toContain("Username cannot be empty");
+  });
+});
+```
+
+### Store Test
+
+```typescript
+describe("authStore", () => {
+  beforeEach(() => setActivePinia(createPinia()));
+
+  it("should login and set user", async () => {
+    const store = useAuthStore();
+    await store.login({ username: "admin", password: "pass" });
+    expect(store.isLoggedIn).toBe(true);
+  });
+});
+```
+
+
+## Anti-pattern
+
+- Inline large sections of business logic in template-driven components
+- Used wide range watcher instead of computed
+- The event payload is unclear
+- Mix raw API calls directly into pure presentation components
+- ref and props have no type constraints
+- Use `watch` + manual assignment to simulate computed
+- Mixing unrelated responsibilities into a component
+- Use large-scale global style coverage to solve local UI problems
+- Push all status to Pinia store instead of managing it nearby
+- Put business coupling components in `components/`
+- Import directly from the deep path inside the feature, bypassing `index.ts`
+
+## Output checklist
+
+- [ ] The file structure is consistent with the project convention (pages/features/components are separated)
+- [ ] Use `<script setup lang="ts">`
+- [ ] Props / Emits type complete
+- [ ] Whether explanatory comments should be given priority in Chinese and to the point
+- [ ] Reusable logic has been extracted to composable
+- [ ] Loading / Error / Empty status have been processed
+- [ ] Routing components are loaded using dynamic import
+- [ ] Reasonable status management plan (proximity principle)
+- [ ] API calls have type constraints and unified error handling
+- [ ] styles use scoped isolation
+- [ ] Key behaviors are covered by tests

package/skills/fec-web-video-presentation/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: fec-web-video-presentation
+description: Use when turning an article, talk script, lesson, product demo, or narrated explanation into a recordable 16:9 web presentation with step-driven scenes, optional narration alignment, theme tokens, and screen-recording guidance; Chinese triggers include web video, dynamic demonstration, spoken script to video, screen-recordable demonstration, 16:9 demonstration.
+---
+
+# Web video demonstration
+
+## Purpose
+
+Convert articles, oral presentations, courses, product explanations or technology sharing into screen-recordable 16:9 web presentations. The product should be like a clickable video stage: each step carries a spoken rhythm, the visual design serves the content rhythm, and can be stably recorded using the browser.
+
+## Procedure
+
+1. Determine the input form
+   - When the user submits an article or long text, it is first split into a spoken draft and an outline.
+   - When the user broadcasts the manuscript to the ready-made script, the original order is retained and only the outline, chapters and steps are added.
+   - When the user only provides a topic but no content, first ask for materials, outlines or key points; do not make up the entire content for the user.
+
+2. Generate a content plan
+   - Press [content-plan.md](references/content-plan.md) to output script and outline.
+   - The script determines the order of telling and each beat; the outline determines the chapters, steps, time estimates, screen information and material list.
+   - The outline only describes the content density and screen tasks, and does not write down the specific animation implementation in advance.
+
+3. Align the demo system
+   - Choose a starter theme from [theme-system.md](references/theme-system.md) or [starter-themes.json](data/starter-themes.json), or redefine the token by project brand.
+   - Create a minimal Vite + React + TypeScript presentation skeleton using [create-video-presentation.mjs](scripts/create-video-presentation.mjs):
+     ```bash
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs ./presentation --theme editorial-slate
+     ```
+   - If you just want to preview optional themes or plan to write content:
+     ```bash
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs --list-themes
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs --dry-run ./presentation --theme editorial-slate
+     ```
+
+4. Implementation Chapter
+   - Each chapter is implemented as [chapter-craft.md](references/chapter-craft.md).
+   - Each step occupies the stage exclusively, and the screen only carries the core content that the user needs to understand for the current spoken beat.
+   - Chapters must have visible visual presentation, graphics, layout changes, status progression, or data/media presentation; do not deliver text-only slides.
+   - The first chapter should be completed and accepted first as the style anchor before continuing with other chapters.
+
+5. Screen recording and audio
+   - Use [recording-and-audio.md](references/recording-and-audio.md) to check stage scale, navigation, recording mode and optional audio synchronization.
+   - Audio can come from the user's existing files, host tools, or the project's own TTS process; this skill is not bound to a specific TTS provider.
+
+6. Pre-delivery verification
+   - Open the demo in a browser to check 16:9 zoom, keyboard/click advancement, step count, text overflow, hidden controls, console errors, and screen recording path.
+   - If the number, order or step number of chapters changes, reset the local persistence key or clear the old progress to avoid reverting to a non-existent step.
+
+## Constraints
+
+- Do not turn web videos into ordinary marketing landing pages, static PPT or long scrolling articles.
+- Do not copy the reference project's themes, template chapters, long prompts, or scaffolding implementations; generate an original skeleton based on the current project.
+- Do not lock each animation name in the outline stage; animations should be driven by chapter content relationships.
+- Do not use fake data, fake quotes, fake product screenshots or uncheckable media to fill the screen.
+- Do not let controls, page numbers, explanatory text or debugging panels pollute the screen recording; necessary controls are hidden or weakened by default.
+- No outside-project vendor conventions are introduced for audio synthesis; TTS is an optional adaptation layer.
+
+## Expected Output
+
+Output script, outline, runnable 16:9 web page demonstration skeleton or chapter implementation, and describe the theme, number of chapters/steps, screen recording method, optional audio path and verification results. The final presentation should be able to be progressed steadily through clicks or keyboards, the visual rhythm should fit the spoken content, and it should be suitable for browser screen recording.