initial commit

2026-01-14 06:12:55 +01:00
commit d702390660
46 changed files with 21386 additions and 0 deletions
@@ -0,0 +1,177 @@
+# Agent Instructions for Next.js + Mantine Project
+
+This document provides context, rules, and workflows for AI agents operating in this codebase.
+
+## 1. Project Overview & Commands
+
+### Core Scripts
+
+The project uses `npm` for dependency management and script execution.
+
+- **Development Server:** `npm run dev`
+  - Starts the Next.js development server on port 3000.
+- **Production Build:** `npm run build`
+  - Creates an optimized production build.
+- **Start Production:** `npm run start`
+  - Runs the built application in production mode.
+- **Type Check:** `npm run typecheck`
+  - Runs TypeScript compiler (`tsc`) without emitting files to verify types.
+- **Storybook:** `npm run storybook`
+  - Launches the Storybook UI environment for component development.
+
+### Linting & Formatting
+
+Always ensure code passes these checks before submitting changes.
+
+- **Lint All:** `npm run lint` (Runs ESLint and Stylelint)
+- **ESLint:** `npm run eslint` (Checks JavaScript/TypeScript rules)
+- **Stylelint:** `npm run stylelint` (Checks CSS/SCSS modules)
+- **Prettier Check:** `npm run prettier:check` (Verifies formatting)
+- **Prettier Fix:** `npm run prettier:write` (Fixes formatting issues automatically)
+
+### Testing
+
+- **Run All Checks:** `npm test`
+  - Comprehensive check: typegen, prettier, lint, typecheck, and unit tests.
+- **Run Unit Tests:** `npm run jest`
+  - Runs the Jest test suite.
+- **Run Single Test File:** `npm run jest -- components/MyComponent/MyComponent.test.tsx`
+  - **Critical:** Use this when working on a specific component to save time.
+- **Watch Mode:** `npm run jest:watch`
+
+## 2. Architecture & File Structure
+
+### Directory Layout
+
+```text
+.
+├── app/                  # Next.js App Router pages and layouts
+├── components/           # Shared React components (Atomic design preferred)
+│   └── Feature/          # Feature-specific directory
+│       ├── Feature.tsx        # Main component file
+│       ├── Feature.module.css # CSS Modules
+│       ├── Feature.story.tsx  # Storybook file
+│       └── Feature.test.tsx   # Jest test file
+├── public/               # Static assets (images, fonts, etc.)
+├── theme.ts              # Mantine theme overrides and configuration
+└── ...config files
+```
+
+### Framework Conventions
+
+- **Next.js App Router:**
+  - Use `page.tsx` for routes.
+  - Use `layout.tsx` for wrapping pages.
+  - default to **Server Components**.
+  - Add `'use client';` at the very top of the file only when interactivity (hooks, event listeners) is required.
+- **Mantine UI:**
+  - Use `@mantine/core` components for structure (`Stack`, `Group`, `Grid`) instead of raw `div`s with CSS flexbox.
+  - Use `rem` functions for sizing to respect user settings.
+
+## 3. Code Style & Standards
+
+### TypeScript
+
+- **Strict Mode:** Enabled. No implicit `any`.
+- **Interfaces:** Prefer `interface` over `type` for object definitions.
+- **Props:** Define a specific interface for component props, exported if reusable.
+  ```typescript
+  export interface MyComponentProps {
+    title: string;
+    isActive?: boolean;
+  }
+  ```
+
+### Naming Conventions
+
+- **Components:** `PascalCase` (e.g., `UserProfile.tsx`).
+- **Functions/Hooks:** `camelCase` (e.g., `useAuth`, `handleSubmit`).
+- **CSS Modules:** `camelCase` for class names.
+  ```css
+  /* styles.module.css */
+  .container { ... } /* Good */
+  .user-card { ... } /* Avoid kebab-case in modules if possible for dot notation access */
+  ```
+- **Tests:** `ComponentName.test.tsx`.
+
+### Imports
+
+- **Path Aliases:** Always use `@/` to refer to the project root.
+  - `import { Button } from '@mantine/core';`
+  - `import { MyComp } from '@/components/MyComp';`
+- **Sorting:** Imports are automatically sorted. Run `npm run prettier:write` if the linter complains.
+
+## 4. Component Development Workflow
+
+When creating or modifying a component (e.g., `UserProfile`), follow this checklist:
+
+1.  **Scaffold Files:**
+    - `UserProfile.tsx`
+    - `UserProfile.module.css`
+    - `UserProfile.test.tsx`
+    - `UserProfile.story.tsx`
+2.  **Implementation:**
+    - Define strict Props interface.
+    - Use Mantine components for layout.
+    - Use CSS Modules for custom styling not covered by Mantine props.
+3.  **Theming:**
+    - Use `theme` object from Mantine for colors/spacing.
+    - Support light/dark mode using Mantine's mixins or standard CSS variables if needed.
+4.  **Testing:**
+    - Write a basic render test.
+    - Test user interactions (clicks, inputs) using `@testing-library/user-event`.
+    - Ensure accessibility (`aria-` attributes) if creating custom interactive elements.
+5.  **Storybook:**
+    - Create a basic story to visualize the component in isolation.
+
+## 5. Testing & Verification
+
+### Jest & React Testing Library
+
+- **Queries:** Prioritize accessibility-based queries:
+  1.  `getByRole` (buttons, links, headings)
+  2.  `getByLabelText` (form inputs)
+  3.  `getByText` (non-interactive content)
+  4.  `getByTestId` (last resort)
+- **Mocking:**
+  - Mock external modules utilizing `jest.mock`.
+  - Use `jest.setup.cjs` for global mocks if needed (like `window.matchMedia`).
+
+### Example Test Pattern
+
+```tsx
+import { render, screen } from '@/test-utils'; // Use project test-utils if available
+import { MyComponent } from './MyComponent';
+
+describe('MyComponent', () => {
+  it('renders correctly', () => {
+    render(<MyComponent title="Test" />);
+    expect(screen.getByRole('heading', { name: /test/i })).toBeInTheDocument();
+  });
+});
+```
+
+## 6. Error Handling & Best Practices
+
+- **Async/Await:** Use `try/catch` blocks for API calls.
+- **Validation:** Use `zod` if installed for schema validation, otherwise use strict TypeScript checks.
+- **Accessibility:**
+  - Ensure all `img` tags have `alt` text.
+  - Ensure buttons have discernible text or `aria-label`.
+  - Verify contrast ratios using the Storybook accessibility addon if available.
+- **Performance:**
+  - Use `next/image` for images.
+  - Avoid heavy computations in render cycles; use `useMemo` sparingly and only when proven necessary.
+
+## 7. Troubleshooting
+
+- **Style Issues:** If styles aren't applying, check if `postcss.config.cjs` is correctly processing the file and that the class is applied via `className={classes.myClass}`.
+- **Hydration Errors:** Ensure HTML structure is valid (no `div` inside `p`) and that the server/client output matches. Use `useEffect` for browser-only rendering if needed.
+- **Test Failures:** If `jest` fails on imports, check `jest.config.cjs` for `moduleNameMapper` settings matching `tsconfig.json` paths.
+
+## 8. Documentation & External Resources
+
+- **Mantine Documentation:**
+  - **CRITICAL:** When implementing Mantine components or features, you MUST refer to the official AI-optimized documentation.
+  - **URL:** [https://mantine.dev/llms.txt](https://mantine.dev/llms.txt)
+  - Use the `WebFetch` tool to retrieve the latest patterns and examples from this URL if you are unsure about the implementation details or best practices for the current version.