desktop-team-doc 0.1.0

package/content/docs/knowledge/component-library/frontend-develop/references/state-management.md

@@ -0,0 +1,331 @@
+# State Management Guidelines
+
+This document provides comprehensive guidelines for state management in React applications, including when to use Redux or local state.
+
+## Priority Order
+
+**State Management Priority**: Redux > Local State
+
+**Zustand 政策**: Zustand 僅既有程式保留使用；新 state 一律使用 Redux 或 Local State。
+
+Choose state management solution based on:
+
+1. **Scope**: Where is the state used?
+2. **Persistence**: Does state need to persist?
+3. **Complexity**: How complex is the state logic?
+4. **Sharing**: How many components need access?
+
+## Redux (Preferred for Global State)
+
+### When to Use Redux
+
+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
+- State needs to be synchronized with external systems
+
+### Redux Toolkit Patterns
+
+**Slice Creation**:
+
+```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 in Components**:
+
+```typescript
+import { useSelector, useDispatch } from 'react-redux';
+import { setOpen } from './appSlice';
+
+function Component() {
+  const isOpen = useSelector((state: RootState) => state.app.isOpen);
+  const dispatch = useDispatch();
+
+  const handleOpen = () => {
+    dispatch(setOpen(true));
+  };
+
+  return <div>{/* Component JSX */}</div>;
+}
+```
+
+**Async Operations with createAsyncThunk**:
+
+```typescript
+import { createAsyncThunk, createSlice } from '@reduxjs/toolkit';
+
+export const fetchUserData = createAsyncThunk('user/fetchUserData', async (userId: string) => {
+  const response = await fetch(`/api/users/${userId}`);
+  return response.json();
+});
+
+const userSlice = createSlice({
+  name: 'user',
+  initialState: { data: null, loading: false, error: null },
+  reducers: {},
+  extraReducers: (builder) => {
+    builder
+      .addCase(fetchUserData.pending, (state) => {
+        state.loading = true;
+      })
+      .addCase(fetchUserData.fulfilled, (state, action) => {
+        state.loading = false;
+        state.data = action.payload;
+      })
+      .addCase(fetchUserData.rejected, (state, action) => {
+        state.loading = false;
+        state.error = action.error.message;
+      });
+  },
+});
+```
+
+## Local State (Preferred for Component-Specific State)
+
+### When to Use Local State
+
+Use local state when:
+
+- State is component-specific
+- State doesn't need to be shared
+- Simple state management
+- UI-only state (modals, form inputs, toggles)
+
+### useState Pattern
+
+**Simple State**:
+
+```typescript
+function Component() {
+  const [isTypingMode, setIsTypingMode] = useState(false);
+  const [inputValue, setInputValue] = useState('');
+
+  return (
+    <div>
+      <input value={inputValue} onChange={(e) => setInputValue(e.target.value)} />
+    </div>
+  );
+}
+```
+
+### useReducer Pattern
+
+**Complex State**:
+
+```typescript
+interface State {
+  count: number;
+  step: number;
+}
+
+type Action = { type: 'increment' } | { type: 'decrement' } | { type: 'reset' } | { type: 'setStep'; step: number };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'increment':
+      return { ...state, count: state.count + state.step };
+    case 'decrement':
+      return { ...state, count: state.count - state.step };
+    case 'reset':
+      return { ...state, count: 0 };
+    case 'setStep':
+      return { ...state, step: action.step };
+    default:
+      return state;
+  }
+}
+
+function Component() {
+  const [state, dispatch] = useReducer(reducer, { count: 0, step: 1 });
+
+  return (
+    <div>
+      <button onClick={() => dispatch({ type: 'increment' })}>Increment</button>
+      <button onClick={() => dispatch({ type: 'decrement' })}>Decrement</button>
+      <button onClick={() => dispatch({ type: 'reset' })}>Reset</button>
+    </div>
+  );
+}
+```
+
+## Zustand（既有功能保留）
+
+Zustand 僅用於既有模組，新 state 一律使用 Redux 或 Local State。既有程式若使用 Zustand，可參考 [Zustand Documentation](https://github.com/pmndrs/zustand) 了解訂閱與使用方式。
+
+## Decision Tree
+
+### State Management Decision Flow
+
+```
+Is state used by multiple components?
+├─ No → Use Local State (useState/useReducer)
+└─ Yes
+   ├─ Is state global/shared across many components?
+   │  ├─ Yes → Use Redux
+   │  └─ No
+   │     ├─ Is state module-specific?
+   │     │  ├─ Yes → Use Redux or Local State (lift state up)
+   │     │  └─ No → Use Local State (lift state up)
+   │     └─ Does state need persistence?
+   │        ├─ Yes → Use Redux
+   │        └─ No → Use Local State
+```
+
+## Best Practices
+
+### State Colocation
+
+**Rule**: Keep state as close to where it's used as possible.
+
+**Bad**:
+
+```typescript
+// State in root component
+function App() {
+  const [modalOpen, setModalOpen] = useState(false);
+  return (
+    <>
+      <Header />
+      <Content />
+      <Modal open={modalOpen} onClose={() => setModalOpen(false)} />
+    </>
+  );
+}
+```
+
+**Good**:
+
+```typescript
+// State colocated with component that uses it
+function App() {
+  return (
+    <>
+      <Header />
+      <Content />
+      <ModalContainer />
+    </>
+  );
+}
+
+function ModalContainer() {
+  const [modalOpen, setModalOpen] = useState(false);
+  return <Modal open={modalOpen} onClose={() => setModalOpen(false)} />;
+}
+```
+
+### State Normalization
+
+**Rule**: Normalize nested state structures.
+
+**Bad**:
+
+```typescript
+interface State {
+  users: {
+    [id: string]: {
+      id: string;
+      name: string;
+      posts: {
+        [id: string]: {
+          id: string;
+          title: string;
+        };
+      };
+    };
+  };
+}
+```
+
+**Good**:
+
+```typescript
+interface State {
+  users: {
+    [id: string]: {
+      id: string;
+      name: string;
+      postIds: string[];
+    };
+  };
+  posts: {
+    [id: string]: {
+      id: string;
+      userId: string;
+      title: string;
+    };
+  };
+}
+```
+
+### Derived State
+
+**Rule**: Compute derived state instead of storing it.
+
+**Bad**:
+
+```typescript
+const [items, setItems] = useState<Item[]>([]);
+const [filteredItems, setFilteredItems] = useState<Item[]>([]);
+
+useEffect(() => {
+  setFilteredItems(items.filter((item) => item.active));
+}, [items]);
+```
+
+**Good**:
+
+```typescript
+const [items, setItems] = useState<Item[]>([]);
+
+// Compute derived state directly
+const filteredItems = items.filter((item) => item.active);
+```
+
+## Summary Checklist
+
+When choosing state management, ensure:
+
+- [ ] State scope evaluated (local vs global)
+- [ ] Redux used for global/shared state
+- [ ] Local state used for component-specific state
+- [ ] State colocated close to usage
+- [ ] State normalized when nested
+- [ ] Derived state computed, not stored
+- [ ] Redux Toolkit patterns followed
+- [ ] Async operations use createAsyncThunk
+
+## References
+
+- [Redux Toolkit Documentation](https://redux-toolkit.js.org/)
+- [React State Management](https://react.dev/learn/managing-state)
+- Project Coding Standards: `desktop-team-documentation/instructions/coding-conventions/frontend.md`

package/content/docs/knowledge/component-library/frontend-develop/references/styling-guidelines.md

@@ -0,0 +1,349 @@
+# Styling Guidelines
+
+This document provides comprehensive guidelines for styling in React applications, including TailwindCSS priority strategy and style organization.
+
+## Styling Priority
+
+**Styling Priority**: TailwindCSS > Custom CSS
+
+## TailwindCSS (Primary)
+
+### Utility-First Approach
+
+**Rule**: Prefer Tailwind utilities over custom CSS.
+
+**Example**:
+```typescript
+function Component() {
+  return (
+    <div className="p-4 bg-white rounded-lg shadow-md">
+      <h2 className="text-xl font-bold mb-2">Title</h2>
+      <p className="text-gray-600">Content</p>
+    </div>
+  );
+}
+```
+
+### Class Merging
+
+**Rule**: Use `twMerge` to merge conflicting Tailwind classes.
+
+**Example**:
+```typescript
+import { twMerge } from 'tailwind-merge';
+
+interface ComponentProps {
+  className?: string;
+}
+
+function Component({ className }: ComponentProps) {
+  return (
+    <div
+      className={twMerge(
+        'p-4 bg-white rounded-lg',
+        className // Can override previous classes
+      )}
+    >
+      Content
+    </div>
+  );
+}
+```
+
+### Conditional Classes
+
+**Rule**: Use `clsx` for conditional class names.
+
+**Example**:
+```typescript
+import clsx from 'clsx';
+
+function Button({ active, disabled }: Props) {
+  return (
+    <button
+      className={clsx(
+        'x-btn',
+        {
+          'x-btn-active': active,
+          'x-btn-disabled': disabled,
+        }
+      )}
+    >
+      Click
+    </button>
+  );
+}
+```
+
+### Design System Classes
+
+**Rule**: Use predefined design system classes.
+
+**Typography Classes**:
+- `.x-heading-14`, `.x-heading-16`, `.x-heading-18`
+- `.x-body-3`, `.x-body-4`
+- `.heading-14`, `.body-16`
+
+**Component Classes**:
+- `.x-btn`, `.x-btn-active`, `.x-btn-disabled`
+- `.x-red-dot`
+- `.pg-scroll-bar`
+
+**Example**:
+```typescript
+function Component() {
+  return (
+    <div>
+      <h1 className="x-heading-18">Title</h1>
+      <p className="x-body-4">Content</p>
+      <button className="x-btn x-btn-active">Click</button>
+    </div>
+  );
+}
+```
+
+### Responsive Design
+
+**Rule**: Use Tailwind breakpoint prefixes.
+
+**Breakpoints**:
+- `sm:` - 640px
+- `md:` - 768px
+- `lg:` - 1024px
+- `xl:` - 1280px
+- `2xl:` - 1536px
+
+**Example**:
+```typescript
+function Component() {
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+      <div>Item 1</div>
+      <div>Item 2</div>
+      <div>Item 3</div>
+    </div>
+  );
+}
+```
+
+## 關於 Emotion / styled-components
+
+專案因效能考量已不再使用 Emotion 與 styled-components。新樣式請使用 Tailwind；既有程式若仍使用 Emotion 可逐步遷移。
+
+## Custom CSS
+
+### When to Use Custom CSS
+
+Use custom CSS only when:
+- Global styles needed
+- Complex animations that can't be done with Tailwind
+- Third-party library overrides
+- Design system utilities
+
+### Global Styles
+
+**Rule**: Define global styles in Tailwind config or global CSS files.
+
+**tailwind.config.js**:
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: '#your-color',
+      },
+    },
+  },
+};
+```
+
+**global.css**:
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  body {
+    @apply font-sans antialiased;
+  }
+}
+```
+
+## Style Organization
+
+### Component Styles
+
+**Rule**: Keep styles close to components.
+
+**Structure**:
+```
+Component.tsx
+Component.module.css (if needed)
+Component.test.tsx
+```
+
+### Theme Variables
+
+**Rule**: Use Tailwind theme configuration for design tokens.
+
+**tailwind.config.js**:
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50: '#f0f9ff',
+          500: '#3b82f6',
+          900: '#1e3a8a',
+        },
+      },
+      spacing: {
+        '18': '4.5rem',
+        '88': '22rem',
+      },
+    },
+  },
+};
+```
+
+### Custom Utilities
+
+**Rule**: Define custom utilities in Tailwind config using plugins.
+
+**tailwind.config.js**:
+```javascript
+const plugin = require('tailwindcss/plugin');
+
+module.exports = {
+  plugins: [
+    plugin(function ({ addUtilities }) {
+      addUtilities({
+        '.scrollbar-hide': {
+          '-ms-overflow-style': 'none',
+          'scrollbar-width': 'none',
+          '&::-webkit-scrollbar': {
+            display: 'none',
+          },
+        },
+      });
+    }),
+  ],
+};
+```
+
+## Performance Considerations
+
+### CSS Performance
+
+**Rule**: Optimize CSS for performance.
+
+**Best Practices**:
+- Use Tailwind's purging to remove unused styles
+- Avoid deeply nested selectors
+- Use CSS transforms for animations
+- Minimize layout thrashing
+
+See [Performance Optimization](./performance-optimization.md) for detailed CSS performance guidelines.
+
+## Common Patterns
+
+### Pattern 1: Variant Styling
+
+```typescript
+import { twMerge } from 'tailwind-merge';
+import clsx from 'clsx';
+
+interface ButtonProps {
+  variant?: 'primary' | 'secondary';
+  size?: 'small' | 'medium' | 'large';
+  className?: string;
+}
+
+function Button({
+  variant = 'primary',
+  size = 'medium',
+  className,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={twMerge(
+        'rounded font-medium transition',
+        variant === 'primary' && 'bg-blue-500 text-white hover:bg-blue-600',
+        variant === 'secondary' && 'bg-gray-200 text-gray-800 hover:bg-gray-300',
+        size === 'small' && 'px-2 py-1 text-sm',
+        size === 'medium' && 'px-4 py-2 text-base',
+        size === 'large' && 'px-6 py-3 text-lg',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+### Pattern 2: Conditional Styling
+
+```typescript
+import clsx from 'clsx';
+
+function Component({ isActive, isDisabled }: Props) {
+  return (
+    <div
+      className={clsx(
+        'base-class',
+        {
+          'active-class': isActive,
+          'disabled-class': isDisabled,
+        }
+      )}
+    >
+      Content
+    </div>
+  );
+}
+```
+
+### Pattern 3: Responsive Styling
+
+```typescript
+function Component() {
+  return (
+    <div className="
+      grid
+      grid-cols-1
+      sm:grid-cols-2
+      md:grid-cols-3
+      lg:grid-cols-4
+      gap-4
+      p-4
+      md:p-6
+      lg:p-8
+    ">
+      {/* Content */}
+    </div>
+  );
+}
+```
+
+## Summary Checklist
+
+When styling components, ensure:
+
+- [ ] TailwindCSS used as primary styling approach
+- [ ] `twMerge` used for class merging
+- [ ] `clsx` used for conditional classes
+- [ ] Design system classes used when available
+- [ ] Responsive design with breakpoint prefixes
+- [ ] Custom CSS minimized
+- [ ] Styles organized close to components
+- [ ] Theme variables in Tailwind config
+- [ ] Performance considerations applied
+
+## References
+
+- [TailwindCSS Documentation](https://tailwindcss.com/docs)
+- Project Coding Standards: `desktop-team-documentation/instructions/coding-conventions/frontend.md`
+- [Performance Optimization](./performance-optimization.md)