entasis 0.10.2 → 0.12.0

package/dist/components/Collapsible/Collapsible.svelte

@@ -1,13 +1,24 @@
 <script lang="ts">
+	import { tick, untrack } from 'svelte';
 	import Slot from '../Slot/Slot.svelte';
 	import type { CollapsibleProps } from './collapsible.props.js';
 	import { useCollapsibleMotion, useCollapsibleTheme } from './collapsible.theme.js';
-	import { slide } from '../../transitions/transition.js';
+	import { disclosurePanel } from '../../attachments/disclosurePanel.svelte.js';
 	import { easingBezierStrings } from '../../transitions/easingFunctions.js';
 	import { caretDownIcon } from '../Icons/caretDown.js';
 	import { plusIcon } from '../Icons/plus.js';
 	import { minusIcon } from '../Icons/minus.js';
 	import { createBindableValue } from '../../utils/state.svelte.js';
+	import {
+		createOpenChangeDetails,
+		requestOpenChange,
+		type OpenChangeInit
+	} from '../../utils/openChange.js';
+	import {
+		openStateAttributes,
+		transitionStatusAttributes,
+		type OpenTransitionStatus
+	} from '../../utils/stateAttributes.js';
 
 	let {
 		ref = $bindable(),
@@ -16,13 +27,15 @@
 		open = $bindable(),
 		disabled = false,
 		onOpenChange,
+		onAfterOpen,
+		onAfterClose,
+		hiddenUntilFound = false,
+		keepMounted = false,
 		size = 'normal',
 		icon = 'chevron',
 		theme,
 		trigger,
 		children,
-		accessible,
-		srOnlyContent,
 		variant = 'default',
 		peekHeight = 80,
 		transition,
@@ -44,14 +57,26 @@
 	// Peek variant: content is always mounted, clipped to `peekHeight` and faded
 	// when closed. `contentHeight` (measured) drives a smooth max-height animation.
 	let contentHeight = $state(0);
+	let clipElement = $state<HTMLElement | null>(null);
+	let contentElement = $state<HTMLElement | null>(null);
 	const peekHeightCss = $derived(typeof peekHeight === 'number' ? `${peekHeight}px` : peekHeight);
 	const maskGradient = 'linear-gradient(to bottom, rgb(0 0 0) 35%, transparent 100%)';
 
-	const handleToggle = () => {
+	// The one path to a state change: `onOpenChange` runs first and may cancel.
+	function requestChange(next: boolean, init: OpenChangeInit) {
+		if (next === isOpen) return;
+		const details = createOpenChangeDetails(init);
+		if (!requestOpenChange(onOpenChange ?? undefined, next, details)) return;
+		openState.value = next;
+	}
+
+	const handleToggle = (event: MouseEvent) => {
 		if (disabled) return;
-		const newOpen = !isOpen;
-		openState.value = newOpen;
-		onOpenChange?.(newOpen);
+		requestChange(!isOpen, {
+			reason: 'trigger-press',
+			event,
+			trigger: event.currentTarget as HTMLElement
+		});
 	};
 
 	const classes = $derived(useCollapsibleTheme(theme));
@@ -60,11 +85,79 @@
 
 	// Motion preset from `collapsibleTheme.motion`, through the override ladder
 	// (registry → `setCollapsibleTheme` → instance `theme.motion` → `transition` prop).
-	// `slide` is a factory: it captures the theme context at init because Svelte runs
-	// transition functions outside component initialisation.
 	const resolveMotion = useCollapsibleMotion();
-	const slideTransition = slide();
 	const contentMotion = $derived(resolveMotion({ variant }, { motion: theme?.motion, transition }));
+
+	// Default variant: the panel's `hidden` state, height animation, find-in-page reveal and the
+	// completion callbacks come from the shared disclosure panel.
+	const panel = disclosurePanel({
+		open: () => isOpen,
+		// A disabled collapsible cannot be toggled, so it is not findable: its closed content stays
+		// under plain `hidden`.
+		hiddenUntilFound: () => hiddenUntilFound && !disabled,
+		keepMounted: () => keepMounted || (hiddenUntilFound && disabled),
+		motion: () => contentMotion,
+		onBeforeMatch: (event) => {
+			if (!disabled) requestChange(true, { reason: 'find-in-page', event });
+		},
+		// The peek variant renders no panel: it reports its own completion below.
+		onAfterOpen: () => variant !== 'peek' && onAfterOpen?.(),
+		onAfterClose: () => variant !== 'peek' && onAfterClose?.()
+	});
+
+	// Peek variant: the clip animates its max-height with a CSS transition, so completion is
+	// the end of whatever animations that left running (none under reduced motion).
+	let peekStatus = $state<OpenTransitionStatus>(untrack(() => (isOpen ? 'open' : 'closed')));
+	let peekDirection = untrack(() => isOpen);
+	let peekPhase = 0;
+
+	$effect(() => {
+		const next = isOpen;
+		untrack(() => {
+			if (next === peekDirection) return;
+			peekDirection = next;
+			if (variant !== 'peek') return;
+			const phase = ++peekPhase;
+			peekStatus = next ? 'entering' : 'exiting';
+			void settlePeek(phase, next);
+		});
+	});
+
+	async function settlePeek(phase: number, next: boolean) {
+		await tick();
+		const animations = clipElement?.getAnimations?.() ?? [];
+		if (animations.length > 0) await Promise.allSettled(animations.map((a) => a.finished));
+		if (phase !== peekPhase) return;
+		peekStatus = next ? 'open' : 'closed';
+		if (next) onAfterOpen?.();
+		else onAfterClose?.();
+	}
+
+	// Closed peek content is clipped, not removed: controls below the visible preview would stay
+	// tabbable while invisible, so they are inert until the content opens.
+	const FOCUSABLE =
+		'a[href],area[href],button,input,select,textarea,summary,iframe,[tabindex],[contenteditable]:not([contenteditable="false"]),audio[controls],video[controls]';
+
+	$effect(() => {
+		if (variant !== 'peek' || peekStatus !== 'closed') return;
+		// Re-run when the content or the preview height changes.
+		void contentHeight;
+		void peekHeightCss;
+		const clip = clipElement;
+		const content = contentElement;
+		if (!clip || !content) return;
+		const inerted: Element[] = [];
+		const limit = clip.getBoundingClientRect().bottom;
+		for (const element of content.querySelectorAll(FOCUSABLE)) {
+			if (element.hasAttribute('inert')) continue;
+			if (element.getBoundingClientRect().top < limit) continue;
+			element.setAttribute('inert', '');
+			inerted.push(element);
+		}
+		return () => {
+			for (const element of inerted) element.removeAttribute('inert');
+		};
+	});
 </script>
 
 {#snippet triggerIcon()}
@@ -88,11 +181,14 @@
 		data-disabled={disabled ? '' : undefined}
 		data-size={size}
 		data-variant="peek"
+		{...openStateAttributes(isOpen)}
+		{...transitionStatusAttributes(peekStatus)}
 		class={classes.root({ size, className })}
 		{...attachments}
 	>
 		<div class="relative">
 			<div
+				bind:this={clipElement}
 				id={contentId}
 				class="overflow-hidden transition-[max-height]"
 				style:transition-duration={`${contentMotion.in.duration ?? 0}ms`}
@@ -103,7 +199,7 @@
 				style:-webkit-mask-image={isOpen ? undefined : maskGradient}
 				style:mask-image={isOpen ? undefined : maskGradient}
 			>
-				<div bind:clientHeight={contentHeight} class="pb-12">
+				<div bind:this={contentElement} bind:clientHeight={contentHeight} class="pb-12">
 					<Slot payload={{ open: isOpen }} render={children} />
 				</div>
 			</div>
@@ -114,6 +210,7 @@
 					aria-controls={contentId}
 					data-state={collapsibleState}
 					data-disabled={disabled ? '' : undefined}
+					{...openStateAttributes(isOpen)}
 					{disabled}
 					class="state-layer bg-surface text-neutral/80 raised-1 pointer-events-auto inline-flex items-center gap-1.5 rounded-full px-3 py-1 text-sm font-medium transition disabled:cursor-not-allowed disabled:opacity-50"
 					onclick={handleToggle}
@@ -130,15 +227,18 @@
 		data-state={collapsibleState}
 		data-disabled={disabled ? '' : undefined}
 		data-size={size}
+		{...openStateAttributes(isOpen)}
+		{...transitionStatusAttributes(panel.status)}
 		class={classes.root({ size, className })}
 		{...attachments}
 	>
 		<button
 			type="button"
 			aria-expanded={isOpen}
-			aria-controls={contentId}
+			aria-controls={panel.rendered ? contentId : undefined}
 			data-state={collapsibleState}
 			data-disabled={disabled ? '' : undefined}
+			{...openStateAttributes(isOpen)}
 			{disabled}
 			class={classes.trigger({ size, disabled })}
 			onclick={handleToggle}
@@ -147,19 +247,25 @@
 			{@render triggerIcon()}
 		</button>
 
-		{#if isOpen}
+		{#if panel.rendered}
+			<!-- The panel stays bare: while it hides until found, only its content is skipped, so
+			     the padding, gap and margin of the content slot live on the element inside. -->
 			<div
 				id={contentId}
 				data-state={collapsibleState}
 				data-disabled={disabled ? '' : undefined}
-				class={classes.content({ size })}
-				in:slideTransition={contentMotion.in}
-				out:slideTransition={contentMotion.out}
+				{...panel.attributes}
+				{@attach panel.attach}
 			>
-				<Slot payload={{ open: isOpen }} render={children} />
+				<div
+					data-state={collapsibleState}
+					data-disabled={disabled ? '' : undefined}
+					{...openStateAttributes(isOpen)}
+					class={classes.content({ size })}
+				>
+					<Slot payload={{ open: isOpen }} render={children} />
+				</div>
 			</div>
-		{:else if accessible || srOnlyContent}
-			<Slot render={srOnlyContent || children} payload={{ open: isOpen }} />
 		{/if}
 	</div>
 {/if}

package/dist/components/Collapsible/collapsible.attributes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The styling hooks a Collapsible exposes. Attributes are presence attributes (`''` while the
+ * state holds, omitted otherwise) unless the description says they carry a value.
+ */
+export declare const collapsibleDataAttributes: {
+    readonly 'data-open': "On the root, the trigger, the panel and the content: present while open.";
+    readonly 'data-closed': "On the root, the trigger, the panel and the content: present while closed, including during the exit transition.";
+    readonly 'data-entering': "On the root and the panel (`variant=\"peek\"` has no separate panel): present while the opening animation plays.";
+    readonly 'data-exiting': "On the root and the panel (`variant=\"peek\"` has no separate panel): present while the closing animation plays.";
+    readonly 'data-disabled': "On the root, the trigger, the panel and the content: present while `disabled`.";
+    readonly 'data-state': "On the root, the trigger, the panel and the content: `open` or `closed` (kept for compatibility; prefer `data-open` / `data-closed`).";
+    readonly 'data-size': "On the root: the resolved `size`.";
+    readonly 'data-variant': "On the root: `peek` with `variant=\"peek\"`.";
+};
+/** The name of a Collapsible data attribute. */
+export type CollapsibleDataAttribute = keyof typeof collapsibleDataAttributes;
+export declare const collapsibleCssVariables: {
+    readonly '--disclosure-panel-height': "On the panel: its measured height in px while it animates, `auto` once open and `0px` once closed.";
+};
+/** The name of a Collapsible CSS variable. */
+export type CollapsibleCssVariable = keyof typeof collapsibleCssVariables;

package/dist/components/Collapsible/collapsible.attributes.js

@@ -0,0 +1,17 @@
+/**
+ * The styling hooks a Collapsible exposes. Attributes are presence attributes (`''` while the
+ * state holds, omitted otherwise) unless the description says they carry a value.
+ */
+export const collapsibleDataAttributes = {
+    'data-open': 'On the root, the trigger, the panel and the content: present while open.',
+    'data-closed': 'On the root, the trigger, the panel and the content: present while closed, including during the exit transition.',
+    'data-entering': 'On the root and the panel (`variant="peek"` has no separate panel): present while the opening animation plays.',
+    'data-exiting': 'On the root and the panel (`variant="peek"` has no separate panel): present while the closing animation plays.',
+    'data-disabled': 'On the root, the trigger, the panel and the content: present while `disabled`.',
+    'data-state': 'On the root, the trigger, the panel and the content: `open` or `closed` (kept for compatibility; prefer `data-open` / `data-closed`).',
+    'data-size': 'On the root: the resolved `size`.',
+    'data-variant': 'On the root: `peek` with `variant="peek"`.'
+};
+export const collapsibleCssVariables = {
+    '--disclosure-panel-height': 'On the panel: its measured height in px while it animates, `auto` once open and `0px` once closed.'
+};

package/dist/components/Collapsible/collapsible.mcp.d.ts

@@ -1 +1 @@
-export declare const collapsibleDescription = "\n# Collapsible Component\n\nThe Collapsible component provides a way to show and hide content with a toggle trigger. It supports both controlled and uncontrolled modes, keyboard navigation, and smooth slide transitions.\n\n## Basic Usage\n\n```svelte\n<Collapsible>\n\t{#snippet trigger()}\n\t\tClick to expand\n\t{/snippet}\n\tThis content will be shown when expanded.\n</Collapsible>\n```\n\n## Props\n\n### Core Props\n- **open**: boolean (optional)\n  - Current bindable disclosure state.\n\n- **defaultOpen**: boolean (default: false)\n  - Initial open state when `open` is omitted.\n  - Ignored when `open` prop is provided.\n\n- **disabled**: boolean (default: false)\n  - Disables the collapsible trigger and prevents toggling.\n  - Applies opacity styling and removes pointer events.\n\n- **onOpenChange**: (open: boolean) => void (optional)\n  - Callback fired once after a component-owned open state change.\n  - Receives the new open state as parameter.\n\n### Layout Props\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - Controls padding and text size of trigger and content.\n  - small: Reduced padding (py-2 px-2) and text-sm\n  - normal: Standard padding (py-3 px-4) and text-base\n  - large: Increased padding (py-4 px-6) and text-lg\n\n- **icon**: 'chevron' | 'plus-minus' | 'none' | Snippet (default: 'chevron')\n  - Disclosure indicator rendered in the trigger.\n  - chevron: rotating chevron; plus-minus: plus/minus glyph; none: no indicator.\n  - Pass a snippet (it receives `{ open }`) for a custom icon.\n\n### Content Props (Slots)\n- **trigger**: Snippet - Content rendered in the toggle button\n  - Required for the component to function\n  - Typically contains text, icons, or both\n\n- **children**: Snippet<{ open: boolean }> - Content shown when expanded\n  - Rendered inside the content container with a slide transition\n  - Receives the current `open` state as a payload\n\n### Advanced Props\n- **theme**: CollapsibleThemeProps - Theme configuration overrides\n  - Allows customizing styles for container, trigger, and content parts\n\n## Examples\n\n### Example 1 - Uncontrolled\n```svelte\n<script lang=\"ts\">\n\timport { Collapsible } from 'entasis/collapsible';\n\timport { caretDownIcon } from 'entasis/icons/caretDown';\n</script>\n\n<Collapsible defaultOpen={false} icon=\"none\">\n\t{#snippet trigger()}\n\t\t<span>Toggle Content</span>\n\t\t{@render caretDownIcon()}\n\t{/snippet}\n\t<p>This content can be toggled.</p>\n</Collapsible>\n```\n\n### Example 2 - Controlled\n```svelte\n<script>\n\tlet open = false;\n</script>\n\n<Collapsible bind:open={open} onOpenChange={(open) => console.log('State:', open)}>\n\t{#snippet trigger()}\n\t\tToggle (Currently: {open ? 'Open' : 'Closed'})\n\t{/snippet}\n\t<p>Controlled content</p>\n</Collapsible>\n```\n\n### Example 3 - Explicit Children Snippet\n```svelte\n<Collapsible>\n\t{#snippet trigger()}\n\t\tShow Details\n\t{/snippet}\n\t{#snippet children({ open })}\n\t\t<p>This panel is {open ? 'open' : 'closed'}.</p>\n\t\t<ul>\n\t\t\t<li>Item 1</li>\n\t\t\t<li>Item 2</li>\n\t\t</ul>\n\t{/snippet}\n</Collapsible>\n```\n\n### Example 4 - Disabled State\n```svelte\n<Collapsible disabled={true}>\n\t{#snippet trigger()}\n\t\tDisabled Collapsible\n\t{/snippet}\n\tThis content cannot be toggled.\n</Collapsible>\n```\n\n### Example 5 - Different Sizes\n```svelte\n<Collapsible size=\"small\">\n\t{#snippet trigger()}\n\t\tSmall Collapsible\n\t{/snippet}\n\tSmall content\n</Collapsible>\n\n<Collapsible size=\"large\">\n\t{#snippet trigger()}\n\t\tLarge Collapsible\n\t{/snippet}\n\tLarge content\n</Collapsible>\n```\n\n## Structure\n\nThe component renders:\n- A container `<div>` with data attributes for state\n- A trigger `<button>` with ARIA attributes\n- A content `<div>` with slide transition (only when open)\n\n## Accessibility\n\n- **ARIA Attributes**:\n  - `aria-expanded` on trigger indicates open/closed state\n  - `aria-controls` links trigger to content element\n  - `data-state` attribute provides state information for styling\n\n- **Keyboard Support**:\n  - **Enter** or **Space**: Toggles the collapsible\n  - Focus management handled by browser default behavior\n\n- **Semantic HTML**:\n  - Uses `<button>` element for trigger (proper focus and keyboard handling)\n  - Content is hidden from accessibility tree when closed\n\n## Notes\n\n- The component uses Svelte's built-in `slide` transition with a 200ms duration.\n- When `open` prop is provided, the component is controlled. Otherwise, it manages its own state.\n- Content is completely removed from DOM when closed (not just hidden) for better performance.\n\n## Theme Customization\n\nThe Collapsible component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main collapsible container styles\n- **trigger**: Toggle trigger button styles\n- **content**: Collapsible content panel styles\n- **icon**: Expand/collapse icon styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for main container\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Container size\n\n**trigger**:\n- base: Base classes for trigger button\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Trigger padding and text size\n  - disabled: boolean - Disabled state styling\n\n**content**:\n- base: Base classes for content panel\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content gap and text size\n\n**icon**:\n- base: Base classes for expand/collapse icon\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Collapsible \n  theme={{\n    root: {\n      base: 'w-full'\n    },\n    trigger: {\n      base: 'flex items-center justify-between w-full',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    }\n  }}\n>\n  {#snippet trigger()}\n    Toggle\n  {/snippet}\n  Content\n</Collapsible>\n```\n\n**Custom Trigger Styling**:\n```svelte\n<Collapsible \n  theme={{\n    trigger: {\n      base: 'state-layer rounded-lg transition-colors',\n      size: {\n        large: 'px-6 py-4 text-lg'\n      },\n      disabled: {\n        true: 'opacity-50 cursor-not-allowed'\n      }\n    },\n    icon: {\n      size: {\n        normal: 'size-5'\n      }\n    }\n  }}\n>\n  {#snippet trigger()}\n    Custom Trigger\n  {/snippet}\n  Content\n</Collapsible>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setCollapsibleTheme } from './index.ts';\n  \n  setCollapsibleTheme({\n    root: {\n      base: 'w-full flex flex-col'\n    },\n    trigger: {\n      base: 'transition-all hover:opacity-80',\n      size: {\n        normal: 'px-2 py-2 text-sm'\n      }\n    },\n    content: {\n      size: {\n        normal: 'gap-2 mt-2'\n      }\n    }\n  });\n</script>\n```\n\n## Motion\n\n- **motion** theme slot, keyed by `variant`: `default` slides the content open on the y axis,\n  `peek` animates its clip height on `slow` / `enter`.\n- Ladder: `<Theme components={{ collapsible: { motion } }}>` \u2192 `setCollapsibleTheme({ motion })`\n  \u2192 `theme.motion` \u2192 the `transition` prop. Reduced motion collapses it to 0.\n";
+export declare const collapsibleDescription = "\n# Collapsible Component\n\nThe Collapsible component provides a way to show and hide content with a toggle trigger. It supports both controlled and uncontrolled modes, keyboard navigation, and smooth slide transitions.\n\n## Basic Usage\n\n```svelte\n<Collapsible>\n\t{#snippet trigger()}\n\t\tClick to expand\n\t{/snippet}\n\tThis content will be shown when expanded.\n</Collapsible>\n```\n\n## Props\n\n### Core Props\n- **open**: boolean (optional)\n  - Current bindable disclosure state.\n\n- **defaultOpen**: boolean (default: false)\n  - Initial open state when `open` is omitted.\n  - Ignored when `open` prop is provided.\n\n- **disabled**: boolean (default: false)\n  - Disables the collapsible trigger and prevents toggling.\n  - Applies opacity styling and removes pointer events.\n\n- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void (optional)\n  - Called before a component-owned open state change: a trigger press or the browser's find-in-page.\n  - `open` is the requested state. `details.reason` is `'trigger-press'` or `'find-in-page'`, `details.event` carries the DOM event, and `details.cancel()` keeps the collapsible as it was. See `entasis/types` for `OpenChangeDetails`.\n  - Not called for initialization or for changes the parent assigns to `open`.\n\n- **onAfterOpen** / **onAfterClose**: () => void (optional)\n  - Called once each time an open or close finishes: after the slide, or at once when no animation plays (reduced motion, zero duration, find-in-page), also when the panel is removed mid-close. Not called for the initial state.\n\n- **hiddenUntilFound**: boolean (default: false)\n  - Keeps the closed content in the DOM under `hidden=\"until-found\"`, so the browser's find-in-page, text fragments and `#id` links reach it and open the collapsible (reason `find-in-page`, no animation).\n  - Closed content stays out of the accessibility tree and the tab order until then. Cancelling the open-change leaves it closed and findable.\n  - A disabled collapsible is not findable: its closed content stays under plain `hidden`.\n  - Only the content is skipped while closed, so keep padding, gaps and margins on an element inside the panel (the `content` theme slot already is).\n\n- **keepMounted**: boolean (default: false)\n  - Keeps the closed content mounted under `hidden`, preserving its state (form values, scroll, media). Not findable by the browser.\n\n### Layout Props\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - Controls padding and text size of trigger and content.\n  - small: Reduced padding (py-2 px-2) and text-sm\n  - normal: Standard padding (py-3 px-4) and text-base\n  - large: Increased padding (py-4 px-6) and text-lg\n\n- **icon**: 'chevron' | 'plus-minus' | 'none' | Snippet (default: 'chevron')\n  - Disclosure indicator rendered in the trigger.\n  - chevron: rotating chevron; plus-minus: plus/minus glyph; none: no indicator.\n  - Pass a snippet (it receives `{ open }`) for a custom icon.\n\n### Content Props (Slots)\n- **trigger**: Snippet - Content rendered in the toggle button\n  - Required for the component to function\n  - Typically contains text, icons, or both\n\n- **children**: Snippet<{ open: boolean }> - Content shown when expanded\n  - Rendered inside the content container, animated by height\n  - Receives the current `open` state as a payload\n\n### Advanced Props\n- **theme**: CollapsibleThemeProps - Theme configuration overrides\n  - Allows customizing styles for container, trigger, and content parts\n\n- **variant**: 'default' | 'peek' (default: 'default')\n  - `peek` keeps the content mounted, clips it to `peekHeight` and fades the edge while closed. While closed, links and controls below the visible preview are inert so Tab never lands on clipped content. The clipped text itself stays in the accessibility tree (the clip is visual only, like a read-more preview), so screen readers read all of it. `hiddenUntilFound` and `keepMounted` apply to `default` only.\n\n## Examples\n\n### Example 1 - Uncontrolled\n```svelte\n<script lang=\"ts\">\n\timport { Collapsible } from 'entasis/collapsible';\n\timport { caretDownIcon } from 'entasis/icons/caretDown';\n</script>\n\n<Collapsible defaultOpen={false} icon=\"none\">\n\t{#snippet trigger()}\n\t\t<span>Toggle Content</span>\n\t\t{@render caretDownIcon()}\n\t{/snippet}\n\t<p>This content can be toggled.</p>\n</Collapsible>\n```\n\n### Example 2 - Controlled\n```svelte\n<script>\n\tlet open = false;\n</script>\n\n<Collapsible bind:open={open} onOpenChange={(open) => console.log('State:', open)}>\n\t{#snippet trigger()}\n\t\tToggle (Currently: {open ? 'Open' : 'Closed'})\n\t{/snippet}\n\t<p>Controlled content</p>\n</Collapsible>\n```\n\n### Example 3 - Explicit Children Snippet\n```svelte\n<Collapsible>\n\t{#snippet trigger()}\n\t\tShow Details\n\t{/snippet}\n\t{#snippet children({ open })}\n\t\t<p>This panel is {open ? 'open' : 'closed'}.</p>\n\t\t<ul>\n\t\t\t<li>Item 1</li>\n\t\t\t<li>Item 2</li>\n\t\t</ul>\n\t{/snippet}\n</Collapsible>\n```\n\n### Example 4 - Disabled State\n```svelte\n<Collapsible disabled={true}>\n\t{#snippet trigger()}\n\t\tDisabled Collapsible\n\t{/snippet}\n\tThis content cannot be toggled.\n</Collapsible>\n```\n\n### Example 5 - Different Sizes\n```svelte\n<Collapsible size=\"small\">\n\t{#snippet trigger()}\n\t\tSmall Collapsible\n\t{/snippet}\n\tSmall content\n</Collapsible>\n\n<Collapsible size=\"large\">\n\t{#snippet trigger()}\n\t\tLarge Collapsible\n\t{/snippet}\n\tLarge content\n</Collapsible>\n```\n\n### Example 6 - Find in page\n```svelte\n<!-- Ctrl+F for \"refund window\" opens the collapsible; onOpenChange reports reason 'find-in-page'. -->\n<Collapsible hiddenUntilFound onOpenChange={(open, details) => console.log(open, details.reason)}>\n\t{#snippet trigger()}\n\t\tRefund policy\n\t{/snippet}\n\t<p>The refund window is 30 days.</p>\n</Collapsible>\n```\n\n## Structure\n\nThe component renders:\n- A container `<div>` with data attributes for state\n- A trigger `<button>` with ARIA attributes\n- A content panel `<div>` (only when open, or while closed with `keepMounted` / `hiddenUntilFound`) holding the themed content `<div>`; it carries `hidden` or `hidden=\"until-found\"` while closed\n- Styling hooks: `data-open` / `data-closed` on the root, trigger and content, `data-disabled`, and `data-entering` / `data-exiting` on the root and panel; the panel exposes `--disclosure-panel-height` while it animates\n\n## Styling hooks\n\nEvery part carries the open state, so a `data-open:` variant styles it without reading component state.\n\nAttributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.\n\n**Data attributes**\n- `data-open`: On the root, the trigger, the panel and the content: present while open.\n- `data-closed`: On the root, the trigger, the panel and the content: present while closed, including during the exit transition.\n- `data-entering`: On the root and the panel (`variant=\"peek\"` has no separate panel): present while the opening animation plays.\n- `data-exiting`: On the root and the panel (`variant=\"peek\"` has no separate panel): present while the closing animation plays.\n- `data-disabled`: On the root, the trigger, the panel and the content: present while `disabled`.\n- `data-state`: On the root, the trigger, the panel and the content: `open` or `closed` (kept for compatibility; prefer `data-open` / `data-closed`).\n- `data-size`: On the root: the resolved `size`.\n- `data-variant`: On the root: `peek` with `variant=\"peek\"`.\n\n**CSS variables**\n- `--disclosure-panel-height`: On the panel: its measured height in px while it animates, `auto` once open and `0px` once closed.\n\nThe typed maps `collapsibleDataAttributes` and `collapsibleCssVariables` (from `entasis/collapsible`) list each name with its meaning.\n\n## Accessibility\n\n- **ARIA Attributes**:\n  - `aria-expanded` on trigger indicates open/closed state\n  - `aria-controls` links trigger to the content element while it exists in the DOM\n  - `data-state` attribute provides state information for styling\n\n- **Keyboard Support**:\n  - **Enter** or **Space**: Toggles the collapsible\n  - Focus management handled by browser default behavior\n\n- **Semantic HTML**:\n  - Uses `<button>` element for trigger (proper focus and keyboard handling)\n  - Closed content is not in the DOM (or is `hidden` / `hidden=\"until-found\"`), so it is neither read nor tabbable\n\n## Notes\n\n- The panel animates its height with the theme's `motion` slot (`duration`, `delay`, `easing`); reduced motion disables it.\n- Migration: the `accessible` and `srOnlyContent` props are removed. They rendered the closed content visibly; use `hiddenUntilFound` or `keepMounted` instead.\n- When `open` prop is provided, the component is controlled. Otherwise, it manages its own state.\n- Content is removed from the DOM when closed unless `keepMounted` or `hiddenUntilFound` is set.\n\n## Theme Customization\n\nThe Collapsible component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main collapsible container styles\n- **trigger**: Toggle trigger button styles\n- **content**: Collapsible content styles, on the element inside the panel\n- **icon**: Expand/collapse icon styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for main container\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Container size\n\n**trigger**:\n- base: Base classes for trigger button\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Trigger padding and text size\n  - disabled: boolean - Disabled state styling\n\n**content**:\n- base: Base classes for content panel\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content gap and text size\n\n**icon**:\n- base: Base classes for expand/collapse icon\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Collapsible \n  theme={{\n    root: {\n      base: 'w-full'\n    },\n    trigger: {\n      base: 'flex items-center justify-between w-full',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    }\n  }}\n>\n  {#snippet trigger()}\n    Toggle\n  {/snippet}\n  Content\n</Collapsible>\n```\n\n**Custom Trigger Styling**:\n```svelte\n<Collapsible \n  theme={{\n    trigger: {\n      base: 'state-layer rounded-lg transition-colors',\n      size: {\n        large: 'px-6 py-4 text-lg'\n      },\n      disabled: {\n        true: 'opacity-50 cursor-not-allowed'\n      }\n    },\n    icon: {\n      size: {\n        normal: 'size-5'\n      }\n    }\n  }}\n>\n  {#snippet trigger()}\n    Custom Trigger\n  {/snippet}\n  Content\n</Collapsible>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setCollapsibleTheme } from './index.ts';\n  \n  setCollapsibleTheme({\n    root: {\n      base: 'w-full flex flex-col'\n    },\n    trigger: {\n      base: 'transition-all hover:opacity-80',\n      size: {\n        normal: 'px-2 py-2 text-sm'\n      }\n    },\n    content: {\n      size: {\n        normal: 'gap-2 mt-2'\n      }\n    }\n  });\n</script>\n```\n\n## Motion\n\n- **motion** theme slot, keyed by `variant`: `default` animates the panel's height with the\n  preset's `duration` / `delay` / `easing`, `peek` animates its clip height on `slow` / `enter`.\n- Ladder: `<Theme components={{ collapsible: { motion } }}>` \u2192 `setCollapsibleTheme({ motion })`\n  \u2192 `theme.motion` \u2192 the `transition` prop. Reduced motion collapses it to 0.\n";

package/dist/components/Collapsible/collapsible.mcp.js

@@ -28,9 +28,22 @@ The Collapsible component provides a way to show and hide content with a toggle
   - Disables the collapsible trigger and prevents toggling.
   - Applies opacity styling and removes pointer events.
 
-- **onOpenChange**: (open: boolean) => void (optional)
-  - Callback fired once after a component-owned open state change.
-  - Receives the new open state as parameter.
+- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void (optional)
+  - Called before a component-owned open state change: a trigger press or the browser's find-in-page.
+  - \`open\` is the requested state. \`details.reason\` is \`'trigger-press'\` or \`'find-in-page'\`, \`details.event\` carries the DOM event, and \`details.cancel()\` keeps the collapsible as it was. See \`entasis/types\` for \`OpenChangeDetails\`.
+  - Not called for initialization or for changes the parent assigns to \`open\`.
+
+- **onAfterOpen** / **onAfterClose**: () => void (optional)
+  - Called once each time an open or close finishes: after the slide, or at once when no animation plays (reduced motion, zero duration, find-in-page), also when the panel is removed mid-close. Not called for the initial state.
+
+- **hiddenUntilFound**: boolean (default: false)
+  - Keeps the closed content in the DOM under \`hidden="until-found"\`, so the browser's find-in-page, text fragments and \`#id\` links reach it and open the collapsible (reason \`find-in-page\`, no animation).
+  - Closed content stays out of the accessibility tree and the tab order until then. Cancelling the open-change leaves it closed and findable.
+  - A disabled collapsible is not findable: its closed content stays under plain \`hidden\`.
+  - Only the content is skipped while closed, so keep padding, gaps and margins on an element inside the panel (the \`content\` theme slot already is).
+
+- **keepMounted**: boolean (default: false)
+  - Keeps the closed content mounted under \`hidden\`, preserving its state (form values, scroll, media). Not findable by the browser.
 
 ### Layout Props
 - **size**: 'small' | 'normal' | 'large' (default: 'normal')
@@ -50,13 +63,16 @@ The Collapsible component provides a way to show and hide content with a toggle
   - Typically contains text, icons, or both
 
 - **children**: Snippet<{ open: boolean }> - Content shown when expanded
-  - Rendered inside the content container with a slide transition
+  - Rendered inside the content container, animated by height
   - Receives the current \`open\` state as a payload
 
 ### Advanced Props
 - **theme**: CollapsibleThemeProps - Theme configuration overrides
   - Allows customizing styles for container, trigger, and content parts
 
+- **variant**: 'default' | 'peek' (default: 'default')
+  - \`peek\` keeps the content mounted, clips it to \`peekHeight\` and fades the edge while closed. While closed, links and controls below the visible preview are inert so Tab never lands on clipped content. The clipped text itself stays in the accessibility tree (the clip is visual only, like a read-more preview), so screen readers read all of it. \`hiddenUntilFound\` and \`keepMounted\` apply to \`default\` only.
+
 ## Examples
 
 ### Example 1 - Uncontrolled
@@ -132,18 +148,51 @@ The Collapsible component provides a way to show and hide content with a toggle
 </Collapsible>
 \`\`\`
 
+### Example 6 - Find in page
+\`\`\`svelte
+<!-- Ctrl+F for "refund window" opens the collapsible; onOpenChange reports reason 'find-in-page'. -->
+<Collapsible hiddenUntilFound onOpenChange={(open, details) => console.log(open, details.reason)}>
+	{#snippet trigger()}
+		Refund policy
+	{/snippet}
+	<p>The refund window is 30 days.</p>
+</Collapsible>
+\`\`\`
+
 ## Structure
 
 The component renders:
 - A container \`<div>\` with data attributes for state
 - A trigger \`<button>\` with ARIA attributes
-- A content \`<div>\` with slide transition (only when open)
+- A content panel \`<div>\` (only when open, or while closed with \`keepMounted\` / \`hiddenUntilFound\`) holding the themed content \`<div>\`; it carries \`hidden\` or \`hidden="until-found"\` while closed
+- Styling hooks: \`data-open\` / \`data-closed\` on the root, trigger and content, \`data-disabled\`, and \`data-entering\` / \`data-exiting\` on the root and panel; the panel exposes \`--disclosure-panel-height\` while it animates
+
+## Styling hooks
+
+Every part carries the open state, so a \`data-open:\` variant styles it without reading component state.
+
+Attributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.
+
+**Data attributes**
+- \`data-open\`: On the root, the trigger, the panel and the content: present while open.
+- \`data-closed\`: On the root, the trigger, the panel and the content: present while closed, including during the exit transition.
+- \`data-entering\`: On the root and the panel (\`variant="peek"\` has no separate panel): present while the opening animation plays.
+- \`data-exiting\`: On the root and the panel (\`variant="peek"\` has no separate panel): present while the closing animation plays.
+- \`data-disabled\`: On the root, the trigger, the panel and the content: present while \`disabled\`.
+- \`data-state\`: On the root, the trigger, the panel and the content: \`open\` or \`closed\` (kept for compatibility; prefer \`data-open\` / \`data-closed\`).
+- \`data-size\`: On the root: the resolved \`size\`.
+- \`data-variant\`: On the root: \`peek\` with \`variant="peek"\`.
+
+**CSS variables**
+- \`--disclosure-panel-height\`: On the panel: its measured height in px while it animates, \`auto\` once open and \`0px\` once closed.
+
+The typed maps \`collapsibleDataAttributes\` and \`collapsibleCssVariables\` (from \`entasis/collapsible\`) list each name with its meaning.
 
 ## Accessibility
 
 - **ARIA Attributes**:
   - \`aria-expanded\` on trigger indicates open/closed state
-  - \`aria-controls\` links trigger to content element
+  - \`aria-controls\` links trigger to the content element while it exists in the DOM
   - \`data-state\` attribute provides state information for styling
 
 - **Keyboard Support**:
@@ -152,13 +201,14 @@ The component renders:
 
 - **Semantic HTML**:
   - Uses \`<button>\` element for trigger (proper focus and keyboard handling)
-  - Content is hidden from accessibility tree when closed
+  - Closed content is not in the DOM (or is \`hidden\` / \`hidden="until-found"\`), so it is neither read nor tabbable
 
 ## Notes
 
-- The component uses Svelte's built-in \`slide\` transition with a 200ms duration.
+- The panel animates its height with the theme's \`motion\` slot (\`duration\`, \`delay\`, \`easing\`); reduced motion disables it.
+- Migration: the \`accessible\` and \`srOnlyContent\` props are removed. They rendered the closed content visibly; use \`hiddenUntilFound\` or \`keepMounted\` instead.
 - When \`open\` prop is provided, the component is controlled. Otherwise, it manages its own state.
-- Content is completely removed from DOM when closed (not just hidden) for better performance.
+- Content is removed from the DOM when closed unless \`keepMounted\` or \`hiddenUntilFound\` is set.
 
 ## Theme Customization
 
@@ -169,7 +219,7 @@ The Collapsible component uses a theme object that can be customized using the \
 The theme object contains the following parts:
 - **root**: Main collapsible container styles
 - **trigger**: Toggle trigger button styles
-- **content**: Collapsible content panel styles
+- **content**: Collapsible content styles, on the element inside the panel
 - **icon**: Expand/collapse icon styles
 
 ### Available Variants
@@ -272,8 +322,8 @@ The theme object contains the following parts:
 
 ## Motion
 
-- **motion** theme slot, keyed by \`variant\`: \`default\` slides the content open on the y axis,
-  \`peek\` animates its clip height on \`slow\` / \`enter\`.
+- **motion** theme slot, keyed by \`variant\`: \`default\` animates the panel's height with the
+  preset's \`duration\` / \`delay\` / \`easing\`, \`peek\` animates its clip height on \`slow\` / \`enter\`.
 - Ladder: \`<Theme components={{ collapsible: { motion } }}>\` → \`setCollapsibleTheme({ motion })\`
   → \`theme.motion\` → the \`transition\` prop. Reduced motion collapses it to 0.
 `;

package/dist/components/Collapsible/collapsible.props.d.ts

@@ -3,6 +3,7 @@ import type { ResponsiveProps } from '../Theme/theme.js';
 import type { FSOProps } from '../../transitions/transition.js';
 import type { WithSlot, Slot } from '../Slot/slot.js';
 import type { WithAttachments } from '../../types/props.js';
+import type { OpenChangeHandler } from '../../utils/openChange.js';
 import type { CollapsibleThemeProps } from './collapsible.theme.js';
 type CollapsibleBaseProps = {
     /**
@@ -26,9 +27,40 @@ type CollapsibleBaseProps = {
      */
     disabled?: boolean;
     /**
-     * Callback fired when the open state changes.
+     * Called before the open state changes, whenever the user (a trigger press, or the browser's
+     * find-in-page reaching hidden content) or an imperative call asks to open or close it.
+     * `details.reason` says why, `details.event` carries the DOM event, and `details.cancel()`
+     * keeps the collapsible as it was. Inside the callback `open` still holds the previous state.
+     * Not called for initialization or for changes the parent assigns to `open`.
      */
-    onOpenChange?: ((open: boolean) => void) | null | undefined;
+    onOpenChange?: OpenChangeHandler | null | undefined;
+    /**
+     * Called once each time an open finishes: after the slide, or at once when no animation runs
+     * (reduced motion, a zero duration, find-in-page). Not called for the initial state.
+     */
+    onAfterOpen?: () => void;
+    /**
+     * Called once each time a close finishes: after the slide, at once when no animation runs, or
+     * when the panel is removed mid-close. Not called for the initial state.
+     */
+    onAfterClose?: () => void;
+    /**
+     * Keeps the closed content in the DOM under `hidden="until-found"`, so the browser's
+     * find-in-page, text fragments and `#id` links can reach it and open the collapsible
+     * (reason `find-in-page`, no animation). Closed content is hidden from assistive technology
+     * and from the tab order until then. A parent that refuses the change leaves it closed. A disabled
+     * collapsible is not findable: its closed content stays under plain `hidden`.
+     * Applies to the `default` variant; `peek` always keeps its content mounted.
+     * @default false
+     */
+    hiddenUntilFound?: boolean;
+    /**
+     * Keeps the closed content mounted under `hidden`, preserving its state (form values, scroll,
+     * media). It is not findable by the browser; use `hiddenUntilFound` for that. Applies to the
+     * `default` variant.
+     * @default false
+     */
+    keepMounted?: boolean;
     /**
      * Size variant of the collapsible.
      */
@@ -42,14 +74,13 @@ type CollapsibleBaseProps = {
      * Theme configuration overrides.
      */
     theme?: CollapsibleThemeProps;
-    /**
-     * Whether the collapsible is accessible.
-     */
-    accessible?: boolean;
     /**
      * Visual variant. `default` toggles the content in and out with a slide.
      * `peek` keeps the content mounted, clips it to `peekHeight` and fades the
-     * edge while closed, with the trigger floating as a pill over the fade.
+     * edge while closed, with the trigger floating as a pill over the fade; links and controls
+     * below the visible preview are inert until it opens. The clipped text stays in the
+     * accessibility tree on purpose: the clip is a visual preview, so screen reader users read the
+     * whole content (a "read more" pattern) and the trigger's `aria-expanded` reports the state.
      */
     variant?: 'default' | 'peek';
     /**
@@ -62,7 +93,7 @@ type CollapsibleBaseProps = {
      */
     transition?: ResponsiveProps<FSOProps>;
 };
-type CollapsibleSlotProps = WithSlot<CollapsibleBaseProps, 'trigger' | 'children' | 'srOnlyContent', {
+type CollapsibleSlotProps = WithSlot<CollapsibleBaseProps, 'trigger' | 'children', {
     open: boolean;
 }>;
 export type CollapsibleProps = WithAttachments<CollapsibleSlotProps>;

package/dist/components/Collapsible/collapsible.theme.js

@@ -45,8 +45,10 @@ const defaultCollapsibleContent = cva({
         size: 'normal'
     }
 });
+// The glyph fills the box: drawn at its own 16px it overflowed a small (12px) box downward and
+// sat in the top of a large (20px) one, so the chevron was off the text's centre.
 const defaultCollapsibleIcon = cva({
-    base: 'size-4 transition-transform flex-shrink-0',
+    base: 'size-4 transition-transform flex-shrink-0 [&>svg]:size-full',
     variants: {
         size: {
             small: 'size-3',

package/dist/components/Collapsible/index.d.ts

@@ -2,3 +2,4 @@ export { default as Collapsible } from './Collapsible.svelte';
 export type { CollapsibleProps } from './collapsible.props.js';
 export type { CollapsibleTheme, CollapsibleThemeProps } from './collapsible.theme.js';
 export { collapsibleTheme, setCollapsibleTheme, useCollapsibleTheme } from './collapsible.theme.js';
+export { collapsibleDataAttributes, collapsibleCssVariables, type CollapsibleDataAttribute, type CollapsibleCssVariable } from './collapsible.attributes.js';

package/dist/components/Collapsible/index.js

@@ -1,2 +1,3 @@
 export { default as Collapsible } from './Collapsible.svelte';
 export { collapsibleTheme, setCollapsibleTheme, useCollapsibleTheme } from './collapsible.theme.js';
+export { collapsibleDataAttributes, collapsibleCssVariables } from './collapsible.attributes.js';