bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbIcon.md

@@ -0,0 +1,238 @@
+# BbIcon
+
+## Template & Script
+
+```vue
+<template>
+	<svg v-bind="iconAttributes" data-allow-mismatch v-html="content"></svg>
+</template>
+
+<script setup lang="ts">
+import {
+	computed,
+	inject,
+	ref,
+	getCurrentInstance,
+	onServerPrefetch,
+	onBeforeMount,
+	watch,
+} from 'vue';
+import { isCssColor } from '@/utilities/functions/isCssColor';
+import { get } from '@/utilities/functions/get';
+import { useLogger } from '@/composables/useLogger';
+import type { BbIconProps, Size } from './types';
+export type { BbIconProps, Size };
+
+const props = withDefaults(defineProps<BbIconProps>(), {
+	size: 'md',
+});
+const logger = useLogger();
+let icons = ref<Record<string, () => Promise<string>>>();
+const icon = ref<string | null>(null);
+const content = computed(() => {
+	if (icon.value) {
+		return icon.value.replace(/<\/?svg[^>]*>/g, '');
+	}
+	return null;
+});
+
+// @ts-expect-error possibily undef
+const isNuxt = !!get(getCurrentInstance(), ['proxy', '$nuxt']);
+
+/**
+ * Loads the icon registry based on the current environment (Nuxt or Vue).
+ * In Nuxt, uses the injected $icons from the Nuxt context.
+ * In Vue, uses the injected 'icons' provider.
+ * Only loads icons once to prevent redundant operations.
+ * Throws an error if icons cannot be loaded in the current environment.
+ */
+const loadIcons = () => {
+	if (isNuxt) {
+		// @ts-expect-error possibily undef
+		icons.value = get(getCurrentInstance(), ['proxy', '$nuxt', '$icons']);
+		if (!icons.value) {
+			logger.throw(
+				'Failed to load Nuxt icons. Make sure the icon provider is properly configured.'
+			);
+		}
+		return;
+	}
+
+	icons.value = inject('icons');
+	if (!icons.value) {
+		logger.throw(
+			'Failed to inject icons. Make sure the icon provider is properly configured in the Vue app.'
+		);
+	}
+};
+
+/**
+ * Retrieves and loads the SVG content for the specified icon type.
+ * Throws an error if icons haven't been loaded or if the icon type doesn't exist.
+ */
+const getIcon = async () => {
+	if (!icons.value) {
+		logger.throw('Icons have not been loaded');
+	}
+
+	const iconLoader = icons.value![props.type];
+	if (!iconLoader) {
+		logger.throw(`Icon "${props.type}" does not exist.`);
+	}
+
+	icon.value = await iconLoader();
+};
+
+onServerPrefetch(async () => {
+	loadIcons();
+	await getIcon();
+});
+
+onBeforeMount(async () => {
+	if (!icons.value) {
+		loadIcons();
+	}
+	if (!icon.value) {
+		await getIcon();
+	}
+});
+
+watch(() => props.type, getIcon);
+
+const sizeMap: Size = {
+	xs: 12,
+	sm: 16,
+	md: 24,
+	lg: 28,
+	xl: 36,
+	xxl: 40,
+};
+
+/**
+ * Computes the width of the icon in pixels based on the size prop.
+ * Supports predefined size keys, numeric values, or custom pixel strings.
+ */
+const iconWidth = computed(() => {
+	if (typeof props.size === 'number') {
+		return `${props.size}px`;
+	}
+
+	if (typeof props.size === 'string') {
+		const mappedSize = sizeMap[props.size as keyof Size];
+		if (mappedSize !== undefined) {
+			return `${mappedSize}px`;
+		}
+		const parsed = parseInt(props.size, 10);
+		if (isNaN(parsed)) {
+			logger.throw(`Invalid size: "${props.size}"`);
+		}
+		return `${parsed}px`;
+	}
+
+	return '24px';
+});
+
+/**
+ * Computes the attributes object for the icon span element.
+ * Includes CSS classes, inline styles, and accessibility attributes.
+ */
+const iconAttributes = computed(() => {
+	const classes: Record<string, boolean> = {
+		'bb-icon': true,
+	};
+	const style: Record<string, string> = {
+		'--bb-icon-dimensions-w': iconWidth.value,
+	};
+
+	if (props.color) {
+		if (isCssColor(props.color)) {
+			style.color = props.color;
+		} else {
+			classes[`bb-icon--${props.color}`] = true;
+		}
+	}
+
+	const inheritedAttributes: Record<string, any> = {};
+	if (icon.value) {
+		const attrString = icon.value.split('>')[0].substring(5); // all attributes in the opening svg tag
+		const attrRegex = /([\w-]+)="([^"]*)"/g;
+		let match;
+		while ((match = attrRegex.exec(attrString)) !== null) {
+			inheritedAttributes[match[1]] = match[2];
+		}
+	}
+
+	const base: Record<string, any> = {
+		viewBox: '0 0 1 1',
+		...inheritedAttributes,
+		class: classes,
+		style,
+	};
+
+	// Determine if the icon should be accessible to screen readers
+	const hasAccessibleLabel = props.label;
+
+	if (hasAccessibleLabel) {
+		// Icon has a meaningful label - make it accessible
+		base['role'] = 'img';
+		base['aria-label'] = props.label.trim();
+		// Add title as fallback for older screen readers and tooltip behavior
+		base['title'] = props.label.trim();
+	}
+
+	// Icons should never be focusable or keyboard navigable since they're not interactive
+	base['focusable'] = 'false';
+
+	return base;
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { Size as S } from '@/types/CommonProps';
+import type { IconType } from '@/types/Icon';
+
+export type Size = {
+	xs: number;
+	sm: number;
+	md: number;
+	lg: number;
+	xl: number;
+	xxl: number;
+};
+
+export interface BbIconProps extends S<Size> {
+	/**
+	 * Define a color for the component.
+	 *
+	 * Either a custom color or a coded color in common HEX, RGB, etc... format.
+	 */
+	color?: string;
+	/**
+	 * Label of the icon for accessibility.
+	 */
+	label?: string;
+	/**
+	 * Name of the icon to use.
+	 *
+	 * @defaultValue `'md'`
+	 */
+	type: IconType;
+}
+```
+
+## Styles
+
+```css
+.bb-icon {
+	--size: var(--bb-icon-dimensions-w);
+	width: var(--size);
+	pointer-events: none;
+}
+```

