From 33aeadf61988b59d10abced32683bf5689cd855c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?= <skjnldsv@protonmail.com>
Date: Thu, 5 Jan 2023 17:09:55 +0100
Subject: [PATCH] feat(AppNavigationItem): Rename title to name
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: John Molakvoæ <skjnldsv@protonmail.com>
---
 .../NcAppNavigationItem.vue                   | 92 +++++++++++++------
 1 file changed, 62 insertions(+), 30 deletions(-)

diff --git a/src/components/NcAppNavigationItem/NcAppNavigationItem.vue b/src/components/NcAppNavigationItem/NcAppNavigationItem.vue
index 245ebe482c..254502222b 100644
--- a/src/components/NcAppNavigationItem/NcAppNavigationItem.vue
+++ b/src/components/NcAppNavigationItem/NcAppNavigationItem.vue
@@ -38,7 +38,7 @@
 * With a spinning loader instead of the icon:
 
 ```
-<NcAppNavigationItem title="Loading Item" :loading="true" />
+<NcAppNavigationItem name="Loading Item" :loading="true" />
 ```
 
 ### Element with actions
@@ -47,7 +47,7 @@ button will be automatically created.
 
 ```
 <div id="app-navigation-vue"><!-- Just a wrapper necessary in the docs. Not needed when NcAppNavigation is correctly used as parent. -->
-	<NcAppNavigationItem title="Item with actions" icon="icon-category-enabled">
+	<NcAppNavigationItem name="Item with actions" icon="icon-category-enabled">
 		<template #actions>
 			<NcActionButton icon="icon-edit" @click="alert('Edit')">
 				Edit
@@ -65,7 +65,7 @@ button will be automatically created.
 Just nest the counter in a template within `<NcAppNavigationItem>` and add `#counter` to it.
 
 ```
-<NcAppNavigationItem title="Item with counter" icon="icon-folder">
+<NcAppNavigationItem name="Item with counter" icon="icon-folder">
 	<template #counter>
 		<NcCounterBubble>
 			99+
@@ -80,30 +80,30 @@ Wrap the children in a template with the `slot` property and use the prop `allow
 prevent the user from collapsing the items.
 
 ```
-<NcAppNavigationItem title="Item with children" :allowCollapse="true" :open="true">
+<NcAppNavigationItem name="Item with children" :allowCollapse="true" :open="true">
 	<template>
-		<NcAppNavigationItem title="AppNavigationItemChild1" />
-		<NcAppNavigationItem title="AppNavigationItemChild2" />
-		<NcAppNavigationItem title="AppNavigationItemChild3" />
-		<NcAppNavigationItem title="AppNavigationItemChild4" />
+		<NcAppNavigationItem name="AppNavigationItemChild1" />
+		<NcAppNavigationItem name="AppNavigationItemChild2" />
+		<NcAppNavigationItem name="AppNavigationItemChild3" />
+		<NcAppNavigationItem name="AppNavigationItemChild4" />
 	</template>
 </NcAppNavigationItem>
 ```
 
 ### Editable element
 Add the prop `:editable=true` and an edit placeholder if you need it. By default
-the placeholder is the previous title of the element.
+the placeholder is the previous name of the element.
 
 ```
-<NcAppNavigationItem title="Editable Item" :editable="true"
-	editPlaceholder="your_placeholder_here" icon="icon-folder" @update:title="function(value){alert(value)}" />
+<NcAppNavigationItem name="Editable Item" :editable="true"
+	editPlaceholder="your_placeholder_here" icon="icon-folder" @update:name="function(value){alert(value)}" />
 ```
 
 ### Undo element
-Just set the `undo` and `title` props. When clicking the undo button, an `undo` event is emitted.
+Just set the `undo` and `name` props. When clicking the undo button, an `undo` event is emitted.
 
 ```
-<NcAppNavigationItem :undo="true" title="Deleted important entry" @undo="alert('undo delete')"  />
+<NcAppNavigationItem :undo="true" name="Deleted important entry" @undo="alert('undo delete')"  />
 
 ```
 
@@ -111,17 +111,21 @@ Just set the `undo` and `title` props. When clicking the undo button, an `undo`
 Href that start by http will be treated as external and opened in a new tab
 ```
 <div>
-	<NcAppNavigationItem title="Files" href="/index.php/apps/files" />
-	<NcAppNavigationItem title="Nextcloud" href="https://nextcloud.com" />
+	<NcAppNavigationItem name="Files" href="/index.php/apps/files" />
+	<NcAppNavigationItem name="Nextcloud" href="https://nextcloud.com" />
 </div>
 ```
 
