fluentui-svelte 0.5.0 → 0.7.0

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

@@ -45,6 +45,40 @@ The Dialog is composed of several components that work together through a shared
 
 ## Examples
 
+### Position
+
+Set `position` on `Dialog` to combine `top`, `middle`, or `bottom` with `start`, `center`, or `end`, for example `top-end` or `bottom-start`. The default is `middle-center`.
+
+Start and end follow the text direction, so `top-start` sits on the right in RTL. All positions keep a 1rem gap from viewport edges and work with modal, non-modal, and alert dialogs. Changing `position` moves an open dialog without closing it.
+
+```svelte
+<Dialog position="top-end">
+	<DialogTrigger>Open Dialog</DialogTrigger>
+	<DialogSurface>
+		<DialogTitle>Dialog Title</DialogTitle>
+		<DialogContent>Dialog body content.</DialogContent>
+	</DialogSurface>
+</Dialog>
+```
+
+### Entrance and Exit Motion
+
+`animation` selects `fade`, `zoom`, `slide`, or `bounce` for both directions. The default is `zoom`. Zoom enters from 88% scale and exits to 90%; slide travels 16px, from above for top positions and below otherwise. Bounce uses a small scale overshoot with Fluent's strong-invoke curve.
+
+`duration` defaults to `normal`. Theme names are `fast`, `normal`, `slow`, `slower`, `very-slow`, and `extra-slow`, matching `--fs-<name>-duration`. A CSS custom property name such as `--fs-fast-duration` is also accepted. Numbers are milliseconds; `0` disables motion.
+
+```svelte
+<Dialog animation="slide" duration={200} position="bottom-end">
+	<DialogTrigger>Open Dialog</DialogTrigger>
+	<DialogSurface>
+		<DialogTitle>Dialog Title</DialogTitle>
+		<DialogContent>Dialog body content.</DialogContent>
+	</DialogSurface>
+</Dialog>
+```
+
+Motion is implemented with CSS `@starting-style` and discrete `display`/`overlay` transitions. Calling `closeDialog()` updates `open` and releases native modal focus immediately; CSS keeps the surface and backdrop painted until the exit ends. Browsers without these CSS features open and close immediately. The OS reduced-motion preference and FluentUISvelte's app preference disable motion, including numeric durations; an explicit app preference takes priority over the OS.
+
 ### With Actions
 
 Add a `DialogActions` region to render action buttons in the dialog footer. Use `bind:this` on the `Dialog` to call `closeDialog()` programmatically.
@@ -83,12 +117,15 @@ Add a `DialogActions` region to render action buttons in the dialog footer. Use
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:DialogProps -->
 
