feat(NcAppSidebar): introduce NcAppSidebarHeader for a11y navigation

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

Author: Antreesy

src/components/NcAppSidebar/NcAppSidebar.vue

@@ -550,7 +550,8 @@ export default {
 				As a simple solution - render it in the content to keep correct position.
 			-->
 			<Teleport v-if="ncContentSelector && !open && !noToggle" :to="ncContentSelector">
-				<NcButton :aria-label="t('Open sidebar')"
+				<NcButton ref="toggle"
+					:aria-label="t('Open sidebar')"
 					class="app-sidebar__toggle"
 					:class="toggleClasses"
 					variant="tertiary"
@@ -570,6 +571,12 @@ export default {
 					'app-sidebar-header--compact': compact,
 				}"
 				class="app-sidebar-header">
+				<!-- a11y fallback for empty content -->
+				<NcAppSidebarHeader v-if="empty"
+					class="app-sidebar-header__mainname--hidden"
+					:name
+					tabindex="-1" />
+
 				<!-- container for figure and description, allows easy switching to compact mode -->
 				<div class="app-sidebar-header__info">
 					<!-- sidebar header illustration/figure -->
@@ -618,17 +625,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
+									:linkify="linkifyName"
+									:title
 									:tabindex="nameEditable ? 0 : -1"
-									@click.self="editName">
-									{{ name }}
-								</h2>
+									@click.self="editName" />
 								<template v-if="nameEditable">
 									<form v-click-outside="() => onSubmitName()"
 										class="app-sidebar-header__mainname-form"
@@ -706,13 +709,14 @@ export default {
 <script>
 import NcAppSidebarTabs from './NcAppSidebarTabs.vue'
 import NcActions from '../NcActions/index.js'
+import NcAppSidebarHeader from '../NcAppSidebarHeader/index.ts'
 import NcButton from '../NcButton/index.ts'
 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.ts'
 import { vOnClickOutside as ClickOutside } from '@vueuse/components'
 import { createFocusTrap } from 'focus-trap'
+import { provide, ref, warn } from 'vue'
 import { useIsSmallMobile } from '../../composables/useIsMobile/index.js'
 import { createElementId } from '../../utils/createElementId.ts'
 import { getTrapStack } from '../../utils/focusTrap.ts'
@@ -730,6 +734,7 @@ export default {
 
 	components: {
 		NcActions,
+		NcAppSidebarHeader,
 		NcAppSidebarTabs,
 		NcButton,
 		NcLoadingIcon,
@@ -743,7 +748,6 @@ export default {
 
 	directives: {
 		Focus,
-		Linkify,
 		ClickOutside,
 	},
 
@@ -922,9 +926,13 @@ export default {
 	],
 
 	setup() {
+		const headerRef = ref(null)
+		provide('NcAppSidebar:header:ref', headerRef)
+
 		return {
 			uid: createElementId(),
 			isMobile: useIsSmallMobile(),
+			headerRef,
 		}
 	},
 
@@ -1135,7 +1143,16 @@ export default {
 		 * @public
 		 */
 		focus() {
-			(this.$refs.header ?? this.$refs.toggle)?.focus()
+			if (!this.open && !this.noToggle) {
+				this.$refs.toggle.$el.focus()
+				return
+			}
+
+			try {
+				this.headerRef.focus()
+			} catch {
+				warn('NcAppSidebar should have focusable header for accessibility reasons. Use NcAppSidebarHeader component.')
+			}
 		},
 
 		/**
@@ -1497,6 +1514,17 @@ $top-buttons-spacing: 6px;
 			}
 		}
 
+		// 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,37 @@
+<!--
+  - SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<script setup lang="ts">
+import { inject } from 'vue'
+import vLinkify from '../../directives/Linkify/index.ts'
+
+defineProps<{
+	/**
+	 * The name used in NcAppSidebar header.
+	 */
+	name: string,
+
+	/**
+	 * Title to display for the name.
+	 */
+	title?: string,
+
+	/**
+	 * Linkify the name.
+	 */
+	linkify?: boolean,
+}>()
+
+const headerRef = inject('NcAppSidebar:header:ref')
+</script>
+
+<template>
+	<h2 ref="headerRef"
+		v-linkify="{ text: name, linkify }"
+		tabindex="-1"
+		: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.ts

@@ -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.cjs

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