maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-timeline.md

@@ -0,0 +1,304 @@
+---
+title: "MazTimeline"
+description: "MazTimeline is a step/progress timeline component for Vue 3 with support for horizontal, vertical, and responsive layouts, customizable colors, sizes, step states, and scoped slots"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-timeline"
+---
+
+# MazTimeline
+
+> MazTimeline is a step/progress timeline component for Vue 3 with support for horizontal, vertical, and responsive layouts, customizable colors, sizes, step states, and scoped slots
+
+- Package: `maz-ui`
+- Import: `import MazTimeline from 'maz-ui/components/MazTimeline'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-timeline
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+---
+
+Control the current step:
+
+## Basic usage
+
+```vue
+<template>
+  <MazTimeline v-model="currentStep" :steps="steps" />
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazTimeline from 'maz-ui/components/MazTimeline'
+
+  const currentStep = ref(1)
+  const steps = [
+    { title: 'Account', subtitle: 'Create your account' },
+    { title: 'Profile', subtitle: 'Set up your profile' },
+    { title: 'Settings', subtitle: 'Configure preferences' },
+    { title: 'Complete', subtitle: 'All done!' },
+  ]
+</script>
+```
+
+## Directions
+
+### Horizontal
+
+```vue
+<template>
+  <MazTimeline v-model="currentStep" :steps="steps" direction="horizontal" />
+</template>
+```
+
+### Vertical
+
+```vue
+<template>
+  <MazTimeline v-model="currentStep" :steps="steps" direction="vertical" />
+</template>
+```
+
+### Auto (responsive)
+
+The default direction is `'auto'`, which switches from horizontal to vertical based on the `breakpoint` prop (default: `'768px'`).
+
+```vue
+<template>
+  <MazTimeline
+    v-model="currentStep"
+    :steps="steps"
+    direction="auto"
+    breakpoint="768px"
+  />
+</template>
+```
+
+## Colors
+
+Use the `color` prop to change the theme color.
+
+```vue
+<template>
+  <MazTimeline :steps="steps" color="primary" />
+  <MazTimeline :steps="steps" color="secondary" />
+  <MazTimeline :steps="steps" color="info" />
+  <MazTimeline :steps="steps" color="success" />
+  <MazTimeline :steps="steps" color="warning" />
+  <MazTimeline :steps="steps" color="destructive" />
+</template>
+```
+
+## Sizes
+
+Use the `size` prop to change the indicator size.
+
+```vue
+<template>
+  <MazTimeline :steps="steps" size="mini" />
+  <MazTimeline :steps="steps" size="xs" />
+  <MazTimeline :steps="steps" size="sm" />
+  <MazTimeline :steps="steps" size="md" />
+  <MazTimeline :steps="steps" size="lg" />
+  <MazTimeline :steps="steps" size="xl" />
+</template>
+```
+
+## Step states
+
+Each step can have a manual `state` property: `'completed'`, `'active'`, `'error'`, `'warning'`, or `'pending'`.
+
+```vue
+<template>
+  <MazTimeline :steps="stateSteps" direction="horizontal" />
+</template>
+
+<script lang="ts" setup>
+  const stateSteps = [
+    { title: 'Completed', subtitle: 'Step finished', state: 'completed' },
+    { title: 'Active', subtitle: 'In progress', state: 'active' },
+    { title: 'Error', subtitle: 'Something went wrong', state: 'error' },
+    { title: 'Warning', subtitle: 'Needs attention', state: 'warning' },
+    { title: 'Pending', subtitle: 'Not started', state: 'pending' },
+  ]
+</script>
+```
+
+## Clickable
+
+Enable `clickable` to allow users to navigate between steps by clicking on them. The `click-step` event is emitted with the step index.
+
+```vue
+<template>
+  <MazTimeline v-model="clickableStep" :steps="steps" clickable />
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+
+  const clickableStep = ref(0)
+</script>
+```
+
+## Disabled steps
+
+Individual steps can be disabled by setting `disabled: true` on the step object.
+
+```vue
+<template>
+  <MazTimeline v-model="currentStep" :steps="disabledSteps" clickable />
+</template>
+
+<script lang="ts" setup>
+  const disabledSteps = [
+    { title: 'Account', subtitle: 'Create your account' },
+    { title: 'Profile', subtitle: 'Set up your profile' },
+    { title: 'Settings', subtitle: 'Locked', disabled: true },
+    { title: 'Complete', subtitle: 'All done!' },
+  ]
+</script>
+```
+
+## Without step numbers
+
+Hide the step numbers inside indicators with `:show-step-numbers="false"`.
+
+```vue
+<template>
+  <MazTimeline
+    v-model="currentStep"
+    :steps="steps"
+    :show-step-numbers="false"
+  />
+</template>
+```
+
+## Without auto-validate
+
+By default, completed steps show a checkmark. Disable this with `:auto-validate-steps="false"`.
+
+```vue
+<template>
+  <MazTimeline
+    :model-value="2"
+    :steps="steps"
+    :auto-validate-steps="false"
+  />
+</template>
+```
+
+## Rounded sizes
+
+Customize the indicator border radius with the `rounded-size` prop.
+
+```vue
+<template>
+  <MazTimeline :steps="steps" rounded-size="full" />
+  <MazTimeline :steps="steps" rounded-size="lg" />
+  <MazTimeline :steps="steps" rounded-size="md" />
+  <MazTimeline :steps="steps" rounded-size="sm" />
+  <MazTimeline :steps="steps" rounded-size="none" />
+</template>
+```
+
+## Custom Icons
+
+```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>
+```
+
+## Custom slots
+
+MazTimeline provides scoped slots for full customization.
+
+### Indicator slot
+
+```vue
+<template>
+  <MazTimeline v-model="currentStep" :steps="steps">
+    <template #indicator="{ step, index, state }">
+      <span style="font-size: 1.2em">{{ index + 1 }}.</span>
+    </template>
+  </MazTimeline>
+</template>
+```
+
+### Content slot
+
+```vue
+<template>
+  <MazTimeline v-model="currentStep" :steps="steps">
+    <template #content="{ step, index, state }">
+      <div class="text-center">
+        <strong>{{ step.title }}</strong>
+        <p class="text-muted text-sm m-0">
+          Step {{ index + 1 }} - {{ state }}
+        </p>
+      </div>
+    </template>
+  </MazTimeline>
+</template>
+```
+
+### Connector slot
+
+```vue
+<template>
+  <MazTimeline v-model="currentStep" :steps="steps">
+    <template #connector="{ index, state }">
+      <div class="text-center text-xs text-muted">---</div>
+    </template>
+  </MazTimeline>
+</template>
+```
+
+## MazTimeline API
+
+`import MazTimeline from 'maz-ui/components/MazTimeline'`
+
+### Props
+
+- `model-value` (`number`, `v-model`): Index of the active step (v-model).
+- `steps` (`MazTimelineItem[]`, required): Array of timeline steps to display.
+- `direction` (`MazTimelineDirection`, default: `"auto"`): Layout direction of the timeline - `'horizontal'`: always horizontal - `'vertical'`: always vertical - `'auto'`: horizontal above breakpoint, vertical below. Values: `'horizontal'`, `'vertical'`, `'auto'` (non exhaustive).
+- `breakpoint` (`string`, default: `"768px"`): CSS media breakpoint for auto direction (below this value → vertical).
+- `color` (`MazTimelineColor`, default: `"primary"`): Color theme for active and completed steps. Values: `'primary'`, `'secondary'`, `'accent'`, `'info'`, `'success'`, `'warning'`, `'destructive'`, `'contrast'` (non exhaustive).
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): Size of the step indicators and typography.
+- `show-step-numbers` (`boolean`, default: `true`): Show step numbers inside the indicators.
+- `auto-validate-steps` (`boolean`, default: `true`): Automatically show a checkmark icon for completed steps.
+- `clickable` (`boolean`, default: `false`): Enable click interaction on steps.
+- `animated` (`boolean`, default: `true`): Enable animations (pulse on active, state transitions, connector progress).
+- `rounded-size` (`MazTimelineRoundedSize`, default: `'md'`): Border radius of step indicators. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'2xl'`, `'3xl'`, `'full'` (non exhaustive).
+
+### Events
+
+- `@update:model-value` (payload: `value: number`): Emitted when the active step changes
+- `@click-step` (payload: `payload: { step: MazTimelineItem; index: number; }`): Emitted when a clickable step is clicked
+
+### Slots
+
+- `#indicator`: Custom content for the step indicator circle Bindings: `step: MazTimelineItem` (The step data), `index: number` (The step index), `state: MazTimelineStepState` (The resolved step state), `isActive: boolean`, `isCompleted: boolean`.
+- `#content`: Full custom content area replacing title and subtitle Bindings: `step: MazTimelineItem` (The step data), `index: number` (The step index), `state: MazTimelineStepState` (The resolved step state), `isActive: boolean`, `isCompleted: boolean`.
+- `#title`: Custom title content Bindings: `step: MazTimelineItem` (The step data), `index: number` (The step index), `state: MazTimelineStepState` (The resolved step state).
+- `#subtitle`: Custom subtitle content Bindings: `step: MazTimelineItem` (The step data), `index: number` (The step index), `state: MazTimelineStepState` (The resolved step state).
+- `#connector`: Custom connector between steps Bindings: `index: number` (The index of the step before this connector), `isCompleted: boolean`, `isActive: boolean`.

