bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseSwitch.md

@@ -0,0 +1,322 @@
+# BaseSwitch
+
+## Template & Script
+
+```vue
+<template>
+	<span v-bind="containerAttributes">
+		<input v-if="!checked && submitWhenFalse" v-bind="hiddenInputAttributes" />
+		<input v-bind="inputAttributes" ref="checkboxInput" />
+		<span class="bb-base-switch-container">
+			<slot name="icon" v-bind="slotAttributes">
+				<span v-bind="iconAttributes">
+					<span class="bb-base-switch-container__icon-thumb"></span>
+				</span>
+			</slot>
+		</span>
+	</span>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { isCssColor } from '@/utilities/functions/isCssColor';
+import { when } from '@/utilities/functions/when';
+import type {
+	BaseSwitchProps,
+	BaseSwitchEvents,
+	BaseSwitchSlots,
+} from './types';
+
+const props = withDefaults(defineProps<BaseSwitchProps>(), {
+	trueValue: true,
+	falseValue: false,
+});
+
+const emit = defineEmits<BaseSwitchEvents>();
+
+defineSlots<BaseSwitchSlots>();
+
+const checkboxInput = ref<HTMLInputElement | null>(null);
+
+const checked = computed(() => {
+	if (props.checked) return true;
+	return JSON.stringify(props.trueValue) === JSON.stringify(props.modelValue);
+});
+const hasFocus = ref(false);
+const hasFocusVisible = ref(false);
+
+const containerAttributes = computed(() => {
+	const attributes: Record<string, any> = {
+		class: {
+			'bb-base-switch': true,
+			'bb-base-switch--disabled': props.disabled,
+			'bb-base-switch--errors': props.hasErrors,
+			'bb-base-switch--indeterminate': props.indeterminate,
+			'bb-base-switch--readonly': props.readonly,
+			[`bb-base-switch--${props.color}`]:
+				props.color && !isCssColor(props.color),
+		},
+	};
+	if (props.color && isCssColor(props.color)) {
+		attributes['style'] = `--color: ${props.color}`;
+	}
+	return attributes;
+});
+
+/**
+ * This is used to keep the value compatible to common html expected values.
+ * Convert to string everything that's not but do not double encode strings
+ */
+const makeInputValue = when(
+	(item: unknown) => typeof item !== 'string',
+	JSON.stringify
+);
+
+const hiddenInputAttributes = computed(() => {
+	const value = makeInputValue(props.falseValue);
+	return {
+		disabled: props.disabled,
+		name: props.name,
+		type: 'hidden',
+		value: value,
+	};
+});
+
+const inputAttributes = computed(() => {
+	const value = makeInputValue(props.trueValue);
+
+	const onBlur = (event: FocusEvent): void => {
+		hasFocus.value = false;
+		hasFocusVisible.value = false;
+		emit('blur', event);
+	};
+
+	const onChange = (event: Event): void => {
+		if (event.target instanceof HTMLInputElement) {
+			let value = event.target.checked ? props.trueValue : props.falseValue;
+
+			emit('change', event);
+			emit('update:modelValue', value);
+		}
+	};
+
+	const onFocus = (event: FocusEvent): void => {
+		hasFocus.value = true;
+		if (event.target instanceof HTMLInputElement) {
+			hasFocusVisible.value = event.target.matches(':focus-visible');
+		}
+		emit('focus', event);
+	};
+
+	const eventListeners = {
+		onBlur,
+		onChange,
+		onClick: (event: MouseEvent) => emit('click', event),
+		onFocus,
+		onInput: (event: Event) => emit('input', event),
+		onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+		onMousedown: (event: MouseEvent) => emit('mousedown', event),
+		onMouseup: (event: MouseEvent) => emit('mouseup', event),
+	};
+
+	return {
+		'aria-describedby': props.ariaDescribedby,
+		autofocus: props.autofocus,
+		checked: checked.value,
+		// There is no such thing as readonly checkbox so we disable and style it with css
+		disabled: props.disabled || props.readonly,
+		id: props.id,
+		indeterminate: props.indeterminate,
+		name: props.name,
+		required: props.required,
+		tabindex: props.disabled ? -1 : undefined,
+		type: 'checkbox',
+		value: value,
+		class: 'sr-only',
+		...eventListeners,
+	};
+});
+
+const slotAttributes = computed(() => ({
+	checked: checked.value,
+	disabled: props.disabled,
+	falseValue: props.falseValue,
+	focused: hasFocus.value,
+	focusVisible: hasFocusVisible.value,
+	hasErrors: props.hasErrors,
+	id: props.id,
+	name: props.name,
+	parsedValue: inputAttributes.value.value,
+	readonly: props.readonly,
+	trueValue: props.trueValue,
+	value: checked.value ? props.trueValue : props.falseValue,
+}));
+
+const iconAttributes = computed(() => {
+	let style: { [key: string]: string } = {};
+	if (props.color && isCssColor(props.color)) {
+		style.color = props.color;
+	}
+	return {
+		class: 'bb-base-switch-container__icon',
+		style,
+	};
+});
+
+/**
+ * Indeterminate is a very volatile prop that is reset upon clicking,
+ * this keeps the state and the prop aligned
+ */
+watch(
+	() => [props.modelValue, props.checked, props.indeterminate],
+	() => {
+		if (checkboxInput.value) {
+			checkboxInput.value.indeterminate = !!props.indeterminate;
+		}
+	}
+);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type {
+	BaseCheckboxEvents,
+	BaseCheckboxProps,
+	BaseCheckboxIconSlotProps,
+} from '../BaseCheckbox/types';
+
+/**
+ * Props for the switch component, extending BaseCheckbox with toggle-specific styling.
+ * Inherits all BaseCheckbox props with the same defaults for trueValue/falseValue.
+ */
+export type BaseSwitchProps = BaseCheckboxProps;
+
+export type BaseSwitchEvents = BaseCheckboxEvents;
+
+export type BaseSwitchSlots = {
+	/**
+	 * Replaces the default toggle thumb rendered inside the switch track.
+	 * @param checked - Whether the switch is currently on.
+	 * @param disabled - Whether the switch is disabled.
+	 * @param falseValue - The value emitted when the switch is off.
+	 * @param focused - Whether the underlying input currently has focus.
+	 * @param focusVisible - Whether focus is keyboard-visible (`:focus-visible`).
+	 * @param hasErrors - Whether the switch is in an error state.
+	 * @param id - The `id` attribute of the underlying input.
+	 * @param name - The `name` attribute of the underlying input.
+	 * @param parsedValue - The `trueValue` serialized to a string for form submission.
+	 * @param readonly - Whether the switch is read-only.
+	 * @param trueValue - The value emitted when the switch is on.
+	 * @param value - The current effective value (`trueValue` when on, `falseValue` when off).
+	 */
+	icon?: (props: BaseCheckboxIconSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+/* base switch */
+.bb-base-switch {
+	--color: var(--bb-primary);
+	--ring-color: color-mix(
+		in srgb,
+		var(--color),
+		transparent calc(var(--bb-ring-opacity) * 100%)
+	);
+	--border-w: 1px;
+	--radius: 30px;
+	cursor: pointer;
+	display: inline-flex;
+
+	&:has(:focus-visible) {
+		.bb-base-switch-container__icon {
+			box-shadow: 0px 0px 0px var(--bb-ring-size) var(--ring-color);
+		}
+	}
+
+	input[type='checkbox'] {
+		&:checked + .bb-base-switch-container .bb-base-switch-container__icon {
+			background-color: var(--color);
+		}
+
+		&:checked
+			+ .bb-base-switch-container
+			.bb-base-switch-container__icon-thumb {
+			translate: calc(
+					var(--bb-switch-w) - var(--bb-switch-thumb) -
+						var(--bb-switch-margin) - var(--border-w)
+				) -50%;
+		}
+
+		&:indeterminate
+			+ .bb-base-switch-container
+			.bb-base-switch-container__icon-thumb {
+			translate: -50% -50%;
+		}
+	}
+
+	&.bb-base-switch--disabled {
+		.bb-base-switch-container__icon {
+			--color: var(--bb-panel-disabled);
+			background-color: var(--color);
+			cursor: not-allowed;
+			.bb-base-switch-container__icon-thumb {
+				background-color: color-mix(
+					in srgb,
+					var(--bb-panel),
+					var(--bb-text) 40%
+				);
+			}
+		}
+	}
+
+	&--errors {
+		/* Add styles for error state if needed */
+	}
+
+	&--readonly {
+		/* Add styles for readonly state if needed */
+	}
+
+	.bb-base-switch-container {
+		display: inline-flex;
+		user-select: none;
+
+		&__icon {
+			background-color: color-mix(in srgb, var(--bb-panel), var(--bb-text) 20%);
+			border: var(--border-w) solid var(--bb-border);
+			border-radius: var(--radius);
+			box-shadow: 0px 0px 0px 0px var(--bb-ring);
+			display: inline-block;
+			height: var(--bb-switch-h);
+			position: relative;
+			transition-duration: 150ms;
+			transition-property: background-color, box-shadow;
+			width: var(--bb-switch-w);
+		}
+
+		.bb-base-switch-container__icon-thumb {
+			background-color: var(--bb-panel);
+			border-radius: calc(
+				(max(var(--bb-switch-margin), 0px) + var(--radius)) / 2
+			);
+			display: inline-block;
+			height: var(--bb-switch-thumb);
+			left: 0px;
+			position: absolute;
+			top: 50%;
+			transition-duration: 150ms;
+			transition-property: translate, left;
+			translate: var(--bb-switch-margin) -50%;
+			width: var(--bb-switch-thumb);
+		}
+	}
+}
+```

