fluentui-svelte 0.6.0 → 0.7.0

package/dist/components/divider/divider.svelte

@@ -3,12 +3,14 @@
 
 	let {
 		as = 'div' as Tag,
-		ref = $bindable(),
+		ref = $bindable(null),
 		vertical,
 		alignContent = 'center',
 		appearance = 'default',
 		inset,
 		children,
+		class: classes,
+		style,
 		...attributes
 	}: DividerProps<Tag> = $props();
 </script>
@@ -30,12 +32,12 @@
 -->
 <svelte:element
 	this={as}
+	{...attributes}
 	bind:this={ref}
 	role="separator"
-	class={['fs-divider', appearance, `align-${alignContent}`, { inset, vertical }]}
-	style=" --divider-margin: {children ? (vertical ? '0.5rem' : '0.75rem') : '0'}"
+	class={['fs-divider', appearance, `align-${alignContent}`, { inset, vertical }, classes]}
+	style="{style ?? ''};  --divider-margin: {children ? (vertical ? '0.5rem' : '0.75rem') : '0'}"
 	aria-orientation={vertical ? 'vertical' : 'horizontal'}
-	{...attributes}
 >
 	{@render children?.()}
 </svelte:element>

package/dist/components/divider/types.d.ts

@@ -10,7 +10,7 @@ export type DividerProps<Tag extends DividerGenerics = 'div'> = {
      * @type HTMLDivElement | HTMLHRElement | HTMLSpanElement
      * @bindable
      */
-    ref?: DividerElement[Tag];
+    ref?: DividerElement[Tag] | null;
     /** Renders the divider vertically instead of horizontally. */
     vertical?: boolean;
     /** Where the content of the divider sits along the line.

package/dist/components/dropdown/docs/llms.md

@@ -9,7 +9,7 @@ The Dropdown lets users select one or more options from a list of `DropdownOptio
 	import { Dropdown, DropdownOption } from 'fluentui-svelte';
 </script>
 
-<Dropdown>
+<Dropdown aria-label="Choose an option">
 	<DropdownOption value="A" text="Option A">Option A</DropdownOption>
 	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
 </Dropdown>
@@ -22,13 +22,13 @@ The Dropdown lets users select one or more options from a list of `DropdownOptio
 Options can render any content, such as a `Persona`. Pass a `text` prop so the closed dropdown can still display the selection.
 
 ```svelte
-<Dropdown>
+<Dropdown aria-label="Choose an option">
 	<DropdownOption value="John Doe" text="John Doe">
 		<Persona
 			name="John Doe"
 			primaryText="Software Engineer"
 			presence={{ status: 'available' }}
-			avatar={{ color: 'colorful', idForColor: '' }}
+			avatarProps={{ color: 'colorful', idForColor: '' }}
 		/>
 	</DropdownOption>
 	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
@@ -41,38 +41,40 @@ Options can render any content, such as a `Persona`. Pass a `text` prop so the c
 Set the `multiple` prop to allow selecting more than one option.
 
 ```svelte
-<Dropdown multiple>
+<Dropdown multiple aria-label="Choose options">
 	<DropdownOption value="A" text="Option A">Option A</DropdownOption>
 	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
 	<DropdownOption value="C" text="Option C">Option C</DropdownOption>
 </Dropdown>
 ```
 
+HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.
+
 ## Component Props
 
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:DropdownProps -->
 
-| Name                                                 | Type                       | Default              | Description                                                             |
-| ---------------------------------------------------- | -------------------------- | -------------------- | ----------------------------------------------------------------------- |
-| `value` _bindable_                                   | `string` &#124; `string[]` | `multiple ? [] : ''` | The selected value. An array of values when `multiple` is set.          |
-| `multiple`                                           | `boolean`                  |                      | Allows more than one option to be selected at a time.                   |
-| `placeholder`                                        | `string`                   | `'Select an option'` | The text shown by the trigger while no option is selected.              |
-| `disabled`                                           | `boolean`                  |                      | Disables the user interaction.                                          |
-| `name`                                               | `string` &#124; `null`     | `id`                 | The name submitted with the form. Falls back to the id of the dropdown. |
-| `ref` _bindable_                                     | `HTMLDivElement`           |                      | The DOM reference of the dropdown element.                              |
-| `onclick`                                            | `(e: MouseEvent) => void`  |                      | Called when the dropdown is clicked.                                    |
-| `wrapperProps`                                       | `HTMLAttributes`           |                      | The attributes to spread on the wrapper element.                        |
-| `buttonRef` _bindable_                               | `HTMLButtonElement`        |                      | The DOM reference of the button that opens the dropdown.                |
-| `buttonProps`                                        | `HTMLButtonAttributes`     |                      | The attributes to spread on the button that opens the dropdown.         |
-| `inputRef`                                           | `HTMLInputElement`         |                      | The DOM reference of the hidden input holding the value.                |
-| `flyoutRef` _bindable_                               | `HTMLDivElement`           |                      | The DOM reference of the flyout element.                                |
-| `flyoutProps`                                        | `FlyoutProps`              |                      | The props to spread on the flyout.                                      |
-| `flyoutMaxHeight`                                    | `string`                   |                      | The maximum height of the flyout, as a CSS length.                      |
-| `listboxRef` _bindable_                              | `HTMLUListElement`         |                      | The DOM reference of the listbox element.                               |
-| `listboxProps`                                       | `ListViewProps`            |                      | The props to spread on the listbox rendered inside the flyout.          |
-| `DropdownMultipleValue` &#124; `DropdownSingleValue` |                            |                      |                                                                         |
-| `HTMLInputAttributes` without `value`, `onclick`     |                            |                      |                                                                         |
+| Name                                                 | Type                              | Default              | Description                                                                                                          |
+| ---------------------------------------------------- | --------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `value` _bindable_                                   | `string` &#124; `string[]`        | `multiple ? [] : ''` | The selected value. An array of values when `multiple` is set.                                                       |
+| `multiple`                                           | `boolean`                         |                      | Allows more than one option to be selected at a time.                                                                |
+| `placeholder`                                        | `string`                          | `'Select an option'` | The text shown by the trigger while no option is selected.                                                           |
+| `disabled`                                           | `boolean`                         |                      | Disables the user interaction.                                                                                       |
+| `name`                                               | `string` &#124; `null`            |                      | The name the value is submitted under. Without one, the form leaves the value out, as with any field.                |
+| `wrapperRef` _bindable_                              | `HTMLDivElement` &#124; `null`    |                      | The DOM reference of the wrapper element.                                                                            |
+| `wrapperAttributes`                                  | `HTMLAttributes`                  |                      | The attributes to spread on the wrapper element.                                                                     |
+| `ref` _bindable_                                     | `HTMLSelectElement` &#124; `null` |                      | The DOM reference of the native select that holds the value. The other attributes of the dropdown are applied to it. |
+| `buttonRef` _bindable_                               | `HTMLButtonElement` &#124; `null` |                      | The DOM reference of the button that opens the dropdown.                                                             |
+| `buttonAttributes`                                   | `HTMLButtonAttributes`            |                      | The attributes to spread on the button that opens the dropdown.                                                      |
+| `flyoutRef` _bindable_                               | `HTMLDivElement` &#124; `null`    |                      | The DOM reference of the flyout element.                                                                             |
+| `flyoutProps`                                        | `FlyoutProps`                     |                      | The props to spread on the flyout.                                                                                   |
+| `flyoutMaxHeight`                                    | `string`                          |                      | The maximum height of the flyout, as a CSS length.                                                                   |
+| `listboxRef` _bindable_                              | `HTMLUListElement` &#124; `null`  |                      | The DOM reference of the listbox element.                                                                            |
+| `listboxProps`                                       | `ListViewProps`                   |                      | The props to spread on the listbox rendered inside the flyout.                                                       |
+| `children`                                           | `Snippet`                         |                      | The `DropdownOption` elements of the list.                                                                           |
+| `DropdownMultipleValue` &#124; `DropdownSingleValue` |                                   |                      |                                                                                                                      |
+| `NativeFieldAttributes<HTMLSelectAttributes>`        |                                   |                      |                                                                                                                      |
 
 <!-- /props:DropdownProps -->
 
@@ -81,9 +83,9 @@ Set the `multiple` prop to allow selecting more than one option.
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:DropdownOptionProps -->
 
-| Name                      | Type     | Default | Description                                                                                      |
-| ------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
-| `text`                    | `string` |         | The text shown by the dropdown once the option is selected. Falls back to the rendered children. |
-| `ListViewItemProps<'li'>` |          |         |                                                                                                  |
+| Name                      | Type     | Default | Description                                                                                                                                                          |
+| ------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `text`                    | `string` |         | The text shown by the dropdown once the option is selected. Falls back to the rendered children, which the server cannot read: pass it when rendering on the server. |
+| `ListViewItemProps<'li'>` |          |         |                                                                                                                                                                      |
 
 <!-- /props:DropdownOptionProps -->

package/dist/components/dropdown/dropdown-option.svelte

@@ -8,17 +8,29 @@
 	const FALLBACK_ID = $props.id();
 	const ID = `${PREFIX}-dropdown-option-${FALLBACK_ID}`;
 
-	let { value, text, disabled, id = ID, ref = $bindable(), children }: DropdownOptionProps = $props();
+	let { value, text, disabled, id = ID, ref = $bindable(null), children }: DropdownOptionProps = $props();
 
 	const context = getDropdownContext();
 
 	if (!context) throw new Error('DropdownOption must be used within a Dropdown');
 
-	// Report the option's label so the trigger can show text instead of the raw value.
+	/** The rendered content, which stands in for a missing `text` once there is a page to read it from. */
+	let rendered = $state<string>();
+
+	// Report the option's label and the trigger can show text instead of the raw value. It is reported
+	// as the option is created, ahead of the trigger, so the server writes it too.
+	const withdraw = context.methods?.registerOption({
+		get value() {
+			return value;
+		},
+		get text() {
+			return text ?? rendered;
+		}
+	});
+
 	onMount(() => {
-		if (value == null) return;
-		const label = text ?? (ref?.textContent?.trim() || String(value));
-		context.methods?.registerOption(String(value), label);
+		rendered = ref?.textContent?.trim() || undefined;
+		return withdraw;
 	});
 </script>
 

package/dist/components/dropdown/dropdown.svelte

@@ -1,11 +1,13 @@
 <script lang="ts">
+	import { claimLabel } from '../label/label-context.js';
+	import { dispatchFieldEvents, invokeHandlers, NativeField } from '../../internal/index.js';
 	import { onClickOutside } from 'runed';
 	import ChevronDownFilled from 'fluentui-icons-svelte/ChevronDownFilled.svelte';
 	import { Flyout, ListView, ListViewItem } from '../../index.js';
-	import type { DropdownContext, DropdownProps } from './types.js';
+	import type { DropdownContext, DropdownOptionLabel, DropdownProps } from './types.js';
 	import { tick } from 'svelte';
-	import { SvelteMap } from 'svelte/reactivity';
-	import { setTabspotAttributes, unsetTabspotSection } from 'tabspot';
+	import { SvelteSet } from 'svelte/reactivity';
+	import { clearTabspotActive, setTabspotActive, setTabspotAttributes, unsetTabspotSection } from 'tabspot';
 	import { PREFIX } from '../../internal/constants.js';
 	import { getGlobalFSContext } from '../../providers/fluentui-svelte/fluentui-svelte.js';
 	import { setDropdownContext } from './dropdown-context.js';
@@ -13,26 +15,39 @@
 	const FALLBACK_ID = $props.id();
 	const ID = `${PREFIX}-dropdown-${FALLBACK_ID}`;
 
+	const labelContext = claimLabel(() => id);
+
 	let {
-		id = ID,
-		name = id,
+		id = labelContext?.fieldId ?? ID,
+		name,
 		placeholder = 'Select an option',
 		multiple,
 		value = $bindable(multiple ? [] : ''),
 		disabled,
 		flyoutMaxHeight,
-		ref = $bindable(),
-		wrapperProps,
-		buttonRef = $bindable(),
-		buttonProps,
-		flyoutRef = $bindable(),
+		wrapperRef = $bindable(null),
+		wrapperAttributes,
+		ref = $bindable(null),
+		buttonRef = $bindable(null),
+		buttonAttributes,
+		flyoutRef = $bindable(null),
 		flyoutProps,
-		listboxRef = $bindable(),
+		listboxRef = $bindable(null),
 		listboxProps,
-		onclick,
-		children
+		onfocus,
+		onblur,
+		children,
+		...attributes
 	}: DropdownProps = $props();
 
+	const BUTTON_ID = $derived(buttonAttributes?.id ?? `${id}-button`);
+
+	const native = new NativeField(
+		() => ref,
+		() => buttonRef,
+		labelContext
+	);
+
 	let open = $state(false);
 
 	let roundClass = $state('bottom');
@@ -41,16 +56,19 @@
 
 	const OPEN_KEYS = ['ArrowDown', 'ArrowUp', 'ArrowLeft', 'ArrowRight', 'Enter', ' '];
 
-	// Options only mount while the flyout is open, so we cache the last-known text
-	// for every value here to keep rendering the selection once the list is closed.
-	const optionLabels = new SvelteMap<string, string>();
+	// The list stays in the page while closed, so every option is here from the start, and is read live.
+	const options = new SvelteSet<DropdownOptionLabel>();
+	const optionLabels = $derived(new Map([...options].map((option) => [option.value, option.text])));
 
 	const context: DropdownContext = $state({
 		config: null,
 		state: null,
 		events: null,
 		methods: {
-			registerOption: (optionValue: string, text: string) => optionLabels.set(optionValue, text)
+			registerOption: (option) => {
+				options.add(option);
+				return () => options.delete(option);
+			}
 		}
 	});
 
@@ -65,8 +83,11 @@
 	);
 
 	onClickOutside(
-		() => ref,
-		() => closeDropdown()
+		() => wrapperRef,
+		(event) => {
+			if (event.target instanceof Element && event.target.closest('label')?.control === ref) return;
+			closeDropdown();
+		}
 	);
 
 	function handlePlacementChange(newPlacement: string) {
@@ -77,7 +98,12 @@
 		if (disabled || open) return;
 		open = true;
 		await tick();
-		globalFSContext?.state?.tabspotInstance?.rebuild(ref);
+		globalFSContext?.state?.tabspotInstance?.rebuild(wrapperRef ?? undefined);
+		// The cursor starts on the selection, or on the first option, so it is announced on open.
+		const start =
+			listboxRef?.querySelector<HTMLElement>('.fs-list-view-item[aria-selected="true"]:not([aria-disabled="true"])') ??
+			listboxRef?.querySelector<HTMLElement>('.fs-list-view-item:not([aria-disabled="true"])');
+		if (start) setTabspotActive(start, { nearest: true });
 	}
 
 	function closeDropdown() {
@@ -91,6 +117,13 @@
 
 		const { key } = e;
 
+		if (open && (key === 'Enter' || key === ' ')) {
+			e.preventDefault();
+			// Focus stays on the button, so the option under the cursor never sees the key: click it here.
+			listboxRef?.querySelector<HTMLElement>('[data-active="true"]')?.click();
+			return;
+		}
+
 		if (OPEN_KEYS.includes(key)) {
 			e.preventDefault();
 			await openDropdown();
@@ -103,18 +136,32 @@
 		}
 	}
 