package/docs/components/maz-ui-provider.md

@@ -0,0 +1,26 @@
+---
+title: "MazUiProvider"
+description: "MazUiProvider component."
+package: "maz-ui"
+---
+
+# MazUiProvider
+
+> MazUiProvider component.
+
+- Package: `maz-ui`
+- Import: `import MazUiProvider from 'maz-ui/components/MazUiProvider'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+## MazUiProvider API
+
+`import MazUiProvider from 'maz-ui/components/MazUiProvider'`
+
+### Props
+
+- `theme` (`MazUiThemeOptions & { preset: ThemePreset; }`, required)
+- `translations` (`MazUiProviderTranslations<TLocale>`, required): Must include `locale` and at least the messages for that locale in `messages`.
+
+### Slots
+
+- `#default`

package/docs/components/maz-window-mockup.md

@@ -0,0 +1,182 @@
+---
+title: "MazWindowMockup"
+description: "MazWindowMockup renders a macOS-style window frame in three variants - browser, terminal, and editor - to showcase content, demos, or code examples in your documentation or UI."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-window-mockup"
+---
+
+# MazWindowMockup
+
+> MazWindowMockup renders a macOS-style window frame in three variants - browser, terminal, and editor - to showcase content, demos, or code examples in your documentation or UI.
+
+- Package: `maz-ui`
+- Import: `import MazWindowMockup from 'maz-ui/components/MazWindowMockup'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-window-mockup
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Note: Optional: shiki for code variants**
+
+When you pass the `code` prop, `MazWindowMockup` mounts `MazCodeHighlight` internally for syntax highlighting. This requires the [`shiki`](https://shiki.style) optional peer dependency to be installed. See the [MazCodeHighlight installation note](./maz-code-highlight.md#installation-requirement).
+
+## Browser variant
+
+The default variant. Displays an address bar with the `url` prop and a copy-URL button on the right side of the bar.
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <div>Browser content goes here</div>
+  </MazWindowMockup>
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+### Hide the URL copy button
+
+Set `:hide-url-copy="true"` to remove the copy-URL button from the title bar.
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="80px" :hide-url-copy="true" />
+</template>
+```
+
+### With screenshot
+
+Use this variant to display a screenshot of a website.
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <img src="/img/screenshots/maz-ui-home-desktop.webp" alt="Maz UI Demo Dashboard" width="100%">
+  </MazWindowMockup>
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+## Terminal variant
+
+Displays a centered title and a `$` prompt prefix in front of the code (when `code` is provided). The prompt prefix is **not** copied to the clipboard - the copy button only writes the raw `code` value.
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" title="zsh" code="pnpm add maz-ui" language="bash" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+### Custom prompt
+
+Replace the default `$` with any character via the `prompt` prop.
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" prompt="❯" />
+</template>
+```
+
+### Without prompt
+
+Hide the default prompt by setting `hide-prompt` to `true`.
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" :hide-prompt="true" />
+</template>
+```
+
+## Editor variant
+
+Shows a filename tab anchored to the bottom of the title bar - matching the look of real editors like VSCode.
+
+```vue
+<template>
+  <MazWindowMockup variant="editor" filename="App.vue" :code="vueCode" language="vue" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+
+  const vueCode = `<template>
+  <MazBtn>Click me</MazBtn>
+</template>`
+</script>
+```
+
+## With code and language props
+
+Pass `code` and `language` to display highlighted source code via `MazCodeHighlight`. The inner highlighter automatically renders with squared corners so it sits flush against the window's border.
+
+```vue
+<template>
+  <MazWindowMockup code="import MazBtn from 'maz-ui/components/MazBtn'" language="ts" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+## Empty-state placeholder
+
+When neither `code` nor a slot content is provided, the content area renders an empty placeholder. Pass the optional `label` prop to display a centered text inside it.
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="160px" label="Preview" />
+</template>
+```
+
+## Custom translations
+
+The URL copy button's aria-label and tooltip come from the `@maz-ui/translations` package (`windowMockup.copyUrlToClipboard` / `windowMockup.urlCopiedToClipboard`). Override per-instance with the `translations` prop:
+
+```vue
+<template>
+  <MazWindowMockup
+    url="https://maz-ui.com"
+    min-height="80px"
+    :translations="{
+      copyUrlToClipboard: 'Copier l\'URL',
+      urlCopiedToClipboard: 'URL copiée !',
+    }"
+  />
+</template>
+```
+
+For app-wide translations, set up the [maz-ui translations plugin](../ecosystem/translations.md) and the component will pick up your locale automatically.
+
+## MazWindowMockup API
+
+`import MazWindowMockup from 'maz-ui/components/MazWindowMockup'`
+
+### Props
+
+- `id` (`string`): Stable id used to scope the empty-state SVG pattern. Auto-generated if not provided.
+- `variant` (`MazWindowMockupVariant`, default: `"browser"`): Window style variant. Values: `'browser'`, `'terminal'`, `'editor'` (non exhaustive).
+- `url` (`string`, default: `"localhost"`): URL to display in the browser address bar (browser variant only).
+- `filename` (`string`, default: `"index.vue"`): Filename to display in the editor tab (editor variant only).
+- `title` (`string`, default: `"zsh"`): Title to display in the terminal title bar (terminal variant only).
+- `min-height` (`string`): Minimum height of the content area as a CSS value (e.g. '200px').
+- `code` (`string`): Source code to display using MazCodeHighlight. Takes priority over the default slot.
+- `language` (`string`): Language identifier for syntax highlighting (e.g. 'vue', 'ts', 'bash').
+- `label` (`string`): Label displayed inside the empty-state placeholder when no code and no slot content are provided.
+- `hide-prompt` (`boolean`, default: `false`): Whether to hide the terminal prompt prefix (no-op on non-terminal variants).
+- `prompt` (`string`, default: `"$"`): Prefix to display before the code in the terminal (terminal variant only).
+- `hide-url-copy` (`boolean`, default: `false`): Hide the copy-to-clipboard button next to the URL bar (browser variant only).
+- `translations` (`{ copyUrlToClipboard?: string | undefined; urlCopiedToClipboard?: string | undefined; }`): Custom translations for the component. Override either key independently.
+
+### Slots
+
+- `#default`: Free content (image, interface, etc.) shown when code prop is not set.

