xertica-ui 2.2.1 → 2.3.0

package/components/brand/language-selector/LanguageSelector.tsx

@@ -1,102 +1,102 @@
-import React from 'react';
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../ui/select';
-import { Globe } from 'lucide-react';
-import { useTranslation } from 'react-i18next';
-import { type Language, useLanguage } from '../../../contexts/LanguageContext';
-
-// Re-export the canonical Language type so consumers can import from either location.
-export type { Language };
-
-export interface LanguageSelectorProps {
-  /** Whether to show text labels alongside the globe icon */
-  showLabel?: boolean;
-  /** UI variant style */
-  variant?: 'minimal' | 'default';
-  /** Whether to show the globe icon */
-  showIcon?: boolean;
-  /** Additional CSS classes */
-  className?: string;
-  /**
-   * Whether to render the selector when only one language is configured.
-   * When `false` (the default), the selector hides itself in monolingual apps.
-   */
-  showWhenMonolingual?: boolean;
-}
-
-/**
- * `LanguageSelector` — a self-contained language picker wired to `LanguageContext`.
- *
- * The list of languages displayed is read from `LanguageContext.availableLanguages`
- * (configured via the `availableLanguages` prop on `<LanguageProvider>` or
- * `<XerticaProvider>`). The component is fully data-driven: pass any number of
- * languages and they will all appear in the dropdown.
- *
- * Changing the selected language:
- * 1. Updates `LanguageContext` (persists to localStorage)
- * 2. Calls `i18n.changeLanguage()` (all `useTranslation()` consumers re-render)
- * 3. Invalidates the React Query cache (data-layer strings refresh)
- *
- * **Auto-hide:** When only one language is configured (`isMonolingual === true`),
- * the component renders `null` by default. Pass `showWhenMonolingual` to override.
- *
- * Must be rendered inside `<LanguageProvider>`.
- */
-export function LanguageSelector({
-  showLabel = false,
-  variant = 'default',
-  showIcon = true,
-  className = '',
-  showWhenMonolingual = false,
-}: LanguageSelectorProps) {
-  const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
-  const { t } = useTranslation();
-
-  // Hide selector when only one language is configured
-  if (isMonolingual && !showWhenMonolingual) {
-    return null;
-  }
-
-  // Compute display labels with i18n fallback support.
-  // Known codes (pt-BR, en, es) get their localized label from translations;
-  // custom codes use the label provided in the LanguageDefinition.
-  const items = availableLanguages.map(lang => {
-    const knownLabelKey =
-      lang.code === 'pt-BR'
-        ? 'languageSelector.ptBR'
-        : lang.code === 'en'
-          ? 'languageSelector.en'
-          : lang.code === 'es'
-            ? 'languageSelector.es'
-            : null;
-
-    return {
-      value: lang.code,
-      label: knownLabelKey ? t(knownLabelKey, lang.label) : lang.label,
-      // Fall back to the first two characters of the code if no shortLabel given
-      minimalLabel: lang.shortLabel ?? lang.code.slice(0, 2).toUpperCase(),
-    };
-  });
-
-  const currentItem = items.find(l => l.value === language) ?? items[0];
-  const displayLabel = variant === 'minimal' ? currentItem.minimalLabel : currentItem.label;
-
-  return (
-    <Select value={language} onValueChange={val => setLanguage(val as Language)}>
-      <SelectTrigger
-        className={`h-9 gap-2 px-3 border-none shadow-none focus:ring-0 text-muted-foreground hover:bg-accent hover:text-accent-foreground ${className}`}
-        aria-label={t('languageSelector.label', 'Selecionar idioma')}
-      >
-        {showIcon && <Globe className="h-4 w-4 shrink-0" />}
-        {/* We do not use SelectValue here because it overrides our custom minimal rendering with the SelectItem's children. */}
-        <span className="text-sm">{displayLabel}</span>
-      </SelectTrigger>
-      <SelectContent align="end">
-        {items.map(({ value, label }) => (
-          <SelectItem key={value} value={value}>
-            {label}
-          </SelectItem>
-        ))}
-      </SelectContent>
-    </Select>
-  );
-}
+import React from 'react';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../ui/select';
+import { Globe } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { type Language, useLanguage } from '../../../contexts/LanguageContext';
+
+// Re-export the canonical Language type so consumers can import from either location.
+export type { Language };
+
+export interface LanguageSelectorProps {
+  /** Whether to show text labels alongside the globe icon */
+  showLabel?: boolean;
+  /** UI variant style */
+  variant?: 'minimal' | 'default';
+  /** Whether to show the globe icon */
+  showIcon?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+  /**
+   * Whether to render the selector when only one language is configured.
+   * When `false` (the default), the selector hides itself in monolingual apps.
+   */
+  showWhenMonolingual?: boolean;
+}
+
+/**
+ * `LanguageSelector` — a self-contained language picker wired to `LanguageContext`.
+ *
+ * The list of languages displayed is read from `LanguageContext.availableLanguages`
+ * (configured via the `availableLanguages` prop on `<LanguageProvider>` or
+ * `<XerticaProvider>`). The component is fully data-driven: pass any number of
+ * languages and they will all appear in the dropdown.
+ *
+ * Changing the selected language:
+ * 1. Updates `LanguageContext` (persists to localStorage)
+ * 2. Calls `i18n.changeLanguage()` (all `useTranslation()` consumers re-render)
+ * 3. Invalidates the React Query cache (data-layer strings refresh)
+ *
+ * **Auto-hide:** When only one language is configured (`isMonolingual === true`),
+ * the component renders `null` by default. Pass `showWhenMonolingual` to override.
+ *
+ * Must be rendered inside `<LanguageProvider>`.
+ */
+export function LanguageSelector({
+  showLabel = false,
+  variant = 'default',
+  showIcon = true,
+  className = '',
+  showWhenMonolingual = false,
+}: LanguageSelectorProps) {
+  const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
+  const { t } = useTranslation();
+
+  // Hide selector when only one language is configured
+  if (isMonolingual && !showWhenMonolingual) {
+    return null;
+  }
+
+  // Compute display labels with i18n fallback support.
+  // Known codes (pt-BR, en, es) get their localized label from translations;
+  // custom codes use the label provided in the LanguageDefinition.
+  const items = availableLanguages.map(lang => {
+    const knownLabelKey =
+      lang.code === 'pt-BR'
+        ? 'languageSelector.ptBR'
+        : lang.code === 'en'
+          ? 'languageSelector.en'
+          : lang.code === 'es'
+            ? 'languageSelector.es'
+            : null;
+
+    return {
+      value: lang.code,
+      label: knownLabelKey ? t(knownLabelKey, lang.label) : lang.label,
+      // Fall back to the first two characters of the code if no shortLabel given
+      minimalLabel: lang.shortLabel ?? lang.code.slice(0, 2).toUpperCase(),
+    };
+  });
+
+  const currentItem = items.find(l => l.value === language) ?? items[0];
+  const displayLabel = variant === 'minimal' ? currentItem.minimalLabel : currentItem.label;
+
+  return (
+    <Select value={language} onValueChange={val => setLanguage(val as Language)}>
+      <SelectTrigger
+        className={`h-9 gap-2 px-3 border-none shadow-none focus:ring-0 text-muted-foreground hover:bg-accent hover:text-accent-foreground ${className}`}
+        aria-label={t('languageSelector.label', 'Selecionar idioma')}
+      >
+        {showIcon && <Globe className="h-4 w-4 shrink-0" />}
+        {/* We do not use SelectValue here because it overrides our custom minimal rendering with the SelectItem's children. */}
+        <span className="text-sm">{displayLabel}</span>
+      </SelectTrigger>
+      <SelectContent align="end">
+        {items.map(({ value, label }) => (
+          <SelectItem key={value} value={value}>
+            {label}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}

package/components/brand/language-selector/index.ts

@@ -1 +1 @@
-export * from './LanguageSelector';
+export * from './LanguageSelector';

package/components/brand/language-selector/language-selector.mdx

@@ -1,126 +1,126 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as LanguageSelectorStories from './language-selector.stories';
-
-<Meta of={LanguageSelectorStories} />
-
-<Title />
-<Subtitle>A self-contained dropdown for switching the application language, wired to LanguageContext and i18next.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Usage
-
-```tsx
-import { LanguageSelector } from 'xertica-ui/brand';
-
-<LanguageSelector />
-```
-
-The component reads the current language from `LanguageContext` and changes it via `setLanguage()` — which persists to `localStorage`, calls `i18n.changeLanguage()`, and invalidates the React Query cache so that mock/API responses also refresh in the new language.
-
-### Minimal variant (short label only)
-
-```tsx
-<LanguageSelector variant="minimal" showIcon={false} />
-```
-
-### Force-visible in a monolingual app
-
-By default, the selector renders `null` when only one language is configured. Pass `showWhenMonolingual` to render anyway:
-
-```tsx
-<LanguageSelector showWhenMonolingual />
-```
-
----
-
-## Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `variant` | `'default' \| 'minimal'` | `'default'` | `minimal` uses the short label (e.g. `PT`, `EN`) instead of the full name |
-| `showIcon` | `boolean` | `true` | Show the globe icon next to the label |
-| `showLabel` | `boolean` | `false` | Reserved for future use — currently no visual effect |
-| `className` | `string` | `''` | Additional CSS classes applied to the trigger button |
-| `showWhenMonolingual` | `boolean` | `false` | Render the selector even when only one language is configured (would otherwise auto-hide) |
-
-> The component does **not** accept `initialLanguage` or `onLanguageChange`. Language state lives in `LanguageContext` — read or change it via `useLanguage()`.
-
----
-
-## Supported Languages
-
-By default, the selector exposes the three languages that ship with the library:
-
-| Code | Full label | Short label |
-|---|---|---|
-| `pt-BR` | Português (BR) | PT |
-| `en` | English | EN |
-| `es` | Español | ES |
-
-**The list is fully runtime-configurable.** Pass `availableLanguages` on `<XerticaProvider>` (or `<LanguageProvider>`) to add, remove, or restrict the languages shown.
-
-### Add a new language
-
-```tsx
-import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui';
-import fr from './locales/fr.json';
-
-<XerticaProvider
-  availableLanguages={[
-    ...DEFAULT_LANGUAGES,
-    { code: 'fr', label: 'Français', shortLabel: 'FR', resources: fr },
-  ]}
->
-  <LanguageSelector />
-  {/* French now appears in the dropdown; its strings are auto-registered with i18next */}
-</XerticaProvider>
-```
-
-### Monolingual app (no selector visible)
-
-```tsx
-<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
-  <LanguageSelector />
-  {/* Renders nothing — there is nothing to switch to */}
-</XerticaProvider>
-```
-
-### Programmatic access
-
-```tsx
-import { useLanguage } from 'xertica-ui';
-
-function MyComponent() {
-  const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
-  // ...
-}
-```
-
----
-
-## Behavior
-
-- **Reads** `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
-- **Persists** the selected language to `localStorage` under the key `xertica_language`
-- **Notifies** `i18next` via `i18n.changeLanguage()` — all components using `useTranslation()` re-render immediately
-- **Invalidates** the React Query cache so mock/API responses translated via `i18n.t()` are refetched in the new language
-- **Auto-hides** when `isMonolingual === true` (single-language apps)
-- **Labels**: known codes (`pt-BR`, `en`, `es`) use translated labels from `assistant.languageSelector.*`. Custom codes fall back to the `label` passed in the `LanguageDefinition`.
-- **Short labels**: when `variant="minimal"`, uses the `shortLabel` from the `LanguageDefinition`, or `code.slice(0, 2).toUpperCase()` as fallback
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
-> - **Placement**: Typically inside `Header` actions (`showLanguageSelector` prop) or the `Sidebar` footer.
-> - **`<LanguageProvider>` is required**: `LanguageSelector` calls `useLanguage()` and throws when rendered outside a `LanguageProvider`. `<XerticaProvider>` provides it automatically.
-> - **Do NOT pass `initialLanguage` or `onLanguageChange`** — these props were removed. Use `useLanguage()` to read or change the language programmatically.
-> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Use `showWhenMonolingual` only if you explicitly need it visible.
-> - **One instance per layout shell** — multiple selectors create UX confusion. Place a single instance in `Header` or `Sidebar`.
-> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as LanguageSelectorStories from './language-selector.stories';
+
+<Meta of={LanguageSelectorStories} />
+
+<Title />
+<Subtitle>A self-contained dropdown for switching the application language, wired to LanguageContext and i18next.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Usage
+
+```tsx
+import { LanguageSelector } from 'xertica-ui/brand';
+
+<LanguageSelector />
+```
+
+The component reads the current language from `LanguageContext` and changes it via `setLanguage()` — which persists to `localStorage`, calls `i18n.changeLanguage()`, and invalidates the React Query cache so that mock/API responses also refresh in the new language.
+
+### Minimal variant (short label only)
+
+```tsx
+<LanguageSelector variant="minimal" showIcon={false} />
+```
+
+### Force-visible in a monolingual app
+
+By default, the selector renders `null` when only one language is configured. Pass `showWhenMonolingual` to render anyway:
+
+```tsx
+<LanguageSelector showWhenMonolingual />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'minimal'` | `'default'` | `minimal` uses the short label (e.g. `PT`, `EN`) instead of the full name |
+| `showIcon` | `boolean` | `true` | Show the globe icon next to the label |
+| `showLabel` | `boolean` | `false` | Reserved for future use — currently no visual effect |
+| `className` | `string` | `''` | Additional CSS classes applied to the trigger button |
+| `showWhenMonolingual` | `boolean` | `false` | Render the selector even when only one language is configured (would otherwise auto-hide) |
+
+> The component does **not** accept `initialLanguage` or `onLanguageChange`. Language state lives in `LanguageContext` — read or change it via `useLanguage()`.
+
+---
+
+## Supported Languages
+
+By default, the selector exposes the three languages that ship with the library:
+
+| Code | Full label | Short label |
+|---|---|---|
+| `pt-BR` | Português (BR) | PT |
+| `en` | English | EN |
+| `es` | Español | ES |
+
+**The list is fully runtime-configurable.** Pass `availableLanguages` on `<XerticaProvider>` (or `<LanguageProvider>`) to add, remove, or restrict the languages shown.
+
+### Add a new language
+
+```tsx
+import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui';
+import fr from './locales/fr.json';
+
+<XerticaProvider
+  availableLanguages={[
+    ...DEFAULT_LANGUAGES,
+    { code: 'fr', label: 'Français', shortLabel: 'FR', resources: fr },
+  ]}
+>
+  <LanguageSelector />
+  {/* French now appears in the dropdown; its strings are auto-registered with i18next */}
+</XerticaProvider>
+```
+
+### Monolingual app (no selector visible)
+
+```tsx
+<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
+  <LanguageSelector />
+  {/* Renders nothing — there is nothing to switch to */}
+</XerticaProvider>
+```
+
+### Programmatic access
+
+```tsx
+import { useLanguage } from 'xertica-ui';
+
+function MyComponent() {
+  const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
+  // ...
+}
+```
+
+---
+
+## Behavior
+
+- **Reads** `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
+- **Persists** the selected language to `localStorage` under the key `xertica_language`
+- **Notifies** `i18next` via `i18n.changeLanguage()` — all components using `useTranslation()` re-render immediately
+- **Invalidates** the React Query cache so mock/API responses translated via `i18n.t()` are refetched in the new language
+- **Auto-hides** when `isMonolingual === true` (single-language apps)
+- **Labels**: known codes (`pt-BR`, `en`, `es`) use translated labels from `assistant.languageSelector.*`. Custom codes fall back to the `label` passed in the `LanguageDefinition`.
+- **Short labels**: when `variant="minimal"`, uses the `shortLabel` from the `LanguageDefinition`, or `code.slice(0, 2).toUpperCase()` as fallback
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Placement**: Typically inside `Header` actions (`showLanguageSelector` prop) or the `Sidebar` footer.
+> - **`<LanguageProvider>` is required**: `LanguageSelector` calls `useLanguage()` and throws when rendered outside a `LanguageProvider`. `<XerticaProvider>` provides it automatically.
+> - **Do NOT pass `initialLanguage` or `onLanguageChange`** — these props were removed. Use `useLanguage()` to read or change the language programmatically.
+> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Use `showWhenMonolingual` only if you explicitly need it visible.
+> - **One instance per layout shell** — multiple selectors create UX confusion. Place a single instance in `Header` or `Sidebar`.
+> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.