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

package/dist/ai/BbAccordion.md

@@ -8,6 +8,14 @@
 - 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)
 
+## Reachable through `BbAccordion`
+
+`BbAccordion` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Prefer these over `:deep()` on an inner class (allowed, unsupported: it can break on upgrade) — and never an import of an internal component.
+
+| pt part | Lands on | In |
+| --- | --- | --- |
+| `pt:header` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -38,38 +46,38 @@ Everything else is composition.
 
 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.
+indicator there, never a nested `<button>`/`<a>`. The panel is a block box
+inside the collapsing region, so padding, a border or a background on it —
+through `pt:panel` or `.bb-accordion__panel` — collapses with the body.
 
 **A pricing-page FAQ of independent panels**
 
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--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)]' : ''"
+			:class="index ? 'border-t border-(--bb-border)' : ''"
 		>
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<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' : ''"
+						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
+						:class="open ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
 					</span>
 				</div>
 			</template>
 
-			<p class="px-3 pb-2.5 text-sm text-[color:var(--bb-text-muted)]">
+			<p class="px-3 pb-2.5 text-sm text-(--bb-text-muted)">
 				{{ faq.answer }}
 			</p>
 		</BbAccordion>
@@ -121,23 +129,23 @@ on the row, badge included, toggles the panel.
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--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)]' : ''"
+			:class="index ? 'border-t border-(--bb-border)' : ''"
 		>
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<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' : ''"
+						class="ml-auto shrink-0 text-(--bb-text-muted) transition-transform duration-200"
+						:class="open ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
 					</span>
@@ -145,7 +153,7 @@ on the row, badge included, toggles the panel.
 			</template>
 
 			<div class="flex flex-col gap-1.5 px-3 pb-2.5">
-				<p class="text-xs text-[color:var(--bb-text-muted)]">
+				<p class="text-xs text-(--bb-text-muted)">
 					{{ endpoint.summary }}
 				</p>
 				<dl class="flex flex-col gap-1 text-xs">
@@ -155,7 +163,7 @@ on the row, badge included, toggles the panel.
 						class="flex items-baseline gap-2"
 					>
 						<dt class="shrink-0 font-mono">{{ param.name }}</dt>
-						<dd class="text-[color:var(--bb-text-muted)]">
+						<dd class="text-(--bb-text-muted)">
 							{{ param.type }} · {{ param.description }}
 						</dd>
 					</div>