package/docs/composables/use-aos.md

@@ -0,0 +1,41 @@
+---
+title: "useAos"
+description: "Vue composable for handling aos plugin in your components"
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-aos"
+---
+
+# useAos
+
+> Vue composable for handling aos plugin in your components
+
+- Package: `maz-ui`
+- Import: `import { useAos } from 'maz-ui/composables/useAos'`
+- Nuxt: auto-imported by `@maz-ui/nuxt` when `mazUi.plugins.aos` is enabled
+- Web: https://maz-ui.com/composables/use-aos
+
+**Warning:**
+
+You must install the [aos plugin](../plugins/aos.md#install) before you start using it
+
+**Tip:**
+
+More info about the [aos plugin](../plugins/aos.md) can be found in its documentation
+
+## Usage
+
+```vue
+<script lang="ts" setup>
+import { useAos } from 'maz-ui/composables'
+
+const aos = useAos()
+
+onMounted(() => {
+  aos.runAnimations()
+})
+</script>
+
+<template>
+  <img data-maz-aos="scale-in">
+</template>
+```

package/docs/composables/use-breakpoints.md

@@ -0,0 +1,42 @@
+---
+title: "useWindowSize"
+description: "This composable extends the functionality of the useWindowSize composable to manage responsive breakpoints"
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-breakpoints"
+---
+
+# useWindowSize
+
+> This composable extends the functionality of the useWindowSize composable to manage responsive breakpoints
+
+- Package: `maz-ui`
+- Import: `import { useBreakpoints } from 'maz-ui/composables/useBreakpoints'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/composables/use-breakpoints
+
+## Basic usage
+
+```ts
+const breakpoints = {
+  'sm': '640px',
+  'md': '768px',
+  'lg': '1024px',
+  'xl': '1280px',
+  '2xl': '1536px',
+}
+
+const {
+  isLargeScreen,
+  isMediumScreen,
+  isSmallScreen,
+} = useBreakpoints({
+  breakpoints,
+  initialWidth: 0,
+  mediumBreakPoint: 'md',
+  largeBreakPoint: 'lg',
+})
+```
+
+**Warning:**
+
+More documentation to come

package/docs/composables/use-dialog.md

@@ -0,0 +1,58 @@
+---
+title: "useDialog"
+description: "Vue composable for handling dialog plugin in your components"
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-dialog"
+---
+
+# useDialog
+
+> Vue composable for handling dialog plugin in your components
+
+- Package: `maz-ui`
+- Import: `import { useDialog } from 'maz-ui/composables/useDialog'`
+- Nuxt: auto-imported by `@maz-ui/nuxt` when `mazUi.plugins.dialog` is enabled
+- Web: https://maz-ui.com/composables/use-dialog
+
+**Warning:**
+
+You must install [dialog plugin](../plugins/dialog.md#install) before use it
+
+**Tip:**
+
+More info about [dialog plugin](../plugins/dialog.md) in its documentation
+
+## Usage
+
+```vue
+<script lang="ts" setup>
+import { useDialog, useToast } from 'maz-ui/composables'
+
+const dialog = useDialog()
+
+const toast = useToast()
+
+function openDialog() {
+  dialog.open({
+    title: 'Dialog title',
+    message: 'Dialog message',
+    onAccept: (response) => {
+      toast.success(`Dialog accepted`, {
+        position: 'bottom',
+      })
+    },
+    onReject: (response) => {
+      toast.error(`Dialog rejected`, {
+        position: 'bottom',
+      })
+    },
+  })
+}
+</script>
+
+<template>
+  <MazBtn @click="openDialog">
+    Open Dialog
+  </MazBtn>
+</template>
+```