From 08a546e1ac902d147ff12944d43d9dd365b170b9 Mon Sep 17 00:00:00 2001 From: Amr Abed <3361565+amrabed@users.noreply.github.com> Date: Sun, 23 Aug 2026 08:42:59 -0400 Subject: [PATCH 1/5] docs: update documentation to match current implementation --- AGENTS.md | 61 +++++++++------- README.md | 4 +- docs/content/adr/_meta.js | 7 +- docs/content/adr/adr-001-nextjs-16.mdx | 9 +-- docs/content/adr/adr-002-heroui-v3.mdx | 9 +-- docs/content/adr/adr-003-vitest.mdx | 9 +-- docs/content/adr/adr-004-playwright.mdx | 9 +-- docs/content/adr/adr-006-tailwind-v4.mdx | 11 +-- docs/content/adr/adr-007-data-layer.mdx | 11 +-- docs/content/adr/adr-008-vercel.mdx | 11 +-- docs/content/adr/index.mdx | 7 +- docs/content/deployment/_meta.js | 1 + docs/content/deployment/firebase.mdx | 34 +++++++++ docs/content/deployment/github-pages.mdx | 28 ++++++-- docs/content/deployment/index.mdx | 4 +- docs/content/deployment/vercel.mdx | 37 ++++++++-- docs/content/getting-started/_meta.js | 10 +-- .../getting-started/environment-variables.mdx | 43 ++++++++--- docs/content/getting-started/installation.mdx | 58 +++++++++------ .../getting-started/project-structure.mdx | 39 ++++++---- docs/content/guides/_meta.js | 2 +- docs/content/guides/adding-a-component.mdx | 60 +++++++++++++--- docs/content/guides/adding-a-shortcut.mdx | 15 ---- docs/content/guides/dark-mode.mdx | 41 +++++++++-- docs/content/guides/error-handling.mdx | 44 ++++++++++++ docs/content/guides/index.mdx | 3 +- docs/content/guides/testing.mdx | 41 ++++++++--- docs/content/index.mdx | 6 +- docs/content/reference/_meta.js | 10 +-- docs/content/reference/components.mdx | 58 +++++++++++---- docs/content/reference/index.mdx | 7 +- docs/content/reference/shortcuts.mdx | 11 --- docs/content/reference/utilities.mdx | 72 +++++++++++++++++++ docs/content/reference/workflows.mdx | 39 ++++++++-- 34 files changed, 601 insertions(+), 210 deletions(-) create mode 100644 docs/content/deployment/firebase.mdx delete mode 100644 docs/content/guides/adding-a-shortcut.mdx create mode 100644 docs/content/guides/error-handling.mdx delete mode 100644 docs/content/reference/shortcuts.mdx create mode 100644 docs/content/reference/utilities.mdx diff --git a/AGENTS.md b/AGENTS.md index ed0f436..6b8eddf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,18 +1,20 @@ # Agents.md ## 1. Project Overview -cur8d is a production-ready Next.js starter optimized for data integration and scalability. +cur8d is a production-ready Next.js starter optimized for performance, accessibility, and type safety. ## 2. Tech Stack -- Next.js 16.2.6: App Router, Server Components. -- HeroUI v3.0.5: Compound components with dot notation. -- Tailwind CSS v4: CSS-first configuration. -- Vitest 4.1.6 & Playwright 1.59.1: Testing. -- Supabase & Vercel Blob: Data and storage stubs. +- Next.js 16 (App Router, Turbopack, Server Components, React 19). +- HeroUI v3: Accessible compound components with dot notation. +- Tailwind CSS v4: CSS-first configuration and theme variables. +- Vitest & Playwright: Unit, E2E, and accessibility (`@axe-core/playwright`) testing. +- Vercel Blob & Observability: Storage stub and centralized error reporting. ## 3. Directory Structure -- `app`: Routes, layouts, components, hooks, and logic/data layer. -- `docs`: Nextra v4 documentation. +- `app`: Routes, layouts, components, hooks, and logic layer (`app/lib`). +- `docs`: Nextra v4 documentation site. +- `scripts`: Template initialization and utility scripts (`scripts/init.ts`). +- `tests`: Test suites (`tests/unit/` for Vitest, `tests/e2e/` for Playwright). ## 4. Toolchain Management Managed via `mise`. Update `.mise.toml` to change Node.js or pnpm versions. @@ -23,43 +25,50 @@ Managed via `mise`. Update `.mise.toml` to change Node.js or pnpm versions. - Explicit interfaces for all component props. ## 6. Coding Conventions -- Named imports for icons. -- Barrel exports (`index.ts`) in component folders. -- Server Components by default. +- Named imports for icons (`lucide-react`, `@icons-pack/react-simple-icons`). +- Component folders in `app/components/ComponentName/index.tsx`. +- Server Components by default; `"use client"` for interactive leaf components. ## 7. How to add a new page Add directory to `app/` with `page.tsx`. ## 8. How to add a new component -Create folder in `app/components/` with `index.tsx`, types, and tests. +Create folder in `app/components/ComponentName/` with `index.tsx`, explicit prop interface, and unit test in `tests/unit/components/ComponentName/index.test.tsx`. -## 9. How to add a keyboard shortcut -Register in `app/config/shortcuts.ts`, use `useShortcuts` hook, add UI hint. +## 9. State Management & Hooks +Custom hooks in `app/hooks/` (e.g., `useSearchState` via `SearchProvider` context). ## 10. Testing Guide -- Unit: `pnpm test` -- E2E: `pnpm test:e2e` -- 80% coverage required. +- Complete Verification: `mise run verify` (alias: `v`) +- Unit: `mise run test` (alias: `t` or `pnpm test`) +- Coverage: `mise run test:coverage` (80% coverage required) +- E2E: `mise run test:e2e` +- Install Playwright Browsers: `mise run playwright:install` ## 11. Environment Variables Validated via Zod in `app/lib/env.ts`. ## 12. Local Development Commands -- `pnpm dev`: Start dev server. -- `pnpm build`: Production build. -- `pnpm lint`: Run linting. +- `mise run dev` (alias: `d` or `pnpm dev`): Start Turbopack dev server. +- `mise run build` (alias: `b` or `pnpm build`): Production build. +- `mise run lint` (alias: `l` or `pnpm lint`): Run linting. +- `mise run docs:dev`: Start documentation server. +- `mise run docs:build`: Build static documentation. ## 13. Deployment -Vercel for SSR, GitHub Pages for static export. +- Vercel: Primary target for SSR site (`mise run deploy:vercel` / `deploy.yml`). +- Firebase Hosting: Alternative target for site and docs (`mise run deploy:firebase`). +- GitHub Pages: Static documentation hosting (`docs.yml`). ## 14. HeroUI v3 usage -Use compound component pattern (e.g., ``). +Use compound component pattern (e.g., ``, ``). ## 15. Dark mode -Wiring via `next-themes` and Tailwind v4 variables. +Wiring via `next-themes` (`Providers` component) and Tailwind v4 CSS variables. ## 16. Icon usage -`lucide-react` named imports with Tailwind `size-*` utilities. +Named imports with Tailwind `size-*` or `h-* w-*` utilities. + +## 17. Logic & Data layer +Logic, Zod schemas, structured metadata (`json-ld.ts`), and centralized error reporting (`error-reporting.ts`) in `app/lib/`. -## 17. Data layer -Mock data in `app/lib/data/mock.ts`, migration path to Supabase documented in `app/lib/data/README.md`. diff --git a/README.md b/README.md index da71393..c18a295 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,8 @@ This project is organized as a monorepo workspace managed by `pnpm`: ```text ├── app/ # Main Next.js App Router application │ ├── components/ # Reusable React components (with barrel exports) -│ ├── hooks/ # Custom React hooks (e.g., keyboard shortcuts) -│ ├── lib/ # Logic layer, Zod environment schema, SEO JSON-LD helpers +│ ├── hooks/ # Custom React hooks (e.g., search state) +│ ├── lib/ # Logic layer, Zod environment schema, SEO JSON-LD helpers, error reporting │ ├── layout.tsx # Root layout with providers configured │ └── globals.css # Tailwind CSS v4 directives and variables ├── docs/ # Nextra v4 documentation site (pnpm workspace package) diff --git a/docs/content/adr/_meta.js b/docs/content/adr/_meta.js index b0ddb48..58ad156 100644 --- a/docs/content/adr/_meta.js +++ b/docs/content/adr/_meta.js @@ -5,7 +5,8 @@ export default { "adr-003-vitest": "ADR 003: Vitest", "adr-004-playwright": "ADR 004: Playwright", "adr-005-mise": "ADR 005: Mise", - "adr-006-tailwind-v4": "ADR 006: Tailwind v4", - "adr-007-data-layer": "ADR 007: Data Layer", - "adr-008-vercel": "ADR 008: Vercel" + "adr-006-tailwind-v4": "ADR 006: Tailwind CSS v4", + "adr-007-data-layer": "ADR 007: Logic & Data Layer", + "adr-008-vercel": "ADR 008: Deployment Architecture" } + diff --git a/docs/content/adr/adr-001-nextjs-16.mdx b/docs/content/adr/adr-001-nextjs-16.mdx index 235c110..a0afac0 100644 --- a/docs/content/adr/adr-001-nextjs-16.mdx +++ b/docs/content/adr/adr-001-nextjs-16.mdx @@ -2,13 +2,14 @@ Status: Accepted ## Context -We need a modern, performant, and developer-friendly framework for the cur8d template. +We need a modern, performant, and developer-friendly React framework for the cur8d starter template. ## Decision -We chose Next.js 16.2.6 (App Router). +We chose Next.js 16 (App Router) with Turbopack and React 19. ## Rationale -Next.js provides excellent support for Server Components, SSR, and built-in optimization. Version 16 brings latest performance improvements and React 19 support. +Next.js provides first-class support for React Server Components, Streaming SSR, and built-in optimization. Version 16 brings cutting-edge performance improvements, Turbopack dev acceleration, and seamless React 19 integration. ## Consequences -All development must follow App Router conventions. Leaf nodes needing interactivity should use `"use client"`. +All page routing and layouts follow App Router conventions. Server Components are used by default, and client-side interactivity is isolated in `"use client"` leaf components. + diff --git a/docs/content/adr/adr-002-heroui-v3.mdx b/docs/content/adr/adr-002-heroui-v3.mdx index 7fc7e3c..e30b44f 100644 --- a/docs/content/adr/adr-002-heroui-v3.mdx +++ b/docs/content/adr/adr-002-heroui-v3.mdx @@ -2,13 +2,14 @@ Status: Accepted ## Context -We need a robust, accessible, and themeable UI component library. +We need a robust, accessible, and themeable UI component library that integrates cleanly with Tailwind CSS. ## Decision -We chose HeroUI v3.0.5. +We chose HeroUI v3. ## Rationale -HeroUI v3 offers a wide range of compound components with dot notation, built-in accessibility, and seamless integration with Tailwind CSS. +HeroUI v3 offers accessible compound components with dot notation, built-in ARIA support, keyboard navigation, and seamless styling compatibility with Tailwind CSS. ## Consequences -Component usage must strictly follow v3 APIs (e.g., `` instead of legacy v2 structures). +Component usage follows v3 compound component APIs (e.g., ``, `` instead of legacy monolithic component wrappers). + diff --git a/docs/content/adr/adr-003-vitest.mdx b/docs/content/adr/adr-003-vitest.mdx index 5c7d1ed..be82134 100644 --- a/docs/content/adr/adr-003-vitest.mdx +++ b/docs/content/adr/adr-003-vitest.mdx @@ -2,13 +2,14 @@ Status: Accepted ## Context -We need a fast and modern unit testing framework compatible with Vite-based tooling. +We need a fast, modern, and ESM-native unit testing framework with built-in code coverage support. ## Decision -We chose Vitest 4.1.6. +We chose Vitest. ## Rationale -Vitest is significantly faster than Jest, provides out-of-the-box ESM support, and shares configuration with Vite, simplifying the build pipeline. +Vitest provides native ESM execution, blazing fast test performance with worker threads, seamless Vite plugin integration, and zero-configuration TypeScript support. ## Consequences -Tests are colocated with source files in `__tests__` directories. +Unit and component tests are organized within the top-level `tests/unit/` directory mirroring the application structure. Code coverage is measured using `@vitest/coverage-v8` with an 80% coverage threshold enforced across CI. + diff --git a/docs/content/adr/adr-004-playwright.mdx b/docs/content/adr/adr-004-playwright.mdx index e22dbef..692f829 100644 --- a/docs/content/adr/adr-004-playwright.mdx +++ b/docs/content/adr/adr-004-playwright.mdx @@ -2,13 +2,14 @@ Status: Accepted ## Context -We need a reliable, cross-browser end-to-end testing framework. +We need a reliable, cross-browser end-to-end testing and automated accessibility auditing framework. ## Decision -We chose Playwright 1.59.1. +We chose Playwright. ## Rationale -Playwright offers superior multi-tab/context support, faster execution, and built-in accessibility testing via `@axe-core/playwright`. +Playwright offers multi-browser testing across Chromium, Firefox, and WebKit, isolated browser contexts, parallel execution, and built-in accessibility testing via `@axe-core/playwright`. ## Consequences -E2E tests live in the `tests/e2e/` directory. +E2E and accessibility test suites live in `tests/e2e/`. Playwright browsers are installed via `mise run playwright:install`. + diff --git a/docs/content/adr/adr-006-tailwind-v4.mdx b/docs/content/adr/adr-006-tailwind-v4.mdx index d95e2b4..79f677b 100644 --- a/docs/content/adr/adr-006-tailwind-v4.mdx +++ b/docs/content/adr/adr-006-tailwind-v4.mdx @@ -1,14 +1,15 @@ -# ADR-006: Tailwind v4 CSS-First +# ADR-006: Tailwind CSS v4 CSS-First Status: Accepted ## Context -We need a powerful and flexible styling solution. +We need a performant, maintainable, and modern styling solution. ## Decision -We chose Tailwind CSS v4.0.0. +We chose Tailwind CSS v4. ## Rationale -Tailwind v4 adopts a CSS-first approach, moving configuration to `@theme` blocks in standard CSS files. This simplifies the toolchain and improves performance. +Tailwind v4 adopts a modern CSS-first configuration model, removing the JavaScript config file in favor of `@theme` directives in standard CSS. This speeds up build times, simplifies dark mode variables, and eliminates build-time plugin overhead. ## Consequences -There is no `tailwind.config.ts`. All customizations live in `app/globals.css`. +There is no `tailwind.config.ts`. All design system customizations and CSS variable bindings are defined in `app/globals.css`. + diff --git a/docs/content/adr/adr-007-data-layer.mdx b/docs/content/adr/adr-007-data-layer.mdx index 766a3cb..708030f 100644 --- a/docs/content/adr/adr-007-data-layer.mdx +++ b/docs/content/adr/adr-007-data-layer.mdx @@ -1,14 +1,15 @@ -# ADR-007: Data Layer Strategy +# ADR-007: Logic & Data Layer Strategy Status: Accepted ## Context -The application needs a consistent way to handle data fetching and mutation. +The application requires a decoupled, testable, and robust architecture for logic, environment validation, error reporting, and data handling. ## Decision -We utilize a service-based architecture in `app/lib/data/` for data access. +We centralize business logic, environment validation, and third-party service abstractions in `app/lib/`. ## Rationale -Decoupling data access from UI components improves testability and makes it easier to switch between mock data and real backend services like Supabase. +Decoupling logic, observability, and data access from React UI components maximizes testability, isolates runtime side-effects, and allows seamless evolution from mock data to production storage providers (such as Vercel Blob). ## Consequences -Direct database or API calls should not be made from React components. Always use the provided data services. +Components focus purely on rendering and user interaction. All environment parsing (`env.ts`), structured metadata serialization (`json-ld.ts`), and error telemetry (`error-reporting.ts`) are imported from `@/lib/`. + diff --git a/docs/content/adr/adr-008-vercel.mdx b/docs/content/adr/adr-008-vercel.mdx index 42b3a73..c4ecb38 100644 --- a/docs/content/adr/adr-008-vercel.mdx +++ b/docs/content/adr/adr-008-vercel.mdx @@ -1,14 +1,15 @@ -# ADR-008: Vercel over Firebase Hosting +# ADR-008: Deployment Architecture Status: Accepted ## Context -We need a hosting provider that fully supports Next.js features. +We need a scalable, automated hosting architecture supporting both Server-Side Rendered (SSR) web applications and static documentation. ## Decision -We chose Vercel. +We chose Vercel as the primary SSR deployment platform, Firebase Hosting as an alternative multi-target host, and GitHub Pages for static documentation. ## Rationale -Vercel is the creator of Next.js and provides the best support for App Router, ISR, and Middleware. Firebase Hosting currently lacks full SSR support for Next.js 16. +Vercel delivers native zero-configuration optimization for Next.js App Router, React Server Components, and Edge Middleware. GitHub Pages provides free, high-availability hosting for Nextra static docs, and Firebase Hosting serves as a battle-tested static and preview environment. ## Consequences -GitHub repository should be connected directly to Vercel for production deployments. +Workflows in `.github/workflows/` are partitioned into `deploy.yml` (application deployment to Vercel/Firebase) and `docs.yml` (documentation deployment to GitHub Pages). + diff --git a/docs/content/adr/index.mdx b/docs/content/adr/index.mdx index 72480c1..c0edad4 100644 --- a/docs/content/adr/index.mdx +++ b/docs/content/adr/index.mdx @@ -7,6 +7,7 @@ Documentation of key architectural decisions made in the project. - [ADR 003: Vitest](/adr/adr-003-vitest) - [ADR 004: Playwright](/adr/adr-004-playwright) - [ADR 005: Mise](/adr/adr-005-mise) -- [ADR 006: Tailwind v4](/adr/adr-006-tailwind-v4) -- [ADR 007: Data Layer Strategy](/adr/adr-007-data-layer) -- [ADR 008: Vercel](/adr/adr-008-vercel) +- [ADR 006: Tailwind CSS v4](/adr/adr-006-tailwind-v4) +- [ADR 007: Logic & Data Layer Strategy](/adr/adr-007-data-layer) +- [ADR 008: Deployment Architecture](/adr/adr-008-vercel) + diff --git a/docs/content/deployment/_meta.js b/docs/content/deployment/_meta.js index 1b4cdaf..c8b0cd9 100644 --- a/docs/content/deployment/_meta.js +++ b/docs/content/deployment/_meta.js @@ -1,5 +1,6 @@ export default { "index": "Overview", "vercel": "Vercel", + "firebase": "Firebase Hosting", "github-pages": "GitHub Pages" } \ No newline at end of file diff --git a/docs/content/deployment/firebase.mdx b/docs/content/deployment/firebase.mdx new file mode 100644 index 0000000..c754eab --- /dev/null +++ b/docs/content/deployment/firebase.mdx @@ -0,0 +1,34 @@ +# Firebase Hosting Deployment + +Cur8d includes configuration for deploying both the main application (`site`) and the documentation (`docs`) to Firebase Hosting. + +## Configuration + +Firebase project mapping and hosting rules are defined in: +- [`.firebaserc`](file:///Users/amrabed/Library/CloudStorage/OneDrive-Personal/code/cur8d.tsx/.firebaserc): Maps project aliases to Firebase project IDs. +- [`firebase.json`](file:///Users/amrabed/Library/CloudStorage/OneDrive-Personal/code/cur8d.tsx/firebase.json): Configures hosting targets (`site` and `docs`), clean URLs, custom HTTP security headers (CSP, HSTS, X-Frame-Options), and cache settings. + +## Automated CI/CD Deployment + +Firebase deployment is configured in `.github/workflows/deploy.yml`: + +- Can be triggered manually via `workflow_dispatch` selecting the `firebase` provider. +- Deploys preview channels or live production channels based on the specified environment. + +### Setting up Secrets in GitHub + +1. Obtain a Firebase CI token via `firebase login:ci`. +2. Add `FIREBASE_TOKEN` as a repository secret (`Settings > Secrets and variables > Actions`). + +## Local Deployment via mise + +```bash +# Deploy main site to Firebase +export FIREBASE_TOKEN="your_token" +export FIREBASE_ENV="production" # or preview +mise run deploy:firebase + +# Or using package.json scripts directly +pnpm run deploy:firebase +pnpm run deploy:firebase:docs +``` diff --git a/docs/content/deployment/github-pages.mdx b/docs/content/deployment/github-pages.mdx index 55ef1df..5f91558 100644 --- a/docs/content/deployment/github-pages.mdx +++ b/docs/content/deployment/github-pages.mdx @@ -1,13 +1,27 @@ # GitHub Pages Deployment -You can deploy cur8d as a static site to GitHub Pages. +Cur8d uses GitHub Pages to host the static Nextra documentation website. -## Limitations +## Automated Documentation Deployment -- **No SSR**: Server Components will be pre-rendered at build time. -- **No Middleware**: `src/middleware.ts` is disabled. -- **Supabase**: Use client-only patterns for Supabase as SSR middleware won't run. +The `.github/workflows/docs.yml` workflow automatically builds and publishes the documentation site to GitHub Pages whenever changes are pushed to `docs/**` on the `main` branch or when triggered via `workflow_dispatch`. -## Workflow +### How It Works + +1. **Static Export**: Runs `mise run docs:build` (which executes `pnpm --filter docs build`), generating a static HTML bundle in `docs/out`. +2. **Pages Configuration**: Configures GitHub Pages settings with `actions/configure-pages@v6`. +3. **Artifact Upload**: Packages `docs/out` using `actions/upload-pages-artifact@v5`. +4. **Deployment**: Deploys the static bundle to your repository's GitHub Pages domain with `actions/deploy-pages@v5`. + +## Local Build & Verification + +To build and preview the static documentation locally: + +```bash +# Build the static export +mise run docs:build + +# Serve the exported documentation +mise run docs +``` -The `.github/workflows/deploy-ghpages.yml` handles building with `output: 'export'` and deploying via `actions/deploy-pages`. diff --git a/docs/content/deployment/index.mdx b/docs/content/deployment/index.mdx index 387af17..2292ea8 100644 --- a/docs/content/deployment/index.mdx +++ b/docs/content/deployment/index.mdx @@ -1,6 +1,8 @@ # Deployment -Instructions for deploying your cur8d application. +Instructions for deploying your cur8d application and documentation. - [Vercel](/deployment/vercel) +- [Firebase Hosting](/deployment/firebase) - [GitHub Pages](/deployment/github-pages) + diff --git a/docs/content/deployment/vercel.mdx b/docs/content/deployment/vercel.mdx index dd4ea3b..42079c3 100644 --- a/docs/content/deployment/vercel.mdx +++ b/docs/content/deployment/vercel.mdx @@ -1,11 +1,36 @@ # Vercel Deployment -Vercel is the primary deployment target for cur8d. +Vercel is the primary deployment target for cur8d, providing native support for Next.js App Router, Server Components, dynamic streaming, and Edge Middleware. -## Continuous Deployment +## Automated CI/CD Deployment -1. Connect your GitHub repository to Vercel. -2. Configure environment variables in the Vercel project dashboard. -3. Vercel will automatically deploy on every push to `main` and create preview URLs for PRs. +The repository includes a pre-configured GitHub Actions workflow in `.github/workflows/deploy.yml`: + +- **Production Deployment**: Triggered automatically on push to `main` (ignoring changes confined to `docs/**`). +- **Preview Deployments**: Can also be triggered on-demand via GitHub Actions `workflow_dispatch` selecting the `vercel` provider and `preview` environment. + +### Setting up Secrets in GitHub + +To enable automated deployments via GitHub Actions: +1. Generate an Access Token in your Vercel Account Settings. +2. Add `VERCEL_TOKEN` to your repository secrets (`Settings > Secrets and variables > Actions`). + +## Local Deployment via mise + +You can trigger a Vercel build and deployment directly from your terminal: + +```bash +# Preview deployment +export VERCEL_TOKEN="your_token" +export VERCEL_ENV="preview" +mise run deploy:vercel + +# Production deployment +export VERCEL_ENV="production" +mise run deploy:vercel +``` + +## Configuration + +Project settings and overrides are maintained in [`vercel.json`](file:///Users/amrabed/Library/CloudStorage/OneDrive-Personal/code/cur8d.tsx/vercel.json). -The `vercel.json` file in the root provides additional project configuration. diff --git a/docs/content/getting-started/_meta.js b/docs/content/getting-started/_meta.js index 21b02ea..62ad5be 100644 --- a/docs/content/getting-started/_meta.js +++ b/docs/content/getting-started/_meta.js @@ -1,6 +1,6 @@ export default { - index: 'Overview', - installation: 'Installation', - 'project-structure': 'Project Structure', - // 'environment-variables': 'Environment Variables' -} \ No newline at end of file + index: 'Overview', + installation: 'Installation', + 'project-structure': 'Project Structure', + 'environment-variables': 'Environment Variables', +}; \ No newline at end of file diff --git a/docs/content/getting-started/environment-variables.mdx b/docs/content/getting-started/environment-variables.mdx index 443eb59..3ecbd10 100644 --- a/docs/content/getting-started/environment-variables.mdx +++ b/docs/content/getting-started/environment-variables.mdx @@ -1,26 +1,47 @@ # Environment Variables -The project uses Zod for type-safe environment variable validation. +The project uses [Zod](https://zod.dev) for type-safe environment variable validation at startup. -## Required Variables +## Application Environment Variables -- `NEXT_PUBLIC_SUPABASE_URL`: Your Supabase project URL. -- `NEXT_PUBLIC_SUPABASE_ANON_KEY`: Your Supabase anonymous public key. +Environment variables are validated against the `envSchema` defined in `app/lib/env.ts`. -## Optional Variables +### `NODE_ENV` +- **Type**: `'development' | 'production' | 'test'` +- **Default**: `'development'` +- **Description**: Standard environment mode indicator. -- `BLOB_READ_WRITE_TOKEN`: Token for Vercel Blob storage (required for file uploads). +### `BLOB_READ_WRITE_TOKEN` +- **Type**: `string` (Optional) +- **Format**: Must begin with `vercel_blob_rw_` +- **Description**: Read/write token for Vercel Blob object storage. -## Configuration +## Deployment Tokens (CI / Local Deployments) -Environment variables are defined and validated in `app/lib/env.ts`. +These tokens are used by deployment workflows in `.github/workflows/deploy.yml` and local deployment tasks defined in `.mise.toml`: + +- `VERCEL_TOKEN`: Authentication token for automated deployments using Vercel CLI. +- `FIREBASE_TOKEN`: Authentication token for deploying to Firebase Hosting via Firebase CLI. + +## Schema Definition ```typescript import { z } from "zod"; const envSchema = z.object({ - NEXT_PUBLIC_SUPABASE_URL: z.string().url(), - NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1), - BLOB_READ_WRITE_TOKEN: z.string().min(1).optional(), + NODE_ENV: z.enum(["development", "production", "test"]).default("development"), + BLOB_READ_WRITE_TOKEN: z + .string() + .min(1) + .startsWith("vercel_blob_rw_", "Token must start with 'vercel_blob_rw_'") + .optional(), +}); + +export const env = envSchema.parse({ + NODE_ENV: process.env.NODE_ENV, + BLOB_READ_WRITE_TOKEN: process.env.BLOB_READ_WRITE_TOKEN, }); + +export type Env = z.infer; ``` + diff --git a/docs/content/getting-started/installation.mdx b/docs/content/getting-started/installation.mdx index 35cb92c..824f692 100644 --- a/docs/content/getting-started/installation.mdx +++ b/docs/content/getting-started/installation.mdx @@ -5,29 +5,45 @@ Follow these steps to get your cur8d-based project up and running. ## Prerequisites - **mise**: For managing Node.js and pnpm versions. -- **Node.js 24**: Managed via mise. -- **pnpm 11**: Managed via mise. +- **Node.js**: Managed via mise (`.mise.toml`). +- **pnpm**: Managed via mise (`.mise.toml`). ## Quick Start -1. **Install toolchain**: - ```bash - mise install - ``` - -2. **Install dependencies**: - ```bash - mise run install - ``` - -3. **Set up environment variables**: - ```bash - cp .env.example .env - ``` - -4. **Start the development server**: - ```bash - mise run dev - ``` +1. **Customize the template (optional)**: + Run the interactive setup script to configure your project name, repository links, and clean up template metadata: + ```bash + mise run init + # or: pnpm run init + ``` + +2. **Install toolchain**: + Let `mise` automatically download and configure Node.js and `pnpm`: + ```bash + mise install + ``` + +3. **Install dependencies**: + ```bash + mise run install + # or: pnpm install + ``` + +4. **Set up environment variables**: + ```bash + cp .env.example .env + ``` + +5. **Install Playwright browsers** (for E2E / accessibility testing): + ```bash + mise run playwright:install + ``` + +6. **Start the development server**: + ```bash + mise run dev + # or: pnpm dev + ``` Your application should now be running at `http://localhost:3000`. + diff --git a/docs/content/getting-started/project-structure.mdx b/docs/content/getting-started/project-structure.mdx index 2b4e3d8..c65f295 100644 --- a/docs/content/getting-started/project-structure.mdx +++ b/docs/content/getting-started/project-structure.mdx @@ -1,20 +1,33 @@ # Project Structure -The project follows a standard Next.js App Router structure with some enhancements for scale and maintainability. +The project follows a modern Next.js App Router workspace structure optimized for scalability, clean separation of concerns, and automated testing. -## Root Directory +## Workspace Layout -- `app/`: Application source code (pages, components, lib, etc.). -- `docs/`: Nextra documentation site. -- `tests/`: Unit and E2E tests. -- `.vibe/`: Project specifications and tasks. -- `.mise.toml`: Toolchain version pinning. +- `app/`: Main Next.js App Router application. +- `docs/`: Nextra documentation site (separate workspace package). +- `scripts/`: Template initialization and setup utility scripts (`init.ts`). +- `tests/`: Unit and End-to-End verification suites. + - `tests/unit/`: Vitest unit and component tests. + - `tests/e2e/`: Playwright E2E and accessibility (Axe) tests. +- `.mise.toml`: Toolchain management and task definitions. +- `pnpm-workspace.yaml`: Monorepo workspaces definition. +- `firebase.json` & `.firebaserc`: Firebase Hosting configuration for app and docs. +- `vercel.json`: Vercel deployment configuration. ## Application Directory (`app/`) -- `components/`: Reusable React components. -- `lib/`: Utility functions and shared logic. -- `types/`: Shared TypeScript interfaces and types. -- `config/`: Application configuration (e.g., shortcuts). -- `hooks/`: Custom React hooks. -- *(Note: Page/Route components are directly at the root of `app/`)* +- `components/`: Reusable React components (e.g., `CodeSnippet`, `Features`, `Footer`, `Hero`, `Navbar`, `Providers`, `ThemeToggle`). +- `hooks/`: Custom React hooks and context providers (`use-search-state.tsx`). +- `lib/`: Shared utilities and logic layer: + - `env.ts`: Zod environment variable validation schema. + - `error-reporting.ts`: Centralized error reporting abstraction. + - `json-ld.ts`: Safe JSON-LD schema serialization for SEO. +- `layout.tsx`: Root application layout with fonts, providers, skip-to-content link, and Vercel analytics. +- `page.tsx`: Landing page with Hero, Features, and structured metadata. +- `globals.css`: Tailwind CSS v4 `@theme` configuration and CSS variables. +- `error.tsx`: Root error boundary for runtime exceptions. +- `not-found.tsx`: Custom 404 page. +- `robots.ts` & `sitemap.ts`: Dynamic SEO routes. +- `icon.png`: Application favicon and app icon. + diff --git a/docs/content/guides/_meta.js b/docs/content/guides/_meta.js index c4a17f9..e52a8c7 100644 --- a/docs/content/guides/_meta.js +++ b/docs/content/guides/_meta.js @@ -2,7 +2,7 @@ export default { "index": "Overview", "adding-a-page": "Adding a Page", "adding-a-component": "Adding a Component", - "adding-a-shortcut": "Adding a Shortcut", "dark-mode": "Dark Mode", + "error-handling": "Error Handling", "testing": "Testing" } \ No newline at end of file diff --git a/docs/content/guides/adding-a-component.mdx b/docs/content/guides/adding-a-component.mdx index 305c804..f6c2b98 100644 --- a/docs/content/guides/adding-a-component.mdx +++ b/docs/content/guides/adding-a-component.mdx @@ -1,20 +1,58 @@ # Adding a Component -Reusable components live in `app/components/`. +Reusable UI components live in `app/components/`. -1. **Create directory**: `app/components/NewComponent/`. -2. **Create implementation**: `app/components/NewComponent/index.tsx`. -3. **Define Props**: Use an `interface` for props. -4. **Export**: Export the component. +## Component Guidelines + +1. **Directory Structure**: Create a dedicated directory: `app/components/ComponentName/`. +2. **Implementation**: Implement the component in `app/components/ComponentName/index.tsx`. +3. **Props Typing**: Always declare explicit TypeScript `interface` types for component props (no `any`). +4. **HeroUI v3**: Use compound component dot notation (e.g. ``, ``) and accessible interactive primitives. +5. **Icons**: Use named imports from `lucide-react` or `@icons-pack/react-simple-icons` with Tailwind `size-*` or `h-* w-*` classes. +6. **Server vs. Client**: Keep components as Server Components by default. Add `"use client"` only when managing state, effects, or browser events. +7. **Unit Testing**: Add a corresponding unit test file under `tests/unit/components/ComponentName/index.test.tsx`. + +## Example Component ```tsx -interface NewComponentProps { - label: string; +import { Card } from "@heroui/react"; +import { Sparkles } from "lucide-react"; + +interface InfoCardProps { + title: string; + description: string; +} + +export function InfoCard({ title, description }: InfoCardProps) { + return ( + + + + +

