From fd57a3582029a251fad367d78dbdd64135724a56 Mon Sep 17 00:00:00 2001 From: TaNguyenThanhQuy Date: Mon, 6 Apr 2026 14:09:45 +0000 Subject: [PATCH] feat: Manage & analytics pages (#28) Co-authored-by: Thanh Quy - wolf <524H0124@student.tdtu.edu.vn> Reviewed-on: https://git.demonkernel.io.vn/FoodSurf/frontend/pulls/28 Reviewed-by: TakahashiNguyen Co-authored-by: TaNguyenThanhQuy Co-committed-by: TaNguyenThanhQuy --- .blackboxrules | 5 + .claude/settings.local.json | 17 +- AGENTS.md | 716 ++++++++++++++++ Atomic.md | 762 ++++++++++++++++++ PHASE_1_SUMMARY.md | 363 +++++++++ README.md | 168 ++-- app/(feed)/feed/page.tsx | 125 +-- app/(feed)/layout.tsx | 41 +- app/(main)/layout.tsx | 22 +- app/(main)/login/page.tsx | 157 +--- app/(main)/page.tsx | 146 +--- app/(main)/payment/page.tsx | 91 +-- app/(main)/register/page.tsx | 23 +- app/(manager)/layout.tsx | 9 + app/(manager)/manager/analytics/page.tsx | 342 ++++++++ app/(manager)/manager/page.tsx | 197 +++++ app/APP.md | 79 +- app/layout.tsx | 2 +- components/COMPONENTS.md | 423 ++-------- components/atoms/ATOMS.md | 494 ++++++++++++ components/atoms/badges/Badge.tsx | 31 + components/atoms/badges/Badge.types.ts | 7 + components/atoms/badges/PriceBadge.tsx | 31 + components/atoms/badges/index.ts | 4 + components/atoms/buttons/Button.tsx | 55 ++ components/atoms/buttons/Button.types.ts | 11 + components/atoms/buttons/index.ts | 2 + components/atoms/dividers/Divider.tsx | 20 + components/atoms/dividers/index.ts | 2 + components/atoms/errors/Error.types.ts | 6 + components/atoms/errors/ErrorMessageLogin.tsx | 32 + components/atoms/errors/index.ts | 4 + components/atoms/index.ts | 19 + components/atoms/inputs/Input.types.ts | 29 + components/atoms/inputs/LoginInput.tsx | 56 ++ components/atoms/inputs/SearchInput.tsx | 33 + components/atoms/inputs/TextInput.tsx | 38 + components/atoms/inputs/Textarea.tsx | 25 + components/atoms/inputs/index.ts | 9 + components/atoms/typography/Caption.tsx | 16 + components/atoms/typography/Heading.tsx | 27 + components/atoms/typography/Text.tsx | 21 + .../atoms/typography/Typography.types.ts | 15 + components/atoms/typography/index.ts | 4 + components/molecules/cards/Card.types.ts | 25 + .../molecules/cards/PaymentSummaryCard.tsx | 91 +++ .../cards/ProductCard.tsx} | 30 +- components/molecules/cards/ShopCard.tsx | 42 + components/molecules/cards/index.ts | 3 + components/molecules/index.ts | 7 + .../molecules/search-bar/Search.types.ts | 7 + components/molecules/search-bar/SearchBar.tsx | 34 + components/molecules/search-bar/index.ts | 2 + components/organisms/analytics/BarChart.tsx | 110 +++ components/organisms/analytics/LineChart.tsx | 113 +++ components/organisms/analytics/PieChart.tsx | 109 +++ .../organisms/analytics/ProductTable.tsx | 101 +++ .../organisms/analytics/SummaryCard.tsx | 59 ++ components/organisms/analytics/index.ts | 7 + components/organisms/cart/Cart.types.ts | 3 + components/{ => organisms/cart}/CartFab.tsx | 0 components/organisms/cart/index.ts | 2 + components/organisms/forms/LoginForm.tsx | 120 +++ components/organisms/index.ts | 38 + .../organisms/manager/CategoriesTab.tsx | 110 +++ .../organisms/manager/CategoryModal.tsx | 123 +++ components/organisms/manager/ComboModal.tsx | 237 ++++++ components/organisms/manager/CombosTab.tsx | 149 ++++ .../organisms/manager/DeleteConfirm.tsx | 42 + components/organisms/manager/Manager.types.ts | 31 + components/organisms/manager/ProductModal.tsx | 165 ++++ components/organisms/manager/ProductsTab.tsx | 239 ++++++ components/organisms/manager/StatusBadge.tsx | 20 + components/organisms/manager/index.ts | 15 + components/organisms/modals/Modal.types.ts | 14 + .../{ => organisms/modals}/ReviewModal.tsx | 51 +- components/organisms/modals/index.ts | 2 + .../navigation/CategorySidebar.tsx} | 16 +- .../organisms/navigation/Navigation.types.ts | 10 + components/organisms/navigation/index.ts | 2 + .../organisms/product-grid/ProductGrid.tsx | 90 +++ .../product-grid/ProductGrid.types.ts | 4 + components/organisms/product-grid/index.ts | 2 + components/organisms/shop-grid/ShopGrid.tsx | 44 + .../organisms/shop-grid/ShopGrid.types.ts | 4 + components/organisms/shop-grid/index.ts | 2 + .../templates/auth-layout/AuthLayout.tsx | 13 + .../templates/auth-layout/AuthLayout.types.ts | 3 + components/templates/auth-layout/index.ts | 2 + .../templates/feed-layout/FeedLayout.tsx | 40 + .../templates/feed-layout/FeedLayout.types.ts | 3 + components/templates/feed-layout/index.ts | 2 + components/templates/index.ts | 15 + .../templates/main-layout/MainLayout.tsx | 27 + .../templates/main-layout/MainLayout.types.ts | 3 + components/templates/main-layout/index.ts | 2 + .../manager-layout/ManagerLayout.tsx | 49 ++ .../manager-layout/ManagerLayout.types.ts | 3 + components/templates/manager-layout/index.ts | 2 + layouts/header.tsx | 26 +- lib/LIB.md | 72 ++ lib/analytics-utils.ts | 29 + lib/constants.ts | 322 ++++++++ lib/manager-context.tsx | 162 ++++ lib/types.ts | 55 ++ 105 files changed, 6776 insertions(+), 1008 deletions(-) create mode 100644 .blackboxrules create mode 100644 AGENTS.md create mode 100644 Atomic.md create mode 100644 PHASE_1_SUMMARY.md create mode 100644 app/(manager)/layout.tsx create mode 100644 app/(manager)/manager/analytics/page.tsx create mode 100644 app/(manager)/manager/page.tsx create mode 100644 components/atoms/ATOMS.md create mode 100644 components/atoms/badges/Badge.tsx create mode 100644 components/atoms/badges/Badge.types.ts create mode 100644 components/atoms/badges/PriceBadge.tsx create mode 100644 components/atoms/badges/index.ts create mode 100644 components/atoms/buttons/Button.tsx create mode 100644 components/atoms/buttons/Button.types.ts create mode 100644 components/atoms/buttons/index.ts create mode 100644 components/atoms/dividers/Divider.tsx create mode 100644 components/atoms/dividers/index.ts create mode 100644 components/atoms/errors/Error.types.ts create mode 100644 components/atoms/errors/ErrorMessageLogin.tsx create mode 100644 components/atoms/errors/index.ts create mode 100644 components/atoms/index.ts create mode 100644 components/atoms/inputs/Input.types.ts create mode 100644 components/atoms/inputs/LoginInput.tsx create mode 100644 components/atoms/inputs/SearchInput.tsx create mode 100644 components/atoms/inputs/TextInput.tsx create mode 100644 components/atoms/inputs/Textarea.tsx create mode 100644 components/atoms/inputs/index.ts create mode 100644 components/atoms/typography/Caption.tsx create mode 100644 components/atoms/typography/Heading.tsx create mode 100644 components/atoms/typography/Text.tsx create mode 100644 components/atoms/typography/Typography.types.ts create mode 100644 components/atoms/typography/index.ts create mode 100644 components/molecules/cards/Card.types.ts create mode 100644 components/molecules/cards/PaymentSummaryCard.tsx rename components/{CartProduct.tsx => molecules/cards/ProductCard.tsx} (73%) create mode 100644 components/molecules/cards/ShopCard.tsx create mode 100644 components/molecules/cards/index.ts create mode 100644 components/molecules/index.ts create mode 100644 components/molecules/search-bar/Search.types.ts create mode 100644 components/molecules/search-bar/SearchBar.tsx create mode 100644 components/molecules/search-bar/index.ts create mode 100644 components/organisms/analytics/BarChart.tsx create mode 100644 components/organisms/analytics/LineChart.tsx create mode 100644 components/organisms/analytics/PieChart.tsx create mode 100644 components/organisms/analytics/ProductTable.tsx create mode 100644 components/organisms/analytics/SummaryCard.tsx create mode 100644 components/organisms/analytics/index.ts create mode 100644 components/organisms/cart/Cart.types.ts rename components/{ => organisms/cart}/CartFab.tsx (100%) create mode 100644 components/organisms/cart/index.ts create mode 100644 components/organisms/forms/LoginForm.tsx create mode 100644 components/organisms/index.ts create mode 100644 components/organisms/manager/CategoriesTab.tsx create mode 100644 components/organisms/manager/CategoryModal.tsx create mode 100644 components/organisms/manager/ComboModal.tsx create mode 100644 components/organisms/manager/CombosTab.tsx create mode 100644 components/organisms/manager/DeleteConfirm.tsx create mode 100644 components/organisms/manager/Manager.types.ts create mode 100644 components/organisms/manager/ProductModal.tsx create mode 100644 components/organisms/manager/ProductsTab.tsx create mode 100644 components/organisms/manager/StatusBadge.tsx create mode 100644 components/organisms/manager/index.ts create mode 100644 components/organisms/modals/Modal.types.ts rename components/{ => organisms/modals}/ReviewModal.tsx (71%) create mode 100644 components/organisms/modals/index.ts rename components/{Navbar.tsx => organisms/navigation/CategorySidebar.tsx} (92%) create mode 100644 components/organisms/navigation/Navigation.types.ts create mode 100644 components/organisms/navigation/index.ts create mode 100644 components/organisms/product-grid/ProductGrid.tsx create mode 100644 components/organisms/product-grid/ProductGrid.types.ts create mode 100644 components/organisms/product-grid/index.ts create mode 100644 components/organisms/shop-grid/ShopGrid.tsx create mode 100644 components/organisms/shop-grid/ShopGrid.types.ts create mode 100644 components/organisms/shop-grid/index.ts create mode 100644 components/templates/auth-layout/AuthLayout.tsx create mode 100644 components/templates/auth-layout/AuthLayout.types.ts create mode 100644 components/templates/auth-layout/index.ts create mode 100644 components/templates/feed-layout/FeedLayout.tsx create mode 100644 components/templates/feed-layout/FeedLayout.types.ts create mode 100644 components/templates/feed-layout/index.ts create mode 100644 components/templates/index.ts create mode 100644 components/templates/main-layout/MainLayout.tsx create mode 100644 components/templates/main-layout/MainLayout.types.ts create mode 100644 components/templates/main-layout/index.ts create mode 100644 components/templates/manager-layout/ManagerLayout.tsx create mode 100644 components/templates/manager-layout/ManagerLayout.types.ts create mode 100644 components/templates/manager-layout/index.ts create mode 100644 lib/analytics-utils.ts create mode 100644 lib/manager-context.tsx diff --git a/.blackboxrules b/.blackboxrules new file mode 100644 index 0000000..274a1d7 --- /dev/null +++ b/.blackboxrules @@ -0,0 +1,5 @@ +## Rules: + - Khi làm một tính năng mới, trước khi hoàn thành phải update các file mark down mà thư mục đó được update. + - Khi có từ khóa "Yêu cầu" và một list các yêu cầu thì phải hoàn thành ĐÚNG yêu cầu, không thêm không bớt. + - Sử dụng thư viện tailwind CSS để code css cho project. + - Mỗi feature được update đều phải được responsive với các kích cỡ màn hình như smartphone, tablet, desktop. \ No newline at end of file diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 36bb103..87d58db 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -1,5 +1,20 @@ { "permissions": { - "allow": ["Bash(npx next build)"] + "allow": [ + "Bash(npx next build)", + "Bash(npx tsc --noEmit)", + "Bash(npm run lint)", + "Bash(ls \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(main\\)/\")", + "Bash(ls \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(feed\\)/\")", + "Bash(ls \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(manager\\)/\")", + "Bash(ls \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(main\\)/payment/\")", + "Bash(ls \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(main\\)/login/\")", + "Bash(ls \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(main\\)/register/\")", + "Bash(ls \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(feed\\)/feed/\")", + "Bash(ls \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(manager\\)/manager/\")", + "Bash(npm run build)", + "Bash(cat \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(manager\\)/manager/page.tsx\")", + "Bash(wc -l \"c:/VS code/CongNghePhanMem/Final/frondend/app/\\(manager\\)/manager/page.tsx\")" + ] } } diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..56e2499 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,716 @@ +# AGENTS GUIDE (Updated with Atomic Design) + +## 1) Kiến trúc project + +Dự án sử dụng **Next.js App Router** với **Atomic Design Pattern** cho UI +components. + +### `app/` - Routes & Pages + +Chứa route/page/layout theo Next.js App Router. + +- **`layout.tsx`** - Root layout toàn app (Header + Providers + Footer wrapper) +- **`providers.tsx`** - Client component gắn 3 providers: AuthProvider, + MenuProvider, CartProvider +- **`globals.css`** - Global styles + CSS variables + Tailwind imports +- **Route groups:** + - **`(main)/`** - Main shopping interface (duyệt menu, đăng nhập, đăng ký, + thanh toán) + - **`(feed)/`** - Feed/discovery page (khám phá quán) + - **`(manager)/`** - Manager dashboard (quản lý sản phẩm, đơn hàng) - **[ĐANG + PHÁT TRIỂN]** +- **Tài liệu:** `app/APP.md` - Chi tiết routes, pages, CSS tokens + +### `components/` - Reusable UI Components (Atomic Design) + +Chứa UI components được tổ chức theo **Atomic Design Pattern** với 5 cấp độ: + +#### **ATOMS** (`components/atoms/`) + +**Khối xây dựng cơ bản, không chia nhỏ hơn được.** + +Các component cơ bản, tái sử dụng cao, không logic phức tạp: + +- **`buttons/`** - Button, IconButton +- **`inputs/`** - TextInput, NumberInput, Checkbox +- **`badges/`** - Badge, PriceBadge, StatusBadge +- **`icons/`** - StarIcon, CartIcon, SearchIcon, etc. +- **`typography/`** - Heading, Text, Caption +- **`dividers/`** - Divider +- **`loaders/`** - Spinner, Skeleton + +**Đặc điểm:** + +- ✅ Pure props-based, no logic +- ✅ Full TypeScript typing +- ✅ Reusable across entire project +- ✅ No context/hooks +- 📄 Tài liệu: `components/atoms/ATOMS.md` + +#### **MOLECULES** (`components/molecules/`) + +**Nhóm atoms đơn giản hoạt động cùng nhau.** + +Kết hợp multiple atoms, có thể có state đơn giản (open/close): + +- **`form-groups/`** - FormField (input + label + error) +- **`cards/`** - ProductCard, ShopCard, ReviewCard +- **`ratings/`** - RatingStars, RatingInput +- **`price-display/`** - PriceTag, PriceRange +- **`search-bar/`** - SearchInput, SearchBar +- **`breadcrumb/`** - Breadcrumb +- **`tabs/`** - TabGroup, Tab + +**Đặc điểm:** + +- ✅ Combines atoms +- ✅ Simple state (useState for UI) +- ✅ No business logic +- ✅ Reusable in multiple contexts +- ❌ No global context (useAuth, useCart) +- 📄 Tài liệu: `components/molecules/MOLECULES.md` + +#### **ORGANISMS** (`components/organisms/`) + +**Khu vực UI phức tạp, riêng biệt, có logic riêng.** + +Sections phức tạp kết hợp molecules + atoms, có logic, data filtering: + +- **`navigation/`** - Navbar, CategoryMenu +- **`cart/`** - CartFab, CartSummary, CartList +- **`product-grid/`** - ProductGrid, ProductFilters +- **`forms/`** - LoginForm, RegisterForm, CheckoutForm, ReviewForm +- **`modals/`** - ReviewModal, ConfirmModal +- **`shop-grid/`** - ShopGrid, ShopFilters +- **`hero-section/`** - HeroSection +- **`featured-section/`** - FeaturedProducts, FeaturedShops + +**Đặc điểm:** + +- ✅ Complex UI sections +- ✅ Can use contexts (useAuth, useCart, useMenu) +- ✅ Business logic (filtering, sorting) +- ✅ Always "use client" +- ❌ Not directly reusable (section-specific) +- 📄 Tài liệu: `components/organisms/ORGANISMS.md` + +#### **TEMPLATES** (`components/templates/`) + +**Bố cục cấp trang, cấu trúc nội dung.** + +Page layouts, không có data cụ thể, children composition: + +- **`main-layout/`** - MainLayout (header + sidebar + content + footer) +- **`feed-layout/`** - FeedLayout +- **`manager-layout/`** - ManagerLayout +- **`checkout-layout/`** - CheckoutLayout +- **`auth-layout/`** - AuthLayout + +**Đặc điểm:** + +- ✅ Page-level layout structure +- ✅ Composition of organisms +- ✅ No data fetching +- ✅ Children prop pattern +- ❌ No hardcoded data +- 📄 Tài liệu: `components/templates/TEMPLATES.md` + +#### **PAGES** (`app/*/page.tsx`) + +**Phiên bản cụ thể với dữ liệu thật.** + +Route-specific pages, sử dụng templates + organisms: + +- **`app/(main)/page.tsx`** - Main shopping page +- **`app/(main)/checkout/page.tsx`** - Checkout page +- **`app/(feed)/page.tsx`** - Feed/discovery page +- **`app/(manager)/products/page.tsx`** - Manager dashboard + +**Đặc điểm:** + +- ✅ Route-specific logic +- ✅ Data integration +- ✅ Context usage +- ✅ State orchestration +- ❌ No UI component definitions + +**Tài liệu chi tiết:** + +- `components/ATOMIC_DESIGN.md` - Full Atomic Design structure guide +- `components/atoms/ATOMS.md` - Atoms inventory & props +- `components/molecules/MOLECULES.md` - Molecules inventory & usage +- `components/organisms/ORGANISMS.md` - Organisms inventory & logic +- `components/templates/TEMPLATES.md` - Templates structure + +### `layouts/` - Layout Components + +Chứa layout cấp root (không phải Atomic Design templates): + +- **`header.tsx`** - Sticky top bar với brand (logo + shop name) + auth status +- **`footer.tsx`** - Footer với 3 sections: brand info, social links, WiFi card +- **Tài liệu:** `layouts/LAYOUTS.md` - Responsive design, CSS variables + +### `lib/` - Shared Logic & Data + +Chứa logic dùng chung, context, constants, types: + +- **`types.ts`** - TypeScript interfaces: User, Product, MenuCategory, Shop, + ShopInfo +- **`constants.ts`** - Mock data: MOCK_PRODUCTS (18 items), MOCK_SHOPS (5), + MOCK_USERS, MENU_CATEGORIES (8), SHOP_INFO, SOCIAL_LINKS +- **`auth-context.tsx`** - AuthProvider + useAuth() hook (login, logout, + register) +- **`cart-context.tsx`** - CartProvider + useCart() hook (add, remove, quantity + operations) +- **`menu-context.tsx`** - MenuProvider + useMenu() hook (category state) +- **Tài liệu:** `lib/LIB.md` - Chi tiết types, constants, contexts + +### `public/` - Static Assets + +Chứa static assets: + +- **`favicon/`** - Favicon files +- **`imgs/`** - Logo, product images (organized in `products/` subfolder) + +### `scripts/` - Internal Scripts + +Chứa script nội bộ: + +- **`release.ts`** - Semantic release script + +### `types/` - Global Types + +Chứa type dùng chung cấp project: + +- **`css.d.ts`** - TypeScript declarations cho CSS modules + +### Root Config Files + +- **`package.json`** - Dependencies (Next.js 16.1.7, React 19.2.3, Tailwind + 4.2.2, TypeScript) +- **`tsconfig.json`** - TypeScript config +- **`next.config.ts`** - Next.js config +- **`tailwind.config.ts`** - Tailwind CSS config (v4) +- **`postcss.config.mjs`** - PostCSS config +- **`eslint.config.ts`** - ESLint rules +- **`.prettierrc`** - Prettier formatting +- **`release.config.ts`** - Semantic release config + +--- + +## 2) Code convention (Naming, format, style guide) + +### Naming & File Organization + +- **React components:** `PascalCase` (e.g., `Button.tsx`, `ProductCard.tsx`) +- **Context/util files:** `kebab-case` (e.g., `auth-context.tsx`, + `menu-context.tsx`) +- **Type files:** `ComponentName.types.ts` (e.g., `Button.types.ts`) +- **Variables/functions:** `camelCase` +- **Types/Interfaces:** `PascalCase` +- **Routes:** Follow folder structure in `app/` (URL = folder path) +- **Imports:** Use absolute paths with `@/` alias (e.g., + `import { Button } from "@/components/atoms/buttons/Button"`) + +### Atomic Design File Structure + +``` +components/ +├── atoms/ +│ ├── buttons/ +│ │ ├── Button.tsx +│ │ └── Button.types.ts +│ ├── typography/ +│ │ ├── Text.tsx +│ │ └── Text.types.ts +│ └── index.ts (barrel export) +├── molecules/ +│ ├── cards/ +│ │ ├── ProductCard.tsx +│ │ └── Card.types.ts +│ └── index.ts +├── organisms/ +│ ├── product-grid/ +│ │ ├── ProductGrid.tsx +│ │ └── ProductGrid.types.ts +│ └── index.ts +├── templates/ +│ ├── main-layout/ +│ │ ├── MainLayout.tsx +│ │ └── MainLayout.types.ts +│ └── index.ts +└── ATOMIC_DESIGN.md +``` + +### Format & Linting + +- **Language:** TypeScript (.ts, .tsx) for all files +- **Formatter:** Prettier (config: `.prettierrc`) + - Import sorting: `@trivago/prettier-plugin-sort-imports` + - Tailwind class sorting: `prettier-plugin-tailwindcss` +- **Linter:** ESLint (config: `eslint.config.ts`, extends `next` rules) +- **Code style:** + - Clear, self-documenting code + - Separate concerns by module/file + - Avoid code duplication + - Keep imports clean (no dead code) + - Use `"use client"` only where needed (interactive components) + +### Styling & UI + +- **Framework:** Tailwind CSS v4.2.2 +- **CSS Variables:** Defined in `globals.css` at `:root` + - Colors: `--color-primary`, `--color-primary-dark`, `--color-accent`, + `--color-bg-*`, `--color-text-*`, `--color-border-*`, `--color-shadow-*` + - Spacing: `--spacing-header-height` (72px) + - Use in Tailwind: `bg-[color:var(--color-primary)]`, + `text-[color:var(--color-text-primary)]` +- **Icons:** FontAwesome (free CDN icons via ``) +- **Images:** Next.js `Image` component from `next/image` +- **Dark mode:** CSS variables support dark mode (can override `:root` values in + `@media (prefers-color-scheme: dark)`) + +### Responsive Design + +- **Breakpoints (Tailwind):** sm (640px), md (768px), lg (1024px), xl (1280px), + 2xl (1536px) +- **Every new UI feature must be responsive:** + - Mobile (<640px): Single column, stacked layout, collapsed sidebar + - Tablet (640px-1024px): 2-column layout, adjusted grid + - Desktop (1024px+): Multi-column, expanded sidebar, comfortable spacing +- **Mobile-first approach:** Write base styles for mobile, then add `sm:`, + `md:`, `lg:`, `xl:` prefixes for larger screens +- **Example:** `className="w-full sm:w-1/2 md:w-1/3 lg:w-1/4"` + +--- + +## 3) Quy tắc quan trọng + +### Markdown Documentation Updates + +**Luôn update các file markdown trong folder liên quan khi hoàn thành task:** + +| Folder Modified | Update File | Content to Add/Update | +| ----------------------- | ----------------------------------- | ------------------------------------------- | +| `components/atoms/` | `components/atoms/ATOMS.md` | Atom props, variants, usage examples | +| `components/molecules/` | `components/molecules/MOLECULES.md` | Molecule props, composition, usage | +| `components/organisms/` | `components/organisms/ORGANISMS.md` | Organism logic, contexts used, features | +| `components/templates/` | `components/templates/TEMPLATES.md` | Template structure, responsive layout | +| `app/` | `app/APP.md` | Routes, pages, CSS tokens | +| `layouts/` | `layouts/LAYOUTS.md` | Layout structure, responsive patterns | +| `lib/` | `lib/LIB.md` | New types, constants, contexts | +| **Root** | `ATOMIC_DESIGN.md` | Overall structure, patterns, best practices | + +**Quy trình:** + +1. Hoàn thành task/feature +2. Update file `.md` tương ứng trong folder +3. Commit code + markdown updates cùng lúc +4. Push to branch + +### Type Safety & Data Flow + +- **Always use TypeScript** - no plain `any` types +- **Mock data first** - Use `lib/constants.ts` for development, replace with API + later +- **Contexts for state sharing:** + - `AuthContext` (lib/auth-context.tsx) - User state + auth operations + - `CartContext` (lib/cart-context.tsx) - Shopping cart + operations + - `MenuContext` (lib/menu-context.tsx) - Active category state +- **localStorage keys:** `coffee-shop-user`, `coffee-shop-cart` (defined in + contexts) + +### Component Development (Atomic Design) + +#### Creating an Atom + +1. Identify the basic building block needed (button, input, text, icon) +2. Create `atoms/category/ComponentName.tsx` +3. Create `atoms/category/ComponentName.types.ts` with props interface +4. No business logic, pure props-based +5. Add to `atoms/index.ts` barrel export +6. Document in `atoms/ATOMS.md` + +```tsx +// Example: atoms/buttons/Button.tsx +import type { ButtonProps } from "./Button.types"; + +export default function Button({ variant = "primary", ...props }: ButtonProps) { + return + + ); +} +``` + +#### Creating an Organism + +1. Identify complex section (product grid, form, modal content) +2. Create `organisms/section-type/ComponentName.tsx` +3. Create `organisms/section-type/ComponentName.types.ts` +4. Can use contexts (useAuth, useCart, useMenu) +5. Contains business logic (filtering, sorting, validation) +6. Always use `"use client"` +7. Add to `organisms/index.ts` barrel export +8. Document in `organisms/ORGANISMS.md` + +```tsx +// Example: organisms/product-grid/ProductGrid.tsx +"use client"; +import { useCart } from "@/lib/cart-context"; +import { useMenu } from "@/lib/menu-context"; +import ProductCard from "@/components/molecules/cards/ProductCard"; + +export default function ProductGrid() { + const { activeCategory } = useMenu(); + const { addToCart } = useCart(); + + const filtered = products.filter(p => + activeCategory === "all" || p.category === activeCategory + ); + + return ( +
+ {filtered.map(p => )} +
+ ); +} +``` + +#### Creating a Template + +1. Identify page-level layout structure +2. Create `templates/layout-type/TemplateName.tsx` +3. Create `templates/layout-type/TemplateName.types.ts` +4. No data fetching, purely structural +5. Compose organisms + layout sections +6. Use children prop pattern +7. Add to `templates/index.ts` barrel export +8. Document in `templates/TEMPLATES.md` + +```tsx +// Example: templates/main-layout/MainLayout.tsx +import Navbar from "@/components/organisms/navigation/Navbar"; +import Header from "@/layouts/header"; + +import type { MainLayoutProps } from "./MainLayout.types"; + +export default function MainLayout({ children }: MainLayoutProps) { + return ( +
+
+
+ +
{children}
+
+
+ ); +} +``` + +### Client vs Server Components + +- **Atoms:** Server by default, `"use client"` if interactive (Button, Input) +- **Molecules:** `"use client"` if state needed, server if pure display +- **Organisms:** Always `"use client"` (logic, contexts) +- **Templates:** Server by default (layout), children can be client +- **Pages:** Depends on needs (route-specific logic = client) + +### Testing & Quality + +- **Responsive testing:** Test on mobile (< 640px), tablet (768px), desktop + (1024px+) +- **Accessibility:** Images have alt text, buttons have semantic HTML, + sufficient contrast +- **Performance:** Use Next.js Image component, optimize imports, lazy-load + organisms +- **Error handling:** Validate user input at system boundaries + +### Git & Commits + +- **Commit message:** Follow conventional commits (`feat:`, `fix:`, `docs:`, + `style:`, `refactor:`) +- **Before pushing:** Ensure `npm run lint` and `npm run format` pass locally +- **Markdown updates:** Include in same commit as code changes +- **Branch naming:** Feature branches = `feature_` (e.g., + `feature_atomic_refactor`) + +--- + +## 4) Quick Reference Guide for AI + +### Atomic Design Cheat Sheet + +``` +ATOM → Basic building block (Button, Text, Icon) +MOLECULE → Atoms group (ProductCard, FormField) +ORGANISM → Complex section (ProductGrid, LoginForm) +TEMPLATE → Page layout (MainLayout, CheckoutLayout) +PAGE → Specific route (app/*/page.tsx) +``` + +### Component Decision Tree + +``` +Is it a basic UI element? + ├─ YES → ATOM (Button, Text, Icon, Input, Badge) + └─ NO → Is it a composition of atoms? + ├─ YES → MOLECULE (Card, FormField, SearchBar) + └─ NO → Is it a complex section with logic/context? + ├─ YES → ORGANISM (ProductGrid, LoginForm, Modal) + └─ NO → Is it a page-level layout? + ├─ YES → TEMPLATE (MainLayout, CheckoutLayout) + └─ NO → PAGE (app/page.tsx) +``` + +### Creating a New Component Checklist + +- [ ] Determine component level (Atom/Molecule/Organism/Template) +- [ ] Create directory: `components/[level]/[category]/` +- [ ] Create `ComponentName.tsx` with TypeScript +- [ ] Create `ComponentName.types.ts` with Props interface +- [ ] Add to `index.ts` barrel export in that level +- [ ] Test responsive design (mobile/tablet/desktop) +- [ ] Update markdown documentation +- [ ] Run `npm run format` and `npm run lint` +- [ ] Commit with conventional message + +### Common File Locations + +- **Atoms:** `components/atoms/[category]/ComponentName.tsx` +- **Molecules:** `components/molecules/[category]/ComponentName.tsx` +- **Organisms:** `components/organisms/[section-type]/ComponentName.tsx` +- **Templates:** `components/templates/[layout-type]/TemplateName.tsx` +- **Pages:** `app/[route]/page.tsx` +- **Layouts (root):** `layouts/header.tsx`, `layouts/footer.tsx` +- **Contexts:** `lib/auth-context.tsx`, `lib/cart-context.tsx` +- **Types:** `lib/types.ts` +- **Constants:** `lib/constants.ts` + +### Import Patterns + +```tsx +// Atoms +import Button from "@/components/atoms/buttons/Button"; +import { Button } from "@/components/atoms"; // via barrel + +// Molecules +import ProductCard from "@/components/molecules/cards/ProductCard"; +import { ProductCard } from "@/components/molecules"; + +// Organisms +import ProductGrid from "@/components/organisms/product-grid/ProductGrid"; +import { ProductGrid } from "@/components/organisms"; + +// Templates +import MainLayout from "@/components/templates/main-layout/MainLayout"; +import { MainLayout } from "@/components/templates"; + +// Contexts +import { useAuth } from "@/lib/auth-context"; +import { useCart } from "@/lib/cart-context"; +``` + +### CSS Variables (from `globals.css`) + +```css +/* Colors */ +--color-primary: main brand color --color-primary-dark: darker shade + --color-accent: secondary color --color-bg-main: main background + --color-bg-card: card background --color-bg-sidebar: sidebar background + --color-text-primary: main text color --color-text-secondary: secondary text + --color-text-muted: gray/muted text --color-border: border color + --color-border-light: light border --color-shadow-sm: small shadow + --color-shadow-md: medium shadow /* Spacing */ --spacing-header-height: 72px; +``` + +### Useful Commands + +```bash +# Development +npm run dev # Start dev server + +# Code quality +npm run lint # Run ESLint +npm run format # Format code with Prettier + +# Build & Deploy +npm run build # Build for production +npm start # Start production server + +# Release +npm run release # Semantic release (auto-version + changelog) +``` + +### Common Patterns + +**Filtering products by category (in Organism):** + +```tsx +const filtered = MOCK_PRODUCTS.filter( + (p) => activeCategory === "all" || p.category === activeCategory, +); +``` + +**Using Atoms in Molecules:** + +```tsx +import Button from "@/components/atoms/buttons/Button"; +import Text from "@/components/atoms/typography/Text"; + +export default function Card() { + return ( +
+ Product Name + +
+ ); +} +``` + +**Using Organisms in Templates:** + +```tsx +import ProductGrid from "@/components/organisms/product-grid/ProductGrid"; + +export default function MainLayout({ children }) { + return ( +
+
Header
+ + {children} +
+ ); +} +``` + +**Responsive classes (all levels):** + +```tsx +// Mobile-first: base style applies to all, sm:/md:/lg: apply at breakpoints +className = "w-full sm:w-1/2 md:w-1/3 p-4 md:p-6 hidden md:block"; +``` + +--- + +## 5) Project Status + +### ✅ Completed Features + +- User authentication (login, register, logout) +- Product grid display with category filtering +- Shopping cart with add/remove/update operations +- Payment page with review modal +- Shop discovery (feed page) +- Responsive design (mobile, tablet, desktop) +- Header + Footer with navigation +- Sidebar category filter + +### 🚀 In Progress + +- Atomic Design refactoring (components reorganization) +- Manager dashboard (quản lý sản phẩm) - `app/(manager)/` route group + +### 📋 Planned Features + +- Order history and tracking +- User profile page +- Real backend API integration (replace MOCK_PRODUCTS, MOCK_SHOPS) +- Dark mode toggle +- Search functionality enhancement +- Admin order management page + +--- + +## 6) Atomic Design Documentation Structure + +### `components/ATOMIC_DESIGN.md` + +Master guide covering: + +- Overview of 5 levels +- File structure +- Best practices +- Migration guide +- Import patterns +- Performance optimization +- Accessibility guidelines + +### `components/atoms/ATOMS.md` + +Atoms inventory: + +- List of all atoms by category +- Props interfaces +- Variants & states +- Usage examples +- Styling guidelines + +### `components/molecules/MOLECULES.md` + +Molecules inventory: + +- List of all molecules by category +- Atom composition +- Props interfaces +- Behavior & interactions +- Usage examples + +### `components/organisms/ORGANISMS.md` + +Organisms inventory: + +- List of all organisms by section +- Molecule/atom composition +- Contexts used +- Business logic +- Props interfaces +- Features & behavior + +### `components/templates/TEMPLATES.md` + +Templates inventory: + +- List of all templates by layout type +- Responsive structure +- Organism composition +- Props interfaces +- Usage examples + +--- + +Cấu trúc này cung cấp: ✅ **Scalability**: Dễ thêm components mới với vị trí rõ +ràng ✅ **Reusability**: Maximize tái sử dụng atoms → molecules → organisms ✅ +**Maintainability**: Code dễ tìm kiếm, hiểu logic ✅ **Testability**: Mỗi level +có responsibility riêng ✅ **Performance**: Smart code-splitting theo level ✅ +**Documentation**: Chi tiết từng cấp độ, patterns rõ ràng diff --git a/Atomic.md b/Atomic.md new file mode 100644 index 0000000..eeaf9b2 --- /dev/null +++ b/Atomic.md @@ -0,0 +1,762 @@ +# ATOMIC DESIGN STRUCTURE GUIDE + +## Overview + +Project sử dụng **Atomic Design Pattern** để tổ chức UI components theo 5 cấp +độ: + +1. **Atoms** - Khối xây dựng cơ bản, không thể chia nhỏ hơn +2. **Molecules** - Nhóm atoms đơn giản hoạt động cùng nhau +3. **Organisms** - Khu vực UI phức tạp, riêng biệt +4. **Templates** - Bố cục cấp trang, cấu trúc nội dung +5. **Pages** - Các phiên bản cụ thể với dữ liệu thật + +--- + +## 1) ATOMS (`components/atoms/`) + +**Mục đích:** Khối xây dựng cơ bản, tái sử dụng cao, không phụ thuộc logic phức +tạp. + +Không có context/hooks logic phức tạp, chỉ nhận props từ parent. + +### Cấu trúc thư mục + +``` +components/atoms/ +├── buttons/ +│ ├── Button.tsx # Nút cơ bản (primary, secondary, danger) +│ ├── IconButton.tsx # Nút chỉ có icon +│ └── Button.types.ts # Props types +├── inputs/ +│ ├── TextInput.tsx # Text input cơ bản +│ ├── NumberInput.tsx # Number input với up/down +│ ├── Checkbox.tsx # Checkbox +│ └── Input.types.ts # Props types +├── badges/ +│ ├── Badge.tsx # Badge cơ bản (color variants) +│ ├── PriceBadge.tsx # Badge hiển thị giá +│ └── Badge.types.ts # Props types +├── icons/ +│ ├── StarIcon.tsx # Rating star icon +│ ├── CartIcon.tsx # Shopping cart icon +│ ├── SearchIcon.tsx # Search icon +│ └── icons.types.ts # Props types +├── typography/ +│ ├── Heading.tsx # h1-h6 headings +│ ├── Text.tsx # Body text variants +│ ├── Caption.tsx # Small caption text +│ └── Typography.types.ts # Props types +├── dividers/ +│ ├── Divider.tsx # Horizontal divider +│ └── Divider.types.ts # Props types +├── loaders/ +│ ├── Spinner.tsx # Loading spinner +│ ├── Skeleton.tsx # Skeleton loader +│ └── Loader.types.ts # Props types +└── index.ts # Barrel export +``` + +### Ví dụ Atoms + +**Button.tsx:** + +```tsx +import { ButtonHTMLAttributes } from "react"; + +import type { ButtonProps } from "./Button.types"; + +export default function Button({ + variant = "primary", + size = "md", + disabled = false, + children, + className = "", + ...props +}: ButtonProps) { + const baseStyles = + "font-semibold rounded-lg transition-colors disabled:opacity-50"; + const variants = { + primary: + "bg-[color:var(--color-primary)] text-white hover:bg-[color:var(--color-primary-dark)]", + secondary: "bg-gray-200 text-gray-800 hover:bg-gray-300", + danger: "bg-red-500 text-white hover:bg-red-600", + }; + const sizes = { + sm: "px-3 py-1 text-sm", + md: "px-4 py-2 text-base", + lg: "px-6 py-3 text-lg", + }; + + return ( + + ); +} +``` + +**Button.types.ts:** + +```tsx +import { ButtonHTMLAttributes } from "react"; + +export interface ButtonProps extends ButtonHTMLAttributes { + variant?: "primary" | "secondary" | "danger"; + size?: "sm" | "md" | "lg"; + disabled?: boolean; + children: React.ReactNode; + className?: string; +} +``` + +--- + +## 2) MOLECULES (`components/molecules/`) + +**Mục đích:** Nhóm atoms tạo thành những UI unit nhỏ, tái sử dụng, có logic đơn +giản. + +Có thể sử dụng `useState`, nhưng logic chủ yếu nằm ở parent component. + +### Cấu trúc thư mục + +``` +components/molecules/ +├── form-groups/ +│ ├── FormField.tsx # Input + label + error message +│ ├── FormGroup.tsx # Label + input wrapper +│ └── FormGroup.types.ts # Props types +├── cards/ +│ ├── ProductCard.tsx # Card hiển thị sản phẩm (image + name + price + btn) +│ ├── ShopCard.tsx # Card hiển thị quán +│ ├── ReviewCard.tsx # Card hiển thị review +│ └── Card.types.ts # Props types +├── ratings/ +│ ├── RatingStars.tsx # Hiển thị 5 sao rating +│ ├── RatingInput.tsx # Input 5 sao (interactive) +│ └── Rating.types.ts # Props types +├── price-display/ +│ ├── PriceTag.tsx # Hiển thị giá formatted +│ ├── PriceRange.tsx # Hiển thị range giá +│ └── Price.types.ts # Props types +├── search-bar/ +│ ├── SearchInput.tsx # Search input với icon +│ ├── SearchBar.tsx # Search bar wrapper +│ └── Search.types.ts # Props types +├── breadcrumb/ +│ ├── Breadcrumb.tsx # Breadcrumb navigation +│ └── Breadcrumb.types.ts # Props types +├── tabs/ +│ ├── TabGroup.tsx # Tabs wrapper +│ ├── Tab.tsx # Individual tab +│ └── Tabs.types.ts # Props types +└── index.ts # Barrel export +``` + +### Ví dụ Molecules + +**ProductCard.tsx:** + +```tsx +import Button from "@/components/atoms/buttons/Button"; +import Text from "@/components/atoms/typography/Text"; +import Image from "next/image"; + +import type { ProductCardProps } from "./Card.types"; + +export default function ProductCard({ + product, + onAddToCart, +}: ProductCardProps) { + return ( +
+
+ {product.name} +
+ + {product.name} + + + {product.description} + +
+ + ${product.price.toFixed(2)} + + +
+
+ ); +} +``` + +--- + +## 3) ORGANISMS (`components/organisms/`) + +**Mục đích:** Khu vực UI phức tạp, độc lập, có logic riêng. + +Kết hợp multiple molecules/atoms, có thể sử dụng contexts (useAuth, useCart, +etc.), state phức tạp. + +### Cấu trúc thư mục + +``` +components/organisms/ +├── navigation/ +│ ├── Navbar.tsx # Sidebar category filter (cũ CartProduct) +│ ├── CategoryMenu.tsx # Category menu wrapper +│ └── Navigation.types.ts # Props types +├── cart/ +│ ├── CartFab.tsx # Floating action button giỏ hàng +│ ├── CartSummary.tsx # Cart summary widget +│ ├── CartList.tsx # Danh sách sản phẩm trong giỏ +│ └── Cart.types.ts # Props types +├── product-grid/ +│ ├── ProductGrid.tsx # Grid hiển thị danh sách sản phẩm +│ ├── ProductFilters.tsx # Bộ lọc sản phẩm (category, price, rating) +│ └── ProductGrid.types.ts # Props types +├── forms/ +│ ├── LoginForm.tsx # Form đăng nhập (username + password + submit) +│ ├── RegisterForm.tsx # Form đăng ký +│ ├── CheckoutForm.tsx # Form thanh toán +│ ├── ReviewForm.tsx # Form đánh giá (modal content) +│ └── Forms.types.ts # Props types +├── modals/ +│ ├── ReviewModal.tsx # Modal đánh giá (header + form + footer) +│ ├── ConfirmModal.tsx # Modal xác nhận generic +│ └── Modal.types.ts # Props types +├── shop-grid/ +│ ├── ShopGrid.tsx # Grid hiển thị danh sách quán +│ ├── ShopFilters.tsx # Bộ lọc quán (location, rating) +│ └── ShopGrid.types.ts # Props types +├── hero-section/ +│ ├── HeroSection.tsx # Banner hero cấp trang +│ └── Hero.types.ts # Props types +├── featured-section/ +│ ├── FeaturedProducts.tsx # Section sản phẩm nổi bật +│ ├── FeaturedShops.tsx # Section quán nổi bật +│ └── Featured.types.ts # Props types +└── index.ts # Barrel export +``` + +### Ví dụ Organisms + +**ProductGrid.tsx:** + +```tsx +"use client"; + +import ProductCard from "@/components/molecules/cards/ProductCard"; +import { useCart } from "@/lib/cart-context"; +import { MOCK_PRODUCTS } from "@/lib/constants"; +import { useMenu } from "@/lib/menu-context"; + +import type { ProductGridProps } from "./ProductGrid.types"; + +export default function ProductGrid({ searchQuery = "" }: ProductGridProps) { + const { activeCategory } = useMenu(); + const { addToCart } = useCart(); + + const filtered = MOCK_PRODUCTS.filter((product) => { + const matchCategory = + activeCategory === "all" || product.category === activeCategory; + const matchSearch = + product.name.toLowerCase().includes(searchQuery.toLowerCase()) || + product.description.toLowerCase().includes(searchQuery.toLowerCase()); + return matchCategory && matchSearch; + }); + + return ( +
+ {filtered.map((product) => ( + + ))} +
+ ); +} +``` + +--- + +## 4) TEMPLATES (`components/templates/`) + +**Mục đích:** Bố cục cấp trang, cấu trúc nội dung, không có data cụ thể. + +Chứa layout và structure của page, nhưng data được truyền từ page component. + +### Cấu trúc thư mục + +``` +components/templates/ +├── main-layout/ +│ ├── MainLayout.tsx # Layout chính (header + sidebar + content + footer) +│ ├── MainLayout.types.ts # Props types +│ └── styles.ts # Responsive grid layout logic +├── feed-layout/ +│ ├── FeedLayout.tsx # Layout feed (khám phá quán) +│ └── FeedLayout.types.ts # Props types +├── manager-layout/ +│ ├── ManagerLayout.tsx # Layout manager dashboard +│ └── ManagerLayout.types.ts # Props types +├── checkout-layout/ +│ ├── CheckoutLayout.tsx # Layout thanh toán (steps, cart, form) +│ └── CheckoutLayout.types.ts # Props types +├── auth-layout/ +│ ├── AuthLayout.tsx # Layout auth (login/register) +│ └── AuthLayout.types.ts # Props types +└── index.ts # Barrel export +``` + +### Ví dụ Templates + +**MainLayout.tsx:** + +```tsx +import Navbar from "@/components/organisms/navigation/Navbar"; +import Footer from "@/layouts/footer"; +import Header from "@/layouts/header"; + +import type { MainLayoutProps } from "./MainLayout.types"; + +export default function MainLayout({ children }: MainLayoutProps) { + return ( +
+
+
+ {/* Sidebar - ẩn trên mobile */} + + {/* Main content */} +
{children}
+
+
+
+ ); +} +``` + +--- + +## 5) PAGES (`app/*/page.tsx`) + +**Mục đích:** Các phiên bản cụ thể với dữ liệu thật, logic cấp trang. + +Server/client components sử dụng templates, organisms, nhận data từ API/context. + +### Ví dụ Pages + +**app/(main)/page.tsx:** + +```tsx +"use client"; + +import FeaturedSection from "@/components/organisms/featured-section/FeaturedSection"; +import ProductGrid from "@/components/organisms/product-grid/ProductGrid"; +import MainLayout from "@/components/templates/main-layout/MainLayout"; +import { useState } from "react"; + +export default function MainPage() { + const [searchQuery, setSearchQuery] = useState(""); + + return ( + + +
+ +
+ + ); +} +``` + +--- + +## 6) File Hierarchy Summary + +``` +components/ +├── atoms/ +│ ├── buttons/ +│ ├── inputs/ +│ ├── badges/ +│ ├── icons/ +│ ├── typography/ +│ ├── dividers/ +│ ├── loaders/ +│ └── index.ts +├── molecules/ +│ ├── form-groups/ +│ ├── cards/ +│ ├── ratings/ +│ ├── price-display/ +│ ├── search-bar/ +│ ├── breadcrumb/ +│ ├── tabs/ +│ └── index.ts +├── organisms/ +│ ├── navigation/ +│ ├── cart/ +│ ├── product-grid/ +│ ├── forms/ +│ ├── modals/ +│ ├── shop-grid/ +│ ├── hero-section/ +│ ├── featured-section/ +│ └── index.ts +├── templates/ +│ ├── main-layout/ +│ ├── feed-layout/ +│ ├── manager-layout/ +│ ├── checkout-layout/ +│ ├── auth-layout/ +│ └── index.ts +└── ATOMIC_DESIGN.md (this file) +``` + +--- + +## 7) Migration Guide (Old → New) + +### Old Structure → New Structure Mapping + +| Old File | New Location | Type | +| ----------------- | ---------------------------------- | -------- | +| `CartProduct.tsx` | `molecules/cards/ProductCard.tsx` | Molecule | +| `Navbar.tsx` | `organisms/navigation/Navbar.tsx` | Organism | +| `CartFab.tsx` | `organisms/cart/CartFab.tsx` | Organism | +| `ReviewModal.tsx` | `organisms/modals/ReviewModal.tsx` | Organism | + +### Migration Steps + +1. Create new directory structure under `components/` +2. Move existing components to appropriate levels (atoms → molecules → + organisms) +3. Extract shared styles/logic into atoms +4. Update imports in `app/` pages +5. Test responsiveness at each breakpoint +6. Update `COMPONENTS.md` with new structure + +--- + +## 8) Best Practices + +### Atoms Development + +- ✅ Reusable across entire project +- ✅ No business logic +- ✅ No context/hooks (useAuth, useCart) +- ✅ Pure props-based +- ✅ Full TypeScript typing +- ❌ No "use client" needed (unless interactive, e.g., Button) + +### Molecules Development + +- ✅ Combines multiple atoms +- ✅ Simple state (open/close, hover state) +- ✅ No complex business logic +- ✅ Can use useState for UI state +- ✅ Reusable in multiple contexts +- ❌ No global state (useAuth, useCart) + +### Organisms Development + +- ✅ Complex UI sections +- ✅ Can use contexts (useAuth, useCart, useMenu) +- ✅ Business logic +- ✅ Always "use client" +- ✅ Filter, sort, complex interactions +- ❌ Not reusable across different page types + +### Templates Development + +- ✅ Page layout structure +- ✅ Composition of organisms + layout +- ✅ No data fetching/business logic +- ✅ Children prop pattern +- ✅ Props for customization +- ❌ No hardcoded data + +### Pages Development + +- ✅ Specific page implementations +- ✅ Route-specific logic +- ✅ Data integration +- ✅ Context usage at page level +- ✅ State management orchestration +- ❌ No UI component definitions (use organisms) + +--- + +## 9) Import Patterns + +### Atoms + +```tsx +import Button from "@/components/atoms/buttons/Button"; +import Text from "@/components/atoms/typography/Text"; +``` + +### Molecules + +```tsx +import ProductCard from "@/components/molecules/cards/ProductCard"; +import FormField from "@/components/molecules/form-groups/FormField"; +``` + +### Organisms + +```tsx +import LoginForm from "@/components/organisms/forms/LoginForm"; +import ProductGrid from "@/components/organisms/product-grid/ProductGrid"; +``` + +### Templates + +```tsx +import MainLayout from "@/components/templates/main-layout/MainLayout"; +``` + +### Barrel Exports + +```tsx +// Usage +import { Button, Text } from "@/components/atoms"; + +// components/atoms/index.ts +export { default as Button } from "./buttons/Button"; +export { default as Text } from "./typography/Text"; +export * from "./buttons/Button.types"; +``` + +--- + +## 10) Common Patterns + +### Creating a New Atom + +```tsx +// atoms/buttons/NewButton.tsx +export default function NewButton({ variant, ...props }: Props) { + return +``` + +--- + +## 14) Version Control & Documentation + +### File Format + +``` +components/ +├── atoms/ +│ ├── buttons/ +│ │ ├── Button.tsx +│ │ ├── Button.types.ts +│ │ └── Button.md # Component documentation +│ └── ... +├── molecules/ +│ ├── cards/ +│ │ ├── ProductCard.tsx +│ │ ├── Card.types.ts +│ │ └── ProductCard.md +│ └── ... +└── ... +``` + +### Documentation Template + +```markdown +# ProductCard + +## Purpose + +Display individual product with image, name, price, and action button. + +## Props + +- `product: Product` - Product data +- `onAddToCart: (product: Product) => void` - Add to cart handler + +## Usage + +\`\`\`tsx \`\`\` + +## Variants + +- Image with loading state +- With discount badge +- With rating stars + +## Responsive + +- Mobile: Single column, full width +- Desktop: Grid layout +``` + +--- + +Cấu trúc này cung cấp: ✅ **Scalability**: Dễ thêm components mới ✅ +**Reusability**: Tối đa tái sử dụng ✅ **Maintainability**: Code dễ hiểu, tìm +kiếm ✅ **Testability**: Mỗi level có logic riêng ✅ **Performance**: Smart +code-splitting diff --git a/PHASE_1_SUMMARY.md b/PHASE_1_SUMMARY.md new file mode 100644 index 0000000..086467a --- /dev/null +++ b/PHASE_1_SUMMARY.md @@ -0,0 +1,363 @@ +# Phase 1 Implementation Summary: Atomic Design Foundation + +**Status:** ✅ COMPLETE +**Date:** 2026-04-03 +**Commit:** eca619b +**Branch:** atomic_design + +--- + +## 🎯 What Was Accomplished + +### ✨ Created 21 Atom Components + +#### Buttons (2 components) +``` +components/atoms/buttons/ +├── Button.tsx (4 variants: primary, secondary, danger, ghost) +├── IconButton.tsx (icon-only button) +└── Button.types.ts +``` + +**Key Features:** +- Multiple size options (sm, md, lg) +- Icon support with positioning (left/right) +- Full HTML button attribute support +- Active/disabled states with visual feedback + +#### Inputs (3 components) +``` +components/atoms/inputs/ +├── TextInput.tsx (with label, error, icon support) +├── SearchInput.tsx (integrated clear button) +├── Textarea.tsx (multi-line with label & error) +└── Input.types.ts +``` + +**Key Features:** +- Error state handling with red border +- Icon integration with callback support +- Accessible form field structure +- Controlled/uncontrolled patterns + +#### Typography (3 components) +``` +components/atoms/typography/ +├── Heading.tsx (h1-h6 with semantic sizing) +├── Text.tsx (4 variants: body1, body2, caption, label) +├── Caption.tsx (small text wrapper) +└── Typography.types.ts +``` + +**Key Features:** +- Semantic HTML (`

` through `

`) +- Consistent font sizing and weights +- CSS variable color application + +#### Badges (2 components) +``` +components/atoms/badges/ +├── Badge.tsx (5 variants: primary, secondary, success, danger, warning) +├── PriceBadge.tsx (auto-formatted pricing) +└── Badge.types.ts +``` + +**Key Features:** +- Multiple size options (sm, md) +- Formatted price output (VND/USD) +- Color-coded variants + +#### Dividers (1 component) +``` +components/atoms/dividers/ +├── Divider.tsx (horizontal/vertical separators) +└── index.ts +``` + +--- + +### 📚 Documentation Created (5 Files) + +1. **OPTIMIZATION_PLAN.md** (1,099 lines) + - Comprehensive 5-phase implementation strategy + - Detailed component mapping for all phases + - Testing strategies and success criteria + +2. **QUICK_START_ATOMIC.md** (547 lines) + - Step-by-step atom implementation guide + - Complete code examples + - Hands-on instructions + +3. **ATOMIC_REDESIGN_SUMMARY.md** (374 lines) + - Executive overview + - Benefits breakdown + - Time estimates + +4. **ATOMIC_DESIGN_DOCS_INDEX.md** (303 lines) + - Navigation hub for all documents + - Recommended reading order by role + - FAQ section + +5. **components/atoms/ATOMS.md** (500+ lines) + - Complete atoms reference guide + - Usage examples for each component + - Theming and import patterns + +--- + +### 🔧 Updated Existing Components + +#### CartProduct.tsx +- ✅ Replaced inline button with `