1.2.0

- added isRawError helper
- added catchErrorString helper to convert any error to a string
- added checkGraphResponse to throw if error is present or data missing
- ErrorMessage now supports wrapping multiple errors ergonomically

.nvmrc

@@ -0,0 +1 @@
+24.12.0

package.json

@@ -4,7 +4,7 @@
 		"type": "git",
 		"url": "https://gitea.auvem.com/svelte-toolkit/sui.git"
 	},
-	"version": "1.0.4",
+	"version": "1.2.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",

src/lib/Combobox.svelte

@@ -29,10 +29,11 @@
 	};
 
 	/** returns option label, falling back to value or 'Undefined Option' if no option provided */
-	const getLabel = (opt: ComboboxOption | undefined): string =>
+	const getLabel = (opt: ComboboxOption | undefined | null): string =>
 		opt ? (opt.label ?? opt.value) : 'Undefined Option';
 	/** returns option preview, falling back to getLabel if missing */
-	const getPreview = (opt: ComboboxOption | undefined): string => opt?.preview ?? getLabel(opt);
+	const getPreview = (opt: ComboboxOption | undefined | null): string =>
+		opt?.preview ?? getLabel(opt);
 </script>
 
 <script lang="ts">
@@ -41,8 +42,7 @@
 	import Label from './Label.svelte';
 	import StyledRawInput from './StyledRawInput.svelte';
 	import { InputValidatorEvent, validate, type ValidatorOptions } from '@svelte-toolkit/validate';
-	import { onMount, tick, untrack, type Snippet } from 'svelte';
+	import { type Snippet } from 'svelte';
-	import { Portal } from '@jsrob/svelte-portal';
 	import { scale } from 'svelte/transition';
 	import { generateIdentifier, type IconDef } from './util';
 	import type { ClassValue, MouseEventHandler } from 'svelte/elements';
@@ -52,6 +52,7 @@
 	import { Tween } from 'svelte/motion';
 	import { cubicOut } from 'svelte/easing';
 	import type { Attachment } from 'svelte/attachments';
+	import { Popover } from './floating.svelte';
 
 	interface Props {
 		/**
@@ -78,7 +79,7 @@
 		stateless?: boolean;
 
 		/** Bindable value of the combobox, the currently selected option */
-		value?: ComboboxOption;
+		value?: ComboboxOption | null;
 		/** Array of ComboboxOptions for the picker */
 		options: ComboboxOption[];
 		/**
@@ -217,6 +218,38 @@
 	const id = $derived(generateIdentifier('combobox', name));
 	const searchKeySet = $derived(new Set(searchKeys));
 	const conditionalUse = $derived(use ? use : () => {});
+	const popover = new Popover({
+		interaction: 'manual',
+		placement: 'bottom-start',
+		offset: 0,
+		ontoggle: async (isOpen) => {
+			open = isOpen;
+
+			if (isOpen) {
+				scrollToHighlighted();
+
+				// focus & select search input after 100ms
+				setTimeout(() => {
+					searchInput?.focus();
+					searchInput?.select();
+				}, 100);
+
+				// handle lazy loading behaviour
+				if (lazy === 'always' || (lazy === true && !lazyApplied)) {
+					lazyApplied = true;
+					loading = true;
+					await onlazy?.();
+					loading = false;
+				}
+			} else {
+				searchValue = ''; // clear search value for next time picker opens
+				searching = false; // reset searching state
+				highlighted = value; // reset highlighted item to current value
+			}
+
+			onopenchange?.(isOpen);
+		}
+	});
 
 	let valid = $state(true);
 	let searchValue = $state('');
@@ -227,8 +260,6 @@
 	let searchContainer = $state<HTMLDivElement | null>(null);
 	let pickerContainer = $state<HTMLDivElement | null>(null);
 
-	// TODO: there's something weird with dropdown placement on narrow screens
-
 	/** options filtered by search value and searchKeys */
 	const filteredItems = $derived.by(() => {
 		let keys: KeyOption<ComboboxOption>[] = [];
@@ -241,7 +272,7 @@
 	});
 
 	/** currently highlighted option, updated by keyboard navigation or defaults to first item */
-	let highlighted = $derived.by((): ComboboxOption | undefined => {
+	let highlighted = $derived.by((): ComboboxOption | undefined | null => {
 		if (!searching) return undefined; // otherwise, the first item is highlighted on first open
 		if (filteredItems.length === 0) return undefined;
 		if (value !== undefined && filteredItems.find((v) => v.value === value?.value)) return value;
@@ -284,11 +315,7 @@
 		easing: cubicOut
 	});
 	$effect(() => {
-		if (iconWidth >= 0) {
+		inputPadding.target = calculatePadding();
-			untrack(() => {
-				inputPadding.target = calculatePadding();
-			});
-		}
 	});
 
 	/*** HELPER FUNCTIONS ***/
@@ -327,35 +354,11 @@
 	};
 
 	let lazyApplied = false;
-	/** opens combobox picker and propagates any necessary events */
-	const openPicker = async () => {
-		open = true;
-
-		updatePickerRect(); // update picker position
-		scrollToHighlighted(); // scroll to highlighted item
-		onopenchange?.(true); // trigger onopenchange event if defined
-
-		// handle lazy loading behaviour
-		if (lazy === 'always' || (lazy === true && !lazyApplied)) {
-			lazyApplied = true;
-			loading = true;
-			await onlazy?.();
-			loading = false;
-		}
-	};
-	/** closes combobox picker and propagates any necessary events */
-	const closePicker = () => {
-		open = false;
-		searchValue = ''; // clear search value for next time picker opens
-		searching = false; // reset searching state
-		highlighted = value; // reset highlighted item to current value
-		onopenchange?.(false); // trigger onopenchange event if defined
-	};
 
 	/** updates the value of the combobox and triggers any callbacks, including closing the picker */
 	const updateValue = (newValue: ComboboxOption) => {
 		if (!stateless) value = newValue;
-		closePicker();
+		popover.setOpen(false);
 		onchange?.(newValue);
 	};
 
@@ -397,7 +400,6 @@
 			if ((opts.mode === 'match' || opts.options.length === 0) && opts.matchElem) {
 				// match width if explicitly enabled, or no options to average
 				elem.style.width = opts.matchElem.offsetWidth + 'px';
-				console.log('matched', elem.style.width, 'to', opts.matchElem.offsetWidth);
 			} else {
 				// otherwise, set width based on average content width
 				let val = '10ch';
@@ -410,53 +412,10 @@
 					}
 				}
 				elem.style.width = val;
-				console.log('averaged', val);
 			}
 		};
 	};
 
