bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbPopover.md

@@ -0,0 +1,580 @@
+# BbPopover
+
+## Template & Script
+
+```vue
+<template>
+	<slot
+		v-if="!hasExternalActivator"
+		name="activator"
+		v-bind="{
+			props: activatorProps,
+			disabled: !!disabled,
+			isOpen,
+			placement,
+		}"
+	/>
+
+	<CommonPopover
+		:id="popoverId"
+		ref="popoverRef"
+		v-model="isOpen"
+		:anchor="effectiveAnchor"
+		:aria-labelledby="hasOpenedOnce ? activatorId : undefined"
+		:arrow-padding="arrowPadding"
+		:boundary="boundary"
+		class="bb-popover"
+		:class="`bb-popover--${theme}`"
+		dialog
+		:eager="eager"
+		:offset="offset"
+		:hide-arrow="placement === 'cursor'"
+		:padding="padding"
+		:placement="placement === 'cursor' ? 'bottom-start' : placement"
+		:style="{ width: parsedWidth }"
+		:transition-duration="transitionDuration"
+		v-bind="$attrs"
+	>
+		<span class="bb-popover__content" :inert="!isOpen">
+			<BaseButton
+				v-if="showClose"
+				:aria-label="closeLabel || t('common.closeLabel').value"
+				class="bb-popover__close"
+				@click="close"
+			>
+				<svg
+					aria-hidden="true"
+					fill="none"
+					viewBox="0 0 24 24"
+					xmlns="http://www.w3.org/2000/svg"
+				>
+					<path
+						d="M23 23L1 1M23 1L1 23"
+						stroke="currentColor"
+						stroke-linecap="round"
+						stroke-width="2"
+					/>
+				</svg>
+			</BaseButton>
+			<slot
+				:close="close"
+				:disabled="!!disabled"
+				:open="isOpen"
+				:placement="placement"
+			/>
+		</span>
+	</CommonPopover>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref, useTemplateRef, watch } from 'vue';
+import { useId } from '@/composables/useId';
+import { useElementSize, useIntersectionObserver } from '@vueuse/core';
+import { useLocale } from '@/composables/useLocale';
+import { useUntil } from '@/composables/useUntil';
+import BaseButton from '../BaseButton/BaseButton.vue';
+import CommonPopover from '../CommonPopover/CommonPopover.vue';
+import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import { parseWidthString } from '@/utilities/functions/parseWidthString';
+import type {
+	BbPopoverProps,
+	BbPopoverEvents,
+	BbPopoverSlots,
+	PopoverTrigger,
+} from './types';
+export type { BbPopoverProps, BbPopoverEvents, BbPopoverSlots, PopoverTrigger };
+
+const props = withDefaults(defineProps<BbPopoverProps>(), {
+	arrowPadding: 10,
+	offset: 3,
+	padding: 10,
+	placement: 'bottom',
+	restoreFocus: true,
+	showClose: true,
+	theme: 'default',
+	transitionDuration: 300,
+	trigger: 'click',
+});
+
+const emit = defineEmits<BbPopoverEvents>();
+
+defineSlots<BbPopoverSlots>();
+
+defineOptions({ inheritAttrs: false });
+
+// --- Core state ---
+
+const { t } = useLocale();
+const { id } = useId();
+const activatorId = props.id ?? id.value;
+const popoverId = `bbp_${activatorId}`;
+
+const activatorEl = ref<HTMLElement>();
+const popoverRef = useTemplateRef('popoverRef');
+const popoverEl = computed(() => extractDomContainer(popoverRef.value));
+
+const isOpen = defineModel<boolean>({ default: false });
+const hasOpenedOnce = useUntil(isOpen);
+const hasExternalActivator = computed(() => props.activator != null);
+
+const triggers = computed(() => {
+	const raw = props.trigger;
+	return new Set(Array.isArray(raw) ? raw : [raw]);
+});
+
+const createVirtualElement = (x: number, y: number) => ({
+	getBoundingClientRect: () => ({
+		x,
+		y,
+		width: 0,
+		height: 0,
+		top: y,
+		left: x,
+		right: x,
+		bottom: y,
+		toJSON() {
+			return this;
+		},
+	}),
+});
+
+const cursorAnchor = ref<ReturnType<typeof createVirtualElement> | null>(null);
+
+const effectiveAnchor = computed(() =>
+	props.placement === 'cursor' && cursorAnchor.value
+		? cursorAnchor.value
+		: activatorEl.value
+);
+
+// --- Long-press (mobile equivalent of contextMenu) ---
+
+const LONG_PRESS_DELAY = 500;
+const LONG_PRESS_MOVE_THRESHOLD = 10;
+let longPressTimer: ReturnType<typeof setTimeout> | undefined;
+let longPressOrigin: { x: number; y: number } | null = null;
+let longPressTriggered = false;
+
+const clearLongPress = () => {
+	clearTimeout(longPressTimer);
+	longPressOrigin = null;
+};
+
+// --- Activator management ---
+
+const setActivatorRef = (reference: unknown) => {
+	activatorEl.value = extractDomContainer(reference) ?? undefined;
+};
+
+const activatorProps = computed(() => {
+	const active = triggers.value;
+	return {
+		'aria-expanded': hasOpenedOnce.value ? isOpen.value : undefined,
+		'aria-controls': hasOpenedOnce.value ? popoverId : undefined,
+		'aria-haspopup': 'dialog' as const,
+		id: activatorId,
+		disabled: !!props.disabled,
+		ref: setActivatorRef,
+		...(active.has('click') ? { onClick: toggle } : {}),
+		...(active.has('contextMenu')
+			? {
+					onContextmenu: onContextMenu,
+					onPointerdown: onPointerDown,
+					onPointermove: onPointerMove,
+					onPointerup: onPointerUp,
+					onPointercancel: onPointerUp,
+				}
+			: {}),
+	};
+});
+
+// Sync external activator prop to internal ref
+watch(
+	() => props.activator,
+	(val) => {
+		if (val) setActivatorRef(val);
+	},
+	{ immediate: true }
+);
+
+// Attach trigger listeners for external activators
+watch(
+	[activatorEl, triggers] as const,
+	([el, active], _, onCleanup) => {
+		if (!el || !hasExternalActivator.value) return;
+
+		const removers: (() => void)[] = [];
+
+		if (active.has('click')) {
+			el.addEventListener('click', toggle);
+			removers.push(() => el.removeEventListener('click', toggle));
+		}
+
+		if (active.has('contextMenu')) {
+			el.addEventListener('contextmenu', onContextMenu);
+			el.addEventListener('pointerdown', onPointerDown);
+			el.addEventListener('pointermove', onPointerMove);
+			el.addEventListener('pointerup', onPointerUp);
+			el.addEventListener('pointercancel', onPointerUp);
+			removers.push(() => {
+				el.removeEventListener('contextmenu', onContextMenu);
+				el.removeEventListener('pointerdown', onPointerDown);
+				el.removeEventListener('pointermove', onPointerMove);
+				el.removeEventListener('pointerup', onPointerUp);
+				el.removeEventListener('pointercancel', onPointerUp);
+				clearLongPress();
+			});
+		}
+
+		el.setAttribute('aria-haspopup', 'dialog');
+
+		onCleanup(() => {
+			removers.forEach((fn) => fn());
+			el.removeAttribute('aria-expanded');
+			el.removeAttribute('aria-controls');
+			el.removeAttribute('aria-haspopup');
+		});
+	},
+	{ immediate: true }
+);
+
+// Sync aria-expanded for external activators
+watch(
+	[activatorEl, isOpen, hasOpenedOnce] as const,
+	([el, open, opened]) => {
+		if (!el || !hasExternalActivator.value || !opened) return;
+		el.setAttribute('id', activatorId);
+		el.setAttribute('aria-expanded', String(open));
+		el.setAttribute('aria-controls', popoverId);
+	},
+	{ immediate: true }
+);
+
+// Close when activator scrolls out of view
+useIntersectionObserver(
+	activatorEl,
+	([{ intersectionRatio }]) => {
+		if (intersectionRatio !== 1 && isOpen.value) close();
+	},
+	{ threshold: [0, 1] }
+);
+
+// --- Open / Close logic ---
+
+const onDocumentClick = (event: MouseEvent) => {
+	const target = event.target;
+	if (!(target instanceof Node)) return;
+
+	const isInsidePopover = popoverEl.value?.contains(target);
+	const isInsideActivator = activatorEl.value?.contains(target);
+
+	if (!isInsidePopover && !isInsideActivator) {
+		close();
+	}
+};
+
+const onKeydown = (event: KeyboardEvent) => {
+	if (event.key === 'Escape') {
+		event.preventDefault();
+		close();
+	}
+};
+
+const addGlobalListeners = () => {
+	document.addEventListener('click', onDocumentClick, { passive: true });
+	document.addEventListener('contextmenu', onDocumentClick, { passive: true });
+	document.addEventListener('keydown', onKeydown);
+};
+
+const removeGlobalListeners = () => {
+	document.removeEventListener('click', onDocumentClick);
+	document.removeEventListener('contextmenu', onDocumentClick);
+	document.removeEventListener('keydown', onKeydown);
+};
+
+const openPopover = async () => {
+	if (props.disabled) return;
+
+	isOpen.value = true;
+	addGlobalListeners();
+
+	await nextTick();
+
+	const focusSelector =
+		props.focusTarget ??
+		(props.showClose
+			? '.bb-popover__close'
+			: '[tabindex]:not([tabindex="-1"]), button, a, input, select, textarea');
+	const focusTarget = popoverEl.value?.querySelector(focusSelector);
+
+	if (focusTarget instanceof HTMLElement) {
+		focusTarget.focus();
+	}
+
+	emit('shown');
+};
+
+const toggle = async (event: MouseEvent) => {
+	if (isOpen.value) {
+		close();
+		return;
+	}
+	if (longPressTriggered) {
+		longPressTriggered = false;
+		event.preventDefault();
+		event.stopPropagation();
+		return;
+	}
+	event.stopImmediatePropagation();
+	if (props.placement === 'cursor') {
+		cursorAnchor.value = createVirtualElement(event.clientX, event.clientY);
+	}
+	await openPopover();
+};
+
+const onContextMenu = (event: MouseEvent) => {
+	if (props.disabled) return;
+	event.preventDefault();
+	event.stopPropagation();
+	if (props.placement === 'cursor') {
+		cursorAnchor.value = createVirtualElement(event.clientX, event.clientY);
+		if (isOpen.value) return;
+	}
+	if (isOpen.value) close();
+	else openPopover();
+};
+
+const onPointerDown = (event: PointerEvent) => {
+	if (props.disabled || event.pointerType === 'mouse') return;
+	longPressTriggered = false;
+	longPressOrigin = { x: event.clientX, y: event.clientY };
+	longPressTimer = setTimeout(() => {
+		longPressTriggered = true;
+		if (props.placement === 'cursor' && longPressOrigin) {
+			cursorAnchor.value = createVirtualElement(
+				longPressOrigin.x,
+				longPressOrigin.y
+			);
+		}
+		longPressOrigin = null;
+		openPopover();
+	}, LONG_PRESS_DELAY);
+};
+
+const onPointerMove = (event: PointerEvent) => {
+	if (!longPressOrigin) return;
+	const dx = event.clientX - longPressOrigin.x;
+	const dy = event.clientY - longPressOrigin.y;
+	if (Math.sqrt(dx * dx + dy * dy) > LONG_PRESS_MOVE_THRESHOLD) {
+		clearLongPress();
+	}
+};
+
+const onPointerUp = () => {
+	clearLongPress();
+};
+
+const close = () => {
+	if (!isOpen.value) return;
+
+	isOpen.value = false;
+	removeGlobalListeners();
+
+	if (props.restoreFocus && activatorEl.value) {
+		activatorEl.value.focus();
+	}
+
+	emit('hidden');
+};
+
+// --- Width calculation ---
+
+const needsReactiveWidth = computed(() => {
+	if (!props.width) return false;
+	const { unit } = parseWidthString(props.width);
+	return unit === '%';
+});
+
+const { width: activatorWidth } = useElementSize(
+	computed(() => (needsReactiveWidth.value ? activatorEl.value : undefined)),
+	{ width: 0, height: 0 },
+	{ box: 'border-box' }
+);
+
+const parsedWidth = computed(() => {
+	if (!props.width) return undefined;
+
+	const { value, unit } = parseWidthString(props.width);
+	if (unit === '%' && activatorEl.value) {
+		return `${activatorWidth.value * (value / 100)}px`;
+	}
+	return `${value}px`;
+});
+
+// --- Public API ---
+
+defineExpose({
+	/** Opens the popover programmatically */
+	show: openPopover,
+	/** Closes the popover programmatically */
+	close,
+	/** Whether the popover is currently open */
+	isOpen: computed(() => isOpen.value),
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { CommonProps } from '@/types/CommonProps';
+
+export type PopoverTrigger = 'click' | 'contextMenu';
+
+export type BbPopoverProps = Pick<
+	CommonProps,
+	| 'arrowPadding'
+	| 'closeLabel'
+	| 'block'
+	| 'disabled'
+	| 'eager'
+	| 'id'
+	| 'offset'
+	| 'padding'
+	| 'showClose'
+	| 'theme'
+	| 'transitionDuration'
+> & {
+	/**
+	 * Position of the popover relative to the activator.
+	 * Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow).
+	 *
+	 * @defaultValue `'bottom'`
+	 */
+	placement?: CommonProps['placement'] | 'cursor';
+	/**
+	 * External activator element or component ref.
+	 * When provided, the activator slot is not rendered and click events
+	 * are attached programmatically to the referenced element.
+	 */
+	activator?: HTMLElement | Record<string, any> | null;
+	/**
+	 * Constrains the popover within a bounding element.
+	 * When provided, the popover will not overflow this container's bounds (e.g. a sidebar).
+	 * Accepts an HTMLElement, a Vue component ref, or a CSS selector string.
+	 */
+	boundary?: HTMLElement | Record<string, any> | string | null;
+	/**
+	 * Selector for the element that receives focus after opening.
+	 * Defaults to the close button, or first focusable element if no close button.
+	 */
+	focusTarget?: string;
+	/**
+	 * Whether to restore focus to the activator when closed.
+	 *
+	 * @defaultValue `true`
+	 */
+	restoreFocus?: boolean;
+	/**
+	 * Theme class applied to the popover container.
+	 *
+	 * @deprecated Use a CSS class on the component instead.
+	 * @defaultValue `'default'`
+	 */
+	theme?: string;
+	/**
+	 * Interaction(s) that open the popover.
+	 * Accepts a single trigger or an array to combine them.
+	 * - `'click'` — left-click / tap (default)
+	 * - `'contextMenu'` — right-click on desktop, long-press on mobile
+	 *
+	 * @defaultValue `'click'`
+	 */
+	trigger?: PopoverTrigger | PopoverTrigger[];
+	/**
+	 * Width of the popover. Accepts pixels or percentage (relative to activator width).
+	 */
+	width?: number | string;
+};
+
+export type BbPopoverEvents = {
+	/** Emitted after the popover is fully opened and focus has been moved inside. */
+	(e: 'shown'): void;
+	/** Emitted after the popover is closed and focus has been restored to the activator. */
+	(e: 'hidden'): void;
+};
+
+/** Props exposed by the `activator` slot. */
+export type BbPopoverActivatorSlotProps = {
+	/** Accessibility and positioning attributes to spread onto the activator element. */
+	props: {
+		'aria-expanded'?: boolean;
+		'aria-controls'?: string;
+		'aria-haspopup': 'dialog';
+		id: string;
+		disabled: boolean;
+		ref: (reference: unknown) => void;
+	};
+	/** Whether the popover is globally disabled. */
+	disabled: boolean;
+	/** Whether the popover is currently open. */
+	isOpen: boolean;
+	/** The current placement of the popover panel. */
+	placement: BbPopoverProps['placement'];
+};
+
+/** Props exposed by the `default` slot. */
+export type BbPopoverDefaultSlotProps = {
+	/** Programmatically closes the popover. */
+	close: () => void;
+	/** Whether the popover is globally disabled. */
+	disabled: boolean;
+	/** Whether the popover is currently open. */
+	open: boolean;
+	/** The current placement of the popover panel. */
+	placement: BbPopoverProps['placement'];
+};
+
+export type BbPopoverSlots = {
+	/**
+	 * The element that triggers the popover to open. Spread `props` onto your trigger element.
+	 */
+	activator?: (props: BbPopoverActivatorSlotProps) => any;
+	/**
+	 * The popover body content rendered inside the floating panel.
+	 */
+	default?: (props: BbPopoverDefaultSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-popover {
+	.bb-popover__content {
+		color: var(--bb-text);
+		display: block;
+		padding: 8px;
+		.bb-popover__close {
+			border-radius: var(--bb-radius);
+			float: right;
+			isolation: isolate;
+			margin: calc(var(--bb-ring-size) * -1) calc(var(--bb-ring-size) * -1) 0 0;
+			outline: none;
+			padding: 8px;
+			position: relative;
+
+			&:hover {
+				color: var(--bb-primary);
+			}
+
+			svg {
+				width: 10px;
+			}
+		}
+	}
+}
+```

