chore(functions): add docs

docs/functions/a11y.md

@@ -0,0 +1,16 @@
+```js static
+import { isA11yActivation } from '@nextcloud/vue/dist/Functions/a11y.js'
+```
+
+## Definitions
+
+```ts static
+/**
+ * Return true if the DOM event is an accessible mouse or keyboard element activation, false otherwise
+ *
+ * @param {Event} event DOM event
+ *
+ * @return {boolean}
+ */
+declare function isA11yActivation(event: Event): boolean
+```

docs/functions/emoji.md

@@ -0,0 +1,122 @@
+```ts static
+import {
+    EmojiSkinTone,
+    emojiSearch,
+    emojiAddRecent,
+    getCurrentSkinTone,
+    setCurrentSkinTone,
+} from '@nextcloud/vue/dist/Functions/emoji.js'
+```
+
+## Definitions
+
+```ts static
+/**
+ * Skin tones supported by Unicode Emojis (Fitzpatrick scale)
+ * The numeric values align with `emoji-mart-vue`
+ */
+enum EmojiSkinTone {}
+
+/**
+ * Get the list of emojis by search filter or the list of frequently used emojis
+ *
+ * @param query Emoji search filter string; if no string or empty string is given, the list of frequently used emojis is returned
+ * @param maxResults Maximum of returned emojis
+ * @return list of found emojis in the same format as the emoji-mart-vue-fast's EmojiIndex
+ */
+declare function emojiSearch(query: string, maxResults: number = 10): object[]
+
+/**
+ * Add emoji to the list of recent emojis.
+ * This list can be got from emojiSearch function and it is used in NcEmojiPicker.
+ *
+ * @param emojiData object with `id` property
+ * @param emojiData.id the emoji ID from emoji index
+ */
+declare function emojiAddRecent(emojiData: { id: string }): void
+
+/**
+ * Get the current skin tone index used for emojis
+ * @return The skin tone
+ */
+declare function getCurrentSkinTone(): EmojiSkinTone
+
+/**
+ * Set the current active skin tone for emojis
+ *
+ * @param skinTone Skin tone
+ */
+declare function setCurrentSkinTone(skinTone: EmojiSkinTone): void
+```
+
+## Usage
+
+```vue
+<template>
+    <div>
+        <NcEmojiPicker :key="selectedTone.value" @select="handleSelect">
+            <NcButton>Open Emoji Picker</NcButton>
+        </NcEmojiPicker>
+
+        <hr />
+
+        <NcSelect v-model="selectedTone" :options="tones" input-label="Current Skin Tone" />
+
+        <hr />
+
+        <p>
+            <code>emojiSearch('', 5).map((emoji) => emoji.native)</code>
+            <br />
+            {{ recent }}
+        </p>
+
+        <hr />
+
+        <NcButton @click="handleAddToRecent">Add 💙 to recent</NcButton>
+    </div>
+</template>
+
+<script>
+export default {
+    data() {
+        const initialSkinTone = getCurrentSkinTone()
+        return {
+            recent: [],
+            selectedTone: {
+                label: EmojiSkinTone[initialSkinTone],
+                value: initialSkinTone,
+            },
+            tones: Object.entries(EmojiSkinTone)
+                .filter(([label, value]) => typeof value === 'number')
+                .map(([label, value]) => ({ label, value })),
+        }
+    },
+
+    watch: {
+        selectedTone({ label, value }) {
+            setCurrentSkinTone(value)
+            this.manuallyUpdateRecent()
+        },
+    },
+
+    created() {
+        this.manuallyUpdateRecent()
+    },
+
+    methods: {
+        manuallyUpdateRecent() {
+            this.recent = emojiSearch('', 5).map((emojiData) => emojiData.native)
+        },
+
+        handleAddToRecent() {
+            emojiAddRecent({ id: 'blue_heart' })
+            this.manuallyUpdateRecent()
+        },
+
+        handleSelect() {
+            this.manuallyUpdateRecent()
+        },
+    },
+}
+</script>
+```

docs/functions/reference.md

@@ -0,0 +1 @@
+

docs/functions/usernameToColor.md

