From f1acfcc465eb427dae4a83d29babf45887435f6a Mon Sep 17 00:00:00 2001
From: Grigorii Shartsev <grigorii.shartsev@nextcloud.com>
Date: Tue, 28 Mar 2023 03:38:52 +0200
Subject: [PATCH] docs(NcAppSIdebarTabs): add JSDocs and examples

Signed-off-by: Grigorii Shartsev <grigorii.shartsev@nextcloud.com>
---
 src/components/NcAppSidebar/NcAppSidebar.vue  | 173 ++++++++++++++----
 .../NcAppSidebar/NcAppSidebarTabs.vue         |  31 ++--
 .../NcAppSidebarTab/NcAppSidebarTab.vue       |  26 +++
 3 files changed, 180 insertions(+), 50 deletions(-)

diff --git a/src/components/NcAppSidebar/NcAppSidebar.vue b/src/components/NcAppSidebar/NcAppSidebar.vue
index 1bbf50c0f3..f4c4117f73 100644
--- a/src/components/NcAppSidebar/NcAppSidebar.vue
+++ b/src/components/NcAppSidebar/NcAppSidebar.vue
@@ -31,54 +31,48 @@ include a standard-header like it's used by the files app.
 
 ```vue
 <template>
-	<div>
-		<NcCheckboxRadioSwitch :checked.sync="hideFirstTab">
-			The first tab is hidden
-		</NcCheckboxRadioSwitch>
-		<NcAppSidebar
-			title="cat-picture.jpg"
-			subtitle="last edited 3 weeks ago">
-			<NcAppSidebarTab v-if="!hideFirstTab" name="Fist tab" id="first-tab">
-				<template #icon>
-					<Cog :size="20" />
-				</template>
-				New tab
-			</NcAppSidebarTab>
-			<NcAppSidebarTab name="Settings" id="settings-tab">
-				<template #icon>
-					<Cog :size="20" />
-				</template>
-				Settings tab content
-			</NcAppSidebarTab>
-			<NcAppSidebarTab name="Sharing" id="share-tab">
-				<template #icon>
-					<ShareVariant :size="20" />
-				</template>
-				Sharing tab content
-			</NcAppSidebarTab>
-		</NcAppSidebar>
-	</div>
+	<NcAppSidebar
+		title="cat-picture.jpg"
+		subtitle="last edited 3 weeks ago">
+		<NcAppSidebarTab name="Search" id="search-tab">
+			<template #icon>
+				<Magnify :size="20" />
+			</template>
+			Search tab content
+		</NcAppSidebarTab>
+		<NcAppSidebarTab name="Settings" id="settings-tab">
+			<template #icon>
+				<Cog :size="20" />
+			</template>
+			Settings tab content
+		</NcAppSidebarTab>
+		<NcAppSidebarTab name="Sharing" id="share-tab">
+			<template #icon>
+				<ShareVariant :size="20" />
+			</template>
+			Sharing tab content
+		</NcAppSidebarTab>
+	</NcAppSidebar>
 </template>
 <script>
+	import Magnify from 'vue-material-design-icons/Magnify'
 	import Cog from 'vue-material-design-icons/Cog'
 	import ShareVariant from 'vue-material-design-icons/ShareVariant'
 
 	export default {
 		components: {
+			Magnify,
 			Cog,
 			ShareVariant,
 		},
-		data() {
-			return {
-				hideFirstTab: true,
-			}
-		},
 	}
 </script>
 ```
 
 ### One tab
 
+Single tab is rendered without navigation.
+
 ```vue
 <template>
 	<div>
@@ -89,7 +83,7 @@ include a standard-header like it's used by the files app.
 				<template #icon>
 					<Cog :size="20" />
 				</template>
-				New tab
+				Single tab content
 			</NcAppSidebarTab>
 		</NcAppSidebar>
 	</div>
@@ -105,18 +99,117 @@ export default {
 </script>
 ```
 