-	/** updates the position of the picker */
-	const updatePickerRect = async () => {
-		if (!searchContainer || !pickerContainer) {
-			await tick();
-			if (!searchContainer || !pickerContainer) {
-				return;
-			}
-		}
-
-		const overlay = pickerContainer;
-		const target = searchContainer;
-		const targetRect = target.getBoundingClientRect();
-
-		if (!open) {
-			return;
-		}
-
-		// choose whether the overlay should be above or below the target
-		const availableSpaceBelow = window.innerHeight - targetRect.bottom;
-		const availableSpaceAbove = targetRect.top;
-		const outerMargin = 24;
-
-		if (availableSpaceBelow < availableSpaceAbove) {
-			// overlay should be above the target
-			overlay.style.bottom = `${window.innerHeight - targetRect.top - window.scrollY}px`;
-			overlay.style.top = 'auto';
-			overlay.style.maxHeight = `${availableSpaceAbove - outerMargin}px`;
-			pickerPosition = 'top';
-			overlay.dataset.side = 'top';
-		} else {
-			// overlay should be below the target
-			overlay.style.top = `${targetRect.bottom + window.scrollY}px`;
-			overlay.style.bottom = 'auto';
-			overlay.style.maxHeight = `${availableSpaceBelow - outerMargin}px`;
-			pickerPosition = 'bottom';
-			overlay.dataset.side = 'bottom';
-		}
-
-		// set overlay left position
-		overlay.style.left = `${targetRect.left}px`;
-	};
-
 	/** scrolls the picker to the highlighted item */
 	const scrollToHighlighted = () => {
 		if (!pickerContainer || !highlighted) return;
@@ -524,79 +483,67 @@
 
 	// close picker if clicked outside
 	const handleWindowClick: MouseEventHandler<Window> = (e) => {
-		if (!searchContainer || !pickerContainer) {
+		if (!open || !searchContainer || !pickerContainer) return;
-			return;
-		}
 
 		if (
-			!open ||
+			e.target instanceof Node &&
-			searchContainer.contains(e.target as Node) ||
+			!searchContainer.contains(e.target) &&
-			pickerContainer.contains(e.target as Node)
+			!pickerContainer.contains(e.target)
 		) {
-			return;
+			popover.setOpen(false);
 		}
-
-		closePicker();
 	};
-
-	onMount(() => {
-		// set initial picker position after load
-		setTimeout(() => {
-			updatePickerRect();
-		}, 500);
-	});
 </script>
 
-<svelte:window onresize={updatePickerRect} onclick={handleWindowClick} />
+<svelte:window onclick={handleWindowClick} />
 
 <!-- Combobox picker -->
-<Portal target="body">
+{#if open}
-	{#if open}
+	<!-- Picker container -->
-		<!-- Picker container -->
+	<div
-		<div
+		class={[
-			class={[
+			'picker absolute top-0 left-0 z-50 overflow-y-auto px-2 py-3',
-				'picker absolute top-0 left-0 z-50 overflow-y-auto px-2 py-3',
+			'rounded-sm border shadow-lg shadow-black/25 outline-hidden',
-				'rounded-sm border shadow-lg shadow-black/25 outline-hidden',
+			'border-sui-accent dark:border-sui-accent/50 dark:bg-sui-text-800 bg-white dark:sm:bg-slate-800',
-				'border-sui-accent dark:border-sui-accent/50 dark:bg-sui-text-800 bg-white dark:sm:bg-slate-800',
+			'text-sui-text dark:text-sui-background',
-				'text-sui-text dark:text-sui-background',
+			open && pickerPosition === 'top' && 'mb-[var(--outer-gap)]',
-				open && pickerPosition === 'top' && 'mb-[var(--outer-gap)]',
+			open && pickerPosition === 'bottom' && 'mt-[var(--outer-gap)]'
-				open && pickerPosition === 'bottom' && 'mt-[var(--outer-gap)]'
+		]}
-			]}
+		bind:this={pickerContainer}
-			bind:this={pickerContainer}
+		transition:scale={{ duration: 200 }}
-			transition:scale={{ duration: 200 }}
+		role="listbox"
-			role="listbox"
+		onkeydown={(e) => {
-			onkeydown={(e) => {
+			if (e.key === 'Escape') {
-				if (e.key === 'Escape') {
+				popover.setOpen(false);
-					closePicker();
+				searchInput?.focus();
-					searchInput?.focus();
+			}
-				}
+		}}
-			}}
+		onscroll={(e) => {
-			onscroll={(e) => {
+			if (!onscroll) return;
-				if (!onscroll) return;
+			const target = e.target as HTMLDivElement;
-				const target = e.target as HTMLDivElement;
+			if (!target) return;
-				if (!target) return;
 
-				const margin = 10; // 10px margin for top & bottom
+			const margin = 10; // 10px margin for top & bottom
-				const atTop = target.scrollTop < margin;
+			const atTop = target.scrollTop < margin;
-				const atBottom = target.scrollTop + target.clientHeight > target.scrollHeight - margin;
+			const atBottom = target.scrollTop + target.clientHeight > target.scrollHeight - margin;
-				onscroll({ event: e, top: atTop, bottom: atBottom, searchInput: searchInput?.value ?? '' });
+			onscroll({ event: e, top: atTop, bottom: atBottom, searchInput: searchInput?.value ?? '' });
-			}}
+		}}
-			tabindex="0"
+		tabindex="0"
-			{@attach minWidth({ options, mode: pickerWidth, matchElem: searchInput })}
+		{@attach minWidth({ options, mode: pickerWidth, matchElem: searchInput })}
-		>
+		{...popover.floating()}
-			{#each filteredItems as opt (opt.value)}
+	>
-				{@render option(opt)}
+		{#each filteredItems as opt (opt.value)}
+			{@render option(opt)}
+		{:else}
+			<!-- Display loading state or not found if no options available -->
+			{#if loading}
+				{@render option(loadingOption, true)}
 			{:else}
-				<!-- Display loading state or not found if no options available -->
+				{@render option(notFoundOption, true)}
-				{#if loading}
+			{/if}
-					{@render option(loadingOption, true)}
+		{/each}
-				{:else}
+	</div>
-					{@render option(notFoundOption, true)}
+{/if}
-				{/if}
-			{/each}
-		</div>
-	{/if}
-</Portal>
 
 <!-- Combobox main input container -->
 <div class={classValue}>
@@ -691,7 +638,7 @@
 
 <!-- Search input box -->
 {#snippet searchInputBox(caret: boolean = true)}
-	<div class="relative">
+	<div class="relative" {...popover.reference()}>
 		<!-- Persistant OR selected option icon, if visible -->
 		{#if iconVisible}
 			<div
@@ -704,9 +651,9 @@
 			>
 				{#if loading}
 					<Spinner class="stroke-sui-accent! -mt-0.5" size="1em" />
-				{:else if useHighlighted && highlighted}
+				{:else if useHighlighted && highlighted && highlighted.icon}
 					{@render optionIcon(highlighted)}
-				{:else if value}
+				{:else if value && value.icon}
 					{@render optionIcon(value)}
 				{:else if icon}
 					{#if typeof icon === 'function'}
@@ -731,13 +678,7 @@
 			autocomplete="off"
 			bind:ref={searchInput}
 			onclick={() => {
-				if (!open) {
+				popover.setOpen(true);
-					setTimeout(() => {
-						searchInput?.select();
-					}, 100);
-				}
-
-				openPicker();
 			}}
 			onkeydown={(e) => {
 				if (!searchInput) return;
@@ -747,17 +688,17 @@
 						updateValue(highlighted);
 					}
 					if (e.key === 'Enter') {
-						closePicker();
+						popover.setOpen(false);
 						e.preventDefault();
 					}
 					return;
 				} else if (e.key === 'Escape') {
-					closePicker();
+					popover.setOpen(false);
 					return;
 				}
 
 				// open the picker
-				openPicker();
+				popover.setOpen(true);
 
 				if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
 					searching = false;
@@ -804,8 +745,7 @@
 			<CaretUpDown
 				class="absolute end-2.5 top-1/2 size-6 -translate-y-1/2"
 				onclick={() => {
-					open = !open;
+					popover.setOpen(!open);
-					if (open) searchInput?.focus();
 				}}
 			/>
 		{/if}

src/lib/Dialog.svelte

@@ -5,6 +5,8 @@
 	export interface DialogAPI {
 		/** shows an error message at the top of the dialog */
 		error: (message: RawError | null) => void;
+		/** Returns if the dialog is displaying an error */
+		hasError: () => boolean;
 		/** closes the dialog */
 		close: () => void;
 		/** opens the dialog */
@@ -39,6 +41,16 @@
 		 * changes made via this API will NOT propagate to consuming components.
 		 */
 		title: (title: string) => void;
+		/** Focuses the dialog */
+		focus: () => void;
+		/** Returns the stack index for this dialog */
+		stackIndex: () => number;
+		/**
+		 * Returns the z-index of this dialog, where each incremental stack
+		 * index increases the z-index by 100 starting from 1000. This can be
+		 * used to layer custom elements on top of and within the dialog.
+		 */
+		zIndex: () => number;
 	}
 
 	type DialogControlButton = {
@@ -64,9 +76,9 @@
 
 	/**
 	 * Stores internal state of the dialog, everything necessary to render
-	 * internal snippets.
+	 * internal and override capable snippets.
 	 */
-	type DialogState = {
+	export type DialogState = {
 		frozen: boolean;
 		loading: boolean;
 		disabled: boolean;
@@ -79,6 +91,9 @@
 	};
 
 	export { dialogCancelButton, dialogOkButton, dialogCloseButton };
+
+	/** stack of currently open dialogs by identifier */
+	let dialogStack: DialogAPI[] = $state([]);
 </script>
 
 <script lang="ts">
@@ -91,15 +106,15 @@
 	import { X } from 'phosphor-svelte';
 	import { ErrorMessage, type RawError } from './error';
 	import ErrorBox from './ErrorBox.svelte';
-	import { mergeOverrideObject } from './util';
+	import { generateIdentifier, mergeOverrideObject } from './util';
 
 	interface Props {
 		/** Bindable open state of the dialog */
 		open?: boolean;
 		/** Title of the dialog */
-		title: string | Snippet;
+		title: string | Snippet<[state: DialogState]>;
 		/** Description of the dialog, optionally rendered below the title */
-		description?: string | Snippet;
+		description?: string | Snippet<[state: DialogState]>;
 		/** Size of the dialog (default: 'sm') */
 		size?: 'sm' | 'md' | 'lg' | 'max';
 		/** Additional classes for the dialog */
@@ -107,19 +122,29 @@
 		/** Content of the dialog */
 		children?: Snippet;
 		/** Bottom controls for the dialog */
-		controls?: Snippet | DialogControls;
+		controls?: Snippet<[state: DialogState]> | DialogControls;
 		/** Sets bottom alignment of controls (default: end) */
 		controlsAlign?: 'start' | 'center' | 'end';
 		/** Top-right close control */
-		close?: Snippet | Omit<DialogControlButton, 'label'> | null;
+		close?: Snippet<[state: DialogState]> | Omit<DialogControlButton, 'label'> | null;
-		/** Callback when the dialog is opened */
+		/**
+		 * Callback when the dialog is opened
+		 * @deprecated use onopenchange instead and check the open parameter
+		 */
 		onopen?: (dialog: DialogAPI) => void;
-		/** Callback when the dialog is closed */
+		/**
+		 * Callback when the dialog is closed
+		 * @deprecated use onopenchange instead and check the open parameter
+		 */
 		onclose?: (dialog: DialogAPI) => void;
+		/** Callback when the dialog open state changes */
+		onopenchange?: ({ open, dialog }: { open: boolean; dialog: DialogAPI }) => void;
 		/** If default controls are used, controls loading state of submit button */
 		loading?: boolean;
-		/** If default controls are used, freezes all interactions */
+		/** If default controls are used, freezes all interactions preventing user input */
 		frozen?: boolean;
+		/** If enabled, automatically freezes dialog when loading (default: true) */
+		autoFreeze?: boolean;
 		/** If default controls are used, disables submit button */
 		disabled?: boolean;
 	}
@@ -136,34 +161,72 @@
 		close = {},
 		onopen,
 		onclose,
+		onopenchange,
 		loading = $bindable(false),
 		frozen = $bindable(false),
+		autoFreeze = true,
 		disabled = $bindable(false)
 	}: Props = $props();
 
-	let controls = $derived(
+	const controls = $derived(
 		typeof rawControls === 'function'
 			? rawControls
 			: mergeOverrideObject(defaultDialogControls, rawControls)
 	);
 
+	const identifier = generateIdentifier('dialog');
+
+	let lastOpen = $state(open);
+	let dialogPage = $state<HTMLDivElement | null>(null);
 	let dialogContainer = $state<HTMLDivElement | null>(null);
 	let error = $state<ErrorMessage | null>(null);
+	let stackIndex = $state(-1);
+	const zIndex = $derived(1000 + stackIndex * 100);
 
-	// disable window scroll when dialog is open
+	const reallyFrozen = $derived(autoFreeze ? frozen || loading : frozen);
-	$effect(() => {
+
-		if (open) {
+	/** handles open change */
-			document.body.style.overflow = 'hidden';
+	const handleOpenChange = (localOpen: boolean) => {
-			untrack(() => onopen?.(dialogAPI));
+		if (localOpen) {
+			document.body.style.overflow = 'hidden'; // prevent scrolling
+			// focus the dialog BEFORE callbacks for accessibility & flexibility
+			dialogPage?.focus();
+			// run callbacks
+			onopen?.(dialogAPI);
+			onopenchange?.({ open: true, dialog: dialogAPI });
+			//update stack
+			dialogStack.push(dialogAPI); // add to stack of open dialogs
+			stackIndex = dialogStack.length - 1; // track index in stack for this dialog
 		} else {
-			document.body.style.overflow = '';
+			// update stack
-			untrack(() => onclose?.(dialogAPI));
+			dialogStack.pop(); // remove from stack of open dialogs
+			stackIndex = -1; // reset stack index for this dialog
+			// update focus & handle scroll locking for accessibility
+			if (dialogStack.length > 0) {
+				dialogStack[dialogStack.length - 1].focus();
+			} else {
+				document.body.style.overflow = ''; // re-enable scrolling since no dialogs are open
+			}
+			// run callbacks
+			onclose?.(dialogAPI);
+			onopenchange?.({ open: false, dialog: dialogAPI });
+		}
+	};
+
+	// deduplicate open changes
+	$effect(() => {
+		if (open !== untrack(() => lastOpen)) {
+			lastOpen = open;
+			untrack(() => {
+				handleOpenChange(open);
+			});
 		}
 	});
 
 	/** DialogAPI instance to control this dialog */
 	export const dialogAPI: DialogAPI = {
 		error: (message) => (error = ErrorMessage.from(message)),
+		hasError: () => error !== null,
 		close: () => (open = false),
 		open: () => (open = true),
 		isOpen: () => open,
@@ -177,13 +240,16 @@
 		unfreeze: () => (frozen = false),
 		isFrozen: () => frozen,
 		canContinue: () => !loading && !disabled && !frozen,
-		title: (newTitle) => (title = newTitle)
+		title: (newTitle) => (title = newTitle),
+		focus: () => dialogPage?.focus(),
+		stackIndex: () => stackIndex,
+		zIndex: () => zIndex
 	};
 
 	/** Returns the current state of the dialog */
 	export const getState = (): DialogState => {
 		return {
-			frozen,
+			frozen: reallyFrozen,
 			loading,
 			disabled,
 			api: dialogAPI
@@ -199,23 +265,31 @@
 
 {#snippet dialog()}
 	<div
+		bind:this={dialogPage}
 		class={[
-			'fixed inset-0 z-50 flex items-center-safe justify-center bg-black/50 backdrop-blur-sm',
+			'fixed inset-0 flex items-center-safe justify-center bg-black/50 backdrop-blur-sm',
 			'overflow-auto p-8',
 			classValue
 		]}
+		style={// increase z-index and decrease opacity for each nested dialog
+		`z-index: ${zIndex}`}
 		transition:fade={{ duration: 150 }}
 		onclick={(e) => {
 			const target = e.target as HTMLElement;
-			if (open && !frozen && !dialogContainer?.contains(target) && target !== dialogContainer)
+			if (open && !reallyFrozen && !dialogContainer?.contains(target) && target !== dialogContainer)
 				open = false;
 		}}
 		onkeydown={(e) => {
-			if (e.key === 'Escape' && !frozen) {
+			if (e.key === 'Escape' && !reallyFrozen) {
-				open = false;
+				if (stackIndex === dialogStack.length - 1) {
+					// only close if this dialog is the topmost dialog
+					open = false;
+				}
 			}
 		}}
 		role="dialog"
+		aria-labelledby="{identifier}-title"
+		aria-describedby="{identifier}-description"
 		tabindex="-1"
 	>
 		<div
@@ -235,14 +309,17 @@
 		>
 			<div class="flex items-center justify-between">
 				<!-- Dialog title -->
-				<h2 class="pointer-events-none mb-2 text-lg font-medium text-black select-none">
+				<h2
+					class="pointer-events-none mb-2 text-lg font-medium text-black select-none"
+					id="{identifier}-title"
+				>
 					{@render stringOrSnippet(title)}
 				</h2>
 
 				<!-- Close Button -->
 				{#if close !== null}
 					{#if typeof close === 'function'}
-						{@render close()}
+						{@render close(getState())}
 					{:else}
 						{@render dialogCloseButton(getState(), close)}
 					{/if}
@@ -254,7 +331,7 @@
 			{/if}
 
 			{#if description}
-				<p class="mb-3 leading-normal text-zinc-600">
+				<p class="mb-3 leading-normal text-zinc-600" id="{identifier}-description">
 					{@render stringOrSnippet(description)}
 				</p>
 			{/if}
@@ -270,7 +347,9 @@
 					controlsAlign === 'end' && 'justify-end'
 				]}
 			>
-				{#if controls && typeof controls === 'function'}{@render controls()}{:else if controls?.flip}
+				{#if controls && typeof controls === 'function'}{@render controls(
+						getState()
+					)}{:else if controls?.flip}
 					{#if controls.ok !== null}
 						{@render dialogOkButton(getState(), controls.ok)}
 					{/if}
@@ -300,7 +379,7 @@
 				state.api.close();
 			}
 		}}
-		disabled={state.frozen}
+		disabled={state.frozen || state.disabled}
 	>
 		{opts?.label || 'Cancel'}
 	</Button>
@@ -345,10 +424,10 @@
 	</button>
 {/snippet}
 
-{#snippet stringOrSnippet(val: string | Snippet)}
+{#snippet stringOrSnippet(val: string | Snippet<[state: DialogState]>)}
 	{#if typeof val === 'string'}
 		{val}
 	{:else}
-		{@render val()}
+		{@render val(getState())}
 	{/if}
 {/snippet}

src/lib/Tabs.svelte

@@ -23,12 +23,22 @@
 		activeIndex?: number;
 		/** Callback fired when the active tab changes */
 		onchange?: (event: { index: number; tab: TabPage }) => void;
-		/** Applies layout padding to the tab header & content areas (default: false) */
+		/** Applies layout padding to the tab header (default: false) */
-		padded?: boolean;
+		padHeader?: boolean;
+		/** Applies layout padding to the content areas (default: false) */
+		padContent?: 'padding' | 'margin' | 'none';
+		/** Additional classes applied to the outer container */
 		class?: ClassValue | null;
 	}
 
-	let { pages, activeIndex = 0, onchange, padded = false, class: classValue }: Props = $props();
+	let {
+		pages,
+		activeIndex = 0,
+		onchange,
+		padHeader = false,
+		padContent = 'none',
+		class: classValue
+	}: Props = $props();
 
 	let primaryContainerEl: HTMLDivElement;
 	let tabContainerEl: HTMLDivElement;
@@ -99,7 +109,7 @@
 		bind:this={tabContainerEl}
 		class={[
 			'border-sui-text/15 relative mb-4 flex items-center gap-5 border-b-2',
-			padded && 'px-layout'
+			padHeader && 'px-layout'
 		]}
 	>
 		{#each pages as page, i (page.title)}
@@ -134,7 +144,7 @@
 
 	{#key activeIndex}
 		<div
-			class={[padded && 'px-layout']}
+			class={[padContent === 'padding' && 'px-layout', padContent === 'margin' && 'mx-layout']}
 			in:flyX={{ direction: activeIndex > prevIndex ? 1 : -1, duration: 180, delay: 181 }}
 			out:flyX={{ direction: activeIndex > prevIndex ? -1 : 1, duration: 180 }}
 			onoutrostart={lockHeight}

src/lib/error.ts

@@ -7,21 +7,105 @@ export interface GraphError {
 }
 
 /** RawError is an error that can be converted to a string by ErrorMessage */
-export type RawError = Error | string | GraphError[];
+export type RawError = ErrorMessage | Error | string | GraphError[];
 
+/**
+ * Type guard to check if an error is a RawError
+ * @param error The error to check
+ * @returns true if the error is a RawError, false otherwise
+ */
+export const isRawError = (error: unknown): error is RawError => {
+	return (
+		error instanceof ErrorMessage ||
+		error instanceof Error ||
+		typeof error === 'string' ||
+		(Array.isArray(error) &&
+			error.every(
+				(e) => typeof e.message === 'string' && (e.path === undefined || Array.isArray(e.path))
+			))
+	);
+};
+
+/**
+ * Converts any error (including GraphQL errors, standard Errors, strings, and
+ * ErrorMessages) into a consistent string format for display.
+ * @param error The error to convert to a string.
+ * @returns A string representation of the error, suitable for display to users.
+ */
+export const catchErrorString = (error: unknown): string => {
+	if (error instanceof ErrorMessage) {
+		return error.toString();
+	} else if (isRawError(error)) {
+		return new ErrorMessage(error).toString();
+	} else {
+		return String(error);
+	}
+};
+
+/**
+ * Checks a typical response from a GraphQL server for error and missing data,
+ * throwing an appropriate ErrorMessage if an error is found or if no data is
+ * returned.
+ * @param resourceName A human-readable name for the resource being fetched,
+ * used in error messages.
+ * @param response The response from the GraphQL server, which may contain an
+ * 'errors' array and a 'data' field.
+ * @throws An ErrorMessage if the response contains errors or if the data field
+ * is missing (undefined or null).
+ */
+export const checkGraphResponse = (
+	resourceName: string,
+	response: { errors?: GraphError[] | null; data?: unknown }
+): void => {
+	if (response.errors && response.errors.length > 0) {
+		throw new ErrorMessage(`Error fetching ${resourceName}`, response.errors);
+	}
+	if (!response.data) {
+		throw new ErrorMessage(`No data returned for ${resourceName}`);
+	}
+};
+
+/**
+ * A class that represents an error message, which can be constructed from various types of raw errors
+ * and provides methods to convert those errors into a consistent format (lines of text) for display.
+ * It also supports wrapping existing error messages with additional context.
+ */
 export class ErrorMessage {
 	private _lines: string[] = [];
 
 	/**
-	 * Converts a RawError to an array of lines and stores it for later access,
+	 * Always creates a new ErrorMessage instance, even if there are no errors.
-	 * or initializes without any errors if the input is null or undefined.
+	 * @param errors The raw errors to convert and store, or null/undefined for no error.
-	 * @param raw The raw error to convert and store, or null/undefined for no error.
+	 * @throws If any of the raw errors are of an unsupported type.
-	 * @throws If the raw error is of an unsupported type.
 	 */
-	constructor(raw: RawError | null | undefined) {
+	constructor(...errors: (unknown | null | undefined)[]) {
-		if (raw) {
+		if (errors.length === 0) return;
-			this._lines = ErrorMessage.rawErrorToLines(raw);
+		this._lines = errors.flatMap((e) => ErrorMessage.rawErrorToLines(e));
-		}
+	}
+
+	/**
+	 * Creates a new ErrorMessage only if the provided errors are not null or
+	 * undefined. If no errors are provided, returns null.
+	 */
+	static from(...errors: (unknown | null | undefined)[]): ErrorMessage | null {
+		if (errors.length === 0) return null;
+		return new ErrorMessage(...errors);
+	}
+
+	/**
+	 * Wraps this ErrorMessage inside another error, nesting the original error.
+	 * @param errors The raw errors to wrap around this error, or null/undefined for no additional error.
+	 * @returns A new ErrorMessage instance that includes the original error and any new errors.
+	 */
+	wrap(...errors: (unknown | null | undefined)[]): ErrorMessage {
+		if (errors.length === 0) return this;
+		const newLines = errors.flatMap((e) => ErrorMessage.rawErrorToLines(e));
+		return new ErrorMessage(...newLines, ...this._lines);
+	}
+
+	/** returns true if there are any error lines */
+	hasError(): boolean {
+		return this._lines.length > 0;
 	}
 
 	/** returns the stored lines */
@@ -37,28 +121,14 @@ export class ErrorMessage {
 		return this._lines.join('<br />');
 	}
 
-	/** returns true if there are any error lines */
-	hasError(): boolean {
-		return this._lines.length > 0;
-	}
-
-	/** adds a new line to the error message */
-	addLine(line: string): void {
-		this._lines.push(line);
-	}
-
-	/** optionally returns a new ErrorMessage only if the RawError is not empty */
-	static from(raw: RawError | null | undefined): ErrorMessage | null {
-		if (!raw) return null;
-		return new ErrorMessage(raw);
-	}
-
 	/** converts a RawError to an array of lines */
-	static rawErrorToLines(raw: RawError | null | undefined): string[] {
+	static rawErrorToLines(raw: unknown | null | undefined): string[] {
-		if (!raw) return ['No error'];
+		if (!raw) return [];
 
 		let errorLines: string[];
-		if (typeof raw === 'string') {
+		if (raw instanceof ErrorMessage) {
+			errorLines = raw.lines;
+		} else if (typeof raw === 'string') {
 			errorLines = [raw];
 		} else if (raw instanceof Error) {
 			errorLines = [raw.message];

src/lib/floating.svelte.ts

@@ -4,7 +4,7 @@
  * for more details, examples, and original source.
  */
 
-import { computePosition, autoUpdate, flip, offset, type Placement } from '@floating-ui/dom';
+import { computePosition, autoUpdate, flip, offset, type Placement, size } from '@floating-ui/dom';
 import { createAttachmentKey } from 'svelte/attachments';
 
 /**
@@ -17,6 +17,13 @@ export interface PopoverOptions {
 	placement?: Placement;
 	/** Offset distance between the reference and floating elements (default: 8) */
 	offset?: number;
+	/**
+	 * Constraints the width and height of the popover to prevent it from
+	 * overflowing the viewport. If true, the popover will adjust its max-width
+	 * and max-height to fit. Scrolling is the responsibility of the parent
+	 * element. Default is true.
+	 */
+	constrainSize?: boolean;
 	/** Callback when the popover is opened or closed */
 	ontoggle?: (open: boolean) => void;
 }
@@ -29,10 +36,12 @@ export class Popover {
 	private options: PopoverOptions = {
 		interaction: 'click',
 		placement: 'bottom-start',
-		offset: 8
+		offset: 8,
+		constrainSize: true
 	};
 	private referenceElement: HTMLElement | undefined = $state();
 	private floatingElement: HTMLElement | undefined = $state();
+	private positionElement: HTMLElement | undefined = $state();
 	private open = $state(false);
 
 	/**
@@ -87,6 +96,23 @@ export class Popover {
 		return attrs;
 	}
 
+	/**
+	 * Optionally sets the positioning element for the popover, which is used
+	 * for calculating the position of the floating element. If not set, the
+	 * reference element is used by default.
+	 * @returns An object containing an attachment key for the positioning element.
+	 */
+	positionReference() {
+		return {
+			[createAttachmentKey()]: (node: HTMLElement) => {
+				this.positionElement = node;
+				return () => {
+					this.positionElement = undefined;
+				};
+			}
+		};
+	}
+
 	/** Returns whether the popover is open */
 	isOpen() {
 		return this.open;
@@ -122,6 +148,38 @@ export class Popover {
 		};
 	}
 
+	/**
+	 * Callback function that closes the popover when the Escape key is pressed.
+	 * Can be applied to the window, typically via <svelte:window onkeydown={popover.handleEscape} />,
+	 * or to any other element that will receive keyboard events while the popover is open.
+	 * @param event - The keyboard event to handle.
+	 */
+	handleEscape(event: KeyboardEvent) {
+		if (event.key === 'Escape') {
+			this.setOpen(false);
+		}
+	}
+
+	/**
+	 * Callback function that closes the popover when a click occurs outside of the
+	 * reference and floating elements. Should be applied to the window, typically
+	 * via <svelte:window onclick={popover.handleClickOutside} />.
+	 * @param event - The click event to handle.
+	 */
+	handleClickOutside(event: MouseEvent) {
+		if (!this.isOpen() || !this.referenceElement || !this.floatingElement) {
+			return;
+		}
+
+		if (
+			event.target instanceof Node &&
+			!this.referenceElement.contains(event.target) &&
+			!this.floatingElement.contains(event.target)
+		) {
+			this.setOpen(false);
+		}
+	}
+
 	/**
 	 * Updates the position of the floating element based on the reference element using
 	 * the computePosition function from floating-ui. It applies the calculated
@@ -131,9 +189,24 @@ export class Popover {
 		if (!this.referenceElement || !this.floatingElement) {
 			return;
 		}
-		const position = await computePosition(this.referenceElement, this.floatingElement, {
+		const reference = this.positionElement || this.referenceElement;
+		const position = await computePosition(reference, this.floatingElement, {
 			placement: this.options.placement,
-			middleware: [flip(), offset(this.options.offset)]
+			middleware: [
+				flip(),
+				offset(this.options.offset),
+				size({
+					apply: ({ availableWidth, availableHeight, elements }) => {
+						if (this.options.constrainSize) {
+							elements.floating.style.maxWidth = `${availableWidth}px`;
+							elements.floating.style.maxHeight = `${availableHeight}px`;
+						} else {
+							elements.floating.style.maxWidth = '';
+							elements.floating.style.maxHeight = '';
+						}
+					}
+				})
+			]
 		});
 		const { x, y } = position;
 		Object.assign(this.floatingElement.style, {

src/lib/index.ts

@@ -10,6 +10,7 @@ export {
 	default as Dialog,
 	type DialogAPI,
 	type DialogControls,
+	type DialogState,
 	dialogCancelButton,
 	dialogCloseButton,
 	dialogOkButton
@@ -30,6 +31,7 @@ export { default as Label } from './Label.svelte';
 export { default as Link, rewriteHref } from './Link.svelte';
 export { default as PhoneInput } from './PhoneInput.svelte';
 export { default as PinInput } from './PinInput.svelte';
+export { type Preventable, checkPreventer, type Reversible, checkReversible } from './prevent';
 export { default as RadioGroup } from './RadioGroup.svelte';
 export { default as ScrollBox } from './ScrollBox.svelte';
 export { default as Spinner } from './Spinner.svelte';
@@ -66,7 +68,14 @@ export {
 	ToolbarGroup,
 	Toolbar
 } from './Toolbar';
-export { type GraphError, type RawError, ErrorMessage } from './error';
+export {
+	type GraphError,
+	type RawError,
+	isRawError,
+	catchErrorString,
+	checkGraphResponse,
+	ErrorMessage
+} from './error';
 export {
 	NavigationItem,
 	NavigationManager,

src/lib/prevent.ts

@@ -0,0 +1,63 @@
+/**
+ * A type for a function that can be prevented from executing its default behavior.
+ * See checkPreventer for easy usage of this type.
+ */
+export type Preventable<T> = (ev: T & { prevent: () => void }) => Promise<void> | void;
+
+/**
+ * Calls the provided function with a preventer object, and if the preventer is not
+ * prevented, calls the callback function.
+ * @param fn The function to call with the preventer.
+ * @param ev The event object to pass to the function.
+ * @param cb The callback function to call if the preventer is not prevented.
+ * @returns A promise that resolves to true if the action was not prevented, or false if it was prevented.
+ */
+export const checkPreventer = async <T>(
+	fn: Preventable<T>,
+	ev: T,
+	cb?: () => void
+): Promise<boolean> => {
+	let prevented = false;
+	const preventer = {
+		prevent: () => {
+			prevented = true;
+		}
+	};
+	await fn({ ...ev, ...preventer });
+	if (!prevented && cb) {
+		cb();
+	}
+	return !prevented;
+};
+
+/**
+ * A type for a function that can be reversed after executing its behavior.
+ * See checkReversible for easy usage of this type.
+ */
+export type Reversible<T> = (ev: T & { reverse: () => void }) => Promise<void> | void;
+
+/**
+ * Calls the provided function with a reverser object, and if the reverser is
+ * reversed, calls the callback function.
+ * @param fn The function to call with the reverser.
+ * @param ev The event object to pass to the function.
+ * @param cb The callback function to call if the reverser is reversed.
+ * @returns A promise that resolves to true if the action was not reversed, or false if it was reversed.
+ */
+export const checkReversible = async <T>(
+	fn: Reversible<T>,
+	ev: T,
+	cb?: () => void
+): Promise<boolean> => {
+	let reversed = false;
+	const reverser = {
+		reverse: () => {
+			reversed = true;
+		}
+	};
+	await fn({ ...ev, ...reverser });
+	if (reversed && cb) {
+		cb();
+	}
+	return !reversed;
+};

src/routes/+page.svelte

@@ -35,8 +35,7 @@
 	import { createLazyComponent, type ComboboxOption, type Option } from '$lib';
 	import Tabs from '$lib/Tabs.svelte';
 	import { Time } from '@internationalized/date';
-	import { onMount, type Component } from 'svelte';
+	import { onMount } from 'svelte';
-	import ErrorBox from '$lib/ErrorBox.svelte';
 	import TextareaInput from '$lib/TextareaInput.svelte';
 	import DurationInput, { formatDuration } from '$lib/DurationInput.svelte';
 	import Banner from '$lib/Banner.svelte';
@@ -60,6 +59,7 @@
 	let dateInputValue = $state<CalendarDate | null>(null);
 	let checkboxValue = $state<CheckboxState>('indeterminate');
 	let dialogOpen = $state(false);
+	let nestedDialogOpen = $state(false);
 	let scrollableDialogOpen = $state(false);
 	let toggleOptions: Option[] = $state([
 		'item one',
@@ -184,7 +184,7 @@
 			]}
 			onchange={(e) => console.log('Selected:', e.value)}
 			onvalidate={(e) => console.log('Validation:', e.detail)}
-			pickerWidth="max-match"
+			pickerWidth="longest"
 		>
 			{#snippet labelRender(opt: ComboboxOption)}
 				Processed {opt.label}
@@ -218,7 +218,7 @@
 			label="Lazy combobox"
 			placeholder="Choose..."
 			options={lazyOptions}
-			lazy={'always'}
+			lazy="always"
 			onlazy={async () => {
 				await new Promise((resolve) => setTimeout(resolve, 2500));
 				lazyOptions = [
@@ -537,15 +537,6 @@
 	bind:open={dialogOpen}
 	title="Dialog Title"
 	size="sm"
-	controls={{
-		ok: {
-			action: (dialog) => {
-				dialog.close();
-				alert('Dialog submitted!');
-			}
-		},
-		cancel: null
-	}}
 	onopen={(dialog) => {
 		dialog.error('Example error message!');
 		dialog.loading();
@@ -554,7 +545,27 @@
 		}, 2000);
 	}}
 >
+	{#snippet controls(state)}
+		<Button onclick={() => state.api.close()}>Cancel</Button>
+		<Button
+			onclick={() => {
+				state.api.close();
+				alert('Dialog submitted!');
+			}}
+			loading={state.loading}
+		>
+			Submit
+		</Button>
+	{/snippet}
+
 	<p>This is a dialog content area.</p>
+
+	<Button onclick={() => (nestedDialogOpen = true)}>Open Nested Dialog</Button>
+</Dialog>
+
+<!-- Nested Dialog Demo -->
+<Dialog bind:open={nestedDialogOpen} title="Nested Dialog" size="sm">
+	<p>This is a nested dialog content area.</p>
 </Dialog>
 
 <!-- Scrollable Dialog Demo -->