{description}

+ + + ); } +``` + +## Adding Unit Tests + +Create `tests/unit/components/InfoCard/index.test.tsx`: + +```tsx +import { render, screen } from "@testing-library/react"; +import { describe, expect, it } from "vitest"; +import { InfoCard } from "@/components/InfoCard"; -export const NewComponent = ({ label }: NewComponentProps) => { - return
{label}
; -}; +describe("InfoCard", () => { + it("renders title and description", () => { + render(); + expect(screen.getByText("Test Title")).toBeInTheDocument(); + expect(screen.getByText("Test Description")).toBeInTheDocument(); + }); +}); ``` -Remember to add TSDoc comments to public exports. diff --git a/docs/content/guides/adding-a-shortcut.mdx b/docs/content/guides/adding-a-shortcut.mdx deleted file mode 100644 index cd7258c..0000000 --- a/docs/content/guides/adding-a-shortcut.mdx +++ /dev/null @@ -1,15 +0,0 @@ -# Adding a Shortcut - -Keyboard shortcuts are centralized in `app/config/shortcuts.ts`. - -1. **Register shortcut**: Add a new entry to the `shortcuts` object. -2. **Update UI Hint**: Use the `` component to show the key combination to users. -3. **Implement Logic**: Use the `useShortcuts` hook or similar mechanism to trigger actions. - -```typescript -export const shortcuts = { - SEARCH: { key: 'k', meta: true, label: 'Search' }, - HELP: { key: '?', label: 'Open Help' }, - // Add your new shortcut here -}; -``` diff --git a/docs/content/guides/dark-mode.mdx b/docs/content/guides/dark-mode.mdx index 82bca23..9c99f35 100644 --- a/docs/content/guides/dark-mode.mdx +++ b/docs/content/guides/dark-mode.mdx @@ -1,16 +1,47 @@ # Dark Mode -Cur8d supports light and dark modes out of the box using `next-themes`. +Cur8d provides system-aware light and dark mode out of the box using `next-themes` and Tailwind CSS v4 variables. -## Usage +## Architecture -- **Theme Toggle**: The `` component in the navbar allows users to switch themes manually. -- **System Preference**: By default, the application respects the user's system theme. -- **Tailwind v4**: Use theme-aware colors and CSS variables defined in `app/globals.css`. +1. **Provider Setup**: `app/components/Providers/index.tsx` wraps the application tree in `NextThemesProvider` with `attribute="class"` and `defaultTheme="system"`. +2. **Interactive Switcher**: The `` component in the navbar gives users a one-click button with tooltips and accessible ARIA attributes to toggle between light and dark modes. +3. **Tailwind CSS v4 `@theme`**: Color tokens are mapped to standard CSS variables in `app/globals.css`, dynamically adjusting with `.dark` class changes. + +## CSS Variable Configuration + +Defined in `app/globals.css`: ```css +@import "tailwindcss"; + +@layer base { + :root { + --background: #ffffff; + --foreground: #09090b; + --muted: #f4f4f5; + --muted-foreground: #71717a; + --border: #e4e4e7; + --primary: #006fee; + } + + .dark { + --background: #09090b; + --foreground: #ededed; + --muted: #27272a; + --muted-foreground: #a1a1aa; + --border: #27272a; + --primary: #006fee; + } +} + @theme { --color-background: var(--background); --color-foreground: var(--foreground); + --color-muted: var(--muted); + --color-muted-foreground: var(--muted-foreground); + --color-border: var(--border); + --color-primary: var(--primary); } ``` + diff --git a/docs/content/guides/error-handling.mdx b/docs/content/guides/error-handling.mdx new file mode 100644 index 0000000..76ebe99 --- /dev/null +++ b/docs/content/guides/error-handling.mdx @@ -0,0 +1,44 @@ +# Error Handling & Reporting + +Cur8d includes a centralized error reporting layer and custom error boundaries for resilient user experiences. + +## Error Reporting Service + +Error tracking and diagnostics are abstracted in `app/lib/error-reporting.ts`. This provides a consistent interface whether running in development (console logging) or production (integrating with third-party observability platforms like Sentry or Datadog). + +### `reportError` + +Report runtime errors and unexpected exceptions alongside contextual metadata: + +```typescript +import { reportError } from "@/lib/error-reporting"; + +try { + await performCriticalAction(); +} catch (error) { + reportError(error, { + component: "ActionComponent", + action: "performCriticalAction", + userId: "user_123", + }); +} +``` + +### `addBreadcrumb` + +Track user actions or lifecycle events leading up to potential failures: + +```typescript +import { addBreadcrumb } from "@/lib/error-reporting"; + +addBreadcrumb({ + category: "navigation", + message: "Navigated to settings", + level: "info", +}); +``` + +## Next.js Error Boundaries + +- **`app/error.tsx`**: Client component acting as the root error boundary. Provides an accessible UI to notify users when a runtime rendering error occurs with a "Try again" action. +- **`app/not-found.tsx`**: Custom 404 page rendered when a requested resource or route does not exist. diff --git a/docs/content/guides/index.mdx b/docs/content/guides/index.mdx index 61dd128..bd6007b 100644 --- a/docs/content/guides/index.mdx +++ b/docs/content/guides/index.mdx @@ -4,6 +4,7 @@ Step-by-step guides for common tasks in cur8d. - [Adding a Page](/guides/adding-a-page) - [Adding a Component](/guides/adding-a-component) -- [Adding a Shortcut](/guides/adding-a-shortcut) - [Dark Mode](/guides/dark-mode) +- [Error Handling & Reporting](/guides/error-handling) - [Testing](/guides/testing) + diff --git a/docs/content/guides/testing.mdx b/docs/content/guides/testing.mdx index 87aaf81..ab90e2a 100644 --- a/docs/content/guides/testing.mdx +++ b/docs/content/guides/testing.mdx @@ -1,17 +1,40 @@ # Testing -We use Vitest for unit tests and Playwright for E2E tests. +Cur8d employs a dual-layered testing strategy combining Vitest for fast, isolated unit and component testing with Playwright for comprehensive End-to-End and accessibility verification. + +## Verification Pipeline + +To run the complete verification suite (linting, typechecking, and unit tests with coverage): + +```bash +mise run verify +# or using shortcut alias: +v +``` ## Unit & Component Tests (Vitest) -- Run tests: `mise run test` -- Coverage: `mise run test:coverage` -- Location: Located under `tests/unit/`, e.g., `tests/unit/components/Navbar/index.test.tsx`. +Unit tests are powered by Vitest, React Testing Library, and `@testing-library/jest-dom` using `jsdom`. + +- **Test Location**: All unit and component tests are organized in `tests/unit/` (e.g., `tests/unit/components/`, `tests/unit/app/`, `tests/unit/lib/`, `tests/unit/hooks/`). +- **Run Unit Tests**: `mise run test` (alias: `t` or `pnpm test`) +- **Interactive UI Mode**: `mise run test:ui` (or `pnpm run test:ui`) +- **Coverage Report**: `mise run test:coverage` (or `pnpm run test:coverage`) + +> [!NOTE] +> Coverage is collected using `@vitest/coverage-v8`. The repository targets a minimum 80% coverage bar across statements, branches, functions, and lines. + +## End-to-End & Accessibility Tests (Playwright) + +E2E tests run against the built Next.js application across Chromium, Firefox, and WebKit. + +- **Test Location**: `tests/e2e/` (e.g., `accessibility.spec.ts`, `navbar.spec.ts`, `theme.spec.ts`, `not-found.spec.ts`). +- **Install Browsers**: `mise run playwright:install` +- **Run E2E Tests**: `mise run test:e2e` (or `pnpm run test:e2e`) +- **Interactive Playwright UI**: `mise run test:e2e:ui` (or `pnpm run test:e2e:ui`) +- **View Last Test Report**: `pnpm run test:e2e:report` -## End-to-End Tests (Playwright) +### Accessibility Auditing -- Run tests: `mise run test:e2e` -- Interactive mode: `mise run test:e2e:ui` -- Location: `tests/e2e/`. +Automated accessibility audits are performed in E2E tests using `@axe-core/playwright` (`tests/e2e/accessibility.spec.ts`), enforcing WCAG 2.1 AA standards and WAI-ARIA compliance. -Accessibility testing is integrated into E2E tests via `@axe-core/playwright`. diff --git a/docs/content/index.mdx b/docs/content/index.mdx index e7debd8..5aa6c50 100644 --- a/docs/content/index.mdx +++ b/docs/content/index.mdx @@ -16,7 +16,8 @@ Learn how to perform common tasks: - [Adding a Page](/guides/adding-a-page) - [Adding a Component](/guides/adding-a-component) -- [Adding a Shortcut](/guides/adding-a-shortcut) +- [Dark Mode](/guides/dark-mode) +- [Error Handling & Reporting](/guides/error-handling) - [Testing](/guides/testing) ## Reference @@ -24,5 +25,6 @@ Learn how to perform common tasks: Explore the technical details: - [Components](/reference/components) -- [Shortcuts](/reference/shortcuts) +- [Utilities & Hooks](/reference/utilities) - [Workflows](/reference/workflows) + diff --git a/docs/content/reference/_meta.js b/docs/content/reference/_meta.js index 4fe6282..bd9c7b8 100644 --- a/docs/content/reference/_meta.js +++ b/docs/content/reference/_meta.js @@ -1,6 +1,6 @@ export default { - index: 'Overview', - components: 'Components', - shortcuts: 'Shortcuts', - workflows: 'Workflows' -} \ No newline at end of file + index: 'Overview', + components: 'Components', + utilities: 'Utilities & Hooks', + workflows: 'Workflows', +}; \ No newline at end of file diff --git a/docs/content/reference/components.mdx b/docs/content/reference/components.mdx index 74e1026..2e5e470 100644 --- a/docs/content/reference/components.mdx +++ b/docs/content/reference/components.mdx @@ -1,12 +1,46 @@ -# Reusable Components - -Cur8d provides several pre-built components in `app/components/`. - -- **Navbar**: Standard navigation bar with theme toggle. -- **Footer**: Branding and copyright information. -- **DataTable**: Generic table with sorting, filtering, and pagination. -- **KpiCard**: Metrics display with trend indicators. -- **SearchPalette**: Keyboard-driven command palette using `cmdk`. -- **PageHeader**: Consistent page titles and breadcrumbs. -- **ShortcutHint**: Displays keyboard shortcut hints. -- **ThemeToggle**: Switch between light and dark modes. +# Components Reference + +Cur8d provides production-ready, accessible components in `app/components/`. + +## Component Catalog + +### `` +- **Location**: `app/components/CodeSnippet/index.tsx` +- **Type**: Client Component (`"use client"`) +- **Description**: Interactive terminal/CLI command snippet box. Features one-click clipboard copying (`navigator.clipboard.writeText`), real-time tooltip feedback states ("Copied!", "Failed to copy"), dynamic icon indicators (Copy, Check, AlertCircle), keyboard accessibility, and fallback error reporting. +- **Props**: + - `code` (`string`): The command or code string to display and copy. + +### `` +- **Location**: `app/components/Features/index.tsx` +- **Type**: Server Component +- **Description**: Responsive feature showcase grid displaying key architectural highlights (Lightning Fast, Type Safe, Accessible) using HeroUI compound ``, ``, and `` components alongside `lucide-react` icons. + +### `