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

package/docs/components/maz-table.md

@@ -0,0 +1,426 @@
+---
+title: "MazTable"
+description: "MazTable is designed to be a reusable data table with advanced features. Pagination, Search, Column Sorting, Row Selection, UI options, Loading and Slots."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-table"
+---
+
+# MazTable
+
+> MazTable is designed to be a reusable data table with advanced features. Pagination, Search, Column Sorting, Row Selection, UI options, Loading and Slots.
+
+- Package: `maz-ui`
+- Import: `import MazTable from 'maz-ui/components/MazTable'` or `import MazTableCell from 'maz-ui/components/MazTableCell'` or `import MazTableRow from 'maz-ui/components/MazTableRow'` or `import MazTableTitle from 'maz-ui/components/MazTableTitle'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-table
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Key Features
+
+1. Pagination (prop `pagination`)
+   * The component supports pagination with buttons to go to the first, previous, next, and last page.
+   * You can display only the pagination elements (input and buttons) and make API calls to your server to get elements by using the prop `pagination` with `no-paginate-rows`.
+2. Search (prop `search`): It includes a search feature with a search bar where users can enter a query to filter displayed data. You can choose the column where the search will be activated.
+3. Column Sorting (prop: `sortable`): Columns are sortable, indicated by arrow icons. Sorting can be activated by clicking on the column header.
+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
+
+* v-model: `(string | boolean | number)[] | undefined` (list of selected key)
+* v-model:search-query: `string | undefined`
+* v-model:page: `number`
+* v-model:page-size: `number`
+
+## Basic usage
+
+You can use MazTable and his child component to build a simple table and enjoy the style.
+
+```vue
+<template>
+  <MazTable size="sm" :headers="['#', 'Lastname', 'Firstname', 'Age']">
+    <MazTableRow>
+      <MazTableCell>
+        1
+      </MazTableCell>
+      <MazTableCell>
+        John
+      </MazTableCell>
+      <MazTableCell>
+        Doe
+      </MazTableCell>
+      <MazTableCell>
+        99
+      </MazTableCell>
+    </MazTableRow>
+    <MazTableRow>
+      <MazTableCell>
+        2
+      </MazTableCell>
+      <MazTableCell>
+        Doe
+      </MazTableCell>
+      <MazTableCell>
+        John
+      </MazTableCell>
+      <MazTableCell>
+        30
+      </MazTableCell>
+    </MazTableRow>
+  </MazTable>
+</template>
+
+<script lang="ts" setup>
+  import { MazTable, MazTableRow, MazTableCell } from 'maz-ui/components'
+</script>
+```
+
+## Advanced data table
+
+You can also provide all your data, the table is auto-generated and you can use the features listed on top
+
+---
+
+```vue
+<template>
+  <MazTable
+    size="sm"
+    v-model="selectedIds"
+    v-model:search-query="searchQuery"
+    v-model:page="page"
+    v-model:page-size="pageSize"
+    search
+    pagination
+    color="secondary"
+    sortable
+    selectable
+    hoverable
+    background-even
+    selected-key="id"
+    :headers="[
+      { label:'#', key: 'index', align: 'center', width: '2rem', sortable: false },
+      { label:'Name', key: 'name' },
+      { label: 'Code', key: 'code', align: 'center'  },
+      { label: 'Type', key: 'type' },
+      { label: 'Area', key: 'areaName', align: 'center', classes: 'font-bold' },
+    ]"
+    :rows="competitions"
+  >
+    <template #cell-index="{ value }">
+      <span class="text-base">{{value}}</span>
+    </template>
+    <template #cell-name="{ row, value }">
+      <div class="flex items-center gap-2">
+        <MazAvatar :src="row.logoUrl" size="0.5rem"></MazAvatar>
+        <span>{{value}}</span>
+      </div>
+    </template>
+    <template #cell-type="{ value }">
+      <MazBadge :color="value === 'CUP' ? 'primary' : 'secondary'">{{value}}</MazBadge>
+    </template>
+
+    <template #actions>
+      <MazBtn fab size="xs" color="destructive" icon="/trash.svg" />
+    </template>
+  </MazTable>
+</template>
+
+<script lang="ts" setup>
+  import MazTable from 'maz-ui/components/MazTable'
+
+  const competitions = [
+  {
+    id: '0262672d-7c7a-4d30-866e-edb88b5a5336',
+    name: 'UEFA Champions League',
+    code: 'CL',
+    type: 'CUP',
+    areaName: 'Europe',
+    matchday: 6,
+    logoUrl: 'https://crests.football-data.org/CL.png',
+    groups: 1,
+    index: 1,
+  },
+  {
+    id: '08d15e97-a319-4772-9b82-f1877369b40f',
+    name: 'Premier League',
+    code: 'PL',
+    type: 'LEAGUE',
+    areaName: 'England',
+    matchday: 18,
+    logoUrl: 'https://crests.football-data.org/PL.png',
+    groups: 1,
+    index: 2,
+  },
+  {
+    id: '17e62396-bbcb-42f5-acff-caed11534976',
+    name: 'Serie A',
+    code: 'SA',
+    type: 'LEAGUE',
+    areaName: 'Italy',
+    matchday: 17,
+    logoUrl: 'https://crests.football-data.org/SA.png',
+    groups: 0,
+    index: 3,
+  },
+  {
+    id: '3726264e-ba3a-4a9f-b4a4-8fc33e12747c',
+    name: 'FIFA World Cup',
+    code: 'WC',
+    type: 'CUP',
+    areaName: 'World',
+    matchday: 8,
+    logoUrl: 'https://crests.football-data.org/qatar.png',
+    groups: 1,
+    index: 4,
+  },
+  {
+    id: '555dc3f4-e592-46af-b634-59f07a201f2e',
+    name: 'Primeira Liga',
+    code: 'PPL',
+    type: 'LEAGUE',
+    areaName: 'Portugal',
+    matchday: 15,
+    logoUrl: 'https://crests.football-data.org/PPL.png',
+    groups: 0,
+    index: 5,
+  },
+  {
+    id: '59bbdfa0-86d8-4a74-b701-435747c55a42',
+    name: 'Primera Division',
+    code: 'PD',
+    type: 'LEAGUE',
+    areaName: 'Spain',
+    matchday: 18,
+    logoUrl: 'https://crests.football-data.org/PD.png',
+    groups: 1,
+    index: 6,
+  },
+  {
+    id: '6ae53332-3d27-4781-912d-d9c4e69657f9',
+    name: 'Ligue 1',
+    code: 'FL1',
+    type: 'LEAGUE',
+    areaName: 'France',
+    matchday: 17,
+    logoUrl: 'https://crests.football-data.org/FL1.png',
+    groups: 4,
+    index: 7,
+  },
+  {
+    id: '747c79ee-89c8-436a-b0ea-53f05f180007',
+    name: 'European Championship',
+    code: 'EC',
+    type: 'CUP',
+    areaName: 'Europe',
+    matchday: 1,
+    logoUrl: 'https://crests.football-data.org/EUR.svg',
+    groups: 1,
+    index: 8,
+  },
+  {
+    id: '7a32d897-6b22-4212-8ffe-049ae912c346',
+    name: 'Eredivisie',
+    code: 'DED',
+    type: 'LEAGUE',
+    areaName: 'Netherlands',
+    matchday: 18,
+    logoUrl: 'https://crests.football-data.org/ED.png',
+    groups: 0,
+    index: 9,
+  },
+  {
+    id: 'ab57e2dc-272c-45e6-b13e-57617a13b753',
+    name: 'Championship',
+    code: 'ELC',
+    type: 'LEAGUE',
+    areaName: 'England',
+    matchday: 23,
+    logoUrl: 'https://crests.football-data.org/ELC.png',
+    groups: 0,
+    index: 10,
+  },
+  {
+    id: 'b84e3295-7315-46c7-b979-6d9d784e5460',
+    name: 'Campeonato Brasileiro Série A',
+    code: 'BSA',
+    type: 'LEAGUE',
+    areaName: 'Brazil',
+    matchday: 38,
+    logoUrl: 'https://crests.football-data.org/764.svg',
+    groups: 0,
+    index: 11,
+  },
+  {
+    id: 'cafad3ce-1783-4652-9248-4bcad024dd98',
+    name: 'Copa Libertadores',
+    code: 'CLI',
+    type: 'CUP',
+    areaName: 'South America',
+    matchday: 11,
+    logoUrl: 'https://crests.football-data.org/CLI.svg',
+    groups: 0,
+    index: 12,
+  },
+  {
+    id: 'ed945bea-9a58-450a-8d62-7baa7722b5e7',
+    name: 'Bundesliga',
+    code: 'BL1',
+    type: 'LEAGUE',
+    areaName: 'Germany',
+    matchday: 16,
+    logoUrl: 'https://crests.football-data.org/BL1.png',
+    groups: 0,
+    index: 13,
+  },
+]
+</script>
+```
+
+## 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.
+
+```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>
+```
+
+## 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.
+
+```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>
+```
+
+### 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`
+
+```html{2}
+<MazTable
+  :loading="true"
+  :headers="['#', 'Lastname', 'Firstname', 'Age']"
+>
+  ...
+</MazTable>
+```
+
+## Sizing
+
+Available sizes: `'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`
+
+```html
+<MazTable size="xs" :headers="['#', 'Lastname', 'Firstname', 'Age']">
+  ...
+</MazTable>
+<MazTable size="md" :headers="['#', 'Lastname', 'Firstname', 'Age']">
+  ...
+</MazTable>
+<MazTable size="lg" :headers="['#', 'Lastname', 'Firstname', 'Age']">
+  ...
+</MazTable>
+```
+
+```ts
+type Row =  Record<string, any> & {
+  selected?: boolean
+  action?: (row: Row) => unknown
+  classes?: HTMLAttributes['class']
+}
+```
+
+```ts
+export interface MazTableHeadersEnriched {
+  label: string
+  key?: string
+  sortable?: boolean
+  hidden?: boolean
+  srOnly?: boolean
+  width?: string
+  maxWidth?: string
+  minWidth?: string
+  classes?: ThHTMLAttributes['class']
+  scope?: ThHTMLAttributes['scope']
+  align?: ThHTMLAttributes['align']
+  rowspan?: ThHTMLAttributes['rowspan']
+  colspan?: ThHTMLAttributes['colspan']
+  headers?: ThHTMLAttributes['headers']
+}
+```

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

