bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbTag.md

@@ -1,314 +1,415 @@
 # BbTag
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Inputs**
+- Description: Captures and displays tag-like token values.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbTag.md](./source/BbTag.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbTag` when the values are authored by the user, not chosen from a
+predefined list: skills, keywords, email recipients, labels. `v-model` binds the
+**array** of tokens; typing and pressing the divider key (Enter by default) turns
+the current text into a chip, and Backspace from an empty field walks back
+through the existing chips to remove them.
+
+If the user should pick from a known set of options instead of inventing values,
+use `BbSelect` (single or multi, with search). Tags are for open vocabularies.
+
+### The model is always an array
+
+`BbTag`'s `modelValue` **must be an array** — the underlying control throws at
+mount if it isn't. Seed it with `ref([])` (or the starting tags); never leave it
+`undefined` or bind a scalar. This is why every interactive example here is a
+small SFC with a typed `ref`, rather than an inline snippet.
+
+```ts
+const skills = ref<string[]>(['Vue', 'TypeScript', 'Design systems']); // ✅
+// const skills = ref();                              // ✗ throws: modelValue must be an array
+```
+
+### Adding and removing
+
+Seed `v-model` with the starting tags. `placeholder` prompts the first entry;
+`clearable` shows a button to empty the whole field at once. Removing a single
+tag is built in — click a chip's close button, or use Backspace (see the keyboard
+section). Editing the text and pressing Enter commits it; the input clears ready
+for the next.
+
+**Skills input**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-tag"
-		: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 max-w-md flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
 	>
-		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseTag
-				:id="id"
-				:append:icon="props['append:icon']"
-				:aria-describedby="ariaDescribedby"
-				:autocomplete="autocomplete"
-				:autofocus="autofocus"
-				:clearable="clearable"
-				:comma="comma"
-				:compact="compact"
-				:disabled="disabled"
-				:divider="divider"
-				:has-errors="hasErrors"
-				:loading="loading"
-				:max="max"
-				:model-value="modelValue"
-				:multiple="multiple"
-				:name="name"
-				:placeholder="placeholder"
-				:prepend:icon="props['prepend:icon']"
-				:readonly="readonly"
-				:required="required"
-				v-bind="eventListeners"
-			>
-				<template #prepend-outer="data"
-					><slot name="prepend-outer" v-bind="data"
-				/></template>
-				<template #prepend="data"
-					><slot name="prepend" v-bind="data"
-				/></template>
-				<template #prefix="data"><slot name="prefix" v-bind="data" /></template>
-				<template #append="data"><slot name="append" v-bind="data" /></template>
-				<template #suffix="data"><slot name="suffix" v-bind="data" /></template>
-				<template #append-outer="data"
-					><slot name="append-outer" v-bind="data"
-				/></template>
-			</BaseTag>
-		</template>
-	</BaseInputContainer>
+		<div class="flex flex-col gap-0.5">
+			<span class="text-sm font-medium">Profile · Skills</span>
+			<span class="text-xs text-gray-500">
+				Shown on your public profile and in search
+			</span>
+		</div>
+		<BbTag
+			v-model="skills"
+			clearable
+			compact
+			hint="Press Enter to add, Backspace to remove the last."
+			label="Skills"
+			name="skills"
+			persistent-hint
+			placeholder="Add a skill…"
+		/>
+		<p class="text-xs text-gray-500" data-testid="count">
+			{{ skills.length }} skill{{ skills.length === 1 ? '' : 's' }} shown on
+			your profile
+		</p>
+	</div>
 </template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTag } from 'bitboss-ui';
+
+const skills = ref<string[]>(['Vue', 'TypeScript', 'Design systems']);
+</script>
+```
+
+Besides `update:modelValue`, `duplicate` and `max` (below) the component
+re-emits the native input events (`focus`, `blur`, `change`, `input`,
+`keydown`, `keyup`, `click`) for analytics or side effects.
+
+### Choosing the delimiter key
 
+`divider` sets the key (or keys) that commit the current text to a chip; it
+defaults to `'Enter'`. Set it to any `KeyboardEvent.key` — most usefully `','`
+for a comma-to-add field — or to an array of keys such as `['Enter', ',']` when
+either should work. With a single-character divider the component also splits a
+value that already contains that character (e.g. pasted text), taking the text
+up to the first delimiter.
+
+**Comma- or Enter-delimited labels**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<span class="text-sm font-medium">Issue #4821</span>
+			<span class="text-xs text-gray-500">bitboss-ui · triage labels</span>
+		</div>
+		<BbTag
+			v-model="labels"
+			compact
+			:divider="[',', 'Enter']"
+			hint="Type a label and press comma or Enter to add it."
+			label="Labels"
+			name="labels"
+			persistent-hint
+			placeholder="bug, regression, breaking-change…"
+		/>
+		<p class="text-xs text-gray-500" data-testid="labels">
+			{{ labels.join(' · ') || 'No labels yet' }}
+		</p>
+	</div>
+</template>
 <script setup lang="ts">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseTag from '../BaseTag/BaseTag.vue';
-import { ref, computed } from 'vue';
-import type { BbTagProps, BbTagEvents, BbTagSlots } from './types';
-
-const props = withDefaults(defineProps<BbTagProps>(), {
-	multiple: true,
-});
-
-const emit = defineEmits<BbTagEvents>();
-
-defineSlots<BbTagSlots>();
-
-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),
-	onDuplicate: (string: string) => emit('duplicate', string),
-	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),
-	onKeyup: (event: KeyboardEvent) => emit('keyup', event),
-	'onUpdate:modelValue': (value: any) => emit('update:modelValue', value),
-};
+import { ref } from 'vue';
+import { BbTag } from 'bitboss-ui';
+
+const labels = ref<string[]>(['bug', 'high-priority']);
 </script>
