svelte-fluentui 1.0.0-rc15 → 1.0.0-rc17

package/README.md

@@ -2,15 +2,43 @@
 
 A comprehensive Svelte wrapper library for Microsoft FluentUI web components (v2.6.x), providing a seamless way to use FluentUI components in Svelte applications.
 
-## What's New in v1.0.0-rc15
-
-- **`QuickGrid` tree mode** — pass `treePathMember="path"` and mark one column with `isTree: true` to render hierarchical data with indentation + expand/collapse. Supports PostgreSQL ltree (`"1.2.3"`), POSIX (`"/1/2/3"`), and Windows (`"C:\foo\bar"`) path styles with auto-detection. Optional `treeLevelMember` / `treeParentMember` skip path parsing when those values are pre-computed in the database. `treeDataSorted` skips internal sort. `expandedPaths` is `$bindable`. `defaultExpandDepth` is interpreted relative to the dataset's shallowest level so subtree views always show their roots. Filter is ancestor-aware. Optional `treeDoubleClickBehavior="toggle"` lets users smash the row instead of aiming at the chevron
-- **`QuickGrid` per-column `filter` callback** — `(filterValue: string, row: T) => boolean | null` replaces the built-in substring match for one column. Use for numeric ranges, date ranges, regex, multi-field search. Returning `null` signals "input is syntactically incomplete" — the grid then ignores the filter (all rows pass) AND adds a `.invalid` class to the input so the user gets a red border instead of an empty grid
-- **`QuickGrid` grid-level `onfilterchange`** — `(filters: Record<string, string>) => void` for server-side filtering. When set, internal filtering is fully bypassed; the grid still renders the inputs, fires this on every keystroke, and trusts the caller to update `items`
-- **`QuickGrid` `idMember` prop** — stable row identity. Drafts and invalid-cell markers now key by this value (or `treePathMember` in tree mode, or displayed-row index as a last-resort fallback that triggers a one-shot console warning) so they survive pagination, filter, sort, and tree expand/collapse re-orderings
-- **`QuickGrid` `columnMinWidth` prop** — default `min-width` for any column without its own. Stops content-sized columns from collapsing too far when paired with `fillerColumn`
-- **`QuickGrid` `fillerColumn` actually absorbs leftover space now** — was `width: auto` (a no-op for absorption), now `width: 100%`. Affects every demo using `fillerColumn`, not just tree
-- **BREAKING — `QuickGrid` `invalidCells` shape: `rowIndex` → `rowKey`** — bindable `invalidCells: CellValidationState[]` now carries `rowKey: string` instead of `rowIndex: number`, matching the new stable-id keying. Migration: callers binding `invalidCells` need to read `c.rowKey` instead of `c.rowIndex`. The `onvalidationerror` callback's `detail.rowIndex` is unchanged
+## What's New in v1.0.0-rc17
+
+- **`Field` component** — wraps any form control with label + hint + validation message + state border. `validationState: "none" | "warning" | "error" | "success"` drives both the message color and the bottom-border accent on the inner control via shadow parts. `hint` renders neutral helper text when there's no error to show. Matches FluentUI 2 / Blazor convention of factoring validation presentation out of individual controls
+- **`ValidationSummary` component** — top-of-form panel listing all errors with clickable jump-to-field links. Takes a plain `errors: Record<string, string>` map, auto-hides when empty, renders as `role="alert"` for screen readers. Pairs with `<Field>` for submit-time validation flows
+- **Field &amp; ValidationSummary demo page** at `/components/forms/field` covers all states, control types, live validation with touched-on-blur, horizontal orientation, and the submit-time summary pattern
+- **Refactored `/applications/form-validation`** to use the new components — ~80 lines of inline `<small class="field-error">` and hand-rolled summary panel removed; reads as a tutorial now
+- **`QuickGrid` `Ctrl`+`→` / `Ctrl`+`←` tree expand-collapse in navigate mode** — keyboard-only tree traversal. `Ctrl`+`→` expands the focused row; `Ctrl`+`←` collapses it (or walks up to the nearest expanded ancestor and collapses that). Modifier-key shape avoids ambiguity with plain ArrowLeft/Right which navigate columns
+- **`QuickGrid` navigate mode: all cells are now focusable, not only editable ones** — previously only editable cells got `tabindex=0`, so users couldn't land on read-only cells (like the tree column or parent rows in heterogeneous trees) and couldn't trigger `Ctrl`+arrow on them. Now every cell is focusable; Tab still walks through editable cells only (the productive Tab-through-fields UX). Focus indicator extended to all focused cells
+- **`QuickGrid` Tab-while-editing now works in `dblclick` / `click` / `button` modes** — only `navigate` mode had a Tab handler before; the others fell through to browser default and focus disappeared. Tab now commits + auto-opens the editor on the next editable cell (spreadsheet pattern)
+- **`QuickGrid` mode-switcher on the editable-per-row-type demo** — `/components/quickgrid-tree` example gained a radio control to flip between `navigate`, `dblclick`, `click`, and `button` so you can verify keyboard behaviors across all modes
+- **`QuickGrid` predefined context-menu types for tree expand / collapse** — `contextMenu={["expand-all", "collapse-all", "expand-tree", "collapse-tree"]}` wires common tree commands without writing handlers. `expand-all` / `collapse-all` operate on the right-clicked row's branch (file-explorer / IDE convention); `expand-tree` / `collapse-tree` operate on the entire dataset. Visibility gates auto-hide useless options (leaf rows don't show subtree commands, etc.). `ContextMenuItem.label` is now optional since predefined `type` supplies a default
+- **Bug fix — Tab traversal correctly skips rows with zero editable columns** — the row-aware Tab promise in rc16 had a hole in heterogeneous trees where a row has *no* editable columns. New `findNextEditableCell` helper walks past such rows in both directions
+- **Bug fix — Toast styles now actually ship in the bundle** — the `_toast.scss` partial existed and was complete (`.fluent-toast-container`, position variants, animations) but `main.scss` never `@use`d it, so every consumer got the toast DOM with zero styling: an unstyled box at top-left of the viewport instead of the styled popover at top-right. Affects every page using the toast service. Fixed by adding `@use "assets/styles/components/toast";` to `main.scss`
+- **Form Validation demo page** — new `/applications/form-validation` walks through the common patterns: required &amp; format, cross-field (passwords match), numeric range with custom rules, debounced async availability check, conditional required, and submit-time error summary with jump-to-field links. Includes a tiny composable validator helper recipe for copy-paste
+
+## What's New in v1.0.0-rc16
+
+### QuickGrid
+- **Per-row-type editability** — `column.isEditable` (renamed from `column.editable`) now accepts a `(row) => boolean` callback so heterogeneous trees can express "only some row types are editable" without the consumer hand-rolling click handlers. Two shapes: per-column (`isEditable: (row) => row.kind === "employee"` — different columns can be editable for different row types) and grid-level (`isRowEditable: (row) => boolean` — single predicate gating the whole row). Three-stage gate: master `editable` → `isRowEditable` → `column.isEditable`. Navigate-mode Tab traversal is row-aware so the cursor skips read-only cells correctly. New demo at `/components/quickgrid-tree` ("Editable per row type — teams vs employees")
+- **`column.nowrap` prop** — body cells never wrap. Combine with `maxWidth` for ellipsis truncation, with `autoWidth` to size the column to `max(header, longest cell)`, or use alone for short identifiers like SKU/code columns. Demo on `/components/quickgrid` shows all three modes
+- **BREAKING — `column.editable` renamed to `column.isEditable`** — boolean form is unchanged; the function form is additive. Migration: rename `editable: true` → `isEditable: true` on every column literal. Grid-level `editable` prop is unchanged
+- **Component-prefixed CSS variables** — `--fluent-quickgrid-header-bg`, `-header-hover-bg`, `-header-sorted-bg`, `-stripe-bg`, `-row-hover-bg` decouple QuickGrid surfaces from the generic `--neutral-layer-*` palette. Themes that overrode `--neutral-layer-2` for navbar branding (e.g. DHL yellow) used to drag QuickGrid header + striped rows along at full saturation; consumers can now tint the grid independently
+- **Sort indicator tracks accent** — the `▲` / `▼` triangle on the actively sorted column uses `var(--accent-fill-rest)` so theme switches propagate to it
+- **Bug fix: body cells inherit width constraints** — `width` / `minWidth` / `maxWidth` / `columnMinWidth` were applied only to `<th>`, so a wide body cell could drag the column past the header's `max-width`. Now mirrored to `<td>` via `getColumnBodyStyle()`. Fixes the case where ellipsis wouldn't activate on `nowrap` columns
+
+### Autocomplete
+- **`startIcon` and `endIcon` snippets** — decorative slots inside the input. `startIcon` renders before, `endIcon` renders after but yields to the auto-rendered clear button / loading spinner so a search icon swaps cleanly to a clear button on selection. New demo on `/components/autocomplete`
+- **Chip-size CSS variables** — eight `--fluent-autocomplete-chip-*` tokens (font-size, line-height, padding, gap, max-width, etc.) drive both inline and external chip geometry, defaults in rem. Override globally via `:root { --fluent-autocomplete-chip-font-size: 0.75rem; }`
+- **Inline chip size unified with external** — was 12px font inline / 14px font external; picking a value visually shrunk the chip. Now both use the same `--fluent-autocomplete-chip-font-size` token (default `0.875rem`)
+- **Focus border follows FluentUI 2** — was painting all four sides accent + outer glow; now only the bottom edge turns accent (the standard FluentUI textfield convention). Matches the Blazor reference and avoids layout shift on focus
+- **Bug fix: single-select replaces instead of appends** — `selectOption` was always appending, which silently wedged single-select mode after the second click (input went blank with two values held in state)
+- **Bug fix: dropdown closes on outside scroll** — `PositioningRegion` doesn't re-anchor on scroll, so scrolling the page used to leave the popover floating detached from its anchor. Now a capture-phase scroll listener closes it when scrolling outside the input or popover surface
+
+### Tabs / Site settings
+- **`Tabs` active tab text tracks accent** — `.fluent-tab.active` color changed to `var(--accent-fill-rest)` so the active label matches its bottom indicator instead of staying neutral gray
+- **Site settings store applies to the document** — pushes every change to `document.documentElement` (`data-theme`, `dir`, `--accent-fill-*`, `--foreground-on-accent-*`, `--neutral-layer-1`, mirrored `--fluent-*` tokens). Theme mode `'system'` resolves via `matchMedia` and re-applies on OS-level theme changes. Foreground-on-accent is computed via W3C luminance so dark accents get white labels and light accents (PowerBI yellow) get black labels
+- **`theme` store localStorage key namespaced** — `"theme"` → `"fluent-theme"` to prevent collisions with host applications using the same generic key (e.g. PureAdmin saves its theme name to `localStorage.theme`)
 
 ## Features
 

