feat: resume download, router v7/v8 migrations, spec restructure

- Add resume download button in Hero CTA and Contact section
- Migrate react-router v6→v7 and v7→v8
- Restructure specs: UI specs to specs/ui/, v2 specs to specs/v2/
- Add profile-photo assets (jpg + webp)
- Update AGENTS.md, spec-v2.md index
This commit is contained in:
dong.nguyen committed 2026-10-06 14:14:01 +07:00
1 parent 02bad6036d
commit d827bf9b23
37 files changed
+770 -443

No files matched your search

+65
View File
@@ -0,0 +1,65 @@
# Specification — v2 Analytics
> **Document:** `spec-v2-analytics.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P2
> **Estimate:** ~30 minutes
---
## Requirement
Privacy-friendly analytics — không dùng Google Analytics.
---
## Options
**Option A: Plausible Analytics** (recommended)
- Lightweight, privacy-first
- No cookie banner needed
- Simple script integration
**Option B: Umami**
- Self-hosted option
- Open source
- Similar to Plausible
**Option C: Custom minimal tracking**
- Track page views only
- Store in localStorage
- Batch send to endpoint (optional)
---
## Implementation (Plausible)
```tsx
// main.tsx — add script tag
<script
defer
data-domain="yourdomain.com"
src="https://plausible.io/js/script.outbound-links.js"
/>
```
Hoặc dùng `react-use-plausible`:
```tsx
import { usePlausible } from 'react-use-plausible'
const plausible = usePlausible()
// Auto pageview tracking
```
Configurable via env var: `ENABLE_ANALYTICS`
---
## Acceptance
- [ ] Page view tracking hoạt động
- [ ] Không cookie banner
- [ ] Không ảnh hưởng performance
- [ ] Configurable via env var (ENABLE_ANALYTICS)
+105
View File
@@ -0,0 +1,105 @@
# Specification — v2 Blog System
> **Document:** `spec-v2-blog.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P1
> **Estimate:** ~4 hours
---
## Requirement
Blog cho phép viết technical articles bằng Markdown/MDX, render trên client.
---
## Architecture
```
src/
content/
blog/
post-1.mdx
post-2.mdx
components/
blog/
BlogListPage.tsx
BlogPostPage.tsx
ArticleCard.tsx
CodeBlock.tsx
```
---
## Features
### Frontmatter
Mỗi article có frontmatter:
```yaml
---
title: "Building High-Performance Event Simulation with Go"
date: "2024-06-15"
tags: ["engineering", "golang", "simulation"]
summary: "Discrete event simulation for logistics facilities"
---
```
### Blog List Page (`/blog`)
- Hiển thị danh sách articles
- Sort theo date (newest first)
- Filter theo tags (pill buttons)
- Mỗi article card: title, date, tags, summary
### Article Page (`/blog/:slug`)
- Render MDX content
- Code blocks với syntax highlighting
- TOC (table of contents) sidebar (desktop)
- Reading time estimate
- Breadcrumb navigation
### Code Highlighting
- Dùng `rehype-prism-plus` hoặc `rehype-raw` + `prismjs`
- Không dùng library nặng như `react-syntax-highlighter`
- Theme: dark/light compatible với CSS variables
### MDX Processing
- Dùng `@mdx-js/react` + `@mdx-js/rollup` (Vite plugin)
- Build-time compilation (không runtime)
- Frontmatter extracted tại build time
### Vite Config Changes
```ts
import mdx from '@mdx-js/rollup'
export default defineConfig({
plugins: [
react(),
mdx({
providerImportSource: '@mdx-js/react',
}),
],
})
```
---
## Acceptance
- [ ] `/blog` hiển thị danh sách articles
- [ ] Article card có title, date, tags, summary
- [ ] Click article → navigate đến `/blog/:slug`
- [ ] MDX content render đúng
- [ ] Code blocks có syntax highlighting
- [ ] Tags filter hoạt động
- [ ] TOC sidebar (desktop only)
- [ ] Reading time hiển thị
- [ ] Responsive
- [ ] Không crash khi missing article
+61
View File
@@ -0,0 +1,61 @@
# Specification — v2 CI/CD Pipeline
> **Document:** `spec-v2-cicd.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P5
> **Estimate:** ~1 hour
---
## Requirement
GitHub Actions pipeline cho automated build, lint, test. Vercel cho deployment.
---
## GitHub Actions
```yaml
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [dev, main]
pull_request:
branches: [dev]
jobs:
ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm lint
- run: pnpm build
- run: pnpm test
```
## Vercel Integration
- Connect GitHub repo
- Auto deploy on `dev` → preview
- Auto deploy on `main` → production
- Environment variables: `SITE_URL`, `PLAUSIBLE_DOMAIN` (optional)
---
## Acceptance
- [ ] CI pass trên push vào dev
- [ ] Lint pass
- [ ] Build pass
- [ ] Tests pass
- [ ] Preview deploy trên Vercel
- [ ] Production deploy khi merge vào main
+104
View File
@@ -0,0 +1,104 @@
# Specification — v2 Resume Download
> **Document:** `spec-v2-resume.md`
> **Version:** 0.3.0
> **Parent:** `spec-v2.md`
> **Priority:** P1
> **Estimate:** ~15 minutes
---
## Requirement
- Nút **"Download Resume"** hiển thị ở **2 vị trí**:
1. **Hero section** — CTA row (bên cạnh "View Projects" / "Contact Me")
2. **Contact section** — trong `contact-links` grid
- Link trực tiếp đến file PDF (`/resume.pdf`) với attribute `download`
- Khi chưa có PDF → ẩn hoàn toàn ở cả 2 vị trí
- PDF upload vào `public/resume.pdf`
- (Optional) Nav link `/resume` để xem resume dạng HTML (Phase 2+)
---
## Implementation
### Hero Section (primary CTA)
```tsx
// Hero.tsx
import { resumeAvailable } from '@/data/resume'
export function Hero() {
return (
<section className="hero container-wide" aria-labelledby="hero-heading">
<div className="hero-content">
{/* ... heading, title, tagline ... */}
<div className="hero-cta">
<Button href="/projects" variant="primary">
View Projects
</Button>
{resumeAvailable && (
<Button href="/resume.pdf" variant="secondary" download>
Download Resume
</Button>
)}
<Button href="/contact" variant="secondary">
Contact Me
</Button>
</div>
<SocialLinks links={socialLinks} />
</div>
{/* ... hero-visual ... */}
</section>
)
}
```
### Contact Section (secondary)
```tsx
// Contact.tsx
import { resumeAvailable } from '@/data/resume'
export function Contact() {
return (
<section className="section container-content" aria-labelledby="contact-heading">
<SectionHeading title="Contact" />
<div className="contact-links">
{/* ... existing links (Email, GitHub, LinkedIn) ... */}
{resumeAvailable && (
<a href="/resume.pdf" download className="contact-link btn-primary">
<svg>...</svg>
<div>
<div>Download Resume</div>
<div style={{ fontSize: '14px', color: 'var(--text-muted)' }}>PDF</div>
</div>
</a>
)}
</div>
</section>
)
}
```
### Data Detection
```ts
// src/data/resume.ts
export const resumeAvailable = true // set false khi chưa có PDF
```
### Nav (optional — Phase 2)
Nút Resume trong nav chỉ hiện khi có `/resume` route (HTML resume page).
---
## Acceptance
- [x] Nút "Download Resume" hiển thị trong Hero CTA row
- [x] Nút "Download Resume" hiển thị trong Contact section
- [x] Click → download PDF từ `/resume.pdf`
- [x] Khi chưa có PDF → ẩn hoàn toàn ở cả 2 vị trí
- [x] Responsive trên mobile
- [x] Nav không có nút Resume (Phase 2)
+94
View File
@@ -0,0 +1,94 @@
# Specification — v2 React Router v7 → v8 Migration
> **Document:** `spec-v2-router-v8.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P0 (prerequisite for v2)
> **Estimate:** ~15 minutes
---
## Background
React Router v8 consolidates DOM APIs into `react-router/dom` and removes the `react-router-dom` re-export package. This app uses only the declarative mode (`<BrowserRouter>` + `<Routes>` + `<Route>`) — no data router, no loaders, no actions, no meta functions, no splat routes.
**Current state:**
- `react-router` pinned at `7.18.4`
- 4 files import from `react-router`
- No `react-router-dom` (already removed in v7 migration)
- No `meta` functions, no `useMatches().data`, no data router APIs
- React `^19.2.8` (≥ 19.2.7 ✅)
- Vite `^8.3.0` (≥ 7 ✅)
---
## Analysis
### Future flags
All 5 future flags are framework/data mode only. **Not applicable** to this app:
| Flag | Applicable? | Notes |
|------|-------------|-------|
| `v8_middleware` | No | No data router / framework mode |
| `v8_splitRouteModules` | No | No `<RouterProvider>` / data router |
| `v8_viteEnvironmentApi` | No | No SSR / custom server config |
| `v8_passThroughRequests` | No | No loaders/actions |
| `v8_trailingSlashAwareDataRequests` | No | No `.data` request handling |
### Breaking changes
| Change | Applicable? | Notes |
|--------|-------------|-------|
| `meta`/`matches` `.data` → `loaderData` | No | No meta functions |
| `react-router-dom` removal | No | Already removed in v7 migration |
| Cloudflare plugin | No | Not using Cloudflare |
| `@react-router/architect` | No | Not using adapters |
### Minimum versions
| Requirement | Current | Required | Status |
|-------------|---------|----------|--------|
| `react` | `^19.2.8` | `≥19.2.7` | ✅ |
| `react-dom` | `^19.2.8` | `≥19.2.7` | ✅ |
| `vite` | `^8.3.0` | `≥7` | ✅ |
---
## Implementation Steps
### Step 1: Update package.json
```diff
- "react-router": "7.18.4"
+ "react-router": "8.4.0"
```
### Step 2: Install and verify
```sh
pnpm install
pnpm build
pnpm lint
```
---
## Acceptance
- [x] `package.json` has `react-router@8.4.0`
- [x] `pnpm build` succeeds without errors
- [x] Dev server runs without console warnings
- [x] All routes work correctly (/ → /about → /projects → /projects/:id → /engineering → /contact)
- [x] Navigation highlighting works (NavLink active state)
- [x] Mobile menu still works
- [x] Project detail page works (useParams + Link)
---
## Notes
- v8 upgrade is non-breaking for this app (pure declarative `<BrowserRouter>` pattern)
- No code changes needed — only package version bump
- `react-router-dom` already removed in v7 migration
- All future flags are framework/data mode only, not applicable to this app
+98
View File
@@ -0,0 +1,98 @@
# Specification — v2 React Router v6 → v7 Migration
> **Document:** `spec-v2-router.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P0 (prerequisite for v2)
> **Estimate:** ~30 minutes
---
## Background
React Router v7 consolidates `react-router-dom` into `react-router`. The upgrade is non-breaking if future flags are enabled. This app uses the simple `<BrowserRouter>` + `<Routes>` pattern (no data router, no forms, no splat routes).
**Current state:**
- `react-router-dom` pinned at `6.30.6` (exact, no `^`)
- 4 files import from `react-router-dom`
- No splat routes, no forms, no data router APIs
---
## Analysis
### Applicable flags
| Flag | Applicable? | Notes |
|------|-------------|-------|
| `v7_relativeSplatPath` | No | No splat routes (`*`) in app |
| `v7_startTransition` | **Yes** | Must enable on `<BrowserRouter>` |
| `v7_fetcherPersist` | No | No `<RouterProvider>` / data router |
| `v7_normalizeFormMethod` | No | No forms in app |
| `v7_partialHydration` | No | No `<RouterProvider>` / data router |
| `v7_skipActionErrorRevalidation` | No | No data router |
### Files affected
| File | Current import | Change needed |
|------|---------------|---------------|
| `src/App.tsx` | `react-router-dom` | → `react-router` + enable flag |
| `src/components/layout/Navigation.tsx` | `react-router-dom` | → `react-router` |
| `src/components/layout/Footer.tsx` | `react-router-dom` | → `react-router` |
| `src/pages/ProjectDetailPage.tsx` | `react-router-dom` | → `react-router` |
---
## Implementation Steps
### Step 1: Verify no future flags needed
In v7, `v7_startTransition` and other future flags are enabled by default. No `future` prop needed on `<BrowserRouter>`.
### Step 2: Update package.json
```diff
- "react-router-dom": "6.30.6"
+ "react-router": "7.18.4"
```
Also remove `@types/react-router-dom` if present (v7 types are bundled).
### Step 3: Update imports
All files: replace `from 'react-router-dom'` → `from 'react-router'`
```
src/App.tsx
src/components/layout/Navigation.tsx
src/components/layout/Footer.tsx
src/pages/ProjectDetailPage.tsx
```
### Step 4: Install and verify
```bash
pnpm install
pnpm build
```
---
## Acceptance
- [x] `package.json` has `react-router` (not `react-router-dom`)
- [x] All 4 files import from `react-router`
- [x] `pnpm build` succeeds without errors
- [x] Dev server runs without console warnings
- [x] All routes work correctly (/ → /about → /projects → /projects/:id → /engineering → /contact)
- [x] Navigation highlighting works (NavLink active state)
- [x] Mobile menu still works
---
## Notes
- v7 upgrade is non-breaking for this app (simple `<BrowserRouter>` pattern)
- No code logic changes needed — only imports + package name
- v7 enables all future flags by default; no `future` prop needed
+72
View File
@@ -0,0 +1,72 @@
# Specification — v2 SEO
> **Document:** `spec-v2-seo.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P1
> **Estimate:** ~1 hour
---
## Requirement
Mỗi page có metadata riêng cho SEO và social sharing.
---
## Implementation
### Dynamic Metadata
Dùng `react-helmet-async`.
```tsx
import { Helmet } from 'react-helmet-async'
// HomePage.tsx
<Helmet>
<title>{profile.name} — Senior Software Engineer</title>
<meta name="description" content={profile.bio} />
<link rel="canonical" href={siteUrl} />
</Helmet>
```
### Open Graph
Mỗi page có OG tags:
```html
<meta property="og:title" content="..." />
<meta property="og:description" content="..." />
<meta property="og:image" content="/og-image.png" />
<meta property="og:url" content="..." />
<meta property="og:type" content="website" />
```
### Sitemap
- Generate `sitemap.xml` tại build time
- Dùng `vite-plugin-sitemap` hoặc tự viết script
- Include tất cả public pages
### Robots.txt
- `public/robots.txt`
- Allow all
### Structured Data (JSON-LD)
- `Person` schema cho homepage
- `Article` schema cho blog posts (sau này)
- `BreadcrumbList` cho nested pages
---
## Acceptance
- [ ] Mỗi page có `<title>` và `<meta description>` riêng
- [ ] OG tags đúng trên mỗi page
- [ ] `sitemap.xml` generated tại build
- [ ] `robots.txt` có trong `public/`
- [ ] JSON-LD structured data
- [ ] Canonical URL đúng
+99
View File
@@ -0,0 +1,99 @@
# Specification — v2 Testing
> **Document:** `spec-v2-testing.md`
> **Version:** 0.1.0
> **Parent:** `spec-v2.md`
> **Priority:** P5
> **Estimate:** ~3 hours
---
## Requirement
Unit tests cho components và hooks. E2E tests cho critical paths.
---
## Stack
- **Vitest** — unit/integration tests
- **@testing-library/react** — component tests
- **@testing-library/jest-dom** — assertions
- **Playwright** — E2E tests
---
## Test Structure
```
src/
__tests__/
hooks/
useTheme.test.tsx
components/
Navigation.test.tsx
Footer.test.tsx
Badge.test.tsx
pages/
HomePage.test.tsx
e2e/
navigation.spec.ts
theme.spec.ts
responsive.spec.ts
```
---
## Critical Tests
### useTheme
```tsx
test('cycles through themes correctly', () => {
const { result } = renderHook(() => useTheme())
act(() => { result.current.cycleTheme() })
expect(result.current.theme).toBe('light')
})
test('persists theme to localStorage', () => {
renderHook(() => useTheme())
expect(localStorage.getItem('portfolio-theme')).toBe('dark')
})
```
### Navigation
```tsx
test('renders all nav items', () => {
render(<Navigation />)
navItems.forEach(item => {
expect(screen.getByText(item.label)).toBeInTheDocument()
})
})
test('NavLink highlights active route', () => {
render(<MemoryRouter initialEntries={['/about']}> <Navigation /> </MemoryRouter>)
expect(screen.getByText('About')).toHaveClass('active')
})
```
### HomePage
```tsx
test('renders hero section', () => {
render(<HomePage />)
expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument()
})
```
---
## Acceptance
- [ ] useTheme tests pass
- [ ] Navigation tests pass
- [ ] HomePage tests pass
- [ ] E2E: navigation works
- [ ] E2E: theme toggle works
- [ ] E2E: responsive layout correct
- [ ] Test coverage > 70%