xertica-ui 2.3.0 → 2.4.1

package/llms.txt

@@ -1,6 +1,6 @@
 # Xertica UI
 
-> Enterprise-grade React design system — 97 components built on Tailwind CSS v4, Radix UI, and Lucide Icons. Designed to be consumed directly by AI coding agents (LLMs, Cursor, Claude Code, Copilot). v2.3.0
+> Enterprise-grade React design system — 97 components built on Tailwind CSS v4, Radix UI, and Lucide Icons. Designed to be consumed directly by AI coding agents (LLMs, Cursor, Claude Code, Copilot). v2.4.1
 
 Xertica UI ships with full source, typed declarations, Storybook stories, and structured documentation inside `node_modules/xertica-ui/`. AI agents should read this file first, then follow links for component-specific detail.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xertica-ui",
-  "version": "2.3.0",
+  "version": "2.4.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/styles/xertica/base.css

@@ -1,84 +1,90 @@
-/* ============================================
-   🧱 BASE STYLES
-   ============================================ */
-
-@import 'tailwindcss';
-@plugin "tailwindcss-animate";
-
-@custom-variant dark (&:is(.dark *));
-@custom-variant mobile (@media (max-width: 767px));
-
-@layer base {
-  * {
-    @apply border-border outline-ring/50;
-  }
-
-  body {
-    @apply bg-background text-foreground;
-    font-family: 'Roboto', sans-serif;
-  }
-
-  html {
-    font-size: var(--font-size);
-  }
-
-  h1 {
-    font-size: var(--text-h1);
-    font-weight: var(--font-weight-extrabold);
-    line-height: 1.2;
-  }
-
-  h2 {
-    font-size: var(--text-h2);
-    font-weight: var(--font-weight-semibold);
-    line-height: 1.2;
-  }
-
-  h3 {
-    font-size: var(--text-h3);
-    font-weight: var(--font-weight-semibold);
-    line-height: 1.2;
-  }
-
-  h4 {
-    font-size: var(--text-h4);
-    font-weight: var(--font-weight-semibold);
-    line-height: 1.2;
-  }
-
-  p {
-    font-size: var(--text-p);
-    font-weight: var(--font-weight-regular);
-    line-height: 1.5;
-  }
-
-  label {
-    font-size: var(--text-label);
-    font-weight: var(--font-weight-semibold);
-    line-height: 1.3;
-  }
-
-  button {
-    font-size: var(--text-small);
-    font-weight: var(--font-weight-medium);
-    line-height: 1.4;
-  }
-
-  input {
-    font-size: var(--text-small);
-    font-weight: var(--font-weight-regular);
-    line-height: 1.4;
-  }
-}
-
-@layer utilities {
-  /* Global mobile content padding utility class.
-     Add class="content-area" to any wrapper to receive the mobile padding.
-     Change --mobile-content-padding in tokens.css to adjust globally. */
-  @media (max-width: 767px) {
-    .content-area {
-      padding-left: var(--mobile-content-padding);
-      padding-right: var(--mobile-content-padding);
-    }
-  }
-}
+/* ============================================
+   🧱 BASE STYLES
+   ============================================ */
+
+@import 'tailwindcss';
+@plugin "tailwindcss-animate";
+
+@custom-variant dark (&:is(.dark *));
+@custom-variant mobile (@media (max-width: 767px));
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  html,
+  body {
+    height: 100%;
+    overflow: hidden;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+    font-family: 'Roboto', sans-serif;
+  }
+
+  html {
+    font-size: var(--font-size);
+  }
+
+  h1 {
+    font-size: var(--text-h1);
+    font-weight: var(--font-weight-extrabold);
+    line-height: 1.2;
+  }
+
+  h2 {
+    font-size: var(--text-h2);
+    font-weight: var(--font-weight-semibold);
+    line-height: 1.2;
+  }
+
+  h3 {
+    font-size: var(--text-h3);
+    font-weight: var(--font-weight-semibold);
+    line-height: 1.2;
+  }
+
+  h4 {
+    font-size: var(--text-h4);
+    font-weight: var(--font-weight-semibold);
+    line-height: 1.2;
+  }
+
+  p {
+    font-size: var(--text-p);
+    font-weight: var(--font-weight-regular);
+    line-height: 1.5;
+  }
+
+  label {
+    font-size: var(--text-label);
+    font-weight: var(--font-weight-semibold);
+    line-height: 1.3;
+  }
+
+  button {
+    font-size: var(--text-small);
+    font-weight: var(--font-weight-medium);
+    line-height: 1.4;
+  }
+
+  input {
+    font-size: var(--text-small);
+    font-weight: var(--font-weight-regular);
+    line-height: 1.4;
+  }
+}
+
+@layer utilities {
+  /* Global mobile content padding utility class.
+     Add class="content-area" to any wrapper to receive the mobile padding.
+     Change --mobile-content-padding in tokens.css to adjust globally. */
+  @media (max-width: 767px) {
+    .content-area {
+      padding-left: var(--mobile-content-padding);
+      padding-right: var(--mobile-content-padding);
+    }
+  }
+}