@@ -0,0 +1,43 @@
+---
+title: "MazTabsBar"
+description: "MazTabsBar is a building block of MazTabs."
+package: "maz-ui"
+---
+
+# MazTabsBar
+
+> MazTabsBar is a building block of MazTabs.
+
+- Package: `maz-ui`
+- Import: `import MazTabsBar from 'maz-ui/components/MazTabsBar'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+Used inside [MazTabs](./maz-tabs.md): read its page for complete examples.
+
+## MazTabsBar API
+
+`import MazTabsBar from 'maz-ui/components/MazTabsBar'`
+
+### Props
+
+- `items` (`readonly Item[]`, required): The items to display in the tabs bar.
+- `model-value` (`MazTabsBarItemValue<Item>`, `v-model`): Selected tab (standalone usage, without MazTabs). Holds the item `value` when provided, otherwise the 1-based index. Pass items `as const` (or with literal `value`) to infer a union type.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): Size of the tabs (forwarded to each MazBtn).
+- `rounded-size` (`MazRoundedSize`, default: `'md'`): Size of the rounded applied to the bar, the indicator and each tab. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`): Color of the active tab indicator. When omitted, the default neutral indicator is used.
+- `standalone` (`boolean`, default: `false`): Force the standalone mode: the tabs bar ignores any surrounding `MazTabs` (selection, size, rounded-size and color are no longer inherited) and is driven only by its own `v-model`. Useful for a nested switcher inside a page already wrapped by `MazTabs`.
+- `persistent` (`boolean`, default: `false`): Will add a query param to the url to keep the selected tab on page refresh.
+- `query-param` (`string`, default: `"tab"`): The name of the query param to add to the url.
+- `block` (`boolean`, default: `false`): Will make the tabs bar full width.
+- `elevation` (`boolean`, default: `false`): Will remove the elevation.
+- `auto-scroll` (`boolean`, default: `true`): Will add a scroll on the tabs bar to show selected element.
+- `bordered` (`boolean`, default: `true`): Will add a border to the tabs bar.
+
+### Events
+
+- `@update:model-value` (payload: `value: MazTabsBarItemValue<Item>`): Emitted when the selected tab changes (standalone usage).
+
+### Slots
+
+- `#item`: Content of item to display in the tabs bar Bindings: `item: { label: Item & string; value: string | number | undefined; disabled: boolean; size: "xs" | "sm" | "md" | "lg" | "xl" | "mini" | undefined; roundedSize: MazRoundedSize | undefined; color: NonNullable<"primary" | "secondary" | "accent" | ...` (all data of the item), `active: boolean` (`true` if the tab is active), `index: number` (index of the item).
+- `#badge-content`: Content in the badge Bindings: `content: string | number | boolean` (content of the badge provided in item).

