bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/ai/source/BbTextarea.md

@@ -6,91 +6,166 @@
 
 ```vue
 <template>
-	<BaseInputContainer
+	<CommonField
 		:id="id"
 		class="bb-textarea"
 		:clearable="isClearable"
 		:compact="compact"
 		:description="description"
-		:direction="direction"
 		:disabled="disabled"
-		:errors="errors"
+		:errors="fieldErrors"
 		:has-errors="hasErrors"
 		:has-value="hasValue"
-		:has-warning="hasWarning"
+		:has-warnings="hasWarnings"
 		:hide-label="hideLabel"
 		:hint="hint"
 		:label="label"
 		:label-mode="resolvedLabelMode"
 		:label-position="labelPosition"
+		:layout="layout"
 		:loading="loading"
-		:model-value="modelValue"
 		:name="name"
+		:passthrough="passthrough"
 		:readonly="readonly"
 		:reverse="reverse"
+		:show-asterisk="showAsterisk"
 		:show-hint="showHint"
 		:warnings="warnings"
+		v-bind="passthrough.forwardAttrs"
 	>
 		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, hasWarning, ariaDescribedby }">
-			<BaseTextarea
-				:id="id"
+		<template v-if="$slots.description" #description="data"
+			><slot name="description" v-bind="data"></slot
+		></template>
+		<template
+			#input="{
+				id: fieldId,
+				hasErrors: fieldHasErrors,
+				hasWarnings: fieldHasWarnings,
+				ariaDescribedby,
+				ariaLabelledby,
+			}"
+		>
+			<CommonFieldInput
 				:append:icon="props['append:icon']"
-				:aria-describedby="ariaDescribedby"
-				:auto-grow="autoGrow"
-				:autocomplete="autocomplete"
-				:autofocus="autofocus"
+				class="bb-textarea__field"
+				:class="{
+					'bb-textarea__field--auto-grow': autoGrow,
+				}"
 				:clearable="clearable"
 				:compact="compact"
 				:disabled="disabled"
-				:has-errors="hasErrors"
-				:has-warning="hasWarning"
+				:has-errors="fieldHasErrors"
+				:has-value="hasValue"
+				:has-warnings="fieldHasWarnings"
 				:loading="loading"
-				:model-value="modelValue"
-				:name="name"
-				:placeholder="placeholder"
+				:passthrough="passthrough"
 				:prepend:icon="props['prepend:icon']"
 				:readonly="readonly"
-				:required="required"
-				:rows="rows"
-				v-bind="eventListeners"
+				:reserve-append-space="clearable"
+				:variant="variant"
+				@click:clear="emit('update:modelValue', emptyValue())"
 			>
-				<template #append-outer><slot name="append-outer" /></template>
-				<template #append><slot name="append" /></template>
+				<template #prepend:outer><slot name="prepend:outer"></slot></template>
 				<template #prepend><slot name="prepend" /></template>
-				<template #prepend-outer><slot name="prepend-outer" /></template>
-				<template #prefix="data"><slot name="prefix" v-bind="data" /></template>
-				<template #suffix="data"><slot name="suffix" v-bind="data" /></template>
-			</BaseTextarea>
+				<template v-if="$slots.prefix" #prefix><slot name="prefix" /></template>
+				<BbSmoothHeight :disabled="!autoGrow" tag="span">
+					<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer listener runs after ours (PASSTHROUGH.md T17) -->
+					<textarea
+						:id="fieldId"
+						ref="textarea"
+						:aria-describedby="ariaDescribedby"
+						:aria-disabled="disabled || undefined"
+						:aria-invalid="fieldHasErrors || undefined"
+						:aria-labelledby="ariaLabelledby"
+						:aria-readonly="readonly || undefined"
+						:autocomplete="autocomplete"
+						:autofocus="autofocus"
+						class="bb-textarea__input scrollbar-border"
+						:disabled="disabled"
+						:name="name"
+						:placeholder="placeholder"
+						:readonly="readonly"
+						:required="fieldRequired"
+						:rows="rows"
+						:value="modelValueWithDefault"
+						@input="onInput"
+						@keydown="onKeydown"
+						v-bind="mergeProps(passthrough.controlAttrs, inputBindings)"
+					></textarea>
+					<!-- eslint-enable vue/attributes-order -->
+				</BbSmoothHeight>
+				<template #append><slot name="append" /></template>
+				<template v-if="$slots.suffix" #suffix><slot name="suffix" /></template>
+				<template #append:outer><slot name="append:outer"></slot></template>
+			</CommonFieldInput>
 		</template>
-	</BaseInputContainer>
+	</CommonField>
 </template>
 
 <script setup lang="ts">
-import { ref, computed } from 'vue';
-import BaseInputContainer from '../BbBaseInputContainer/BbBaseInputContainer.vue';
-import BaseTextarea from '../BbBaseTextarea/BbBaseTextarea.vue';
-import { config } from 'virtual:bitboss-ui/config';
+import { removedPropsFor } from '@/deprecation/removedProps';
+import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
+import {
+	computed,
+	mergeProps,
+	nextTick,
+	onMounted,
+	ref,
+	useAttrs,
+	watch,
+} from 'vue';
+import { useResizeObserver } from '@vueuse/core';
+import CommonField from '../CommonField/CommonField.vue';
+import CommonFieldInput from '../CommonFieldInput/CommonFieldInput.vue';
+import BbSmoothHeight from '../BbSmoothHeight/BbSmoothHeight.vue';
+import { useConfig } from '@/composables/useConfig';
+import { useFormBinding } from '@/composables/useFormBinding';
+import {
+	formControlPtActive,
+	TEXT_CONTROL_NATIVE_ATTRS,
+	usePassthrough,
+} from '@/composables/usePassthrough';
 import { isNotEmpty } from '@/utilities/functions/isNotEmpty';
-import type {
-	BbTextareaProps,
-	BbTextareaEvents,
-	BbTextareaSlots,
+import {
+	BB_TEXTAREA_PT,
+	type BbTextareaProps,
+	type BbTextareaEvents,
+	type BbTextareaSlots,
 } from './types';
-export type { BbTextareaProps, BbTextareaEvents, BbTextareaSlots };
 
-const props = defineProps<BbTextareaProps>();
-
-const emit = defineEmits<BbTextareaEvents>();
+defineOptions({ inheritAttrs: false });
+const declaredProps = defineProps<BbTextareaProps>();
 
+const declaredEmit = defineEmits<BbTextareaEvents>();
 defineSlots<BbTextareaSlots>();
+// Inside a BbForm the field joins it (Q54.4): `props` / `emit` are bound.
+const {
+	props,
+	emit,
+	showAsterisk,
+	errors: fieldErrors,
+	required: fieldRequired,
+} = useFormBinding(declaredProps, declaredEmit, {
+	componentName: 'BbTextarea',
+	identifierFallback: () => declaredProps.label,
+	leaveOn: 'blur',
+});
+if (process.env.NODE_ENV !== 'production')
+	warnRemovedAttrs('BbTextarea', removedPropsFor('BbTextarea'));
+const config = useConfig();
+
+/**
+ * What the field emits once emptied (typed empty or cleared): `null` by
+ * default, or `''` through `formControls.textareaNullValue`. Read per emit.
+ */
+const emptyValue = () => config.formControls?.textareaNullValue ?? null;
+export type { BbTextareaProps, BbTextareaEvents, BbTextareaSlots };
 
 const active = ref(false);
 const showHint = computed(() => props.persistentHint || active.value);
-const isClearable = computed(
-	() => Boolean(props.clearable) && isNotEmpty(props.modelValue)
-);
 const hasValue = computed(() => isNotEmpty(props.modelValue));
+const isClearable = computed(() => Boolean(props.clearable) && hasValue.value);
 // Same label-mode resolution as BbTextInput/BbNumberInput — honor the prop, else
 // fall back to the library default.
 const resolvedLabelMode = computed(
@@ -98,8 +173,97 @@ const resolvedLabelMode = computed(
 );
 
 /**
- * These events are just propagated
+ * Passthrough (plans/passthrough/BbTextarea.md). The frame binds `root` /
+ * `label` / `description` / `message` / `hint`, the box row binds `box` /
+ * `icon` / `spinner` / `prefix` / `suffix` / `clear`, and `input` lands on the
+ * native textarea below. `hasValue` follows this control's own notion of a
+ * value.
  */
+const passthrough = usePassthrough({
+	component: 'BbTextarea',
+	attrs: useAttrs(),
+	controlAttrs: TEXT_CONTROL_NATIVE_ATTRS,
+	props,
+	parts: BB_TEXTAREA_PT.parts,
+	states: BB_TEXTAREA_PT.states,
+	active: formControlPtActive(props, () => hasValue.value),
+});
+
+// `rows` + `auto-grow` are compatible: `rows` seeds the starting/minimum height
+// (a floor the field never shrinks below) and auto-grow expands from there. See
+// computeTextareaHeight below.
+
+const textarea = ref<HTMLTextAreaElement | null>(null);
+
+// Allow modelvalue to be reset to null
+const modelValueWithDefault = computed(() => props.modelValue ?? '');
+onMounted(() => {
+	if (props.autoGrow) {
+		computeTextareaHeight();
+	}
+});
+watch(
+	() => props.modelValue,
+	() => {
+		if (props.autoGrow) {
+			nextTick(computeTextareaHeight);
+		}
+	}
+);
+watch(
+	() => props.autoGrow,
+	(isAutoGrow) => {
+		if (isAutoGrow) {
+			nextTick(computeTextareaHeight);
+			return;
+		}
+
+		resetTextareaHeight();
+	}
+);
+
+// Re-measure only for EXTERNALLY caused resizes (container width change,
+// zoom, font load). computeTextareaHeight itself resizes the element, so
+// without the size check every keystroke's measure retriggered the observer
+// into a second, redundant reset-and-measure pass.
+useResizeObserver(textarea, () => {
+	if (!props.autoGrow) return;
+	if (lastMeasuredSize && textarea.value) {
+		const rect = textarea.value.getBoundingClientRect();
+		if (
+			Math.abs(rect.width - lastMeasuredSize.width) < 0.5 &&
+			Math.abs(rect.height - lastMeasuredSize.height) < 0.5
+		) {
+			return;
+		}
+	}
+	computeTextareaHeight();
+});
+
+// `input` and `keydown` stop at the textarea (an Enter must not reach an
+// ancestor's key handler); consumers receive only the component events.
+// `input` is emitted BEFORE `update:modelValue`.
+function onInput(event: Event): void {
+	event.stopPropagation();
+	if (event.target instanceof HTMLTextAreaElement) {
+		const value = event.target.value;
+		const normalizedValue = value === '' ? emptyValue() : value;
+		emit('input', event);
+		emit('update:modelValue', normalizedValue);
+		if (props.autoGrow) {
+			computeTextareaHeight();
+		}
+	}
+}
+function onKeydown(event: KeyboardEvent): void {
+	event.stopPropagation();
+	if (event.target instanceof HTMLTextAreaElement) {
+		emit('keydown', event);
+	}
+}
+
+// Native DOM events are re-emitted as component events; `focus` / `blur` also
+// drive the hint. `input` and `keydown` are bound separately above.
 const eventListeners = {
 	onBlur: (event: FocusEvent) => {
 		active.value = false;
@@ -111,8 +275,6 @@ const eventListeners = {
 		active.value = true;
 		emit('focus', event);
 	},
-	onInput: (event: Event) => emit('input', event),
-	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
 	onKeyup: (event: KeyboardEvent) => emit('keyup', event),
 	onMousedown: (event: MouseEvent) => emit('mousedown', event),
 	onMouseup: (event: MouseEvent) => emit('mouseup', event),
@@ -120,9 +282,50 @@ const eventListeners = {
 	onCompositionstart: (event: CompositionEvent) =>
 		emit('compositionstart', event),
 	onCompositionend: (event: CompositionEvent) => emit('compositionend', event),
-	'onUpdate:modelValue': (value: string | null) =>
-		emit('update:modelValue', value),
 };
+
+/**
+ * The native control's whole `v-bind`: the listeners, then `pt:input` LAST —
+ * one object, because two `v-bind`s on one element are a duplicate attribute.
+ * `mergeProps` keeps the contract: a class appends, an attribute wins, a
+ * listener concatenates after ours.
+ */
+const inputBindings = computed(() =>
+	passthrough.input
+		? mergeProps(eventListeners, passthrough.input)
+		: eventListeners
+);
+
+/**
+ * The size this component last set/observed on the textarea, recorded after
+ * each measure. The ResizeObserver above compares against it so the resize
+ * event caused by our own height write doesn't trigger a second measure.
+ * Recorded via getBoundingClientRect — the same fractional CSS-pixel basis
+ * the comparison reads — and cleared when auto-grow releases the height.
+ */
+let lastMeasuredSize: { width: number; height: number } | null = null;
+
+/*
+Reset height then apply scroll height so the field tracks its content. With
+`rows` set we reset to `auto` (not `0`) so the browser's rows-based height acts
+as the minimum floor — the field grows past it but never shrinks below it.
+Without `rows` we reset to `0` and the auto-grow `min-height` in index.css is
+the floor: one line, BbTextInput's height.
+*/
+function computeTextareaHeight() {
+	if (!textarea.value) return;
+	textarea.value.style.height = props.rows ? 'auto' : '0px';
+
+	textarea.value.style.height = `${textarea.value.scrollHeight}px`;
+	const rect = textarea.value.getBoundingClientRect();
+	lastMeasuredSize = { width: rect.width, height: rect.height };
+}
+
+function resetTextareaHeight() {
+	if (!textarea.value) return;
+	textarea.value.style.removeProperty('height');
+	lastMeasuredSize = null;
+}
 </script>
 
 <style lang="postcss">
@@ -133,15 +336,56 @@ const eventListeners = {
 ## Types
 
 ```ts
