diff --git a/.github/prompts/audit-docs.md b/.github/prompts/audit-docs.md index e956219..26a5a11 100644 --- a/.github/prompts/audit-docs.md +++ b/.github/prompts/audit-docs.md @@ -11,7 +11,7 @@ labels: --- **Purpose:** -While reviewing this #activePullRequest, analyze the entire #codebase and ensure the #file:docs directory is accurate, up to date, and fully aligned with the current implementation. +While reviewing this #activePullRequest #changes, analyze the entire #codebase and ensure the #file:docs directory is accurate, up to date, and fully aligned with the current implementation. --- @@ -35,6 +35,19 @@ While reviewing this #activePullRequest, analyze the entire #codebase and ensure --- +--- + +## Execution Order (IMPORTANT) + +1. **Audit `docs/` first** +2. **Only if `docs/` is already accurate**, then: + - Audit markdown files elsewhere in the repository (root or subdirectories) + - Audit in-code documentation/comments where clarity or accuracy is lacking + +Do **not** skip ahead. + +--- + ## What to Do ### 1. Audit the `docs/` directory diff --git a/docs/architecture/components/avatar.md b/docs/architecture/components/avatar.md new file mode 100644 index 0000000..a3d2b05 --- /dev/null +++ b/docs/architecture/components/avatar.md @@ -0,0 +1,205 @@ +# Banner & Avatar Components + +This document details the Banner and Avatar components that create the introductory section of the portfolio. + +## Overview + +The Banner component displays the header section with profile information and an animated avatar that includes an Easter egg feature. + +## Component Structure + +```mermaid +flowchart TD + Banner[Banner Component] -->|Contains| Avatar[Avatar Component] + Banner -->|Displays| Title[Title & Subtitle] + Avatar -->|Hover| Sneeze[Sneeze Animation] + Avatar -->|6x Sneeze| AAAAHHHH[Easter Egg Trigger] + AAAAHHHH -->|Calls| Helper[aaaahhhh helper] + Helper -->|Transforms| Page[Entire Page] +``` + +## Banner Component + +Location: [`src/components/banner/Banner.tsx`](../../src/components/banner/Banner.tsx) + +**Purpose:** Displays the introductory section with profile image and text. + +**Key Features:** + +- Responsive layout using MUI Grid/Stack +- Profile avatar with animations +- Title and subtitle text +- Accessibility attributes + +**Usage Example:** + +```tsx +import Banner from '@components/banner/Banner'; + +; +``` + +## Avatar Component + +Location: [`src/components/banner/Avatar.tsx`](../../src/components/banner/Avatar.tsx) + +**Purpose:** Displays an animated profile picture with an interactive sneeze animation and Easter egg. + +### Key Features + +1. **Sneeze Animation:** Triggered every 5 hovers +2. **Easter Egg:** After 6 sneezes, triggers the "AAAAHHHH" transformation +3. **Analytics Tracking:** Logs user interactions +4. **Image Optimization:** Uses Next.js Image component + +### State Management + +```typescript +const hoverProfilePic = useRef(0); // Hover count +const totalSneeze = useRef(0); // Total sneezes +const sneezing = useRef(false); // Animation lock +const [image, setImage] = useState(imageList['default']); // Current image +``` + +### Image Assets + +```typescript +const imageList = { + default: '/images/drawn/profile_pic_drawn.webp', + sneeze_1: '/images/drawn/profile_pic_drawn_2.webp', + sneeze_2: '/images/drawn/profile_pic_drawn_3.webp', + sneeze_3: '/images/drawn/profile_pic_drawn_4.webp', +}; +``` + +### Sneeze Animation Sequence + +```typescript +handleTriggerSneeze() { + hoverProfilePic.current += 1; + + if (hoverProfilePic.current % 5 === 0 && !sneezing.current) { + totalSneeze.current += 1; + + if (totalSneeze.current >= 6) { + logAnalyticsEvent('trigger_aaaahhhh', {...}); + aaaahhhh(); // Transform entire page + } else { + sneezing.current = true; + + // Animate through sneeze sequence + setImage('sneeze_1'); + setTimeout(() => setImage('sneeze_2'), 500); + setTimeout(() => setImage('sneeze_3'), 800); + setTimeout(() => { + setImage('default'); + sneezing.current = false; + }, 1800); + + logAnalyticsEvent('trigger_sneeze', {...}); + } + } +} +``` + +### AAAAHHHH Easter Egg + +When the avatar sneezes 6 times, it triggers [`aaaahhhh()`](../../src/helpers/aaaahhhh.ts) which: + +1. Converts all text to "AAAAHHHH" format +2. Replaces all images with the AAAAHHHH image +3. Changes background images +4. Creates a playful page transformation + +See [AAAAHHHH Helper Documentation](../helpers.md#aaaahhhh-helper) for details. + +### Analytics Integration + +The component logs two event types: + +```typescript +// Sneeze event +logAnalyticsEvent('trigger_sneeze', { + name: 'trigger_sneeze', + type: 'hover', +}); + +// Easter egg event +logAnalyticsEvent('trigger_aaaahhhh', { + name: 'trigger_aaaahhhh', + type: 'hover', +}); +``` + +### Usage Example + +```tsx +import Avatar from '@components/banner/Avatar'; + +; // No props required +``` + +### Performance Considerations + +- **Debounced Hover:** Uses `lodash.debounce` to prevent rapid triggering +- **Ref-based State:** Uses refs for counters to avoid unnecessary re-renders +- **Animation Lock:** Prevents overlapping sneeze animations +- **Image Preloading:** All sneeze images should be optimized as WebP + +### Accessibility + +```tsx + + Alexander Sullivan profile picture + +``` + +## Component Interaction + +```mermaid +sequenceDiagram + participant User + participant Avatar + participant State + participant Helper + participant Analytics + + User->>Avatar: Hover (5th time) + Avatar->>State: Increment counter + State->>Avatar: Trigger sneeze + Avatar->>Avatar: Animate sneeze sequence + Avatar->>Analytics: Log sneeze event + + User->>Avatar: Hover (6th sneeze) + Avatar->>Helper: Call aaaahhhh() + Helper->>Helper: Transform page + Avatar->>Analytics: Log AAAAHHHH event +``` + +## Testing + +Test file: [`src/components/banner/Avatar.test.tsx`](../../src/components/banner/Avatar.test.tsx) + +**Test Coverage:** + +- Component renders +- Image changes on hover +- Sneeze animation triggers +- Easter egg activation +- Analytics event logging + +## Related Documentation + +- [Helpers: AAAAHHHH](./helpers.md#aaaahhhh-helper) +- [Components Overview](./components/index.md) +- [Firebase Analytics](./configs.md#firebase-configuration-and-usage) + +--- + +💡 **Tip:** Try hovering over the profile picture to discover the sneeze animation and Easter egg! diff --git a/docs/architecture/components/index.md b/docs/architecture/components/index.md index 31cd84a..1757c2d 100644 --- a/docs/architecture/components/index.md +++ b/docs/architecture/components/index.md @@ -2,54 +2,252 @@ This document describes the internal architecture, relationships, and usage of major UI components in the AlexJSully Portfolio project. Components are modular, reusable, and styled with Material-UI and Emotion. -## 📦 Component List & Hierarchy +## Component List & Hierarchy -- [ProjectsGrid](./projects.md): Displays a grid of projects. -- [Publications](./publications.md): Lists publications. -- [Footer](./socials.md): Shows social media links. -- [Navbar](../architecture/index.md): Navigation bar (see architecture for layout details). -- [Banner, CookieSnackbar, StarsBackground]: Utility and visual components. +### Core Components + +- [Navbar](./navbar.md): Top navigation bar with smooth scrolling +- [Banner & Avatar](./avatar.md): Header section with animated profile picture +- [ProjectsGrid](./projects.md): Displays project cards in a grid +- [Publications](./publications.md): Lists publications with metadata +- [Footer](./socials.md): Social media links and copyright +- [StarsBackground](./stars.md): Animated starfield background +- [CookieSnackbar](./cookie-snackbar.md): Cookie consent notification +- [ServiceWorkerRegister](../service-worker.md): PWA service worker registration ### Component Hierarchy ```mermaid flowchart TD - App --> Navbar - App --> Banner - App --> ProjectsGrid - App --> Publications - App --> Footer - App --> CookieSnackbar - App --> StarsBackground + RootLayout[Root Layout] --> Navbar + RootLayout --> Main[Main Content] + RootLayout --> Footer + RootLayout --> ServiceWorkerRegister + + Main --> Banner + Main --> ProjectsGrid + Main --> Publications + Main --> StarsBackground + Main --> CookieSnackbar + + Banner --> Avatar + + ProjectsGrid --> ProjectCards[Project Cards] + Publications --> PublicationCards[Publication Cards] + Footer --> SocialLinks[Social Links] +``` + +## Component Details + +### Navbar + +**Location:** [`src/components/navbar/Navbar.tsx`](../../src/components/navbar/Navbar.tsx) + +Top navigation bar with smooth scrolling to page sections. + +**Features:** + +- Smooth scroll navigation +- Firebase Analytics tracking +- Responsive design +- Path-aware behavior + +**See:** [Navbar Documentation](./navbar.md) + +### Banner & Avatar + +**Location:** [`src/components/banner/Banner.tsx`](../../src/components/banner/Banner.tsx), [`Avatar.tsx`](../../src/components/banner/Avatar.tsx) + +Header section with animated profile picture featuring a sneeze animation and Easter egg. + +**Features:** + +- Interactive avatar with sneeze animation +- Easter egg trigger (6 sneezes activates AAAAHHHH transformation) +- Analytics tracking +- Image optimization + +**See:** [Banner & Avatar Documentation](./avatar.md) + +### ProjectsGrid + +**Location:** [`src/components/projects/ProjectsGrid.tsx`](../../src/components/projects/ProjectsGrid.tsx) + +Displays project cards in a responsive grid layout. + +**Features:** + +- Grid layout with MUI +- Project thumbnails and metadata +- External links with icons +- YouTube video embeds +- Analytics tracking +- Responsive design + +**See:** [Projects Documentation](./projects.md) + +### Publications + +**Location:** [`src/components/publications/Publications.tsx`](../../src/components/publications/Publications.tsx) + +Lists publications with authors, abstracts, and metadata. + +**Features:** + +- Publication cards with metadata +- DOI and journal links +- Related project linking +- Analytics tracking + +**See:** [Publications Documentation](./publications.md) + +### Footer + +**Location:** [`src/components/footer/Footer.tsx`](../../src/components/footer/Footer.tsx) + +Social media links and copyright information. + +**Features:** + +- Social media icon buttons +- Tooltips with platform names +- Responsive grid layout +- Analytics tracking + +**See:** [Socials Documentation](./socials.md) + +### StarsBackground + +**Location:** [`src/components/Stars/StarsBackground.tsx`](../../src/components/Stars/StarsBackground.tsx) + +Animated starfield background with twinkling stars. + +**Features:** + +- Dynamic star generation (50-100 stars) +- CSS animations for twinkling +- Fixed position background +- Performance optimized + +**See:** [Stars Documentation](./stars.md) + +### CookieSnackbar + +**Location:** [`src/components/cookie-snackbar/CookieSnackbar.tsx`](../../src/components/cookie-snackbar/CookieSnackbar.tsx) + +Cookie consent notification with localStorage persistence. + +**Features:** + +- Cookie consent management +- localStorage persistence +- MUI Snackbar integration +- Privacy compliance + +**See:** [Cookie Snackbar Documentation](./cookie-snackbar.md) + +### ServiceWorkerRegister + +**Location:** [`src/components/ServiceWorkerRegister.tsx`](../../src/components/ServiceWorkerRegister.tsx) + +Client component that registers the service worker for PWA functionality. + +**Features:** + +- Service worker registration +- Error handling +- Browser compatibility check + +**See:** [Service Worker Documentation](../service-worker.md) + +## Relationships & Composition + +Components are composed in the [`GeneralLayout`](../../src/layouts/GeneralLayout.tsx): + +```tsx +export default function GeneralLayout({ children }) { + return ( +
+ +
+ {children} + + +
+
+
+
+
+ ); +} ``` -## 🔍 Component Details +Data flow: + +```mermaid +sequenceDiagram + participant Page + participant Data + participant Component + participant Firebase -- **Navbar:** Top navigation bar, links to sections. Handles navigation, accessibility, and logs analytics via `logAnalyticsEvent`. -- **Banner:** Header section, may include avatar and intro. Displays profile and branding. -- **ProjectsGrid:** Displays project cards in a grid. Located at `src/components/projects/ProjectsGrid.tsx`. Handles filtering, analytics (uses `logAnalyticsEvent`), and responsive layout. -- **Publications:** Lists publications with metadata. Located at `src/components/publications/Publications.tsx`. Supports external links and logs analytics on interactions. -- **Footer:** Social media links and copyright. Located at `src/components/footer/Footer.tsx`. Includes contact and resume links and logs analytics. -- **CookieSnackbar:** Shows cookie consent. Manages cookie state and user interaction. -- **StarsBackground:** Visual background effect. Renders animated stars for visual appeal. + Page->>Data: Import projects, publications, socials + Data-->>Page: Static data arrays + Page->>Component: Pass data as props + Component->>Component: Render UI + Component->>Firebase: Log analytics events + Firebase-->>Component: Event logged +``` -## 🏗️ Relationships & Composition +## How Components Work -- Components are composed in page layouts (see `GeneralLayout.tsx`). -- Data is passed via props or imported from `src/data/`. -- Styling is handled via MUI and Emotion. -- Utility components (Banner, CookieSnackbar, StarsBackground) are used for branding and user experience. +**Component Organization:** -## 🧩 How Components Work +- Located in `src/components/` +- Grouped by feature (e.g., `banner/`, `projects/`) +- TypeScript with strong typing +- Path aliases for clean imports (`@components/`) -Components are located in `src/components/` and are imported using TypeScript path aliases (see `tsconfig.json`). -Each component is tested with Jest and/or Cypress for reliability. +**Data Integration:** -## 🔗 Related Docs +- Import from `src/data/` +- TypeScript interfaces for type safety +- Props for component composition -- [Architecture Overview](../architecture/index.md) -- [Usage Guides](../usage/index.md) +**Styling:** + +- Material-UI (MUI) components +- Emotion for CSS-in-JS +- Responsive design with MUI Grid/Stack +- Theme colors and typography + +**Testing:** + +- Jest for unit tests +- Cypress for E2E tests +- Test files colocated with components + +## Component Data Flow + +```mermaid +flowchart LR + Data[src/data/] -->|Import| Page[page.tsx] + Page -->|Props| ProjectsGrid + Page -->|Props| Publications + Page -->|Static| Footer + Page -->|Static| Navbar + Page -->|Static| Avatar + + Navbar -->|Events| Firebase[Firebase] + Avatar -->|Events| Firebase + ProjectsGrid -->|Events| Firebase + Publications -->|Events| Firebase + Footer -->|Events| Firebase +``` ---- +## Related Docs -💡 **Tip:** See each component's documentation for usage examples, diagrams, and integration details. +- [Architecture Overview](../index.md) +- [Data Architecture](../data.md) +- [GeneralLayout](../layouts.md) +- [Firebase Configuration](../configs.md) diff --git a/docs/architecture/components/navbar.md b/docs/architecture/components/navbar.md new file mode 100644 index 0000000..38af186 --- /dev/null +++ b/docs/architecture/components/navbar.md @@ -0,0 +1,260 @@ +# Navbar Component Documentation + +This document details the navigation bar component that provides site-wide navigation and smooth scrolling. + +## Overview + +The Navbar component is a fixed-position navigation bar located in [`src/components/navbar/Navbar.tsx`](../../src/components/navbar/Navbar.tsx). It provides navigation links with smooth scrolling behavior and analytics tracking. + +## Component Structure + +```mermaid +flowchart LR + Navbar[Navbar] -->|Contains| Home[Home Button] + Navbar -->|Contains| Projects[Projects Link] + Navbar -->|Contains| Pubs[Publications Link] + Navbar -->|Contains| Resume[Resume Link] + + Home -->|Scroll to| Top[Page Top] + Projects -->|Scroll to| ProjectsGrid[Projects Grid] + Pubs -->|Scroll to| PublicationsList[Publications] + Resume -->|Opens| PDF[Resume PDF] +``` + +## Key Features + +### 1. Smooth Scrolling Navigation + +The navbar uses smooth scrolling to navigate to page sections: + +```typescript +onClick={(e) => { + logAnalyticsEvent('navbar_projects', { + name: 'navbar_projects', + type: 'click', + }); + + if (pathname === '/') { + e.preventDefault(); + document.getElementById('projects-grid')?.scrollIntoView({ behavior: 'smooth' }); + } +}}; +``` + +### 2. Analytics Integration + +Each navigation action is logged using Firebase Analytics: + +```typescript +logAnalyticsEvent('navbar_home', { + name: 'navbar_home', + type: 'click', +}); +``` + +**Tracked Events:** + +- `navbar_home` - Home button click +- `navbar_projects` - Projects link click +- `navbar_publications` - Publications link click +- `navbar_resume` - Resume link click + +### 3. Responsive Design + +Built with Material-UI AppBar and Toolbar: + +```typescript + + + {/* Navigation items */} + + +``` + +### 4. Path-aware Behavior + +Uses Next.js `usePathname` hook to determine behavior: + +```typescript +const pathname = usePathname(); + +// On home page, prevent default and smooth scroll +// On other pages, navigate to home first +if (pathname === '/') { + e.preventDefault(); + document.getElementById('content')?.scrollIntoView({ behavior: 'smooth' }); +} +``` + +## Navigation Items + +### Home Button + +**Icon:** `HomeRoundedIcon` from MUI +**Target:** Page top (`#content`) +**Tooltip:** "Home" + +```tsx + + + + + + + +``` + +### Projects Link + +**Target:** `#projects-grid` section +**Text:** "Projects" + +### Publications Link + +**Target:** `#publications` section +**Text:** "Publications" + +### Resume Link + +**Target:** External PDF (`/resume/resume.pdf`) +**Behavior:** Opens in new tab + +```tsx + { + logAnalyticsEvent('navbar_resume', { + name: 'navbar_resume', + type: 'click', + }); + }} + rel='noopener noreferrer' + target='_blank' +> + Resume + +``` + +## Interaction Flow + +```mermaid +sequenceDiagram + participant User + participant Navbar + participant Router + participant Analytics + participant DOM + + User->>Navbar: Click Projects + Navbar->>Analytics: Log event + Navbar->>Router: Check pathname + + alt On Home Page + Navbar->>DOM: getElementById('projects-grid') + DOM->>DOM: scrollIntoView({behavior: 'smooth'}) + else On Other Page + Navbar->>Router: Navigate to /#projects-grid + Router->>DOM: Scroll to section + end +``` + +## Accessibility Features + +1. **ARIA Labels:** All links have descriptive `aria-label` attributes +2. **Tooltips:** Visual feedback for icon buttons +3. **Keyboard Navigation:** Fully keyboard accessible +4. **Focus Management:** Proper focus indicators +5. **Semantic HTML:** Uses proper `` and `` components + +## Styling + +**Colors:** + +- Background: `#131518` (dark gray) +- Text: Inherited from theme +- Hover: MUI default hover state + +**Transitions:** + +- All transitions: `0.5s ease-in-out` +- Height: `2rem` +- z-index: `10` (ensures navbar stays on top) + +## Testing + +Test file: [`src/components/navbar/Navbar.test.tsx`](../../src/components/navbar/Navbar.test.tsx) + +**Test Coverage:** + +- Component renders +- Navigation links present +- Click handlers fire +- Analytics events logged +- Smooth scroll behavior +- External links open correctly + +## Usage Example + +```tsx +import Navbar from '@components/navbar/Navbar'; + +// In layout or page +; +``` + +## Integration with Layout + +The Navbar is rendered in the [`GeneralLayout`](../../src/layouts/GeneralLayout.tsx): + +```tsx +export default function GeneralLayout({ children }) { + return ( +
+ +
{children}
+
+
+ ); +} +``` + +## Scroll Target IDs + +The component relies on the following element IDs: + +- `content` - Page container +- `projects-grid` - Projects section +- `publications` - Publications section + +Ensure these IDs exist in your page structure. + +## Performance Considerations + +- **Client Component:** Uses `'use client'` for browser APIs +- **Lightweight:** Minimal re-renders +- **Fixed Position:** Always visible during scroll +- **Analytics Batching:** Firebase handles event batching + +## Related Documentation + +- [GeneralLayout](../layouts.md) +- [Firebase Analytics](../configs.md#firebase-configuration-and-usage) +- [Components Overview](./index.md) + +--- + +💡 **Tip:** Use descriptive `aria-label` and `id` attributes for smooth scrolling to work correctly. diff --git a/docs/architecture/components/stars.md b/docs/architecture/components/stars.md new file mode 100644 index 0000000..b8e8592 --- /dev/null +++ b/docs/architecture/components/stars.md @@ -0,0 +1,242 @@ +# Stars Background Component + +This document details the StarsBackground component that creates an animated starfield background effect. + +## Overview + +Location: [`src/components/Stars/StarsBackground.tsx`](../../src/components/Stars/StarsBackground.tsx) + +The StarsBackground component creates a visually appealing animated background with twinkling stars and occasional shooting stars. + +## Component Structure + +```mermaid +flowchart TD + StarsBackground[StarsBackground] -->|Creates| Container[Sky Container] + Container -->|Generates| Stars[Star Elements] + Stars -->|Random| Position[Random Positions] + Stars -->|Random| Size[Random Sizes] + Stars -->|Random| Animation[Twinkle Animation] + Stars -->|Occasional| Shooting[Shooting Stars] +``` + +## Key Features + +### 1. Dynamic Star Generation + +Stars are generated on component mount with random properties: + +```typescript +useEffect(() => { + const starCount = Math.floor(Math.random() * 50) + 50; // 50-100 stars + + const newStars = Array.from({ length: starCount }, (_, i) => ({ + id: i, + top: `${Math.random() * 100}%`, + left: `${Math.random() * 100}%`, + size: Math.random() * 3 + 1, // 1-4px + animationDuration: `${Math.random() * 3 + 2}s`, // 2-5s + animationDelay: `${Math.random() * 5}s`, + })); + + setStars(newStars); +}, []); +``` + +### 2. Star Properties + +Each star has: + +- **Position:** Random top and left coordinates (0-100%) +- **Size:** Random size between 1-4px +- **Animation Duration:** Random duration 2-5 seconds +- **Animation Delay:** Random delay 0-5 seconds + +### 3. Twinkle Animation + +Stars twinkle using CSS animations: + +```typescript +sx={{ + animation: `twinkle ${star.animationDuration} infinite`, + animationDelay: star.animationDelay, +}}; +``` + +The `twinkle` animation should be defined in global styles: + +```scss +@keyframes twinkle { + 0%, + 100% { + opacity: 1; + } + 50% { + opacity: 0.3; + } +} +``` + +### 4. Shooting Stars + +Occasionally, stars become shooting stars (implementation detail may vary). + +## Component Implementation + +```tsx +'use client'; + +import { Box } from '@mui/material'; +import { useEffect, useState } from 'react'; + +export default function StarsBackground() { + const [stars, setStars] = useState([]); + + useEffect(() => { + // Generate stars on mount + const starCount = Math.floor(Math.random() * 50) + 50; + const newStars = Array.from({ length: starCount }, (_, i) => ({ + id: i, + top: `${Math.random() * 100}%`, + left: `${Math.random() * 100}%`, + size: Math.random() * 3 + 1, + animationDuration: `${Math.random() * 3 + 2}s`, + animationDelay: `${Math.random() * 5}s`, + })); + setStars(newStars); + }, []); + + return ( +