xertica-ui 2.1.2 → 2.1.4

package/docs/patterns/settings.md

@@ -0,0 +1,346 @@
+# Pattern: Settings Page
+
+A structured settings page with categorized sections, form fields, and save/cancel actions. Suitable for user preferences, application configuration, and account management.
+
+---
+
+## When to Use
+
+Use the Settings pattern when:
+- Users need to configure personal preferences (theme, language, notifications)
+- Administrators need to manage application-level configuration
+- Account management (profile, password, API keys) is required
+- Settings are grouped into logical categories (General, Security, Notifications, etc.)
+
+---
+
+## Components Used
+
+- [`PageHeader`](../components/page-header.md) — page title and breadcrumb
+- [`Card`](../components/card.md) — settings section container
+- [`Tabs`](../components/tabs.md) — category navigation (sidebar or top tabs)
+- [`Form`](../components/form.md) + form elements — settings fields
+- [`Switch`](../components/switch.md) — boolean toggles
+- [`Select`](../components/select.md) — option dropdowns
+- [`Input`](../components/input.md) — text settings
+- [`Button`](../components/button.md) — Save and Cancel actions
+- [`Separator`](../components/separator.md) — section dividers
+- [`Sonner`](../components/sonner.md) — success/error toast after save
+
+---
+
+## Basic Structure
+
+```tsx
+import {
+  Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle,
+  Tabs, TabsContent, TabsList, TabsTrigger,
+  Button, Input, Label, Switch, Select, SelectContent, SelectItem,
+  SelectTrigger, SelectValue, Separator,
+} from 'xertica-ui/ui';
+import { PageHeader, PageHeaderHeading, PageHeaderDescription } from 'xertica-ui/ui';
+import { toast } from 'sonner';
+
+export function SettingsPage() {
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      <PageHeader>
+        <div>
+          <PageHeaderHeading>Configurações</PageHeaderHeading>
+          <PageHeaderDescription>
+            Gerencie suas preferências e configurações da conta.
+          </PageHeaderDescription>
+        </div>
+      </PageHeader>
+
+      <div className="flex-1 overflow-y-auto p-6">
+        <Tabs defaultValue="general" className="space-y-6">
+          <TabsList>
+            <TabsTrigger value="general">Geral</TabsTrigger>
+            <TabsTrigger value="security">Segurança</TabsTrigger>
+            <TabsTrigger value="notifications">Notificações</TabsTrigger>
+            <TabsTrigger value="api">API Keys</TabsTrigger>
+          </TabsList>
+
+          <TabsContent value="general">
+            <GeneralSettings />
+          </TabsContent>
+
+          <TabsContent value="security">
+            <SecuritySettings />
+          </TabsContent>
+
+          <TabsContent value="notifications">
+            <NotificationSettings />
+          </TabsContent>
+
+          <TabsContent value="api">
+            <ApiKeySettings />
+          </TabsContent>
+        </Tabs>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## General Settings Section
+
+```tsx
+function GeneralSettings() {
+  const [name, setName] = useState('João Silva');
+  const [language, setLanguage] = useState('pt-BR');
+  const [theme, setTheme] = useState('system');
+
+  const handleSave = () => {
+    // persist settings
+    toast.success('Configurações salvas com sucesso.');
+  };
+
+  return (
+    <div className="space-y-6 max-w-2xl">
+      {/* Profile */}
+      <Card>
+        <CardHeader>
+          <CardTitle>Perfil</CardTitle>
+          <CardDescription>Informações básicas da sua conta.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="name">Nome completo</Label>
+            <Input
+              id="name"
+              value={name}
+              onChange={e => setName(e.target.value)}
+            />
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Preferences */}
+      <Card>
+        <CardHeader>
+          <CardTitle>Preferências</CardTitle>
+          <CardDescription>Idioma e aparência da interface.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="space-y-2">
+            <Label>Idioma</Label>
+            <Select value={language} onValueChange={setLanguage}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="pt-BR">Português (Brasil)</SelectItem>
+                <SelectItem value="en">English</SelectItem>
+                <SelectItem value="es">Español</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div className="space-y-2">
+            <Label>Tema</Label>
+            <Select value={theme} onValueChange={setTheme}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="light">Claro</SelectItem>
+                <SelectItem value="dark">Escuro</SelectItem>
+                <SelectItem value="system">Sistema</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+        </CardContent>
+        <CardFooter className="flex justify-end gap-2">
+          <Button variant="outline">Cancelar</Button>
+          <Button onClick={handleSave}>Salvar alterações</Button>
+        </CardFooter>
+      </Card>
+    </div>
+  );
+}
+```
+
+---
+
+## Notification Settings Section
+
+```tsx
+function NotificationSettings() {
+  const [notifications, setNotifications] = useState({
+    email: true,
+    push: false,
+    weeklyReport: true,
+    securityAlerts: true,
+  });
+
+  const toggle = (key: keyof typeof notifications) => {
+    setNotifications(prev => ({ ...prev, [key]: !prev[key] }));
+  };
+
+  const items = [
+    { key: 'email', label: 'Notificações por e-mail', description: 'Receba atualizações no seu e-mail' },
+    { key: 'push', label: 'Notificações push', description: 'Notificações no navegador' },
+    { key: 'weeklyReport', label: 'Relatório semanal', description: 'Resumo de atividades toda segunda-feira' },
+    { key: 'securityAlerts', label: 'Alertas de segurança', description: 'Notificações sobre acessos suspeitos' },
+  ];
+
+  return (
+    <Card className="max-w-2xl">
+      <CardHeader>
+        <CardTitle>Notificações</CardTitle>
+        <CardDescription>Escolha quais notificações deseja receber.</CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-0">
+        {items.map(({ key, label, description }, index) => (
+          <div key={key}>
+            <div className="flex items-center justify-between py-4">
+              <div className="space-y-0.5">
+                <Label className="text-base">{label}</Label>
+                <p className="text-sm text-muted-foreground">{description}</p>
+              </div>
+              <Switch
+                checked={notifications[key as keyof typeof notifications]}
+                onCheckedChange={() => toggle(key as keyof typeof notifications)}
+              />
+            </div>
+            {index < items.length - 1 && <Separator />}
+          </div>
+        ))}
+      </CardContent>
+      <CardFooter className="flex justify-end">
+        <Button onClick={() => toast.success('Preferências de notificação salvas.')}>
+          Salvar
+        </Button>
+      </CardFooter>
+    </Card>
+  );
+}
+```
+
+---
+
+## Security Settings Section
+
+```tsx
+function SecuritySettings() {
+  const [currentPassword, setCurrentPassword] = useState('');
+  const [newPassword, setNewPassword] = useState('');
+  const [confirmPassword, setConfirmPassword] = useState('');
+
+  const handleChangePassword = () => {
+    if (newPassword !== confirmPassword) {
+      toast.error('As senhas não coincidem.');
+      return;
+    }
+    // call API
+    toast.success('Senha alterada com sucesso.');
+    setCurrentPassword('');
+    setNewPassword('');
+    setConfirmPassword('');
+  };
+
+  return (
+    <Card className="max-w-2xl">
+      <CardHeader>
+        <CardTitle>Alterar Senha</CardTitle>
+        <CardDescription>Use uma senha forte com pelo menos 8 caracteres.</CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="space-y-2">
+          <Label htmlFor="current-password">Senha atual</Label>
+          <Input
+            id="current-password"
+            type="password"
+            value={currentPassword}
+            onChange={e => setCurrentPassword(e.target.value)}
+          />
+        </div>
+        <div className="space-y-2">
+          <Label htmlFor="new-password">Nova senha</Label>
+          <Input
+            id="new-password"
+            type="password"
+            value={newPassword}
+            onChange={e => setNewPassword(e.target.value)}
+          />
+        </div>
+        <div className="space-y-2">
+          <Label htmlFor="confirm-password">Confirmar nova senha</Label>
+          <Input
+            id="confirm-password"
+            type="password"
+            value={confirmPassword}
+            onChange={e => setConfirmPassword(e.target.value)}
+          />
+        </div>
+      </CardContent>
+      <CardFooter className="flex justify-end">
+        <Button onClick={handleChangePassword}>Alterar senha</Button>
+      </CardFooter>
+    </Card>
+  );
+}
+```
+
+---
+
+## API Key Settings Section
+
+```tsx
+import { useApiKey } from 'xertica-ui/hooks';
+
+function ApiKeySettings() {
+  const { geminiApiKey, setGeminiApiKey } = useApiKey();
+  const [localKey, setLocalKey] = useState(geminiApiKey);
+
+  const handleSave = () => {
+    setGeminiApiKey(localKey);
+    toast.success('API key salva com sucesso.');
+  };
+
+  return (
+    <Card className="max-w-2xl">
+      <CardHeader>
+        <CardTitle>Chaves de API</CardTitle>
+        <CardDescription>
+          Configure as chaves de API para os serviços integrados.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="space-y-2">
+          <Label htmlFor="gemini-key">Google Gemini API Key</Label>
+          <Input
+            id="gemini-key"
+            type="password"
+            value={localKey}
+            onChange={e => setLocalKey(e.target.value)}
+            placeholder="AIza..."
+          />
+          <p className="text-xs text-muted-foreground">
+            Necessária para o assistente de IA em modo real.
+          </p>
+        </div>
+      </CardContent>
+      <CardFooter className="flex justify-end">
+        <Button onClick={handleSave}>Salvar chave</Button>
+      </CardFooter>
+    </Card>
+  );
+}
+```
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **One `Card` per settings group**: Group related settings into a single `Card` with a `CardHeader` (title + description), `CardContent` (fields), and `CardFooter` (Save/Cancel buttons).
+> - **Use `Switch` for boolean settings**: Never use `Checkbox` for on/off toggles in settings. `Switch` is the correct component for this context.
+> - **Always show a toast after save**: Use `toast.success()` from `sonner` to confirm that settings were saved. Use `toast.error()` for validation failures.
+> - **`Tabs` for categories**: When there are more than 2 settings categories, use `Tabs` to organize them. Do not use a custom sidebar navigation.
+> - **Password fields use `type="password"`**: Never render password inputs as plain text. Always use `<Input type="password">`.
+> - **API keys via `useApiKey`**: Use the `useApiKey()` hook from `xertica-ui/hooks` to read and write API keys. Do not store them in component state or `localStorage` directly.

package/docs/patterns/wizard.md

@@ -0,0 +1,217 @@
+# Pattern: Wizard (Multi-Step Form)
+
+A multi-step form pattern using the `Stepper` component to guide users through a sequential process with validation at each step.
+
+---
+
+## When to Use
+
+Use the Wizard pattern when:
+- A form has more than 4–5 fields and benefits from being broken into logical sections
+- Each step has its own validation before proceeding
+- The user needs to review a summary before final submission
+- The process has a clear linear sequence (e.g., onboarding, checkout, configuration)
+
+---
+
+## Components Used
+
+- [`Stepper`](../components/stepper.md) — step indicator and navigation
+- [`Card`](../components/card.md) — content container for each step
+- [`Button`](../components/button.md) — Next, Back, and Submit actions
+- [`Form`](../components/form.md) + [`Input`](../components/input.md) — form fields with validation
+- [`PageHeader`](../components/page-header.md) — page title and breadcrumb
+
+---
+
+## Basic Structure
+
+```tsx
+import { useState } from 'react';
+import { Stepper } from 'xertica-ui/ui';
+import { Button } from 'xertica-ui/ui';
+import { Card, CardContent, CardFooter, CardHeader, CardTitle } from 'xertica-ui/ui';
+
+const STEPS = [
+  { id: 'info',    label: 'Informações Básicas' },
+  { id: 'address', label: 'Endereço' },
+  { id: 'review',  label: 'Revisão' },
+];
+
+export function WizardExample() {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [formData, setFormData] = useState({
+    name: '', email: '',
+    street: '', city: '',
+  });
+
+  const isLastStep = currentStep === STEPS.length - 1;
+
+  const handleNext = () => {
+    if (!isLastStep) setCurrentStep(s => s + 1);
+    else handleSubmit();
+  };
+
+  const handleBack = () => {
+    if (currentStep > 0) setCurrentStep(s => s - 1);
+  };
+
+  const handleSubmit = () => {
+    console.log('Submitted:', formData);
+  };
+
+  return (
+    <div className="max-w-2xl mx-auto p-6 space-y-6">
+      <Stepper
+        steps={STEPS}
+        currentStep={currentStep}
+        onStepClick={setCurrentStep}
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle>{STEPS[currentStep].label}</CardTitle>
+        </CardHeader>
+
+        <CardContent>
+          {currentStep === 0 && <StepBasicInfo data={formData} onChange={setFormData} />}
+          {currentStep === 1 && <StepAddress data={formData} onChange={setFormData} />}
+          {currentStep === 2 && <StepReview data={formData} />}
+        </CardContent>
+
+        <CardFooter className="flex justify-between">
+          <Button
+            variant="outline"
+            onClick={handleBack}
+            disabled={currentStep === 0}
+          >
+            Voltar
+          </Button>
+          <Button onClick={handleNext}>
+            {isLastStep ? 'Confirmar' : 'Próximo'}
+          </Button>
+        </CardFooter>
+      </Card>
+    </div>
+  );
+}
+```
+
+---
+
+## Step Components
+
+Each step is a focused form section:
+
+```tsx
+function StepBasicInfo({ data, onChange }) {
+  return (
+    <div className="space-y-4">
+      <div className="space-y-2">
+        <Label htmlFor="name">Nome completo</Label>
+        <Input
+          id="name"
+          value={data.name}
+          onChange={e => onChange(prev => ({ ...prev, name: e.target.value }))}
+          placeholder="João Silva"
+        />
+      </div>
+      <div className="space-y-2">
+        <Label htmlFor="email">E-mail</Label>
+        <Input
+          id="email"
+          type="email"
+          value={data.email}
+          onChange={e => onChange(prev => ({ ...prev, email: e.target.value }))}
+          placeholder="joao@empresa.com"
+        />
+      </div>
+    </div>
+  );
+}
+
+function StepReview({ data }) {
+  return (
+    <div className="space-y-3">
+      <div className="flex justify-between py-2 border-b border-border">
+        <span className="text-muted-foreground">Nome</span>
+        <span className="font-medium">{data.name}</span>
+      </div>
+      <div className="flex justify-between py-2 border-b border-border">
+        <span className="text-muted-foreground">E-mail</span>
+        <span className="font-medium">{data.email}</span>
+      </div>
+      <div className="flex justify-between py-2 border-b border-border">
+        <span className="text-muted-foreground">Endereço</span>
+        <span className="font-medium">{data.street}, {data.city}</span>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## With React Hook Form Validation
+
+For production forms, integrate `react-hook-form` with per-step validation:
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from 'xertica-ui/ui';
+
+function StepBasicInfoValidated({ onValid }) {
+  const form = useForm({
+    defaultValues: { name: '', email: '' },
+  });
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onValid)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="name"
+          rules={{ required: 'Nome é obrigatório' }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Nome</FormLabel>
+              <FormControl>
+                <Input {...field} placeholder="João Silva" />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Próximo</Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+---
+
+## Progress Persistence
+
+For long wizards, persist progress in `localStorage` or a URL query parameter:
+
+```tsx
+// Save step to URL
+const [searchParams, setSearchParams] = useSearchParams();
+const currentStep = parseInt(searchParams.get('step') || '0');
+
+const handleNext = () => {
+  setSearchParams({ step: String(currentStep + 1) });
+};
+```
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Use `Stepper` for the indicator**: Never build a custom step indicator with raw `div` elements. The `Stepper` component handles accessibility, active state, and completed state automatically.
+> - **One `Card` per step**: Each step's content should be inside a single `Card`. Do not render multiple cards or use `Tabs` as a substitute for `Stepper`.
+> - **Validate before advancing**: Always validate the current step's fields before calling `setCurrentStep(s => s + 1)`. Use `react-hook-form`'s `trigger()` method for partial validation.
+> - **Review step is read-only**: The final review step should display a summary of all collected data. It must not contain editable fields.
+> - **Back button is never disabled on step > 0**: Users must always be able to go back. Only disable the Back button on the first step.

package/guidelines/Guidelines.md

@@ -95,17 +95,19 @@ The root `from 'xertica-ui'` exports everything and remains supported for backwa
 
 ## 5. Design Tokens — Rules for Component Authors
 
-All components must use semantic CSS tokens exclusively. Never hardcode colors, radii, or shadows:
+All **library components** (`components/ui/`, `components/layout/`, etc.) must use semantic CSS tokens exclusively. Never hardcode colors, radii, or shadows in library source:
 
 ```tsx
-// ✅ Correct
+// ✅ Correct — library component
 className="bg-primary text-primary-foreground rounded-[var(--radius)]"
 
-// ❌ Wrong
+// ❌ Wrong — library component
 className="bg-blue-600 text-white rounded-lg"
 style={{ backgroundColor: '#3b82f6' }}
 ```
 
+> **Note for Storybook stories and consumer applications:** The strict "semantic tokens only" rule applies to **library component internals** and to **semantic/status contexts** (error states, warning banners, success indicators, status badges) in all code. For layout, spacing, and general non-semantic UI in stories or consumer apps, standard Tailwind color utilities (`bg-blue-500`, `text-gray-700`) are acceptable when no semantic token maps to the intent. Raw hex values and `rgb()`/`hsl()` literals are **never** acceptable in any context.
+
 ### Token reference
 
 ```

package/llms.txt

@@ -51,7 +51,7 @@ import 'xertica-ui/style.css';
 - [Calendar](docs/components/calendar.md): Date picker. Almost always wrapped in `Popover`.
 - [Card](docs/components/card.md): Primary content container. Never recreate with raw `<div>`.
 - [Carousel](docs/components/carousel.md): Horizontal content slider. Built on embla-carousel.
-- [Chart](docs/components/chart.md): Token-aware charts built on Recharts. Use `ChartContainer`; dashboard-ready wrappers include `ChartCard`, `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, and `DonutBreakdownChart`.
+- [Chart](docs/components/chart.md): Token-aware charts built on Recharts. Use `ChartContainer`; 11 dashboard-ready wrappers: `ChartCard`, `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, `DonutBreakdownChart`, `SparklineChart`, `RadarMetricChart`, `PieMetricChart`, `RadialBarMetricChart`, and `GaugeChart` (pure SVG semicircle gauge with thresholds).
 - [Checkbox](docs/components/checkbox.md): Boolean toggle or multi-select option.
 - [Collapsible](docs/components/collapsible.md): Single expandable section — no sibling management.
 - [Command](docs/components/command.md): Command palette (⌘K). Searchable action list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xertica-ui",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "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",
@@ -154,12 +154,12 @@
     "react-router-dom": "^7.1.3"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^5.1.2",
-    "@storybook/addon-a11y": "10.3.5",
-    "@storybook/addon-docs": "10.3.5",
-    "@storybook/addon-onboarding": "10.3.5",
-    "@storybook/addon-vitest": "^10.3.5",
-    "@storybook/react-vite": "10.3.5",
+    "@chromatic-com/storybook": "^5.2.1",
+    "@storybook/addon-a11y": "10.4.0",
+    "@storybook/addon-docs": "10.4.0",
+    "@storybook/addon-onboarding": "10.4.0",
+    "@storybook/addon-vitest": "^10.4.0",
+    "@storybook/react-vite": "10.4.0",
     "@tailwindcss/postcss": "^4.0.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
@@ -182,7 +182,7 @@
     "eslint": "^9.18.0",
     "eslint-plugin-react-hooks": "^5.1.0",
     "eslint-plugin-react-refresh": "^0.4.16",
-    "eslint-plugin-storybook": "^10.3.5",
+    "eslint-plugin-storybook": "^10.4.0",
     "globals": "^15.14.0",
     "jsdom": "^29.0.2",
     "playwright": "^1.59.1",
@@ -191,7 +191,7 @@
     "react-dom": "^18.3.1",
     "react-router-dom": "^7.1.3",
     "set-cookie-parser": "^3.1.0",
-    "storybook": "^10.3.6",
+    "storybook": "^10.4.0",
     "tailwindcss": "^4.0.0",
     "ts-morph": "^28.0.0",
     "ts-node": "^10.9.2",
@@ -200,4 +200,4 @@
     "vite": "^6.0.5",
     "vitest": "^4.1.5"
   }
-}
+}