# Page Templates — Xertica UI

Xertica UI ships 8 ready-to-use page templates covering authentication flows, the main dashboard shell, and a fully-featured component showcase. All templates are exported from `xertica-ui/pages`.

---

## Import

```tsx
import {
  LoginPage,
  ForgotPasswordPage,
  ResetPasswordPage,
  VerifyEmailPage,
  HomePage,
  HomeContent,
  TemplatePage,
  TemplateContent,
} from 'xertica-ui/pages';
```

---

## Authentication Pages

### `LoginPage`

A complete, responsive login screen with a hero image side-panel (desktop) and a focused authentication form.

**Features:**

- Email + password form with validation
- Loading state during submission
- Error message display
- Social/SSO provider placeholders (Google, MT Login, gov.br)
- Language selector (`LanguageSelector`)
- Xertica logo
- Link to forgot-password flow (via `react-router-dom`)

**Props:**

| Prop      | Type                                           | Description                                                                 |
| --------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
| `onLogin` | `(email: string, password: string) => boolean` | Authentication handler. Return `true` on success, `false` to show an error. |

**Usage:**

```tsx
import { LoginPage } from 'xertica-ui/pages';
import { useNavigate } from 'react-router-dom';

function AuthRoute() {
  const navigate = useNavigate();

  const handleLogin = (email: string, password: string): boolean => {
    if (!email || !password) return false;
    // call your auth API here
    navigate('/home');
    return true;
  };

  return <LoginPage onLogin={handleLogin} />;
}
```

---

### `ForgotPasswordPage`

A password recovery form where users enter their email to receive a reset link.

**Features:**

- Email input with validation
- Success state (shows confirmation message after submission)
- Back-to-login navigation link
- Xertica logo + hero image

**Props:**

| Prop       | Type                      | Description                                    |
| ---------- | ------------------------- | ---------------------------------------------- |
| `onSubmit` | `(email: string) => void` | Called when the user submits the recovery form |

**Usage:**

```tsx
import { ForgotPasswordPage } from 'xertica-ui/pages';

<ForgotPasswordPage
  onSubmit={email => {
    // send password reset email
    console.log('Reset requested for:', email);
  }}
/>;
```

---

### `ResetPasswordPage`

A new-password form for users arriving via a password reset link.

**Features:**

- New password + confirm password fields
- Password match validation
- Success state after reset

**Props:**

| Prop      | Type                         | Description                                             |
| --------- | ---------------------------- | ------------------------------------------------------- |
| `onReset` | `(password: string) => void` | Called with the new password when the form is submitted |

**Usage:**

```tsx
import { ResetPasswordPage } from 'xertica-ui/pages';

<ResetPasswordPage
  onReset={newPassword => {
    // call your reset API with the token from the URL
    console.log('New password:', newPassword);
  }}
/>;
```

---

### `VerifyEmailPage`

An email verification confirmation screen shown after registration.

**Features:**

- Confirmation message with email address display
- "Resend email" action
- Back-to-login link

**Props:**

| Prop       | Type         | Description                                              |
| ---------- | ------------ | -------------------------------------------------------- |
| `email`    | `string`     | The email address to display in the confirmation message |
| `onResend` | `() => void` | Called when the user clicks "Resend verification email"  |

**Usage:**

```tsx
import { VerifyEmailPage } from 'xertica-ui/pages';

<VerifyEmailPage
  email="user@example.com"
  onResend={() => {
    // resend verification email
  }}
/>;
```

---

## Dashboard Pages

### `HomePage`

The root dashboard page. Assembles `Sidebar`, `HomeContent`, and `XerticaAssistant` into a full-screen layout.

**Features:**

- Full-screen `h-screen` layout with sidebar + main content + assistant
- Integrates `LayoutContext` for synchronized sidebar/assistant state
- Auth state from `useAuth()` — **no `user` or `onLogout` props needed**
- `XerticaAssistant` config (suggestions, feedback options) fetched via `useAssistantConfig()` (React Query)

**Props:** none — all state consumed from `AuthContext` and React Query.

**Usage:**

```tsx
import { HomePage } from 'xertica-ui/pages';

// Inside <AuthProvider> and <QueryClientProvider>
<Route
  path="/home"
  element={
    <ProtectedRoute>
      <HomePage />
    </ProtectedRoute>
  }
/>;
```

> **Note**: `HomePage` uses `react-router-dom` hooks internally. It must be rendered inside a `<BrowserRouter>` (or equivalent) and inside `<AuthProvider>`.

---

### `HomeContent`

The main content area of the dashboard. Feature cards are fetched via `useFeatureCards()` (React Query) — no hardcoded data.

**Features:**

- `Header` with breadcrumbs, theme toggle, and language selector
- Feature card grid — data from `features/home/hooks/useFeatureCards.ts`
- Skeleton loading state while query is in-flight

