-
Notifications
You must be signed in to change notification settings - Fork 84
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #5693 from nextcloud-libraries/backport/5669/next
[next] chore(functions): add docs
- Loading branch information
Showing
10 changed files
with
292 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| <!-- | ||
| - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
| - SPDX-License-Identifier: AGPL-3.0-or-later | ||
| --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| <!-- | ||
| - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
| - SPDX-License-Identifier: AGPL-3.0-or-later | ||
| --> | ||
|
|
||
| ```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 | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,127 @@ | ||
| <!-- | ||
| - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
| - SPDX-License-Identifier: AGPL-3.0-or-later | ||
| --> | ||
|
|
||
| ```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> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| <!-- | ||
| - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
| - SPDX-License-Identifier: AGPL-3.0-or-later | ||
| --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| <!-- | ||
| - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
| - SPDX-License-Identifier: AGPL-3.0-or-later | ||
| --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| <!-- | ||
| - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
| - SPDX-License-Identifier: AGPL-3.0-or-later | ||
| --> | ||
|
|
||
| ```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" v-model="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> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters