Merge pull request #5580 from nextcloud-libraries/backport/heading-id

[next] feat(NcAppNavigationCaption): Add `heading-id` prop

src/components/NcAppNavigationCaption/NcAppNavigationCaption.vue

@@ -1,4 +1,6 @@
 <docs>
+### Basic usage
+
 ```vue
 	<template>
 		<ul class="nav">
@@ -95,14 +97,33 @@
 	</style>
 ```
 
+### Element used as a heading
+```vue
+	<template>
+		<!-- e.g. NcAppNavigation-->
+		<div style="display: flex; flex-direction: column;">
+			<NcAppNavigationCaption heading-id="mylist-heading"
+				is-heading
+				name="My navigation list" />
+			<NcAppNavigationList aria-labelledby="mylist-heading">
+				<NcAppNavigationItem name="First" />
+				<NcAppNavigationItem name="Second" />
+				<NcAppNavigationItem name="Third" />
+			</NcAppNavigationList>
+		</div>
+	</template>
+```
+
 </docs>
 
 <template>
 	<component :is="wrapperTag"
 		class="app-navigation-caption"
 		:class="{ 'app-navigation-caption--heading': isHeading }">
 		<!-- Name of the caption -->
-		<component :is="captionTag" class="app-navigation-caption__name">
+		<component :is="captionTag"
+			:id="headingId"
+			class="app-navigation-caption__name">
 			{{ name }}
 		</component>
 
@@ -138,6 +159,15 @@ export default {
 			required: true,
 		},
 
+		/**
+		 * `id` to set on the inner caption
+		 * Can be used for connecting the `NcActionCaption` with `NcActionList` using `aria-labelledby`.
+		 */
+		headingId: {
+			type: String,
+			default: null,
+		},
+
 		/**
 		 * Enable when used as a heading
 		 * e.g. Before NcAppNavigationList

tests/unit/components/NcAppNavigation/NcAppNavigation.spec.js

@@ -19,7 +19,6 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
-
 import { mount } from '@vue/test-utils'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { emit } from '@nextcloud/event-bus'

tests/unit/components/NcAppNavigation/NcAppNavigationCaption.spec.ts

@@ -22,53 +22,39 @@ describe('NcAppNavigationCaption.vue', () => {
 		expect(wrapper.findComponent({ name: 'NcActions' }).attributes('forcemenu')).toBe('true')
 	})
 
-	test('component is a list entry by default', async () => {
-		const wrapper = shallowMount(NcAppNavigationCaption, {
-			props: {
-				name: 'The name',
-			},
-		})
-
-		expect(wrapper.element.tagName).toBe('LI')
-		expect(wrapper.find('h2').exists()).toBe(false)
-		expect(wrapper.find('span').exists()).toBe(true)
-	})
-
-	test('component tags are adjusted when used as heading', async () => {
+	test('can set id on the caption', async () => {
 		const wrapper = shallowMount(NcAppNavigationCaption, {
 			props: {
 				name: 'The name',
 				isHeading: true,
+				headingId: 'my-heading-id',
 			},
 		})
 
-		expect(wrapper.element.tagName).toBe('DIV')
-		expect(wrapper.find('h2').exists()).toBe(true)
+		expect(wrapper.find('h2').attributes('id')).toBe('my-heading-id')
 	})
 
-	test('can set the heading level', async () => {
+	test('component is a list entry by default', async () => {
 		const wrapper = shallowMount(NcAppNavigationCaption, {
 			props: {
 				name: 'The name',
-				isHeading: true,
-				headingLevel: 3,
 			},
 		})
 
-		expect(wrapper.find('h3').exists()).toBe(true)
+		expect(wrapper.element.tagName).toBe('LI')
 		expect(wrapper.find('h2').exists()).toBe(false)
+		expect(wrapper.find('span').exists()).toBe(true)
 	})
 
-	test('does not set the heading level to h1', async () => {
+	test('component tags are adjusted when used as heading', async () => {
 		const wrapper = shallowMount(NcAppNavigationCaption, {
 			props: {
 				name: 'The name',
 				isHeading: true,
-				headingLevel: 1,
 			},
 		})
 
+		expect(wrapper.element.tagName).toBe('DIV')
 		expect(wrapper.find('h2').exists()).toBe(true)
-		expect(wrapper.find('h1').exists()).toBe(false)
 	})
 })