sheer-ui 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sheer-ui",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Svelte 5 UI component library with Tailwind CSS",
 	"license": "MIT",
 	"repository": {
@@ -332,7 +332,6 @@
 	"dependencies": {
 		"@lucide/svelte": "^1.18.0",
 		"esm-env": "^1.2.2",
-		"handful": "^0.3.0",
 		"d3-scale": "^4.0.2",
 		"layerchart": "^2.0.1",
 		"overrule": "^0.7.3"
@@ -341,6 +340,7 @@
 		"@changesets/changelog-github": "^1.0.0",
 		"@changesets/cli": "^3.0.1",
 		"@fontsource-variable/inter": "^5.2.8",
+		"handful": "^0.3.0",
 		"@sveltejs/adapter-auto": "8.0.0-next.1",
 		"@internationalized/date": "^3.12.2",
 		"@sveltejs/kit": "^3.0.0-next.25",

package/src/lib/components/data-table/table-column-header.svelte

@@ -43,8 +43,10 @@
 			<DropdownMenu.Content align="start">
 				{@render item(() => column.toggleSorting(false), ArrowUpIcon, 'Asc')}
 				{@render item(() => column.toggleSorting(true), ArrowDownIcon, 'Desc')}
-				<DropdownMenu.Separator />
-				{@render item(() => column.toggleVisibility(false), EyeOffIcon, 'Hide')}
+				{#if column.canHide}
+					<DropdownMenu.Separator />
+					{@render item(() => (column.isVisible = false), EyeOffIcon, 'Hide')}
+				{/if}
 			</DropdownMenu.Content>
 		</DropdownMenu.Root>
 	</div>

package/src/lib/components/data-table/table-view-options.svelte

@@ -16,7 +16,7 @@
 			<DropdownMenu.GroupHeading>Toggle columns</DropdownMenu.GroupHeading>
 			<DropdownMenu.Separator />
 			{#each table.allColumns.filter((col) => typeof col.accessorFn !== 'undefined' && col.canHide) as column (column)}
-				<DropdownMenu.CheckboxItem bind:checked={() => column.isVisible, (v) => column.toggleVisibility(!!v)} class="capitalize">
+				<DropdownMenu.CheckboxItem bind:checked={column.isVisible} class="capitalize">
 					{column.id}
 				</DropdownMenu.CheckboxItem>
 			{/each}

package/src/lib/components/menu/components/menu-checkbox-item.svelte

@@ -19,7 +19,6 @@
 		onCheckedChange = () => {},
 		disabled = false,
 		onSelect = () => {},
-		closeOnSelect = true,
 		indeterminate = $bindable(false),
 		onIndeterminateChange = () => {},
 		value = '',
@@ -34,12 +33,11 @@
 		),
 		id: boxWith(() => id),
 		disabled: boxWith(() => disabled),
-		onSelect: boxWith(() => handleSelect),
+		onSelect: boxWith(() => onSelect),
 		ref: boxWith(
 			() => ref,
 			(v) => (ref = v),
 		),
-		closeOnSelect: boxWith(() => closeOnSelect),
 		indeterminate: bindableWith(
 			() => indeterminate,
 			(v) => (indeterminate = v),
@@ -50,12 +48,6 @@
 
 	repairBindable(checkboxItemState.groupChecked, () => (checked = checkboxItemState.groupChecked() ?? checked));
 
-	function handleSelect(e: Event) {
-		onSelect(e);
-		if (e.defaultPrevented) return;
-		checkboxItemState.toggleChecked();
-	}
-
 	const mergedProps = $derived(
 		mergeProps(
 			{

package/src/lib/components/menu/components/menu-item.svelte

@@ -14,7 +14,6 @@
 		id = createId(uid),
 		disabled = false,
 		onSelect = () => {},
-		closeOnSelect = true,
 		inset,
 		variant = 'default',
 		...restProps
@@ -31,7 +30,6 @@
 			() => ref,
 			(v) => (ref = v),
 		),
-		closeOnSelect: boxWith(() => closeOnSelect),
 	});
 
 	const mergedProps = $derived(

package/src/lib/components/menu/components/menu-radio-item.svelte

@@ -16,7 +16,6 @@
 		onSelect = () => {},
 		id = createId(uid),
 		disabled = false,
-		closeOnSelect = true,
 		...restProps
 	}: MenuRadioItemProps = $props();
 
@@ -24,20 +23,13 @@
 		value: boxWith(() => value),
 		id: boxWith(() => id),
 		disabled: boxWith(() => disabled),
-		onSelect: boxWith(() => handleSelect),
+		onSelect: boxWith(() => onSelect),
 		ref: boxWith(
 			() => ref,
 			(v) => (ref = v),
 		),
-		closeOnSelect: boxWith(() => closeOnSelect),
 	});
 
-	function handleSelect(e: Event) {
-		onSelect(e);
-		if (e.defaultPrevented) return;
-		radioItemState.selectValue();
-	}
-
 	const mergedProps = $derived(
 		mergeProps(
 			{

package/src/lib/components/menu/menu.svelte.ts

@@ -924,24 +924,31 @@ type MenuItemCombinedProps = MenuItemSharedStateOpts & MenuItemStateOpts;
 
 interface MenuItemStateOpts extends ReadableBoxedValues<{
 	onSelect: AnyFn;
-	closeOnSelect: boolean;
 }> {}
 
+/** What an item kind does when selected: its own action, and whether the menu closes afterwards. */
+interface MenuItemSelect {
+	closes: boolean;
+	act?: () => void;
+}
+
 export class MenuItemState {
 	static create(opts: MenuItemCombinedProps) {
 		const item = new MenuItemSharedState(opts, getMenuContent());
-		return new MenuItemState(opts, item);
+		return new MenuItemState(opts, item, { closes: true });
 	}
 
 	readonly opts: MenuItemStateOpts;
 	readonly item: MenuItemSharedState;
 	readonly root: MenuRootState;
+	readonly #select: MenuItemSelect;
 	#isPointerDown = false;
 
-	constructor(opts: MenuItemStateOpts, item: MenuItemSharedState) {
+	constructor(opts: MenuItemStateOpts, item: MenuItemSharedState, select: MenuItemSelect) {
 		this.opts = opts;
 		this.item = item;
 		this.root = item.content.parentMenu.root;
+		this.#select = select;
 
 		this.onkeydown = this.onkeydown.bind(this);
 		this.onclick = this.onclick.bind(this);
@@ -949,17 +956,13 @@ export class MenuItemState {
 		this.onpointerup = this.onpointerup.bind(this);
 	}
 
+	// The consumer's onSelect runs first; preventDefault only keeps the menu open, the item's own action always runs.
 	#handleSelect() {
 		if (this.item.opts.disabled.current) return;
 		const selectEvent = new CustomEvent('menuitemselect', { bubbles: true, cancelable: true });
 		this.opts.onSelect.current(selectEvent);
-		if (selectEvent.defaultPrevented) {
-			this.item.content.parentMenu.root.isKeyboard = false;
-			return;
-		}
-		if (this.opts.closeOnSelect.current) {
-			this.item.content.parentMenu.root.opts.onClose();
-		}
+		this.#select.act?.();
+		if (this.#select.closes && !selectEvent.defaultPrevented) this.root.opts.onClose();
 	}
 
 	onkeydown(e: BitsKeyboardEvent) {
@@ -983,12 +986,14 @@ export class MenuItemState {
 		this.#handleSelect();
 	}
 
+	// A press that started elsewhere (on the trigger, dragged here) gets its click synthesised; a
+	// press that started here gets the native one. The content stays mounted across openings and
+	// a checkbox item outlives many selects, so the flag resets per press.
 	onpointerup(e: BitsPointerEvent) {
 		if (e.defaultPrevented) return;
-		if (!this.#isPointerDown) {
-			if (!isHTMLElement(e.currentTarget)) return;
-			e.currentTarget?.click();
-		}
+		const pressedHere = this.#isPointerDown;
+		this.#isPointerDown = false;
+		if (!pressedHere && isHTMLElement(e.currentTarget)) e.currentTarget.click();
 	}
 
 	onpointerdown(_: BitsPointerEvent) {
@@ -1124,21 +1129,20 @@ interface MenuCheckboxItemStateOpts
 
 export class MenuCheckboxItemState {
 	static create(opts: MenuItemCombinedProps & MenuCheckboxItemStateOpts) {
-		const item = new MenuItemState(opts, new MenuItemSharedState(opts, getMenuContent()));
-		return new MenuCheckboxItemState(opts, item);
+		return new MenuCheckboxItemState(opts, new MenuItemSharedState(opts, getMenuContent()));
 	}
 
 	readonly opts: MenuCheckboxItemStateOpts;
 	readonly item: MenuItemState;
 	readonly groupChecked: () => boolean | undefined;
 
-	constructor(opts: MenuCheckboxItemStateOpts, item: MenuItemState) {
+	constructor(opts: MenuItemCombinedProps & MenuCheckboxItemStateOpts, shared: MenuItemSharedState) {
 		this.opts = opts;
-		this.item = item;
+		this.item = new MenuItemState(opts, shared, { closes: false, act: () => this.#toggle() });
 		this.groupChecked = joinGroup(hasMenuCheckboxGroup() ? getMenuCheckboxGroup() : null, opts);
 	}
 
-	toggleChecked() {
+	#toggle() {
 		if (this.opts.indeterminate.current) {
 			this.opts.indeterminate.current = false;
 			this.opts.checked.current = true;
@@ -1293,6 +1297,7 @@ export class MenuRadioGroupState {
 	}
 
 	setValue(v: string) {
+		if (this.opts.value.current === v) return;
 		this.opts.value.current = v;
 	}
 
@@ -1313,31 +1318,24 @@ interface MenuRadioItemStateOpts
 		WithRefOpts,
 		ReadableBoxedValues<{
 			value: string;
-			closeOnSelect: boolean;
 		}> {}
 
 export class MenuRadioItemState {
 	static create(opts: MenuRadioItemStateOpts & MenuItemCombinedProps) {
-		const radioGroup = getMenuRadioGroup();
-		const sharedItem = new MenuItemSharedState(opts, radioGroup.content);
-		const item = new MenuItemState(opts, sharedItem);
-		return new MenuRadioItemState(opts, item, radioGroup);
+		return new MenuRadioItemState(opts, getMenuRadioGroup());
 	}
 	readonly opts: MenuRadioItemStateOpts;
 	readonly item: MenuItemState;
 	readonly group: MenuRadioGroupState;
-	readonly attachment: RefAttachment;
 	readonly isChecked = $derived.by(() => this.group.opts.value.current === this.opts.value.current);
 
-	constructor(opts: MenuRadioItemStateOpts, item: MenuItemState, group: MenuRadioGroupState) {
+	constructor(opts: MenuRadioItemStateOpts & MenuItemCombinedProps, group: MenuRadioGroupState) {
 		this.opts = opts;
-		this.item = item;
 		this.group = group;
-		this.attachment = attachRef(this.opts.ref);
-	}
-
-	selectValue() {
-		this.group.setValue(this.opts.value.current);
+		this.item = new MenuItemState(opts, new MenuItemSharedState(opts, group.content), {
+			closes: true,
+			act: () => group.setValue(opts.value.current),
+		});
 	}
 
 	readonly props = $derived.by(
@@ -1348,7 +1346,6 @@ export class MenuRadioItemState {
 				role: 'menuitemradio',
 				'aria-checked': getAriaChecked(this.isChecked, false),
 				'data-state': getCheckedState(this.isChecked),
-				...this.attachment,
 			}) as const,
 	);
 }

package/src/lib/components/menu/types.ts

@@ -81,27 +81,13 @@ export type MenuItemPropsWithoutHTML<U extends Record<PropertyKey, unknown> = {
 		 */
 		disabled?: boolean;
 
-		/**
-		 * Optional text to use for typeahead filtering. By default, typeahead will use
-		 * the `.textContent` of the menu item. When the content is more complex, you
-		 * can provide a string here instead.
-		 *
-		 * @defaultValue undefined
-		 */
-		textValue?: string;
-
 		/**
 		 * A callback fired when the menu item is selected.
 		 *
-		 * Prevent default behavior of selection with `event.preventDefault()`.
+		 * Calling `event.preventDefault()` keeps a plain or radio item from closing the
+		 * menu; the radio item still selects. A checkbox item never closes it.
 		 */
 		onSelect?: (event: Event) => void;
-
-		/**
-		 * Whether or not the menu item should close when selected.
-		 * @defaultValue true
-		 */
-		closeOnSelect?: boolean;
 	},
 	U
 >;
@@ -137,13 +123,6 @@ export type MenuCheckboxItemPropsWithoutHTML = MenuItemPropsWithoutHTML<MenuChec
 	 */
 	onIndeterminateChange?: OnChangeFn<boolean>;
 
-	/**
-	 * Whether or not the menu item should close when selected.
-	 *
-	 * @defaultValue true
-	 */
-	closeOnSelect?: boolean;
-
 	/**
 	 * The value of the checkbox item when used in a checkbox group.
 	 */
@@ -219,7 +198,14 @@ export type MenuSubContentStaticPropsWithoutHTML = Expand<
 export type MenuSubContentStaticProps = MenuSubContentStaticPropsWithoutHTML &
 	Without<BitsPrimitiveDivAttributes, MenuSubContentStaticPropsWithoutHTML>;
 
-export type MenuSubTriggerPropsWithoutHTML = Omit<MenuItemPropsWithoutHTML, 'closeOnSelect'> & {
+export type MenuSubTriggerPropsWithoutHTML = Omit<MenuItemPropsWithoutHTML, 'onSelect'> & {
+	/**
+	 * A callback fired when the sub-trigger is selected, right before its submenu opens.
+	 * `event.preventDefault()` has no effect here: the submenu opens either way and the
+	 * parent menu never closes on a sub-trigger.
+	 */
+	onSelect?: (event: Event) => void;
+
 	/**
 	 * The amount of time in ms from when the mouse enters the subtrigger until
 	 * the submenu opens. This is useful for preventing the submenu from opening
@@ -271,12 +257,6 @@ export type MenuRadioItemPropsWithoutHTML = MenuItemPropsWithoutHTML<MenuRadioIt
 	 * The value of the radio item.
 	 */
 	value: string;
-
-	/**
-	 * Whether or not the menu item should close when selected.
-	 * @defaultValue true
-	 */
-	closeOnSelect?: boolean;
 };
 
 export type MenuRadioItemProps = MenuRadioItemPropsWithoutHTML & Without<BitsPrimitiveDivAttributes, MenuRadioItemPropsWithoutHTML>;

package/src/lib/components/sidebar/context.svelte.ts

@@ -1,5 +1,4 @@
 import { createContext } from "svelte";
-import { isMobile as viewportIsMobile } from 'handful';
 import { SIDEBAR_KEYBOARD_SHORTCUT } from './constants';
 
 function isEditableTarget(target: EventTarget | null) {
@@ -23,16 +22,30 @@ type SidebarStateProps = {
 	setOpen: (open: boolean) => void;
 };
 
+/** Whether the `md:` rule on the desktop panel is in effect: the panel's own display, not an ancestor's. */
+export const panelDisplayed = (panel: HTMLElement) => getComputedStyle(panel).display !== 'none';
+
 export class SidebarState {
 	readonly props: SidebarStateProps;
 	open = $derived.by(() => this.props.open());
-	#openMobile = $state(false);
-	openForViewport = $derived.by(() => (viewportIsMobile.current ? this.#openMobile : this.open));
+	sheetOpen = $state(false);
+	/**
+	 * The mounted desktop panels (one per Root; a Provider may hold several). CSS displays a panel
+	 * or its sheet per viewport, so whether a panel is displayed IS the viewport: a toggle writes
+	 * the persisted `open` while it is, and the sheet's bit while it isn't. No media query is read
+	 * in JS; the breakpoint lives only in the panel's `md:` classes.
+	 */
+	readonly desktopPanels = new Set<HTMLElement>();
 
 	constructor(props: SidebarStateProps) {
 		this.props = props;
 	}
 
+	#onDesktop() {
+		for (const panel of this.desktopPanels) return panelDisplayed(panel);
+		return true;
+	}
+
 	// Event handler to apply to the `<svelte:window>`
 	handleShortcutKeydown = (e: KeyboardEvent) => {
 		if (e.defaultPrevented || e.repeat || isEditableTarget(e.target)) return;
@@ -43,11 +56,15 @@ export class SidebarState {
 	};
 
 	setOpen = (value: boolean) => {
-		viewportIsMobile.current ? (this.#openMobile = value) : this.props.setOpen(value);
+		this.#onDesktop() ? this.props.setOpen(value) : (this.sheetOpen = value);
 	};
 
 	toggle = () => {
-		this.setOpen(!this.openForViewport);
+		this.#onDesktop() ? this.props.setOpen(!this.open) : (this.sheetOpen = !this.sheetOpen);
+	};
+
+	closeSheet = () => {
+		this.sheetOpen = false;
 	};
 }
 

package/src/lib/components/sidebar/sidebar-desktop-surface.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
 	import { join } from 'overrule';
-	import { useSidebar } from './context.svelte.js';
+	import { panelDisplayed, useSidebar } from './context.svelte.js';
+	import { resizeAttachment } from '../../internal/svelte-resize-observer.svelte.js';
 	import type { SidebarRootProps } from './types.js';
+	import type { Attachment } from 'svelte/attachments';
 
 	let {
 		ref = $bindable(null),
@@ -10,14 +12,65 @@
 		collapsible = 'offcanvas',
 		class: className,
 		children,
+		sheetBody = null,
+		sheetDialog = null,
 		...restProps
-	}: SidebarRootProps = $props();
+	}: SidebarRootProps & {
+		/** This Root's sheet, bound by the Root: where the content goes while CSS hides this panel. */
+		sheetBody?: HTMLElement | null;
+		sheetDialog?: HTMLDialogElement | null;
+	} = $props();
 
 	const sidebar = useSidebar();
+
+	let container: HTMLElement;
+	let inner: HTMLElement;
+
+	// The content tree renders once, here, server-side always here, and lives in whichever
+	// surface CSS displays: this panel's own display (not an ancestor's) is the viewport.
+	const rehome = (panel: HTMLElement) => {
+		const displayed = panelDisplayed(panel);
+		const home = displayed ? container : sheetBody;
+		// append() re-inserts even in place, which would blur focus and restart transitions.
+		if (home && inner.parentNode !== home) home.append(inner);
+		if (!displayed) return;
+		// A sheet left open at the crossing goes the way it did when the surface unmounted:
+		// closed this frame, no exit slide, the page interactive at once. Routing through state
+		// would keep the page inert behind an empty sheet for the 300ms exit.
+		if (sheetDialog?.open) sheetDialog.close();
+		sidebar.closeSheet();
+	};
+
+	// The observer fires when `hidden md:block` flips this box between 0×0 and laid out, which is
+	// the breakpoint crossing. It also fires every frame of the 200ms width transition, so a
+	// report that leaves the display as it was is dropped before the style read.
+	let lastDisplayed: boolean | undefined;
+	const observe = resizeAttachment(([entry]) => {
+		if (!entry) return;
+		const panel = entry.target as HTMLElement;
+		const displayed = panelDisplayed(panel);
+		if (displayed === lastDisplayed) return;
+		lastDisplayed = displayed;
+		rehome(panel);
+	});
+	const register: Attachment<HTMLElement> = (node) => {
+		sidebar.desktopPanels.add(node);
+		return () => sidebar.desktopPanels.delete(node);
+	};
+	// A display:none panel gets no initial observation, and a crossing made while an ancestor is
+	// display:none reports no size change (0×0 either way), so the content can be parked in the
+	// wrong surface while nothing shows it; the sheet opening is the moment that matters, and
+	// re-homes. A pre effect so it runs before the sheet's showModal(), which picks the initial
+	// focus from whatever the dialog holds at that moment.
+	$effect.pre(() => {
+		if (sidebar.sheetOpen && ref) rehome(ref);
+	});
 </script>
 
 <div
 	bind:this={ref}
+	{@attach register}
+	{...observe}
 	class="text-sidebar-foreground group peer hidden md:block"
 	data-state={sidebar.open ? 'expanded' : 'collapsed'}
 	data-collapsible={sidebar.open ? '' : collapsible}
@@ -37,6 +90,7 @@
 		)}>
 	</div>
 	<div
+		bind:this={container}
 		data-slot="sidebar-container"
 		class={join(
 			'fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex',
@@ -51,6 +105,7 @@
 		)}
 		{...restProps}>
 		<div
+			bind:this={inner}
 			data-sidebar="sidebar"
 			data-slot="sidebar-inner"
 			class="bg-sidebar group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:shadow-sm group-data-[variant=floating]:ring-1 group-data-[variant=floating]:ring-sidebar-border flex size-full flex-col">

package/src/lib/components/sidebar/sidebar-mobile-surface.svelte

@@ -8,18 +8,26 @@
 	import { useSidebar } from './context.svelte.js';
 	import type { SidebarRootProps } from './types.js';
 
-	let { ref = $bindable(null), side = 'left', class: className, children }: SidebarRootProps = $props();
+	let {
+		ref = $bindable(null),
+		body = $bindable(null),
+		side = 'left',
+		class: className,
+	}: Pick<SidebarRootProps, 'ref' | 'side' | 'class'> & {
+		/** An empty shell: the desktop panel moves the content tree here while CSS hides the panel. */
+		body?: HTMLElement | null;
+	} = $props();
 
 	const sidebar = useSidebar();
 
-	// SidebarState is an external machine that owns `open`; the sheet cell
+	// SidebarState is an external machine that owns the sheet's bit; the sheet cell
 	// derives from it, and sheet-initiated dismissals route back through it.
 	// This surface acts as its own sheet root so the cell stays internal.
-	const sheetCell = new DialogState(() => sidebar.openForViewport);
+	const sheetCell = new DialogState(() => sidebar.sheetOpen);
 	$effect(() => {
 		const o = sheetCell.open;
 		untrack(() => {
-			if (o !== sidebar.openForViewport) sidebar.setOpen(o);
+			if (o !== sidebar.sheetOpen) sidebar.sheetOpen = o;
 		});
 	});
 
@@ -42,7 +50,5 @@
 			<Sheet.Title>Sidebar</Sheet.Title>
 			<Sheet.Description>Displays the mobile sidebar.</Sheet.Description>
 		</Sheet.Header>
-		<div class="flex h-full w-full flex-col">
-			{@render children?.()}
-		</div>
+		<div class="flex h-full w-full flex-col" bind:this={body}></div>
 	</Sheet.Content>

package/src/lib/components/sidebar/sidebar-provider.svelte

@@ -7,7 +7,6 @@
 	import { SIDEBAR_COOKIE_MAX_AGE, SIDEBAR_COOKIE_NAME, SIDEBAR_WIDTH, SIDEBAR_WIDTH_ICON } from './constants';
 	import { setSidebar, SidebarState } from './context.svelte';
 	import { OpenCell } from '../../internal/open-cell.svelte.js';
-	import { isMobile } from 'handful';
 	import type { Snippet } from 'svelte';
 
 	let {
@@ -43,7 +42,8 @@
 	);
 
 	// Closes the mobile sidebar on navigation, since clicking a nav link doesn't dismiss it.
-	beforeNavigate(() => isMobile.current && sidebar.openForViewport && sidebar.setOpen(false));
+	// The sheet is only ever open on a phone, so no viewport check.
+	beforeNavigate(sidebar.closeSheet);
 </script>
 
 <svelte:window onkeydown={sidebar.handleShortcutKeydown} />

package/src/lib/components/sidebar/sidebar.svelte

@@ -1,6 +1,5 @@
 <script lang="ts">
 	import { join } from 'overrule';
-	import { isMobile as viewportIsMobile } from 'handful';
 	import MobileSurface from './sidebar-mobile-surface.svelte';
 	import DesktopSurface from './sidebar-desktop-surface.svelte';
 	import type { SidebarRootProps } from './types.js';
@@ -14,6 +13,10 @@
 		children,
 		...restProps
 	}: SidebarRootProps = $props();
+
+	// This Root's sheet, handed to its panel so several Roots in one Provider stay paired.
+	let sheetBody = $state<HTMLElement | null>(null);
+	let sheetDialog = $state<HTMLDialogElement | null>(null);
 </script>
 
 {#if collapsible === 'none'}
@@ -23,8 +26,11 @@
 		{...restProps}>
 		{@render children?.()}
 	</div>
-{:else if viewportIsMobile.current}
-	<MobileSurface bind:ref {side} class={className} {children} {...restProps} />
 {:else}
-	<DesktopSurface bind:ref {side} {variant} {collapsible} class={className} {children} {...restProps} />
+	<!-- Both surfaces render on every viewport and server render alike; the sheet is a closed <dialog>
+	     and the panel is `hidden md:block`, so CSS shows one and nothing swaps at hydration. The
+	     content renders once, in the panel, which moves it into the sheet while CSS hides the panel.
+	     `ref` is the panel; the sheet is reachable as [data-mobile]. -->
+	<MobileSurface bind:ref={sheetDialog} bind:body={sheetBody} {side} class={className} />
+	<DesktopSurface bind:ref {side} {variant} {collapsible} class={className} {children} {sheetBody} {sheetDialog} {...restProps} />
 {/if}

package/src/lib/components/toggle-group/components/toggle-group-item.svelte

@@ -2,7 +2,7 @@
 	import { boxWith } from '../../../internal/tools/index.js';
 	import { mergeProps } from '../../../internal/merge-props.js';
 	import type { ToggleGroupItemProps } from '../types.js';
-	import { ToggleGroupItemState } from '../toggle-group.svelte.js';
+	import { createToggleGroupItem } from '../toggle-group.svelte.js';
 	import { createId } from '../../../internal/create-id.js';
 	import { getToggleGroupCtx } from './toggle-group.svelte';
 	import { toggleVariants, type ToggleSize, type ToggleVariant } from '../../toggle/variants.js';
@@ -27,7 +27,7 @@
 
 	const ctx = getToggleGroupCtx();
 
-	const itemState = ToggleGroupItemState.create({
+	const itemState = createToggleGroupItem({
 		id: boxWith(() => id),
 		value: boxWith(() => value),
 		disabled: boxWith(() => disabled ?? false),

package/src/lib/components/toggle-group/components/toggle-group.svelte

@@ -14,7 +14,8 @@
 
 <script lang="ts">
 	import { untrack } from 'svelte';
-	import { type WritableBox, boxWith } from '../../../internal/tools/index.js';
+	import { boxWith, repairBindable } from '../../../internal/tools/index.js';
+	import { emptySelection } from '../../../internal/selection.svelte.js';
 	import { mergeProps } from '../../../internal/merge-props.js';
 	import type { ToggleGroupRootProps } from '../types.js';
 	import { ToggleGroupRootState } from '../toggle-group.svelte.js';
@@ -43,35 +44,27 @@
 	// Context for toggle group items (values are stable, no reactivity needed)
 	setToggleGroupCtx(untrack(() => ({ variant, size, spacing })));
 
-	// Mode is construction-static: ToggleGroupRootState chooses a single/multiple class once.
+	// Mode is construction-static: the selection stays single or multiple for the group's life.
 	const valueType = untrack(() => type);
 
-	function getDefaultValue(): string | string[] {
-		return valueType === 'single' ? '' : [];
-	}
-
-	function handleDefaultValue() {
-		if (value !== undefined) return;
-		value = getDefaultValue();
-	}
-
-	function getValue() {
-		return value ?? getDefaultValue();
-	}
-
-	// SSR
-	handleDefaultValue();
+	// The group owns a mode-specific controlled value.
+	repairBindable(
+		() => value,
+		() => {
+			if (value === undefined) value = emptySelection(valueType);
+		},
+	);
 
 	const rootState = ToggleGroupRootState.create({
 		id: boxWith(() => id),
 		value: boxWith(
-			() => getValue(),
+			() => value ?? emptySelection(valueType),
 			(v) => {
 				value = v;
-				// @ts-expect-error - we know
-				onValueChange(v);
+				// oxlint-disable-next-line no-explicit-any
+				onValueChange(v as any);
 			},
-		) as WritableBox<string> | WritableBox<string[]>,
+		),
 		disabled: boxWith(() => disabled),
 		loop: boxWith(() => loop),
 		orientation: boxWith(() => orientation),