-	async function handleClick(e: MouseEvent) {
+	async function handleClick() {
 		if (open) closeDropdown();
 		else await openDropdown();
-		onclick?.(e);
+	}
+
+	/** A label activates the native select it belongs to, which hands the activation to the button. */
+	async function openFromField() {
+		buttonRef?.focus();
+		await openDropdown();
+	}
+
+	function select(items: string[] | undefined) {
+		const next = multiple ? (items ?? []) : (items?.[0] ?? '');
+		if (!multiple && next === value) return;
+		value = next;
+		dispatchFieldEvents(ref);
 	}
 
 	// Force rebuild of tabspot handling tree
 	$effect(() => {
-		if (!ref) return;
+		if (!wrapperRef) return;
 
 		if (!open) {
-			unsetTabspotSection(ref, 'root');
+			// The list stays in the page once closed: nothing in it reads as chosen.
+			clearTabspotActive(wrapperRef);
+			unsetTabspotSection(wrapperRef, 'root');
 			return;
 		}
 
@@ -127,7 +174,7 @@
 					axis: 'vertical',
 					items: '.fs-list-view-item',
 					activation: {
-						controller: `#${id}-button`,
+						controller: `#${CSS.escape(BUTTON_ID)}`,
 						mode: 'activedescendant',
 						mark: {
 							attribute: 'data-active'
@@ -135,83 +182,119 @@
 					}
 				}
 			},
-			element: ref,
+			element: wrapperRef,
 			merge: true
 		});
 	});
 </script>
 
