bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbAccordion.md

@@ -1,134 +1,543 @@
 # BbAccordion
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Navigation**
+- Description: Expands and collapses a content panel.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbAccordion.md](./source/BbAccordion.md)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbAccordion` is the top of the disclosure ladder: a ready-made panel that pairs
+a header **button** with a collapsible body and wires the accessibility for you
+(`aria-expanded`, `aria-controls`, `role="region"`, `aria-labelledby`). Reach for
+it for FAQs, settings sections, and any "click a title to reveal detail" pattern.
+
+Each `BbAccordion` is **one** panel controlled by a boolean `v-model`. Compose
+several for a list; there is no group wrapper. That keeps the model explicit: for
+independent panels give each its own boolean, and for single-open behaviour track
+one active key yourself (shown below).
+
+Step down the ladder when the composed header doesn't fit:
+
+- Your trigger lives somewhere the header can't (inline link, toolbar, inside
+  another component) → **`BbCollapsible`** (`./BbCollapsible.md`), the primitive
+  this is built on.
+- You only need to animate a height change, with no hide/show state at all →
+  **`BbSmoothHeight`** (`./BbSmoothHeight.md`).
+
+The public surface is small on purpose: `v-model` (boolean), `eager`,
+`transition-duration`, `id`, two slots, and the `update:modelValue` event.
+Everything else is composition.
+
+### Composing an FAQ
+
+The classic pricing-page FAQ is independent panels — each with its own boolean.
+The `header` slot is rendered **inside the header button** — so put text and an
+indicator there, never a nested `<button>`/`<a>`. Style the body on the slotted
+content, not the panel: the underlying collapsible forces a true zero-height
+collapsed state and strips padding/borders you put on the panel itself.
+
+**A pricing-page FAQ of independent panels**
 
 ```vue
 <template>
-	<div class="bb-accordion">
-		<BaseButton
-			:id="`${id}_header`"
-			:aria-controls="id"
-			:aria-expanded="internalValue"
-			:class="'bb-accordion__header'"
-			@click.self="toggle"
-			><slot name="header" :toggle="toggle" :value="internalValue"></slot
-		></BaseButton>
-		<BbCollapsible
-			:id="id"
-			:aria-labelledby="`${id}_header`"
-			:class="'bb-accordion__content'"
-			:eager="eager"
-			:model-value="internalValue"
-			:role="'region'"
-			:transition-duration="transitionDuration"
-			><slot :toggle="toggle" :value="internalValue"></slot
-		></BbCollapsible>
+	<div
+		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbAccordion
+			v-for="(faq, index) in faqs"
+			:key="faq.question"
+			v-model="faq.open"
+			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
+		>
+			<template #header="{ value }">
+				<div
+					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
+				>
+					<span>{{ faq.question }}</span>
+					<span
+						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
+						:class="value ? 'rotate-180' : ''"
+					>
+						<BbIcon icon="lucide:chevron-down" size="sm" />
+					</span>
+				</div>
+			</template>
+
+			<p class="px-3 pb-2.5 text-sm text-gray-500">
+				{{ faq.answer }}
+			</p>
+		</BbAccordion>
 	</div>
 </template>
 
 <script setup lang="ts">
