bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbRating.md

@@ -1,244 +1,379 @@
 # BbRating
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Collects scalar ratings through interactive icons.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbRating.md](./source/BbRating.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbRating` for a small whole-number scale where each step is a distinct
+judgement: 1–5 stars, a 1–10 recommendation, a satisfaction score. It works two
+ways from the same component:
+
+- **Interactive** — the user picks a value (`v-model`).
+- **Read-only** — you show an existing score (`readonly` + `model-value`).
+
+For a continuous value from an interval reach for `BbSlider`; for a single
+yes/no use `BbSwitch` or `BbCheckbox`. Ratings are for "how many out of N", and
+the value is always a **whole number** — see the constraint below.
+
+### Collect a rating
+
+Bind `v-model`; set `stars` for the scale (default 5). The underlying control is
+a native radio group: `legend` labels the set, and `name` is optional — omit it
+and the component generates a unique group name. Pass `name` only when a native
+form post needs the value under a known key.
+
+**Interactive rating**
+
+```vue
+<BbRating
+	v-model="state.stars"
+	legend="Rate your experience"
+	name="experience"
+/>
+```
+
+Besides `update:modelValue` the component re-emits the native interaction events
+(`change`, `click`, `input`, `focus`, `blur`, `keydown`, `mousedown`,
+`mouseup`) — listen to those for side effects, never to derive the value.
+
+### Clearing a rating
+
+By default a radio group cannot be un-picked. Set `clearable` to let the user
+reset to unrated (`null`): clicking the **currently selected** star again clears
+it, and so does pressing **Delete** or **Backspace** while it is focused. The
+gesture isn't obvious, so pair it with a hint.
+
+**Clearable rating**
+
+```vue
+<BbRating
+	v-model="state.score"
+	legend="Rate your order"
+	name="order"
+	clearable
+	hint="Click the selected star again to clear."
+	persistent-hint
+/>
+```
+
+When cleared, `v-model` becomes `null` (not `0`) — model your ref as
+`number | null` and treat `null` as "not rated yet".
+
+### Read-only score display
+
+With `readonly` the stars become a compact score indicator that can still be
+focused but not changed. Use the `append` slot to add the numeric value and
+sample size next to the stars.
+
+**Average score**
+
+```vue
+<BbRating :model-value="4" readonly legend="Average rating" name="avg">
+	<template #append>
+		<span class="text-sm text-gray-500">4.0 · 128 reviews</span>
+	</template>
+</BbRating>
+```
+
+### Whole numbers only — no half stars
+
+`BbRating` renders one radio per whole star and fills every star **at or below**
+the value, so it has no concept of a half or fractional star. A decimal average
+like `4.5` fills four stars, not four-and-a-half. When you display an average,
+round for the glyphs and print the precise figure as text (as above) rather than
+expecting a half-filled star. For fractional _input_, use `BbSlider`.
+
+### Scale size with `stars`
+
+`stars` sets both how many glyphs render **and** the maximum value. Use it for
+non-5 scales — a 3-point mood, a 10-point NPS-style score.
+
+**Ten-point scale**
+
+```vue
+<BbRating
+	v-model="state.nps"
+	legend="How likely are you to recommend us?"
+	name="nps"
+	:stars="10"
+	size="sm"
+/>
+```
+
+### Glyph sizes
+
+`size` takes the shared scale (`xs`–`2xl`), or any non-percentage CSS length.
+Prefer the default for interactive ratings; use `sm`/`xs` for dense inline
+score displays next to compact chrome.
+
+**Size scale**
+
+```vue
+<div class="flex flex-wrap items-center gap-3">
+	<BbRating :model-value="4" readonly hide-legend legend="Small" name="rs" size="sm" />
+	<BbRating :model-value="4" readonly hide-legend legend="Medium" name="rm" size="md" />
+	<BbRating :model-value="4" readonly hide-legend legend="Large" name="rl" size="lg" />
+</div>
+```
+
+### Custom glyph
+
+The `icon` slot replaces the star and receives `checked` (is this glyph filled?)
+plus the rendered `size`. Swap in any icon and colour the filled vs empty state
+with utility classes — `BbIcon` inherits `currentColor`.
+
+Note the slot's `size` is a **CSS length string** (e.g. `"28"`), already resolved
+from the `size` prop through the shared scale — pass it straight to `BbIcon`'s
+`size`, don't do arithmetic on it as if it were a number.
+
+**Hearts instead of stars**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-rating"
-		:compact="compact"
-		:direction="direction"
-		:errors="errors"
-		:has-errors="hasErrors"
-		:hide-label="hideLegend"
-		:hint="hint"
-		:input-position="inputPosition"
-		:label="legend"
-		:label-position="legendPosition"
-		:label-tag="'legend'"
-		:name="name"
-		:reverse="reverse"
-		:show-hint="showHint"
-		:tag="'fieldset'"
+	<div
+		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
 	>
-		<template #label="data"><slot name="legend" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseRating
-				:id="id"
-				:aria-describedby="ariaDescribedby"
-				:autofocus="autofocus"
-				:color="color"
-				:disabled="disabled"
-				:has-errors="hasErrors"
-				:model-value="modelValue"
-				:name="name"
-				:readonly="readonly"
-				:size="size"
-				:stars="stars"
-				v-bind="eventListeners"
-			>
-				<template #prepend="data"
-					><slot name="prepend" v-bind="data"
-				/></template>
-				<template #append="data"><slot name="append" v-bind="data" /></template>
-				<template #icon="data"><slot name="icon" v-bind="data" /></template>
-			</BaseRating>
-		</template>
-	</BaseInputContainer>
+		<div class="flex flex-col gap-0.5">
+			<span class="text-sm font-medium">Pulse · App Store</span>
+			<span class="text-xs text-gray-500">How much do you love it?</span>
+		</div>
+		<BbRating
+			v-model="love"
+			hide-legend
+			legend="How much do you love it?"
+			name="love"
+		>
+			<template #icon="{ checked, size }">
+				<BbIcon
+					:class="checked ? 'text-rose-500' : 'text-gray-300'"
+					icon="lucide:heart"
+					:size="size"
+				/>
+			</template>
+		</BbRating>
+	</div>
 </template>
 
 <script setup lang="ts">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseRating from '../BaseRating/BaseRating.vue';
-import type { BaseRatingEvents } from '../BaseRating/types';
-import { ref, computed } from 'vue';
-import type { BbRatingProps, BbRatingEvents, BbRatingSlots } from './types';
-
-const props = withDefaults(defineProps<BbRatingProps>(), {
-	inputPosition: 'left',
-});
-
-const emit = defineEmits<BaseRatingEvents>();
-
-defineSlots<BbRatingSlots>();
-
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
-
-const eventListeners = {
-	onBlur: (event: FocusEvent) => emit('blur', event),
-	onChange: (event: Event) => emit('change', event),
-	onClick: (event: MouseEvent) => emit('click', event),
-	onFocus: (event: FocusEvent) => {
-		active.value = true;
-		emit('focus', event);
-	},
-	onInactive: () => {
-		active.value = false;
-		emit('inactive');
-	},
-	onInput: (event: Event) => emit('input', event),
-	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
-	onMousedown: (event: MouseEvent) => emit('mousedown', event),
-	onMouseup: (event: MouseEvent) => emit('mouseup', event),
-	'onUpdate:modelValue': (event: any) => emit('update:modelValue', event),
-};
-</script>
+import { ref } from 'vue';
+import { BbIcon, BbRating } from 'bitboss-ui';
 
-<style lang="postcss">
-@import './index.css';
-</style>
+// The icon slot replaces the star glyph; `size` arrives as a resolved CSS
+// length string, so pass it straight through to BbIcon.
+const love = ref<number | null>(4);
+</script>
 ```
 
-## Types
-
-```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { BaseRatingEvents, BaseRatingSlots } from '../BaseRating/types';
-import type { BbIconProps } from '../BbIcon/types';
-
-export type BbRatingProps = {
-	/**
-	 * 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;
-
-	/**
-	 * Sets the component in a compact state.
-	 */
-	compact?: boolean;
-
-	/**
-	 * Disables the component.
-	 */
-	disabled?: 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;
-
-	/**
-	 * 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 legend of the fieldset while maintaining accessibility.
-	 */
-	hideLegend?: boolean;
-	/**
-	 * Text box to be displayed near the input, usually to indicate instructions.
-	 */
-	hint?: string;
-
-	/**
-	 * The identifier of the component.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can.
-	 *
-	 * @defaultValue `'left'`
-	 */
-	inputPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Text content of the legend.
-	 */
-	legend: string;
-
-	/**
-	 * Sets the text alignment of the legend.
-	 */
-	legendPosition?: 'left' | 'center' | 'right';
-	/**
-	 * Used by v-model.
-	 */
-	modelValue: null | number;
-	/**
-	 * Defines the name of the input.
-	 */
-	name: string;
-
-	/**
-	 * Keeps the hint displayed.
-	 */
-	persistentHint?: 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;
-	/**
-	 * Maximum number of stars to render and maximum value of the component.
-	 */
-	stars?: number;
-} & Pick<BbIconProps, 'size'>;
-
-/** Re-export for consumers importing events type from BbRating. */
-export type BbRatingEvents = BaseRatingEvents;
-
-/** Props exposed by the `legend` slot. */
-export type BbRatingLegendSlotProps = {
-	/** The `legend` prop value. */
-	text: string;
-	/** Whether the rating is in an error state. */
-	hasErrors: boolean;
-};
+### Keyboard
 
-export type BbRatingSlots = BaseRatingSlots & {
-	/**
-	 * Replaces the default fieldset legend text rendered above the rating stars.
-	 */
-	legend?: (props: BbRatingLegendSlotProps) => any;
-};
-```
+The stars are a standard radio group, so keyboard behaviour is the native one:
+**Arrow** keys move the selection between adjacent stars and **Tab** moves in and
+out of the group. When `clearable` is set, **Delete** / **Backspace** on the
+selected star clears it to `null`. A `readonly` rating swallows those keys so the
+displayed score can't be nudged while remaining focusable.
 
-## Styles
+### A rating inside a form
 
-```css
-.bb-rating {
-	.bb-base-input-container--horizontal {
-		.bb-base-input-container__label {
-			float: left;
-		}
-	}
+Because the control is a real radio group inside a `<fieldset>`, `required` and
+the error props integrate with form validation like any other field. `errors`
+(string or array) renders messages under the stars; `has-errors` toggles error
+styling alone.
 
-	.bb-base-input-container__input--right {
-		.bb-cr-container__container {
-			justify-content: flex-end;
-		}
-	}
-	.bb-base-input-container__input--center {
-		.bb-cr-container__container {
-			justify-content: center;
-		}
+The classic shape is a post-purchase review prompt: the rating is the required
+field, a follow-up question appears only for low scores, and submitting without
+a rating surfaces `errors` on the fieldset. Remember to reset `errors` as soon
+as the user picks a value.
+
+**Order review with follow-up**
+
+```vue
+<template>
+	<form
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+		novalidate
+		@submit.prevent
+	>
+		<div class="flex flex-col gap-0.5">
+			<span class="text-sm font-medium">How was your order?</span>
+			<span class="text-xs text-gray-500">
+				Order #10482 · delivered Jul 8, 2026
+			</span>
+		</div>
+		<BbRating
+			v-model="score"
+			clearable
+			compact
+			:errors="errors"
+			legend="Rate your order"
+			name="order-review"
+			required
+			@update:model-value="onScoreChange"
+		/>
+		<p class="text-sm text-gray-500" data-testid="score">
+			{{ score === null ? 'Not rated yet' : `${score}/5 — ${labels[score]}` }}
+		</p>
+		<BbTextarea
+			v-if="score !== null && score <= 3"
+			v-model="feedback"
+			compact
+			data-testid="followup"
+			label="What went wrong?"
+			name="order-feedback"
+			placeholder="Late delivery, damaged packaging…"
+			:rows="3"
+		/>
+		<div class="flex items-center gap-2">
+			<BbButton variant="primary" @click="submit">Submit review</BbButton>
+			<span v-if="sent" class="text-xs text-gray-500" data-testid="sent">
+				Thanks — review received.
+			</span>
+		</div>
+	</form>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbRating, BbTextarea } from 'bitboss-ui';
+
+const score = ref<number | null>(null);
+const feedback = ref('');
+const errors = ref<string | undefined>();
+const sent = ref(false);
+
+const labels: Record<number, string> = {
+	1: 'Poor',
+	2: 'Fair',
+	3: 'Good',
+	4: 'Great',
+	5: 'Excellent',
+};
+
+/** Clear validation as soon as a star is picked. */
+const onScoreChange = () => {
+	errors.value = undefined;
+	sent.value = false;
+};
+
+/** Stand-in mutation; the button spins until this resolves. */
+const submit = async () => {
+	if (score.value === null) {
+		errors.value = 'Select a rating before submitting.';
+		return;
 	}
-}
+	await new Promise((resolve) => setTimeout(resolve, 600));
+	sent.value = true;
+};
+</script>
 ```
+
+### Works well with
+
+- `BbSlider` — when you actually need a fractional or continuous value.
+- `BbIcon` — inside the `icon` slot for a custom glyph.
+- `BbTextarea` — the follow-up question in a review form.
+- `useToast` — confirm a submitted rating in review flows.
+
+No plugin options change `BbRating` behaviour except the star/clear accessible
+labels, which come from the library's i18n strings (`rating.singleStar`,
+`rating.multipleStars`, `rating.clearHint`) and localize automatically. It
+renders SSR-safe markup in Nuxt and Inertia apps.
+
+### Gotchas and anti-patterns
+
+- Don't expect half stars — the value is a whole number; round averages for the
+  glyphs and show the decimal as text.
+- Don't treat a cleared rating as `0`; `clearable` emits `null`. Type the model
+  `number | null`.
+- Don't do math on the `icon` slot's `size` — it's a CSS length string, pass it
+  through to `BbIcon`.
+- Don't hide the per-star accessible label to "clean up" the DOM — it is the only
+  text a screen-reader user gets.
+- Pass `name` when a native form post needs a known key; otherwise the generated
+  group name is enough for multiple ratings on one page.
+
+### Accessibility
+
+- `legend` is required — it labels the set via the `<fieldset>`. `name` is
+  optional (a unique group name is generated when omitted).
+- Each star exposes an accessible label ("n of m stars"); keep it.
+- `hint`, `description` and `errors` are announced via `aria-describedby`; the
+  clear affordance adds its own hint when `clearable`.
+- The `icon` slot content is decorative — keep the meaningful label on the
+  fieldset, not the glyph.
+- Prefer `readonly` (focusable) over `disabled` for scores the user may inspect.
+
+## v-model
+
+- `v-model` — type: `number \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `clearable` | `boolean \| undefined` |  |  | Allows clearing the selected rating by clicking the current value. |
+| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `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`. |
+| `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. |
+| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. |
+| `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. |
+| `hideLegend` | `boolean \| undefined` |  |  | Visually hides the legend of the fieldset 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. |
+| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
+| `legend` | `string` |  | yes | Text content of the legend. |
+| `legendMode` | `"outside" \| "inside" \| undefined` |  |  | Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow; `'inside'` overlays the legend inside the fieldset border. Floating mode is not supported for rating groups. |
+| `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the legend. |
+| `modelValue` | `number \| null` |  | yes | Used by v-model. |
+| `name` | `string \| undefined` |  |  | Defines the name of the star radio inputs. Optional: the stars live inside a single component instance, so an omitted name falls back to a generated one that groups them correctly on its own. Pass a name only when the value has to be submit… |
+| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `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. |
+| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` |  |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
+| `stars` | `number \| undefined` |  |  | Maximum number of stars to render and maximum value of the component. |
+| `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. |
+
+## Events
+
+- `active` — `(event: "active"): void`
+- `blur` — `(event: "blur", event: FocusEvent): void`
+- `change` — `(event: "change", event: Event): void`
+- `click` — `(event: "click", event: MouseEvent): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `inactive` — `(event: "inactive"): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
+- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", value: number \| null): void`
+
+## Slots
+
+- `append` — scope: `object` — Content rendered after the row of rating stars.
+- `icon` — scope: `BaseRatingIconSlotProps` — Replaces the default star SVG for each rating option.
+- `legend` — scope: `BbRatingLegendSlotProps` — Replaces the default fieldset legend text rendered above the rating stars.
+- `prepend` — scope: `object` — Content rendered before the row of rating stars.
+
+## 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 \| null>` | vee-validate rules for this field. |
+| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation. Defaults are per-control (e.g. `['blur']` for text inputs, `['inactive']` for pickers/groups). |
+| `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
+
+- [BbSlider](./BbSlider.md) — Selects numeric values across a bounded range.