maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-checkbox.md

@@ -0,0 +1,138 @@
+---
+title: "MazCheckbox"
+description: "MazCheckbox is a standalone component that replaces the standard html input checkbox. Color options are available."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-checkbox"
+---
+
+# MazCheckbox
+
+> MazCheckbox is a standalone component that replaces the standard html input checkbox. Color options are available.
+
+- Package: `maz-ui`
+- Import: `import MazCheckbox from 'maz-ui/components/MazCheckbox'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-checkbox
+
+> 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=""`
+
+```vue
+<script lang="ts" setup>
+import MazCheckbox from 'maz-ui/components/MazCheckbox'
+import { ref } from 'vue'
+
+const checked = ref(false)
+</script>
+
+<template>
+  <MazCheckbox v-model="checked" :label="checked ? 'Checked' : 'Unchecked'" />
+</template>
+```
+
+## Colors
+
+`v-model=""`
+
+**Details: View code**
+
+```vue
+<script lang="ts" setup>
+import type { Color } from 'maz-ui/components'
+import MazCheckbox from 'maz-ui/components/MazCheckbox'
+import { ref } from 'vue'
+
+const chosenColors = ref([])
+
+const colors: Color[] = [
+  'primary',
+  'secondary',
+  'info',
+  'success',
+  'warning',
+  'destructive',
+  'contrast',
+  'accent',
+]
+</script>
+
+<template>
+  <MazCheckbox
+    v-for="color in colors"
+    :id="color"
+    :key="color"
+    v-model="chosenColors"
+    :color="color"
+    name="color"
+    :value="color"
+  >
+    {{ color }}
+  </MazCheckbox>
+</template>
+```
+
+## Sizing
+
+`v-model=""`
+
+**Details: View code**
+
+```vue
+<script lang="ts" setup>
+import type { MazSize } from 'maz-ui/components'
+import MazCheckbox from 'maz-ui/components/MazCheckbox'
+import { ref } from 'vue'
+
+const chosenSizes = ref([])
+
+const sizes: MazSize[] = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
+</script>
+
+<template>
+  <MazCheckbox
+    v-for="size in sizes"
+    :key="size"
+    v-model="chosenSizes"
+    name="size"
+    :value="size"
+    :size="size"
+  >
+    {{ size }}
+  </MazCheckbox>
+</template>
+```
+
+## Disabled
+
+## MazCheckbox API
+
+`import MazCheckbox from 'maz-ui/components/MazCheckbox'`
+
+### Props
+
+- `model-value` (`T`, `v-model`): The model value of the checkbox.
+- `id` (`string`): The id of the checkbox.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the checkbox.
+- `value` (`MazCheckboxValue`): The value of the checkbox when selected.
+- `name` (`string`, default: `"m-checkbox"`): The name of the checkbox.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): The size of the checkbox.
+- `label` (`string`): Text label.
+- `disabled` (`boolean`): If the checkbox is disabled.
+- `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`): Emitted when the model value change
+- `@blur` (payload: `value: FocusEvent`): Emitted when the checkbox lost focus
+- `@change` (payload: `value: T`): Emitted when the model value change
+- `@focus` (payload: `value: FocusEvent`): Emitted when the checkbox is focused
+
+### Slots
+
+- `#default` Bindings: `value: MazCheckboxValue`.

package/docs/components/maz-checklist.md

