bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbSlider.md

@@ -1,273 +1,517 @@
 # BbSlider
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Selects numeric values across a bounded range.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbSlider.md](./source/BbSlider.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbSlider` when the value lives in a known interval and the _position_
+carries meaning: volume, brightness, opacity, a price filter. The trade-off is
+precision — a slider is for "about here", not exact entry.
+
+- Need an exact number typed in? Use `BbNumberInput`.
+- Rating a few discrete points (1–5 stars, a score)? Use `BbRating`.
+- Bounded interval, approximate, visual? `BbSlider`.
+
+Always give it a real interval: set `min`, `max`, and a `step` that matches the
+resolution you want. The slider has **no built-in numeric read-out** — the thumb
+shows position, not a number — so pair it with a live value display (or the
+`thumb` slot below) whenever the exact figure matters.
+
+### A single value
+
+Bind a number with `v-model`. The label sits above the track; add a live readout
+so the current number is legible.
+
+**Volume**
+
+```vue
+<div class="w-full max-w-sm">
+	<BbSlider v-model="state.volume" label="Volume" :min="0" :max="100" :step="5" />
+	<p class="text-sm text-[color:var(--bb-text-muted)]">{{ state.volume ?? 0 }}%</p>
+</div>
+```
+
+Besides `update:modelValue` the slider re-emits interaction events (`active`,
+`inactive`, `focus`, `keydown`, `pointerdown`, `pointermove`, `pointerup`) —
+use them for analytics or "commit on release" patterns, never to derive the
+value: the value is what `v-model` gives you.
+
+### Range mode
+
+Set `range` and bind a **two-element array** to select an interval between two
+thumbs — the canonical "price from–to" filter. In range mode `modelValue` must
+be an array; passing a scalar throws at mount. The component keeps the pair
+sorted for you and assigns each incoming value to the nearer thumb, so you never
+have to reason about which handle is which.
+
+**Price range filter**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-slider"
-		:compact="compact"
-		:direction="direction"
-		:errors="errors"
-		:has-errors="hasErrors"
-		:hide-label="hideLabel"
-		:hint="hint"
-		:label="label"
-		:label-position="labelPosition"
-		:model-value="modelValue"
-		:name="name"
-		:reverse="reverse"
-		:show-hint="showHint"
+	<div
+		class="flex w-full max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-4"
 	>
-		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseSlider
-				:id="id"
-				:aria-describedby="ariaDescribedby"
-				:autofocus="autofocus"
-				:color="color"
-				:disabled="disabled"
-				:has-errors="hasErrors"
-				:max="max"
-				:min="min"
-				:model-value="modelValue"
-				:name="name"
-				:range="range"
-				:readonly="readonly"
-				:required="required"
-				:step="step"
-				:thumb-translate="thumbTranslate"
-				:ticks="ticks"
-				v-bind="eventListeners"
+		<div class="flex items-baseline justify-between gap-2">
+			<p class="text-sm font-medium">Price</p>
+			<p
+				class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+				data-testid="range"
 			>
-				<template #append="data"><slot name="append" v-bind="data" /></template>
-				<template #prepend="data"
-					><slot name="prepend" v-bind="data"
-				/></template>
-				<template #thumb="data"><slot name="thumb" v-bind="data" /></template>
-				<template #thumb:lower="data"
-					><slot name="thumb:lower" v-bind="data"
-				/></template>
-				<template #thumb:higher="data"
-					><slot name="thumb:higher" v-bind="data"
-				/></template>
-				<template #tick="data"><slot name="tick" v-bind="data" /></template>
-			</BaseSlider>
-		</template>
-	</BaseInputContainer>
+				€{{ price[0] }} – €{{ price[1] }}
+			</p>
+		</div>
+		<BbSlider
+			v-model="price"
+			hide-label
+			label="Price range"
+			:max="1000"
+			:min="0"
+			range
+			:step="50"
+		/>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			324 stays in this range
+		</p>
+	</div>
 </template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSlider } from 'bitboss-ui';
+
+const price = ref<[number, number]>([200, 800]);
+</script>
+```
+
+### Min, max and step
+
+`min`/`max` bound the interval (defaults `0`–`100`) and `step` sets the
+granularity every value snaps to (default `1`). These are validated at mount and
+throw on nonsense input, so treat them as hard invariants:
 
+- `max` must be strictly greater than `min` (else `RangeError`).
+- `step` must be a finite number greater than `0` (else `RangeError`).
+- `min`/`max` must be finite and within safe-integer range.
+
+Fractional steps work — emitted values are rounded to **`max-precision`
+decimal places** (default `2`) to avoid floating-point dust like
+`10.000000000000002`. For steps finer than `0.01`, raise `max-precision` to
+match the step's resolution (e.g. `:step="0.001"` needs
+`:max-precision="3"`), otherwise the extra digits are rounded away.
+
+**Fractional step**
+
+```vue
+<div class="w-full max-w-sm">
+	<BbSlider v-model="state.opacity" label="Layer opacity" :min="0" :max="1" :step="0.05" />
+	<p class="text-sm text-[color:var(--bb-text-muted)]">{{ (state.opacity ?? 0).toFixed(2) }}</p>
+</div>
+```
+
+### Stepper controls
+
+The `prepend` and `append` slots receive `increase` / `decrease` callbacks that
+nudge the value by one `step`. Wrap them in `BbButton`s for an accessible
+±stepper around the track — no manual math, the slider clamps to `min`/`max`
+for you. These callbacks are **single-value only**; they are inert in `range`
+mode (they early-return), so don't build a stepper around a range slider.
+
+**Volume with ± buttons**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div class="flex items-baseline justify-between gap-2">
+			<div>
+				<p class="text-sm font-medium">Playback volume</p>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					Speaker · MacBook Pro
+				</p>
+			</div>
+			<p
+				class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+				data-testid="value"
+			>
+				{{ volume }}%
+			</p>
+		</div>
+		<BbSlider
+			v-model="volume"
+			hide-label
+			label="Playback volume"
+			:max="100"
+			:min="0"
+			:step="10"
+		>
+			<template #prepend="{ decrease }">
+				<BbButton
+					aria-label="Quieter"
+					icon="lucide:minus"
+					size="xs"
+					variant="ghost"
+					@click="decrease"
+				/>
+			</template>
+			<template #append="{ increase }">
+				<BbButton
+					aria-label="Louder"
+					icon="lucide:plus"
+					size="xs"
+					variant="ghost"
+					@click="increase"
+				/>
+			</template>
+		</BbSlider>
+	</div>
+</template>
 <script setup lang="ts">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseSlider from '../BaseSlider/BaseSlider.vue';
