xertica-ui 1.7.4 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.8.0] — 2026-04-27
+
+### Added
+- **VideoPlayer UI Enhancements** — Added gradient overlay on controls for improved contrast against video content:
+  - Gradient: `from-black/60 via-black/30 to-transparent` with `pt-12` spacing
+  - White progress bar with `bg-white/30` track, `bg-white` fill, and `rounded-r-sm` on filled portion
+  - White icons with `drop-shadow-md` for visibility
+  - Buttons use `text-white hover:text-white hover:bg-black/50` for proper hover states
+- **Slider Visual Fixes** — Improved progress bar alignment:
+  - Added left margin `ml-2` to track for thumb alignment
+  - Added `rounded-r-sm` to Range for filled portion
+  - Adjusted track/margins for proper visual alignment at full value
+
+### Changed
+- **Documentation** — Updated component counts across all docs:
+  - `llms.txt`: 75 → 97 components
+  - `llms-full.txt`: Added statistics table
+  - `docs/llms.md`: Added statistics section
+  - `Introduction.mdx`: Added "97 Components" badge
+- **components.json** — 75 → 89 components (added missing Media, Assistant, Pages, and Map components)
+
+### Fixed
+- **Slider Progress Bar** — Fixed visual gap where thumb doesn't align with filled bar at end position by adjusting track margins
+
+---
+
 ## [1.7.0] — 2026-04-23
 
 ### Fixed

package/README.md

