@maz-ui/mcp 5.0.0 → 5.1.0-beta.0

package/docs/src/ecosystem/utils/country-code-to-unicode-flag.md

@@ -1,213 +0,0 @@
----
-title: country-code-to-unicode-flag
-description: Convert country code in unicode flag
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-::: warning
-  This feature does not work with Windows but you can use this polyfill: [https://www.npmjs.com/package/country-flag-emoji-polyfill](https://www.npmjs.com/package/country-flag-emoji-polyfill)
-
-  Use can also use [get-country-flag-url](./get-country-flag-url.md) instead.
-:::
-
-## Basic usage
-
-<span style="font-size: 2rem;">
-  {{ unicodeFlag }}
-</span>
-
-```vue
-<template>
-  <span style="font-size: 2rem;">
-    {{ unicodeFlag }}
-  </span>
-</template>
-
-<script lang="ts" setup >
-  import { countryCodeToUnicodeFlag } from '@maz-ui/utils'
-
-  const unicodeFlag = countryCodeToUnicodeFlag('FR')
-</script>
-```
-
-## Example
-
-<div class="maz:gap-2 maz:flex maz:flex-wrap maz:items-center">
-  <span class="maz:text-xs">{{ flag }}</span>
-  <span class="maz:text-sm">{{ flag }}</span>
-  <span class="maz:text-base">{{ flag }}</span>
-  <span class="maz:text-lg">{{ flag }}</span>
-  <span class="maz:text-xl">{{ flag }}</span>
-  <span class="maz:text-2xl">{{ flag }}</span>
-  <span class="maz:text-3xl">{{ flag }}</span>
-  <span class="maz:text-4xl">{{ flag }}</span>
-  <span class="maz:text-5xl">{{ flag }}</span>
-  <span class="maz:text-6xl">{{ flag }}</span>
-  <span class="maz:text-7xl">{{ flag }}</span>
-</div>
-
-<MazSelect
-  v-model="countryCode"
-  :options="countryOptions"
-  label="Select country"
-  search
-  search-placeholder="Search country"
-  @selected-option="(option) => console.log('option', option)"
->
-  <template #default="{ option, isSelected }">
-    <div
-      class="maz:flex maz:items-center maz:gap-3"
-    >
-      <span class="maz:text-lg">
-        {{ option.unicodeFlag }}
-      </span>
-      <MazBadge
-        pastel
-        size="0.7rem"
-        class="maz:w-9"
-        :class="{ 'maz:text-muted': !isSelected }"
-      >
-        {{ option.value }}
-      </MazBadge>
-      <span :class="{ 'maz:font-semibold': isSelected }">
-        {{ option.label }}
-      </span>
-    </div>
-  </template>
-</MazSelect>
-
-<script lang="ts" setup>
-  import { computed, ref, onMounted } from 'vue'
-  import { countryCodeToUnicodeFlag } from '@maz-ui/utils'
-  import { getCountries } from 'libphonenumber-js'
-
-  const unicodeFlag = countryCodeToUnicodeFlag('FR')
-
-  const countryCode = ref('FR')
-  const flag = computed(() => countryCodeToUnicodeFlag(countryCode.value))
-
-  const countryOptions = ref(getCountriesList())
-
-  onMounted(() => {
-    const listOfCountries = getCountriesList(window.navigator.language)
-    if (listOfCountries.length > 1) {
-      countryOptions.value = listOfCountries
-    }
-  })
-
-  function getCountriesList(
-    locale?: string,
-  ) {
-    const countriesList = []
-    const isoList = getCountries()
-
-    for (const iso2 of isoList) {
-      const name = new Intl.DisplayNames([locale ?? 'en-US'], { type: 'region' }).of(iso2)
-
-      if (name) {
-        countriesList.push({
-          value: iso2,
-          label: name,
-          unicodeFlag: countryCodeToUnicodeFlag(iso2)
-        })
-      }
-    }
-
-    return countriesList
-  }
-</script>
-
-::: details Show full code
-
-```vue
-
-<template>
-  <div class="maz:gap-2 maz:flex maz:flex-wrap maz:items-center">
-    <span class="maz:text-xs">{{ flag }}</span>
-    <span class="maz:text-sm">{{ flag }}</span>
-    <span class="maz:text-base">{{ flag }}</span>
-    <span class="maz:text-lg">{{ flag }}</span>
-    <span class="maz:text-xl">{{ flag }}</span>
-    <span class="maz:text-2xl">{{ flag }}</span>
-    <span class="maz:text-3xl">{{ flag }}</span>
-    <span class="maz:text-4xl">{{ flag }}</span>
-    <span class="maz:text-5xl">{{ flag }}</span>
-    <span class="maz:text-6xl">{{ flag }}</span>
-    <span class="maz:text-7xl">{{ flag }}</span>
-  </div>
-
-  <MazSelect
-    v-model="countryCode"
-    :options="countryOptions"
-    label="Select country"
-    search
-    search-placeholder="Search country"
-    @selected-option="(option) => console.log('option', option)"
-  >
-    <template #default="{ option, isSelected }">
-      <div
-        class="maz:flex maz:items-center maz:gap-3"
-      >
-        <span class="maz:text-lg">
-          {{ option.unicodeFlag }}
-        </span>
-        <MazBadge
-          pastel
-          size="0.7rem"
-          class="maz:w-9"
-          :class="{ 'maz:text-muted': !isSelected }"
-        >
-          {{ option.value }}
-        </MazBadge>
-        <span :class="{ 'maz:font-semibold': isSelected }">
-          {{ option.label }}
-        </span>
-      </div>
-    </template>
-  </MazSelect>
-</template>
-
-<script lang="ts" setup>
-  import { computed, ref, onMounted } from 'vue'
-  import { countryCodeToUnicodeFlag } from '@maz-ui/utils'
-  import { getCountries } from 'libphonenumber-js'
-
-  const countryCode = ref('FR')
-  const flag = computed(() => countryCodeToUnicodeFlag(countryCode.value))
-
-  const countryOptions = ref(getCountriesList())
-
-  onMounted(() => {
-    const listOfCountries = getCountriesList(window.navigator.language)
-    if (listOfCountries.length > 1) {
-      countryOptions.value = listOfCountries
-    }
-  })
-
-  function getCountriesList(
-    locale?: string,
-  ) {
-    const countriesList = []
-    const isoList = getCountries()
-
-    for (const iso2 of isoList) {
-      const name = new Intl.DisplayNames([locale ?? 'en-US'], { type: 'region' }).of(iso2)
-
-      if (name) {
-        countriesList.push({
-          value: iso2,
-          label: name,
-          unicodeFlag: countryCodeToUnicodeFlag(iso2)
-        })
-      }
-    }
-
-    return countriesList
-  }
-</script>
-```
-
-:::

package/docs/src/ecosystem/utils/debounce-callback.md

@@ -1,38 +0,0 @@
----
-title: debounceCallback
-description: Module-scoped one-shot debounce — schedule a callback that gets reset on each new call.
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-Unlike [`debounce`](./debounce), which builds a debounced wrapper around a function, `debounceCallback` is a procedural helper: each call schedules a callback after `delay` ms, cancelling any previous pending callback.
-
-::: warning Shared module state
-`debounceCallback` uses a single module-level timer. All consumers of this function share the same timer slot, so calling it from two unrelated places will cancel each other. Use [`debounceId`](./debounce-id) for isolated debounces.
-:::
-
-## Usage
-
-```ts
-import { debounceCallback } from '@maz-ui/utils'
-
-debounceCallback(() => {
-  console.log('runs only if no other call happens in the next 300 ms')
-}, 300)
-```
-
-## API
-
-```ts
-function debounceCallback(
-  callback: (...args: unknown[]) => unknown,
-  delay: number,
-): void
-```
-
-| Parameter  | Type       | Description                                |
-| ---------- | ---------- | ------------------------------------------ |
-| `callback` | `Function` | Function to run after the quiet window     |
-| `delay`    | `number`   | Quiet window before firing, in milliseconds |

package/docs/src/ecosystem/utils/fetch-locale-ip.md

@@ -1,33 +0,0 @@
----
-title: fetchLocaleIp
-description: Resolve the visitor's ISO country code from their IP address using the free `ipwho.is` service.
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-Useful for pre-filling locale-aware UI — phone-number country selectors, currency hints, default language — before the user has interacted with the page.
-
-## Usage
-
-```ts
-import { fetchLocaleIp } from '@maz-ui/utils'
-
-const countryCode = await fetchLocaleIp()
-// 'FR' | 'US' | …  or undefined if the request fails
-```
-
-## API
-
-```ts
-function fetchLocaleIp(): Promise<string | undefined>
-```
-
-Returns the ISO 3166-1 alpha-2 country code (e.g. `'FR'`), or `undefined` if the request fails. Errors are caught and logged via `console.error` — the call never throws.
-
-## Notes
-
-- Hits `https://ipwho.is` — a public, no-key service. Consider rate limits and privacy for production usage.
-- Returns `undefined` rather than throwing so a fallback path (default locale, manual selection) can be wired without `try/catch`.
-- For a static locale source, see [`getBrowserLocale`](./get-browser-locale).

package/docs/src/ecosystem/utils/get-browser-locale.md

@@ -1,29 +0,0 @@
----
-title: getBrowserLocale
-description: Read the user's browser language tag (e.g. `'fr-FR'`, `'en-US'`) — returns `undefined` on the server.
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-## Usage
-
-```ts
-import { getBrowserLocale } from '@maz-ui/utils'
-
-const locale = getBrowserLocale() // 'fr-FR' | 'en-US' | … | undefined
-```
-
-## API
-
-```ts
-function getBrowserLocale(): string | undefined
-```
-
-Returns `navigator.language` on the client. On the server (no `navigator`), returns `undefined`.
-
-## Notes
-
-- For IP-based country detection instead of the browser-declared locale, see [`fetchLocaleIp`](./fetch-locale-ip).
-- The returned tag follows [BCP 47](https://www.rfc-editor.org/info/bcp47).

package/docs/src/ecosystem/utils/get-country-flag-url.md

@@ -1,156 +0,0 @@
----
-title: getCountryFlagUrl
-description: Get country flag from flagcdn.com with a simple function call
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-<MazSelect
-  v-model="countryCode"
-  :options="countryOptions"
-  label="Select country"
-  search
-  search-placeholder="Search country"
-  @selected-option="(option) => console.log('option', option)"
->
-  <template #default="{ option, isSelected }">
-    <div
-      class="maz:flex maz:items-center maz:gap-3"
-    >
-      <img :src="option.flagSrc" class="maz:text-lg" :alt="`Flag of ${option.label}`" />
-      <MazBadge
-        pastel
-        size="0.7rem"
-        class="maz:w-9"
-        :class="{ 'maz:text-muted': !isSelected }"
-      >
-        {{ option.value }}
-      </MazBadge>
-      <span :class="{ 'maz:font-semibold': isSelected }">
-        {{ option.label }}
-      </span>
-    </div>
-  </template>
-</MazSelect>
-
-## Basic usage
-
-<img :src="flagSrc" alt="Flag of France" />
-
-```vue
-<template>
-  <img :src="flagSrc" alt="Flag of France" />
-</template>
-
-<script lang="ts" setup >
-  import { getCountryFlagUrl } from '@maz-ui/utils'
-
-  const flagSrc = getCountryFlagUrl('FR')
-</script>
-```
-
-## Sizing
-
-<div class="maz:gap-2 maz:flex maz:flex-wrap maz:items-center">
-  <img
-    v-for="{ src, size, countryCode } in sizedFlags"
-    :key="src"
-    :src="src"
-    :alt="`${countryCode} Flag`"
-  />
-</div>
-
-::: details Show full code
-
-```vue
-<template>
-  <img
-    v-for="{ src, size, countryCode } in sizedFlags"
-    :key="src"
-    :src="src"
-    :alt="`${countryCode} Flag`"
-  />
-</template>
-
-<script lang="ts" setup>
-  import { computed } from 'vue'
-  import { getCountryFlagUrl } from '@maz-ui/utils'
-
-  const countryCode = ref('FR')
-
-  const sizedFlags = computed(() => {
-    const sizes: Size[] = [
-      '16x12',
-      '20x15',
-      '24x18',
-      '80x60',
-      'h80',
-      'w160',
-    ]
-
-    return sizes.map(size => ({
-      src: getCountryFlagUrl(countryCode.value, size),
-      size: size,
-      countryCode: countryCode.value
-    }))
-  })
-</script>
-```
-
-:::
-
-<script lang="ts" setup>
-  import { computed, ref, onMounted } from 'vue'
-  import { getCountryFlagUrl } from '@maz-ui/utils'
-  import { getCountries } from 'libphonenumber-js'
-
-  const countryCode = ref('FR')
-  const flagSrc = computed(() => getCountryFlagUrl(countryCode.value))
-
-  const sizedFlags = computed(() => {
-    const sizes: Size[] = [
-      '16x12',
-      '20x15',
-      '24x18',
-      '80x60',
-      'h80',
-      'w160',
-    ]
-
-    return sizes.map(size => ({
-      src: getCountryFlagUrl(countryCode.value, size),
-      size: size,
-      countryCode: countryCode.value
-    }))
-  })
-
-  const countryOptions = ref(getCountriesList())
-
-  onMounted(() => {
-    const listOfCountries = getCountriesList(window.navigator.language)
-    if (listOfCountries.length > 1) {
-      countryOptions.value = listOfCountries
-    }
-  })
-
-  function getCountriesList(locale?: string) {
-    const countriesList = []
-    const isoList = getCountries()
-
-    for (const iso2 of isoList) {
-      const name = new Intl.DisplayNames([locale ?? 'en-US'], { type: 'region' }).of(iso2)
-
-      if (name) {
-        countriesList.push({
-          value: iso2,
-          label: name,
-          flagSrc: getCountryFlagUrl(iso2)
-        })
-      }
-    }
-
-    return countriesList
-  }
-</script>

package/docs/src/ecosystem/utils/is-server.md

@@ -1,31 +0,0 @@
----
-title: isServer
-description: Check whether the code is running on the server (no `window` or `document`).
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-## Usage
-
-```ts
-import { isServer } from '@maz-ui/utils'
-
-if (isServer()) {
-  return placeholder
-}
-```
-
-## API
-
-```ts
-function isServer(): boolean
-```
-
-Returns `true` when either `document` or `window` is undefined — covers Node.js, Bun, Deno, Edge runtimes and Web Workers.
-
-## Notes
-
-- The opposite is [`isClient`](./is-client).
-- Useful for guarding `window`-dependent code from SSR errors.

package/docs/src/ecosystem/utils/is-standalone-mode.md

@@ -1,43 +0,0 @@
----
-title: isStandaloneMode
-description: Check whether the app is running as an installed Progressive Web App (PWA) rather than inside a browser tab.
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-## Usage
-
-```ts
-import { isStandaloneMode } from '@maz-ui/utils'
-
-if (isStandaloneMode()) {
-  console.log('Running as installed PWA')
-}
-```
-
-## API
-
-```ts
-function isStandaloneMode(): boolean
-```
-
-Returns `true` if the page is rendered in standalone display mode, `false` otherwise (including during SSR).
-
-## Detection rules
-
-The check returns `true` when **either**:
-
-- `window.matchMedia('(display-mode: standalone)').matches` — covers Chrome, Edge, Firefox, etc.
-- `navigator.standalone` is truthy — iOS Safari's legacy property.
-
-## Examples
-
-Hide install prompts when already installed:
-
-```ts
-if (!isStandaloneMode()) {
-  showInstallBanner()
-}
-```

package/docs/src/ecosystem/utils/truthy-filter.md

@@ -1,31 +0,0 @@
----
-title: truthyFilter
-description: Type guard that filters out falsy values (`false`, `''`, `0`, `null`, `undefined`) while narrowing the TypeScript type.
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-Pass it directly to `Array.prototype.filter` to drop nullish/empty entries while telling TypeScript the result no longer contains those types.
-
-## Usage
-
-```ts
-import { truthyFilter } from '@maz-ui/utils'
-
-const items: (string | null | undefined)[] = ['a', null, 'b', undefined, '']
-const cleaned = items.filter(truthyFilter)
-// cleaned has type string[]
-// cleaned = ['a', 'b']
-```
-
-## API
-
-```ts
-type Truthy<T> = T extends false | '' | 0 | null | undefined ? never : T
-
-function truthyFilter<T>(value: T): value is Truthy<T>
-```
-
-The function returns `Boolean(value)` — its real value is in the type predicate, which narrows away the falsy variants for downstream type-checking.

package/docs/src/ecosystem/utils/types/deep-required.md

@@ -1,39 +0,0 @@
----
-title: DeepRequired
-description: Recursive variant of TypeScript's `Required<T>` — strips `?` from every property at every depth.
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-The mirror image of [`DeepPartial`](./deep-partial). Useful when you want a fully-resolved internal type derived from a public options interface.
-
-## Usage
-
-```ts
-import type { DeepRequired } from '@maz-ui/utils'
-
-interface Options {
-  cache?: {
-    ttl?: number
-    strategy?: 'memory' | 'disk'
-  }
-}
-
-type ResolvedOptions = DeepRequired<Options>
-// {
-//   cache: {
-//     ttl: number
-//     strategy: 'memory' | 'disk'
-//   }
-// }
-```
-
-## API
-
-```ts
-type DeepRequired<T> = Required<{
-  [K in keyof T]: T[K] extends Required<T[K]> ? T[K] : DeepRequired<T[K]>
-}>
-```

package/docs/src/ecosystem/utils/types/flatten-object-keys.md

@@ -1,44 +0,0 @@
----
-title: FlattenObjectKeys
-description: Build a union of dot-separated leaf paths for a nested object, with an optional prefix.
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-Similar to [`DeepKeyOf`](./deep-key-of) but only yields **leaf** paths (skips intermediate object keys), and accepts a `Prefix` parameter for namespacing.
-
-## Usage
-
-```ts
-import type { FlattenObjectKeys } from '@maz-ui/utils'
-
-interface Config {
-  app: {
-    name: string
-    version: number
-  }
-  debug: boolean
-}
-
-type Leaves = FlattenObjectKeys<Config>
-// → 'app.name' | 'app.version' | 'debug'
-
-type Namespaced = FlattenObjectKeys<Config, 'config.'>
-// → 'config.app.name' | 'config.app.version' | 'config.debug'
-```
-
-## API
-
-```ts
-type FlattenObjectKeys<T extends Record<string, any>, Prefix extends string = ''> = {
-  [K in keyof T]: T[K] extends Record<string, any>
-    ? FlattenObjectKeys<T[K], `${Prefix}${K extends string ? K : ''}.`>
-    : `${Prefix}${K extends string ? K : ''}`
-}[keyof T]
-```
-
-## Notes
-
-- Unlike `DeepKeyOf`, intermediate object keys (e.g. `'app'` in the example) are not included — only the paths that resolve to non-object leaves.

package/docs/src/ecosystem/utils/upper-first.md

@@ -1,32 +0,0 @@
----
-title: upperFirst
-description: Uppercase the first character of a string and leave the rest unchanged.
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-## Usage
-
-```ts
-import { upperFirst } from '@maz-ui/utils'
-
-upperFirst('hello') // → 'Hello'
-upperFirst('hELLO') // → 'HELLO'
-upperFirst('') // → ''
-```
-
-## API
-
-```ts
-function upperFirst(value: string): string
-```
-
-| Parameter | Type     | Description           |
-| --------- | -------- | --------------------- |
-| `value`   | `string` | The string to process |
-
-## Notes
-
-- Does **not** lowercase the remaining characters — use [`capitalize`](./capitalize) for the same behaviour when you control the input shape.