xertica-ui 2.2.1 → 2.3.0

package/docs/components/label.md

@@ -1,69 +1,69 @@
-# Label
-
-## Overview
-
-An accessible form field label that is always associated with a specific input via `htmlFor`. Automatically applies styling that visually communicates field relationships and disabled states. Used in every form — standalone or via `<FormLabel>` inside the `Form` system.
-
----
-
-## When to Use
-
-- Above or beside every form input (`<Input>`, `<Textarea>`, `<Select>`, `<Checkbox>`)
-- As a visual pointer for non-form groups (settings toggles with `<Switch>`)
-
-## When NOT to Use
-
-- As generic body text — use a `<p>` or `<span>` instead.
-- Do not omit labels from forms for aesthetic reasons — accessibility requires them.
-
----
-
-## Props
-
-| Prop        | Type                   | Required             | Default | Description                         |
-| ----------- | ---------------------- | -------------------- | ------- | ----------------------------------- |
-| `htmlFor`   | `string`               | **Yes** (standalone) | —       | ID of the associated input element  |
-| `size`      | `'sm' \| 'md' \| 'lg'` | No                   | `'md'`  | Size variant controlling font size. |
-| `className` | `string"               | No                   | —       | Additional CSS classes              |
-
----
-
-## Examples
-
-### Standalone Label + Input
-
-```tsx
-import { Label, Input } from 'xertica-ui/ui';
-
-<div className="grid gap-2">
-  <Label htmlFor="username">Username</Label>
-  <Input id="username" placeholder="johndoe" />
-</div>;
-```
-
-### With Switch
-
-```tsx
-import { Label, Switch } from 'xertica-ui/ui';
-
-<div className="flex items-center space-x-2">
-  <Switch id="notifications" />
-  <Label htmlFor="notifications">Enable notifications</Label>
-</div>;
-```
-
----
-
-## AI Rules
-
-- Every standalone `<Input>`, `<Textarea>`, or `<Select>` must have a `<Label htmlFor="...">`. No exceptions.
-- **Sizing** — Matches the standard scale (`sm`, `md`, `lg`). Always set the same `size` as the associated input component.
-- When using inside `<FormField>` from `react-hook-form`, use `<FormLabel>` instead — it auto-links to the field.
-- `htmlFor` must match the `id` prop on the associated input exactly.
-
----
-
-## Related Components
-
-- [`Form`](./form.md) — Uses `<FormLabel>` which wraps `<Label>` with automatic `htmlFor` linking
-- [`Input`](./input.md), [`Textarea`](./textarea.md), [`Select`](./select.md)
+# Label
+
+## Overview
+
+An accessible form field label that is always associated with a specific input via `htmlFor`. Automatically applies styling that visually communicates field relationships and disabled states. Used in every form — standalone or via `<FormLabel>` inside the `Form` system.
+
+---
+
+## When to Use
+
+- Above or beside every form input (`<Input>`, `<Textarea>`, `<Select>`, `<Checkbox>`)
+- As a visual pointer for non-form groups (settings toggles with `<Switch>`)
+
+## When NOT to Use
+
+- As generic body text — use a `<p>` or `<span>` instead.
+- Do not omit labels from forms for aesthetic reasons — accessibility requires them.
+
+---
+
+## Props
+
+| Prop        | Type                   | Required             | Default | Description                         |
+| ----------- | ---------------------- | -------------------- | ------- | ----------------------------------- |
+| `htmlFor`   | `string`               | **Yes** (standalone) | —       | ID of the associated input element  |
+| `size`      | `'sm' \| 'md' \| 'lg'` | No                   | `'md'`  | Size variant controlling font size. |
+| `className` | `string"               | No                   | —       | Additional CSS classes              |
+
+---
+
+## Examples
+
+### Standalone Label + Input
+
+```tsx
+import { Label, Input } from 'xertica-ui/ui';
+
+<div className="grid gap-2">
+  <Label htmlFor="username">Username</Label>
+  <Input id="username" placeholder="johndoe" />
+</div>;
+```
+
+### With Switch
+
+```tsx
+import { Label, Switch } from 'xertica-ui/ui';
+
+<div className="flex items-center space-x-2">
+  <Switch id="notifications" />
+  <Label htmlFor="notifications">Enable notifications</Label>
+</div>;
+```
+
+---
+
+## AI Rules
+
+- Every standalone `<Input>`, `<Textarea>`, or `<Select>` must have a `<Label htmlFor="...">`. No exceptions.
+- **Sizing** — Matches the standard scale (`sm`, `md`, `lg`). Always set the same `size` as the associated input component.
+- When using inside `<FormField>` from `react-hook-form`, use `<FormLabel>` instead — it auto-links to the field.
+- `htmlFor` must match the `id` prop on the associated input exactly.
+
+---
+
+## Related Components
+
+- [`Form`](./form.md) — Uses `<FormLabel>` which wraps `<Label>` with automatic `htmlFor` linking
+- [`Input`](./input.md), [`Textarea`](./textarea.md), [`Select`](./select.md)

package/docs/components/language-selector.md

@@ -1,172 +1,172 @@
-# 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.