bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbButton.md

@@ -0,0 +1,687 @@
+# BbButton
+
+## Template & Script
+
+```vue
+<template>
+	<BaseButton
+		:ref="setButtonRef"
+		v-bind="propsToPass"
+		:aria-disabled="loading ? true : undefined"
+		:aria-pressed="isToggle ? isPressed : undefined"
+		:class="{
+			'bb-button': true,
+			'bb-button--loading': loading,
+			'bb-button--group': props.group,
+			'bb-button--icon': !!icon,
+			'bb-button--active': isToggle && isPressed,
+		}"
+		:disabled="disabled"
+		:tabindex="loading ? -1 : undefined"
+		@click="onClick"
+	>
+		<BbSpinner class="bb-button__spinner" />
+		<BbIcon
+			v-if="props['icon']"
+			class="bb-button__icon"
+			:type="props['icon']"
+		/>
+		<BbIcon
+			v-else-if="props['prepend:icon']"
+			class="bb-button__prepend-icon"
+			:type="props['prepend:icon']"
+		/>
+		<span class="bb-button__content" :class="{ 'sr-only': !!icon }"
+			><slot>{{ text }}</slot></span
+		>
+		<span v-if="loading" class="bb-button__loading-label sr-only">{{
+			t('common.loadingText')
+		}}</span>
+
+		<BbIcon
+			v-if="!icon && props['append:icon']"
+			class="bb-button__append-icon"
+			:type="props['append:icon']"
+		/>
+	</BaseButton>
+
+	<BbTooltipAsync
+		v-if="tooltip != null || $slots.tooltip"
+		:activator="buttonDom"
+		:placement="tooltipPlacement"
+		:show-close="false"
+		:timeout="tooltipTimeout"
+	>
+		<slot name="tooltip" :text="tooltip">{{ tooltip }}</slot>
+	</BbTooltipAsync>
+</template>
+
+<script setup lang="ts">
+import { BaseButton, BbSpinner } from '@/index';
+import BbIcon from '../BbIcon/BbIcon.vue';
+import { computed, defineAsyncComponent, ref, toRef, useAttrs } from 'vue';
+import { pickBy } from '@/utilities/functions/pickBy';
+import { noop } from '@/utilities/functions/noop';
+import { useLocale } from '@/composables/useLocale';
+import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import { isEqual } from '@/utilities/functions/isEqual';
+import type { BbButtonProps, BbButtonSlots } from './types';
+export type { BbButtonProps, BbButtonSlots };
+
+const BbTooltipAsync = defineAsyncComponent(
+	() => import('../BbTooltip/BbTooltip.vue')
+);
+
+type Sizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+defineOptions({
+	inheritAttrs: false,
+});
+
+const props = withDefaults(defineProps<BbButtonProps>(), {
+	falseValue: false,
+	size: 'md',
+	trueValue: true,
+});
+
+const modelValue = defineModel<unknown>();
+
+const isToggle = computed(() => modelValue.value !== undefined);
+const isPressed = computed(() => isEqual(modelValue.value, props.trueValue));
+
+defineSlots<BbButtonSlots>();
+
+const { t } = useLocale();
+const attrs = useAttrs();
+const buttonDom = ref<HTMLElement>();
+
+const setButtonRef = (el: unknown) => {
+	buttonDom.value = extractDomContainer(el) ?? undefined;
+};
+
+const forwardedAttrs = computed(() => {
+	const { onClick: _, ...rest } = attrs;
+	return rest;
+});
+
+const internalLoading = ref(0);
+
+const loading = computed(
+	() => props.loading || (!!internalLoading.value && props.autoLoading)
+);
+
+const disabled = computed(() => props.disabled);
+
+const onClick = async (event: Event) => {
+	if (loading.value && !props.enabledWhileLoading) {
+		// router-link doesn't allow for prevent default but the logic stays
+		if (props.type === 'submit' || props.href || props.to) {
+			event.preventDefault();
+		}
+		return null;
+	}
+	if (isToggle.value) {
+		const trueVal = props.trueValue;
+		const falseVal = props.falseValue;
+		modelValue.value = isEqual(modelValue.value, trueVal) ? falseVal : trueVal;
+	}
+	internalLoading.value++;
+	await ((attrs.onClick ?? noop) as (...args: any[]) => any)(event);
+	internalLoading.value--;
+};
+
+const baseSize: { default: Sizes } & Partial<Record<Sizes, Sizes>> =
+	typeof props.size === 'string'
+		? { default: props.size }
+		: { default: 'md', ...props.size };
+
+const sizeAttributes = Object.entries<Sizes>(baseSize).reduce(
+	(acc: Record<string, string>, [key, value]) => {
+		if (key === 'default') {
+			acc[`data-${value}`] = '';
+		} else {
+			acc[`data-${key}:${value}`] = '';
+		}
+		return acc;
+	},
+	{}
+);
+
+const propsToPass = toRef(() => ({
+	...forwardedAttrs.value,
+	...sizeAttributes,
+	...pickBy(
+		props,
+		(_, key) =>
+			![
+				'append:icon',
+				'autoLoading',
+				'disabled',
+				'enabledWhileLoading',
+				'falseValue',
+				'group',
+				'icon',
+				'loading',
+				'modelValue',
+				'prepend:icon',
+				'size',
+				'tooltip',
+				'tooltipPlacement',
+				'trueValue',
+			].includes(key)
+	),
+}));
+
+/**
+ * Redefined so current implementation of other components
+ * which leverage this component can still access the button
+ * DOM element
+ */
+defineExpose({ $el: buttonDom });
+</script>
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { RouteLocationRaw } from 'vue-router';
+import type { Placement } from '@floating-ui/vue';
+import type { IconType } from '@/types/Icon';
+
+type Sizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export type BbButtonProps = {
+	/**
+	 * Tracks the loading status internally.
+	 */
+	autoLoading?: boolean;
+	/**
+	 * Class to apply when the link is active.
+	 */
+	activeClass?: string;
+	/**
+	 * Value passed to the attribute `aria-current` when the link is exact active.
+	 *
+	 * @defaultValue `'page'`
+	 */
+	ariaCurrentValue?:
+		| 'page'
+		| 'step'
+		| 'location'
+		| 'date'
+		| 'time'
+		| 'true'
+		| 'false';
+	/**
+	 * Icon to be added on the right of the text.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'append:icon'?: IconType;
+	/**
+	 * Displays the component as full width.
+	 */
+	block?: boolean;
+
+	data?: object;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Disables the click handler while the component is loading.
+	 */
+	enabledWhileLoading?: boolean;
+
+	/**
+	 * Class to apply when the link is exact active.
+	 */
+	exactActiveClass?: string;
+
+	/**
+	 * Identifies the button as part of a button group.
+	 */
+	group?: boolean;
+
+	headers?: object;
+
+	/**
+	 * Returns the hyperlink's URL.
+	 *
+	 * Can be set, to change the URL.
+	 */
+	href?: HTMLAnchorElement['href'];
+	/**
+	 * Used when only an icon with no text should be displayed.
+	 */
+	icon?: IconType;
+
+	/**
+	 * Triggers a loading indicator.
+	 */
+	loading?: boolean;
+
+	method?: 'get' | 'post' | 'put' | 'patch' | 'delete';
+
+	onBefore?: () => void;
+
+	onCancel?: () => void;
+
+	onCancelToken?: (cancelToken: import('axios').CancelTokenSource) => void;
+
+	onFinish?: () => void;
+
+	only?: string[];
+
+	onProgress?: (progress: { percentage: number | undefined }) => void;
+
+	onStart?: () => void;
+
+	onSuccess?: () => void;
+
+	/**
+	 * Icon to be added on the left of the text.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'prepend:icon'?: IconType;
+
+	preserveScroll?: boolean | ((props: { [key: string]: unknown }) => boolean);
+
+	preserveState?:
+		| boolean
+		| ((props: { [key: string]: unknown }) => boolean)
+		| null;
+
+	queryStringArrayFormat?: 'brackets' | 'indices';
+
+	/**
+	 * Calls `router.replace` instead of `router.push`.
+	 */
+	replace?: boolean;
+
+	/**
+	 * Sets the size of the button. When the value is a string, it will be applied to all
+	 * screen sizes. Otherwise, it will be applied to the screen size specified by the object.
+	 *
+	 * @defaultValue `'md'`
+	 */
+	size?:
+		| Sizes
+		| Partial<
+				Record<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'default', Sizes>
+		  >;
+
+	/**
+	 * Any HTML tag corresponding to a non-void HTML element.
+	 */
+	tag?: string;
+
+	/**
+	 * Sets or retrieves the window or frame at which to target content.
+	 */
+	target?: HTMLAnchorElement['target'];
+
+	/**
+	 * Text content of the component.
+	 */
+	text?: string;
+
+	/**
+	 * Text content for a tooltip displayed on hover.
+	 * When provided, a {@link BbTooltip} is lazily loaded and attached to the button.
+	 */
+	tooltip?: string;
+
+	/**
+	 * Placement of the tooltip relative to the button.
+	 * Accepts any {@link Placement} value from Floating UI.
+	 *
+	 * @defaultValue `'top'`
+	 */
+	tooltipPlacement?: Placement;
+
+	/**
+	 * The delay in milliseconds before the tooltip is shown.
+	 *
+	 * @defaultValue `0`
+	 */
+	tooltipTimeout?: number;
+
+	/**
+	 * Route Location the link should navigate to when clicked on.
+	 */
+	to?: RouteLocationRaw;
+
+	/**
+	 * Value emitted when the toggle is activated.
+	 *
+	 * @defaultValue `true`
+	 */
+	trueValue?: any;
+
+	/**
+	 * Value emitted when the toggle is deactivated.
+	 *
+	 * @defaultValue `false`
+	 */
+	falseValue?: any;
+
+	/**
+	 * Gets the classification and default behavior of the button.
+	 */
+	type?: HTMLButtonElement['type'];
+};
+
+/** Props exposed by the `tooltip` slot. */
+export type BbButtonTooltipSlotProps = {
+	/** The `tooltip` prop value, or `undefined` if not set. */
+	text: string | undefined;
+};
+
+export type BbButtonSlots = {
+	/**
+	 * Primary content rendered inside the button. Falls back to the `text` prop when empty.
+	 */
+	default?: (props: object) => any;
+	/**
+	 * Custom content for the tooltip. Falls back to the {@link BbButtonProps.tooltip | tooltip} prop text.
+	 */
+	tooltip?: (props: BbButtonTooltipSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-button {
+	--color: var(--bb-primary);
+	--border-color: var(--color);
+	--text-color: var(--bb-contrasting);
+	--gap: 8px;
+	--px: 12px;
+	--py: 4px;
+	--ring-color: color-mix(
+		in srgb,
+		var(--color),
+		transparent calc(100% - var(--bb-ring-opacity) * 100%)
+	);
+	--font-size-xs: 12px;
+	--font-size-sm: 14px;
+	--font-size-md: 16px;
+	--font-size-lg: 18px;
+	--font-size-xl: 20px;
+	--bb-button-h-xs: 28px;
+	--bb-button-h-sm: 32px;
+	--bb-button-h-md: 36px;
+	--bb-button-h-lg: 40px;
+	--bb-button-h-xl: 44px;
+	align-items: center;
+	background-color: var(--color);
+	border-color: var(--border-color);
+	border-radius: var(--bb-radius);
+	border-width: 1px;
+	box-shadow: 0px 0px 0px 0px var(--bb-ring);
+	color: var(--text-color);
+	display: inline-flex;
+	font-size: var(--font-size);
+	font-weight: 500;
+	gap: var(--gap);
+	justify-content: center;
+	line-height: 1;
+	min-height: var(--bb-button-h);
+	padding-bottom: var(--py);
+	padding-left: var(--px);
+	padding-right: var(--px);
+	padding-top: var(--py);
+	transition: all 0.3s;
+	transition-duration: 150ms;
+	transition-property:
+		box-shadow, color, background-color, min-height, font-size;
+	transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+	vertical-align: top;
+
+	&[aria-pressed='true']:not(.base-btn--disabled) {
+		background-color: color-mix(in srgb, var(--color) 80%, black);
+	}
+
+	&:hover:not(.base-btn--disabled) {
+		background-color: color-mix(in srgb, var(--color) 90%, black);
+	}
+
+	&:focus-visible {
+		background-color: color-mix(in srgb, var(--color) 90%, black);
+		box-shadow: 0px 0px 0px var(--bb-ring-size) var(--ring-color);
+		outline: none;
+	}
+
+	&.base-btn--disabled {
+		cursor: not-allowed;
+
+		&:not(.bb-button--loading) {
+			--color: color-mix(in srgb, var(--bb-panel), var(--bb-text) 10%);
+			--text-color: color-mix(in srgb, var(--bb-panel), var(--bb-text) 40%);
+		}
+	}
+
+	&.bb-button--icon {
+		--px: var(--py);
+		min-width: var(--bb-button-h);
+	}
+
+	&.bb-button--loading {
+		.bb-spinner {
+			opacity: 1;
+
+			+ .bb-icon {
+				opacity: 0;
+			}
+
+			+ .bb-button__content {
+				margin-left: calc(var(--gap) + var(--bb-button-icon));
+			}
+		}
+	}
+
+	&.bb-button--group {
+		&:has(+ .bb-button--group) {
+			border-bottom-right-radius: 0;
+			border-top-right-radius: 0;
+		}
+
+		& + .bb-button--group {
+			border-bottom-left-radius: 0 !important;
+			border-top-left-radius: 0 !important;
+		}
+	}
+
+	&[data-xs] {
+		--bb-button-h: var(--bb-button-h-xs);
+		--font-size: var(--font-size-xs);
+	}
+	&[data-sm] {
+		--bb-button-h: var(--bb-button-h-sm);
+		--font-size: var(--font-size-sm);
+	}
+
+	&[data-md] {
+		--bb-button-h: var(--bb-button-h-md);
+		--font-size: var(--font-size-md);
+	}
+
+	&[data-lg] {
+		--bb-button-h: var(--bb-button-h-lg);
+		--font-size: var(--font-size-lg);
+	}
+
+	&[data-xl] {
+		--bb-button-h: var(--bb-button-h-xl);
+		--font-size: var(--font-size-xl);
+	}
+	.bb-button__content {
+		transition: margin-left 0.3s;
+	}
+
+	.bb-spinner,
+	.bb-button__icon,
+	.bb-button__prepend-icon,
+	.bb-button__append-icon {
+		color: currentColor;
+		display: inline-block;
+		flex-shrink: 0;
+		transition: opacity 0.3s;
+		width: var(--bb-button-icon);
+	}
+
+	.bb-spinner {
+		margin-right: calc((var(--gap) + var(--bb-button-icon)) * -1);
+		opacity: 0;
+	}
+
+	.bb-button__loading-label {
+	}
+}
+
+@media (min-width: 640px) {
+	.bb-button {
+		&[data-sm\:xs] {
+			--bb-button-h: var(--bb-button-h-xs);
+			--font-size: var(--font-size-xs);
+		}
+
+		&[data-sm\:sm] {
+			--bb-button-h: var(--bb-button-h-sm);
+			--font-size: var(--font-size-sm);
+		}
+
+		&[data-sm\:md] {
+			--bb-button-h: var(--bb-button-h-md);
+			--font-size: var(--font-size-md);
+		}
+
+		&[data-sm\:lg] {
+			--bb-button-h: var(--bb-button-h-lg);
+			--font-size: var(--font-size-lg);
+		}
+		&[data-sm\:xl] {
+			--bb-button-h: var(--bb-button-h-xl);
+			--font-size: var(--font-size-xl);
+		}
+	}
+}
+
+@media (min-width: 768px) {
+	.bb-button {
+		&[data-md\:xs] {
+			--bb-button-h: var(--bb-button-h-xs);
+			--font-size: var(--font-size-xs);
+		}
+
+		&[data-md\:sm] {
+			--bb-button-h: var(--bb-button-h-sm);
+			--font-size: var(--font-size-sm);
+		}
+
+		&[data-md\:md] {
+			--bb-button-h: var(--bb-button-h-md);
+			--font-size: var(--font-size-md);
+		}
+
+		&[data-md\:lg] {
+			--bb-button-h: var(--bb-button-h-lg);
+			--font-size: var(--font-size-lg);
+		}
+		&[data-md\:xl] {
+			--bb-button-h: var(--bb-button-h-xl);
+			--font-size: var(--font-size-xl);
+		}
+	}
+}
+
+@media (min-width: 1024px) {
+	.bb-button {
+		&[data-lg\:xs] {
+			--bb-button-h: var(--bb-button-h-xs);
+			--font-size: var(--font-size-xs);
+		}
+
+		&[data-lg\:sm] {
+			--bb-button-h: var(--bb-button-h-sm);
+			--font-size: var(--font-size-sm);
+		}
+
+		&[data-lg\:md] {
+			--bb-button-h: var(--bb-button-h-md);
+			--font-size: var(--font-size-md);
+		}
+
+		&[data-lg\:lg] {
+			--bb-button-h: var(--bb-button-h-lg);
+			--font-size: var(--font-size-lg);
+		}
+		&[data-lg\:xl] {
+			--bb-button-h: var(--bb-button-h-xl);
+			--font-size: var(--font-size-xl);
+		}
+	}
+}
+
+@media (min-width: 1280px) {
+	.bb-button {
+		&[data-xl\:xs] {
+			--bb-button-h: var(--bb-button-h-xs);
+			--font-size: var(--font-size-xs);
+		}
+
+		&[data-xl\:sm] {
+			--bb-button-h: var(--bb-button-h-sm);
+			--font-size: var(--font-size-sm);
+		}
+
+		&[data-xl\:md] {
+			--bb-button-h: var(--bb-button-h-md);
+			--font-size: var(--font-size-md);
+		}
+
+		&[data-xl\:lg] {
+			--bb-button-h: var(--bb-button-h-lg);
+			--font-size: var(--font-size-lg);
+		}
+		&[data-xl\:xl] {
+			--bb-button-h: var(--bb-button-h-xl);
+			--font-size: var(--font-size-xl);
+		}
+	}
+}
+
+@media (min-width: 1536px) {
+	.bb-button {
+		&[data-2xl\:xs] {
+			--bb-button-h: var(--bb-button-h-xs);
+			--font-size: var(--font-size-xs);
+		}
+
+		&[data-2xl\:sm] {
+			--bb-button-h: var(--bb-button-h-sm);
+			--font-size: var(--font-size-sm);
+		}
+
+		&[data-2xl\:md] {
+			--bb-button-h: var(--bb-button-h-md);
+			--font-size: var(--font-size-md);
+		}
+
+		&[data-2xl\:lg] {
+			--bb-button-h: var(--bb-button-h-lg);
+			--font-size: var(--font-size-lg);
+		}
+		&[data-2xl\:xl] {
+			--bb-button-h: var(--bb-button-h-xl);
+			--font-size: var(--font-size-xl);
+		}
+	}
+}
+```