From add69434e55742b4c565bad0a8c003118ef24a06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Raimund=20Schl=C3=BC=C3=9Fler?=
 <raimund.schluessler@mailbox.org>
Date: Mon, 2 May 2022 21:57:29 +0200
Subject: [PATCH] Add Dashboard documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Raimund Schlüßler <raimund.schluessler@mailbox.org>
---
 .../DashboardWidget/DashboardWidget.vue       | 151 ++++++++++++++++++
 .../DashboardWidgetItem.vue                   |   9 ++
 styleguide.config.js                          |   7 +
 3 files changed, 167 insertions(+)

diff --git a/src/components/DashboardWidget/DashboardWidget.vue b/src/components/DashboardWidget/DashboardWidget.vue
index 047a3f651e..bc1362ddfc 100644
--- a/src/components/DashboardWidget/DashboardWidget.vue
+++ b/src/components/DashboardWidget/DashboardWidget.vue
@@ -19,6 +19,122 @@
  - along with this program. If not, see <http://www.gnu.org/licenses/>.
  -
  -->
+ <docs>
+
+## Usage
+
+### Simplest example with custom item
+```vue
+<template>
+	<DashboardWidget :items="items">
+		<template #default="{ item }">
+			{{ item.title }}
+		</template>
+	</DashboardWidget>
+</template>
+
+<script>
+const myItems = [
+	{
+		title: 'first',
+		content: 'blabla',
+	},
+	{
+		title: 'second',
+		content: 'fuzzfuzz',
+	},
+]
+export default {
+	name: 'MyDashboardWidget',
+	props: [],
+	data() {
+		return {
+			items: myItems
+		}
+	},
+}
+</script>
+```
+
+### Complete example using DashboardWidgetItem
+
+```vue
+<template>
+	<DashboardWidget :items="items"
+		:show-more-url="'https://nextcloud.com'"
+		:item-menu="itemMenu"
+		@hide="onHide"
+		@markDone="onMarkDone">
+
+		<template #empty-content>
+			Nothing to display
+		</template>
+	</DashboardWidget>
+</template>
+
+<script>
+const myItems = [
+	{
+		id: '1',
+		targetUrl: 'https://target.org',
+		avatarUrl: 'https://avatar.url/img.png',
+		avatarUsername: 'Robert',
+		avatarIsNoUser: true,
+		overlayIconUrl: '/svg/core/actions/sound?color=000',
+		mainText: 'First item text',
+		subText: 'First item subtext',
+	},
+	{
+		id: '2',
+		targetUrl: 'https://other-target.org',
+		avatarUrl: 'https://other-avatar.url/img.png',
+		overlayIconUrl: '/svg/core/actions/add?color=000',
+		mainText: 'Second item text',
+		subText: 'Second item subtext',
+	},
+]
+const myItemMenu = {
+	// triggers an event named "markDone" when clicked
+	'markDone': {
+		text: 'Mark as done',
+		icon: 'icon-checkmark',
+	},
+	// triggers an event named "hide" when clicked
+	'hide': {
+		text: 'Hide',
+		icon: 'icon-toggle',
+	}
+}
+export default {
+	name: 'MyDashboardWidget',
+	props: [],
+	data() {
+		return {
+			items: myItems,
+			itemMenu: myItemMenu,
+			loading: true,
+		}
+	},
+	methods: {
+		onMoreClick() {
+			console.log('more clicked')
+			const win = window.open('https://wherever.you.want', '_blank')
+			win.focus()
+		},
+		onHide(item) {
+			console.log('user wants to hide item ' + item.id)
+			// do what you want
+		},
+		onMarkDone(item) {
+			console.log('user wants to mark item ' + item.id + ' as done')
+			// do what you want
+		},
+	},
+}
+</script>
+```
+
+ </docs>
 
 <template>
 	<div>
@@ -31,6 +147,7 @@
 		</EmptyContent>
 		<ul>
 			<li v-for="item in displayedItems" :key="item.id">
+				<!-- @slot The default slot can be optionally overridden. It contains the template of one item. -->
 				<slot name="default" :item="item">
 					<DashboardWidgetItem :id="item.id"
 						:target-url="item.targetUrl"
