bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseRadio.md

@@ -0,0 +1,405 @@
+# BaseRadio
+
+## Template & Script
+
+```vue
+<template>
+	<span v-bind="containerAttributes">
+		<input v-bind="inputAttributes" class="sr-only" />
+		<span aria-hidden="true" class="bb-base-radio-container">
+			<slot name="icon" v-bind="slotAttributes">
+				<span v-bind="iconAttributes"></span>
+			</slot>
+		</span>
+	</span>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { isCssColor } from '@/utilities/functions/isCssColor';
+import { when } from '@/utilities/functions/when';
+import type {
+	BaseRadioProps,
+	BaseRadioEvents,
+	BaseRadioSlots,
+	BaseRadioIconSlotProps,
+} from './types';
+
+const props = defineProps<BaseRadioProps>();
+
+const emit = defineEmits<BaseRadioEvents>();
+
+defineSlots<BaseRadioSlots>();
+
+const checked = computed(() => {
+	if (props.checked) return true;
+	return JSON.stringify(props.modelValue) === JSON.stringify(props.value);
+});
+const hasFocus = ref(false);
+const hasFocusVisible = ref(false);
+
+const containerAttributes = computed(() => {
+	const attributes: Record<string, any> = {
+		class: {
+			'bb-base-radio': true,
+			'bb-base-radio--disabled': props.disabled,
+			'bb-base-radio--errors': props.hasErrors,
+			'bb-base-radio--readonly': props.readonly,
+			[`bb-base-radio--${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 inputAttributes = computed(() => {
+	const value = makeInputValue(props.value);
+
+	const onBlur = (event: FocusEvent): void => {
+		hasFocus.value = false;
+		hasFocusVisible.value = false;
+		emit('blur', event);
+	};
+	const onChange = (event: Event): void => {
+		emit('change', event);
+		emit('update:modelValue', props.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 radio so we disable and style it with css
+		disabled: props.disabled || props.readonly,
+		id: props.id,
+		name: props.name,
+		required: props.required,
+		tabindex: props.disabled ? -1 : undefined,
+		type: 'radio',
+		value: value,
+		...eventListeners,
+	};
+});
+
+const slotAttributes = computed<BaseRadioIconSlotProps>(() => ({
+	checked: checked.value,
+	disabled: props.disabled,
+	focused: hasFocus.value,
+	focusVisible: hasFocusVisible.value,
+	hasErrors: props.hasErrors,
+	id: props.id,
+	name: props.name,
+	parsedValue: inputAttributes.value.value,
+	readonly: props.readonly,
+	value: props.value,
+}));
+
+const iconAttributes = computed(() => {
+	let style: { [key: string]: string } = {};
+	if (props.color && isCssColor(props.color)) {
+		style.color = props.color;
+	}
+	return {
+		class: 'bb-base-radio-container__icon',
+		style,
+	};
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { InputHTMLAttributes, HTMLAttributes } from 'vue';
+
+/**
+ * Props for the base radio control that exposes a stylable icon slot while keeping native semantics.
+ */
+export type BaseRadioProps = {
+	/**
+	 * Id(s) of descriptive elements associated with the radio.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+
+	/**
+	 * Focus the control automatically after mount.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Force the radio into a checked state regardless of `modelValue`.
+	 */
+	checked?: InputHTMLAttributes['checked'];
+
+	/**
+	 * Name of the theme color to apply or any valid CSS color string.
+	 */
+	color?: string;
+
+	/**
+	 * Disable the radio. When combined with `readonly`, the control is also disabled to mimic native behaviour.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Apply the error styling class.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Explicit id for the underlying input element.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Current v-model value used to determine checked state.
+	 */
+	modelValue?: any;
+
+	/**
+	 * Shared group name for the radio input (required to join options).
+	 */
+	name: InputHTMLAttributes['name'];
+
+	/**
+	 * Treat the radio as read-only. Implemented by disabling the input while preserving styling hooks.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Mark the radio as required within its group.
+	 */
+	required?: boolean;
+
+	/**
+	 * Value emitted when the radio becomes checked. Accepts any serializable value.
+	 */
+	value: any;
+};
+
+export type BaseRadioEvents = {
+	/**
+	 * Emitted when the native input loses focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'blur', event: FocusEvent): void;
+	/**
+	 * Emitted when the radio selection changes.
+	 * Forwards the original DOM `Event`.
+	 */
+	(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 radio 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 when the radio becomes selected, carrying the radio's `value` prop.
+	 */
+	(e: 'update:modelValue', value: any): void;
+};
+
+/**
+ * Props exposed by the `icon` slot for custom radio visuals.
+ *
+ * These values are normalized at runtime so consumers receive stable types
+ * (not optional/undefined booleans).
+ */
+export type BaseRadioIconSlotProps = {
+	/**
+	 * Whether the radio is currently selected.
+	 */
+	checked: boolean;
+	/**
+	 * Whether the radio is disabled.
+	 * Mirrors `props.disabled`.
+	 */
+	disabled: Exclude<BaseRadioProps['disabled'], undefined>;
+	/**
+	 * Whether the native input currently has focus.
+	 */
+	focused: boolean;
+	/**
+	 * Whether focus is keyboard-visible (`:focus-visible`).
+	 */
+	focusVisible: boolean;
+	/**
+	 * Whether the radio is in an error state.
+	 * Mirrors `props.hasErrors`.
+	 */
+	hasErrors: Exclude<BaseRadioProps['hasErrors'], undefined>;
+	/**
+	 * The `id` attribute of the underlying input.
+	 * Mirrors `props.id`.
+	 */
+	id: BaseRadioProps['id'];
+	/**
+	 * The `name` attribute of the underlying input.
+	 * Mirrors `props.name`.
+	 */
+	name: BaseRadioProps['name'];
+	/**
+	 * The radio value serialized to a string for form submission.
+	 */
+	parsedValue: string;
+	/**
+	 * Whether the radio is read-only.
+	 * Mirrors `props.readonly`.
+	 */
+	readonly: BaseRadioProps['readonly'];
+	/**
+	 * The effective value of this radio option (the `value` prop).
+	 */
+	value: any;
+};
+
+export type BaseRadioSlots = {
+	/**
+	 * Replaces the default radio dot visual rendered inside the radio container.
+	 * @param checked - Whether the radio is currently selected.
+	 * @param disabled - Whether the radio is disabled.
+	 * @param focused - Whether the radio input currently has focus.
+	 * @param focusVisible - Whether focus is keyboard-visible (`:focus-visible`).
+	 * @param hasErrors - Whether the radio 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 radio value serialized to a string for form submission.
+	 * @param readonly - Whether the radio is read-only.
+	 * @param value - The current effective value of this radio option.
+	 */
+	icon?: (props: BaseRadioIconSlotProps) => any;
+};
+
+/**
+ * @deprecated Use `BaseRadioIconSlotProps`.
+ */
+export type SlotAttributes = BaseRadioIconSlotProps;
+```
+
+## Styles
+
+```css
+/* base radio */
+.bb-base-radio {
+	--color: var(--bb-primary);
+	display: inline-flex;
+
+	&:has(:focus-visible) {
+		.bb-base-radio-container__icon {
+			/* Replacing Tailwind's `ring` utility */
+			box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
+		}
+	}
+
+	input[type='radio'] {
+		&:checked + .bb-base-radio-container .bb-base-radio-container__icon {
+			&::after {
+				height: calc(100% - 2px - var(--bb-radio-space));
+				width: calc(100% - 2px - var(--bb-radio-space));
+			}
+		}
+	}
+
+	&.bb-base-radio--disabled {
+		.bb-base-radio-container__icon {
+			background-color: var(--bb-panel-disabled);
+			--color: color-mix(in srgb, var(--bb-panel), var(--bb-text) 40%);
+		}
+	}
+	&--errors {
+	}
+	&--readonly {
+	}
+
+	.bb-base-radio-container {
+		display: inline-flex;
+		user-select: none;
+
+		&__icon {
+			background-color: var(--bb-panel);
+			border: 1px solid var(--bb-border);
+			border-radius: 999px;
+			box-shadow: 0 0 0 3px transparent;
+			box-shadow: 0px 0px 0px 0px var(--bb-ring);
+			cursor: pointer;
+			display: inline-block;
+			height: var(--bb-checkbox-w);
+			position: relative;
+			transition: all 0.2s ease;
+			width: var(--bb-checkbox-w);
+
+			&::after {
+				background-color: var(--color);
+				border-radius: 999px;
+				content: '';
+				height: 0;
+				left: 50%;
+				position: absolute;
+				top: 50%;
+				transform: translate(-50%, -50%);
+				transition: all 0.2s ease;
+				width: 0;
+			}
+		}
+	}
+}
+```