@@ -226,22 +234,22 @@ const endpoints = ref<Endpoint[]>([
      Non-scoped so variant classes on the child badge receive the accents. -->
 <style>
 .bb-badge.bb-badge--soft-blue {
-	--accent: #2563eb;
+	--accent: var(--bb-info);
 }
 .bb-badge.bb-badge--soft-green {
-	--accent: #16a34a;
+	--accent: var(--bb-success);
 }
 .bb-badge.bb-badge--soft-red {
-	--accent: #dc2626;
+	--accent: var(--bb-danger);
 }
 .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;
+	--fg: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--bw: 1px;
 	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
-	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+	--ring-color: color-mix(in oklab, var(--accent) 45%, transparent);
 }
 </style>
 ```
@@ -249,9 +257,9 @@ const endpoints = ref<Endpoint[]>([
 ### Slot scope: the open flag and the toggle handle
 
 Both slots — `header` and the default (body) slot — receive the same scope,
-`{ value, toggle }`:
+`{ open, toggle }`:
 
-- `value` mirrors the open state (one-way — assigning to it does nothing). Use
+- `open` 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
@@ -263,17 +271,17 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion v-model="notes">
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<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' : ''"
+						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
+						:class="open ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
 					</span>
@@ -281,7 +289,7 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 			</template>
 			<template #default="{ toggle }">
 				<div class="flex flex-col items-start gap-1.5 px-3 pb-2.5">
-					<p class="text-sm text-[color:var(--bb-text-muted)]">
+					<p class="text-sm text-(--bb-text-muted)">
 						Dropdown keyboard navigation, smoother select popovers, and a new
 						color picker.
 					</p>
@@ -317,27 +325,25 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion
 			v-for="(plan, index) in plans"
 			:key="plan.name"
-			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
+			:class="index ? 'border-t border-(--bb-border)' : ''"
 			:model-value="openIndex === index"
 			@update:model-value="openIndex = $event ? index : null"
 		>
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<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-[color:var(--bb-text-muted)]"
-					>
+					<span class="flex items-center gap-1.5 text-(--bb-text-muted)">
 						{{ plan.price }}
 						<span
 							class="shrink-0 transition-transform duration-200"
-							:class="value ? 'rotate-180' : ''"
+							:class="open ? 'rotate-180' : ''"
 						>
 							<BbIcon icon="lucide:chevron-down" size="sm" />
 						</span>
@@ -346,7 +352,7 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 			</template>
 
 			<ul
-				class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-[color:var(--bb-text-muted)]"
+				class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-(--bb-text-muted)"
 			>
 				<li v-for="feature in plan.features" :key="feature">{{ feature }}</li>
 			</ul>
@@ -394,17 +400,17 @@ padding on the nested body content.
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion v-model="notifications">
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<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' : ''"
+						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
+						:class="open ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
 					</span>
@@ -414,20 +420,20 @@ padding on the nested body content.
 				<BbCheckbox v-model="mentions" label="Mentions" />
 				<BbCheckbox v-model="digests" label="Weekly digest" />
 				<BbAccordion v-model="advanced">
-					<template #header="{ value }">
+					<template #header="{ open }">
 						<div
-							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-[color:var(--bb-text-muted)]"
+							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-(--bb-text-muted)"
 						>
 							<span>Advanced</span>
 							<span
 								class="shrink-0 transition-transform duration-200"
-								:class="value ? 'rotate-180' : ''"
+								:class="open ? 'rotate-180' : ''"
 							>
 								<BbIcon icon="lucide:chevron-down" size="sm" />
 							</span>
 						</div>
 					</template>
-					<div class="pb-1 pt-1">
+					<div class="pt-1 pb-1">
 						<BbCheckbox v-model="quiet" label="Quiet hours (22:00–08:00)" />
 					</div>
 				</BbAccordion>
@@ -470,7 +476,7 @@ get a near-instant transition automatically.
 	<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)]">
+	<p class="px-3 pb-3 text-sm text-(--bb-text-muted)">
 		Rendered up front so its text is present even while collapsed.
 	</p>
 </BbAccordion>
@@ -483,9 +489,97 @@ 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.
 
+### Restyling with passthrough
+
+`pt` reaches a named part with a class list — or, in the object form, a
+style and attributes — optionally only while a state is on. Parts: `root`,
+`header` (the trigger button) and `panel` (the region the header controls). State:
+`open`. There is no chevron of ours — the header is your slot markup — so there
+is no `icon`.
+
+The pricing-page FAQ above, restyled through those parts: layout, type and
+hover on `pt:header` (children are click-transparent, so hover belongs on the
+button), a heavier weight on `pt:header:open`, join lines on `pt:root`. Padding
+can go on `pt:panel`: the panel sits inside the collapsing region, so it
+collapses with the body.
+
+**pt:header — the FAQ trigger, a wash while open**
+
+```vue
+<template>
+	<div
+		class="max-w-2xl overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
+	>
+		<BbAccordion
+			v-for="(faq, index) in faqs"
+			:key="faq.question"
+			v-model="faq.open"
+			pt:header="flex items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium hover:underline"
+			pt:header:open="font-semibold"
+			pt:panel="text-sm"
+			:pt:root="index ? 'border-t border-(--bb-border)' : ''"
+		>
+			<template #header="{ open }">
+				<span>{{ faq.question }}</span>
+				<span
+					class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
+					:class="open ? 'rotate-180' : ''"
+				>
+					<BbIcon icon="lucide:chevron-down" size="sm" />
+				</span>
+			</template>
+
+			<p class="px-3 pb-2.5 text-(--bb-text-muted)">
+				{{ faq.answer }}
+			</p>
+		</BbAccordion>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbAccordion, BbIcon } from 'bitboss-ui';
+
+type Faq = { question: string; answer: string; open: boolean };
+
+// Same pricing-page FAQ as `FaqList.vue`, restyled through passthrough:
+// layout and hover on `pt:header`, a heavier weight on `pt:header:open`,
+// join lines on `pt:root`. Padding may go on `pt:panel` or the slotted body
+// alike: the panel is inside the collapsing region, so both collapse.
+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>
+```
+
+A listener on `pt:header` runs after the toggle, never instead of it. The full
+grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbAccordionProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
-- `BbIcon` — a rotating chevron in the header, driven by the slot's `value` (see
+- `BbIcon` — a rotating chevron in the header, driven by the slot's `open` (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.
@@ -501,8 +595,6 @@ is generated for you.
   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
@@ -529,21 +621,51 @@ is generated for you.
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
-| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `header`, `panel`, `root`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAccordionProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `id` | `string \| undefined` |  |  | The root's `id`; the header button's id (`<id>_header`) derives from it. Generated when omitted. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds |
+| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |
+
+## Passthrough parts and states
+
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The accordion's outer element: the header and its panel. |
+| `header` | The trigger button that opens and closes the panel. Its content is your slot markup — there is no chevron of ours, so no `icon` part. |
+| `panel` | The region the header controls (the ARIA accordion panel). |
+
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `open` | Component-wide: the panel is open (follows `v-model`). |
 
 ## Events
 
-- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+- `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
 
 ## Slots
 
-- `default` — scope: `BbAccordionToggleSlotProps` — The collapsible body content shown when the accordion is open.
-- `header` — scope: `BbAccordionToggleSlotProps` — Content rendered inside the accordion header button.
+- `default` — scope: `BbAccordionToggleSlotProps` `{ open: boolean; toggle: () => void }` — The collapsible body content shown when the accordion is open.
+- `header` — scope: `BbAccordionToggleSlotProps` `{ open: boolean; toggle: () => void }` — Content rendered inside the accordion header button.
+
+## Component tree
+
+`BbAccordion` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbAccordion`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:
+
+- **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbAccordion`. A pt part listed as landing there is set on `BbAccordion` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbAccordion` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbAccordion`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
+- **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbAccordion`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
+- Listed nodes are the ones `BbAccordion`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
+
+- `BbAccordion` _(this component)_ — its own template binds: `header` → `BbBaseButton`, `panel` → `div.bb-accordion__panel`
+  - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
+  - `BbCollapsible` _(public — [contract](./BbCollapsible.md))_ — its own pt parts (`BbCollapsible`): `content` → `component.bb-collapsible__content`
 
 ## 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).
+- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanels exports enable split layouts).