From 562a8b7cdecc83b1826e84f140fc0ee9fabd8826 Mon Sep 17 00:00:00 2001
From: Ferdinand Thiessen <opensource@fthiessen.de>
Date: Wed, 29 Jan 2025 12:20:14 +0100
Subject: [PATCH] fixup! feat: Refactor `NcButton`

---
 src/components/NcButton/NcButton.vue | 288 ++++++---------------------
 src/components/NcButton/types.ts     | 148 +++++++++++++-
 src/utils/enumOrValue.ts             |  20 ++
 3 files changed, 228 insertions(+), 228 deletions(-)
 create mode 100644 src/utils/enumOrValue.ts

diff --git a/src/components/NcButton/NcButton.vue b/src/components/NcButton/NcButton.vue
index fd807e1a96..4ae62f2d28 100644
--- a/src/components/NcButton/NcButton.vue
+++ b/src/components/NcButton/NcButton.vue
@@ -38,7 +38,7 @@ It can be used with one or multiple actions.
 			:disabled="disabled"
 			:size="size"
 			:text="text"
-			type="tertiary-no-background">
+			variant="tertiary-no-background">
 			<template v-if="style.indexOf('icon') !== -1" #icon>
 				<Video
 					:size="20" />
@@ -49,7 +49,7 @@ It can be used with one or multiple actions.
 			:disabled="disabled"
 			:size="size"
 			:text="text"
-			type="tertiary">
+			variant="tertiary">
 			<template v-if="style.indexOf('icon') !== -1" #icon>
 				<Video
 					:size="20" />
@@ -70,7 +70,7 @@ It can be used with one or multiple actions.
 			:disabled="disabled"
 			:size="size"
 			:text="text"
-			type="primary">
+			variant="primary">
 			<template v-if="style.indexOf('icon') !== -1" #icon>
 				<Video
 					:size="20" />
@@ -103,7 +103,7 @@ It can be used with one or multiple actions.
 			:disabled="disabled"
 			:size="size"
 			text="Example text"
-			type="success">
+			variant="success">
 			<template #icon>
 				<Video
 					:size="20" />
@@ -113,7 +113,7 @@ It can be used with one or multiple actions.
 			:disabled="disabled"
 			:size="size"
 			text="Example text"
-			type="warning">
+			variant="warning">
 			<template #icon>
 				<Video
 					:size="20" />
@@ -123,7 +123,7 @@ It can be used with one or multiple actions.
 			:disabled="disabled"
 			:size="size"
 			text="Example text"
-			type="error">
+			variant="error">
 			<template #icon>
 				<Video
 					:size="20" />
