tabs: separate controls for header and content padding

Enabled by default, autofreeze freezes the dialog whenever loading state
is enabled.

.vscode/settings.json

@@ -2,5 +2,6 @@
 	"files.associations": {
 		"*.css": "tailwindcss"
 	},
-	"makefile.configureOnOpen": false
+	"makefile.configureOnOpen": false,
+	"tailwindCSS.experimental.configFile": "src/lib/styles/tailwind.css"
 }

package.json

@@ -4,7 +4,7 @@
 		"type": "git",
 		"url": "https://gitea.auvem.com/svelte-toolkit/sui.git"
 	},
-	"version": "1.0.2",
+	"version": "1.1.2",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",
@@ -62,6 +62,7 @@
 	"devDependencies": {
 		"@eslint/compat": "^1.2.5",
 		"@eslint/js": "^9.18.0",
+		"@floating-ui/dom": "^1.7.6",
 		"@sveltejs/adapter-auto": "^4.0.0",
 		"@sveltejs/package": "^2.5.0",
 		"@sveltejs/vite-plugin-svelte": "^5.0.0",

pnpm-lock.yaml

@@ -40,7 +40,7 @@ importers:
         version: 8.1.0
       melt:
         specifier: ^0.37.0
-        version: 0.37.0(@floating-ui/dom@1.7.3)(svelte@5.38.1)
+        version: 0.37.0(@floating-ui/dom@1.7.6)(svelte@5.38.1)
       moment:
         specifier: ^2.30.1
         version: 2.30.1
@@ -66,6 +66,9 @@ importers:
       '@eslint/js':
         specifier: ^9.18.0
         version: 9.33.0
+      '@floating-ui/dom':
+        specifier: ^1.7.6
+        version: 1.7.6
       '@sveltejs/adapter-auto':
         specifier: ^4.0.0
         version: 4.0.0(@sveltejs/kit@2.28.0(@sveltejs/vite-plugin-svelte@5.1.1(svelte@5.38.1)(vite@6.3.5(@types/node@24.2.1)(jiti@2.5.1)(lightningcss@1.30.1)))(svelte@5.38.1)(vite@6.3.5(@types/node@24.2.1)(jiti@2.5.1)(lightningcss@1.30.1)))
@@ -328,14 +331,14 @@ packages:
     resolution: {integrity: sha512-Z5kJ+wU3oA7MMIqVR9tyZRtjYPr4OC004Q4Rw7pgOKUOKkJfZ3O24nz3WYfGRpMDNmcOi3TwQOmgm7B7Tpii0w==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
-  '@floating-ui/core@1.7.3':
+  '@floating-ui/core@1.7.5':
-    resolution: {integrity: sha512-sGnvb5dmrJaKEZ+LDIpguvdX3bDlEllmv4/ClQ9awcmCZrlx5jQyyMWFM5kBI+EyNOCDDiKk8il0zeuX3Zlg/w==}
+    resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==}
 
-  '@floating-ui/dom@1.7.3':
+  '@floating-ui/dom@1.7.6':
-    resolution: {integrity: sha512-uZA413QEpNuhtb3/iIKoYMSK07keHPYeXF02Zhd6e213j+d1NamLix/mCLxBUDW/Gx52sPH2m+chlUsyaBs/Ag==}
+    resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==}
 
-  '@floating-ui/utils@0.2.10':
+  '@floating-ui/utils@0.2.11':
-    resolution: {integrity: sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ==}
+    resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
 
   '@humanfs/core@0.19.1':
     resolution: {integrity: sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA==}
@@ -1803,16 +1806,16 @@ snapshots:
       '@eslint/core': 0.15.2
       levn: 0.4.1
 
-  '@floating-ui/core@1.7.3':
+  '@floating-ui/core@1.7.5':
     dependencies:
-      '@floating-ui/utils': 0.2.10
+      '@floating-ui/utils': 0.2.11
 
-  '@floating-ui/dom@1.7.3':
+  '@floating-ui/dom@1.7.6':
     dependencies:
-      '@floating-ui/core': 1.7.3
+      '@floating-ui/core': 1.7.5
-      '@floating-ui/utils': 0.2.10
+      '@floating-ui/utils': 0.2.11
 
-  '@floating-ui/utils@0.2.10': {}
+  '@floating-ui/utils@0.2.11': {}
 
   '@humanfs/core@0.19.1': {}
 
@@ -2641,9 +2644,9 @@ snapshots:
       '@babel/runtime': 7.28.2
       remove-accents: 0.5.0
 
-  melt@0.37.0(@floating-ui/dom@1.7.3)(svelte@5.38.1):
+  melt@0.37.0(@floating-ui/dom@1.7.6)(svelte@5.38.1):
     dependencies:
-      '@floating-ui/dom': 1.7.3
+      '@floating-ui/dom': 1.7.6
       dequal: 2.0.3
       focus-trap: 7.6.5
       jest-axe: 9.0.0

src/lib/Combobox.svelte

@@ -1,16 +1,38 @@
 <script lang="ts" module>
 	export type ComboboxOption = {
+		/** Value of the option */
 		value: string;
+		/**
+		 * Label of the option displayed in the picker and, if the option is
+		 * selected, in the main input field. Preview overrides label if provided
+		 * and the combobox is open (see usePreview prop for exceptions).
+		 */
 		label?: string;
-		infotext?: string;
+		/**
+		 * Preview text for the option, displayed in the main input field when
+		 * the option is selected. See usePreview prop for controlling when
+		 * preview takes precedence over label.
+		 */
 		preview?: string;
+		/**
+		 * Additional information text for the option, displayed beside the
+		 * label in the picker and, if the option is selected, in the main
+		 * input field.
+		 */
+		infotext?: string;
+		/** An optional icon for the option, displayed in the picker and,
+		 * if the option is selected, in the main input field.
+		 */
+		icon?: IconDef;
+		/** Whether the option is disabled */
 		disabled?: boolean;
-		icon?: Snippet<[item: ComboboxOption]>;
-		render?: Snippet<[item: ComboboxOption]>;
 	};
 
