xertica-ui 2.2.1 → 2.3.0

package/templates/CLAUDE.md

@@ -1,165 +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.
-
-## 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.
+# 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/eslint.config.js

@@ -1,26 +1,26 @@
-import js from '@eslint/js';
-import globals from 'globals';
-import reactHooks from 'eslint-plugin-react-hooks';
-import reactRefresh from 'eslint-plugin-react-refresh';
-import tseslint from 'typescript-eslint';
-
-export default tseslint.config(
-  { ignores: ['dist/**', 'node_modules/**', '.vite/**'] },
-  {
-    extends: [js.configs.recommended, ...tseslint.configs.recommended],
-    files: ['**/*.{ts,tsx}'],
-    languageOptions: {
-      ecmaVersion: 2020,
-      globals: globals.browser,
-    },
-    plugins: {
-      'react-hooks': reactHooks,
-      'react-refresh': reactRefresh,
-    },
-    rules: {
-      ...reactHooks.configs.recommended.rules,
-      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
-      '@typescript-eslint/no-explicit-any': 'off',
-    },
-  }
-);
+import js from '@eslint/js';
+import globals from 'globals';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  { ignores: ['dist/**', 'node_modules/**', '.vite/**'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  }
+);

package/templates/package.json

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

package/templates/postcss.config.js

@@ -1,6 +1,6 @@
-export default {
-  plugins: {
-    '@tailwindcss/postcss': {},
-    autoprefixer: {},
-  },
-};
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+    autoprefixer: {},
+  },
+};

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

@@ -1,55 +1,55 @@
-import React from 'react';
-import { useLocation, useNavigate } from 'react-router-dom';
-import { Sidebar } from 'xertica-ui/layout';
-import { useLayout } from 'xertica-ui/hooks';
-import { routes } from '../../shared/config/navigation';
-import { useAuth } from '../context/AuthContext';
-
-interface AppLayoutProps {
-  children: React.ReactNode;
-  assistant?: React.ReactNode;
-  sidebarVariant?: 'default' | 'assistant';
-  sidebarProps?: Record<string, any>;
-}
-
-/**
- * `AppLayout` — shared shell for all authenticated pages.
- *
- * Auth state (user, logout) is consumed from `AuthContext` — no props needed.
- * Pass only layout-specific concerns: `children`, `assistant`, and sidebar options.
- */
-export function AppLayout({
-  children,
-  assistant,
-  sidebarVariant = 'default',
-  sidebarProps,
-}: AppLayoutProps) {
-  const { user, logout } = useAuth();
-  const { sidebarExpanded, sidebarWidth, toggleSidebar } = 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}
-        variant={sidebarVariant}
-        user={{
-          ...user,
-          name: 'Ariel Santos',
-          avatar: 'https://github.com/shadcn.png',
-        }}
-        onLogout={logout}
-        onSettingsClick={() => navigate('/settings')}
-        location={location}
-        navigate={navigate}
-        routes={routes}
-        {...sidebarProps}
-      />
-      {children}
-      {assistant}
-    </div>
-  );
-}
+import React from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import { Sidebar } from 'xertica-ui/layout';
+import { useLayout } from 'xertica-ui/hooks';
+import { routes } from '../../shared/config/navigation';
+import { useAuth } from '../context/AuthContext';
+
+interface AppLayoutProps {
+  children: React.ReactNode;
+  assistant?: React.ReactNode;
+  sidebarVariant?: 'default' | 'assistant';
+  sidebarProps?: Record<string, any>;
+}
+
+/**
+ * `AppLayout` — shared shell for all authenticated pages.
+ *
+ * Auth state (user, logout) is consumed from `AuthContext` — no props needed.
+ * Pass only layout-specific concerns: `children`, `assistant`, and sidebar options.
+ */
+export function AppLayout({
+  children,
+  assistant,
+  sidebarVariant = 'default',
+  sidebarProps,
+}: AppLayoutProps) {
+  const { user, logout } = useAuth();
+  const { sidebarExpanded, sidebarWidth, toggleSidebar } = 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}
+        variant={sidebarVariant}
+        user={{
+          ...user,
+          name: 'Ariel Santos',
+          avatar: 'https://github.com/shadcn.png',
+        }}
+        onLogout={logout}
+        onSettingsClick={() => navigate('/settings')}
+        location={location}
+        navigate={navigate}
+        routes={routes}
+        {...sidebarProps}
+      />
+      {children}
+      {assistant}
+    </div>
+  );
+}