@@ -0,0 +1,65 @@
+```js static
+import usernameToColor from '@nextcloud/vue/dist/Functions/usernameToColor.js'
+```
+
+## Definition
+
+```ts static
+/**
+ * Generate a color from a username
+ * Originally taken from https://github.com/nextcloud/server/blob/master/core/js/placeholder.js
+ *
+ * @param {string} username Display name or user id to generate from
+ * @return {{ r: number, g: number, b: number }} the RGB color
+ */
+declare function usernameToColor(username: string): { r: number, g: number, b: number }
+```
+
+## Usage
+
+```vue
+<template>
+    <div>
+        <NcTextField label="username" :value.sync="username" />
+        <hr />
+        <p class="color" :style="{ backgroundColor: color }">
+            <span class="color-text">{{ color }}</span>
+        </p>
+    </div>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            username: 'alice',
+        }
+    },
+
+    computed: {
+        color() {
+            const { r, g, b } = usernameToColor(this.username)
+            return `rgb(${r}, ${g}, ${b})`
+        },
+    },
+}
+</script>
+
+<style scoped>
+.color {
+    border-radius: var(--border-radius-large);
+    width: 100%;
+    padding: var(--default-grid-baseline);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.color-text {
+    border-radius: var(--border-radius-large);
+    background-color: white;
+    color: black;
+    padding: var(--default-grid-baseline);
+}
+</style>
+```

src/functions/emoji/emoji.ts

@@ -45,11 +45,13 @@ export enum EmojiSkinTone {
 }
 
 /**
- * @param {string} query Emoji search string
- * @param {number} maxResults Maximum of returned emojis
- * @return {Array} list of found emojis
+ * Get the list of emojis by search filter or the list of frequently used emojis
+ *
+ * @param query Emoji search filter string; if no string or empty string is given, the list of frequently used emojis is returned
+ * @param maxResults Maximum of returned emojis
+ * @return {object[]} list of found emojis in the same format as the emoji-mart-vue-fast's EmojiIndex
  */