package/docs/components/maz-tabs-content-item.md

@@ -0,0 +1,27 @@
+---
+title: "MazTabsContentItem"
+description: "MazTabsContentItem is a building block of MazTabs."
+package: "maz-ui"
+---
+
+# MazTabsContentItem
+
+> MazTabsContentItem is a building block of MazTabs.
+
+- Package: `maz-ui`
+- Import: `import MazTabsContentItem from 'maz-ui/components/MazTabsContentItem'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+Used inside [MazTabs](./maz-tabs.md): read its page for complete examples.
+
+## MazTabsContentItem API
+
+`import MazTabsContentItem from 'maz-ui/components/MazTabsContentItem'`
+
+### Props
+
+- `tab` (`number`, required)
+
+### Slots
+
+- `#default`

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

@@ -0,0 +1,27 @@
+---
+title: "MazTabsContent"
+description: "MazTabsContent is a building block of MazTabs."
+package: "maz-ui"
+---
+
+# MazTabsContent
+
+> MazTabsContent is a building block of MazTabs.
+
+- Package: `maz-ui`
+- Import: `import MazTabsContent from 'maz-ui/components/MazTabsContent'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+Used inside [MazTabs](./maz-tabs.md): read its page for complete examples.
+
+## MazTabsContent API
+
+`import MazTabsContent from 'maz-ui/components/MazTabsContent'`
+
+### Props
+
+No props.
+
+### Slots
+
+- `#default`