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

package/docs/{src/components → components}/maz-pull-to-refresh.md

@@ -1,13 +1,20 @@
 ---
-title: MazPullToRefresh
-description: MazPullToRefresh adds a native-feeling pull to refresh gesture to your app or to any scroll container, with a progress ring, haptic feedback and translated, accessible feedback.
+title: "MazPullToRefresh"
+description: "MazPullToRefresh adds a native-feeling pull to refresh gesture to your app or to any scroll container, with a progress ring, haptic feedback and translated, accessible feedback."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-pull-to-refresh"
 ---
 
-# {{ $frontmatter.title }}
+# MazPullToRefresh
 
-{{ $frontmatter.description }}
+> MazPullToRefresh adds a native-feeling pull to refresh gesture to your app or to any scroll container, with a progress ring, haptic feedback and translated, accessible feedback.
 
-<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+- Package: `maz-ui`
+- Import: `import MazPullToRefresh from 'maz-ui/components/MazPullToRefresh'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-pull-to-refresh
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
 
 ## Key Features
 
@@ -16,45 +23,13 @@ description: MazPullToRefresh adds a native-feeling pull to refresh gesture to y
 - Rubber band resistance beyond the trigger distance, and a progress ring that fills while pulling
 - Ignores horizontal swipes and multi-touch gestures, and prevents the native bounce (and the browser's own pull to refresh) while pulling
 - Haptic feedback when the trigger distance is reached (devices supporting `navigator.vibrate`)
-- Texts from [@maz-ui/translations](./../ecosystem/translations.md), overridable with the `translations` prop or the slots
+- Texts from [@maz-ui/translations](../ecosystem/translations.md), overridable with the `translations` prop or the slots
 - Accessible: the refresh is announced to screen readers, `aria-busy` is set while refreshing, and `refresh()` is exposed for a button usable with a keyboard or a mouse
 - Optional `standalone-mode` to enable it only in an installed PWA (browsers already have their own pull to refresh)
-- Built on the headless [usePullToRefresh](./../composables/use-pull-to-refresh.md) composable
+- Built on the headless [usePullToRefresh](../composables/use-pull-to-refresh.md) composable
 
 ## Demo
 
-<div class="maz:flex maz:flex-col maz:items-center maz:gap-3 vp-raw">
-  <p class="maz:text-sm maz:text-muted">
-    Pull down inside the box on a touch device (or with the touch emulation of your browser's device toolbar).
-  </p>
-  <div class="maz:h-80 maz:w-full maz:max-w-sm maz:overflow-y-auto maz:rounded-lg maz:border maz:border-divider maz:bg-container">
-    <MazPullToRefresh ref="demo" :on-refresh="refreshDemo">
-      <ul class="maz:m-0 maz:list-none maz:p-0">
-        <li v-for="item in items" :key="item" class="maz:border-b maz:border-divider maz:px-4 maz:py-3">
-          {{ item }}
-        </li>
-      </ul>
-    </MazPullToRefresh>
-  </div>
-  <MazBtn size="sm" :loading="demo?.isRefreshing" @click="demo?.refresh()">
-    Refresh ({{ refreshCount }})
-  </MazBtn>
-</div>
-
-<script lang="ts" setup>
-import { ref, useTemplateRef } from 'vue'
-
-const demo = useTemplateRef('demo')
-const refreshCount = ref(0)
-const items = ref(Array.from({ length: 20 }, (_, index) => `Item ${index + 1}`))
-
-async function refreshDemo() {
-  await new Promise(resolve => setTimeout(resolve, 1000))
-  refreshCount.value++
-  items.value = [`New item ${refreshCount.value}`, ...items.value]
-}
-</script>
-
 ## Basic usage
 
 Wrap your app (or a page) inside the component and give it the function that reloads your data. The spinner stays visible until the returned promise settles.
@@ -91,9 +66,9 @@ The pull can only start when its scroll container is at the top. By default, the
 
 ```vue
 <template>
-  <div class="app-shell maz:fixed maz:inset-0 maz:flex maz:flex-col">
+  <div class="app-shell fixed inset-0 flex flex-col">
     <header>…</header>
