desktop-team-doc 0.1.0

package/content/docs/instructions/coding-conventions/frontend.md

@@ -0,0 +1,612 @@
+# Frontend Coding Standards
+
+*Last Updated: 2025-10-16*
+
+This document outlines the frontend coding standards for the Desktop Team across all React/TypeScript projects.
+
+## Formatting
+
+* All frontend code formatting MUST adhere to the Prettier configuration located in `.prettierrc`.
+* ESLint rules in `.eslintrc.json` must be followed for code quality.
+* Ensure any generated or modified code passes both Prettier and ESLint checks.
+
+### Key Formatting Rules (from `.prettierrc`)
+
+* **Indentation**: 2 spaces (not tabs)
+* **Line Length**: Maximum 120 characters
+* **Semicolons**: Always use semicolons
+* **Quotes**: Single quotes for strings
+* **Trailing Commas**: As per Prettier defaults
+* **No trailing whitespace**
+* **No indentation on empty lines**
+
+**Note**: Run `npm run eslint` before committing to ensure code quality.
+
+## Technology Stack
+
+### Core Technologies
+
+* **React 18.2+**: Component-based UI library
+* **TypeScript 5.0+**: Typed JavaScript for better code quality
+* **Vite 4.4+**: Build tool and dev server
+* **Vitest**: Testing framework
+
+### State Management
+
+* **Redux Toolkit (@reduxjs/toolkit)**: Primary global state management (preferred)
+* **React Hooks**: Local component state
+* **Zustand**: 僅既有功能保留，新 state 請使用 Redux 或 Local State。
+
+### Styling
+
+* **TailwindCSS 3.3+**: Utility-first CSS framework
+* **Note**: 專案因效能考量已不再使用 styled-components 與 @emotion，新樣式請以 TailwindCSS 為主。
+* **tailwind-merge**: For merging Tailwind classes
+* **clsx**: For conditional class names
+
+### UI Libraries
+
+* **@positivegrid/pg-react-ui-library**: Internal component library
+* **React Router DOM 5.x**: Client-side routing
+* **React Beautiful DnD**: Drag and drop functionality
+* **Framer Motion (motion)**: Animation library
+
+## Naming Conventions
+
+### Files and Directories
+
+* **Components**: `PascalCase.tsx` for React components (e.g., `AppButton.tsx`, `EditableText.tsx`)
+* **Hooks**: `camelCase.ts` starting with "use" (e.g., `useInputStatus.ts`, `useGearMenuStore.ts`)
+* **Utilities**: `camelCase.ts` for utility files (e.g., `constants.ts`, `utils.ts`)
+* **Stores**: `camelCase.ts` with "Store" suffix (e.g., `guitarMatchStore.ts`, `pedalGridStore.ts`)
+* **Types/Interfaces**: `types.ts` or `interfaces.ts`
+* **Command Files**: `camelCase.ts` with "Cmd" suffix (e.g., `initMainViewCmd.ts`)
+
+### TypeScript/JavaScript
+
+* **Variables**: `camelCase` (e.g., `userName`, `isLoading`)
+* **Functions**: `camelCase` (e.g., `handleClick`, `fetchData`)
+* **React Components**: `PascalCase` (e.g., `AppButton`, `EditableText`)
+* **Interfaces/Types**: `PascalCase` with descriptive names (e.g., `AppButtonProps`, `EditableTextHandle`)
+* **Type Aliases**: `PascalCase` starting with `T` prefix (e.g., `TKnobProps`)
+* **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_BUFFER_SIZE`, `DEFAULT_FRAMES`)
+  * Exception: Configuration objects use `camelCase` (e.g., `kDaysInAWeek` when porting from C++)
+* **Enums**: `PascalCase` for enum name, `camelCase` for values
+* **Props Types**: Component name + `Props` suffix (e.g., `AppButtonProps`)
+* **Handler Types**: Component name + `Handle` suffix for refs (e.g., `EditableTextHandle`)
+
+### CSS Classes (TailwindCSS)
+
+* **Custom Components**: Use descriptive class names with prefixes
+  * `.x-` prefix for design system components (e.g., `.x-btn`, `.x-red-dot`)
+  * `.pg-` prefix for Positive Grid specific utilities (e.g., `.pg-scroll-bar`)
+* **Typography Classes**: Semantic naming (e.g., `.heading-14`, `.body-16`, `.x-heading-4`)
+
+## Code Style Conventions
+
+### Braces (Always Use)
+
+**Always use braces** for functions and control statements (if/else) for better readability, formatting, and flexibility when making changes.
+
+**Bad**:
+
+```typescript
+const openLoginWindow = (): StoreThunkAction<unknown> => (dispatch) => {
+  dispatch(openLoginModal());
+};
+
+if (isOpen) closeModal();
+else if (isSaveDialogShowed) setIsSaveDialogShowed(false);
+```
+
+**Good**:
+
+```typescript
+const openLoginWindow = (): StoreThunkAction<unknown> => {
+  return (dispatch) => {
+    dispatch(openLoginModal());
+  };
+};
+
+if (isOpen) {
+  closeModal();
+} else if (isSaveDialogShowed) {
+  setIsSaveDialogShowed(false);
+}
+```
+
+**Exception**: Early returns or guards can be written on one line when used for quick preprocessing:
+
+```typescript
+if (!inputData) return;
+processData1(inputData.data1);
+processData2(inputData.data2);
+```
+
+This single-line format emphasizes the guard nature of the check.
+
+### API Client Standards
+
+* **Use Axios**: Standardize on `axios` for all API calls
+* **Exception**: `XMLHttpRequest` is used for native command communication - do not modify this pattern without team discussion
+* Gradually migrate legacy API call patterns to axios
+
+**Example**:
+
+```typescript
+import axios from 'axios';
+
+const fetchUserData = async (userId: string) => {
+  try {
+    const response = await axios.get(`/api/users/${userId}`);
+    return response.data;
+  } catch (error) {
+    console.error('Failed to fetch user data:', error);
+    throw error;
+  }
+};
+```
+
+## TypeScript Standards
+
+### Type Safety
+
+* **Strict Mode**: Enable `noImplicitAny: true`
+* **Avoid `any`**: Use specific types or `unknown` when type is truly unknown
+* **Type Imports**: Use `type` keyword for type-only imports
+  ```typescript
+  import type { MousePos } from '@/src/utils/mouseRx/types';
+  ```
+
+### Interface vs Type
+
+* **Interfaces**: For object shapes, especially props and public APIs
+  ```typescript
+  export interface AppButtonProps {
+    disable?: boolean;
+    selected?: boolean;
+    className?: string;
+  }
+  ```
+* **Type Aliases**: For unions, intersections, and complex types
+  ```typescript
+  export type TKnobProps = {
+    config: KnobConfig;
+  };
+  ```
+
+### Type Annotations
+
+* **Function Return Types**: Explicitly define return types for functions
+  ```typescript
+  const processData = (): string => {
+    return 'result';
+  };
+  ```
+* **Props Destructuring**: Type props inline or via interface
+  ```typescript
+  const Component = ({ value, onChange }: EditableTextProps) => {
+    // Component logic
+  };
+  ```
+
+### Generics
+
+* Use descriptive generic names: `<T>`, `<TItem>`, `<TData>`
+* Constrain generics when possible
+  ```typescript
+  function process<T extends object>(data: T): T {
+    return data;
+  }
+  ```
+
+## React Patterns
+
+### Component Structure
+
+1. **Imports**: Group by external libraries, internal utilities, types, styles
+2. **Type Definitions**: Props interfaces, handler types
+3. **Component Declaration**: Use arrow functions or `function` keyword with `forwardRef` when needed
+4. **Hooks**: `useState`, `useRef`, `useEffect`, etc.
+5. **Handlers**: Event handlers and callbacks
+6. **Render Helpers**: Small render functions if needed
+7. **Return Statement**: JSX
+
+**Example**:
+
+```typescript
+import React, { forwardRef, useState, useEffect } from 'react';
+import { twMerge } from 'tailwind-merge';
+import type { SomeType } from './types';
+
+export type MyComponentProps = {
+  value: string;
+  onChange: (value: string) => void;
+  className?: string;
+};
+
+const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
+  function MyComponent(props, ref) {
+    const { value, onChange, className } = props;
+
+    const [localState, setLocalState] = useState('');
+
+    useEffect(() => {
+      // Effect logic
+    }, []);
+
+    const handleClick = () => {
+      onChange(value);
+    };
+
+    return (
+      <div ref={ref} className={twMerge('base-class', className)}>
+        {/* JSX content */}
+      </div>
+    );
+  }
+);
+
+export default MyComponent;
+```
+
+### Hooks Best Practices
+
+* **Custom Hooks**: Start with `use` prefix
+* **Dependencies**: Always specify complete dependency arrays
+* **Hook Order**: Keep hook calls at the top level, same order every render
+* **Ref Hooks**: Use `useRef` for mutable values that don't trigger re-renders
+* **Imperative Handles**: Use `useImperativeHandle` to expose component methods via refs
+
+### Props
+
+* **Destructure Props**: Destructure in function parameters
+* **Default Values**: Use destructuring defaults
+  ```typescript
+  const Component = ({ value = '', disabled = false }: Props) => {
+    // Component logic
+  };
+  ```
+* **Spread Props**: Use `...others` or `...rest` for passing through props
+* **Children**: Type as `React.ReactNode` for flexibility
+
+#### Props Spreading (Use Sparingly)
+
+**Avoid indiscriminate props spreading** - directly spreading props makes it difficult to quickly see what is being passed down.
+
+**Bad**:
+
+```typescript
+const color = (props) => getSyncButtonColor({ hover: true, ...props });
+
+function Comp({ dataA, ...props }) {
+  return <div {...props} />;
+}
+```
+
+**Good**:
+
+```typescript
+// Explicitly list props for clarity
+const color = ({ disabled, selected }) =>
+  getSyncButtonColor({ hover: true, disabled, selected });
+
+function Comp({ dataA, onClick, onMouseMove, role }) {
+  return <div onClick={onClick} onMouseMove={onMouseMove} role={role} />;
+}
+
+// Or use a named prop object for clarity
+function Comp({ dataA, divProps }) {
+  return <div {...divProps} />;
+}
+```
+
+**When to use spreading**:
+* Only when creating wrapper components that truly need to forward all props
+* When using a named props object (e.g., `divProps`, `buttonProps`) to make intent clear
+
+### State Management Patterns
+
+**Priority Order**: Redux > Local State
+
+#### 1. Redux (Preferred for Global State)
+
+* **Primary choice** for global application state
+* Use Redux Toolkit (`@reduxjs/toolkit`) for modern Redux patterns
+* Use `useSelector` and `useDispatch` hooks in components
+* Create slices with `createSlice` for state management
+* Use `createAsyncThunk` for async operations
+
+**Example**:
+
+```typescript
+import { createSlice, PayloadAction } from '@reduxjs/toolkit';
+
+interface AppState {
+  isOpen: boolean;
+  currentUser: string | null;
+}
+
+const initialState: AppState = {
+  isOpen: false,
+  currentUser: null,
+};
+
+const appSlice = createSlice({
+  name: 'app',
+  initialState,
+  reducers: {
+    setOpen: (state, action: PayloadAction<boolean>) => {
+      state.isOpen = action.payload;
+    },
+    setUser: (state, action: PayloadAction<string>) => {
+      state.currentUser = action.payload;
+    },
+  },
+});
+
+export const { setOpen, setUser } = appSlice.actions;
+export default appSlice.reducer;
+```
+
+**Usage**:
+
+```typescript
+import { useSelector, useDispatch } from 'react-redux';
+import { setOpen } from './appSlice';
+
+const Component = () => {
+  const isOpen = useSelector((state: RootState) => state.app.isOpen);
+  const dispatch = useDispatch();
+
+  const handleOpen = () => {
+    dispatch(setOpen(true));
+  };
+
+  return <div>{/* Component JSX */}</div>;
+};
+```
+
+#### 2. Local State (Preferred for Component-Specific State)
+
+* **Primary choice** for component-local state that doesn't need to be shared
+* Use `useState` for simple component-local state
+* Use `useReducer` for complex state logic with multiple sub-values
+* Keep state as local as possible before lifting to Redux
+
+**Example**:
+
+```typescript
+// Simple local state
+const [isTypingMode, setIsTypingMode] = useState(false);
+
+// Complex local state
+const [state, dispatch] = useReducer(reducer, initialState);
+```
+
+**Zustand 政策**: Zustand 僅供既有模組保留使用，新功能不得新增 Zustand store。
+
+**When to use each**:
+
+* **Redux**: Global state, cross-feature state, persistent state
+* **Local State**: UI state, form inputs, toggles, component-specific state
+
+## Styling Conventions
+
+### TailwindCSS
+
+* **Utility-First**: Prefer Tailwind utilities over custom CSS
+* **Class Merging**: Use `twMerge` to merge conflicting Tailwind classes
+  ```typescript
+  className={twMerge('p-0 bg-transparent rounded-none', classes.input)}
+  ```
+* **Conditional Classes**: Use `clsx` for conditional class names
+  ```typescript
+  className={clsx('x-btn', { 'x-btn-active': isActive }, className)}
+  ```
+* **Custom Utilities**: Define in `tailwind.config.js` using plugins
+* **Design System Classes**: Use predefined typography classes (`.x-heading-14`, `.x-body-3`, etc.)
+
+### 關於 Emotion / styled-components
+
+專案已不再使用 Emotion 與 styled-components；既有程式若仍使用可暫時保留，新程式請使用 Tailwind。
+
+### Style Organization
+
+* **Global Styles**: Define in Tailwind config or global CSS files
+* **Component Styles**: Inline with Tailwind classes
+* **Theme Variables**: Use Tailwind theme configuration
+* **Responsive Design**: Use Tailwind breakpoint prefixes (`sm:`, `md:`, `lg:`)
+
+## Event Handlers
+
+### Naming
+
+* Prefix with `handle` for event handlers: `handleClick`, `handleChange`, `handleSubmit`
+* Prefix with `on` for prop callbacks: `onClick`, `onChange`, `onSubmit`
+
+### Async Handlers
+
+* Mark as `async` when performing asynchronous operations
+* Handle errors appropriately
+  ```typescript
+  const handleSubmit = async () => {
+    try {
+      await submitData();
+    } catch (error) {
+      console.error('Submit failed:', error);
+    }
+  };
+  ```
+
+### Debouncing/Throttling
+
+* Use `lodash/throttle` or `lodash/debounce` for expensive operations
+* Use `@react-hook/throttle` for React-specific throttling
+
+## Code Organization
+
+### Directory Structure
+
+```
+next/
+├── components/
+│   ├── common/          # Reusable utility components
+│   ├── dumbs/           # Presentational "dumb" components
+│   ├── smarts/          # Smart/container components
+│   └── module/          # Feature modules
+├── api/                 # API utilities
+├── flow/                # Application flow logic
+└── utils/               # Shared utilities
+```
+
+### Component Categories
+
+* **Common**: Shared, reusable components (e.g., `EditableText`, `SvgIcon`)
+* **Dumbs**: Presentational components without business logic
+* **Smarts**: Container components with state and business logic
+* **Module**: Feature-specific components grouped by functionality
+
+### Barrel Exports
+
+* Use `index.ts` for clean imports
+  ```typescript
+  // index.ts
+  export { default as AppButton } from './AppButton';
+  export type { AppButtonProps } from './AppButton';
+  ```
+
+## Testing
+
+### Test Files
+
+* Co-locate tests with components: `ComponentName.test.tsx`
+* Use Vitest for unit and integration tests
+* Use `@testing-library/react` for component testing
+
+### Testing Best Practices
+
+* Test user behavior, not implementation details
+* Use semantic queries (`getByRole`, `getByLabelText`)
+* Mock external dependencies
+* Test edge cases and error states
+
+## Performance Optimization
+
+### React Optimization
+
+* Use `React.memo` for expensive pure components
+* Use `useMemo` for expensive computations
+* Use `useCallback` for stable function references
+* Avoid inline object/array creation in props
+
+### Code Splitting
+
+* Use dynamic `import()` for lazy loading
+* Split routes and large features
+
+### Bundle Size
+
+* Monitor bundle size with build tools
+* Tree-shake unused code
+* Use named imports from lodash: `import debounce from 'lodash/debounce'`
+
+## Commenting Policy
+
+See [Team-wide Coding Conventions](./team-wide.md#commenting-policy) for the team's minimalist commenting policy which applies to all languages including TypeScript/JavaScript.
+
+### Frontend-Specific Guidelines
+
+* **Complex State Logic**: Comment non-obvious state management patterns
+* **Workarounds**: Document workarounds with explanation
+  ```typescript
+  // WORKAROUND: without setTimeout, the focus won't work
+  setTimeout(() => {
+    inputRef.current.focus();
+  }, 0);
+  ```
+* **Type Assertions**: Explain why type assertion is necessary if non-obvious
+* **Regex Patterns**: Comment complex regex with explanation
+* **Magic Numbers**: Use named constants instead of comments
+
+## Import Organization
+
+### Import Order
+
+1. External libraries (React, third-party)
+2. Internal modules (aliased with `@/`)
+3. Types (using `import type`)
+4. Relative imports
+5. Styles (if any)
+
+**Example**:
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import { twMerge } from 'tailwind-merge';
+import clsx from 'clsx';
+
+import ClickOutsideHandler from '@/src/components/dumbs/click-outside-handler';
+import { useParameterComponentProps } from '@/src/components/shared/store';
+
+import type { MousePos } from '@/src/utils/mouseRx/types';
+import type { AppButtonProps } from './types';
+
+import './styles.css';
+```
+
+### Path Aliases
+
+* **Configure `@/` to point to project root**: The `@/` alias should point to the project root directory in `tsconfig.json` and build tool configuration
+* **Use `@/src/` for source imports**: Import from source code using `@/src/` prefix for semantic correctness
+* **Avoid `@src/` pattern**: This pattern semantically represents `https://npmjs.com/org/src` (an npm organization package), which is incorrect for local paths
+
+**tsconfig.json configuration**:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"]
+    }
+  }
+}
+```
+
+**Example usage**:
+
+```typescript
+// Good - clear local path alias (@/ points to project root)
+import { Component } from '@/src/components/AppButton';
+import type { UserData } from '@/src/types/user';
+
+// Bad - looks like npm org package
+import { Component } from '@src/components/AppButton';
+```
+
+## Accessibility (a11y)
+
+* Use semantic HTML elements
+* Provide `aria-` attributes when needed
+* Support keyboard navigation
+* Test with screen readers
+* Use ESLint plugin `jsx-a11y` rules
+
+## Internationalization (i18n)
+
+* Use translation keys, not hard-coded text
+* Follow `@m6web/i18n` ESLint rules
+* Avoid text as children or attributes without translation
+
+## Error Handling
+
+* Use try-catch for async operations
+* Log errors appropriately
+* Show user-friendly error messages
+* Handle edge cases gracefully
+
+## Related Resources
+
+* [Team-wide Coding Conventions](./team-wide.md) - Universal coding standards
+* [C++ Coding Standards](./cpp.md) - For native bridge integration
+* [Tech Stack Overview](../../knowledge/development/tech-stack.md) - Frontend technologies