Merge pull request #4507 from nextcloud-libraries/feat/4485/enhance-r…

…ich-docs feat(docs) - add cross-examples for rich components in docs, add mention support
nextcloud-libraries · Sep 14, 2023 · 2cbafa1 · 2cbafa1
2 parents 55aee1a + f84af07
commit 2cbafa1
Show file tree

Hide file tree

Showing 2 changed files with 226 additions and 12 deletions.
diff --git a/src/components/NcRichContenteditable/NcRichContenteditable.vue b/src/components/NcRichContenteditable/NcRichContenteditable.vue
@@ -27,6 +27,8 @@ This component displays contenteditable div with automated `@` [at] autocompleti
 
 ### Examples
 
+Try mentioning user @Test01 or inserting emoji :smile
+
 ```vue
 <template>
 	<div>
@@ -53,21 +55,16 @@ This component displays contenteditable div with automated `@` [at] autocompleti
 		<p class="pre-line">{{ message }}</p>
 
 		<h5>Output - in NcRichText with markdown support</h5>
-		<NcRichText :text="message" use-markdown />
+		<NcRichText :text="text" :arguments="userMentions" autolink use-markdown />
 	</div>
 </template>
 <script>
-	import NcRichText from "../NcRichText/NcRichText.vue";
-
 export default {
-	components: {NcRichText},
-
 	data() {
 		return {
 			message: '**Lorem ipsum** dolor sit amet.',
-
-			// You need to provide this for the inline
-			// mention to understand what to display or not.
+			// You need to provide this for the inline mention to understand what to display or not.
+			// Key should be a string with leading '@', like @Test02 or @"Test Offline"
 			userData: {
 				Test01: {
 					icon: 'icon-user',
@@ -128,9 +125,59 @@ export default {
 					},
 					subline: 'Out sick',
 				},
+			},
+			// To display user bubbles in NcRichText, special format of data should be provided:
+			// Key should be in curly brackets without '@' and ' ' symbols, like {user-2}
+			userMentions: {
+				'user-1': {
+					component: 'NcUserBubble',
+					props: {
+						displayName: 'Test01',
+						user: 'Test01',
+						primary: true,
+					},
+				},
+				'user-2': {
+					component: 'NcUserBubble',
+					props: {
+						displayName: 'Test02',
+						user: 'Test02',
+					},
+				},
+				'user-3': {
+					component: 'NcUserBubble',
+					props: {
+						displayName: 'Test 03',
+						user: 'Test@User',
+					},
+				},
+				'user-4': {
+					component: 'NcUserBubble',
+					props: {
+						displayName: 'Test Offline',
+						user: 'Test Offline',
+					},
+				},
+				'user-5': {
+					component: 'NcUserBubble',
+					props: {
+						displayName: 'Test DND',
+						user: 'Test DND',
+					},
+				},
 			}
 		}
 	},
+	computed: {
+		text() {
+			return this.message
+					.replace('@Test01', '{user-1}')
+					.replace('@Test02', '{user-2}')
+					.replace('@Test@User', '{user-3}')
+					.replace('@"Test Offline"', '{user-4}')
+					.replace('@"Test DND"', '{user-5}')
+		},
+	},
 	methods: {
 		/**
 		* Do your own query to the autocompletion api.

diff --git a/src/components/NcRichText/NcRichText.vue b/src/components/NcRichText/NcRichText.vue
@@ -21,6 +21,10 @@
   -
   -->
 <docs>
+### General description
+
+This component displays rich text with optional autolink or [Markdown support](https://www.markdownguide.org/basic-syntax/).
+
 ```vue
 <template>
 	<div>
@@ -29,6 +33,7 @@
 		<NcCheckboxRadioSwitch :checked.sync="useMarkdown" type="checkbox">Use Markdown</NcCheckboxRadioSwitch>
 
 		<NcRichText
+			:class="{'plain-text': !useMarkdown }"
 			:text="text" :autolink="autolink" :arguments="args"
 			:use-markdown="useMarkdown" />
 	</div>