package/dist/assets/styles/_variables.scss

@@ -50,6 +50,13 @@ $footer-bg-light: $neutral-white !default;
 $footer-text-light: $neutral-gray-110 !default;
 $footer-border-light: $neutral-gray-40 !default;
 
+// QuickGrid
+$quickgrid-header-bg-light: $neutral-gray-20 !default;
+$quickgrid-header-hover-bg-light: $neutral-gray-30 !default;
+$quickgrid-header-sorted-bg-light: $neutral-gray-30 !default;
+$quickgrid-stripe-bg-light: $neutral-gray-10 !default;
+$quickgrid-row-hover-bg-light: $neutral-gray-30 !default;
+
 // ===== DARK THEME DEFAULTS =====
 
 // Background colors
@@ -94,6 +101,13 @@ $footer-bg-dark: $neutral-gray-150 !default;
 $footer-text-dark: $neutral-gray-20 !default;
 $footer-border-dark: $neutral-gray-100 !default;
 
+// QuickGrid
+$quickgrid-header-bg-dark: $neutral-gray-120 !default;
+$quickgrid-header-hover-bg-dark: $neutral-gray-110 !default;
+$quickgrid-header-sorted-bg-dark: $neutral-gray-110 !default;
+$quickgrid-stripe-bg-dark: $neutral-gray-130 !default;
+$quickgrid-row-hover-bg-dark: $neutral-gray-110 !default;
+
 // ===== COMPONENT-SPECIFIC VARIABLES =====
 
 // Spacing