-	const getLabel = (item: ComboboxOption | undefined): string => item?.label ?? item?.value ?? '';
+	/** returns option label, falling back to value or 'Undefined Option' if no option provided */
-	const getPreview = (item: ComboboxOption | undefined): string => item?.preview ?? getLabel(item);
+	const getLabel = (opt: ComboboxOption | undefined): 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);
 </script>
 
 <script lang="ts">
@@ -19,51 +41,145 @@
 	import Label from './Label.svelte';
 	import StyledRawInput from './StyledRawInput.svelte';
 	import { InputValidatorEvent, validate, type ValidatorOptions } from '@svelte-toolkit/validate';
-	import type { Action } from 'svelte/action';
+	import { untrack, type Snippet } from 'svelte';
-	import { onMount, tick, untrack, type Snippet } from 'svelte';
-	import { Portal } from '@jsrob/svelte-portal';
 	import { scale } from 'svelte/transition';
 	import { generateIdentifier, type IconDef } from './util';
-	import type { ClassValue } from 'svelte/elements';
+	import type { ClassValue, MouseEventHandler } from 'svelte/elements';
 	import { matchSorter } from 'match-sorter';
 	import Spinner from './Spinner.svelte';
+	import type { KeyOption } from 'match-sorter';
+	import { Tween } from 'svelte/motion';
+	import { cubicOut } from 'svelte/easing';
+	import type { Attachment } from 'svelte/attachments';
+	import { Popover } from './floating.svelte';
 
 	interface Props {
-		name?: string;
-		value?: ComboboxOption;
-		open?: boolean;
-		usePreview?: boolean | 'auto';
-		matchWidth?: boolean;
-		options: ComboboxOption[];
-		required?: boolean;
-		invalidMessage?: string | null;
-		label?: string;
-		placeholder?: string;
-		/** displayed by default if no item is selected that has its own icon */
-		icon?: IconDef;
 		/**
-		 * enables loading spinner and fallback text if no items are found. may be changed
+		 * Name of the input, used for form submission. The currently selected
-		 * internally if lazy is enabled. loading is, however, not bindable, so don't expect
+		 * option's value will be submitted under this name.
-		 * any internal changes to be propagated outward.
+		 */
+		name?: string;
+		/** Optional label for the combobox */
+		label?: string;
+		/** Optional placeholder for the main input field */
+		placeholder?: string;
+		/** Whether an option must be selected to continue (default: false) */
+		required?: boolean;
+		/**
+		 * Message displayed below the main input field when required but no
+		 * option is selected (default: 'Please select an option'). If set to
+		 * null, no message is displayed.
+		 */
+		invalidMessage?: string | null;
+		/**
+		 * Allows the user to select an option without updating the value
+		 * (events are still triggered).
+		 */
+		stateless?: boolean;
+
+		/** Bindable value of the combobox, the currently selected option */
+		value?: ComboboxOption;
+		/** Array of ComboboxOptions for the picker */
+		options: ComboboxOption[];
+		/**
+		 * Overrides label render behaviour for all options. Receives the option
+		 * as an argument. If not provided, the option's `label` field is used.
+		 * Option `label` field must still be present for search, accessibility,
+		 * and visibility in the main input field.
+		 */
+		labelRender?: Snippet<[opt: ComboboxOption]>;
+		/**
+		 * Overrides infotext render behaviour for all options. Receives the option
+		 * as an argument. If not provided, the option's `infotext` field is used.
+		 * Option `infotext` field must still be present for search and accessibility.
+		 */
+		infotextRender?: Snippet<[opt: ComboboxOption]>;
+		/**
+		 * Overrides icon render behaviour for all options and the main input. Receives
+		 * the option as an argument. If not provided, the option's `icon` field is used,
+		 * based on the phosphor `IconDef` structure.
+		 */
+		iconRender?: Snippet<[opt: ComboboxOption]>;
+
+		/** Bindable open state of the combobox */
+		open?: boolean;
+		/**
+		 * Determines picker width based on content with four options:
+		 * `match`: matches the input width
+		 * `average`: calculates average width based on the length of option
+		 *  content, with a reasonable minimum
+		 * `longest`: sets width based on the longest option, which can lead to
+		 * excessively wide pickers but tries to prevent wrapping
+		 * `max-match` (default): sets width based on the maximum of the input
+		 * width and the longest option
+		 */
+		pickerWidth?: 'match' | 'average' | 'longest' | 'max-match';
+		/** Uses a compact layout for the search input with less padding and smaller text */
+		compact?: boolean;
+		/**
+		 * Optional icon displayed as long as the selected option does not have
+		 * its own icon.
+		 */
+		icon?: IconDef | Snippet;
+		/**
+		 * Bindable loading state controls visibility of spinner and fallback
+		 * text if no options are found (see notFoundMessage). Only changed
+		 * internally if lazy loading is used.
 		 */
 		loading?: boolean;
-		/** applies the loading state on first interaction */
+		/** Special always-disabled option displayed when loading */
-		lazy?: boolean;
+		loadingOption?: ComboboxOption;
-		/** uses a compact layout for the search input with less padding and smaller text */
+		/**
-		compact?: boolean;
+		 * Applies the loading state when the picker is opened, allowing for
-		/** allows the user to select an option without selecting a value (events are still triggered) */
+		 * asynchronous loading of options.
-		stateless?: boolean;
+		 * `always`: applies loading state each time the picker is opened
-		notFoundMessage?: string;
+		 * `true`: applies loading state only the first time the picker is opened
+		 * `false` (default): loading state must be controlled externally
+		 */
+		lazy?: 'always' | boolean;
+		/**
+		 * Controls when the option preview should take precedence over the
+		 * label in the main input field.
+		 * `auto` (default): uses preview only when the picker is closed
+		 * `true`: always uses preview
+		 * `false`: never uses preview
+		 */
+		usePreview?: boolean | 'auto';
+		/** Special always-disabled option displayed when no options match the search */
+		notFoundOption?: ComboboxOption;
+		/**
+		 * Configures which option fields are included in the search
+		 * (default: 'label' and 'value'). An empty array triggers fallback
+		 * to searching by value only.
+		 */
+		searchKeys?: ('value' | 'label' | 'preview' | 'infotext')[];
+
+		/** Additional classes applied to the persistent div container */
 		class?: ClassValue | null | undefined;
+		/** Optional action applied to the main input */
 		use?: () => void;
+
+		/** Callback when the input value changes, triggering validation */
 		onvalidate?: (e: InputValidatorEvent) => void;
-		onchange?: (item: ComboboxOption) => void;
+		/** Callback when the selected option changes */
+		onchange?: (opt: ComboboxOption) => void;
+		/** Callback when a search is performed */
 		onsearch?: (query: string) => boolean | void;
-		onscroll?: (detail: { event: UIEvent; top: boolean; bottom: boolean }) => void;
+		/** Callback when the picker is scrolled */
-		/** this callback runs only once on the first interaction if lazy is enabled */
+		onscroll?: (detail: {
-		onlazy?: () => void;
+			event: UIEvent;
-		onopen?: () => void;
+			top: boolean;
-		onclose?: () => void;
+			bottom: boolean;
+			searchInput: string;
+		}) => void;
+		/**
+		 * Callback when options should be lazily loaded, see lazy prop.
+		 * Expects a promise to be returned, allowing for loading state
+		 * to be automatically managed.
+		 */
+		onlazy?: () => Promise<void>;
+		/** Callback when the picker is opened or closed */
+		onopenchange?: (open: boolean) => void;
 	}
 
 	let {
@@ -71,18 +187,20 @@
 		value = $bindable<ComboboxOption | undefined>(undefined),
 		open = $bindable(false),
 		usePreview = 'auto',
-		matchWidth = false,
+		pickerWidth = 'average',
 		options,
 		required = false,
 		invalidMessage = 'Please select an option',
 		label,
 		placeholder,
 		icon,
-		loading = false,
+		loading = $bindable(false),
 		lazy = false,
 		compact = false,
 		stateless = false,
-		notFoundMessage = 'No results found',
+		loadingOption = { value: 'special-loading', label: 'Loading...' },
+		notFoundOption = { value: 'special-not-found', label: 'No options found' },
+		searchKeys = ['label', 'value'],
 		class: classValue,
 		use,
 		onvalidate,
@@ -90,32 +208,69 @@
 		onsearch,
 		onscroll,
 		onlazy,
-		onopen,
+		onopenchange,
-		onclose
+		labelRender,
+		infotextRender,
+		iconRender
 	}: Props = $props();
 
