bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbSmoothHeight.md

@@ -1,166 +1,499 @@
 # BbSmoothHeight
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Layout & Utility**
+- Description: Animates height transitions for dynamic content.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbSmoothHeight.md](./source/BbSmoothHeight.md)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbSmoothHeight` is the lowest rung of the disclosure ladder: it does one thing —
+smoothly transition its own height whenever the content inside it changes size.
+It has **no `v-model`, no trigger, no events, and no hide/show semantics**. You
+keep owning the content; it just removes the layout jump.
+
+Reach for it when height changes for reasons other than a simple toggle: content
+swapping in a wizard step, a list gaining or losing rows, an async panel that
+grows once data loads, a validation message appearing under a field.
+
+Escalate when you actually need to _hide_ something:
+
+- A toggle that reveals a body under a header → **`BbAccordion`**
+  (`./BbAccordion.md`) — header + collapsible body, ARIA wired for you.
+- A toggle you drive from your own trigger → **`BbCollapsible`**
+  (`./BbCollapsible.md`) — a show/hide primitive with a boolean model.
+
+Because the content is always mounted and measured, `BbSmoothHeight` does **not**
+add `hidden`/`inert` — everything inside stays in the DOM and focusable. Use a
+collapsible when hidden content must be inert.
+
+### How it works (and why it matters)
+
+The component wraps your content in an inner measuring element, watches that
+element with an observer, and sets an explicit pixel `height` on the outer
+wrapper, which CSS then transitions. Height updates are batched to one per
+animation frame, and a trailing re-measure runs after `transition-duration` so
+the final height always settles exactly on the content's real size. The wrapper
+has `overflow: clip`, so content never spills while animating.
+
+Practical consequences:
+
+- The wrapper always carries a fixed inline height — don't try to stretch it
+  with `height: 100%` from outside or read its height mid-animation.
+- Every animated frame re-runs layout for the wrapped subtree. Cheap for cards
+  and lists; see "When not to use it" for the expensive cases.
+
+### Animating a content reveal
+
+Wrap the region whose height changes. The default `resize` strategy puts a
+`ResizeObserver` on the content box and animates the container to match — you
+toggle content however you like (here a `v-if`), and the height follows. This
+also catches text reflow, images loading, and window-resize-driven wrapping.
+
+**Height follows a v-if reveal**
 
 ```vue
 <template>
-	<component
-		:is="tag"
-		ref="container"
-		class="bb-smooth-height"
-		:style="{ 'transition-duration': props.transitionDuration / 1000 + 's' }"
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
 	>
-		<component :is="tag" ref="content" class="content">
-			<slot />
-		</component>
-	</component>
+		<div class="flex items-start justify-between gap-3">
+			<div class="flex flex-col gap-0.5">
+				<p class="text-sm font-medium">Acme Pro</p>
+				<p class="text-xs text-gray-500">$29 / month · billed annually</p>
+			</div>
+			<BbButton
+				:aria-expanded="showDetails"
+				variant="outline"
+				@click="showDetails = !showDetails"
+			>
+				{{ showDetails ? 'Hide details' : "What's included" }}
+			</BbButton>
+		</div>
+
+		<BbSmoothHeight>
+			<ul
+				v-if="showDetails"
+				class="flex flex-col gap-1.5 text-sm text-gray-500"
+			>
+				<li v-for="perk in perks" :key="perk">{{ perk }}</li>
+			</ul>
+		</BbSmoothHeight>
+	</div>
 </template>
 
 <script setup lang="ts">
-import type { BbSmoothHeightProps, BbSmoothHeightSlots } from './types';
-import { ref, onMounted, onBeforeUnmount } from 'vue';
-
-const props = withDefaults(defineProps<BbSmoothHeightProps>(), {
-	transitionDuration: 200,
-	strategy: 'resize',
-	mutationOptions: () => ({ childList: true }),
-	tag: 'div',
-});
+import { ref } from 'vue';
+import { BbButton, BbSmoothHeight } from 'bitboss-ui';
 
-defineSlots<BbSmoothHeightSlots>();
+const showDetails = ref(false);
 
