bitboss-ui 2.1.135 → 3.0.0-alpha.1

package/dist/ai/source/BbBaseSlider.md

@@ -0,0 +1,1085 @@
+# BbBaseSlider — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbBaseSlider.md](../BbBaseSlider.md).
+>
+> Safety level: **Reference Only - Internal** — do not use in consumer-facing code unless explicitly requested.
+
+## Template & Script
+
+```vue
+<template>
+	<span v-bind="outerContainerAttributes">
+		<slot :decrease="decrease" :increase="increase" name="prepend"></slot>
+		<span
+			ref="container"
+			v-bind="innerContainerAttributes"
+			class="bb-base-slider__slider-container"
+		>
+			<span v-if="ticks.length" class="bb-base-slider__ticks-container">
+				<span
+					v-for="tick in ticks"
+					:key="tick.value"
+					class="bb-base-slider__tick"
+					><slot
+						:active="tick.active"
+						name="tick"
+						:percent="tick.percent"
+						:value="tick.value"
+				/></span>
+			</span>
+			<input
+				:id="id"
+				ref="hiddenInput"
+				class="sr-only"
+				:disabled="disabled"
+				:name="name"
+				:readonly="true"
+				:required="required"
+				:tabindex="-1"
+				type="text"
+				:value="JSON.stringify(modelValue)"
+				@focus="onFocusHiddenInput"
+			/>
+			<span ref="track" class="bb-base-slider__track-container">
+				<span class="bb-base-slider__track-fill"></span>
+				<span v-bind="sliderBackgroundAttributes"></span>
+			</span>
+			<span
+				v-if="props.range"
+				v-bind="listeners"
+				key="thumblower"
+				ref="thumblower"
+				:aria-describedby="ariaDescribedby"
+				aria-orientation="horizontal"
+				:aria-readonly="readonly ? 'true' : undefined"
+				:aria-valuemax="max"
+				:aria-valuemin="min"
+				:aria-valuenow="valueNowLower"
+				class="bb-base-slider__thumb-container"
+				data-thumb="lower"
+				role="slider"
+				:style="{ left: getThumbAnchorPosition(internalValueLower) }"
+				:tabindex="disabled ? -1 : 0"
+				@focus="onFocus"
+				@keydown="onKeydown"
+			>
+				<span
+					class="bb-base-slider__thumb bb-base-slider__thumb--lower"
+					:class="{
+						'bb-base-slider__thumb--focused': targetThumb === 'lower',
+					}"
+					:style="{
+						transform: `translateY(-50%) ${!disableThumbTranslate ? `translateX(-${internalValueLower}%)` : `translateX(-50%)`}`,
+						left: `0`,
+					}"
+					><slot
+						:focused="targetThumb === 'lower'"
+						name="thumb:lower"
+						:percent="internalValueLower"
+						:value="valueNowLower"
+						><slot
+							:focused="targetThumb === 'lower'"
+							name="thumb"
+							:percent="internalValueLower"
+							:value="valueNowLower" /></slot
+				></span>
+			</span>
+			<span
+				v-bind="listeners"
+				key="thumbhigher"
+				ref="thumbhigher"
+				:aria-describedby="ariaDescribedby"
+				aria-orientation="horizontal"
+				:aria-readonly="readonly ? 'true' : undefined"
+				:aria-valuemax="max"
+				:aria-valuemin="min"
+				:aria-valuenow="valueNowHigher"
+				class="bb-base-slider__thumb-container"
+				data-thumb="higher"
+				role="slider"
+				:style="{ left: getThumbAnchorPosition(internalValueHigher) }"
+				:tabindex="disabled ? -1 : 0"
+				@focus="onFocus"
+				@keydown="onKeydown"
+			>
+				<span
+					class="bb-base-slider__thumb bb-base-slider__thumb--higher"
+					:class="{
+						'bb-base-slider__thumb--focused': targetThumb === 'higher',
+					}"
+					:style="{
+						transform: `translateY(-50%) ${!disableThumbTranslate ? `translateX(-${internalValueHigher}%)` : `translateX(-50%)`}`,
+						left: `0`,
+					}"
+					><slot
+						:focused="targetThumb === 'higher'"
+						name="thumb:higher"
+						:percent="internalValueHigher"
+						:value="valueNowHigher"
+						><slot
+							:focused="targetThumb === 'higher'"
+							name="thumb"
+							:percent="internalValueHigher"
+							:value="valueNowHigher" /></slot
+				></span>
+			</span>
+		</span>
+		<slot :decrease="decrease" :increase="increase" name="append"></slot>
+	</span>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { head } from '@/utilities/functions/head';
+import { isNil } from '@/utilities/functions/isNil';
+import {
+	getAsPercentage,
+	getAsPercentageBetween,
+	getValueFromPercentageInInterval,
+} from '@/utilities/functions/percentage';
+import { snapToStep } from '@/utilities/functions/snapToStep';
+import { last } from '@/utilities/functions/last';
+import { transpose } from '@/utilities/functions/transpose';
+import { clamp } from '@/utilities/functions/clamp';
+import { useLogger } from '@/composables/useLogger';
+import type {
+	BaseSliderProps,
+	BaseSliderEvents,
+	BaseSliderSlots,
+} from './types';
+
+const props = withDefaults(defineProps<BaseSliderProps>(), {
+	maxPrecision: 2,
+	max: 100,
+	min: 0,
+	modelValue: 0,
+	step: 1,
+});
+
+const emit = defineEmits<BaseSliderEvents>();
+
+defineSlots<BaseSliderSlots>();
+
+const logger = useLogger();
+
+if (
+	props.min < Number.MIN_SAFE_INTEGER ||
+	props.max > Number.MAX_SAFE_INTEGER
+) {
+	logger.throw('BaseSlider min or max is too large');
+}
+
+if (!Number.isFinite(props.min) || !Number.isFinite(props.max)) {
+	logger.throw('BaseSlider min and max must be finite numbers', TypeError);
+}
+
+if (props.max <= props.min) {
+	logger.throw('BaseSlider max must be greater than min', RangeError);
+}
+
+if (!Number.isFinite(props.step) || props.step <= 0) {
+	logger.throw(
+		'BaseSlider step must be a finite number greater than 0',
+		RangeError
+	);
+}
+
+if (!Number.isFinite(props.maxPrecision) || props.maxPrecision < 0) {
+	logger.throw(
+		'BaseSlider maxPrecision must be a non-negative number',
+		RangeError
+	);
+}
+
+const container = ref<HTMLElement>();
+const track = ref<HTMLElement>();
+const thumblower = ref<HTMLElement>();
+const thumbhigher = ref<HTMLElement>();
+const hiddenInput = ref<HTMLInputElement>();
+const internalValueLower = ref(0);
+const internalValueHigher = ref(0);
+const valueNowLower = computed(() => {
+	if (Array.isArray(props.modelValue))
+		return head(props.modelValue) ?? undefined;
+	return isNil(props.modelValue) ? undefined : Number(props.modelValue);
+});
+const valueNowHigher = computed(() => {
+	if (Array.isArray(props.modelValue))
+		return last(props.modelValue) ?? undefined;
+	return isNil(props.modelValue) ? undefined : Number(props.modelValue);
+});
+const sortedInternalValues = computed(() => {
+	return [internalValueLower.value, internalValueHigher.value].sort(
+		(a, b) => a - b
+	);
+});
+
+const active = ref(false);
+
+if (props.range && !Array.isArray(props.modelValue)) {
+	logger.throw(
+		'BaseSlider mode is set as range but modelValue is not an array',
+		TypeError
+	);
+}
+
+onMounted(() => {
+	if (props.autofocus) {
+		focusDefaultThumb();
+	}
+});
+
+const thumbPressed = ref(false);
+const targetThumb = ref<'higher' | 'lower' | null>(null);
+
+const focusDefaultThumb = () => {
+	if (props.disabled) return;
+	if (props.range) {
+		(thumblower.value ?? thumbhigher.value)?.focus();
+		return;
+	}
+	thumbhigher.value?.focus();
+};
+
+const onFocusHiddenInput = () => {
+	if (document.activeElement !== hiddenInput.value) return;
+	focusDefaultThumb();
+};
+
+const getThumbAnchorPosition = (percent: number) =>
+	`calc(var(--track-inset) + (100% - (var(--track-inset) * 2)) * ${percent} / 100)`;
+
+const getTargetThumb = (event: Event): 'higher' | 'lower' => {
+	if (thumbhigher.value && thumbhigher.value.contains(event.target as Node))
+		return 'higher';
+	if (thumblower.value && thumblower.value.contains(event.target as Node))
+		return 'lower';
+	return logger.throw('Could not identify target thumb');
+};
+
+const removePointerListeners = () => {
+	document.removeEventListener('pointermove', onPointermove);
+	document.removeEventListener('pointerup', onPointerup);
+};
+
+const removeInteractionListeners = () => {
+	document.removeEventListener('focusin', onDocumentInteraction);
+	document.removeEventListener('click', onDocumentInteraction);
+};
+
+const onPointerdown = (event: PointerEvent) => {
+	if (props.disabled || props.readonly) return;
+	if (!targetThumb.value) {
+		targetThumb.value = getTargetThumb(event);
+	}
+	thumbPressed.value = true;
+	document.addEventListener('pointermove', onPointermove);
+	document.addEventListener('pointerup', onPointerup);
+	emit('pointerdown', event);
+};
+
+const listeners = computed(() => (thumbPressed.value ? {} : { onPointerdown }));
+
+const onPointermove = (event: PointerEvent) => {
+	if (props.disabled || props.readonly) return;
+	if (track.value) {
+		emit('pointermove', event);
+		const trackPosition = track.value.getBoundingClientRect();
+		const clickOffset = event.clientX;
+		const trackStart = trackPosition.left;
+		const trackLength = trackPosition.width;
+
+		// Snap the value to the step
+		const transposedValue = transpose(
+			clickOffset,
+			trackStart,
+			trackStart + trackLength,
+			props.min,
+			props.max
+		);
+		const snappedValue = snapToStep(
+			transposedValue,
+			props.min,
+			props.max,
+			props.step
+		);
+
+		// Transform the snapped value back to a percentage so it matches the original intent
+		const adjustedPercent = getAsPercentageBetween(
+			snappedValue,
+			props.min,
+			props.max
+		);
+		const clampedPercent = clamp(adjustedPercent, 0, 100);
+		if (targetThumb.value === 'higher') {
+			internalValueHigher.value = clampedPercent;
+		} else if (targetThumb.value === 'lower') {
+			internalValueLower.value = clampedPercent;
+		}
+		emit('update:modelValue', getValueToEmit());
+	}
+};
+
+const getValueToEmit = () => {
+	if (props.range) {
+		return (
+			[
+				getValueFromPercentageInInterval(
+					internalValueLower.value,
+					props.min,
+					props.max
+				),
+				getValueFromPercentageInInterval(
+					internalValueHigher.value,
+					props.min,
+					props.max
+				),
+			]
+				.sort((a, b) => a - b)
+				// This prevents floating point precision issues like 10.000000000000002
+				.map((v) => Number(v.toFixed(props.maxPrecision)))
+		);
+	} else {
+		const value = getValueFromPercentageInInterval(
+			internalValueHigher.value,
+			props.min,
+			props.max
+		);
+		return Number(value.toFixed(props.maxPrecision));
+	}
+};
+
+/**
+ * DEV-only: the prepend/append `increase`/`decrease` slot callbacks are no-ops
+ * in range mode (there is no single value to step). Warn so a stepper wired to
+ * a range slider isn't silent dead UI.
+ */
+const warnRangeStepper = (callback: 'increase' | 'decrease') => {
+	if (!import.meta.env.DEV) return;
+	logger.warn(
+		`BaseSlider: the ${callback}() slot callback does nothing in range mode — steppers are only supported on single-value sliders.`
+	);
+};
+
+const increase = () => {
+	if (props.disabled || props.readonly) return;
+	if (props.range) {
+		warnRangeStepper('increase');
+		return;
+	}
+	const initialValue = (props.modelValue as number | null) ?? 0;
+	const increased = initialValue + props.step;
+	const clamped = clamp(increased, props.min, props.max);
+	emit('update:modelValue', clamped);
+};
+
+const decrease = () => {
+	if (props.disabled || props.readonly) return;
+	if (props.range) {
+		warnRangeStepper('decrease');
+		return;
+	}
+	const initialValue = (props.modelValue as number | null) ?? 0;
+	const decreased = initialValue - props.step;
+	const clamped = clamp(decreased, props.min, props.max);
+	emit('update:modelValue', clamped);
+};
+
+watch(
+	() => props.modelValue,
+	(value) => {
+		if (props.range) {
+			const rangeValue = Array.isArray(value) ? value : null;
+			if (!rangeValue) {
+				logger.throw('BaseSlider modelValue must be an array');
+				return;
+			}
+			if (rangeValue.length !== 2) {
+				internalValueLower.value = 0;
+				internalValueHigher.value = 100;
+				return;
+			}
+			const sortedExternal = [...rangeValue].sort((a, b) => a - b);
+			const normalizedExternal = sortedExternal.map((v) =>
+				clamp(getAsPercentageBetween(v, props.min, props.max), 0, 100)
+			);
+			// Assign the values to the internal values based on which is closest
+			// this is useful so the user doesn't have to think about the thumbs position
+			if (internalValueLower.value > internalValueHigher.value) {
+				internalValueLower.value = normalizedExternal[1];
+				internalValueHigher.value = normalizedExternal[0];
+			} else {
+				internalValueLower.value = normalizedExternal[0];
+				internalValueHigher.value = normalizedExternal[1];
+			}
+		} else {
+			const newValue = (value as number | null) ?? props.min;
+			const transposed = transpose(newValue, props.min, props.max, 0, 100);
+			const clamped = clamp(transposed, 0, 100);
+			internalValueHigher.value = clamped;
+		}
+	},
+	{ immediate: true }
+);
+
+const onPointerup = (event: PointerEvent) => {
+	thumbPressed.value = false;
+	targetThumb.value = null;
+	removePointerListeners();
+	emit('pointerup', event);
+};
+
+const proportionalStep = computed(() =>
+	getAsPercentage(props.step, props.max - props.min)
+);
+
+const getInteractedThumb = (event: KeyboardEvent) => {
+	if (
+		targetThumb.value === 'higher' ||
+		document.activeElement === thumbhigher.value ||
+		event.target === thumbhigher.value
+	) {
+		return 'higher' as const;
+	}
+	return 'lower' as const;
+};
+
+const updateThumbByPercent = (thumb: 'higher' | 'lower', nextValue: number) => {
+	const clampedValue = clamp(nextValue, 0, 100);
+	if (thumb === 'higher') {
+		internalValueHigher.value = clampedValue;
+		return;
+	}
+	internalValueLower.value = clampedValue;
+};
+
+const onKeydown = (event: KeyboardEvent) => {
+	emit('keydown', event);
+	if (props.disabled || props.readonly) {
+		return;
+	}
+	const thumb = getInteractedThumb(event);
+	const pageStep = proportionalStep.value * 10;
+	const keyHandlers: Record<string, () => void> = {
+		ArrowLeft: () =>
+			updateThumbByPercent(
+				thumb,
+				(thumb === 'higher'
+					? internalValueHigher.value
+					: internalValueLower.value) - proportionalStep.value
+			),
+		ArrowDown: () =>
+			updateThumbByPercent(
+				thumb,
+				(thumb === 'higher'
+					? internalValueHigher.value
+					: internalValueLower.value) - proportionalStep.value
+			),
+		ArrowRight: () =>
+			updateThumbByPercent(
+				thumb,
+				(thumb === 'higher'
+					? internalValueHigher.value
+					: internalValueLower.value) + proportionalStep.value
+			),
+		ArrowUp: () =>
+			updateThumbByPercent(
+				thumb,
+				(thumb === 'higher'
+					? internalValueHigher.value
+					: internalValueLower.value) + proportionalStep.value
+			),
+		PageDown: () =>
+			updateThumbByPercent(
+				thumb,
+				(thumb === 'higher'
+					? internalValueHigher.value
+					: internalValueLower.value) - pageStep
+			),
+		PageUp: () =>
+			updateThumbByPercent(
+				thumb,
+				(thumb === 'higher'
+					? internalValueHigher.value
+					: internalValueLower.value) + pageStep
+			),
+		Home: () => updateThumbByPercent(thumb, 0),
+		End: () => updateThumbByPercent(thumb, 100),
+	};
+	const handler = keyHandlers[event.key];
+	if (!handler) {
+		return;
+	}
+	event.preventDefault();
+	handler();
+	emit('update:modelValue', getValueToEmit());
+};
+
+const onFocus = (event: FocusEvent) => {
+	if (props.disabled) {
+		if (event.target instanceof HTMLElement) {
+			event.target.blur();
+		}
+		return;
+	}
+	emit('focus', event);
+	const found = getTargetThumb(event);
+	if (found) targetThumb.value = found;
+	if (!active.value) {
+		active.value = true;
+		emit('active');
+		document.addEventListener('focusin', onDocumentInteraction);
+		document.addEventListener('click', onDocumentInteraction);
+	}
+};
+
+const onDocumentInteraction = (event: Event) => {
+	if (event.target instanceof HTMLElement) {
+		const isTargetInside = !!container.value?.contains(event.target);
+		const activeElement = document.activeElement;
+		const isFocusInside =
+			activeElement instanceof HTMLElement &&
+			!!container.value?.contains(activeElement);
+		if (!isTargetInside && !isFocusInside) {
+			active.value = false;
+			targetThumb.value = null;
+			emit('inactive');
+			removeInteractionListeners();
+		}
+	}
+};
+
+onBeforeUnmount(() => {
+	removePointerListeners();
+	removeInteractionListeners();
+});
+
+const outerContainerAttributes: Record<string, any> = computed(() => {
+	const base: Record<string, any> = {
+		class: {
+			'bb-base-slider': true,
+			'bb-base-slider--compact': props.compact,
+			'bb-base-slider--disabled': props.disabled,
+			'bb-base-slider--errors': props.hasErrors,
+			'bb-base-slider--warnings': Boolean(props.hasWarning) && !props.hasErrors,
+			'bb-base-slider--readonly': props.readonly,
+		},
+		style: {},
+	};
+	return base;
+});
+
+/** Track-relative percentage (0–100) of a pointer press, or null off-track. */
+const getPressedPercent = (event: PointerEvent): number | null => {
+	if (!track.value) return null;
+	const rect = track.value.getBoundingClientRect();
+	if (rect.width === 0) return null;
+	return clamp(((event.clientX - rect.left) / rect.width) * 100, 0, 100);
+};
+
+/** The thumb closest to a pressed percentage; ties break toward the press direction. */
+const nearestThumb = (percent: number): 'higher' | 'lower' => {
+	const distLower = Math.abs(percent - internalValueLower.value);
+	const distHigher = Math.abs(percent - internalValueHigher.value);
+	if (distLower === distHigher) {
+		return percent < internalValueLower.value ? 'lower' : 'higher';
+	}
+	return distLower < distHigher ? 'lower' : 'higher';
+};
+
+const innerContainerAttributes: Record<string, any> = {
+	onPointerdown: (event: PointerEvent) => {
+		// Don't focus the thumb or attach document drag listeners on a disabled or
+		// readonly track (the value can't change anyway) — SUS-024.
+		if (props.disabled || props.readonly) return;
+		// A 0-width / unmeasured track can't map a press to a position — bail for
+		// BOTH range and single mode (single mode previously skipped this guard and
+		// acted on a NaN position when the track measured 0×0).
+		const percent = getPressedPercent(event);
+		if (percent === null) return;
+		if (props.range) {
+			// Range mode: move the nearest thumb to the pressed position and drag
+			// it, instead of leaving the track dead.
+			targetThumb.value = nearestThumb(percent);
+			(targetThumb.value === 'lower'
+				? thumblower.value
+				: thumbhigher.value
+			)?.focus();
+		} else {
+			thumbhigher.value?.focus();
+		}
+		onPointermove(event);
+		document.addEventListener('pointermove', onPointermove);
+		document.addEventListener('pointerup', onPointerup);
+	},
+};
+
+const sliderBackgroundAttributes = computed(() => {
+	const classes = 'bb-base-slider__track-background';
+	const style: Record<string, any> = {
+		width: `${sortedInternalValues.value[1] - sortedInternalValues.value[0]}%`,
+		left: `${sortedInternalValues.value[0]}%`,
+	};
+	return {
+		class: classes,
+		style,
+	};
+});
+
+type Tick = {
+	value: number;
+	percent: number;
+	active: boolean;
+};
+
+const isSelected = (value: number) => {
+	if (isNil(props.modelValue)) return false;
+
+	if (Array.isArray(props.modelValue)) {
+		if (props.modelValue.length === 0) return false;
+		const ordered = [...props.modelValue].sort((a, b) => a - b);
+		return ordered[0] <= value && ordered[1] >= value;
+	}
+	return value <= Number(props.modelValue);
+};
+
+const ticks = computed<Tick[]>(() => {
+	if (!props.ticks) return [] as Tick[];
+	const ticks: Tick[] = [];
+	let current = props.min;
+	while (current <= props.max) {
+		const value = current;
+		const percent = getAsPercentageBetween(value, props.min, props.max);
+		const active = isSelected(value);
+		ticks.push({
+			value,
+			percent,
+			active,
+		});
+		current += props.step;
+	}
+	return ticks;
+});
+</script>
+
+<style lang="postcss">
+/* @inherit --track-inset — defined in index.css on the component root */
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { InputHTMLAttributes, HTMLAttributes } from 'vue';
+
+/**
+ * Props for the slider component with range support, ticks, and keyboard navigation.
+ */
+export type BaseSliderProps = {
+	/**
+	 * Apply the compact density variant.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Id(s) of elements describing this slider for assistive technologies.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+
+	/**
+	 * Focus the slider on mount.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Disable all interactions with the slider.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Apply error styling to the slider.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Apply warning styling (same chrome as errors, `--bb-warn` color).
+	 * Suppressed when `hasErrors` is also set.
+	 */
+	hasWarning?: boolean;
+
+	/**
+	 * Explicit id for the slider container. Used to generate ids for thumbs.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Upper bound for slider values.
+	 * @defaultValue `100`
+	 */
+	max?: number;
+
+	/**
+	 * Maximum decimal places to retain in emitted values.
+	 * @defaultValue `2`
+	 */
+	maxPrecision?: number;
+
+	/**
+	 * Lower bound for slider values.
+	 * @defaultValue `0`
+	 */
+	min?: number;
+
+	/**
+	 * v-model value. Single number for single slider, two-element array for range.
+	 * @defaultValue `0`
+	 */
+	modelValue: number[] | number | null;
+
+	/**
+	 * Defines the name of the input.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * Enable range selection with two thumbs. When true, modelValue must be an array.
+	 */
+	range?: boolean;
+
+	/**
+	 * Make the slider read-only while keeping it visible.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Mark the slider as required.
+	 */
+	required?: boolean;
+
+	/**
+	 * Granularity step for value changes via keyboard or pointer interaction.
+	 * @defaultValue `1`
+	 */
+	step?: number;
+
+	/**
+	 * Show tick marks at each step interval.
+	 */
+	ticks?: boolean;
+
+	/**
+	 * Disables the proportional thumb translation that keeps thumbs centered
+	 * on the track (enabled by default). Set it when displaying ticks for
+	 * better alignment.
+	 * @defaultValue `false`
+	 */
+	disableThumbTranslate?: boolean;
+};
+
+export type BaseSliderEvents = {
+	/**
+	 * Emitted when the slider gains focus and becomes interactive.
+	 */
+	(e: 'active'): void;
+	/**
+	 * Emitted when focus/click moves outside the slider after it was active.
+	 */
+	(e: 'inactive'): void;
+	/**
+	 * Emitted when a thumb gains focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted for keyboard interaction on a thumb.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/**
+	 * Emitted when a pointer device is pressed on a thumb.
+	 * Forwards the original DOM `PointerEvent`.
+	 */
+	(e: 'pointerdown', event: PointerEvent): void;
+	/**
+	 * Emitted as a pointer device moves while dragging a thumb.
+	 * Forwards the original DOM `PointerEvent`.
+	 */
+	(e: 'pointermove', event: PointerEvent): void;
+	/**
+	 * Emitted when a pointer device is released after dragging.
+	 * Forwards the original DOM `PointerEvent`.
+	 */
+	(e: 'pointerup', event: PointerEvent): void;
+	/**
+	 * Emitted with new value(s) whenever the slider position changes.
+	 * Single number for single slider, array for range mode.
+	 */
+	(e: 'update:modelValue', event: number | number[]): void;
+};
+
+/**
+ * Props exposed by the `thumb`, `thumb:higher`, and `thumb:lower` slots.
+ */
+export type BaseSliderThumbSlotProps = {
+	/**
+	 * The current value controlled by this thumb, or `undefined` if unset.
+	 */
+	value: number | undefined;
+	/**
+	 * The thumb's horizontal position as a percentage (0–100) along the track.
+	 */
+	percent: number;
+	/**
+	 * Whether this thumb currently has keyboard focus.
+	 */
+	focused: boolean;
+};
+
+/**
+ * Props exposed by the `append` and `prepend` slots.
+ */
+export type BaseSliderStepSlotProps = {
+	/**
+	 * Increments the value by one `step`.
+	 */
+	increase: () => void;
+	/**
+	 * Decrements the value by one `step`.
+	 */
+	decrease: () => void;
+};
+
+/**
+ * Props exposed by the `tick` slot.
+ */
+export type BaseSliderTickSlotProps = {
+	/**
+	 * The numeric value this tick represents.
+	 */
+	value: number;
+	/**
+	 * The tick's horizontal position as a percentage (0–100) along the track.
+	 */
+	percent: number;
+	/**
+	 * Whether the tick falls within the currently selected range/value.
+	 */
+	active: boolean;
+};
+
+export type BaseSliderSlots = {
+	/**
+	 * Replaces the default higher-value thumb in range mode (`range: true`).
+	 */
+	'thumb:higher': (props: BaseSliderThumbSlotProps) => any;
+	/**
+	 * Replaces the default lower-value thumb in range mode (`range: true`).
+	 */
+	'thumb:lower': (props: BaseSliderThumbSlotProps) => any;
+	/**
+	 * Content rendered after the slider track, typically used to add a max-value label or button.
+	 */
+	append: (props: BaseSliderStepSlotProps) => any;
+	/**
+	 * Content rendered before the slider track, typically used to add a min-value label or button.
+	 */
+	prepend: (props: BaseSliderStepSlotProps) => any;
+	/**
+	 * Fallback thumb used for non-range sliders (or inside `thumb:higher`/`thumb:lower` when not overridden separately).
+	 */
+	thumb: (props: BaseSliderThumbSlotProps) => any;
+	/**
+	 * Replaces the default tick mark rendered at each step when ticks are enabled.
+	 */
+	tick: (props: BaseSliderTickSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-slider {
+	--thumb: 12px;
+	--track: 4px;
+	--track-color: var(--bb-muted);
+	--padding: calc((var(--thumb) - var(--track)) / 2);
+	--control-h: var(--bb-input-h);
+	--px: var(--bb-input-px);
+	--shell-px: 0px;
+	--track-inset: 0px;
+	--inside-label-clearance: 0px;
+	--inside-label-track-offset: 0px;
+	--shell-bg: transparent;
+	--shell-border-width: 0px;
+	--shell-border-color: var(--bb-border);
+	--shell-radius: 0px;
+	--shell-focus-border: var(--bb-border);
+	--shell-focus-ring: 0px 0px 0px 0px transparent;
+	--shell-disabled-bg: transparent;
+	--color: var(--bb-primary);
+	--ring-color: color-mix(
+		in oklab,
+		var(--color) var(--bb-ring-opacity),
+		transparent
+	);
+
+	--radius: var(--bb-radius);
+	align-items: center;
+	display: inline-flex;
+	min-height: var(--control-h);
+
+	&.bb-base-slider--compact {
+		--control-h: var(--bb-input-h-compact);
+	}
+
+	&__slider-container {
+		background-color: var(--shell-bg);
+		border: var(--shell-border-width) solid var(--shell-border-color);
+		border-radius: var(--shell-radius);
+		box-shadow: 0px 0px 0px 0px var(--bb-ring);
+		display: block;
+		flex-grow: 1;
+		min-height: calc(var(--control-h) + var(--inside-label-clearance));
+		min-width: 100px;
+		padding-bottom: var(--padding);
+		padding-left: var(--shell-px);
+		padding-right: var(--shell-px);
+		padding-top: var(--padding);
+		position: relative;
+		-webkit-touch-callout: none;
+		transition: all var(--bb-transition-medium) var(--bb-ease);
+		-webkit-user-select: none;
+		-khtml-user-select: none;
+		-moz-user-select: none;
+		-ms-user-select: none;
+		user-select: none;
+	}
+
+	&.bb-base-slider--disabled {
+		.bb-base-slider__thumb-container {
+			pointer-events: none;
+		}
+		.bb-base-slider__track-background {
+			background-color: color-mix(
+				in oklab,
+				var(--bb-text) 45%,
+				var(--bb-panel)
+			);
+			cursor: not-allowed;
+		}
+		.bb-base-slider__track-fill {
+			background-color: var(--bb-muted);
+			cursor: not-allowed;
+		}
+		.bb-base-slider__thumb {
+			cursor: not-allowed;
+		}
+		.bb-base-slider__slider-container {
+			background-color: var(--shell-disabled-bg);
+		}
+	}
+
+	&:has(.bb-base-slider__thumb-container:focus)
+		.bb-base-slider__slider-container,
+	&:has(.bb-base-slider__thumb:active) .bb-base-slider__slider-container {
+		border-color: var(--shell-focus-border);
+		box-shadow: var(--shell-focus-ring);
+	}
+
+	&.bb-base-slider--errors {
+		--ring-color: var(--bb-ring-danger);
+
+		.bb-base-slider__slider-container {
+			border-color: var(--shell-focus-border);
+		}
+	}
+
+	&.bb-base-slider--warnings {
+		--ring-color: var(--bb-ring-warn);
+
+		.bb-base-slider__slider-container {
+			border-color: var(--shell-focus-border);
+		}
+	}
+
+	&__track-container {
+		display: block;
+		height: var(--track);
+		left: var(--track-inset);
+		position: absolute;
+		right: var(--track-inset);
+		top: calc(50% + var(--inside-label-track-offset));
+		transform: translateY(-50%);
+	}
+
+	&__track-background {
+		background-color: var(--color);
+		border-bottom-left-radius: var(--radius);
+		border-top-left-radius: var(--radius);
+		cursor: pointer;
+		display: block;
+		height: 100%;
+		left: 0;
+		position: absolute;
+		top: 0;
+	}
+
+	&__track-fill {
+		background-color: var(--track-color);
+		border-radius: var(--radius);
+		cursor: pointer;
+		display: block;
+		height: 100%;
+		position: absolute;
+		right: 0;
+		top: 0;
+		width: 100%;
+	}
+
+	&__thumb-container {
+		display: block;
+		position: absolute;
+		top: calc(50% + var(--inside-label-track-offset));
+
+		/* Hover highlights like focus (shadcn behavior) — a hint that the
+		   thumb is grabbable before the pointer commits. */
+		&:focus,
+		&:hover {
+			.bb-base-slider__thumb {
+				box-shadow: 0px 0px 0px var(--bb-ring-size) var(--ring-color);
+			}
+		}
+	}
+
+	&__thumb {
+		background-color: var(--bb-panel);
+		border: 1px solid var(--bb-border);
+		border-radius: 50%;
+		box-shadow: 0px 0px 0px 0px var(--bb-ring);
+		cursor: pointer;
+		display: block;
+		height: var(--thumb);
+		position: absolute;
+		top: 50%;
+		touch-action: none;
+		transition-duration: 150ms;
+		transition-property: box-shadow;
+		transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+		width: var(--thumb);
+	}
+
+	&__ticks-container {
+		display: flex;
+		justify-content: space-between;
+		left: var(--track-inset);
+		position: absolute;
+		right: var(--track-inset);
+		top: 100%;
+	}
+
+	&__tick {
+		position: relative;
+	}
+}
+```