package/dist/ai/BbIntersection.md

@@ -0,0 +1,121 @@
+# BbIntersection
+
+## Template & Script
+
+```vue
+<template>
+	<component :is="tag" ref="infinitescrolltrigger" class="bb-intersection">
+		<slot :hidden="hidden" :percentage="percentage" :shown="shown"></slot>
+	</component>
+</template>
+
+<script setup lang="ts">
+import { throttle } from '@/utilities/functions/throttle';
+import { onBeforeUnmount, onMounted, ref } from 'vue';
+import type {
+	BbIntersectionProps,
+	BbIntersectionEvents,
+	BbIntersectionSlots,
+} from './types';
+export type { BbIntersectionProps, BbIntersectionEvents, BbIntersectionSlots };
+
+const props = withDefaults(defineProps<BbIntersectionProps>(), {
+	debounceTime: 0,
+	options: () => ({
+		root: null,
+		threshold: [0, 0.2, 0.4, 0.6, 0.8, 1],
+	}),
+	tag: 'div',
+});
+
+const emit = defineEmits<BbIntersectionEvents>();
+
+defineSlots<BbIntersectionSlots>();
+
+const observer = ref<IntersectionObserver | null>(null);
+const infinitescrolltrigger = ref<Element | null>(null);
+const shown = ref(false);
+const hidden = ref(true);
+const percentage = ref(0);
+
+onMounted(() => {
+	observer.value = new IntersectionObserver((entries) => {
+		handleIntersect(entries[0]);
+	}, props.options);
+	if (infinitescrolltrigger.value) {
+		observer.value.observe(infinitescrolltrigger.value);
+	}
+});
+onBeforeUnmount(() => {
+	if (observer.value) observer.value.disconnect();
+});
+
+const handleIntersect = throttle((entry: IntersectionObserverEntry) => {
+	if (entry.isIntersecting) {
+		percentage.value = Math.trunc(entry.intersectionRatio * 100);
+		if (entry.intersectionRatio === 1) {
+			shown.value = true;
+			hidden.value = false;
+			emit('shown');
+		} else {
+			shown.value = false;
+			hidden.value = false;
+			emitIntersected(Math.trunc(entry.intersectionRatio * 100));
+		}
+	} else {
+		shown.value = false;
+		hidden.value = true;
+		emit('hidden');
+	}
+});
+
+const emitIntersected = throttle((percentage: number) => {
+	emit('intersected', percentage);
+}, props.debounceTime);
+</script>
+```
+
+## Types
+
+```ts
+import type { NonVoidElementTag } from '@/types/CommonProps';
+
+export type BbIntersectionProps = {
+	/**
+	 * Time to wait before emitting intersection value.
+	 *
+	 * @defaultValue `0`
+	 */
+	debounceTime?: number;
+	/**
+	 * Options used to configure the IntersectionObserver.
+	 */
+	options?: IntersectionObserverInit; // eslint-disable-line no-undef
+} & NonVoidElementTag;
+
+export type BbIntersectionEvents = {
+	/** Emitted when the element becomes fully visible in the viewport. */
+	(e: 'shown'): void;
+	/** Emitted when the element leaves the viewport entirely. */
+	(e: 'hidden'): void;
+	/** Emitted when the intersection ratio changes. Payload is the ratio as a percentage (0–100). */
+	(e: 'intersected', value: number): void;
+};
+
+/** Props exposed by the `default` slot. */
+export type BbIntersectionDefaultSlotProps = {
+	/** Whether the component is currently fully out of the viewport. */
+	hidden: boolean;
+	/** The current intersection ratio as a percentage (0–100). */
+	percentage: number;
+	/** Whether the component is currently at least partially visible. */
+	shown: boolean;
+};
+
+export type BbIntersectionSlots = {
+	/**
+	 * Content rendered inside the observed element. Receives live intersection state.
+	 */
+	default?: (props: BbIntersectionDefaultSlotProps) => any;
+};
+```