-	let id = $derived(generateIdentifier('combobox', name));
+	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('');
 	let pickerPosition = $state<'top' | 'bottom'>('bottom');
 	let searching = $state(false);
-	let iconWidth = $state<number | undefined>(undefined);
 
 	let searchInput = $state<HTMLInputElement | null>(null);
 	let searchContainer = $state<HTMLDivElement | null>(null);
 	let pickerContainer = $state<HTMLDivElement | null>(null);
 
-	/** stores options filtered according to search value */
+	/** options filtered by search value and searchKeys */
 	const filteredItems = $derived.by(() => {
-		const arr = matchSorter(options, searchValue, { keys: [(item) => getLabel(item)] });
+		let keys: KeyOption<ComboboxOption>[] = [];
-		// if (loading) {
+		if (searchKeySet.has('label')) keys.push((item) => getLabel(item));
-		// arr.push({ value: 'loading', label: 'Loading more...', disabled: true });
+		if (searchKeySet.has('preview')) keys.push((item) => getPreview(item));
-		// }
+		if (searchKeySet.has('infotext')) keys.push('infotext');
+		if (searchKeySet.has('value') || keys.length === 0) keys.push('value');
+		const arr = matchSorter(options, searchValue, { keys });
 		return arr;
 	});
 
-	/** stores currently highlighted option (according to keyboard navigation or default item) */
+	/** currently highlighted option, updated by keyboard navigation or defaults to first item */
 	let highlighted = $derived.by((): ComboboxOption | undefined => {
 		if (!searching) return undefined; // otherwise, the first item is highlighted on first open
 		if (filteredItems.length === 0) return undefined;
@@ -123,20 +278,50 @@
 		if (!filteredItems[0]?.disabled) return filteredItems[0];
 	});
 
-	/** controls whether an icon should be displayed */
+	/**
-	let iconVisible = $derived(
+	 * Whether an icon should be displayed with the main input.
+	 * The icon is determined by the following precedence:
+	 * highlighted option (only when the picker is open) > selected value > icon prop
+	 */
+	const iconVisible = $derived(
 		(open && highlighted && highlighted.icon) ||
 			(value && value.icon && searchValue === '') ||
 			loading ||
 			icon !== undefined
 	);
 