-import { ref, watch } from 'vue';
-import { useId } from '@/composables/useId';
-import BaseButton from '../BaseButton/BaseButton.vue';
-import BbCollapsible from '../BbCollapsible/BbCollapsible.vue';
-import type {
-	BbAccordionProps,
-	BbAccordionEvents,
-	BbAccordionSlots,
-} from './types';
-
-const emit = defineEmits<BbAccordionEvents>();
-
-const props = withDefaults(defineProps<BbAccordionProps>(), {
-	transitionDuration: 250,
-});
-
-const id = props.id || `bba_${useId().id.value}`;
-
-const internalValue = ref(props.modelValue);
-/**
- * Watch external changes and align internal value
- */
-watch(
-	() => props.modelValue,
-	(current, previous) => {
-		if (current !== previous && current !== internalValue.value) {
-			internalValue.value = current;
-		}
-	}
-);
-
-const toggle = () => {
-	internalValue.value = !internalValue.value;
-	emit('update:modelValue', !props.modelValue);
+import { ref } from 'vue';
+import { BbAccordion, BbIcon } from 'bitboss-ui';
+
+type Faq = { question: string; answer: string; open: boolean };
+
+// Pricing-page FAQ — independent panels, each with its own boolean.
+const faqs = ref<Faq[]>([
+	{
+		question: 'Can I change plans mid-cycle?',
+		answer:
+			'Yes. Upgrades take effect immediately and are prorated; downgrades apply at the next renewal.',
+		open: true,
+	},
+	{
+		question: 'Do you offer annual billing?',
+		answer:
+			'Annual plans are billed once per year at a 20% discount versus monthly.',
+		open: false,
+	},
+	{
+		question: 'What happens when I exceed my seat limit?',
+		answer:
+			'New invites pause until you add seats or free an existing one. Usage never auto-charges.',
+		open: false,
+	},
+]);
+</script>
+```
+
+The header button spans the full width and is the only click target: any
+non-interactive element you slot into it is made click-transparent
+(`pointer-events: none`), so wrappers, icons and badges never swallow the toggle
+click.
+
+That click-transparency is what lets headers carry rich, passive metadata. An
+API-reference disclosure list leans on it: a soft method `BbBadge` and a
+`<code>` path in the header, parameter details in the body — clicking anywhere
+on the row, badge included, toggles the panel.
+
+**An API reference disclosure list**
+
+```vue
+<template>
+	<div
+		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbAccordion
+			v-for="(endpoint, index) in endpoints"
+			:key="`${endpoint.method}:${endpoint.path}`"
+			v-model="endpoint.open"
+			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
+		>
+			<template #header="{ value }">
+				<div class="flex w-full items-center gap-2 px-3 py-2 text-left">
+					<BbBadge size="xs" :variant="METHOD_VARIANT[endpoint.method]">{{
+						endpoint.method
+					}}</BbBadge>
+					<code class="truncate font-mono text-xs">{{ endpoint.path }}</code>
+					<span
+						class="ml-auto shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
+						:class="value ? 'rotate-180' : ''"
+					>
+						<BbIcon icon="lucide:chevron-down" size="sm" />
+					</span>
+				</div>
+			</template>
+
+			<div class="flex flex-col gap-1.5 px-3 pb-2.5">
+				<p class="text-xs text-gray-500">{{ endpoint.summary }}</p>
+				<dl class="flex flex-col gap-1 text-xs">
+					<div
+						v-for="param in endpoint.params"
+						:key="param.name"
+						class="flex items-baseline gap-2"
+					>
+						<dt class="shrink-0 font-mono">{{ param.name }}</dt>
+						<dd class="text-gray-500">
+							{{ param.type }} · {{ param.description }}
+						</dd>
+					</div>
+				</dl>
+			</div>
+		</BbAccordion>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbAccordion, BbBadge, BbIcon } from 'bitboss-ui';
+import type { BbBadgeProps } from 'bitboss-ui';
+
+type Endpoint = {
+	method: 'GET' | 'POST' | 'DELETE';
+	path: string;
+	summary: string;
+	params: Array<{ name: string; type: string; description: string }>;
+	open: boolean;
+};
+
+// Soft status palette — method hue, not action intent (no primary/destructive).
+const METHOD_VARIANT: Record<Endpoint['method'], BbBadgeProps['variant']> = {
+	GET: 'soft-blue',
+	POST: 'soft-green',
+	DELETE: 'soft-red',
 };
 