+### Custom title
+```
+<NcAppNavigationItem name="Nextcloud" title="Open the Nextcloud website" href="https://nextcloud.com" />
+```
+
 ### Pinned element
 Just set the `pinned` prop.
 ```
-<NcAppNavigationItem title="Pinned item" :pinned="true" />
+<NcAppNavigationItem name="Pinned item" :pinned="true" />
 ```
-
 </docs>
 
 <template>
@@ -140,17 +144,18 @@ Just set the `pinned` prop.
 				'active': isActive,
 			}"
 			class="app-navigation-entry">
-			<!-- Icon and title -->
+			<!-- Icon and name -->
 			<a v-if="!undo"
 				class="app-navigation-entry-link"
 				:aria-description="ariaDescription"
 				:aria-expanded="opened.toString()"
 				:href="href || '#'"
 				:target="isExternal(href) ? '_blank' : ''"
-				@focus="handleFocus"
+				:title="title || nameTitleFallback"
 				@blur="handleBlur"
-				@keydown.tab.exact="handleTab"
-				@click="onClick">
+				@click="onClick"
+				@focus="handleFocus"
+				@keydown.tab.exact="handleTab">
 
 				<!-- icon if not collapsible -->
 				<!-- never show the icon over the collapsible if mobile -->
@@ -159,13 +164,13 @@ Just set the `pinned` prop.
 					<NcLoadingIcon v-if="loading" />
 					<slot v-else-if="isIconShown" name="icon" />
 				</div>
-				<span v-if="!editingActive" class="app-navigation-entry__title" :title="title">
-					{{ title }}
+				<span v-if="!editingActive" class="app-navigation-entry__title">
+					{{ nameTitleFallback }}
 				</span>
 				<div v-if="editingActive" class="editingContainer">
 					<NcInputConfirmCancel ref="editingInput"
 						v-model="editingValue"
-						:placeholder="editPlaceholder !== '' ? editPlaceholder : title"
+						:placeholder="editPlaceholder !== '' ? editPlaceholder : nameTitleFallback"
 						@cancel="cancelEditing"
 						@confirm="handleEditingDone" />
 				</div>
@@ -175,7 +180,7 @@ Just set the `pinned` prop.
 			<!-- undo entry -->
 			<div v-if="undo" class="app-navigation-entry__deleted">
 				<div class="app-navigation-entry__deleted-description">
-					{{ title }}
+					{{ nameTitleFallback }}
 				</div>
 			</div>
 
@@ -265,11 +270,25 @@ export default {
 
 	props: {
 		/**
-		 * The title of the element.
+		 * The main text content of the entry.
+		 * Previously called `title`, now deprecated
+		 */
+		name: {
+			type: String,
+			// TODO: Make it required in the next major release (see title prop)
+			default: '',
+		},
+
+		/**
+		 * The title attribute of the element.
+		 *
+		 * ⚠ Using this prop as the main content text is DEPRECATED
+		 * Please use `name` instead. If you were planning to define the
+		 * html element title attribute, this is the proper way.
 		 */
 		title: {
 			type: String,
-			required: true,
+			default: null,
 		},
 
 		/**
@@ -336,7 +355,7 @@ export default {
 		},
 
 		/**
-		 * Makes the title of the item editable by providing an `ActionButton`
+		 * Makes the name of the item editable by providing an `ActionButton`
 		 * component that toggles a form
 		 */
 		editable: {
@@ -438,7 +457,7 @@ export default {
 	emits: [
 		'update:menuOpen',
 		'update:open',
-		'update:title',
+		'update:name',
 		'click',
 		'undo',
 	],
@@ -458,6 +477,17 @@ export default {
 	},
 
 	computed: {
+		/**
+		 * TODO: drop on the 8.0.0 major, see title/name prop
+		 */
+		nameTitleFallback() {
+			if (!this.name) {
+				console.warn('The `name` prop is required. Please migrate away from the deprecated `title` prop.')
+				return this.title
+			}
+			return this.name
+		},
+
 		collapsible() {
 			return this.allowCollapse && !!this.$slots.default
 		},
@@ -553,7 +583,7 @@ export default {
 
 		// Edition methods
 		handleEdit() {
-			this.editingValue = this.title
+			this.editingValue = this.nameTitleFallback
 			this.editingActive = true
 			this.onMenuToggle(false)
 			this.$nextTick(() => {
@@ -564,7 +594,9 @@ export default {
 			this.editingActive = false
 		},
 		handleEditingDone() {
+			// @deprecated, please use `name` instead
 			this.$emit('update:title', this.editingValue)
+			this.$emit('update:name', this.editingValue)
 			this.editingValue = ''
 			this.editingActive = false
 		},