@nextcloud/vue 9.0.0-alpha.6 → 9.0.0-alpha.8

package/README.md

@@ -3,44 +3,71 @@
   - SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Vue components
+# @nextcloud/vue
 
-[![npm last version](https://img.shields.io/npm/v/@nextcloud/vue.svg?style=flat-square)](https://www.npmjs.com/package/@nextcloud/vue)
-[![Dependabot status](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg?longCache=true&style=flat-square&logo=dependabot)](https://dependabot.com)
+[![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)
 
-This repo contains the various Vue.js components that Nextcloud uses for its internal design and structure. It provides standardized UI elements for building Nextcloud app frontends with Vue.js.
+> 🖼️ UI Kit for building Nextcloud apps with Vue
 
-## Documentation
+- ✨ Standardized UI Components
+- 🛠️ Composables and frontend utilities
+- 🔗 [Reference providers](https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/reference.html) utilities
 
-A list of available components with examples to try out is available in the [documentation](https://nextcloud-vue-components.netlify.app).
+## 📄 Documentation
 
-The documentation is built from the latest development branch, for stable releases the documentation can be found matching the latest minor version:
+| Version        | Target                | Documentation                                         |
+|----------------|-----------------------|-------------------------------------------------------|
+| v9.x [main]    | Nextcloud 30+ (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 |
 
-- [master](https://nextcloud-vue-components.netlify.app).
-- [7.x.x](https://stable7--nextcloud-vue-components.netlify.app/)
-- [6.x.x](https://stable6--nextcloud-vue-components.netlify.app/)
-
-## Getting started
-
-### App example
-If you want to check a real live example of a nextcloud app that uses this library, you can head over to https://github.com/skjnldsv/vueexample/
-We will try to maintain this repository the best we can, but some example might be obsolete. Always check this [repository documentation](#documentation).
-
-### Install the library
+## 📦 Install
 
 ```bash
 npm i @nextcloud/vue@next
 ```
 
-### Usage
+## 🚀 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'
+```
 
-To use a component, just import it:
+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 { NcAppNavigation, NcActions, NcActionButton } from '@nextcloud/vue'
+import { NcButton, useHotKey } from '@nextcloud/vue'
 ```
 
-## Development setup
+## 🤝 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 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
 
 If you want to work on improving the components it’s best to run the latest code and link it to your local Nextcloud installation:
 
@@ -54,64 +81,36 @@ If you want to work on improving the components it’s best to run the latest co
     - In the repository of an app do `npm link @nextcloud/vue` (you need to re-link any time you do `npm ci` in the app)
 4. Then build the app with: `npm run build` (or watch for changes with `npm run watch`)
 
-## Translations
+### 🌐 Translations
 
-This library uses translated strings.
-When you edit/create a translated string, you need to run `npm run l10n:extract` to update the source files.
-Our awesome translation community will then be notified and a bot will sync those changes automatically.
+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).
 
-Nonetheless, it requires a bit of caution.
-When you implement a translated string, import the `translate` or `translatePlural` and add it in your methods like so:
 ```vue
+<script setup lang="ts">
+import { t } from '../../l10n.js'
+</script>
+
 <template>
 	<element>
 		{{ t('Choose') }}
 	</element>
 </template>
-
-<script>
-import { translate as t } from '@nextcloud/l10n'
-
-export default {
-	methods: {
-		t,
-	},
-}
-</script>
 ```
 
-Please note that using a translated string as an attribute will _NOT_ work.
-But it will work if it's within an element (like the example above)
-```vue
-<template>
-	<element :prop="t('This will not work')" />
-</template>
-```
-
-You will instead have to define the string in the data section and use the relevant variable reference.
-```vue
-<template>
-	<element :prop="chooseProp" />
-</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.
 
-<script>
-export default {
-	data() {
-		return {
-			chooseProp: t('Choose'),
-		},
-	}
-}
-</script>
+```sh
+npm run l10n:extract
 ```
 
-## Styleguide
+### 🐸 Styleguidist
 
 When developing new components or extending components, make sure to also have some bits of related documentation like examples, where applicable.
 To test components and the documentation in that context, you can run `npm run styleguide` to run a local server that serves the style guide
 with all the components.
 
-### Using vue-devtools in Firefox
+#### Using vue-devtools in Firefox
 
 If you want to use [vue-devtools](https://github.com/vuejs/vue-devtools) in Firefox, you need to:
 
@@ -137,16 +136,20 @@ index 0e3a6a705d..416b8b0fb9 100644
         /** @var array Domains from which scripts can get loaded */
 ```
 
-## Releasing a new version
+## 📤 Releasing a new version
 
-- Pull the latest changes from `master` or `stableX`
+- 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. use the version as tag AND title (e.g `v4.0.1`)
-  2. add the changelog content as description (https://github.com/nextcloud-libraries/nextcloud-vue/releases)
+  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

package/dist/assets/{NcActionButton-BLoWchS5.css → NcActionButton-d8aZCq9u.css}

@@ -9,34 +9,37 @@
 /*
 * Ensure proper alignment of the vue material icons
 */
-.material-design-icon[data-v-8e10d6ef] {
+.material-design-icon[data-v-5482345d] {
   display: flex;
   align-self: center;
   justify-self: center;
   align-items: center;
   justify-content: center;
 }
+
 /**
  * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-li.action.active[data-v-8e10d6ef] {
-  background-color: var(--color-background-hover);
+li.action[data-v-5482345d]:hover, li.action.active[data-v-5482345d] {
   border-radius: 6px;
   padding: 0;
 }
-.action--disabled[data-v-8e10d6ef] {
+li.action[data-v-5482345d]:hover {
+  background-color: var(--color-background-hover);
+}
+.action--disabled[data-v-5482345d] {
   pointer-events: none;
   opacity: 0.5;
 }
-.action--disabled[data-v-8e10d6ef]:hover, .action--disabled[data-v-8e10d6ef]:focus {
+.action--disabled[data-v-5482345d]:hover, .action--disabled[data-v-5482345d]:focus {
   cursor: default;
   opacity: 0.5;
 }
-.action--disabled[data-v-8e10d6ef] * {
+.action--disabled[data-v-5482345d] * {
   opacity: 1 !important;
 }
-.action-button[data-v-8e10d6ef] {
+.action-button[data-v-5482345d] {
   display: flex;
   align-items: flex-start;
   width: 100%;
@@ -56,11 +59,11 @@ li.action.active[data-v-8e10d6ef] {
   font-size: var(--default-font-size);
   line-height: var(--default-clickable-area);
 }
-.action-button > span[data-v-8e10d6ef] {
+.action-button > span[data-v-5482345d] {
   cursor: pointer;
   white-space: nowrap;
 }
-.action-button__icon[data-v-8e10d6ef] {
+.action-button__icon[data-v-5482345d] {
   width: var(--default-clickable-area);
   height: var(--default-clickable-area);
   opacity: 1;
@@ -68,15 +71,15 @@ li.action.active[data-v-8e10d6ef] {
   background-size: 16px;
   background-repeat: no-repeat;
 }
-.action-button[data-v-8e10d6ef] .material-design-icon {
+.action-button[data-v-5482345d] .material-design-icon {
   width: var(--default-clickable-area);
   height: var(--default-clickable-area);
   opacity: 1;
 }
-.action-button[data-v-8e10d6ef] .material-design-icon .material-design-icon__svg {
+.action-button[data-v-5482345d] .material-design-icon .material-design-icon__svg {
   vertical-align: middle;
 }
-.action-button__longtext-wrapper[data-v-8e10d6ef], .action-button__longtext[data-v-8e10d6ef] {
+.action-button__longtext-wrapper[data-v-5482345d], .action-button__longtext[data-v-5482345d] {
   max-width: 220px;
   line-height: 1.6em;
   padding: calc((var(--default-clickable-area) - 1.6em) / 2) 0;
@@ -85,11 +88,11 @@ li.action.active[data-v-8e10d6ef] {
   overflow: hidden;
   text-overflow: ellipsis;
 }
-.action-button__longtext[data-v-8e10d6ef] {
+.action-button__longtext[data-v-5482345d] {
   cursor: pointer;
   white-space: pre-wrap !important;
 }
-.action-button__name[data-v-8e10d6ef] {
+.action-button__name[data-v-5482345d] {
   font-weight: bold;
   text-overflow: ellipsis;
   overflow: hidden;
@@ -97,9 +100,9 @@ li.action.active[data-v-8e10d6ef] {
   max-width: 100%;
   display: inline-block;
 }
-.action-button__menu-icon[data-v-8e10d6ef] {
+.action-button__menu-icon[data-v-5482345d] {
   margin-inline: auto calc((var(--default-clickable-area) - 16px) / 2 * -1);
 }
-.action-button__pressed-icon[data-v-8e10d6ef] {
+.action-button__pressed-icon[data-v-5482345d] {
   margin-inline: auto calc((var(--default-clickable-area) - 16px) / 2 * -1);
 }

package/dist/assets/{NcActionCaption-B7FZTc3Y.css → NcActionCaption-DnG2OyWa.css}

@@ -9,14 +9,14 @@
 /*
 * Ensure proper alignment of the vue material icons
 */
-.material-design-icon[data-v-b9668c9e] {
+.material-design-icon[data-v-1009e96c] {
   display: flex;
   align-self: center;
   justify-self: center;
   align-items: center;
   justify-content: center;
 }
-.app-navigation-caption[data-v-b9668c9e] {
+.app-navigation-caption[data-v-1009e96c] {
   color: var(--color-text-maxcontrast);
   line-height: var(--default-clickable-area);
   white-space: nowrap;
@@ -24,8 +24,8 @@
   box-shadow: none !important;
   user-select: none;
   pointer-events: none;
-  margin-left: 12px;
-  padding-right: 14px;
+  margin-inline-start: 12px;
+  padding-inline-end: 14px;
   height: var(--default-clickable-area);
   display: flex;
   align-items: center;

package/dist/assets/{NcActionCheckbox-CoQEhC0c.css → NcActionCheckbox-tMIOGziy.css}

@@ -9,34 +9,37 @@
 /*
 * Ensure proper alignment of the vue material icons
 */
-.material-design-icon[data-v-259d078c] {
+.material-design-icon[data-v-735edb01] {
   display: flex;
   align-self: center;
   justify-self: center;
   align-items: center;
   justify-content: center;
 }
+
 /**
  * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-li.action.active[data-v-259d078c] {
-  background-color: var(--color-background-hover);
+li.action[data-v-735edb01]:hover, li.action.active[data-v-735edb01] {
   border-radius: 6px;
   padding: 0;
 }
-.action--disabled[data-v-259d078c] {
+li.action[data-v-735edb01]:hover {
+  background-color: var(--color-background-hover);
+}
+.action--disabled[data-v-735edb01] {
   pointer-events: none;
   opacity: 0.5;
 }
-.action--disabled[data-v-259d078c]:hover, .action--disabled[data-v-259d078c]:focus {
+.action--disabled[data-v-735edb01]:hover, .action--disabled[data-v-735edb01]:focus {
   cursor: default;
   opacity: 0.5;
 }
-.action--disabled[data-v-259d078c] * {
+.action--disabled[data-v-735edb01] * {
   opacity: 1 !important;
 }
-.action-checkbox[data-v-259d078c] {
+.action-checkbox[data-v-735edb01] {
   display: flex;
   align-items: flex-start;
   width: 100%;
@@ -54,26 +57,24 @@ li.action.active[data-v-259d078c] {
   line-height: var(--default-clickable-area);
   /* checkbox/radio fixes */
 }
-.action-checkbox__checkbox[data-v-259d078c] {
+.action-checkbox__checkbox[data-v-735edb01] {
   position: absolute;
-  top: auto;
-  left: -10000px;
-  overflow: hidden;
-  width: 1px;
-  height: 1px;
+  inset-inline-start: 0 !important;
+  z-index: -1;
+  opacity: 0;
 }
-.action-checkbox__label[data-v-259d078c] {
+.action-checkbox__label[data-v-735edb01] {
   display: flex;
   align-items: center;
   width: 100%;
   padding: 0 !important;
   padding-inline-end: calc((var(--default-clickable-area) - 16px) / 2) !important;
 }
-.action-checkbox__label[data-v-259d078c]::before {
+.action-checkbox__label[data-v-735edb01]::before {
   margin-block: 0 !important;
   margin-inline: calc((var(--default-clickable-area) - 14px) / 2) !important;
 }
-.action-checkbox--disabled[data-v-259d078c],
-.action-checkbox--disabled .action-checkbox__label[data-v-259d078c] {
+.action-checkbox--disabled[data-v-735edb01],
+.action-checkbox--disabled .action-checkbox__label[data-v-735edb01] {
   cursor: pointer;
 }