-	/** controls whether the highlighted option should be used in the selection preview  */
+	/** whether the highlighted option should be used in the selection preview  */
-	let useHighlighted = $derived.by(() => {
+	const useHighlighted = $derived.by(() => {
 		return open && highlighted;
 	});
 
-	const validateOpts: ValidatorOptions = { required };
+	/** validation options build from props */
+	const validateOpts: ValidatorOptions = $derived({ required });
+
+	/** calculates padding for the input based on icon visibility and size */
+	const calculatePadding = () => {
+		const gap = 5; // gap between icon and text
+		// base padding when no icon is visible, see StyledRawInput padding
+		const basePadding = compact ? 12 : 18;
+		// if icon is visible, padding is icon width + gap + base padding,
+		// otherwise it's just base padding
+		return iconVisible ? iconWidth + gap + basePadding : basePadding;
+	};
+	let iconWidth = $state<number>(0);
+	/** tweens main input padding */
+	const inputPadding = new Tween(calculatePadding(), {
+		duration: 150,
+		easing: cubicOut
+	});
+	$effect(() => {
+		if (iconWidth >= 0) {
+			untrack(() => {
+				inputPadding.target = calculatePadding();
+			});
+		}
+	});
+
+	/*** HELPER FUNCTIONS ***/
 
 	/** returns the index of the highlighted item in filteredItems */
 	const getHighlightedIndex = () => {
@@ -172,104 +357,66 @@
 	};
 
 	let lazyApplied = false;
-	/** opens combobox picker and propages any necessary events */
-	const openPicker = () => {
-		open = true;
-
-		// if lazy and not applied, enable loading state once and run callback
-		if (lazy && !lazyApplied) {
-			lazyApplied = true;
-			loading = true;
-			onlazy?.();
-		}
-
-		updatePickerRect(); // update picker position
-		scrollToHighlighted(); // scroll to highlighted item
-		onopen?.(); // trigger onopen event if defined
-	};
-	/** closes combobox picker and propages 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
-		onclose?.(); // trigger onclose 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);
 	};
 
-	/** action to set the minimum width of the combobox based on the number of options */
+	/**
-	const minWidth: Action<HTMLDivElement, { options: ComboboxOption[] }> = (
+	 * Calculates average width based on provided options returning an estimated
-		container,
+	 * width in 'ch' units or a reasonable minimum when no options are provided.
-		buildOpts
+	 */
-	) => {
+	const calculateAvgWidth = (opts: ComboboxOption[]) => {
-		const f = (opts: typeof buildOpts) => {
+		if (opts.length === 0) return '10ch'; // reasonable minimum width when no options
-			if (matchWidth && searchInput) {
+		const labelAvg = opts.reduce((acc, item) => acc + getLabel(item).length, 0) / opts.length;
-				container.style.width = searchInput.scrollWidth + 'px';
+		const infotextAvg =
-				return;
+			opts.reduce((acc, item) => acc + (item.infotext ? item.infotext.length : 0), 0) / opts.length;
-			}
+		const avgWidth = labelAvg * 2 + infotextAvg * 1.5 + (infotextAvg > 0 ? 10 : 0);
-
+		return `${Math.max(avgWidth, 10)}ch`;
-			const options = opts.options;
-			if (options.length === 0) return;
-			const avg = options.reduce((acc, item) => acc + getLabel(item).length, 0) / options.length;
-			container.style.width = `${avg * 2.5}ch`;
-		};
-
-		f(buildOpts);
-
-		return {
-			update: (updateOpts: typeof buildOpts) => {
-				f(updateOpts);
-			}
-		};
 	};
 
-	/** updates the position of the picker */
+	/**
-	const updatePickerRect = async () => {
+	 * Calculates longest width based on provided options, attempting to prevent
-		if (!searchContainer || !pickerContainer) {
+	 * wrapping by returning a width in 'ch' units based on the longest label and
-			await tick();
+	 * infotext, or a reasonable minimum when no options are provided.
-			if (!searchContainer || !pickerContainer) {
+	 */
-				return;
+	const calculateLongestWidth = (opts: ComboboxOption[]) => {
+		if (opts.length === 0) return '10ch'; // reasonable minimum width when no options
+		const longestLabel = Math.max(...opts.map((item) => getLabel(item).length));
+		const longestInfotext = Math.max(
+			...opts.map((item) => (item.infotext ? item.infotext.length : 0))
+		);
+		const longestWidth = longestLabel * 2 + longestInfotext * 1.5 + (longestInfotext > 0 ? 10 : 0);
+		return `${Math.max(longestWidth, 10)}ch`;
+	};
+
+	/** sets minimum width of the picker as configured by props */
+	const minWidth = (opts: {
+		options: ComboboxOption[];
+		matchElem: HTMLInputElement | null;
+		mode: Props['pickerWidth'];
+	}): Attachment<HTMLDivElement> => {
+		return (elem) => {
+			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';
+			} else {
+				// otherwise, set width based on average content width
+				let val = '10ch';
+				if (opts.mode === 'average') {
+					val = calculateAvgWidth(opts.options);
+				} else if (opts.mode === 'longest' || opts.mode === 'max-match') {
+					val = calculateLongestWidth(opts.options);
+					if (opts.mode === 'max-match') {
+						elem.style.maxWidth = opts.matchElem ? opts.matchElem.offsetWidth + 'px' : 'none';
+					}
+				}
+				elem.style.width = val;
 			}
-		}
+		};
-
-		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 */
@@ -292,7 +439,7 @@
 		}
 	};
 
-	const conditionalUse = $derived(use ? use : () => {});
+	/*** EXPORTED API ***/
 
 	/** focuses the combobox search input */
 	export const focus = () => {
@@ -309,18 +456,21 @@
 		}
 	};
 
