@maz-ui/mcp 5.0.0-canary.ef64a02.0 → 5.0.0

package/docs/src/components/maz-slider.md

@@ -189,4 +189,10 @@ const multipleSilders = ref([25, 50, 75])
   const logSildersLabels = ['Micro', 'Small', 'Middle', 'Big']
 </script>
 
+## Accessibility
+
+Each cursor is a `slider` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext` when `labels` are set.
+
+**Keyboard**: <kbd>←</kbd> / <kbd>↓</kbd> and <kbd>→</kbd> / <kbd>↑</kbd> move by one `step`, <kbd>Page Down</kbd> / <kbd>Page Up</kbd> by ten steps, <kbd>Home</kbd> / <kbd>End</kbd> to the lowest / highest value allowed for the cursor (a cursor never passes its neighbours).
+
 <!--@include: ./../../.vitepress/generated-docs/maz-slider.doc.md-->

package/docs/src/components/maz-stepper.md

@@ -436,4 +436,8 @@ type Steps = Array<{
   const password = ref()
 </script>
 
+## Accessibility
+
+Each step header is a button exposing the current step (`aria-current="step"`) and its open state (`aria-expanded`), and controls its content (`aria-controls`), labelled by the header. The ids are unique per instance.
+
 <!--@include: ./../../.vitepress/generated-docs/maz-stepper.doc.md-->

package/docs/src/components/maz-table.md

@@ -19,6 +19,8 @@ description: MazTable is designed to be a reusable data table with advanced feat
 4. Row Selection (prop `select-value="key"`): There is a dedicated column for selection with a checkbox for each row. Users can individually or collectively select/deselect rows.
 5. Customizable Page Size: Users can choose the number of items to display per page using a dropdown list.
 6. Loading Indicator (prop `loading`): A loading indicator (MazLoadingBar) is displayed when data is being loaded.
+7. Animated rows (props `animated-rows` + `row-key`): rows slide to their new position when the order changes (FLIP animation). Respects `prefers-reduced-motion`.
+8. Virtualization (prop `virtualized`): render only the rows visible in the viewport (plus an overscan) so the table stays fast with thousands of rows.
 
 ## Available models
 
@@ -155,7 +157,7 @@ v-model:page-size="{{pageSize ?? 'undefined'}}"
   </template>
   <template #cell-name="{ row, value }">
     <div class="maz:flex maz:items-center maz:gap-2">
-      <MazAvatar :src="row.logoUrl" size="0.5rem"></MazAvatar>
+      <MazAvatar :src="row.logoUrl" size="mini"></MazAvatar>
       <span>{{value}}</span>
     </div>
   </template>
@@ -369,6 +371,140 @@ v-model:page-size="{{pageSize ?? 'undefined'}}"
 
 </ComponentDemo>
 
+## Animated rows
+
+Enable `animated-rows` to make rows slide to their new position when the order changes (FLIP animation) - perfect for live leaderboards or sortable lists. Provide a stable `row-key` (a field uniquely identifying each row) so every row keeps its identity across reorders. The animation is automatically disabled when the user prefers reduced motion.
+
+<ComponentDemo>
+  <MazBtn class="vp-raw" size="sm" @click="shuffleRows">Shuffle</MazBtn>
+  <br />
+  <br />
+  <MazTable
+    class="vp-raw"
+    size="sm"
+    animated-rows
+    row-key="id"
+    :headers="[
+      { label: '#', key: 'id', align: 'center', width: '3rem' },
+      { label: 'Name', key: 'name' },
+      { label: 'Score', key: 'score', align: 'center' },
+    ]"
+    :rows="players"
+  />
+
+  <template #code>
+
+  ```vue
+  <template>
+    <MazBtn @click="shuffleRows">
+      Shuffle
+    </MazBtn>
+    <MazTable
+      animated-rows
+      row-key="id"
+      :headers="[
+        { label: '#', key: 'id', align: 'center', width: '3rem' },
+        { label: 'Name', key: 'name' },
+        { label: 'Score', key: 'score', align: 'center' },
+      ]"
+      :rows="players"
+    />
+  </template>
+
+  <script lang="ts" setup>
+    import { MazTable } from 'maz-ui/components'
+    import { ref } from 'vue'
+
+    const players = ref([
+      { id: 1, name: 'John', score: 12 },
+      { id: 2, name: 'Jane', score: 24 },
+      { id: 3, name: 'Alice', score: 8 },
+      { id: 4, name: 'Bob', score: 31 },
+    ])
+
+    function shuffleRows() {
+      players.value = [...players.value].sort(() => Math.random() - 0.5)
+    }
+  </script>
+  ```
+
+  </template>
+
+</ComponentDemo>
+
+## Virtualization
+
+Enable `virtualized` to render only the rows inside the viewport (plus an overscan) instead of every row. This keeps the table fast and the DOM light even with tens of thousands of rows. It works in `rows` mode (data-driven), and `@tanstack/vue-virtual` is loaded on demand - pages that never virtualize a table never ship it.
+
+The example below renders **10 000 rows** but only keeps ~20 `<tr>` in the DOM at any time.
+
+<ComponentDemo>
+  <MazTable
+    class="vp-raw"
+    size="sm"
+    virtualized
+    max-height="300px"
+    :estimated-row-height="38"
+    :headers="[
+      { label: '#', key: 'id', width: '5rem' },
+      { label: 'Name', key: 'name', width: '12rem' },
+      { label: 'Email', key: 'email' },
+      { label: 'Score', key: 'score', align: 'center', width: '6rem' },
+    ]"
+    :rows="virtualizedRows"
+  />
+
+  <template #code>
+
+  ```vue
+  <template>
+    <MazTable
+      virtualized
+      max-height="400px"
+      :estimated-row-height="38"
+      :headers="[
+        { label: '#', key: 'id', width: '5rem' },
+        { label: 'Name', key: 'name', width: '12rem' },
+        { label: 'Email', key: 'email' },
+        { label: 'Score', key: 'score', align: 'center', width: '6rem' },
+      ]"
+      :rows="rows"
+    />
+  </template>
+
+  <script lang="ts" setup>
+    import { MazTable } from 'maz-ui/components'
+
+    // 10 000 rows - only the visible window is rendered to the DOM
+    const rows = Array.from({ length: 10_000 }, (_, i) => ({
+      id: i + 1,
+      name: `User ${i + 1}`,
+      email: `user${i + 1}@maz-ui.com`,
+      score: Math.round(Math.random() * 100),
+    }))
+  </script>
+  ```
+
+  </template>
+
+</ComponentDemo>
+
+### Options
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `virtualized` | `false` | Turns virtualization on. |
+| `max-height` | - | **Required.** Bounds the scroll viewport (any CSS length, e.g. `'400px'`, `'70vh'`). Scrolling is enabled automatically and the header stays sticky. |
+| `estimated-row-height` | `44` | Fixed row height (in px) used to place rows and size the spacers. Set it to your real row height; virtualized rows should be uniform (single line). |
+| `overscan` | `10` | Rows rendered outside the viewport on each side. |
+
+### Good to know
+
+* **Set a `width` (or `minWidth`) on your headers.** Virtualization forces `table-layout: fixed` so columns stay aligned across the rendered window; without widths the browser distributes them equally.
+* **Accessibility:** the table exposes `aria-rowcount` and each rendered row an `aria-rowindex`, so screen readers still announce "row X of N".
+* **Ignored** (with a dev warning) when `animated-rows` is enabled or when you provide a custom default slot - those paths render every row.
+* **Rendered client-side:** the virtualized body is empty during SSR and fills in on hydration.
+
 ## Loading
 
 Enable the loading state with the prop `loading`
@@ -516,6 +652,24 @@ Available sizes: `'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`
   const searchQuery = ref<string>()
   const pageSize = ref<number>(10)
   const page = ref<number>(1)