**Props:** none — layout from `useLayout()`, data from React Query.

**Usage:**

```tsx
import { HomeContent } from 'xertica-ui/pages';

// Self-contained — no props required
<HomeContent />;
```

---

### `TemplatePage`

A complete layout shell identical to `HomePage` but with `TemplateContent` as the main area. Use this as the **primary reference** for building new pages.

**Features:**

- Full-screen layout: Sidebar + TemplateContent + XerticaAssistant
- Auth state from `useAuth()` — **no props needed**
- Synchronized layout state via `LayoutContext`

**Props:** none.

**Usage:**

```tsx
import { TemplatePage } from 'xertica-ui/pages';

<Route
  path="/template"
  element={
    <ProtectedRoute>
      <TemplatePage />
    </ProtectedRoute>
  }
/>;
```

---

### `TemplateContent`

The main content area of `TemplatePage`. Contains a comprehensive showcase of all Xertica UI components.

**Features:**

- `Header` with full breadcrumb, user menu, and action buttons
- All form elements (Input, Select, Checkbox, Switch, Slider, etc.)
- Data display: Table with team members from `useTeamMembers()` (React Query)
- UI toggles (progress, slider, switch) from `useDashboardStore` (Zustand)
- Overlay components (Dialog, Sheet, Drawer, Popover, Tooltip)
- Media components (AudioPlayer, VideoPlayer)
- AI components (XerticaAssistant in full-page mode)

**Props:** none — all state from React Query hooks and Zustand store.

---

## Page Architecture Pattern

All dashboard pages follow the same three-column layout pattern:

```
┌─────────────────────────────────────────────────────┐
│  Sidebar  │         Main Content          │Assistant │
│  (fixed)  │  Header + scrollable body     │ (fixed)  │
└─────────────────────────────────────────────────────┘
```

```tsx
// Standard page shell — auth from context, data from React Query
function MyPage() {
  const { user, logout } = useAuth(); // ← no prop drilling
  const { data: myData } = useMyFeatureQuery(); // ← React Query
  const { sidebarExpanded, sidebarWidth, assistenteExpanded, toggleSidebar, toggleAssistente } =
    useLayout();
  const location = useLocation();
  const navigate = useNavigate();

  return (
    <div className="h-screen flex bg-muted overflow-hidden relative">
      <Sidebar
        expanded={sidebarExpanded}
        width={sidebarWidth}
        onToggle={toggleSidebar}
        user={{ ...user, name: 'Display Name', avatar: '...' }}
        onLogout={logout}
        location={location}
        navigate={navigate}
        routes={routes}
      />
      <MyContent data={myData} />
      <XerticaAssistant isExpanded={assistenteExpanded} onToggle={toggleAssistente} demoMode />
    </div>
  );
}
```

---

## AI Rules

> [!IMPORTANT]
>
> - **`user` and `onLogout` are NOT props on `HomePage` or `TemplatePage`**: They are consumed via `useAuth()` from `AuthContext`. Never pass `user` or `onLogout` as props to these components.
> - **Use `TemplatePage` as the reference**: When building a new page, copy the structure from `TemplatePage` — it demonstrates the correct three-column layout with synchronized state.
> - **Router dependency**: All dashboard pages use `useLocation` and `useNavigate` from `react-router-dom`. They must be rendered inside a `<BrowserRouter>`.
> - **`LayoutContext` is optional**: Pages use `useOptionalLayout()` and fall back to local state if the context is not available. This allows standalone usage in Storybook or tests.
> - **Authentication pages are standalone**: `LoginPage`, `ForgotPasswordPage`, `ResetPasswordPage`, and `VerifyEmailPage` do not use `LayoutContext` and can be rendered without `XerticaProvider`.
> - **Data comes from `features/`**: All server data (team members, stats, feature cards, assistant config) is fetched via React Query hooks in `features/*/hooks/`. Never hardcode this data in components.
> - **Do not add business logic to page shells**: Page components (`HomePage`, `TemplatePage`) are thin layout containers. Business logic and data fetching belong in `features/*/hooks/` or content components.
> - **`LoginPage` still accepts `onLogin` prop**: It is a reusable library component decoupled from `AuthContext`. Use a bridge wrapper (e.g., `LoginPageWithAuth`) that reads `useAuth().login` and passes it as `onLogin`.
> - **Wrap route entries in `<PageErrorBoundary>`**: Place `<PageErrorBoundary>` around `<Routes>` / `<AuthGuard>` so that lazy-chunk load failures and page render errors show a recoverable fallback instead of a blank screen.
> - **Wrap data-heavy sections in `<SectionErrorBoundary>`**: Any section that renders server data (tables, charts, the assistant panel) must be wrapped in `<SectionErrorBoundary>`. An error in one section must not crash the entire page.