@@ -196,36 +196,36 @@ Sometimes it is required to change the icon alignment on the button, like for sw
 ```vue
 <template>
 	<div style="display: flex; flex-direction: column; gap: 12px;">
-		<NcButton text="center (default)" type="secondary" wide>
+		<NcButton text="center (default)" variant="secondary" wide>
 			<template #icon>
 				<IconLeft :size="20" />
 			</template>
 		</NcButton>
-		<NcButton alignment="center-reverse" text="center-reverse" type="secondary" wide>
+		<NcButton alignment="center-reverse" text="center-reverse" variant="secondary" wide>
 			<template #icon>
 				<IconRight :size="20" />
 			</template>
 		</NcButton>
 		<div style="display: flex; gap: 12px;">
 			<div style="display: flex; flex-direction: column; gap: 12px; flex: 1">
-				<NcButton alignment="start" text="start" type="secondary" wide>
+				<NcButton alignment="start" text="start" variant="secondary" wide>
 					<template #icon>
 						<IconLeft :size="20" />
 					</template>
 				</NcButton>
-				<NcButton alignment="start-reverse" text="start-reverse" type="secondary" wide>
+				<NcButton alignment="start-reverse" text="start-reverse" variant="secondary" wide>
 					<template #icon>
 						<IconRight :size="20" />
 					</template>
 				</NcButton>
 			</div>
 			<div style="display: flex; flex-direction: column; gap: 12px; flex: 1">
-				<NcButton alignment="end" text="end" type="secondary" wide>
+				<NcButton alignment="end" text="end" variant="secondary" wide>
 					<template #icon>
 						<IconLeft :size="20" />
 					</template>
 				</NcButton>
-				<NcButton alignment="end-reverse" text="end-reverse" type="secondary" wide>
+				<NcButton alignment="end-reverse" text="end-reverse" variant="secondary" wide>
 					<template #icon>
 						<IconRight :size="20" />
 					</template>
@@ -250,7 +250,7 @@ export default {
 ### Pressed state
 
 It is possible to make the button stateful by adding a pressed state, e.g. if you like to create a favorite button.
-The button will have the required `aria` attribute for accessibility and visual style (`primary` when pressed, and the configured type otherwise).
+The button will have the required `aria` attribute for accessibility and visual style (`primary` when pressed, and the configured variant otherwise).
 
 Do not change `text` or `aria-label` of the pressed/unpressed button. See: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed
 
@@ -258,13 +258,13 @@ Do not change `text` or `aria-label` of the pressed/unpressed button. See: https
 <template>
 	<div>
 		<div style="display: flex; gap: 12px;">
-			<NcButton v-model:pressed="isFavorite" aria-label="Favorite" type="tertiary-no-background">
+			<NcButton v-model:pressed="isFavorite" aria-label="Favorite" variant="tertiary-no-background">
 				<template #icon>
 					<IconStar v-if="isFavorite" :size="20" />
 					<IconStarOutline v-else :size="20" />
 				</template>
 			</NcButton>
-			<NcButton v-model:pressed="isFavorite" text="Favorite" type="tertiary">
+			<NcButton v-model:pressed="isFavorite" text="Favorite" variant="tertiary">
 				<template #icon>
 					<IconStar v-if="isFavorite" :size="20" />
 					<IconStarOutline v-else :size="20" />
@@ -331,7 +331,7 @@ The standard way to implement sortable table column headers should be like this:
 				<th :aria-sorted="sortedName" class="row-name">
 					<NcButton alignment="start-reverse"
 						:wide="true"
-						type="tertiary"
+						variant="tertiary"
 						@click="sortName">
 						<template #icon>
 							<IconDown v-if="sortedName === 'ascending'" class="sort-icon" :size="20" />
@@ -343,7 +343,7 @@ The standard way to implement sortable table column headers should be like this:
 				<th :aria-sorted="sortedSize" class="row-size">
 					<NcButton alignment="end"
 						:wide="true"
-						type="tertiary"
+						variant="tertiary"
 						@click="sortSize">
 						<template #icon>
 							<IconDown v-if="sortedSize === 'ascending'" class="sort-icon" :size="20" />
@@ -438,7 +438,7 @@ td.row-size {
 			'button-vue',
 			`button-vue--size-${size}`,
 			{
-				[`button-vue--vue-${realType}`]: realType,
+				[`button-vue--${realVariant}`]: realVariant,
 				'button-vue--wide': wide,
 				[`button-vue--${flexAlignment}`]: flexAlignment !== 'center',
 				'button-vue--reverse': isReverseAligned,
@@ -468,196 +468,30 @@ td.row-size {
 </template>
 
 <script setup lang="ts">
-import type { PropType, Slot } from 'vue'
+import type { NcButtonEvents, NcButtonProps, NcButtonSlots } from './types.ts'
 
-import { ButtonAlignment, ButtonNativeType, ButtonType } from './types'
 import { computed, inject, toRef, watch } from 'vue'
 import { routerKey, useLink } from 'vue-router'
 import isSlotPopulated from '../../utils/isSlotPopulated'
 import logger from '../../utils/logger'
 
-const props = defineProps({
-	/**
-	 * Set the text and icon alignment
-	 *
-	 * @default 'center'
-	 * @type {'start' | 'start-reverse' | 'center' | 'center-reverse' | 'end' | 'end-reverse'}
-	 */
-	 alignment: {
-		type: String as PropType<ButtonAlignment>,
-		default: ButtonAlignment.Center,
-		validator(value: string) {
-			return Object.values(ButtonAlignment).includes(value as ButtonAlignment)
-		},
-	},
-
-	/**
-	 * By default the icon is set to `aria-hidden="true"` to hide it from the accessibility tree.
-	 * But sometimes this is not desired, e.g. for a loading icon with an accessible name,
-	 * setting this prop will make the icon appear in the accessible tree.
-	 * @default false
-	 * @since 9.0.0
-	 */
-	noIconAriaHidden: {
-		type: Boolean,
-		default: false,
-	},
-
-	/**
-	 * Toggles the disabled state of the button on and off.
-	 */
-	disabled: {
-		type: Boolean,
-		default: false,
-	},
-
-	/**
-	 * Specify the button size
-	 * Accepted values: `'small'`, `'normal'` (default), `'large'`
-	 */
-	size: {
-		type: String,
-		default: 'normal',
-		validator(value: string) {
-			return ['small', 'normal', 'large'].includes(value)
-		},
-	},
-
-	/**
-	 * The main button text.
-	 * This can be overwritten by using the *default* slot.
-	 * @since 9.0.0
-	 */
-	text: {
-		type: String,
-		default: '',
-	},
-
-	/**
-	 * Specifies the button type
-	 * If left empty, the default button style will be applied.
-	 *
-	 * @default 'secondary'
-	 * @type {'primary' | 'secondary' | 'tertiary' | 'tertiary-no-background' | 'tertiary-on-primary' | 'error' | 'warning' | 'success'}
-	 */
-	type: {
-		type: String as PropType<ButtonType>,
-		default: ButtonType.Secondary,
-		validator(value: string) {
-			return Object.values(ButtonType).includes(value as ButtonType)
-		},
-	},
-
-	/**
-	 * Specifies the button native type
-	 * If left empty, the default "button" type will be used.
-	 *
-	 * @default 'button'
-	 * @type {'submit' | 'reset' | 'button'}
-	 */
-	nativeType: {
-		type: String as PropType<ButtonNativeType>,
-		default: ButtonNativeType.Button,
-		validator(value: string) {
-			return Object.values(ButtonNativeType).includes(value as ButtonNativeType)
-		},
-	},
-
-	/**
-	 * Specifies whether the button should span all the available width.
-	 * By default, buttons span the whole width of the container.
-	 */
-	wide: {
-		type: Boolean,
-		default: false,
-	},
-
-	/**
-	 * Always try to provide an aria-label to your button. Make it more
-	 * specific than the button's name by provide some more context. E.g. if
-	 * the name of the button is "send" in the Mail app, the aria label could
-	 * be "Send email".
-	 */
-	ariaLabel: {
-		type: String,
-		default: null,
-	},
-
-	/**
-	 * Providing the href attribute turns the button component into an `a`
-	 * element.
-	 */
-	href: {
-		type: String,
-		default: null,
-	},
-
-	/**
-	 * Target for the `a` element if `href` is set.
-	 * @default '_self'
-	 */
-	target: {
-		type: String,
-		default: '_self',
-	},
-
-	/**
-	 * Providing the download attribute with href downloads file when clicking.
-	 */
-	download: {
-		type: String,
-		default: null,
-	},
-
-	/**
-	 * The pressed state of the button if it has a checked state
-	 * This will add the `aria-pressed` attribute and for the button to have the primary style in checked state.
-	 *
-	 * Pressed state is not supported for links
-	 */
-	pressed: {
-		type: Boolean,
-		default: null,
-	},
-
-	/**
-	 * Providing the to attribute turns the button component into a `router-link`
-	 * element. Takes precedence over the href attribute.
-	 */
-	to: {
-		type: [String, Object],
-		default: null,
-	},
+const props = withDefaults(defineProps<NcButtonProps>(), {
+	alignment: 'center',
+	size: 'normal',
+	type: 'button',
+	variant: 'secondary',
 })
 
-const emit = defineEmits<{
-	(e: 'click', event: MouseEvent): void
-	/**
-	 * Update the current pressed state of the button (if the `pressed` property was configured)
-	 */
-	(e: 'update:pressed', pressed: boolean): void
-}>()
-
-const slots = defineSlots<{
-	/**
-	 * Custom button content.
-	 * This can be used for custom formatted content, ensure to not include any interactive elements.
-	 * For plain text it is preferred to use the `text` prop instead.
-	 */
-	default?: Slot
-
-	/**
-	 * Icon (optional) to show within the button
-	 */
-	icon?: Slot
-}>()
+const emit = defineEmits<NcButtonEvents>()
+const slots = defineSlots<NcButtonSlots>()
 
 // Make sure the component also works if the app does not use any router
 // And if the app uses a router we need to make sure a `to` prop was passed to use to router
-const routerLink = computed(() => inject(routerKey, null) !== null && props.to
-	? useLink({ to: toRef(() => props.to) })
-	: undefined,
-)
+const routerLink = computed(() => (
+	inject(routerKey, null) !== null && props.to
+		? useLink({ to: toRef(() => props.to as Required<typeof props.to>) })
+		: undefined
+))
 
 /**
  * If this is a link (<a>) element
@@ -670,19 +504,19 @@ const isLink = computed(() => props.href)
 const hasPressedState = computed(() => !isLink.value && typeof props.pressed === 'boolean')
 
 /**
- * The real type to be used for the button, enforces `primary` for pressed state and, if stateful button, any other type for not pressed state
+ * The real variant to be used for the button, enforces `primary` for pressed state and, if stateful button, any other type for not pressed state
  * Otherwise the type property is used.
  */
-const realType = computed(() => {
+const realVariant = computed(() => {
 	// Force *primary* when pressed
 	if (props.pressed) {
 		return 'primary'
 	}
 	// If not pressed but button is configured as stateful button then the type must not be primary
-	if (props.pressed === false && props.type === 'primary') {
+	if (props.pressed === false && props.variant === 'primary') {
 		return 'secondary'
 	}
-	return props.type
+	return props.variant
 })
 
 /**
@@ -714,7 +548,7 @@ const linkAttrs = computed(() => ({
  */
 const buttonAttrs = computed(() => ({
 	'aria-pressed': hasPressedState.value ? String(props.pressed) : undefined,
-	type: props.nativeType,
+	type: props.type,
 }))
 
 /**
@@ -792,6 +626,8 @@ watch(
 	width: fit-content;
 	overflow: hidden;
 	border: 0;
+	border-radius: var(--button-radius);
+	cursor: pointer;
 	padding-block: 0;
 	padding-inline: var(--button-padding);
 	font-size: var(--default-font-size);
@@ -801,36 +637,38 @@ watch(
 	display: flex;
 	align-items: center;
 	justify-content: center;
+	// Transition styles for hover and pressed toggle
+	transition-property: color, border-color, background-color;
+	transition-duration: var(--animation-quick);
+	transition-timing-function: linear;
+	// Default button type
+	color: var(--color-primary-element-light-text);
+	background-color: var(--color-primary-element-light);
 
-	// Cursor pointer on element and all children
-	cursor: pointer;
-	& *,
-	span {
+	// Also apply the Cursor pointer on element and all children
+	:deep(*) {
 		cursor: pointer;
 	}
-	border-radius: var(--button-radius);
-	transition-property: color, border-color, background-color;
-	transition-duration: 0.1s;
-	transition-timing-function: linear;
 
 	// No outline feedback for focus. Handled with a toggled class in js (see data)
 	&:focus {
 		outline: none;
 	}
 
+	// Disabled styles
 	&:disabled {
+		// Gives a wash out effect
+		filter: saturate($opacity_normal);
+		opacity: $opacity_disabled;
+
+		// Reset the cursor
 		cursor: default;
-		& * {
+		:deep(*) {
 			cursor: default;
 		}
-		opacity: $opacity_disabled;
-		// Gives a wash out effect
-		filter: saturate($opacity_normal);
 	}
 
-	// Default button type
-	color: var(--color-primary-element-light-text);
-	background-color: var(--color-primary-element-light);
+	// Hover styles when not disabled (for the default theming of 'secondary')
 	&:hover:not(:disabled) {
 		background-color: var(--color-primary-element-light-hover);
 	}
@@ -925,7 +763,7 @@ watch(
 	// Button types
 
 	// Primary
-	&--vue-primary {
+	&--primary {
 		background-color: var(--color-primary-element);
 		color: var(--color-primary-element-text);
 		&:hover:not(:disabled) {
@@ -939,7 +777,7 @@ watch(
 	}
 
 	// Secondary
-	&--vue-secondary {
+	&--secondary {
 		color: var(--color-primary-element-light-text);
 		background-color: var(--color-primary-element-light);
 		&:hover:not(:disabled) {
@@ -949,7 +787,7 @@ watch(
 	}
 
 	// Tertiary
-	&--vue-tertiary {
+	&--tertiary {
 		color: var(--color-main-text);
 		background-color: transparent;
 		&:hover:not(:disabled) {
@@ -958,7 +796,7 @@ watch(
 	}
 
 	// Tertiary, no background
-	&--vue-tertiary-no-background {
+	&--tertiary-no-background {
 		color: var(--color-main-text);
 		background-color: transparent;
 		&:hover:not(:disabled) {
@@ -967,7 +805,7 @@ watch(
 	}
 
 	// Tertiary on primary color (like the header)
-	&--vue-tertiary-on-primary {
+	&--tertiary-on-primary {
 		color: var(--color-primary-element-text);
 		background-color: transparent;
 
@@ -977,7 +815,7 @@ watch(
 	}
 
 	// Success
-	&--vue-success {
+	&--success {
 		background-color: var(--color-success);
 		color: white;
 		&:hover:not(:disabled) {
@@ -991,7 +829,7 @@ watch(
 	}
 
 	// Warning
-	&--vue-warning {
+	&--warning {
 		background-color: var(--color-warning);
 		color: white;
 		&:hover:not(:disabled) {
@@ -1005,7 +843,7 @@ watch(
 	}
 
 	// Error
-	&--vue-error {
+	&--error {
 		background-color: var(--color-error);
 		color: white;
 		&:hover:not(:disabled) {
diff --git a/src/components/NcButton/types.ts b/src/components/NcButton/types.ts
index 551a35c221..d570f2c1c6 100644
--- a/src/components/NcButton/types.ts
+++ b/src/components/NcButton/types.ts
@@ -1,8 +1,12 @@
-/**
+/*!
  * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
+import type { Slot } from 'vue'
+import type { RouteLocation } from 'vue-router'
+import type { EnumOrValue } from '../../utils/enumOrValue.ts'
+
 export enum ButtonAlignment {
 	Start = 'start',
 	StartReverse = 'start-reverse',
@@ -12,13 +16,19 @@ export enum ButtonAlignment {
 	EndReverse = 'end-reverse',
 }
 
-export enum ButtonNativeType {
+export enum ButtonSize {
+	Small = 'small',
+	Normal = 'normal',
+	Large = 'large',
+}
+
+export enum ButtonType {
 	Submit = 'submit',
 	Reset = 'reset',
 	Button = 'button',
 }
 
-export enum ButtonType {
+export enum ButtonVariant {
 	Primary = 'primary',
 	Secondary = 'secondary',
 	Tertiary = 'tertiary',
@@ -31,3 +41,135 @@ export enum ButtonType {
 	Warning = 'warning',
 	Success = 'success',
 }
+
+export interface NcButtonProps {
+	/**
+	 * Set the text and icon alignment
+	 *
+	 * @default ButtonAlignment.Center
+	 */
+	alignment?: EnumOrValue<ButtonAlignment>
+
+	/**
+	 * By default the icon is set to `aria-hidden="true"` to hide it from the accessibility tree.
+	 * But sometimes this is not desired, e.g. for a loading icon with an accessible name,
+	 * setting this prop will make the icon appear in the accessible tree.
+	 * @default false
+	 * @since 9.0.0
+	 */
+	noIconAriaHidden?: boolean
+
+	/**
+	 * Toggles the disabled state of the button on and off.
+	 * @default false
+	 */
+	disabled?: boolean
+
+	/**
+	 * Specify the button size.
+	 * @default 'normal'
+	 */
+	size?: EnumOrValue<ButtonSize>
+
+	/**
+	 * The main button text.
+	 * This can be overwritten by using the *default* slot.
+	 * @since 9.0.0
+	 */
+	text?: string
+
+	/**
+	 * Specifies the button variant.
+	 * If left empty, the default button style will be applied.
+	 *
+	 * @default 'secondary'
+	 */
+	variant?: EnumOrValue<ButtonVariant>
+
+	/**
+	 * Specifies the button native type
+	 * If left empty, the default "button" type will be used.
+	 *
+	 * @default 'button'
+	 */
+	type?: EnumOrValue<ButtonType>
+
+	/**
+	 * Specifies whether the button should span all the available width.
+	 * By default, buttons span the whole width of the container.
+	 * @default false
+	 */
+	wide?: boolean
+
+	/**
+	 * Always try to provide an aria-label to your button.
+	 *
+	 * Make it more specific than the button's name by provide some more context.
+	 * E.g. if the name of the button is "send" in the Mail app,
+	 * the aria label could be "Send email".
+	 */
+	ariaLabel?: string
+
+	/**
+	 * Providing the href attribute turns the button component into an `a` element.
+	 */
+	href?: string
+
+	/**
+	 * Target for the `a` element if `href` is set.
+	 * @default '_self'
+	 */
+	target?: string
+
+	/**
+	 * When `href` is set this will make the browser try to download the target.
+	 * If a string is passed the browser will use it as the filename.
+	 *
+	 * Note that the browser might adjust it for allowed characters (e.g. '/' or '\').
+	 * Also this only works with same-origin URLs and `blob:` or `data:` schemas.
+	 * Moreover a `Content-Disposition` header set by the server will override the filename.
+	 */
+	download?: string|true
+
+	/**
+	 * The pressed state of the button if it has a checked state.
+	 * This will add the `aria-pressed` attribute and for the button to have the primary style in checked state.
+	 *
+	 * Note: Pressed state is not supported for links.
+	 */
+	pressed?: boolean
+
+	/**
+	 * Providing the to attribute turns the button component into a `router-link` element.
+	 *
+	 * Note: This takes precedence over the href attribute.
+	 */
+	to?: string | RouteLocation
+}
+
+export interface NcButtonEvents {
+	/**
+	 * Emitted when the button was clicked.
+	 */
+	click: [e: MouseEvent]
+
+	/**
+	 * If the button is a toggle button (`pressed` state is boolean),
+	 * then this will be emitted if the user toggled the state.
+	 */
+	'update:pressed': [pressed: boolean]
+}
+
+export interface NcButtonSlots {
+	/**
+	 * Custom button content.
+	 * This can be used for custom formatted content, ensure to not include any interactive elements.
+	 * For plain text it is preferred to use the `text` prop instead.
+	 */
+	default?: Slot
+
+	/**
+	 * Icon (optional) to show within the button
+	 */
+	icon?: Slot
+}
diff --git a/src/utils/enumOrValue.ts b/src/utils/enumOrValue.ts
new file mode 100644
index 0000000000..c5d1771a72
--- /dev/null
+++ b/src/utils/enumOrValue.ts
@@ -0,0 +1,20 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+/**
+ * Helper to allow either the enum T or its string variant.
+ *
+ * @example ```ts
+ * enum Foo {
+ *   A = 'a',
+ *   B = 'b',
+ * }
+ * // The type will be: Foo | 'a' | 'b'
+ * let foo: EnumOrValue<Foo>
+ * // The type is only `Foo` - thus passing 'a' or 'b' is invalid
+ * let bar: Foo
+ * ```
+ */
+export type EnumOrValue<T extends string> = T | `${T}`