@@ -0,0 +1,251 @@
+---
+title: "MazChecklist"
+description: "MazChecklist is a standalone component that allows creating a checklist with integrated search functionality. It provides a flexible and customizable user interface for selecting multiple items from a list of options. The component supports real-time search, color customization, and displays messages when no results are found."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-checklist"
+---
+
+# MazChecklist
+
+> MazChecklist is a standalone component that allows creating a checklist with integrated search functionality. It provides a flexible and customizable user interface for selecting multiple items from a list of options. The component supports real-time search, color customization, and displays messages when no results are found.
+
+- Package: `maz-ui`
+- Import: `import MazChecklist from 'maz-ui/components/MazChecklist'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-checklist
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Tip:**
+
+This component can be translated globally using the [MazUi](../ecosystem/translations.md) plugin.
+
+## Basic usage
+
+```vue
+<template>
+  Selected languages: {{ languages || 'none' }}
+
+  <br />
+
+  <MazChecklist
+    v-model="languages"
+    v-model:query="query"
+    title="Select your languages"
+    :search="{
+      enabled: true,
+      placeholder: 'Search a language',
+      debounce: 300,
+      autoFocus: false,
+      size: 'sm'
+    }"
+    :items="languagesOptions"
+    class="h-80"
+  >
+    <template #item="{ item }">
+      <div class="flex w-full items-center justify-between gap-2">
+        <span class="capitalize">{{ item.label }}</span>
+        <MazBadge color="theme" outlined>
+          {{ item.value }}
+        </MazBadge>
+      </div>
+    </template>
+  </MazChecklist>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazChecklist from 'maz-ui/components/MazChecklist'
+  import { useDisplayNames } from 'maz-ui/composables/useDisplayNames'
+
+  const query = ref<string>()
+  const languages = ref<string[]>()
+  const languagesOptions = useDisplayNames('en-US').getAllDisplayNames({ type: 'language' }).value.map(({ code, name }) => ({
+    label: name,
+    value: code,
+  }))
+</script>
+```
+
+## Custom search function
+
+You can replace the default search function by providing a custom search function. Useful when you need to search by multiple fields, if you want to use a different search algorithm or if you want search into your database by fetching data from an API.
+
+```vue
+<template>
+  Selected employees: {{ selectedEmployees || 'none' }}
+
+  <br />
+
+  <MazChecklist
+    v-model="selectedEmployees"
+    v-model:query="employeeQuery"
+    title="Select team members"
+    :search="{
+      placeholder: 'Search by name, email, or department...',
+      debounce: 200,
+      block: true,
+    }"
+    :items="employees"
+    :search-function="customEmployeeSearch"
+    color="success"
+    elevation
+    class="max-h-96"
+  >
+    <template #item="{ item }">
+      <div class="flex w-full items-center gap-4">
+        <div class="flex h-12 w-12 flex-none items-center justify-center rounded-full bg-linear-to-br from-primary-500 to-secondary-500 text-white font-semibold text-lg">
+          {{ item.initials }}
+        </div>
+        <div class="flex flex-1 flex-col gap-1">
+          <div class="flex items-center gap-2">
+            <span class="font-semibold text-normal">{{ item.label }}</span>
+            <MazBadge :color="item.departmentColor" size="xs">
+              {{ item.department }}
+            </MazBadge>
+          </div>
+          <span class="text-muted text-sm">{{ item.email }}</span>
+        </div>
+        <div class="flex flex-none items-center gap-1">
+          <MazIcon icon="/star.svg" class="text-warning-500" size="1rem" />
+          <span class="text-sm font-medium">{{ item.rating }}</span>
+        </div>
+      </div>
+    </template>
+  </MazChecklist>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazChecklist from 'maz-ui/components/MazChecklist'
+
+  const employeeQuery = ref<string>()
+  const selectedEmployees = ref<string[]>()
+
+  const employees = [
+    {
+      label: 'Sarah Johnson',
+      value: 'sarah.johnson',
+      email: 'sarah.johnson@company.com',
+      department: 'Engineering',
+      departmentColor: 'info',
+      initials: 'SJ',
+      rating: 4.9
+    },
+    {
+      label: 'Michael Chen',
+      value: 'michael.chen',
+      email: 'michael.chen@company.com',
+      department: 'Design',
+      departmentColor: 'warning',
+      initials: 'MC',
+      rating: 4.7
+    },
+    {
+      label: 'Emma Rodriguez',
+      value: 'emma.rodriguez',
+      email: 'emma.rodriguez@company.com',
+      department: 'Marketing',
+      departmentColor: 'success',
+      initials: 'ER',
+      rating: 4.8
+    },
+    {
+      label: 'David Kim',
+      value: 'david.kim',
+      email: 'david.kim@company.com',
+      department: 'Engineering',
+      departmentColor: 'info',
+      initials: 'DK',
+      rating: 4.6
+    },
+    {
+      label: 'Lisa Thompson',
+      value: 'lisa.thompson',
+      email: 'lisa.thompson@company.com',
+      department: 'Product',
+      departmentColor: 'contrast',
+      initials: 'LT',
+      rating: 4.9
+    },
+    {
+      label: 'John Doe',
+      value: 'john.doe',
+      email: 'john.doe@company.com',
+      department: 'Marketing',
+      departmentColor: 'success',
+      initials: 'JD',
+      rating: 4.9
+    },
+    {
+      label: 'Jane Smith',
+      value: 'jane.smith',
+      email: 'jane.smith@company.com',
+      department: 'Engineering',
+      departmentColor: 'info',
+      initials: 'JS',
+      rating: 4.9
+    },
+    {
+      label: 'Jim Beam',
+      value: 'jim.beam',
+      email: 'jim.beam@company.com',
+      department: 'Sales',
+      departmentColor: 'destructive',
+      initials: 'JB',
+      rating: 4.9
+    },
+    {
+      label: 'Jill Johnson',
+      value: 'jill.johnson',
+      email: 'jill.johnson@company.com',
+      department: 'Marketing',
+      departmentColor: 'success',
+      initials: 'JJ',
+      rating: 4.9
+    },
+  ]
+
+  function customEmployeeSearch(query: string, items: typeof employees) {
+    const searchTerm = query.toLowerCase().trim()
+
+    if (!searchTerm) return items
+
+    return items.filter(employee =>
+      employee.label.toLowerCase().includes(searchTerm) ||
+      employee.email.toLowerCase().includes(searchTerm) ||
+      employee.department.toLowerCase().includes(searchTerm) ||
+      employee.value.toLowerCase().includes(searchTerm)
+    )
+  }
+</script>
+```
+
+## MazChecklist API
+
+`import MazChecklist from 'maz-ui/components/MazChecklist'`
+
+### Props
+
+- `model-value` (`T[]`, `v-model`): The model value of the checklist (selected items).
+- `query` (`string`, `v-model:query`): The query to filter the items (model).
+- `items` (`O[]`): The list of items to display.
+- `title` (`string`): The title of the checklist.
+- `elevation` (`boolean`, default: `false`): Add elevation to the card.
+- `search` (`boolean | MazInputProps<string>`, default: `{ enabled: false, debounce: 300, autoFocus: false }`): The search input options.
+- `search-options` (`(NormalizeStringOptions & { threshold?: number | undefined; })`): The options to normalize the search query (used by the default search function) By default, the threshold is 0.75.
+- `search-function` (`((query: string, items: O[]) => O[] | undefined)`): Replace the default search function to provide a custom search function.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the checklist (card, checkbox and search input).
+- `translations` (`{ noResultsFound?: string | undefined; searchInput?: { placeholder?: string | undefined; } | undefined; }`, default: `Translations from`): Translations of the checklist component.
+
+### Events
+
+- `@update:model-value` (payload: `value?: T[] | undefined`): Emitted when the model value change
+- `@update:query` (payload: `value?: string | undefined`): Emitted when the query change
+
+### Slots
+
+- `#title`: use this slot to customize the title
+- `#no-results`: use this slot to customize the no results area
+- `#no-results-text`: use this slot to customize the no results message
+- `#item`: use this slot to customize the item Bindings: `selectedValues: T[]`, `item: O`.