package/templates/CLAUDE.md

@@ -23,6 +23,7 @@ This project follows **FSD (Feature-Sliced Design)** layered architecture combin
 - **`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)
@@ -34,6 +35,7 @@ This project follows **FSD (Feature-Sliced Design)** layered architecture combin
 ## 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`)
@@ -49,7 +51,9 @@ 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>`
@@ -58,19 +62,24 @@ Never use native HTML interactive elements where design system components exist:
 - `<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>
@@ -90,11 +99,14 @@ Always wrap destructive actions in `<AlertDialog>` for confirmation:
 ```
 
 ### 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>`.
 
 ---
@@ -102,6 +114,7 @@ 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.
@@ -124,7 +137,7 @@ Every user-facing string must go through `useTranslation()`:
   return useQuery({
     queryKey: ['home', 'feature-cards', language],
     queryFn: fetchFeatureCards,
-    staleTime: 10 * 60 * 1000
+    staleTime: 10 * 60 * 1000,
   });
   ```
 
@@ -133,6 +146,7 @@ Every user-facing string must go through `useTranslation()`:
 ## 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" />`.
@@ -149,6 +163,7 @@ Always render matching skeletons instead of spinners for data loading:
 ## 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

package/templates/guidelines/Guidelines.md

@@ -302,11 +302,11 @@ Every user-facing string must come from `useTranslation()`. Add new keys to the
 
 ```tsx
 // ❌ Wrong
-<Button aria-label="Save">Save</Button>
+<Button aria-label="Save">Save</Button>;
 
 // ✅ Correct
 const { t } = useTranslation();
-<Button aria-label={t('common.save')}>{t('common.save')}</Button>
+<Button aria-label={t('common.save')}>{t('common.save')}</Button>;
 ```
 
 This applies to `aria-label`, `placeholder`, `title`, toast messages, error text, dropdown items — everything the user can read.
@@ -340,6 +340,7 @@ npx xertica-ui update
 ```
 
 The CLI shows your current selection, prompts for the new set, displays the diff (`+ es`, `- en`), and on confirm:
+
 - copies any newly-added locale JSONs from `node_modules/xertica-ui/templates/src/locales/`
 - removes JSONs of unselected languages
 - regenerates `src/i18n.ts` and `src/app/App.tsx`
@@ -347,6 +348,24 @@ The CLI shows your current selection, prompts for the new set, displays the diff
 
 > The `update` → **Project files** flow also reads `.languages.json` and preserves your selection. Updating App.tsx and i18n.ts won't reset your languages.
 
+### Enabling or disabling Dark Mode support later
+
+```bash
+npx xertica-ui update
+# → select "Dark Mode"
+```
+
+The CLI reads your current setting from `.xertica.json` and prompts you to enable or disable dark mode. On confirmation, it updates `.xertica.json` and regenerates `App.tsx` to set `disableDarkMode={true}` or `false`.
+
+### Adding or removing the AI Assistant later
+
+```bash
+npx xertica-ui update
+# → select "Assistant"
+```
+
+The CLI detects whether the assistant is currently active (via `.xertica.json` or page presence) and prompts to add or remove the feature. It automatically copies/deletes the feature files and updates `AuthGuard.tsx`, `HomePage.tsx`, and `TemplatePage.tsx` to reflect the change.
+
 ### Using translations in components
 
 ```tsx
