bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbTooltip.md

@@ -0,0 +1,353 @@
+# BbTooltip
+
+## Template & Script
+
+```vue
+<template>
+	<slot
+		v-if="!hasExternalActivator"
+		name="activator"
+		v-bind="{
+			props: {
+				ref: setActivatorRef,
+			},
+			disabled: disabled,
+			open: open,
+			placement: placement,
+		}"
+	></slot>
+
+	<CommonPopover
+		ref="popover"
+		v-model="open"
+		:anchor="activatorEl"
+		:arrow-padding="arrowPadding"
+		:boundary="boundary"
+		class="bb-tooltip"
+		:class="{
+			[`bb-tooltip--${theme}`]: true,
+		}"
+		:padding="padding"
+		:placement="placement"
+		:transition-duration="transitionDuration"
+		v-bind="$attrs"
+	>
+		<span :id="id" class="bb-tooltip__content" :style="{ width: parsedWidth }">
+			<BaseButton
+				v-if="showClose"
+				:aria-label="t('common.closeLabel').value"
+				class="bb-tooltip__close"
+				tabindex="-1"
+				@click="onClickClose"
+			>
+				<svg 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></slot>
+		</span>
+	</CommonPopover>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, useTemplateRef, watch } from 'vue';
+import { useId } from '@/composables/useId';
+import { useLocale } from '@/composables/useLocale';
+import { useUntil } from '@/composables/useUntil';
+import BaseButton from '../BaseButton/BaseButton.vue';
+import CommonPopover from '../CommonPopover/CommonPopover.vue';
+import { useElementSize } from '@vueuse/core';
+import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import { parseWidthString } from '@/utilities/functions/parseWidthString';
+import type { BbTooltipProps, BbTooltipSlots } from './types';
+export type { BbTooltipProps, BbTooltipSlots };
+
+const props = withDefaults(defineProps<BbTooltipProps>(), {
+	arrowPadding: 10,
+	padding: 10,
+	placement: 'top',
+	showClose: true,
+	theme: 'default',
+	transitionDuration: 250,
+	timeout: 0,
+});
+
+defineSlots<BbTooltipSlots>();
+
+defineOptions({
+	inheritAttrs: false,
+});
+
+const { t } = useLocale();
+const id = `bb_${props.id ?? useId().id.value}`;
+const activatorEl = ref<HTMLElement>();
+const hasExternalActivator = computed(() => props.activator != null);
+const popoverRef = useTemplateRef('popover');
+const popoverDom = computed(() => extractDomContainer(popoverRef.value));
+const canOpen = ref(true);
+const open = defineModel<boolean>({ default: false });
+const hasOpenedOnce = useUntil(open);
+
+const setActivatorRef = (reference: unknown) => {
+	const el = extractDomContainer(reference);
+	if (!el) return;
+	activatorEl.value = el;
+};
+
+// --- Open / close ---
+
+let _openTimeout: ReturnType<typeof setTimeout> | undefined;
+let _closeTimeout: ReturnType<typeof setTimeout> | undefined;
+
+const cancelClose = () => {
+	clearTimeout(_closeTimeout);
+};
+
+const forceClose = () => {
+	clearTimeout(_openTimeout);
+	clearTimeout(_closeTimeout);
+	document.removeEventListener('keydown', onEsc);
+	open.value = false;
+};
+
+const scheduleClose = () => {
+	clearTimeout(_openTimeout);
+	clearTimeout(_closeTimeout);
+	_closeTimeout = setTimeout(forceClose, 50);
+};
+
+const scheduleOpen = () => {
+	cancelClose();
+	if (open.value || props.disabled || !canOpen.value) return;
+	_openTimeout = setTimeout(() => {
+		open.value = true;
+		document.addEventListener('keydown', onEsc, { passive: true });
+	}, props.timeout);
+};
+
+const onEsc = (event: KeyboardEvent) => {
+	if (event.key === 'Escape') forceClose();
+};
+
+const onClickClose = () => {
+	canOpen.value = false;
+	forceClose();
+};
+
+// --- Sync external activator prop ---
+
+watch(
+	() => props.activator,
+	(val) => {
+		if (val) setActivatorRef(val);
+	},
+	{ immediate: true }
+);
+
+let cleanupActivator: (() => void) | null = null;
+
+watch(
+	activatorEl,
+	(el) => {
+		if (cleanupActivator) {
+			cleanupActivator();
+			cleanupActivator = null;
+		}
+		if (!el) return;
+
+		el.addEventListener('mouseenter', scheduleOpen, { passive: true });
+		el.addEventListener('mouseleave', scheduleClose, { passive: true });
+		el.addEventListener('focus', scheduleOpen, { passive: true });
+		el.addEventListener('blur', forceClose, { passive: true });
+
+		cleanupActivator = () => {
+			el.removeEventListener('mouseenter', scheduleOpen);
+			el.removeEventListener('mouseleave', scheduleClose);
+			el.removeEventListener('focus', scheduleOpen);
+			el.removeEventListener('blur', forceClose);
+		};
+	},
+	{ immediate: true }
+);
+
+let cleanupPopover: (() => void) | null = null;
+
+watch(
+	popoverDom,
+	(el) => {
+		if (cleanupPopover) {
+			cleanupPopover();
+			cleanupPopover = null;
+		}
+		if (!el) return;
+
+		el.addEventListener('mouseenter', cancelClose, { passive: true });
+		el.addEventListener('mouseleave', scheduleClose, { passive: true });
+
+		cleanupPopover = () => {
+			el.removeEventListener('mouseenter', cancelClose);
+			el.removeEventListener('mouseleave', scheduleClose);
+		};
+	},
+	{ immediate: true }
+);
+
+watch(
+	[activatorEl, hasOpenedOnce] as const,
+	([el, opened]) => {
+		if (!el) return;
+		if (opened) {
+			el.setAttribute('aria-describedby', id);
+		}
+	},
+	{ immediate: true }
+);
+
+onBeforeUnmount(() => {
+	cleanupActivator?.();
+	cleanupPopover?.();
+	if (activatorEl.value) {
+		activatorEl.value.removeAttribute('aria-describedby');
+	}
+	forceClose();
+});
+
+const { width: activatorWidth } = useElementSize(
+	activatorEl,
+	{ width: 0, height: 0 },
+	{
+		box: 'border-box',
+	}
+);
+const parsedWidth = computed(() => {
+	if (props.width) {
+		const { value, unit } = parseWidthString(props.width);
+		if (unit === '%') {
+			if (!activatorEl.value) return '0px';
+			return `${activatorWidth.value * (value / 100)}px`;
+		}
+		return `${value}px`;
+	}
+	return undefined;
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { CommonProps } from '@/types/CommonProps';
+import type { Placement } from '@floating-ui/vue';
+
+export type BbTooltipProps = Pick<
+	CommonProps,
+	| 'arrowPadding'
+	| 'block'
+	| 'disabled'
+	| 'eager'
+	| 'id'
+	| 'padding'
+	| 'placement'
+	| 'showClose'
+	| 'theme'
+	| 'transitionDuration'
+> & {
+	/**
+	 * External activator element or component ref.
+	 * When provided, the activator slot is not rendered and event listeners
+	 * are attached programmatically to the referenced element.
+	 */
+	activator?: HTMLElement | Record<string, any> | null;
+	/**
+	 * Constrains the tooltip within a bounding element.
+	 * When provided, the tooltip 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;
+	/**
+	 * Name of the theme to apply to the component.
+	 * @deprecated since the popover is local you should use a normal css class applied to
+	 * the top level element.
+	 */
+	theme?: string;
+	/**
+	 * The delay in milliseconds before the tooltip is shown.
+	 *
+	 * @defaultValue `0`
+	 */
+	timeout?: number;
+	/**
+	 * Width of the dropdown in pixels or percentage.
+	 */
+	width?: number | string;
+};
+
+/** Props exposed by the `activator` slot. */
+export type BbTooltipActivatorSlotProps = {
+	/** Bind onto the activator element with `v-bind="props"` to wire up the popover reference. */
+	props: {
+		ref: (reference: unknown) => void;
+	};
+	/** Whether the tooltip is disabled. */
+	disabled?: boolean;
+	/** Whether the tooltip is currently visible. */
+	open: boolean;
+	/** The current placement of the tooltip relative to the activator. */
+	placement: Placement;
+};
+
+export type BbTooltipSlots = {
+	/**
+	 * Replaces the default trigger element that opens the tooltip.
+	 */
+	activator?: (props: BbTooltipActivatorSlotProps) => any;
+	/**
+	 * Content rendered inside the tooltip bubble.
+	 */
+	default?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-tooltip {
+	.bb-tooltip__content {
+		--p: 8px;
+		color: var(--bb-text);
+		display: inline-flex;
+		align-items: flex-start;
+		font-size: 14px;
+		padding: var(--p);
+		.bb-tooltip__close {
+			border-radius: var(--bb-radius);
+			flex-shrink: 0;
+			order: 1;
+			isolation: isolate;
+			padding: var(--p);
+			margin: -2px calc(var(--p) * -1) calc(var(--p) * -1) 0px;
+
+			&:hover {
+				color: var(--bb-primary);
+			}
+
+			&:focus-visible {
+				color: var(--bb-primary);
+			}
+
+			svg {
+				width: 10px;
+			}
+		}
+	}
+}
+```