+
+  const players = ref([
+    { id: 1, name: 'John', score: 12 },
+    { id: 2, name: 'Jane', score: 24 },
+    { id: 3, name: 'Alice', score: 8 },
+    { id: 4, name: 'Bob', score: 31 },
+  ])
+
+  function shuffleRows() {
+    players.value = [...players.value].sort(() => Math.random() - 0.5)
+  }
+
+  const virtualizedRows = Array.from({ length: 10_000 }, (_, i) => ({
+    id: i + 1,
+    name: `User ${i + 1}`,
+    email: `user${i + 1}@maz-ui.com`,
+    score: Math.round(Math.random() * 100),
+  }))
 </script>
 
 ## Types
@@ -545,6 +699,7 @@ export interface MazTableHeadersEnriched {
   srOnly?: boolean
   width?: string
   maxWidth?: string
+  minWidth?: string
   classes?: ThHTMLAttributes['class']
   scope?: ThHTMLAttributes['scope']
   align?: ThHTMLAttributes['align']
@@ -554,6 +709,12 @@ export interface MazTableHeadersEnriched {
 }
 ```
 
+## Accessibility
+
+- The column headers have `scope="col"` by default (override it with the `scope` of the header).
+- A sortable column header exposes its state with `aria-sort` (`ascending`, `descending` or `none`), is focusable and sorted with <kbd>Enter</kbd> or <kbd>Space</kbd>.
+- The selection checkboxes are labelled from `@maz-ui/translations` (`aria.selectAll`, `aria.selectRow`).
+
 ## Props & Events emitted
 
 <!--@include: ./../../.vitepress/generated-docs/maz-table.doc.md-->

package/docs/src/components/maz-tabs.md

@@ -182,17 +182,124 @@ You can choose the name of this query parameter with the props `query-param` `@d
   ]
 
   const tabs2: MazTabsBarItem[] = ['First Tab', 'Second Tab', 'Third Tab', 'Fourth Tab', 'Fifth Tab', 'Sixth Tab', 'Seventh Tab', 'Eighth Tab', 'Ninth Tab', 'Tenth Tab']