package/docs/components/maz-circular-progress-bar.md

@@ -0,0 +1,109 @@
+---
+title: "MazCircularProgressBar"
+description: "MazCircularProgressBar is a standalone component"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-circular-progress-bar"
+---
+
+# MazCircularProgressBar
+
+> MazCircularProgressBar is a standalone component
+
+- Package: `maz-ui`
+- Import: `import MazCircularProgressBar from 'maz-ui/components/MazCircularProgressBar'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-circular-progress-bar
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+import MazCircularProgressBar from 'maz-ui/components/MazCircularProgressBar'
+</script>
+
+<template>
+  <MazCircularProgressBar :percentage="75" suffix="%" />
+</template>
+```
+
+## Size
+
+The size of the component can be changed by passing the `size` prop. The value could be a string in px, em or rem.
+
+```vue
+<MazCircularProgressBar :percentage="75" suffix="%" size="3em" />
+
+<MazCircularProgressBar :percentage="75" suffix="%" size="100px" />
+
+<MazCircularProgressBar :percentage="75" suffix="%" size="10rem" />
+
+<MazCircularProgressBar :percentage="75" suffix="%" size="15rem" />
+```
+
+## Duration
+
+The duration of the animation can be changed by passing the `duration` prop. The value could be a number in milliseconds.
+
+```vue
+<MazCircularProgressBar :percentage="75" :duration="5000" />
+```
+
+## Color
+
+```vue
+<MazCircularProgressBar :percentage="75" :duration="5000" />
+```
+
+## Auto-color
+
+The color of the component is automatically according to the percentage. The color will be green if the percentage is egal to 100%, orange if below 100%, and red if below 50%.
+
+```vue
+<MazCircularProgressBar :percentage="0" auto-color size="9rem" />
+
+<MazCircularProgressBar :percentage="25" auto-color size="9rem" />
+
+<MazCircularProgressBar :percentage="50" auto-color size="9rem" />
+
+<MazCircularProgressBar :percentage="100" auto-color size="9rem" />
+```
+
+## Slot
+
+Replace the percentage value by a custom slot.
+
+Obviously, the "counter animation" will not work in this case.
+
+```vue
+<MazCircularProgressBar :percentage="75" :duration="5000" />
+```
+
+## MazCircularProgressBar API
+
+`import MazCircularProgressBar from 'maz-ui/components/MazCircularProgressBar'`
+
+### Props
+
+- `percentage` (`number`, required): The percentage value of the progress bar.
+- `size` (`` `${number}rem` | `${number}px` | `${number}em` | `${number}vw` | `${number}vh` | `${number}vmin` | `${number}vmax` | `${number}%` | `${number}ch` | `${number}cm` | `${number}mm` | `${number}in` | `${number}ex` | `${number}pc` | `${number... ``, default: `"10em"`): The size of the progress bar.
+- `duration` (`number`, default: `1000`): Duration of the animation in milliseconds.
+- `delay` (`number`, default: `100`): Delay before the animation starts in milliseconds.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`): The color of the progress bar.
+- `auto-color` (`boolean`, default: `false`): Auto color based on the count (destructive, warning, success).
+- `prefix` (`string`): Suffix to display next to the number.
+- `suffix` (`string`): Suffix to display next to the number.
+- `stroke-linecap` (`"square" | "butt" | "round" | "inherit"`, default: `"round"`): The stroke-linecap style.
+- `stroke-width` (`Numberish`, default: `6`): The stroke width.
+- `stroke` (`string`): The stroke color Use this prop to override the gradient color You can use a color name or a color code.
+- `success-percentage` (`number`, default: `100`): The percentage value of the success level - The progress circle will be filled with the success color when the percentage is greater than or equal to this value.
+- `warning-percentage` (`number`, default: `75`): The percentage value of the warning level - The progress circle will be filled with the warning color when the percentage is greater than or equal to this value.
+- `danger-percentage` (`number`, default: `50`): The percentage value of the danger level - The progress circle will be filled with the danger color when the percentage is greater than or equal to this value.
+- `once` (`boolean`, default: `true`): Play the animation only once.
+
+### Slots
+
+- `#default`: Default slot - Replace the percaentage value
+- `#prefix`: Prefix slot - Add a prefix next to the number (e.g: "$")
+- `#suffix`: Suffix slot - Add a suffix next to the number (e.g: "%")