package/dist/assets/styles/components/_field.scss

@@ -0,0 +1,102 @@
+/* ========================================
+   Field — label + control + hint + validation message
+   FluentUI 2 / Blazor convention: Field owns label, hint, and inline validation
+   message rendering. Inner control (TextField, NumberField, etc.) sits in the slot.
+   ======================================== */
+
+.fluent-field {
+	display: flex;
+	flex-direction: column;
+	gap: 0.25rem;
+
+	// State color: per-data-state, fall back to error color so unrecognized
+	// states don't render unstyled. Components below read this var.
+	--fluent-field-state-color: transparent;
+
+	&--horizontal {
+		flex-direction: row;
+		flex-wrap: wrap;
+		align-items: flex-start;
+		gap: 0.5rem 1rem;
+
+		.fluent-field__label {
+			flex: 0 0 auto;
+			padding-top: 0.35rem; // align with input baseline-ish
+			margin-bottom: 0;
+		}
+		.fluent-field__control {
+			flex: 1 1 auto;
+			min-width: 0;
+		}
+		.fluent-field__hint,
+		.fluent-field__message {
+			flex-basis: 100%;
+		}
+	}
+
+	&__label {
+		display: block;
+		font-size: 0.875rem;
+		font-weight: 600;
+		line-height: 1.25;
+		color: var(--neutral-foreground-rest, #424242);
+		margin-bottom: 0;
+	}
+
+	&__required {
+		color: #c50f1f;
+		margin-left: 0.15rem;
+		font-weight: 700;
+	}
+
+	&__control {
+		display: flex;
+		flex-direction: column;
+		gap: 0.2rem;
+		min-width: 0;
+	}
+
+	&__hint {
+		display: block;
+		color: var(--neutral-foreground-hint, #707070);
+		font-size: 0.8rem;
+		line-height: 1.35;
+	}
+
+	&__message {
+		display: block;
+		font-size: 0.8rem;
+		line-height: 1.35;
+		color: var(--fluent-field-state-color);
+	}
+
+	// ===== States =====
+
+	&[data-state="error"] {
+		--fluent-field-state-color: #c50f1f;
+	}
+	&[data-state="warning"] {
+		--fluent-field-state-color: #c87018;
+	}
+	&[data-state="success"] {
+		--fluent-field-state-color: #107c10;
+	}
+
+	// Paint the inner Fluent web component's border to match the field state.
+	// The fluent-* web components expose `root` as the visible bordered box.
+	// FluentUI 2 paints only the bottom border on focus, so we mirror that
+	// convention for the validation accent rather than ringing all four sides.
+	&[data-state="error"],
+	&[data-state="warning"],
+	&[data-state="success"] {
+		fluent-text-field::part(root),
+		fluent-number-field::part(root),
+		fluent-search::part(root),
+		fluent-text-area::part(control),
+		fluent-select::part(control),
+		fluent-combobox::part(control) {
+			border-bottom-color: var(--fluent-field-state-color);
+			box-shadow: inset 0 -1px 0 0 var(--fluent-field-state-color);
+		}
+	}
+}

package/dist/assets/styles/components/_validation-summary.scss

@@ -0,0 +1,43 @@
+/* ========================================
+   Validation Summary — inline error panel listing all field errors
+   Pairs with <Field> for forms that defer all validation to submit.
+   ======================================== */
+
+.fluent-validation-summary {
+	background: rgba(197, 15, 31, 0.08);
+	border-left: 3px solid #c50f1f;
+	padding: 0.6rem 0.9rem;
+	border-radius: 4px;
+	color: var(--neutral-foreground-rest, #424242);
+
+	&__title {
+		font-weight: 600;
+		margin-bottom: 0.4rem;
+		color: #c50f1f;
+	}
+
+	&__list {
+		margin: 0;
+		padding-left: 1.1rem;
+		list-style: disc;
+	}
+
+	&__item {
+		margin: 0.15rem 0;
+		line-height: 1.4;
+	}
+
+	&__link {
+		color: #c50f1f;
+		text-decoration: underline;
+		cursor: pointer;
+	}
+	&__link:hover {
+		text-decoration: none;
+	}
+	&__link:focus-visible {
+		outline: 2px solid var(--accent-fill-rest, #0078d4);
+		outline-offset: 2px;
+		border-radius: 2px;
+	}
+}

package/dist/assets/styles/theme.scss

@@ -52,6 +52,13 @@
 	--fluent-footer-text: #{$footer-text-light};
 	--fluent-footer-border: #{$footer-border-light};
 
+	// QuickGrid
+	--fluent-quickgrid-header-bg: #{$quickgrid-header-bg-light};
+	--fluent-quickgrid-header-hover-bg: #{$quickgrid-header-hover-bg-light};
+	--fluent-quickgrid-header-sorted-bg: #{$quickgrid-header-sorted-bg-light};
+	--fluent-quickgrid-stripe-bg: #{$quickgrid-stripe-bg-light};
+	--fluent-quickgrid-row-hover-bg: #{$quickgrid-row-hover-bg-light};
+
 	// Component spacing
 	--fluent-component-padding: #{$component-padding};
 	--fluent-component-margin: #{$component-margin};
@@ -132,6 +139,13 @@
 	--fluent-footer-bg: #{$footer-bg-dark};
 	--fluent-footer-text: #{$footer-text-dark};
 	--fluent-footer-border: #{$footer-border-dark};
+
+	// QuickGrid
+	--fluent-quickgrid-header-bg: #{$quickgrid-header-bg-dark};
+	--fluent-quickgrid-header-hover-bg: #{$quickgrid-header-hover-bg-dark};
+	--fluent-quickgrid-header-sorted-bg: #{$quickgrid-header-sorted-bg-dark};
+	--fluent-quickgrid-stripe-bg: #{$quickgrid-stripe-bg-dark};
+	--fluent-quickgrid-row-hover-bg: #{$quickgrid-row-hover-bg-dark};
 }
 
 [data-theme="dhl"] {

package/dist/components/AccordionItem.svelte

@@ -41,7 +41,7 @@
 		// console.log("Accordion item change", ev)
 		const target = ev.target as HTMLElement
 
-		onchange?.(ev, target.attributes["expanded"]?.value === "")
+		onchange?.(ev, target.getAttribute("expanded") === "")
 	}
 </script>
 

package/dist/components/Anchor.svelte

@@ -64,7 +64,8 @@
 	}
 </script>
 
-<!-- svelte-ignore a11y_no_static_element_interactions a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<!-- svelte-ignore a11y_click_events_have_key_events -->
 <fluent-anchor
 	bind:this={element}
 	{id}

package/dist/components/Autocomplete.svelte

@@ -49,6 +49,12 @@
 		headerContent?: Snippet
 		footerContent?: Snippet
 		optionTemplate?: Snippet<[OptionItem<T>]>
+		// Decorative slots inside the input. Render arbitrary content (typically icons or
+		// small buttons) at the start (left) or end (right) of the input. The auto-rendered
+		// clear button and loading spinner take precedence in the end slot — `endIcon`
+		// renders only when neither is active, so a search icon doesn't fight a clear button.
+		startIcon?: Snippet
+		endIcon?: Snippet
 		class?: string
 		style?: string
 		initialSearchQuery?: string
@@ -89,6 +95,8 @@
 		headerContent = undefined,
 		footerContent = undefined,
 		optionTemplate = undefined,
+		startIcon = undefined,
+		endIcon = undefined,
 		class: className = "",
 		style = "",
 		initialSearchQuery = "",
@@ -204,16 +212,20 @@
 	function selectOption(option: OptionItem) {
 		if (disabled || readonly || option.disabled) return
 
-		if (maxSelectedOptions && selectedOptions.length >= maxSelectedOptions) {
+		if (effectiveMultiple && maxSelectedOptions && selectedOptions.length >= maxSelectedOptions) {
 			return
 		}
 
-		selectedOptions = [...selectedOptions, option.value]
+		// Single-select replaces the previous value; multi-select appends.
+		selectedOptions = effectiveMultiple
+			? [...selectedOptions, option.value]
+			: [option.value]
 		searchText = ""
 		filteredOptions = []
 		highlightedIndex = -1
 
-		if (!keepOpen || (maxSelectedOptions && selectedOptions.length >= maxSelectedOptions)) {
+		// Always close after a single-select pick; multi-select honors keepOpen / max-cap.
+		if (!effectiveMultiple || !keepOpen || (maxSelectedOptions && selectedOptions.length >= maxSelectedOptions)) {
 			closeDropdown()
 		}
 
@@ -344,12 +356,31 @@
 		}
 	}
 
-	// Add click outside listener
+	// Close dropdown on outside scroll. The options list itself is scrollable
+	// (max-height + overflow-y: auto) and is portaled out via PositioningRegion,
+	// so scrolling inside the listbox must not trigger this. Scrolling anywhere
+	// else on the page would otherwise leave the dropdown floating at its old
+	// anchor position, since PositioningRegion does not re-anchor on scroll.
+	function handleOutsideScroll(event: Event) {
+		const target = event.target as Node | null
+		if (!target) return
+		// Allow scroll inside our own anchor container (input + inline chips, etc.)
+		if (containerElement && containerElement.contains(target)) return
+		// Allow scroll inside the popover surface (options-list lives in a portal).
+		if (target instanceof Element && target.closest('.options-list, .positioning-region')) return
+		closeDropdown()
+	}
+
+	// Add click-outside and outside-scroll listeners
 	$effect(() => {
 		if (isOpen) {
 			document.addEventListener("click", handleClickOutside)
+			// `capture: true` because most page scroll containers don't bubble
+			// scroll events to document; capture phase reliably catches them.
+			window.addEventListener("scroll", handleOutsideScroll, true)
 			return () => {
 				document.removeEventListener("click", handleClickOutside)
+				window.removeEventListener("scroll", handleOutsideScroll, true)
 			}
 		}
 	})
@@ -446,7 +477,10 @@
 		{/if}
 
 		<!-- Input container -->
-		<!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+		<!-- svelte-ignore a11y_click_events_have_key_events -->
+		<!-- svelte-ignore a11y_no_static_element_interactions -->
+		<!-- svelte-ignore a11y_role_has_required_aria_props -->
+		<!-- svelte-ignore a11y_interactive_supports_focus -->
 		<div
 			class="autocomplete-input-container"
 			class:inline-mode={tagsPosition === 'inline'}
@@ -460,6 +494,13 @@
 			aria-expanded={isOpen}
 			aria-haspopup="listbox"
 		>
+			<!-- Start icon slot (e.g. search magnifying glass) -->
+			{#if startIcon}
+				<div class="input-start">
+					{@render startIcon()}
+				</div>
+			{/if}
+
 			<!-- Tags INLINE (if tagsPosition === 'inline') -->
 			{#if tagsPosition === 'inline' && showTags}
 				{#each selectedOptions as value}
@@ -483,6 +524,7 @@
 			{/if}
 
 			<!-- Native input element -->
+			<!-- svelte-ignore a11y_autofocus -->
 			<input
 				type="text"
 				class="autocomplete-native-input"
@@ -493,36 +535,42 @@
 				readonly={readonly}
 				{required}
 				autofocus={autofocus}
-				autocomplete={autocomplete || 'off'}
+				autocomplete={(autocomplete || 'off') as AutoFill}
 				oninput={handleInput}
 				onkeydown={handleKeyDown}
 				onfocus={handleInputFocus}
 				onblur={handleInputBlur}
 			/>
 
-			<!-- End slot: clear button or loading indicator -->
-			<div class="input-end">
-				{#if hasSingleSelection && !disabled && !readonly}
-					<button
-						type="button"
-						class="clear-button"
-						onclick={clearSingleSelection}
-						aria-label="Clear selection"
-						title="Clear selection"
-					>
-						<svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
-							<path d="M2.09 2.22a.75.75 0 0 1 1.06-.13L6 4.94l2.85-2.85a.75.75 0 1 1 1.06 1.06L7.06 6l2.85 2.85a.75.75 0 1 1-1.06 1.06L6 7.06l-2.85 2.85a.75.75 0 0 1-1.06-1.06L4.94 6 2.09 3.15a.75.75 0 0 1-.13-1.06z"/>
-						</svg>
-					</button>
-				{:else if showLoading}
-					<div class="loading-indicator">
-						<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" class="spinner">
-							<circle cx="8" cy="8" r="7" stroke="currentColor" stroke-width="2" fill="none" opacity="0.25"/>
-							<path d="M8 1a7 7 0 0 1 7 7" stroke="currentColor" stroke-width="2" fill="none"/>
-						</svg>
-					</div>
-				{/if}
-			</div>
+			<!-- End slot: clear button OR loading indicator OR custom endIcon (in that priority).
+				 Only renders when something will show inside, so the `:has(.input-end)` padding
+				 rule on the input doesn't reserve space for an empty slot. -->
+			{#if (hasSingleSelection && !disabled && !readonly) || showLoading || endIcon}
+				<div class="input-end">
+					{#if hasSingleSelection && !disabled && !readonly}
+						<button
+							type="button"
+							class="clear-button"
+							onclick={clearSingleSelection}
+							aria-label="Clear selection"
+							title="Clear selection"
+						>
+							<svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
+								<path d="M2.09 2.22a.75.75 0 0 1 1.06-.13L6 4.94l2.85-2.85a.75.75 0 1 1 1.06 1.06L7.06 6l2.85 2.85a.75.75 0 1 1-1.06 1.06L6 7.06l-2.85 2.85a.75.75 0 0 1-1.06-1.06L4.94 6 2.09 3.15a.75.75 0 0 1-.13-1.06z"/>
+							</svg>
+						</button>
+					{:else if showLoading}
+						<div class="loading-indicator">
+							<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" class="spinner">
+								<circle cx="8" cy="8" r="7" stroke="currentColor" stroke-width="2" fill="none" opacity="0.25"/>
+								<path d="M8 1a7 7 0 0 1 7 7" stroke="currentColor" stroke-width="2" fill="none"/>
+							</svg>
+						</div>
+					{:else if endIcon}
+						{@render endIcon()}
+					{/if}
+				</div>
+			{/if}
 		</div>
 
 		<!-- Tags BELOW (if tagsPosition === 'below') -->
@@ -648,8 +696,12 @@
 	}
 
 	.autocomplete-input-container.inline-mode.focused:not(.disabled) {
-		border-color: var(--accent-fill-rest, #0078d4);
-		box-shadow: 0 0 0 1px var(--accent-fill-rest, #0078d4);
+		/* FluentUI 2 textfield focus: thin gray border on top/sides stays put,
+		   bottom edge becomes accent + visually 2px thick. We use an inset box-shadow
+		   to add the 1px instead of bumping border-bottom-width — that would shift
+		   the input's content by 1px on focus. */
+		border-bottom-color: var(--accent-fill-rest, #0078d4);
+		box-shadow: inset 0 -1px 0 0 var(--accent-fill-rest, #0078d4);
 	}
 
 	.autocomplete-input-container.inline-mode.disabled {
@@ -679,18 +731,26 @@
 		box-shadow: 0 1px 0 0 var(--accent-fill-rest, #0078d4);
 	}
 
-	/* ===== Inline Chips ===== */
+	/* ===== Inline Chips =====
+	   Inline chips share the same height + typography as external chips so picking a value
+	   doesn't visually shrink it on its way into the input. The only intentional difference
+	   is the border: inline chips sit inside the input's own border so adding another would
+	   double up; external chips are standalone elements and need their own.
+
+	   Sizing tokens (`--fluent-autocomplete-chip-*`) drive both inline and external chip
+	   geometry, so theme overrides apply everywhere chips render. Defaults are in rem so
+	   chips scale with the user's root font-size. */
 	.inline-chip {
 		display: inline-flex;
 		align-items: center;
-		gap: 4px;
-		padding: 2px 8px;
+		gap: var(--fluent-autocomplete-chip-gap, 0.25rem);
+		padding: var(--fluent-autocomplete-chip-padding-y, 0.125rem) var(--fluent-autocomplete-chip-padding-x, 0.5rem);
 		background: var(--neutral-fill-secondary-rest, #f0f0f0);
 		border-radius: calc(var(--control-corner-radius, 4) * 1px);
-		font-size: 12px;
-		line-height: 1.4;
+		font-size: var(--fluent-autocomplete-chip-font-size, 0.875rem);
+		line-height: var(--fluent-autocomplete-chip-line-height, 1.4);
 		white-space: nowrap;
-		max-width: 150px;
+		max-width: var(--fluent-autocomplete-chip-max-width, 9.375rem);
 		color: var(--neutral-foreground-rest, #242424);
 	}
 
@@ -705,10 +765,10 @@
 		justify-content: center;
 		background: transparent;
 		border: none;
-		padding: 2px;
+		padding: var(--fluent-autocomplete-chip-remove-padding, 0.125rem);
 		cursor: pointer;
 		color: var(--neutral-foreground-hint, #717171);
-		border-radius: 2px;
+		border-radius: 0.125rem;
 		flex-shrink: 0;
 		transition: color 0.1s ease, background 0.1s ease;
 	}
@@ -765,8 +825,9 @@
 	}
 
 	.autocomplete-input-container:not(.inline-mode) .autocomplete-native-input:focus {
-		border-color: var(--accent-fill-rest, #0078d4);
-		box-shadow: 0 0 0 1px var(--accent-fill-rest, #0078d4);
+		/* See comment on `.inline-mode.focused` — same FluentUI bottom-emphasis pattern. */
+		border-bottom-color: var(--accent-fill-rest, #0078d4);
+		box-shadow: inset 0 -1px 0 0 var(--accent-fill-rest, #0078d4);
 	}
 
 	.autocomplete-input-container:not(.inline-mode).filled .autocomplete-native-input {
@@ -776,12 +837,22 @@
 		border-radius: calc(var(--control-corner-radius, 4) * 1px) calc(var(--control-corner-radius, 4) * 1px) 0 0;
 	}
 
+	/* ===== Input Start Slot ===== */
+	.input-start {
+		flex-shrink: 0;
+		display: flex;
+		align-items: center;
+		padding-right: 4px;
+		color: var(--neutral-foreground-hint, #707070);
+	}
+
 	/* ===== Input End Slot ===== */
 	.input-end {
 		flex-shrink: 0;
 		display: flex;
 		align-items: center;
 		padding-left: 4px;
+		color: var(--neutral-foreground-hint, #707070);
 	}
 
 	/* Non-inline mode: position end slot inside input */
@@ -792,6 +863,22 @@
 		transform: translateY(-50%);
 	}
 
+	.autocomplete-input-container:not(.inline-mode) .input-start {
+		position: absolute;
+		left: 8px;
+		top: 50%;
+		transform: translateY(-50%);
+	}
+
+	/* Non-inline mode: pad the input so its text doesn't sit underneath the icons */
+	.autocomplete-input-container:not(.inline-mode):has(.input-start) .autocomplete-native-input {
+		padding-left: 32px;
+	}
+
+	.autocomplete-input-container:not(.inline-mode):has(.input-end) .autocomplete-native-input {
+		padding-right: 32px;
+	}
+
 	/* ===== Selected Options Container (above/below modes) ===== */
 	.selected-options {
 		display: flex;
@@ -802,17 +889,20 @@
 		overflow-y: auto;
 	}
 
-	/* External chips (above/below modes) - FluentUI Blazor style */
+	/* External chips (above/below modes) - FluentUI Blazor style.
+	   Same `--fluent-autocomplete-chip-*` tokens as inline chips. Adds a 1px border
+	   since these aren't sitting inside the input's own border. */
 	.external-chip {
 		display: inline-flex;
 		align-items: center;
-		gap: 4px;
-		padding: 2px 8px;
+		gap: var(--fluent-autocomplete-chip-gap, 0.25rem);
+		padding: var(--fluent-autocomplete-chip-padding-y, 0.125rem) var(--fluent-autocomplete-chip-padding-x, 0.5rem);
 		background: var(--neutral-fill-secondary-rest, #f5f5f5);
 		color: var(--neutral-foreground-rest, #242424);
 		border: 1px solid var(--neutral-stroke-rest, #d1d1d1);
 		border-radius: calc(var(--control-corner-radius, 4) * 1px);
-		font-size: 14px;
+		font-size: var(--fluent-autocomplete-chip-font-size, 0.875rem);
+		line-height: var(--fluent-autocomplete-chip-line-height, 1.4);
 		font-weight: 400;
 		white-space: nowrap;
 	}
@@ -820,7 +910,7 @@
 	.external-chip .chip-text {
 		overflow: hidden;
 		text-overflow: ellipsis;
-		max-width: 200px;
+		max-width: var(--fluent-autocomplete-chip-text-max-width, 12.5rem);
 	}
 
 	.external-chip .chip-remove {
@@ -829,10 +919,10 @@
 		justify-content: center;
 		background: transparent;
 		border: none;
-		padding: 2px;
+		padding: var(--fluent-autocomplete-chip-remove-padding, 0.125rem);
 		cursor: pointer;
 		color: var(--error-foreground-rest, #c42b1c);
-		border-radius: 2px;
+		border-radius: 0.125rem;
 	}
 
 	.external-chip .chip-remove:hover {

package/dist/components/Autocomplete.svelte.d.ts

@@ -36,6 +36,8 @@ type Props<T = any> = {
     headerContent?: Snippet;
     footerContent?: Snippet;
     optionTemplate?: Snippet<[OptionItem<T>]>;
+    startIcon?: Snippet;
+    endIcon?: Snippet;
     class?: string;
     style?: string;
     initialSearchQuery?: string;

package/dist/components/Badge.svelte

@@ -62,7 +62,8 @@
 	})
 </script>
 
-<!-- svelte-ignore a11y_no_static_element_interactions a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<!-- svelte-ignore a11y_click_events_have_key_events -->
 <span
 	class={classes}
 	style={computedStyle || null}