maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-btn-group.md

@@ -0,0 +1,316 @@
+---
+title: "MazBtnGroup"
+description: "MazBtnGroup is a component to group multiple MazBtn buttons together with seamless styling. Supports props-based or slot-based rendering with customizable orientation, size, and color."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-btn-group"
+---
+
+# MazBtnGroup
+
+> MazBtnGroup is a component to group multiple MazBtn buttons together with seamless styling. Supports props-based or slot-based rendering with customizable orientation, size, and color.
+
+- Package: `maz-ui`
+- Import: `import MazBtnGroup from 'maz-ui/components/MazBtnGroup'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-btn-group
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage with items
+
+Use the `items` prop to quickly create a button group from an array of button configurations.
+
+```vue
+<template>
+  <MazBtnGroup :items="items" />
+</template>
+
+<script lang="ts" setup>
+import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
+import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
+
+const items: MazButtonGroupOption[] = [
+  { text: 'Day' },
+  { text: 'Week', active: true },
+  { text: 'Month' },
+]
+</script>
+```
+
+## Slot-based usage
+
+Use the default slot to pass `MazBtn` components directly for full control over each button.
+
+```vue
+<template>
+  <MazBtnGroup>
+    <MazBtn>Edit</MazBtn>
+    <MazBtn :active="true">Save</MazBtn>
+    <MazBtn>Delete</MazBtn>
+  </MazBtnGroup>
+</template>
+
+<script lang="ts" setup>
+import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
+import MazBtn from 'maz-ui/components/MazBtn'
+</script>
+```
+
+## Orientation
+
+Use the `orientation` prop to arrange buttons horizontally (`row`) or vertically (`col`).
+
+```vue
+<template>
+  <MazBtnGroup :items="items" orientation="row" />
+  <MazBtnGroup :items="items" orientation="col" />
+</template>
+```
+
+## Sizes
+
+Use the `size` prop to apply a size to all buttons in the group.
+
+```vue
+<template>
+  <MazBtnGroup :items="items" size="mini" />
+  <MazBtnGroup :items="items" size="xs" />
+  <MazBtnGroup :items="items" size="sm" />
+  <MazBtnGroup :items="items" size="md" />
+  <MazBtnGroup :items="items" size="lg" />
+  <MazBtnGroup :items="items" size="xl" />
+</template>
+```
+
+## Colors
+
+Use the `color` prop to apply a color to all buttons in the group.
+
+```vue
+<template>
+  <MazBtnGroup :items="items" color="primary" />
+  <MazBtnGroup :items="items" color="secondary" />
+  <MazBtnGroup :items="items" color="info" />
+  <MazBtnGroup :items="items" color="success" />
+  <MazBtnGroup :items="items" color="warning" />
+  <MazBtnGroup :items="items" color="destructive" />
+</template>
+```
+
+## Button variants
+
+Use the `outlined` or `pastel` properties on individual buttons or apply different variants to buttons in the group.
+
+### Outlined
+
+```vue
+<template>
+  <MazBtnGroup :items="items" />
+</template>
+
+<script lang="ts" setup>
+import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
+import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
+
+const items: MazButtonGroupOption[] = [
+  { text: 'Day', outlined: true },
+  { text: 'Week', outlined: true },
+  { text: 'Month', outlined: true },
+]
+</script>
+```
+
+### Pastel
+
+```vue
+<template>
+  <MazBtnGroup :items="items" />
+</template>
+
+<script lang="ts" setup>
+import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
+import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
+
+const items: MazButtonGroupOption[] = [
+  { text: 'Day', pastel: true },
+  { text: 'Week', pastel: true },
+  { text: 'Month', pastel: true },
+]
+</script>
+```
+
+### Slot-based variants
+
+```vue
+<template>
+  <MazBtnGroup>
+    <MazBtn outlined>Edit</MazBtn>
+    <MazBtn outlined>Save</MazBtn>
+    <MazBtn outlined>Delete</MazBtn>
+  </MazBtnGroup>
+
+  <MazBtnGroup>
+    <MazBtn pastel>Edit</MazBtn>
+    <MazBtn pastel>Save</MazBtn>
+    <MazBtn pastel>Delete</MazBtn>
+  </MazBtnGroup>
+</template>
+```
+
+## Click handlers
+
+Add click handlers to buttons using the `onClick` property in items.
+
+```vue
+<template>
+  <MazBtnGroup :items="items" />
+</template>
+
+<script lang="ts" setup>
+import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
+import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
+
+const items: MazButtonGroupOption[] = [
+  { text: 'Alert', onClick: () => alert('Clicked Alert!') },
+  { text: 'Console', onClick: () => console.log('Clicked Console!') },
+]
+</script>
+```
+
+## With icons
+
+Use the `startIcon` or `endIcon` properties to add icons to buttons.
+
+```vue
+<template>
+  <MazBtnGroup :items="items" />
+  <MazBtnGroup :items="iconOnlyItems" />
+</template>
+
+<script lang="ts" setup>
+import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
+import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
+import { MazArrowLeft } from '@maz-ui/icons/raw/MazArrowLeft'
+import { MazArrowRight } from '@maz-ui/icons/raw/MazArrowRight'
+
+const items: MazButtonGroupOption[] = [
+  { text: 'Previous', startIcon: MazArrowLeft, active: true },
+  { text: 'Next', endIcon: MazArrowRight },
+]
+
+const iconOnlyItems: MazButtonGroupOption[] = [
+  { icon: MazBars3, color: 'transparent', outlined: true, active: true },
+  { icon: MazSquares2x2, color: 'transparent', outlined: true },
+]
+</script>
+```
+
+## With links
+
+Use the `href` or `to` properties to create link buttons.
+
+```vue
+<template>
+  <MazBtnGroup :items="items" />
+</template>
+
+<script lang="ts" setup>
+import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
+import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
+
+const items: MazButtonGroupOption[] = [
+  { text: 'External Link', href: 'https://maz-ui.com', target: '_blank' },
+  { text: 'Router Link', to: { path: '/components/maz-btn' } },
+]
+</script>
+```
+
+## Mixed button styles
+
+Combine different button styles within the same group.
+
+```vue
+<template>
+  <MazBtnGroup :items="items" />
+</template>
+
+<script lang="ts" setup>
+import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
+import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
+
+const items: MazButtonGroupOption[] = [
+  { text: 'Primary', color: 'primary' },
+  { text: 'Success', color: 'success' },
+  { text: 'Warning', color: 'warning', outlined: true },
+  { text: 'Destructive', color: 'destructive', pastel: true },
+]
+</script>
+```
+
+## Types
+
+### MazButtonGroupOption
+
+```ts
+import type { MazBtnProps } from 'maz-ui/components/MazBtn'
+import type { RouteLocationRaw } from 'vue-router'
+
+interface MazButtonGroupOption extends Omit<MazBtnProps, 'block'> {
+  /** The text of the button */
+  text: string
+  /** Click handler for the button */
+  onClick?: () => void
+  /** The href for anchor links */
+  href?: string
+  /** The route for router-link */
+  to?: RouteLocationRaw
+}
+```
+
+### MazButtonGroupProps
+
+```ts
+interface MazButtonGroupProps {
+  /**
+   * The items for the button group (optional when using slot-based approach)
+   * @default undefined
+   */
+  items?: MazButtonGroupOption[]
+  /**
+   * The orientation of the button group
+   * @values 'row' | 'col'
+   * @default 'row'
+   */
+  orientation?: 'row' | 'col'
+  /**
+   * The size of all buttons (only applies to props-based buttons)
+   * @default 'md'
+   */
+  size?: 'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  /**
+   * The color of all buttons (only applies to props-based buttons)
+   * @default 'primary'
+   */
+  color?: 'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'destructive' | 'transparent' | 'contrast' | 'accent'
+}
+```
+
+## MazBtnGroup API
+
+`import MazBtnGroup from 'maz-ui/components/MazBtnGroup'`
+
+### Props
+
+- `items` (`MazButtonGroupOption[]`): The items for the button group (optional when using slot-based approach).
+- `orientation` (`"row" | "col"`, default: `"row"`): The orientation of the button group.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of all buttons (only applies to props-based buttons).
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of all buttons (only applies to props-based buttons).
+- `rounded-size` (`MazRoundedSize`, default: `'lg'`): The rounded size of the buttons.
+- `outlined` (`boolean`, default: `false`): The outlined state of the buttons.
+- `pastel` (`boolean`, default: `false`): The pastel state of the buttons.
+- `loading` (`boolean`, default: `false`): The loading state of the buttons.
+- `disabled` (`boolean`, default: `false`): The disabled state of the buttons.
+
+### Slots
+
+- `#default`: Slot for passing MazBtn components directly