xertica-ui 2.1.2 → 2.1.4

package/docs/components/pages.md

@@ -0,0 +1,351 @@
+# 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
+- Falls back to local state if `LayoutContext` is not available (standalone usage)
+- Pre-configured `XerticaAssistant` in demo mode with sample suggestions
+
+**Props:**
+
+| Prop | Type | Description |
+|---|---|---|
+| `user` | `{ email: string } \| null` | Currently logged-in user |
+| `onLogout` | `() => void` | Logout handler passed to the Sidebar footer |
+
+**Usage:**
+
+```tsx
+import { HomePage } from 'xertica-ui/pages';
+
+<HomePage
+  user={{ email: 'user@example.com' }}
+  onLogout={() => {
+    // clear session and redirect to login
+    navigate('/login');
+  }}
+/>
+```
+
+> **Note**: `HomePage` uses `react-router-dom` hooks internally. It must be rendered inside a `<BrowserRouter>` (or equivalent).
+
+---
+
+### `HomeContent`
+
+The main content area of the dashboard — used inside `HomePage`. Can also be used standalone to build custom page shells.
+
+**Features:**
+- `Header` with breadcrumbs, user menu, and actions
+- Stats cards row
+- Charts section
+- Recent activity table
+
+**Props:**
+
+| Prop | Type | Description |
+|---|---|---|
+| `user` | `{ email: string } \| null` | User object for the header |
+| `onLogout` | `() => void` | Logout handler |
+| `sidebarExpanded` | `boolean` | Controls header left padding |
+| `sidebarWidth` | `number` | Sidebar width in pixels |
+| `onToggleSidebar` | `() => void` | Sidebar toggle callback |
+| `onToggleAssistant` | `() => void` | Assistant toggle callback |
+
+**Usage:**
+
+```tsx
+import { HomeContent } from 'xertica-ui/pages';
+import { useLayout } from 'xertica-ui/hooks';
+
+function MyDashboard({ user, onLogout }) {
+  const { sidebarExpanded, sidebarWidth, toggleSidebar, toggleAssistente } = useLayout();
+  return (
+    <HomeContent
+      user={user}
+      onLogout={onLogout}
+      sidebarExpanded={sidebarExpanded}
+      sidebarWidth={sidebarWidth}
+      onToggleSidebar={toggleSidebar}
+      onToggleAssistant={toggleAssistente}
+    />
+  );
+}
+```
+
+---
+
+### `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 in a Xertica UI project.
+
+**Features:**
+- Full-screen layout: Sidebar + TemplateContent + XerticaAssistant
+- Synchronized layout state via `LayoutContext`
+- Demonstrates all major layout patterns
+
+**Props:**
+
+| Prop | Type | Description |
+|---|---|---|
+| `user` | `{ email: string } \| null` | Currently logged-in user |
+| `onLogout` | `() => void` | Logout handler |
+
+**Usage:**
+
+```tsx
+import { TemplatePage } from 'xertica-ui/pages';
+
+// Use as a starting point for new feature pages
+<TemplatePage
+  user={currentUser}
+  onLogout={handleLogout}
+/>
+```
+
+---
+
+### `TemplateContent`
+
+The main content area of `TemplatePage`. Contains a comprehensive showcase of all Xertica UI components — useful as a living reference during development.
+
+**Features:**
+- `Header` with full breadcrumb, user menu, and action buttons
+- All form elements (Input, Select, Checkbox, Switch, Slider, etc.)
+- Data display components (Table, Chart, StatsCard, Timeline, TreeView)
+- Overlay components (Dialog, Sheet, Drawer, Popover, Tooltip)
+- Media components (AudioPlayer, VideoPlayer)
+- AI components (XerticaAssistant in full-page mode)
+
+**Props:**
+
+| Prop | Type | Description |
+|---|---|---|
+| `user` | `{ email: string } \| null` | User object for the header |
+| `onLogout` | `() => void` | Logout handler |
+| `sidebarExpanded` | `boolean` | Controls header left padding |
+| `sidebarWidth` | `number` | Sidebar width in pixels |
+| `onToggleSidebar` | `() => void` | Sidebar toggle callback |
+| `onToggleAssistant` | `() => void` | Assistant toggle callback |
+
+---
+
+## 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 pattern
+function MyPage({ user, onLogout }) {
+  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}
+        onLogout={onLogout}
+        location={location}
+        navigate={navigate}
+        routes={routes}
+      />
+      <MyContent
+        sidebarExpanded={sidebarExpanded}
+        sidebarWidth={sidebarWidth}
+        onToggleSidebar={toggleSidebar}
+        onToggleAssistant={toggleAssistente}
+      />
+      <XerticaAssistant
+        isExpanded={assistenteExpanded}
+        onToggle={toggleAssistente}
+        mode="demo"
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **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`.
+> - **Do not add business logic to page shells**: Page components (`HomePage`, `TemplatePage`) are layout containers. Business logic belongs in content components (`HomeContent`, `TemplateContent`) or custom feature components.

package/docs/components/pagination.md

@@ -4,6 +4,26 @@
 
 A navigation control for moving through pages of a large dataset. Renders Previous/Next buttons, numbered page buttons, and ellipsis for large page counts. Use it below data tables to control which page of records is displayed.
 
+The package also exports a **headless `usePagination` hook** that computes the full page item list (numbers + ellipsis) and exposes navigation helpers — use it when you need full control over the pagination UI.
+
+---
+
+## Exports
+
+| Export | Description |
+|---|---|
+| `Pagination` | Root nav wrapper |
+| `PaginationContent` | Flex container for all items |
+| `PaginationItem` | Individual item wrapper |
+| `PaginationLink` | Numbered page button |
+| `PaginationPrevious` | "Previous" button with left arrow |
+| `PaginationNext` | "Next" button with right arrow |
+| `PaginationEllipsis` | "..." indicator for skipped pages |
+| `usePagination` | Headless hook — all logic, no UI |
+| `UsePaginationProps` | TypeScript props type for the hook |
+| `UsePaginationReturn` | TypeScript return type for the hook |
+| `PaginationPageItem` | Union type for page items returned by the hook |
+
 ---
 
 ## When to Use
@@ -108,11 +128,178 @@ const totalPages = 10;
 
 ---
 
+## `usePagination` Hook
+
+A headless hook that computes the full page item list (page numbers + ellipsis markers) and exposes navigation helpers. Supports both **uncontrolled** (internal state) and **controlled** (external `page` prop) modes.
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `totalItems` | `number` | — | **Required.** Total number of items across all pages |
+| `pageSize` | `number` | `10` | Number of items per page |
+| `initialPage` | `number` | `1` | Initial page (uncontrolled mode only) |
+| `page` | `number` | — | Controlled current page — when provided, the hook uses this value instead of internal state |
+| `onPageChange` | `(page: number) => void` | — | Called whenever the page changes |
+| `siblingCount` | `number` | `1` | Number of page buttons to show on each side of the current page |
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `currentPage` | `number` | The currently active page (1-indexed) |
+| `totalPages` | `number` | Total number of pages |
+| `startIndex` | `number` | Zero-based index of the first item on the current page |
+| `endIndex` | `number` | Zero-based index of the last item on the current page (exclusive) |
+| `canGoPrev` | `boolean` | Whether navigating to the previous page is possible |
+| `canGoNext` | `boolean` | Whether navigating to the next page is possible |
+| `isFirstPage` | `boolean` | Whether the current page is the first page |
+| `isLastPage` | `boolean` | Whether the current page is the last page |
+| `items` | `PaginationPageItem[]` | Ordered list of page items to render (see below) |
+| `goTo` | `(page: number) => void` | Navigate to a specific page number |
+| `next` | `() => void` | Navigate to the next page |
+| `prev` | `() => void` | Navigate to the previous page |
+| `first` | `() => void` | Navigate to the first page |
+| `last` | `() => void` | Navigate to the last page |
+
+### `PaginationPageItem` Type
+
+```typescript
+type PaginationPageItem =
+  | { type: 'page'; page: number }
+  | { type: 'ellipsis'; key: string };
+```
+
+The `items` array is ready to render directly — map over it and render `<PaginationLink>` for `type: 'page'` items and `<PaginationEllipsis>` for `type: 'ellipsis'` items.
+
+### Uncontrolled Example
+
+```tsx
+import {
+  usePagination,
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from 'xertica-ui/ui';
+
+function MyTable({ data }: { data: Record<string, unknown>[] }) {
+  const {
+    currentPage,
+    totalPages,
+    startIndex,
+    endIndex,
+    canGoPrev,
+    canGoNext,
+    items,
+    next,
+    prev,
+  } = usePagination({ totalItems: data.length, pageSize: 10 });
+
+  const pageData = data.slice(startIndex, endIndex);
+
+  return (
+    <div className="space-y-4">
+      <table>
+        {/* render pageData rows */}
+      </table>
+
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationPrevious onClick={prev} aria-disabled={!canGoPrev} />
+          </PaginationItem>
+
+          {items.map((item) =>
+            item.type === 'ellipsis' ? (
+              <PaginationItem key={item.key}>
+                <PaginationEllipsis />
+              </PaginationItem>
+            ) : (
+              <PaginationItem key={item.page}>
+                <PaginationLink
+                  isActive={item.page === currentPage}
+                  onClick={() => goTo(item.page)}
+                >
+                  {item.page}
+                </PaginationLink>
+              </PaginationItem>
+            )
+          )}
+
+          <PaginationItem>
+            <PaginationNext onClick={next} aria-disabled={!canGoNext} />
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    </div>
+  );
+}
+```
+
+### Controlled Example (API-driven pagination)
+
+```tsx
+import { usePagination } from 'xertica-ui/ui';
+import { useState } from 'react';
+
+function ServerPaginatedTable({ totalItems }: { totalItems: number }) {
+  const [page, setPage] = useState(1);
+
+  const { items, canGoPrev, canGoNext, next, prev, goTo, currentPage } =
+    usePagination({
+      totalItems,
+      pageSize: 20,
+      page,               // controlled
+      onPageChange: setPage,
+    });
+
+  // fetch data for `page` from your API...
+
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious onClick={prev} aria-disabled={!canGoPrev} />
+        </PaginationItem>
+        {items.map((item) =>
+          item.type === 'ellipsis' ? (
+            <PaginationItem key={item.key}><PaginationEllipsis /></PaginationItem>
+          ) : (
+            <PaginationItem key={item.page}>
+              <PaginationLink
+                isActive={item.page === currentPage}
+                onClick={() => goTo(item.page)}
+              >
+                {item.page}
+              </PaginationLink>
+            </PaginationItem>
+          )
+        )}
+        <PaginationItem>
+          <PaginationNext onClick={next} aria-disabled={!canGoNext} />
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  );
+}
+```
+
+---
+
 ## AI Rules
 
 - Place Pagination below the `<Table>` inside the same `<Card>` wrapping both.
 - Use `isActive` on the currently selected page link.
 - For controlled pagination (API-driven), use `onClick` instead of `href` on `PaginationLink`.
+- When using `usePagination`, use `startIndex` and `endIndex` to slice client-side data arrays: `data.slice(startIndex, endIndex)`.
+- For server-side pagination, pass `page` and `onPageChange` to `usePagination` to use controlled mode — the hook will not manage internal state.
+- Always render `PaginationEllipsis` for `item.type === 'ellipsis'` items from the `items` array — never skip them.
+- `totalItems` is the count of **all** records, not just the current page.
+- Pages are **1-indexed** — the first page is `1`, not `0`.
 
 ---