# AGENTS.md

This file contains guidelines and commands for agentic coding agents working in this repository.

## Build/Lint/Test Commands

```bash
# Development
npm run dev                    # Start development server (Next.js)

# Build & Production
npm run build                  # Build for production
npm run start                  # Start production server

# Code Quality
npm run lint                   # Run ESLint
```

**Note**: This project does not have test commands configured. If tests are added, update the scripts in package.json.

## Project Architecture

This is a **Next.js 16** application with **TypeScript** that serves as a dashboard for Dolibarr project management. The app uses:

- **UI Framework**: shadcn/ui components with Radix UI primitives
- **Styling**: Tailwind CSS with custom design system
- **State Management**: React hooks and context
- **API Integration**: Custom Dolibarr client
- **Icons**: Lucide React

## Code Style Guidelines

### Imports & Dependencies

```typescript
// 1. React imports first
import React from "react";
import { forwardRef } from "react";

// 2. Third-party libraries (alphabetical)
import { cva, type VariantProps } from "class-variance-authority";
import { Slot } from "@radix-ui/react-slot";

// 3. Internal imports (use @/ aliases)
import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import { Project } from "@/types/project";
```

### Component Structure

```typescript
"use client"; // Add for client components

// Imports
import { ComponentProps } from "react";

// Types/Interfaces
interface ComponentProps {
  // props here
}

// Helper functions (if any)
function helper() {
  // implementation
}

// Main component
export default function Component({ prop }: ComponentProps) {
  // implementation
}
```

### TypeScript Guidelines

- **Always use types** for props, function parameters, and return values
- **Prefer interfaces** for object shapes, types for unions/primitives
- **Use generic types** when appropriate: `React.FC<Props>`, `VariantProps<T>`
- **Strict mode enabled** - no implicit `any`

### Naming Conventions

- **Components**: PascalCase (`ProjectCard`, `DashboardHeader`)
- **Functions**: camelCase (`getInitials`, `mapDolibarrProject`)
- **Constants**: UPPER_SNAKE_CASE (`STATUS_CONFIG`, `API_BASE_URL`)
- **Files**: kebab-case (`project-card.tsx`, `dolibarr-client.ts`)
- **Types**: PascalCase with descriptive suffixes (`ProjectStatus`, `DolibarrProject`)

### shadcn/ui Component Patterns

```typescript
// Use cva for variant styling
const buttonVariants = cva(
  "base-classes",
  {
    variants: {
      variant: {
        default: "variant-classes",
        // other variants
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
);

// Forward ref for composable components
const Component = forwardRef<HTMLDivElement, ComponentProps>(
  ({ className, ...props }, ref) => {
    return (
      <div
        className={cn(variantClasses, className)}
        ref={ref}
        {...props}
      />
    );
  }
);
Component.displayName = "Component";
```

### Styling Guidelines

- **Use Tailwind classes** for all styling
- **Utility-first approach** - avoid custom CSS when possible
- **Responsive design**: `sm:`, `md:`, `lg:`, `xl:` prefixes
- **State styling**: `hover:`, `focus:`, `disabled:` prefixes
- **Use cn() utility** for conditional class merging
- **Design tokens**: Use CSS custom properties from `globals.css`

### Error Handling

```typescript
// API calls - throw errors, handle at call site
export async function apiCall() {
  const res = await fetch(url);
  if (!res.ok) {
    console.error("API Error:", res.status, await res.text());
    throw new Error("API request failed");
  }
  return res.json();
}

// Components - handle errors gracefully
try {
  const data = await apiCall();
  // render data
} catch (error) {
  console.error("Failed to load data:", error);
  // render error state or fallback
}
```

### File Organization

```
src/
├── app/                 # Next.js app router
├── components/         # React components
│   ├── ui/            # shadcn/ui components
│   └── dashboard/     # Feature components
├── hooks/             # Custom React hooks
├── lib/               # Utilities, API clients
├── types/             # TypeScript type definitions
└── public/            # Static assets
```

### Path Aliases

Use these configured path aliases:
- `@/components` → `./components`
- `@/lib` → `./lib`
- `@/hooks` → `./hooks`
- `@/utils` → `./lib/utils`
- `@/ui` → `./components/ui`

### API Integration

- **Environment variables**: Use `NEXT_PUBLIC_*` for client-side access
- **Dolibarr client**: Use `dolibarrFetch()` from `@/lib/dolibarrClient`
- **Data transformation**: Map API responses to UI types using helper functions
- **Error boundaries**: Implement error handling for API failures

### Performance Guidelines

- **Dynamic imports**: Use `next/dynamic` for heavy components
- **Image optimization**: Use Next.js Image component
- **Bundle analysis**: Check bundle size with `npm run build`
- **Memoization**: Use `React.memo()` for expensive components

### Accessibility

- **Semantic HTML**: Use appropriate elements (`<button>`, `<nav>`, etc.)
- **ARIA attributes**: Add when needed for screen readers
- **Keyboard navigation**: Ensure all interactive elements are keyboard accessible
- **Focus management**: Handle focus in modals and dropdowns

## Development Workflow

1. **Start development**: `npm run dev`
2. **Run linter**: `npm run lint` (fix any errors before committing)
3. **Build test**: `npm run build` (ensure production build works)
4. **Type checking**: TypeScript is strict - fix all type errors

## Key Dependencies

- **Next.js**: 16.0.7 (App Router)
- **React**: 19.2.0
- **TypeScript**: 5.x
- **Tailwind CSS**: 3.4.18 + tailwindcss-animate
- **Radix UI**: Headless components for accessibility
- **Lucide React**: Icon library
- **shadcn/ui**: Component library built on Radix UI

## Environment Variables

Required environment variables (create `.env.local`):
- `NEXT_PUBLIC_API_URL` - Dolibarr API base URL
- `NEXT_PUBLIC_DOLIBARR_API_KEY` - Dolibarr API key

## Testing

No test framework is currently configured. Recommended setup:
- Add Jest/Vitest for unit tests
- Add React Testing Library for component tests
- Add Playwright/Cypress for E2E tests
- Update package.json with test scripts