xertica-ui 2.3.0 → 2.4.1

package/docs/components/pages.md

@@ -1,309 +1,323 @@
-# 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.
+# 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.