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`.