bitboss-ui 2.1.114 → 2.1.115

package/dist/ai/BbRating.md

@@ -0,0 +1,245 @@
+# BbRating
+
+## Template & Script
+
+```vue
+<template>
+	<BaseInputContainer
+		:id="id"
+		class="bb-rating"
+		:compact="compact"
+		:direction="direction"
+		:errors="errors"
+		:has-errors="hasErrors"
+		:hide-label="hideLegend"
+		:hint="hint"
+		:input-position="inputPosition"
+		:label="legend"
+		:label-position="legendPosition"
+		:label-tag="'legend'"
+		:name="name"
+		:reverse="reverse"
+		:show-hint="showHint"
+		:tag="'fieldset'"
+	>
+		<template #label="data"><slot name="legend" v-bind="data"></slot></template>
+		<template #input="{ id, hasErrors, ariaDescribedby }">
+			<BaseRating
+				:id="id"
+				:aria-describedby="ariaDescribedby"
+				:autofocus="autofocus"
+				:color="color"
+				:disabled="disabled"
+				:has-errors="hasErrors"
+				:model-value="modelValue"
+				:name="name"
+				:readonly="readonly"
+				:size="size"
+				:stars="stars"
+				v-bind="eventListeners"
+			>
+				<template #prepend="data"
+					><slot name="prepend" v-bind="data"
+				/></template>
+				<template #append="data"><slot name="append" v-bind="data" /></template>
+				<template #icon="data"><slot name="icon" v-bind="data" /></template>
+			</BaseRating>
+		</template>
+	</BaseInputContainer>
+</template>
+
+<script setup lang="ts">
+import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
+import BaseRating from '../BaseRating/BaseRating.vue';
+import type { BaseRatingEvents } from '../BaseRating/types';
+import { ref, computed } from 'vue';
+import type { BbRatingProps, BbRatingEvents, BbRatingSlots } from './types';
+export type { BbRatingProps, BbRatingEvents, BbRatingSlots };
+
+const props = withDefaults(defineProps<BbRatingProps>(), {
+	inputPosition: 'left',
+});
+
+const emit = defineEmits<BaseRatingEvents>();
+
+defineSlots<BbRatingSlots>();
+
+const active = ref(false);
+const showHint = computed(() => props.persistentHint || active.value);
+
+const eventListeners = {
+	onBlur: (event: FocusEvent) => emit('blur', event),
+	onChange: (event: Event) => emit('change', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	onFocus: (event: FocusEvent) => {
+		active.value = true;
+		emit('focus', event);
+	},
+	onInactive: () => {
+		active.value = false;
+		emit('inactive');
+	},
+	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': (event: any) => emit('update:modelValue', event),
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { BaseRatingEvents, BaseRatingSlots } from '../BaseRating/types';
+import type { BbIconProps } from '../BbIcon/types';
+
+export type BbRatingProps = {
+	/**
+	 * Sets autofocus on page load.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Define a color for the component.
+	 *
+	 * Either a custom color or a coded color in common HEX, RGB, etc... format.
+	 */
+	color?: string;
+
+	/**
+	 * Sets the component in a compact state.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: 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;
+
+	/**
+	 * 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 legend of the fieldset while maintaining accessibility.
+	 */
+	hideLegend?: boolean;
+	/**
+	 * Text box to be displayed near the input, usually to indicate instructions.
+	 */
+	hint?: string;
+
+	/**
+	 * The identifier of the component.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can.
+	 *
+	 * @defaultValue `'left'`
+	 */
+	inputPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Text content of the legend.
+	 */
+	legend: string;
+
+	/**
+	 * Sets the text alignment of the legend.
+	 */
+	legendPosition?: 'left' | 'center' | 'right';
+	/**
+	 * Used by v-model.
+	 */
+	modelValue: null | number;
+	/**
+	 * Defines the name of the input.
+	 */
+	name: string;
+
+	/**
+	 * Keeps the hint displayed.
+	 */
+	persistentHint?: boolean;
+
+	/**
+	 * 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;
+	/**
+	 * Maximum number of stars to render and maximum value of the component.
+	 */
+	stars?: number;
+} & Pick<BbIconProps, 'size'>;
+
+/** Re-export for consumers importing events type from BbRating. */
+export type BbRatingEvents = BaseRatingEvents;
+
+/** Props exposed by the `legend` slot. */
+export type BbRatingLegendSlotProps = {
+	/** The `legend` prop value. */
+	text: string;
+	/** Whether the rating is in an error state. */
+	hasErrors: boolean;
+};
+
+export type BbRatingSlots = BaseRatingSlots & {
+	/**
+	 * Replaces the default fieldset legend text rendered above the rating stars.
+	 */
+	legend?: (props: BbRatingLegendSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-rating {
+	.bb-base-input-container--horizontal {
+		.bb-base-input-container__label {
+			float: left;
+		}
+	}
+
+	.bb-base-input-container__input--right {
+		.bb-cr-container__container {
+			justify-content: flex-end;
+		}
+	}
+	.bb-base-input-container__input--center {
+		.bb-cr-container__container {
+			justify-content: center;
+		}
+	}
+}
+```