-    <main class="maz:flex-1 maz:overflow-y-auto">
+    <main class="flex-1 overflow-y-auto">
       <MazPullToRefresh :on-refresh="refresh">
         <slot />
       </MazPullToRefresh>
@@ -140,7 +115,7 @@ The three states have their own slot. Each one receives the pull `progress` (0 t
 
 ```vue
 <template>
-  <MazPullToRefresh :on-refresh="refresh" header-class="maz:bg-surface-600">
+  <MazPullToRefresh :on-refresh="refresh" header-class="bg-surface-600">
     <template #pull-before="{ progress }">
       <span>{{ Math.round(progress * 100) }}%</span>
     </template>
@@ -160,7 +135,7 @@ The three states have their own slot. Each one receives the pull `progress` (0 t
 
 ## Translations
 
-Texts come from [@maz-ui/translations](./../ecosystem/translations.md) (`pullToRefresh.pull`, `pullToRefresh.release`, `pullToRefresh.refreshing`). Override them per instance with the `translations` prop:
+Texts come from [@maz-ui/translations](../ecosystem/translations.md) (`pullToRefresh.pull`, `pullToRefresh.release`, `pullToRefresh.refreshing`). Override them per instance with the `translations` prop:
 
 ```vue
 <template>
@@ -203,6 +178,45 @@ The events follow the life of a refresh: `start`, then `loaded` and `response` (
 
 ## Headless usage
 
-Need a different indicator, or a gesture on an element without wrapping it? Use the [usePullToRefresh](./../composables/use-pull-to-refresh.md) composable.
+Need a different indicator, or a gesture on an element without wrapping it? Use the [usePullToRefresh](../composables/use-pull-to-refresh.md) composable.
+
+## MazPullToRefresh API
+
+`import MazPullToRefresh from 'maz-ui/components/MazPullToRefresh'`
+
+### Props
+
+- `on-refresh` (`(() => unknown)`): Function called when the user releases after pulling far enough. The spinner stays visible until the returned promise settles. Without it, the component does nothing.
+- `distance` (`number`, default: `80`): Pull distance (in px, after resistance) required to trigger a refresh.
+- `max-distance` (`number`, default: `distance * 1.6`): Maximum pull distance (in px), reached with a rubber band effect beyond `distance`.
+- `resistance` (`number`, default: `0.5`): Ratio between the finger movement and the pull distance, between 0 and 1. Lower is stiffer.
+- `min-duration` (`number`, default: `400`): Minimum duration (in ms) of the refreshing state, so the feedback stays visible on fast refreshes.
+- `container-selector` (`string`): CSS selector of the scroll container. By default, the closest scrollable ancestor of the component, or the window. The pull only starts when this container is scrolled to the top.
+- `header-class` (`ClassValue`): Class of the header that holds the indicator.
+- `spinner-color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): Color of the progress ring and the spinner.
+- `disabled` (`boolean`, default: `false`): Disable the pull to refresh.
+- `standalone-mode` (`boolean`, default: `false`): Only enable the pull to refresh when the app runs as an installed PWA (standalone display mode), browsers already provide their own pull to refresh.
+- `haptic` (`boolean`, default: `true`): Vibrate briefly when the pull reaches `distance` (devices supporting `navigator.vibrate`).
+- `translations` (`{ pull?: string | undefined; release?: string | undefined; refreshing?: string | undefined; }`, default: `Translations from`): Translations of the pull to refresh.
+- `offset` (`number`)
+
+### Events
+
+- `@loaded`: Emitted when `onRefresh` resolved
+- `@error` (payload: `error: unknown`): Emitted when `onRefresh` threw or rejected
+- `@start`: Emitted when the refresh starts
+- `@response` (payload: `response: unknown`): Emitted with the value resolved by `onRefresh`
+- `@finish`: Emitted when the refresh ends, after `loaded` or `error`
+
+### Slots
+
+- `#pull-before`: Content shown while pulling, before the threshold Bindings: `progress: number`, `distance: number`.
+- `#pull-ready`: Content shown once releasing triggers a refresh Bindings: `progress: number`, `distance: number`.
+- `#pull-loading`: Content shown while refreshing Bindings: `progress: number`, `distance: number`.
+- `#default`: Content of the page
+
+### Exposed (template ref)
 
-<!--@include: ./../../.vitepress/generated-docs/maz-pull-to-refresh.doc.md-->
+- `refresh`: Run the refresh programmatically (a "refresh" button for keyboard and mouse users)
+- `isRefreshing`: `onRefresh` is running
+- `progress`: Pull progress towards `distance`, from 0 to 1

package/docs/components/maz-radio-buttons.md

@@ -0,0 +1,313 @@
+---
+title: "MazRadioButtons"
+description: "MazRadioButtons is a standalone component to select a value in a list. Made with native HTMLInputElement type radio"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-radio-buttons"
+---
+
+# MazRadioButtons
+
+> MazRadioButtons is a standalone component to select a value in a list. Made with native HTMLInputElement type radio
+
+- Package: `maz-ui`
+- Import: `import MazRadioButtons from 'maz-ui/components/MazRadioButtons'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-radio-buttons
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+```vue
+<template>
+  <MazRadioButtons
+    v-model="selectedCompetition"
+    :options="competitions"
+  />
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+
+  import MazRadioButtons from 'maz-ui/components/MazRadioButtons'
+
+  const selectedCompetition = ref<string>()
+
+  const competitions = [
+    {
+      value: "1",
+      label: "Ligue 1",
+      areaName: "France",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/c/c3/Flag_of_France.svg",
+    },
+    {
+      value: "2",
+      label: "Premier League",
+      areaName: "England",
+      areaEnsignUrl: "https://crests.football-data.org/770.svg",
+    },
+    {
+      value: "3",
+      label: "Bundesliga",
+      areaName: "Germany",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/b/ba/Flag_of_Germany.svg",
+    },
+    {
+      value: "4",
+      label: "Eredivisie",
+      areaName: "Netherlands",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/2/20/Flag_of_the_Netherlands.svg",
+    },
+    {
+      value: "5",
+      label: "Serie A",
+      areaName: "Italy",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/0/03/Flag_of_Italy.svg",
+    },
+    {
+      value: "6",
+      label: "Primera Division",
+      areaName: "Spain",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/9/9a/Flag_of_Spain.svg",
+    },
+    {
+      value: "7",
+      label: "Primeira Liga",
+      areaName: "Portugal",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/5/5c/Flag_of_Portugal.svg",
+    },
+    {
+      value: "8",
+      label: "UEFA Champions League",
+      areaName: "Europe",
+      areaEnsignUrl: "https://crests.football-data.org/EUR.svg",
+    }
+  ]
+</script>
+```
+
+## Custom slot template
+
+```html
+<MazRadioButtons
+  v-model="selectedCompetition"
+  :options="competitions"
+  color="secondary"
+>
+  <template #default="{ option, selected }">
+    <div style="display: flex;">
+      <MazAvatar
+        v-if="option.areaEnsignUrl"
+        :src="option.areaEnsignUrl"
+        style="margin-right: 16px;"
+        size="0.8rem"
+      />
+      <div style="display: flex; flex-direction: column;">
+        <span>
+          {{ option.label }}
+        </span>
+        <span :class="{ 'text-muted': !selected }">
+          {{ option.areaName }}
+        </span>
+      </div>
+    </div>
+  </template>
+</MazRadioButtons>
+```
+
+## Orientation - Column
+
+```vue
+<template>
+  <MazRadioButtons
+    v-model="selectedCompetition"
+    :options="competitions"
+    orientation="col | row"
+    v-slot="{ option, selected }"
+  >
+    <div style="display: flex;">
+      <MazAvatar
+        v-if="option.areaEnsignUrl"
+        :src="option.areaEnsignUrl"
+        style="margin-right: 16px;"
+        size="0.8rem"
+      />
+      <div style="display: flex; flex-direction: column;">
+        <span>
+          {{ option.label }}
+        </span>
+        <span :class="{ 'text-muted': !selected }">
+          {{ option.areaName }}
+        </span>
+      </div>
+    </div>
+  </MazRadioButtons>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+
+  import { MazRadioButtons, MazAvatar } from 'maz-ui/components'
+
+  const selectedCompetition = ref<string>()
+
+  const competitions = [
+    {
+      value: "1",
+      label: "Ligue 1",
+      areaName: "France",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/c/c3/Flag_of_France.svg",
+    },
+    {
+      value: "2",
+      label: "Premier League",
+      areaName: "England",
+      areaEnsignUrl: "https://crests.football-data.org/770.svg",
+    },
+    {
+      value: "3",
+      label: "Bundesliga",
+      areaName: "Germany",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/b/ba/Flag_of_Germany.svg",
+    },
+    {
+      value: "4",
+      label: "Eredivisie",
+      areaName: "Netherlands",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/2/20/Flag_of_the_Netherlands.svg",
+    },
+    {
+      value: "5",
+      label: "Serie A",
+      areaName: "Italy",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/0/03/Flag_of_Italy.svg",
+    },
+    {
+      value: "6",
+      label: "Primera Division",
+      areaName: "Spain",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/9/9a/Flag_of_Spain.svg",
+    },
+    {
+      value: "7",
+      label: "Primeira Liga",
+      areaName: "Portugal",
+      areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/5/5c/Flag_of_Portugal.svg",
+    },
+    {
+      value: "8",
+      label: "UEFA Champions League",
+      areaName: "Europe",
+      areaEnsignUrl: "https://crests.football-data.org/EUR.svg",
+    }
+  ]
+</script>
+```
+
+## Selector icon with options equal-size
+
+This option will display a select icon on the left of the label
+
+```vue
+<template>
+  <MazRadioButtons
+    v-slot="{ option, selected }"
+    v-model="selectedMode"
+    :options="modeOptions"
+    selector
+    equal-size
+    block
+  >
+    <div class="flex flex-col items-start p-2">
+      <h3 class="mb-2 text-xl font-semibold">
+        {{ option.label }}
+      </h3>
+      <span :class="{ 'text-muted': !selected }">
+        {{ option.description }}
+      </span>
+    </div>
+  </MazRadioButtons>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import { type MazRadioButtonsOption } from 'maz-ui/components/MazRadioButtons'
+
+  const selectedMode = ref('scores')
+
+  const modeOptions: MazRadioButtonsOption[] = [
+    {
+      label: 'Scores',
+      value: 'scores',
+      description:
+        'Predict the score of matches. If you find the outcome of the match you win 5 points, if you get the perfect score you double your score!',
+      style: 'min-width: 250px;'
+    },
+    {
+      label: 'Cotes',
+      value: 'odds',
+      description:
+        'Predict with match odds. If you find the correct winner of the match you earn the points associated with the rating, if you have the perfect score you double your score.',
+      style: 'min-width: 250px;'
+    },
+  ]
+</script>
+```
+
+## Types
+
+### options
+
+The options prop is an array of `ButtonsRadioOption` type
+
+```ts
+export type ButtonsRadioOption = {
+  /** The label of the option */
+  label: string
+  /** The value of the option */
+  value: string | number | boolean
+  /** The classes to apply to the option */
+  classes?: any
+  /** The style to apply to the option */
+  style?: StyleValue
+} & Record<string, unknown>
+```
+
+## Accessibility
+
+The root element is a `radiogroup` of native radio inputs: pass an `aria-label` (or `aria-labelledby`) to name it. The `hint` describes the group (`aria-describedby`) and `error` sets `aria-invalid`. The arrows move between the options natively.
+
+When no `name` is provided, each instance gets a unique one, so two groups of the same page never share their radios.
+
+## MazRadioButtons API
+
+`import MazRadioButtons from 'maz-ui/components/MazRadioButtons'`
+
+### Props
+
+- `model-value` (`T`, `v-model`): The value of the selected option.
+- `options` (`Option[]`, required): The options to display.
+- `name` (`string`, default: `a unique name per instance`): The name of the radio group.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent" | "surface"`, default: `"primary"`): The color of the selected radio buttons.
+- `elevation` (`boolean`, default: `false`): Add elevation to the radio buttons.
+- `orientation` (`"row" | "col"`, default: `"row"`): The orientation of the radio buttons.
+- `wrap` (`boolean`, default: `true`): Disable the wrap of the radio buttons.
+- `equal-size` (`boolean`, default: `false`): Make all radio buttons the same size.
+- `selector` (`boolean`, default: `false`): Display a selector icon.
+- `block` (`boolean`, default: `false`): The component will be displayed in full width.
+- `error` (`boolean`): Whether there is an error with the input.
+- `success` (`boolean`): Whether the input is successful.
+- `warning` (`boolean`): Whether there is a warning with the input.
+- `hint` (`string`): The hint text to display below the input.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of the radio buttons.
+
+### Events
+
+- `@update:model-value` (payload: `value: Option["value"]`): Emitted when the selected option change
+- `@blur` (payload: `value: FocusEvent`): Emitted when the a radio button lost focus
+- `@change` (payload: `value: Option["value"]`): Emitted when the selected option change
+- `@focus` (payload: `value: FocusEvent`): Emitted when the a radio button is focused
+
+### Slots
+
+- `#default`: Label of the radio Bindings: `option: Option` (The value of the option), `selected: boolean` (If the option is selected).

package/docs/components/maz-radio.md

@@ -0,0 +1,119 @@
+---
+title: "MazRadio"
+description: "MazRadio is a radio input with a label, colors and sizes to pick one value among several options; see MazRadioButtons for a ready-made group"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-radio"
+---
+
+# MazRadio
+
+> MazRadio is a radio input with a label, colors and sizes to pick one value among several options; see MazRadioButtons for a ready-made group
+
+- Package: `maz-ui`
+- Import: `import MazRadio from 'maz-ui/components/MazRadio'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-radio
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+`v-model=""`
+
+**Details: View code**
+
+```vue
+<script lang="ts" setup>
+import MazRadio from 'maz-ui/components/MazRadio'
+import { ref } from 'vue'
+
+const chosenColor = ref('primary')
+const chosenSize = ref('mini')
+
+const colors: Color[] = [
+  'primary',
+  'secondary',
+  'info',
+  'success',
+  'warning',
+  'destructive',
+  'accent',
+  'contrast',
+]
+</script>
+
+<template>
+  <MazRadio
+    v-for="color in colors"
+    :key="color"
+    v-model="chosenColor"
+    name="chosenColor"
+    :color="color"
+    :value="color"
+  >
+    {{ color }}
+  </MazRadio>
+</template>
+```
+
+## Sizing
+
+`v-model=""`
+
+**Details: View code**
+
+```vue
+<script lang="ts" setup>
+import MazRadio from 'maz-ui/components/MazRadio'
+import type { Size } from 'maz-ui/components'
+import { ref } from 'vue'
+
+const chosenSize = ref('mini')
+
+const sizes: Size[] = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
+</script>
+
+<template>
+  <MazRadio
+    v-for="size in sizes"
+    :key="size"
+    v-model="chosenSize"
+    name="chosenSize"
+    :size="size"
+    :value="size"
+    :label="size"
+  />
+</template>
+```
+
+## Disabled
+
+## MazRadio API
+
+`import MazRadio from 'maz-ui/components/MazRadio'`
+
+### Props
+
+- `id` (`string`): The id of the radio.
+- `model-value` (`T`, `v-model`): The value of the radio.
+- `value` (`T`, required): The value of the radio.
+- `name` (`string`, required): The name of the radio.
+- `label` (`string`): The label of the radio.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the radio.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): The size of the radio.
+- `disabled` (`boolean`, default: `false`): The disabled state of the radio.
+- `error` (`boolean`): Whether there is an error with the input.
+- `success` (`boolean`): Whether the input is successful.
+- `warning` (`boolean`): Whether there is a warning with the input.
+- `hint` (`string`): The hint text to display below the input.
+
+### Events
+
+- `@update:model-value` (payload: `value: T`): Event emitted when value change
+- `@blur` (payload: `value: FocusEvent`): Emitted when the radio lost focus
+- `@change` (payload: `value: T`): Event emitted when value change
+- `@focus` (payload: `value: FocusEvent`): Emitted when the radio is focused
+
+### Slots
+
+- `#default` Bindings: `isSelected: boolean`, `value: T`.