# MagicAccordion

MagicAccordion is a collection of components intended for building vertically stacked headlines where each reveals related content.

::component-preview{src="./demo/DefaultDemo.vue"}
::

## Anatomy

```vue
<template>
  <magic-accordion-provider id="your-accordion-id">
    <magic-accordion-view>
      <magic-accordion-trigger>
        <!-- your content -->
      </magic-accordion-trigger>
      <magic-accordion-content>
        <!-- your content -->
      </magic-accordion-content>
    </magic-accordion-view>
  </magic-accordion-provider>
</template>

<script setup>
const { selectView } = useMagicAccordion('your-accordion-id')
</script>
```

## Installation

### CLI

Add `@maas/vue-equipment` to your dependencies.

::package-install{name="@maas/vue-equipment"}
::

### Vue

If you are using Vue, import and add `MagicAccordionPlugin` to your app.

```js
import { createApp } from 'vue'
import { MagicAccordionPlugin } from '@maas/vue-equipment/plugins/MagicAccordion'

const app = createApp({})

app.use(MagicAccordionPlugin)
```

### Nuxt

The accordion is available as a Nuxt module. In your Nuxt config file add `@maas/vue-equipment/nuxt` to your modules and add `MagicAccordion` to the plugins in your configuration.

```js
export default defineNuxtConfig({
  modules: ['@maas/vue-equipment/nuxt'],
  vueEquipment: {
    plugins: ['MagicAccordion'],
  },
})
```

### Composable

In order to interact with the accordion from anywhere within your app, we provide a `useMagicAccordion` composable. Import it directly when needed.

```js
import { useMagicAccordion } from '@maas/vue-equipment/plugins/MagicAccordion'

const { selectView } = useMagicAccordion('your-accordion-id')

function handleClick() {
  selectView('your-view-id')
}
```

::tip
If you have installed the accordion as a Nuxt module, the composable will be auto-imported and is automatically available in your Nuxt app.
::

## Peer Dependencies

