xertica-ui 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to `xertica-ui` will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.6.0] — 2026-04-20
+
+### Added
+- **`docs/llms.md`** — Master LLM/AI-agent entrypoint index with full component catalog, token quick reference, and reading order guide.
+- **`docs/layout.md`** — Complete `LayoutContext` and `useLayout()` API reference.
+- **`docs/components/route-map.md`** — New documentation for `RouteMap` component.
+- **`docs/components/use-mobile.md`** — New documentation for `useMobile` / `useIsMobile` hooks.
+- **`Header`** — New props: `user` (profile with avatar, name, email, and dropdown menu items), `actions` (custom icon action buttons), `showSettings` / `onSettingsClick`, `showLogout` / `onLogoutClick`. Fixed render order: Language → Theme → Actions → Settings → User → Logout.
+- **`Sidebar`** — New `width` prop (`expandedWidth: number`) for configuring the expanded sidebar pixel width. Width is now read and stored via `LayoutContext.sidebarWidth`.
+
+### Changed
+- **Documentation** — All 61 component docs, 5 pattern docs, and 6 root docs fully rewritten in English with standardized structure (Overview, When to Use, Anatomy, Props table, Examples, AI Rules, Related Components).
+- **JSDoc** — All Portuguese JSDoc comments in `components/ui/` translated to English and enriched with accurate `@ai-rules`.
+- **`README.md`** — Complete rewrite in English, restructured for npm page quality (quick start, install guide, component catalog, token reference, AI agent entrypoint, troubleshooting).
+- **`package.json`** — Version bumped to `1.6.0`. Description translated to English.
+
+### Fixed
+- **`docs/components/page-header.md`** — Was documenting a wrong API (`title/description/actions`). Now correctly documents the real API: `breadcrumbs[]`, `showLanguageSelector`, `rightContent`, `PageHeaderHeading`, `PageHeaderDescription`.
+- **`docs/components/stepper.md`** — Was documenting a `steps[]` array prop. Now correctly documents the composable `<Stepper currentStep> + <Step step label>` API (1-indexed).
+- **`docs/components/empty.md`** — Was documenting single-prop component. Now correctly documents the composable sub-component pattern: `Empty > EmptyIcon > EmptyTitle > EmptyDescription > EmptyAction`.
+- **`docs/components/stats-card.md`** — `trend` was documented as a string. Now correctly documented as `{ value: number; label?: string }`.
+- **`docs/components/chart.md`** — Was documenting raw Recharts usage. Now correctly documents the `ChartContainer + ChartConfig + var(--color-*)` pattern.
+
+---
+
+## [1.5.2] — 2026-04-15
+
+### Fixed
+- Resolved regression where modal components (Dialog/AlertDialog) failed to render in projects initialized via the CLI.
+- Implemented robust CSS integration using Tailwind v4 theme mappings.
+- Ensured Radix UI portals correctly inherit theme variables.
+
+---
+
+## [1.5.1] — 2026-04-14
+
+### Changed
+- Sidebar: Added `assistente` variant with fixed areas, searchable navigation, and grouped navigation structures.
+- Template page updated to demonstrate the assistant sidebar variant.
+
+---
+
+## [1.5.0] — 2026-04-13
+
+### Added
+- `Sidebar` — `width` / `expandedWidth` prop for configurable expanded sidebar width.
+- `LayoutContext` — `sidebarWidth` and `setSidebarWidth` for global sidebar width management.
+- `Header` — User profile section with avatar, dropdown menu, settings button, and logout button.
+- `StatsCard` — KPI metric card component.
+- `Timeline` — Chronological event list with dot variants.
+- `TreeView` — Hierarchical tree navigation.
+- `Rating` — Star-based rating input.
+- `FileUpload` — Drag-and-drop file input.
+- `Search` — Pre-built search input with icon and clear button.
+- `NotificationBadge` — Dot/count badge overlay.
+- `RouteMap` — Google Maps route display and direction calculation.
+- `Stepper` — Multi-step progress indicator.
+- `Map` — Advanced Google Maps integration with markers, circles, polygons, and layers.
+- `XerticaAssistant` — Embedded Gemini AI assistant panel.

