fluentui-svelte 0.3.0 → 0.5.0

package/README.md

@@ -169,7 +169,7 @@ after changing a prop's JSDoc rather than editing the generated tables by hand.
 >
 > This app demonstrates all of the Windows UI 3 library controls and styles available to make a WinUI 3 app with the Windows App SDK.
 
-> ### Documentation: [Microsoft's Fluent UI](https://learn.microsoft.com/en-us/windows/apps/design/)
+> ### Documentation: [Microsoft's Fluent UI](https://developer.microsoft.com/en-us/fluentui/)
 >
 > Design guidelines and UI code examples for creating Windows app experiences.
 

package/dist/components/auto-suggest-box/docs/llms.md

@@ -18,44 +18,105 @@ The AutoSuggestBox component provides an input field with dynamic suggestions as
 
 ## Examples
 
-### Virtualized Suggestions
+### Open on focus
 
-Long lists can be windowed. Pass a `virtualizer` describing the _whole_ list — `size` is the
-total number of suggestions, not the number rendered — and the box drives your list component
-when the cursor walks past what is on screen. Options keep their real `index`, which is what
-ties a rendered row back to the data.
+Use `openOnFocus` to show suggestions as soon as the text box receives focus, before anything is typed.
+
+```svelte
+<AutoSuggestBox openOnFocus placeholder="Choose a fruit...">
+	{#each fruits as fruit, index (fruit.id)}
+		<AutoSuggestBoxOption {index} id={fruit.id} value={fruit.name}>
+			{fruit.name}
+		</AutoSuggestBoxOption>
+	{/each}
+</AutoSuggestBox>
+```
+
+### Virtualization
+
+Window large suggestion sets by connecting AutoSuggestBox to a virtual list through the `virtualizer` prop. Its `size` is the total number of suggestions, while each option keeps its real `index`.
+
+```svelte
+<script>
+	import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
+
+	let listRef;
+</script>
+
+<AutoSuggestBox
+	placeholder="Type a name..."
+	virtualizer={{
+		size: people.length,
+		scrollToTop: () => listRef.scroll({ index: 0, align: 'top', smoothScroll: false }),
+		scrollToBottom: () => listRef.scroll({ index: people.length - 1, align: 'bottom', smoothScroll: false }),
+		scrollToIndex: (index) => listRef.scroll({ index, align: 'auto', smoothScroll: false })
+	}}
+>
+	<SvelteVirtualList items={people} bind:this={listRef} defaultEstimatedItemHeight={30}>
+		{#snippet renderItem(person, index)}
+			<AutoSuggestBoxOption {index} id={person.id} value={person.name}>
+				{person.name}
+			</AutoSuggestBoxOption>
+		{/snippet}
+	</SvelteVirtualList>
+</AutoSuggestBox>
+```
+
+### Multiselect
+
+Allow people to choose several suggestions and optionally show the selected values in the text box.
+
+```svelte
+<script>
+	let selectedOptions = $state([]);
+</script>
+
+<AutoSuggestBox multiselect showTextualMultiselect bind:selectedOptions placeholder="Choose fruits...">
+	{#each fruits as fruit, index (fruit.id)}
+		<AutoSuggestBoxOption {index} id={fruit.id} value={fruit.name}>
+			{fruit.name}
+		</AutoSuggestBoxOption>
+	{/each}
+</AutoSuggestBox>
+```
+
+### Virtualization with filtering
+
+A virtualized list must filter its source data itself and report the filtered length through `virtualizer.size`.
 
 ```svelte
 <script>
 	import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
 
-	let items = $state(fruits);
+	let items = $state(people);
 	let listRef;
 </script>
 
 <AutoSuggestBox
-	placeholder="Type a fruit..."
+	placeholder="Type a name..."
 	virtualizer={{
 		size: items.length,
 		scrollToTop: () => listRef.scroll({ index: 0, align: 'top', smoothScroll: false }),
-		scrollToBottom: () => listRef.scroll({ index: items.length - 1, align: 'bottom', smoothScroll: false }),
+		scrollToBottom: () => {
+			if (items.length) listRef.scroll({ index: items.length - 1, align: 'bottom', smoothScroll: false });
+		},
 		scrollToIndex: (index) => listRef.scroll({ index, align: 'auto', smoothScroll: false })
 	}}
-	textChanged={(e, val) => (items = fruits.filter((item) => item.name.toLowerCase().includes(val.toLowerCase())))}
+	textChanged={(_, value) => {
+		const query = value.trim().toLowerCase();
+		items = people.filter(({ name }) => name.toLowerCase().includes(query));
+	}}
 >
 	<SvelteVirtualList {items} bind:this={listRef} defaultEstimatedItemHeight={30}>
-		{#snippet renderItem(item, index)}
-			<AutoSuggestBoxOption {index} id={item.id} value={item.name} text={item.name}>
-				{item.name}
+		{#snippet renderItem(person, index)}
+			<AutoSuggestBoxOption {index} id={person.id} value={person.name}>
+				{person.name}
 			</AutoSuggestBoxOption>
 		{/snippet}
 	</SvelteVirtualList>
 </AutoSuggestBox>
 ```
 