@@ -1,227 +1,184 @@
-# Xertica UI
-
-> **Enterprise-grade React design system** built on Tailwind CSS v4, Radix UI, and Lucide Icons — with an AI-first documentation layer for accurate LLM-driven composition.
-
-[![npm version](https://img.shields.io/npm/v/xertica-ui)](https://www.npmjs.com/package/xertica-ui)
-[![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
-
----
-
-## Quick Start — CLI (Recommended)
-
-Scaffold a full application in seconds:
-
-```bash
-npx xertica-ui@latest init my-app
-cd my-app
-npm run dev
-```
-
-The CLI scaffolds a complete Vite + React + TypeScript project with routing, authentication pages, a sidebar layout, and all Xertica UI components pre-configured.
-
----
-
-## Installation as a Library
-
-To add Xertica UI to an existing React project:
-
-```bash
-npm install xertica-ui
-```
-
-**1. Import the stylesheet** in your entry file (`main.tsx` or `App.tsx`):
-
-```tsx
-import 'xertica-ui/style.css';
-```
-
-**2. Wrap your app** with `XerticaProvider`:
-
-```tsx
-import { XerticaProvider } from 'xertica-ui';
-
-function App() {
-  return (
-    <XerticaProvider>
-      <YourApp />
-    </XerticaProvider>
-  );
-}
-```
-
-**3. Use components:**
-
-```tsx
-import { Button, Card, CardContent } from 'xertica-ui';
-
-export function Example() {
-  return (
-    <Card>
-      <CardContent>
-        <Button>Get Started</Button>
-      </CardContent>
-    </Card>
-  );
-}
-```
-
----
-
-## XerticaProvider Props
-
-| Prop | Type | Description |
-|---|---|---|
-| `apiKey` | `string` | Google Gemini API key for the AI assistant |
-| `googleMapsApiKey` | `string` | Google Maps JavaScript API key |
-| `primaryColor` | `string` | Override the primary brand color |
-| `defaultBrandTheme` | `string` | Preset brand theme name |
-| `useCustomTokens` | `boolean` | Use local `tokens.css` instead of library defaults |
-| `disableDarkMode` | `boolean` | Disables dark mode support |
-
----
-
-## Component Catalog
-
-### Layout & Navigation
-`Header` · `Sidebar` · `PageHeader` · `PageHeaderHeading` · `PageHeaderDescription` · `Breadcrumb` · `NavigationMenu` · `Tabs` · `Pagination`
-
-### Surfaces
-`Card` · `CardHeader` · `CardTitle` · `CardDescription` · `CardContent` · `CardFooter` · `Separator` · `ScrollArea` · `AspectRatio` · `ResizablePanelGroup`
-
-### Form & Input
-`Form` · `FormField` · `FormItem` · `FormLabel` · `FormControl` · `FormMessage` · `Input` · `Textarea` · `Label` · `Checkbox` · `RadioGroup` · `Switch` · `Slider` · `Select` · `Calendar` · `InputOTP` · `FileUpload` · `Search`
-
-### Actions
-`Button` · `Toggle` · `ToggleGroup` · `Rating`
-
-### Data Display
-`Table` · `Badge` · `Avatar` · `Progress` · `Skeleton` · `Empty` · `StatsCard` · `Timeline` · `Stepper` · `TreeView` · `NotificationBadge` · `ChartContainer`
-
-### Structure & Utilities
-`Accordion` · `Collapsible` · `Carousel` · `ScrollArea`
-
-### Overlays & Feedback
-`Dialog` · `AlertDialog` · `Sheet` · `Drawer` · `Popover` · `HoverCard` · `Tooltip` · `Alert` · `Toaster` · `Command`
-
-### Menus
-`DropdownMenu` · `ContextMenu` · `Menubar`
-
-### Maps
-`Map` · `RouteMap`
-
-### AI Features
-`XerticaAssistant`
-
-### Hooks
-`useMobile` · `useIsMobile` · `useLayout`
-
----
-
-## Design Tokens
-
-Xertica UI uses semantic CSS tokens — **never use raw colors or Tailwind color classes**:
-
-```
-Background:     bg-background          text-foreground
-Card surface:   bg-card                text-card-foreground
-Muted area:     bg-muted               text-muted-foreground
-Primary action: bg-primary             text-primary-foreground
-Destructive:    bg-destructive         text-destructive-foreground
-Border:         border-border
-```
-
-Tokens are defined in `styles/xertica/tokens.css` and customizable per project:
-
-```css
-:root {
-  --primary: rgba(44, 39, 91, 1);
-  --radius: 6px;
-  --radius-card: 12px;
-}
-```
-
----
-
-## Dark Mode
-
-Full dark mode support via `data-mode="dark"` attribute or `.dark` class, managed automatically by `XerticaProvider`. User preference is persisted to `localStorage`.
-
----
-
-## AI Agent / LLM Usage
-
-Xertica UI ships with a comprehensive AI-first documentation layer in `docs/`:
-
-| File | Purpose |
-|---|---|
-| `docs/llms.md` | **Start here** — master index for AI agents |
-| `docs/ai-usage.md` | Mandatory rules for LLM-driven code generation |
-| `docs/guidelines.md` | Design token semantics and composition rules |
-| `docs/layout.md` | `LayoutContext` and `useLayout` API reference |
-| `docs/components/*.md` | Per-component reference with props, examples, and AI rules |
-| `docs/patterns/*.md` | Full page composition patterns (dashboard, CRUD, form, etc.) |
-
-Point your LLM agent to `docs/llms.md` as the entrypoint.
-
----
-
-## Tech Stack
-
-| Technology | Version |
-|---|---|
-| React | 18.3 |
-| TypeScript | 5.7 |
-| Tailwind CSS | 4.0 |
-| Vite | 6.0 |
-| Radix UI | latest |
-| Recharts | 2.x |
-| Lucide React | 0.469+ |
-| react-hook-form | 7.x |
-| zod | 3.x |
-
----
-
-## Peer Dependencies
-
-```json
-{
-  "react": "^18.3.1",
-  "react-dom": "^18.3.1",
-  "react-router-dom": "^7.1.3"
-}
-```
-
----
-
-## Scripts
-
-| Command | Description |
-|---|---|
-| `npm run dev` | Start development server |
-| `npm run build` | Production bundle |
-| `npm run type-check` | TypeScript validation |
-| `npm run lint` | ESLint check |
-
----
-
-## Troubleshooting
-
-**CSS not loading:**
-```bash
-npm install
-rm -rf node_modules/.vite
-npm run dev
-```
-
-**TypeScript errors:**
-```bash
-npm run type-check
-```
-
-**Maps not rendering:** Ensure `googleMapsApiKey` is passed to `<XerticaProvider>` and the Maps JavaScript API + Directions API are enabled in your Google Cloud project.
-
----
-
-## License
-
-Proprietary — Xertica AI Team.
+# Xertica UI
+
+> **Enterprise-grade React design system** built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction.
+
+[![npm version](https://img.shields.io/npm/v/xertica-ui)](https://www.npmjs.com/package/xertica-ui)
+[![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
+
+---
+
+## 🤖 AI-First Single Source of Truth
+
+Xertica UI is specifically designed to be consumed by AI Agents (LLMs, code assistants, autonomous agents). We provide dedicated entry points for AI context:
+
+| File | Purpose |
+|---|---|
+| [`llms.txt`](./llms.txt) | Standard index for AI crawlers and context-aware agents. |
+| [`llms-full.txt`](./llms-full.txt) | **Complete documentation** of all 96 components in a single file for large-context LLMs. |
+| `docs/llms.md` | Master index for agents to navigate the documentation folder. |
+
+---
+
+## 🚀 Quick Start — CLI (Recommended)
+
+Scaffold a full application with pre-configured routing, layout, and components:
+
+```bash
+npx xertica-ui@latest init my-app
+cd my-app
+npm run dev
+```
+
+The CLI scaffolds a complete Vite + React + TypeScript project with Portuguese UI localization and English AI-ready documentation.
+
+---
+
+## 📦 Installation as a Library
+
+To add Xertica UI to an existing React project:
+
+```bash
+npm install xertica-ui
+```
+
+**1. Import the stylesheet** in your entry file (`main.tsx` or `App.tsx`):
+
+```tsx
+import 'xertica-ui/style.css';
+```
+
+**2. Wrap your app** with `XerticaProvider`:
+
+```tsx
+import { XerticaProvider } from 'xertica-ui';
+
+function App() {
+  return (
+    <XerticaProvider>
+      <YourApp />
+    </XerticaProvider>
+  );
+}
+```
+
+---
+
+## 🛠️ The Layout System
+
+Xertica UI features an autonomous layout system managed by `LayoutContext`.
+
+### Mandatory Page Structure
+Every page **must** use the `<PageHeader>` component for its title and primary actions. Never use raw `h1` or `div` for headers.
+
+```tsx
+import { PageHeader, PageHeaderHeading, Button } from 'xertica-ui';
+
+export function MyPage() {
+  return (
+    <>
+      <PageHeader>
+        <PageHeaderHeading>Dashboard</PageHeaderHeading>
+        <Button>Action</Button>
+      </PageHeader>
+      <div className="p-6">
+        {/* Page Content */}
+      </div>
+    </>
+  );
+}
+```
+
+### `useLayout()` Hook
+Access the sidebar state, width, and toggle functions anywhere in the component tree:
+```tsx
+const { sidebarWidth, isSidebarOpen, toggleSidebar } = useLayout();
+```
+
+---
+
+## 🧩 Component Catalog (96 Components)
+
+### Layout & Navigation
+`Header` · `Sidebar` · `PageHeader` · `Breadcrumb` · `NavigationMenu` · `Tabs` · `Pagination` · `Accordion` · `Collapsible`
+
+### Core Surfaces
+`Card` · `Separator` · `ScrollArea` · `AspectRatio` · `Resizable` · `Skeleton` · `Empty`
+
+### Forms & Inputs
+`Form` · `Input` · `Textarea` · `RichTextEditor` · `Label` · `Checkbox` · `RadioGroup` · `Switch` · `Select` · `Slider` · `Calendar` · `InputOTP` · `FileUpload` · `Search`
+
+### Actions & Data
+`Button` · `Toggle` · `ToggleGroup` · `Rating` · `Table` · `Badge` · `Avatar` · `Progress` · `StatsCard` · `Timeline` · `Stepper` · `TreeView` · `NotificationBadge` · `Chart`
+
+### Overlays & Feedback
+`Dialog` · `AlertDialog` · `Sheet` · `Drawer` · `Popover` · `HoverCard` · `Tooltip` · `Alert` · `Sonner (Toast)` · `Command`
+
+---
+
+## 🌟 Specialized Modules
+
+### 🤖 AI Assistant
+Integrated AI chat panel with workspace support.
+- `XerticaAssistant` · `MarkdownMessage` · `CodeBlock` · `AssistantChart`
+
+### 🗺️ Maps & Geolocation
+First-class Google Maps integration.
+- `Map` · `RouteMap` · `SimpleMap` · `GoogleMapsLoader`
+
+### 🎙️ Media
+- `AudioPlayer` · `VideoPlayer` · `FloatingMediaWrapper`
+
+---
+
+## 🎨 Design Tokens
+
+Xertica UI uses semantic CSS tokens. **Never use raw colors or generic Tailwind color classes**:
+
+```
+Background:     bg-background          text-foreground
+Card surface:   bg-card                text-card-foreground
+Muted area:     bg-muted               text-muted-foreground
+Primary action: bg-primary             text-primary-foreground
+Destructive:    bg-destructive         text-destructive-foreground
+Border:         border-border
+```
+
+---
+
+## 🌍 Localization
+
+- **UI Components**: Fully localized in **Portuguese (pt-BR)** for end-users.
+- **Documentation/Code**: Strictly maintained in **English** for AI Agent compatibility and global developer standard.
+
+---
+
+## 💻 Tech Stack
+
+| Technology | Version |
+|---|---|
+| React | 18.3 |
+| TypeScript | 5.7 |
+| Tailwind CSS | 4.0 |
+| Vite | 6.0 |
+| Radix UI | Latest |
+| Lucide React | 0.469+ |
+| Vitest | 4.1 |
+
+---
+
+## 📜 Scripts
+
+| Command | Description |
+|---|---|
+| `npm run dev` | Start development server |
+| `npm run build` | Production bundle |
+| `npm run storybook` | Launch component library documentation |
+| `npm run test` | Run unit tests via Vitest |
+| `npm run type-check` | TypeScript validation |
+
+---
+
+## ⚖️ License
+
+Proprietary — Xertica AI Team.
+

package/components/Introduction.mdx

@@ -12,6 +12,9 @@ import { XerticaLogo } from './brand/xertica-logo/XerticaLogo';
     <p className="text-xl text-muted-foreground max-w-2xl">
       Official Design System for Xertica projects. Built with Tailwind CSS v4, Radix UI, and AI-first engineering.
     </p>
+    <div className="text-lg font-mono text-muted-foreground bg-muted px-4 py-2 rounded-lg">
+      97 Components
+    </div>
     <div className="flex gap-4 pt-4">
       <a href="https://www.npmjs.com/package/xertica-ui" target="_blank" className="h-11 px-8 rounded-full border border-border bg-background text-foreground font-medium flex items-center hover:bg-accent transition-colors no-underline">
         NPM