-| Name              | Type                                            | Default   | Description                                       |
-| ----------------- | ----------------------------------------------- | --------- | ------------------------------------------------- |
-| `type`            | `'modal'` &#124; `'non-modal'` &#124; `'alert'` | `'modal'` | How the dialog behaves once open.                 |
-| `open` _bindable_ | `boolean`                                       |           | Controls the open state of the dialog.            |
-| `onOpenChange`    | `(open: boolean) => void`                       |           | Called whenever the dialog opens or closes.       |
-| `children`        | `Snippet`                                       |           | The parts of the dialog: a trigger and a surface. |
+| Name              | Type                                                                       | Default           | Description                                                                                          |
+| ----------------- | -------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `type`            | `'modal'` &#124; `'non-modal'` &#124; `'alert'`                            | `'modal'`         | How the dialog behaves once open.                                                                    |
+| `position`        | [`DialogPosition`](https://fluentui-svelte.dev/docs/types/#dialogposition) | `'middle-center'` | Where the dialog sits in the viewport. Start and end follow the text direction.                      |
+| `animation`       | `'fade'` &#124; `'zoom'` &#124; `'slide'` &#124; `'bounce'`                | `'zoom'`          | The entrance and exit animation. Bounce uses a subtle overshoot.                                     |
+| `duration`        | [`DialogDuration`](https://fluentui-svelte.dev/docs/types/#dialogduration) | `'normal'`        | Duration in milliseconds, a theme duration name, or a CSS custom property name. Use 0 for no motion. |
+| `open` _bindable_ | `boolean` &#124; `null`                                                    |                   | Controls the open state of the dialog.                                                               |
+| `onOpenChange`    | `(open: boolean) => void`                                                  |                   | Called whenever the dialog opens or closes.                                                          |
+| `children`        | `Snippet`                                                                  |                   | The parts of the dialog: a trigger and a surface.                                                    |
 
 <!-- /props:DialogProps -->
 
@@ -97,10 +134,10 @@ Add a `DialogActions` region to render action buttons in the dialog footer. Use
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:DialogTriggerProps -->
 
-| Name                    | Type                | Default | Description                               |
-| ----------------------- | ------------------- | ------- | ----------------------------------------- |
-| `ref`                   | `HTMLButtonElement` |         | The DOM reference of the trigger element. |
-| `ButtonProps<'button'>` |                     |         |                                           |
+| Name                    | Type                              | Default | Description                               |
+| ----------------------- | --------------------------------- | ------- | ----------------------------------------- |
+| `ref` _bindable_        | `HTMLButtonElement` &#124; `null` |         | The DOM reference of the trigger element. |
+| `ButtonProps<'button'>` |                                   |         |                                           |
 
 <!-- /props:DialogTriggerProps -->
 
@@ -109,10 +146,10 @@ Add a `DialogActions` region to render action buttons in the dialog footer. Use
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:DialogSurfaceProps -->
 
-| Name                          | Type                | Default | Description                              |
-| ----------------------------- | ------------------- | ------- | ---------------------------------------- |
-| `ref` _bindable_              | `HTMLDialogElement` |         | The DOM reference of the dialog element. |
-| Element Attributes (`dialog`) |                     |         |                                          |
+| Name                          | Type                              | Default | Description                              |
+| ----------------------------- | --------------------------------- | ------- | ---------------------------------------- |
+| `ref` _bindable_              | `HTMLDialogElement` &#124; `null` |         | The DOM reference of the dialog element. |
+| Element Attributes (`dialog`) |                                   |         |                                          |
 
 <!-- /props:DialogSurfaceProps -->
 
@@ -134,10 +171,10 @@ Add a `DialogActions` region to render action buttons in the dialog footer. Use
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:DialogContentProps -->
 
-| Name                       | Type             | Default | Description                               |
-| -------------------------- | ---------------- | ------- | ----------------------------------------- |
-| `ref`                      | `HTMLDivElement` |         | The DOM reference of the content element. |
-| Element Attributes (`div`) |                  |         |                                           |
+| Name                       | Type                           | Default | Description                               |
+| -------------------------- | ------------------------------ | ------- | ----------------------------------------- |
+| `ref` _bindable_           | `HTMLDivElement` &#124; `null` |         | The DOM reference of the content element. |
+| Element Attributes (`div`) |                                |         |                                           |
 
 <!-- /props:DialogContentProps -->
 
@@ -148,7 +185,7 @@ Add a `DialogActions` region to render action buttons in the dialog footer. Use
 
 | Name                       | Type                                       | Default | Description                                                 |
 | -------------------------- | ------------------------------------------ | ------- | ----------------------------------------------------------- |
-| `ref` _bindable_           | `HTMLDivElement`                           |         | The DOM reference of the actions element.                   |
+| `ref` _bindable_           | `HTMLDivElement` &#124; `null`             |         | The DOM reference of the actions element.                   |
 | `fluid`                    | `boolean`                                  |         | Stretches every action to share the available width evenly. |
 | `position`                 | `'start'` &#124; `'center'` &#124; `'end'` | `'end'` | Where the actions sit along the main axis.                  |
 | Element Attributes (`div`) |                                            |         |                                                             |

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

@@ -4,6 +4,9 @@ import type { HTMLAttributes } from 'svelte/elements';
 import type { ButtonProps } from '../button/types.ts';
 import type { PolymorphicProps, XDirection } from '../../types/index.js';
 export type DialogType = 'modal' | 'non-modal' | 'alert';
+export type DialogAnimation = 'fade' | 'zoom' | 'slide' | 'bounce';
+export type DialogDuration = number | 'fast' | 'normal' | 'slow' | 'slower' | 'very-slow' | 'extra-slow' | `--${string}`;
+export type DialogPosition = 'top-start' | 'top-center' | 'top-end' | 'middle-start' | 'middle-center' | 'middle-end' | 'bottom-start' | 'bottom-center' | 'bottom-end';
 export type DialogTitleTag = 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 /** @propsmith DialogProps */
 export type DialogProps = {
@@ -17,10 +20,22 @@ export type DialogProps = {
      * @default 'modal'
      */
     type?: DialogType;
+    /** Where the dialog sits in the viewport. Start and end follow the text direction.
+     * @default 'middle-center'
+     */
+    position?: DialogPosition;
+    /** The entrance and exit animation. Bounce uses a subtle overshoot.
+     * @default 'zoom'
+     */
+    animation?: DialogAnimation;
+    /** Duration in milliseconds, a theme duration name, or a CSS custom property name. Use 0 for no motion.
+     * @default 'normal'
+     */
+    duration?: DialogDuration;
     /** Controls the open state of the dialog.
      * @bindable
      */
-    open?: boolean;
+    open?: boolean | null;
     /** Called whenever the dialog opens or closes. */
     onOpenChange?: (open: boolean) => void;
     /** The parts of the dialog: a trigger and a surface. */
@@ -31,24 +46,28 @@ export type DialogSurfaceProps = {
     /** The DOM reference of the dialog element.
      * @bindable
      */
-    ref?: HTMLDialogElement;
+    ref?: HTMLDialogElement | null;
 } & HTMLAttributes<HTMLDialogElement>;
 /** @propsmith DialogTriggerProps */
 export type DialogTriggerProps = {
-    /** The DOM reference of the trigger element. */
-    ref?: HTMLButtonElement;
+    /** The DOM reference of the trigger element.
+     * @bindable
+     */
+    ref?: HTMLButtonElement | null;
 } & ButtonProps<'button'>;
 /** @propsmith DialogContentProps */
 export type DialogContentProps = {
-    /** The DOM reference of the content element. */
-    ref?: HTMLDivElement;
+    /** The DOM reference of the content element.
+     * @bindable
+     */
+    ref?: HTMLDivElement | null;
 } & HTMLAttributes<HTMLDivElement>;
 /** @propsmith DialogActionsProps */
 export type DialogActionsProps = {
     /** The DOM reference of the actions element.
      * @bindable
      */
-    ref?: HTMLDivElement;
+    ref?: HTMLDivElement | null;
     /** Stretches every action to share the available width evenly. */
     fluid?: boolean;
     /** Where the actions sit along the main axis.
@@ -71,7 +90,7 @@ export type DialogTitleProps<T extends DialogTitleTag> = {
      * @type HTMLDivElement | HTMLHeadingElement
      * @bindable
      */
-    ref?: DialogTitleRefType[T];
+    ref?: DialogTitleRefType[T] | null;
     /** The HTML element to render the title as.
      * @type DialogTitleTag
      * @default 'h3'
@@ -80,9 +99,12 @@ export type DialogTitleProps<T extends DialogTitleTag> = {
 } & PolymorphicProps<T>;
 export type DialogContext = FSContext<{
     type: DialogType;
+    position: DialogPosition;
+    animation: DialogAnimation;
+    duration: DialogDuration;
 }, {
     dialogRef: HTMLDialogElement | undefined;
-    readonly open: boolean | undefined;
+    readonly open: boolean | null | undefined;
     /** Set by `DialogTitle`, to allow the surface pointing `aria-labelledby` at it. */
     titleId: string | undefined;
 }, null, {

package/dist/components/dialog/utils.d.ts

@@ -0,0 +1,2 @@
+import type { DialogTitleTag } from './types.ts';
+export declare const TITLE_TAG: DialogTitleTag[];

package/dist/components/dialog/utils.js

@@ -0,0 +1 @@
+export const TITLE_TAG = ['div', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'];

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>