feat(NcAppSidebar): introduce NcAppSidebarHeader for a11y navigation

Signed-off-by: Maksim Sukharev <antreesy.web@gmail.com>

Author: Antreesy

src/components/NcAppSidebar/NcAppSidebar.vue

@@ -545,7 +545,8 @@ export default {
 				As a simple solution - render it in the content to keep correct position.
 			-->
 			<Teleport v-if="ncContentSelector && !open && !noToggle" :selector="ncContentSelector">
-				<NcButton :aria-label="t('Open sidebar')"
+				<NcButton ref="toggle"
+					:aria-label="t('Open sidebar')"
 					class="app-sidebar__toggle"
 					:class="toggleClasses"
 					variant="tertiary"
@@ -613,17 +614,13 @@ export default {
 						<div class="app-sidebar-header__name-container">
 							<div class="app-sidebar-header__mainname-container">
 								<!-- main name -->
-								<h2 v-show="!nameEditable"
-									:id="`app-sidebar-vue-${uid}__header`"
-									ref="header"
-									v-linkify="{text: name, linkify: linkifyName}"
-									:aria-label="title"
-									:title="title"
+								<NcAppSidebarHeader v-show="!nameEditable"
 									class="app-sidebar-header__mainname"
+									:name="name"
+									:linkify="linkifyName"
+									:title="title"
 									:tabindex="nameEditable ? 0 : -1"
-									@click.self="editName">
-									{{ name }}
-								</h2>
+									@click.self.native="editName" />
 								<template v-if="nameEditable">
 									<form v-click-outside="() => onSubmitName()"
 										class="app-sidebar-header__mainname-form"
@@ -664,6 +661,11 @@ export default {
 						</div>
 					</div>
 				</div>
+				<!-- a11y fallback for empty content -->
+				<NcAppSidebarHeader v-if="empty"
+					class="app-sidebar-header__mainname--hidden"
+					:name="name"
+					tabindex="-1" />
 
 				<NcButton ref="closeButton"
 					:aria-label="closeTranslated"
@@ -704,11 +706,11 @@ import { Portal as Teleport } from '@linusborg/vue-simple-portal'
 
 import NcAppSidebarTabs from './NcAppSidebarTabs.vue'
 import NcActions from '../NcActions/index.js'
+import NcAppSidebarHeader from '../NcAppSidebarHeader/index.ts'
 import NcButton from '../NcButton/index.js'
 import NcEmptyContent from '../NcEmptyContent/index.js'
 import NcLoadingIcon from '../NcLoadingIcon/index.js'
 import Focus from '../../directives/Focus/index.js'
-import Linkify from '../../directives/Linkify/index.js'
 import { useIsSmallMobile } from '../../composables/useIsMobile/index.js'
 import GenRandomId from '../../utils/GenRandomId.js'
 import { getTrapStack } from '../../utils/focusTrap.ts'
@@ -722,13 +724,15 @@ import StarOutline from 'vue-material-design-icons/StarOutline.vue'
 
 import { vOnClickOutside as ClickOutside } from '@vueuse/components'
 import { createFocusTrap } from 'focus-trap'
+import Vue, { provide, ref } from 'vue'
 
 export default {
 	name: 'NcAppSidebar',
 
 	components: {
 		Teleport,
 		NcActions,
+		NcAppSidebarHeader,
 		NcAppSidebarTabs,
 		ArrowRight,
 		IconDockRight,
@@ -742,7 +746,6 @@ export default {
 
 	directives: {
 		focus: Focus,
-		linkify: Linkify,
 		ClickOutside,
 	},
 
@@ -923,9 +926,13 @@ export default {
 	],
 
 	setup() {
+		const headerRef = ref(null)
+		provide('NcAppSidebar:header:ref', headerRef)
+
 		return {
 			uid: GenRandomId(),
 			isMobile: useIsSmallMobile(),
+			headerRef,
 		}
 	},
 
@@ -1155,7 +1162,16 @@ export default {
 		 * @public
 		 */
 		focus() {
-			this.$refs.header.focus()
+			if (!this.open && !this.noToggle) {
+				this.$refs.toggle.$el.focus()
+				return
+			}
+
+			try {
+				this.headerRef.focus()
+			} catch {
+				Vue.util.warn('NcAppSidebar should have focusable header for accessibility reasons. Use NcAppSidebarHeader component.')
+			}
 		},
 
 		/**
@@ -1517,6 +1533,17 @@ $top-buttons-spacing: $app-navigation-padding; // align with app navigation
 			}
 		}
 
+		// Hidden a11y fallback
+		.app-sidebar-header__mainname--hidden {
+			position: absolute;
+			top: 0;
+			inset-inline-start: 0;
+			margin: 0;
+			width: 1px;
+			height: 1px;
+			overflow: hidden;
+		}
+
 		// sidebar description slot
 		&__description {
 			display: flex;

src/components/NcAppSidebarHeader/NcAppSidebarHeader.vue

@@ -0,0 +1,44 @@
+<!--
+  - SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<script setup>
+import { inject } from 'vue'
+import vLinkify from '../../directives/Linkify/index.js'
+
+defineProps({
+	/**
+	 * The name used in NcAppSidebar header.
+	 */
+	name: {
+		type: String,
+		required: true,
+	},
+
+	/**
+	 * Title to display for the name.
+	 */
+	title: {
+		type: String,
+	},
+
+	/**
+	 * Linkify the name.
+	 */
+	linkify: {
+		type: Boolean,
+	},
+})
+
+const headerRef = inject('NcAppSidebar:header:ref')
+</script>
+
+<template>
+	<h2 ref="headerRef"
+		v-linkify="{ text: name, linkify }"
+		tabindex="-1"
+		:title="title">
+		{{ name }}
+	</h2>
+</template>

src/components/NcAppSidebarHeader/index.ts

@@ -0,0 +1,6 @@
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+export { default } from './NcAppSidebarHeader.vue'

src/components/index.js

@@ -31,6 +31,7 @@ export { default as NcAppNavigationSpacer } from './NcAppNavigationSpacer/index.
 export { default as NcAppSettingsDialog } from './NcAppSettingsDialog/index.js'
 export { default as NcAppSettingsSection } from './NcAppSettingsSection/index.js'
 export { default as NcAppSidebar } from './NcAppSidebar/index.js'
+export { default as NcAppSidebarHeader } from './NcAppSidebarHeader/index.ts'
 export { default as NcAppSidebarTab } from './NcAppSidebarTab/index.js'
 export { default as NcAvatar } from './NcAvatar/index.js'
 export { default as NcBlurHash } from './NcBlurHash/index.js'

styleguide.config.js

@@ -236,6 +236,7 @@ module.exports = async () => {
 								name: 'NcAppSidebar',
 								components: [
 									'src/components/NcAppSidebar/NcAppSidebar.vue',
+									'src/components/NcAppSidebarHeader/NcAppSidebarHeader.vue',
 									'src/components/NcAppSidebarTab/NcAppSidebarTab.vue',
 								],
 							},