@@ -37,11 +42,16 @@
 export default {
 	data() {
 		return {
-			text: `Hello {username}. The file {file} was added by {username}. Go visit https://nextcloud.com
+			text: `## Hello everyone 🎉
+The file {file} was added by {username}. Visit https://nextcloud.com to check it!
 
-Local IP: http://127.0.0.1/status.php should be clickable
+Some examples for markdown syntax:
+1. **bold text**
+2. _italic text_
+3. example of \`inline code\`
 
-Some examples for markdown syntax: **bold text** *italic text* \`inline code\``,
+> blockquote example
+`,
 			autolink: true,
 			useMarkdown: true,
 			args: {
@@ -60,10 +70,167 @@ Some examples for markdown syntax: **bold text** *italic text* \`inline code\``,
 <style lang="scss">
 textarea {
 	width: 100%;
-	height: 100px;
+	height: 200px;
+}
+
+.plain-text {
+	white-space: pre-line;
 }
 </style>
 ```
+
+### Usage with NcRichContenteditable
+
+See [NcRichContenteditable](#/Components/NcRichContenteditable) documentation for more information
+
+```vue
+<template>
+	<div>
+		<NcRichContenteditable :value.sync="message"
+			:auto-complete="autoComplete"
+			:maxlength="100"
+			:user-data="userData"
+			placeholder="Try mentioning user @Test01 or inserting emoji :smile"
+			@submit="onSubmit" />
+
+		<NcCheckboxRadioSwitch :checked.sync="autolink" type="checkbox">Autolink</NcCheckboxRadioSwitch>
+		<NcCheckboxRadioSwitch :checked.sync="useMarkdown" type="checkbox">Use Markdown</NcCheckboxRadioSwitch>
+
+		<NcRichText :text="text"
+			:autolink="autolink"
+			:arguments="userMentions"
+			:use-markdown="useMarkdown" />
+	</div>
+</template>
+<script>
+	export default {
+		data() {
+			return {
+				message: '',
+				autolink: true,
+				useMarkdown: true,
+				userData: {
+					Test01: {
+						icon: 'icon-user',
+						id: 'Test01',
+						title: 'Test01',
+						source: 'users',
+						primary: true,
+					},
+					Test02: {
+						icon: 'icon-user',
+						id: 'Test02',
+						title: 'Test02',
+						source: 'users',
+						status: {
+							clearAt: null,
+							icon: '🎡',
+							message: 'Visiting London',
+							status: 'away',
+						},
+						subline: 'Visiting London',
+					},
+					'Test@User': {
+						icon: 'icon-user',
+						id: 'Test@User',
+						title: 'Test 03',
+						source: 'users',
+						status: {
+							clearAt: null,
+							icon: '🎡',
+							message: 'Having space in my name',
+							status: 'online',
+						},
+						subline: 'Visiting London',
+					},
+					'Test Offline': {
+						icon: 'icon-user',
+						id: 'Test Offline',
+						title: 'Test Offline',
+						source: 'users',
+						status: {
+							clearAt: null,
+							icon: null,
+							message: null,
+							status: 'offline',
+						},
+						subline: null,
+					},
+					'Test DND': {
+						icon: 'icon-user',
+						id: 'Test DND',
+						title: 'Test DND',
+						source: 'users',
+						status: {
+							clearAt: null,
+							icon: null,
+							message: 'Out sick',
+							status: 'dnd',
+						},
+						subline: 'Out sick',
+					},
+				},
+				userMentions: {
+					'user-1': {
+						component: 'NcUserBubble',
+						props: {
+							displayName: 'Test01',
+							user: 'Test01',
+							primary: true,
+						},
+					},
+					'user-2': {
+						component: 'NcUserBubble',
+						props: {
+							displayName: 'Test02',
+							user: 'Test02',
+						},
+					},
+					'user-3': {
+						component: 'NcUserBubble',
+						props: {
+							displayName: 'Test 03',
+							user: 'Test@User',
+						},
+					},
+					'user-4': {
+						component: 'NcUserBubble',
+						props: {
+							displayName: 'Test Offline',
+							user: 'Test Offline',
+						},
+					},
+					'user-5': {
+						component: 'NcUserBubble',
+						props: {
+							displayName: 'Test DND',
+							user: 'Test DND',
+						},
+					},
+				},
+			}
+		},
+		computed: {
+			text() {
+				return this.message
+						.replace('@Test01', '{user-1}')
+						.replace('@Test02', '{user-2}')
+						.replace('@Test@User', '{user-3}')
+						.replace('@"Test Offline"', '{user-4}')
+						.replace('@"Test DND"', '{user-5}')
+			},
+		},
+		methods: {
+			autoComplete(search, callback) {
+				callback(Object.values(this.userData))
+			},
+			onSubmit() {
+				alert(this.message)
+			}
+		}
+	}
+</script>
+```
 </docs>
 
 <script>