+```
+
+### Duplicates, max and feedback
+
+Adding a value already present does **not** create a second chip — the component
+emits a `duplicate` event with the offending string instead, which you can
+surface as a warning.
+
+Entries are **always trimmed** before they are committed or compared, so
+`  vue  ` is stored as `vue`, a padded restatement of an existing tag counts as
+a duplicate, and a whitespace-only entry is ignored rather than becoming an
+invisible chip. Matching also **folds case by default** — `Vue` is a duplicate
+of `vue` — because two chips differing only in case read as duplicates to the
+user. The tag is still stored with the casing the user typed; only the
+comparison folds. Set `case-sensitive` when case genuinely distinguishes two
+tags:
 
-<style lang="postcss">
-@import './index.css';
-</style>
+```vue
+<!-- 'Vue' and 'vue' can both exist -->
+<BbTag v-model="tags" case-sensitive label="Tags" />
 ```
 
-## Types
+`max` caps the number of tags; once the cap is reached
+further entries are rejected and the component emits a `max` event with the
+rejected string — surface it the same way you would a `duplicate`, and show the
+remaining count from `modelValue.length` if it helps.
 
-```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { IconType } from '@/types/Icon';
-import type { BaseTagEvents } from '../BaseTag/types';
-
-export type BbTagProps = {
-	/**
-	 * Name of the icon to be added at the end of the input.
-	 */
-	// eslint-disable-next-line vue/prop-name-casing
-	'append:icon'?: IconType;
-
-	/**
-	 * Guides to the browser as to the type of information expected in the field.
-	 */
-	autocomplete?: InputHTMLAttributes['autocomplete'];
-
-	/**
-	 * Sets autofocus on page load.
-	 */
-	autofocus?: InputHTMLAttributes['autofocus'];
-
-	/**
-	 * Sets the display model for selected values to a list of comma separated string.
-	 * In this mode the user cannot deselect an option by pressing the close button.
-	 */
-	comma?: boolean;
-
-	/**
-	 * Displays a clear button when the input has a value and is being interacted with.
-	 */
-	clearable?: boolean;
-
-	/**
-	 * Sets the component in a 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;
-
-	/**
-	 * The divider key used to separate values from one another. By default it is "Enter".
-	 */
-	divider?: KeyboardEvent['key'];
-
-	/**
-	 * 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';
-
-	/**
-	 * Sets the component in a loading state, usually triggering some visual styles.
-	 */
-	loading?: boolean;
-
-	/**
-	 * Maximum number of selected items.
-	 */
-	max?: number;
-
-	/**
-	 * Used by v-model. Can be any serializable type.
-	 */
-	modelValue: any;
-
-	/**
-	 * Allows the selection of multiple items.
-	 *
-	 * @defaultValue `true`
-	 */
-	multiple?: boolean;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name?: InputHTMLAttributes['name'];
-
-	/**
-	 * Keeps the hint displayed.
-	 */
-	persistentHint?: boolean;
-
-	/**
-	 * String displayed when there's no data.
-	 */
-	placeholder?: InputHTMLAttributes['placeholder'];
-
-	/**
-	 * Name of the icon to be added at the start of the input.
-	 */
-	// eslint-disable-next-line vue/prop-name-casing
-	'prepend:icon'?: IconType;
-
-	/**
-	 * 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;
-};
+**Recipients with a cap**
+
+```vue
+<template>
+	<div
+		class="flex max-w-md flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<span class="text-sm font-medium">Invite to Acme Studio</span>
+			<span class="text-xs text-gray-500">
+				Up to 5 people · they get editor access
+			</span>
+		</div>
+		<BbTag
+			v-model="recipients"
+			autocomplete="email"
+			compact
+			label="Invite people"
+			:max="5"
+			name="recipients"
+			placeholder="Add an email…"
+			prepend:icon="lucide:mail"
+			@duplicate="onDuplicate"
+			@max="onMax"
+			@update:model-value="warning = ''"
+		/>
+		<p class="text-xs text-gray-500" data-testid="invite-status">
+			{{ recipients.length }} / 5 invited<span v-if="warning">
+				— {{ warning }}</span
+			>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTag } from 'bitboss-ui';
 
-/** Re-export for consumers importing events type from BbTag. */
-export type BbTagEvents = BaseTagEvents;
+const recipients = ref<string[]>(['ada@lovelace.dev', 'grace@hopper.io']);
+const warning = ref('');
 
-/** Props exposed by the `label` slot. */
-export type BbTagLabelSlotProps = {
-	/** The `label` prop value. */
-	text: string;
-	/** Whether the input is in an error state. */
-	hasErrors: boolean;
+const onDuplicate = (value: string) => {
+	warning.value = `${value} is already invited`;
 };
 
-export type BbTagSlots = {
-	/**
-	 * Content appended inside the input field wrapper, after the tag chips.
-	 */
-	append?: (props: object) => any;
-	/**
-	 * Content appended outside the input field wrapper.
-	 */
-	'append-outer'?: (props: object) => any;
-	/**
-	 * Replaces the default label text rendered above the input.
-	 */
-	label?: (props: BbTagLabelSlotProps) => any;
-	/**
-	 * Content prepended inside the input field wrapper, before the tag chips.
-	 */
-	prepend?: (props: object) => any;
-	/**
-	 * Content rendered as an inline prefix inside the input field.
-	 */
-	prefix?: (props: object) => any;
-	/**
-	 * Content rendered as an inline suffix inside the input field.
-	 */
-	suffix?: (props: object) => any;
-	/**
-	 * Content prepended outside the input field wrapper.
-	 */
-	'prepend-outer'?: (props: object) => any;
+const onMax = (value: string) => {
+	warning.value = `cannot invite ${value}: the list is full`;
 };
+</script>
+```
+
+### Keyboard
+
+With text in the field:
+
+- A **divider** key (Enter by default) commits the text as a new chip.
+
+With the field **empty**, the keys navigate and edit the existing chips:
+
+- **Backspace** highlights the last chip, then removes the highlighted one on the
+  next press — a two-step "select, then delete" rather than an instant wipe.
+- **Arrow Left / Arrow Right** move the highlight between chips.
+- **Home / End** jump to the first / last chip.
+- **Escape** drops the chip highlight back to the input.
+
+`readonly` and `disabled` suppress all of this while keeping existing chips
+visible.
+
+### Comma display mode
+
+`comma` renders the selected tags as a single comma-separated string rather than
+individual chips. It is a compact **display** mode — in it, chips cannot be
+removed one by one (there are no close buttons), so use it where the set changes
+rarely. `clearable` still empties the whole field.
+
+**Digest topics as a comma list**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<span class="text-sm font-medium">Weekly digest</span>
+			<span class="text-xs text-gray-500">
+				Topics land as a compact comma list
+			</span>
+		</div>
+		<BbTag
+			v-model="topics"
+			clearable
+			comma
+			compact
+			label="Digest topics"
+			name="topics"
+			placeholder="Add a topic…"
+		/>
+		<p class="text-xs text-gray-500">
+			Your weekly digest covers {{ topics.length }} topics.
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTag } from 'bitboss-ui';
+
+const topics = ref<string[]>(['Product updates', 'Engineering', 'Design']);
+</script>
 ```
 
-## Styles
-
-```css
-.bb-tag {
-	.bb-base-input-container {
-		.bb-base-input-container__input {
-			.bb-base-tag {
-				display: inline-flex;
-			}
-		}
-	}
-}
+### Affordances and state
+
+- `prepend:icon` / `append:icon` add a leading/trailing glyph (e.g. a mail icon
+  for a recipients field) — decorative, so they never replace the label.
+- `prefix` / `suffix` slots add inline content inside the field; `prepend` /
+  `append` and their `-outer` variants add content in and around the input
+  chrome.
+- `loading` shows the loading affordance — useful while validating or
+  de-duplicating tags against a server.
+- `compact` applies the denser variant for toolbars.
+
+### Disabled, readonly and errors
+
+- `disabled` sets the native attribute: the field leaves the tab order and greys
+  out; chips stay visible but inert.
+- `readonly` keeps the field focusable and the chips visible but blocks typing
+  and removal — prefer it, with an explanation, for a locked set of tags.
+- `required` marks the field invalid until at least one tag is present (the
+  underlying input drops its `required` once the array is non-empty). Combine
+  with `errors` / `has-errors` for validation messaging; the input exposes
+  `aria-invalid` in the error state.
+
+### Works well with
+
+- `BbSelect` — when the values come from a known list instead of free text.
+- `useToast` — report a rejected `duplicate` / `max` entry or a server-side
+  validation failure.
+- `BbBadge` — the same token visual (add `clearable` for a removable one), for
+  read-only display elsewhere in the UI.
+
+No plugin options change `BbTag` behaviour (no i18n strings of its own, no
+teleport). It renders SSR-safe markup in Nuxt and Inertia apps.
+
+### Gotchas and anti-patterns
+
+- Don't bind a non-array (or `undefined`) `modelValue` — it throws at mount.
+  Always seed `ref([])`.
+- Don't stack up divider keys "just in case" — `divider` accepts an array
+  (e.g. `['Enter', ',']`), but only add keys users actually expect; a comma
+  divider makes values containing commas impossible to enter.
+- Don't mutate the array from a `max` handler to "make room" — the rejected
+  value is only reported; decide explicitly whether to raise the cap or warn.
+- Don't hand-roll trimming or case-folding in an `update:modelValue` handler —
+  entries are trimmed and matched case-insensitively already. Reach for
+  `case-sensitive` only when `Vue` and `vue` really are different tags.
+- Don't use `comma` mode when users need to remove individual tags — it has no
+  per-chip close button.
+
+### Label placement
+
+`labelMode` places the label like on every other input — `outside` (above the
+field), `inside`, or `floating` — and falls back to the plugin's
+`defaultInputLabelMode` when unset, so a tag field matches the rest of the form
+without being configured separately. It is orthogonal to `labelPosition`, which
+only sets the label's text alignment.
+
+```vue
+<BbTag v-model="tags" label="Skills" label-mode="floating" />
 ```
+
+### Accessibility
+
+- `label` names the field; keep it visible unless an adjacent heading labels it
+  (`hide-label`).
+- `hint`, `description` and `errors` are announced via `aria-describedby`; the
+  input exposes `aria-invalid` in the error state.
+- Chip removal is keyboard-reachable (Backspace / arrows), not pointer-only.
+- Prefer `readonly` (focusable, discoverable) over `disabled` for a locked set of
+  tags, with a nearby explanation.
+
+## v-model
+
+- `v-model` — type: `string[]`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
+| `autocomplete` | `string \| undefined` |  |  | Guides to the browser as to the type of information expected in the field. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `caseSensitive` | `boolean \| undefined` |  |  | Compare tags case-sensitively when rejecting duplicates, so `Vue` and `vue` can both exist. By default matching folds case, because two chips differing only in case read as duplicates to a user. Either way the tag is stored with the casing … |
+| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
+| `comma` | `boolean \| undefined` |  |  | Sets the display model for selected values to a list of comma separated string. In this mode the user cannot deselect an option by pressing the close button. |
+| `compact` | `boolean \| undefined` |  |  | Sets the component in a 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`. |
+| `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. |
+| `divider` | `string \| string[] \| undefined` |  |  | The divider key used to separate values from one another. By default it is "Enter". Accepts a single key or an array of keys (e.g. `['Enter', ',']`) — any of them commits the current text. |
+| `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. |
+| `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` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Where the label sits relative to the field: `outside` above it, `inside` within the control, or `floating` (starts inside, lifts on focus/value). Defaults to `config.defaultInputLabelMode`, like the other inputs. |
+| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. |
+| `max` | `number \| undefined` |  |  | Maximum number of selected items. |
+| `modelValue` | `string[]` |  | yes | Used by v-model. Contains all selected tags. |
+| `name` | `string \| undefined` |  |  | Defines the name of the input. |
+| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
+| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
+| `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. |
+| `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`
+- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
+- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
+- `duplicate` — `(event: "duplicate", string: string): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `inactive` — `(event: "inactive"): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
+- `max` — `(event: "max", string: string): void`
+- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
+- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
+- `paste` — `(event: "paste", event: ClipboardEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", value: string[]): void`
+
+## Slots
+
+- `append` — scope: `Record<string, never>` — Content appended inside the input field wrapper, after the tag chips.
+- `append-outer` — scope: `Record<string, never>` — Content appended outside the input field wrapper.
+- `label` — scope: `BbTagLabelSlotProps` — Replaces the default label text rendered above the input.
+- `prefix` — scope: `Record<string, never>` — Content rendered as an inline prefix inside the input field.
+- `prepend` — scope: `Record<string, never>` — Content prepended inside the input field wrapper, before the tag chips.
+- `prepend-outer` — scope: `Record<string, never>` — Content prepended outside the input field wrapper.
+- `suffix` — scope: `Record<string, never>` — Content rendered as an inline suffix inside the input field.
+
+## 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<string[]>` | 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
+
+- [BbBadge](./BbBadge.md) — Displays compact status counters or labels, the floating mode acts as notification dot.
+- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.