diff --git a/docs/functions.md b/docs/functions.md new file mode 100644 index 0000000000..c88a470eb2 --- /dev/null +++ b/docs/functions.md @@ -0,0 +1,4 @@ + diff --git a/docs/functions/a11y.md b/docs/functions/a11y.md new file mode 100644 index 0000000000..71627dcf8d --- /dev/null +++ b/docs/functions/a11y.md @@ -0,0 +1,21 @@ + + +```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..a7937aafd2 --- /dev/null +++ b/docs/functions/emoji.md @@ -0,0 +1,127 @@ + + +```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..c88a470eb2 --- /dev/null +++ b/docs/functions/reference.md @@ -0,0 +1,4 @@ + diff --git a/docs/functions/registerReference.md b/docs/functions/registerReference.md new file mode 100644 index 0000000000..c88a470eb2 --- /dev/null +++ b/docs/functions/registerReference.md @@ -0,0 +1,4 @@ + diff --git a/docs/functions/usernameToColor.md b/docs/functions/usernameToColor.md new file mode 100644 index 0000000000..53bd34ac51 --- /dev/null +++ b/docs/functions/usernameToColor.md @@ -0,0 +1,70 @@ + + +```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 48090d8b74..bdcaed8b5c 100644 --- a/src/functions/emoji/emoji.ts +++ b/src/functions/emoji/emoji.ts @@ -28,11 +28,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) @@ -52,15 +54,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) @@ -68,9 +78,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 c2a0558cb9..37c0a3ed6d 100644 --- a/src/functions/usernameToColor/usernameToColor.js +++ b/src/functions/usernameToColor/usernameToColor.js @@ -8,10 +8,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.cjs b/styleguide.config.cjs index c8741dcf99..b64044a09b 100644 --- a/styleguide.config.cjs +++ b/styleguide.config.cjs @@ -105,6 +105,33 @@ module.exports = async () => { }, ], }, + { + 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 49fd483521..0083853bc1 100644 --- a/styleguide/global.requires.js +++ b/styleguide/global.requires.js @@ -8,6 +8,10 @@ import 'regenerator-runtime/runtime.js' import axios from '@nextcloud/axios' +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' + const USER_GROUPS = [ { id: 'admin', displayname: 'The administrators' }, { id: 'accounting', displayname: 'Accounting team' }, @@ -145,6 +149,15 @@ window.OC = { window.OCA = {} window.appName = 'nextcloud-vue' +// Exported Functions +window.isA11yActivation = isA11yActivation +window.EmojiSkinTone = EmojiSkinTone +window.emojiSearch = emojiSearch +window.emojiAddRecent = emojiAddRecent +window.getCurrentSkinTone = getCurrentSkinTone +window.setCurrentSkinTone = setCurrentSkinTone +window.usernameToColor = usernameToColor + 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', }