package/dist/ai/BbRatio.md

@@ -0,0 +1,62 @@
+# BbRatio
+
+## Template & Script
+
+```vue
+<template>
+	<component
+		:is="tag"
+		class="bb-ratio"
+		:style="{
+			aspectRatio: ratio,
+		}"
+		><slot></slot>
+	</component>
+</template>
+
+<script setup lang="ts">
+import type { BbRatioProps, BbRatioSlots } from './types';
+export type { BbRatioProps, BbRatioSlots };
+
+withDefaults(defineProps<BbRatioProps>(), {
+	ratio: 1,
+	tag: 'div',
+});
+
+defineSlots<BbRatioSlots>();
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { NonVoidElementTag } from '@/types/CommonProps';
+
+export type BbRatioProps = {
+	/**
+	 * The ratio the component should maintain. It should be passed as a number as in `16/9`.
+	 *
+	 * @defaultValue `1`
+	 */
+	ratio?: number;
+} & NonVoidElementTag;
+
+export type BbRatioSlots = {
+	/**
+	 * Content rendered inside the ratio container, scaled to maintain the configured aspect ratio.
+	 */
+	default?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-ratio {
+	display: block;
+}
+```

package/dist/ai/BbRows.md

@@ -0,0 +1,307 @@
+# BbRows
+
+## Template & Script
+
+```vue
+<template>
+	<slot v-if="loading" :items="internalItems" name="loading"></slot>
+	<slot v-if="!mappedItems.length" :loading="loading" name="no-data"></slot>
+	<template v-else>
+		<template
+			v-for="(item, index) in mappedItems"
+			:key="item.valueHash + selectAll"
+		>
+			<slot
+				:checked="item.selected"
+				:columns="item.columns"
+				:disabled="item.disabled"
+				:index="index"
+				:item="item.item"
+				:select="() => selectItem(item)"
+				:unselect="() => unselectItem(item)"
+				:value="item.value"
+			/>
+		</template>
+	</template>
+</template>
+
+<script setup lang="ts" generic="Item = any">
+import { reactive, ref, toRef, watch } from 'vue';
+import { computed } from 'vue';
+import type { Option as BaseOption } from '@/types/Option';
+import { useItemValue } from '@/composables/useItemValue';
+import { isNil } from '@/utilities/functions/isNil';
+import { indexBy } from '@/utilities/functions/indexBy';
+import { hash } from '@/utilities/functions/hash';
+import { useItemsGetter } from '@/composables/useItemsGetter';
+import { usePrefill } from '@/composables/usePrefill';
+import { useIndexById } from '@/composables/useIndexById';
+import { useBaseOptions } from '@/composables/useBaseOptions';
+import { useHashedWatcher } from '@/composables/useHashedWatcher';
+import type { BbRowsColumn, BbRowsEvents, BbRowsProps } from './types';
+
+/**
+ * Projection that represents a row of cells with flags
+ * linked to the state of the item
+ */
+type MappedItem = BaseOption & {
+	columns: Record<string, ItemColumn>;
+	selected: boolean;
+	disabled: boolean;
+};
+
+type ItemColumn = {
+	key: string;
+	label: string;
+	value: any;
+};
+
+const props = withDefaults(defineProps<BbRowsProps<Item>>(), {
+	allowSelectAll: true,
+	columns: () => [],
+	dependencies: () => [],
+	depsDebounceTime: 0,
+	fixedColumns: () => [],
+	items: () => [],
+	max: Infinity,
+	multiple: true,
+	modelValue: () => [],
+	unselectedItems: () => [],
+});
+
+const emit = defineEmits<BbRowsEvents>();
+
+defineSlots<{
+	/**
+	 * Rendered once per item in `items`. Provides the full state of a single row.
+	 * @param checked - Whether this item is currently selected.
+	 * @param columns - A map of column key to `{ key, label, value }` for each defined column.
+	 * @param disabled - Whether this item is disabled (based on the `selectable` prop).
+	 * @param index - The zero-based index of this item in the list.
+	 * @param item - The raw item from the `items` prop.
+	 * @param select - Selects this item.
+	 * @param unselect - Deselects this item.
+	 * @param value - The resolved value of this item (from `itemValue`).
+	 */
+	default?: (props: {
+		checked: boolean;
+		columns: Record<string, { key: string; label: string; value: any }>;
+		disabled: boolean;
+		index: number;
+		item: Item;
+		select: () => void;
+		unselect: () => void;
+		value: any;
+	}) => any;
+	/**
+	 * Content shown while items are loading (replaces the default loading state).
+	 * @param items - The current (possibly stale) list of items, useful to show a skeleton matching the previous count.
+	 */
+	loading?: (props: { items: Item[] }) => any;
+	/**
+	 * Content shown when the items list is empty and not loading.
+	 * @param loading - Whether items are currently being fetched.
+	 */
+	'no-data'?: (props: { loading: boolean }) => any;
+}>();
+
+const { getItemValue } = useItemValue();
+
+const loading = computed(() => !!(props.loading || innerLoading.value));
+
+const {
+	getter,
+	items: internalItems,
+	loading: innerLoading,
+} = useItemsGetter({
+	items: toRef(props, 'items'),
+});
+
+const { hasPrefilled } = usePrefill({
+	trigger: true,
+	fn: async (isPrefill) => {
+		await getter(isPrefill, props.modelValue);
+	},
+});
+
+const { data: modelValueIndexedByHash } = useIndexById({
+	items: toRef(props, 'modelValue'),
+});
+
+const { options } = useBaseOptions({
+	disabled: toRef(props, 'disabled'),
+	items: internalItems,
+	itemText: undefined,
+	itemValue: props.itemValue,
+	max: props.max,
+	selectable: true,
+	selectedIndexedByHash: modelValueIndexedByHash,
+});
+const onOptionSelected = async (option: BaseOption) => {
+	if (props.multiple) {
+		emit('update:modelValue', props.modelValue.concat(option.value));
+	} else {
+		emit('update:modelValue', option.value);
+	}
+};
+
+const onOptionUnselected = async (option: BaseOption) => {
+	if (props.multiple) {
+		const copy = { ...modelValueIndexedByHash.value };
+		delete copy[option.valueHash];
+		emit('update:modelValue', Object.values(copy));
+	} else {
+		emit('update:modelValue', null);
+	}
+};
+
+useHashedWatcher(
+	() => [props.dependencies, props.items],
+	async () => {
+		if (!hasPrefilled.value) {
+			return;
+		}
+		await getter(false, props.modelValue);
+	},
+	{
+		debounce: props.depsDebounceTime,
+	}
+);
+
+/**
+ * Map items to an an array that represents the entire row.
+ * Track every logic here so we don't have inline callbacks in the template.
+ */
+const mappedItems = computed<MappedItem[]>(() => {
+	return options.value.map((item: BaseOption): MappedItem => {
+		/**
+		 * Item is selectable only if the table allows or item
+		 * passes iteratee and the selection is not disabled
+		 */
+		let disabled = !props.selectable;
+		if (typeof props.selectable === 'function') {
+			disabled = !props.selectable(item.item);
+		}
+		disabled = disabled || !!item.disabled;
+
+		// Create a projection of the columns and run all formatter logic so
+		// we just display content in the template
+		const columns = indexBy(
+			props.columns.map((column) => {
+				const { label, key } = column;
+				// The content
+				let content = getItemValue(item.item, column.key);
+				if (
+					column.formatter &&
+					// By default the formatter runs anyway
+					(!isNil(content) || column.formatOnNull !== false)
+				) {
+					content = column.formatter(content, column.key, item.item);
+				}
+				if (column.placeholder && isNil(content)) {
+					content = column.placeholder;
+				}
+
+				return {
+					value: content,
+					key,
+					label,
+				} as ItemColumn;
+			}),
+			(c) => c.key
+		);
+
+		// If the item is selected or the select all is checked and the item is not explicitly unselected
+		const selected =
+			!!(item.selected || selectAll.value) &&
+			!unselectedItems.has(item.valueHash);
+		const res = {
+			columns: columns,
+			item: item.item,
+			text: item.text,
+			valueHash: item.valueHash,
+			value: item.value,
+			selected,
+			disabled,
+		};
+		return res;
+	});
+});
+
+const selectItem = (item: MappedItem) => {
+	if (!selectAll.value) {
+		onOptionSelected(item);
+	}
+	unselectedItems.delete(item.valueHash);
+	emit(
+		'update:unselectedItems',
+		props.unselectedItems.filter((i) => hash(i) !== hash(item.value))
+	);
+};
+const unselectItem = (item: MappedItem) => {
+	unselectedItems.add(item.valueHash);
+	emit('update:unselectedItems', [...props.unselectedItems, item.value]);
+	onOptionUnselected(item);
+};
+
+// eslint-disable-next-line vue/no-dupe-keys
+const unselectedItems = reactive(new Set<string>());
+watch(
+	() => props.unselectedItems,
+	() => {
+		unselectedItems.clear();
+		props.unselectedItems.forEach((i) => {
+			unselectedItems.add(hash(i));
+		});
+	}
+);
+
+const selectAll = ref(props.selectAll);
+watch(
+	() => props.selectAll,
+	() => {
+		selectAll.value = props.selectAll;
+	}
+);
+
+watch(selectAll, () => {
+	unselectedItems.clear();
+	emit('update:unselectedItems', []);
+	emit('update:modelValue', []);
+});
+</script>
+
+<style scoped></style>
+```
+
+## Types
+
+```ts
+import type { BaseColumn } from '../BbTable/types';
+
+export type BbRowsColumn<Item = any> = BaseColumn<Item>;
+
+export type BbRowsProps<Item = any> = {
+	columns: BbRowsColumn<Item>[];
+	dependencies?: any[];
+	depsDebounceTime?: number;
+	disabled?: boolean;
+	items:
+		| any[]
+		| ((prefill: boolean, modelValue?: any[]) => Promise<any[]>)
+		| ((prefill: boolean, modelValue?: any[]) => any[]);
+	itemValue?: string | ((item: any) => any);
+	loading?: boolean;
+	max?: number;
+	modelValue?: any;
+	multiple?: boolean;
+	selectable?: boolean | ((item: any) => boolean);
+	selectAll?: boolean;
+	unselectedItems?: any[];
+};
+
+export type BbRowsEvents = {
+	(e: 'update:modelValue', value: any): void;
+	(e: 'update:unselectedItems', value: any[]): void;
+};
+```