npm package: @aautcq/aautcq-ui
Description: VueJS components library
Author: Adrien Autricque
Latest version: 0.1.1

# AautcqUI

_AautcqUI_ is a Vue 3 components library.

## Prerequisites

You will need the following things properly installed on your computer.

- [Node.js](http://nodejs.org/) (with NPM)

## Install & config

### With NPM

```bash
$ npm i @aautcq/aautcq-ui
```

### Global components registration

In your Vue project, you can either register all components globally

```js
import App from '@/App.vue';
import { createApp } from 'vue';
import createAautcqUi from '@aautcq/aautcq-ui';

const app = createApp(App);

const AautcqUI = createAautcqUi({
  // options object
});

app.use(AautcqUI).mount('#app');
```

### On the fly import

You can also import components one at a time

```vue
<template>
  <aa-button>Hello world</aa-button>
</template>

<script setup lang="ts">
import { AaButton } from '@aautcq/aautcq-ui';
</script>
```

**Important:** if you choose this method, you must manually initialize the Filestack service using `initFilestack` (documentation below).

### Options

The `createAautcqUi` method takes an options object as parameter. Below are the keys of this object, which can be used to customize you usage of _AautcqUI_.

- **`components`** - `Array<String>`

The array of component names to be globally registered. If not set, all components will be registered.

- **`locale`** - `String`

Locale to use for component wordings. Available locales are `'fr'` and `'en'`.

### Composables

- **Focus trap**

This composable creates a focus trap: the focus cannot go outside of the specified HTML element.

```vue
<template>
  <div>
    <div ref="trapRef">Everything in here can be focused!</div>
    <div>Cannot be focused</div>
  </div>
</template>

<script setup lang="ts">
import { useFocusTrap } from '@/composables/useFocusTrap';

const { trapRef } = useFocusTrap();
</script>
```

### Exposed methods

- **Modals**

To toggle modals built using the `Modal.vue` component, you can use the `toggle` exposed method.

```vue
<template>
  <aa-modal ref="myModal" name="my-modal">I am a modal!</aa-modal>

  <button type="button" @click="myModal.toggle()">Toggle modal</button>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const myModal = ref(null);
</script>
```

Alternatively, you can use the global `toggleModal` method.

```vue
<template>
  <aa-modal name="my-modal">I am a modal!</aa-modal>

  <button type="button" @click="toggleModal('my-modal')">Toggle modal</button>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { toggleModal } from '@aautcq/aautcq-ui';
</script>
```

- **Locale**

If you chose to import components on the fly (see above for more details), you might need to manually initialize the locale using the `setLocale` method.

In your `main.js` file:

```js
import { setLocale } from '@aautcq/aautcq-ui';

const locale = 'fr';
setLocale(locale);
```

The accepted locale is the same as the `options.locale` string used in the `createAautcqUi` method.

## Build the library

Kindly ask another developper for the content of the `.env` file, then run

```bash
$ npm run build
```

## Run the documentation locally

To run the documentation locally, run

```bash
$ npm run docs:dev
```

## Further Reading / Useful Links

- [Vue 3](https://vuejs.org/guide/introduction.html)
- [Tailwind](https://tailwindcss.com/docs/installation)
- [Sass](https://sass-lang.com/documentation)
- [Histoire](https://histoire.dev/guide/vue3/getting-started.html)
- [TypeScript](https://www.typescriptlang.org/docs/handbook/)
- [Vite](https://vitejs.dev/guide/)