entasis 0.11.0 → 0.12.0

package/dist/components/Tabbar/Tabbar.svelte

@@ -5,11 +5,17 @@
 	import { caretUpIcon } from '../Icons/caretUp.js';
 	import { checkIcon } from '../Icons/check.js';
 	import { getTabValue, type TabbarProps } from './tabbar.props.js';
+	import {
+		getDefaultTabValue,
+		getTabValueOrigin,
+		isTabDisabled,
+		useTabSelection
+	} from './tabbar.selection.svelte.js';
 	import { useTabbarTheme } from './tabbar.theme.js';
 	import { useNavigation } from '../../utils/useNavigation.svelte.js';
 	import { useOverflowObserver } from '../../utils/useOverflowObserver.svelte.js';
 	import { useSlidingIndicator } from '../../utils/useSlidingIndicator.svelte.js';
-	import type { Snippet } from 'svelte';
+	import { untrack, type Snippet } from 'svelte';
 	import { createBindableValue } from '../../utils/state.svelte.js';
 	import { useDefaultColor } from '../Theme/theme.state.svelte.js';
 
@@ -22,6 +28,7 @@
 		label,
 		controlsPanels = false,
 		onValueChange,
+		activateOnFocus = true,
 		size = 'normal',
 		orientation = 'horizontal',
 		color,
@@ -34,12 +41,13 @@
 		scrollFade = true,
 		...attachments
 	}: TabbarProps = $props();
+	const origin = untrack(() => getTabValueOrigin(value, defaultValue));
 	const valueState = createBindableValue(
 		() => value,
 		(next) => {
 			value = next;
 		},
-		() => defaultValue ?? (items[0] === undefined ? '' : getTabValue(items[0], 0))
+		() => defaultValue ?? getDefaultTabValue(items)
 	);
 
 	const generatedId = $props.id();
@@ -47,15 +55,28 @@
 	const classes = $derived(useTabbarTheme(theme));
 	const resolvedColor = $derived(useDefaultColor(color));
 	const tabValues = $derived(items.map(getTabValue));
-	/** Index of the active tab; -1 when `value` matches no tab. */
-	const selectedValue = $derived(tabValues.indexOf(valueState.value));
+	// Removing or disabling the selected tab moves the selection to an enabled one, written back
+	// and reported; a value the parent set that names no enabled tab is shown as it is.
+	const selection = useTabSelection({
+		items: () => items,
+		value: () => valueState.value,
+		origin,
+		onFallback: (next, { reason }) => {
+			valueState.value = next;
+			if (reason) onValueChange?.({ value: next, reason });
+		}
+	});
+	/** Index of the active tab; -1 when no tab is selected. */
+	const selectedIndex = $derived(selection.index);
 	const tabId = (index: number) => `${id}-tab-${index}`;
 	const panelId = (index: number) => (controlsPanels ? `${id}-panel-${index}` : undefined);
+	// Every path into a selection (click, focus-follows-selection, menu entry) lands here, so a
+	// disabled tab can never be selected even when a key reaches it while it holds DOM focus.
 	const select = (index: number) => {
-		if (selectedValue === index) return;
+		if (selectedIndex === index || isTabDisabled(items[index])) return;
 		const next = tabValues[index];
 		valueState.value = next;
-		onValueChange?.(next);
+		onValueChange?.({ value: next, reason: 'user' });
 	};
 
 	type NormalizedTab = {
@@ -124,12 +145,18 @@
 		enableHoverFocus: false,
 		onChange: (index) => {
 			// Menu tabs activate manually (via entry selection), never by focus alone —
-			// arrowing onto the trigger must not slide the indicator to it.
-			if (index !== null && index !== selectedValue && !normalizedTabs[index]?.menu) {
+			// arrowing onto the trigger must not slide the indicator to it. With
+			// `activateOnFocus={false}` no tab activates by focus: Enter, Space or a click does.
+			if (
+				activateOnFocus &&
+				index !== null &&
+				index !== selectedIndex &&
+				!normalizedTabs[index]?.menu
+			) {
 				select(index);
 			}
 		},
-		defaultFocusedIndex: () => selectedValue
+		defaultFocusedIndex: () => (selectedIndex >= 0 ? selectedIndex : null)
 	});
 
 	function handleTabClick(event: MouseEvent, index: number, tab: NormalizedTab) {
@@ -138,14 +165,23 @@
 			event.stopPropagation();
 			return;
 		}