-defineSlots<BbAccordionSlots>();
+const endpoints = ref<Endpoint[]>([
+	{
+		method: 'GET',
+		path: '/v1/invoices',
+		summary: 'List invoices, most recent first. Paginated by cursor.',
+		params: [
+			{ name: 'status', type: 'string', description: 'draft, open or paid' },
+			{ name: 'limit', type: 'integer', description: '1–100, default 25' },
+		],
+		open: true,
+	},
+	{
+		method: 'POST',
+		path: '/v1/invoices',
+		summary: 'Create a draft invoice for a customer.',
+		params: [
+			{
+				name: 'customer',
+				type: 'string',
+				description: 'customer id, required',
+			},
+			{ name: 'due_date', type: 'string', description: 'ISO date, optional' },
+		],
+		open: false,
+	},
+	{
+		method: 'DELETE',
+		path: '/v1/invoices/:id',
+		summary: 'Delete a draft invoice. Finalized invoices cannot be deleted.',
+		params: [
+			{ name: 'id', type: 'string', description: 'invoice id, in path' },
+		],
+		open: false,
+	},
+]);
 </script>
 
-<style lang="postcss">
-@import './index.css';
+<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
+     Non-scoped so variant classes on the child badge receive the accents. -->
+<style>
+.bb-badge.bb-badge--soft-blue {
+	--accent: #2563eb;
+}
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-red {
+	--accent: #dc2626;
+}
+.bb-badge.bb-badge--soft-blue,
+.bb-badge.bb-badge--soft-green,
+.bb-badge.bb-badge--soft-red {
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
 </style>
 ```
 
-## Types
-
-```ts
-import type { BbCollapsibleProps } from '../BbCollapsible/types';
-import type { CommonProps } from '@/types/CommonProps';
-
-export type BbAccordionProps = Pick<
-	BbCollapsibleProps,
-	'eager' | 'transitionDuration'
-> & {
-	/**
-	 * Used by v-model to trigger opening / closing the collapsible.
-	 * @defaultValue `undefined`
-	 */
-	modelValue?: boolean;
-} & Pick<CommonProps, 'id'>;
-
-export type BbAccordionEvents = {
-	/**
-	 * Emitted when the accordion open/closed state changes.
-	 */
-	(e: 'update:modelValue', value: boolean): void;
-};
+### Slot scope: the open flag and the toggle handle
 
-/** Props exposed by the `header` and `default` slots. */
-export type BbAccordionToggleSlotProps = {
-	/** Whether the accordion panel is currently open. */
-	value: BbAccordionProps['modelValue'];
-	/** Toggles the open/closed state. */
-	toggle: () => void;
-};
+Both slots — `header` and the default (body) slot — receive the same scope,
+`{ value, toggle }`:
 
-export type BbAccordionSlots = {
-	/**
-	 * Content rendered inside the accordion header button.
-	 */
-	header?: (props: BbAccordionToggleSlotProps) => any;
-	/**
-	 * The collapsible body content shown when the accordion is open.
-	 */
-	default?: (props: BbAccordionToggleSlotProps) => any;
-};
+- `value` mirrors the open state (one-way — assigning to it does nothing). Use
+  it to spin a chevron or swap header copy.
+- `toggle()` flips the panel. In the header it is redundant (the button already
+  toggles); its real use is in the **body**, for a "Show less" affordance that
+  collapses the panel without reaching back to the header. Writing to your own
+  `v-model` ref is equivalent — pick one style.
+
+**A body action that closes the panel**
+
+```vue
+<template>
+	<div
+		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbAccordion v-model="notes">
+			<template #header="{ value }">
+				<div
+					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
+				>
+					<span>Release notes</span>
+					<span
+						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
+						:class="value ? 'rotate-180' : ''"
+					>
+						<BbIcon icon="lucide:chevron-down" size="sm" />
+					</span>
+				</div>
+			</template>
+			<template #default="{ toggle }">
+				<div class="flex flex-col items-start gap-1.5 px-3 pb-2.5">
+					<p class="text-sm text-gray-500">
+						Dropdown keyboard navigation, smoother select popovers, and a new
+						color picker.
+					</p>
+					<BbButton variant="link" @click="toggle">Show less</BbButton>
+				</div>
+			</template>
+		</BbAccordion>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbAccordion, BbButton, BbIcon } from 'bitboss-ui';
+
+// Panel starts open so the in-body "Show less" affordance is visible.
+const notes = ref(true);
+</script>
 ```
 
-## Styles
-
-```css
-.bb-accordion {
-	color: var(--bb-text);
-	.bb-accordion__header {
-		text-align: left;
-		width: 100%;
-
-		*:not(button):not(a) {
-			pointer-events: none;
-		}
-	}
-	.bb-accordion__content {
-	}
-}
+`update:modelValue` fires on every toggle (header click or `toggle()` call) with
+the new boolean — listen to it only for side effects (analytics, lazy-fetch on
+first open); the open/close itself needs no handler.
+
+### Single-open (exclusive) accordions
+
+Track the open index/key and derive
+each panel's state from it; opening one closes the rest, and clicking the open
+header closes all (the `update:modelValue` payload is `false`, so the key resets
+to `null`). Prefer a stable key over an index when the list can reorder.
+
+**Only one plan expanded at a time**
+
+```vue
+<template>
+	<div
+		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbAccordion
+			v-for="(plan, index) in plans"
+			:key="plan.name"
+			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
+			:model-value="openIndex === index"
+			@update:model-value="openIndex = $event ? index : null"
+		>
+			<template #header="{ value }">
+				<div
+					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm"
+				>
+					<span class="font-medium">{{ plan.name }}</span>
+					<span class="flex items-center gap-1.5 text-gray-500">
+						{{ plan.price }}
+						<span
+							class="shrink-0 transition-transform duration-200"
+							:class="value ? 'rotate-180' : ''"
+						>
+							<BbIcon icon="lucide:chevron-down" size="sm" />
+						</span>
+					</span>
+				</div>
+			</template>
+
+			<ul class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-gray-500">
+				<li v-for="feature in plan.features" :key="feature">{{ feature }}</li>
+			</ul>
+		</BbAccordion>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbAccordion, BbIcon } from 'bitboss-ui';
+
+type Plan = { name: string; price: string; features: string[] };
+
+const plans: Plan[] = [
+	{
+		name: 'Starter',
+		price: 'Free',
+		features: ['1 project', 'Community support', '7-day history'],
+	},
+	{
+		name: 'Team',
+		price: '$29 / mo',
+		features: ['Unlimited projects', 'Priority support', 'SSO'],
+	},
+	{
+		name: 'Enterprise',
+		price: 'Custom',
+		features: ['Dedicated success manager', 'Audit logs', 'Custom SLAs'],
+	},
+];
+
+// Only one panel open at a time — a plain index keeps them mutually exclusive.
+const openIndex = ref<number | null>(0);
+</script>
+```
+
+### Nesting accordions
+
+Panels nest without extra wiring: the body animates with CSS grid rows, so an
+inner panel opening simply grows the outer one. Keep the hierarchy readable with
+padding on the nested body content.
+
+**A settings section with a nested advanced panel**
+
+```vue
+<template>
+	<div
+		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbAccordion v-model="notifications">
+			<template #header="{ value }">
+				<div
+					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
+				>
+					<span>Notifications</span>
+					<span
+						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
+						:class="value ? 'rotate-180' : ''"
+					>
+						<BbIcon icon="lucide:chevron-down" size="sm" />
+					</span>
+				</div>
+			</template>
+			<div class="flex flex-col gap-2 px-3 pb-2.5 text-sm">
+				<BbCheckbox v-model="mentions" label="Mentions" />
+				<BbCheckbox v-model="digests" label="Weekly digest" />
+				<BbAccordion v-model="advanced">
+					<template #header="{ value }">
+						<div
+							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-gray-500"
+						>
+							<span>Advanced</span>
+							<span
+								class="shrink-0 transition-transform duration-200"
+								:class="value ? 'rotate-180' : ''"
+							>
+								<BbIcon icon="lucide:chevron-down" size="sm" />
+							</span>
+						</div>
+					</template>
+					<div class="pb-1 pt-1">
+						<BbCheckbox v-model="quiet" label="Quiet hours (22:00–08:00)" />
+					</div>
+				</BbAccordion>
+			</div>
+		</BbAccordion>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbAccordion, BbCheckbox, BbIcon } from 'bitboss-ui';
+
+const notifications = ref(true);
+const mentions = ref(true);
+const digests = ref(false);
+const advanced = ref(false);
+const quiet = ref(false);
+</script>
 ```
+
+### Deferred vs eager mounting, and timing
+
+The body is **not rendered until the first open** — no wasted work for panels
+the user never touches. Once opened it stays mounted, so state inside the body
+survives close/reopen. While closed, mounted content is `aria-hidden` and
+`inert`: it leaves the tab order and cannot be focused or clicked.
+
+Pass `eager` to mount the body immediately — needed when the content must exist
+up front: searchable/indexable text, form fields that register or validate
+before the panel is ever opened, anything you measure on mount.
+
+`transition-duration` (ms, default 250) tunes the open/close animation — one
+value drives both the height and the fade. Users with `prefers-reduced-motion`
+get a near-instant transition automatically.
+
+**Eager body with a slower transition**
+
+```vue
+<BbAccordion v-model="state.shipping" eager :transition-duration="350">
+	<template #header>
+		<span class="px-3 py-2 text-sm font-medium">Shipping details</span>
+	</template>
+	<p class="px-3 pb-3 text-sm text-[color:var(--bb-text-muted)]">
+		Rendered up front so its text is present even while collapsed.
+	</p>
+</BbAccordion>
+```
+
+### Stable ids
+
+Pass `id` when you need deterministic markup (tests, external `aria-*`
+references): the body region gets your id and the header gets `<id>_header`,
+already cross-wired via `aria-controls`/`aria-labelledby`. Omitted, a unique id
+is generated for you.
+
+### Works well with
+
+- `BbIcon` — a rotating chevron in the header, driven by the slot's `value` (see
+  the FAQ example).
+- `BbBadge` — counts or soft method/status pills in the header (see the API
+  reference example); non-interactive content stays click-transparent.
+- `BbCollapsible` / `BbSmoothHeight` — the rungs to step down to when the
+  composed header doesn't fit (see When to use).
+- Form components (`BbCheckbox`, `BbTextInput`…) in the body for progressive
+  disclosure of settings — add `eager` when those fields must exist on mount.
+
+### Gotchas & anti-patterns
+
+- **Don't nest interactive elements in the header** — it is already a `<button>`;
+  a nested button/link is invalid HTML and splits the click target. Actions
+  belong in the body.
+- **Don't build a group wrapper** with watchers that force-close siblings —
+  derive `model-value` from one active key instead (single-open above).
+- **Don't put padding/borders on the panel itself** expecting them to collapse —
+  the collapsed state zeroes them; style the slotted content.
+- **Don't add `v-if`/`v-show` around the body** to "optimize" — deferred
+  mounting is already the default; `eager` is the explicit opt-out.
+- **Hover styles on non-interactive header children won't fire** (they are
+  `pointer-events: none` by design) — style hover states on the header button
+  via the wrapper instead.
+
+### Accessibility
+
+- The header is a real `button` with `aria-expanded`/`aria-controls`; the body
+  is a `role="region"` labelled by the header via `aria-labelledby`. You add
+  nothing — and you must not wrap the header slot in another interactive
+  element.
+- Keyboard comes free with the native button: Tab to the header, Enter/Space
+  toggles. Closed content is `inert`, so it can never be tabbed into.
+- Provide a visible, meaningful header label; the chevron is decorative (mark
+  custom SVGs `aria-hidden`).
+- Honours `prefers-reduced-motion` via the underlying `BbCollapsible`.
+
+## v-model
+
+- `v-model` — type: `boolean \| undefined`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. |
+| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds |
+
+## Events
+
+- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+
+## Slots
+
+- `default` — scope: `BbAccordionToggleSlotProps` — The collapsible body content shown when the accordion is open.
+- `header` — scope: `BbAccordionToggleSlotProps` — Content rendered inside the accordion header button.
+
+## See Also
+
+- [BbCollapsible](./BbCollapsible.md) — Toggles visibility of collapsible content blocks.
+- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; BbTabRoot enables split layouts).