@@ -385,10 +404,13 @@ export function getMockOptions() {
 Inside components, build label maps for enums with `useMemo([..., t])`:
 
 ```tsx
-const statusLabels = useMemo(() => ({
-  active: t('status.active'),
-  inactive: t('status.inactive'),
-}), [t]);
+const statusLabels = useMemo(
+  () => ({
+    active: t('status.active'),
+    inactive: t('status.inactive'),
+  }),
+  [t]
+);
 ```
 
 ---
@@ -447,9 +469,9 @@ Every card pattern ships with a matching `*Skeleton`:
 ```tsx
 import { ActivityCard, ActivityCardSkeleton } from 'xertica-ui';
 
-{isLoading
-  ? <ActivityCardSkeleton rows={5} />
-  : <ActivityCard items={items} />}
+{
+  isLoading ? <ActivityCardSkeleton rows={5} /> : <ActivityCard items={items} />;
+}
 ```
 
 Available skeleton companions: `ActivityCardSkeleton`, `ProfileCardSkeleton`, `ProjectCardSkeleton`, `NotificationCardSkeleton`, `QuickActionCardSkeleton`, `FeatureCardSkeleton`, `StatsCardSkeleton`.
@@ -457,15 +479,17 @@ Available skeleton companions: `ActivityCardSkeleton`, `ProfileCardSkeleton`, `P
 For grids, render one skeleton per expected card:
 
 ```tsx
-{isLoading ? (
-  <>
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-  </>
-) : (
-  data.map(item => <FeatureCard key={item.id} {...item} />)
-)}
+{
+  isLoading ? (
+    <>
+      <FeatureCardSkeleton showAction />
+      <FeatureCardSkeleton showAction />
+      <FeatureCardSkeleton showAction />
+    </>
+  ) : (
+    data.map(item => <FeatureCard key={item.id} {...item} />)
+  );
+}
 ```
 
 For tables, render skeleton rows with the `<Skeleton>` primitive (from `xertica-ui/ui`):

package/templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xertica-ui-template",
-  "version": "2.3.0",
+  "version": "2.4.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.3.0",
+    "xertica-ui": "^2.4.1",
     "zustand": "^5.0.13"
   },
   "devDependencies": {
@@ -66,4 +66,4 @@
       "vite": "6.3.5"
     }
   }
-}
+}

package/templates/src/app/components/AuthGuard.tsx

@@ -1,82 +1,131 @@
-import React from 'react';
-import { Routes, Route, Navigate } from 'react-router-dom';
-import { useAuth } from '../context/AuthContext';
-
-// ─── Lazy page imports ────────────────────────────────────────────────────────
-// Each route bundle is loaded only when the route is first visited.
-
-const LoginPage = React.lazy(() =>
-  import('../../pages/LoginPage').then(m => ({ default: m.LoginPage }))
-);
-const ForgotPasswordPage = React.lazy(() =>
-  import('../../pages/ForgotPasswordPage').then(m => ({ default: m.ForgotPasswordPage }))
-);
-const VerifyEmailPage = React.lazy(() =>
-  import('../../pages/VerifyEmailPage').then(m => ({ default: m.VerifyEmailPage }))
-);
-const ResetPasswordPage = React.lazy(() =>
-  import('../../pages/ResetPasswordPage').then(m => ({ default: m.ResetPasswordPage }))
-);
-const HomePage = React.lazy(() =>
-  import('../../pages/HomePage').then(m => ({ default: m.HomePage }))
-);
-const TemplatePage = React.lazy(() =>
-  import('../../pages/TemplatePage').then(m => ({ default: m.TemplatePage }))
-);
-const AssistantPage = React.lazy(() =>
-  import('../../pages/AssistantPage').then(m => ({ default: m.AssistantPage }))
-);
-
-// ─── Route guards ─────────────────────────────────────────────────────────────
-
-/** Redirects unauthenticated visitors to /login. */
-function ProtectedRoute({ children }: { children: React.ReactNode }) {
-  const { user, isLoading } = useAuth();
-  if (isLoading) return null;
-  if (!user) return <Navigate to="/login" replace />;
-  return <>{children}</>;
-}
-
-/** Redirects authenticated users away from auth-only pages. */
-function GuestRoute({ children }: { children: React.ReactNode }) {
-  const { user, isLoading } = useAuth();
-  if (isLoading) return null;
-  if (user) return <Navigate to="/home" replace />;
-  return <>{children}</>;
-}
-
-// ─── Bridge for LoginPage ─────────────────────────────────────────────────────
-// LoginPage expects an onLogin prop — this bridge wires AuthContext.login to it,
-// keeping the LoginPage component decoupled from the AuthContext.
-
-function LoginPageWithAuth() {
-  const { login } = useAuth();
-  return <LoginPage onLogin={login} />;
-}
-
-// ─── Route tree ───────────────────────────────────────────────────────────────
-
-export function AuthGuard() {
-  const { user } = useAuth();
-
-  return (
-    <div className="min-h-screen bg-muted overflow-x-hidden max-w-full">
-      <Routes>
-        {/* Auth pages — redirect to /home when already signed in */}
-        <Route path="/login" element={<GuestRoute><LoginPageWithAuth /></GuestRoute>} />
-        <Route path="/forgot-password" element={<GuestRoute><ForgotPasswordPage /></GuestRoute>} />
-        <Route path="/verify-email" element={<GuestRoute><VerifyEmailPage /></GuestRoute>} />
-        <Route path="/reset-password" element={<GuestRoute><ResetPasswordPage /></GuestRoute>} />
-
-        {/* Protected pages */}
-        <Route path="/home" element={<ProtectedRoute><HomePage /></ProtectedRoute>} />
-        <Route path="/template" element={<ProtectedRoute><TemplatePage /></ProtectedRoute>} />
-        <Route path="/assistente" element={<ProtectedRoute><AssistantPage /></ProtectedRoute>} />
-
-        {/* Fallback */}
-        <Route path="/" element={<Navigate to={user ? '/home' : '/login'} replace />} />
-        <Route path="*" element={<Navigate to={user ? '/home' : '/login'} replace />} />
-      </Routes>
-    </div>
-  );
-}
+import React from 'react';
+import { Routes, Route, Navigate } from 'react-router-dom';
+import { useAuth } from '../context/AuthContext';
+
+// ─── Lazy page imports ────────────────────────────────────────────────────────
+// Each route bundle is loaded only when the route is first visited.
+
+const LoginPage = React.lazy(() =>
+  import('../../pages/LoginPage').then(m => ({ default: m.LoginPage }))
+);
+const ForgotPasswordPage = React.lazy(() =>
+  import('../../pages/ForgotPasswordPage').then(m => ({ default: m.ForgotPasswordPage }))
+);
+const VerifyEmailPage = React.lazy(() =>
+  import('../../pages/VerifyEmailPage').then(m => ({ default: m.VerifyEmailPage }))
+);
+const ResetPasswordPage = React.lazy(() =>
+  import('../../pages/ResetPasswordPage').then(m => ({ default: m.ResetPasswordPage }))
+);
+const HomePage = React.lazy(() =>
+  import('../../pages/HomePage').then(m => ({ default: m.HomePage }))
+);
+const TemplatePage = React.lazy(() =>
+  import('../../pages/TemplatePage').then(m => ({ default: m.TemplatePage }))
+);
+const AssistantPage = React.lazy(() =>
+  import('../../pages/AssistantPage').then(m => ({ default: m.AssistantPage }))
+);
+
+// ─── Route guards ─────────────────────────────────────────────────────────────
+
+/** Redirects unauthenticated visitors to /login. */
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { user, isLoading } = useAuth();
+  if (isLoading) return null;
+  if (!user) return <Navigate to="/login" replace />;
+  return <>{children}</>;
+}
+
+/** Redirects authenticated users away from auth-only pages. */
+function GuestRoute({ children }: { children: React.ReactNode }) {
+  const { user, isLoading } = useAuth();
+  if (isLoading) return null;
+  if (user) return <Navigate to="/home" replace />;
+  return <>{children}</>;
+}
+
+// ─── Bridge for LoginPage ─────────────────────────────────────────────────────
+// LoginPage expects an onLogin prop — this bridge wires AuthContext.login to it,
+// keeping the LoginPage component decoupled from the AuthContext.
+
+function LoginPageWithAuth() {
+  const { login } = useAuth();
+  return <LoginPage onLogin={login} />;
+}
+
+// ─── Route tree ───────────────────────────────────────────────────────────────
+
+export function AuthGuard() {
+  const { user } = useAuth();
+
+  return (
+    <div className="h-screen bg-muted overflow-hidden max-w-full">
+      <Routes>
+        {/* Auth pages — redirect to /home when already signed in */}
+        <Route
+          path="/login"
+          element={
+            <GuestRoute>
+              <LoginPageWithAuth />
+            </GuestRoute>
+          }
+        />
+        <Route
+          path="/forgot-password"
+          element={
+            <GuestRoute>
+              <ForgotPasswordPage />
+            </GuestRoute>
+          }
+        />
+        <Route
+          path="/verify-email"
+          element={
+            <GuestRoute>
+              <VerifyEmailPage />
+            </GuestRoute>
+          }
+        />
+        <Route
+          path="/reset-password"
+          element={
+            <GuestRoute>
+              <ResetPasswordPage />
+            </GuestRoute>
+          }
+        />
+
+        {/* Protected pages */}
+        <Route
+          path="/home"
+          element={
+            <ProtectedRoute>
+              <HomePage />
+            </ProtectedRoute>
+          }
+        />
+        <Route
+          path="/template"
+          element={
+            <ProtectedRoute>
+              <TemplatePage />
+            </ProtectedRoute>
+          }
+        />
+        <Route
+          path="/assistente"
+          element={
+            <ProtectedRoute>
+              <AssistantPage />
+            </ProtectedRoute>
+          }
+        />
+
+        {/* Fallback */}
+        <Route path="/" element={<Navigate to={user ? '/home' : '/login'} replace />} />
+        <Route path="*" element={<Navigate to={user ? '/home' : '/login'} replace />} />
+      </Routes>
+    </div>
+  );
+}