-	// when the value (or, in some circumstances, highlighted item) changes, update the search input
+	/*** EFFECTS & WINDOW CALLBACKS ***/
+
+	// when the value (or, in some circumstances, highlighted item) changes,
+	// update the search input
+	//
+	// expected triggers include: value, highlighted, useHighlighted, usePreview,
+	// searchInput, searching, and open
 	$effect(() => {
-		if (!searchInput) return;
+		if (!searchInput || searching) return;
 
-		if (useHighlighted && !searching) {
+		if ((!value && !highlighted) || (useHighlighted && !highlighted)) {
+			searchInput.value = '';
+		} else if (useHighlighted) {
 			searchInput.value = getLabel(highlighted);
-			return;
+		} else if (!usePreview || (usePreview === 'auto' && open)) {
-		}
-
-		if (untrack(() => searching)) return;
-
-		if (!usePreview || (usePreview === 'auto' && open)) {
 			searchInput.value = getLabel(value);
 		} else {
 			searchInput.value = getPreview(value);
@@ -334,130 +484,71 @@
 		}
 	});
 
-	onMount(() => {
+	// close picker if clicked outside
-		// set initial picker position on load
+	const handleWindowClick: MouseEventHandler<Window> = (e) => {
-		setTimeout(() => {
+		if (!open || !searchContainer || !pickerContainer) return;
-			updatePickerRect();
-		}, 500);
 
-		// update picker position on window resize
+		if (
-		window.addEventListener('resize', updatePickerRect);
+			e.target instanceof Node &&
-
+			!searchContainer.contains(e.target) &&
-		// add window click listener to close picker
+			!pickerContainer.contains(e.target)
-		window.addEventListener('click', (e) => {
+		) {
-			if (!searchContainer || !pickerContainer) {
+			popover.setOpen(false);
-				return;
+		}
-			}
+	};
-
-			if (
-				searchContainer.contains(e.target as Node) ||
-				pickerContainer.contains(e.target as Node) ||
-				!open
-			) {
-				return;
-			}
-
-			closePicker();
-		});
-	});
 </script>
 
+<svelte:window onclick={handleWindowClick} />
+
 <!-- Combobox picker -->
-<Portal target="body">
+{#if open}
-	{#if open}
+	<!-- 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)]'
-			]}
+		]}
-			use:minWidth={{ options: options }}
+		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 });
+			onscroll({ event: e, top: atTop, bottom: atBottom, searchInput: searchInput?.value ?? '' });
-			}}
+		}}
-			tabindex="0"
+		tabindex="0"
-		>
+		{@attach minWidth({ options, mode: pickerWidth, matchElem: searchInput })}
-			{#each filteredItems as item, i (item.value)}
+		{...popover.floating()}
-				<div
+	>
-					data-id={item.value}
+		{#each filteredItems as opt (opt.value)}
-					aria-selected={value?.value === item.value}
+			{@render option(opt)}
-					aria-label={getLabel(item)}
+		{:else}
-					aria-disabled={item.disabled}
+			<!-- Display loading state or not found if no options available -->
-					class={[
+			{#if loading}
-						!compact
+				{@render option(loadingOption, true)}
-							? 'mb-0.5 min-h-10 py-2.5 pr-1.5 pl-5'
-							: 'mb-0.25 min-h-8 py-1.5 pr-1.5 pl-2.5',
-						'flex flex-wrap items-center',
-						'rounded-sm text-sm capitalize outline-hidden select-none',
-						'hover:bg-sui-accent-500/30 dark:hover:bg-sui-accent-700/30',
-						item.value === highlighted?.value && 'bg-sui-accent-500/80 dark:bg-sui-accent-700/80',
-						item.disabled && 'cursor-not-allowed opacity-50'
-					]}
-					role="option"
-					onclick={() => {
-						if (item.disabled) return;
-						updateValue(item);
-						searchInput?.focus();
-					}}
-					onkeydown={() => {}}
-					tabindex="-1"
-				>
-					{#if item.icon}
-						{@render item.icon(item)}
-					{/if}
-
-					<div class={['mr-8', item.icon && 'ml-2']}>
-						{#if item.render}
-							{@render item.render(item)}
-						{:else}
-							{getLabel(item)}
-						{/if}
-					</div>
-
-					{#if item?.infotext}
-						<div class="text-sui-text/80 dark:text-sui-background/80 ml-auto text-sm">
-							{item.infotext}
-						</div>
-					{/if}
-
-					{#if value?.value === item.value}
-						<div class={[item?.infotext ? 'ml-2' : 'ml-auto']}>
-							<Check />
-						</div>
-					{/if}
-				</div>
 			{:else}
-				<span class="block px-5 py-2 text-sm">
+				{@render option(notFoundOption, true)}
-					{#if loading}
+			{/if}
-						Loading...
+		{/each}
-					{:else}
+	</div>
-						{notFoundMessage}
+{/if}
-					{/if}
-				</span>
-			{/each}
-		</div>
-	{/if}
-</Portal>
 
+<!-- Combobox main input container -->
 <div class={classValue}>
 	<!-- Combobox Label -->
 	{#if label}
@@ -490,34 +581,98 @@
 	{/if}
 </div>
 
+{#snippet optionIcon(opt: ComboboxOption)}
+	{#if iconRender}
+		{@render iconRender(opt)}
+	{:else if opt.icon}
+		<opt.icon.component {...opt.icon.props} />
+	{/if}
+{/snippet}
+
+<!-- Combobox option -->
+{#snippet option(opt: ComboboxOption, forceDisabled?: boolean)}
+	{@const optDisabled = opt.disabled || forceDisabled}
+	<!-- Option container -->
+	<div
+		data-id={opt.value}
+		aria-selected={value?.value === opt.value}
+		aria-label={getLabel(opt)}
+		aria-disabled={optDisabled}
+		class={[
+			!compact ? 'mb-0.5 min-h-10 py-2.5 pr-1.5 pl-5' : 'mb-0.25 min-h-8 py-1.5 pr-1.5 pl-2.5',
+			'flex flex-wrap items-center',
+			'rounded-sm text-sm capitalize outline-hidden select-none',
+			'hover:bg-sui-accent-500/30 dark:hover:bg-sui-accent-700/30',
+			opt.value === highlighted?.value && 'bg-sui-accent-500/80 dark:bg-sui-accent-700/80',
+			optDisabled && 'cursor-not-allowed opacity-50'
+		]}
+		role="option"
+		onclick={() => {
+			if (optDisabled) return;
+			updateValue(opt);
+			searchInput?.focus();
+		}}
+		onkeydown={() => {}}
+		tabindex="-1"
+	>
+		<!-- Option icon -->
+		{@render optionIcon(opt)}
+
+		<!-- Option label -->
+		<div class={['mr-8', opt.icon && 'ml-2']}>
+			{@render snippetOrString(opt, labelRender || getLabel(opt))}
+		</div>
+
+		<!-- Option infotext (always right-aligned) -->
+		{#if opt.infotext || infotextRender}
+			<div class="text-sui-text/80 dark:text-sui-background/80 ml-auto text-sm">
+				{@render snippetOrString(opt, infotextRender || opt.infotext)}
+			</div>
+		{/if}
+
+		<!-- Option checkmark, visible if selected -->
+		{#if value?.value === opt.value}
+			<div class={[opt?.infotext ? 'ml-2' : 'ml-auto']}>
+				<Check />
+			</div>
+		{/if}
+	</div>
+{/snippet}
+
 <!-- 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
 				class={[
-					(iconWidth === undefined || iconWidth === 0) && 'opacity-0',
+					'pointer-events-none absolute top-1/2 left-3.5 -translate-y-1/2 transform select-none',
-					'pointer-events-none absolute top-1/2 left-3.5 -translate-y-1/2 transform select-none'
+					iconWidth === 0 && 'opacity-0'
 				]}
 				transition:scale
 				bind:clientWidth={iconWidth}
 			>
 				{#if loading}
 					<Spinner class="stroke-sui-accent! -mt-0.5" size="1em" />
-				{:else if useHighlighted && highlighted?.icon}
+				{:else if useHighlighted && highlighted}
-					{@render highlighted.icon(highlighted)}
+					{@render optionIcon(highlighted)}
-				{:else if value?.icon}
+				{:else if value}
-					{@render value.icon(value)}
+					{@render optionIcon(value)}
 				{:else if icon}
-					<icon.component {...icon.props} />
+					{#if typeof icon === 'function'}
+						{@render icon()}
+					{:else}
+						<icon.component {...icon.props} />
+					{/if}
 				{:else}
 					❌
 				{/if}
 			</div>
 		{/if}
 
+		<!-- Combobox input box -->
 		<StyledRawInput
-			style={iconWidth && iconVisible ? `padding-left: ${iconWidth + 14 + 10}px` : undefined}
+			style={`padding-left: ${inputPadding.current}px`}
 			class={[caret && 'pr-9', !valid && 'border-red-500!']}
 			{compact}
 			type="text"
@@ -526,13 +681,7 @@
 			autocomplete="off"
 			bind:ref={searchInput}
 			onclick={() => {
-				if (!open) {
+				popover.setOpen(true);
-					setTimeout(() => {
-						searchInput?.select();
-					}, 100);
-				}
-
-				openPicker();
 			}}
 			onkeydown={(e) => {
 				if (!searchInput) return;
@@ -542,17 +691,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;
@@ -578,7 +727,8 @@
 			}}
 		/>
 
-		{#if (value && value.infotext) || (highlighted && useHighlighted && highlighted.infotext)}
+		<!-- Right-aligned infotext (overlay) -->
+		{#if (value && value.infotext) || (highlighted && useHighlighted && highlighted.infotext) || infotextRender}
 			<div
 				class={[
 					'pointer-events-none absolute top-1/2 -translate-y-1/2 transform text-sm select-none',
@@ -586,7 +736,11 @@
 					caret ? 'end-10' : 'end-[1.125rem]'
 				]}
 			>
-				{useHighlighted && highlighted?.infotext ? highlighted.infotext : value?.infotext}
+				{#if useHighlighted && highlighted}
+					{@render snippetOrString(highlighted, infotextRender || highlighted.infotext)}
+				{:else if value}
+					{@render snippetOrString(value, infotextRender || value.infotext)}
+				{/if}
 			</div>
 		{/if}
 
@@ -594,14 +748,24 @@
 			<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}
 	</div>
 {/snippet}
 
+{#snippet snippetOrString(
+	opt: ComboboxOption,
+	value: string | Snippet<[item: ComboboxOption]> | undefined
+)}
+	{#if typeof value === 'function'}
+		{@render value(opt)}
+	{:else}
+		{value}
+	{/if}
+{/snippet}
+
 <style lang="postcss">
 	@reference "./styles/reference.css";
 

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,11 +41,24 @@
 		 * 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 = {
+		/** Label for the button */
 		label?: string;
+		/** Additional classes to apply to the button */
 		class?: ClassValue;
+		/** Callback when the button is pressed */
 		action?: (dialog: DialogAPI) => void;
 	};
 
@@ -51,25 +66,39 @@
 	 * Configures the default dialog controls.
 	 */
 	export type DialogControls = {
+		/** Options for the bottom cancel button */
 		cancel?: DialogControlButton | null;
+		/** Options for the bottom submit button */
 		ok?: DialogControlButton | null;
-		close?: Omit<DialogControlButton, 'label'> | null;
+		/** Inverts the order of the buttons */
+		flip?: boolean;
+	};
+
+	/**
+	 * Stores internal state of the dialog, everything necessary to render
+	 * internal and override capable snippets.
+	 */
+	export type DialogState = {
+		frozen: boolean;
+		loading: boolean;
+		disabled: boolean;
+		api: DialogAPI;
 	};
 
 	const defaultDialogControls: DialogControls = {
-		cancel: {
+		cancel: { label: 'Cancel' },
-			label: 'Cancel'
+		ok: { label: 'OK' }
-		},
-		ok: {
-			label: 'OK'
-		},
-		close: {}
 	};
+
+	export { dialogCancelButton, dialogOkButton, dialogCloseButton };
+
+	/** stack of currently open dialogs by identifier */
+	let dialogStack: DialogAPI[] = $state([]);
 </script>
 
 <script lang="ts">
 	import { Portal } from '@jsrob/svelte-portal';
-	import { type Snippet } from 'svelte';
+	import { untrack, type Snippet } from 'svelte';
 	import type { ClassValue } from 'svelte/elements';
 	import { fade } from 'svelte/transition';
 	import { flyAndScale } from './transition';
@@ -77,20 +106,46 @@
 	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: string;
+		/** Title of the dialog */
-		description?: string;
+		title: string | Snippet<[state: DialogState]>;
+		/** Description of the dialog, optionally rendered below the title */
+		description?: string | Snippet<[state: DialogState]>;
+		/** Size of the dialog (default: 'sm') */
 		size?: 'sm' | 'md' | 'lg' | 'max';
+		/** Additional classes for the dialog */
 		class?: ClassValue;
+		/** Content of the dialog */
 		children?: Snippet;
-		controls?: Snippet | DialogControls;
+		/** Bottom controls for the dialog */
+		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;
+		/**
+		 * 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
+		 * @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 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;
 	}
 
@@ -102,35 +157,76 @@
 		class: classValue,
 		children,
 		controls: rawControls = defaultDialogControls,
+		controlsAlign = 'end',
+		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) => {
+		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
+			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);
+			});
 		}
 	});
 
-	const dialogAPI: DialogAPI = {
+	/** 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,
@@ -144,7 +240,20 @@
 		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: reallyFrozen,
+			loading,
+			disabled,
+			api: dialogAPI
+		};
 	};
 </script>
 
@@ -156,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
@@ -190,76 +307,127 @@
 				start: 0.96
 			}}
 		>
-			<h2 class="pointer-events-none mb-2 text-lg font-medium text-black select-none">{title}</h2>
+			<div class="flex items-center justify-between">
+				<!-- Dialog title -->
+				<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()}
+					{:else}
+						{@render dialogCloseButton(getState(), close)}
+					{/if}
+				{/if}
+			</div>
 
 			{#if error}
 				<ErrorBox {error} />
 			{/if}
 
 			{#if description}
-				<p class="mb-3 leading-normal text-zinc-600">
+				<p class="mb-3 leading-normal text-zinc-600" id="{identifier}-description">
-					{description}
+					{@render stringOrSnippet(description)}
 				</p>
 			{/if}
 
 			{#if children}{@render children()}{:else}Dialog is empty{/if}
 
 			<!-- Dialog Controls -->
-			<div class="mt-6 flex justify-end gap-4">
+			<div
-				{#if controls && typeof controls === 'function'}{@render controls()}{:else}
+				class={[
+					'mt-6 flex gap-4',
+					controlsAlign === 'start' && 'justify-start',
+					controlsAlign === 'center' && 'justify-center',
+					controlsAlign === 'end' && 'justify-end'
+				]}
+			>
+				{#if controls && typeof controls === 'function'}{@render controls(
+						getState()
+					)}{:else if controls?.flip}
+					{#if controls.ok !== null}
+						{@render dialogOkButton(getState(), controls.ok)}
+					{/if}
 					{#if controls.cancel !== null}
-						<Button
+						{@render dialogCancelButton(getState(), controls.cancel)}
-							class={controls?.cancel?.class}
+					{/if}
-							onclick={() => {
+				{:else}
-								if (controls?.cancel?.action) {
+					{#if controls.cancel !== null}
-									controls.cancel.action(dialogAPI);
+						{@render dialogCancelButton(getState(), controls.cancel)}
-								} else if (!frozen) {
-									open = false;
-								}
-							}}
-							disabled={frozen}
-						>
-							{controls?.cancel?.label || 'Cancel'}
-						</Button>
 					{/if}
 					{#if controls.ok !== null}
-						<Button
+						{@render dialogOkButton(getState(), controls.ok)}
-							class={controls?.ok?.class}
-							onclick={() => {
-								if (controls?.ok?.action) {
-									controls.ok.action(dialogAPI);
-								} else if (!frozen && !loading && !disabled) {
-									open = false;
-								}
-							}}
-							disabled={frozen || loading || disabled}
-							{loading}
-						>
-							{controls?.ok?.label || 'OK'}
-						</Button>
 					{/if}
 				{/if}
 			</div>
-
-			<!-- Close Button -->
-			{#if typeof controls === 'function' || controls?.close !== null}
-				<button
-					type="button"
-					aria-label="close"
-					class="absolute top-4 right-4 inline-flex cursor-pointer items-center
-				justify-center disabled:cursor-not-allowed disabled:opacity-50"
-					onclick={() => {
-						if (typeof controls !== 'function' && controls?.close?.action) {
-							controls?.close?.action?.(dialogAPI);
-						} else if (!frozen) {
-							open = false;
-						}
-					}}
-					disabled={frozen}
-				>
-					<X size="1.5em" weight="bold" />
-				</button>
-			{/if}
 		</div>
 	</div>
 {/snippet}
+
+{#snippet dialogCancelButton(state: DialogState, opts?: DialogControls['cancel'])}
+	<Button
+		class={opts?.class}
+		onclick={() => {
+			if (opts?.action) {
+				opts.action(state.api);
+			} else if (!state.frozen) {
+				state.api.close();
+			}
+		}}
+		disabled={state.frozen || state.disabled}
+	>
+		{opts?.label || 'Cancel'}
+	</Button>
+{/snippet}
+
+{#snippet dialogOkButton(state: DialogState, opts?: DialogControls['ok'])}
+	<Button
+		class={opts?.class}
+		onclick={() => {
+			if (opts?.action) {
+				opts.action(state.api);
+			} else if (!state.frozen && !state.loading && !state.disabled) {
+				state.api.close();
+			}
+		}}
+		disabled={state.frozen || state.loading || state.disabled}
+		loading={state.loading}
+	>
+		{opts?.label || 'OK'}
+	</Button>
+{/snippet}
+
+{#snippet dialogCloseButton(state: DialogState, opts?: Omit<DialogControlButton, 'label'> | null)}
+	<button
+		type="button"
+		aria-label="close"
+		class={[
+			'inline-flex cursor-pointer items-center justify-center',
+			'disabled:cursor-not-allowed disabled:opacity-50',
+			'rounded-full p-2 transition-colors hover:bg-zinc-200/50'
+		]}
+		onclick={() => {
+			if (opts?.action) {
+				opts.action(state.api);
+			} else if (!state.frozen) {
+				state.api.close();
+			}
+		}}
+		disabled={state.frozen}
+	>
+		<X size="1.25em" weight="bold" />
+	</button>
+{/snippet}
+
+{#snippet stringOrSnippet(val: string | Snippet<[state: DialogState]>)}
+	{#if typeof val === 'string'}
+		{val}
+	{:else}
+		{@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?: boolean;
+		/** 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 = false,
+		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 && 'px-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/TimezoneInput.svelte

@@ -120,7 +120,7 @@
 	{required}
 	bind:value={timezone}
 	{options}
-	matchWidth
+	pickerWidth="match"
 	placeholder="Select a timezone"
 	class={classValue}
 />

src/lib/floating.svelte.ts

@@ -0,0 +1,144 @@
+/**
+ * implements a popover using floating-ui for positioning and auto-update
+ * see https://www.skeleton.dev/docs/svelte/guides/cookbook/floating-ui-attachments
+ * for more details, examples, and original source.
+ */
+
+import { computePosition, autoUpdate, flip, offset, type Placement } from '@floating-ui/dom';
+import { createAttachmentKey } from 'svelte/attachments';
+
+/**
+ * Options for configuring the Popover behavior and appearance.
+ */
+export interface PopoverOptions {
+	/** Interaction type for the popover */
+	interaction?: 'click' | 'hover' | 'manual';
+	/** Placement of the popover */
+	placement?: Placement;
+	/** Offset distance between the reference and floating elements (default: 8) */
+	offset?: number;
+	/** Callback when the popover is opened or closed */
+	ontoggle?: (open: boolean) => void;
+}
+
+/**
+ * Popover class that manages the state and behavior of a popover element.
+ * It uses floating-ui for positioning and auto-update functionality.
+ */
+export class Popover {
+	private options: PopoverOptions = {
+		interaction: 'click',
+		placement: 'bottom-start',
+		offset: 8
+	};
+	private referenceElement: HTMLElement | undefined = $state();
+	private floatingElement: HTMLElement | undefined = $state();
+	private open = $state(false);
+
+	/**
+	 * Creates a new Popover instance with optional configuration options.
+	 * @param options - Optional configuration for the popover behavior and appearance.
+	 */
+	constructor(options?: PopoverOptions) {
+		if (options) this.options = { ...this.options, ...options };
+		$effect(() => {
+			if (!this.referenceElement || !this.floatingElement) return;
+			return autoUpdate(this.referenceElement, this.floatingElement, this.#updatePosition);
+		});
+	}
+
+	/**
+	 * Generates attributes for the reference element that triggers the popover.
+	 * Includes event handlers based on the specified interaction type (click or hover).
+	 * @returns An object containing necessary attributes and event handlers for
+	 * the reference element.
+	 */
+	reference() {
+		const attrs = {
+			[createAttachmentKey()]: (node: HTMLElement) => {
+				this.referenceElement = node;
+				return () => {
+					this.referenceElement = undefined;
+				};
+			},
+			onclick: () => {},
+			onmouseover: () => {},
+			onmouseout: () => {}
+		};
+		// If click interaction
+		if (this.options.interaction === 'click') {
+			attrs['onclick'] = () => {
+				console.log('reference clicked, toggling popover');
+				this.setOpen(!this.open);
+			};
+		}
+		// If hover interaction
+		if (this.options.interaction === 'hover') {
+			attrs['onclick'] = () => {
+				this.setOpen(!this.open);
+			};
+			attrs['onmouseover'] = () => {
+				this.setOpen(true);
+			};
+			attrs['onmouseout'] = () => {
+				this.setOpen(false);
+			};
+		}
+		return attrs;
+	}
+
+	/** Returns whether the popover is open */
+	isOpen() {
+		return this.open;
+	}
+	/** Sets whether the popover is open, and triggers callbacks */
+	setOpen(open: boolean) {
+		if (this.open !== open) {
+			this.open = open;
+			this.options.ontoggle?.(open);
+		}
+	}
+
+	/**
+	 * Generates attributes for the floating element (popover content) that is positioned
+	 * relative to the reference element. It includes an attachment key to link the
+	 * floating element to the popover instance.
+	 * @returns An object containing necessary attributes for the floating element.
+	 */
+	floating() {
+		return {
+			[createAttachmentKey()]: (node: HTMLElement) => {
+				this.floatingElement = node;
+				node.style.position = 'absolute';
+				node.style.top = '0';
+				node.style.left = '0';
+				return () => {
+					this.floatingElement = undefined;
+					node.style.position = '';
+					node.style.top = '';
+					node.style.left = '';
+				};
+			}
+		};
+	}
+
+	/**
+	 * Updates the position of the floating element based on the reference element using
+	 * the computePosition function from floating-ui. It applies the calculated
+	 * position to the floating element's style.
+	 */
+	#updatePosition = async () => {
+		if (!this.referenceElement || !this.floatingElement) {
+			return;
+		}
+		const position = await computePosition(this.referenceElement, this.floatingElement, {
+			placement: this.options.placement,
+			middleware: [flip(), offset(this.options.offset)]
+		});
+		const { x, y } = position;
+		Object.assign(this.floatingElement.style, {
+			left: `${x}px`,
+			top: `${y}px`
+		});
+	};
+}

src/lib/index.ts

@@ -6,7 +6,15 @@ export { default as CenterBox } from './CenterBox.svelte';
 export { default as Checkbox, type CheckboxState } from './Checkbox.svelte';
 export { default as Combobox, type ComboboxOption } from './Combobox.svelte';
 export { default as DateInput } from './DateInput.svelte';
-export { default as Dialog, type DialogAPI, type DialogControls } from './Dialog.svelte';
+export {
+	default as Dialog,
+	type DialogAPI,
+	type DialogControls,
+	type DialogState,
+	dialogCancelButton,
+	dialogCloseButton,
+	dialogOkButton
+} from './Dialog.svelte';
 export {
 	default as DurationInput,
 	formatDuration,
@@ -14,6 +22,7 @@ export {
 	iso8601ToDuration
 } from './DurationInput.svelte';
 export { default as ErrorBox } from './ErrorBox.svelte';
+export { type PopoverOptions, Popover } from './floating.svelte';
 export { default as FramelessButton } from './FramelessButton.svelte';
 export { default as InjectGoogleMaps } from './InjectGoogleMaps.svelte';
 export { default as InjectUmami } from './InjectUmami.svelte';

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',
@@ -172,10 +172,27 @@
 			name="example-combobox"
 			label="Select an option"
 			placeholder="Choose..."
-			options={comboboxOptions}
+			options={[
+				{
+					value: 'option1',
+					label: 'Option 1',
+					preview: 'Prvw',
+					infotext: 'Info'
+				},
+				{ value: 'option2', label: 'Option 2' },
+				{ value: 'option3', label: 'Option 3', disabled: true }
+			]}
 			onchange={(e) => console.log('Selected:', e.value)}
 			onvalidate={(e) => console.log('Validation:', e.detail)}
-		/>
+			pickerWidth="longest"
+		>
+			{#snippet labelRender(opt: ComboboxOption)}
+				Processed {opt.label}
+			{/snippet}
+			{#snippet infotextRender(opt: ComboboxOption)}
+				Processed {opt.infotext}
+			{/snippet}
+		</Combobox>
 
 		<Combobox
 			loading
@@ -201,15 +218,17 @@
 			label="Lazy combobox"
 			placeholder="Choose..."
 			options={lazyOptions}
-			lazy
+			lazy="always"
-			onlazy={() => {
+			onlazy={async () => {
-				setTimeout(() => {
+				await new Promise((resolve) => setTimeout(resolve, 2500));
-					lazyOptions = [
+				lazyOptions = [
-						{ value: 'option1', label: 'Option 1' },
+					{ value: 'option1', label: 'Option 1' },
-						{ value: 'option2', label: 'Option 2' },
+					{ value: 'option2', label: 'Option 2' },
-						{ value: 'option3', label: 'Option 3' }
+					{ value: 'option3', label: 'Option 3' }
-					];
+				];
-				}, 2500);
+			}}
+			onopenchange={(open) => {
+				if (!open) lazyOptions = [];
 			}}
 		/>
 		<Combobox
@@ -518,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();
@@ -535,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 -->