diff --git a/AGENTS.md b/AGENTS.md index 60e0ad3..c2c2a0a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -96,8 +96,9 @@ All specification documents are in `docs/design/`: |------|---------| | `spec.md` | Main PRD — product vision, positioning, narrative, IA, acceptance criteria | | `spec-v1.md` | v1 completion record — features implemented, known limitations, files summary | -| `spec-v2.md` | v2 features — Resume, Blog, SEO, Analytics, Testing, CI/CD | -| `spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) | +| `spec-v2.md` | v2 index — overview, implementation order, feature list | +| `specs/ui/spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) | +| `specs/v2/spec-v2-*.md` | v2 feature specs (resume, seo, blog, analytics, testing, cicd) | Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope. diff --git a/docs/design/spec-v2.md b/docs/design/spec-v2.md index 09ddf08..f352deb 100644 --- a/docs/design/spec-v2.md +++ b/docs/design/spec-v2.md @@ -8,418 +8,27 @@ --- + +## Prerequisites (Completed) + +| File | Feature | Status | +|------|---------|--------| +| `specs/v2/spec-v2-router.md` | React Router v6 → v7 | ✅ Done | +| `specs/v2/spec-v2-router-v8.md` | React Router v7 → v8 | ✅ Done | ## Overview -Phase 1 (Foundation) + Phase 2 (Core Portfolio) đã hoàn thành trong v0.0.1. v2 tập trung vào: - -1. **Resume download** (P1) -2. **Blog system** — MDX-based articles (P1) -3. **SEO** — metadata, Open Graph, sitemap (P1) -4. **Analytics** — privacy-friendly page view tracking (P2) -5. **Testing** — Vitest + Testing Library (P5) -6. **CI/CD pipeline** (P5) - ---- - -## 1. Resume Download - -### Requirement - -- Nút "Download Resume" trong nav hoặc Contact page -- Link đến file PDF (placeholder ban đầu) -- Khi chưa có PDF → ẩn nút, hoặc hiển thị "Coming soon" -- PDF sẽ upload vào `public/resume.pdf` - -### Implementation - -```tsx -// Navigation.tsx -{resumeAvailable && ( - Resume -)} - -// OR ContactPage.tsx -Download Resume -``` - -### Data - -- `public/resume.pdf` — PDF file (user tự upload) -- Không cần data module - -### Acceptance - -- [ ] Nút Resume hiển thị trong nav -- [ ] Click → download PDF -- [ ] Khi chưa có PDF → nút ẩn hoặc disabled -- [ ] Responsive trên mobile - ---- - -## 2. Blog System - -### 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 - -#### 2.1. 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" ---- -``` - -#### 2.2. 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 - -#### 2.3. Article Page (`/blog/:slug`) - -- Render MDX content -- Code blocks với syntax highlighting -- TOC (table of contents) sidebar (desktop) -- Reading time estimate -- Breadcrumb navigation - -#### 2.4. 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 - -#### 2.5. 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 -// vite.config.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 - ---- - -## 3. SEO - -### Requirement - -Mỗi page có metadata riêng cho SEO và social sharing. - -### Implementation - -#### 3.1. Dynamic Metadata - -Dùng `react-helmet-async` (hoặc `@remix-run/react` helmet nếu cần SSR sau này). - -```tsx -import { Helmet } from 'react-helmet-async' - -// HomePage.tsx - - {profile.name} — Senior Software Engineer - - - -``` - -#### 3.2. Open Graph - -Mỗi page có OG tags: - -```html - - - - - -``` - -#### 3.3. 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 - -#### 3.4. Robots.txt - -- `public/robots.txt` -- Allow all (trừ `/admin` nếu có sau này) - -#### 3.5. Structured Data (JSON-LD) - -- `Person` schema cho homepage -- `Article` schema cho blog posts -- `BreadcrumbList` cho nested pages - -### Acceptance - -- [ ] Mỗi page có `` 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 - ---- - -## 4. Analytics - -### 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 -<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 -``` - -### Acceptance - -- [ ] Page view tracking hoạt động -- [ ] Không cookie banner -- [ ] Không ảnh hưởng performance -- [ ] Configurable via env var (ENABLE_ANALYTICS) - ---- - -## 5. Testing - -### 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') // or 'dark' -}) - -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% - ---- - -## 6. CI/CD Pipeline - -### Requirement - -GitHub Actions pipeline: - -1. **Lint** — oxlint -2. **Type check** — tsc -b -3. **Test** — vitest -4. **Build** — vite build -5. **Deploy** — to Vercel (on main branch push) - -### 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 - ---- - -## Implementation Order - -Ưu tiên thực hiện: - -1. **Resume download** (5 phút, trivial) -2. **SEO** (metadata, OG, sitemap) — cần làm trước khi deploy -3. **Blog system** (MDX + articles) — P1, substantial work -4. **Analytics** (Plausible) — quick win -5. **Testing** (Vitest + E2E) — P5, important but can iterate -6. **CI/CD** (GitHub Actions) — P5, automate after features done +v2 bao gồm 6 tính năng, mỗi tính năng có spec riêng trong `specs/`: + +| File | Feature | Priority | Est. | Status | +|------|---------|----------|------|--------| +| `specs/v2/spec-v2-resume.md` | Resume download | P1 | ~15 min | ✅ Done | +| `specs/v2/spec-v2-seo.md` | SEO (metadata, OG, sitemap) | P1 | ~1 hour | | +| `specs/v2/spec-v2-blog.md` | Blog (MDX, articles, syntax highlight) | P1 | ~4 hours | | +| `specs/v2/spec-v2-analytics.md` | Analytics (Plausible) | P2 | ~30 min | | +| `specs/v2/spec-v2-testing.md` | Testing (Vitest + E2E) | P5 | ~3 hours | | +| `specs/v2/spec-v2-cicd.md` | CI/CD (GitHub Actions) | P5 | ~1 hour | | + +**Implementation order:** ~~Resume~~ → SEO → Blog → Analytics → Testing → CI/CD --- diff --git a/docs/design/spec-ui-about.md b/docs/design/specs/ui/spec-ui-about.md similarity index 100% rename from docs/design/spec-ui-about.md rename to docs/design/specs/ui/spec-ui-about.md diff --git a/docs/design/spec-ui-blog.md b/docs/design/specs/ui/spec-ui-blog.md similarity index 100% rename from docs/design/spec-ui-blog.md rename to docs/design/specs/ui/spec-ui-blog.md diff --git a/docs/design/spec-ui-components.md b/docs/design/specs/ui/spec-ui-components.md similarity index 100% rename from docs/design/spec-ui-components.md rename to docs/design/specs/ui/spec-ui-components.md diff --git a/docs/design/spec-ui-contact.md b/docs/design/specs/ui/spec-ui-contact.md similarity index 100% rename from docs/design/spec-ui-contact.md rename to docs/design/specs/ui/spec-ui-contact.md diff --git a/docs/design/spec-ui-engineering.md b/docs/design/specs/ui/spec-ui-engineering.md similarity index 100% rename from docs/design/spec-ui-engineering.md rename to docs/design/specs/ui/spec-ui-engineering.md diff --git a/docs/design/spec-ui-experience.md b/docs/design/specs/ui/spec-ui-experience.md similarity index 100% rename from docs/design/spec-ui-experience.md rename to docs/design/specs/ui/spec-ui-experience.md diff --git a/docs/design/spec-ui-expertise.md b/docs/design/specs/ui/spec-ui-expertise.md similarity index 100% rename from docs/design/spec-ui-expertise.md rename to docs/design/specs/ui/spec-ui-expertise.md diff --git a/docs/design/spec-ui-footer.md b/docs/design/specs/ui/spec-ui-footer.md similarity index 100% rename from docs/design/spec-ui-footer.md rename to docs/design/specs/ui/spec-ui-footer.md diff --git a/docs/design/spec-ui-hero.md b/docs/design/specs/ui/spec-ui-hero.md similarity index 100% rename from docs/design/spec-ui-hero.md rename to docs/design/specs/ui/spec-ui-hero.md diff --git a/docs/design/spec-ui-layout.md b/docs/design/specs/ui/spec-ui-layout.md similarity index 100% rename from docs/design/spec-ui-layout.md rename to docs/design/specs/ui/spec-ui-layout.md diff --git a/docs/design/spec-ui-navigation.md b/docs/design/specs/ui/spec-ui-navigation.md similarity index 100% rename from docs/design/spec-ui-navigation.md rename to docs/design/specs/ui/spec-ui-navigation.md diff --git a/docs/design/spec-ui-project-detail.md b/docs/design/specs/ui/spec-ui-project-detail.md similarity index 100% rename from docs/design/spec-ui-project-detail.md rename to docs/design/specs/ui/spec-ui-project-detail.md diff --git a/docs/design/spec-ui-projects-list.md b/docs/design/specs/ui/spec-ui-projects-list.md similarity index 100% rename from docs/design/spec-ui-projects-list.md rename to docs/design/specs/ui/spec-ui-projects-list.md diff --git a/docs/design/spec-ui-projects.md b/docs/design/specs/ui/spec-ui-projects.md similarity index 100% rename from docs/design/spec-ui-projects.md rename to docs/design/specs/ui/spec-ui-projects.md diff --git a/docs/design/specs/v2/spec-v2-analytics.md b/docs/design/specs/v2/spec-v2-analytics.md new file mode 100644 index 0000000..d6a1b47 --- /dev/null +++ b/docs/design/specs/v2/spec-v2-analytics.md @@ -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) diff --git a/docs/design/specs/v2/spec-v2-blog.md b/docs/design/specs/v2/spec-v2-blog.md new file mode 100644 index 0000000..4951976 --- /dev/null +++ b/docs/design/specs/v2/spec-v2-blog.md @@ -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 diff --git a/docs/design/specs/v2/spec-v2-cicd.md b/docs/design/specs/v2/spec-v2-cicd.md new file mode 100644 index 0000000..33eba73 --- /dev/null +++ b/docs/design/specs/v2/spec-v2-cicd.md @@ -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 diff --git a/docs/design/specs/v2/spec-v2-resume.md b/docs/design/specs/v2/spec-v2-resume.md new file mode 100644 index 0000000..07cfa1f --- /dev/null +++ b/docs/design/specs/v2/spec-v2-resume.md @@ -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) + diff --git a/docs/design/specs/v2/spec-v2-router-v8.md b/docs/design/specs/v2/spec-v2-router-v8.md new file mode 100644 index 0000000..94cc191 --- /dev/null +++ b/docs/design/specs/v2/spec-v2-router-v8.md @@ -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 diff --git a/docs/design/specs/v2/spec-v2-router.md b/docs/design/specs/v2/spec-v2-router.md new file mode 100644 index 0000000..9cdc34f --- /dev/null +++ b/docs/design/specs/v2/spec-v2-router.md @@ -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 diff --git a/docs/design/specs/v2/spec-v2-seo.md b/docs/design/specs/v2/spec-v2-seo.md new file mode 100644 index 0000000..b442ccf --- /dev/null +++ b/docs/design/specs/v2/spec-v2-seo.md @@ -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 + + + +``` + +### Open Graph + +Mỗi page có OG tags: + +```html + + + + + +``` + +### 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ó `` 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 diff --git a/docs/design/specs/v2/spec-v2-testing.md b/docs/design/specs/v2/spec-v2-testing.md new file mode 100644 index 0000000..da61e1d --- /dev/null +++ b/docs/design/specs/v2/spec-v2-testing.md @@ -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% diff --git a/package.json b/package.json index 6d0b62e..e798262 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "dependencies": { "react": "^19.2.8", "react-dom": "^19.2.8", - "react-router-dom": "6.30.6" + "react-router": "8.4.0" }, "devDependencies": { "@types/node": "^24.13.3", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9d5c6c5..8f6af07 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -14,9 +14,9 @@ importers: react-dom: specifier: ^19.2.8 version: 19.3.0(react@19.3.0) - react-router-dom: - specifier: 6.30.6 - version: 6.30.6(react-dom@19.3.0(react@19.3.0))(react@19.3.0) + react-router: + specifier: 8.4.0 + version: 8.4.0(react-dom@19.3.0(react@19.3.0))(react@19.3.0) devDependencies: '@types/node': specifier: ^24.13.3 @@ -167,9 +167,8 @@ packages: cpu: [x64] os: [win32] - '@remix-run/router@1.23.4': - resolution: {integrity: sha512-q7j5geK7xs3UJSdm9/iytUNclBnLmYx1EnSeCFXHPeutdqgIMeFeHtUZgS3EhlKxdBEAu8OwtJCwmLrEzpSs7Q==} - engines: {node: '>=14.0.0'} + '@remix-run/route-pattern@0.22.1': + resolution: {integrity: sha512-czdGJWh09Lapvcqt7Vb09KlrU2PhRJ8xQaI+AItTuD9aDJ5MAgxnS38lnys6Ll+6RJEqPiaUqTwIQhVLwFvv+w==} '@rolldown/binding-android-arm-eabi@1.2.12': resolution: {integrity: sha512-dB/a1214qKfHMXCpgqR4OZT+jS4kTyEXbQGJPqzobt5EwH5rX080pxE37alt3RzvR1bf1Yz/yGqRfrYAxuPw0A==} @@ -297,6 +296,9 @@ packages: oxc-transform-react: optional: true + cookie-es@3.1.1: + resolution: {integrity: sha512-UaXxwISYJPTr9hwQxMFYZ7kNhSXboMXP+Z3TRX6f1/NyaGPfuNUZOWP1pUEb75B2HjfklIYLVRfWiFZJyC6Npg==} + csstype@3.2.3: resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==} @@ -426,18 +428,15 @@ packages: peerDependencies: react: ^19.3.0 - react-router-dom@6.30.6: - resolution: {integrity: sha512-0RHKZz7wwffvkU+2MFVT2NnjK44ssLEV+m0CAJaS2Ksmorrwj7WxH00jO0SOCW26/tINUnJHToXblDs33I38YQ==} - engines: {node: '>=14.0.0'} + react-router@8.4.0: + resolution: {integrity: sha512-JtydAkBvU9UTEe5qNC+POhu+ZBNM7rlKY2IegwXc7Idj7xfRG16x5RZrw3mju+XlqBxfvb2ky9P3jUp9WyWC1g==} + engines: {node: '>=22.22.0'} peerDependencies: - react: '>=16.8' - react-dom: '>=16.8' - - react-router@6.30.6: - resolution: {integrity: sha512-5HfK7k5im7LTOB0EqCQmfvy4C13G92Ssj1VTmouTK3AJvyjKTnFuCV0vcMAD/JS+JC4DvDIBRrlAeJIFjh5VWg==} - engines: {node: '>=14.0.0'} - peerDependencies: - react: '>=16.8' + react: '>=19.2.7' + react-dom: '>=19.2.7' + peerDependenciesMeta: + react-dom: + optional: true react@19.3.0: resolution: {integrity: sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog==} @@ -571,7 +570,7 @@ snapshots: '@oxlint/binding-win32-x64-msvc@1.86.0': optional: true - '@remix-run/router@1.23.4': {} + '@remix-run/route-pattern@0.22.1': {} '@rolldown/binding-android-arm-eabi@1.2.12': optional: true @@ -637,6 +636,8 @@ snapshots: '@rolldown/pluginutils': 1.0.1 vite: 8.3.2(@types/node@24.19.1) + cookie-es@3.1.1: {} + csstype@3.2.3: {} detect-libc@2.1.2: {} @@ -736,17 +737,13 @@ snapshots: react: 19.3.0 scheduler: 0.28.0 - react-router-dom@6.30.6(react-dom@19.3.0(react@19.3.0))(react@19.3.0): + react-router@8.4.0(react-dom@19.3.0(react@19.3.0))(react@19.3.0): dependencies: - '@remix-run/router': 1.23.4 + '@remix-run/route-pattern': 0.22.1 + cookie-es: 3.1.1 react: 19.3.0 + optionalDependencies: react-dom: 19.3.0(react@19.3.0) - react-router: 6.30.6(react@19.3.0) - - react-router@6.30.6(react@19.3.0): - dependencies: - '@remix-run/router': 1.23.4 - react: 19.3.0 react@19.3.0: {} diff --git a/public/profile-photo.jpg b/public/profile-photo.jpg new file mode 100644 index 0000000..3d8c0ec Binary files /dev/null and b/public/profile-photo.jpg differ diff --git a/public/profile-photo.webp b/public/profile-photo.webp new file mode 100644 index 0000000..4670338 Binary files /dev/null and b/public/profile-photo.webp differ diff --git a/public/profile-photo.webp~ b/public/profile-photo.webp~ new file mode 100644 index 0000000..af79baf Binary files /dev/null and b/public/profile-photo.webp~ differ diff --git a/src/App.tsx b/src/App.tsx index b22964b..70f639d 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -1,5 +1,5 @@ import './App.css' -import { BrowserRouter, Routes, Route } from 'react-router-dom' +import { BrowserRouter, Routes, Route } from 'react-router' import { ThemeProvider } from '@/hooks/useTheme' import { Layout } from '@/components/layout/Layout' import { diff --git a/src/components/layout/Footer.tsx b/src/components/layout/Footer.tsx index 68dcb21..c7f8e15 100644 --- a/src/components/layout/Footer.tsx +++ b/src/components/layout/Footer.tsx @@ -1,4 +1,4 @@ -import { Link } from 'react-router-dom' +import { Link } from 'react-router' import { profile } from '@/data/profile' const footerLinks = [ diff --git a/src/components/layout/Navigation.tsx b/src/components/layout/Navigation.tsx index cc0246f..7d806aa 100644 --- a/src/components/layout/Navigation.tsx +++ b/src/components/layout/Navigation.tsx @@ -1,5 +1,5 @@ import { useState, useEffect } from 'react' -import { Link, NavLink, useLocation } from 'react-router-dom' +import { Link, NavLink, useLocation } from 'react-router' import { useTheme } from '@/hooks/useTheme' const navItems = [ diff --git a/src/components/sections/Contact.tsx b/src/components/sections/Contact.tsx index 91f7bbb..f9789b1 100644 --- a/src/components/sections/Contact.tsx +++ b/src/components/sections/Contact.tsx @@ -1,3 +1,4 @@ +import { resumeAvailable } from '@/data/resume' import { SectionHeading } from '@/components/ui/SectionHeading' import { profile } from '@/data/profile' @@ -34,6 +35,19 @@ export function Contact() { <div style={{ fontSize: '14px', color: 'var(--text-muted)' }}>Your Name</div> </div> </a> + {resumeAvailable && ( + <a href="/resume.pdf" download className="contact-link"> + <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" width="24" height="24"> + <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /> + <polyline points="7 10 12 15 17 10" /> + <line x1="12" y1="15" x2="12" y2="3" /> + </svg> + <div> + <div style={{ fontWeight: 500, color: 'var(--text-primary)' }}>Download Resume</div> + <div style={{ fontSize: '14px', color: 'var(--text-muted)' }}>PDF</div> + </div> + </a> + )} </div> </section> ) diff --git a/src/components/sections/Hero.tsx b/src/components/sections/Hero.tsx index 1c48da1..7415117 100644 --- a/src/components/sections/Hero.tsx +++ b/src/components/sections/Hero.tsx @@ -1,3 +1,4 @@ +import { resumeAvailable } from '@/data/resume' import { Button } from '@/components/ui/Button' import { SocialLinks } from '@/components/ui/SocialLinks' import { profile } from '@/data/profile' @@ -49,6 +50,11 @@ export function Hero() { <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> diff --git a/src/components/ui/Button.tsx b/src/components/ui/Button.tsx index 8dc78d5..ca0da91 100644 --- a/src/components/ui/Button.tsx +++ b/src/components/ui/Button.tsx @@ -8,6 +8,7 @@ interface ButtonProps extends ComponentPropsWithoutRef<'button'> { variant?: ButtonVariant size?: ButtonSize href?: string + download?: boolean children: React.ReactNode } diff --git a/src/data/resume.ts b/src/data/resume.ts new file mode 100644 index 0000000..3fde682 --- /dev/null +++ b/src/data/resume.ts @@ -0,0 +1 @@ +export const resumeAvailable = true diff --git a/src/pages/ProjectDetailPage.tsx b/src/pages/ProjectDetailPage.tsx index d275658..338ef87 100644 --- a/src/pages/ProjectDetailPage.tsx +++ b/src/pages/ProjectDetailPage.tsx @@ -1,4 +1,4 @@ -import { useParams, Link } from 'react-router-dom' +import { useParams, Link } from 'react-router' import { Badge } from '@/components/ui/Badge' import { Tag } from '@/components/ui/Tag' import { projects } from '@/data/projects'