entasis 0.11.0 → 0.12.0

package/dist/components/Tabs/Tabs.svelte

@@ -2,10 +2,19 @@
 	import { Tabbar } from '../Tabbar/index.js';
 	import { Stepper } from '../Stepper/index.js';
 	import { getTabValue, type TabItem } from '../Tabbar/tabbar.props.js';
+	import {
+		getDefaultTabValue,
+		getTabValueOrigin,
+		isTabDisabled,
+		useTabSelection
+	} from '../Tabbar/tabbar.selection.svelte.js';
 	import { StepperState } from '../Stepper/stepper.state.svelte.js';
-	import type { TabsProps } from './tabs.props.js';
+	import { untrack } from 'svelte';
+	import type { TabsProps, TabsValueChangeReason } from './tabs.props.js';
 	import { useTabsMotion, useTabsTheme } from './tabs.theme.js';
 	import { createBindableValue } from '../../utils/state.svelte.js';
+	import { useDirection } from '../../utils/useDirection.svelte.js';
+	import { useActivationDirection } from './tabs.direction.svelte.js';
 
 	let {
 		items,
@@ -22,24 +31,61 @@
 		children: panel,
 		...attachments
 	}: TabsProps<Item> = $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 id = $props.id();
 	const tabValues = $derived(items.map(getTabValue));
-	// Stepper works in indexes; Tabs speaks values. Map both ways here, once.
-	const activeIndex = $derived(Math.max(0, tabValues.indexOf(valueState.value)));
+	const emitChange = (index: number, reason: TabsValueChangeReason) => {
+		onValueChange?.({ value: tabValues[index], item: items[index], index, reason });
+	};
+	// One effective selection drives both the tab list and the panels, so they always show the
+	// same tab, or none when the value names no tab.
+	const selection = useTabSelection({
+		items: () => items,
+		value: () => valueState.value,
+		origin,
+		onFallback: (next, { index, reason }) => {
+			valueState.value = next;
+			if (reason) emitChange(index, reason);
+		}
+	});
+	const activeIndex = $derived(selection.index);
+	/** The value the Tabbar shows: the resolved tab's, or the raw value when none resolves. */
+	const activeValue = $derived(tabValues[activeIndex] ?? valueState.value);
+	const isSelectable = (index: number) => index in items && !isTabDisabled(items[index]);
+	// Stepper works in indexes; Tabs speaks values. Map both ways here, once. The `api` handle
+	// cannot activate a disabled tab: the request is dropped and the panels stay put.
 	const setActiveIndex = (index: number) => {
+		if (!isSelectable(index)) return;
 		const next = tabValues[index];
-		if (next !== undefined && next !== valueState.value) valueState.value = next;
+		if (next !== valueState.value) valueState.value = next;
+	};
+	const handleStepChange = (index: number) => {
+		if (index === activeIndex) {
+			emitChange(index, 'user');
+			return;
+		}
+		// `goTo` slides before it reports; slide back to the panel of the selected tab, or to no
+		// panel when no tab is selected.
+		api?.translate();
 	};
-	const emitChange = (index: number) => {
-		onValueChange?.({ value: tabValues[index], item: items[index], index });
+	// `next` and `previous` step over disabled tabs, as the arrow keys do.
+	const stepToEnabledTab = (stepper: StepperState<Item>, direction: 1 | -1) => {
+		for (let index = activeIndex + direction; index in items; index += direction) {
+			if (isSelectable(index)) return stepper.goTo(index);
+		}
+	};
+	const bindApi = (stepper: StepperState<Item>) => {
+		stepper.next = () => stepToEnabledTab(stepper, 1);
+		stepper.previous = () => stepToEnabledTab(stepper, -1);
+		api = stepper;
 	};
 
 	const classes = $derived(useTabsTheme(theme));
@@ -54,21 +100,30 @@
 		tabbar?.orientation ??
 			(placement === 'left' || placement === 'right' ? 'vertical' : 'horizontal')
 	);
-
-	function handleTabChange(nextValue: string) {
-		emitChange(tabValues.indexOf(nextValue));
-	}
+	let root = $state<HTMLElement | null>(null);
+	const direction = useDirection(() => root);
+	const activationDirection = useActivationDirection({
+		index: () => activeIndex,
+		orientation: () => effectiveTabbarOrientation,
+		direction
+	});
 </script>
 
-<div class={classes.root({ placement, className })} {...attachments}>
+<div
+	bind:this={root}
+	class={classes.root({ placement, className })}
+	data-activation-direction={activationDirection.value}
+	{...attachments}
+>
 	<Tabbar
 		id={`${id}-tabs`}
 		controlsPanels
 		fullWidth={tabbar?.fullWidth}
 		label={tabbar?.label}
-		onValueChange={handleTabChange}
+		onValueChange={({ value: next, reason }) => emitChange(tabValues.indexOf(next), reason)}
+		activateOnFocus={tabbar?.activateOnFocus}
 		{items}
-		bind:value={valueState.value}
+		bind:value={() => activeValue, (next) => (valueState.value = next)}
 		size={tabbar?.size}
 		orientation={effectiveTabbarOrientation}
 		color={tabbar?.color}
@@ -81,15 +136,17 @@
 	/>
 	<Stepper
 		class={classes.content({ placement })}
-		bind:api
+		bind:api={() => api, bindApi}
 		{items}
 		bind:value={() => activeIndex, setActiveIndex}
-		onValueChange={({ value: index }) => emitChange(index)}
+		onValueChange={({ value: index }) => handleStepChange(index)}
 		panelRole="tabpanel"
 		panelId={(index) => `${id}-tabs-panel-${index}`}
 		panelAriaLabelledby={({ index }) => `${id}-tabs-tab-${index}`}
 		transition={panelTransition}
 		{mount}
+		panelActivationDirection={(index) =>
+			index === activeIndex ? activationDirection.value : undefined}
 	>
 		{#snippet children(payload)}
 			{@render panel?.(payload)}

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

@@ -1,3 +1,4 @@
 export { default as Tabs } from './Tabs.svelte';
-export type { TabsApi, TabsProps, TabsPlacement, TabsRenderPayload } from './tabs.props.js';
+export type { TabsApi, TabsProps, TabsPlacement, TabsRenderPayload, TabsValueChangePayload, TabsValueChangeReason } from './tabs.props.js';
+export type { TabsActivationDirection } from './tabs.direction.svelte.js';
 export { tabsTheme, setTabsTheme, useTabsTheme, type TabsTheme, type TabsThemeProps } from './tabs.theme.js';

package/dist/components/Tabs/tabs.direction.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { Direction } from '../../utils/useDirection.svelte.js';
+/**
+ * Where the active tab sits relative to the previously active one, along the tab list's axis:
+ * `left` or `right` for a horizontal list (mirrored in a right-to-left document), `up` or `down`
+ * for a vertical one, and `none` before the first change or when no tab is selected.
+ */
+export type TabsActivationDirection = 'left' | 'right' | 'up' | 'down' | 'none';
+/** The direction from `previous` to `next`; `none` when either is not a tab or they are equal. */
+export declare const getActivationDirection: (previous: number, next: number, orientation: "horizontal" | "vertical", direction: Direction) => TabsActivationDirection;
+type ActivationDirectionOptions = {
+    /** The index of the selected tab; -1 when none is. */
+    index: () => number;
+    orientation: () => 'horizontal' | 'vertical';
+    direction: () => Direction;
+};
+/**
+ * Tracks the activation direction across selection changes. It updates before the DOM does
+ * (`$effect.pre`), so the attribute and the new panel arrive in the same render, for a click, a
+ * key, `api` navigation and a parent changing a bound `value` alike. The direction persists
+ * until the next change and starts as `none`.
+ */
+export declare const useActivationDirection: (options: ActivationDirectionOptions) => {
+    readonly value: TabsActivationDirection;
+};
+export {};

package/dist/components/Tabs/tabs.direction.svelte.js

@@ -0,0 +1,40 @@
+import { untrack } from 'svelte';
+/** The direction from `previous` to `next`; `none` when either is not a tab or they are equal. */
+export const getActivationDirection = (previous, next, orientation, direction) => {
+    if (previous < 0 || next < 0 || previous === next)
+        return 'none';
+    const forward = next > previous;
+    if (orientation === 'vertical')
+        return forward ? 'down' : 'up';
+    return forward === (direction === 'ltr') ? 'right' : 'left';
+};
+/**
+ * Tracks the activation direction across selection changes. It updates before the DOM does
+ * (`$effect.pre`), so the attribute and the new panel arrive in the same render, for a click, a
+ * key, `api` navigation and a parent changing a bound `value` alike. The direction persists
+ * until the next change and starts as `none`.
+ */
+export const useActivationDirection = (options) => {
+    // -1 until a tab is selected, so the first selection has no direction.
+    let previous = untrack(options.index);
+    let current = $state('none');
+    $effect.pre(() => {
+        const next = options.index();
+        const orientation = options.orientation();
+        const direction = options.direction();
+        untrack(() => {
+            if (next === previous)
+                return;
+            // Losing the selection keeps the last direction and the last selected tab as reference.
+            if (next < 0)
+                return;
+            current = getActivationDirection(previous, next, orientation, direction);
+            previous = next;
+        });
+    });
+    return {
+        get value() {
+            return current;
+        }
+    };
+};

package/dist/components/Tabs/tabs.mcp.d.ts

@@ -1 +1 @@
-export declare const tabsDescription = "\n# Tabs Component\n\nTabs combines Tabbar navigation with Stepper-powered animated panels.\n\n## Usage\n\nUse items for the tab collection and a single children snippet for the repeated panel content. The snippet receives the instance handle as api, the current item, and the zero-based index. The active tab is addressed by its string value (an item's `value`, else its string label).\n\n<script lang=\"ts\">\n\timport { Tabs } from '$lib/components/Tabs';\n\n\tconst items = [\n\t\t{ value: 'overview', label: 'Overview', title: 'Overview', body: 'A summary of the current workspace.' },\n\t\t{ value: 'activity', label: 'Activity', title: 'Activity', body: 'Recent events and changes.' },\n\t\t{ value: 'settings', label: 'Settings', title: 'Settings', body: 'Configuration for this resource.' }\n\t];\n\tlet value = $state('overview');\n</script>\n\n<Tabs {items} bind:value tabbar={{ size: 'small', color: 'secondary', fullWidth: true }}>\n\t{#snippet children({ item, index, api })}\n\t\t<section class=\"space-y-3 p-6\">\n\t\t\t<p class=\"text-sm text-neutral/70\">Panel {index + 1}</p>\n\t\t\t<h2>{item.title}</h2>\n\t\t\t<p>{item.body}</p>\n\t\t\t<button onclick={() => api.goTo(0)}>Back to overview</button>\n\t\t</section>\n\t{/snippet}\n</Tabs>\n\n## Props\n\n- items: required array of TabItem values. Each item is used by Tabbar and passed to children as item. A string item is its own value; an object item resolves to its `value`, else its string label, else its index as a string.\n- children: repeated panel renderer called with { api, item, index }.\n- value: bindable string value of the active tab (defaults to the first tab's value).\n- defaultValue: initial active tab value when value is omitted.\n- onValueChange: called once per change with { value, item, index }; not called when the current tab is re-selected or when value is changed externally.\n- placement: top, bottom, left, or right. Also drives the default tabbar orientation.\n- api: bindable TabsApi (a StepperState) for next(), previous(), and goTo(index).\n- transition: panel swap timing override (`duration` in ms, `easing`); responsive, and it beats the `motion` theme slot.\n- tabbar: props forwarded to the inner Tabbar as one object \u2014 `{ size, orientation, color, alignment, fullWidth, variant, scrollFade, label, class, theme }`. `orientation` overrides the placement-derived default.\n- mount: when a panel's content is created \u2014 `lazy` (default) on first activation and destroyed when the tab is left, `once` on first activation and kept, `eager` for every panel up front. Inactive panels are `hidden` and `inert` in every mode.\n- class: extra classes for the root.\n- theme: theme overrides for the Tabs wrapper.\n\n## Composition Rules\n\n- Render panel content through children.\n- Put per-panel differences in the item data and branch inside children when needed.\n- Use value (a string) as the public controlled state; compare against item values, not indexes.\n- Use api only when external controls need programmatic navigation.\n\n## Structure\n\nTabs renders a Tabbar next to a Stepper. Tabbar owns the clickable tab controls; Stepper owns the animated panel track.\n\n## Accessibility\n\nTabs wires the tablist to its panels: every tab has an id (`{id}-tabs-tab-{index}`), `aria-selected`, and `aria-controls`; every panel renders with role=\"tabpanel\", id `{id}-tabs-panel-{index}`, and `aria-labelledby` pointing back at its tab. Inactive panels are `hidden`, inert and out of the tab order, so only the active panel reaches the text and accessibility layers.\n\n## Theme Parts\n\n- root: wrapper around the Tabbar and panel content.\n- content: Stepper wrapper for tab panels.\n\nThe theme supports the placement variant on root and content.\n\n## Motion\n\n- **motion** theme slot: one preset (no variants) for the panel swap; the resolved\n  `{ in, out }` is forwarded to the inner Stepper's `transition`, where it wins.\n- Ladder: `<Theme components={{ tabs: { motion } }}>` \u2192 `setTabsTheme({ motion })` \u2192\n  `theme.motion` \u2192 the `transition` prop. Reduced motion snaps between panels.\n";
+export declare const tabsDescription = "\n# Tabs Component\n\nTabs combines Tabbar navigation with Stepper-powered animated panels.\n\n## Usage\n\nUse items for the tab collection and a single children snippet for the repeated panel content. The snippet receives the instance handle as api, the current item, and the zero-based index. The active tab is addressed by its string value (an item's `value`, else its string label).\n\n<script lang=\"ts\">\n\timport { Tabs } from '$lib/components/Tabs';\n\n\tconst items = [\n\t\t{ value: 'overview', label: 'Overview', title: 'Overview', body: 'A summary of the current workspace.' },\n\t\t{ value: 'activity', label: 'Activity', title: 'Activity', body: 'Recent events and changes.' },\n\t\t{ value: 'settings', label: 'Settings', title: 'Settings', body: 'Configuration for this resource.' }\n\t];\n\tlet value = $state('overview');\n</script>\n\n<Tabs {items} bind:value tabbar={{ size: 'small', color: 'secondary', fullWidth: true }}>\n\t{#snippet children({ item, index, api })}\n\t\t<section class=\"space-y-3 p-6\">\n\t\t\t<p class=\"text-sm text-neutral/70\">Panel {index + 1}</p>\n\t\t\t<h2>{item.title}</h2>\n\t\t\t<p>{item.body}</p>\n\t\t\t<button onclick={() => api.goTo(0)}>Back to overview</button>\n\t\t</section>\n\t{/snippet}\n</Tabs>\n\n## Props\n\n- items: required array of TabItem values. Each item is used by Tabbar and passed to children as item. A string item is its own value; an object item resolves to its `value`, else its string label, else its index as a string.\n- children: repeated panel renderer called with { api, item, index }.\n- value: bindable string value of the active tab (defaults to the first enabled tab's value).\n- defaultValue: initial active tab value when value is omitted.\n- onValueChange: called once per change with { value, item, index, reason } (`TabsValueChangePayload`). `reason` (`TabsValueChangeReason`) is `user` for a click, arrow key, menu entry or api navigation, and `initial`, `disabled` or `missing` for an automatic fallback (see Selection fallback). Not called when the current tab is re-selected or when value is changed externally.\n- placement: top, bottom, left, or right. Also drives the default tabbar orientation.\n- api: bindable TabsApi (a StepperState) for next(), previous(), and goTo(index). next() and previous() step over disabled tabs, as the arrow keys do; goTo() a disabled tab does nothing.\n- transition: panel swap timing override (`duration` in ms, `easing`); responsive, and it beats the `motion` theme slot.\n- tabbar: props forwarded to the inner Tabbar as one object \u2014 `{ size, orientation, color, alignment, fullWidth, variant, scrollFade, label, activateOnFocus, class, theme }`. `orientation` overrides the placement-derived default. `activateOnFocus: false` switches to manual activation (see below).\n- mount: when a panel's content is created \u2014 `lazy` (default) on first activation and destroyed when the tab is left, `once` on first activation and kept, `eager` for every panel up front. Inactive panels are `hidden` and `inert` in every mode.\n- class: extra classes for the root.\n- theme: theme overrides for the Tabs wrapper.\n\n## Selection fallback\n\nThe tab list and the panels always show the same tab. Tabs 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 the reason:\n\n- `initial`: on mount, defaultValue named a disabled or unknown tab; the first enabled tab is selected.\n- `disabled`: the selected tab became disabled; the first enabled tab is selected.\n- `missing`: the selected tab was 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) is never rewritten: a value naming a disabled tab shows that tab, and a value naming no tab selects no tab and shows no panel until a tab with that value appears. When every tab is disabled, nothing can be selected instead, so a value naming one of them stays selected and an unknown value shows no panel.\n\n## Manual activation\n\nBy default the arrow keys select the tab they move to. With `tabbar={{ activateOnFocus: false }}` they only move focus, and Enter, Space or a click opens the tab. Since `mount` defaults to `lazy`, selecting on focus builds and destroys a whole panel on every keypress; manual activation builds only the panel you open (APG recommends it when panels are costly).\n\n## Activation direction\n\nTabs sets `data-activation-direction` on its root and on the active panel: where the active tab sits relative to the previously active one, along the tab list's axis. The value is `left` or `right` for a horizontal list (mirrored in a right-to-left document), `up` or `down` for a vertical one (`placement` left or right), and `none` until the selection first changes. A click, a key, `api` navigation and a change of the bound `value` all set it, in the same render as the new panel. Use it to style direction-aware panel animations, for example `[data-activation-direction='right'] [role='tabpanel']:not([hidden])`. It stays until the next change.\n\n## Composition Rules\n\n- Render panel content through children.\n- Put per-panel differences in the item data and branch inside children when needed.\n- Use value (a string) as the public controlled state; compare against item values, not indexes.\n- Use api only when external controls need programmatic navigation.\n\n## Structure\n\nTabs renders a Tabbar next to a Stepper. Tabbar owns the clickable tab controls; Stepper owns the animated panel track.\n\n## Accessibility\n\nTabs wires the tablist to its panels: every tab has an id (`{id}-tabs-tab-{index}`), `aria-selected`, and `aria-controls`; every panel renders with role=\"tabpanel\", id `{id}-tabs-panel-{index}`, and `aria-labelledby` pointing back at its tab. Inactive panels are `hidden`, inert and out of the tab order, so only the active panel reaches the text and accessibility layers.\n\n## Theme Parts\n\n- root: wrapper around the Tabbar and panel content.\n- content: Stepper wrapper for tab panels.\n\nThe theme supports the placement variant on root and content.\n\n## Motion\n\n- **motion** theme slot: one preset (no variants) for the panel swap; the resolved\n  `{ in, out }` is forwarded to the inner Stepper's `transition`, where it wins.\n- Ladder: `<Theme components={{ tabs: { motion } }}>` \u2192 `setTabsTheme({ motion })` \u2192\n  `theme.motion` \u2192 the `transition` prop. Reduced motion snaps between panels.\n";

package/dist/components/Tabs/tabs.mcp.js

@@ -33,17 +33,35 @@ Use items for the tab collection and a single children snippet for the repeated
 
 - items: required array of TabItem values. Each item is used by Tabbar and passed to children as item. A string item is its own value; an object item resolves to its \`value\`, else its string label, else its index as a string.
 - children: repeated panel renderer called with { api, item, index }.
-- value: bindable string value of the active tab (defaults to the first tab's value).
+- value: bindable string value of the active tab (defaults to the first enabled tab's value).
 - defaultValue: initial active tab value when value is omitted.
-- onValueChange: called once per change with { value, item, index }; not called when the current tab is re-selected or when value is changed externally.
+- onValueChange: called once per change with { value, item, index, reason } (\`TabsValueChangePayload\`). \`reason\` (\`TabsValueChangeReason\`) is \`user\` for a click, arrow key, menu entry or api navigation, and \`initial\`, \`disabled\` or \`missing\` for an automatic fallback (see Selection fallback). Not called when the current tab is re-selected or when value is changed externally.
 - placement: top, bottom, left, or right. Also drives the default tabbar orientation.
-- api: bindable TabsApi (a StepperState) for next(), previous(), and goTo(index).
+- api: bindable TabsApi (a StepperState) for next(), previous(), and goTo(index). next() and previous() step over disabled tabs, as the arrow keys do; goTo() a disabled tab does nothing.
 - transition: panel swap timing override (\`duration\` in ms, \`easing\`); responsive, and it beats the \`motion\` theme slot.
-- tabbar: props forwarded to the inner Tabbar as one object — \`{ size, orientation, color, alignment, fullWidth, variant, scrollFade, label, class, theme }\`. \`orientation\` overrides the placement-derived default.
+- tabbar: props forwarded to the inner Tabbar as one object — \`{ size, orientation, color, alignment, fullWidth, variant, scrollFade, label, activateOnFocus, class, theme }\`. \`orientation\` overrides the placement-derived default. \`activateOnFocus: false\` switches to manual activation (see below).
 - mount: when a panel's content is created — \`lazy\` (default) on first activation and destroyed when the tab is left, \`once\` on first activation and kept, \`eager\` for every panel up front. Inactive panels are \`hidden\` and \`inert\` in every mode.
 - class: extra classes for the root.
 - theme: theme overrides for the Tabs wrapper.
 
+## Selection fallback
+
+The tab list and the panels always show the same tab. Tabs 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 the reason:
+
+- \`initial\`: on mount, defaultValue named a disabled or unknown tab; the first enabled tab is selected.
+- \`disabled\`: the selected tab became disabled; the first enabled tab is selected.
+- \`missing\`: the selected tab was 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) is never rewritten: a value naming a disabled tab shows that tab, and a value naming no tab selects no tab and shows no panel until a tab with that value appears. When every tab is disabled, nothing can be selected instead, so a value naming one of them stays selected and an unknown value shows no panel.
+
+## Manual activation
+
+By default the arrow keys select the tab they move to. With \`tabbar={{ activateOnFocus: false }}\` they only move focus, and Enter, Space or a click opens the tab. Since \`mount\` defaults to \`lazy\`, selecting on focus builds and destroys a whole panel on every keypress; manual activation builds only the panel you open (APG recommends it when panels are costly).
+
+## Activation direction
+
+Tabs sets \`data-activation-direction\` on its root and on the active panel: where the active tab sits relative to the previously active one, along the tab list's axis. The value is \`left\` or \`right\` for a horizontal list (mirrored in a right-to-left document), \`up\` or \`down\` for a vertical one (\`placement\` left or right), and \`none\` until the selection first changes. A click, a key, \`api\` navigation and a change of the bound \`value\` all set it, in the same render as the new panel. Use it to style direction-aware panel animations, for example \`[data-activation-direction='right'] [role='tabpanel']:not([hidden])\`. It stays until the next change.
+
 ## Composition Rules
 
 - Render panel content through children.

package/dist/components/Tabs/tabs.props.d.ts

@@ -9,6 +9,27 @@ import type { StepperMount } from '../Stepper/stepper.props.js';
 export type TabsPlacement = 'top' | 'bottom' | 'left' | 'right';
 /** Instance handle exposed by `bind:api` and by the repeated `children` snippet. */
 export type TabsApi<Item extends TabItem = TabItem> = StepperState<Item>;
+/**
+ * Why the active tab changed.
+ * - `user`: a click, an arrow key, a menu entry or the `api` handle picked the tab.
+ * - `initial`: on mount, `defaultValue` named a disabled or unknown tab, so the first enabled tab
+ *   was selected instead.
+ * - `disabled`: the selected tab became disabled, so the first enabled tab was selected.
+ * - `missing`: the selected tab was removed, so the enabled tab nearest to it was selected.
+ */
+export type TabsValueChangeReason = 'user' | 'initial' | 'disabled' | 'missing';
+/** Payload of Tabs' `onValueChange`. */
+export type TabsValueChangePayload<Item extends TabItem = TabItem> = {
+    /** The new active tab's value. */
+    value: string;
+    item: Item;
+    index: number;
+    /**
+     * `user` for a click, arrow key, menu entry or `api` navigation; `initial`, `disabled` or
+     * `missing` when Tabs moved the selection to an enabled tab by itself.
+     */
+    reason: TabsValueChangeReason;
+};
 export type TabsRenderPayload<Item extends TabItem = TabItem> = {
     api: TabsApi<Item>;
     item: Item;
@@ -23,20 +44,23 @@ export type TabsProps<Item extends TabItem = TabItem> = WithAttachments<{
     /**
      * The `value` of the active tab (a string item resolves to itself; objects use `value`,
      * else their string label, else their index). Bindable.
-     * @default the first tab's value
+     * A value you set is never rewritten: one naming a disabled tab shows that tab and its
+     * panel, and one naming no tab selects no tab and shows no panel. When the selected tab is
+     * removed or disabled, Tabs selects its nearest enabled neighbour or the first enabled tab,
+     * writes it back here and reports it through `onValueChange` with its `reason`.
+     * @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 with reason `initial`.
+     */
     defaultValue?: string;
     /**
-     * Callback function called when the active tab changes.
-     * Receives the new tab's value and item.
+     * Called once per change of the active tab with `{ value, item, index, reason }`.
+     * Not called when the current tab is re-selected or when `value` is changed externally.
      */
-    onValueChange?: (payload: {
-        value: string;
-        item: Item;
-        index: number;
-    }) => void;
+    onValueChange?: (payload: TabsValueChangePayload<Item>) => void;
     /**
      * The placement of the tabbar relative to the content.
      * @default 'top'
@@ -52,7 +76,8 @@ export type TabsProps<Item extends TabItem = TabItem> = WithAttachments<{
     theme?: TabsThemeProps;
     /**
      * Bindable instance handle for programmatic control.
-     * Provides methods like next(), previous(), goTo(index).
+     * Provides methods like next(), previous(), goTo(index). `next` and `previous` step over
+     * disabled tabs; `goTo` a disabled tab does nothing.
      */
     api?: TabsApi<Item>;
     /**
@@ -62,9 +87,11 @@ export type TabsProps<Item extends TabItem = TabItem> = WithAttachments<{
     transition?: ResponsiveProps<FSOProps>;
     /**
      * Props forwarded to the inner Tabbar. `orientation` falls back to the value implied by
-     * `placement` (vertical for `left`/`right`).
+     * `placement` (vertical for `left`/`right`). `activateOnFocus: false` switches to manual
+     * activation: the arrow keys only move focus, and Enter, Space or a click opens the tab, so
+     * arrowing across the list does not mount every lazy panel on the way.
      */
-    tabbar?: Pick<TabbarProps, 'size' | 'orientation' | 'color' | 'alignment' | 'class' | 'theme' | 'fullWidth' | 'label' | 'variant' | 'scrollFade'>;
+    tabbar?: Pick<TabbarProps, 'size' | 'orientation' | 'color' | 'alignment' | 'class' | 'theme' | 'fullWidth' | 'label' | 'variant' | 'scrollFade' | 'activateOnFocus'>;
     /**
      * When each panel's content is created.
      * `lazy` creates a panel the first time it is activated and destroys it when it is left,

package/dist/components/Tabs/tabs.theme.js

@@ -15,8 +15,10 @@ const defaultTabs = cva({
         placement: 'top'
     }
 });
+// `my-md` keeps panel content off the tab list. It is a margin, not padding: the Stepper positions
+// its panel track from the padding box, so padding on it would offset the panels.
 const defaultTabsContent = cva({
-    base: 'w-full  flex-full',
+    base: 'my-md w-full flex-full',
     variants: {
         placement: {
             top: 'w-full',

package/dist/components/Theme/Theme.svelte

@@ -5,7 +5,7 @@
 	import BeforeHydratation from '../Utils/BeforeHydratation.svelte';
 	import { Theme as SvelteTheme } from 'svelte-themes';
 	import { ThemeState } from './theme.state.svelte.js';
-	import { compileThemeBlockingScript } from './helper.js';
+	import { compileThemeBlockingScript, compileViewportScript, disableAnimation } from './helper.js';
 	import TooltipHost from '../Tooltip/TooltipHost.svelte';
 	import DialogBackdrop from '../Dialog/DialogBackdrop.svelte';
 	import type { ThemeProps } from './theme.props.js';
@@ -14,6 +14,8 @@
 	import { compileThemeDesignTokens, type ThemeDesignTokens } from './theme.designTokens.js';
 	import { mergeMotionTokens } from '../../tailwind/scales.js';
 	import { REDUCED_MOTION_ATTRIBUTE, REDUCED_MOTION_QUERY } from '../../utils/motion.svelte.js';
+	import { untrack } from 'svelte';
+	import { installFocusHistory } from '../../utils/focusHistory.js';
 
 	let {
 		children,
@@ -32,7 +34,9 @@
 		colorScheme,
 		reduceMotion,
 		motion,
-		components
+		components,
+		nonce,
+		portalContainer
 	}: ThemeProps<T> = $props();
 
 	const validatedDefaultTheme = (() => {
@@ -83,10 +87,30 @@
 		get storageKey() {
 			return storageKey;
 		},
-		// `transitionOnChange` is the positive form of svelte-themes' `disableTransitionOnChange`.
-		get disableTransitionOnChange() {
-			return !transitionOnChange;
-		}
+		// svelte-themes would inject its transition-suppressing style element without a nonce; the
+		// effects below do that part with the Theme `nonce`, around the same DOM update.
+		disableTransitionOnChange: false
+	});
+
+	// `transitionOnChange={false}` suppresses CSS transitions for the swap. The pre effect runs
+	// before svelte-themes applies the resolved theme (its effect was created first, in the
+	// constructor above) and the effect after it, so the style brackets the DOM update.
+	let restoreTransitions: (() => void) | null = null;
+	$effect.pre(() => {
+		void theme.resolvedTheme;
+		// `transitionOnChange` is read untracked: this effect must only re-run with a theme swap,
+		// because only the post effect below (which follows `resolvedTheme` alone) releases the
+		// style. Re-running on the prop would leave `*{transition:none!important}` in the head.
+		untrack(() => {
+			if (transitionOnChange) return;
+			restoreTransitions?.();
+			restoreTransitions = disableAnimation(nonce);
+		});
+	});
+	$effect(() => {
+		void theme.resolvedTheme;
+		restoreTransitions?.();
+		restoreTransitions = null;
 	});
 
 	const entasisTheme = new ThemeState(
@@ -114,6 +138,12 @@
 			get componentThemes() {
 				return components;
 			},
+			get nonce() {
+				return nonce;
+			},
+			get portalContainer() {
+				return portalContainer;
+			},
 			get defaultColor() {
 				const resolved = theme.resolvedTheme;
 				if (!resolved || !designTokens) return 'neutral';
@@ -126,6 +156,10 @@
 		theme
 	);
 
+	// Remember where focus has been, so a dialog whose opener left the page (a menu item) can hand
+	// focus to the last element that is still there.
+	$effect(() => installFocusHistory(document));
+
 	// Mirror the resolved preference onto <html> so CSS-only animations (Marquee, Code)
 	// can honour it. The blocking script below sets it before hydration so a
 	// reduced-motion user never sees a first frame of animation.
@@ -162,7 +196,8 @@
 			syncColorScheme,
 			forcedTheme,
 			defaultTheme: validatedDefaultTheme,
-			attribute
+			attribute,
+			nonce
 		})
 	);
 </script>
@@ -170,27 +205,9 @@
 <BeforeHydratation
 	immediate
 	once
-	scripts={[
-		/* js */ `
-	(() => {
-			const visualViewport = window.visualViewport;
-			const setWindowHeight = () => {
-				const height = visualViewport?.height ?? window.innerHeight;
-				document.documentElement.style.setProperty('--window-height', height + 'px');
-			};
-			const setWindowWidth = () => {
-				document.documentElement.style.setProperty('--window-width', window.innerWidth + 'px');
-			};
-			window.addEventListener('resize', setWindowHeight);
-			window.addEventListener('resize', setWindowWidth);
-			visualViewport?.addEventListener('resize', setWindowHeight);
-			setWindowHeight();
-			setWindowWidth();
-	})();
-`,
-		reduceMotionScript
-	]}
+	scripts={[compileViewportScript(), reduceMotionScript]}
 	css={[designTokenCss]}
+	{nonce}
 />
 
 <svelte:head>

package/dist/components/Theme/helper.d.ts

@@ -1,4 +1,5 @@
-export declare const disableAnimation: () => () => void;
+/** Suspends every CSS transition until the returned function runs; the style carries `nonce`. */
+export declare const disableAnimation: (nonce?: string) => () => void;
 export declare const escapeForInlineScript: (json: unknown) => string;
 export declare const escapeJsString: (s: string) => string;
 export declare const MEDIA = "(prefers-color-scheme: dark)";
@@ -13,9 +14,22 @@ type ThemeBlockingScriptOptions = {
     forcedTheme?: string;
     defaultTheme: string;
     attribute: string;
+    /** The CSP nonce stamped on the emitted `<script>`. */
+    nonce?: string;
 };
 /** Blocking `<head>` script that applies the stored theme before first paint. */
-export declare const compileThemeBlockingScript: ({ value, colorScheme, themes, validThemes, storageKey, systemTheme, syncColorScheme, forcedTheme, defaultTheme, attribute }: ThemeBlockingScriptOptions) => string;
+export declare const compileThemeBlockingScript: ({ value, colorScheme, themes, validThemes, storageKey, systemTheme, syncColorScheme, forcedTheme, defaultTheme, attribute, nonce }: ThemeBlockingScriptOptions) => string;
+/** The custom property carrying how far the on-screen keyboard overlaps the layout viewport. */
+export declare const KEYBOARD_INSET_VARIABLE = "--keyboard-inset";
+/**
+ * Boot script that mirrors the viewport onto `<html>`: `--window-height` and `--window-width`,
+ * and `--keyboard-inset`, the px height the on-screen keyboard (or any other browser UI that
+ * shrinks only the visual viewport) covers at the bottom of the layout viewport, `0px` without
+ * one. A pinch zoom also shrinks the visual viewport, so the inset stays `0px` while it is
+ * zoomed. Browsers that resize the layout viewport for the keyboard report no overlap either.
+ * Written as a self-contained string because it runs before hydration.
+ */
+export declare const compileViewportScript: () => string;
 export declare const colorSchemes: readonly ["light", "dark"];
 export type ColorScheme = (typeof colorSchemes)[number];
 export {};

package/dist/components/Theme/helper.js

@@ -1,6 +1,8 @@
+import { applyCspNonce, nonceAttribute } from '../../utils/cspNonce.js';
 const ANIMATION_DELAY_MS = 1;
-export const disableAnimation = () => {
-    const css = document.createElement('style');
+/** Suspends every CSS transition until the returned function runs; the style carries `nonce`. */
+export const disableAnimation = (nonce) => {
+    const css = applyCspNonce(document.createElement('style'), nonce);
     css.appendChild(document.createTextNode(`*{-webkit-transition:none!important;-moz-transition:none!important;-o-transition:none!important;-ms-transition:none!important;transition:none!important}`));
     document.head.appendChild(css);
     return () => {
@@ -25,7 +27,7 @@ export const escapeJsString = (s) => String(s)
     .replace(/\u2029/g, '\\u2029');
 export const MEDIA = '(prefers-color-scheme: dark)';
 /** Blocking `<head>` script that applies the stored theme before first paint. */
-export const compileThemeBlockingScript = ({ value, colorScheme, themes, validThemes, storageKey, systemTheme, syncColorScheme, forcedTheme, defaultTheme, attribute }) => {
+export const compileThemeBlockingScript = ({ value, colorScheme, themes, validThemes, storageKey, systemTheme, syncColorScheme, forcedTheme, defaultTheme, attribute, nonce }) => {
     const classNames = !value ? [...(themes ?? [])] : Object.values(value);
     const escapedDefaultTheme = escapeJsString(defaultTheme);
     const escapedStorageKey = escapeJsString(storageKey);
@@ -44,7 +46,7 @@ export const compileThemeBlockingScript = ({ value, colorScheme, themes, validTh
     const applyStmt = attribute === 'class'
         ? `d.classList.add(val);`
         : `d.setAttribute('${escapeJsString(attribute)}', val);`;
-    return `<script>
+    return `<script${nonceAttribute(nonce)}>
 		function svelteTheme(){
 		var d=document.documentElement;
 		var x=${escapeForInlineScript(value || {})};
@@ -69,4 +71,44 @@ export const compileThemeBlockingScript = ({ value, colorScheme, themes, validTh
 		};svelteTheme();
 		</script>`;
 };