package/dist/ai/BaseSwitchGroup.md

@@ -0,0 +1,298 @@
+# BaseSwitchGroup
+
+## Template & Script
+
+```vue
+<template>
+	<OptionsContainer
+		ref="container"
+		class="bb-base-switch-group"
+		:direction="direction"
+		:has-errors="hasErrors"
+		:hide-label="hideLabel"
+		:loading="!!loading"
+		:loading-text="loadingText"
+		:no-data-text="noDataText"
+		:options="options"
+	>
+		<template #prepend><slot name="prepend"></slot></template>
+		<template #loading><slot name="loading"></slot></template>
+		<template #no-data><slot name="no-data"></slot></template>
+		<template #label="data"><slot name="label" v-bind="data"></slot></template>
+		<template #option:prepend="data"
+			><slot name="option:prepend" v-bind="data"></slot
+		></template>
+		<template #input="{ option, index }">
+			<BaseSwitch
+				:id="getId(option)"
+				:aria-describedby="ariaDescribedby"
+				:autofocus="autofocus && !index"
+				:checked="option.selected"
+				:color="color"
+				:disabled="option.disabled"
+				:has-errors="hasErrors"
+				:name="name"
+				:readonly="readonly"
+				:true-value="option.value"
+				v-bind="eventListeners"
+				@change="(event: Event) => onChange(event, option)"
+			>
+				<template v-if="$slots.icon" #icon="data">
+					<slot
+						:item="option.item"
+						name="icon"
+						:text="option.text"
+						v-bind="data"
+					/>
+				</template>
+			</BaseSwitch>
+		</template>
+		<template #option:append="data"
+			><slot name="option:append" v-bind="data"></slot
+		></template>
+		<template #append><slot name="append"></slot></template>
+	</OptionsContainer>
+</template>
+
+<script setup lang="ts" generic="T = any">
+import { ref, toRef } from 'vue';
+import type { Option as BaseOption } from '@/types/Option';
+import BaseSwitch from '../BaseSwitch/BaseSwitch.vue';
+import type { Option } from '@/types/Option';
+import OptionsContainer from '../OptionsContainer/OptionsContainer.vue';
+import { useItemsGetter } from '@/composables/useItemsGetter';
+import { useIndexById } from '@/composables/useIndexById';
+import { useBaseOptions } from '@/composables/useBaseOptions';
+import { useCoherence } from '@/composables/useCoherence';
+import { hash } from '@/utilities/functions/hash';
+import { useHashedWatcher } from '@/composables/useHashedWatcher';
+import { usePrefill } from '@/composables/usePrefill';
+import type {
+	BaseSwitchGroupProps,
+	BaseSwitchGroupEvents,
+	BaseSwitchGroupSlots,
+} from './types';
+
+const props = withDefaults(defineProps<BaseSwitchGroupProps<T>>(), {
+	depsDebounceTime: 0,
+	direction: 'horizontal',
+	items: () => [],
+	modelValueDebounceTime: 0,
+	max: Infinity,
+});
+
+const emit = defineEmits<BaseSwitchGroupEvents>();
+
+defineSlots<BaseSwitchGroupSlots<T>>();
+
+if (!Array.isArray(props.modelValue)) {
+	throw new Error('Model value must be an array in checkbox group.');
+}
+
+const container = ref<any>();
+const active = ref(false);
+
+const {
+	getter,
+	items: internalItems,
+	loading,
+} = useItemsGetter({
+	items: toRef(props, 'items'),
+	debounce: 0,
+});
+
+const alignToCoherenceSettings = () => {
+	if (props.enforceCoherence && !coherent.value) {
+		emit('update:modelValue', status.value.coherent);
+	}
+};
+
+const { hasPrefilled } = usePrefill({
+	trigger: true,
+	fn: async (isPrefill) => {
+		await getter(isPrefill, props.modelValue);
+		alignToCoherenceSettings();
+	},
+});
+
+const { data: modelValueIndexedByHash } = useIndexById({
+	items: toRef(props, 'modelValue'),
+});
+
+const { options } = useBaseOptions({
+	disabled: toRef(props, 'disabled'),
+	items: internalItems,
+	itemText: props.itemText,
+	itemValue: props.itemValue,
+	max: props.max,
+	selectable: true,
+	selectedIndexedByHash: modelValueIndexedByHash,
+});
+
+const onOptionSelected = async (option: BaseOption) => {
+	emit('update:modelValue', props.modelValue.concat(option.value));
+};
+
+const onOptionUnselected = async (option: BaseOption) => {
+	const copy = { ...modelValueIndexedByHash.value };
+	delete copy[option.valueHash];
+	emit('update:modelValue', Object.values(copy));
+};
+
+const { data: optionsIndexedByHash } = useIndexById({
+	items: options,
+	key: 'valueHash',
+});
+
+const { coherent, status } = useCoherence({
+	modelValue: toRef(props, 'modelValue'),
+
+	multiple: true,
+	iteratee: (item) => !!optionsIndexedByHash.value[hash(item)],
+});
+
+/**
+ * If multiple watchers are running we don't want to run the coherence watcher
+ * multiple times we only run it the last time
+ */
+let runningWatcher = 0;
+useHashedWatcher(
+	() => props.modelValue,
+	async () => {
+		runningWatcher++;
+		if (!coherent.value) {
+			await getter(false, props.modelValue);
+			alignToCoherenceSettings();
+		}
+		runningWatcher--;
+	},
+	{
+		debounce: props.modelValueDebounceTime,
+	}
+);
+useHashedWatcher(
+	() => [props.dependencies, props.items],
+	async () => {
+		if (!hasPrefilled.value) {
+			return;
+		}
+		runningWatcher++;
+		await getter(false, props.modelValue);
+		if (runningWatcher === 1) {
+			alignToCoherenceSettings();
+		}
+		runningWatcher--;
+	},
+	{
+		debounce: props.depsDebounceTime,
+	}
+);
+
+const getId = (option: Option) => {
+	if (!props.id) return undefined;
+	return [props.id, option.valueHash].filter(Boolean).join('-');
+};
+
+const onChange = (event: Event, option: Option) => {
+	emit('change', event);
+	if (!option.selected) {
+		onOptionSelected(option);
+	} else {
+		onOptionUnselected(option);
+	}
+};
+
+const onFocus = (event: FocusEvent) => {
+	emit('focus', event);
+	if (!active.value) {
+		document.addEventListener('focusin', onDocumentFocus, { passive: true });
+		document.addEventListener('click', onDocumentClick, { passive: true });
+		active.value = true;
+	}
+};
+
+const eventListeners = {
+	onBlur: (event: FocusEvent) => emit('blur', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	onFocus,
+	onInput: (event: Event) => emit('input', event),
+	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+	onMousedown: (event: MouseEvent) => emit('mousedown', event),
+	onMouseup: (event: MouseEvent) => emit('mouseup', event),
+};
+
+const onDocumentFocus = (event: FocusEvent) => {
+	if (event.target instanceof HTMLElement) {
+		if (!container.value?.$el.contains(event.target)) {
+			emit('inactive');
+			active.value = false;
+			document.removeEventListener('focusin', onDocumentFocus);
+			document.removeEventListener('click', onDocumentClick);
+		}
+	}
+};
+
+const onDocumentClick = (event: MouseEvent) => {
+	if (event.target instanceof HTMLElement) {
+		if (!container.value?.$el.contains(event.target)) {
+			emit('inactive');
+			active.value = false;
+			document.removeEventListener('focusin', onDocumentFocus);
+			document.removeEventListener('click', onDocumentClick);
+		}
+	}
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type {
+	BaseCheckboxGroupEvents,
+	BaseCheckboxGroupProps,
+	BaseCheckboxGroupSlots,
+} from '../BaseCheckboxGroup/types';
+
+/**
+ * Props for the switch group component that renders a list of switches from items.
+ * Extends BaseCheckboxGroup with switch-specific visuals instead of checkboxes.
+ */
+export type BaseSwitchGroupProps<T = any> = BaseCheckboxGroupProps<T>;
+
+export type BaseSwitchGroupEvents = BaseCheckboxGroupEvents;
+
+export type BaseSwitchGroupSlots<T = any> = BaseCheckboxGroupSlots<T>;
+```
+
+## Styles
+
+```css
+.bb-base-switch-group {
+	&.bb-cr-container {
+		&--horizontal {
+			.bb-cr-container-option {
+			}
+		}
+		&--vertical {
+			.bb-cr-container-option {
+			}
+		}
+
+		&__container {
+		}
+		&-option {
+			> .bb-base-switch {
+			}
+			&__text {
+				&--hidden {
+				}
+			}
+		}
+	}
+}
+```