@maz-ui/mcp 5.0.1-beta.0 → 5.1.0-beta.1

package/docs/{src/components → components}/maz-select-country.md

@@ -1,31 +1,26 @@
 ---
-title: MazSelectCountry
-description: MazSelectCountry is a versatile Vue component for selecting countries or languages with built-in internationalization support and customizable display options
+title: "MazSelectCountry"
+description: "MazSelectCountry is a versatile Vue component for selecting countries or languages with built-in internationalization support and customizable display options"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-select-country"
 ---
 
-# {{ $frontmatter.title }}
+# MazSelectCountry
 
-{{ $frontmatter.description }}
+> MazSelectCountry is a versatile Vue component for selecting countries or languages with built-in internationalization support and customizable display options
 
-<!--@include: ./../../.vitepress/mixins/translated-component.md-->
+- Package: `maz-ui`
+- Import: `import MazSelectCountry from 'maz-ui/components/MazSelectCountry'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-select-country
 
-## Basic usage
+**Tip:**
 
-The most common use case is selecting a country. The component automatically displays country names in the user's locale with their respective flags.
+This component can be translated globally using the [MazUi](../ecosystem/translations.md) plugin.
 
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazSelectCountry
-      v-model="selectedCountry"
-      :codes="['FR', 'DE', 'IT', 'ES', 'GB', 'NL', 'BE', 'AT', 'CH', 'PT']"
-      label="Select a country"
-    />
-    <div class="maz:text-sm maz:text-muted">
-      Selected: {{ selectedCountry || 'None' }}
-    </div>
-  </div>
+## Basic usage
 
-<template #code>
+The most common use case is selecting a country. The component automatically displays country names in the user's locale with their respective flags.
 
 ```vue
 <script setup>