MagicAccordion relies on the following optional peer dependencies in addition to the [core peer dependencies](/overview/getting-started#core). Package managers don’t install optional peer dependencies automatically, so add them to your project.

::docs-table
---
columns:
  - label: Package
rows:
  - items:
      - label: '[@maas/vue-autosize](https://www.npmjs.com/package/@maas/vue-autosize)'
---
::

### Installation

::package-install{name="@maas/vue-autosize"}
::

## API Reference

### MagicAccordionProvider

The MagicAccordionProvider wraps the accordion and configures all child components according to the provided [options](#options).

#### Props

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Required
rows:
  - items:
      - label: id
        description: Providing an id is required. Can either be a string or a ref.
      - label: MaybeRef<string>
        escape: true
      - label: 'true'
  - items:
      - label: asChild
        description: Prevent the component from rendering and pass all functionality to a child element.
      - label: boolean
      - label: 'false'
  - items:
      - label: options
        description: Refer to the [options table](#options) for details.
      - label: MagicAccordionOptions
      - label: 'false'
---
::

#### Options

To customize the accordion, override the necessary options. Any custom options will be merged with the default options.

::docs-table
---
columns:
  - label: Option
  - label: Type
  - label: Default
rows:
  - items:
      - label: mode
        description: Set mode to multiple to allow multiple views to be open in parallel.
      - label: AccordionMode
        description: "'single' | 'multiple'"
      - label: single
  - items:
      - label: transition
        description: Override the [transition name](https://vuejs.org/guide/built-ins/transition#named-transitions) of nested `MagicAccordionContent` elements.
      - label: string
      - label: string
        description: "'magic-accordion'"
  - items:
      - label: animation.duration
        description: Configure the accordions’s animation duration.
      - label: number
      - label: '200'
  - items:
      - label: animation.easing
        description: Configure the accordions’s animation easing.
      - label: function
        description: '(t: number) => number'
      - label: easeOutQuad
        description: t * (2 - t)
  - items:
      - label: disabled
        description: Disable the accordion completely.
      - label: boolean
      - label: 'false'
---
::

### MagicAccordionView

Wraps a single accordion entry and manages its open/closed state.

#### Props

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Required
rows:
  - items:
      - label: id
        description: Providing an id is optional. Neccessary for interacting with the view through `useMagicAccordion`.
      - label: MaybeRef<string>
        escape: true
      - label: 'false'
  - items:
      - label: asChild
        description: Prevent the component from rendering and pass all functionality to a child element.
      - label: boolean
      - label: 'false'
  - items:
      - label: active
        description: Force active state on mounted.
      - label: boolean
      - label: 'false'
---
::

#### Slot Props

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Description
rows:
  - items:
      - label: view-active
      - label: boolean
      - plaintext: true
        label: Whether the accordion view is currently open.
---
::

### MagicAccordionContent

The expandable content area of an accordion view.

#### Props

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Required
rows:
  - items:
      - label: asChild
        description: Prevent the inner component inside the `<transition>` from rendering and pass all functionality to a child element.
      - label: boolean
      - label: 'false'
  - items:
      - label: transition
        description: Override the [transition name](https://vuejs.org/guide/built-ins/transition#named-transitions).
      - label: string
      - label: 'false'
  - items:
      - label: animation.duration
        description: Override the component’s animation duration.
      - label: number
      - label: 'false'
  - items:
      - label: animation.easing
        description: Override the component’s animation easing.
      - label: function
        description: '(t: number) => number'
      - label: 'false'
---
::

#### CSS Variables

::docs-table
---
columns:
  - label: Variable
  - label: Default
rows:
  - items:
      - label: --magic-accordion-content-clip-path
      - label: inset(0)
---
::

#### Slot Props

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Description
rows:
  - items:
      - label: view-active
      - label: boolean
      - plaintext: true
        label: Whether the accordion view is currently open.
---
::

### MagicAccordionTrigger

Opens or closes the parent accordion view on click.

#### Props

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Required
rows:
  - items:
      - label: asChild
        description: Prevent the component from rendering and pass all functionality to a child element.
      - label: boolean
      - label: 'false'
  - items:
      - label: disabled
        description: Disable the trigger.
      - label: boolean
      - label: 'false'
  - items:
      - label: trigger
        description: Override the interactions that activate the trigger.
      - label: Interaction[]
        description: Array<'click' | 'mouseenter'>
      - label: 'false'
---
::

#### CSS Variables

::docs-table
---
columns:
  - label: Variable
  - label: Default
rows:
  - items:
      - label: --magic-accordion-trigger-cursor-disabled
      - label: not-allowed
---
::

#### Slot Props

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Description
rows:
  - items:
      - label: view-active
      - label: boolean
      - plaintext: true
        label: Whether the accordion view is currently open.
---
::

## Errors

::docs-table
---
columns:
  - label: Source
  - label: Error Code
  - label: Message
rows:
  - items:
      - label: MagicAccordionContent
      - label: missing_instance_id
      - plaintext: true
        label: MagicAccordionContent must be nested inside MagicAccordionProvider
  - items:
      - label: MagicAccordionContent
      - label: missing_view_id
      - plaintext: true
        label: MagicAccordionContent must be nested inside MagicAccordionView
  - items:
      - label: MagicAccordionTrigger
      - label: missing_instance_id
      - plaintext: true
        label: MagicAccordionTrigger must be nested inside MagicAccordionProvider
  - items:
      - label: MagicAccordionTrigger
      - label: missing_view_id
      - plaintext: true
        label: MagicAccordionTrigger must be nested inside MagicAccordionView or a viewId must be provided
  - items:
      - label: MagicAccordionView
      - label: missing_instance_id
      - plaintext: true
        label: MagicAccordionView must be nested inside MagicAccordionProvider
---
::