bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseCheckbox.md

@@ -0,0 +1,494 @@
+# BaseCheckbox
+
+## Template & Script
+
+```vue
+<template>
+	<span v-bind="containerAttributes">
+		<input v-if="!checked && submitWhenFalse" v-bind="hiddenInputAttributes" />
+		<input v-bind="inputAttributes" ref="checkboxInput" />
+		<span aria-hidden="true" class="bb-base-checkbox-container">
+			<slot name="icon" v-bind="slotAttributes">
+				<svg
+					class="bb-base-checkbox-container__icon"
+					viewBox="276.411 158.834 114.971 114.97"
+				>
+					<path
+						d="M 297.574 224.786 L 318.309 243.134 L 371.568 189.232"
+						fill="none"
+						stroke-linecap="round"
+						stroke-width="14px"
+					></path>
+				</svg>
+			</slot>
+		</span>
+	</span>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { isCssColor } from '@/utilities/functions/isCssColor';
+import { booleanishToBoolean } from '@/utilities/functions/booleanishToBoolean';
+import { isEqual } from '@/utilities/functions/isEqual';
+import type {
+	BaseCheckboxProps,
+	BaseCheckboxEvents,
+	BaseCheckboxIconSlotProps,
+} from './types';
+
+const props = withDefaults(defineProps<BaseCheckboxProps>(), {
+	trueValue: true,
+	falseValue: false,
+});
+
+const emit = defineEmits<BaseCheckboxEvents>();
+
+defineSlots<{
+	/**
+	 * Replaces the default checkmark SVG rendered inside the checkbox box.
+	 */
+	icon?: (props: BaseCheckboxIconSlotProps) => any;
+}>();
+
+const checkboxInput = ref<HTMLInputElement | null>(null);
+
+const checked = computed(() => {
+	if (props.checked) return booleanishToBoolean(props.checked);
+	return isEqual(props.trueValue, props.modelValue);
+});
+const hasFocus = ref(false);
+const hasFocusVisible = ref(false);
+
+const handleBlur = (event: FocusEvent): void => {
+	hasFocus.value = false;
+	hasFocusVisible.value = false;
+	emit('blur', event);
+};
+
+const handleChange = (event: Event): void => {
+	if (event.target instanceof HTMLInputElement) {
+		const value = event.target.checked ? props.trueValue : props.falseValue;
+		emit('change', event);
+		emit('update:modelValue', value);
+	}
+};
+
+const handleFocus = (event: FocusEvent): void => {
+	hasFocus.value = true;
+	if (event.target instanceof HTMLInputElement) {
+		hasFocusVisible.value = event.target.matches(':focus-visible');
+	}
+	emit('focus', event);
+};
+
+const containerAttributes = computed(() => {
+	const attributes: Record<string, any> = {
+		class: {
+			'bb-base-checkbox': true,
+			'bb-base-checkbox--disabled': props.disabled,
+			'bb-base-checkbox--errors': props.hasErrors,
+			'bb-base-checkbox--indeterminate': props.indeterminate,
+			'bb-base-checkbox--readonly': props.readonly,
+			[`bb-base-checkbox--${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 = (item: unknown): string =>
+	typeof item === 'string' ? item : JSON.stringify(item);
+
+const hiddenInputAttributes = computed(() => {
+	const value = makeInputValue(props.falseValue);
+	return {
+		disabled: props.disabled,
+		name: props.name,
+		type: 'hidden',
+		value: value,
+	};
+});
+
+const eventListeners = {
+	onBlur: handleBlur,
+	onChange: handleChange,
+	onFocus: handleFocus,
+	onClick: (event: MouseEvent) => emit('click', 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),
+};
+
+const inputAttributes = computed(() => {
+	const value = makeInputValue(props.trueValue);
+
+	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,
+		...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,
+}));
+
+/**
+ * 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 { HTMLAttributes, InputHTMLAttributes } from 'vue';
+
+export type BaseCheckboxProps = {
+	/**
+	 * ID of the element that describes this checkbox for assistive technologies.
+	 * Forwarded to the input as `aria-describedby`.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+	/**
+	 * Automatically focuses the checkbox when the page/component loads.
+	 * Use sparingly to avoid usability issues.
+	 * @defaultValue `false`
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+	/**
+	 * Forces the checkbox checked state (controlled prop). Accepts booleanish
+	 * values (`true`/`false` or `'true'`/`'false'`). When omitted, the checked
+	 * state is derived from `modelValue === trueValue`.
+	 * @defaultValue `false`
+	 */
+	checked?: boolean | 'true' | 'false';
+	/**
+	 * Visual color of the checkbox.
+	 * - If a valid CSS color (HEX/RGB/HSL/etc.), it is applied via the `--color`
+	 *   CSS variable.
+	 * - Otherwise, a BEM modifier class `bb-base-checkbox--{color}` is added for
+	 *   theme-based styling.
+	 */
+	color?: string;
+	/**
+	 * Disables user interaction. Also applied when `readonly` is set, since
+	 * native checkboxes do not support `readonly`.
+	 * @defaultValue `false`
+	 */
+	disabled?: boolean;
+	/**
+	 * Value submitted/emitted when the checkbox is unchecked. Accepts any
+	 * serializable value. Serialized to a string for form submission.
+	 * @defaultValue `false`
+	 */
+	falseValue?: any;
+	/**
+	 * Puts the component into an error state (adds error styling class `bb-base-checkbox--errors`).
+	 * @defaultValue `false`
+	 */
+	hasErrors?: boolean;
+	/**
+	 * Identifier forwarded to the input.
+	 */
+	id?: HTMLAttributes['id'];
+	/**
+	 * Renders the checkbox in the indeterminate state (neither checked nor
+	 * unchecked). Note: the native `indeterminate` state resets on user click;
+	 * this component re-applies it to keep UI and prop aligned.
+	 * @defaultValue `false`
+	 */
+	indeterminate?: InputHTMLAttributes['indeterminate'];
+	/**
+	 * Bound value for `v-model`. When it equals `trueValue` the checkbox is
+	 * considered checked, otherwise unchecked.
+	 */
+	modelValue?: any;
+	/**
+	 * Name attribute of the input, used during form submission.
+	 */
+	name?: InputHTMLAttributes['name'];
+	/**
+	 * Puts the input in a read-only state. Since checkboxes do not support
+	 * native `readonly`, the input is disabled while styled as read-only.
+	 * @defaultValue `false`
+	 */
+	readonly?: boolean;
+	/**
+	 * Marks the input as required for form validation.
+	 * @defaultValue `false`
+	 */
+	required?: boolean;
+	/**
+	 * When unchecked, submits a hidden input with `falseValue` so that a value
+	 * is still posted with the form. When checked, the visible input submits
+	 * `trueValue` as usual.
+	 * @defaultValue `false`
+	 */
+	submitWhenFalse?: boolean;
+	/**
+	 * Value submitted/emitted when the checkbox is checked. Accepts any
+	 * serializable value. Serialized to a string for form submission.
+	 * @defaultValue `true`
+	 */
+	trueValue?: any;
+};
+
+export type BaseCheckboxEvents = {
+	/**
+	 * Emitted when the native input loses focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'blur', event: FocusEvent): void;
+	/**
+	 * Emitted when the checkbox checked state changes.
+	 * Forwards the original DOM `Event` from the input.
+	 */
+	(e: 'change', event: Event): void;
+	/**
+	 * Emitted when the input receives a click interaction.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'click', event: MouseEvent): void;
+	/**
+	 * Emitted when the native input gains focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted on native input events from the checkbox input.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'input', event: Event): void;
+	/**
+	 * Emitted for keyboard interaction on the input.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/**
+	 * Emitted when a pointing device button is pressed over the input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mousedown', event: MouseEvent): void;
+	/**
+	 * Emitted when a pointing device button is released over the input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mouseup', event: MouseEvent): void;
+	/**
+	 * Emitted on checked-state changes with the effective model value:
+	 * - `trueValue` when checked
+	 * - `falseValue` when unchecked
+	 */
+	(e: 'update:modelValue', value: any): void;
+};
+
+/**
+ * Props exposed by the `icon` slot.
+ *
+ * These values are normalized at runtime so consumers receive stable types
+ * (not optional/undefined booleans).
+ */
+export type BaseCheckboxIconSlotProps = {
+	/**
+	 * Whether the checkbox is currently checked.
+	 * @defaultValue `false`
+	 */
+	checked: boolean;
+	/**
+	 * Whether the checkbox is disabled.
+	 * Mirrors `props.disabled`.
+	 * @defaultValue `false`
+	 */
+	disabled: boolean;
+	/**
+	 * Value emitted/submitted when unchecked.
+	 * Mirrors `props.falseValue`.
+	 * @defaultValue `false`
+	 */
+	falseValue: any;
+	/**
+	 * Whether the native input currently has focus.
+	 * @defaultValue `false`
+	 */
+	focused: boolean;
+	/**
+	 * Whether focus is keyboard-visible (`:focus-visible`).
+	 * @defaultValue `false`
+	 */
+	focusVisible: boolean;
+	/**
+	 * Whether the checkbox is in an error state.
+	 * Mirrors `props.hasErrors`.
+	 * @defaultValue `false`
+	 */
+	hasErrors: boolean;
+	/**
+	 * The `id` attribute forwarded to the native input.
+	 * Mirrors `props.id`.
+	 */
+	id: BaseCheckboxProps['id'];
+	/**
+	 * The `name` attribute forwarded to the native input.
+	 * Mirrors `props.name`.
+	 */
+	name: BaseCheckboxProps['name'];
+	/**
+	 * Serialized `trueValue` used by native form submission.
+	 */
+	parsedValue: string;
+	/**
+	 * Whether the checkbox is readonly.
+	 * Mirrors `props.readonly`.
+	 * @defaultValue `false`
+	 */
+	readonly: boolean;
+	/**
+	 * Value emitted/submitted when checked.
+	 * Mirrors `props.trueValue`.
+	 * @defaultValue `true`
+	 */
+	trueValue: any;
+	/**
+	 * Current effective value (`trueValue` when checked, otherwise `falseValue`).
+	 */
+	value: any;
+};
+
+/**
+ * @deprecated Use `BaseCheckboxIconSlotProps`.
+ */
+export type SlotAttributes = BaseCheckboxIconSlotProps;
+```
+
+## Styles
+
+```css
+.bb-base-checkbox {
+	--color: var(--bb-primary);
+	--check-color: var(--bb-contrasting);
+	display: inline-flex;
+
+	&:has(:focus-visible) {
+		.bb-base-checkbox-container__icon {
+			box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
+		}
+	}
+
+	input[type='checkbox'] {
+		border-width: 0;
+		clip: rect(0, 0, 0, 0);
+		height: 1px;
+		margin: -1px;
+		overflow: hidden;
+		padding: 0;
+		position: absolute;
+		white-space: nowrap;
+		width: 1px;
+
+		&:checked + .bb-base-checkbox-container {
+			.bb-base-checkbox-container__icon {
+				background-color: var(--color);
+				border-color: var(--color);
+
+				path {
+					stroke-dashoffset: 0;
+				}
+			}
+		}
+
+		&:indeterminate
+			+ .bb-base-checkbox-container
+			.bb-base-checkbox-container__icon {
+			background-color: var(--color);
+		}
+	}
+
+	&.bb-base-checkbox--disabled {
+		--check-color: color-mix(in srgb, var(--bb-panel), var(--bb-text) 40%);
+
+		input[type='checkbox'] + .bb-base-checkbox-container,
+		.bb-base-checkbox-container {
+			.bb-base-checkbox-container__icon {
+				background-color: var(--bb-panel-disabled);
+				border-color: var(--bb-border);
+			}
+		}
+	}
+	&--errors {
+	}
+	&--readonly {
+	}
+
+	.bb-base-checkbox-container {
+		align-items: center;
+		display: inline-flex;
+		user-select: none;
+
+		&__icon {
+			background-color: var(--bb-panel);
+			border-color: var(--bb-border);
+			border-radius: min(6px, var(--bb-radius));
+			border-style: solid;
+			border-width: 1px;
+			box-shadow: 0px 0px 0px 0px var(--bb-ring);
+			cursor: pointer;
+			display: inline-block;
+			height: var(--bb-checkbox-w);
+			transition-duration: 300ms;
+			transition-property:
+				color, background-color, border-color, text-decoration-color, box-shadow;
+			transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+			width: var(--bb-checkbox-w);
+
+			path {
+				stroke: var(--check-color);
+				stroke-dasharray: 105;
+				stroke-dashoffset: 105;
+				transition: stroke-dashoffset 0.3s;
+			}
+		}
+	}
+}
+```