bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseRating.md

@@ -0,0 +1,489 @@
+# BaseRating
+
+## Template & Script
+
+```vue
+<template>
+	<span v-bind="outerContainerAttributes" ref="container">
+		<span class="bb-base-rating__inner-container">
+			<slot name="prepend"></slot>
+			<label
+				v-for="(option, index) in options"
+				:key="option.value"
+				class="bb-base-rating__option"
+				:class="{ 'bb-base-rating__option--highlighted': option.highlighted }"
+			>
+				<span class="bb-base-rating__label-text sr-only">{{
+					option.value == 1
+						? t('rating.singleStar', option.value, props.stars).value
+						: t('rating.multipleStars', option.value, props.stars).value
+				}}</span>
+				<input
+					:id="option.id"
+					:aria-describedby="ariaDescribedby"
+					:autofocus="autofocus && !index"
+					:checked="option.checked"
+					class="sr-only"
+					:disabled="option.disabled"
+					:name="option.name"
+					:required="required"
+					type="radio"
+					:value="option.value"
+					v-bind="eventListeners"
+				/>
+				<slot
+					:id="option.id"
+					:checked="option.checked"
+					:disabled="option.disabled"
+					name="icon"
+					:size="option.size"
+					:value="option.value"
+				>
+					<svg
+						:height="option.size"
+						viewBox="0 0 24 24"
+						:width="option.size"
+						xmlns="http://www.w3.org/2000/svg"
+					>
+						<path
+							d="m8.243 7.34l-6.38.925l-.113.023a1 1 0 0 0-.44 1.684l4.622 4.499l-1.09 6.355l-.013.11a1 1 0 0 0 1.464.944l5.706-3l5.693 3l.1.046a1 1 0 0 0 1.352-1.1l-1.091-6.355l4.624-4.5l.078-.085a1 1 0 0 0-.633-1.62l-6.38-.926l-2.852-5.78a1 1 0 0 0-1.794 0L8.243 7.34z"
+							stroke-linecap="round"
+							stroke-linejoin="round"
+						/>
+					</svg>
+				</slot>
+			</label>
+			<slot name="append"></slot>
+		</span>
+	</span>
+</template>
+
+<script setup lang="ts">
+import { booleanishToBoolean } from '@/utilities/functions/booleanishToBoolean';
+import { computed, ref } from 'vue';
+import { identity } from '@/utilities/functions/identity';
+import { isCssColor } from '@/utilities/functions/isCssColor';
+import { isNotNil } from '@/utilities/functions/isNotNil';
+import type {
+	BaseRatingProps,
+	BaseRatingEvents,
+	BaseRatingSlots,
+} from './types';
+import type { Size } from '../BbIcon/BbIcon.vue';
+import { useLocale } from '@/composables/useLocale';
+
+type Option = {
+	checked: boolean;
+	disabled: boolean;
+	highlighted: boolean;
+	id?: string;
+	name: string;
+	size: number | undefined;
+	value: number;
+};
+
+const props = withDefaults(defineProps<BaseRatingProps>(), {
+	stars: 5,
+});
+
+defineSlots<BaseRatingSlots>();
+
+const emit = defineEmits<BaseRatingEvents>();
+
+const { t } = useLocale();
+
+const container = ref<HTMLElement>();
+const active = ref(false);
+
+const onInputChange = (event: Event) => {
+	emit('change', event);
+	if (event.target instanceof HTMLInputElement) {
+		if (event.target.checked) {
+			emit('update:modelValue', +event.target.value);
+		}
+	}
+};
+
+const onInputClick = (event: MouseEvent) => {
+	emit('click', event);
+	if (event.target instanceof HTMLInputElement) {
+		if (event.target.checked) {
+			if (+event.target.value === props.modelValue) {
+				emit('update:modelValue', null);
+			}
+		}
+	}
+};
+
+const onInputFocus = (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),
+	onChange: onInputChange,
+	onClick: onInputClick,
+	onFocus: onInputFocus,
+	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?.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?.contains(event.target)) {
+			emit('inactive');
+			active.value = false;
+			document.removeEventListener('focusin', onDocumentFocus);
+			document.removeEventListener('click', onDocumentClick);
+		}
+	}
+};
+
+const sizeMap: Size = {
+	xs: 12,
+	sm: 16,
+	md: 24,
+	lg: 28,
+	xl: 36,
+	xxl: 40,
+};
+
+const size = computed(() => {
+	let dimension: number | undefined;
+	if (typeof props.size === 'string') {
+		dimension = sizeMap[props.size as keyof Size] ?? parseInt(props.size, 10);
+	} else {
+		dimension = props.size;
+	}
+	return dimension;
+});
+
+const options = computed(() => {
+	return Array.from({ length: props.stars }, (_, index) => index + 1).map(
+		(number): Option => {
+			const id = props.id
+				? [props.id, number].filter(identity).join('_')
+				: undefined;
+
+			const checked = number === props.modelValue;
+			const highlighted = !!(props.modelValue && number <= props.modelValue);
+
+			const disabled = !!(
+				props.disabled ||
+				(isNotNil(props.readonly) ? booleanishToBoolean(props.readonly) : false)
+			);
+
+			return {
+				checked,
+				disabled,
+				highlighted,
+				id,
+				name: props.name,
+				size: size.value,
+				value: number,
+			};
+		}
+	);
+});
+
+const outerContainerAttributes = computed(() => {
+	let style: { [key: string]: string } = {};
+	if (props.color && isCssColor(props.color)) {
+		style['--color'] = props.color;
+	}
+	if (size.value) {
+		style['--size'] = `${size.value}px`;
+	}
+	return {
+		class: {
+			'bb-base-rating': true,
+			'bb-base-rating--has-value': props.modelValue,
+			'bb-base-rating--disabled': props.disabled,
+			'bb-base-rating--errors': props.hasErrors,
+			'bb-base-rating--readonly': props.readonly,
+			[`bb-base-rating--${props.color}`]:
+				props.color && !isCssColor(props.color),
+		},
+		style,
+	};
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { InputHTMLAttributes, HTMLAttributes } from 'vue';
+import type { BbIconProps, Size } from '../BbIcon/BbIcon.vue';
+
+/**
+ * Props for the star rating input component with customizable star count and visual feedback.
+ */
+export type BaseRatingProps = {
+	/**
+	 * Id(s) of elements describing this rating input for assistive technologies.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+
+	/**
+	 * 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;
+
+	/**
+	 * Disable all interactions with the rating.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Apply error styling to the rating.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Explicit id for the rating container. Used to generate ids for individual stars.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * v-model value: the selected rating (1 to `stars`) or `null` for no selection.
+	 */
+	modelValue: null | number;
+
+	/**
+	 * Shared name attribute for all star radio inputs (required for grouping).
+	 */
+	name: Exclude<InputHTMLAttributes['name'], undefined>;
+
+	/**
+	 * Make the rating read-only while keeping it visible.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Mark the rating as required.
+	 */
+	required?: boolean;
+
+	/**
+	 * Maximum number of stars to render and maximum selectable rating value.
+	 * @defaultValue `5`
+	 */
+	stars?: number;
+} & Pick<BbIconProps, 'size'>;
+
+export type BaseRatingEvents = {
+	/**
+	 * Emitted when a star input loses focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'blur', event: FocusEvent): void;
+	/**
+	 * Emitted when the selected rating changes.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'change', event: Event): void;
+	/**
+	 * Emitted when a star input receives a click.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'click', event: MouseEvent): void;
+	/**
+	 * Emitted when a star input gains focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted when focus/click moves outside the rating after it was active.
+	 */
+	(e: 'inactive'): void;
+	/**
+	 * Emitted on native input events from the star inputs.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'input', event: Event): void;
+	/**
+	 * Emitted for keyboard interaction on a star input.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/**
+	 * Emitted when a pointing device button is pressed over a star input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mousedown', event: MouseEvent): void;
+	/**
+	 * Emitted when a pointing device button is released over a star input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mouseup', event: MouseEvent): void;
+	/**
+	 * Emitted with the selected rating (1 to `stars`) when clicked, or `null` when
+	 * clicking the already-selected star deselects it.
+	 */
+	(e: 'update:modelValue', value: number | null): void;
+};
+
+/**
+ * Props exposed by the `icon` slot for each rating star.
+ */
+export type BaseRatingIconSlotProps = {
+	/**
+	 * Whether this star is filled (i.e. the rating value is ≥ this star's value).
+	 */
+	checked: boolean;
+	/**
+	 * Whether the rating is disabled.
+	 */
+	disabled: boolean;
+	/**
+	 * The `id` of this star's underlying radio input.
+	 */
+	id?: string;
+	/**
+	 * The rendered size of the icon in pixels, from the `size` prop.
+	 */
+	size: number | undefined;
+	/**
+	 * The numeric value this star represents (1-based).
+	 */
+	value: number;
+};
+
+export type BaseRatingSlots = {
+	/**
+	 * Replaces the default star SVG for each rating option.
+	 */
+	icon?: (props: BaseRatingIconSlotProps) => any;
+	/**
+	 * Content rendered before the row of rating stars.
+	 */
+	prepend?: (props: object) => any;
+	/**
+	 * Content rendered after the row of rating stars.
+	 */
+	append?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-rating {
+	--color: var(--bb-primary);
+	--size: var(--bb-rating-size);
+
+	&.bb-base-rating--has-value {
+		.bb-base-rating__inner-container {
+			.bb-base-rating__option {
+				color: var(--color);
+			}
+			.bb-base-rating__option:not(.bb-base-rating__option--highlighted) {
+				color: var(--bb-panel);
+			}
+		}
+	}
+	&:not(.bb-base-rating--disabled):not(.bb-base-rating--readonly) {
+		.bb-base-rating__inner-container {
+			&:hover {
+				.bb-base-rating__option {
+					color: var(--color);
+
+					&:hover ~ .bb-base-rating__option {
+						color: var(--bb-panel);
+					}
+				}
+			}
+		}
+		.bb-base-rating__option {
+			aspect-ratio: 1 / 1;
+			border-radius: 0.375rem;
+
+			&:hover {
+				transform: scale(1.25);
+			}
+
+			&:has(:focus-visible) {
+				box-shadow: 0px 0px 0px var(--bb-ring-size)
+					color-mix(
+						in srgb,
+						var(--color) calc(var(--bb-ring-opacity) * 100%),
+						transparent
+					);
+			}
+		}
+	}
+	&.bb-base-rating--disabled {
+		--color: color-mix(in srgb, var(--bb-panel), var(--bb-text) 40%);
+		.bb-base-rating__inner-container {
+			.bb-base-rating__option {
+				cursor: not-allowed;
+			}
+
+			.bb-base-rating__option:not(.bb-base-rating__option--highlighted) {
+				color: var(--bb-panel-disabled);
+			}
+		}
+	}
+
+	&__inner-container {
+		column-gap: var(--bb-base-rating-spacing);
+		display: inline-flex;
+		flex-wrap: wrap;
+	}
+	&__option {
+		align-items: center;
+		box-shadow: 0px 0px 0px 0px transparent;
+		color: var(--bb-panel);
+		cursor: pointer;
+		display: flex;
+		justify-content: center;
+		padding-left: 2px;
+		padding-right: 2px;
+		transition: all 0.2s ease;
+
+		.bb-base-rating__label-text {
+		}
+
+		input[type='radio'] {
+		}
+		svg {
+			fill: currentColor;
+			height: var(--size);
+			stroke: var(--bb-border);
+			stroke-width: 1;
+			transition: color 300ms ease;
+			width: var(--size);
+		}
+	}
+}
+```