bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbTextInput.md

@@ -1,356 +1,875 @@
 # BbTextInput
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Inputs**
+- Description: Captures single-line text values.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbTextInput.md](./source/BbTextInput.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbTextInput` for any short, single-line string: names, emails, URLs,
+search boxes, coupon codes. It owns the shared input chrome — label, description,
+hint, validation, affix icons/slots, `clearable`, `loading` and masking — that
+the whole form family builds on.
+
+Pick a sibling when the shape of the data is different:
+
+- multi-line prose (bios, notes, messages) → `BbTextarea`;
+- numbers with clamping/stepping (quantities, prices) → `BbNumberInput`;
+- calendar dates → `BbDatePickerInput`;
+- choosing from a known set of options → `BbSelect` / `BbRadioGroup`.
+
+`v-model` binds a `string | null` — an emptied field emits `null`, never `''`.
+`label` is required (hide it visually with `hideLabel`, never drop it).
+
+### Label & label modes
+
+`label` names the field and doubles as the default `name` (lowercased,
+accents stripped, spaces removed) — pass `name` explicitly when the value is
+posted to a server.
+
+- **`labelMode`** sets where the label sits: `outside` (above the field),
+  `floating` (rests inside like a placeholder at reduced opacity, lifts on
+  focus/fill) or `inside` (pinned small inside the top of the field). When you
+  don't set it, the project-wide `config.defaultInputLabelMode` applies
+  (library default: `outside`) — so a project can go all-floating without
+  touching call sites.
+- **`labelPosition`** aligns the label text `left` / `center` / `right`.
+- **`hideLabel`** keeps the label for screen readers but removes it visually —
+  the right move for search boxes whose design shows only a placeholder.
+- The **`label` slot** replaces the label text and receives
+  `{ text, hasErrors }`, e.g. to append a required marker that turns red with
+  the error state.
+
+Avoid combining `labelMode="floating"` with a `placeholder` — the resting
+label already plays that role and the two would overlap.
+
+**The three label modes**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-text-input"
-		:compact="compact"
-		:direction="direction"
-		:errors="errors"
-		:has-errors="hasErrors"
-		:hide-label="hideLabel"
-		:hint="hint"
-		:label="label"
-		:label-mode="labelMode"
-		:label-position="labelPosition"
-		:model-value="modelValue"
-		:name="name"
-		:reverse="reverse"
-		:show-hint="showHint"
-	>
-		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseTextInput
-				:id="id"
-				:append:icon="props['append:icon']"
-				:aria-describedby="ariaDescribedby"
-				:autocomplete="autocomplete"
-				:autofocus="autofocus"
-				:clearable="clearable"
-				:compact="compact"
-				:disabled="disabled"
-				:emit-masked="emitMasked"
-				:has-errors="hasErrors"
-				:input-mode="inputMode"
-				:label-mode="labelMode"
-				:loading="loading"
-				:mask="mask"
-				:model-value="modelValue"
-				:name="name"
-				:placeholder="placeholder"
-				:prepend:icon="props['prepend:icon']"
-				:readonly="readonly"
-				:required="required"
-				:type="type"
-				v-bind="eventListeners"
-			>
-				<template #append-outer><slot name="append-outer" /></template>
-				<template #append><slot name="append" /></template>
-				<template #prefix><slot name="prefix" /></template>
-				<template #suffix><slot name="suffix" /></template>
-				<template #prepend><slot name="prepend" /></template>
-				<template #prepend-outer><slot name="prepend-outer" /></template>
-			</BaseTextInput>
-		</template>
-	</BaseInputContainer>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Profile basics</p>
+			<p class="text-xs text-gray-500">
+				Same field, three label placements — pick one per product.
+			</p>
+		</div>
+		<BbTextInput
+			v-model="outside"
+			label="Outside (default)"
+			placeholder="Display name"
+		/>
+		<BbTextInput v-model="floating" label="Floating" label-mode="floating" />
+		<BbTextInput v-model="inside" label="Inside" label-mode="inside" />
+	</div>
 </template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTextInput } from 'bitboss-ui';
 
+const outside = ref<string | null>('Ada Lovelace');
+const floating = ref<string | null>('ada@bitboss.it');
+const inside = ref<string | null>('Bitboss');
+</script>
+```
+
+**Custom label via slot**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Workspace settings</p>
+			<p class="text-xs text-gray-500">
+				Required fields mark the label — keep the accessible name intact.
+			</p>
+		</div>
+		<BbTextInput
+			v-model="organization"
+			description="Appears on invoices and member invites."
+			label="Organization"
+			name="organization"
+			placeholder="Bitboss"
+		>
+			<template #label="{ text, hasErrors }">
+				{{ text }}
+				<span
+					:class="hasErrors ? 'text-[color:var(--bb-danger)]' : 'text-gray-500'"
+				>
+					*
+				</span>
+			</template>
+		</BbTextInput>
+	</div>
+</template>
 <script setup lang="ts">
-import { ref, computed } from 'vue';
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseTextInput from '../BaseTextInput/BaseTextInput.vue';
-import type {
-	BbTextInputProps,
-	BbTextInputEvents,
-	BbTextInputSlots,
-} from './types';
-
-const props = defineProps<BbTextInputProps>();
-
-const emit = defineEmits<BbTextInputEvents>();
-
-defineSlots<BbTextInputSlots>();
-
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
-
-/**
- * These events are just propagated
- */
-const eventListeners = {
-	onBlur: (event: FocusEvent) => {
-		active.value = false;
-		emit('blur', event);
-	},
-	onChange: (event: Event) => emit('change', event),
-	onClick: (event: MouseEvent) => emit('click', event),
-	onFocus: (event: FocusEvent) => {
-		active.value = true;
-		emit('focus', event);
-	},
-	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': (value: string | null) =>
-		emit('update:modelValue', value),
-};
+import { ref } from 'vue';
+import { BbTextInput } from 'bitboss-ui';
+
+const organization = ref<string | null>('Bitboss');
 </script>
+```
 
-<style lang="postcss">
-@import './index.css';
-</style>
+### Description, hint & errors
+
+Three messaging surfaces, three jobs:
+
+- **`description`** — always-visible muted text between label and field, linked
+  via `aria-describedby`. Use for instructions the user needs _before_ typing.
+- **`hint`** — appears below the field while it's focused; `persistentHint`
+  keeps it visible. Use for reassurance or format examples.
+- **`errors`** — a string or string array rendered below the field in an
+  `aria-live="polite"` region, so new messages are announced. **`hasErrors`**
+  flips the visual error state and `aria-invalid` — passing `errors` alone
+  already implies the error state, so use `hasErrors` by itself when the
+  message lives elsewhere (e.g. a form-level summary).
+- **`warnings`** — the amber counterpart of `errors`: a string or string array
+  rendered below the field in its own `aria-live="polite"` region, for a
+  valid-but-noteworthy value (unusual, near a limit, soft-flagged) where a hard
+  error would overstate the problem. A non-empty `warnings` implies the warning
+  state (same as `errors` implies the error state). **`hasWarning`** forces that
+  chrome without a message. Either way you get tinted border, focus ring and a
+  warning icon in amber (`--bb-warn`) — but, unlike `hasErrors`, **no**
+  `aria-invalid`. Errors win when both are set, and the warning messages are
+  suppressed, so the field never shows amber and red at once.
+
+`required` forwards to the native input for browser validation; your own
+validation layer should still drive `errors`.
+
+**The messaging surface, in one field**
+
+```vue
+<div class="max-w-sm">
+	<BbTextInput
+		v-model="state.displayName"
+		label="Display name"
+		description="This is the name shown on your public profile."
+		hint="2–32 characters, letters and spaces."
+		persistentHint
+		placeholder="Ada Lovelace"
+	/>
+</div>
 ```
 
-## Types
-
-```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { MaskInputOptions } from 'maska';
-import type { IconType } from '@/types/Icon';
-import type {
-	BaseTextInputEvents,
-	BaseTextInputSlots,
-} from '../BaseTextInput/types';
-
-export type BbTextInputProps = {
-	/**
-	 * 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'];
-
-	/**
-	 * Displays a clear button when the input has a value and is being interacted with.
-	 */
-	clearable?: boolean;
-
-	/**
-	 * Displays the component in a compact version.
-	 */
-	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;
-
-	/**
-	 * Emits the masked value of the input.
-	 */
-	emitMasked?: 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'];
-
-	/**
-	 * The inputmode of the input.
-	 */
-	inputMode?: InputHTMLAttributes['inputmode'];
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Label rendering mode.
-	 */
-	labelMode?: 'outside' | 'floating' | 'inside';
-
-	/**
-	 * Sets the component in a loading state, usually triggering some visual styles.
-	 */
-	loading?: boolean;
-
-	/**
-	 * The mask to be applied to the input.
-	 * Please visit https://beholdr.github.io/maska/v3 for syntax examples.
-	 */
-	mask?: MaskInputOptions;
-
-	/**
-	 * Used by v-model.
-	 */
-	modelValue: string | null;
-
-	/**
-	 * 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;
-
-	/**
-	 * Type of the input. Returns the content type of the object.
-	 */
-	type?: HTMLInputElement['type'];
-};
+**Validation states**
 
-/** Re-export for consumers importing events type from BbTextInput. */
-export type BbTextInputEvents = BaseTextInputEvents;
+```vue
+<template>
+	<div class="grid max-w-sm gap-3">
+		<div class="grid gap-2 rounded-[var(--bb-radius)] border p-3">
+			<p class="text-xs font-medium text-gray-500">Invite teammate</p>
+			<BbTextInput
+				v-model="email"
+				compact
+				:errors="['Enter a valid email', 'Use your company domain']"
+				label="Work email"
+				name="email"
+				placeholder="ada@bitboss.it"
+				prepend:icon="lucide:mail"
+				type="email"
+			/>
+		</div>
+		<div class="grid gap-2 rounded-[var(--bb-radius)] border p-3">
+			<p class="text-xs font-medium text-gray-500">Non-blocking hint</p>
+			<BbTextInput
+				v-model="handle"
+				compact
+				label="Display name"
+				name="handle"
+				placeholder="ada"
+				:warnings="['This name is very short — is it what you meant?']"
+			/>
+		</div>
+		<div class="rounded-[var(--bb-radius)] border px-2 py-1.5">
+			<BbTextInput
+				v-model="search"
+				class="w-full"
+				clearable
+				compact
+				hide-label
+				label="Search"
+				placeholder="Search projects…"
+				prepend:icon="lucide:search"
+				type="search"
+			/>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTextInput } from 'bitboss-ui';
 
-/** Props exposed by the `label` slot. */
-export type BbTextInputLabelSlotProps = {
-	/** The `label` prop value. */
-	text: string;
-	/** Whether the input is in an error state. */
-	hasErrors: boolean;
-};
+const email = ref<string | null>('ada@');
+const handle = ref<string | null>('ad');
+const search = ref<string | null>('billing');
+</script>
+```
 
-export type BbTextInputSlots = BaseTextInputSlots & {
-	/**
-	 * Replaces the default label text rendered above the input.
-	 */
-	label?: (props: BbTextInputLabelSlotProps) => any;
-};
+The second field carries `warnings` — a non-blocking amber hint in an
+`aria-live` region, mirroring `errors`. A non-empty `warnings` lights the state
+on its own (use `hasWarning` to force the chrome without messages). When a field
+has **both** `errors` and `warnings`, errors win: the field shows error chrome
+and only the error messages. The last field shows the common a11y move: a search
+box with a _visually_ hidden label (`hideLabel`) — the accessible name survives
+for screen readers even though the design shows only a placeholder.
+
+### Icons, affixes & slots
+
+Use `prepend:icon` / `append:icon` for iconography inside the field, and the
+`prefix` / `suffix` slots for short inline text (units, fixed URL segments,
+currency). Affixes are decoration — they never receive focus, so keep
+interactive controls out of them.
+
+The append-icon position is shared with the field's status indicators, one at
+a time by priority: **clear button → spinner (`loading`) → error icon
+(`hasErrors`) → your `append:icon`**. The warning icon (`hasWarning`) shares the
+error icon's slot — shown when `hasWarning` is set and there is no error. Don't
+rely on an `append:icon` staying visible on a field that is also `clearable` or
+validated.
+
+The full slot ring, inside → out:
+
+- `prefix` / `suffix` — styled inline text hugging the typed value;
+- `prepend` / `append` — free-form content inside the input chrome (replaces
+  `prefix`/`suffix` when both are given);
+- `prepend-outer` / `append-outer` — content outside the chrome, laid out next
+  to the field; the right home for an adjacent button.
+
+**Icons and text affixes**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Workspace & billing</p>
+			<p class="text-xs text-gray-500">
+				Icons and short affixes live inside the chrome; actions sit outside.
+			</p>
+		</div>
+		<BbTextInput
+			v-model="site"
+			append:icon="lucide:check"
+			compact
+			label="Workspace URL"
+			name="workspace-url"
+		>
+			<template #prefix>acme.app/</template>
+		</BbTextInput>
+		<BbTextInput v-model="price" compact label="Seat price" name="price">
+			<template #prefix>$</template>
+			<template #suffix>USD</template>
+		</BbTextInput>
+		<BbTextInput
+			compact
+			label="API key"
+			:model-value="apiKey"
+			name="api-key"
+			readonly
+		>
+			<template #append-outer>
+				<BbButton
+					aria-label="Copy API key"
+					icon="lucide:copy"
+					variant="ghost"
+				/>
+			</template>
+		</BbTextInput>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbTextInput } from 'bitboss-ui';
+
+const site = ref<string | null>('acme');
+const price = ref<string | null>('49.00');
+const apiKey = 'sk_live_51Hn3x8Kj2';
+</script>
 ```
 
-## Styles
+### Clearable & loading
 
-```css
-.bb-text-input {
-	&.bb-base-input-outer-container--errors {
-	}
-	&.bb-base-input-outer-container--hint {
-	}
-	.bb-base-input-container {
-		&--vertical {
-		}
-		&--horizontal {
-		}
+`clearable` reveals a clear button while the field has a value and is hovered
+or focused; clicking it emits `update:modelValue` with `null` and refocuses the
+input. There is no separate `clear` event — watch the model for `null`. The
+button is suppressed on `disabled`/`readonly` fields.
 
-		&__label {
-			&--left {
-			}
-			&--center {
-			}
-			&--right {
-			}
-			&--hidden {
-			}
-		}
-		&__input {
-			&--left {
-			}
-			&--center {
-			}
-			&--right {
-			}
-
-			.bb-base-text-input {
-				display: inline-flex;
-				&--disabled {
-				}
-				&--errors {
-				}
-				&--loading {
-				}
-				&--readonly {
-				}
-
-				.bb-common-input-inner-container {
-					.bb-base-text-input__input {
-					}
-
-					&__prepend-icon,
-					&__append-icon {
-					}
-					.bb-spinner {
-					}
-					.bb-error-icon {
-					}
-					&__prefix,
-					&__suffix {
-					}
-				}
-			}
-		}
+`loading` shows a spinner in the append position. It is **visual only** — the
+field stays editable, so pair it with your own guard if the value must not
+change mid-check (e.g. an async username availability call). They compose: a
+clearable field can also be loading.
 
-		&__hint-container {
-			.bb-base-input-container__hint {
-			}
-		}
-		&__errors {
-		}
-		&__error {
+The classic pairing is a signup handle checker: debounce keystrokes, flip
+`loading` while the (simulated) availability call runs, then land the result
+in `errors` or `hint`. Because the field stays editable during the check, the
+handler tags each request and drops stale responses. Watching the model —
+rather than listening to `input` — means the clear button's `null` also resets
+the status.
+
+**Async username check**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Claim your handle</p>
+			<p class="text-xs text-gray-500">
+				Debounced check — spinner while pending, hint or error on result.
+			</p>
+		</div>
+		<BbTextInput
+			v-model="username"
+			clearable
+			compact
+			:errors="errors"
+			:hint="hint"
+			label="Username"
+			:loading="checking"
+			name="username"
+			persistent-hint
+			placeholder="ada"
+		>
+			<template #prefix>bitboss.app/</template>
+		</BbTextInput>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { BbTextInput } from 'bitboss-ui';
+
+const DEFAULT_HINT = 'Lowercase letters and digits, 3–20 characters.';
+const TAKEN = ['ada', 'grace', 'linus'];
+
+const username = ref<string | null>(null);
+const checking = ref(false);
+const errors = ref<string[]>([]);
+const hint = ref(DEFAULT_HINT);
+
+// Simulated availability endpoint — deterministic and fast.
+const isTaken = (handle: string) =>
+	new Promise<boolean>((resolve) => {
+		setTimeout(() => resolve(TAKEN.includes(handle)), 400);
+	});
+
+let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+let requestId = 0;
+
+// Watching the model (instead of @input) also covers the clear button,
+// which emits `null` like any other emptied state.
+watch(username, () => {
+	errors.value = [];
+	hint.value = DEFAULT_HINT;
+	clearTimeout(debounceTimer);
+	requestId += 1;
+	checking.value = false;
+	debounceTimer = setTimeout(async () => {
+		const value = username.value?.trim().toLowerCase();
+		if (!value) return;
+		const id = ++requestId;
+		checking.value = true;
+		const taken = await isTaken(value);
+		// `loading` is only a status light: the field stays editable, so a
+		// newer keystroke may have superseded this check — drop stale results.
+		if (id !== requestId) return;
+		checking.value = false;
+		if (taken) {
+			errors.value = [`"${value}" is already taken`];
+		} else {
+			hint.value = `bitboss.app/${value} is available`;
 		}
+	}, 250);
+});
+</script>
+```
+
+### Masked input
+
+Pass a [maska](https://beholdr.github.io/maska/v3) config to `mask` to format
+as the user types — card numbers, phone numbers, license keys. By default
+`v-model` receives the _unmasked_ value (`'4242424242424242'` for the card
+below); set `emitMasked` to persist the formatted string instead. A fully
+emptied masked field emits `null`, like every other state of this component.
+
+The mask is live-reactive: changing the `mask` options at runtime reformats the
+current value, and toggling `emitMasked` re-emits the model in the new format.
+
+**Credit-card mask**
+
+```vue
+<div class="max-w-sm">
+	<BbTextInput
+		v-model="state.card"
+		label="Card number"
+		placeholder="4242 4242 4242 4242"
+		prepend:icon="lucide:credit-card"
+		:mask="{ mask: '#### #### #### ####' }"
+	/>
+</div>
+```
+
+Masks are for _formatting_; they don't validate. Keep `errors` in charge of
+telling the user a complete-but-wrong value is invalid.
+
+### Type, keyboard & autofill hints
+
+`type` forwards any native input type (default `text`): use `email`, `url`,
+`tel`, `search`, `password`. Don't use `type="number"` or `type="date"` — those
+are `BbNumberInput`'s and `BbDatePickerInput`'s jobs.
+
+- `autocomplete` passes through to the browser (`"email"`, `"current-password"`,
+  `"one-time-code"`, `"off"`…) — set it on every field in auth and checkout
+  flows.
+- `inputMode` steers mobile keyboards independently of `type` (e.g.
+  `inputMode="numeric"` on a masked code field that must stay `type="text"`).
+- `autofocus` focuses the field on mount; use at most one per view.
+
+**An OTP field: text type, numeric keyboard, masked**
+
+```vue
+<div class="max-w-sm">
+	<BbTextInput
+		v-model="state.otp"
+		label="Verification code"
+		autocomplete="one-time-code"
+		inputMode="numeric"
+		:mask="{ mask: '### ###' }"
+		placeholder="123 456"
+	/>
+</div>
+```
+
+### Events & v-model
+
+- `update:modelValue` — every value change; `string`, or `null` when emptied
+  (with a mask: the unmasked/masked string per `emitMasked`).
+- `focus` / `blur` — forwarded `FocusEvent`s; they also drive the hint's
+  show-on-focus behavior.
+- `input` — every keystroke (raw DOM event); `change` — on commit
+  (blur/Enter), the right hook for expensive side effects.
+- `keydown`, `keyup`, `click`, `mousedown`, `mouseup`, `paste`,
+  `compositionstart`, `compositionend` — forwarded as-is; `paste` is the hook
+  for normalizing pasted content, the composition pair for IME-aware logic.
+
+### Disabled & readonly
+
+`disabled` greys the field and blocks all interaction (also sets
+`aria-disabled`); `readonly` keeps the value visible, focusable and copyable
+but not editable (`aria-readonly`). Prefer `readonly` for derived or
+provisioned values — screen-reader and keyboard users can still reach them.
+
+**Disabled vs readonly**
+
+```vue
+<div class="grid max-w-sm gap-4">
+	<BbTextInput :model-value="'Business (annual)'" label="Plan (managed by billing)" disabled />
+	<BbTextInput :model-value="'eu-west-1'" label="Region" readonly hint="Set at workspace creation." persistentHint />
+</div>
+```
+
+### Density & layout
+
+`compact` reduces the control height — apply it per view, not per field, so
+density stays consistent.
+
+The API also exposes `direction` (horizontal/pattern layouts), `reverse` and
+`labelPosition`. `direction` works whenever the **resolved** label mode is
+`'outside'` — which is the config default, so it works out of the box. With
+`labelMode="floating"` or `"inside"` (via prop or
+`config.defaultInputLabelMode`) the label is embedded in the field, so those
+modes force the vertical layout and ignore `direction`. The same rule applies
+to `BbNumberInput`, `BbSelect` and `BbDatePickerInput`; `BbTextarea` has no
+label mode at all, so it always honors `direction`.
+
+**Horizontal row via direction (outside label)**
+
+```vue
+<template>
+	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div>
+			<p class="text-sm font-medium">Billing contact</p>
+			<p class="text-xs text-gray-500">
+				Outside labels only — horizontal rows keep dense forms scannable.
+			</p>
+		</div>
+		<BbTextInput
+			v-model="fullName"
+			compact
+			direction="horizontal"
+			label="Full name"
+			name="full-name"
+			placeholder="Ada Lovelace"
+		/>
+		<BbTextInput
+			v-model="company"
+			compact
+			direction="xx xxxxxx"
+			label="Company"
+			name="company"
+			placeholder="Bitboss"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTextInput } from 'bitboss-ui';
+
+const fullName = ref<string | null>('Ada Lovelace');
+const company = ref<string | null>('Bitboss');
+</script>
+```
+
+`direction="horizontal"` splits label and field 50/50; a pattern string like
+`"xx xxxxxx"` sets proportional column widths (here 25% label / 75% field).
+
+**Compact density for dense panels**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<p class="text-sm font-medium">Merino Tee — Black / M</p>
+			<p class="text-xs text-gray-500">Product identifiers · compact density</p>
+		</div>
+		<BbTextInput
+			v-model="sku"
+			compact
+			label="SKU"
+			name="sku"
+			placeholder="TSH-BLK-M"
+		/>
+		<BbTextInput
+			v-model="barcode"
+			compact
+			label="Barcode"
+			name="barcode"
+			placeholder="0 12345 67890 5"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTextInput } from 'bitboss-ui';
+
+const sku = ref<string | null>('TSH-BLK-M');
+const barcode = ref<string | null>('0 12345 67890 5');
+</script>
+```
+
+### Global config & platforms
+
+- `config.defaultInputLabelMode` — project-wide default for `labelMode`
+  (also read by `BbNumberInput`, `BbSelect` and `BbDatePickerInput`).
+- The component is a plain controlled `<input>`: SSR-safe in Nuxt, no teleports
+  or portals, nothing to hydrate carefully.
+- In Inertia apps, bind server-side validation straight into the field:
+
+```vue
+<!-- Inertia: useForm drives value and errors -->
+<BbTextInput
+	v-model="form.email"
+	label="Email"
+	type="email"
+	autocomplete="email"
+	:errors="form.errors.email"
+	:has-errors="!!form.errors.email"
+/>
+```
+
+### A composed form
+
+The input family shares one chrome, so fields line up cleanly when combined.
+This invoice form pairs `BbTextInput` with `BbTextarea`, `BbNumberInput` and
+`BbDatePickerInput`, and wires a real validation flow: required checks on
+submit, format checks on blur, errors cleared as the user fixes them.
+
+**Invoice form with validation**
+
+```vue
+<template>
+	<form
+		class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4"
+		novalidate
+		@submit.prevent="submit"
+	>
+		<div>
+			<p class="text-sm font-medium">
+				Invoice for {{ customer || 'a new client' }}
+			</p>
+			<p class="text-xs text-gray-500">
+				Draft INV-2048 · validate on blur / submit, clear as they type
+			</p>
+		</div>
+		<BbTextInput
+			v-model="customer"
+			clearable
+			compact
+			:errors="errors.customer"
+			label="Bill to"
+			name="customer"
+			placeholder="Company or person"
+			prepend:icon="lucide:user"
+			required
+			@input="errors.customer = ''"
+		/>
+		<BbTextInput
+			v-model="email"
+			autocomplete="email"
+			compact
+			:errors="errors.email"
+			label="Billing email"
+			name="email"
+			placeholder="billing@company.com"
+			prepend:icon="lucide:mail"
+			required
+			type="email"
+			@blur="validateEmail"
+			@input="errors.email = ''"
+		/>
+		<div class="grid gap-3 sm:grid-cols-2">
+			<BbDatePickerInput
+				v-model="servicePeriod"
+				compact
+				label="Service period"
+				placeholder="Start → end"
+				prepend:icon="lucide:calendar"
+				range
+			/>
+			<BbDatePickerInput
+				v-model="dueDate"
+				compact
+				:errors="errors.dueDate"
+				label="Due date"
+				:min="today"
+				placeholder="YYYY-MM-DD"
+				prepend:icon="lucide:calendar"
+				@update:model-value="errors.dueDate = ''"
+			/>
+		</div>
+		<div class="grid gap-3 sm:grid-cols-2">
+			<BbNumberInput
+				v-model="quantity"
+				compact
+				label="Quantity"
+				:max="999"
+				:min="1"
+			/>
+			<BbNumberInput
+				v-model="unitPrice"
+				compact
+				label="Unit price"
+				:max-precision="2"
+				:min="0"
+			>
+				<template #prefix>$</template>
+				<template #suffix>USD</template>
+			</BbNumberInput>
+		</div>
+		<BbTextarea
+			v-model="notes"
+			auto-grow
+			compact
+			hint="Shown at the bottom of the invoice."
+			label="Notes"
+			persistent-hint
+			placeholder="Payment terms, PO number…"
+		/>
+		<div
+			class="flex flex-wrap items-center justify-between gap-2 border-t pt-3"
+		>
+			<p class="text-sm font-medium">
+				{{
+					queued ? `Queued — ${formattedTotal}` : `Total due: ${formattedTotal}`
+				}}
+			</p>
+			<BbButton variant="primary" @click="submit">Queue invoice</BbButton>
+		</div>
+	</form>
+</template>
+<script setup lang="ts">
+import { ref, reactive, computed } from 'vue';
+import dayjs from 'dayjs';
+import {
+	BbButton,
+	BbTextInput,
+	BbTextarea,
+	BbNumberInput,
+	BbDatePickerInput,
+} from 'bitboss-ui';
+
+const customer = ref<string | null>(null);
+const email = ref<string | null>(null);
+const servicePeriod = ref<string[]>([]);
+const dueDate = ref<string | null>(null);
+const quantity = ref<number>(1);
+const unitPrice = ref<number>(1200);
+const notes = ref<string | null>(null);
+const queued = ref(false);
+
+const errors = reactive({ customer: '', email: '', dueDate: '' });
+
+const today = dayjs().format('YYYY-MM-DD');
+
+const isValidEmail = (value: string) =>
+	/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+
+// Format checks run on blur; required checks only on submit — never while
+// the user is still typing a first attempt.
+const validateEmail = () => {
+	if (email.value && !isValidEmail(email.value)) {
+		errors.email = 'Enter a valid email address';
+	}
+};
+
+const submit = () => {
+	queued.value = false;
+	errors.customer = customer.value ? '' : 'Tell us who to bill';
+	errors.email = email.value
+		? isValidEmail(email.value)
+			? ''
+			: 'Enter a valid email address'
+		: 'A billing email is required';
+	errors.dueDate = dueDate.value ? '' : 'Pick a due date';
+	if (!errors.customer && !errors.email && !errors.dueDate) {
+		queued.value = true;
 	}
-}
+};
+
+const formattedTotal = computed(() =>
+	new Intl.NumberFormat('en-US', {
+		style: 'currency',
+		currency: 'USD',
+	}).format((quantity.value ?? 0) * (unitPrice.value ?? 0))
+);
+</script>
 ```
+
+### Works well with
+
+- `BbButton` — submit actions; an async `@click` handler gets automatic
+  loading state while the save is in flight.
+- `BbSelect` — when a free-text field grows a known option set, switch
+  component instead of validating strings.
+- `useToast` — confirm a successful save after the form clears.
+- `BbTooltip` — attach extra context to the label via the `label` slot rather
+  than cramming it into `description`.
+- `BbTextarea` / `BbNumberInput` / `BbDatePickerInput` — same chrome, same
+  messaging surface; mix freely in one form.
+
+### Gotchas & anti-patterns
+
+- An emptied field emits `null`, not `''` — write `value ?? ''` when feeding
+  APIs that require strings.
+- `direction` is ignored under `labelMode="floating"`/`"inside"` — those modes
+  embed the label in the field and force the vertical layout (see _Density &
+  layout_).
+- `loading` does not lock the field — it's a status light, not a guard.
+- Don't rebuild the clear button in an `append` slot; `clearable` already
+  handles show/hide, clearing and refocusing.
+- Don't put buttons in `prefix`/`suffix` — clicks there focus the input; use
+  `append-outer`/`prepend-outer` for interactive neighbors.
+- Don't validate _while_ the user types their first attempt; validate on
+  `blur` or submit, then clear errors on `input` (see the invoice example).
+- Masked fields emit the **unmasked** value by default — don't strip
+  formatting server-side that was never sent.
+
+### Accessibility
+
+- Always provide `label`. To hide it visually, use `hideLabel` (keeps the
+  accessible name) rather than omitting it.
+- `description` and `hint` are wired to the input through `aria-describedby`;
+  `errors` render in an `aria-live="polite"` region so they're announced when
+  they appear — keep messages meaningful, not decorative.
+- `hasErrors` (or a non-empty `errors`) sets `aria-invalid` on the native
+  input; `disabled`/`readonly` set `aria-disabled`/`aria-readonly`.
+- Prefer real, always-enabled fields; when you must disable one, explain why
+  nearby.
+- Icon affixes are decorative and hidden from the accessible name — if an icon
+  carries meaning (e.g. "verified"), also say it in `hint` or `description`.
+
+## v-model
+
+- `v-model` — type: `string \| null`
+
+## 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. |
+| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
+| `compact` | `boolean \| undefined` |  |  | Displays the component in a compact version. |
+| `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. |
+| `emitMasked` | `boolean \| undefined` |  |  | Emits the masked value of the input. |
+| `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. |
+| `inputMode` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "none" \| "numeric" \| "decimal" \| undefined` |  |  | The inputmode of the input. |
+| `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
+| `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. |
+| `mask` | `MaskInputOptions \| undefined` |  |  | The mask to be applied to the input. Please visit https://beholdr.github.io/maska/v3 for syntax examples. |
+| `modelValue` | `string \| null` |  | yes | Used by v-model. |
+| `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. |
+| `type` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "password" \| undefined` |  |  | Type of the input. Restricted to the textual input types this component supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates. |
+| `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
+
+- `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`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `keyup` — `(event: "keyup", event: KeyboardEvent): 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 \| null): void`
+
+## Slots
+
+- `append` — scope: `object` — Content rendered after the text input, at the end of the inner container.
+- `append-outer` — scope: `object` — Content rendered after the entire text input control, outside the input chrome.
+- `label` — scope: `BbTextInputLabelSlotProps` — Replaces the default label text rendered above the input.
+- `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the typed text.
+- `prepend` — scope: `object` — Content rendered before the text input, at the start of the inner container.
+- `prepend-outer` — scope: `object` — Content rendered before the entire text input control, outside the input chrome.
+- `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the typed text.
+
+## 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 \| 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
+
+- [BbTextarea](./BbTextarea.md) — Captures multi-line text values.
+- [BbNumberInput](./BbNumberInput.md) — Captures and validates numeric form values, emits a number value.
+- [BbColorInput](./BbColorInput.md) — Captures color values through input controls.
+- [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.