# WOLK Frontend

Modern React 18 SPA for WOLK file browser.

## Tech Stack

- **Framework:** React 18 + TypeScript
- **Build Tool:** Vite
- **Package Manager:** Bun
- **Routing:** TanStack Router (file-based)
- **Data Fetching:** TanStack React Query
- **State Management:** Context API + custom hooks
- **UI Components:** shadcn/ui (Radix UI + Tailwind CSS)
- **Styling:** Tailwind CSS
- **Internationalization:** i18next
- **Notifications:** react-hot-toast
- **Date Formatting:** dayjs

## Getting Started

### Prerequisites

- **Bun** >=1.0 ([install](https://bun.sh))
- **Node** >=24.0.0 (for Vite compatibility)
- **Go backend** running on `localhost:8080`

### Installation

```bash
cd frontend
bun install
```

### Development

```bash
# Start dev server (http://localhost:5173)
bun run dev

# In another terminal, start Go backend
cd ..
go run . --http :8080
```

Dev server automatically proxies `/api` to `http://localhost:8080`.

### Building

```bash
# Full build with type-checking
bun run build

# Type-check only
bun run typecheck

# Lint
bun run lint
bun run lint:fix

# Format
bun run format

# Clean dist
bun run clean
```

## Project Structure

```
src/
├── api/                    # API client modules (files, auth)
├── components/
│   ├── ui/                 # shadcn UI components
│   ├── layout/             # Header, Sidebar, LayoutShell
│   ├── files/              # File-related components
│   └── modals/             # Dialog components
├── context/                # React Context (Auth, Layout)
├── hooks/                  # Custom React hooks (useFiles, useAuth, etc.)
├── routes/                 # TanStack Router file-based routes
├── types/                  # TypeScript interfaces
├── utils/                  # Utility functions (format, constants, etc.)
├── i18n/                   # i18next translations
├── lib/                    # Library setup (QueryClient, etc.)
├── styles/                 # Global CSS
├── main.tsx                # Entry point
└── App.tsx                 # Root component
```

## Coding Standards

See `AGENTS.md` in the project root for detailed style guidelines.

### Key Patterns

**Custom Hooks (TanStack Query)**
```tsx
const { data, isPending, error } = useFiles(path);
```

**Components**
```tsx
interface FileListingProps {
  path: string;
  onFileSelect?: (file: IFile) => void;
}

export function FileListing({ path, onFileSelect }: FileListingProps) {
  // Component logic
}
```

**Routes**
```tsx
export const Route = createFileRoute("/files/$path")({
  component: FileListingPage,
  loader: async ({ params }) => {
    // Pre-fetch data
  },
});
```

**Error Handling**
```tsx
const { showError } = useToast();
try {
  await apiCall();
} catch (err) {
  if (err instanceof ApiError && err.isCanceled) return; // silent
  showError(err);
}
```

## API Client

The API client is located in `src/api/` with automatic:
- Token injection in `X-Auth` header
- Error handling with `ApiError` class
- Auto-logout on 401
- Request cancellation support

```ts
import { files as fileAPI } from "@/api";

const files = await fileAPI.fetchFiles("/documents");
```

## Translations

Translations are in `src/i18n/en.json`. To add support for more languages:

1. Create `src/i18n/{lang}.json` with translations
2. Update `src/i18n/config.ts` to include the new language

```ts
import langTranslations from "./{lang}.json";

resources: {
  {lang}: { translation: langTranslations },
}
```

## Testing

Frontend testing infrastructure is not yet configured. Future: Vitest for unit tests, Playwright for e2e.

For now, use `bun run typecheck` for type validation.

## Contributing

1. Follow the code style guidelines in `AGENTS.md`
2. Use `bun run lint:fix && bun run format` before committing
3. Ensure `bun run typecheck` passes
4. Create reusable components in `src/components/`
5. Use TanStack Query for all server state

## Resources

- [TanStack React Query](https://tanstack.com/query/latest)
- [TanStack Router](https://tanstack.com/router/latest)
- [shadcn/ui](https://ui.shadcn.com)
- [Tailwind CSS](https://tailwindcss.com)
- [i18next](https://www.i18next.com)
- [Vite](https://vitejs.dev)