CLAUDE.md

1# GenSlides Frontend - Development Guidelines
2 
3IMPORTANT: always use latest dependencies. follow design tokens and global.css in ./src/styles/design-tokens.css and ./src/styles/global.css
4 
5## Tech Stack
6 
7- **Language**: TypeScript
8- **Framework**: React 19+
9- **Build Tool**: Vite
10- **Styling**: Tailwind CSS
11- **State Management**: Zustand
12- **Drag & Drop**: @dnd-kit
13 
14## Architecture Principles
15 
16### SOLID Principles (Adapted for React)
17 
18- **S - Single Responsibility**: One component, one purpose
19  - `SlideList.tsx` - Renders list only, delegates item rendering to `SlideItem`
20  - `useSlides.ts` - Data fetching only, no UI logic
21  - `slideStore.ts` - State management only, no API calls
22 
23- **O - Open/Closed**: Components open for extension via props
24 
25```tsx
26  // Good: extensible via props
27  <Button variant="primary" size="lg" onClick={handleClick} />
28 
29  // Avoid: modifying component internals for each use case
30```
31 
32- **L - Liskov Substitution**: Components with same interface are interchangeable
33 
34```tsx
35  // Both can be used wherever a clickable element is expected
36  <Button onClick={...}>Click</Button>
37  <IconButton onClick={...} icon={<PlayIcon />} />
38```
39 
40- **I - Interface Segregation**: Small, focused prop interfaces
41 
42```tsx
43  // Good: focused interface
44  interface SlideItemProps {
45    slide: Slide;
46    isSelected: boolean;
47    onSelect: (sid: string) => void;
48  }
49 
50  // Avoid: bloated interface with optional props
51```
52 
53- **D - Dependency Inversion**: Components depend on abstractions
54 
55```tsx
56  // Good: component receives data via props/hooks
57  function SlideList({ slides, onSelect }: Props) { ... }
58 
59  // Avoid: component directly imports global state
60```
61 
62### YAGNI (You Aren't Gonna Need It)
63 
64- Don't add props "just in case"
65- Start with inline styles, extract to components when reused
66- Avoid premature optimization (memo, useMemo, useCallback)
67 
68### KISS (Keep It Simple, Stupid)
69 
70- Prefer composition over configuration
71- Use native HTML elements when possible
72- Minimize state - derive values when possible
73 
74### DRY (Don't Repeat Yourself)
75 
76- Avoid duplicating code
77- Use functions, classes, and modules to DRY code
78- Use patterns and templates to DRY code
79 
80## Code Organization
81 
82```
83src/
84├── main.tsx           # App entry point
85├── App.tsx            # Root component, routing setup
86├── api/               # API layer - HTTP requests only
87│   ├── index.ts       # Axios/fetch instance, interceptors
88│   ├── slides.ts      # Slides API functions
89│   ├── images.ts      # Images API functions
90│   └── style.ts       # Style API functions
91├── stores/            # Zustand stores - global state only
92│   ├── index.ts       # Store exports
93│   ├── slideStore.ts  # Slides & project state
94│   └── playerStore.ts # Playback state
95├── components/        # UI components
96│   ├── layout/        # Layout components (Header, Sidebar, etc.)
97│   ├── slides/        # Slide-related components
98│   ├── preview/       # Image preview components
99│   ├── player/        # Fullscreen player
100│   ├── style/         # Style picker modal
101│   └── common/        # Reusable UI primitives
102├── hooks/             # Custom React hooks
103├── types/             # TypeScript type definitions
104└── styles/            # Global styles
105```
106 
107### Component Structure
108 
109```tsx
110// components/slides/SlideItem.tsx
111 
112// 1. Imports (React, libraries, local)
113import { useState, useCallback } from 'react';
114import { useSortable } from '@dnd-kit/sortable';
115import { CSS } from '@dnd-kit/utilities';
116import type { Slide } from '@/types';
117 
118// 2. Types
119interface SlideItemProps {
120  slide: Slide;
121  isSelected: boolean;
122  onSelect: (sid: string) => void;
123  onEdit: (sid: string, content: string) => void;
124}
125 
126// 3. Component
127export function SlideItem({ slide, isSelected, onSelect, onEdit }: SlideItemProps) {
128  // 3a. Hooks
129  const [isEditing, setIsEditing] = useState(false);
130  const { attributes, listeners, setNodeRef, transform, transition } = useSortable({
131    id: slide.sid,
132  });
133 
134  // 3b. Derived state
135  const style = {
136    transform: CSS.Transform.toString(transform),
137    transition,
138  };
139 
140  // 3c. Handlers
141  const handleDoubleClick = useCallback(() => {
142    setIsEditing(true);
143  }, []);
144 
145  // 3d. Render
146  return (
147    <div
148      ref={setNodeRef}
149      style={style}
150      {...attributes}
151      {...listeners}
152      onClick={() => onSelect(slide.sid)}
153      onDoubleClick={handleDoubleClick}
154      className={`p-4 rounded-lg ${isSelected ? 'ring-2 ring-blue-500' : ''}`}
155    >
156      {isEditing ? (
157        <SlideEditor ... />
158      ) : (
159        <p>{slide.content}</p>
160      )}
161    </div>
162  );
163}
164```
165 
166## State Management (Zustand)
167 
168### Store Structure
169 
170```typescript
171// stores/slideStore.ts
172import { create } from 'zustand';
173import { slidesApi } from '@/api/slides';
174import type { Slide, Style, ProjectResponse } from '@/types';
175 
176interface SlideState {
177  // Data
178  slug: string | null;
179  title: string;
180  style: Style | null;
181  slides: Slide[];
182  selectedSlideId: string | null;
183 
184  // Loading states
185  isLoading: boolean;
186  isGenerating: boolean;
187  error: string | null;
188 
189  // Actions
190  loadProject: (slug: string) => Promise<void>;
191  selectSlide: (sid: string) => void;
192  createSlide: (content: string, position?: number) => Promise<void>;
193  updateSlide: (sid: string, content: string) => Promise<void>;
194  deleteSlide: (sid: string) => Promise<void>;
195  reorderSlides: (slideIds: string[]) => Promise<void>;
196  clearError: () => void;
197}
198 
199export const useSlideStore = create<SlideState>((set, get) => ({
200  // Initial state
201  slug: null,
202  title: '',
203  style: null,
204  slides: [],
205  selectedSlideId: null,
206  isLoading: false,
207  isGenerating: false,
208  error: null,
209 
210  // Actions
211  loadProject: async (slug) => {
212    set({ isLoading: true, error: null });
213    try {
214      const data = await slidesApi.getProject(slug);
215      set({
216        slug,
217        title: data.title,
218        style: data.style,
219        slides: data.slides,
220        selectedSlideId: data.slides[0]?.sid ?? null,
221        isLoading: false,
222      });
223    } catch (e) {
224      set({ error: (e as Error).message, isLoading: false });
225    }
226  },
227 
228  selectSlide: (sid) => set({ selectedSlideId: sid }),
229 
230  // ... other actions
231}));
232```
233 
234### Store Best Practices
235 
236```typescript
237// DO: Keep stores focused
238const useSlideStore = create<SlideState>(...);  // Slide data
239const usePlayerStore = create<PlayerState>(...);  // Playback state
240 
241// DON'T: Create god stores with everything
242const useAppStore = create<EverythingState>(...);
243 
244// DO: Use selectors for derived state
245const selectedSlide = useSlideStore(
246  (state) => state.slides.find(s => s.sid === state.selectedSlideId)
247);
248 
249// DON'T: Store derived state
250const useSlideStore = create((set) => ({
251  slides: [],
252  selectedSlideId: null,
253  selectedSlide: null,  // This is derived, don't store it!
254}));
255```
256 
257## Concurrency & Async
258 
259### API Request Patterns
260 
261```typescript
262// api/index.ts
263const BASE_URL = '/api';
264 
265export async function request<T>(
266  endpoint: string,
267  options: RequestInit = {}
268): Promise<T> {
269  const response = await fetch(`${BASE_URL}${endpoint}`, {
270    headers: {
271      'Content-Type': 'application/json',
272      ...options.headers,
273    },
274    ...options,
275  });
276 
277  if (!response.ok) {
278    const error = await response.json().catch(() => ({}));
279    throw new Error(error.detail || `Request failed: ${response.status}`);
280  }
281 
282  return response.json();
283}
284 
285// api/slides.ts
286export const slidesApi = {
287  getProject: (slug: string) =>
288    request<ProjectResponse>(`/slides/${slug}`),
289 
290  createSlide: (slug: string, data: CreateSlideRequest) =>
291    request<SlideResponse>(`/slides/${slug}`, {
292      method: 'POST',
293      body: JSON.stringify(data),
294    }),
295};
296```
297 
298### Loading States
299 
300```tsx
301function SlideList() {
302  const { slides, isLoading, error } = useSlideStore();
303 
304  if (isLoading) {
305    return <LoadingSpinner />;
306  }
307 
308  if (error) {
309    return <ErrorMessage message={error} />;
310  }
311 
312  if (slides.length === 0) {
313    return <EmptyState message="No slides yet" />;
314  }
315 
316  return (
317    <div>
318      {slides.map(slide => <SlideItem key={slide.sid} slide={slide} />)}
319    </div>
320  );
321}
322```
323 
324### Optimistic Updates
325 
326```typescript
327// For better UX, update UI before server confirms
328reorderSlides: async (slideIds) => {
329  const prevSlides = get().slides;
330 
331  // Optimistic update
332  const reorderedSlides = slideIds.map(
333    id => prevSlides.find(s => s.sid === id)!
334  );
335  set({ slides: reorderedSlides });
336 
337  try {
338    await slidesApi.reorderSlides(get().slug!, slideIds);
339  } catch (e) {
340    // Rollback on error
341    set({ slides: prevSlides, error: (e as Error).message });
342  }
343},
344```
345 
346### Debouncing
347 
348```typescript
349// hooks/useDebounce.ts
350import { useState, useEffect } from 'react';
351 
352export function useDebounce<T>(value: T, delay: number): T {
353  const [debouncedValue, setDebouncedValue] = useState(value);
354 
355  useEffect(() => {
356    const timer = setTimeout(() => setDebouncedValue(value), delay);
357    return () => clearTimeout(timer);
358  }, [value, delay]);
359 
360  return debouncedValue;
361}
362 
363// Usage in SlideEditor
364function SlideEditor({ slide, onSave }: Props) {
365  const [content, setContent] = useState(slide.content);
366  const debouncedContent = useDebounce(content, 500);
367 
368  useEffect(() => {
369    if (debouncedContent !== slide.content) {
370      onSave(slide.sid, debouncedContent);
371    }
372  }, [debouncedContent, slide.sid, slide.content, onSave]);
373 
374  return <textarea value={content} onChange={e => setContent(e.target.value)} />;
375}
376```
377 
378## Error Handling
379 
380### Error Boundary
381 
382```tsx
383// components/common/ErrorBoundary.tsx
384import { Component, ReactNode } from 'react';
385 
386interface Props {
387  children: ReactNode;
388  fallback?: ReactNode;
389}
390 
391interface State {
392  hasError: boolean;
393  error: Error | null;
394}
395 
396export class ErrorBoundary extends Component<Props, State> {
397  state: State = { hasError: false, error: null };
398 
399  static getDerivedStateFromError(error: Error): State {
400    return { hasError: true, error };
401  }
402 
403  componentDidCatch(error: Error, info: React.ErrorInfo) {
404    console.error('ErrorBoundary caught:', error, info);
405  }
406 
407  render() {
408    if (this.state.hasError) {
409      return this.props.fallback ?? (
410        <div className="p-4 text-red-500">
411          Something went wrong: {this.state.error?.message}
412        </div>
413      );
414    }
415    return this.props.children;
416  }
417}
418```
419 
420### API Error Handling
421 
422```typescript
423// types/index.ts
424export interface ApiError {
425  detail: string;
426  error_code?: string;
427}
428 
429// api/index.ts
430export class ApiRequestError extends Error {
431  constructor(
432    message: string,
433    public statusCode: number,
434    public errorCode?: string
435  ) {
436    super(message);
437    this.name = 'ApiRequestError';
438  }
439}
440 
441// Handle in components
442async function handleGenerateImage() {
443  try {
444    await generateImage(selectedSlideId);
445  } catch (e) {
446    if (e instanceof ApiRequestError) {
447      if (e.statusCode === 502) {
448        toast.error('Image generation failed. Please try again.');
449      } else if (e.statusCode === 429) {
450        toast.error('Rate limited. Please wait a moment.');
451      }
452    } else {
453      toast.error('An unexpected error occurred.');
454    }
455  }
456}
457```
458 
459### Form Validation
460 
461```tsx
462function StylePickerForm({ onSubmit }: Props) {
463  const [prompt, setPrompt] = useState('');
464  const [error, setError] = useState<string | null>(null);
465 
466  const handleSubmit = (e: React.FormEvent) => {
467    e.preventDefault();
468    setError(null);
469 
470    if (!prompt.trim()) {
471      setError('Please enter a style description');
472      return;
473    }
474 
475    if (prompt.length < 5) {
476      setError('Description must be at least 5 characters');
477      return;
478    }
479 
480    onSubmit(prompt);
481  };
482 
483  return (
484    <form onSubmit={handleSubmit}>
485      <input
486        value={prompt}
487        onChange={e => setPrompt(e.target.value)}
488        className={error ? 'border-red-500' : ''}
489      />
490      {error && <p className="text-red-500 text-sm">{error}</p>}
491      <button type="submit">Generate</button>
492    </form>
493  );
494}
495```
496 
497## Logging & Debugging
498 
499### Console Logging (Development Only)
500 
501```typescript
502// utils/logger.ts
503const isDev = import.meta.env.DEV;
504 
505export const logger = {
506  debug: (...args: unknown[]) => {
507    if (isDev) console.debug('[DEBUG]', ...args);
508  },
509  info: (...args: unknown[]) => {
510    if (isDev) console.info('[INFO]', ...args);
511  },
512  warn: (...args: unknown[]) => {
513    console.warn('[WARN]', ...args);
514  },
515  error: (...args: unknown[]) => {
516    console.error('[ERROR]', ...args);
517  },
518};
519 
520// Usage
521logger.debug('Slide selected:', sid);
522logger.info('Project loaded:', { slug, slideCount: slides.length });
523logger.error('API request failed:', error);
524```
525 
526### React DevTools Integration
527 
528```typescript
529// stores/slideStore.ts
530import { devtools } from 'zustand/middleware';
531 
532export const useSlideStore = create<SlideState>()(
533  devtools(
534    (set, get) => ({
535      // ... store implementation
536    }),
537    { name: 'SlideStore' }  // Shows in Redux DevTools
538  )
539);
540```
541 
542## Testing
543 
544### Test Structure
545 
546```
547src/
548├── __tests__/
549│   ├── components/
550│   │   └── SlideItem.test.tsx
551│   ├── stores/
552│   │   └── slideStore.test.ts
553│   └── hooks/
554│       └── useKeyboard.test.ts
555```
556 
557### Component Testing
558 
559```tsx
560// __tests__/components/SlideItem.test.tsx
561import { render, screen, fireEvent } from '@testing-library/react';
562import { SlideItem } from '@/components/slides/SlideItem';
563 
564describe('SlideItem', () => {
565  const mockSlide = {
566    sid: 'slide_001',
567    content: 'Test slide content',
568    content_hash: 'abc123',
569    created_at: '2024-01-01T00:00:00Z',
570    updated_at: '2024-01-01T00:00:00Z',
571  };
572 
573  it('renders slide content', () => {
574    render(
575      <SlideItem
576        slide={mockSlide}
577        isSelected={false}
578        onSelect={vi.fn()}
579        onEdit={vi.fn()}
580      />
581    );
582    expect(screen.getByText('Test slide content')).toBeInTheDocument();
583  });
584 
585  it('calls onSelect when clicked', () => {
586    const onSelect = vi.fn();
587    render(
588      <SlideItem
589        slide={mockSlide}
590        isSelected={false}
591        onSelect={onSelect}
592        onEdit={vi.fn()}
593      />
594    );
595    fireEvent.click(screen.getByText('Test slide content'));
596    expect(onSelect).toHaveBeenCalledWith('slide_001');
597  });
598});
599```
600 
601### Running Tests
602 
603```bash
604# Run all tests
605npm test
606 
607# Run in watch mode
608npm test -- --watch
609 
610# Run with coverage
611npm test -- --coverage
612```
613 
614## Code Style
615 
616### TypeScript Strict Mode
617 
618```json
619// tsconfig.json
620{
621  "compilerOptions": {
622    "strict": true,
623    "noUncheckedIndexedAccess": true,
624    "noImplicitReturns": true
625  }
626}
627```
628 
629### Naming Conventions
630 
631| Type             | Convention                    | Example                   |
632|------------------|-------------------------------|---------------------------|
633| Components       | PascalCase                    | `SlideItem.tsx`           |
634| Hooks            | camelCase with `use` prefix   | `useSlides.ts`            |
635| Stores           | camelCase with `Store` suffix | `slideStore.ts`           |
636| Types/Interfaces | PascalCase                    | `Slide`, `SlideItemProps` |
637| Constants        | SCREAMING_SNAKE_CASE          | `API_BASE_URL`            |
638| CSS Classes      | kebab-case (Tailwind)         | `bg-blue-500`             |
639 
640### Import Order
641 
642```tsx
643// 1. React
644import { useState, useEffect } from 'react';
645 
646// 2. Third-party libraries
647import { useSortable } from '@dnd-kit/sortable';
648 
649// 3. Internal modules (absolute imports)
650import { useSlideStore } from '@/stores';
651import type { Slide } from '@/types';
652 
653// 4. Relative imports
654import { SlideEditor } from './SlideEditor';
655 
656// 5. Styles
657import './SlideItem.css';
658```
659 
660### Tailwind Best Practices
661 
662```tsx
663// DO: Use Tailwind utilities directly
664<button className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
665  Click me
666</button>
667 
668// DO: Extract repeated patterns to components
669function Button({ children, variant = 'primary' }: ButtonProps) {
670  const variants = {
671    primary: 'bg-blue-500 text-white hover:bg-blue-600',
672    secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
673  };
674  return (
675    <button className={`px-4 py-2 rounded ${variants[variant]}`}>
676      {children}
677    </button>
678  );
679}
680 
681// AVOID: Using @apply excessively in CSS
682```
683