package/dist/ai/BbProgress.md

@@ -0,0 +1,97 @@
+# BbProgress
+
+## Template & Script
+
+```vue
+<template>
+	<div
+		class="bb-progress"
+		:class="{
+			'bb-progress--horizontal': true,
+		}"
+	>
+		<div class="bb-progress-bar" :style="{ width: width + '%' }"></div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { clamp } from '@/utilities/functions/clamp';
+import { getAsPercentageBetween } from '@/utilities/functions/percentage';
+import { computed } from 'vue';
+import type { BbProgressProps } from './types';
+export type { BbProgressProps };
+
+/**
+ * You can get percentage between 250 and 370 and have it compute it automatically.
+ */
+const props = withDefaults(defineProps<BbProgressProps>(), {
+	modelValue: 0,
+	min: 0,
+	max: 100,
+});
+
+const width = computed(() =>
+	clamp(
+		getAsPercentageBetween(props.modelValue || props.min, props.min, props.max),
+		0,
+		100
+	)
+);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+export type BbProgressProps = {
+	/**
+	 * Used by v-model. It's a number contained between `min` and `max` that corresponds to the current value.
+	 *
+	 * @defaultValue `0`
+	 */
+	modelValue: number | null;
+	/**
+	 * Minimum value. Lower cap.
+	 *
+	 * @defaultValue `0`
+	 */
+	min?: number;
+	/**
+	 * Maximum value. Upper cap.
+	 *
+	 * @defaultValue `100`
+	 */
+	max?: number;
+};
+```
+
+## Styles
+
+```css
+.bb-progress {
+	background-color: color-mix(in srgb, var(--bb-panel) 92%, var(--bb-text));
+	border-radius: var(--bb-radius);
+
+	&.bb-progress--vertical {
+		/* Add styles for vertical progress bar if needed */
+	}
+
+	&.bb-progress--horizontal {
+		height: var(--bb-progress-track);
+
+		.bb-progress-bar {
+			height: 100%;
+		}
+	}
+
+	.bb-progress-bar {
+		background-color: var(--bb-primary);
+		border-radius: var(--bb-radius);
+		transition: all 0.3s; /* or adjust the transition duration as needed */
+	}
+}
+```