-### One or two tabs with condition
+### Dynamic tabs
 
 ```vue
 <template>
 	<div>
-		<NcCheckboxRadioSwitch :checked.sync="hideFirstTab">
-			The first tab is hidden
-		</NcCheckboxRadioSwitch>
+		<NcCheckboxRadioSwitch :checked.sync="showTabs[0]">Show search tab</NcCheckboxRadioSwitch>
+		<NcCheckboxRadioSwitch :checked.sync="showTabs[1]">Show settings tab</NcCheckboxRadioSwitch>
+		<NcCheckboxRadioSwitch :checked.sync="showTabs[2]">Show sharing tab</NcCheckboxRadioSwitch>
 		<NcAppSidebar
 			title="cat-picture.jpg"
 			subtitle="last edited 3 weeks ago">
-			<NcAppSidebarTab v-if="!hideFirstTab" name="Settings" id="settings-tab">
+			<NcAppSidebarTab v-if="showTabs[0]" name="Search" id="search-tab">
+				<template #icon>
+					<Magnify :size="20" />
+				</template>
+				Search tab content
+			</NcAppSidebarTab>
+			<NcAppSidebarTab v-if="showTabs[1]" name="Settings" id="settings-tab">
+				<template #icon>
+					<Cog :size="20" />
+				</template>
+				Settings
+			</NcAppSidebarTab>
+			<NcAppSidebarTab v-if="showTabs[2]" name="Sharing" id="share-tab">
+				<template #icon>
+					<ShareVariant :size="20" />
+				</template>
+				Sharing tab content
+			</NcAppSidebarTab>
+		</NcAppSidebar>
+	</div>
+</template>
+<script>
+import Magnify from 'vue-material-design-icons/Magnify'
+import Cog from 'vue-material-design-icons/Cog'
+import ShareVariant from 'vue-material-design-icons/ShareVariant'
+
+export default {
+	components: {
+		Magnify,
+		Cog,
+		ShareVariant,
+	},
+	data() {
+		return {
+			showTabs: [true, true, false],
+		}
+	},
+}
+</script>
+```
+
+### Custom order
+
+```vue
+<template>
+	<NcAppSidebar
+		title="cat-picture.jpg"
+		subtitle="last edited 3 weeks ago">
+		<NcAppSidebarTab name="Search" id="search-tab" order="3">
+			<template #icon>
+				<Magnify :size="20" />
+			</template>
+			Search tab content
+		</NcAppSidebarTab>
+		<NcAppSidebarTab name="Settings" id="settings-tab" order="2">
+			<template #icon>
+				<Cog :size="20" />
+			</template>
+			Settings tab content
+		</NcAppSidebarTab>
+		<NcAppSidebarTab name="Sharing" id="share-tab" order="1">
+			<template #icon>
+				<ShareVariant :size="20" />
+			</template>
+			Sharing tab content
+		</NcAppSidebarTab>
+	</NcAppSidebar>
+</template>
+<script>
+import Magnify from 'vue-material-design-icons/Magnify'
+import Cog from 'vue-material-design-icons/Cog'
+import ShareVariant from 'vue-material-design-icons/ShareVariant'
+
+export default {
+	components: {
+		Magnify,
+		Cog,
+		ShareVariant,
+	},
+}
+</script>
+```
+
+### Activating tab programmatically
+
+```vue
+<template>
+	<div>
+		<NcMultiselect v-model="active" :options="['search-tab', 'settings-tab', 'share-tab']" />
+		<NcAppSidebar
+			title="cat-picture.jpg"
+			subtitle="last edited 3 weeks ago"
+			:active.sync="active">
+			<NcAppSidebarTab name="Search" id="search-tab">
+				<template #icon>
+					<Magnify :size="20" />
+				</template>
+				Search tab content
+			</NcAppSidebarTab>
+			<NcAppSidebarTab name="Settings" id="settings-tab">
 				<template #icon>
 					<Cog :size="20" />
 				</template>
@@ -132,17 +225,19 @@ export default {
 	</div>
 </template>
 <script>
+import Magnify from 'vue-material-design-icons/Magnify'
 import Cog from 'vue-material-design-icons/Cog'
 import ShareVariant from 'vue-material-design-icons/ShareVariant'
 
 export default {
 	components: {
+		Magnify,
 		Cog,
 		ShareVariant,
 	},
 	data() {
 		return {
-			hideFirstTab: true,
+			active: 'search-tab',
 		}
 	},
 }
diff --git a/src/components/NcAppSidebar/NcAppSidebarTabs.vue b/src/components/NcAppSidebar/NcAppSidebarTabs.vue
index f251322eb4..b3f32fb884 100644
--- a/src/components/NcAppSidebar/NcAppSidebarTabs.vue
+++ b/src/components/NcAppSidebar/NcAppSidebarTabs.vue
@@ -60,6 +60,7 @@
 		<!-- tabs content -->
 		<div :class="{'app-sidebar-tabs__content--multiple': hasMultipleTabs}"
 			class="app-sidebar-tabs__content">
+			<!-- @slot Tabs content - NcAppSidebarTab components or any content if there is no tabs -->
 			<slot />
 		</div>
 	</div>
@@ -72,7 +73,6 @@ export default {
 	name: 'NcAppSidebarTabs',
 
 	components: {
-		// Component to render the material design icon (vnodes)
 		NcVNodes,
 	},
 
@@ -100,22 +100,28 @@ export default {
 	data() {
 		return {
 			/**
-			 * The tab component instances to build the tab navbar from.
+			 * Tab descriptions from the passed NcSidebarTab components' props to build the tab navbar from.
 			 */
 			tabs: [],
 			/**
-			 * The id of the currently active tab.
+			 * Local active (open) tab's ID. It allows to use component without active.sync
 			 */
 			activeTab: '',
 		}
 	},
 
 	computed: {
+		/**
+		 * Has multiple tabs. If only one tab - its content is shown without navigation
+		 *
+		 * @return {boolean}
+		 */
 		hasMultipleTabs() {
 			return this.tabs.length > 1
 		},
+
 		currentTabIndex() {
-			return this.tabs.findIndex(tab => tab.id === this.activeTab)
+			return this.tabs.findIndex((tab) => tab.id === this.activeTab)
 		},
 	},
 
@@ -137,6 +143,9 @@ export default {
 		 */
 		setActive(id) {
 			this.activeTab = id
+			/**
+			 * @property {string} active - active tab's id
+			 */
 			this.$emit('update:active', this.activeTab)
 		},
 
@@ -148,7 +157,7 @@ export default {
 			if (this.currentTabIndex > 0) {
 				this.setActive(this.tabs[this.currentTabIndex - 1].id)
 			}
-			this.focusActiveTab() // focus nav item
+			this.focusActiveTab()
 		},
 
 		/**
@@ -159,7 +168,7 @@ export default {
 			if (this.currentTabIndex < this.tabs.length - 1) {
 				this.setActive(this.tabs[this.currentTabIndex + 1].id)
 			}
-			this.focusActiveTab() // focus nav item
+			this.focusActiveTab()
 		},
 
 		/**
@@ -168,7 +177,7 @@ export default {
 		 */
 		focusFirstTab() {
 			this.setActive(this.tabs[0].id)
-			this.focusActiveTab() // focus nav item
+			this.focusActiveTab()
 		},
 
 		/**
@@ -177,7 +186,7 @@ export default {
 		 */
 		focusLastTab() {
 			this.setActive(this.tabs[this.tabs.length - 1].id)
-			this.focusActiveTab() // focus nav item
+			this.focusActiveTab()
 		},
 
 		/**
@@ -210,7 +219,7 @@ export default {
 		/**
 		 * Register child tab in the tabs
 		 *
-		 * @param {object} tab - tab props (only the "id" is used actually)
+		 * @param {object} tab child tab passed to slot
 		 */
 		registerTab(tab) {
 			this.tabs.push(tab)
@@ -226,9 +235,9 @@ export default {
 		},
 
 		/**
-		 * Unregister child tab in the tabs
+		 * Unregister child tab from the tabs
 		 *
-		 * @param {string} id - tab's id
+		 * @param {string} id tab's id
 		 */
 		unregisterTab(id) {
 			const tabIndex = this.tabs.findIndex((tab) => tab.id === id)
diff --git a/src/components/NcAppSidebarTab/NcAppSidebarTab.vue b/src/components/NcAppSidebarTab/NcAppSidebarTab.vue
index ae9f9100f4..72bfa0ac1c 100644
--- a/src/components/NcAppSidebarTab/NcAppSidebarTab.vue
+++ b/src/components/NcAppSidebarTab/NcAppSidebarTab.vue
@@ -35,6 +35,7 @@
 		<h3 class="hidden-visually">
 			{{ name }}
 		</h3>
+		<!-- @slot Tab panel content -->
 		<slot />
 	</section>
 </template>
@@ -52,14 +53,26 @@ export default {
 			type: String,
 			required: true,
 		},
+
+		/**
+		 * Tab title in navigation
+		 */
 		name: {
 			type: String,
 			required: true,
 		},
+
+		/**
+		 * Tab icon's html class in navigation. Used if #icon slot is not provided
+		 */
 		icon: {
 			type: String,
 			default: '',
 		},
+
+		/**
+		 * Tab order in navigation. If not provided, name is used.
+		 */
 		order: {
 			type: Number,
 			default: 0,
@@ -74,16 +87,24 @@ export default {
 	expose: ['id', 'name', 'icon', 'order', 'renderIcon'],
 
 	computed: {
+		/**
+		 * Is the current tab an active tab, that should be shown?
+		 *
+		 * @return {boolean}
+		 */
 		isActive() {
 			return this.getActiveTab() === this.id
 		},
 	},
 
 	created() {
+		// As the tab is created - register it in the tabs component
+		// It's better to provide computed tab object, not component instance as it easy
 		this.registerTab(this)
 	},
 
 	beforeDestroy() {
+		// Unregister the tab from tabs
 		this.unregisterTab(this.id)
 	},
 
@@ -93,9 +114,14 @@ export default {
 			if (this.$el.scrollHeight - this.$el.scrollTop === this.$el.clientHeight) {
 				/**
 				 * Bottom scroll is reached
+				 *
+				 * @property {Event} event Native scroll event
 				 */
 				this.$emit('bottom-reached', event)
 			}
+			/**
+			 * @property {Event} event Native scroll event
+			 */
 			this.$emit('scroll', event)
 		},