Merge pull request #5285 from nextcloud-libraries/feat/app-sidebar-ad…

…d-subname-slot
nextcloud-libraries · Feb 22, 2024 · 12b5a90 · 12b5a90
2 parents 26a086c + d84e3d5
commit 12b5a90
Show file tree

Hide file tree

Showing 2 changed files with 83 additions and 9 deletions.
diff --git a/src/components/NcAppSidebar/NcAppSidebar.vue b/src/components/NcAppSidebar/NcAppSidebar.vue
@@ -312,6 +312,36 @@ export default {
 </script>
 ```
 
+### Custom subname
+
+Instead of using the `subname` prop you can use the same called slot. This is handy if you need to add accessible information.
+Like in the following example where the goal is to show a star icon to mark the file a favorite.
+Simplying adding `★` would not work as screen readers might not or wrongly announce the icon meaning this information is lost.
+
+A working alternative would be using an icon together with an `aria-label`:
+
+```vue
+	<template>
+		<NcAppSidebar name="cat-picture.jpg">
+			<template #subname>
+				<NcIconSvgWrapper inline :path="mdiStar" name="Favorite" />
+				123 KiB, a month ago
+			</template>
+		</NcAppSidebar>
+	</template>
+	<script>
+	import { mdiStar } from '@mdi/js'
+
+	export default {
+		setup() {
+			return {
+				mdiStar,
+			}
+		}
+	}
+	</script>
+```
+
 ### Empty sidebar for e.g. empty content component.
 
 ```vue
@@ -443,11 +473,13 @@ export default {
 								</NcActions>
 							</div>
 							<!-- secondary name -->
-							<p v-if="subname.trim() !== ''"
-								:aria-label="subtitle"
-								:title="subtitle"
+							<p v-if="subname.trim() !== '' || $slots['subname']"
+								:title="subtitle || undefined"
 								class="app-sidebar-header__subname">
-								{{ subname }}
+								<!-- @slot Alternative to the `subname` prop can be used for more complex conent. It will be rendered within a `p` tag. -->
+								<slot name="subname">
+									{{ subname }}
+								</slot>
 							</p>
 						</div>
 					</div>
@@ -1163,9 +1195,13 @@ $top-buttons-spacing: 6px;
 
 				// subname
 				.app-sidebar-header__subname {
-					padding: 0;
-					opacity: $opacity_normal;
+					color: var(--color-text-maxcontrast);
 					font-size: var(--default-font-size);
+					padding: 0;
+
+					* {
+						vertical-align: text-bottom;
+					}
 				}
 			}
 		}

diff --git a/src/components/NcIconSvgWrapper/NcIconSvgWrapper.vue b/src/components/NcIconSvgWrapper/NcIconSvgWrapper.vue
@@ -25,7 +25,7 @@
 
 Render raw SVG string icons.
 
-### Example
+### Usage within `icon`-slot
 
 ```vue
 <template>
@@ -66,7 +66,8 @@ import { mdiSend } from '@mdi/js'
 import { mdiStar } from '@mdi/js'
 
 export default {
-	data() {
+	setup() {
+		// This icons are static data, so you do not need to put them into `data` which will make them reactive
 		return {
 			closeSvg,
 			cogSvg,
@@ -86,6 +87,27 @@ export default {
 }
 </style>
 ```
+
+### Inline usage inside text
+
+```vue
+<template>
+	<p>
+		This is my <NcIconSvgWrapper inline :path="mdiStar" /> Favorite
+	</p>
+</template>
+<script>
+import { mdiStar } from '@mdi/js'
+
+export default {
+	setup() {
+		return {
+			mdiStar,
+		}
+	},
+}
+</script>
+```
 </docs>
 
 <template>
@@ -108,6 +130,15 @@ export default {
 	name: 'NcIconSvgWrapper',
 
 	props: {
+		/**
+		 * Set if the icon should be used as inline content e.g. within text.
+		 * By default the icon is made a block element for use inside `icon`-slots.
+		 */
+		inline: {
+			type: Boolean,
+			default: false,
+		},
+
 		/**
 		 * Raw SVG string to render
 		 */
@@ -174,7 +205,7 @@ export default {
 		},
 		attributes() {
 			return {
-				class: 'icon-vue',
+				class: ['icon-vue', { 'icon-vue--inline': this.inline }],
 				role: 'img',
 				'aria-hidden': !this.name ? true : undefined,
 				'aria-label': this.name || undefined,
@@ -193,6 +224,13 @@ export default {
 	min-height: 44px;
 	opacity: 1;
 
+	&--inline {
+		display: inline-flex;
+		min-width: fit-content;
+		min-height: fit-content;
+		vertical-align: text-bottom;
+	}
+
 	&:deep(svg) {
 		fill: currentColor;
 		width: v-bind('iconSize');