-import { ref, computed } from 'vue';
-import type { BbSliderProps, BbSliderEvents, BbSliderSlots } from './types';
-
-const props = withDefaults(defineProps<BbSliderProps>(), {
-	thumbTranslate: true,
-});
-
-const emit = defineEmits<BbSliderEvents>();
-
-defineSlots<BbSliderSlots>();
-
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
-
-/**
- * These events are just propagated
- */
-const eventListeners = {
-	onActive: () => {
-		active.value = true;
-		emit('active');
-	},
-	onClick: (event: MouseEvent) => emit('click', event),
-	onFocus: (event: FocusEvent) => emit('focus', event),
-	onInactive: () => {
-		active.value = false;
-		emit('inactive');
-	},
-	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
-	onPointerdown: (event: PointerEvent) => emit('pointerdown', event),
-	onPointermove: (event: PointerEvent) => emit('pointermove', event),
-	onPointerup: (event: PointerEvent) => emit('pointerup', event),
-	'onUpdate:modelValue': (value: number | number[]) =>
-		emit('update:modelValue', value),
-};
+import { ref } from 'vue';
+import { BbButton, BbSlider } from 'bitboss-ui';
+
+const volume = ref(40);
 </script>
+```
 
-<style lang="postcss">
-@import './index.css';
-</style>
+### Discrete steps with ticks
+
+`ticks` marks every step. Add `disable-thumb-translate` so the thumb sits exactly
+over each tick instead of being nudged to stay centred — the two pair naturally
+when you want a stepped, notched slider. The `tick` slot (`{ value, percent,
+active }`) replaces each mark if you want custom notches or per-step labels.
+
+**Stepped slider with ticks**
+
+```vue
+<div class="w-full max-w-sm">
+	<BbSlider
+		v-model="state.priority"
+		label="Priority"
+		:min="1"
+		:max="5"
+		:step="1"
+		ticks
+		disable-thumb-translate
+	/>
+</div>
 ```
 
-## Types
-
-```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { BaseSliderEvents, BaseSliderSlots } from '../BaseSlider/types';
-
-export type BbSliderProps = {
-	/**
-	 * 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;
-
-	/**
-	 * Set the component in compact mode.
-	 */
-	compact?: boolean;
-
-	/**
-	 * Direction of the layout of the component. Can either be a predefined value or a
-	 * pattern separated by a space like `xx xxxxx`.
-	 */
-	direction?: 'horizontal' | 'vertical' | 'auto' | string;
-
-	/**
-	 * Disables the component.
-	 */
-	disabled?: boolean;
-
-	/**
-	 * Can be a string or an array of string containing the messages to display.
-	 */
-	errors?: string | string[];
-
-	/**
-	 * Define if the component should be in an error state.
-	 * It usually attaches a CSS class for styling purposes.
-	 */
-	hasErrors?: boolean;
-
-	/**
-	 * Visually hides the label of the input while maintaining accessibility.
-	 */
-	hideLabel?: boolean;
-
-	/**
-	 * Text box to be displayed near the input, usually to indicate instructions.
-	 */
-	hint?: string;
-
-	/**
-	 * The identifier of the component.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Maximum value cap.
-	 */
-	max?: number;
-
-	/**
-	 * Minimum value cap.
-	 */
-	min?: number;
-
-	/**
-	 * Used by v-model.
-	 */
-	modelValue: number[] | number | string | null;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name?: InputHTMLAttributes['name'];
-
-	/**
-	 * Keeps the hint displayed.
-	 */
-	persistentHint?: boolean;
-
-	/**
-	 * Set the input as range. modelValue must be an array.
-	 */
-	range?: boolean;
-
-	/**
-	 * Sets the input in a readonly state.
-	 */
-	readonly?: boolean;
-
-	/**
-	 * Sets the input as required.
-	 */
-	required?: boolean;
-
-	/**
-	 * Reverses the layout. Applicable in every direction the order of the label and
-	 * the input is swapped.
-	 */
-	reverse?: boolean;
-
-	/**
-	 * The step attribute specifies the granularity that the value must adhere to.
-	 */
-	step?: number;
-
-	/**
-	 * Proportionally translates the thumb so it remains on track. Set it to `false` when
-	 * displaying ticks so they align with less effort.
-	 *
-	 * @defaultValue `true`
-	 */
-	thumbTranslate?: boolean;
-
-	/**
-	 * Displays ticks on step.
-	 */
-	ticks?: boolean;
-};
-
-/** Re-export for consumers importing events type from BbSlider. */
-export type BbSliderEvents = BaseSliderEvents;
-
-/** Props exposed by the `label` slot. */
-export type BbSliderLabelSlotProps = {
-	/** The `label` prop value. */
-	text: string;
-	/** Whether the slider is in an error state. */
-	hasErrors: boolean;
-};
-
-export type BbSliderSlots = BaseSliderSlots & {
-	/**
-	 * Replaces the default label text rendered above the slider.
-	 */
-	label?: (props: BbSliderLabelSlotProps) => any;
-};
+### Keyboard model
+
+Each thumb is a real `role="slider"` handle in the tab order, and moves the
+value from the keyboard when focused:
+
+- **Arrow Right / Arrow Up** — increase by one `step`.
+- **Arrow Left / Arrow Down** — decrease by one `step`.
+- **Page Up / Page Down** — jump by ten steps.
+- **Home / End** — snap to `min` / `max`.
+
+In range mode the keys drive whichever thumb has focus. Every keystroke emits
+`update:modelValue`, so keyboard and pointer produce identical, clamped values —
+never wire your own key handlers on top.
+
+### Displaying the value on the thumb
+
+Because there is no built-in tooltip, use the `thumb` slot to render the current
+value on the handle itself. The slot gives you `{ value, percent, focused }`; its
+content renders inside the thumb, so you augment the handle rather than replacing
+it. (Use `thumb:lower` / `thumb:higher` to target one handle of a range.)
+
+**Value bubble on the thumb**
+
+```vue
+<template>
+	<div class="w-full max-w-sm pt-8">
+		<BbSlider v-model="zoom" label="Zoom" :max="200" :min="0" :step="10">
+			<template #thumb="{ value, focused }">
+				<span
+					class="absolute -top-7 left-1/2 -translate-x-1/2 rounded-[var(--bb-radius-sm)] bg-[var(--bb-primary)] px-1.5 py-0.5 text-xs text-[var(--bb-primary-fg)] transition-opacity"
+					:class="focused ? 'opacity-100' : 'opacity-0'"
+					>{{ value ?? 0 }}%</span
+				>
+			</template>
+		</BbSlider>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSlider } from 'bitboss-ui';
+
+const zoom = ref(80);
+</script>
+```
+
+### Pair with exact entry
+
+When the figure is consequential — a billing cap, a quota — the slider gives the
+feel of the interval and a `BbNumberInput` bound to the **same ref** gives exact
+entry. No sync code is needed: both components drive the one value, and the
+slider clamps and snaps whatever the field emits.
+
+**Monthly spend limit**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div class="flex items-baseline justify-between gap-2">
+			<div>
+				<p class="text-sm font-medium">Monthly spend limit</p>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					API usage pauses once the cap is reached.
+				</p>
+			</div>
+			<p class="text-sm font-medium tabular-nums">€{{ limit ?? 0 }}</p>
+		</div>
+		<BbSlider
+			v-model="limit"
+			compact
+			hide-label
+			label="Monthly spend limit"
+			:max="500"
+			:min="0"
+			:step="25"
+		/>
+		<BbNumberInput
+			v-model="limit"
+			compact
+			hide-label
+			label="Monthly spend limit, exact amount"
+			:max="500"
+			:max-precision="0"
+			:min="0"
+			:step="25"
+		>
+			<template #prefix>€</template>
+			<template #suffix>/ mo</template>
+		</BbNumberInput>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbNumberInput, BbSlider } from 'bitboss-ui';
+
+const limit = ref<number | null>(200);
+</script>
 ```
 
-## Styles
-
-```css
-.bb-slider {
-	.bb-base-input-container {
-		.bb-base-input-container__input {
-			.bb-base-slider {
-				display: inline-flex;
-			}
-		}
-	}
-}
+### Label modes, layout and density
+
+- `label` is required and names the slider; `hide-label` keeps it for assistive
+  tech only.
+- `label-mode` is `'outside'` (default) or `'inside'`. `'floating'` is **not
+  supported and throws at runtime** — a slider has no empty/filled state for the
+  label to float against.
+- `direction` (`'horizontal'`, `'vertical'`, `'auto'`, or a pattern like
+  `'xx xxxxxx'`), `reverse`, and `label-position` arrange the label against the
+  track, exactly as on the other inputs.
+- `compact` applies the denser variant for toolbars and settings rows.
+
+**Inside label mode**
+
+```vue
+<div class="w-full max-w-sm">
+	<BbSlider
+		v-model="state.contrast"
+		label="Contrast"
+		label-mode="inside"
+		:min="0"
+		:max="100"
+		:step="1"
+	/>
+</div>
 ```
