bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbDropdownButton.md

@@ -0,0 +1,629 @@
+# BbDropdownButton
+
+## Template & Script
+
+```vue
+<template>
+	<span
+		class="bb-dropdown-button"
+		:class="{
+			'bb-dropdown-button--block': block,
+			'bb-dropdown-button--loading': loading,
+			[`bb-dropdown-button--${theme}`]: true,
+		}"
+		v-bind="sizeAttributes"
+	>
+		<BaseButton v-bind="mainBtn" class="bb-dropdown-button__main-btn">
+			<BbSpinner class="bb-dropdown-button__spinner" />
+
+			<BbIcon
+				v-if="props['prepend:icon']"
+				class="bb-dropdown-button__prepend-icon"
+				:type="props['prepend:icon']"
+			/>
+			<span class="bb-dropdown-button__content">{{ mainBtn.text }}</span>
+			<span v-if="loading" class="bb-dropdown-button__loading-label sr-only">{{
+				t('common.loadingText').value
+			}}</span>
+
+			<BbIcon
+				v-if="props['append:icon']"
+				class="bb-dropdown-button__append-icon"
+				:type="props['append:icon']"
+			/>
+		</BaseButton>
+
+		<BbDropdown
+			:id="id"
+			:arrow-padding="arrowPadding"
+			:disabled="disabled"
+			:eager="eager"
+			:items="mappedItems"
+			:offset="offset"
+			:padding="padding"
+			:placement="placement"
+			:theme="theme"
+			:transition-duration="transitionDuration"
+			:width="width"
+		>
+			<template #activator="{ props, open, disabled, placement }">
+				<slot
+					:disabled="disabled"
+					name="activator"
+					:open="open"
+					:placement="placement"
+					:props="props"
+				>
+					<BaseButton v-bind="props" class="bb-dropdown-button__dropdown-btn">
+						<span class="bb-dropdown-button__dropdown-label sr-only">{{
+							open
+								? t('dropdownButton.close').value
+								: t('dropdownButton.open').value
+						}}</span>
+						<slot
+							:disabled="disabled"
+							name="right-btn"
+							:open="open"
+							:placement="placement"
+						>
+							<svg
+								class="bb-dropdown-button__dropdown-chevron"
+								viewBox="0 0 24 24"
+								xmlns="http://www.w3.org/2000/svg"
+							>
+								<path
+									d="M7.41 15.41L12 10.83l4.59 4.58L18 14l-6-6l-6 6l1.41 1.41Z"
+									fill="currentColor"
+								/>
+							</svg>
+						</slot>
+					</BaseButton>
+				</slot>
+			</template>
+			<template #prepend="data"><slot name="prepend" v-bind="data" /></template>
+			<template #item:prepend="data">
+				<slot name="item:prepend" v-bind="data" />
+			</template>
+			<!-- @vue-ignore - wrong inferred type -->
+			<template v-for="item in mappedItems" #[item.key]="data">
+				<slot :name="item.key" v-bind="data" />
+			</template>
+			<template #item:append="data">
+				<slot name="item:append" v-bind="data" />
+			</template>
+			<template #append="data"><slot name="append" v-bind="data" /></template>
+		</BbDropdown>
+	</span>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import BaseButton from '../BaseButton/BaseButton.vue';
+import BbDropdown from '../BbDropdown/BbDropdown.vue';
+import { ref } from 'vue';
+import { BbIcon, BbSpinner } from '@/index';
+import { useLocale } from '@/composables/useLocale';
+import type { BbDropdownButtonProps, BbDropdownButtonSlots } from './types';
+export type { BbDropdownButtonProps, BbDropdownButtonSlots };
+
+type Sizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+const props = withDefaults(defineProps<BbDropdownButtonProps>(), {
+	theme: 'default',
+	autoLoading: true,
+	disabledWhileLoading: true,
+});
+
+defineSlots<BbDropdownButtonSlots>();
+
+const { t } = useLocale();
+const internalLoading = ref(0);
+
+const loading = computed(
+	() => props.loading || (!!internalLoading.value && props.autoLoading)
+);
+
+const wrapClick =
+	(fn: (...args: any[]) => any) =>
+	async (...args: any[]) => {
+		if (loading.value && props.disabledWhileLoading) return;
+		internalLoading.value++;
+		await fn(...args);
+		internalLoading.value--;
+	};
+
+const mappedItems = computed(() =>
+	props.items.map((el) => {
+		if (el.onClick)
+			return {
+				...el,
+				key: el.key.split(/\W+/g).join('_').toLowerCase(),
+				onClick: wrapClick(el.onClick),
+			};
+		return {
+			...el,
+			key: el.key.split(/\W+/g).join('_').toLowerCase(),
+		};
+	})
+);
+
+const mainBtn = computed(() => {
+	const base = { ...mappedItems.value[0] };
+	base.disabled = base.disabled || props.disabled;
+	return base;
+});
+
+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;
+	},
+	{}
+);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { BbDropdownProps, MappedItem } from '../BbDropdown/types';
+import type { IconType } from '@/types/Icon';
+
+type Sizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export type BbDropdownButtonProps = Pick<
+	BbDropdownProps,
+	| 'arrowPadding'
+	| 'disabled'
+	| 'eager'
+	| 'id'
+	| 'items'
+	| 'offset'
+	| 'padding'
+	| 'placement'
+	| 'theme'
+	| 'transitionDuration'
+	| 'width'
+> & {
+	/**
+	 * Tracks the loading status internally.
+	 *
+	 * @defaultValue `true`
+	 */
+	autoLoading?: boolean;
+	/**
+	 * 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;
+	/**
+	 * Disables the click handler while the component is loading.
+	 *
+	 * @defaultValue `true`
+	 */
+	disabledWhileLoading?: boolean;
+	/**
+	 * Triggers a loading indicator.
+	 */
+	loading?: boolean;
+	/**
+	 * Icon to be added on the left of the text.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'prepend:icon'?: IconType;
+
+	/**
+	 * 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.
+	 */
+	size?:
+		| Sizes
+		| Partial<
+				Record<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'default', Sizes>
+		  >;
+};
+
+/** Props exposed by the `activator` slot. */
+export type BbDropdownButtonActivatorSlotProps = {
+	/** Spread onto the activator element to register the floating-UI anchor. */
+	props: object;
+	/** Whether the button is globally disabled. */
+	disabled?: boolean;
+	/** Whether the dropdown panel is currently open. */
+	open: boolean;
+	/** The current placement of the dropdown panel. */
+	placement: BbDropdownProps['placement'];
+};
+
+/** Props exposed by the `prepend` and `append` slots. */
+export type BbDropdownButtonEdgeSlotProps = {
+	/** Whether the button is globally disabled. */
+	disabled?: boolean;
+	/** Whether the dropdown panel is currently open. */
+	open: boolean;
+	/** The current placement of the dropdown panel. */
+	placement: BbDropdownProps['placement'];
+};
+
+/** Props exposed by item-level slots (`item:prepend`, `item:append`, and named item slots). */
+export type BbDropdownButtonItemSlotProps = {
+	/** Whether this item is disabled. */
+	disabled?: MappedItem['disabled'];
+	/** The zero-based index of this item. */
+	index: number;
+	/** The raw item object from the `items` prop. */
+	item: BbDropdownProps['items'][number];
+	/** Whether the dropdown panel is currently open. */
+	open: boolean;
+	/** The current placement of the dropdown panel. */
+	placement: BbDropdownProps['placement'];
+	/** The resolved display text for this item. */
+	text: MappedItem['text'];
+};
+
+/** Props exposed by the `right-btn` slot. */
+export type BbDropdownButtonRightBtnSlotProps = {
+	/** Whether the button is globally disabled. */
+	disabled?: boolean;
+	/** Whether the dropdown panel is currently open. */
+	open: boolean;
+	/** The current placement of the dropdown panel. */
+	placement: BbDropdownButtonProps['placement'];
+};
+
+export type BbDropdownButtonSlots = {
+	/**
+	 * The left-side trigger button content. Spread `props` onto your element to wire the anchor reference.
+	 */
+	activator?: (props: BbDropdownButtonActivatorSlotProps) => any;
+	/**
+	 * Content rendered before the first item in the dropdown panel.
+	 */
+	prepend?: (props: BbDropdownButtonEdgeSlotProps) => any;
+	/**
+	 * Content rendered before each dropdown item's default content.
+	 */
+	'item:prepend'?: (props: BbDropdownButtonItemSlotProps) => any;
+	/**
+	 * Content rendered after each dropdown item's default content.
+	 */
+	'item:append'?: (props: BbDropdownButtonItemSlotProps) => any;
+	/**
+	 * Content rendered after the last item in the dropdown panel.
+	 */
+	append?: (props: BbDropdownButtonEdgeSlotProps) => any;
+	/**
+	 * Replaces the right-side split button that toggles the dropdown.
+	 */
+	'right-btn'?: (props: BbDropdownButtonRightBtnSlotProps) => any;
+} & {
+	/**
+	 * Named slot for a specific item, identified by `item.key`. Replaces the item's default label content.
+	 */
+	[key: string]: (props: BbDropdownButtonItemSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-dropdown-button {
+	--color: var(--bb-primary);
+	--border-color: var(--color);
+	--text-color: var(--bb-contrasting);
+	--gap: 8px;
+	--px: 8px;
+	--py: 4px;
+	--ring-color: color-mix(
+		in srgb,
+		var(--color),
+		transparent calc(100% - var(--bb-ring-opacity) * 100%)
+	);
+	--font-size: 16px;
+	display: inline-grid;
+	grid-template-columns: 1fr min-content;
+	vertical-align: top;
+
+	&.bb-dropdown-button--block {
+		width: 100%;
+	}
+
+	&:not(.bb-dropdown-button--loading) {
+		.bb-dropdown-button__main-btn,
+		.bb-dropdown-button__dropdown-btn {
+			&:disabled {
+				background-color: gray;
+				color: color-mix(in srgb, var(--bb-text), transparent 20%);
+				opacity: 0.5;
+			}
+		}
+	}
+
+	&[data-xs] {
+		--bb-button-h: 28px;
+		--font-size: 12px;
+	}
+	&[data-sm] {
+		--bb-button-h: 32px;
+		--font-size: 14px;
+	}
+
+	&[data-md] {
+		--bb-button-h: 36px;
+		--font-size: 16px;
+	}
+
+	&[data-lg] {
+		--bb-button-h: 40px;
+		--font-size: 18px;
+	}
+
+	&[data-xl] {
+		--bb-button-h: 44px;
+		--font-size: 20px;
+	}
+
+	.bb-dropdown-button__main-btn,
+	.bb-dropdown-button__dropdown-btn {
+		align-items: center;
+		background-color: var(--color);
+		border-color: var(--border-color);
+		border-radius: var(--bb-radius);
+		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;
+		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;
+		transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+		vertical-align: top;
+
+		&:hover:not(: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;
+		}
+
+		&:disabled {
+			cursor: not-allowed;
+		}
+	}
+
+	&.bb-dropdown-button--loading {
+		.bb-spinner {
+			opacity: 1;
+
+			+ .bb-icon {
+				opacity: 0;
+			}
+
+			+ .bb-dropdown-button__content {
+				margin-left: calc(var(--gap) + var(--bb-button-icon));
+			}
+		}
+	}
+
+	.bb-dropdown-button__main-btn {
+		border-bottom-right-radius: 0px;
+		border-right: 1px solid
+			color-mix(in srgb, var(--bb-border), transparent 40%);
+		border-top-right-radius: 0px;
+	}
+	.bb-dropdown-button__dropdown-btn {
+		border-bottom-left-radius: 0px;
+		border-top-left-radius: 0px;
+		&[aria-expanded='false'] .bb-dropdown-button__dropdown-chevron {
+			transform: rotate(180deg);
+		}
+	}
+
+	.bb-dropdown-button__content {
+		transition: margin-left 0.3s;
+	}
+
+	.bb-spinner,
+	.bb-dropdown-button__icon,
+	.bb-dropdown-button__prepend-icon,
+	.bb-dropdown-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-dropdown-button__loading-label {
+	}
+
+	.bb-dropdown-button__dropdown-label {
+	}
+
+	.bb-dropdown-button__dropdown-chevron {
+		width: 16px;
+	}
+
+	.bb-dropdown {
+		display: inline-flex;
+	}
+
+	.bb-dropdown__wrapper {
+		display: inline-flex;
+	}
+}
+
+@media (min-width: 640px) {
+	.bb-dropdown-button {
+		&[data-sm\:xs] {
+			--bb-button-h: 28px;
+			--font-size: 12px;
+		}
+
+		&[data-sm\:sm] {
+			--bb-button-h: 32px;
+			--font-size: 14px;
+		}
+
+		&[data-sm\:md] {
+			--bb-button-h: 36px;
+			--font-size: 16px;
+		}
+
+		&[data-sm\:lg] {
+			--bb-button-h: 40px;
+			--font-size: 18px;
+		}
+		&[data-sm\:xl] {
+			--bb-button-h: 44px;
+			--font-size: 20px;
+		}
+	}
+}
+
+@media (min-width: 768px) {
+	.bb-dropdown-button {
+		&[data-md\:xs] {
+			--bb-button-h: 28px;
+			--font-size: 12px;
+		}
+
+		&[data-md\:sm] {
+			--bb-button-h: 32px;
+			--font-size: 14px;
+		}
+
+		&[data-md\:md] {
+			--bb-button-h: 36px;
+			--font-size: 16px;
+		}
+
+		&[data-md\:lg] {
+			--bb-button-h: 40px;
+			--font-size: 18px;
+		}
+		&[data-sm\:xl] {
+			--bb-button-h: 44px;
+			--font-size: 20px;
+		}
+	}
+}
+
+@media (min-width: 1024px) {
+	.bb-dropdown-button {
+		&[data-lg\:xs] {
+			--bb-button-h: 28px;
+			--font-size: 12px;
+		}
+
+		&[data-lg\:sm] {
+			--bb-button-h: 32px;
+			--font-size: 14px;
+		}
+
+		&[data-lg\:md] {
+			--bb-button-h: 36px;
+			--font-size: 16px;
+		}
+
+		&[data-lg\:lg] {
+			--bb-button-h: 40px;
+			--font-size: 18px;
+		}
+		&[data-lg\:xl] {
+			--bb-button-h: 44px;
+			--font-size: 20px;
+		}
+	}
+}
+
+@media (min-width: 1280px) {
+	.bb-dropdown-button {
+		&[data-xl\:xs] {
+			--bb-button-h: 28px;
+			--font-size: 12px;
+		}
+
+		&[data-xl\:sm] {
+			--bb-button-h: 32px;
+			--font-size: 14px;
+		}
+
+		&[data-xl\:md] {
+			--bb-button-h: 36px;
+			--font-size: 16px;
+		}
+
+		&[data-xl\:lg] {
+			--bb-button-h: 40px;
+			--font-size: 18px;
+		}
+		&[data-xl\:xl] {
+			--bb-button-h: 44px;
+			--font-size: 20px;
+		}
+	}
+}
+
+@media (min-width: 1536px) {
+	.bb-dropdown-button {
+		&[data-2xl\:xs] {
+			--bb-button-h: 28px;
+			--font-size: 12px;
+		}
+
+		&[data-2xl\:sm] {
+			--bb-button-h: 32px;
+			--font-size: 14px;
+		}
+
+		&[data-2xl\:md] {
+			--bb-button-h: 36px;
+			--font-size: 16px;
+		}
+
+		&[data-2xl\:lg] {
+			--bb-button-h: 40px;
+			--font-size: 18px;
+		}
+		&[data-2xl\:xl] {
+			--bb-button-h: 44px;
+			--font-size: 20px;
+		}
+	}
+}
+```