-const container = ref<HTMLElement | null>(null);
-const content = ref<HTMLElement | null>(null);
-const observer = ref<ResizeObserver | MutationObserver | null>(null);
+const perks = [
+	'Unlimited projects',
+	'Priority support',
+	'Advanced analytics',
+	'Single sign-on (SSO)',
+];
+</script>
+```
 
-let rafId: number | null = null;
-let settleTimeoutId: ReturnType<typeof setTimeout> | null = null;
-let pendingHeight: number | null = null;
+### Swapping sections of different heights
 
-function applyHeight(height: number) {
-	if (container.value) {
-		container.value.style.height = `${height}px`;
-	}
-}
-
-function scheduleUpdate(height: number) {
-	pendingHeight = height;
-
-	if (rafId === null) {
-		rafId = requestAnimationFrame(() => {
-			if (pendingHeight !== null) {
-				applyHeight(pendingHeight);
-				pendingHeight = null;
-			}
-			rafId = null;
-		});
-	}
+The same wrapper handles content **replacement**, not just reveal: when a
+`v-if`/`v-else` swaps one block for another (a wizard step, a form section
+that depends on an earlier choice), the container glides from the old height
+to the new one instead of snapping. Wrap only the region that swaps — the
+controls above and the actions below stay put while the middle animates.
+
+**Form section swap on payment method**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Billing details</p>
+			<p class="text-xs text-gray-500">
+				Acme Studio · next invoice Jul 31, 2026
+			</p>
+		</div>
+
+		<BbRadioGroup
+			v-model="method"
+			compact
+			input-direction="horizontal"
+			item-text="label"
+			item-value="id"
+			:items="methods"
+			legend="Payment method"
+			name="payment-method"
+		/>
+
+		<BbSmoothHeight>
+			<div v-if="method === 'card'" class="flex flex-col gap-3">
+				<BbTextInput
+					v-model="cardNumber"
+					compact
+					label="Card number"
+					placeholder="4242 4242 4242 4242"
+					prepend:icon="lucide:credit-card"
+				/>
+				<div class="grid grid-cols-2 gap-3">
+					<BbTextInput
+						v-model="expiry"
+						compact
+						label="Expiry"
+						placeholder="08/28"
+					/>
+					<BbTextInput v-model="cvc" compact label="CVC" placeholder="123" />
+				</div>
+			</div>
+			<div v-else class="flex flex-col gap-2">
+				<BbTextInput
+					v-model="iban"
+					compact
+					label="IBAN"
+					placeholder="DE89 3704 0044 0532 0130 00"
+				/>
+				<p class="text-xs text-gray-500">
+					We will email a SEPA mandate to finance@acme.dev for approval.
+				</p>
+			</div>
+		</BbSmoothHeight>
+
+		<BbButton class="self-start" variant="primary">
+			Save payment method
+		</BbButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+	BbButton,
+	BbRadioGroup,
+	BbSmoothHeight,
+	BbTextInput,
+} from 'bitboss-ui';
+
+type MethodId = 'card' | 'bank';
+
+const methods: Array<{ id: MethodId; label: string }> = [
+	{ id: 'card', label: 'Card' },
+	{ id: 'bank', label: 'Bank transfer' },
+];
+
+const method = ref<MethodId>('card');
+
+const cardNumber = ref<string | null>(null);
+const expiry = ref<string | null>(null);
+const cvc = ref<string | null>(null);
+const iban = ref<string | null>(null);
+</script>
+```
+
+### Expanding search results
+
+Async panels are the same story with three branches instead of two: a spinner
+while the query runs, the result list once it lands, an empty message when
+nothing matches. Keep every branch inside one `BbSmoothHeight` and the panel
+glides between their heights — short spinner row, tall result list, one-line
+empty state — instead of snapping as each state swaps in. The default `resize`
+strategy covers all of it, including results wrapping onto more lines.
+
+**Expanding search results**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<BbTextInput
+			v-model="query"
+			compact
+			hide-label
+			label="Search documentation"
+			placeholder="Search documentation…"
+			prepend:icon="lucide:search"
+		/>
+
+		<BbSmoothHeight>
+			<div
+				v-if="loading"
+				class="flex items-center gap-2 px-1 py-2 text-sm text-gray-500"
+				role="status"
+			>
+				<BbSpinner size="sm" /> Searching…
+			</div>
+			<ul v-else-if="results.length" class="flex flex-col">
+				<li
+					v-for="page in results"
+					:key="page.href"
+					class="flex items-baseline justify-between gap-3 px-1 py-1.5 text-sm"
+				>
+					<a class="truncate font-medium" :href="page.href">{{ page.title }}</a>
+					<span class="shrink-0 text-xs text-gray-500">{{ page.section }}</span>
+				</li>
+			</ul>
+			<p v-else-if="query" class="px-1 py-2 text-sm text-gray-500">
+				No pages match “{{ query }}”.
+			</p>
+		</BbSmoothHeight>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, onBeforeUnmount } from 'vue';
+import { BbSmoothHeight, BbSpinner, BbTextInput } from 'bitboss-ui';
+
+type DocPage = { title: string; section: string; href: string };
+
+const pages: DocPage[] = [
+	{ title: 'Quickstart', section: 'Getting started', href: '#quickstart' },
+	{ title: 'Authentication', section: 'Guides', href: '#authentication' },
+	{ title: 'Webhooks', section: 'Guides', href: '#webhooks' },
+	{ title: 'Rate limits', section: 'Reference', href: '#rate-limits' },
+	{ title: 'Error codes', section: 'Reference', href: '#error-codes' },
+	{ title: 'API keys', section: 'Reference', href: '#api-keys' },
+];
 