+import type { InputVariantType } from '@/types/InputVariant';
 import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { InputDirection } from '@/types/InputDirection';
+import type { FieldLayout } from '@/types/FieldLayout';
 import type { IconType } from '@/types/Icon';
-import type {
-	BaseTextareaEvents,
-	BaseTextareaSlots,
-} from '../BbBaseTextarea/types';
+import {
+	FORM_CONTROL_PT_STATES,
+	TEXT_CONTROL_PT_PARTS,
+	type FormControlPtState,
+	type PtMap,
+	type PtValue,
+	type TextControlPtPart,
+} from '@/types/passthrough';
+import type { FormFieldProps } from '@/composables/useFormBinding';
 
+/**
+ * Passthrough parts of `BbTextarea` (plans/passthrough/BbTextarea.md) — the form-control
+ * family vocabulary: `root` (the container), `label`, `description`, `message`, `hint`
+ * (the errors / warnings region), `box` (the bordered box), `input` (the
+ * native control), `icon` (the prepend + append content icons — a broadcast;
+ * the clear button and the error / warning glyphs are chrome), `spinner`
+ * (the spinner shown while `loading`),
+ * `prefix`, `suffix`.
+ */
+export type BbTextareaPtPart = TextControlPtPart;
+/** Passthrough states of `BbTextarea`: the family's six, true while the matching `--` modifier is on. */
+export type BbTextareaPtState = FormControlPtState;
+/** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
+export const BB_TEXTAREA_PT = {
+	parts: TEXT_CONTROL_PT_PARTS,
+	states: FORM_CONTROL_PT_STATES,
+} as const satisfies {
+	parts: readonly BbTextareaPtPart[];
+	states: readonly BbTextareaPtState[];
+};
+
+// The passthrough props are a mapped type written INLINE with this
+// component's own unions (Vue's SFC type resolver does not substitute a
+// generic alias's type parameters — plans/PASSTHROUGH.md T20); the test
+// asserts the resolved prop names.
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
 export type BbTextareaProps = {
+	[K in
+		| `pt:${BbTextareaPtPart}`
+		| `pt:${BbTextareaPtPart}:${BbTextareaPtState}`]?: PtValue;
+} & {
+	/**
+	 * Passthrough, object form: `{ box: '…', 'box:errors': '…' }` — the same
+	 * keys as the `pt:*` attributes without the prefix. See the `pt:<part>` row.
+	 */
+	pt?: PtMap<BbTextareaPtPart, BbTextareaPtState>;
 	/**
 	 * Name of the icon to be added at the end of the input.
 	 */