package/README.md

@@ -1,367 +1,227 @@
 # Xertica UI
 
-Design System completo com componentes React e Tailwind CSS v4.0, construído com TypeScript seguindo arquitetura CLI-first (modelo Shadcn).
+> **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.
 
-## 🚀 Início Rápido (CLI)
+[![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)
 
-Para criar um novo projeto utilizando o Xertica UI:
-
-```bash
-npx xertica-ui init meu-projeto
-```
-
-O CLI irá guiá-lo através da configuração:
-1. **Componentes**: Escolha quais componentes incluir.
-2. **Páginas**: Opte por incluir ou não Login, Home e Template.
-3. **Instalação**: Dependências são instaladas automaticamente.
+---
 
-### Desenvolvimento no Projeto Clona
+## Quick Start — CLI (Recommended)
 
-Após a inicialização:
+Scaffold a full application in seconds:
 
 ```bash
-cd meu-projeto
+npx xertica-ui@latest init my-app
+cd my-app
 npm run dev
 ```
 
-Acesse: **http://localhost:5173**
-Login padrão: Use qualquer email e senha.
-
-## 📋 Pré-requisitos
+The CLI scaffolds a complete Vite + React + TypeScript project with routing, authentication pages, a sidebar layout, and all Xertica UI components pre-configured.
 
-- Node.js 18+ instalado
-- npm, yarn ou pnpm
-
-## 🔧 Instalação
-
-O método recomendado é usar o CLI:
-```bash
-npx xertica-ui init meu-app
-```
+---
 
-### Instalação como Biblioteca
+## Installation as a Library
 
-Se você deseja usar os componentes em um projeto React existente:
+To add Xertica UI to an existing React project:
 
-1. Instale o pacote:
 ```bash
 npm install xertica-ui
 ```
 
-2. Importe o CSS (obrigatório) no seu arquivo `main.tsx` ou `App.tsx`:
+**1. Import the stylesheet** in your entry file (`main.tsx` or `App.tsx`):
+
 ```tsx
 import 'xertica-ui/style.css';
 ```
 
-3. Envolva sua aplicação com o `XerticaProvider`:
+**2. Wrap your app** with `XerticaProvider`:
+
 ```tsx
 import { XerticaProvider } from 'xertica-ui';
 
 function App() {
   return (
     <XerticaProvider>
-      <SeuApp />
+      <YourApp />
     </XerticaProvider>
   );
 }
 ```
 
-4. Comece a usar os componentes:
+**3. Use components:**
+
 ```tsx
-import { Button } from 'xertica-ui';
+import { Button, Card, CardContent } from 'xertica-ui';
 
-export function MeuComponente() {
-  return <Button>Clique aqui</Button>;
+export function Example() {
+  return (
+    <Card>
+      <CardContent>
+        <Button>Get Started</Button>
+      </CardContent>
+    </Card>
+  );
 }
 ```
 
-### Desenvolvimento do Projeto (Contribuição)
-Para desenvolvimento do próprio pacote/biblioteca:
-1. Clone o repositório:
-```bash
-git clone [URL_DO_REPOSITORIO]
-cd xertica-ui
-```
+---
 
-2. Instale as dependências:
-```bash
-npm install
-```
+## XerticaProvider Props
 
-## 📁 Estrutura do Projeto
+| 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 |
 
-```
-xertica-ui/
-├── components/
-│   ├── ui/                      # 156 componentes do Design System
-│   │   ├── index.ts             # Export central
-│   │   ├── button.tsx
-│   │   ├── card.tsx
-│   │   ├── alert.tsx
-│   │   ├── map.tsx
-│   │   ├── xertica-assistant.tsx
-│   │   └── ... (todos os componentes)
-│   │
-│   ├── examples/                # Exemplos de uso (Maps)
-│   ├── figma/                   # Componentes Figma
-│   ├── media/                   # Players de áudio/vídeo
-│   │
-│   ├── HomePage.tsx             # Página Home
-│   ├── TemplatePage.tsx         # Template completo
-│   ├── LoginPage.tsx            # Login
-│   └── ... (componentes auxiliares)
-│
-├── contexts/                    # Contextos React
-│   ├── ThemeContext.tsx
-│   ├── LanguageContext.tsx
-│   └── ...
-│
-├── styles/
-│   └── xertica/
-│       ├── tokens.css           # Design Tokens (Source of Truth)
-│       ├── base.css             # Base styles + Tailwind
-│       ├── theme-map.css        # Theme mapping
-│       └── integrations/        # CSS overrides
-│
-├── App.tsx                      # Componente raiz
-├── routes.tsx                   # Configuração de rotas
-└── package.json                 # Dependências
-```
+---
 
-## 🚀 Tecnologias
+## Component Catalog
 
-- **React 18.3** - Biblioteca JavaScript para interfaces
-- **TypeScript 5.7** - Superset tipado do JavaScript
-- **Tailwind CSS v4.0** - Framework CSS utility-first
-- **Vite 6.0** - Build tool e dev server ultrarrápido
-- **React Router 7** - Roteamento client-side
-- **Radix UI** - Componentes acessíveis e não estilizados
-- **Shadcn/ui** - Modelo CLI-first para componentes
-- **Lucide React** - Ícones SVG
-- **Sonner** - Toast notifications elegantes
-- **Recharts** - Gráficos e visualizações de dados
-- **Google Generative AI** - Integração com Gemini
+### Layout & Navigation
+`Header` · `Sidebar` · `PageHeader` · `PageHeaderHeading` · `PageHeaderDescription` · `Breadcrumb` · `NavigationMenu` · `Tabs` · `Pagination`
 
-## 🏃 Executando o Projeto
+### Surfaces
+`Card` · `CardHeader` · `CardTitle` · `CardDescription` · `CardContent` · `CardFooter` · `Separator` · `ScrollArea` · `AspectRatio` · `ResizablePanelGroup`
 
-### Modo de Desenvolvimento
+### Form & Input
+`Form` · `FormField` · `FormItem` · `FormLabel` · `FormControl` · `FormMessage` · `Input` · `Textarea` · `Label` · `Checkbox` · `RadioGroup` · `Switch` · `Slider` · `Select` · `Calendar` · `InputOTP` · `FileUpload` · `Search`
 
-```bash
-npm run dev
-```
+### Actions
+`Button` · `Toggle` · `ToggleGroup` · `Rating`
 
-O projeto será aberto automaticamente em `http://localhost:5173`
+### Data Display
+`Table` · `Badge` · `Avatar` · `Progress` · `Skeleton` · `Empty` · `StatsCard` · `Timeline` · `Stepper` · `TreeView` · `NotificationBadge` · `ChartContainer`
 
-### Build de Produção
+### Structure & Utilities
+`Accordion` · `Collapsible` · `Carousel` · `ScrollArea`
 
-```bash
-npm run build
-```
+### Overlays & Feedback
+`Dialog` · `AlertDialog` · `Sheet` · `Drawer` · `Popover` · `HoverCard` · `Tooltip` · `Alert` · `Toaster` · `Command`
 
-### Preview da Build de Produção
+### Menus
+`DropdownMenu` · `ContextMenu` · `Menubar`
 
-```bash
-npm run preview
-```
+### Maps
+`Map` · `RouteMap`
 
-### Type Check
+### AI Features
+`XerticaAssistant`
 
-```bash
-npm run type-check
-```
+### Hooks
+`useMobile` · `useIsMobile` · `useLayout`
 
-## 🎨 Design System
+---
 
-### Sistema de Tokens CSS
+## Design Tokens
 
-Todos os estilos são baseados em variáveis CSS definidas em `/styles/xertica/tokens.css`:
+Xertica UI uses semantic CSS tokens — **never use raw colors or Tailwind color classes**:
 
-```css
-/* Cores */
---primary: rgba(44, 39, 91, 1);
---background: rgba(255, 255, 255, 1);
---foreground: rgba(9, 9, 11, 1);
-
-/* Tipografia */
---text-h1: 2rem;
---text-h2: 1.75rem;
---text-stats: 2.25rem;
---font-weight-medium: 500;
---font-weight-bold: 700;
-
-/* Radius */
---radius: 6px;
---radius-button: 12px;
---radius-card: 12px;
-
-/* Spacing */
---spacing-4: 1rem;
---spacing-8: 2rem;
+```
+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
 ```
 
-### Customização
-
-Edite `/styles/xertica/tokens.css` e todo o sistema se adapta automaticamente:
+Tokens are defined in `styles/xertica/tokens.css` and customizable per project:
 
 ```css
 :root {
-  --primary: rgba(255, 0, 0, 1);  /* Vermelho customizado */
-  --radius: 16px;                  /* Bordas mais arredondadas */
+  --primary: rgba(44, 39, 91, 1);
+  --radius: 6px;
+  --radius-card: 12px;
 }
 ```
 
-### Tipografia
-
-- **Fonte**: Roboto (400, 500, 600, 700, 800)
-- **Tamanhos**: Definidos via variáveis CSS (`--text-*`)
-- **Zero classes Tailwind** de font-size ou font-weight hardcoded
-
-## 🌓 Dark Mode
-
-Suporte completo a Dark Mode com toggle manual. A preferência é salva em `localStorage`.
-
-Troca via atributo `data-mode="dark"` ou classe `.dark`
-
-## 🔐 Autenticação
-
-Sistema de autenticação simulada que aceita qualquer credencial não vazia:
-
-- **Email**: qualquer@email.com
-- **Senha**: qualquer senha
-
-## 🗺️ Rotas
-
-- `/login` - Página de login
-- `/forgot-password` - Recuperação de senha
-- `/verify-email` - Verificação de email
-- `/reset-password` - Redefinição de senha
-- `/home` - Página principal (protegida)
-- `/template` - Template com todos os componentes (protegida)
-
-## 🤖 Integração com Gemini AI
-
-O assistente Xertica usa Google Gemini AI. Configure a API Key:
-
-1. Acesse o assistente AI
-2. Clique em "Configurar API Key"
-3. Insira sua chave da API do Google Gemini
-4. A chave é salva localmente no navegador
-
-**Obter API Key**: [Google AI Studio](https://aistudio.google.com/app/apikey)
-
-## 📦 Componentes UI (156 total)
-
-### Layout & Structure
-Card, Separator, AspectRatio, Resizable
-
-### Navigation
-Tabs, Breadcrumb, NavigationMenu, Sidebar, Pagination
-
-### Buttons & Interactions
-Button, Toggle, ToggleGroup
-
-### Forms & Inputs
-Input, Textarea, Label, Checkbox, RadioGroup, Switch, Slider, Select, InputOTP, Form, Calendar
+---
 
-### Overlays & Dialogs
-Dialog, AlertDialog, Sheet, Drawer, Popover, Tooltip, HoverCard
+## Dark Mode
 
-### Menus
-DropdownMenu, ContextMenu, Menubar, Command
+Full dark mode support via `data-mode="dark"` attribute or `.dark` class, managed automatically by `XerticaProvider`. User preference is persisted to `localStorage`.
 
-### Feedback & Notifications
-Alert, Badge, Progress, Skeleton, Toast (Sonner), NotificationBadge
-
-### Data Display
-Avatar, Table, Chart, Empty, StatsCard, Timeline, TreeView
+---
 
-### Utility Components
-Collapsible, Accordion, ScrollArea, Carousel, Stepper, FileUpload, Rating, Search
+## AI Agent / LLM Usage
 
-### Maps
-Map, RouteMap, SimpleMap (Google Maps integration)
+Xertica UI ships with a comprehensive AI-first documentation layer in `docs/`:
 
-### Xertica Custom
-XerticaAssistant, PageHeader
+| 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.) |
 
-### Hooks
-useMobile, useIsMobile
+Point your LLM agent to `docs/llms.md` as the entrypoint.
 
-## 🎯 Funcionalidades
+---
 
-- ✅ Sistema de autenticação completo
-- ✅ 156 componentes CLI-ready
-- ✅ Design System baseado em variáveis CSS
-- ✅ Dark mode completo
-- ✅ Assistente AI integrado
-- ✅ Sistema de notificações (toast)
-- ✅ Design responsivo
-- ✅ Arquitetura CLI-first (modelo Shadcn)
-- ✅ TypeScript completo
-- ✅ Zero CSS oculto
+## Tech Stack
 
-## 📱 Responsividade
+| 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 |
 
-Totalmente responsivo com breakpoints:
+---
 
-- Mobile: 320px+
-- Tablet: 768px+
-- Desktop: 1024px+
+## Peer Dependencies
 
-## 🔄 Scripts Disponíveis
+```json
+{
+  "react": "^18.3.1",
+  "react-dom": "^18.3.1",
+  "react-router-dom": "^7.1.3"
+}
+```
 
-- `npm run dev` - Inicia servidor de desenvolvimento
-- `npm run build` - Cria build de produção
-- `npm run preview` - Preview da build
-- `npm run type-check` - Verifica tipos TypeScript
-- `npm run lint` - Executa linter
+---
 
-## 📝 Convenções de Código
+## Scripts
 
-- **Componentes**: PascalCase (ex: `LoginPage.tsx`)
-- **Utilitários**: camelCase (ex: `utils.ts`)
-- **Contextos**: PascalCase com sufixo Context (ex: `ThemeContext.tsx`)
-- **CSS**: Variáveis CSS em vez de classes Tailwind para tipografia
+| 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 não carrega
+## Troubleshooting
 
-1. Verifique se todas as dependências estão instaladas:
+**CSS not loading:**
 ```bash
 npm install
-```
-
-2. Limpe o cache do Vite:
-```bash
 rm -rf node_modules/.vite
 npm run dev
 ```
 
-### Erros de TypeScript
-
-Execute a verificação de tipos:
+**TypeScript errors:**
 ```bash
 npm run type-check
 ```
 
-### Porta em uso
-
-Altere a porta em `vite.config.ts`:
-```ts
-server: {
-  port: 3001,
-}
-```
-
-## 📄 Licença
-
-Este projeto é privado e proprietário.
-
-## 👥 Autor
-
-Xertica AI Team
+**Maps not rendering:** Ensure `googleMapsApiKey` is passed to `<XerticaProvider>` and the Maps JavaScript API + Directions API are enabled in your Google Cloud project.
 
 ---
 
-**Nota**: Este é um projeto de demonstração. Para uso em produção, implemente autenticação real, validação de segurança e testes adequados.
+## License
+
+Proprietary — Xertica AI Team.

package/components/AudioPlayer.tsx

@@ -23,22 +23,45 @@ import {
 } from './ui/tooltip';
 import { cn } from './ui/utils';
 
+/**
+ * Props for the AudioPlayer component.
+ */
 interface AudioPlayerProps {
+  /** Whether the player is currently visible and open */
   isOpen: boolean;
+  /** Callback to close the player bar */
   onClose: () => void;
+  /** Pass sidebar expansion state to adjust layout positioning */
   sidebarExpanded: boolean;
+  /** Title of the audio track/podcast */
   title?: string;
+  /** Subtitle or source information */
   subtitle?: string;
-  duration?: number; // in seconds
+  /** Total duration in seconds */
+  duration?: number; 
+  /** Initial or current playback time in seconds */
   currentTime?: number;
 }
 
+/**
+ * Global floating Audio Player bar.
+ * 
+ * @description
+ * A fixed-position playback bar that handles audio progress, volume, 
+ * and specific podcast actions (reset, speed, info, refresh). 
+ * It transitions smoothly from the bottom of the screen.
+ * 
+ * @ai-rules
+ * 1. Placement: This component should typically be rendered once at the top level (e.g., in a Layout) and controlled via global state.
+ * 2. Positional logic: It automatically offsets itself based on `sidebarExpanded` to avoid overlapping navigation.
+ * 3. Use `duration` and `currentTime` to synchronize with external audio state if needed.
+ */
 export function AudioPlayer({ 
   isOpen, 
   onClose, 
   sidebarExpanded,
-  title = "Processo 50002396220258210104",
-  subtitle = "Podcast atualizado até Evento 26",
+  title = "Process 50002396220258210104",
+  subtitle = "Podcast updated to Event 26",
   duration = 1200, // 20:00
   currentTime = 0
 }: AudioPlayerProps) {
@@ -147,7 +170,7 @@ export function AudioPlayer({
                        <RotateCcw className="w-4 h-4" />
                      </Button>
                   </TooltipTrigger>
-                  <TooltipContent>Reiniciar</TooltipContent>
+                  <TooltipContent>Restart</TooltipContent>
                 </Tooltip>
               </TooltipProvider>
 
@@ -158,7 +181,7 @@ export function AudioPlayer({
                        <Gauge className="w-4 h-4" />
                      </Button>
                    </TooltipTrigger>
-                   <TooltipContent>Velocidade (1.0x)</TooltipContent>
+                   <TooltipContent>Speed (1.0x)</TooltipContent>
                  </Tooltip>
               </TooltipProvider>
 
@@ -170,7 +193,7 @@ export function AudioPlayer({
                      </Button>
                    </TooltipTrigger>
                    <TooltipContent className="max-w-[300px] bg-popover text-popover-foreground">
-                     <p>Identificamos a entrada de novos eventos neste processo desde a última atualização deste podcast.</p>
+                     <p>We identified new events in this process since the last podcast update.</p>
                    </TooltipContent>
                  </Tooltip>
               </TooltipProvider>
@@ -182,7 +205,7 @@ export function AudioPlayer({
                        <RefreshCw className="w-4 h-4" />
                      </Button>
                    </TooltipTrigger>
-                   <TooltipContent>Atualizar Versão</TooltipContent>
+                   <TooltipContent>Update Version</TooltipContent>
                  </Tooltip>
               </TooltipProvider>
 

package/components/CodeBlock.tsx

@@ -130,13 +130,33 @@ const elegantTheme = {
   },
 };
 
+/**
+ * Props for the CodeBlock component.
+ */
 interface CodeBlockProps {
+  /** The code string to be displayed */
   code: string;
+  /** Programming language for syntax highlighting */
   language?: 'typescript' | 'tsx' | 'css' | 'bash' | 'jsx';
+  /** Optional filename to display in the header */
   filename?: string;
+  /** Whether to show line numbers */
   showLineNumbers?: boolean;
 }
 
+/**
+ * Enhanced Syntax Highlighter component with "Copy to Clipboard" functionality.
+ * 
+ * @description
+ * Uses `react-syntax-highlighter` with a custom "Elegant" theme inspired by Xertica's 
+ * design tokens. It includes a fallback mechanism for the Clipboard API and 
+ * optionally displays a header with the filename and language.
+ * 
+ * @ai-rules
+ * 1. Theme: Uses a custom `elegantTheme` that maps to system CSS variables. Avoid overriding these colors manually.
+ * 2. Clipboard: The copy functionality is robust with multiple fallback methods.
+ * 3. Content: Ensure `code` is passed as a raw string without pre-formatting indentation if possible.
+ */
 export const CodeBlock = ({
   code,
   language = 'tsx',