xertica-ui 2.5.1 → 2.5.2

package/docs/components/language-selector.md

@@ -1,176 +1,176 @@
-# LanguageSelector — Xertica UI
-
-A dropdown component for switching the interface language. It reads the current language from `LanguageContext` and calls `i18n.changeLanguage()` when the user selects a new option — all `useTranslation()` consumers in the app re-render immediately, and the React Query cache is invalidated so data-layer strings refresh too.
-
----
-
-## Import
-
-```tsx
-import { LanguageSelector } from 'xertica-ui/brand';
-// or
-import { LanguageSelector } from 'xertica-ui';
-```
-
----
-
-## Requirements
-
-`LanguageSelector` calls `useLanguage()` internally and **must** be rendered inside `<LanguageProvider>`. This is satisfied automatically when using `<XerticaProvider>`, which includes `LanguageProvider`.
-
----
-
-## Usage
-
-### Basic (no props needed)
-
-```tsx
-// Language is read from LanguageContext automatically
-<LanguageSelector />
-```
-
-### In the Header
-
-```tsx
-import { Header } from 'xertica-ui/layout';
-
-<Header
-  showLanguageSelector={true}
-  {/* ...other props */}
-/>
-```
-
-The `Header` component accepts `showLanguageSelector` and renders `<LanguageSelector />` in its actions area — no manual placement needed.
-
-### Minimal variant (short code only)
-
-```tsx
-<LanguageSelector variant="minimal" showIcon={false} />;
-{
-  /* Trigger displays "PT", "EN", "ES" (or the LanguageDefinition.shortLabel of custom locales) */
-}
-```
-
----
-
-## Props
-
-| Prop                  | Type                     | Default     | Description                                                                               |
-| --------------------- | ------------------------ | ----------- | ----------------------------------------------------------------------------------------- |
-| `variant`             | `'default' \| 'minimal'` | `'default'` | `minimal` shows the short label (`PT`, `EN`, …); `default` shows the full label           |
-| `showIcon`            | `boolean`                | `true`      | Show the Globe icon in the trigger                                                        |
-| `showLabel`           | `boolean`                | `false`     | Reserved — currently has no visual effect                                                 |
-| `className`           | `string`                 | `''`        | Additional CSS classes applied to the `SelectTrigger`                                     |
-| `showWhenMonolingual` | `boolean`                | `false`     | Render the selector even when only one language is configured (would otherwise auto-hide) |
-
-> **Removed props**: `initialLanguage` and `onLanguageChange` no longer exist. The component reads from `LanguageContext` and drives language changes through `i18n.changeLanguage()` internally.
-
----
-
-## Supported Languages
-
-By default the library ships with three languages (`DEFAULT_LANGUAGES`):
-
-| Code      | Display        | 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>` to add, remove, or restrict the set of languages exposed by the selector — no source-file edits required. See [`docs/i18n.md`](../i18n.md#configuring-available-languages) for the full API.
-
-### Adding a custom 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 appears in the dropdown; bundle auto-registered with i18next */}
-</XerticaProvider>;
-```
-
-### Monolingual app — selector auto-hides
-
-```tsx
-<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
-  <LanguageSelector />
-  {/* Renders nothing — there is nothing to switch to */}
-</XerticaProvider>
-```
-
-To force the selector to render anyway (e.g. as a future-proof placeholder):
-
-```tsx
-<LanguageSelector showWhenMonolingual />
-```
-
----
-
-## Behavior
-
-- Reads `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
-- On selection: calls `setLanguage(lang)` which:
-  1. Updates `LanguageContext` state
-  2. Writes the new code to `localStorage` (key: `xertica_language`)
-  3. Calls `i18n.changeLanguage(lang)` — all `useTranslation()` consumers re-render
-  4. Invalidates the React Query cache — mock/API responses translated via `i18n.t()` are refetched in the new language
-- **Auto-hides** when `isMonolingual === true` (single-language apps). Pass `showWhenMonolingual` to override.
-- The `aria-label` and label text are themselves translated via `useTranslation()` — they change with the active language. Custom language codes fall back to the `label` passed in their `LanguageDefinition`.
-- `variant="minimal"` uses `LanguageDefinition.shortLabel` when present, else `code.slice(0, 2).toUpperCase()`.
-
----
-
-## Placement Guidelines
-
-- **Header actions** — right side, adjacent to `ThemeToggle` and the user avatar (use `Header showLanguageSelector`)
-- **Sidebar footer** — when persistent language switching is needed outside the header
-- **Login / onboarding screens** — standalone usage before the main layout is mounted
-
----
-
-## Manual Language Control
-
-If you need to change the language programmatically (e.g., from user profile settings) without rendering `LanguageSelector`:
-
-```tsx
-import { useLanguage } from 'xertica-ui/hooks';
-
-function ProfileSettings() {
-  const { language, setLanguage, availableLanguages } = useLanguage();
-
-  // Fully data-driven — works with any number of languages
-  return (
-    <select value={language} onChange={e => setLanguage(e.target.value)}>
-      {availableLanguages.map(lang => (
-        <option key={lang.code} value={lang.code}>
-          {lang.label}
-        </option>
-      ))}
-    </select>
-  );
-}
-```
-
-> Avoid hardcoding the `<option>` list — using `availableLanguages` keeps your settings UI in sync with whatever the consumer configured on `<XerticaProvider>`.
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **`<LanguageProvider>` is required**: `LanguageSelector` uses `useLanguage()` — it will throw if rendered outside a `LanguageProvider`. `<XerticaProvider>` includes this automatically.
-> - **Do NOT pass `onLanguageChange` or `initialLanguage`** — these props no longer exist. Language state lives in `LanguageContext`; use `useLanguage()` to read or change it.
-> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Only use `showWhenMonolingual` if you explicitly need it visible.
-> - **One per layout shell**: Avoid rendering multiple `LanguageSelector` instances — they all share the same context and the UI does not need duplication.
-> - **Use `Header showLanguageSelector`** in page shells instead of placing `<LanguageSelector>` manually — it handles positioning and responsive visibility.
-> - **`i18next` must be initialized**: `import './i18n'` must appear in `main.tsx` before any component renders; otherwise `useTranslation()` inside `LanguageSelector` will return raw keys.
-> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.
-> - **In settings/profile pages**, use `availableLanguages` from `useLanguage()` to build the language picker — never hardcode the `<option>` list.
+# LanguageSelector — Xertica UI
+
+A dropdown component for switching the interface language. It reads the current language from `LanguageContext` and calls `i18n.changeLanguage()` when the user selects a new option — all `useTranslation()` consumers in the app re-render immediately, and the React Query cache is invalidated so data-layer strings refresh too.
+
+---
+
+## Import
+
+```tsx
+import { LanguageSelector } from 'xertica-ui/brand';
+// or
+import { LanguageSelector } from 'xertica-ui';
+```
+
+---
+
+## Requirements
+
+`LanguageSelector` calls `useLanguage()` internally and **must** be rendered inside `<LanguageProvider>`. This is satisfied automatically when using `<XerticaProvider>`, which includes `LanguageProvider`.
+
+---
+
+## Usage
+
+### Basic (no props needed)
+
+```tsx
+// Language is read from LanguageContext automatically
+<LanguageSelector />
+```
+
+### In the Header
+
+```tsx
+import { Header } from 'xertica-ui/layout';
+
+<Header
+  showLanguageSelector={true}
+  {/* ...other props */}
+/>
+```
+
+The `Header` component accepts `showLanguageSelector` and renders `<LanguageSelector />` in its actions area — no manual placement needed.
+
+### Minimal variant (short code only)
+
+```tsx
+<LanguageSelector variant="minimal" showIcon={false} />;
+{
+  /* Trigger displays "PT", "EN", "ES" (or the LanguageDefinition.shortLabel of custom locales) */
+}
+```
+
+---
+
+## Props
+
+| Prop                  | Type                     | Default     | Description                                                                               |
+| --------------------- | ------------------------ | ----------- | ----------------------------------------------------------------------------------------- |
+| `variant`             | `'default' \| 'minimal'` | `'default'` | `minimal` shows the short label (`PT`, `EN`, …); `default` shows the full label           |
+| `showIcon`            | `boolean`                | `true`      | Show the Globe icon in the trigger                                                        |
+| `showLabel`           | `boolean`                | `false`     | Reserved — currently has no visual effect                                                 |
+| `className`           | `string`                 | `''`        | Additional CSS classes applied to the `SelectTrigger`                                     |
+| `showWhenMonolingual` | `boolean`                | `false`     | Render the selector even when only one language is configured (would otherwise auto-hide) |
+
+> **Removed props**: `initialLanguage` and `onLanguageChange` no longer exist. The component reads from `LanguageContext` and drives language changes through `i18n.changeLanguage()` internally.
+
+---
+
+## Supported Languages
+
+By default the library ships with three languages (`DEFAULT_LANGUAGES`):
+
+| Code      | Display        | 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>` to add, remove, or restrict the set of languages exposed by the selector — no source-file edits required. See [`docs/i18n.md`](../i18n.md#configuring-available-languages) for the full API.
+
+### Adding a custom 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 appears in the dropdown; bundle auto-registered with i18next */}
+</XerticaProvider>;
+```
+
+### Monolingual app — selector auto-hides
+
+```tsx
+<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
+  <LanguageSelector />
+  {/* Renders nothing — there is nothing to switch to */}
+</XerticaProvider>
+```
+
+To force the selector to render anyway (e.g. as a future-proof placeholder):
+
+```tsx
+<LanguageSelector showWhenMonolingual />
+```
+
+---
+
+## Behavior
+
+- Reads `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
+- On selection: calls `setLanguage(lang)` which:
+  1. Updates `LanguageContext` state
+  2. Writes the new code to `localStorage` (key: `xertica_language`)
+  3. Calls `i18n.changeLanguage(lang)` — all `useTranslation()` consumers re-render
+  4. Invalidates the React Query cache — mock/API responses translated via `i18n.t()` are refetched in the new language
+- **Auto-hides** when `isMonolingual === true` (single-language apps). Pass `showWhenMonolingual` to override.
+- The `aria-label` and label text are themselves translated via `useTranslation()` — they change with the active language. Custom language codes fall back to the `label` passed in their `LanguageDefinition`.
+- `variant="minimal"` uses `LanguageDefinition.shortLabel` when present, else `code.slice(0, 2).toUpperCase()`.
+
+---
+
+## Placement Guidelines
+
+- **Header actions** — right side, adjacent to `ThemeToggle` and the user avatar (use `Header showLanguageSelector`)
+- **Sidebar footer** — when persistent language switching is needed outside the header
+- **Login / onboarding screens** — standalone usage before the main layout is mounted
+
+---
+
+## Manual Language Control
+
+If you need to change the language programmatically (e.g., from user profile settings) without rendering `LanguageSelector`:
+
+```tsx
+import { useLanguage } from 'xertica-ui/hooks';
+
+function ProfileSettings() {
+  const { language, setLanguage, availableLanguages } = useLanguage();
+
+  // Fully data-driven — works with any number of languages
+  return (
+    <select value={language} onChange={e => setLanguage(e.target.value)}>
+      {availableLanguages.map(lang => (
+        <option key={lang.code} value={lang.code}>
+          {lang.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+> Avoid hardcoding the `<option>` list — using `availableLanguages` keeps your settings UI in sync with whatever the consumer configured on `<XerticaProvider>`.
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **`<LanguageProvider>` is required**: `LanguageSelector` uses `useLanguage()` — it will throw if rendered outside a `LanguageProvider`. `<XerticaProvider>` includes this automatically.
+> - **Do NOT pass `onLanguageChange` or `initialLanguage`** — these props no longer exist. Language state lives in `LanguageContext`; use `useLanguage()` to read or change it.
+> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Only use `showWhenMonolingual` if you explicitly need it visible.
+> - **One per layout shell**: Avoid rendering multiple `LanguageSelector` instances — they all share the same context and the UI does not need duplication.
+> - **Use `Header showLanguageSelector`** in page shells instead of placing `<LanguageSelector>` manually — it handles positioning and responsive visibility.
+> - **`i18next` must be initialized**: `import './i18n'` must appear in `main.tsx` before any component renders; otherwise `useTranslation()` inside `LanguageSelector` will return raw keys.
+> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.
+> - **In settings/profile pages**, use `availableLanguages` from `useLanguage()` to build the language picker — never hardcode the `<option>` list.