@@ -159,7 +403,8 @@ export type BbTextareaProps = {
 	autofocus?: InputHTMLAttributes['autofocus'];
 
 	/**
-	 * Expands the textarea to match its content.
+	 * Expands the textarea to match its content. Empty, it is one BbTextInput
+	 * tall (text on the same line); it never shrinks below that, or below `rows`.
 	 */
 	autoGrow?: boolean;
 
@@ -169,10 +414,32 @@ export type BbTextareaProps = {
 	clearable?: boolean;
 
 	/**
-	 * Sets the component in a compact state.
+	 * Compact density. Swaps `--bb-input-h`, `--bb-input-py` and
+	 * `--bb-label-spacing-y` for their `-compact` twins on the field, so a
+	 * `--bb-input-h` you set on the component is ignored while `compact` is on:
+	 * size a compact field with `--bb-input-h-compact` (and
+	 * `--bb-input-py-compact`) instead.
 	 */
 	compact?: boolean;
 
+	/**
+	 * Visual variant of the field box — the same names and tokens as the
+	 * `BbButton` variants. Colours only: height, padding and border width are
+	 * identical across variants, so a form never reflows when one changes.
+	 * `'ghost'` has no border in any state (errors and warnings show through
+	 * the icon and the messages); every variant keeps the focus ring.
+	 * Register extra names with the plugin's `inputVariants` option.
+	 *
+	 * `'none'` is a blank starting point: the field keeps its structure and
+	 * behaviour but takes no look, so your own classes don't fight a built-in
+	 * one. You then own hover, focus, disabled and the error / warning states.
+	 * Fine for a one-off; keep inline styling short, and register a real
+	 * variant (`inputVariants`) when the look recurs.
+	 *
+	 * @defaultValue `'outline'`
+	 */
+	variant?: InputVariantType;
+
 	/**
 	 * 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
@@ -181,10 +448,12 @@ export type BbTextareaProps = {
 	description?: string;
 
 	/**
-	 * Direction of the layout of the component. Can either be a predefined value or a
-	 * pattern separated by a space like `xx xxxxx`.
+	 * How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50),
+	 * `'auto'`, `'label-fill'` (the label takes the free space, the input keeps
+	 * its size), `'input-fill'` (the other way round), or a two-word ratio
+	 * pattern like `'xx xxxxx'`.
 	 */
-	direction?: InputDirection;
+	layout?: FieldLayout;
 
 	/**
 	 * Disables the component.
@@ -219,7 +488,7 @@ export type BbTextareaProps = {
 	 * Define if the component should be in a warning state.
 	 * Same chrome as errors with `--bb-warn`; errors take priority.
 	 */
-	hasWarning?: boolean;
+	hasWarnings?: boolean;
 
 	/**
 	 * Visually hides the label of the input while maintaining accessibility.
@@ -232,7 +501,8 @@ export type BbTextareaProps = {
 	hint?: string;
 
 	/**
-	 * The identifier of the component.
+	 * The `id` of the native control; the label's `for` and the description
+	 * and message ids derive from it. Generated when omitted.
 	 */
 	id?: HTMLAttributes['id'];
 
@@ -260,7 +530,7 @@ export type BbTextareaProps = {
 	/**
 	 * Used by v-model.
 	 */
-	modelValue: string | null;
+	modelValue?: string | null;
 
 	/**
 	 * Defines the name of the input.
@@ -303,10 +573,75 @@ export type BbTextareaProps = {
 	 * Sets the number of visible text lines for the control.
 	 */
 	rows?: string | number;
+} & FormFieldProps<string | null>;
+
+export type BbTextareaEvents = {
+	/**
+	 * Emitted when the native textarea loses focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'blur', event: FocusEvent): void;
+	/**
+	 * Emitted when the native textarea fires a change event.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'change', event: Event): void;
+	/**
+	 * Emitted when the textarea receives a click interaction.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'click', event: MouseEvent): void;
+	/**
+	 * Emitted when the native textarea gains focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted on native input events from the textarea.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'input', event: Event): void;
+	/**
+	 * Emitted for keyboard interaction on the textarea.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/**
+	 * Emitted for keyboard interaction on the textarea.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keyup', event: KeyboardEvent): void;
+	/**
+	 * Emitted when a pointing device button is pressed over the textarea.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mousedown', event: MouseEvent): void;
+	/**
+	 * Emitted when a pointing device button is released over the textarea.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mouseup', event: MouseEvent): void;
+	/** Native clipboard paste. Forwards the original DOM `ClipboardEvent`. */
+	(e: 'paste', event: ClipboardEvent): void;
+	/** An IME composition started. Forwards the original DOM `CompositionEvent`. */
+	(e: 'compositionstart', event: CompositionEvent): void;
+	/** An IME composition ended. Forwards the original DOM `CompositionEvent`. */
+	(e: 'compositionend', event: CompositionEvent): void;
+	/**
+	 * Emitted when the value changes. Carries the new text or `null` when cleared.
+	 */
+	(e: 'update:modelValue', value: string | null): void;
 };
 
-/** Re-export for consumers importing events type from BbTextarea. */
-export type BbTextareaEvents = BaseTextareaEvents;
+/** Props exposed by the `description` slot. */
+export type BbTextareaDescriptionSlotProps = {
+	/** The `description` prop value (empty when only the slot is provided). */
+	text: string;
+	/** Whether the field is in an error state. */
+	hasErrors: boolean;
+	/** Whether the field is in a warning state (suppressed when errors win). */
+	hasWarnings: boolean;
+};
 
 /** Props exposed by the `label` slot. */
 export type BbTextareaLabelSlotProps = {
@@ -315,14 +650,43 @@ export type BbTextareaLabelSlotProps = {
 	/** Whether the textarea is in an error state. */
 	hasErrors: boolean;
 	/** Whether the textarea is in a warning state (suppressed when errors win). */
-	hasWarning: boolean;
+	hasWarnings: boolean;
 };
 
-export type BbTextareaSlots = BaseTextareaSlots & {
+export type BbTextareaSlots = {
+	/**
+	 * Content rendered before the entire textarea control, outside the input chrome.
+	 */
+	'prepend:outer'?: (props: Record<string, never>) => any;
+	/**
+	 * Content rendered before the textarea, at the start of the inner container.
+	 */
+	prepend?: (props: Record<string, never>) => any;
+	/**
+	 * Content rendered after the textarea, at the end of the inner container.
+	 */
+	append?: (props: Record<string, never>) => any;
+	/**
+	 * Content rendered after the entire textarea control, outside the input chrome.
+	 */
+	'append:outer'?: (props: Record<string, never>) => any;
+	/**
+	 * Inline content rendered at the start of the textarea field area, before the text.
+	 */
+	prefix?: (props: Record<string, never>) => any;
+	/**
+	 * Inline content rendered at the end of the textarea field area, after the text.
+	 */
+	suffix?: (props: Record<string, never>) => any;
 	/**
 	 * Replaces the default label text rendered above the textarea.
 	 */
 	label?: (props: BbTextareaLabelSlotProps) => any;
+	/**
+	 * Replaces the description text. Provided alone (no `description` prop) it still
+	 * renders the description region and wires it into `aria-describedby`.
+	 */
+	description?: (props: BbTextareaDescriptionSlotProps) => any;
 };
 ```
 
@@ -330,8 +694,129 @@ export type BbTextareaSlots = BaseTextareaSlots & {
 
 ```css
 .bb-textarea {
-	.bb-base-textarea {
+	/* The box row (`.bb-field-input`) carries the textarea's tokens and scopes
+	   the rules below, so the compact override can compound with the row's own
+	   `--compact` modifier on the same node. */
+	&__field {
+		--min-height: 150px; /* height of the box when the consumer gives no `rows` */
+		/* The first text row's height: the tallest of one line plus its vertical
+		   padding, the input height less its borders, and the icon box. */
+		--inner-h: max(
+			calc(var(--bb-leading) + var(--bb-input-py) * 2),
+			calc(var(--bb-input-h) - 2px),
+			var(--bb-input-icon)
+		);
+		/* Top offset that centres the icons, affixes, spinner and clear button on
+		   that first row — the shell top-aligns them for a textarea. */
+		--floating-py: calc((var(--inner-h) - var(--bb-input-icon)) / 2);
+
+		&.bb-field-input--compact {
+			--floating-py: calc(
+				(var(--bb-input-h-compact) - var(--bb-input-icon)) / 2
+			);
+		}
+
+		.bb-smooth-height {
+			align-self: center;
+			flex: 1 1 auto;
+			text-align: left;
+		}
+
+		.bb-field-input__box {
+			align-items: flex-start;
+			.bb-clearable-button {
+				margin-top: var(--floating-py);
+			}
+			.bb-spinner {
+				margin-top: var(--floating-py);
+			}
+
+			.bb-error-icon,
+			.bb-warning-icon {
+				margin-top: var(--floating-py);
+			}
+
+			.bb-field-input__prepend-icon,
+			.bb-field-input__append-icon {
+				margin-top: var(--floating-py);
+			}
+
+			.bb-field-input__prefix,
+			.bb-field-input__suffix {
+				align-items: flex-start;
+				padding-top: var(--floating-py);
+			}
+		}
+	}
+
+	&__input {
+		background-color: transparent;
+		outline: none;
+		padding-top: calc((var(--bb-input-h) - (var(--bb-input-fs) * 2.35)) / 2);
+		resize: vertical;
 		width: 100%;
+
+		&:not([rows]) {
+			min-height: var(--min-height);
+		}
+
+		&::-webkit-resizer {
+			background:
+				linear-gradient(
+					135deg,
+					transparent 48%,
+					var(--bb-border) 48% 56%,
+					transparent 56%
+				),
+				linear-gradient(
+					135deg,
+					transparent 62%,
+					var(--bb-border) 62% 70%,
+					transparent 70%
+				);
+			background-position: right 2px bottom 2px;
+			background-repeat: no-repeat;
+			background-size: 12px 12px;
+		}
+
+		&:hover::-webkit-resizer {
+			background:
+				linear-gradient(
+					135deg,
+					transparent 48%,
+					var(--bb-primary) 48% 56%,
+					transparent 56%
+				),
+				linear-gradient(
+					135deg,
+					transparent 62%,
+					var(--bb-primary) 62% 70%,
+					transparent 70%
+				);
+			background-position: right 2px bottom 2px;
+			background-repeat: no-repeat;
+			background-size: 12px 12px;
+		}
+	}
+}
+
+/* Auto-grow starts at BbTextInput's exact height and text position (Q49.11):
+   the textarea fills the shell's inner row (`--bb-input-h` less the borders
+   and the vertical margins), and a known line box lets the padding centre one
+   line in it the way the input centres its text. It grows a line at a time
+   and shrinks back to this floor, never below; `rows` still starts taller. */
+.bb-textarea__field--auto-grow {
+	.bb-textarea__input {
+		--row-h: calc(
+			var(--bb-input-h) - var(--bb-border-w) * 2 - var(--bb-input-py) * 2
+		);
+		line-height: var(--bb-leading);
+		min-height: var(--row-h);
+		padding-bottom: max(0px, calc((var(--row-h) - var(--bb-leading)) / 2));
+		padding-top: max(0px, calc((var(--row-h) - var(--bb-leading)) / 2));
+		resize: none;
+		/* No baseline gap under it inside BbSmoothHeight's inline wrapper. */
+		vertical-align: top;
 	}
 }
 ```