@@ -42,27 +37,10 @@ const selectedCountry = ref('FR')
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Language selection
 
 Configure the component to display languages instead of countries by setting the appropriate `displayNamesOptions`.
 
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazSelectCountry
-      v-model="selectedLanguage"
-      label="Select a language"
-      :display-names-options="{ type: 'language' }"
-    />
-    <div class="maz:text-sm maz:text-muted">
-      Selected: {{ selectedLanguage || 'None' }}
-    </div>
-  </div>
-
-<template #code>
-
 ```vue
 <script setup>
 import { ref } from 'vue'
@@ -79,53 +57,8 @@ const selectedLanguage = ref('en')
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Sizes and colors
 
-<ComponentDemo>
-  <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4">
-    <div class="maz:space-y-4">
-      <h4 class="maz:font-semibold">Sizes</h4>
-      <MazSelectCountry
-        v-model="sizeExample1"
-        size="sm"
-        label="Small"
-      />
-      <MazSelectCountry
-        v-model="sizeExample2"
-        size="md"
-        label="Medium (default)"
-      />
-      <MazSelectCountry
-        v-model="sizeExample3"
-        size="lg"
-        label="Large"
-      />
-    </div>
-    <div class="maz:space-y-4">
-      <h4 class="maz:font-semibold">Colors</h4>
-      <MazSelectCountry
-        v-model="colorExample1"
-        color="primary"
-        label="Primary"
-      />
-      <MazSelectCountry
-        v-model="colorExample2"
-        color="secondary"
-        label="Secondary"
-      />
-      <MazSelectCountry
-        v-model="colorExample3"
-        color="accent"
-        label="Accent"
-      />
-    </div>
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <!-- Sizes -->
@@ -164,24 +97,10 @@ const selectedLanguage = ref('en')
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Preferred countries
 
 You can prioritize certain countries to appear at the top of the list using the `preferredCodes` prop.
 
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazSelectCountry
-      v-model="preferredExample"
-      label="European countries first"
-      :preferred-codes="['FR', 'DE', 'IT', 'ES', 'GB']"
-    />
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <MazSelectCountry
@@ -192,35 +111,10 @@ You can prioritize certain countries to appear at the top of the list using the
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Filtering options
 
 Control which countries are displayed using `onlyCodes` to show only specific countries, or `ignoredCodes` to exclude certain ones.
 
-<ComponentDemo>
-  <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4">
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Only European countries</h4>
-      <MazSelectCountry
-        v-model="europeExample"
-        label="European countries only"
-        :only-codes="['FR', 'DE', 'IT', 'ES', 'GB', 'NL', 'BE', 'AT', 'CH', 'PT']"
-      />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Exclude specific countries</h4>
-      <MazSelectCountry
-        v-model="excludeExample"
-        label="All except some countries"
-        :ignored-codes="['KP', 'SY', 'AF']"
-      />
-    </div>
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <!-- Only specific countries -->
@@ -239,36 +133,10 @@ Control which countries are displayed using `onlyCodes` to show only specific co
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Custom display options
 
 Configure how country/language names are displayed using the `displayNamesOptions` prop, which leverages the browser's `Intl.DisplayNames` API.
 
-<ComponentDemo>
-  <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4">
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Short country names</h4>
-      <MazSelectCountry
-        v-model="shortExample"
-        label="Short names"
-        :display-names-options="{ type: 'region', style: 'short' }"
-      />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Languages with narrow style</h4>
-      <MazSelectCountry
-        v-model="languageNarrowExample"
-        label="Language names (narrow)"
-        :display-names-options="{ type: 'language', style: 'narrow' }"
-        hide-flags
-      />
-    </div>
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <!-- Short country names -->
@@ -288,9 +156,6 @@ Configure how country/language names are displayed using the `displayNamesOption
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Flags source
 
 By default, the flags are images of the [flagcdn.com](https://flagcdn.com) CDN: each user's browser requests them from this third party. The `flag-src` prop changes where they come from, in four ways:
@@ -335,17 +200,6 @@ export default defineNuxtConfig({
 
 `loadCountryFlag` gives the square flag of a code from the 256 flags of `@maz-ui/icons`, as a `data:image/svg+xml` URL: no request to a third party (nothing to allow for flagcdn.com in your Content Security Policy, the user's IP is not sent to it), and the component works offline (hybrid apps with Capacitor or Cordova, PWAs, intranets).
 
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazSelectCountry
-      v-model="localFlagsExample"
-      label="Country (flags of maz-ui)"
-      :flag-src="loadCountryFlag"
-    />
-  </div>
-
-<template #code>
-
 ```vue
 <script lang="ts" setup>
 import { loadCountryFlag } from 'maz-ui/country-flags'
@@ -363,9 +217,6 @@ const selectedCountry = ref('FR')
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 How it stays light:
 
 - Nothing in maz-ui imports `maz-ui/country-flags`: an app that does not import it has **no flag file at all** in its build.
@@ -376,11 +227,12 @@ How it stays light:
 const flagSrc = (code: string) => import('maz-ui/country-flags').then(({ loadCountryFlag }) => loadCountryFlag(code))
 ```
 
-::: tip Content Security Policy
+**Tip: Content Security Policy**
+
 The flags are `data:` URLs: a strict CSP must allow `img-src data:` (already needed by the lazy images of maz-ui).
-:::
 
-::: tip PWA precache
+**Tip: PWA precache**
+
 Once you use `loadCountryFlag`, the 256 flag chunks are part of your build, so a service worker that precaches every `**/*.js` downloads all of them at install. Keep them (every flag available offline) or exclude them and let them load on demand. With Vite, the chunks are named after their module, `MazFlagSquareFR-[hash].js`:
 
 ```ts
@@ -389,7 +241,6 @@ VitePWA({ workbox: { globIgnores: ['**/MazFlagSquare*.js'] } })
 ```
 
 Nuxt names its chunks `_nuxt/[hash].js` only: name the flag chunks yourself to exclude them, e.g. `vite.build.rollupOptions.output.chunkFileNames: chunk => chunk.name.startsWith('MazFlagSquare') ? '_nuxt/flags/[name].[hash].js' : '_nuxt/[hash].js'`, then ignore `**/_nuxt/flags/**`.
-:::
 
 ### Your own files
 
@@ -430,18 +281,6 @@ You can also replace the flags entirely with the `selector-flag` and `country-li
 
 Hide country flags using the `hideFlags` prop for a cleaner text-only interface.
 
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazSelectCountry
-      v-model="noFlagsExample"
-      label="Countries without flags"
-      hide-flags
-      placeholder="Text-only country selection"
-    />
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <MazSelectCountry
@@ -453,35 +292,10 @@ Hide country flags using the `hideFlags` prop for a cleaner text-only interface.
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Custom locale
 
 Override the default locale to display country/language names in a specific language.
 
-<ComponentDemo>
-  <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4">
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Countries in French</h4>
-      <MazSelectCountry
-        v-model="frenchExample"
-        label="Pays (French)"
-        locale="fr-FR"
-      />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Countries in Spanish</h4>
-      <MazSelectCountry
-        v-model="spanishExample"
-        label="País (Spanish)"
-        locale="es-ES"
-      />
-    </div>
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <!-- Countries in French -->
@@ -500,47 +314,10 @@ Override the default locale to display country/language names in a specific lang
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## States and validation
 
 The component supports all the standard form states for better user experience.
 
-<ComponentDemo>
-  <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4">
-    <div class="maz:space-y-4">
-      <MazSelectCountry
-        v-model="successExample"
-        label="Success state"
-        success
-        hint="Valid country selected"
-      />
-      <MazSelectCountry
-        v-model="warningExample"
-        label="Warning state"
-        warning
-        hint="Please verify your selection"
-      />
-    </div>
-    <div class="maz:space-y-4">
-      <MazSelectCountry
-        v-model="errorExample"
-        label="Error state"
-        error
-        hint="Please select a valid country"
-      />
-      <MazSelectCountry
-        v-model="disabledExample"
-        label="Disabled state"
-        disabled
-        hint="Selection is not available"
-      />
-    </div>
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <MazSelectCountry
@@ -573,25 +350,10 @@ The component supports all the standard form states for better user experience.
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Custom options
 
 Provide your own list of options instead of using the built-in country/language codes.
 
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazSelectCountry
-      v-model="customExample"
-      label="Custom regions"
-      :options="customRegions"
-      hide-flags
-    />
-  </div>
-
-<template #code>
-
 ```vue
 <script setup>
 import { ref } from 'vue'
@@ -616,25 +378,10 @@ const customRegions = [
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Display code instead of name
 
 Show country/language codes in the input field instead of names using the `displayCode` prop.
 
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazSelectCountry
-      v-model="codeDisplayExample"
-      label="Display country codes"
-      display-code
-      placeholder="Shows codes like 'FR', 'US'..."
-    />
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <MazSelectCountry
@@ -646,31 +393,10 @@ Show country/language codes in the input field instead of names using the `displ
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Advanced configuration
 
 Combine multiple features for complex use cases, such as business applications requiring specific country lists with custom styling.
 
-<ComponentDemo>
-  <div class="maz:max-w-md">
-    <MazSelectCountry
-      v-model="advancedExample"
-      label="Business countries"
-      color="primary"
-      size="lg"
-      :preferred-codes="['US', 'GB', 'DE', 'FR', 'CA']"
-      :ignored-codes="['AQ', 'BV', 'HM']"
-      :search-threshold="2"
-      display-code
-      success
-      hint="Primary business regions prioritized"
-    />
-  </div>
-
-<template #code>
-
 ```vue
 <template>
   <MazSelectCountry
@@ -688,9 +414,6 @@ Combine multiple features for complex use cases, such as business applications r
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## How it works
 
 The `MazSelectCountry` component is built on top of `MazSelect` and leverages the powerful `useDisplayNames` composable, which uses the browser's native `Intl.DisplayNames` API for internationalization.
@@ -726,48 +449,65 @@ const allCountries = getAllDisplayNames({
 
 This ensures consistent internationalization across your application while providing maximum flexibility for different use cases.
 
-<script setup>
-import { loadCountryFlag } from 'maz-ui/country-flags'
-import { ref } from 'vue'
-
-// Basic examples
-const selectedCountry = ref('FR')
-const selectedLanguage = ref('en-US')
-
-// Size and color examples
-const sizeExample1 = ref()
-const sizeExample2 = ref()
-const sizeExample3 = ref()
-const colorExample1 = ref()
-const colorExample2 = ref()
-const colorExample3 = ref()
-
-// Other examples
-const preferredExample = ref()
-const europeExample = ref()
-const excludeExample = ref()
-const shortExample = ref()
-const languageNarrowExample = ref()
-const noFlagsExample = ref()
-const localFlagsExample = ref('FR')
-const frenchExample = ref()
-const spanishExample = ref()
-const successExample = ref()
-const warningExample = ref()
-const errorExample = ref()
-const disabledExample = ref()
-const codeDisplayExample = ref()
-const advancedExample = ref()
-
-// Custom options example
-const customExample = ref()
-const customRegions = [
-  { code: 'EUROPE', name: 'Europe' },
-  { code: 'ASIA', name: 'Asia' },
-  { code: 'AFRICA', name: 'Africa' },
-  { code: 'AMERICAS', name: 'Americas' },
-  { code: 'OCEANIA', name: 'Oceania' }
-]
-</script>
-
-<!--@include: ./../../.vitepress/generated-docs/maz-select-country.doc.md-->
+## MazSelectCountry API
+
+`import MazSelectCountry from 'maz-ui/components/MazSelectCountry'`
+
+### Props
+
+- `id` (`string`): Id of the component.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): Color of the component.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `md`): Size of the component.
+- `preferred-codes` (`Option["code"][]`): Preferred countries to display.
+- `ignored-codes` (`Option["code"][]`): Ignored countries to display.
+- `only-codes` (`Option["code"][]`): Only countries to display.
+- `list-position` (`MazPopoverPosition`, default: `'auto'`): Position of the list.
+- `hide-flags` (`boolean`): Hide flags.
+- `flag-src` (`MazCountryFlagSrc`, default: `undefined (flags from flagcdn.com)`): Source of the flags, instead of the flagcdn.com CDN: - a URL template with the code, `{code}` (lowercase) or `{CODE}` (uppercase): `/flags/{code}.svg` - a function giving the image source of a code (URL or data URL), called when the flag becomes visible, or `undefined` to display the code in a badge Use `loadCountryFlag` from `maz-ui/country-flags` for the flags of `@maz-ui/icons`, without any request to a third party. Can be set for the whole app with the `defaults.global.flagSrc` option of the MazUi plugin.
+- `search` (`boolean`, default: `true`): Display search input in options list.
+- `show-code-in-list` (`boolean`, default: `false`): Show code on list.
+- `locale` (`string`, default: `locale defined within the maz-ui plugin or browser locale or en-US`): Locale.
+- `success` (`boolean`): Success state.
+- `error` (`boolean`): Error state.
+- `warning` (`boolean`): Warning state.
+- `display-code` (`boolean`)
+- `search-threshold` (`number`, default: `0.75`): Search threshold.
+- `translations` (`Partial<{ searchPlaceholder: string; }>`, default: `MazUiTranslationsNestedSchema['selectCountry']`): Translations.
+- `hint` (`string`): Hint message displayed.
+- `options` (`Option[]`): Options.
+- `display-names-options` (`DisplayNamesOptions`, default: `{ type: "region", languageDisplay: "standard", fallback: "code", style: "long" }`): Display name type.
+- `codes-type` (`CodesType`, default: `defined by displayNamesOptions.type (if 'region', 'country' is used, otherwise 'iso')`): Codes type. Values: `'iso'`, `'bcp'`, `'country'`, `'all'` (non exhaustive).
+- `open` (`boolean`, default: `false`): Open the select.
+- `model-value` (`Option["code"]`, `v-model`): The value of the select.
+- `block` (`boolean`): The input will be displayed in full width.
+- `disabled` (`boolean`): Disable the component.
+- `required` (`boolean`): Make the input required in the form.
+- `placeholder` (`string`): The placeholder of the select.
+- `label` (`string`): The label of the select.
+- `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
+- `transition` (`string`, default: `'scale-fade'`): The transition name of the panel list options.
+- `prefer-position` (`MazPopoverPreferPosition`, default: `'bottom-start'`): The prefer position of the list.
+- `fallback-position` (`MazPopoverFallbackPosition`, default: `'top-start'`): The fallback position of the list.
+- `top-label` (`string`): Static label displayed above the input field. Unlike the floating label, this remains fixed.
+- `autocomplete` (`string`, default: `'off'`): The autocomplete attribute of the input.
+- `option-value-key` (`string`, default: `"code"`): The key of the option value.
+- `option-label-key` (`string`, default: `"name"`): The key of the option label.
+- `option-input-value-key` (`string`, default: `"name"`): The key of the option input value.
+- `item-height` (`number`): The height of the option list item.
+- `max-list-height` (`number`, default: `240`): The max height of the option list.
+- `max-list-width` (`number`, default: `250`): The max width of the option list.
+- `min-list-height` (`number`): The min height of the option list.
+- `min-list-width` (`number`, default: `200`): The min width of the option list.
+- `format-input-value` (`((value: Option["code"]) => string)`): The function to format the input value.
+
+### Events
+
+- `@update:model-value` (payload: `value?: Option["code"] | undefined`): Emitted when the model value changes
+
+### Slots
+
+- `#selector-flag`: Country selector flag Bindings: `countryCode: Option["code"]` (current selected country code - Ex: `"FR"`).
+- `#no-results`
+- `#country-list-flag`: Country list flag Bindings: `option: Option` (country data), `isSelected: boolean` (`true` if option is selected).
+- `#country-list-code` Bindings: `option: Option`, `isSelected: boolean`.
+- `#country-list-name` Bindings: `option: Option`, `isSelected: boolean`.