entasis 0.10.2 → 0.12.0

package/dist/components/Toast/toast.theme.js

@@ -219,7 +219,7 @@ const defaultToastDescription = cva({
 // (margins, border, padding, sizing) and lets pointer events fall through — the
 // toasts themselves re-enable pointer-events.
 const defaultToaster = cva({
-    base: 'pointer-events-none fixed inset-0 z-[9999] m-0 h-full w-full max-h-none max-w-none overflow-hidden border-0 bg-transparent p-0'
+    base: 'pointer-events-none fixed inset-0 z-[9999] m-0 h-full w-full max-h-none max-w-none overflow-hidden border-0 bg-transparent p-0 outline-none'
 });
 // Motion preset, keyed by the toast's resolved `position`: every toast flies in from
 // the screen edge it is pinned to and leaves the same way. Banners slide by their own

package/dist/components/ToggleButton/ToggleButton.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import type { Attachment } from 'svelte/attachments';
 	import Slot from '../Slot/Slot.svelte';
 	import type { ToggleButtonProps } from './toggleButton.props.js';
 	import { useToggleButtonTheme } from './toggleButton.theme.js';
@@ -17,6 +18,7 @@
 		size = 'normal',
 		ref = $bindable(),
 		disabled = false,
+		focusableWhenDisabled = false,
 		theme,
 		defaultValue = false,
 		value = $bindable(),
@@ -35,6 +37,23 @@
 		!!((!children && prefix && !suffix) || (!children && !prefix && suffix))
 	);
 
+	// A disabled button leaves the tab order through the native attribute, unless it is
+	// `focusableWhenDisabled`: then it keeps focus and announces `aria-disabled` instead.
+	const nativeDisabled = $derived(disabled && !focusableWhenDisabled);
+
+	// A focusable disabled button still receives clicks (and Enter or Space), so a capture listener
+	// cancels them before the group's or the consumer's own handlers see them. It is registered
+	// once and reads `disabled` on each click.
+	const refuseDisabledActivation: Attachment<HTMLElement> = (node) => {
+		const refuse = (event: MouseEvent) => {
+			if (!disabled) return;
+			event.preventDefault();
+			event.stopImmediatePropagation();
+		};
+		node.addEventListener('click', refuse, { capture: true });
+		return () => node.removeEventListener('click', refuse, { capture: true });
+	};
+
 	const classes = $derived(useToggleButtonTheme(theme));
 	const resolvedColor = $derived(useDefaultColor(color));
 </script>
@@ -48,7 +67,8 @@
 	{role}
 	aria-pressed={role === 'radio' ? undefined : valueState.value}
 	aria-checked={role === 'radio' ? valueState.value : undefined}
-	{disabled}
+	disabled={nativeDisabled ? true : undefined}
+	aria-disabled={disabled && !nativeDisabled ? true : undefined}
 	class={classes.root({
 		color: resolvedColor,
 		checked: valueState.value,
@@ -56,8 +76,10 @@
 		variant,
 		size,
 		disabled,
+		focusable: focusableWhenDisabled,
 		className
 	})}
+	{@attach refuseDisabledActivation}
 	onclick={() => {
 		if (!disabled) {
 			valueState.value = !valueState.value;

package/dist/components/ToggleButton/toggleButton.mcp.d.ts

@@ -1 +1 @@
-export declare const toggleButtonDescription = "\n# ToggleButton Component\n\nThe ToggleButton component is a two-state button that can be toggled on and off, useful for binary settings and selections.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet isActive = $state(false);\n</script>\n\n<ToggleButton bind:value={isActive}>\n\tToggle Me\n</ToggleButton>\n```\n\n## Props\n\n### Core Props\n- **value**: boolean (bindable) - Toggle state\n- **defaultValue**: boolean (default: false) - Initial state when value is omitted\n- **label**: string - Accessible name for icon-only buttons\n- **type**: 'button' | 'submit' | 'reset' (default: 'button') - Native button type. The default prevents accidental form submission.\n- **role**: 'radio' - Exposes the pressed state as `aria-checked` instead of `aria-pressed`. Set by ToggleButtonGroup in `type=\"single\"` mode; rarely needed on a standalone button\n\n### Visual Props\n- **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' (default: 'neutral')\n- **variant**: 'outline' | 'ghost' (default: 'ghost') \u2014 a Button subset. Resting outline uses the same border and surface recipe as Button; the pressed state adds a muted fill.\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n\n### State Props\n- **disabled**: boolean (default: false) - Disables interaction\n\n### Event Props\n- **onValueChange**: (value: boolean) => void - Called once when toggle state changes\n\n### Content Slots\n- **children**: Snippet - Button content\n- **prefix**: Snippet - Content before text (typically icons)\n- **suffix**: Snippet - Content after text (typically icons)\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Examples\n\n### Basic Toggle\n```svelte\n<script>\n\tlet value = $state(false);\n</script>\n\n<ToggleButton bind:value>\n\t{value ? 'On' : 'Off'}\n</ToggleButton>\n```\n\n### With Icon\n```svelte\n<script lang=\"ts\">\n\timport { textBIcon } from 'entasis/icons/textB';\n\n\tlet isBold = $state(false);\n</script>\n\n<ToggleButton bind:value={isBold}>\n\t{#snippet prefix()}\n\t\t{@render textBIcon()}\n\t{/snippet}\n\tBold\n</ToggleButton>\n```\n\n### Different Variants\n```svelte\n<ToggleButton variant=\"ghost\" bind:value>Ghost</ToggleButton>\n<ToggleButton variant=\"outline\" bind:value>Outline</ToggleButton>\n```\n\n### Different Colors\n```svelte\n<ToggleButton color=\"primary\" bind:value>Primary</ToggleButton>\n<ToggleButton color=\"danger\" bind:value>Danger</ToggleButton>\n<ToggleButton color=\"success\" bind:value>Success</ToggleButton>\n```\n\n### Toolbar Buttons\n```svelte\n<script lang=\"ts\">\n\timport { textBIcon } from 'entasis/icons/textB';\n\timport { textItalicIcon } from 'entasis/icons/textItalic';\n\timport { textUnderlineIcon } from 'entasis/icons/textUnderline';\n\n\tlet format = $state({ bold: false, italic: false, underline: false });\n</script>\n\n<div class=\"flex gap-1\">\n\t<ToggleButton bind:value={format.bold}>\n\t\t{#snippet prefix()}\n\t\t\t{@render textBIcon()}\n\t\t{/snippet}\n\t</ToggleButton>\n\t<ToggleButton bind:value={format.italic}>\n\t\t{#snippet prefix()}\n\t\t\t{@render textItalicIcon()}\n\t\t{/snippet}\n\t</ToggleButton>\n\t<ToggleButton bind:value={format.underline}>\n\t\t{#snippet prefix()}\n\t\t\t{@render textUnderlineIcon()}\n\t\t{/snippet}\n\t</ToggleButton>\n</div>\n```\n\n### With Change Handler\n```svelte\n<script>\n\tfunction handleChange(value) {\n\t\tconsole.log('Toggled:', value);\n\t}\n</script>\n\n<ToggleButton onValueChange={handleChange}>\n\tNotify Me\n</ToggleButton>\n```\n\n### Disabled State\n```svelte\n<ToggleButton disabled value>Disabled On</ToggleButton>\n<ToggleButton disabled>Disabled Off</ToggleButton>\n```\n\n## Accessibility\n\n- Exposes the checked state through `aria-pressed` (or `aria-checked` when `role=\"radio\"`)\n- Renders `type=\"button\"` unless explicitly overridden\n- Keyboard accessible (Space/Enter to toggle)\n- Focus states for keyboard navigation\n- Screen reader friendly\n\n## Notes\n\n- Maintains toggle state between interactions\n- Visual feedback for checked/unchecked states\n- Can be used standalone or in ToggleButtonGroup\n- Supports all standard button features\n\n## Theme Customization\n\nThe ToggleButton 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 button element styles\n- **prefix**: Prefix icon/content styles\n- **suffix**: Suffix icon/content styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for button element\n- Variants:\n  - checked: boolean - Checked/toggled state styling\n  - disabled: boolean - Disabled state styling\n  - color: Color variants\n  - variant: 'outline' | 'ghost' - Button variant\n  - squared: boolean - Square button styling\n  - size: 'small' | 'normal' | 'large' - Button size\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n  - checked: boolean - Checked state styling\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n  - checked: boolean - Checked state styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<ToggleButton \n  bind:value\n  theme={{\n    root: {\n      base: 'rounded-md transition-all',\n      checked: {\n        true: 'bg-primary text-white',\n        false: 'bg-gray-200'\n      },\n      size: {\n        normal: 'px-4 py-2'\n      }\n    }\n  }}\n>\n  Toggle\n</ToggleButton>\n```\n\n**Custom Checked State**:\n```svelte\n<script lang=\"ts\">\n  import { checkIcon } from 'entasis/icons/check';\n</script>\n\n<ToggleButton \n  bind:value\n  variant=\"outline\"\n  theme={{\n    root: {\n      variant: {\n        outline: 'border-2'\n      },\n      checked: {\n        true: 'border-primary bg-primary/10 text-primary',\n        false: 'border-gray-300'\n      }\n    },\n    prefix: {\n      checked: {\n        true: 'text-primary'\n      }\n    }\n  }}\n>\n  {#snippet prefix()}\n    {@render checkIcon()}\n  {/snippet}\n  Toggle\n</ToggleButton>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setToggleButtonTheme } from './index.ts';\n  \n  setToggleButtonTheme({\n    root: {\n      base: 'transition-all duration-100',\n      checked: {\n        true: 'bg-primary text-white',\n        false: 'bg-gray-200'\n      },\n      size: {\n        normal: 'px-4 py-2 h-8'\n      }\n    },\n    prefix: {\n      size: {\n        normal: 'max-w-6 max-h-6'\n      }\n    }\n  });\n</script>\n```\n";
+export declare const toggleButtonDescription = "\n# ToggleButton Component\n\nThe ToggleButton component is a two-state button that can be toggled on and off, useful for binary settings and selections.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet isActive = $state(false);\n</script>\n\n<ToggleButton bind:value={isActive}>\n\tToggle Me\n</ToggleButton>\n```\n\n## Props\n\n### Core Props\n- **value**: boolean (bindable) - Toggle state\n- **defaultValue**: boolean (default: false) - Initial state when value is omitted\n- **label**: string - Accessible name for icon-only buttons\n- **type**: 'button' | 'submit' | 'reset' (default: 'button') - Native button type. The default prevents accidental form submission.\n- **role**: 'radio' - Exposes the pressed state as `aria-checked` instead of `aria-pressed`. Set by ToggleButtonGroup in `type=\"single\"` mode; rarely needed on a standalone button\n\n### Visual Props\n- **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' (default: 'neutral')\n- **variant**: 'outline' | 'ghost' (default: 'ghost') \u2014 a Button subset. Resting outline uses the same border and surface recipe as Button; the pressed state adds a muted fill.\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n\n### State Props\n- **disabled**: boolean (default: false) - Disables interaction. The button gets the native `disabled` attribute and leaves the tab order, unless `focusableWhenDisabled` is set\n- **focusableWhenDisabled**: boolean (default: false) - Keeps a `disabled` button focusable: it renders `aria-disabled=\"true\"` instead of the native attribute, stays in the tab order, still receives pointer events (for a tooltip that explains why), and refuses to toggle: clicks from the pointer, Enter and Space are cancelled before any other listener sees them. Has no effect without `disabled`\n\n### Event Props\n- **onValueChange**: (value: boolean) => void - Called once when toggle state changes\n\n### Content Slots\n- **children**: Snippet - Button content\n- **prefix**: Snippet - Content before text (typically icons)\n- **suffix**: Snippet - Content after text (typically icons)\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Examples\n\n### Basic Toggle\n```svelte\n<script>\n\tlet value = $state(false);\n</script>\n\n<ToggleButton bind:value>\n\t{value ? 'On' : 'Off'}\n</ToggleButton>\n```\n\n### With Icon\n```svelte\n<script lang=\"ts\">\n\timport { textBIcon } from 'entasis/icons/textB';\n\n\tlet isBold = $state(false);\n</script>\n\n<ToggleButton bind:value={isBold}>\n\t{#snippet prefix()}\n\t\t{@render textBIcon()}\n\t{/snippet}\n\tBold\n</ToggleButton>\n```\n\n### Different Variants\n```svelte\n<ToggleButton variant=\"ghost\" bind:value>Ghost</ToggleButton>\n<ToggleButton variant=\"outline\" bind:value>Outline</ToggleButton>\n```\n\n### Different Colors\n```svelte\n<ToggleButton color=\"primary\" bind:value>Primary</ToggleButton>\n<ToggleButton color=\"danger\" bind:value>Danger</ToggleButton>\n<ToggleButton color=\"success\" bind:value>Success</ToggleButton>\n```\n\n### Toolbar Buttons\n```svelte\n<script lang=\"ts\">\n\timport { textBIcon } from 'entasis/icons/textB';\n\timport { textItalicIcon } from 'entasis/icons/textItalic';\n\timport { textUnderlineIcon } from 'entasis/icons/textUnderline';\n\n\tlet format = $state({ bold: false, italic: false, underline: false });\n</script>\n\n<div class=\"flex gap-1\">\n\t<ToggleButton bind:value={format.bold}>\n\t\t{#snippet prefix()}\n\t\t\t{@render textBIcon()}\n\t\t{/snippet}\n\t</ToggleButton>\n\t<ToggleButton bind:value={format.italic}>\n\t\t{#snippet prefix()}\n\t\t\t{@render textItalicIcon()}\n\t\t{/snippet}\n\t</ToggleButton>\n\t<ToggleButton bind:value={format.underline}>\n\t\t{#snippet prefix()}\n\t\t\t{@render textUnderlineIcon()}\n\t\t{/snippet}\n\t</ToggleButton>\n</div>\n```\n\n### With Change Handler\n```svelte\n<script>\n\tfunction handleChange(value) {\n\t\tconsole.log('Toggled:', value);\n\t}\n</script>\n\n<ToggleButton onValueChange={handleChange}>\n\tNotify Me\n</ToggleButton>\n```\n\n### Disabled State\n```svelte\n<ToggleButton disabled value>Disabled On</ToggleButton>\n<ToggleButton disabled>Disabled Off</ToggleButton>\n```\n\n## Accessibility\n\n- Exposes the checked state through `aria-pressed` (or `aria-checked` when `role=\"radio\"`)\n- Renders `type=\"button\"` unless explicitly overridden\n- Keyboard accessible (Space/Enter to toggle)\n- Focus states for keyboard navigation\n- Screen reader friendly\n\n## Notes\n\n- Maintains toggle state between interactions\n- Visual feedback for checked/unchecked states\n- Can be used standalone or in ToggleButtonGroup\n- Supports all standard button features\n\n## Theme Customization\n\nThe ToggleButton 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 button element styles\n- **prefix**: Prefix icon/content styles\n- **suffix**: Suffix icon/content styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for button element\n- Variants:\n  - checked: boolean - Checked/toggled state styling\n  - disabled: boolean - Disabled state styling\n  - focusable: boolean - Set with `focusableWhenDisabled`: a disabled button keeps its pointer events\n  - color: Color variants\n  - variant: 'outline' | 'ghost' - Button variant\n  - squared: boolean - Square button styling\n  - size: 'small' | 'normal' | 'large' - Button size\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n  - checked: boolean - Checked state styling\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n  - checked: boolean - Checked state styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<ToggleButton \n  bind:value\n  theme={{\n    root: {\n      base: 'rounded-md transition-all',\n      checked: {\n        true: 'bg-primary text-white',\n        false: 'bg-gray-200'\n      },\n      size: {\n        normal: 'px-4 py-2'\n      }\n    }\n  }}\n>\n  Toggle\n</ToggleButton>\n```\n\n**Custom Checked State**:\n```svelte\n<script lang=\"ts\">\n  import { checkIcon } from 'entasis/icons/check';\n</script>\n\n<ToggleButton \n  bind:value\n  variant=\"outline\"\n  theme={{\n    root: {\n      variant: {\n        outline: 'border-2'\n      },\n      checked: {\n        true: 'border-primary bg-primary/10 text-primary',\n        false: 'border-gray-300'\n      }\n    },\n    prefix: {\n      checked: {\n        true: 'text-primary'\n      }\n    }\n  }}\n>\n  {#snippet prefix()}\n    {@render checkIcon()}\n  {/snippet}\n  Toggle\n</ToggleButton>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setToggleButtonTheme } from './index.ts';\n  \n  setToggleButtonTheme({\n    root: {\n      base: 'transition-all duration-100',\n      checked: {\n        true: 'bg-primary text-white',\n        false: 'bg-gray-200'\n      },\n      size: {\n        normal: 'px-4 py-2 h-8'\n      }\n    },\n    prefix: {\n      size: {\n        normal: 'max-w-6 max-h-6'\n      }\n    }\n  });\n</script>\n```\n";

package/dist/components/ToggleButton/toggleButton.mcp.js

@@ -30,7 +30,8 @@ The ToggleButton component is a two-state button that can be toggled on and off,
 - **size**: 'small' | 'normal' | 'large' (default: 'normal')
 
 ### State Props
-- **disabled**: boolean (default: false) - Disables interaction
+- **disabled**: boolean (default: false) - Disables interaction. The button gets the native \`disabled\` attribute and leaves the tab order, unless \`focusableWhenDisabled\` is set
+- **focusableWhenDisabled**: boolean (default: false) - Keeps a \`disabled\` button focusable: it renders \`aria-disabled="true"\` instead of the native attribute, stays in the tab order, still receives pointer events (for a tooltip that explains why), and refuses to toggle: clicks from the pointer, Enter and Space are cancelled before any other listener sees them. Has no effect without \`disabled\`
 
 ### Event Props
 - **onValueChange**: (value: boolean) => void - Called once when toggle state changes
@@ -167,6 +168,7 @@ The theme object contains the following parts:
 - Variants:
   - checked: boolean - Checked/toggled state styling
   - disabled: boolean - Disabled state styling
+  - focusable: boolean - Set with \`focusableWhenDisabled\`: a disabled button keeps its pointer events
   - color: Color variants
   - variant: 'outline' | 'ghost' - Button variant
   - squared: boolean - Square button styling

package/dist/components/ToggleButton/toggleButton.props.d.ts

@@ -22,8 +22,20 @@ export type ToggleButtonProps = WithAttachments<WithSlot<{
     variant?: ToggleButtonVariant;
     /** Size token controlling padding, height, and typography. */
     size?: Sizes;
-    /** When true, prevents toggling and applies disabled styles. */
+    /**
+     * When true, prevents toggling and applies disabled styles. The button gets the native
+     * `disabled` attribute and leaves the tab order, unless `focusableWhenDisabled` is set.
+     */
     disabled?: boolean;
+    /**
+     * When true, a `disabled` button stays focusable: it renders `aria-disabled="true"`
+     * instead of the native `disabled` attribute, keeps its place in the tab order and still
+     * receives pointer events, and refuses to toggle: clicks from the pointer, Enter and
+     * Space are cancelled before any other listener sees them. Inside a ToggleButtonGroup the
+     * arrow keys stop on it. Has no effect without `disabled`.
+     * @default false
+     */
+    focusableWhenDisabled?: boolean;
     /**
      * The class name of the button. First element that the component outputs in the DOM.
      */

package/dist/components/ToggleButton/toggleButton.theme.d.ts

@@ -9,6 +9,10 @@ export declare const toggleButtonTheme: {
             true: string;
             false: null;
         };
+        focusable: {
+            true: null;
+            false: null;
+        };
         color: {
             primary: string;
             secondary: string;
@@ -67,6 +71,10 @@ export declare const setToggleButtonTheme: (theme: InferComponentTheme<{
             true: string;
             false: null;
         };
+        focusable: {
+            true: null;
+            false: null;
+        };
         color: {
             primary: string;
             secondary: string;
@@ -123,6 +131,10 @@ export declare const useToggleButtonTheme: import("../../utils/cva/theme.js").Us
             true: string;
             false: null;
         };
+        focusable: {
+            true: null;
+            false: null;
+        };
         color: {
             primary: string;
             secondary: string;

package/dist/components/ToggleButton/toggleButton.theme.js

@@ -9,7 +9,13 @@ const defaultButton = cva({
             false: null
         },
         disabled: {
-            true: 'opacity-50 cursor-not-allowed pointer-events-none',
+            true: 'opacity-50 cursor-not-allowed',
+            false: null
+        },
+        // Disabled but still focusable (`focusableWhenDisabled`): it renders `aria-disabled`, so it
+        // keeps its pointer events for the click guard and for hover tooltips.
+        focusable: {
+            true: null,
             false: null
         },
         color: {
@@ -39,9 +45,12 @@ const defaultButton = cva({
         checked: false,
         size: 'normal',
         variant: 'ghost',
-        color: 'neutral'
+        color: 'neutral',
+        focusable: false
     },
     compoundVariants: [
+        // A natively disabled button takes no pointer events; a focusable one keeps them.
+        { disabled: true, focusable: false, class: 'pointer-events-none' },
         // Mirrors button.theme.ts: the neutral outline is toolbar chrome next to inputs and selects,
         // which all draw a `neutral-muted` hairline; a full-strength neutral border made it the odd
         // one out.
@@ -55,7 +64,10 @@ const defaultButton = cva({
             variant: 'outline',
             checked: true,
             class: `${selectedSoft} border-color`
-        }
+        },
+        // A pressed neutral outline keeps its hairline: the soft fill shows the selection, and a
+        // full-strength neutral border boxed the pressed segment off from the rest of a joined group.
+        { color: 'neutral', variant: 'outline', checked: true, class: 'border-neutral-muted' }
     ]
 });
 const defaultToggleButtonPrefix = cva({

package/dist/components/ToggleButtonGroup/ToggleButtonGroup.svelte

@@ -26,6 +26,8 @@
 		variant,
 		disabled,
 		joined = false,
+		orientation = 'horizontal',
+		loopFocus = true,
 		type = 'multiple' as Type,
 		theme,
 		class: className,
@@ -42,20 +44,35 @@
 
 	const classes = $derived(useToggleButtonGroupTheme(theme));
 	const id = $props.id();
-	// One tab stop for the whole group; arrows move between buttons (Radix ToggleGroup / Toolbar).
-	const navigation = useNavigation({
-		orientation: 'horizontal',
-		loop: true,
-		id,
-		enableHoverFocus: false
-	});
-
 	const pressed = $derived.by(() => {
 		const current = valueState.value as string[] | string | undefined;
 		if (Array.isArray(current)) return current;
 		return current === undefined ? [] : [current];
 	});
 
+	// One tab stop for the whole group, on the first pressed enabled button (the first enabled one
+	// when nothing is pressed); arrows move between buttons (Radix ToggleGroup / Toolbar). The group
+	// element is never a tab stop, so Shift+Tab leaves it in one step and a disabled group has no
+	// tabbable element. Buttons that are `focusableWhenDisabled` stay in the arrow-key order.
+	const navigation = useNavigation({
+		orientation: () => orientation,
+		get loop() {
+			return loopFocus;
+		},
+		id,
+		enableHoverFocus: false,
+		focusableContainer: false,
+		disabledItemsFocusable: true,
+		defaultFocusedIndex: () => {
+			const index = items.findIndex(
+				(item) =>
+					pressed.includes(item.value) &&
+					(!(disabled || item.disabled) || item.focusableWhenDisabled)
+			);
+			return index === -1 ? null : index;
+		}
+	});
+
 	function getButtonProps(item: ToggleButtonGroupItem) {
 		// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Strip the group keys before forwarding native toggle props.
 		const { value: _value, onValueChange: _onValueChange, ...props } = item;
@@ -78,9 +95,12 @@
 <div
 	role={type === 'single' ? 'radiogroup' : 'group'}
 	aria-label={label}
+	aria-orientation={type === 'single' ? orientation : undefined}
 	data-color={color}
 	data-type={type}
-	class={classes.root({ className, joined })}
+	data-orientation={orientation}
+	data-disabled={disabled ? '' : undefined}
+	class={classes.root({ className, joined, orientation })}
 	{@attach navigation.containerReference}
 	{...attachments}
 >

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

@@ -1,3 +1,3 @@
 export { default as ToggleButtonGroup } from './ToggleButtonGroup.svelte';
-export type { ToggleButtonGroupItem, ToggleButtonGroupItems, ToggleButtonGroupProps, ToggleButtonGroupType, ToggleButtonGroupValue } from './toggleButtonGroup.props.js';
+export type { ToggleButtonGroupItem, ToggleButtonGroupItems, ToggleButtonGroupOrientation, ToggleButtonGroupProps, ToggleButtonGroupType, ToggleButtonGroupValue } from './toggleButtonGroup.props.js';
 export { toggleButtonGroupTheme, setToggleButtonGroupTheme, useToggleButtonGroupTheme, type ToggleButtonGroupTheme, type ToggleButtonGroupThemeProps } from './toggleButtonGroup.theme.js';

package/dist/components/ToggleButtonGroup/toggleButtonGroup.mcp.d.ts

@@ -1 +1 @@
-export declare const toggleButtonGroupDescription = "\n# ToggleButtonGroup Component\n\nToggleButtonGroup renders an ordered list of ToggleButton items and exposes the pressed values as one bindable value.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\tlet formatting = $state(['bold']);\n</script>\n\n<ToggleButtonGroup\n\tbind:value={formatting}\n\tlabel=\"Text formatting\"\n\tcolor=\"neutral\"\n\titems={[\n\t\t{ value: 'bold', children: 'Bold' },\n\t\t{ value: 'italic', children: 'Italic' },\n\t\t{ value: 'underline', children: 'Underline' }\n\t]}\n/>\n```\n\n## Props\n\n- **items**: ToggleButtonGroupItem[] (required) - Ordered button configurations. Each item carries a unique `value` plus ToggleButton props (no `variant`, `color`, or `size`; pressed state lives on the group value).\n- **label**: string (required) - Accessible name for the group.\n- **value**: string[] | string | undefined (bindable) - The only pressed-state source. `type=\"multiple\"` holds every pressed value as an array; `type=\"single\"` holds the checked value.\n- **defaultValue**: same shape as value - Initial pressed state when value is omitted.\n- **onValueChange**: (value) => void - Called once with the updated group value after a toggle.\n- **size**: 'small' | 'normal' | 'large' - Applied to every item.\n- **color**: Colors - Applied to every item.\n- **variant**: 'outline' | 'ghost' - Applied to every item. Defaults to 'ghost'.\n- **disabled**: boolean - Disables every item.\n- **joined**: boolean (default: false) - Renders the buttons as contiguous segments.\n- **type**: 'single' | 'multiple' (default: 'multiple') - `'multiple'` lets any number of buttons be pressed (`role=\"group\"`, `aria-pressed`) and its value is a `string[]`. `'single'` makes the selection exclusive: the value is a single string, the root becomes `role=\"radiogroup\"`, each button `role=\"radio\"` with `aria-checked`, pressing one clears the others, and the checked radio cannot be unpressed.\n- **class**: string - Additional CSS classes for the root.\n- **theme**: ToggleButtonGroupThemeProps - Theme overrides.\n\n## Examples\n\n### Icon Toolbar\n\n```svelte\n<ToggleButtonGroup\n\tbind:value={formatting}\n\tlabel=\"Text formatting\"\n\titems={[\n\t\t{ value: 'bold', prefix: textBIcon, label: 'Bold' },\n\t\t{ value: 'italic', prefix: textItalicIcon, label: 'Italic' },\n\t\t{ value: 'underline', prefix: textUnderlineIcon, label: 'Underline' }\n\t]}\n/>\n```\n\n### Joined Segments\n\n```svelte\n<ToggleButtonGroup\n\tjoined\n\tvariant=\"outline\"\n\tcolor=\"neutral\"\n\tlabel=\"Text formatting\"\n\tvalue={['bold']}\n\titems={[\n\t\t{ value: 'bold', prefix: textBIcon, label: 'Bold' },\n\t\t{ value: 'italic', prefix: textItalicIcon, label: 'Italic' },\n\t\t{ value: 'underline', prefix: textUnderlineIcon, label: 'Underline' }\n\t]}\n/>\n```\n\n### Single Selection (radio group)\n\n```svelte\n<script lang=\"ts\">\n\tlet alignment = $state('left');\n</script>\n\n<ToggleButtonGroup\n\ttype=\"single\"\n\tlabel=\"Alignment\"\n\tbind:value={alignment}\n\titems={[\n\t\t{ value: 'left', children: 'Left' },\n\t\t{ value: 'center', children: 'Center' },\n\t\t{ value: 'right', children: 'Right' }\n\t]}\n/>\n```\n\n### Change Handler\n\n```svelte\n<ToggleButtonGroup\n\tlabel=\"Density options\"\n\titems={[\n\t\t{ value: 'compact', children: 'Compact' },\n\t\t{ value: 'comfortable', children: 'Comfortable' }\n\t]}\n\tonValueChange={(value) => {\n\t\tconsole.log(value);\n\t}}\n/>\n```\n\n## Theme\n\n- **root**: Main button group container styles.\n\n## Accessibility\n\n- `type=\"multiple\"`: the root is `role=\"group\"` named by `label`; each ToggleButton exposes its independent state through `aria-pressed`.\n- `type=\"single\"`: the root is `role=\"radiogroup\"`; buttons are `role=\"radio\"` with `aria-checked`.\n- The group is a single tab stop (roving tabindex): Tab enters it, ArrowLeft / ArrowRight move between buttons (looping, mirrored in RTL), Home / End jump to the first / last, Space or Enter toggles the focused button.\n- Prefer SegmentedControl for a visually segmented exclusive choice; use `type=\"single\"` when you want toggle-button styling with exclusive semantics.\n\n## Theme example\n\n```svelte\n<ToggleButtonGroup\n\tlabel=\"Options\"\n\titems={items}\n\ttheme={{\n\t\troot: {\n\t\t\tbase: 'flex items-center gap-1'\n\t\t}\n\t}}\n/>\n```\n";
+export declare const toggleButtonGroupDescription = "\n# ToggleButtonGroup Component\n\nToggleButtonGroup renders an ordered list of ToggleButton items and exposes the pressed values as one bindable value.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\tlet formatting = $state(['bold']);\n</script>\n\n<ToggleButtonGroup\n\tbind:value={formatting}\n\tlabel=\"Text formatting\"\n\tcolor=\"neutral\"\n\titems={[\n\t\t{ value: 'bold', children: 'Bold' },\n\t\t{ value: 'italic', children: 'Italic' },\n\t\t{ value: 'underline', children: 'Underline' }\n\t]}\n/>\n```\n\n## Props\n\n- **items**: ToggleButtonGroupItem[] (required) - Ordered button configurations. Each item carries a unique `value` plus ToggleButton props (no `variant`, `color`, or `size`; pressed state lives on the group value).\n- **label**: string (required) - Accessible name for the group.\n- **value**: string[] | string | undefined (bindable) - The only pressed-state source. `type=\"multiple\"` holds every pressed value as an array; `type=\"single\"` holds the checked value.\n- **defaultValue**: same shape as value - Initial pressed state when value is omitted.\n- **onValueChange**: (value) => void - Called once with the updated group value after a toggle.\n- **size**: 'small' | 'normal' | 'large' - Applied to every item.\n- **color**: Colors - Applied to every item.\n- **variant**: 'outline' | 'ghost' - Applied to every item. Defaults to 'ghost'.\n- **disabled**: boolean - Disables every item. A disabled group has no tab stop, unless an item sets `focusableWhenDisabled`.\n- **joined**: boolean (default: false) - Renders the buttons as contiguous segments.\n- **orientation**: 'horizontal' | 'vertical' (default: 'horizontal') - Axis of the group. Horizontal lays the buttons out in a row and moves with ArrowLeft / ArrowRight; vertical stacks them (joined segments join top to bottom) and moves with ArrowUp / ArrowDown. Keys of the other axis are ignored. Reflected as `data-orientation`; a `type=\"single\"` group (radiogroup) also sets `aria-orientation`, the `group` role of a multiple group never does.\n- **loopFocus**: boolean (default: true) - Whether the arrow keys wrap from the last button to the first and back. False stops focus at the ends (Home / End still jump).\n- **type**: 'single' | 'multiple' (default: 'multiple') - `'multiple'` lets any number of buttons be pressed (`role=\"group\"`, `aria-pressed`) and its value is a `string[]`. `'single'` makes the selection exclusive: the value is a single string, the root becomes `role=\"radiogroup\"`, each button `role=\"radio\"` with `aria-checked`, pressing one clears the others, and the checked radio cannot be unpressed.\n- **class**: string - Additional CSS classes for the root.\n- **theme**: ToggleButtonGroupThemeProps - Theme overrides.\n\n## Examples\n\n### Icon Toolbar\n\n```svelte\n<ToggleButtonGroup\n\tbind:value={formatting}\n\tlabel=\"Text formatting\"\n\titems={[\n\t\t{ value: 'bold', prefix: textBIcon, label: 'Bold' },\n\t\t{ value: 'italic', prefix: textItalicIcon, label: 'Italic' },\n\t\t{ value: 'underline', prefix: textUnderlineIcon, label: 'Underline' }\n\t]}\n/>\n```\n\n### Joined Segments\n\n```svelte\n<ToggleButtonGroup\n\tjoined\n\tvariant=\"outline\"\n\tcolor=\"neutral\"\n\tlabel=\"Text formatting\"\n\tvalue={['bold']}\n\titems={[\n\t\t{ value: 'bold', prefix: textBIcon, label: 'Bold' },\n\t\t{ value: 'italic', prefix: textItalicIcon, label: 'Italic' },\n\t\t{ value: 'underline', prefix: textUnderlineIcon, label: 'Underline' }\n\t]}\n/>\n```\n\n### Single Selection (radio group)\n\n```svelte\n<script lang=\"ts\">\n\tlet alignment = $state('left');\n</script>\n\n<ToggleButtonGroup\n\ttype=\"single\"\n\tlabel=\"Alignment\"\n\tbind:value={alignment}\n\titems={[\n\t\t{ value: 'left', children: 'Left' },\n\t\t{ value: 'center', children: 'Center' },\n\t\t{ value: 'right', children: 'Right' }\n\t]}\n/>\n```\n\n### Change Handler\n\n```svelte\n<ToggleButtonGroup\n\tlabel=\"Density options\"\n\titems={[\n\t\t{ value: 'compact', children: 'Compact' },\n\t\t{ value: 'comfortable', children: 'Comfortable' }\n\t]}\n\tonValueChange={(value) => {\n\t\tconsole.log(value);\n\t}}\n/>\n```\n\n## Theme\n\n- **root**: Main button group container styles.\n\n## Accessibility\n\n- `type=\"multiple\"`: the root is `role=\"group\"` named by `label`; each ToggleButton exposes its independent state through `aria-pressed`.\n- `type=\"single\"`: the root is `role=\"radiogroup\"`; buttons are `role=\"radio\"` with `aria-checked`.\n- The group is a single tab stop (roving tabindex), and the group element itself is not focusable, so Shift+Tab leaves the group in one step. Tab lands on the first pressed enabled button, or the first enabled button when nothing is pressed. ArrowLeft / ArrowRight (ArrowUp / ArrowDown when `orientation=\"vertical\"`) move between buttons (looping unless `loopFocus={false}`, mirrored in RTL), Home / End jump to the first / last, Space or Enter toggles the focused button. Alt, Ctrl or Meta with an arrow is left to the browser.\n- An item with `focusableWhenDisabled` that is disabled stays in the arrow-key order and keeps the tab stop reachable, announced with `aria-disabled`; it cannot be toggled.\n- Prefer SegmentedControl for a visually segmented exclusive choice; use `type=\"single\"` when you want toggle-button styling with exclusive semantics.\n\n## Theme example\n\n```svelte\n<ToggleButtonGroup\n\tlabel=\"Options\"\n\titems={items}\n\ttheme={{\n\t\troot: {\n\t\t\tbase: 'flex items-center gap-1'\n\t\t}\n\t}}\n/>\n```\n";

package/dist/components/ToggleButtonGroup/toggleButtonGroup.mcp.js

@@ -32,8 +32,10 @@ ToggleButtonGroup renders an ordered list of ToggleButton items and exposes the
 - **size**: 'small' | 'normal' | 'large' - Applied to every item.
 - **color**: Colors - Applied to every item.
 - **variant**: 'outline' | 'ghost' - Applied to every item. Defaults to 'ghost'.
-- **disabled**: boolean - Disables every item.
+- **disabled**: boolean - Disables every item. A disabled group has no tab stop, unless an item sets \`focusableWhenDisabled\`.
 - **joined**: boolean (default: false) - Renders the buttons as contiguous segments.
+- **orientation**: 'horizontal' | 'vertical' (default: 'horizontal') - Axis of the group. Horizontal lays the buttons out in a row and moves with ArrowLeft / ArrowRight; vertical stacks them (joined segments join top to bottom) and moves with ArrowUp / ArrowDown. Keys of the other axis are ignored. Reflected as \`data-orientation\`; a \`type="single"\` group (radiogroup) also sets \`aria-orientation\`, the \`group\` role of a multiple group never does.
+- **loopFocus**: boolean (default: true) - Whether the arrow keys wrap from the last button to the first and back. False stops focus at the ends (Home / End still jump).
 - **type**: 'single' | 'multiple' (default: 'multiple') - \`'multiple'\` lets any number of buttons be pressed (\`role="group"\`, \`aria-pressed\`) and its value is a \`string[]\`. \`'single'\` makes the selection exclusive: the value is a single string, the root becomes \`role="radiogroup"\`, each button \`role="radio"\` with \`aria-checked\`, pressing one clears the others, and the checked radio cannot be unpressed.
 - **class**: string - Additional CSS classes for the root.
 - **theme**: ToggleButtonGroupThemeProps - Theme overrides.
@@ -113,7 +115,8 @@ ToggleButtonGroup renders an ordered list of ToggleButton items and exposes the
 
 - \`type="multiple"\`: the root is \`role="group"\` named by \`label\`; each ToggleButton exposes its independent state through \`aria-pressed\`.
 - \`type="single"\`: the root is \`role="radiogroup"\`; buttons are \`role="radio"\` with \`aria-checked\`.
-- The group is a single tab stop (roving tabindex): Tab enters it, ArrowLeft / ArrowRight move between buttons (looping, mirrored in RTL), Home / End jump to the first / last, Space or Enter toggles the focused button.
+- The group is a single tab stop (roving tabindex), and the group element itself is not focusable, so Shift+Tab leaves the group in one step. Tab lands on the first pressed enabled button, or the first enabled button when nothing is pressed. ArrowLeft / ArrowRight (ArrowUp / ArrowDown when \`orientation="vertical"\`) move between buttons (looping unless \`loopFocus={false}\`, mirrored in RTL), Home / End jump to the first / last, Space or Enter toggles the focused button. Alt, Ctrl or Meta with an arrow is left to the browser.
+- An item with \`focusableWhenDisabled\` that is disabled stays in the arrow-key order and keeps the tab stop reachable, announced with \`aria-disabled\`; it cannot be toggled.
 - Prefer SegmentedControl for a visually segmented exclusive choice; use \`type="single"\` when you want toggle-button styling with exclusive semantics.
 
 ## Theme example

package/dist/components/ToggleButtonGroup/toggleButtonGroup.props.d.ts

@@ -2,6 +2,7 @@ import type { Sizes, Colors } from '../../types/theme.js';
 import type { WithAttachments, WithoutAttachments } from '../../types/props.js';
 import type { ToggleButtonProps, ToggleButtonVariant } from '../ToggleButton/index.js';
 import type { ToggleButtonGroupThemeProps } from './toggleButtonGroup.theme.js';
+export type ToggleButtonGroupOrientation = 'horizontal' | 'vertical';
 export type ToggleButtonGroupType = 'single' | 'multiple';
 export type ToggleButtonGroupItem = Omit<WithoutAttachments<ToggleButtonProps>, 'value' | 'defaultValue' | 'variant' | 'color' | 'size'> & {
     /** Value identifying this button inside the group value. Must be unique. */
@@ -23,10 +24,27 @@ export type ToggleButtonGroupProps<Items extends ToggleButtonGroupItems = Toggle
     color?: Colors;
     /** Visual variant applied to every button in the group. */
     variant?: ToggleButtonVariant;
-    /** When true, disables all buttons in the group. */
+    /**
+     * When true, disables all buttons in the group. A disabled group has no tab stop, unless an
+     * item sets `focusableWhenDisabled`.
+     */
     disabled?: boolean;
     /** When true, renders the buttons as contiguous segments. */
     joined?: boolean;
+    /**
+     * Axis of the group: `'horizontal'` lays the buttons out in a row and moves between them with
+     * ArrowLeft and ArrowRight; `'vertical'` stacks them and uses ArrowUp and ArrowDown. Keys of
+     * the other axis are ignored. Exposed as `data-orientation`; a `type="single"` group (`radiogroup`)
+     * also sets `aria-orientation`, the `group` role of a multiple group never does.
+     * @default 'horizontal'
+     */
+    orientation?: ToggleButtonGroupOrientation;
+    /**
+     * Whether the arrow keys wrap from the last button to the first and back. When false, focus
+     * stops at the ends.
+     * @default true
+     */
+    loopFocus?: boolean;
     /**
      * `'multiple'` (default): any number of buttons can be pressed (`aria-pressed`).
      * `'single'`: at most one is checked at a time, exposed as a radio group.

package/dist/components/ToggleButtonGroup/toggleButtonGroup.theme.d.ts

@@ -1,6 +1,10 @@
 import { type InferComponentTheme } from '../../utils/cva/index.js';
 export declare const toggleButtonGroupTheme: {
     root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+        orientation: {
+            horizontal: string;
+            vertical: string;
+        };
         joined: {
             true: string;
             false: string;
@@ -11,6 +15,10 @@ export type ToggleButtonGroupTheme = typeof toggleButtonGroupTheme;
 export type ToggleButtonGroupThemeProps = InferComponentTheme<ToggleButtonGroupTheme>;
 export declare const setToggleButtonGroupTheme: (theme: InferComponentTheme<{
     root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+        orientation: {
+            horizontal: string;
+            vertical: string;
+        };
         joined: {
             true: string;
             false: string;
@@ -19,6 +27,10 @@ export declare const setToggleButtonGroupTheme: (theme: InferComponentTheme<{
 }>) => void;
 export declare const useToggleButtonGroupTheme: import("../../utils/cva/theme.js").UseComponentTheme<{
     root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+        orientation: {
+            horizontal: string;
+            vertical: string;
+        };
         joined: {
             true: string;
             false: string;

package/dist/components/ToggleButtonGroup/toggleButtonGroup.theme.js

@@ -1,14 +1,33 @@
 import { setComponentTheme, useComponentTheme } from '../../utils/cva/index.js';
 import { cva } from '../../utils/cva/index.js';
 const defaultToggleButtonGroup = cva({
-    base: 'flex items-center',
+    base: 'flex',
     variants: {
+        orientation: {
+            horizontal: 'flex-row items-center',
+            vertical: 'flex-col items-stretch'
+        },
         joined: {
-            true: 'first-child:rounded-r-none last-child:rounded-l-none not-first-not-last-child:rounded-none not-first-child:-ml-px [&>*:focus-visible]:z-10 [&>*]:active:translate-y-0',
+            // Joined segments overlap by a pixel: a pressed segment sits above its neighbours so its
+            // border is not cut by theirs, and a focused one above that.
+            true: '[&>[data-checked=true]]:z-1 [&>*:focus-visible]:z-10 [&>*]:active:translate-y-0',
             false: 'gap-xs'
         }
     },
+    compoundVariants: [
+        {
+            joined: true,
+            orientation: 'horizontal',
+            class: 'first-child:rounded-r-none last-child:rounded-l-none not-first-not-last-child:rounded-none not-first-child:-ml-px'
+        },
+        {
+            joined: true,
+            orientation: 'vertical',
+            class: 'first-child:rounded-b-none last-child:rounded-t-none not-first-not-last-child:rounded-none not-first-child:-mt-px'
+        }
+    ],
     defaultVariants: {
+        orientation: 'horizontal',
         joined: false
     }
 });