desktop-team-doc 0.1.0

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

@@ -0,0 +1,554 @@
+# Real-World Examples and Best Practices
+
+This document provides comprehensive real-world examples demonstrating best practices for frontend development, including component patterns, common anti-patterns, and practical solutions.
+
+## Complete Component Example
+
+### Example: Reusable Button Component
+
+This example demonstrates:
+- Proper TypeScript typing
+- Variant design
+- Performance optimization
+- Style organization
+- Accessibility
+
+```typescript
+import React, { forwardRef } from 'react';
+import { twMerge } from 'tailwind-merge';
+import clsx from 'clsx';
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'outline';
+  size?: 'small' | 'medium' | 'large';
+  loading?: boolean;
+  fullWidth?: boolean;
+}
+
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button(
+    {
+      variant = 'primary',
+      size = 'medium',
+      loading = false,
+      fullWidth = false,
+      disabled,
+      className,
+      children,
+      ...props
+    },
+    ref
+  ) {
+    const isDisabled = disabled || loading;
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        disabled={isDisabled}
+        className={twMerge(
+          'inline-flex items-center justify-center rounded font-medium transition-colors',
+          'focus:outline-none focus:ring-2 focus:ring-offset-2',
+          variant === 'primary' && 'bg-blue-500 text-white hover:bg-blue-600 focus:ring-blue-500',
+          variant === 'secondary' && 'bg-gray-200 text-gray-800 hover:bg-gray-300 focus:ring-gray-500',
+          variant === 'outline' && 'border-2 border-blue-500 text-blue-500 hover:bg-blue-50 focus:ring-blue-500',
+          size === 'small' && 'px-2 py-1 text-sm',
+          size === 'medium' && 'px-4 py-2 text-base',
+          size === 'large' && 'px-6 py-3 text-lg',
+          {
+            'opacity-50 cursor-not-allowed': isDisabled,
+            'w-full': fullWidth,
+          },
+          className
+        )}
+        aria-busy={loading}
+        {...props}
+      >
+        {loading ? (
+          <>
+            <Spinner className="mr-2" />
+            Loading...
+          </>
+        ) : (
+          children
+        )}
+      </button>
+    );
+  }
+);
+
+export default Button;
+```
+
+## Common Patterns
+
+### Pattern 1: Custom Hook for Data Fetching
+
+```typescript
+import { useState, useEffect } from 'react';
+
+interface UseApiDataOptions {
+  enabled?: boolean;
+}
+
+function useApiData<T>(
+  url: string,
+  options: UseApiDataOptions = {}
+): {
+  data: T | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [refetchTrigger, setRefetchTrigger] = useState(0);
+
+  const refetch = () => {
+    setRefetchTrigger(prev => prev + 1);
+  };
+
+  useEffect(() => {
+    if (options.enabled === false) {
+      return;
+    }
+
+    let cancelled = false;
+
+    setLoading(true);
+    setError(null);
+
+    fetch(url)
+      .then(res => {
+        if (!res.ok) {
+          throw new Error(`HTTP error! status: ${res.status}`);
+        }
+        return res.json();
+      })
+      .then((data: T) => {
+        if (!cancelled) {
+          setData(data);
+          setLoading(false);
+        }
+      })
+      .catch((err: Error) => {
+        if (!cancelled) {
+          setError(err);
+          setLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [url, refetchTrigger, options.enabled]);
+
+  return { data, loading, error, refetch };
+}
+
+// Usage
+interface UserProfileProps {
+  userId: string;
+}
+
+function UserProfile({ userId }: UserProfileProps) {
+  const { data: user, loading, error } = useApiData<User>(
+    `/api/users/${userId}`
+  );
+
+  if (loading) {
+    return <LoadingSpinner />;
+  }
+
+  if (error) {
+    return <ErrorMessage error={error} />;
+  }
+
+  if (!user) {
+    return <EmptyState />;
+  }
+
+  return <div>{user.name}</div>;
+}
+```
+
+### Pattern 2: Form Handling with Validation
+
+```typescript
+import { useState, useCallback } from 'react';
+
+interface FormData {
+  email: string;
+  password: string;
+}
+
+interface FormErrors {
+  email?: string;
+  password?: string;
+}
+
+function validateForm(data: FormData): FormErrors {
+  const errors: FormErrors = {};
+
+  if (!data.email) {
+    errors.email = 'Email is required';
+  } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
+    errors.email = 'Invalid email format';
+  }
+
+  if (!data.password) {
+    errors.password = 'Password is required';
+  } else if (data.password.length < 8) {
+    errors.password = 'Password must be at least 8 characters';
+  }
+
+  return errors;
+}
+
+interface LoginFormProps {
+  onSubmit: (data: FormData) => Promise<void>;
+}
+
+function LoginForm({ onSubmit }: LoginFormProps) {
+  const [formData, setFormData] = useState<FormData>({
+    email: '',
+    password: '',
+  });
+  const [errors, setErrors] = useState<FormErrors>({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleChange = useCallback((field: keyof FormData) => {
+    return (e: React.ChangeEvent<HTMLInputElement>) => {
+      setFormData(prev => ({ ...prev, [field]: e.target.value }));
+      // Clear error when user starts typing
+      if (errors[field]) {
+        setErrors(prev => ({ ...prev, [field]: undefined }));
+      }
+    };
+  }, [errors]);
+
+  const handleSubmit = useCallback(async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    const validationErrors = validateForm(formData);
+    if (Object.keys(validationErrors).length > 0) {
+      setErrors(validationErrors);
+      return;
+    }
+
+    setIsSubmitting(true);
+    try {
+      await onSubmit(formData);
+    } catch (error) {
+      console.error('Submit failed:', error);
+    } finally {
+      setIsSubmitting(false);
+    }
+  }, [formData, onSubmit]);
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <div>
+        <label htmlFor="email">Email</label>
+        <input
+          id="email"
+          type="email"
+          value={formData.email}
+          onChange={handleChange('email')}
+          aria-invalid={!!errors.email}
+          aria-describedby={errors.email ? 'email-error' : undefined}
+        />
+        {errors.email && (
+          <span id="email-error" role="alert">
+            {errors.email}
+          </span>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="password">Password</label>
+        <input
+          id="password"
+          type="password"
+          value={formData.password}
+          onChange={handleChange('password')}
+          aria-invalid={!!errors.password}
+          aria-describedby={errors.password ? 'password-error' : undefined}
+        />
+        {errors.password && (
+          <span id="password-error" role="alert">
+            {errors.password}
+          </span>
+        )}
+      </div>
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Submitting...' : 'Login'}
+      </button>
+    </form>
+  );
+}
+```
+
+### Pattern 3: Optimized List Component
+
+```typescript
+import React, { memo, useMemo } from 'react';
+
+interface Item {
+  id: string;
+  name: string;
+  description: string;
+}
+
+interface ItemProps {
+  item: Item;
+  onSelect: (id: string) => void;
+  isSelected: boolean;
+}
+
+const Item = memo(function Item({ item, onSelect, isSelected }: ItemProps) {
+  const handleClick = React.useCallback(() => {
+    onSelect(item.id);
+  }, [item.id, onSelect]);
+
+  return (
+    <div
+      onClick={handleClick}
+      className={clsx(
+        'p-4 border rounded cursor-pointer transition',
+        {
+          'border-blue-500 bg-blue-50': isSelected,
+          'border-gray-200 hover:border-gray-300': !isSelected,
+        }
+      )}
+    >
+      <h3 className="font-semibold">{item.name}</h3>
+      <p className="text-sm text-gray-600">{item.description}</p>
+    </div>
+  );
+});
+
+interface ItemListProps {
+  items: Item[];
+  selectedIds: Set<string>;
+  onSelect: (id: string) => void;
+  filter?: string;
+}
+
+function ItemList({ items, selectedIds, onSelect, filter }: ItemListProps) {
+  // Memoize filtered items
+  const filteredItems = useMemo(() => {
+    if (!filter) {
+      return items;
+    }
+    return items.filter(item =>
+      item.name.toLowerCase().includes(filter.toLowerCase()) ||
+      item.description.toLowerCase().includes(filter.toLowerCase())
+    );
+  }, [items, filter]);
+
+  // Memoize callback
+  const handleSelect = React.useCallback((id: string) => {
+    onSelect(id);
+  }, [onSelect]);
+
+  return (
+    <div className="space-y-2">
+      {filteredItems.map(item => (
+        <Item
+          key={item.id}
+          item={item}
+          onSelect={handleSelect}
+          isSelected={selectedIds.has(item.id)}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+## Anti-patterns and Solutions
+
+### Anti-pattern 1: Unnecessary useMemo
+
+**Bad**:
+```typescript
+function Component({ count }: { count: number }) {
+  // Unnecessary: simple calculation
+  const doubled = useMemo(() => count * 2, [count]);
+  return <div>{doubled}</div>;
+}
+```
+
+**Good**:
+```typescript
+interface ComponentProps {
+  count: number;
+}
+
+function Component({ count }: ComponentProps) {
+  // Simple calculation, no memoization needed
+  const doubled = count * 2;
+  return <div>{doubled}</div>;
+}
+```
+
+### Anti-pattern 2: Missing Dependency Arrays
+
+**Bad**:
+```typescript
+function Component({ userId }: { userId: string }) {
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    fetchUser(userId).then(setUser);
+  }, []); // Missing userId dependency
+}
+```
+
+**Good**:
+```typescript
+interface ComponentProps {
+  userId: string;
+}
+
+function Component({ userId }: ComponentProps) {
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    fetchUser(userId).then(setUser);
+  }, [userId]); // Complete dependency array
+}
+```
+
+### Anti-pattern 3: Creating Objects in Render
+
+**Bad**:
+```typescript
+interface ParentProps {
+  items: Item[];
+}
+
+const MemoizedChild = React.memo(ChildComponent);
+
+function Parent({ items }: ParentProps) {
+  return (
+    <MemoizedChild
+      config={{ columns: items[0]?.columns || [] }} // New object every render
+    />
+  );
+}
+```
+
+**Good**:
+```typescript
+interface ParentProps {
+  items: Item[];
+}
+
+const MemoizedChild = React.memo(ChildComponent);
+
+function Parent({ items }: ParentProps) {
+  // Memoize config object
+  const config = useMemo(() => ({
+    columns: items[0]?.columns || [],
+  }), [items]);
+
+  return <MemoizedChild config={config} />;
+}
+```
+
+### Anti-pattern 4: Prop Drilling
+
+**Bad**:
+```typescript
+interface HeaderProps {
+  user: User | null;
+}
+
+interface NavProps {
+  user: User | null;
+}
+
+function App() {
+  const [user, setUser] = useState(null);
+  return <Header user={user} />;
+}
+
+function Header({ user }: HeaderProps) {
+  return <Nav user={user} />;
+}
+
+function Nav({ user }: NavProps) {
+  return <UserMenu user={user} />;
+}
+```
+
+**Good**:
+```typescript
+// Use context or state management
+const UserContext = createContext<User | null>(null);
+
+function App() {
+  const [user, setUser] = useState(null);
+  return (
+    <UserContext.Provider value={user}>
+      <Header />
+    </UserContext.Provider>
+  );
+}
+
+function Header() {
+  return <Nav />;
+}
+
+function Nav() {
+  return <UserMenu />;
+}
+
+function UserMenu() {
+  const user = useContext(UserContext);
+  // Use user
+}
+```
+
+## Best Practices Summary
+
+### Component Design
+
+1. **Single Responsibility**: Each component should have one clear purpose
+2. **Composition over Configuration**: Prefer composition over complex props
+3. **Controlled Components**: Use controlled components for forms
+4. **Accessibility**: Always include ARIA attributes when needed
+
+### Performance
+
+1. **Measure First**: Use React DevTools Profiler before optimizing
+2. **Memoize Wisely**: Only memoize expensive computations or for reference equality
+3. **Code Split**: Use dynamic imports for route-based splitting
+4. **Avoid Premature Optimization**: Optimize only when there's a measurable problem
+
+### State Management
+
+1. **Colocate State**: Keep state close to where it's used
+2. **Lift State Up**: Share state by lifting to common ancestor
+3. **Use Redux for Global State**: Use Redux for state shared across many components
+4. **Normalize State**: Normalize nested state structures
+
+### Type Safety
+
+1. **Avoid `any`**: Use specific types or `unknown`
+2. **Explicit Return Types**: Always define function return types
+3. **Type Guards**: Use type guards for runtime type checking
+4. **Discriminated Unions**: Use for type-safe variant handling
+
+## References
+
+- [Type Safety Guidelines](./type-safety.md)
+- [Code Organization Guidelines](./code-organization.md)
+- [Performance Optimization](./performance-optimization.md)
+- [State Management Guidelines](./state-management.md)
+- [Styling Guidelines](./styling-guidelines.md)
+- Project Coding Standards: `desktop-team-documentation/instructions/coding-conventions/frontend.md`