package/docs/components/maz-code-highlight.md

@@ -0,0 +1,155 @@
+---
+title: "MazCodeHighlight"
+description: "MazCodeHighlight displays source code with syntax highlighting powered by shiki. It auto-detects dark/light mode, ships with a copy-to-clipboard button, a language badge, and supports lazy loading."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-code-highlight"
+---
+
+# MazCodeHighlight
+
+> MazCodeHighlight displays source code with syntax highlighting powered by shiki. It auto-detects dark/light mode, ships with a copy-to-clipboard button, a language badge, and supports lazy loading.
+
+- Package: `maz-ui`
+- Import: `import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-code-highlight
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Installation requirement
+
+Install [`shiki`](https://shiki.style) in your project to enable highlighting:
+
+```bash [pnpm]
+pnpm add shiki
+```
+
+```bash [npm]
+npm install shiki
+```
+
+```bash [yarn]
+yarn add shiki
+```
+
+If `shiki` is not installed, the component falls back to a plain `<pre><code>` block.
+
+## Basic usage
+
+```vue
+<template>
+  <MazCodeHighlight code="const greeting = 'Hello, maz-ui!'" language="ts" />
+</template>
+
+<script lang="ts" setup>
+  import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'
+</script>
+```
+
+## With slot
+
+The default slot text is used as source code when the `code` prop is not provided. This is useful for plain text blocks.
+
+```vue
+<template>
+  <MazCodeHighlight language="bash">npm install maz-ui</MazCodeHighlight>
+</template>
+
+<script lang="ts" setup>
+  import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'
+</script>
+```
+
+## Languages
+
+Pass any valid [shiki language identifier](https://shiki.style/languages) to the `language` prop. The chosen language is also displayed as a small badge in the top-right corner (the badge fades out on hover when the copy button appears).
+
+```vue
+<template>
+  <MazCodeHighlight language="vue" :code="vueExample" />
+</template>
+
+<script lang="ts" setup>
+  import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'
+
+  const vueExample = `<script lang="ts" setup>
+  import { ref } from 'vue'
+  const count = ref(0)
+<\/script>
+
+<template>
+  <button @click="count++">Count: {{ count }}</button>
+</template>`
+</script>
+```
+
+## Custom theme
+
+Override the auto-detected theme with any [shiki built-in theme](https://shiki.style/themes).
+
+```vue
+<template>
+  <MazCodeHighlight code="console.log('dracula theme')" language="js" theme="dracula" />
+</template>
+
+<script lang="ts" setup>
+  import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'
+</script>
+```
+
+## Copy to clipboard
+
+A copy button is displayed in the top-right corner on hover (or when focused via keyboard). Clicking it writes the resolved code to the clipboard and shows a check icon for ~1.5s.
+
+### Disable the copy button
+
+Set `:copyable="false"` to hide the button entirely.
+
+```vue
+<template>
+  <MazCodeHighlight code="const noCopyButton = true" language="ts" :copyable="false" />
+</template>
+```
+
+### Copy a different value than the displayed code
+
+Use `copyValue` when the displayed source differs from what should be copied - for example to strip a leading `$` prompt when rendering a shell command. This is the mechanism `MazWindowMockup` uses internally to keep the terminal prompt out of the clipboard.
+
+```vue
+<template>
+  <MazCodeHighlight
+    code="$ pnpm add maz-ui"
+    copy-value="pnpm add maz-ui"
+    language="bash"
+  />
+</template>
+```
+
+## Disable rounded corners
+
+Set `:rounded="false"` to render the highlighted block with squared corners - useful when embedding inside another container that already has its own border-radius (e.g. inside `MazWindowMockup`).
+
+```vue
+<template>
+  <MazCodeHighlight code="// squared corners" language="ts" :rounded="false" />
+</template>
+```
+
+## Custom translations
+
+The copy button's aria-label and tooltip come from the `@maz-ui/translations` package (`codeHighlight.copyToClipboard` / `codeHighlight.copiedToClipboard`). You can override either key per-instance with the `translations` prop without touching the global locale:
+
+```vue
+<template>
+  <MazCodeHighlight
+    code="const hello = 'world'"
+    language="ts"
+    :translations="{
+      copyToClipboard: 'Copier le code',
+      copiedToClipboard: 'Copié !',
+    }"
+  />
+</template>
+```
+
+For app-wide translations, set up the [maz-ui translations plugin](../ecosystem/translations.md) and the component will pick up your locale automatically.