-		if (!tab.href) {
-			select(index);
-			navigation.focusItem(index);
-		}
+		// Link tabs select on click too, without preventing navigation: with focus-driven
+		// activation the focus already selected them (select is idempotent), and with
+		// `activateOnFocus={false}` this is their only path to a selection.
+		select(index);
+		if (!tab.href) navigation.focusItem(index);
+	}
+
+	// Enter on an anchor already dispatches a click; Space does not, so a link tab selects on it
+	// here (and keeps the page from scrolling), matching button tabs.
+	function handleTabKeydown(event: KeyboardEvent, index: number, tab: NormalizedTab) {
+		if (event.key !== ' ' || !tab.href || tab.disabled) return;
+		event.preventDefault();
+		select(index);
 	}
 
 	const indicator = useSlidingIndicator({
-		activeIndex: () => selectedValue,
+		activeIndex: () => selectedIndex,
 		observe: () => [
 			items,
 			size,
@@ -211,11 +247,12 @@
 			style={indicator.style}
 			data-color={resolvedColor}
 			data-ready={indicator.isReady ? 'true' : 'false'}
+			hidden={!indicator.isVisible}
 			aria-hidden="true"
 		></div>
 	{/if}
 	{#each normalizedTabs as tab, index (index)}
-		{@const isActive = selectedValue === index}
+		{@const isActive = selectedIndex === index}
 		{@const isFocused = navigation.focusedIndex === index}
 		{@const elementType = tab.href ? 'a' : 'button'}
 
@@ -226,8 +263,9 @@
 				{/if}
 			{/snippet}
 			<PopupMenu
+				{size}
 				position="bottom-start"
-				menu={{ items: menuItemsFor(index, tab), header: menuHeader }}
+				menu={{ items: menuItemsFor(index, tab), header: menuHeader, size }}
 			>
 				{#snippet trigger(popover)}
 					<button
@@ -314,6 +352,7 @@
 					fullWidth
 				})}
 				onclick={(event: MouseEvent) => handleTabClick(event, index, tab)}
+				onkeydown={(event: KeyboardEvent) => handleTabKeydown(event, index, tab)}
 				{@attach navigation.itemReference}
 				{@attach indicator.itemReference(index)}
 			>

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

@@ -1,3 +1,3 @@
 export { default as Tabbar } from './Tabbar.svelte';
-export type { TabbarProps, TabItem, TabAlignment, TabOrientation, TabbarPosition } from './tabbar.props.js';
+export type { TabbarProps, TabItem, TabAlignment, TabOrientation, TabbarPosition, TabbarValueChangePayload, TabbarValueChangeReason } from './tabbar.props.js';
 export { tabbarTheme, setTabbarTheme, useTabbarTheme, type TabbarTheme, type TabbarThemeProps } from './tabbar.theme.js';

package/dist/components/Tabbar/tabbar.mcp.d.ts

@@ -1 +1 @@
-export declare const tabbarDescription = "\n# Tabbar Component\n\nThe Tabbar component is a flexible navigation component that displays a list of tabs with support for active state management, custom styling, icons, and links.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet activeTab = $state('Home');\n</script>\n\n<Tabbar items={['Home', 'Profile', 'Settings']} bind:value={activeTab} />\n```\n\n## Props\n\n### Core Props\n- **items**: Array<string | TabItem> (required)\n  - Array of tab items. Each item can be:\n    - A simple string (e.g., \"Home\")\n    - A TabItem object with: { value?, label, prefix?, suffix?, href?, disabled?, target?, rel? }\n  - Every tab resolves to a string value: its `value`, else its string label, else its index as a string (`getTabValue(item, index)` is exported from `entasis/tabbar`)\n\n- **value**: string (default: the first tab's value, bindable)\n  - The value of the currently active tab (a string item is its own value)\n  - Can be bound with `bind:value`\n- **defaultValue**: string - Initial active tab value when value is omitted\n\n- **onValueChange**: (value: string) => void\n  - Callback function called when the active tab changes\n  - Receives the new tab's value as an argument; not called when the current tab is re-selected\n\n### Styling Props\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - small: Compact size with smaller padding and text\n  - normal: Standard size\n  - large: Larger size with more padding\n\n- **orientation**: 'horizontal' | 'vertical' (default: 'horizontal')\n  - horizontal: Tabs arranged in a row\n  - vertical: Tabs arranged in a column\n\n- **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' (default: 'primary')\n  - Determines the color scheme of the active tab\n\n- **variant**: 'underline' | 'pill' (default: 'underline')\n  - underline: a colored bar slides along the active tab edge (side set by position)\n  - pill: a rounded track where the active tab is a raised pill; the pill slides and resizes between tabs with the same animation\n  - Both variants respect the color prop: the underline bar and the pill fill use color, and the active pill's label uses the color's contrast tone (use color='neutral' for a neutral pill)\n  - The indicator is correct during SSR (a CSS-only bar rendered in the active tab) and hands off to a single measured element that slides after hydration, so it adapts to variable tab widths and to the vertical orientation\n\n- **alignment**: 'start' | 'center' | 'end' (default: 'start')\n  - start: Tabs aligned to the start of the container\n  - center: Tabs centered in the container\n  - end: Tabs aligned to the end of the container\n\n- **fullWidth**: boolean (default: false)\n  - Whether the tabbar should be full width\n  - When true, the tabbar and individual tabs will expand to fill the available width\n\n- **scrollFade**: boolean (default: true)\n  - Applies the shared logical-axis scroll fade only while the tab list overflows\n\n### Advanced Props\n- **label**: string - Accessible name for the tab list, applied as aria-label. Give one to every page that shows more than one set of tabs\n- **id**: string - DOM id prefix for the tabs; each tab renders as `{id}-tab-{index}`. Generated when omitted\n- **controlsPanels**: boolean (default: false) - Adds `aria-controls=\"{id}-panel-{index}\"` to every tab. `Tabs` sets it and renders the matching panels; only enable it yourself when you render panels with those ids\n- **ref**: HTMLDivElement | null (bindable) - Reference to the tab list element\n- **class**: string - Additional CSS classes for the tabbar container\n- **theme**: TabbarThemeProps - Custom theme overrides\n\nNative div attributes and attachments are forwarded to the root, minus the ARIA the tab list owns: `role`, `aria-orientation` (from `orientation`), and its accessible name (from `label`) are written by the component and cannot be overridden. Horizontal and vertical overflow use the shared `scroll-fade-x` and `scroll-fade-y` utilities by default; non-overflowing tab lists remain unmasked, including in no-support fallback browsers.\n\n## TabItem Structure\n\nWhen using object format for items:\n\n```typescript\ntype TabItem = {\n  value?: string;                // Stable identifier; defaults to the string label\n  label: string | Snippet;      // Tab label (required)\n  prefix?: Snippet;              // Icon or content before label\n  suffix?: Snippet;              // Icon or content after label\n  href?: string;                 // URL for navigation tabs\n  disabled?: boolean;            // Disable the tab\n  target?: string;               // Link target (e.g., \"_blank\")\n  rel?: string;                  // Link relationship\n  menu?: string[];               // Entries shown in a popover menu (overflow pattern)\n  onSelect?: (menuIndex: number) => void; // Called when a menu entry is picked\n}\n```\n\n### Menu tab (overflow pattern)\n\nA tab with `menu` renders with a chevron and opens a popover menu instead of activating directly. Selecting an entry activates the tab, displays the entry's label on it (the tab's own label becomes the menu header), slides the indicator to it, and calls `onSelect(menuIndex)`. The selected entry shows a check mark in the menu.\n\n```svelte\n<Tabbar\n\titems={['Home', 'Projects', { label: 'More', menu: ['Analytics', 'Reports', 'Billing'] }]}\n\tbind:value={activeTab}\n/>\n```\n\n## Structure\n\nThe tabbar follows this DOM structure:\n```\n<Tabbar>\n\t<Tab>\n\t\t<TabContent>      <!-- Optional wrapper when prefix/suffix exist -->\n\t\t\t<Prefix />      <!-- Optional prefix content -->\n\t\t\t<Label />       <!-- Tab label -->\n\t\t\t<Suffix />      <!-- Optional suffix content -->\n\t\t</TabContent>\n\t</Tab>\n\t<!-- More tabs... -->\n</Tabbar>\n```\n\n## Examples\n\n### Simple String Tabs\n```svelte\n<script>\n\tlet activeTab = $state('Home');\n</script>\n\n<Tabbar \n\titems={['Home', 'About', 'Contact']} \n\tbind:value={activeTab}\n\tcolor=\"primary\"\n/>\n```\n\n### Tabs with Icons\n```svelte\n<script lang=\"ts\">\n\timport { houseIcon } from 'entasis/icons/house';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\n\tlet activeTab = $state('Home');\n\n\tconst tabs = [\n\t\t{\n\t\t\tlabel: 'Home',\n\t\t\tprefix: houseIcon\n\t\t},\n\t\t{\n\t\t\tlabel: 'Profile',\n\t\t\tprefix: userIcon\n\t\t},\n\t\t{\n\t\t\tlabel: 'Settings',\n\t\t\tprefix: gearIcon\n\t\t}\n\t];\n</script>\n\n<Tabbar items={tabs} bind:value={activeTab} />\n```\n\n### Navigation Tabs (with links)\n```svelte\n<script>\n\tconst tabs = [\n\t\t{ label: 'Dashboard', href: '/dashboard' },\n\t\t{ label: 'Analytics', href: '/analytics' },\n\t\t{ label: 'Reports', href: '/reports' }\n\t];\n</script>\n\n<Tabbar items={tabs} />\n```\n\n### Tabs with Disabled State\n```svelte\n<script>\n\tlet activeTab = $state('Enabled Tab');\n\t\n\tconst tabs = [\n\t\t{ label: 'Enabled Tab' },\n\t\t{ label: 'Disabled Tab', disabled: true },\n\t\t{ label: 'Another Tab' }\n\t];\n</script>\n\n<Tabbar items={tabs} bind:value={activeTab} />\n```\n\n### Vertical Orientation\n```svelte\n<script>\n\tlet activeTab = $state('First');\n</script>\n\n<Tabbar \n\titems={['First', 'Second', 'Third']} \n\tbind:value={activeTab}\n\torientation=\"vertical\"\n/>\n```\n\n### Different Alignments\n```svelte\n<script>\n\tlet activeTab = $state('One');\n</script>\n\n<!-- Centered tabs -->\n<Tabbar items={['One', 'Two', 'Three']} bind:value={activeTab} alignment=\"center\" />\n\n<!-- Right-aligned tabs -->\n<Tabbar items={['One', 'Two', 'Three']} bind:value={activeTab} alignment=\"end\" />\n```\n\n### Full Width Tabs\n```svelte\n<script>\n\tlet activeTab = $state('Tab 1');\n</script>\n\n<!-- Full width tabbar where tabs expand to fill available space -->\n<Tabbar items={['Tab 1', 'Tab 2', 'Tab 3']} bind:value={activeTab} fullWidth />\n```\n\n### With onValueChange Callback\n```svelte\n<script lang=\"ts\">\n\tlet activeTab = $state('Tab 1');\n\t\n\tfunction handleTabChange(value: string) {\n\t\tconsole.log('Active tab changed to:', value); // e.g. 'Tab 2'\n\t}\n</script>\n\n<Tabbar \n\titems={['Tab 1', 'Tab 2', 'Tab 3']} \n\tbind:value={activeTab}\n\tonValueChange={handleTabChange}\n/>\n```\n\n### Different Sizes and Colors\n```svelte\n<script>\n\tlet activeTab = $state('Small');\n</script>\n\n<!-- Small size with secondary color -->\n<Tabbar \n\titems={['Small', 'Tabs']} \n\tbind:value={activeTab}\n\tsize=\"small\"\n\tcolor=\"secondary\"\n/>\n\n<!-- Large size with success color -->\n<Tabbar \n\titems={['Large', 'Tabs']} \n\tbind:value={activeTab}\n\tsize=\"large\"\n\tcolor=\"success\"\n/>\n```\n\n### Complex Tabs with Badges\n```svelte\n<script>\n\timport { Chip } from 'entasis/chip';\n\t\n\tlet activeTab = $state('Inbox');\n</script>\n\n{#snippet unreadCount()}\n\t<Chip color=\"danger\" size=\"small\">5</Chip>\n{/snippet}\n\n<Tabbar\n\titems={['Inbox', { label: 'Messages', suffix: unreadCount }, 'Sent']}\n\tbind:value={activeTab}\n/>\n```\n\n### External Links\n```svelte\n<script>\n\tconst tabs = [\n\t\t{ label: 'Internal', href: '/dashboard' },\n\t\t{ label: 'External', href: 'https://example.com', target: '_blank', rel: 'noopener' }\n\t];\n</script>\n\n<Tabbar items={tabs} />\n```\n\n## Accessibility\n\nThe Tabbar component follows WAI-ARIA best practices for tablist patterns:\n\n### ARIA Attributes\n- Sets `role=\"tablist\"` on the container\n- Sets `role=\"tab\"` on each tab button\n- Sets `aria-selected=\"true\"` on the active tab, `\"false\"` on others\n- Gives each tab a stable `id` (`{id}-tab-{index}`) and, with `controlsPanels`, an `aria-controls` pointing at its panel\n- Sets `aria-disabled=\"true\"` on disabled tabs\n- Sets `aria-activedescendant` on the container to reference the active tab\n- Implements roving tabindex pattern (active tab has `tabindex=\"0\"`, others have `tabindex=\"-1\"`)\n\n### Keyboard Navigation\nFull keyboard support following WAI-ARIA best practices:\n\n**Horizontal Orientation:**\n- **Arrow Left**: Move focus to previous tab\n- **Arrow Right**: Move focus to next tab\n- **Home**: Move focus to first tab\n- **End**: Move focus to last tab\n- **Enter/Space**: Activate the focused tab\n\n**Vertical Orientation:**\n- **Arrow Up**: Move focus to previous tab\n- **Arrow Down**: Move focus to next tab\n- **Home**: Move focus to first tab\n- **End**: Move focus to last tab\n- **Enter/Space**: Activate the focused tab\n\n**Behavior:**\n- Arrow keys move keyboard **focus** (visual indicator with ring)\n- Enter/Space keys **activate** the focused tab (changes selection)\n- Focus automatically wraps around (loops from last to first and vice versa)\n- Disabled tabs are automatically skipped during navigation\n- Focused tab automatically scrolls into view (smooth scroll)\n- All navigation keys are prevented from scrolling the page\n- Focus ring color matches the tab's color scheme\n\n**Visual States:**\n- **Active tab**: Colored text, background, and bottom/left border\n- **Focused tab**: Ring outline in theme color (keyboard navigation)\n- **Inactive tab**: Neutral gray text with subtle hover effect\n\n## Notes\n\n- When `href` is provided in a tab, it renders as an `<a>` tag, otherwise as a `<button>`\n- Disabled tabs cannot be clicked and do not trigger `onValueChange`\n- The active tab is identified by its string value (a string item's label, or an object item's `value` / string label); give object items an explicit `value` when labels may change or are snippets\n- The `value` prop is bindable for two-way data binding\n- Tabs with `href` will not update `value` on click (they navigate instead)\n- Icon/content sizing is automatically adjusted based on tab size\n- The component is fully responsive and works with all color schemes\n\n## Theme Customization\n\nThe Tabbar 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 tabbar container styles\n- **tab**: Individual tab styles\n- **indicator**: The single measured active indicator that slides between tabs\n- **staticIndicator**: The CSS-only indicator rendered inside the active tab for SSR / pre-hydration\n- **prefix**: Prefix icon/content styles\n- **suffix**: Suffix icon/content styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for tabbar container\n- Variants:\n  - orientation: 'horizontal' | 'vertical' - Tab orientation\n  - scrollFade: 'none' | 'x' | 'y' - Logical-axis scroll fade, applied only while the list overflows\n  - alignment: 'start' | 'center' | 'end' - Tab alignment\n  - size: 'small' | 'normal' | 'large' - Gap between tabs\n  - variant: 'underline' | 'pill' - Track styling\n  - fullWidth: boolean - Expand the tabbar to fill its container\n\n**tab**:\n- base: Base classes for tab items\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Padding, text size and gap\n  - color: Color variants\n  - active: boolean - Active state styling\n  - focused: boolean - Keyboard-focused state styling\n  - disabled: boolean - Disabled state styling\n  - orientation: 'horizontal' | 'vertical'\n  - position: 'top' | 'bottom' | 'left' | 'right' - Indicator edge\n  - variant: 'underline' | 'pill'\n  - fullWidth: boolean\n\n**indicator**:\n- base: Base classes for the sliding active indicator\n- Variants:\n  - variant: 'underline' | 'pill' - Bar or raised pill\n\n**staticIndicator**:\n- base: Base classes for the SSR indicator\n- Variants:\n  - variant: 'underline' | 'pill'\n  - position: 'top' | 'bottom' | 'left' | 'right' - Which tab edge the underline sits on\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Tabbar items={tabs}\n  bind:value={activeTab}\n  theme={{\n    root: {\n      base: 'border-b-2 border-gray-200',\n      size: {\n        normal: 'gap-4'\n      }\n    },\n    tab: {\n      active: {\n        true: 'border-b-2 border-primary'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Active State**:\n```svelte\n<Tabbar items={tabs}\n  bind:value={activeTab}\n  theme={{\n    tab: {\n      active: {\n        true: 'bg-primary text-white rounded-t-lg'\n      }\n    },\n    indicator: {\n      base: 'bg-primary h-1 rounded-full'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setTabbarTheme } from './index.ts';\n  \n  setTabbarTheme({\n    root: {\n      base: 'border-b border-gray-200',\n      size: {\n        normal: 'gap-2'\n      }\n    },\n    tab: {\n      base: 'transition-colors',\n      active: {\n        true: 'text-primary border-b-2 border-primary'\n      }\n    }\n  });\n</script>\n```\n";
+export declare const tabbarDescription = "\n# Tabbar Component\n\nThe Tabbar component is a flexible navigation component that displays a list of tabs with support for active state management, custom styling, icons, and links.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet activeTab = $state('Home');\n</script>\n\n<Tabbar items={['Home', 'Profile', 'Settings']} bind:value={activeTab} />\n```\n\n## Props\n\n### Core Props\n- **items**: Array<string | TabItem> (required)\n  - Array of tab items. Each item can be:\n    - A simple string (e.g., \"Home\")\n    - A TabItem object with: { value?, label, prefix?, suffix?, href?, disabled?, target?, rel? }\n  - Every tab resolves to a string value: its `value`, else its string label, else its index as a string\n\n- **value**: string (default: the first enabled tab's value, bindable)\n  - The value of the currently active tab (a string item is its own value)\n  - Can be bound with `bind:value`\n  - A value you set is never rewritten; see Selection fallback for what the Tabbar changes by itself\n- **defaultValue**: string - Initial active tab value when value is omitted\n\n- **onValueChange**: (payload: { value: string; reason }) => void\n  - Called once per change of the active tab with `{ value, reason }`, the new tab's value and why it changed: a click, an arrow key, Enter or Space, a menu entry, or an automatic fallback (see Selection fallback)\n  - `reason` (`TabbarValueChangeReason`) is `user` for a click, key or menu entry, and `initial`, `disabled` or `missing` when the Tabbar selected an enabled tab by itself\n  - Not called when the current tab is re-selected or when value is changed externally\n- **activateOnFocus**: boolean (default: true)\n  - `true`: the arrow keys, Home and End select the tab they move to (selection follows focus)\n  - `false`: manual activation. The keys only move focus; Enter, Space or a click selects the focused tab. Use it when selecting is costly, for example when lazy panels mount on selection, so arrowing across the list does not build every panel it passes\n  - Menu tabs always open manually, whatever this is set to\n\n### Styling Props\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - small: Compact size with smaller padding and text\n  - normal: Standard size\n  - large: Larger size with more padding\n\n- **orientation**: 'horizontal' | 'vertical' (default: 'horizontal')\n  - horizontal: Tabs arranged in a row\n  - vertical: Tabs arranged in a column\n\n- **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' (default: 'primary')\n  - Determines the color scheme of the active tab\n\n- **variant**: 'underline' | 'pill' (default: 'underline')\n  - underline: a colored bar slides along the active tab edge (side set by position)\n  - pill: a rounded track where the active tab is a raised pill; the pill slides and resizes between tabs with the same animation\n  - Both variants respect the color prop: the underline bar and the pill fill use color, and the active pill's label uses the color's contrast tone (use color='neutral' for a neutral pill)\n  - The indicator is correct during SSR (a CSS-only bar rendered in the active tab) and hands off to a single measured element that slides after hydration, so it adapts to variable tab widths and to the vertical orientation\n\n- **alignment**: 'start' | 'center' | 'end' (default: 'start')\n  - start: Tabs aligned to the start of the container\n  - center: Tabs centered in the container\n  - end: Tabs aligned to the end of the container\n\n- **fullWidth**: boolean (default: false)\n  - Whether the tabbar should be full width\n  - When true, the tabbar and individual tabs will expand to fill the available width\n\n- **scrollFade**: boolean (default: true)\n  - Applies the shared logical-axis scroll fade only while the tab list overflows\n\n### Advanced Props\n- **label**: string - Accessible name for the tab list, applied as aria-label. Give one to every page that shows more than one set of tabs\n- **id**: string - DOM id prefix for the tabs; each tab renders as `{id}-tab-{index}`. Generated when omitted\n- **controlsPanels**: boolean (default: false) - Adds `aria-controls=\"{id}-panel-{index}\"` to every tab. `Tabs` sets it and renders the matching panels; only enable it yourself when you render panels with those ids\n- **ref**: HTMLDivElement | null (bindable) - Reference to the tab list element\n- **class**: string - Additional CSS classes for the tabbar container\n- **theme**: TabbarThemeProps - Custom theme overrides\n\nNative div attributes and attachments are forwarded to the root, minus the ARIA the tab list owns: `role`, `aria-orientation` (from `orientation`), and its accessible name (from `label`) are written by the component and cannot be overridden. Horizontal and vertical overflow use the shared `scroll-fade-x` and `scroll-fade-y` utilities by default; non-overflowing tab lists remain unmasked, including in no-support fallback browsers.\n\n## Selection fallback\n\nThe Tabbar moves the selection by itself only when the change is its own; it then renders the new tab (also during SSR), writes its value back to value and calls onValueChange with it:\n\n- On mount, a defaultValue naming a disabled or unknown tab selects the first enabled tab.\n- When the selected tab becomes disabled, the first enabled tab is selected.\n- When the selected tab is removed from items, its nearest enabled neighbour is selected (the tab that moved into its place first, then the one before it).\n\nOmitting value and defaultValue selects the first enabled tab and reports nothing, including when items arrive after mount. A value the parent sets (on mount or later, by binding or by another control such as an overflow picker or a second tab list) is never rewritten: a value naming a disabled tab shows that tab, and a value naming no tab selects no tab until a tab with that value appears. With no selected tab every tab has `aria-selected=\"false\"` and the sliding indicator is `hidden` with `data-ready=\"false\"` and no inline style; when a tab is selected again the indicator snaps into place before it animates. When every tab is disabled, a value naming one of them stays selected. A disabled tab is never selected by a click, a key or a menu entry.\n\n## TabItem Structure\n\nWhen using object format for items:\n\n```typescript\ntype TabItem = {\n  value?: string;                // Stable identifier; defaults to the string label\n  label: string | Snippet;      // Tab label (required)\n  prefix?: Snippet;              // Icon or content before label\n  suffix?: Snippet;              // Icon or content after label\n  href?: string;                 // URL for navigation tabs\n  disabled?: boolean;            // Disable the tab\n  target?: string;               // Link target (e.g., \"_blank\")\n  rel?: string;                  // Link relationship\n  menu?: string[];               // Entries shown in a popover menu (overflow pattern)\n  onSelect?: (menuIndex: number) => void; // Called when a menu entry is picked\n}\n```\n\n### Menu tab (overflow pattern)\n\nA tab with `menu` renders with a chevron and opens a popover menu instead of activating directly. Selecting an entry activates the tab, displays the entry's label on it (the tab's own label becomes the menu header), slides the indicator to it, and calls `onSelect(menuIndex)`. The selected entry shows a check mark in the menu.\n\n```svelte\n<Tabbar\n\titems={['Home', 'Projects', { label: 'More', menu: ['Analytics', 'Reports', 'Billing'] }]}\n\tbind:value={activeTab}\n/>\n```\n\n## Structure\n\nThe tabbar follows this DOM structure:\n```\n<Tabbar>\n\t<Tab>\n\t\t<TabContent>      <!-- Optional wrapper when prefix/suffix exist -->\n\t\t\t<Prefix />      <!-- Optional prefix content -->\n\t\t\t<Label />       <!-- Tab label -->\n\t\t\t<Suffix />      <!-- Optional suffix content -->\n\t\t</TabContent>\n\t</Tab>\n\t<!-- More tabs... -->\n</Tabbar>\n```\n\n## Examples\n\n### Simple String Tabs\n```svelte\n<script>\n\tlet activeTab = $state('Home');\n</script>\n\n<Tabbar \n\titems={['Home', 'About', 'Contact']} \n\tbind:value={activeTab}\n\tcolor=\"primary\"\n/>\n```\n\n### Tabs with Icons\n```svelte\n<script lang=\"ts\">\n\timport { houseIcon } from 'entasis/icons/house';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\n\tlet activeTab = $state('Home');\n\n\tconst tabs = [\n\t\t{\n\t\t\tlabel: 'Home',\n\t\t\tprefix: houseIcon\n\t\t},\n\t\t{\n\t\t\tlabel: 'Profile',\n\t\t\tprefix: userIcon\n\t\t},\n\t\t{\n\t\t\tlabel: 'Settings',\n\t\t\tprefix: gearIcon\n\t\t}\n\t];\n</script>\n\n<Tabbar items={tabs} bind:value={activeTab} />\n```\n\n### Navigation Tabs (with links)\n```svelte\n<script>\n\tconst tabs = [\n\t\t{ label: 'Dashboard', href: '/dashboard' },\n\t\t{ label: 'Analytics', href: '/analytics' },\n\t\t{ label: 'Reports', href: '/reports' }\n\t];\n</script>\n\n<Tabbar items={tabs} />\n```\n\n### Tabs with Disabled State\n```svelte\n<script>\n\tlet activeTab = $state('Enabled Tab');\n\t\n\tconst tabs = [\n\t\t{ label: 'Enabled Tab' },\n\t\t{ label: 'Disabled Tab', disabled: true },\n\t\t{ label: 'Another Tab' }\n\t];\n</script>\n\n<Tabbar items={tabs} bind:value={activeTab} />\n```\n\n### Vertical Orientation\n```svelte\n<script>\n\tlet activeTab = $state('First');\n</script>\n\n<Tabbar \n\titems={['First', 'Second', 'Third']} \n\tbind:value={activeTab}\n\torientation=\"vertical\"\n/>\n```\n\n### Different Alignments\n```svelte\n<script>\n\tlet activeTab = $state('One');\n</script>\n\n<!-- Centered tabs -->\n<Tabbar items={['One', 'Two', 'Three']} bind:value={activeTab} alignment=\"center\" />\n\n<!-- Right-aligned tabs -->\n<Tabbar items={['One', 'Two', 'Three']} bind:value={activeTab} alignment=\"end\" />\n```\n\n### Full Width Tabs\n```svelte\n<script>\n\tlet activeTab = $state('Tab 1');\n</script>\n\n<!-- Full width tabbar where tabs expand to fill available space -->\n<Tabbar items={['Tab 1', 'Tab 2', 'Tab 3']} bind:value={activeTab} fullWidth />\n```\n\n### With onValueChange Callback\n```svelte\n<script lang=\"ts\">\n\tlet activeTab = $state('Tab 1');\n\t\n\tfunction handleTabChange({ value }: { value: string }) {\n\t\tconsole.log('Active tab changed to:', value); // e.g. 'Tab 2'\n\t}\n</script>\n\n<Tabbar \n\titems={['Tab 1', 'Tab 2', 'Tab 3']} \n\tbind:value={activeTab}\n\tonValueChange={handleTabChange}\n/>\n```\n\n### Different Sizes and Colors\n```svelte\n<script>\n\tlet activeTab = $state('Small');\n</script>\n\n<!-- Small size with secondary color -->\n<Tabbar \n\titems={['Small', 'Tabs']} \n\tbind:value={activeTab}\n\tsize=\"small\"\n\tcolor=\"secondary\"\n/>\n\n<!-- Large size with success color -->\n<Tabbar \n\titems={['Large', 'Tabs']} \n\tbind:value={activeTab}\n\tsize=\"large\"\n\tcolor=\"success\"\n/>\n```\n\n### Complex Tabs with Badges\n```svelte\n<script>\n\timport { Chip } from 'entasis/chip';\n\t\n\tlet activeTab = $state('Inbox');\n</script>\n\n{#snippet unreadCount()}\n\t<Chip color=\"danger\" size=\"small\">5</Chip>\n{/snippet}\n\n<Tabbar\n\titems={['Inbox', { label: 'Messages', suffix: unreadCount }, 'Sent']}\n\tbind:value={activeTab}\n/>\n```\n\n### External Links\n```svelte\n<script>\n\tconst tabs = [\n\t\t{ label: 'Internal', href: '/dashboard' },\n\t\t{ label: 'External', href: 'https://example.com', target: '_blank', rel: 'noopener' }\n\t];\n</script>\n\n<Tabbar items={tabs} />\n```\n\n## Accessibility\n\nThe Tabbar component follows WAI-ARIA best practices for tablist patterns:\n\n### ARIA Attributes\n- Sets `role=\"tablist\"` on the container\n- Sets `role=\"tab\"` on each tab button\n- Sets `aria-selected=\"true\"` on the active tab, `\"false\"` on others\n- Gives each tab a stable `id` (`{id}-tab-{index}`) and, with `controlsPanels`, an `aria-controls` pointing at its panel\n- Sets `aria-disabled=\"true\"` on disabled tabs\n- Sets `aria-activedescendant` on the container to reference the active tab\n- Implements roving tabindex pattern (active tab has `tabindex=\"0\"`, others have `tabindex=\"-1\"`). The tablist itself has `tabindex=\"-1\"`, so Tab and Shift+Tab pass through the tab list in one step\n- The tab stop stays on the focused tab element and skips tabs hidden with CSS, including ones hidden by a class, a style or a media query after mount; removing the focused tab moves focus to the tab that takes its place. Tabs are keyed by position, so inserting or reordering tabs before the focused one leaves focus and the tab stop at the same position\n\n### Keyboard Navigation\nFull keyboard support following WAI-ARIA best practices:\n\n**Horizontal Orientation:**\n- **Arrow Left**: Move focus to previous tab\n- **Arrow Right**: Move focus to next tab\n- **Home**: Move focus to first tab\n- **End**: Move focus to last tab\n- **Enter/Space**: Activate the focused tab\n\n**Vertical Orientation:**\n- **Arrow Up**: Move focus to previous tab\n- **Arrow Down**: Move focus to next tab\n- **Home**: Move focus to first tab\n- **End**: Move focus to last tab\n- **Enter/Space**: Activate the focused tab\n\n**Behavior:**\n- Arrow keys move keyboard **focus** (visual indicator with ring) and, by default, select the tab they reach (`activateOnFocus`)\n- With `activateOnFocus={false}` the arrow keys only move focus, and Enter/Space **activate** the focused tab (changes selection)\n- Focus automatically wraps around (loops from last to first and vice versa)\n- Disabled tabs are automatically skipped during navigation\n- Focused tab automatically scrolls into view (smooth scroll)\n- All navigation keys are prevented from scrolling the page\n- Focus ring color matches the tab's color scheme\n\n**Visual States:**\n- **Active tab**: Colored text, background, and bottom/left border\n- **Focused tab**: Ring outline in theme color (keyboard navigation)\n- **Inactive tab**: Neutral gray text with subtle hover effect\n\n## Notes\n\n- When `href` is provided in a tab, it renders as an `<a>` tag, otherwise as a `<button>`\n- Disabled tabs cannot be clicked and do not trigger `onValueChange`\n- The active tab is identified by its string value (a string item's label, or an object item's `value` / string label); give object items an explicit `value` when labels may change or are snippets\n- The `value` prop is bindable for two-way data binding\n- Tabs with `href` will not update `value` on click (they navigate instead)\n- Icon/content sizing is automatically adjusted based on tab size\n- The component is fully responsive and works with all color schemes\n\n## Theme Customization\n\nThe Tabbar 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 tabbar container styles\n- **tab**: Individual tab styles\n- **indicator**: The single measured active indicator that slides between tabs\n- **staticIndicator**: The CSS-only indicator rendered inside the active tab for SSR / pre-hydration\n- **prefix**: Prefix icon/content styles\n- **suffix**: Suffix icon/content styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for tabbar container\n- Variants:\n  - orientation: 'horizontal' | 'vertical' - Tab orientation\n  - scrollFade: 'none' | 'x' | 'y' - Logical-axis scroll fade, applied only while the list overflows\n  - alignment: 'start' | 'center' | 'end' - Tab alignment\n  - size: 'small' | 'normal' | 'large' - Gap between tabs\n  - variant: 'underline' | 'pill' - Track styling\n  - fullWidth: boolean - Expand the tabbar to fill its container\n\n**tab**:\n- base: Base classes for tab items\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Padding, text size and gap\n  - color: Color variants\n  - active: boolean - Active state styling\n  - focused: boolean - Keyboard-focused state styling\n  - disabled: boolean - Disabled state styling\n  - orientation: 'horizontal' | 'vertical'\n  - position: 'top' | 'bottom' | 'left' | 'right' - Indicator edge\n  - variant: 'underline' | 'pill'\n  - fullWidth: boolean\n\n**indicator**:\n- base: Base classes for the sliding active indicator\n- Variants:\n  - variant: 'underline' | 'pill' - Bar or raised pill\n\n**staticIndicator**:\n- base: Base classes for the SSR indicator\n- Variants:\n  - variant: 'underline' | 'pill'\n  - position: 'top' | 'bottom' | 'left' | 'right' - Which tab edge the underline sits on\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Tabbar items={tabs}\n  bind:value={activeTab}\n  theme={{\n    root: {\n      base: 'border-b-2 border-gray-200',\n      size: {\n        normal: 'gap-4'\n      }\n    },\n    tab: {\n      active: {\n        true: 'border-b-2 border-primary'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Active State**:\n```svelte\n<Tabbar items={tabs}\n  bind:value={activeTab}\n  theme={{\n    tab: {\n      active: {\n        true: 'bg-primary text-white rounded-t-lg'\n      }\n    },\n    indicator: {\n      base: 'bg-primary h-1 rounded-full'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setTabbarTheme } from './index.ts';\n  \n  setTabbarTheme({\n    root: {\n      base: 'border-b border-gray-200',\n      size: {\n        normal: 'gap-2'\n      }\n    },\n    tab: {\n      base: 'transition-colors',\n      active: {\n        true: 'text-primary border-b-2 border-primary'\n      }\n    }\n  });\n</script>\n```\n";

package/dist/components/Tabbar/tabbar.mcp.js

@@ -20,16 +20,22 @@ The Tabbar component is a flexible navigation component that displays a list of
   - Array of tab items. Each item can be:
     - A simple string (e.g., "Home")
     - A TabItem object with: { value?, label, prefix?, suffix?, href?, disabled?, target?, rel? }
-  - Every tab resolves to a string value: its \`value\`, else its string label, else its index as a string (\`getTabValue(item, index)\` is exported from \`entasis/tabbar\`)
+  - Every tab resolves to a string value: its \`value\`, else its string label, else its index as a string
 
-- **value**: string (default: the first tab's value, bindable)
+- **value**: string (default: the first enabled tab's value, bindable)
   - The value of the currently active tab (a string item is its own value)
   - Can be bound with \`bind:value\`
+  - A value you set is never rewritten; see Selection fallback for what the Tabbar changes by itself
 - **defaultValue**: string - Initial active tab value when value is omitted
 
-- **onValueChange**: (value: string) => void
-  - Callback function called when the active tab changes
-  - Receives the new tab's value as an argument; not called when the current tab is re-selected
+- **onValueChange**: (payload: { value: string; reason }) => void
+  - Called once per change of the active tab with \`{ value, reason }\`, the new tab's value and why it changed: a click, an arrow key, Enter or Space, a menu entry, or an automatic fallback (see Selection fallback)
+  - \`reason\` (\`TabbarValueChangeReason\`) is \`user\` for a click, key or menu entry, and \`initial\`, \`disabled\` or \`missing\` when the Tabbar selected an enabled tab by itself
+  - Not called when the current tab is re-selected or when value is changed externally
+- **activateOnFocus**: boolean (default: true)
+  - \`true\`: the arrow keys, Home and End select the tab they move to (selection follows focus)
+  - \`false\`: manual activation. The keys only move focus; Enter, Space or a click selects the focused tab. Use it when selecting is costly, for example when lazy panels mount on selection, so arrowing across the list does not build every panel it passes
+  - Menu tabs always open manually, whatever this is set to
 
 ### Styling Props
 - **size**: 'small' | 'normal' | 'large' (default: 'normal')
@@ -72,6 +78,16 @@ The Tabbar component is a flexible navigation component that displays a list of
 
 Native div attributes and attachments are forwarded to the root, minus the ARIA the tab list owns: \`role\`, \`aria-orientation\` (from \`orientation\`), and its accessible name (from \`label\`) are written by the component and cannot be overridden. Horizontal and vertical overflow use the shared \`scroll-fade-x\` and \`scroll-fade-y\` utilities by default; non-overflowing tab lists remain unmasked, including in no-support fallback browsers.
 
+## Selection fallback
+
+The Tabbar moves the selection by itself only when the change is its own; it then renders the new tab (also during SSR), writes its value back to value and calls onValueChange with it:
+
+- On mount, a defaultValue naming a disabled or unknown tab selects the first enabled tab.
+- When the selected tab becomes disabled, the first enabled tab is selected.
+- When the selected tab is removed from items, its nearest enabled neighbour is selected (the tab that moved into its place first, then the one before it).
+
+Omitting value and defaultValue selects the first enabled tab and reports nothing, including when items arrive after mount. A value the parent sets (on mount or later, by binding or by another control such as an overflow picker or a second tab list) is never rewritten: a value naming a disabled tab shows that tab, and a value naming no tab selects no tab until a tab with that value appears. With no selected tab every tab has \`aria-selected="false"\` and the sliding indicator is \`hidden\` with \`data-ready="false"\` and no inline style; when a tab is selected again the indicator snaps into place before it animates. When every tab is disabled, a value naming one of them stays selected. A disabled tab is never selected by a click, a key or a menu entry.
+
 ## TabItem Structure
 
 When using object format for items:
@@ -230,7 +246,7 @@ The tabbar follows this DOM structure:
 <script lang="ts">
 	let activeTab = $state('Tab 1');
 	
-	function handleTabChange(value: string) {
+	function handleTabChange({ value }: { value: string }) {
 		console.log('Active tab changed to:', value); // e.g. 'Tab 2'
 	}
 </script>
@@ -306,7 +322,8 @@ The Tabbar component follows WAI-ARIA best practices for tablist patterns:
 - Gives each tab a stable \`id\` (\`{id}-tab-{index}\`) and, with \`controlsPanels\`, an \`aria-controls\` pointing at its panel
 - Sets \`aria-disabled="true"\` on disabled tabs
 - Sets \`aria-activedescendant\` on the container to reference the active tab
-- Implements roving tabindex pattern (active tab has \`tabindex="0"\`, others have \`tabindex="-1"\`)
+- Implements roving tabindex pattern (active tab has \`tabindex="0"\`, others have \`tabindex="-1"\`). The tablist itself has \`tabindex="-1"\`, so Tab and Shift+Tab pass through the tab list in one step
+- The tab stop stays on the focused tab element and skips tabs hidden with CSS, including ones hidden by a class, a style or a media query after mount; removing the focused tab moves focus to the tab that takes its place. Tabs are keyed by position, so inserting or reordering tabs before the focused one leaves focus and the tab stop at the same position
 
 ### Keyboard Navigation
 Full keyboard support following WAI-ARIA best practices:
@@ -326,8 +343,8 @@ Full keyboard support following WAI-ARIA best practices:
 - **Enter/Space**: Activate the focused tab
 
 **Behavior:**
-- Arrow keys move keyboard **focus** (visual indicator with ring)
-- Enter/Space keys **activate** the focused tab (changes selection)
+- Arrow keys move keyboard **focus** (visual indicator with ring) and, by default, select the tab they reach (\`activateOnFocus\`)
+- With \`activateOnFocus={false}\` the arrow keys only move focus, and Enter/Space **activate** the focused tab (changes selection)
 - Focus automatically wraps around (loops from last to first and vice versa)
 - Disabled tabs are automatically skipped during navigation
 - Focused tab automatically scrolls into view (smooth scroll)

package/dist/components/Tabbar/tabbar.props.d.ts

@@ -3,6 +3,17 @@ import type { Snippet } from 'svelte';
 import type { WithAttachments } from '../../types/props.js';
 import type { TabbarThemeProps } from './tabbar.theme.js';
 import type { HTMLAttributes } from 'svelte/elements';
+/**
+ * Why a Tabbar reported a change: `user` for a click, arrow key, Enter, Space or menu entry,
+ * `initial`, `disabled` or `missing` when the Tabbar selected an enabled tab by itself.
+ */
+export type TabbarValueChangeReason = 'user' | 'initial' | 'disabled' | 'missing';
+/** Payload of Tabbar's `onValueChange`. */
+export type TabbarValueChangePayload = {
+    /** The new active tab's value. */
+    value: string;
+    reason: TabbarValueChangeReason;
+};
 export type TabAlignment = 'start' | 'center' | 'end';
 export type TabOrientation = 'horizontal' | 'vertical';
 export type TabbarPosition = 'top' | 'bottom' | 'left' | 'right';
@@ -71,16 +82,34 @@ export type TabbarProps = WithAttachments<TabbarRootAttributes & {
     items: TabItem[];
     /**
      * The `value` of the active tab (a string label resolves to itself). Bindable.
-     * @default the first tab's value
+     * A value you set is never rewritten: one naming a disabled tab shows that tab, and one
+     * naming no tab selects nothing. When the selected tab is removed or disabled, an enabled
+     * tab is selected instead, written back here and reported through `onValueChange`.
+     * @default the first enabled tab's value
      */
     value?: string;
-    /** Initial active tab value when `value` is omitted. */
+    /**
+     * Initial active tab value when `value` is omitted. One that names a disabled or unknown
+     * tab selects the first enabled tab on mount, reported through `onValueChange`.
+     */
     defaultValue?: string;
     /**
-     * Callback function called when the active tab changes.
-     * Receives the new tab's value.
+     * Called once per change of the active tab with its value: a click, an arrow key, a menu
+     * entry, or the Tabbar moving the selection to an enabled tab by itself because
+     * `defaultValue` named no enabled tab or the selected tab was removed or disabled. Not
+     * called when the current tab is re-selected or when `value` is changed externally. The
+     * payload is `{ value, reason }`: `reason` is `user`, or `initial`, `disabled` or `missing`
+     * for a selection the Tabbar made by itself.
+     */
+    onValueChange?: (payload: TabbarValueChangePayload) => void;
+    /**
+     * Whether moving focus with the arrow keys, Home or End also selects the tab. Set `false`
+     * for manual activation: the keys only move focus, and Enter or Space (or a click) selects
+     * the focused tab. Use it when selecting a tab is costly, for example when each panel
+     * mounts lazily, so arrowing across the list does not build every panel on the way.
+     * @default true
      */
-    onValueChange?: (value: string) => void;
+    activateOnFocus?: boolean;
     /** DOM id prefix for tab elements (`{id}-tab-{index}`); `aria-controls` targets `{id}-panel-{index}`. */
     id?: string;
     /**

package/dist/components/Tabbar/tabbar.selection.svelte.d.ts

@@ -0,0 +1,79 @@
+import { type TabItem } from './tabbar.props.js';
+/**
+ * Why a tab list selected a tab by itself: `initial` when `defaultValue` named a disabled or
+ * unknown tab, `disabled` when the selected tab became disabled, `missing` when it was removed.
+ */
+export type TabFallbackReason = 'initial' | 'disabled' | 'missing';
+/**
+ * The tab that shows as selected. `fallback` is set when the tab list moves the selection by
+ * itself: the new value is written back, and reported unless it is the silent `default`.
+ */
+export type TabSelection = {
+    index: number;
+    fallback?: TabFallbackReason | 'default';
+};
+/**
+ * Who chose the value a tab list starts with: the parent (`value`), the parent's `defaultValue`,
+ * or the tab list's own `default` (the first enabled tab) when neither was given.
+ */
+export type TabValueOrigin = 'value' | 'defaultValue' | 'default';
+/**
+ * What a tab list remembers between resolutions.
+ * - `settled`: the value that last selected an enabled tab and that tab's index, kept while the
+ *   value stays the same, so removing or disabling that tab is known to be the list's own change.
+ * - `initial`: the list's own starting value (`defaultValue` or the default), kept until a tab is
+ *   first selected, so tabs that arrive after mount still replace it.
+ */
+export type TabSelectionHistory = {
+    settled?: {
+        value: string;
+        index: number;
+    };
+    initial?: {
+        value: string;
+        origin: Exclude<TabValueOrigin, 'value'>;
+    };
+};
+export declare const isTabDisabled: (item: TabItem | undefined) => boolean;
+/** The default selection: the first enabled tab's value, else the first tab's, else `''`. */
+export declare const getDefaultTabValue: (items: TabItem[]) => string;
+/**
+ * Who chose the starting value; read before `createBindableValue` writes its default back. A
+ * `value` equal to `defaultValue` is the default written back into a binding: the server renders
+ * a bound component again with it.
+ */
+export declare const getTabValueOrigin: (value: unknown, defaultValue: unknown) => TabValueOrigin;
+/**
+ * Resolves the tab to show for `value`. A value that names an enabled tab is kept. The tab list
+ * replaces a value only when the change is its own: the selected tab was removed (`missing`, the
+ * nearest enabled neighbour) or disabled (`disabled`, the first enabled tab), or its starting
+ * value names no enabled tab (`initial` for `defaultValue`, the silent `default` otherwise). Any
+ * other value came from the parent and is never replaced: a disabled tab it names stays selected
+ * and an unknown value selects nothing (-1). With no enabled tab nothing can be replaced either.
+ */
+export declare const resolveTabSelection: (items: TabItem[], value: string, history?: TabSelectionHistory) => TabSelection;
+type TabSelectionOptions = {
+    items: () => TabItem[];
+    value: () => string;
+    /** Who chose the value present on mount; see `getTabValueOrigin`. */
+    origin: TabValueOrigin;
+    /**
+     * Writes a selection the tab list made by itself; runs untracked, once per fallback. `reason`
+     * is undefined for the default selection, which is written back but not reported.
+     */
+    onFallback: (value: string, details: {
+        index: number;
+        reason?: TabFallbackReason;
+    }) => void;
+};
+/**
+ * One effective selection for a tab list. `index` is what renders — on the server too — and a
+ * fallback the list owns is written back through `onFallback` after it renders, so a bound
+ * `value` and the rendered tab never disagree for longer than one flush. A value the parent set
+ * is never written over, so two lists sharing one value cannot undo each other's picks.
+ */
+export declare const useTabSelection: (options: TabSelectionOptions) => {
+    /** Index of the tab that shows as selected; -1 when no tab is. */
+    readonly index: number;
+};
+export {};

package/dist/components/Tabbar/tabbar.selection.svelte.js

@@ -0,0 +1,99 @@
+import { untrack } from 'svelte';
+import { getTabValue } from './tabbar.props.js';
+export const isTabDisabled = (item) => typeof item === 'object' && item.disabled === true;
+const firstEnabledIndex = (items) => items.findIndex((item) => !isTabDisabled(item));
+/** The default selection: the first enabled tab's value, else the first tab's, else `''`. */
+export const getDefaultTabValue = (items) => {
+    const index = Math.max(0, firstEnabledIndex(items));
+    const item = items[index];
+    return item === undefined ? '' : getTabValue(item, index);
+};
+/**
+ * Who chose the starting value; read before `createBindableValue` writes its default back. A
+ * `value` equal to `defaultValue` is the default written back into a binding: the server renders
+ * a bound component again with it.
+ */
+export const getTabValueOrigin = (value, defaultValue) => {
+    if (defaultValue !== undefined && (value === undefined || value === defaultValue)) {
+        return 'defaultValue';
+    }
+    return value === undefined ? 'default' : 'value';
+};
+// After a removal, the tabs that sat on either side of the removed one are at `from` and
+// `from - 1`; the next ring out is `from + 1` and `from - 2`, and so on. Following tabs win ties.
+const nearestEnabledIndex = (items, from) => {
+    for (let distance = 0; distance <= Math.max(from, items.length); distance += 1) {
+        for (const index of [from + distance, from - distance - 1]) {
+            if (index >= 0 && index < items.length && !isTabDisabled(items[index]))
+                return index;
+        }
+    }
+    return firstEnabledIndex(items);
+};
+/**
+ * Resolves the tab to show for `value`. A value that names an enabled tab is kept. The tab list
+ * replaces a value only when the change is its own: the selected tab was removed (`missing`, the
+ * nearest enabled neighbour) or disabled (`disabled`, the first enabled tab), or its starting
+ * value names no enabled tab (`initial` for `defaultValue`, the silent `default` otherwise). Any
+ * other value came from the parent and is never replaced: a disabled tab it names stays selected
+ * and an unknown value selects nothing (-1). With no enabled tab nothing can be replaced either.
+ */
+export const resolveTabSelection = (items, value, history = {}) => {
+    const index = items.findIndex((item, itemIndex) => getTabValue(item, itemIndex) === value);
+    if (index !== -1 && !isTabDisabled(items[index]))
+        return { index };
+    const first = firstEnabledIndex(items);
+    if (first === -1)
+        return { index };
+    const { settled, initial } = history;
+    if (settled?.value === value) {
+        return index === -1
+            ? { index: nearestEnabledIndex(items, settled.index), fallback: 'missing' }
+            : { index: first, fallback: 'disabled' };
+    }
+    if (initial?.value === value) {
+        return { index: first, fallback: initial.origin === 'default' ? 'default' : 'initial' };
+    }
+    return { index };
+};
+/**
+ * One effective selection for a tab list. `index` is what renders — on the server too — and a
+ * fallback the list owns is written back through `onFallback` after it renders, so a bound
+ * `value` and the rendered tab never disagree for longer than one flush. A value the parent set
+ * is never written over, so two lists sharing one value cannot undo each other's picks.
+ */
+export const useTabSelection = (options) => {
+    // A plain object on purpose: it describes the last committed selection and must not make the
+    // selection depend on its own write-back.
+    const history = {};
+    if (options.origin !== 'value') {
+        history.initial = { value: untrack(options.value), origin: options.origin };
+    }
+    const selection = $derived(resolveTabSelection(options.items(), options.value(), history));
+    $effect(() => {
+        const { index, fallback } = selection;
+        const items = options.items();
+        const value = options.value();
+        if (!fallback && index !== -1 && !isTabDisabled(items[index])) {
+            history.settled = { value, index };
+            history.initial = undefined;
+        }
+        else {
+            // The value moved on: there is no selected tab left to fall back from.
+            if (history.settled?.value !== value)
+                history.settled = undefined;
+            if (history.initial?.value !== value)
+                history.initial = undefined;
+        }
+        if (!fallback)
+            return;
+        const reason = fallback === 'default' ? undefined : fallback;
+        untrack(() => options.onFallback(getTabValue(items[index], index), { index, reason }));
+    });
+    return {
+        /** Index of the tab that shows as selected; -1 when no tab is. */
+        get index() {
+            return selection.index;
+        }
+    };
+};

package/dist/components/TableOfContents/tableOfContents.state.svelte.js

@@ -1,3 +1,4 @@
+import { elementById } from '../../utils/id.js';
 import { withOptions } from '../../utils/state.svelte.js';
 import { onDestroy, tick, untrack } from 'svelte';
 import { normalizeTableOfContentsItems } from './tableOfContents.items.js';
@@ -196,7 +197,9 @@ export class TableOfContentsState extends withOptions() {
         const headingElements = plainMap();
         const targetHeadings = this.targetElement ? getHeadingElementsById(this.targetElement) : null;
         for (const item of this.resolvedProvidedItems ?? []) {
-            const heading = targetHeadings ? targetHeadings.get(item.id) : getHeadingElementById(item.id);
+            const heading = targetHeadings
+                ? targetHeadings.get(item.id)
+                : getHeadingElementById(this.rootElement, item.id);
             if (heading)
                 headingElements.set(item.id, heading);
         }
@@ -388,10 +391,9 @@ function getHeadingElementsById(target) {
     }
     return headings;
 }
-function getHeadingElementById(id) {
-    if (typeof document === 'undefined')
-        return null;
-    const element = document.getElementById(id);
+function getHeadingElementById(from, id) {
+    // Resolved in the tree the table of contents renders in, so a shadow root's headings are found.
+    const element = elementById(from, id);
     if (!(element instanceof HTMLElement) || !/^H[1-6]$/.test(element.tagName))
         return null;
     return element;
@@ -399,7 +401,7 @@ function getHeadingElementById(id) {
 function getHeadingId(heading, title, usedIds) {
     const explicitId = heading.id.trim();
     if (explicitId) {
-        const owner = document.getElementById(explicitId);
+        const owner = elementById(heading, explicitId);
         return !usedIds.has(explicitId) && (!owner || owner === heading) ? explicitId : null;
     }
     const slug = title
@@ -411,7 +413,7 @@ function getHeadingId(heading, title, usedIds) {
     const baseId = `toc-${slug || 'section'}`;
     let candidate = baseId;
     let suffix = 2;
-    while (usedIds.has(candidate) || document.getElementById(candidate)) {
+    while (usedIds.has(candidate) || elementById(heading, candidate)) {
         candidate = `${baseId}-${suffix}`;
         suffix += 1;
     }