xertica-ui 2.2.0 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xertica-ui",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Xertica UI — Enterprise-grade React design system with Tailwind CSS v4, Radix UI, and AI-first documentation.",
   "type": "module",
   "main": "./dist/index.cjs.js",

package/templates/CLAUDE.md

@@ -1,180 +1,165 @@
-# Xertica UI — Project Rules
-
-This project uses **xertica-ui**, an enterprise React design system built on Tailwind CSS v4, Radix UI, and Lucide Icons.
-
-> For the complete component reference, read `node_modules/xertica-ui/llms-full.txt`.
-> For a compact quick-reference, read `node_modules/xertica-ui/llms-compact.txt`.
-> For component selection guidance, read `node_modules/xertica-ui/docs/decision-tree.md`.
-
----
-
-## Import Rules
-
-Always use the most specific subpath — never import from a category you don't need:
-
-```tsx
-import { Button, Card, Input, Badge, Table, Dialog } from 'xertica-ui/ui';
-import { Sidebar, Header } from 'xertica-ui/layout';
-import { XerticaProvider, XerticaLogo, ThemeToggle } from 'xertica-ui/brand';
-import { XerticaAssistant, generateDemoResponse } from 'xertica-ui/assistant';
-import { VideoPlayer, AudioPlayer } from 'xertica-ui/media';
-import { useLayout, useOptionalLayout, useTheme } from 'xertica-ui/hooks';
-import 'xertica-ui/style.css'; // import once at root only
-```
-
-The root `from 'xertica-ui'` remains valid for backward compatibility, but scaffolded project code must prefer the subpaths above.
-
-Icons are **never** from xertica-ui — always use `lucide-react`:
-
-```tsx
-import { Home, Settings, Plus, Trash2, ChevronRight } from 'lucide-react';
-```
-
----
-
-## Non-Negotiable Rules
-
-### HTML — never use raw elements for UI
-
-| ❌ Never                         | ✅ Always                           |
-| -------------------------------- | ----------------------------------- |
-| `<button>`                       | `<Button>` from `xertica-ui/ui`     |
-| `<input>`                        | `<Input>` from `xertica-ui/ui`      |
-| `<select>`                       | `<Select>` from `xertica-ui/ui`     |
-| `<h1>` / `<h2>` for page headers | `<PageHeader><PageHeaderHeading>`   |
-| `<div class="card ...">`         | `<Card>` from `xertica-ui/ui`       |
-| custom scrollbar div             | `<ScrollArea>` from `xertica-ui/ui` |
-
-### Colors — context-dependent rules
-
-| ❌ Never (any context)                   | Reason                     |
-| ---------------------------------------- | -------------------------- |
-| `#3b82f6`, `rgb(59,130,246)`, `hsl(...)` | Raw values — non-themeable |
-| `style={{ color: '#...' }}` for theming  | Non-themeable inline style |
-
-| ❌ Wrong for semantic/status contexts | ✅ Required instead |
-| ------------------------------------- | ------------------- |
-| `bg-red-500` for error states         | `bg-destructive`    |
-| `text-red-500` for error text         | `text-destructive`  |
-| `bg-green-500` for success states     | `bg-success`        |
-| `bg-yellow-500` for warnings          | `bg-warning`        |
-
-> For **layout, spacing, and general non-semantic UI** (custom components, decorative elements, Storybook stories where no semantic token applies), standard Tailwind color utilities like `bg-blue-500` or `text-gray-700` are acceptable.
-
-Semantic token reference:
-
-```
-bg-background / text-foreground       → page background and primary text
-bg-card / text-card-foreground        → card surfaces
-bg-muted / text-muted-foreground      → subdued areas and secondary text
-bg-primary / text-primary-foreground  → primary actions
-bg-destructive                        → danger / error states
-bg-success / bg-warning / bg-info     → semantic status states
-bg-accent                             → hover states
-border-border                         → standard borders
-border-input                          → form field borders
-```
-
-### Layout — always use context, never hardcode
-
-```tsx
-// ✅ Correct
-import { useLayout } from 'xertica-ui/hooks';
-const { sidebarExpanded, sidebarWidth } = useLayout();
-<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
-
-// ✅ Correct for reusable components that may render without providers
-import { useOptionalLayout } from 'xertica-ui/hooks';
-const layout = useOptionalLayout();
-const fallbackSidebarWidth = layout?.sidebarWidth ?? 80;
-
-// ❌ Wrong — never hardcode sidebar width
-<div style={{ paddingLeft: '256px' }}>
-```
-
-### Destructive actions — always confirm
-
-```tsx
-// ✅ Correct — confirm before executing
-<AlertDialog>
-  <AlertDialogTrigger asChild>
-    <Button variant="destructive">Delete</Button>
-  </AlertDialogTrigger>
-  <AlertDialogContent>...</AlertDialogContent>
-</AlertDialog>
-
-// ❌ Wrong — never execute destructive action directly on click
-<Button variant="destructive" onClick={deleteRecord}>Delete</Button>
-```
-
----
-
-## Page Structure
-
-Every page must follow this structure:
-
-```tsx
-import { PageHeader, PageHeaderHeading, PageHeaderDescription } from 'xertica-ui/ui';
-
-export function MyPage() {
-  return (
-    <>
-      <PageHeader>
-        <PageHeaderHeading>Page Title</PageHeaderHeading>
-        <PageHeaderDescription>Optional subtitle</PageHeaderDescription>
-        <Button>Primary Action</Button>
-      </PageHeader>
-      <div className="p-6 space-y-6">{/* Page content */}</div>
-    </>
-  );
-}
-```
-
----
-
-## App Root Structure
-
-```tsx
-import { XerticaProvider } from 'xertica-ui/brand';
-import { BrowserRouter } from 'react-router-dom';
-import 'xertica-ui/style.css';
-
-function Root() {
-  const geminiApiKey = import.meta.env.VITE_GEMINI_API_KEY;
-  const googleMapsApiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
-
-  return (
-    <XerticaProvider apiKey={geminiApiKey} googleMapsApiKey={googleMapsApiKey}>
-      <BrowserRouter>
-        <App />
-      </BrowserRouter>
-    </XerticaProvider>
-  );
-}
-```
-
-`XerticaProvider` is the app-level convenience wrapper used by this template. It composes theme, brand colors, language, layout, assistant/API keys, Google Maps, tooltips, and toasts. Most individual `xertica-ui` components are designed to render independently; use `useOptionalLayout()` when building reusable components that should keep working outside this provider.
-
----
-
-## Toast Notifications
-
-```tsx
-import { toast } from 'sonner'; // sonner is re-exported, no extra install needed
-
-toast.success('Saved successfully');
-toast.error('Something went wrong');
-toast.info('Processing...');
-toast.warning('Check your input');
-```
-
-Never render `<Toaster>` manually — it is auto-injected by `<XerticaProvider>`.
-
----
-
-## Before Writing Any Component
-
-1. Check `node_modules/xertica-ui/llms-compact.txt` — the component may already exist.
-2. Check `node_modules/xertica-ui/docs/decision-tree.md` — you may be choosing the wrong component.
-3. Read the specific component doc at `node_modules/xertica-ui/docs/components/[name].md`.
-4. Never create custom primitives that duplicate library components.
+# Xertica UI — Project Rules
+
+This project uses **xertica-ui**, an enterprise React design system built on Tailwind CSS v4, Radix UI, and Lucide Icons.
+
+## Command Reference
+
+- **Dev Server**: `npm run dev`
+- **Build Production**: `npm run build`
+- **Linter**: `npm run lint` / `npm run lint:fix`
+- **Type Checker**: `npm run type-check`
+- **All Validation Checks**: `npm run check` (type-check + lint)
+- **Code Formatter**: `npm run format`
+
+---
+
+## Architecture — Feature-Sliced Design (FSD) + Feature-Driven Architecture (FDA)
+
+This project follows **FSD (Feature-Sliced Design)** layered architecture combined with **FDA (Feature-Driven Architecture)** vertical slicing. Layers can only import from layers below them.
+
+- **`src/app/`**: Application shell (BrowserRouter, AppLayout, AuthGuard, AuthContext). No business logic.
+- **`src/shared/`**: Shared layer with no business domain (config/navigation, lib/auth, types). Importable by any layer.
+- **`src/features/`**: Self-contained vertical slices by business capability (auth, home, template, assistant). Import only from the barrel `src/features/<name>/index.ts` — never from internal feature paths.
+- **`src/pages/`**: Thin route wrappers composing `AppLayout` + feature content. No logic or API calls here.
+
+### Adding a New Route
+1. **Create the feature content**: `src/features/<name>/ui/<NameContent>.tsx`
+2. **Export from the barrel**: `src/features/<name>/index.ts`
+3. **Create the page**: `src/pages/<NamePage>.tsx` (thin AppLayout wrapper)
+4. **Register the route**: Add route path, label, and icon to the `routes` array in `src/shared/config/navigation.ts`.
+5. **Register the `<Route>`**: Add the route element inside `<Routes>` in `src/app/components/AuthGuard.tsx`.
+
+---
+
+## Import Rules
+
+Always use the correct `xertica-ui` subpath:
+- **UI Primitives**: `xertica-ui/ui` (e.g. `Button`, `Card`, `Input`, `Badge`, `Table`, `Dialog`, `Select`)
+- **Providers & Brand**: `xertica-ui/brand` (e.g. `XerticaProvider`, `XerticaLogo`, `ThemeToggle`, `LanguageSelector`)
+- **Navigation Shell**: `xertica-ui/layout` (e.g. `Sidebar`, `Header`)
+- **AI Assistant**: `xertica-ui/assistant` (e.g. `XerticaAssistant`, `generateDemoResponse`)
+- **Media Players**: `xertica-ui/media` (e.g. `VideoPlayer`, `AudioPlayer`)
+- **Hooks & Contexts**: `xertica-ui/hooks` (e.g. `useLayout`, `useOptionalLayout`, `useTheme`, `useLanguage`)
+- **Styles**: Import `xertica-ui/style.css` once in `src/styles/index.css` (never directly inside components).
+
+Icons always come from `lucide-react` — never from `xertica-ui`.
+
+---
+
+## Non-Negotiable Coding Rules
+
+### HTML & Radix Elements
+Never use native HTML interactive elements where design system components exist:
+- `<Button>` instead of `<button>`
+- `<Input>` instead of `<input>`
+- `<Select>` instead of `<select>`
+- `<PageHeader>` + `<PageHeaderHeading>` instead of `<h1>`/`<h2>` for page titles
+- `<Card>` instead of `<div className="card">`
+- `<ScrollArea>` instead of custom scrollbars
+
+### Color & Border Radius Styling
+- **Never use raw color values** (`#hex`, `rgb()`, `hsl()`) or inline styles for theming.
+- **Never use standard Tailwind color classes for semantic/status contexts** (e.g., do not use `bg-red-500` or `text-green-500` for status/feedback/errors). Use semantic tokens: `bg-destructive`/`text-destructive` for errors, `bg-success` for success, `bg-warning` for warnings, `bg-info` for info.
+- **Tailwind colors** (`bg-blue-500`, `text-gray-700`) are allowed **only** for layout, spacing, and general non-semantic UI where no semantic token applies.
+- **Borders**: Always use `rounded-[var(--radius)]` — never use fixed radius classes like `rounded-lg` or `rounded-xl`.
+
+### Layout State
+Never hardcode sidebar or layout widths (e.g. `256px`). Read them dynamically:
+- `const { sidebarExpanded, sidebarWidth } = useLayout()`
+- For components that might render outside the layout provider:
+  `const layout = useOptionalLayout(); const fallbackSidebarWidth = layout?.sidebarWidth ?? 80;`
+
+### Confirm Destructive Actions
+Always wrap destructive actions in `<AlertDialog>` for confirmation:
+```tsx
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### Toast Notifications
+Always use `toast` from `sonner` and translate messages via `t()`:
+```tsx
+toast.success(t('common.saveSuccess'));
+toast.error(t('errors.somethingWentWrong'));
+```
+Never render `<Toaster>` manually — it is auto-injected by `<XerticaProvider>`.
+
+---
+
+## Internationalization (i18n)
+
+Every user-facing string must go through `useTranslation()`:
+- Translate all labels, placeholders, titles, aria-labels, tooltips, toasts, etc.
+- Add translation keys to split JSON files in `src/locales/<lang>/` for all languages.
+- **Monolingual Mode**: `<LanguageSelector>` auto-hides when a single language is configured. Use `<LanguageSelector showWhenMonolingual />` to override.
+- **Dynamic mock data / outside React cycle**: Always use **factory functions** returning `i18n.t(...)` rather than static arrays, so translations update dynamically:
+  ```tsx
+  export function getMockOptions() {
+    return [i18n.t('feedback.notWhatIWanted')];
+  }
+  ```
+- Inside components, wrap enum label maps in `useMemo([..., t])`.
+
+---
+
+## Server State (React Query)
+
+- Place typed fetch functions in `data/mock.ts` and React Query wrappers in `hooks/use<Xxx>.ts`.
+- **Language-aware queryKey is MANDATORY**: Every hook returning translated data must include `language` in its `queryKey` so switching languages invalidates the cache and triggers a refetch:
+  ```tsx
+  const { language } = useLanguage();
+  return useQuery({
+    queryKey: ['home', 'feature-cards', language],
+    queryFn: fetchFeatureCards,
+    staleTime: 10 * 60 * 1000
+  });
+  ```
+
+---
+
+## Loading States (Skeletons)
+
+Always render matching skeletons instead of spinners for data loading:
+- Wrap cards/lists with their matching FSD skeleton companions (`ActivityCardSkeleton`, `ProfileCardSkeleton`, `ProjectCardSkeleton`, `NotificationCardSkeleton`, `QuickActionCardSkeleton`, `FeatureCardSkeleton`, `StatsCardSkeleton`).
+- Pass `rows` to skeletons (e.g. `<ActivityCardSkeleton rows={5} />`) to match the loaded state height.
+- For tables, build loading rows using `<TableRow>` + `<TableCell>` + `<Skeleton className="h-3.5 w-28" />`.
+
+---
+
+## Theme & Token Customization
+
+- Customize colors, fonts, and dark mode classes by editing `src/styles/xertica/tokens.css`.
+- Update theme or languages using the CLI: `npx xertica-ui update`.
+
+---
+
+## Authentication Pattern
+
+The auth flow is managed in `src/app/context/AuthContext.tsx` via the `useAuth()` hook:
+- `getStoredUser()` / `storeUser()` / `clearStoredUser()` — from `src/shared/lib/auth.ts`
+- Auth pages (`/login`, `/forgot-password`, etc.) redirect to `/home` when user is already logged in
+- Protected routes use `<ProtectedRoute>` wrapper that redirects to `/login` if user is null
+- `useAuth().login(email, password)` stores the user
+- `useAuth().logout()` clears storage and navigates to `/login`
+
+---
+
+## Before Writing Any Component
+
+1. Check `node_modules/xertica-ui/llms-compact.txt` — the component may already exist.
+2. Check `node_modules/xertica-ui/docs/decision-tree.md` — you may be choosing the wrong component.
+3. Read the specific component doc at `node_modules/xertica-ui/docs/components/[name].md`.
+4. Never create custom primitives that duplicate library components.

package/templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xertica-ui-template",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "private": true,
   "type": "module",
   "scripts": {
@@ -24,7 +24,7 @@
     "react-i18next": "^17.0.8",
     "react-router-dom": "^7.1.3",
     "sonner": "^1.7.3",
-    "xertica-ui": "^2.2.0",
+    "xertica-ui": "^2.2.1",
     "zustand": "^5.0.13"
   },
   "devDependencies": {

package/templates/src/features/auth/ui/ForgotPasswordContent.tsx

@@ -5,9 +5,11 @@ import { ArrowLeft } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
 import { AuthPageShell } from './AuthPageShell';
 import { SocialLoginButtons } from './SocialLoginButtons';
+import { useTranslation } from 'react-i18next';
 
 export function ForgotPasswordContent() {
   const navigate = useNavigate();
+  const { t } = useTranslation();
   const [email, setEmail] = useState('');
   const [isLoading, setIsLoading] = useState(false);
 
@@ -22,35 +24,35 @@ export function ForgotPasswordContent() {
   return (
     <AuthPageShell
       imageSrc="https://images.unsplash.com/photo-1557804506-669a67965ba0?w=1200&h=800&fit=crop&auto=format"
-      imageAlt="Segurança e tecnologia"
+      imageAlt={t('forgotPassword.heroImageAlt')}
     >
       <div className="text-center">
         <div className="flex items-center justify-center mb-4">
           <XerticaLogo className="h-12 w-auto text-primary dark:text-foreground" variant="theme" />
         </div>
-        <h2 className="text-sm text-muted-foreground">Recuperar senha</h2>
+        <h2 className="text-sm text-muted-foreground">{t('forgotPassword.heading')}</h2>
         <p className="mt-2 text-muted-foreground">
-          Digite seu email e enviaremos instruções para redefinir sua senha
+          {t('forgotPassword.subheading')}
         </p>
       </div>
 
       <form className="space-y-6" onSubmit={handleSubmit}>
         <div className="form-group space-y-2">
-          <Label htmlFor="email">E-mail</Label>
+          <Label htmlFor="email">{t('forgotPassword.emailLabel')}</Label>
           <Input
             id="email"
             name="email"
             type="email"
             required
             className="w-full"
-            placeholder="seu@email.com"
+            placeholder={t('forgotPassword.emailPlaceholder')}
             value={email}
             onChange={e => setEmail(e.target.value)}
           />
         </div>
         <div className="space-y-3">
           <Button type="submit" className="w-full" disabled={isLoading}>
-            {isLoading ? 'Enviando...' : 'Enviar instruções'}
+            {isLoading ? t('forgotPassword.submitting') : t('forgotPassword.submit')}
           </Button>
           <Button
             type="button"
@@ -59,7 +61,7 @@ export function ForgotPasswordContent() {
             className="w-full text-muted-foreground hover:text-foreground"
           >
             <ArrowLeft className="w-4 h-4 mr-2" />
-            Voltar para login
+            {t('forgotPassword.backToLogin')}
           </Button>
         </div>
       </form>

package/templates/src/features/auth/ui/LoginContent.tsx

@@ -4,6 +4,7 @@ import { XerticaLogo } from 'xertica-ui/brand';
 import { useNavigate } from 'react-router-dom';
 import { AuthPageShell } from './AuthPageShell';
 import { SocialLoginButtons } from './SocialLoginButtons';
+import { useTranslation } from 'react-i18next';
 
 interface LoginContentProps {
   onLogin: (email: string, password: string) => boolean;
@@ -11,6 +12,7 @@ interface LoginContentProps {
 
 export function LoginContent({ onLogin }: LoginContentProps) {
   const navigate = useNavigate();
+  const { t } = useTranslation();
   const [email, setEmail] = useState('');
   const [password, setPassword] = useState('');
   const [isLoading, setIsLoading] = useState(false);
@@ -21,38 +23,38 @@ export function LoginContent({ onLogin }: LoginContentProps) {
     setError('');
     setIsLoading(true);
     await new Promise(resolve => setTimeout(resolve, 1000));
-    if (!onLogin(email, password)) setError('Por favor, preencha todos os campos');
+    if (!onLogin(email, password)) setError(t('login.errorFillFields'));
     setIsLoading(false);
   };
 
   return (
     <AuthPageShell
       imageSrc="https://images.unsplash.com/photo-1551434678-e076c223a692?w=1200&h=800&fit=crop&auto=format"
-      imageAlt="Equipe trabalhando com tecnologia"
+      imageAlt={t('login.heroImageAlt')}
     >
       <div className="text-center">
         <div className="flex items-center justify-center mb-4">
           <XerticaLogo className="h-12 w-auto text-primary dark:text-foreground" variant="theme" />
         </div>
-        <h2 className="text-sm text-muted-foreground">Faça login em sua conta</h2>
+        <h2 className="text-sm text-muted-foreground">{t('login.heading')}</h2>
       </div>
 
       <form className="space-y-6" onSubmit={handleSubmit}>
         <div className="space-y-2">
-          <Label htmlFor="email">E-mail</Label>
+          <Label htmlFor="email">{t('login.emailLabel')}</Label>
           <Input
             id="email"
             name="email"
             type="email"
             required
             className="w-full"
-            placeholder="seu@email.com"
+            placeholder={t('login.emailPlaceholder')}
             value={email}
             onChange={e => setEmail(e.target.value)}
           />
         </div>
         <div className="space-y-2">
-          <Label htmlFor="password">Senha</Label>
+          <Label htmlFor="password">{t('login.passwordLabel')}</Label>
           <Input
             id="password"
             name="password"
@@ -66,7 +68,7 @@ export function LoginContent({ onLogin }: LoginContentProps) {
         </div>
         {error && <div className="text-destructive text-sm text-center">{error}</div>}
         <Button type="submit" className="w-full" disabled={isLoading}>
-          {isLoading ? 'Entrando...' : 'Entrar'}
+          {isLoading ? t('login.submitting') : t('login.submit')}
         </Button>
         <div className="text-center">
           <button
@@ -74,7 +76,7 @@ export function LoginContent({ onLogin }: LoginContentProps) {
             onClick={() => navigate('/forgot-password')}
             className="text-sm text-primary hover:opacity-80 transition-colors"
           >
-            Esqueceu sua senha?
+            {t('login.forgotPassword')}
           </button>
         </div>
       </form>