diff --git a/docs/functions.md b/docs/functions.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/functions/a11y.md b/docs/functions/a11y.md new file mode 100644 index 0000000000..5e1059d8f0 --- /dev/null +++ b/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 +``` diff --git a/docs/functions/emoji.md b/docs/functions/emoji.md new file mode 100644 index 0000000000..4704b6eb6d --- /dev/null +++ b/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 + + + +``` \ No newline at end of file diff --git a/docs/functions/reference.md b/docs/functions/reference.md new file mode 100644 index 0000000000..991aa1a51e --- /dev/null +++ b/docs/functions/reference.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/functions/registerReference.md b/docs/functions/registerReference.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/functions/usernameToColor.md b/docs/functions/usernameToColor.md new file mode 100644 index 0000000000..06d4fd8e68 --- /dev/null +++ b/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 + + + + + +``` diff --git a/src/functions/emoji/emoji.ts b/src/functions/emoji/emoji.ts index 519633edc9..5318d45b16 100644 --- a/src/functions/emoji/emoji.ts +++ b/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,15 +71,23 @@ 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) @@ -85,9 +95,10 @@ export const getCurrentSkinTone = () => { /** * 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()) diff --git a/src/functions/usernameToColor/usernameToColor.js b/src/functions/usernameToColor/usernameToColor.js index 82321bd111..6136983248 100644 --- a/src/functions/usernameToColor/usernameToColor.js +++ b/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 diff --git a/styleguide.config.js b/styleguide.config.js index 030adc287a..0b4f7d962d 100644 --- a/styleguide.config.js +++ b/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', diff --git a/styleguide/global.requires.js b/styleguide/global.requires.js index 222f99a2ac..eed8ffd31a 100644 --- a/styleguide/global.requires.js +++ b/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: '/remote.php/dav/systemtags/HTTP/1.1 404 Not Found/remote.php/dav/systemtags/77tag1truetruetrueHTTP/1.1 200 OK/remote.php/dav/systemtags/22tag2falsetruetrueHTTP/1.1 200 OK/remote.php/dav/systemtags/33tag3truetruetrueHTTP/1.1 200 OK/remote.php/dav/systemtags/44importanttruetruetrueHTTP/1.1 200 OK/remote.php/dav/systemtags/11secrettruefalsetrueHTTP/1.1 200 OK/remote.php/dav/systemtags/55testtruefalsetrueHTTP/1.1 200 OK/remote.php/dav/systemtags/66test2falsefalsetrueHTTP/1.1 200 OK', } +// 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)