@nextcloud/vue/README.md

Nextcloud vue components

<!--
  - SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors
  - SPDX-License-Identifier: AGPL-3.0-or-later
-->

# @nextcloud/vue

[![npm last version](https://img.shields.io/npm/v/@nextcloud/vue.svg?style=flat)](https://www.npmjs.com/package/@nextcloud/vue)
[![Dependabot status](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg?longCache=true&style=flat&logo=dependabot)](https://dependabot.com)

> 🖼️ UI Kit for building Nextcloud apps with Vue

- ✨ Standardized UI Components
- 🛠️ Composables and frontend utilities
- 🔗 [Reference providers](https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/reference.html) utilities

## 📄 Documentation

| Version        | Target                | Documentation                                         |
|----------------|-----------------------|-------------------------------------------------------|
| v9.x [main]    | Nextcloud 31+ (Vue 3) | https://nextcloud-vue-components.netlify.app          |
| v8.x [stable8] | Nextcloud 28+ (Vue 2) | https://stable8--nextcloud-vue-components.netlify.app |
| v7.x [stable7] | Nextcloud 25 - 27     | https://stable7--nextcloud-vue-components.netlify.app |
| v6.x [stable6] | Nextcloud 24 - 25     | https://stable6--nextcloud-vue-components.netlify.app |

## 📦 Install

```bash
npm i @nextcloud/vue@next
```

## 🚀 Usage

Import corresponding components and other modules on use. Check the documentation for more details.

```js
import NcButton from '@nextcloud/vue/components/NcButton'
import { useHotKey } from '@nextcloud/vue/composables/useHotKey'
```

Import from a single root is available as well. Use with caution: this might lead to slower build time and larger bundles in some cases.

```js
import { NcButton, useHotKey } from '@nextcloud/vue'
```

## 🤝 Contributing

### 📜 How to contribute

1. It's always good to check/create an issue first and discuss the problem or feature you want to work on
2. Fork the repository and create a new branch
3. Make the changes
4. Check the change in Vue-Styleguidist and/or Nextcloud apps
   - Do not forget to `lint` and `test` your changes
   - If possible, add tests and documentation for your changes
5. Commit and push your changes, create a Pull Request
   - Make sure to follow the [Conventional Commits](https://www.conventionalcommits.org) in commit messages, and PR titles, for example:\
     `fix(NcButton): correct layout on Safari`
   - Make sure to follow the **Pull Request template**
   - Sign-off you commits for the [Developer Certificate of Origin (DCO)](https://developercertificate.org/)
6. Get your PR reviewed
   - If you don't receive a feedback in a week, feel free to mention the maintainers, for example, last developers worked on the module
7. Get your PR merged 

Please read the [Code of Conduct](https://nextcloud.com/community/code-of-conduct/). This document offers some guidance to ensure Nextcloud participants can cooperate effectively in a positive and inspiring atmosphere and to explain how together we can strengthen and support each other.

More information on how to contribute: [https://nextcloud.com/contribute/](https://nextcloud.com/contribute/)

### 🧑‍💻 Development setup

First, install dependencies with `npm`:

```sh
npm ci
```

#### 🐸 Development with Styleguidist

The simplest way to develop and debug `@nextcloud/vue` is to use our live documentation via [`vue-styleguidist`](https://vue-styleguidist.github.io). 

Run the development server with component documentation and playground:
```sh
npm run styleguide
```

You can also test if the design still works with a legacy Nextcloud version by setting `NEXTCLOUD_LEGACY` ENV variable.

```sh
NEXTCLOUD_LEGACY=y npm run styleguide
```

#### Unit tests

```sh
npm run test
```

#### Component tests


> [!TIP]
> We use Playwright for component tests.
>
> If you don't meet the [system requirements](https://playwright.dev/docs/intro#system-requirements),
> try the provided [Development Container](.devcontainer/devcontainer.json).
>
> It also matches the CI environment, so snapshots taken with it are less likely to break in CI.

```sh
npm run test:component # or test:component:gui
```

#### ☁️ Development with Nextcloud apps

To test or debug `@nextcloud/vue` in Nextcloud app you need to [pack](https://docs.npmjs.com/cli/v11/commands/npm-pack) the library and **install** it in the app.

1. In `nextcloud-vue`:
   1. Build the library with:
      - `npm run dev` for development build
      - `npm run build` for production build
   2. Pack with `npm pack`
2. In the Nextcloud app:
   1. Install the packed file by path to the file, for example:
      ```sh
      npm install --no-save ../../../nextcloud-vue-9.3.1.tgz
      ```
   2. Rebuild the app or run it in `watch` mode
   3. To remove the linked package, reinstall dependencies with `npm ci`
3. Repeat every time you do a change in `@nextcloud/vue`
4. Do not commit the created `.tgz` file

> [!WARNING]
> Do not use `npm link`
>
> While it is a simple and popular way to connect a local npm package to another package, it doesn't have proper dependency resolution which leads to issues. Adding a package via `npm pack` does exactly the same as installing a published package.

### 🌐 Translations

Use `t` and `n` functions from `src/l10n.js` to display translated strings. They follow `gettext` and `ngettext` interface from [`@nextcloud/l10n/gettext`](https://nextcloud-libraries.github.io/nextcloud-l10n/modules/_nextcloud_l10n_gettext.html).

```vue
<script setup lang="ts">
import { t } from '../../l10n.js'
</script>

<template>
	<element>
		{{ t('Choose') }}
	</element>
</template>
```

When you edit/create a translated string, you need to update the l10n files.
Our awesome translation community will then be notified and a bot will sync translations automatically.

```sh
npm run l10n:extract
```

## 📤 Releasing a new version

- Pull the latest changes from `main` or `stableX`
- Checkout a new branch with the tag name (e.g `v4.0.1`): `git checkout -b v<version>`
- Run `npm version patch --no-git-tag-version` (`npm version minor --no-git-tag-version` if minor).
  This will return a new version name, make sure it matches what you expect
- Generate the changelog content from the [release](https://github.com/nextcloud-libraries/nextcloud-vue/releases) page.
  Create a draft release, select the previous tag, click `generate` then paste the content to the `CHANGELOG.md` file
  1. adjust the links to the merged pull requests and authors so that the changelog also works outside of GitHub
     by running `npm run prerelease:format-changelog`.
     This will apply this regex: `by @([^ ]+) in ((https://github.com/)nextcloud-libraries/nextcloud-vue/pull/(\d+))`
     Which this as the replacement: `[\#$4]($2) \([$1]($3$1)\)`
  2. use the the version as tag AND title (e.g `v4.0.1`)
  3. add the changelog content as description (https://github.com/nextcloud-libraries/nextcloud-vue/releases)
- Commit, push and create PR
- Get your PR reviewed and merged
- Create a milestone with the follow-up version at https://github.com/nextcloud-libraries/nextcloud-vue/milestones
- Move all open tickets and PRs to the follow-up
- Close the milestone of the version you release
- Publish the previously drafted release on GitHub
  ![image](https://user-images.githubusercontent.com/14975046/124442568-2a952500-dd7d-11eb-82a2-402f9170231a.png)

<a href="https://www.netlify.com">
  <img src="https://www.netlify.com/img/global/badges/netlify-dark.svg"/>
</a>

### Releasing a pre-release

A pre-release can be built in the same way as described above, however it requires manual adjustments to avoid that npm ships the pre-release to all users:

1. Retag latest to the last stable release

    npm dist-tag add @nextcloud/vue@5.4.0 latest

2. Tag the new pre-release as next

    npm dist-tag add @nextcloud/vue@6.0.0-beta.2 next