desktop-team-doc 0.1.0

package/content/docs/knowledge/component-library/frontend-develop/references/code-organization.md

@@ -0,0 +1,620 @@
+# Code Organization Guidelines
+
+This document provides comprehensive guidelines for organizing frontend code, including functionality classification, hooks and stores usage, Atomic Design principles, and single responsibility principle.
+
+## Core Principles
+
+### Single Responsibility Principle (SRP)
+
+**Rule**: Each component, hook, or function should have one clear responsibility.
+
+**Bad**:
+
+```typescript
+function UserProfile({ userId }: { userId: string }) {
+  const [user, setUser] = useState(null);
+  const [posts, setPosts] = useState([]);
+  const [comments, setComments] = useState([]);
+
+  useEffect(() => {
+    // Fetch user
+    fetchUser(userId).then(setUser);
+    // Fetch posts
+    fetchPosts(userId).then(setPosts);
+    // Fetch comments
+    fetchComments(userId).then(setComments);
+  }, [userId]);
+
+  // Render user, posts, and comments...
+}
+```
+
+**Good**:
+
+```typescript
+interface UserProfileProps {
+  userId: string;
+}
+
+// Separate concerns into hooks
+function useUser(userId: string) {
+  const [user, setUser] = useState(null);
+  useEffect(() => {
+    fetchUser(userId).then(setUser);
+  }, [userId]);
+  return user;
+}
+
+function useUserPosts(userId: string) {
+  const [posts, setPosts] = useState([]);
+  useEffect(() => {
+    fetchPosts(userId).then(setPosts);
+  }, [userId]);
+  return posts;
+}
+
+function UserProfile({ userId }: UserProfileProps) {
+  const user = useUser(userId);
+  const posts = useUserPosts(userId);
+  // Render...
+}
+```
+
+## Functionality Classification
+
+### When to Extract Functionality
+
+Extract functionality into separate modules when:
+
+1. **Reusability**: Logic is used in multiple components
+2. **Complexity**: Logic is complex enough to warrant separation
+3. **Testability**: Logic needs to be tested independently
+4. **Maintainability**: Logic changes independently from component
+
+### Classification Patterns
+
+#### Pattern 1: Extract to Custom Hook
+
+**When**: Logic involves React hooks and state management.
+
+**Example**:
+
+```typescript
+// Custom hook for cooldown pattern
+const useCooldown = (delayMs: number) => {
+  const lastCallTime = useRef(0);
+
+  return () => {
+    const now = Date.now();
+    if (now - lastCallTime.current < delayMs) {
+      return false;
+    }
+    lastCallTime.current = now;
+    return true;
+  };
+};
+
+// Usage
+function Button() {
+  const checkCooldown = useCooldown(1000);
+
+  const handleClick = () => {
+    if (checkCooldown()) {
+      // Execute action
+    }
+  };
+}
+```
+
+#### Pattern 2: Extract to Utility Function
+
+**When**: Pure functions without React dependencies.
+
+**Example**:
+
+```typescript
+// Utility function
+export function formatCurrency(amount: number, currency: string): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+  }).format(amount);
+}
+
+// Usage in component
+interface PriceDisplayProps {
+  amount: number;
+}
+
+function PriceDisplay({ amount }: PriceDisplayProps) {
+  return <span>{formatCurrency(amount, 'USD')}</span>;
+}
+```
+
+#### Pattern 3: Extract to Store (Redux)
+
+**When**: State needs to be shared across multiple components.
+
+See [State Management](./state-management.md) for detailed guidelines.
+
+## Hooks Organization
+
+### Custom Hooks Best Practices
+
+#### Naming Convention
+
+**Rule**: Custom hooks must start with `use` prefix.
+
+**Example**:
+
+```typescript
+// Good
+function useCooldown(delayMs: number) {}
+function useNewestValue<T>(value: T) {}
+function useMountedState() {}
+
+// Bad
+function cooldown(delayMs: number) {}
+function getNewestValue<T>(value: T) {}
+```
+
+#### Hook Structure
+
+**Rule**: Follow consistent structure for custom hooks.
+
+**Structure**:
+
+1. Input parameters (props)
+2. State declarations (`useState`, `useRef`)
+3. Effects (`useEffect`, `useLayoutEffect`)
+4. Computed values (`useMemo`, `useCallback`)
+5. Return value
+
+**Example**:
+
+```typescript
+function useNewestValue<T>(value: T): () => T {
+  // 1. Input: value (T)
+
+  // 2. State
+  const ref = useRef(value);
+
+  // 3. Effects
+  ref.current = value;
+
+  // 4. Computed
+  // (none in this case)
+
+  // 5. Return
+  return () => ref.current;
+}
+```
+
+#### Hook Dependencies
+
+**Rule**: Always specify complete dependency arrays.
+
+**Bad**:
+
+```typescript
+useEffect(() => {
+  fetchData(userId);
+}, []); // Missing userId dependency
+```
+
+**Good**:
+
+```typescript
+useEffect(() => {
+  fetchData(userId);
+}, [userId]); // Complete dependency array
+```
+
+### When to Create Custom Hooks
+
+Create custom hooks when:
+
+1. **Reusable Logic**: Logic is used in multiple components
+2. **Complex State**: State logic is complex
+3. **Side Effects**: Managing side effects that can be abstracted
+4. **API Calls**: Data fetching logic that can be reused
+
+**Example**: Custom hook for API calls
+
+```typescript
+function useApiData<T>(url: string): {
+  data: T | null;
+  loading: boolean;
+  error: Error | null;
+} {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    setLoading(true);
+    fetch(url)
+      .then((res) => res.json())
+      .then((data) => {
+        setData(data);
+        setLoading(false);
+      })
+      .catch((err) => {
+        setError(err);
+        setLoading(false);
+      });
+  }, [url]);
+
+  return { data, loading, error };
+}
+```
+
+## Store Organization
+
+### When to Use Stores
+
+**Priority Order**: Redux > Local State
+
+#### Use Redux When:
+
+- State is global and shared across many components
+- State needs to persist across navigation
+- State needs time-travel debugging
+- Complex state updates with middleware
+
+#### Use Local State When:
+
+- State is component-specific
+- State doesn't need to be shared
+- Simple state management
+
+**Zustand 政策**: Zustand 僅既有模組保留，新功能請用 Redux 或 Local State。
+
+See [State Management](./state-management.md) for detailed guidelines.
+
+## Atomic Design Principles
+
+### Component Hierarchy
+
+Atomic Design organizes components into five levels:
+
+1. **Atoms**: Basic building blocks (buttons, inputs, labels)
+2. **Molecules**: Simple combinations of atoms (form fields, search bars)
+3. **Organisms**: Complex UI components (headers, forms, tables)
+4. **Templates**: Page-level layouts
+5. **Pages**: Specific instances of templates
+
+### Directory Structure
+
+**Rule**: Organize components by Atomic Design levels.
+
+**Structure**:
+
+```
+components/
+├── atoms/              # Basic building blocks
+│   ├── Button.tsx
+│   ├── Input.tsx
+│   └── Label.tsx
+├── molecules/          # Simple combinations
+│   ├── FormField.tsx
+│   └── SearchBar.tsx
+├── organisms/          # Complex components
+│   ├── Header.tsx
+│   └── DataTable.tsx
+├── templates/          # Page layouts
+│   └── MainLayout.tsx
+└── pages/              # Specific pages
+    └── HomePage.tsx
+```
+
+### Project-Specific Structure
+
+This project uses a modified structure:
+
+```
+components/
+├── common/            # Reusable utility components
+├── dumbs/             # Presentational components (no logic)
+├── smarts/             # Container components (with logic)
+└── module/             # Feature modules
+```
+
+**Rule**: Follow project structure conventions.
+
+- **dumbs/**: Presentational components without business logic
+- **smarts/**: Container components with state and business logic
+- **common/**: Shared utility components
+- **module/**: Feature-specific components grouped by functionality
+
+### Component Classification Examples
+
+#### Dumb Component (Presentational)
+
+```typescript
+// components/dumbs/Button.tsx
+export interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+  variant?: 'primary' | 'secondary';
+}
+
+export function Button({ label, onClick, disabled = false, variant = 'primary' }: ButtonProps): JSX.Element {
+  return (
+    <button onClick={onClick} disabled={disabled} className={clsx('btn', `btn-${variant}`)}>
+      {label}
+    </button>
+  );
+}
+```
+
+#### Smart Component (Container)
+
+```typescript
+// components/smarts/UserProfile.tsx
+interface UserProfileProps {
+  userId: string;
+}
+
+export function UserProfile({ userId }: UserProfileProps): JSX.Element {
+  const user = useUser(userId);
+  const posts = useUserPosts(userId);
+  const { updateUser } = useUserActions();
+
+  if (!user) {
+    return <LoadingSpinner />;
+  }
+
+  return (
+    <div>
+      <UserHeader user={user} />
+      <UserPosts posts={posts} />
+      <UserActions onUpdate={updateUser} />
+    </div>
+  );
+}
+```
+
+## Layout Organization
+
+### Avoid Excessive Nesting
+
+**Rule**: Keep component nesting levels reasonable (max 3-4 levels).
+
+**Bad**:
+
+```typescript
+function App() {
+  return (
+    <div>
+      <div>
+        <div>
+          <div>
+            <div>
+              <Component />
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+**Good**:
+
+```typescript
+function App() {
+  return (
+    <Layout>
+      <Header />
+      <MainContent>
+        <Component />
+      </MainContent>
+      <Footer />
+    </Layout>
+  );
+}
+```
+
+### Split Complex Layouts
+
+**Rule**: Break down complex layouts into smaller, focused components.
+
+**Example**:
+
+```typescript
+// Instead of one large component
+function ComplexDashboard() {
+  return <div>{/* 200 lines of JSX */}</div>;
+}
+
+// Split into focused components
+function Dashboard() {
+  return (
+    <DashboardLayout>
+      <DashboardHeader />
+      <DashboardSidebar />
+      <DashboardContent>
+        <StatsPanel />
+        <ChartsPanel />
+        <ActivityFeed />
+      </DashboardContent>
+    </DashboardLayout>
+  );
+}
+```
+
+## File Organization
+
+### File Naming
+
+**Rule**: Follow project naming conventions.
+
+- **Components**: `PascalCase.tsx` (e.g., `AppButton.tsx`)
+- **Hooks**: `camelCase.ts` starting with "use" (e.g., `useInputStatus.ts`)
+- **Utilities**: `camelCase.ts` (e.g., `constants.ts`, `utils.ts`)
+- **Stores**: `camelCase.ts` with "Store" suffix (e.g., `guitarMatchStore.ts`)
+- **Types**: `types.ts` or `interfaces.ts`
+
+### Import Organization
+
+**Rule**: Organize imports in specific order.
+
+1. External libraries (React, third-party)
+2. Internal modules (aliased with `@/`)
+3. Types (using `import type`)
+4. Relative imports
+5. Styles
+
+**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';
+```
+
+### Barrel Exports
+
+**Rule**: Use `index.ts` for clean imports.
+
+**Example**:
+
+```typescript
+// components/common/index.ts
+export { default as AppButton } from './AppButton';
+export type { AppButtonProps } from './AppButton';
+export { default as EditableText } from './EditableText';
+export type { EditableTextProps } from './EditableText';
+
+// Usage
+import { AppButton, EditableText } from '@/src/components/common';
+import type { AppButtonProps } from '@/src/components/common';
+```
+
+## Module Organization
+
+### Feature-Based Organization
+
+**Rule**: Group related components, hooks, and utilities by feature.
+
+**Structure**:
+
+```
+feature-name/
+├── components/
+│   ├── FeatureComponent.tsx
+│   └── FeatureSubComponent.tsx
+├── hooks/
+│   ├── useFeatureData.ts
+│   └── useFeatureActions.ts
+├── utils/
+│   └── featureUtils.ts
+├── types.ts
+├── constants.ts
+└── index.ts
+```
+
+**Example**: MIDI Control Module
+
+```
+midi-control/
+├── components/
+│   ├── MidiMapping.tsx
+│   ├── MidiPresetSettings.tsx
+│   └── MidiGlobalSettings.tsx
+├── hooks/
+│   ├── useCcControl.ts
+│   ├── useGlobalMidiMappings.ts
+│   └── useGlobalMidiParameterOptions.ts
+├── utils/
+│   └── midiUtils.ts
+├── types.ts
+├── constants.ts
+└── index.ts
+```
+
+## Code Splitting
+
+### Component-Level Splitting
+
+**Rule**: Split large components into smaller, focused components.
+
+**Example**:
+
+```typescript
+// Large component (bad)
+function UserDashboard() {
+  // 500+ lines of code
+}
+
+// Split into smaller components (good)
+function UserDashboard() {
+  return (
+    <>
+      <UserHeader />
+      <UserStats />
+      <UserActivity />
+      <UserSettings />
+    </>
+  );
+}
+```
+
+### Route-Based Splitting
+
+**Rule**: Use dynamic imports for route-based code splitting.
+
+**Example**:
+
+```typescript
+import { lazy, Suspense } from 'react';
+
+const UserProfile = lazy(() => import('./UserProfile'));
+const Settings = lazy(() => import('./Settings'));
+
+function App() {
+  return (
+    <Suspense fallback={<LoadingSpinner />}>
+      <Routes>
+        <Route path="/profile" element={<UserProfile />} />
+        <Route path="/settings" element={<Settings />} />
+      </Routes>
+    </Suspense>
+  );
+}
+```
+
+## Summary Checklist
+
+When organizing code, ensure:
+
+- [ ] Single responsibility principle maintained
+- [ ] Functionality properly classified (hooks, utilities, stores)
+- [ ] Custom hooks follow naming convention (`use` prefix)
+- [ ] Components follow Atomic Design principles
+- [ ] Dumb/smart component separation clear
+- [ ] No excessive nesting (max 3-4 levels)
+- [ ] Complex layouts split into smaller components
+- [ ] Files follow naming conventions
+- [ ] Imports organized in correct order
+- [ ] Barrel exports used for clean imports
+- [ ] Feature-based module organization
+- [ ] Code splitting implemented where appropriate
+
+## References
+
+- [Atomic Design Methodology](https://atomicdesign.bradfrost.com/)
+- [React Hooks Best Practices](https://react.dev/reference/react)
+- Project Coding Standards: `desktop-team-documentation/instructions/coding-conventions/frontend.md`
+- [State Management Guidelines](./state-management.md)