+
+  const standaloneModel = ref('weekly')
+
+  const standaloneItems = [
+    { label: 'Daily', value: 'daily' },
+    { label: 'Weekly', value: 'weekly' },
+    { label: 'Monthly', value: 'monthly' },
+  ]
+</script>
+
+## Size and rounded size
+
+Each tab is rendered with a [`MazBtn`](./maz-btn.md), so you can control its `size` (`MazSize`) and `rounded-size` (`MazRoundedSize`, applied to the bar, the indicator and each tab).
+
+These props can be set on `MazTabsBar` directly, or on `MazTabs` which forwards them to its `MazTabsBar`. They are also globalizable through the [global defaults](./../guide/global-defaults.md) (`MazTabsBar` or `global` entry).
+
+<MazTabs size="sm" rounded-size="lg">
+  <MazTabsBar :items="tabs2" />
+</MazTabs>
+
+```vue
+<template>
+  <!-- size & rounded-size forwarded from MazTabs to MazTabsBar -->
+  <MazTabs size="sm" rounded-size="lg">
+    <MazTabsBar :items="tabs" />
+    <!-- ... -->
+  </MazTabs>
+
+  <!-- or directly on MazTabsBar -->
+  <MazTabsBar :items="tabs" size="lg" rounded-size="full" />
+</template>
+```
+
+Each item can also override the `size` and `rounded-size` (and accepts every other [`MazBtn`](./maz-btn.md) prop, except `active`, `block`, `type`, `loading` and `fab`).
+
+## Active color
+
+The active tab is highlighted by the indicator. Use the `color` prop (`MazColor`) on `MazTabsBar` (or on `MazTabs`, which forwards it) to color it. When omitted, the default neutral indicator is used.
+
+<MazTabs>
+  <MazTabsBar :items="tabs2" color="primary" />
+</MazTabs>
+
+```vue
+<template>
+  <MazTabsBar :items="tabs" color="primary" />
+</template>
+```
+
+## Standalone usage
+
+`MazTabsBar` can be used on its own, without `MazTabs`, as an independent switcher with its own `v-model`.
+
+::: tip Nested inside a `MazTabs`
+If your page is already wrapped by a `MazTabs`, a nested `MazTabsBar` would otherwise be linked to that parent (clicking a tab would change the page). Add the `standalone` prop to make it fully independent (it then ignores the parent's selection, size, rounded-size and color):
+
+```vue
+<MazTabsBar v-model="selected" :items="items" standalone />
+```
+:::
+
+The model returns the `1`-based index of the selected tab, unless the items provide a `value` (`string | number`), in which case that value is returned. The model type is inferred from the items passed: declare the items `as const` (or with literal `value`s) to get a strict union type for the model and the `@update:model-value` event.
+
+<MazTabsBar v-model="standaloneModel" :items="standaloneItems" color="secondary" rounded-size="full" />
+
+<br />
+
+<p>Selected value: <strong>{{ standaloneModel }}</strong></p>
+
+```vue
+<script lang="ts" setup>
+import { MazTabsBar, type MazTabsBarItem } from 'maz-ui/components'
+import { ref } from 'vue'
+
+const selected = ref('weekly')
+
+const items = [
+  { label: 'Daily', value: 'daily' },
+  { label: 'Weekly', value: 'weekly' },
+  { label: 'Monthly', value: 'monthly' },
+] as const satisfies readonly MazTabsBarItem[]
+</script>
+
+<template>
+  <MazTabsBar v-model="selected" :items="items" color="secondary" rounded-size="full" />
+  <!-- selected & @update:model-value === 'daily' | 'weekly' | 'monthly' -->
+</template>
+```
+
+When no `value` is set on the items, the model is a number (the `1`-based index):
+
+```vue
+<script lang="ts" setup>
+const selected = ref(1)
+const items = ['First', 'Second', 'Third']
 </script>
 
+<template>
+  <MazTabsBar v-model="selected" :items="items" />
+  <!-- selected === 1 | 2 | 3 -->
+</template>
+```
+
 ## Types
 
 ```ts
-type MazTabsBarItem
-  = | {
+type MazTabsBarItem<Value extends string | number = string | number>
+  // Inherits all MazBtn props except 'active' | 'block' | 'type' | 'loading' | 'fab'
+  = | (Omit<MazBtnProps, 'active' | 'block' | 'type' | 'loading' | 'fab'> & {
     /**
      * Label of the tab
      */
     label: string
+    /**
+     * Value returned by the model when the tab is selected (standalone usage).
+     * When omitted, the model returns the 1-based index of the tab.
+     */
+    value?: Value
     /**
      * Will disable the tab
      * @default false
@@ -208,10 +315,17 @@ type MazTabsBarItem
        */
       content: string | number | boolean
     }
-  }
+  })
   | string
 ```
 
+## Accessibility
+
+The tabs follow the [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/):
+
+- `MazTabsBar` is a `tablist` (pass an `aria-label` to name it), each item is a `tab` with `aria-selected`, linked to its `MazTabsContentItem` (`tabpanel`) through `aria-controls` / `aria-labelledby`.
+- **Keyboard**: only the selected tab is in the tab sequence, <kbd>←</kbd> / <kbd>→</kbd> select the previous / next tab (reversed in RTL), <kbd>Home</kbd> / <kbd>End</kbd> the first / last one. Disabled tabs are skipped.
+
 ## Props & Events emitted
 
 ## MazTabs

package/docs/src/components/maz-textarea.md

@@ -68,6 +68,32 @@ You can use the `top-label` attribute to display a top label above the textarea.
   </template>
 </ComponentDemo>
 
+## With assistive text
+
+You can use the `assistive-text` attribute to display a assistive text below the textarea.
+
+<ComponentDemo>
+  <MazTextarea
+    v-model="value"
+    top-label="Your message"
+    placeholder="Type your message..."
+    assistive-text="This is an assistive text"
+  />
+
+<template #code>
+
+```html
+<MazTextarea
+  v-model="value"
+  top-label="Your message"
+  placeholder="Type your message..."
+  assistive-text="This is an assistive text"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ## With label and append slots
 
 You can use the `label` and `append` slots to customize the label and the append element.
@@ -84,7 +110,7 @@ You can use the `label` and `append` slots to customize the label and the append
       </span>
     </template>
     <template #append>
-      <MazBtn icon="paper-airplane" size="sm" @click="sendMessage" />
+      <MazBtn icon="/paper-airplane.svg" size="sm" @click="sendMessage" />
     </template>
   </MazTextarea>
 
@@ -277,6 +303,64 @@ By default, the textarea automatically expands as the user types. You can disabl
   </template>
 </ComponentDemo>
 
+## Minimum rows (compact / input-like)
+
+Use the `min-rows` prop to control the initial (minimum) height of the textarea. It defaults to `3` lines. Set it to `1` to make the textarea start at the height of a regular input while keeping the autogrow behavior: it grows line by line as the user types.
+
+<ComponentDemo>
+  <MazTextarea
+    v-model="value"
+    name="comment"
+    :min-rows="1"
+    rounded-size="xl"
+    placeholder="Send your message"
+  />
+
+<template #code>
+
+```vue
+<template>
+  <MazTextarea
+    v-model="value"
+    name="comment"
+    :min-rows="1"
+    rounded-size="xl"
+    placeholder="Send your message"
+  />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Sizes
+
+The `size` prop controls the padding (height) and text size of the textarea, mirroring the `MazInput` sizes (`mini`, `xs`, `sm`, `md`, `lg`, `xl`). Combined with `:min-rows="1"`, a given size matches the height of a `MazInput` of the same size, while keeping the autogrow behavior.
+
+<ComponentDemo>
+  <div class="maz:flex maz:flex-col maz:gap-4">
+    <MazTextarea v-model="value" name="comment" size="xs" :min-rows="1" placeholder="Size xs" />
+    <MazTextarea v-model="value" name="comment" size="sm" :min-rows="1" placeholder="Size sm" />
+    <MazTextarea v-model="value" name="comment" size="md" :min-rows="1" placeholder="Size md" />
+    <MazTextarea v-model="value" name="comment" size="lg" :min-rows="1" placeholder="Size lg" />
+    <MazTextarea v-model="value" name="comment" size="xl" :min-rows="1" placeholder="Size xl" />
+  </div>
+
+<template #code>
+
+```vue
+<template>
+  <MazTextarea v-model="value" name="comment" size="xs" :min-rows="1" placeholder="Size xs" />
+  <MazTextarea v-model="value" name="comment" size="sm" :min-rows="1" placeholder="Size sm" />
+  <MazTextarea v-model="value" name="comment" size="md" :min-rows="1" placeholder="Size md" />
+  <MazTextarea v-model="value" name="comment" size="lg" :min-rows="1" placeholder="Size lg" />
+  <MazTextarea v-model="value" name="comment" size="xl" :min-rows="1" placeholder="Size xl" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
 ## Disabled
 
 <ComponentDemo>

package/docs/src/components/maz-timeline.md

@@ -9,6 +9,21 @@ description: MazTimeline is a step/progress timeline component for Vue 3 with su
 
 <!--@include: ./../../.vitepress/mixins/getting-started.md-->
 
+---
+
+Control the current step:
+
+<MazRadioButtons
+  :model-value="currentStep"
+  size="sm"
+  :options="[
+    { label: 'None', value: -1 },
+    ...steps.map((step, index) => ({ label: index, value: index })),
+    { label: 'All Completed', value: 99 },
+  ]"
+  @update:model-value="currentStep = $event"
+/>
+
 ## Basic usage
 
 <ComponentDemo>
@@ -292,6 +307,40 @@ Customize the indicator border radius with the `rounded-size` prop.
   </template>
 </ComponentDemo>
 
+## Custom Icons
+
+<ComponentDemo>
+  <MazTimeline :model-value="0" :steps="iconsSteps" direction="horizontal" size="lg" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazTimeline
+    v-model="currentStep"
+    :steps="steps"
+    size="lg"
+  />
+</template>
+
+<script lang="ts" setup>
+  import { MazCommandLine } from '@maz-ui/icons/MazCommandLine'
+  import { MazClipboardDocumentList } from '@maz-ui/icons/MazClipboardDocumentList'
+  import { MazClipboardDocumentCheck } from '@maz-ui/icons/MazClipboardDocumentCheck'
+  import { MazComputerDesktop } from '@maz-ui/icons/MazComputerDesktop'
+
+  const iconsSteps = [
+    { title: 'PO', subtitle: 'Writing PRD', icon: MazClipboardDocumentList },
+    { title: 'Dev', subtitle: 'Building Code', icon: MazCommandLine },
+    { title: 'Tech Lead', subtitle: 'Review Code', icon: MazComputerDesktop },
+    { title: 'QA', subtitle: 'Testing', icon: MazClipboardDocumentCheck },
+  ]
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
 ## Custom slots
 
 MazTimeline provides scoped slots for full customization.
@@ -378,6 +427,10 @@ MazTimeline provides scoped slots for full customization.
 
 <script lang="ts" setup>
   import { ref } from 'vue'
+  import { MazComputerDesktop } from '@maz-ui/icons/MazComputerDesktop'
+  import { MazCommandLine } from '@maz-ui/icons/MazCommandLine'
+  import { MazClipboardDocumentList } from '@maz-ui/icons/MazClipboardDocumentList'
+  import { MazClipboardDocumentCheck } from '@maz-ui/icons/MazClipboardDocumentCheck'
 
   const currentStep = ref(1)
   const clickableStep = ref(0)
@@ -410,6 +463,13 @@ MazTimeline provides scoped slots for full customization.
     { title: 'Complete', subtitle: 'All done!' },
   ]
 
+  const iconsSteps = [
+    { title: 'PO', subtitle: 'Writing PRD', icon: MazClipboardDocumentList },
+    { title: 'Dev', subtitle: 'Building Code', icon: MazCommandLine },
+    { title: 'Tech Lead', subtitle: 'Review Code', icon: MazComputerDesktop },
+    { title: 'QA', subtitle: 'Testing', icon: MazClipboardDocumentCheck },
+  ]
+
   const colors = ['primary', 'secondary', 'info', 'success', 'warning', 'destructive']
   const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
   const roundedSizes = ['full', 'lg', 'md', 'sm', 'none']