@@ -56,6 +173,7 @@
 				</div>
 			</div>
 		</div>
+		<!-- @slot Slot for showing information in case of an empty item list. -->
 		<slot v-else-if="items.length === 0" name="empty-content">
 			<EmptyContent v-if="emptyContentMessage"
 				:icon="emptyContentIcon">
@@ -90,42 +208,75 @@ export default {
 	},
 
 	props: {
+		/**
+		 * An array containing the items to show (specific structure must be respected,
+		 * except if you override item rendering in the default slot).
+		 */
 		items: {
 			type: Array,
 			default: () => { return [] },
 		},
+		/**
+		 * If this is set, a "show more" text is displayed on the widget's bottom.
+		 * It's a link pointing to this URL.
+		 */
 		showMoreUrl: {
 			type: String,
 			default: '',
 		},
+		/**
+		 * The type of elements to show more.
+		 */
 		showMoreText: {
 			type: String,
 			default: t('items'),
 		},
+		/**
+		 * A boolean to put the widget in a loading state.
+		 */
 		loading: {
 			type: Boolean,
 			default: false,
 		},
+		/**
+		 * An object containing context menu entries that will be displayed for each item.
+		 */
 		itemMenu: {
 			type: Object,
 			default: () => { return {} },
 		},
+		/**
+		 * Whether both the items and the empty content message are shown.
+		 * Usefull for e.g. showing "No mentions" and a list of elements.
+		 */
 		showItemsAndEmptyContent: {
 			type: Boolean,
 			default: false,
 		},
+		/**
+		 * The icon to show in the empty content area.
+		 */
 		emptyContentIcon: {
 			type: String,
 			default: '',
 		},
+		/**
+		 * The text to show in the empty content area.
+		 */
 		emptyContentMessage: {
 			type: String,
 			default: '',
 		},
+		/**
+		 * The icon to show in the half empty content area.
+		 */
 		halfEmptyContentIcon: {
 			type: String,
 			default: 'icon-checkmark',
 		},
+		/**
+		 * The text to show in the half empty content area.
+		 */
 		halfEmptyContentMessage: {
 			type: String,
 			default: '',
diff --git a/src/components/DashboardWidgetItem/DashboardWidgetItem.vue b/src/components/DashboardWidgetItem/DashboardWidgetItem.vue
index 07cbbdd138..c33849b45b 100644
--- a/src/components/DashboardWidgetItem/DashboardWidgetItem.vue
+++ b/src/components/DashboardWidgetItem/DashboardWidgetItem.vue
@@ -20,6 +20,14 @@
  -
  -->
 
+<docs>
+
+### General description
+
+This component is meant to be used inside a DashboardWidget component.
+
+</docs>
+
 <template>
 	<div @mouseover="hovered = true" @mouseleave="hovered = false">
 		<component :is="targetUrl ? 'a' : 'div'"
@@ -27,6 +35,7 @@
 			:target="targetUrl ? '_blank' : undefined"
 			:class="{ 'item-list__entry': true, 'item-list__entry--has-actions-menu': gotMenu }"
 			@click="onLinkClick">
+			<!-- @slot Slot for passing a user avatar. -->
 			<slot name="avatar" :avatar-url="avatarUrl" :avatar-username="avatarUsername">
 				<Avatar class="item-avatar"
 					:size="44"
diff --git a/styleguide.config.js b/styleguide.config.js
index 1aa48c6b75..4742a85f35 100644
--- a/styleguide.config.js
+++ b/styleguide.config.js
@@ -69,6 +69,7 @@ module.exports = {
 				'src/components/AppSidebar*/*.vue',
 				'src/components/Breadcrumb*/*.vue',
 				'src/components/Content/*.vue',
+				'src/components/Dashboard*/*.vue',
 				'src/components/Multiselect*/*.vue',
 				'src/components/PopoverMenu/!(PopoverMenu).vue',
 				'src/components/ListItem*/*.vue',
@@ -125,6 +126,12 @@ module.exports = {
 						'src/components/Breadcrumb*/*.vue',
 					],
 				},
+				{
+					name: 'Dashboard',
+					components: [
+						'src/components/Dashboard*/*.vue',
+					],
+				},
 				{
 					name: 'List items',
 					components: [