maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-card.md

@@ -0,0 +1,321 @@
+---
+title: "MazCard"
+description: "MazCard is a standalone component to display some texts and images and also add button actions"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-card"
+---
+
+# MazCard
+
+> MazCard is a standalone component to display some texts and images and also add button actions
+
+- Package: `maz-ui`
+- Import: `import MazCard from 'maz-ui/components/MazCard'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-card
+
+> 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>
+  <MazCard class="vp-raw" title="Cute Kitten">
+    <p class="text-muted">
+      Lorem Ipsum is simply dummy text of the printing and typesetting industry.
+      Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an
+      unknown printer took a galley of type and scrambled it to make a type specimen book.
+    </p>
+  </MazCard>
+</template>
+
+<script lang="ts" setup>
+  import MazCard from 'maz-ui/components/MazCard'
+</script>
+```
+
+## Advanced usage
+
+**Details: View code**
+
+```vue
+<template>
+  <MazCard
+    :gallery="{ images: ['https://placedog.net/520/520'], height: 300, zoom: true }"
+  >
+    <template #content-title>
+      <h3>
+        Cute Kitten
+      </h3>
+    </template>
+    <template #subtitle>
+      <span>
+        Cat
+      </span>
+    </template>
+    <template #content-body>
+      <p class="text-muted">
+        Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+      </p>
+    </template>
+    <template #actions>
+      <MazBtn
+        size="md"
+        fab
+        color="destructive"
+        class="me-2"
+      >
+        <MazIcon icon="/trash.svg" />
+      </MazBtn>
+      <MazBtn
+        size="md"
+        color="contrast"
+      >
+        <MazIcon icon="/user-plus.svg" />
+      </MazBtn>
+    </template>
+  </MazCard>
+</template>
+
+<script lang="ts" setup>
+  import MazCard from 'maz-ui/components/MazCard'
+</script>
+```
+
+## Orientation
+
+When you display images, you can change the orientation of the card, available options include: `column` `row` `row-reverse` `column-reverse`
+
+### Row
+
+**Details: View code**
+
+```html
+<MazCard :gallery="{ images: ['https://placedog.net/450/450'] }" orientation="row">
+  <template #content-title>
+    <h3> Cute Kitten </h3>
+  </template>
+  <template #content-body>
+    <p class="text-muted">
+      Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+    </p>
+  </template>
+</MazCard>
+```
+
+### Row Reverse
+
+**Details: View code**
+
+```html
+<MazCard
+  :gallery="{ images: ['https://placedog.net/380/380'] }"
+  orientation="row-reverse"
+>
+  <template #content-title>
+    <h3> Cute Kitten </h3>
+  </template>
+  <template #content-body>
+    <p class="text-muted">
+      Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+    </p>
+  </template>
+</MazCard>
+
+```
+
+### Column Reverse
+
+**Details: View code**
+
+```html
+<MazCard
+  :gallery="{ images: ['https://placedog.net/420/420'], height: 300 }"
+  orientation="column-reverse"
+>
+  <template #content-title>
+    <h3> Cute Kitten </h3>
+  </template>
+  <template #content-body>
+    <p class="text-muted">
+      Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+    </p>
+  </template>
+</MazCard>
+```
+
+## Collapsible
+
+Use props: `collapsible` & `v-model:collapse-open`
+
+**Details: View code**
+
+```vue
+<template>
+  <MazCard collapsible title="Lorem Ipsum is simply" block style="margin-bottom: 1rem;">
+    <p>
+      Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+    </p>
+  </MazCard>
+
+  <MazCard collapsible v-model:collapse-open="cardOpen" title="Lorem Ipsum is simply" block>
+    <p>
+      Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+    </p>
+  </MazCard>
+</template>
+
+<script setup>
+  import { ref } from 'vue'
+
+  const cardOpen = ref(true)
+</script>
+```
+
+## Linked card
+
+To access the link, simply click the card.
+
+- `href` is the link or `to` if you use router-link or nuxt-link
+- `href-target` is the behavior of the link on click
+- You can use `:scale="false"` to remove the scale animation on hover
+
+- [MazCard](./maz-card.md#linked-card)
+
+**Details: View code**
+
+```html
+<MazCard
+  :gallery="{ images: ['https://placedog.net/400/400'], height: 300 }"
+  href="/components/maz-card#linked-card"
+  href-target="_blank"
+  block
+>
+  <span>
+    Click on the card to follow the href link
+  </span>
+</MazCard>
+```
+
+## No bordered
+
+**Details: View code**
+
+```html
+<MazCard :bordered="false">
+  Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+</MazCard>
+```
+
+## Elevation
+
+**Details: View code**
+
+```html
+<MazCard elevation :bordered="false">
+  Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+</MazCard>
+```
+
+## Gallery images
+
+**Details: View code**
+
+```html
+<MazCard
+  :gallery="{
+    images: ['https://placedog.net/640/640', 'https://placedog.net/560/560', 'https://placedog.net/720/720', 'https://placedog.net/360/360'],
+    displayedCount: 3,
+    remaining: true,
+    zoom: true,
+  }"
+>
+  Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+</MazCard>
+```
+
+## Footer slot
+
+### Basic
+
+**Details: View code**
+
+```html
+<MazCard>
+  Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+
+  <template #footer>
+    <MazBtn>
+      Button
+    </MazBtn>
+  </template>
+</MazCard>
+```
+
+### Footer aligned on left
+
+Use the prop option `footer-align="start"`
+
+**Details: View code**
+
+```html
+<MazCard footer-align="start">
+  Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+
+  <template #footer>
+    <MazBtn>
+      Button
+    </MazBtn>
+  </template>
+</MazCard>
+```
+
+## Types
+
+```ts
+type MazGalleryImage =
+  | {
+      thumbnail?: string
+      src: string
+      alt?: string
+    }
+  | string
+```
+
+## MazCard API
+
+`import MazCard from 'maz-ui/components/MazCard'`
+
+### Props
+
+- `orientation` (`"row" | "column" | "column-reverse" | "row-reverse"`, default: `"column"`): Card variant: Must be `column | row | row-reverse | column-reverse`.
+- `href` (`string`): Make card a link (footer area excluded).
+- `to` (`string | et | X`): Make card a link with a router-link or nuxt-link (footer area excluded).
+- `href-target` (`string`, default: `"_self"`): Target option of link: Muse be one of `_blank | _self | _parent | _top | framename`.
+- `footer-align` (`"end" | "start"`, default: `"end"`): Footer text alignment along the inline axis: `start | end` (`end` = right in LTR, left in RTL).
+- `gallery` (`MazGalleryProps`, default: `` `{ displayedCount: 3, remaining: false, zoom: !href && !to, width: 200, height: 150 }` If `href` or `to` is set, `zoom` is set to `false` ``): Images gallery props options (see `MazGallery` component).
+- `scale` (`boolean`): scale animation on hover (only linked cards).
+- `elevation` (`boolean`): Set elevation to card (box-shadow).
+- `radius` (`boolean`): Set radius to card.
+- `bordered` (`boolean`): Set border to card (in dark mode, the card is always bordered).
+- `wrapper-class` (`ClassValue`): add classes to wrapper.
+- `padding` (`boolean`): Remove padding from content wrapper.
+- `overflow-hidden` (`boolean`): Hide overflow.
+- `collapsible` (`boolean`, default: `false`): Make card collapsible.
+- `collapse-open` (`boolean`, default: `false`, `v-model:collapse-open`): Card is open by default if `true`.
+- `title` (`string`): Title of the card in header.
+- `block` (`boolean`): The card will be displayed in full width.
+
+### Events
+
+- `@update:collapseOpen` (payload: `unknown[`): Update the collapseOpen model
+
+### Slots
+
+- `#title`: The title of the card
+- `#content-title`: The title of the card Bindings: `collapseOpen: boolean` (The collapse open state of the card).
+- `#content-subtitle`: The subtitle of the card
+- `#content-body`: The body of the card
+- `#default`: The content of the card Bindings: `collapseOpen: boolean` (The collapse open state of the card).
+- `#footer`: The footer of the card
+- `#actions`: The actions of the image gallery (only if gallery is displayed)

package/docs/components/maz-carousel.md

@@ -0,0 +1,153 @@
+---
+title: "MazCarousel"
+description: "MazCarousel is a standalone component to display and manage items in a row"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-carousel"
+---
+
+# MazCarousel
+
+> MazCarousel is a standalone component to display and manage items in a row
+
+- Package: `maz-ui`
+- Import: `import MazCarousel from 'maz-ui/components/MazCarousel'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-carousel
+
+> 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
+<script lang="ts" setup>
+import MazCarousel from 'maz-ui/components/MazCarousel'
+import MazCard from 'maz-ui/components/MazCard'
+</script>
+
+<template>
+  <MazCarousel title="Carousel title">
+    <MazCard
+      v-for="(item, i) in Array(8)"
+      :key="i"
+      :gallery="{
+        images: [
+          'https://placedog.net/250/300?random',
+        ],
+      }"
+      style="min-width: 250px;"
+    >
+      <template #title>
+        <h4 class="m-0">
+          Doggo
+        </h4>
+      </template>
+      <template #content-body>
+        <p class="text-muted" style="margin-bottom: 0;">
+          It's a beautifull doggo, no ?
+        </p>
+      </template>
+    </MazCard>
+  </MazCarousel>
+</template>
+```
+
+## Options
+
+### hide-scrollbar
+
+This options will display the component without scrollbar only when the component is not hovered, focused or active
+
+```vue
+<script lang="ts" setup>
+import MazCarousel from 'maz-ui/components/MazCarousel'
+import MazCard from 'maz-ui/components/MazCard'
+</script>
+
+<template>
+  <MazCarousel hide-scrollbar>
+    <template #title>
+      <h4 class="text-2xl font-bold">Carousel</h4>
+    </template>
+    <MazCard
+      v-for="(item, i) in Array(8)"
+      :key="i"
+      :gallery="{
+        images: [
+          'https://placedog.net/400/200?random'
+        ]
+      }"
+      style="min-width: 250px;"
+    >
+      <template #content-title>
+        <h4 class="m-0">
+          Doggo
+        </h4>
+      </template>
+      <template #content-body>
+        <p class="text-muted" style="margin-bottom: 0;">
+          It's a beautifull doggo, no ?
+        </p>
+      </template>
+    </MazCard>
+  </MazCarousel>
+</template>
+```
+
+### hide-scroll-buttons
+
+This options will display the component without scroll buttons
+
+```vue
+<script lang="ts" setup>
+import MazCarousel from 'maz-ui/components/MazCarousel'
+import MazCard from 'maz-ui/components/MazCard'
+</script>
+
+<template>
+  <MazCarousel hide-scroll-buttons title="Carousel without scroll buttons">
+    <MazCard
+      v-for="(item, i) in Array(8)"
+      :key="i"
+      :gallery="{
+        images: [
+          'https://placedog.net/300/200'
+        ]
+      }"
+      style="min-width: 250px;"
+    >
+      <template #content-title>
+        <h4 class="m-0">
+          Doggo
+        </h4>
+      </template>
+      <template #content-body>
+        <p class="text-muted" style="margin-bottom: 0;">
+          It's a beautifull doggo, no ?
+        </p>
+      </template>
+    </MazCard>
+  </MazCarousel>
+</template>
+```
+
+## MazCarousel API
+
+`import MazCarousel from 'maz-ui/components/MazCarousel'`
+
+### Props
+
+- `hide-scroll-buttons` (`boolean`, default: `false`): Hide display the scroll buttons.
+- `translations` (`{ ariaLabel?: { previousButton?: string | undefined; nextButton?: string | undefined; } | undefined; }`, default: `Translations from`): Translations of the carousel.
+- `hide-scrollbar` (`boolean`, default: `false`): Hide the scrollbar when not active.
+- `title` (`string`): The title of the carousel.
+
+### Slots
+
+- `#title`
+- `#previous-icon`
+- `#next-icon`
+- `#default`

package/docs/components/maz-chart.md

@@ -0,0 +1,206 @@
+---
+title: "MazChart"
+description: "MazChart is a standalone component which generates graphics & charts with chart.js"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-chart"
+---
+
+# MazChart
+
+> MazChart is a standalone component which generates graphics & charts with chart.js
+
+- Package: `maz-ui`
+- Import: `import MazChart from 'maz-ui/components/MazChart'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-chart
+
+## Documentation
+
+Follow the [Chart.JS](https://www.chartjs.org/docs/latest/) documentation to create your own chart.
+
+You can use all the plugins of Chart.JS. Follow the examples below.
+
+**Tip: Performance**
+
+`MazChart` lazy-loads `chart.js` on mount and registers only the controllers, elements and scales needed for the chart `type` you requested. A `<MazChart type="pie">` won't pull `BarController`, `LineElement` or any other unused module. The chart instance is also held outside Vue's reactivity (`shallowRef` + `markRaw`) - this avoids accidental deep proxying of the underlying chart and the freezes that can come with it on large datasets.
+
+When `data` or `options` change after the initial render, `chart.update()` is called with `'none'` by default so updates don't animate. Pass `update-mode="default"` (or any other Chart.js update mode) to opt back into animations.
+
+## Bar chart
+
+**Details: View code**
+
+```vue
+<script setup lang="ts">
+import dataLabels from 'chartjs-plugin-datalabels'
+
+const barChart = {
+  type: 'bar',
+  data: {
+    labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
+    datasets: [{
+      label: 'My First Dataset',
+      data: [65, 59, 80, 81, 56, 55, 40],
+      backgroundColor: [
+        'rgba(255, 99, 132, 0.2)',
+        'rgba(255, 159, 64, 0.2)',
+        'rgba(255, 205, 86, 0.2)',
+        'rgba(75, 192, 192, 0.2)',
+        'rgba(54, 162, 235, 0.2)',
+        'rgba(153, 102, 255, 0.2)',
+        'rgba(201, 203, 207, 0.2)'
+      ],
+      borderColor: [
+        'rgb(255, 99, 132)',
+        'rgb(255, 159, 64)',
+        'rgb(255, 205, 86)',
+        'rgb(75, 192, 192)',
+        'rgb(54, 162, 235)',
+        'rgb(153, 102, 255)',
+        'rgb(201, 203, 207)'
+      ],
+      borderWidth: 1
+    }]
+  },
+}
+</script>
+
+<template>
+  <MazChart
+    :type="barChart.type"
+    :data="barChart.data"
+    :options="barChart.options"
+  />
+</template>
+```
+
+## Pie chart
+
+**Details: View code**
+
+```vue
+<script setup lang="ts">
+const pieChart = {
+  type: 'doughnut',
+  data: {
+    labels: [
+      `Perfects - ${40}%`,
+      `Bons - ${35}%`,
+      `Mauvais - ${25}%`,
+    ],
+    datasets: [
+      {
+        backgroundColor: [
+          '#fcb731',
+          'rgb(28 209 161)',
+          'rgb(255, 109, 106)',
+        ],
+        data: [
+          40,
+          35,
+          25,
+        ],
+      },
+    ],
+  },
+}
+</script>
+
+<template>
+  <MazChart
+    :type="pieChart.type"
+    :data="pieChart.data"
+  />
+</template>
+```
+
+## Line chart
+
+**Details: View code**
+
+```vue
+<script setup lang="ts">
+import dataLabels from 'chartjs-plugin-datalabels'
+
+let delayed: boolean
+
+const animation = {
+  onComplete: () => {
+    delayed = true
+  },
+  delay: (context: Record<string, any>) => {
+    let delay = 0
+    if (context.type === 'data' && context.mode === 'default' && !delayed) {
+      delay = context.dataIndex * 100 + context.datasetIndex * 50
+    }
+    return delay
+  },
+}
+
+const lineChart = {
+  type: 'line',
+  // locally registered and available for this chart
+  plugins: [dataLabels],
+  data: {
+    labels: [1, 2, 3, 4, 5, 6],
+    datasets: [
+      {
+        label: 'Moyenne des bons pronos du groupe',
+        data: [10, 15, 20, 25, 30, 35],
+        fill: false,
+        borderColor: 'rgb(28 209 161)',
+        tension: 0.5,
+        backgroundColor: '#17a2b8',
+      },
+      {
+        label: 'Vos bons pronos',
+        data: [10, 15, 20, 25, 30, 35],
+        fill: false,
+        borderColor: '#333',
+        tension: 0.5,
+        backgroundColor: '#1e90ff',
+      },
+    ],
+  },
+  options: {
+    plugins: {
+      datalabels: {
+        backgroundColor: (context: Record<string, any>) => {
+          return context.dataset.backgroundColor
+        },
+        borderRadius: 4,
+        color: 'white',
+        font: {
+          weight: 'bold',
+        },
+        padding: 6,
+      },
+    },
+    animation,
+  }
+}
+</script>
+
+<template>
+  <MazChart v-bind="lineChart" />
+</template>
+```
+
+```vue
+<MazChart type="bar" :data="data" aria-label="Sales by quarter, from 120 to 340 units" />
+```
+
+```ts
+interface MazChartProps<
+  T extends ChartType = ChartType,
+  TData = DefaultDataPoint<T>,
+  TLabel = unknown,
+> {
+  type: T
+  data: ChartData<T, TData, TLabel>
+  options?: ChartOptions<T>
+  plugins?: Plugin[]
+  datasetIdKey?: string
+  updateMode?: UpdateMode
+}
+```