+/** The custom property carrying how far the on-screen keyboard overlaps the layout viewport. */
+export const KEYBOARD_INSET_VARIABLE = '--keyboard-inset';
+/**
+ * Boot script that mirrors the viewport onto `<html>`: `--window-height` and `--window-width`,
+ * and `--keyboard-inset`, the px height the on-screen keyboard (or any other browser UI that
+ * shrinks only the visual viewport) covers at the bottom of the layout viewport, `0px` without
+ * one. A pinch zoom also shrinks the visual viewport, so the inset stays `0px` while it is
+ * zoomed. Browsers that resize the layout viewport for the keyboard report no overlap either.
+ * Written as a self-contained string because it runs before hydration.
+ */
+export const compileViewportScript = () => /* js */ `
+(() => {
+	const visualViewport = window.visualViewport;
+	const root = document.documentElement;
+	const setWindowHeight = () => {
+		const height = visualViewport?.height ?? window.innerHeight;
+		root.style.setProperty('--window-height', height + 'px');
+	};
+	const setWindowWidth = () => {
+		root.style.setProperty('--window-width', window.innerWidth + 'px');
+	};
+	const setKeyboardInset = () => {
+		const zoomed = !!visualViewport && Math.abs(visualViewport.scale - 1) > 0.01;
+		const inset =
+			visualViewport && !zoomed
+				? Math.max(0, Math.round(window.innerHeight - visualViewport.height - visualViewport.offsetTop))
+				: 0;
+		root.style.setProperty('${KEYBOARD_INSET_VARIABLE}', inset + 'px');
+	};
+	window.addEventListener('resize', setWindowHeight);
+	window.addEventListener('resize', setWindowWidth);
+	window.addEventListener('resize', setKeyboardInset);
+	visualViewport?.addEventListener('resize', setWindowHeight);
+	visualViewport?.addEventListener('resize', setKeyboardInset);
+	visualViewport?.addEventListener('scroll', setKeyboardInset);
+	setWindowHeight();
+	setWindowWidth();
+	setKeyboardInset();
+})();
+`;
 export const colorSchemes = ['light', 'dark'];