Feature/combined updates

ai_docs/concepts/concept-points-counter.md

@@ -0,0 +1,120 @@
+# Points Counter Component System
+
+<!--
+Last Updated: 2024-04-01
+Updated By: AI Assistant
+Changes Made:
+- Initial documentation for PointsCounter component system
+Reason for Changes:
+Documentation needed to explain the component structure and key features of the points counter system.
+-->
+
+## Overview
+
+The Points Counter is a composite component system that handles point management for students. It consists of three main components that work together to provide a rich user experience for point manipulation and display.
+
+## Components
+
+### 1. PointsCounter (Container)
+- Main container component that orchestrates the point management system
+- Manages state and business logic
+- Handles animations and sound effects
+- Coordinates between child components
+- Key features:
+  - Debounced click handling to prevent double-clicks
+  - Sound effect coordination
+  - Animation triggering
+  - Recent change tracking
+
+### 2. PointsButton
+- Reusable button component for increment/decrement actions
+- Props:
+  - `onClick`: Handler for button clicks
+  - `symbol`: "+" or "-" to indicate action
+  - `disabled`: Optional state to prevent clicks
+- Features:
+  - Hover effects
+  - Disabled state styling
+  - Prevents text selection
+  - Handles pointer events appropriately
+
+### 3. PointsDisplay
+- Manages the display of points and recent changes
+- Props:
+  - `points`: Current point value
+  - `recentChange`: Optional value to show recent changes
+  - `onChange`: Handler for direct point input
+  - `animationTrigger`: Value to trigger animations
+- Features:
+  - Dynamic color based on point value
+  - Recent change overlay
+  - Pop animation on value changes
+  - Negative value highlighting
+
+## Key Features
+
+### Animation System
+- Uses CSS keyframes for pop animation
+- Triggers on point changes
+- Supports delayed animations for batch updates
+- Smooth transitions for visual feedback
+
+### Sound Effects
+- Plays different sounds for:
+  - Single point changes
+  - Batch point changes
+- Coordinated with animations
+
+### Input Handling
+- Supports both button clicks and direct number input
+- Debounced click handling prevents accidental double-clicks
+- Visual feedback for disabled state
+
+### Visual Feedback
+- Dynamic color gradient based on point value
+- Recent change overlay with +/- indicators
+- Hover effects on buttons
+- Clear disabled states
+
+## Technical Notes
+
+### State Management
+- Uses React's useState for local state
+- Leverages useCallback for memoized handlers
+- Implements useDebounce for click handling
+- Uses usePrevious hook for change detection
+
+### Performance Considerations
+- Memoized color calculations
+- Debounced handlers to prevent rapid-fire events
+- Efficient animation triggering
+- Optimized re-renders through proper prop passing
+
+### Accessibility
+- Clear visual feedback for interactions
+- Proper disabled states
+- Non-selectable text
+- Appropriate cursor states
+
+## Related Components
+- StudentCard
+- NumberInput
+- SoundContext
+- StudentContext
+
+## Usage Example
+
+```tsx
+<PointsCounter
+  student={student}
+  index={studentIndex}
+  className="custom-class"
+/>
+```
+
+## Future Considerations
+- Custom animation timing options
+- Configurable sound effects
+- Custom color gradient ranges
+- Additional input validation
+- Keyboard shortcut support 

ai_notes/README.md

@@ -0,0 +1,62 @@
+# AI Documentation
+
+This directory serves as an AI-optimized knowledge base for the Student Points Tracker project. It's designed to help AI agents understand and work with the codebase more effectively while remaining human-readable.
+
+## Structure
+
+- `/concepts` - Core concepts and domain knowledge
+- `/architecture` - System architecture and technical decisions
+- `/decisions` - Project decisions and their rationale
+
+## Purpose
+
+This directory acts as an encyclopedia for the project, containing:
+- Important concepts and their relationships
+- Architectural decisions and patterns
+- Project-specific terminology
+- AI agent notes and observations
+- Reference points for different parts of the application
+
+## Usage
+
+### For AI Agents
+- Use this directory as the primary source of project knowledge
+- Reference relevant files when making changes or suggestions
+- Add notes when discovering useful patterns or concepts
+- Update existing documentation when making significant changes
+
+### For Humans
+- Use as a reference for understanding the project
+- Maintain documentation when making architectural changes
+- Add context to complex decisions
+- Track project evolution
+
+## Maintenance
+
+1. Keep documentation up to date with code changes
+2. Add new concepts as they emerge
+3. Document architectural decisions when made
+4. Include examples where helpful
+5. Cross-reference related concepts
+6. Add timestamps to significant updates
+
+## File Naming Convention
+
+- Use kebab-case for filenames
+- Include category prefix (e.g., `concept-`, `arch-`, `decision-`)
+- Add date suffix for versioned documents (e.g., `-2024-04-01`)
+
+## Example Structure
+
+```
+ai_docs/
+├── concepts/
+│   ├── concept-points-system.md
+│   └── concept-student-roles.md
+├── architecture/
+│   ├── arch-data-flow.md
+│   └── arch-state-management.md
+└── decisions/
+    ├── decision-vite-migration.md
+    └── decision-testing-framework.md
+``` 

src/components/StudentCard/PointsCounter/PointsButton.tsx

@@ -0,0 +1,29 @@
+import { useCallback } from "react";
+import { cnsMerge } from "../../../utils/cnsMerge";
+
+interface PointsButtonProps {
+  symbol: "+" | "-";
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+export const PointsButton = ({ symbol, onClick, disabled = false }: PointsButtonProps) => {
+  const handleClick = useCallback(() => {
+    if (!disabled) {
+      onClick();
+    }
+  }, [onClick, disabled]);
+
+  return (
+    <div
+      className={cnsMerge(
+        "flex-1 flex items-center justify-center cursor-pointer select-none p-1",
+        "text-gray-400 hover:text-gray-600 hover:bg-gray-100",
+        disabled && "opacity-50 cursor-not-allowed"
+      )}
+      onClick={handleClick}
+    >
+      <span className="text-lg font-bold">{symbol}</span>
+    </div>
+  );
+};