-<div class={['fs-dropdown', `square-${roundClass}`, { open, disabled }]} bind:this={ref} {...wrapperProps}>
+<div
+	{...wrapperAttributes}
+	class={['fs-dropdown', `square-${roundClass}`, { open, disabled }, wrapperAttributes?.class]}
+	bind:this={wrapperRef}
+>
+	<!-- Hidden while closed, not gone: each option reports its text as it is created, and comes before
+	     the button, so the button shows it before the list ever opens, on the server too. -->
+	<Flyout
+		{...flyoutProps}
+		hidden={!open}
+		style="{flyoutProps?.style ?? ''}; {flyoutMaxHeight ? `max-height: ${flyoutMaxHeight};` : ''}"
+		offset={0}
+		bind:ref={flyoutRef}
+		floating
+		roundCorners="bottom"
+		reference={wrapperRef ?? undefined}
+		id={`${id}-flyout`}
+		onPlacementChange={(place) => {
+			handlePlacementChange(place);
+			flyoutProps?.onPlacementChange?.(place);
+		}}
+		placementConfig={{ allowedPlacements: ['bottom', 'top'] }}
+		class="fs-dropdown-flyout {roundClass === 'top' ? 'top-shadow' : ''} {flyoutProps?.class}"
+	>
+		<ListView
+			{...listboxProps}
+			bind:ref={listboxRef}
+			bind:selectedItems={() => selectedValues, select}
+			selectionMode={multiple ? 'multiselect' : 'single'}
+			toggleOnClick={multiple}
+			onSelectionChange={(event, selected) => {
+				if (!multiple) closeDropdown();
+				listboxProps?.onSelectionChange?.(event, selected);
+			}}
+			navigationMode="items"
+			id={`${id}-listbox`}
+			role="listbox"
+			disableTabspot
+		>
+			{#if !children}
+				<ListViewItem disabled>No options available</ListViewItem>
+			{:else}
+				{@render children?.()}
+			{/if}
+		</ListView>
+	</Flyout>
 	<ChevronDownFilled class="indicator" />
 	<button
+		{...buttonAttributes}
+		{...native.aria(attributes, buttonAttributes)}
 		bind:this={buttonRef}
 		type="button"
 		role="combobox"
-		onclick={handleClick}
-		onkeydown={handleKeyDown}
-		aria-controls={`${id}-listbox`}
+		onclick={(e) => invokeHandlers(e, [disabled], [handleClick, buttonAttributes?.onclick])}
+		onkeydown={(e) => invokeHandlers(e, [disabled], [handleKeyDown, buttonAttributes?.onkeydown])}
+		onfocus={(e) => invokeHandlers(e, [], [onfocus, buttonAttributes?.onfocus])}
+		onblur={(e) => invokeHandlers(e, [], [onblur, buttonAttributes?.onblur])}
+		aria-controls={open ? `${id}-listbox` : undefined}
 		aria-expanded={open}
-		id={`${id}-button`}
+		id={BUTTON_ID}
 		aria-haspopup="listbox"
 		{disabled}
-		class={['fs-dropdown-button', hasValue && 'has-value']}
-		{...buttonProps}
+		class={['fs-dropdown-button', hasValue && 'has-value', buttonAttributes?.class]}
 	>
 		{displayLabel}
 	</button>
 
-	<input type="hidden" {name} {value} {id} {disabled} />
-
-	{#if open}
-		<Flyout
-			style={flyoutMaxHeight ? `max-height: ${flyoutMaxHeight};` : ''}
-			offset={0}
-			bind:ref={flyoutRef}
-			{...flyoutProps}
-			floating
-			roundCorners="bottom"
-			reference={ref}
-			id={`${id}-flyout`}
-			onPlacementChange={(place) => handlePlacementChange(place)}
-			placementConfig={{ allowedPlacements: ['bottom', 'top'] }}
-			class="fs-dropdown-flyout {roundClass === 'top' ? 'top-shadow' : ''} {flyoutProps?.class}"
+	<!-- The field of the form: submitted, validated and reset like any select input,
+	     behind the button and out of the tab order, since the button is what people use. See `NativeField`. -->
+	<!-- Svelte needs a static `multiple` to bind a select, hence the two branches. This is the native form -->
+	{#if multiple}
+		<select
+			{...attributes}
+			class="native-field"
+			aria-hidden={native.reported ? undefined : 'true'}
+			multiple
+			tabindex={-1}
+			{id}
+			{name}
+			{disabled}
+			bind:value
+			bind:this={ref}
+			onclick={openFromField}
 		>
-			<ListView
-				bind:ref={listboxRef}
-				bind:selectedItems={
-					() => {
-						if (multiple) {
-							return (value as string[]) || [];
-						} else {
-							return value ? [value as string] : [];
-						}
-					},
-					(v) => {
-						if (multiple) {
-							value = v || [];
-						} else {
-							value = v?.[0] || '';
-						}
-					}
-				}
-				selectionMode={multiple ? 'multiselect' : 'single'}
-				toggleOnClick={multiple}
-				onSelectionChange={() => {
-					if (!multiple) closeDropdown();
-				}}
-				navigationMode="items"
-				id={`${id}-listbox`}
-				role="listbox"
-				disableTabspot
-				{...listboxProps}
-			>
-				{#if !children}
-					<ListViewItem disabled>No options available</ListViewItem>
-				{:else}
-					{@render children?.()}
-				{/if}
-			</ListView>
-		</Flyout>
+			{#each selectedValues as option (option)}
+				<option value={option}>{optionLabels.get(option) ?? option}</option>
+			{/each}
+		</select>
+	{:else}
+		<select
+			{...attributes}
+			class="native-field"
+			aria-hidden={native.reported ? undefined : 'true'}
+			tabindex={-1}
+			{id}
+			{name}
+			{disabled}
+			bind:value
+			bind:this={ref}
+			onclick={openFromField}
+		>
+			<!-- The placeholder makes an empty value missing for `required`, and is what a reset returns to. -->
+			<option value="" hidden></option>
+			{#if hasValue}
+				<option {value}>{displayLabel}</option>
+			{/if}
+		</select>
 	{/if}
 </div>
 
@@ -300,6 +383,21 @@
 			left: -0.063rem;
 			background-color: var(--fs-accent-fill-default);
 		}
+		&:has(> .native-field:is(:user-invalid, [aria-invalid='true'])):after {
+			width: calc(100% + 0.125rem);
+			left: -0.063rem;
+			background-color: var(--fs-system-critical);
+		}
+		& .native-field {
+			position: absolute;
+			inset: 0;
+			inline-size: 100%;
+			block-size: 100%;
+			margin: 0;
+			box-sizing: border-box;
+			opacity: 0;
+			pointer-events: none;
+		}
 		& :global(> .indicator) {
 			width: 1rem;
 			position: absolute;

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

@@ -1,4 +1,4 @@
 import type { DropdownProps } from './types.ts';
-declare const Dropdown: import("svelte").Component<DropdownProps, {}, "ref" | "value" | "flyoutRef" | "buttonRef" | "listboxRef">;
+declare const Dropdown: import("svelte").Component<DropdownProps, {}, "ref" | "value" | "wrapperRef" | "flyoutRef" | "buttonRef" | "listboxRef">;
 type Dropdown = ReturnType<typeof Dropdown>;
 export default Dropdown;