From e8c9d4a7ace3b4f7a32d672f82d66d1047044891 Mon Sep 17 00:00:00 2001
From: "Grigorii K. Shartsev" <me@shgk.me>
Date: Tue, 21 May 2024 18:04:44 +0200
Subject: [PATCH] WIP! update docs

Signed-off-by: Grigorii K. Shartsev <me@shgk.me>
---
 src/components/NcAppSidebar/NcAppSidebar.vue | 96 ++++++++++++++++++--
 1 file changed, 87 insertions(+), 9 deletions(-)

diff --git a/src/components/NcAppSidebar/NcAppSidebar.vue b/src/components/NcAppSidebar/NcAppSidebar.vue
index 988bcfeacb..879a8e3eb3 100644
--- a/src/components/NcAppSidebar/NcAppSidebar.vue
+++ b/src/components/NcAppSidebar/NcAppSidebar.vue
@@ -371,14 +371,13 @@ A working alternative would be using an icon together with an `aria-label`:
 	</script>
 ```
 
-### Conditionally show the sidebar
+### Conditionally show the sidebar with `open`
 
-If the sidebar should be shown conditionally (e.g. using a button)
-and the users are expected to open and close the sidebar multiple times,
-then using `v-if` might result in bad performance.
-So instead use the `open` property.
+If the sidebar should be shown conditionally, you can use `open` prop to define sidebar visibility.
+It automatically shows a toggle button to open the sidebar if it is closed.
 
-You can also use `--app-sidebar-offset` CSS variable to preserve space for the toggle button, for example, in top bar of NcAppContent.
+You can also use `--app-sidebar-offset` CSS variable to preserve space
+for the toggle button, for example, in top bar of `NcAppContent`.
 
 ```vue
 <template>
@@ -386,9 +385,7 @@ You can also use `--app-sidebar-offset` CSS variable to preserve space for the t
 	<NcContent app-name="styleguidist" class="content-styleguidist">
 		<NcAppContent>
 			<div class="top-bar">
-				<NcButton @click.prevent="showSidebar = !showSidebar">
-					Toggle sidebar
-				</NcButton>
+				<NcButton type="primary">Start a call</NcButton>
 			</div>
 		</NcAppContent>
 		<!-- The sidebar -->
@@ -441,6 +438,87 @@ export default {
 	}
 }
 
+.top-bar {
+	display: flex;
+	justify-content: flex-end;
+	/* preserve space for toggle button */
+	padding-inline-end: var(--app-sidebar-offset);
+	/* same as on toggle button, but doesn't have to be the same */
+	margin: var(--app-sidebar-padding);
+}
+</style>
+```
+
+### Conditionally show the sidebar programmatically with `v-if`
+
+If the sidebar should be shown conditionally without any explicit toggle button, you can use `v-if`.
+
+**Note about performance**: using `v-if` might result in bad performance and loosing sidebar content state.
+
+**Note about `v-show`**: using `v-show` to hide sidebar will result in usability issues due to active focus trap on mobile.
+
+```vue
+<template>
+	<!-- This is in most cases NcContent -->
+	<NcContent app-name="styleguidist" class="content-styleguidist">
+		<NcAppContent>
+			<div class="top-bar">
+				<NcButton @click.prevent="showSidebar = true">
+					Toggle sidebar
+				</NcButton>
+			</div>
+		</NcAppContent>
+		<!-- The sidebar -->
+		<NcAppSidebar
+			v-if="showSidebar"
+			name="cat-picture.jpg"
+			subname="last edited 3 weeks ago"
+			@close="showSidebar = false">
+			<NcAppSidebarTab name="Settings" id="settings-tab">
+				<template #icon>
+					<Cog :size="20" />
+				</template>
+				Single tab content
+			</NcAppSidebarTab>
+		</NcAppSidebar>
+	</NcContent>
+</template>
+
+<script>
+import Cog from 'vue-material-design-icons/Cog'
+
+export default {
+	components: {
+		Cog,
+	},
+	data() {
+		return {
+			showSidebar: true,
+		}
+	},
+}
+</script>
+<style scoped>
+/* This styles just mock NcContent and NcAppContent */
+.content-styleguidist {
+	position: relative !important;
+	/* Just to prevent jumping when the sidebar is hidden */
+	min-height: 360px;
+}
+
+.main-content {
+	position: absolute;
+	height: 100%;
+	width: 100%;
+}
+
+/* Fix styles on this style guide page */
+@media only screen and (max-width: 512px) {
+	:deep(aside) {
+		width: calc(100vw - 64px) !important;
+	}
+}
+
 .top-bar {
 	display: flex;
 	justify-content: flex-end;