-	// Schedule a trailing measurement after things settle
-	if (settleTimeoutId !== null) {
-		clearTimeout(settleTimeoutId);
+const query = ref<string | null>(null);
+const loading = ref(false);
+const results = ref<DocPage[]>([]);
+
+let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+watch(query, (value) => {
+	if (timeoutId !== null) {
+		clearTimeout(timeoutId);
+		timeoutId = null;
 	}
-	settleTimeoutId = setTimeout(() => {
-		if (content.value) {
-			applyHeight(content.value.scrollHeight);
-		}
-		settleTimeoutId = null;
-	}, props.transitionDuration);
-}
-
-function onResize(entries: ResizeObserverEntry[]) {
-	if (entries.length > 0) {
-		scheduleUpdate(entries[0].contentRect.height);
+
+	const term = value?.trim().toLowerCase() ?? '';
+	if (!term) {
+		loading.value = false;
+		results.value = [];
+		return;
 	}
-}
 
-function onMutation() {
-	if (content.value) {
-		scheduleUpdate(content.value.scrollHeight);
+	loading.value = true;
+	timeoutId = setTimeout(() => {
+		results.value = pages.filter((page) =>
+			`${page.title} ${page.section}`.toLowerCase().includes(term)
+		);
+		loading.value = false;
+		timeoutId = null;
+	}, 300);
+});
+
+onBeforeUnmount(() => {
+	if (timeoutId !== null) {
+		clearTimeout(timeoutId);
 	}
-}
-
-if (globalThis.ResizeObserver) {
-	onMounted(() => {
-		if (props.strategy === 'resize') {
-			if (content.value) {
-				observer.value = new ResizeObserver(onResize);
-				observer.value.observe(content.value, props.resizeOptions);
-			}
-		} else if (props.strategy === 'mutation') {
-			if (content.value) {
-				observer.value = new MutationObserver(onMutation);
-				observer.value.observe(content.value, props.mutationOptions);
-			}
-		}
-		// Initial measurement
-		if (content.value) {
-			applyHeight(content.value.scrollHeight);
-		}
-	});
-	onBeforeUnmount(() => {
-		if (observer.value) {
-			observer.value.disconnect();
-		}
-		if (rafId !== null) {
-			cancelAnimationFrame(rafId);
-		}
-		if (settleTimeoutId !== null) {
-			clearTimeout(settleTimeoutId);
-		}
-	});
-}
+});
 </script>
-
-<style lang="postcss">
-@import './index.css';
-</style>
 ```
 
-## Types
-
-```ts
-import type { CommonProps, NonVoidElementTag } from '@/types/CommonProps';
-
-export type BbSmoothHeightProps = {
-	/**
-	 * Options to pass to the MutationObserver.
-	 */
-	mutationOptions?: MutationObserverInit; // eslint-disable-line no-undef
-	/**
-	 * Options to pass to the ResizeObserver.
-	 */
-	resizeOptions?: ResizeObserverOptions; // eslint-disable-line no-undef
-	/**
-	 * Define which strategy to use. By default `'resize'` is used, which means the
-	 * component will update on resizing. You can also define `'mutation'` to use a MutationObserver.
-	 *
-	 * @defaultValue `'resize'`
-	 */
-	strategy?: 'resize' | 'mutation';
-} & NonVoidElementTag &
-	Pick<CommonProps, 'transitionDuration'>;
-
-export type BbSmoothHeightSlots = {
-	/**
-	 * Content whose height changes are animated with a smooth transition.
-	 */
-	default?: (props: object) => any;
+### Growing and shrinking lists (mutation strategy)
+
+When height changes because DOM nodes are **added or removed**, switch to
+`strategy="mutation"`: a `MutationObserver` re-measures `scrollHeight` whenever
+the DOM mutates. The default watch scope is `{ childList: true }` — **direct
+children of the content element only**. Pass `mutation-options` (a standard
+`MutationObserverInit`) to widen it: `{ childList: true, subtree: true }`
+catches nested inserts, and you can add `attributes` or `characterData` when
+class swaps or text edits drive the height.
+
+**Mutation strategy for a dynamic list**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex items-center justify-between gap-3">
+			<div class="flex flex-col gap-0.5">
+				<p class="text-sm font-medium">Recent activity</p>
+				<p class="text-xs text-gray-500">Q3 launch · Acme Studio</p>
+			</div>
+			<div class="flex gap-1.5">
+				<BbButton size="sm" variant="ghost" @click="removeEntry">
+					Remove
+				</BbButton>
+				<BbButton size="sm" variant="outline" @click="addEntry">Add</BbButton>
+			</div>
+		</div>
+
+		<BbSmoothHeight
+			:mutation-options="{ childList: true, subtree: true }"
+			strategy="mutation"
+		>
+			<ul class="flex flex-col divide-y">
+				<li
+					v-for="entry in entries"
+					:key="entry.id"
+					class="flex items-baseline justify-between gap-3 py-2 text-sm first:pt-0 last:pb-0"
+				>
+					<span>{{ entry.text }}</span>
+					<span class="shrink-0 text-xs text-gray-500">{{ entry.when }}</span>
+				</li>
+			</ul>
+		</BbSmoothHeight>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbSmoothHeight } from 'bitboss-ui';
+
+type Entry = { id: number; text: string; when: string };
+
+const feed: Array<{ text: string; when: string }> = [
+	{ text: 'Jordan closed “Q3 launch”', when: '2m' },
+	{ text: 'Priya commented on “Pricing page”', when: '18m' },
+	{ text: 'Sam invited a new teammate', when: '1h' },
+	{ text: 'Alex archived “Legacy import”', when: '3h' },
+];
+
+let nextId = 2;
+const entries = ref<Entry[]>([
+	{ id: 0, ...feed[0] },
+	{ id: 1, ...feed[1] },
+]);
+
+const addEntry = () => {
+	const item = feed[nextId % feed.length];
+	entries.value = [...entries.value, { id: nextId++, ...item }];
+};
+
+const removeEntry = () => {
+	entries.value = entries.value.slice(0, -1);
 };
+</script>
 ```
 
-## Styles
+Rule of thumb: stay on `resize` — it covers anything that changes the measured
+box, structural or not. Choose `mutation` when you need mutation-scoped control
+(or want `resizeOptions`' counterpart tuning); `resize-options` likewise forwards
+`ResizeObserverOptions` (e.g. `box`) to the resize path. Changing `strategy`,
+options, `disabled` or `transition-duration` at runtime re-wires the observer
+on the fly.
 
-```css
-.bb-smooth-height {
-	display: block;
-	overflow: clip;
-	transition-duration: 300ms;
-	transition-property: height;
-	transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+### Tag, timing and opting out
 
-	.content {
-		display: block;
-	}
-}
+- `tag` picks the wrapper: `div` (default) or `span` when the surrounding markup
+  only accepts phrasing content. The inner measuring element mirrors it, so you
+  get div-in-div or span-in-span — never a block element inside an inline one.
+  Both are forced to `display: block`, so a `span` animates exactly like a
+  `div`. That mirroring is why the list is only those two: anything with a
+  restricted content model (`<ul>`, `<p>`…) would nest invalidly inside itself.
+  Wrap such an element around `BbSmoothHeight` instead of asking for it via
+  `tag`.
+- `transition-duration` (ms, default 250) sets the animation length; the easing
+  comes from the design-token `--bb-ease`.
+- `disabled` opts out entirely: the inline height is removed, overflow returns
+  to visible, and layout is instant. It is reactive — flip it per instance when
+  a parent already animates height. (You don't need it for reduced motion —
+  that's automatic, see below.)
+
+**Slower glide on a release checklist**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Release checklist</p>
+			<p class="text-xs text-gray-500">v2.4.0 · ship window Fri Jul 24</p>
+		</div>
+
+		<BbSmoothHeight :transition-duration="400">
+			<ul class="flex flex-col gap-1.5 text-sm">
+				<li>Design review signed off</li>
+				<li>Ship the release notes</li>
+				<li v-if="expanded" class="text-gray-500">
+					Notify the changelog subscribers
+				</li>
+			</ul>
+		</BbSmoothHeight>
+
+		<BbButton class="self-start" variant="ghost" @click="expanded = !expanded">
+			{{ expanded ? 'Hide optional step' : 'Show optional step' }}
+		</BbButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSmoothHeight, BbButton } from 'bitboss-ui';
+
+// A longer 400ms transition makes the height glide read clearly as the
+// final release-checklist step appears and disappears.
+const expanded = ref(false);
+</script>
 ```
+
+### When NOT to use it
+
+- **Continuously resizing content** — a textarea being typed into, streaming
+  chat output, anything animating inside: the height transition re-runs layout
+  every frame, permanently.
+- **Large or expensive subtrees** — virtualized tables (`BbTable` with
+  `virtual`), long feeds: per-frame layout of a huge subtree janks. Animate a
+  small wrapper near the change instead of the whole page section.
+- **Inside `BbCollapsible`/`BbAccordion` content** — they already animate
+  height; nesting a second height animation causes double-easing and fighting
+  measurements.
+- **When the content must be hidden** — this component never hides anything;
+  use the collapsible rungs.
+- `strategy="mutation"` with `subtree: true` on a large tree observes every
+  descendant — keep the wrapped region small.
+
+### Works well with
+
+- `BbTextInput`/form fields — wrap the field + its error region so validation
+  messages push content smoothly instead of jumping.
+- Multi-step forms — wrap the step outlet so each step change glides to the new
+  height instead of snapping.
+- `BbSpinner` → content swaps — wrap the region that shows a spinner while
+  loading, so the swap to real data stops jumping.
+
+### Accessibility & motion
+
+- Purely visual — it adds no roles or ARIA, and hidden-looking content does not
+  exist: everything stays mounted and focusable. If the region is a disclosure
+  that should be announced, use `BbAccordion`/`BbCollapsible` so state and
+  `inert` are handled.
+- **It respects `prefers-reduced-motion: reduce` automatically** — a CSS media
+  query collapses the transition duration, so the height still updates (layout
+  stays correct) but the change applies instantly. No prop wiring needed.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `disabled` | `boolean \| undefined` | `false` |  | Disable smooth-height behavior and allow natural content height. |
+| `mutationOptions` | `MutationObserverInit \| undefined` | `{ childList: true }` |  | Options to pass to the MutationObserver. |
+| `resizeOptions` | `ResizeObserverOptions \| undefined` |  |  | Options to pass to the ResizeObserver. |
+| `strategy` | `"resize" \| "mutation" \| undefined` | `"resize"` |  | Define which strategy to use. By default `'resize'` is used, which means the component will update on resizing. You can also define `'mutation'` to use a MutationObserver. |
+| `tag` | `LayoutTag \| undefined` | `"div"` |  | Element rendered as the component's wrapper. |
+| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds |
+
+## Events
+
+- None.
+
+## Slots
+
+- `default` — scope: `object` — Content whose height changes are animated with a smooth transition.
+
+## See Also
+
+- [BbCollapsible](./BbCollapsible.md) — Toggles visibility of collapsible content blocks.