package/dist/ai/BbNumberInput.md

@@ -0,0 +1,372 @@
+# BbNumberInput
+
+## Template & Script
+
+```vue
+<template>
+	<BaseInputContainer
+		:id="id"
+		class="bb-number-input"
+		:compact="compact"
+		:direction="direction"
+		:errors="errors"
+		:has-errors="hasErrors"
+		:hide-label="hideLabel"
+		:hint="hint"
+		:label="label"
+		:label-position="labelPosition"
+		:model-value="modelValue"
+		:name="name"
+		:reverse="reverse"
+		:show-hint="showHint"
+	>
+		<template #label="data"><slot name="label" v-bind="data"></slot></template>
+		<template #input="{ id, hasErrors, ariaDescribedby }">
+			<BaseNumberInput
+				:id="id"
+				ref="bni"
+				:append:icon="props['append:icon']"
+				:aria-describedby="ariaDescribedby"
+				:autocomplete="autocomplete"
+				:autofocus="autofocus"
+				:clearable="clearable"
+				:compact="compact"
+				:disabled="disabled"
+				:has-errors="hasErrors"
+				:loading="loading"
+				:max="max"
+				:max-precision="maxPrecision"
+				:min="min"
+				:model-value="modelValue"
+				:name="name"
+				:placeholder="placeholder"
+				:prepend:icon="props['prepend:icon']"
+				:readonly="readonly"
+				:required="required"
+				:step="step"
+				v-bind="eventListeners"
+			>
+				<template #append-outer="data"
+					><slot name="append-outer" v-bind="data"
+				/></template>
+				<template #append="data"><slot name="append" v-bind="data" /></template>
+				<template #prefix="data"><slot name="prefix" v-bind="data" /></template>
+				<template #prepend="data"
+					><slot name="prepend" v-bind="data"
+				/></template>
+				<template #suffix="data"><slot name="suffix" v-bind="data" /></template>
+				<template #prepend-outer="data"
+					><slot name="prepend-outer" v-bind="data"
+				/></template>
+			</BaseNumberInput>
+		</template>
+	</BaseInputContainer>
+</template>
+
+<script setup lang="ts">
+import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
+import BaseNumberInput from '../BaseNumberInput/BaseNumberInput.vue';
+import type { BaseNumberInputEvents } from '../BaseNumberInput/types';
+import { computed, ref } from 'vue';
+import type {
+	BbNumberInputProps,
+	BbNumberInputEvents,
+	BbNumberInputSlots,
+} from './types';
+export type { BbNumberInputProps, BbNumberInputEvents, BbNumberInputSlots };
+
+const props = withDefaults(defineProps<BbNumberInputProps>(), {});
+
+const emit = defineEmits<BaseNumberInputEvents>();
+
+defineSlots<BbNumberInputSlots>();
+
+const bni = ref();
+
+const active = ref(false);
+const showHint = computed(() => props.persistentHint || active.value);
+
+/**
+ * These events are just propagated
+ */
+const eventListeners = {
+	onBlur: (event: FocusEvent) => {
+		active.value = false;
+		emit('blur', event);
+	},
+	onChange: (event: Event) => emit('change', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	onDecrease: (event: number) => emit('decrease', event),
+	onFocus: (event: FocusEvent) => {
+		active.value = true;
+		emit('focus', event);
+	},
+	onIncrease: (event: number) => emit('increase', event),
+	onInput: (event: Event) => emit('input', event),
+	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+	onMousedown: (event: MouseEvent) => emit('mousedown', event),
+	onMouseup: (event: MouseEvent) => emit('mouseup', event),
+	'onUpdate:modelValue': (value: number | null) =>
+		emit('update:modelValue', value),
+};
+
+const decrease = () => {
+	bni.value?.decrease();
+};
+
+const increase = () => {
+	bni.value?.increase();
+};
+
+defineExpose({
+	increase,
+	decrease,
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { IconType } from '@/types/Icon';
+import type {
+	BaseNumberInputEvents,
+	BaseNumberInputSlots,
+} from '../BaseNumberInput/types';
+
+export type BbNumberInputProps = {
+	/**
+	 * Name of the icon to be added at the end of the input.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'append:icon'?: IconType;
+	/**
+	 * Guides the browser as to the type of information expected in the field.
+	 */
+	autocomplete?: InputHTMLAttributes['autocomplete'];
+
+	/**
+	 * Sets autofocus on page load.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Displays a clear button when the input has a value and is being interacted with.
+	 */
+	clearable?: boolean;
+
+	/**
+	 * Sets the component in a compact state.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`.
+	 */
+	direction?: 'horizontal' | 'vertical' | 'auto' | string;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Can be a string or an array of string containing the messages to display.
+	 */
+	errors?: string | string[];
+
+	/**
+	 * Define if the component should be in an error state.
+	 * It usually attaches a CSS class for styling purposes.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Visually hides the label of the input while maintaining accessibility.
+	 */
+	hideLabel?: boolean;
+
+	/**
+	 * Text box to be displayed near the input, usually to indicate instructions.
+	 */
+	hint?: string;
+
+	/**
+	 * The identifier of the component.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Text content of the label of the element.
+	 */
+	label: string;
+
+	/**
+	 * Sets the text alignment of the label.
+	 */
+	labelPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Sets the component in a loading state, usually triggering some visual styles.
+	 */
+	loading?: boolean;
+
+	/**
+	 * Maximum value cap.
+	 */
+	max?: number;
+
+	/**
+	 * Maximum precision of the number.
+	 */
+	maxPrecision?: number;
+
+	/**
+	 * Minimum value cap.
+	 */
+	min?: number;
+
+	/**
+	 * Used by v-model.
+	 */
+	modelValue: number | string | null;
+
+	/**
+	 * Defines the name of the input.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * Keeps the hint displayed.
+	 */
+	persistentHint?: boolean;
+
+	/**
+	 * String displayed when there's no data.
+	 */
+	placeholder?: InputHTMLAttributes['placeholder'];
+
+	/**
+	 * Name of the icon to be added at the start of the input.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'prepend:icon'?: IconType;
+
+	/**
+	 * Sets the input in a readonly state.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Sets the input as required.
+	 */
+	required?: boolean;
+
+	/**
+	 * Reverses the layout. Applicable in every direction the order of the label and the input is swapped.
+	 */
+	reverse?: boolean;
+
+	/**
+	 * Incremental unit used in the exposed `increase` and `decrease` functions.
+	 * It is NOT applied to manual input as a step of 5 would prevent the user from inserting a value like `115` because of rounding down.
+	 */
+	step?: number;
+};
+
+/** Re-export for consumers importing events type from BbNumberInput. */
+export type { BaseNumberInputEvents as BbNumberInputEvents };
+
+/** Props exposed by the `label` slot. */
+export type BbNumberInputLabelSlotProps = {
+	/** The `label` prop value. */
+	text: string;
+	/** Whether the input is in an error state. */
+	hasErrors: boolean;
+};
+
+export type BbNumberInputSlots = BaseNumberInputSlots & {
+	/**
+	 * Replaces the default label text rendered above the number input.
+	 */
+	label?: (props: BbNumberInputLabelSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-number-input {
+	&.bb-base-input-outer-container--errors {
+	}
+	&.bb-base-input-outer-container--hint {
+	}
+	.bb-base-input-container {
+		&--vertical {
+		}
+		&--horizontal {
+		}
+
+		&__label {
+			&--left {
+			}
+			&--center {
+			}
+			&--right {
+			}
+			&--hidden {
+			}
+		}
+		&__input {
+			&--left {
+			}
+			&--center {
+			}
+			&--right {
+			}
+
+			.bb-base-number-input {
+				display: inline-flex;
+				&--disabled {
+				}
+				&--errors {
+				}
+				&--loading {
+				}
+				&--readonly {
+				}
+
+				.bb-common-input-inner-container {
+					> input {
+					}
+
+					&__prepend-icon,
+					&__append-icon {
+					}
+					.bb-spinner {
+					}
+					.bb-error-icon {
+					}
+					&__prefix,
+					&__suffix {
+					}
+				}
+			}
+		}
+
+		&__hint-container {
+			.bb-base-input-container__hint {
+			}
+		}
+		&__errors {
+		}
+		&__error {
+		}
+	}
+}
+```