package/dist/ai/BbTree.md

@@ -0,0 +1,271 @@
+# BbTree
+
+## Template & Script
+
+```vue
+<template>
+	<div
+		v-for="item in internalItems"
+		:key="item.identifier"
+		class="bb-tree"
+		:class="{
+			[`bb-tree--depth-${item.depth}`]: true,
+			'bb-tree--open': item.open,
+		}"
+	>
+		<div class="bb-tree-row">
+			<div class="bb-tree-main-content">
+				<!-- Slot for a speciifc item -->
+				<slot
+					v-if="$slots[item.identifier]"
+					:depth="item.depth"
+					:expandable="item.expandable"
+					:identifier="item.identifier"
+					:index="item.index"
+					:item="item.original"
+					:name="item.identifier"
+					:offset="item.offset"
+					:open="item.open"
+					:parent="item.parent"
+				/>
+				<!-- Slot for all items in this level -->
+				<slot
+					v-else-if="$slots[item.depth]"
+					:depth="item.depth"
+					:expandable="item.expandable"
+					:identifier="item.identifier"
+					:index="item.index"
+					:item="item.original"
+					:name="item.depth"
+					:offset="item.offset"
+					:open="item.open"
+					:parent="item.parent"
+				/>
+				<!-- Default slot -->
+				<slot
+					v-else
+					:depth="item.depth"
+					:expandable="item.expandable"
+					:identifier="item.identifier"
+					:index="item.index"
+					:item="item.original"
+					:name="'default'"
+					:offset="item.offset"
+					:open="item.open"
+					:parent="item.parent"
+				></slot>
+			</div>
+		</div>
+		<div :class="`bb-tree--depth-${item.depth}-children`">
+			<slot
+				:depth="item.depth"
+				:expandable="item.expandable"
+				:identifier="item.identifier"
+				:index="item.index"
+				:item="item.original"
+				:name="`${item.identifier}-children`"
+				:offset="item.offset"
+				:open="item.open"
+				:parent="item.parent"
+			>
+				<slot
+					:depth="item.depth"
+					:expandable="item.expandable"
+					:identifier="item.identifier"
+					:index="item.index"
+					:item="item.original"
+					:name="`${item.depth}-children`"
+					:offset="item.offset"
+					:open="item.open"
+					:parent="item.parent"
+				>
+					<BbTree
+						:depth="item.depth + 1"
+						:expandable="expandable"
+						:identifier="props.identifier"
+						:items="item.children as any"
+						:parent="item"
+					>
+						<template v-for="(_, name) in $slots" #[name]="data: any">
+							<slot :name="name" v-bind="data" />
+						</template>
+					</BbTree>
+				</slot>
+			</slot>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { flattenTree } from '@/utilities/functions/flattenTree';
+import { computed } from 'vue';
+import type { BbTreeProps, TreeItem, BbTreeSlots } from './types';
+export type { BbTreeProps, TreeItem, BbTreeSlots };
+
+const props = withDefaults(defineProps<BbTreeProps>(), {
+	identifier: 'id',
+	depth: 0,
+	offset: 0,
+	items: () => [] as TreeItem[],
+});
+
+defineSlots<BbTreeSlots>();
+
+const itemIsOpen = (item: TreeItem) => {
+	/* If the item is not expandable it must be open */
+	if (typeof item.open === 'undefined') return true;
+	return item.open;
+};
+
+type MappedItem = {
+	children: TreeItem['children'];
+	depth: NonNullable<BbTreeProps['depth']>;
+	expandable: boolean;
+	identifier: any;
+	index: number;
+	offset: number;
+	open: boolean;
+	original: any;
+	parent: BbTreeProps['parent'];
+};
+
+const internalItems = computed<MappedItem[]>(() => {
+	let currentOffset = 0;
+
+	return props.items.map((item: TreeItem, index) => {
+		const open = itemIsOpen(item);
+		const expandableProp = item.expandable ?? props.expandable;
+		const offset = currentOffset + 1;
+
+		currentOffset = currentOffset + flattenTree([item], 'children').length;
+
+		let expandable = false;
+		if (typeof expandableProp !== 'undefined') {
+			if (typeof expandableProp === 'function')
+				expandable = expandableProp(item, props.depth, props.parent);
+			else expandable = expandableProp;
+		}
+		return {
+			children: item.children,
+			depth: props.depth,
+			expandable: expandable,
+			identifier: item[props.identifier],
+			offset,
+			index,
+			open,
+			original: item,
+			parent: props.parent,
+		};
+	});
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+export type TreeItem = {
+	/**
+	 * Array of children of the current item. Is the key
+	 * with which we can identify whether the node is nested or not.
+	 */
+	children?: TreeItem[];
+	/**
+	 * Status of the current node. When a node is open
+	 * its children are displayed. Otherwise its children are hidden.
+	 */
+	open?: boolean;
+	[key: symbol | string]: any;
+} & Pick<BbTreeProps, 'expandable'>;
+
+export type BbTreeProps = {
+	/**
+	 * Array containing the tree-like structure of the items.
+	 */
+	items: TreeItem[];
+	/**
+	 * Parent of the current node. `undefined` for the first level.
+	 */
+	parent?: TreeItem;
+	/**
+	 * Identifier of the item.
+	 *
+	 * @defaultValue `'id'`
+	 */
+	identifier?: string | number;
+	/**
+	 * Current depth of the tree. Starting at 0 for
+	 * the first level, increasing at every level down.
+	 *
+	 * @defaultValue `0`
+	 */
+	depth?: number;
+	/**
+	 * Defines the item as expandable. It can be a global boolean defining all items as
+	 * expandable, or a function that receives the item, depth, and parent of the current
+	 * node and returns a boolean.
+	 */
+	expandable?:
+		| boolean
+		| ((item: TreeItem, depth: number, parent?: TreeItem) => boolean);
+};
+
+/** Props exposed by all tree node slots. */
+export type BbTreeNodeSlotProps = {
+	/** The raw item from the `items` prop for this node. */
+	item: any;
+	/** The parent item, or `undefined` for root-level nodes. */
+	parent?: any;
+	/** Zero-based index of this node among its siblings. */
+	index: number;
+	/** Absolute position of this node in the flattened tree. */
+	offset: number;
+	/** Whether this node is currently expanded (children visible). */
+	open: boolean;
+	/** Nesting depth of this node, starting at `0` for the root level. */
+	depth: number;
+	/** The resolved identifier value for this node. */
+	identifier?: string | number;
+	/** Whether this node can be expanded. */
+	expandable: boolean;
+};
+
+export type BbTreeSlots = {
+	/**
+	 * Named slots for tree nodes, resolved in priority order: `{identifier}` (specific node),
+	 * `{depth}` (all nodes at that depth), `{identifier}-children` (children container),
+	 * `{depth}-children` (children container at that depth), or `default` (all remaining nodes).
+	 */
+	[key: string]: (props: BbTreeNodeSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-tree {
+	display: grid;
+	grid-template-rows: min-content 0fr;
+	transition: grid-template-rows 0.3s;
+
+	&.bb-tree--open {
+		grid-template-rows: min-content 1fr;
+	}
+
+	> .bb-tree-row {
+		display: flex;
+
+		> .bb-tree-main-content {
+			flex-grow: 1;
+		}
+	}
+
+	> div[class^='bb-tree--depth-'] {
+		overflow: hidden;
+	}
+}
+```