-export const emojiSearch = (query: string, maxResults: number = 10) => {
+export function emojiSearch(query: string, maxResults: number = 10): object[] {
 	// If this is the first call of function - initialize EmojiIndex
 	if (!emojiIndex) {
 		emojiIndex = new EmojiIndex(data)
@@ -69,25 +71,34 @@ export const emojiSearch = (query: string, maxResults: number = 10) => {
 	return results.map((emoji) => emoji.getSkin(currentSkinTone))
 }
 
-export const emojiAddRecent = function(id) {
-	frequently.add(id)
+/**
+ * Add emoji to the list of recent emojis.
+ * This list can be got from emojiSearch function and it is used in NcEmojiPicker.
+ *
+ * @param emojiData object with `id` property
+ * @param emojiData.id the emoji ID from emoji index
+ */
+export function emojiAddRecent(emojiData: { id: string }): void {
+	frequently.add(emojiData)
 }
 
 /**
  * Get the current skin tone index used for emojis
+ *
  * @return {EmojiSkinTone} The skin tone
  */
-export const getCurrentSkinTone = () => {
+export function getCurrentSkinTone(): EmojiSkinTone {
 	const skinTone = Number.parseInt(storage.getItem('NcEmojiPicker::currentSkinTone') ?? '1')
 	// Clamp skinTone to valid ranges
 	return Math.min(Math.max(skinTone, EmojiSkinTone.Neutral), EmojiSkinTone.Dark)
 }
 
 /**
  * Set the current active skin tone for emojis
- * @param {EmojiSkinTone} skinTone Skin tone
+ *
+ * @param skinTone Skin tone
  */
-export const setCurrentSkinTone = (skinTone: EmojiSkinTone) => {
+export function setCurrentSkinTone(skinTone: EmojiSkinTone): void {
 	// Clamp skinTone to valid ranges
 	skinTone = Math.min(Math.max(skinTone, EmojiSkinTone.Neutral), EmojiSkinTone.Dark)
 	storage.setItem('NcEmojiPicker::currentSkinTone', skinTone.toString())

src/functions/usernameToColor/usernameToColor.js

@@ -24,10 +24,11 @@ import { GenColors } from '../../utils/GenColors.js'
 import md5 from 'md5'
 
 /**
+ * Generate a color from a username
  * Originally taken from https://github.com/nextcloud/server/blob/master/core/js/placeholder.js
  *
  * @param {string} username Display name or user id to generate from
- * @return {object} the rgb colors as {r:255, g:255, b:255}
+ * @return {{ r: number, g: number, b: number }} the RGB color
  */
 const usernameToColor = function(username) {
 	// Normalize hash

styleguide.config.js

@@ -88,6 +88,33 @@ module.exports = async () => {
 				name: 'Directives',
 				content: 'docs/directives.md',
 			},
+			{
+				name: 'Functions',
+				content: 'docs/functions.md',
+				sectionDepth: 1,
+				sections: [
+					{
+						name: 'a11y',
+						content: 'docs/functions/a11y.md',
+					},
+					{
+						name: 'emoji',
+						content: 'docs/functions/emoji.md',
+					},
+					{
+						name: 'usernameToColor',
+						content: 'docs/functions/usernameToColor.md',
+					},
+					{
+						name: 'reference',
+						content: 'docs/functions/reference.md',
+					},
+					{
+						name: 'registerReference',
+						content: 'docs/functions/registerReference.md',
+					},
+				],
+			},
 			{
 				name: 'Components',
 				content: 'docs/components.md',

styleguide/global.requires.js

@@ -1,6 +1,10 @@
 /* eslint-disable-next-line */
 import 'core-js/stable'
 import Vue from 'vue'
+import { isA11yActivation } from '../src/functions/a11y/index.ts'
+import { EmojiSkinTone, emojiSearch, emojiAddRecent, getCurrentSkinTone, setCurrentSkinTone } from '../src/functions/emoji/index.ts'
+import usernameToColor from '../src/functions/usernameToColor/index.js'
+
 import VTooltip from './../src/directives/Tooltip/index.js'
 
 import axios from '@nextcloud/axios'
@@ -146,4 +150,13 @@ window.NextcloudVueDocs = {
 	tags: '<?xml version="1.0"?><d:multistatus xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns"><d:response><d:href>/remote.php/dav/systemtags/</d:href><d:propstat><d:prop><oc:id/><oc:display-name/><oc:user-visible/><oc:user-assignable/><oc:can-assign/></d:prop><d:status>HTTP/1.1 404 Not Found</d:status></d:propstat></d:response><d:response><d:href>/remote.php/dav/systemtags/7</d:href><d:propstat><d:prop><oc:id>7</oc:id><oc:display-name>tag1</oc:display-name><oc:user-visible>true</oc:user-visible><oc:user-assignable>true</oc:user-assignable><oc:can-assign>true</oc:can-assign></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response><d:response><d:href>/remote.php/dav/systemtags/2</d:href><d:propstat><d:prop><oc:id>2</oc:id><oc:display-name>tag2</oc:display-name><oc:user-visible>false</oc:user-visible><oc:user-assignable>true</oc:user-assignable><oc:can-assign>true</oc:can-assign></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response><d:response><d:href>/remote.php/dav/systemtags/3</d:href><d:propstat><d:prop><oc:id>3</oc:id><oc:display-name>tag3</oc:display-name><oc:user-visible>true</oc:user-visible><oc:user-assignable>true</oc:user-assignable><oc:can-assign>true</oc:can-assign></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response><d:response><d:href>/remote.php/dav/systemtags/4</d:href><d:propstat><d:prop><oc:id>4</oc:id><oc:display-name>important</oc:display-name><oc:user-visible>true</oc:user-visible><oc:user-assignable>true</oc:user-assignable><oc:can-assign>true</oc:can-assign></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response><d:response><d:href>/remote.php/dav/systemtags/1</d:href><d:propstat><d:prop><oc:id>1</oc:id><oc:display-name>secret</oc:display-name><oc:user-visible>true</oc:user-visible><oc:user-assignable>false</oc:user-assignable><oc:can-assign>true</oc:can-assign></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response><d:response><d:href>/remote.php/dav/systemtags/5</d:href><d:propstat><d:prop><oc:id>5</oc:id><oc:display-name>test</oc:display-name><oc:user-visible>true</oc:user-visible><oc:user-assignable>false</oc:user-assignable><oc:can-assign>true</oc:can-assign></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response><d:response><d:href>/remote.php/dav/systemtags/6</d:href><d:propstat><d:prop><oc:id>6</oc:id><oc:display-name>test2</oc:display-name><oc:user-visible>false</oc:user-visible><oc:user-assignable>false</oc:user-assignable><oc:can-assign>true</oc:can-assign></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response></d:multistatus>',
 }
 
+// Exported Functions
+window.isA11yActivation = isA11yActivation
+window.EmojiSkinTone = EmojiSkinTone
+window.emojiSearch = emojiSearch
+window.emojiAddRecent = emojiAddRecent
+window.getCurrentSkinTone = getCurrentSkinTone
+window.setCurrentSkinTone = setCurrentSkinTone
+window.usernameToColor = usernameToColor
+
 Vue.directive('tooltip', VTooltip)