feat(NcAppContent): Allow to set the page title

Sometimes - e.g. when you have multiple view - you want to adjust the page title,
that is shown as the browsers tab name. This adds a property to set that value.

Co-authored-by: Ferdinand Thiessen <[email protected]>
Co-authored-by: Grigorii K. Shartsev <[email protected]>
Signed-off-by: Ferdinand Thiessen <[email protected]>

Author: susnux

l10n/messages.pot

@@ -8,6 +8,9 @@ msgstr ""
 msgid "{tag} (restricted)"
 msgstr ""
 
+msgid "{view} - {app} - {product}"
+msgstr ""
+
 msgid "A color with a HEX value {hex}"
 msgstr ""
 

src/components/NcAppContent/NcAppContent.vue

@@ -50,6 +50,45 @@ The list size must be between the min and the max width value.
 	:list-max-width="45"
 >...</NcAppContent>
 ```
+
+#### Usage: Custom document title
+For accessibility reasons every document should have a `h1` heading,
+this is visually hidden, but required for a semantically correct document.
+You can use your app name or current view for the heading.
+
+Additionally you can set a custom document title, e.g. to show the current status.
+
+```vue
+<template>
+	<NcAppContent :pageHeading="heading ? 'Heading' : undefined" :pageTitle="title ? 'Title' : undefined" >
+		<NcCheckboxRadioSwitch type="switch" :checked.sync="title">
+			Toggle title
+		</NcCheckboxRadioSwitch>
+		<NcCheckboxRadioSwitch type="switch" :checked.sync="heading">
+			Toggle Heading
+		</NcCheckboxRadioSwitch>
+		<NcButton @click="reset">Reset</NcButton>
+	</NcAppContent>
+</template>
+
+<script>
+export default {
+	data() {
+		return {
+			heading: false,
+			title: false,
+		}
+	},
+	methods: {
+		reset() {
+			this.heading = false
+			this.title = false
+			document.title = ''
+		},
+	},
+}
+</script>
+```
 </docs>
 
 <template>
@@ -103,18 +142,22 @@ The list size must be between the min and the max width value.
 </template>
 
 <script>
-import NcAppDetailsToggle from './NcAppDetailsToggle.vue'
-import { useIsMobile } from '../../composables/useIsMobile/index.js'
-
 import { getBuilder } from '@nextcloud/browser-storage'
+import { emit } from '@nextcloud/event-bus'
+import { loadState } from '@nextcloud/initial-state'
 import { useSwipe } from '@vueuse/core'
 import { Splitpanes, Pane } from 'splitpanes'
+import { useIsMobile } from '../../composables/useIsMobile/index.js'
+import { isRtl } from '../../utils/rtl.ts'
+
+import NcAppDetailsToggle from './NcAppDetailsToggle.vue'
 
 import 'splitpanes/dist/splitpanes.css'
-import { emit } from '@nextcloud/event-bus'
-import { isRtl } from '../../utils/rtl.ts'
 
 const browserStorage = getBuilder('nextcloud').persist().build()
+const { name: productName } = loadState('theming', 'data', { name: 'Nextcloud' })
+const activeApp = loadState('core', 'active-app', appName)
+const localizedAppName = loadState('core', 'apps', {})[activeApp]?.name ?? appName
 
 /**
  * App content container to be used for the main content of your app
@@ -217,6 +260,18 @@ export default {
 				return ['no-split', 'vertical-split', 'horizontal-split'].includes(value)
 			},
 		},
+
+		/**
+		 * Allow setting the page's `<title>`
+		 *
+		 * If a page heading is set it defaults to `{pageHeading} - {appName} - {productName}` e.g. `Favorites - Files - Nextcloud`.
+		 * When the page heading and the app name is the same only one is used, e.g. `Files - Files - Nextcloud` is shown as `Files - Nextcloud`.
+		 * When setting the prop then the following format will be used: `{pageTitle} - {pageHeading || appName} - {productName}`
+		 */
+		pageTitle: {
+			type: String,
+			default: null,
+		},
 	},
 
 	emits: [
@@ -284,6 +339,37 @@ export default {
 				},
 			}
 		},
+
+		realPageTitle() {
+			const entries = new Set()
+			if (this.pageTitle) {
+				entries.add(this.pageTitle)
+			}
+			if (this.pageHeading) {
+				entries.add(this.pageHeading)
+			}
+			if (entries.size === 0) {
+				return null
+			}
+
+			if (entries.size < 2) {
+				// Only add if not already pageHeading and pageTitle are included
+				entries.add(localizedAppName)
+			}
+			entries.add(productName)
+			return [...entries.values()].join(' - ')
+		},
+	},
+
+	watch: {
+		realPageTitle: {
+			immediate: true,
+			handler() {
+				if (this.realPageTitle !== null) {
+					document.title = this.realPageTitle
+				}
+			},
+		},
 	},
 
 	updated() {

tests/unit/components/NcAppContent/NcAppContent.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from '@jest/globals'
+import { mount } from '@vue/test-utils'
+import NcAppContent from '../../../../src/components/NcAppContent/NcAppContent.vue'
+
+describe('NcAppContent', () => {
+	beforeEach(() => {
+		document.title = 'Initial title'
+	})
+
+	it('does not set a page heading by default', () => {
+		const wrapper = mount(NcAppContent)
+
+		expect(wrapper.find('h1').exists()).toBe(false)
+	})
+
+	it('can set the page heading', () => {
+		const wrapper = mount(NcAppContent, {
+			propsData: {
+				pageHeading: 'My heading',
+			},
+		})
+
+		expect(wrapper.find('h1').text()).toBe('My heading')
+	})
+
+	it('does not set the document title without page heading', () => {
+		mount(NcAppContent)
+
+		expect(document.title).toBe('Initial title')
+	})
+
+	it('sets the document title if a heading is provided', () => {
+		mount(NcAppContent, {
+			propsData: {
+				pageHeading: 'My heading',
+			},
+		})
+
+		expect(document.title).toBe('My heading - nextcloud-vue - Nextcloud')
+	})
+
+	it('does not duplicate the heading in the document title', () => {
+		mount(NcAppContent, {
+			propsData: {
+				pageHeading: 'nextcloud-vue',
+			},
+		})
+
+		expect(document.title).toBe('nextcloud-vue - Nextcloud')
+	})
+
+	it('sets the document title if pageTitle is provided', () => {
+		mount(NcAppContent, {
+			propsData: {
+				pageTitle: 'My title',
+			},
+		})
+
+		expect(document.title).toBe('My title - nextcloud-vue - Nextcloud')
+	})
+
+	it('does not duplicate the title in the document title', () => {
+		mount(NcAppContent, {
+			propsData: {
+				pageTitle: 'nextcloud-vue',
+			},
+		})
+
+		expect(document.title).toBe('nextcloud-vue - Nextcloud')
+	})
+
+	it('sets the document title if pageTitle and pageHeading are provided', () => {
+		mount(NcAppContent, {
+			propsData: {
+				pageHeading: 'My heading',
+				pageTitle: 'My title',
+			},
+		})
+
+		expect(document.title).toBe('My title - My heading - Nextcloud')
+	})
+})