@bovinphang/frontend-craft 2.6.0 → 2.8.0

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

@@ -0,0 +1,197 @@
+# React project structure and component boundaries
+
+## Project structure (recommended reference)
+
+The following is the industry's best practice structure for medium and large React projects, tailored according to the actual situation of the project:
+
+```text
+src/
+├── app/ # Application entry and global configuration
+│ ├── App.tsx # Root component (Provider combination)
+│ ├── routes.tsx # Routing configuration
+│ └── providers.tsx # Global Provider assembly
+│
+├── pages/ # Page components (one-to-one correspondence with routing)
+│   ├── Dashboard/
+│   │   ├── DashboardPage.tsx
+│ │ ├── components/ # Page private components
+│ │ └── hooks/ # Page private hooks
+│   ├── UserList/
+│   └── Settings/
+│
+├── layouts/ # Layout component
+│ ├── MainLayout.tsx # Main layout (sidebar + top bar + content area)
+│ ├── AuthLayout.tsx # Login/registration page layout
+│ └── BlankLayout.tsx # Blank layout (error page, etc.)
+│
+├── features/ # Function modules (divided by business areas)
+│   ├── auth/
+│ │ ├── components/ # Module components
+│ │ ├── hooks/ # module hooks
+│ │ ├── 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
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.styles.css
+│   │   └── __tests__/
+│   ├── Modal/
+│   ├── Form/
+│ └── ErrorBoundary/ # Thin wrapper (function component) for react-error-boundary etc.
+│
+├── hooks/ # Global shared hooks
+│   ├── 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/ # Global status management
+│   ├── authStore.ts
+│   └── uiStore.ts
+│
+├── locales/ # International language pack
+│ ├── zh-CN.json # Simplified Chinese
+│ ├── en-US.json # English
+│ └── index.ts # i18n instance initialization (i18next / react-intl)
+│
+├── 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 (picture module declaration, etc.)
+│
+├── utils/ # Pure utility function
+│ ├── format.ts # Date, number, currency formatting
+│ ├── validators.ts # Form validation rules
+│ └── storage.ts # LocalStorage / SessionStorage package
+│
+├── 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 page arrangement, and does not carry large pieces of reusable business logic.
+- `layouts/` is responsible for the page skeleton and layout container, referenced by the routing configuration
+- `features/` is divided according to business areas, and the module should be as self-contained as possible
+- `components/` only contains common components that are reused across pages and modules
+- `hooks/` only puts global general hooks; business hooks are put back to the corresponding feature or page first
+- `locales/` stores language pack JSON files, use `t('key')` in the component instead of hard-coded copy
+- `assets/` stores static resources, SVG is preferred for icons, and WebP/AVIF is preferred for images.
+- `services/` is responsible for requesting infrastructure and does not stack business details
+- `config/` uniformly encapsulates environment variables and feature switches, prohibiting direct reading of `import.meta.env` in components
+- `styles/` and theme variables are managed uniformly to avoid colors and sizes being scattered in business code
+- Each module controls the public API through `index.ts` to avoid deep path imports
+
+---
+
+## Component and module layering
+
+Recommended layering:
+
+```text
+Page components (Pages) → route mapping, layout combination, page arrangement
+  └── Container/orchestration layer → data acquisition, status organization, event orchestration
+       └── Business components → Domain logic display
+            └── Common components → No business coupling, reusable across modules
+```
+
+### When to put it in `pages/`
+
+Suitable for:
+
+- Routing entry component
+- Page level layout combination
+- Page private lightweight orchestration logic
+
+Not suitable for:
+
+- A lot of domain logic
+- Complex business blocks that can be reused on multiple pages
+- API/hooks/types that are strongly bound to a certain business domain
+
+### When to put it in `features/`
+
+Suitable for:
+
+- Components, hooks, apis, and types of a certain business domain
+- Logic that can be shared by multiple pages but has business semantics
+- Self-contained implementation of a complete business unit
+
+### When to put it in `components/`
+
+Suitable for:
+
+- Common UI such as buttons, pop-up windows, form items, table shells, empty states, error states, etc.
+- Components that have nothing to do with specific business and can be reused across modules
+
+---
+
+## Component design specifications
+
+- Use **Functional Components**, Hooks and TypeScript; **Do not** add new class components (Error Boundary uses libraries such as `react-error-boundary`, see below)
+- **Single file size** and splitting principles can be found in `templates/shared/rules/fec-react.md` "**Component file size**" (approximately 300 lines is preferred, if it exceeds 500 lines or is too complex, sub-components, Hooks, utils, and types will be split)
+- Keep components with single responsibilities and composable
+- Extract reusable logic into hooks
+- Prioritize the use of controlled component APIs in appropriate scenarios
+- props are clearly defined and typed
+- Prioritize reuse of existing design system components
+- Maintain accessibility with keyboard interaction
+- Avoid deep JSX nesting and duplicate branches
+- Do not store additional state for deducible values
+
+---
+
+
+## Component directory suggestions
+
+When the component complexity is low, only one file can be kept.  
+When a component contains styles, subcomponents, hooks, and tests, it is recommended to use the following structure:
+
+```text
+ComponentName/
+├── ComponentName.tsx
+├── ComponentName.types.ts
+├── ComponentName.styles.css
+├── hooks/
+│   └── useComponentLogic.ts
+├── components/
+│   └── SubComponent.tsx
+└── __tests__/
+    └── ComponentName.spec.tsx
+```
+
+Description:
+
+- Split `ComponentName.types.ts` when the type is complex
+- Split `hooks/` when there is local logic reuse
+- When the subcomponent is only used inside the current component, it is placed in the current directory `components/`
+- Whether the test should be placed nearby should follow the existing protocols of the warehouse
+
+---
+

package/skills/fec-react-project-standard/references/react-quality-patterns.md

@@ -0,0 +1,131 @@
+# React quality patterns
+
+## Style access
+
+This skill does not enforce a specific style scheme and follows the current status of the warehouse by default.
+
+Please note when adapting:
+
+- Tailwind project continues to use Tailwind
+- CSS Modules projects keep naming consistent with file organization
+- The styled-components project continues to follow its pattern
+- Theme, color, font size, spacing, etc. give priority to reusing warehouse token / CSS variables
+- Avoid hardcoding a large number of visual constants within the component
+- Disable inline styles (except dynamic values)
+- Responsive processing must be consistent with the project breakpoint agreement
+
+---
+
+## 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**: The external contract of modules or hooks 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 React specification only supplements components, Props, events and TSX generic writing; complex type modeling or cross-framework type contracts are first offloaded to `fec-typescript-project-standard`.
+
+### React project supplementary conventions
+
+- Props interface naming: `ComponentNameProps`
+- Event handling function: `handle` prefix (such as `handleClick`)
+- Callback Props: `on` prefix (such as `onChange`, `onSubmit`)
+- Components give priority to writing explicit props and return value types (`JSX.Element` / `React.ReactElement`) to avoid behavioral differences such as relying on the implicit `children` of `React.FC`
+- Generic components use `<T>` constraints to maintain call-site type derivation; callback and event types preferentially use DOM/React’s own types (such as `React.ChangeEvent<HTMLInputElement>`)
+
+```tsx
+interface TableProps<T extends Record<string, unknown>> {
+  data: T[];
+  columns: ColumnDef<T>[];
+  onRowClick?: (row: T) => void;
+}
+```
+
+---
+
+## Test specifications
+
+### Content that should be covered first
+
+- Core interaction behaviors (click, input, submit)
+- Conditional rendering (loading/error/empty/data)
+- Return values and side effects of key hooks
+- API call mock and module-level integration testing
+
+### Recommended style
+
+- Test user behavior, not implementation details
+- Prioritize using `screen.getByRole`, `getByLabelText`
+- Avoid writing brittle tests around internal state
+- Only measure key behaviors and do not mechanically pursue coverage figures
+
+### Example
+
+```tsx
+describe("UserForm", () => {
+  it("should submit with valid data", async () => {
+    const onSubmit = vi.fn();
+    render(<UserForm onSubmit={onSubmit} />);
+
+    await userEvent.type(screen.getByLabelText("username"), "test");
+    await userEvent.click(screen.getByRole("button", { name: "Submit" }));
+
+    expect(onSubmit).toHaveBeenCalledWith({ username: "test" });
+  });
+
+  it("should show error on invalid input", async () => {
+    render(<UserForm onSubmit={vi.fn()} />);
+    await userEvent.click(screen.getByRole("button", { name: "Submit" }));
+    expect(screen.getByText("Username cannot be empty")).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+
+## Common anti-patterns
+
+Avoid:
+
+- prop drilling is too deep without considering combination or partial encapsulation
+- Excessive use of context for local issues
+- Stuff data requests, view rendering, and imperative DOM operations into one file
+- Do things in useEffect that can be done in event handlers
+- Use `useEffect + setState` to simulate derived values that could be calculated directly
+- Push all states to the global store
+- Put business coupling components in `components/`
+- Directly bypass the module export and import from the feature deep path
+- There is no obvious benefit but complex optimization is done in advance
+- **New class component** or handwritten class Error Boundary (should function component + `react-error-boundary`, etc.)
+
+---
+
+## Output checklist
+
+When outputting React code or solutions, at least check:
+
+- [ ] Whether to align the existing contracts of the warehouse first
+- [ ] Page / feature / Is the boundary of common components clear?
+- [ ] Whether the directory structure matches the module complexity
+- [ ] Props type is complete and clear
+- [ ] Whether explanatory comments should be given priority in Chinese and to the point
+- [ ] Whether reusable logic has been extracted into hooks
+- [ ] loading / error / empty / data status is complete
+- [ ] Whether the API layer has type constraints and unified error handling
+- [ ] Whether complex DTO, external data narrowing, public types or `tsconfig` issues have been offloaded to `fec-typescript-project-standard`
+- [ ] Whether status management complies with the proximity principle
+- [ ] Whether lazy loading is considered for routing-level or heavy-duty modules
+- [ ] Whether the style scheme is consistent with the warehouse
+- [ ] Whether key behaviors are covered by tests
+- [ ] Key modules have been wrapped with **`react-error-boundary`** (etc.), and no hand-written class component Boundary
+- [ ] Whether the long list evaluates virtualization; whether the pop-up window/composite component has keyboard and focus conventions
+- [ ] Whether unnecessary new dependencies or new paradigms are introduced
+
+---

package/skills/fec-react-project-standard/references/react-runtime-patterns.md

@@ -0,0 +1,293 @@
+# React runtime patterns
+
+## Common UI and status mode
+
+The following patterns can be used in comparison with other chapters of this skill (Hooks, state management, performance optimization, error handling); **Select based on business complexity and team familiarity** to avoid patterns for pattern's sake. The ideas refer to common React front-end pattern practices in the industry (such as component combination, composite components, performance and accessibility, etc.).
+
+### Composition is better than inheritance
+
+- Use **small subcomponents** + `children` / explicit props to assemble the interface instead of building a class inheritance hierarchy in React.
+- Example: `Card` + `CardHeader` + `CardBody`, composed by the consumer, rather than one giant `Card` branched with a lot of boolean props.
+
+### Compound Components
+
+- The root component provides internal state (such as current Tab, open/closed) to child components through **Context**.
+- The subcomponent **throws an error or asserts** when `useContext` is empty, making it clear that it "must be used within the Provider tree".
+- API surfaces remain readable: `<Tabs><TabList><Tab /></TabList></Tabs>`.
+
+### Render Props/Functionator
+
+- Applicable: Encapsulate **data acquisition and three-state** (loading / error / data), and hand over **rendering decision** to the parent.
+- Choose one of the two with **Custom Hook**: `useXxx()` + ordinary components are more intuitive in most scenarios; only keep Render Props when strong constraints on "same-layer rendering logic" are required.
+
+### Context + useReducer
+
+- Suitable for **moderate complexity, multi-subtree sharing** client state, and updates can be reduced to explicit `action`.
+- Avoid stuffing large objects that change frequently into the top-level Context; server-side data still takes priority **React Query / SWR**.
+- Large global business status continues to use the **Zusand / Redux Toolkit / Jotai** selected by the warehouse.
+
+### Form
+
+- Controlled fields + validation error objects are a feasible implementation; medium and large forms are given priority **React Hook Form** (or Formik) + **Zod**, and complex form values, DTO and validation type contracts are offloaded to `fec-typescript-project-standard`.
+- Avoid huge `useState` form objects and repeated validation logic in a single component, detachable field subcomponents or extract `useFormSchema`.
+
+### Error Boundary
+
+- **Don't** handwrite Error Boundary in the form of React **class component** in business code; uniformly use **`react-error-boundary`** (or a similar library recognized by the team) to render failure at the **module boundary** (consistent with "Error Handling" and `error-handling.md` in this chapter).
+- Use `FallbackComponent` and `resetErrorBoundary` to provide "retry"; **log reporting** is placed in the library's **`onError`** (waiting for callbacks), and production code avoids long-term dependence on `console.log` (see TypeScript rules).
+
+
+### Animation and Transition
+
+- List entry and exit can be done using **Framer Motion**'s `AnimatePresence` + `key`, or CSS `transition`; note that reduced layout jitter and `prefers-reduced-motion` (when consistent with accessibility policies).
+
+### Accessibility and Focus
+
+- Customized drop-downs, tabs, etc.: **`role` / `aria-*`**, **Direction keys / Enter / Escape** Behavior and focus rings are visible.
+- Pop-up window: Move the focus into the dialog box when it is opened, and **restore** when it is closed to trigger the element focus; **`focus-trap-react`** or similar solutions can be used to complement the `fec-accessibility-check` skill.
+
+### Next.js and server-side components
+
+- **App Router, Server Components, server-side data acquisition and caching** see **`fec-nextjs-project-standard`**; the client interaction mode is still subject to this chapter and the Hooks specification.
+
+---
+
+
+## Hooks design pattern
+
+### Suitable for scenarios where custom Hooks are drawn
+
+- Data acquisition and three-state management
+- Form status logic
+- Paging, filtering, sorting and arrangement
+- Event monitoring and side effect cleanup
+- Interaction logic that can be reused in multiple components
+
+### Recommended principles
+
+- Uniformly use `use` prefix naming
+- Return objects instead of arrays to facilitate on-demand destructuring and enhance readability and scalability
+- State and behavior are encapsulated together
+- Hook internal processing `loading/error/data`
+- Expose a clear minimal interface to the outside world without leaking irrelevant internal details
+
+### Example
+
+```tsx
+function useUserList(params: QueryParams) {
+  const [data, setData] = useState<User[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetch = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await getUserList(params);
+      setData(res.list);
+    } catch (e) {
+      setError(e as Error);
+    } finally {
+      setLoading(false);
+    }
+  }, [params]);
+
+  useEffect(() => {
+    fetch();
+  }, [fetch]);
+
+  return { data, loading, error, refetch: fetch };
+}
+```
+
+### Hook usage principles
+
+- `useEffect` must have correct dependencies and cleanup logic
+- `useMemo` / `useCallback` Don’t overuse it, add it only when stable references are really important
+- Don't call hooks in conditional branches or loops
+- When React Query / SWR has been introduced, data requests go through these libraries first instead of recreating a cache layer yourself.
+
+---
+
+## Routing organization
+
+### Recommended method
+
+- Centralized management of routing configuration
+- Path constantization
+- Lazy loading of page components on demand
+- Permission control is placed in the guard layer instead of scattered within the page components
+- Paging, filtering, sorting, etc. URL driver status is synchronized with the address bar first
+
+### Example
+
+```tsx
+const routes: RouteObject[] = [
+  {
+    path: "/",
+    element: <MainLayout />,
+    children: [
+      { index: true, element: <DashboardPage /> },
+      { path: "users", element: <UserListPage /> },
+      { path: "users/:id", element: <UserDetailPage /> },
+      { path: "settings", element: <SettingsPage /> },
+    ],
+  },
+  { path: "/login", element: <LoginPage /> },
+  { path: "*", element: <NotFoundPage /> },
+];
+```
+
+```tsx
+const UserListPage = lazy(() => import("@/pages/UserList/UserListPage"));
+
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated } = useAuth();
+  if (!isAuthenticated) return <Navigate to="/login" replace />;
+  return <>{children}</>;
+}
+```
+
+---
+
+## Status management selection
+
+| Status type | Recommended solution |
+| ------------------ | ------------------------------------------------- |
+| Temporary UI state within the component | `useState` / `useReducer` |
+| Sharing business status across components | Zustand / Redux Toolkit / Jotai (actual selection by warehouse) |
+| Server-side data caching | React Query / SWR |
+| URL driver status | Route parameters / `useSearchParams` |
+| Form State | React Hook Form / Formik |
+
+### Core Principles
+
+- Proximity management: try to place the state on the nearest common ancestor
+-Single data source: Do not maintain multiple copies of the same data
+- Derived over synchronized: computable values are calculated first at render time
+- The server-side data is given priority to the request library management and is not manually inserted into the global store.
+- Don’t upgrade local state to global state in advance just because it “may be used in the future”
+
+---
+
+## API layer specification
+
+### Design principles
+
+- Request infrastructure is centralized in `services/`
+-Business APIs are split by feature instead of stacking them all in one file
+- Both request parameters and response results should have clear types
+- Authentication, error formatting, and universal interception are handled uniformly at the request layer
+- Do not directly scatter splicing request details on pages and components
+
+### Example
+
+```ts
+// services/request.ts
+const request = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  timeout: 10000,
+});
+
+request.interceptors.response.use(
+  (res) => res.data,
+  (error) => {
+    if (error.response?.status === 401) {
+      redirectToLogin();
+    }
+    return Promise.reject(normalizeError(error));
+  },
+);
+```
+
+```ts
+// 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);
+}
+```
+
+---
+
+## Error handling
+
+### Status that must be overridden
+
+- Loading
+- Error
+- Empty
+- Data
+
+### Recommended practices
+
+- Use Error Boundary to wrap key functional modules to avoid local exceptions causing a full-page white screen
+- Visible feedback must be given to the user when an asynchronous request fails
+- Provide retry capability for important operations
+- Don’t catch mistakes, don’t write empty `catch`
+
+### Example (`react-error-boundary`, functional Fallback)
+
+```tsx
+import { ErrorBoundary } from "react-error-boundary";
+
+function ModuleErrorFallback({
+  resetErrorBoundary,
+}: {
+  resetErrorBoundary: () => void;
+}) {
+  return (
+    <div>
+      Module loading failed
+      <button type="button" onClick={resetErrorBoundary}>
+        Try again
+      </button>
+    </div>
+  );
+}
+
+export function UserDashboardSection() {
+  return (
+    <ErrorBoundary FallbackComponent={ModuleErrorFallback}>
+      <UserDashboard />
+    </ErrorBoundary>
+  );
+}
+```
+
+---
+
+## Suspense and lazy loading
+
+Applicable scenarios:
+
+- Routing level page
+- Large components such as charts, rich text editors, maps, heavy tables, etc.
+- Modules with higher initialization costs
+
+Example:
+
+```tsx
+const HeavyChart = lazy(() => import("./components/HeavyChart"));
+
+function Dashboard() {
+  return (
+    <Suspense fallback={<ChartSkeleton />}>
+      <HeavyChart data={chartData} />
+    </Suspense>
+  );
+}
+```
+
+Suggestions:
+
+- Route level priority `lazy + Suspense`
+- `fallback` gives priority to using Skeleton or a placeholder state closer to the content instead of a pure spinner
+
+---
+