[next] chore(directives): add docs

docs/directives.md

@@ -1,63 +1,33 @@
-## Tooltip
-
 <!--
- - SPDX-FileCopyrightText: 2020-2024 Nextcloud GmbH and Nextcloud contributors
+ - SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors
  - SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-```js static
-import { Tooltip } from '@nextcloud/vue'
+### Registration
 
-Vue.directive('tooltip', Tooltip)
-```
+To use any directive, import and register it locally, for example:
 
-The tooltip directive is based on v-tooltip. For a full feature list see the projects [README](https://github.com/Akryum/v-tooltip/blob/master/README.md#directive)
-
-In the template, use the `v-tooltip` directive:
+```js static
+import Tooltip from '@nextcloud/vue/dist/Directives/Tooltip.js'
 
-```vue
-<a v-tooltip="'You have new messages.'">Hover me</a>
+export default {
+ directives: {
+ Tooltip,
+ },
+}
 ```
+or in `<script setup>`:
 
-Of course, you can use a reactive property:
-
-```vue
- <template>
- <a v-tooltip="tooltipContent">Hover me</a>
- </template>
- <script>
- export default {
- computed: {
- tooltipContent: () => 'You have new messages.'
- }
- }
- </script>
+```js static
+import vTooltip from '@nextcloud/vue/dist/Directives/Tooltip.js'
 ```
 
-You can specify the tooltip position as a modifier:
+You can also register any directive globally. But it is not recommended.
 
-```vue
-<a v-tooltip.bottom="'You have new messages.'">Hover me</a>
-```
-The available positions are:
- - `'auto'`
- - `'auto-start'`
- - `'auto-end'`
- - `'top'`
- - `'top-start'`
- - `'top-end'`
- - `'right'`
- - `'right-start'`
- - `'right-end'`
- - `'bottom'`
- - `'bottom-start'`
- - `'bottom-end'`
- - `'left'`
- - `'left-start'`
- - `'left-end'`
-
-```vue
-<button v-tooltip="{content: 'I\'m a tooltip', show: true, placement: 'right'}">
- I'm a button with a tooltip
-</button>
+```js static
+import Tooltip from '@nextcloud/vue/dist/Directives/Tooltip.js'
+
+const app = createApp(App)
+ .directive('Tooltip', Tooltip)
+ .mount('#content-vue')
 ```

docs/directives/focus.md

@@ -0,0 +1,14 @@
+<!--
+ - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+```js static
+import Focus from '@nextcloud/vue/dist/Directives/Focus.js'
+```
+
+Focus an element when it is mounted to DOM.
+
+```vue
+<input v-focus placeholder="I'm focused" />
+```

docs/directives/linkify.md

@@ -0,0 +1,18 @@
+<!--
+ - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+```js static
+import Linkify from '@nextcloud/vue/dist/Directives/Linkify.js'
+```
+
+Automatically make links in rendered text clickable.
+
+To use the directive, bind object with `linkify === true` and the text in the `text` property:
+
+```vue
+<template>
+ <p v-linkify="{ linkify: true, text: 'Read more about Nextcloud on https://nextcloud.com' }"></p>
+</template>
+```

docs/directives/tooltip.md

@@ -0,0 +1,55 @@
+<!--
+ - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+```js static
+import Tooltip from '@nextcloud/vue/dist/Directives/Tooltip.js'
+```
+
+Tooltip directive based on [v-tooltip](https://github.com/Akryum/v-tooltip).
+
+Note: it's preferred to use [native HTML title attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title) instead for accessibility.
+
+## Usage
+
+In a component register the directive and use the `v-tooltip` in the template with static or dynamic value:
+
+```vue
+<template>
+ <button v-tooltip="'A tooltip text'">Hover me</button>
+</template>
+```
+
+You can specify the tooltip position as a modifier:
+
+```vue
+<button v-tooltip.bottom="'You have new messages.'">Hover me</button>
+```
+
+The available positions are:
+ - `'auto'`
+ - `'auto-start'`
+ - `'auto-end'`
+ - `'top'`
+ - `'top-start'`
+ - `'top-end'`
+ - `'right'`
+ - `'right-start'`
+ - `'right-end'`
+ - `'bottom'`
+ - `'bottom-start'`
+ - `'bottom-end'`
+ - `'left'`
+ - `'left-start'`
+ - `'left-end'`
+
+You can also specify more options. 
+
+```vue
+<button v-tooltip="{ content: 'I\'m a tooltip', show: true, placement: 'right' }">
+ I'm a button with a tooltip
+</button>
+```
+
+For a full documentation see: [v-tooltip/README](https://github.com/Akryum/v-tooltip/blob/master/README.md#directive).

styleguide.config.cjs

@@ -89,6 +89,21 @@ module.exports = async () => {
  {
  name: 'Directives',
  content: 'docs/directives.md',
+ sectionDepth: 1,
+ sections: [
+ {
+ name: 'Focus',
+ content: 'docs/directives/focus.md',
+ },
+ {
+ name: 'Linkify',
+ content: 'docs/directives/linkify.md',
+ },
+ {
+ name: 'Tooltip',
+ content: 'docs/directives/tooltip.md',
+ },
+ ],
  },
  {
  name: 'Components',

styleguide/preview.js

@@ -3,11 +3,12 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-import { Tooltip } from '../src/directives/index.ts'
+import { Tooltip, Focus, Linkify } from '../src/directives/index.ts'
 
 // The export here MUST be default or module.export
 // this is what is imported by the styleguide
 export default (app) => {
- app.directive('tooltip', Tooltip)
+ app.directive('focus', Focus)
+ app.directive('linkify', Linkify)
+ app.directive('tooltip', Tooltip)
 }
-