maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-container.md

@@ -0,0 +1,241 @@
+---
+title: "MazContainer"
+description: "MazContainer is a lightweight component to wrap content with optional header, border, elevation, and rounded corners - a simpler alternative to MazCard"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-container"
+---
+
+# MazContainer
+
+> MazContainer is a lightweight component to wrap content with optional header, border, elevation, and rounded corners - a simpler alternative to MazCard
+
+- Package: `maz-ui`
+- Import: `import MazContainer from 'maz-ui/components/MazContainer'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-container
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Tip:**
+
+MazContainer is designed to be a lighter alternative to [MazCard](./maz-card.md). Use it when you need a simple container with basic styling options without the extra features like galleries, collapsible content, or actions.
+
+## Basic usage
+
+```vue
+<template>
+  <MazContainer>
+    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.
+  </MazContainer>
+</template>
+
+<script lang="ts" setup>
+  import MazContainer from 'maz-ui/components/MazContainer'
+</script>
+```
+
+## With title
+
+Add a header with a title using the `title` prop or the `title` slot.
+
+```vue
+<template>
+  <MazContainer title="Section Title">
+    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.
+  </MazContainer>
+</template>
+```
+
+## With icons
+
+Add icons to the header using `start-icon` and `end-icon` props.
+
+```vue
+<template>
+  <MazContainer title="Settings" start-icon="/cog-6-tooth.svg">
+    Configure your application settings here.
+  </MazContainer>
+
+  <MazContainer title="User Profile" start-icon="/user.svg" end-icon="/pencil.svg">
+    View and edit your profile information.
+  </MazContainer>
+</template>
+```
+
+`startIcon` and `endIcon` also accept a full `MazIconProps` object - pass the same shape `<MazIcon>` accepts to override the icon size, add a `<title>` for screen readers, etc.
+
+```vue
+<MazContainer
+  title="Settings"
+  :start-icon="{
+    icon: MazCog6Tooth,
+    size: 'lg',
+    title: 'Open settings',
+  }"
+>
+  Configure your application settings here.
+</MazContainer>
+```
+
+## Styling options
+
+### Elevation
+
+Add shadow to make the container stand out.
+
+```vue
+<template>
+  <MazContainer elevation :bordered="false">
+    Container with elevation effect and no border.
+  </MazContainer>
+</template>
+```
+
+### Bordered
+
+By default, the container has a border. You can disable it.
+
+```vue
+<template>
+  <MazContainer title="With border (default)">
+    This container has a border.
+  </MazContainer>
+
+  <MazContainer title="Without border" :bordered="false">
+    This container has no border.
+  </MazContainer>
+</template>
+```
+
+### Transparent
+
+Remove the background color with the `transparent` prop.
+
+```vue
+<template>
+  <MazContainer title="Transparent container" transparent>
+    This container has a transparent background.
+  </MazContainer>
+</template>
+```
+
+### Rounded sizes
+
+Customize the border radius with the `rounded-size` prop.
+
+```vue
+<template>
+  <MazContainer v-for="size in roundedSizes" :key="size" :rounded-size="size">
+    {{ size }}
+  </MazContainer>
+</template>
+
+<script lang="ts" setup>
+  import MazContainer from 'maz-ui/components/MazContainer'
+
+  const roundedSizes = ['none', 'sm', 'md', 'lg', 'xl', 'full']
+</script>
+```
+
+### No padding
+
+Remove internal padding with `:padding="false"`.
+
+```vue
+<template>
+  <MazContainer title="No padding" :padding="false">
+    Content without container padding - useful for custom layouts.
+  </MazContainer>
+</template>
+```
+
+## Full width
+
+Use the `block` prop to make the container take full width.
+
+```vue
+<template>
+  <MazContainer title="Full width container" block>
+    This container spans the full width of its parent.
+  </MazContainer>
+</template>
+```
+
+## Custom header
+
+Use the `header` slot to fully customize the header, or use `title`, `icon-start`, and `icon-end` slots for more granular control.
+
+```vue
+<template>
+  <MazContainer>
+    <template #header>
+      <div class="flex items-center justify-between w-full px-4 py-3 bg-primary text-primary-foreground">
+        <span class="font-semibold">Custom Header</span>
+        <MazBadge size="sm" color="white" class="text-primary">
+          New
+        </MazBadge>
+      </div>
+    </template>
+    Content with a fully customized header.
+  </MazContainer>
+</template>
+```
+
+## Combining options
+
+```vue
+<template>
+  <MazContainer
+    title="Dashboard Overview"
+    start-icon="/chart-bar.svg"
+    elevation
+    :bordered="false"
+    rounded-size="xl"
+    block
+  >
+    <div class="flex gap-4 flex-wrap">
+      <MazContainer class="flex-1 min-w-[150px]">
+        <p class="text-muted text-sm">Users</p>
+        <p class="text-2xl font-bold">1,234</p>
+      </MazContainer>
+      <MazContainer class="flex-1 min-w-[150px]">
+        <p class="text-muted text-sm">Revenue</p>
+        <p class="text-2xl font-bold">$12.5k</p>
+      </MazContainer>
+      <MazContainer class="flex-1 min-w-[150px]">
+        <p class="text-muted text-sm">Orders</p>
+        <p class="text-2xl font-bold">567</p>
+      </MazContainer>
+    </div>
+  </MazContainer>
+</template>
+```
+
+## MazContainer API
+
+`import MazContainer from 'maz-ui/components/MazContainer'`
+
+### Props
+
+- `title` (`string`): Title of the card in header.
+- `elevation` (`boolean`, default: `false`): Add elevation to the component.
+- `padding` (`boolean`, default: `true`): Add padding to the content.
+- `bordered` (`boolean`, default: `true`): Add border to the component.
+- `rounded-size` (`MazRoundedSize`, default: `'md'`): Size of the rounded. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
+- `transparent` (`boolean`, default: `false`): Remove background color.
+- `overflow-hidden` (`boolean`, default: `true`): Hide overflow.
+- `start-icon` (`MazIconLike`): Icon displayed on the inline-start edge of the header (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
+- `end-icon` (`MazIconLike`): Icon displayed on the inline-end edge of the header (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `icon-size` (`MazIconSize`, default: `"md"`): Size of the icon.
+- `block` (`boolean`, default: `false`): Display the container in full width.
+- `content-class` (`string`): Additional class to add to the content wrapper.
+
+### Slots
+
+- `#header`: Replace the header
+- `#icon-start`: inline-start edge of the header (left in LTR, right in RTL)
+- `#title`: title
+- `#icon-end`: inline-end edge of the header (right in LTR, left in RTL)
+- `#default`: content of the container