+
+In a dense settings panel set `compact` on every slider in the group — density
+is a screen-level decision, not a per-control one.
+
+**Compact display settings**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div>
+			<p class="text-sm font-medium">Display</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Applies to this display only.
+			</p>
+		</div>
+		<div class="flex flex-col gap-1">
+			<BbSlider
+				v-model="brightness"
+				compact
+				label="Brightness"
+				:max="100"
+				:min="0"
+				:step="5"
+			/>
+			<p
+				class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+				data-testid="brightness"
+			>
+				{{ brightness }}%
+			</p>
+		</div>
+		<div class="flex flex-col gap-1">
+			<BbSlider
+				v-model="warmth"
+				compact
+				label="Night light"
+				:max="100"
+				:min="0"
+				:step="5"
+			/>
+			<p
+				class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+				data-testid="warmth"
+			>
+				{{ warmth }}%
+			</p>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSlider } from 'bitboss-ui';
+
+const brightness = ref(80);
+const warmth = ref(20);
+</script>
+```
+
+### Disabled, readonly and errors
+
+- `disabled` removes the thumb from the tab order and greys the track; pointer
+  and keyboard are inert.
+- `readonly` shows a fixed value that can still be focused and exposes
+  `aria-readonly` — prefer it, with a nearby explanation, for values the user may
+  inspect but not change.
+- `errors` (string or array) renders messages below the track and `has-errors`
+  toggles error styling alone — rare for a bounded slider, but available when a
+  value is rejected by validation.
+
+### Config, platform and pairings
+
+No plugin options change `BbSlider` behaviour (no i18n strings, no teleport, no
+variant registry) and it renders SSR-safe static markup in Nuxt and Inertia
+apps. A hidden text input carries the JSON-serialized value under `name` for
+classic form posts.
+
+Works well with:
+
+- `BbButton` — as the ± stepper via the `prepend`/`append` callbacks.
+- `BbNumberInput` — a paired exact-entry field for the same value.
+- `useToast` — confirm a committed change on `inactive` (drag release).
+
+### Gotchas and anti-patterns
+
+- Don't bind a scalar with `range` (or an array without it) — the mode and the
+  `modelValue` shape must match, or it throws at mount.
+- Don't expect `increase`/`decrease` to work in range mode; they are single-value
+  only. Drive range thumbs with the keyboard or pointer.
+- Don't set `label-mode="floating"` — it throws. Use `'outside'` or `'inside'`.
+- Don't rely on a slider for exact numbers — steps finer than `0.01` round away
+  unless you raise `max-precision` to match. Use `BbNumberInput` when the
+  precise figure is the point.
+- Don't add your own value read-out via `@pointermove`/`@keydown` math — read
+  `v-model` (or use the `thumb` slot), which already delivers the clamped value.
+
+### Accessibility
+
+- Always provide a `label` — it is the slider's accessible name.
+- Each thumb exposes `role="slider"` with `aria-valuemin`/`aria-valuemax`/
+  `aria-valuenow` automatically; do not add your own ARIA.
+- `errors`, `warnings`, `description` and `hint` are all wired to each thumb through
+  `aria-describedby`, in that order: the reason the field is invalid is spoken
+  first when it regains focus, and a channel is referenced only while it
+  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
+  so they are announced the moment they appear — announced on change, re-read
+  on focus. Keep messages meaningful, not decorative.
+- Prefer `readonly` (focusable, discoverable) with an explanation over a silent
+  `disabled` for locked settings.
+- Provide a visible value read-out for sighted users — the thumb position alone
+  is not a precise number.
+
+## v-model
+
+- `v-model` — type: `number \| number[] \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `compact` | `boolean \| undefined` |  |  | Set the component in compact mode. |
+| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
+| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disableThumbTranslate` | `boolean \| undefined` |  |  | Disables the proportional thumb translation that keeps the thumb on track (enabled by default). Set it when displaying ticks so they align with less effort. |
+| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
+| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelMode` | `"outside" \| "inside" \| undefined` |  |  | Label rendering mode. Sliders do not support `floating` labels. |
+| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `max` | `number \| undefined` |  |  | Maximum value cap. |
+| `maxPrecision` | `number \| undefined` |  |  | Maximum decimal places to retain in emitted values. |
+| `min` | `number \| undefined` |  |  | Minimum value cap. |
+| `modelValue` | `number \| number[] \| null` |  | yes | Used by v-model. |
+| `name` | `string \| undefined` |  |  | Defines the name of the input. |
+| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `range` | `boolean \| undefined` |  |  | Set the input as range. modelValue must be an array. |
+| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `step` | `number \| undefined` |  |  | The step attribute specifies the granularity that the value must adhere to. |
+| `ticks` | `boolean \| undefined` |  |  | Displays ticks on step. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also… |
+
+## Events
+
+- `active` — `(event: "active"): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `inactive` — `(event: "inactive"): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `pointerdown` — `(event: "pointerdown", event: PointerEvent): void`
+- `pointermove` — `(event: "pointermove", event: PointerEvent): void`
+- `pointerup` — `(event: "pointerup", event: PointerEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", event: number \| number[]): void`
+
+## Slots
+
+- `append` — scope: `BaseSliderStepSlotProps` — Content rendered after the slider track, typically used to add a max-value label or button.
+- `label` — scope: `BbSliderLabelSlotProps` — Replaces the default label text rendered above the slider.
+- `prepend` — scope: `BaseSliderStepSlotProps` — Content rendered before the slider track, typically used to add a min-value label or button.
+- `thumb` — scope: `BaseSliderThumbSlotProps` — Fallback thumb used for non-range sliders (or inside `thumb:higher`/`thumb:lower` when not overridden separately).
+- `thumb:higher` — scope: `BaseSliderThumbSlotProps` — Replaces the default higher-value thumb in range mode (`range: true`).
+- `thumb:lower` — scope: `BaseSliderThumbSlotProps` — Replaces the default lower-value thumb in range mode (`range: true`).
+- `tick` — scope: `BaseSliderTickSlotProps` — Replaces the default tick mark rendered at each step when ticks are enabled.
+
+## Validated variant
+
+Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `rules` | `RuleExpression<number \| number[] \| null>` | vee-validate rules for this field. |
+| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
+| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |
+
+## See Also
+
+- [BbNumberInput](./BbNumberInput.md) — Captures and validates numeric form values, emits a number value.
+- [BbRating](./BbRating.md) — Collects scalar ratings through interactive icons.