-Filtering is yours to do in `textChanged`: a windowed list renders from your data, so the
-built-in filter that a plain option list applies is skipped.
-
 ## Component Props
 
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->

package/dist/components/breadcrumb/breadcrumb-button.svelte

@@ -0,0 +1,130 @@
+<script lang="ts" generics="T extends BreadcrumbItemGenerics = 'button'">
+	import { invokeHandlers, RenderSoC } from '../../internal/index.js';
+	import type { BreadcrumbButtonProps, BreadcrumbItemElementDOMType, BreadcrumbItemGenerics } from './types.js';
+
+	let {
+		as = 'button' as T,
+		ref = $bindable(),
+		icon,
+		iconPosition = 'before',
+		current = false,
+		disabled,
+		disabledFocusable = false,
+		onclick,
+		class: classes,
+		children,
+		...attributes
+	}: BreadcrumbButtonProps<T> = $props();
+
+	const _as = $derived.by(() => {
+		if (as !== 'button' && as !== 'a') throw new Error(`Invalid tag: ${as}. Must be one of button, a`);
+		return as;
+	});
+
+	const nativelyDisabled = $derived(_as === 'button' && disabled && !disabledFocusable);
+</script>
+
+<!--
+	@component
+	A step of a `Breadcrumb` that can be activated: an anchor when it goes somewhere, a button when
+	it does something. The last step is the page itself, and `current` is what announces it.
+
+	- Usage:
+	```tsx
+	<BreadcrumbButton as="a" href="/files" icon={FolderRegular}>Files</BreadcrumbButton>
+	<BreadcrumbButton current>This page</BreadcrumbButton>
+	```
+-->
+<svelte:element
+	this={_as}
+	bind:this={ref as BreadcrumbItemElementDOMType[T]}
+	type={_as === 'button' ? 'button' : undefined}
+	disabled={nativelyDisabled || undefined}
+	aria-disabled={disabled || undefined}
+	aria-current={current ? 'page' : undefined}
+	class={['fs-breadcrumb-button', { current, disabled }, classes]}
+	onclick={(e: MouseEvent) => invokeHandlers(e, disabled, [onclick])}
+	{...attributes}
+>
+	{#if icon && iconPosition === 'before'}
+		<span class="fs-breadcrumb-button-icon">
+			<RenderSoC SoC={icon} />
+		</span>
+	{/if}
+	<span class="fs-breadcrumb-button-label">
+		{@render children?.()}
+	</span>
+	{#if icon && iconPosition === 'after'}
+		<span class="fs-breadcrumb-button-icon">
+			<RenderSoC SoC={icon} />
+		</span>
+	{/if}
+</svelte:element>
+
+<style>
+	.fs-breadcrumb-button {
+		display: inline-flex;
+		align-items: center;
+		gap: var(--fs-breadcrumb-gap, 0.25rem);
+		box-sizing: border-box;
+		min-width: 0;
+		height: var(--fs-breadcrumb-height, 1.5rem);
+		padding: 0 var(--fs-breadcrumb-padding-inline, 0.375rem);
+		border: none;
+		border-radius: var(--fs-control-border-radius);
+		background: transparent;
+		color: var(--fs-text-secondary);
+		font-family: inherit;
+		font-size: var(--fs-breadcrumb-font-size, var(--fs-body2-font-size));
+		line-height: var(--fs-breadcrumb-line-height, var(--fs-body2-line-height));
+		/* An anchor arrives underlined and in the colour of a link; a step is neither. */
+		text-decoration: none;
+		cursor: pointer;
+		outline: none;
+		transition:
+			color var(--fs-fast-duration) var(--fs-point-to-point),
+			background var(--fs-fast-duration) var(--fs-point-to-point);
+		&:hover:not(.disabled) {
+			background: var(--fs-subtle-fill-secondary);
+			color: var(--fs-text-primary);
+		}
+		&:active:not(.disabled) {
+			background: var(--fs-subtle-fill-tertiary);
+			color: var(--fs-text-secondary);
+		}
+		&:focus-visible {
+			outline: 0.125rem var(--fs-focus-stroke-outer) solid;
+			outline-offset: 0.125rem;
+		}
+		/* The end of the trail is where the reader already is, so it reads as text, not as a way out. */
+		&.current {
+			color: var(--fs-text-primary);
+			font-weight: 600;
+			cursor: default;
+			&:hover,
+			&:active {
+				background: transparent;
+				color: var(--fs-text-primary);
+			}
+		}
+		&.disabled {
+			color: var(--fs-text-disabled);
+			cursor: not-allowed;
+		}
+		& .fs-breadcrumb-button-icon {
+			display: flex;
+			flex: 0 0 auto;
+			align-items: center;
+			justify-content: center;
+			& :global(svg) {
+				width: var(--fs-breadcrumb-icon-size, 1rem);
+				height: var(--fs-breadcrumb-icon-size, 1rem);
+			}
+		}
+		& .fs-breadcrumb-button-label {
+			overflow: hidden;
+			text-overflow: ellipsis;
+			white-space: nowrap;
+		}
+	}
+</style>

package/dist/components/breadcrumb/breadcrumb-button.svelte.d.ts

@@ -0,0 +1,35 @@
+import type { BreadcrumbButtonProps, BreadcrumbItemGenerics } from './types.ts';
+declare function $$render<T extends BreadcrumbItemGenerics = 'button'>(): {
+    props: BreadcrumbButtonProps<T>;
+    exports: {};
+    bindings: "ref";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends BreadcrumbItemGenerics = 'button'> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "ref";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends BreadcrumbItemGenerics = 'button'>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends BreadcrumbItemGenerics = 'button'>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * A step of a `Breadcrumb` that can be activated: an anchor when it goes somewhere, a button when
+ * it does something. The last step is the page itself, and `current` is what announces it.
+ *
+ * - Usage:
+ * ```tsx
+ * <BreadcrumbButton as="a" href="/files" icon={FolderRegular}>Files</BreadcrumbButton>
+ * <BreadcrumbButton current>This page</BreadcrumbButton>
+ * ```
+ */
+declare const BreadcrumbButton: $$IsomorphicComponent;
+type BreadcrumbButton<T extends BreadcrumbItemGenerics = 'button'> = InstanceType<typeof BreadcrumbButton<T>>;
+export default BreadcrumbButton;

package/dist/components/breadcrumb/breadcrumb-divider.svelte

@@ -0,0 +1,39 @@
+<script lang="ts">
+	import ChevronRightRegular from 'fluentui-icons-svelte/ChevronRightRegular.svelte';
+	import type { BreadcrumbDividerProps } from './types.js';
+
+	let { ref = $bindable(), class: classes, children, ...attributes }: BreadcrumbDividerProps = $props();
+</script>
+
+<!--
+	@component
+	The mark between two steps of a `Breadcrumb`. It is decoration, so it is held out of the
+	accessibility tree: a reader counting the steps of the trail should not be read a chevron
+	between each one, nor be told the list is twice as long as it is.
+
+	- Usage:
+	```tsx
+	<BreadcrumbDivider />
+	```
+-->
+<li bind:this={ref} aria-hidden="true" class={['fs-breadcrumb-divider', classes]} {...attributes}>
+	{#if children}
+		{@render children()}
+	{:else}
+		<ChevronRightRegular />
+	{/if}
+</li>
+
+<style>
+	.fs-breadcrumb-divider {
+		display: flex;
+		flex: 0 0 auto;
+		align-items: center;
+		justify-content: center;
+		color: var(--fs-text-secondary);
+		& :global(svg) {
+			width: var(--fs-breadcrumb-divider-size, 0.75rem);
+			height: var(--fs-breadcrumb-divider-size, 0.75rem);
+		}
+	}
+</style>

package/dist/components/breadcrumb/breadcrumb-divider.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { BreadcrumbDividerProps } from './types.ts';
+/**
+ * The mark between two steps of a `Breadcrumb`. It is decoration, so it is held out of the
+ * accessibility tree: a reader counting the steps of the trail should not be read a chevron
+ * between each one, nor be told the list is twice as long as it is.
+ *
+ * - Usage:
+ * ```tsx
+ * <BreadcrumbDivider />
+ * ```
+ */
+declare const BreadcrumbDivider: import("svelte").Component<BreadcrumbDividerProps, {}, "ref">;
+type BreadcrumbDivider = ReturnType<typeof BreadcrumbDivider>;
+export default BreadcrumbDivider;

package/dist/components/breadcrumb/breadcrumb-item.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	import type { BreadcrumbItemProps } from './types.js';
+
+	let { ref = $bindable(), class: classes, children, ...attributes }: BreadcrumbItemProps = $props();
+</script>
+
+<!--
+	@component
+	One step of a `Breadcrumb`: the list item the step lives in. What goes inside is usually a
+	`BreadcrumbButton`, but it takes anything — a menu holding the steps that were folded away, for
+	instance.
+
+	- Usage:
+	```tsx
+	<BreadcrumbItem>
+		<BreadcrumbButton as="a" href="/">Home</BreadcrumbButton>
+	</BreadcrumbItem>
+	```
+-->
+<li bind:this={ref} class={['fs-breadcrumb-item', classes]} {...attributes}>
+	{@render children?.()}
+</li>
+
+<style>
+	.fs-breadcrumb-item {
+		display: flex;
+		align-items: center;
+		min-width: 0;
+	}
+</style>

package/dist/components/breadcrumb/breadcrumb-item.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { BreadcrumbItemProps } from './types.ts';
+/**
+ * One step of a `Breadcrumb`: the list item the step lives in. What goes inside is usually a
+ * `BreadcrumbButton`, but it takes anything — a menu holding the steps that were folded away, for
+ * instance.
+ *
+ * - Usage:
+ * ```tsx
+ * <BreadcrumbItem>
+ * 	<BreadcrumbButton as="a" href="/">Home</BreadcrumbButton>
+ * </BreadcrumbItem>
+ * ```
+ */
+declare const BreadcrumbItem: import("svelte").Component<BreadcrumbItemProps, {}, "ref">;
+type BreadcrumbItem = ReturnType<typeof BreadcrumbItem>;
+export default BreadcrumbItem;

package/dist/components/breadcrumb/breadcrumb.svelte

@@ -0,0 +1,101 @@
+<script lang="ts">
+	import { getTabspotAttributes } from 'tabspot';
+	import type { BreadcrumbProps } from './types.js';
+
+	/** The steps a mover lands on when the trail takes a single tab stop. */
+	const TABSPOT_ITEMS = '.fs-breadcrumb-button';
+
+	let {
+		ref = $bindable(),
+		listRef = $bindable(),
+		listProps,
+		size = 'medium',
+		focusMode = 'tab',
+		'aria-label': ariaLabel,
+		'aria-labelledby': ariaLabelledby,
+		class: classes,
+		children,
+		...attributes
+	}: BreadcrumbProps = $props();
+
+	const tabspotAttributes = $derived(
+		focusMode === 'arrow' &&
+			getTabspotAttributes({
+				root: { manageSpecialKeys: { Home: true, End: true } },
+				mover: { axis: 'horizontal', items: TABSPOT_ITEMS }
+			})
+	);
+</script>
+
+<!--
+	@component
+	A breadcrumb shows where a page sits in the hierarchy above it, and gives the reader a way back
+	up. It renders a landmark of its own, so a screen reader can jump straight to it.
+
+	- Usage:
+	```tsx
+	<script>
+		import { Breadcrumb, BreadcrumbItem, BreadcrumbButton, BreadcrumbDivider } from 'fluentui-svelte';
+	</script>
+
+	<Breadcrumb>
+		<BreadcrumbItem>
+			<BreadcrumbButton as="a" href="/">Home</BreadcrumbButton>
+		</BreadcrumbItem>
+		<BreadcrumbDivider />
+		<BreadcrumbItem>
+			<BreadcrumbButton current>This page</BreadcrumbButton>
+		</BreadcrumbItem>
+	</Breadcrumb>
+	```
+-->
+<nav
+	bind:this={ref}
+	aria-label={ariaLabelledby ? undefined : (ariaLabel ?? 'Breadcrumb')}
+	aria-labelledby={ariaLabelledby}
+	class={['fs-breadcrumb', size, classes]}
+	{...attributes}
+>
+	<ol bind:this={listRef} class="fs-breadcrumb-list" {...tabspotAttributes} {...listProps}>
+		{@render children?.()}
+	</ol>
+</nav>
+
+<style>
+	.fs-breadcrumb {
+		font-family: var(--fs-font-family-base);
+		color: var(--fs-text-primary);
+		/* Read by every step and divider */
+		--fs-breadcrumb-font-size: var(--fs-body2-font-size);
+		--fs-breadcrumb-line-height: var(--fs-body2-line-height);
+		--fs-breadcrumb-height: 1.5rem;
+		--fs-breadcrumb-padding-inline: 0.375rem;
+		--fs-breadcrumb-gap: 0.25rem;
+		--fs-breadcrumb-icon-size: 1rem;
+		--fs-breadcrumb-divider-size: 1rem;
+		&.small {
+			--fs-breadcrumb-font-size: var(--fs-caption-font-size);
+			--fs-breadcrumb-line-height: var(--fs-caption-line-height);
+			--fs-breadcrumb-height: 1.25rem;
+			--fs-breadcrumb-padding-inline: 0.25rem;
+			--fs-breadcrumb-icon-size: 0.875rem;
+			--fs-breadcrumb-divider-size: 0.625rem;
+		}
+		&.large {
+			--fs-breadcrumb-font-size: var(--fs-body-font-size);
+			--fs-breadcrumb-line-height: var(--fs-body-line-height);
+			--fs-breadcrumb-height: 2rem;
+			--fs-breadcrumb-padding-inline: 0.5rem;
+			--fs-breadcrumb-icon-size: 1.25rem;
+			--fs-breadcrumb-divider-size: 1.25rem;
+		}
+		& .fs-breadcrumb-list {
+			display: flex;
+			flex-wrap: wrap;
+			align-items: center;
+			margin: 0;
+			padding: 0;
+			list-style: none;
+		}
+	}
+</style>

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

@@ -0,0 +1,25 @@
+import type { BreadcrumbProps } from './types.ts';
+/**
+ * A breadcrumb shows where a page sits in the hierarchy above it, and gives the reader a way back
+ * up. It renders a landmark of its own, so a screen reader can jump straight to it.
+ *
+ * - Usage:
+ * ```tsx
+ * <script>
+ * 	import { Breadcrumb, BreadcrumbItem, BreadcrumbButton, BreadcrumbDivider } from 'fluentui-svelte';
+ * </script>
+ *
+ * <Breadcrumb>
+ * 	<BreadcrumbItem>
+ * 		<BreadcrumbButton as="a" href="/">Home</BreadcrumbButton>
+ * 	</BreadcrumbItem>
+ * 	<BreadcrumbDivider />
+ * 	<BreadcrumbItem>
+ * 		<BreadcrumbButton current>This page</BreadcrumbButton>
+ * 	</BreadcrumbItem>
+ * </Breadcrumb>
+ * ```
+ */
+declare const Breadcrumb: import("svelte").Component<BreadcrumbProps, {}, "ref" | "listRef">;
+type Breadcrumb = ReturnType<typeof Breadcrumb>;
+export default Breadcrumb;